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

package/dist/runtime/windowed-minimap-projection.d.ts

@@ -0,0 +1,28 @@
+export interface WindowedMinimapGeometry {
+    pageHeight: number;
+    windowStart: number;
+    renderSpan: number;
+    compression: number;
+    rootStyleCssText: string;
+}
+export declare function readWindowedMinimapGeometry(doc: Document): WindowedMinimapGeometry | null;
+/**
+ * A reversible lease on the root declarations needed by the bounded minimap
+ * projection. It is inactive unless Studio explicitly requests it.
+ *
+ * The site still receives a normal 1440×900 layout viewport. Only paint is
+ * compressed; Studio expands that paint back into the minimap's document
+ * coordinate space. Slice snapshots use the geometry above to undo the paint
+ * transform before crossing the iframe boundary.
+ */
+export declare function createWindowedMinimapProjection(win: Window, doc: Document, viewportHeight?: number): {
+    enter(initialRenderSpan?: number): WindowedMinimapGeometry | null;
+    update(nextWindowStart: number, nextRenderSpan: number): WindowedMinimapGeometry | null;
+    reapplyAfterRootReset(): void;
+    refresh(): WindowedMinimapGeometry | null;
+    exit(): string[];
+    ownsRootStyle(): boolean;
+    readonly active: boolean;
+    readonly geometry: WindowedMinimapGeometry | null;
+    readonly stoppedReason: string | null;
+};

package/dist/runtime/windowed-minimap-projection.js

@@ -0,0 +1,189 @@
+const geometryByDocument = new WeakMap();
+export function readWindowedMinimapGeometry(doc) {
+    return geometryByDocument.get(doc) ?? null;
+}
+/**
+ * A reversible lease on the root declarations needed by the bounded minimap
+ * projection. It is inactive unless Studio explicitly requests it.
+ *
+ * The site still receives a normal 1440×900 layout viewport. Only paint is
+ * compressed; Studio expands that paint back into the minimap's document
+ * coordinate space. Slice snapshots use the geometry above to undo the paint
+ * transform before crossing the iframe boundary.
+ */
+export function createWindowedMinimapProjection(win, doc, viewportHeight = 900) {
+    const root = doc.documentElement;
+    const original = new Map();
+    const owned = new Map();
+    let active = false;
+    let pageHeight = viewportHeight;
+    let windowStart = 0;
+    let renderSpan = viewportHeight;
+    let stoppedReason = null;
+    let rootStyleCssText = '';
+    const read = (property) => ({
+        value: root.style.getPropertyValue(property),
+        priority: root.style.getPropertyPriority(property),
+    });
+    const equal = (property, a, b) => a.value === b.value &&
+        // Next.js temporarily writes `scroll-behavior: auto` on the root during
+        // navigation without preserving our `!important` priority. The semantic
+        // value is unchanged, so this is safe to reclaim on the next projection
+        // pass. Value changes and every other leased declaration remain strict.
+        (property === 'scroll-behavior' || a.priority === b.priority);
+    const set = (property, value) => {
+        if (!original.has(property))
+            original.set(property, read(property));
+        root.style.setProperty(property, value, 'important');
+        owned.set(property, read(property));
+        rootStyleCssText = root.style.cssText;
+    };
+    const conflicts = () => [...owned].filter(([property, state]) => !equal(property, read(property), state));
+    const restore = () => {
+        geometryByDocument.delete(doc);
+        const concurrent = conflicts().map(([property]) => property);
+        for (const [property, state] of original) {
+            if (concurrent.includes(property))
+                continue;
+            if (state.value)
+                root.style.setProperty(property, state.value, state.priority);
+            else
+                root.style.removeProperty(property);
+        }
+        original.clear();
+        owned.clear();
+        rootStyleCssText = '';
+        return concurrent;
+    };
+    const unsupported = () => {
+        if (doc.compatMode !== 'CSS1Compat')
+            return 'non-standards document';
+        const css = win.getComputedStyle(root);
+        if (css.writingMode && css.writingMode !== 'horizontal-tb') {
+            return 'root writing mode';
+        }
+        for (const property of ['transform', 'translate', 'scale', 'rotate']) {
+            const value = css.getPropertyValue(property);
+            if (value !== '' && value !== 'none')
+                return 'existing root transform';
+        }
+        if (css.zoom && Number(css.zoom) !== 1)
+            return 'existing root zoom';
+        return null;
+    };
+    const readNaturalHeight = () => Math.max(viewportHeight, doc.body?.scrollHeight ?? 0, doc.body?.offsetHeight ?? 0, doc.scrollingElement?.scrollHeight ?? 0);
+    const apply = () => {
+        if (!active)
+            return;
+        // Studio owns the paint window and its inverse transform. A resize report
+        // (including an intermediate route subtree) may change pageHeight, but
+        // must not silently change this half of the transform pair. Studio clamps
+        // the next window to the measured page before sending update().
+        const rendered = Math.max(viewportHeight, Number.isFinite(renderSpan) ? renderSpan : viewportHeight);
+        renderSpan = rendered;
+        windowStart = Math.max(0, Number.isFinite(windowStart) ? windowStart : 0);
+        const compression = viewportHeight / rendered;
+        set('min-height', `${viewportHeight}px`);
+        set('max-height', `${viewportHeight}px`);
+        set('transform-origin', '0 0');
+        set('scroll-behavior', 'auto');
+        set('transform', `scale(${compression})`);
+        const targetScroll = windowStart * compression;
+        const scroller = doc.scrollingElement;
+        if (scroller) {
+            scroller.scrollLeft = 0;
+            scroller.scrollTop = targetScroll;
+        }
+        else {
+            win.scrollTo({ top: targetScroll, left: 0, behavior: 'instant' });
+        }
+        const geometry = {
+            pageHeight,
+            windowStart,
+            renderSpan,
+            compression,
+            rootStyleCssText,
+        };
+        geometryByDocument.set(doc, geometry);
+    };
+    return {
+        enter(initialRenderSpan = viewportHeight) {
+            // Studio reasserts Navigation before it dispatches the next route. The
+            // current realm is already projected at that point; resetting its span
+            // to the native viewport would expose one enlarged frame before the
+            // router starts. The following window message remains the authority for
+            // changing an active projection.
+            if (active)
+                return geometryByDocument.get(doc) ?? null;
+            stoppedReason = unsupported();
+            if (stoppedReason)
+                return null;
+            pageHeight = readNaturalHeight();
+            renderSpan = initialRenderSpan;
+            windowStart = 0;
+            active = true;
+            apply();
+            return geometryByDocument.get(doc) ?? null;
+        },
+        update(nextWindowStart, nextRenderSpan) {
+            if (!active)
+                return null;
+            if (conflicts().length > 0) {
+                this.exit();
+                return null;
+            }
+            windowStart = nextWindowStart;
+            renderSpan = nextRenderSpan;
+            apply();
+            return geometryByDocument.get(doc) ?? null;
+        },
+        reapplyAfterRootReset() {
+            // A router can remount <html> and remove every leased declaration.
+            // During a navigation handoff, keep the existing transform pair before
+            // paint. This is not permission to overwrite a new site's root styles:
+            // partial edits and replacement transforms still take the conflict path.
+            if (!active ||
+                owned.size === 0 ||
+                [...owned.keys()].some((property) => read(property).value !== '') ||
+                unsupported()) {
+                return;
+            }
+            original.clear();
+            owned.clear();
+            apply();
+        },
+        refresh() {
+            if (!active)
+                return null;
+            if (conflicts().length > 0) {
+                this.exit();
+                return null;
+            }
+            pageHeight = readNaturalHeight();
+            apply();
+            return geometryByDocument.get(doc) ?? null;
+        },
+        exit() {
+            if (!active && original.size === 0)
+                return [];
+            const concurrent = restore();
+            active = false;
+            if (concurrent.length > 0) {
+                stoppedReason = `concurrent root style: ${concurrent.join(', ')}`;
+            }
+            return concurrent;
+        },
+        ownsRootStyle() {
+            return active && root.style.cssText === rootStyleCssText;
+        },
+        get active() {
+            return active;
+        },
+        get geometry() {
+            return geometryByDocument.get(doc) ?? null;
+        },
+        get stoppedReason() {
+            return stoppedReason;
+        },
+    };
+}

package/dist/runtime/workspace-shortcuts.d.ts

@@ -0,0 +1,30 @@
+/** Commands explicitly reserved by an attached Studio, including in Navigate inputs. */
+export declare const previewWorkspaceCommandIds: readonly ["workspace.navigation.toggle", "workspace.preview.toggle", "workspace.details.toggle", "workspace.assistant.toggle", "commands.open", "focus.next", "focus.previous"];
+export type PreviewWorkspaceCommandId = (typeof previewWorkspaceCommandIds)[number];
+export interface PreviewShortcutBinding {
+    id: PreviewWorkspaceCommandId;
+    key: string;
+    meta: boolean;
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+}
+export interface PreviewShortcutIdentity {
+    sessionId: string;
+    projectId: string;
+    parentOrigin: string | null;
+}
+export interface PreviewShortcutMessage {
+    type: 'storystick.preview.shortcuts';
+    kind: 'ready' | 'configure' | 'invoke' | 'probe';
+    sessionId: string;
+    projectId: string;
+    relayId: string;
+    connectionId?: string;
+    revision?: number;
+    bindings?: PreviewShortcutBinding[];
+    command?: PreviewWorkspaceCommandId;
+    sequence?: number;
+}
+/** Self-contained: the exact same implementation is embedded in the early script. */
+export declare function installPreviewWorkspaceShortcuts(win: Window, getIdentity: () => PreviewShortcutIdentity | null, commandIds?: readonly string[], subscribeIdentity?: (listener: () => void) => () => void): () => void;

package/dist/runtime/workspace-shortcuts.js

@@ -0,0 +1,188 @@
+/** Commands explicitly reserved by an attached Studio, including in Navigate inputs. */
+export const previewWorkspaceCommandIds = [
+    'workspace.navigation.toggle',
+    'workspace.preview.toggle',
+    'workspace.details.toggle',
+    'workspace.assistant.toggle',
+    'commands.open',
+    'focus.next',
+    'focus.previous',
+];
+/** Self-contained: the exact same implementation is embedded in the early script. */
+export function installPreviewWorkspaceShortcuts(win, getIdentity, commandIds = previewWorkspaceCommandIds, subscribeIdentity) {
+    if (win.parent === win)
+        return () => { };
+    const view = win;
+    // SDK adapters and the early provenance script share one listener per realm.
+    let shared = view.__storystickWorkspaceShortcuts;
+    if (!shared) {
+        const owners = new Set();
+        const type = 'storystick.preview.shortcuts';
+        const newRelayId = () => Array.from(win.crypto.getRandomValues(new Uint32Array(4))).join('-');
+        let identity = null;
+        let relayId = newRelayId();
+        let bindings = [];
+        let connectionId = null;
+        let revision = -1;
+        let sequence = 0;
+        let disposed = false;
+        const readIdentity = () => {
+            const next = Array.from(owners)
+                .map((read) => read())
+                .find((value) => value?.parentOrigin) ?? null;
+            if (!next?.parentOrigin || !next.sessionId || !next.projectId)
+                return null;
+            try {
+                if (new URL(next.parentOrigin).origin !== next.parentOrigin ||
+                    next.parentOrigin === 'null')
+                    return null;
+            }
+            catch {
+                return null;
+            }
+            return {
+                sessionId: next.sessionId,
+                projectId: next.projectId,
+                parentOrigin: next.parentOrigin,
+            };
+        };
+        const syncIdentity = () => {
+            const next = readIdentity();
+            if (JSON.stringify(next) !== JSON.stringify(identity)) {
+                identity = next;
+                relayId = newRelayId();
+                bindings = [];
+                revision = -1;
+                sequence = 0;
+            }
+            return identity;
+        };
+        const post = (message) => {
+            if (!identity?.parentOrigin)
+                return;
+            win.parent.postMessage({
+                type,
+                sessionId: identity.sessionId,
+                projectId: identity.projectId,
+                relayId,
+                ...message,
+            }, identity.parentOrigin);
+        };
+        const refresh = () => {
+            if (disposed)
+                return;
+            if (syncIdentity())
+                post({ kind: 'ready' });
+        };
+        const onMessage = (event) => {
+            if (event.source !== win.parent)
+                return;
+            // Identity delivery may be handled by a later listener in the same turn.
+            if (event.data?.type === 'storystick.preview.session-broadcast') {
+                queueMicrotask(refresh);
+                return;
+            }
+            const current = syncIdentity();
+            const data = event.data;
+            if (!current ||
+                event.origin !== current.parentOrigin ||
+                data?.type !== type ||
+                data.sessionId !== current.sessionId ||
+                data.projectId !== current.projectId)
+                return;
+            if (data.kind === 'probe') {
+                refresh();
+                return;
+            }
+            if (data.kind !== 'configure' ||
+                data.relayId !== relayId ||
+                typeof data.connectionId !== 'string' ||
+                !data.connectionId ||
+                data.connectionId.length > 128 ||
+                !Number.isSafeInteger(data.revision) ||
+                data.revision < 0 ||
+                (data.connectionId === connectionId && data.revision < revision) ||
+                !Array.isArray(data.bindings) ||
+                data.bindings.length > 16)
+                return;
+            // A configuration can reserve only workspace chords, never ordinary typing.
+            if (!data.bindings.every((b) => b &&
+                commandIds.includes(b.id) &&
+                typeof b.key === 'string' &&
+                (b.key.length === 1 || b.key === 'f6') &&
+                ['meta', 'ctrl', 'alt', 'shift'].every((k) => typeof b[k] === 'boolean') &&
+                (b.meta || b.ctrl || b.key === 'f6')))
+                return;
+            connectionId = data.connectionId;
+            revision = data.revision;
+            bindings = data.bindings;
+        };
+        const onKeyDown = (event) => {
+            if (!syncIdentity() ||
+                event.isComposing ||
+                event.keyCode === 229 ||
+                event.getModifierState?.('AltGraph') ||
+                ['Dead', 'Process', 'Unidentified'].includes(event.key))
+                return;
+            const binding = bindings.find((b) => b.key === event.key.toLowerCase() &&
+                b.meta === event.metaKey &&
+                b.ctrl === event.ctrlKey &&
+                b.alt === event.altKey &&
+                b.shift === event.shiftKey);
+            if (!binding)
+                return;
+            // Cancellation must be synchronous in this document. postMessage cannot
+            // cancel the browser/site action after the Studio receives the command.
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            if (!event.repeat)
+                post({
+                    kind: 'invoke',
+                    command: binding.id,
+                    connectionId,
+                    revision,
+                    sequence: ++sequence,
+                });
+        };
+        const suspend = () => {
+            bindings = [];
+            revision = -1;
+            relayId = newRelayId();
+            sequence = 0;
+        };
+        win.addEventListener('message', onMessage);
+        win.addEventListener('keydown', onKeyDown, true);
+        win.addEventListener('focus', refresh);
+        win.addEventListener('pageshow', refresh);
+        win.addEventListener('pagehide', suspend);
+        shared = {
+            owners,
+            refresh,
+            dispose: () => {
+                disposed = true;
+                win.removeEventListener('message', onMessage);
+                win.removeEventListener('keydown', onKeyDown, true);
+                win.removeEventListener('focus', refresh);
+                win.removeEventListener('pageshow', refresh);
+                win.removeEventListener('pagehide', suspend);
+                delete view.__storystickWorkspaceShortcuts;
+            },
+        };
+        view.__storystickWorkspaceShortcuts = shared;
+    }
+    shared.owners.add(getIdentity);
+    const unsubscribe = subscribeIdentity?.(shared.refresh);
+    queueMicrotask(shared.refresh);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        unsubscribe?.();
+        shared.owners.delete(getIdentity);
+        if (shared.owners.size === 0)
+            shared.dispose();
+        else
+            shared.refresh();
+    };
+}

package/dist/sdk-error-copy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ADR-134 §9.T2 — SDK-side copy table for the `<Storystick />` terminal
+ * panel in `@storystick/next`. Mirror of `apps/studio/src/lib/preview-
+ * error-copy.ts`, scoped to the SUBSET of codes the customer-side panel
+ * actually renders. A contract test at `apps/studio/tests/sdk-error-
+ * copy-contract.test.ts` pins overlap rows verbatim against Studio's
+ * copy so the two tables can't drift on shared codes.
+ *
+ * Why a separate table : Studio product copy doesn't ship in customer-
+ * runtime bundle (different audience, different vocabulary, different
+ * bundle size budget). The SDK surface renders inside the customer's
+ * page, so it speaks to the DEVELOPER hosting the customer site rather
+ * than to a Studio editor. Phrasing can legitimately diverge on Studio-
+ * specific codes ; the contract test ensures shared codes don't.
+ *
+ * Codes covered :
+ *   - `runtime.cache_unavailable`  (D6 — Layer1 cache failed to open)
+ *   - `runtime.schema_sync_delayed`  (D6 — attempt 1 of schema retry)
+ *   - `runtime.schema_delivery_failed`  (D6 — attempt 5 of schema retry)
+ *   - `identity_carrier_timeout` when Studio identity cannot be established.
+ *   - PreviewGrant/context boundary codes emitted by the same-origin token
+ *     route or Convex subscriptions.
+ *
+ * Unknown codes fall back to a generic entry. The fallback's body is
+ * intentionally honest : the SDK doesn't claim to know what happened.
+ */
+export interface SdkErrorCopyEntry {
+    title: string;
+    body: string;
+    /**
+     * Non-exhaustive list of likely causes. The SDK panel renders these
+     * as a bullet list inside the red surface. Empty array → list is
+     * suppressed.
+     */
+    commonCauses: ReadonlyArray<string>;
+}
+/**
+ * Canonical map. Codes here MUST match `apps/studio/src/lib/preview-
+ * error-copy.ts` on overlap rows (contract-tested). Title + body
+ * fields share verbatim, commonCauses share as a set (order can
+ * differ).
+ */
+export declare const SDK_ERROR_COPY: Readonly<Record<string, SdkErrorCopyEntry>>;
+/**
+ * Look up the structured SDK copy for a code. Always returns an entry
+ * (never null) so the panel can render unconditionally.
+ */
+export declare function lookupSdkCopy(code: string | null | undefined): SdkErrorCopyEntry;

package/dist/sdk-error-copy.js

@@ -0,0 +1,182 @@
+/**
+ * ADR-134 §9.T2 — SDK-side copy table for the `<Storystick />` terminal
+ * panel in `@storystick/next`. Mirror of `apps/studio/src/lib/preview-
+ * error-copy.ts`, scoped to the SUBSET of codes the customer-side panel
+ * actually renders. A contract test at `apps/studio/tests/sdk-error-
+ * copy-contract.test.ts` pins overlap rows verbatim against Studio's
+ * copy so the two tables can't drift on shared codes.
+ *
+ * Why a separate table : Studio product copy doesn't ship in customer-
+ * runtime bundle (different audience, different vocabulary, different
+ * bundle size budget). The SDK surface renders inside the customer's
+ * page, so it speaks to the DEVELOPER hosting the customer site rather
+ * than to a Studio editor. Phrasing can legitimately diverge on Studio-
+ * specific codes ; the contract test ensures shared codes don't.
+ *
+ * Codes covered :
+ *   - `runtime.cache_unavailable`  (D6 — Layer1 cache failed to open)
+ *   - `runtime.schema_sync_delayed`  (D6 — attempt 1 of schema retry)
+ *   - `runtime.schema_delivery_failed`  (D6 — attempt 5 of schema retry)
+ *   - `identity_carrier_timeout` when Studio identity cannot be established.
+ *   - PreviewGrant/context boundary codes emitted by the same-origin token
+ *     route or Convex subscriptions.
+ *
+ * Unknown codes fall back to a generic entry. The fallback's body is
+ * intentionally honest : the SDK doesn't claim to know what happened.
+ */
+const PREVIEW_ACCESS_ENDED = {
+    title: 'Preview access ended',
+    body: 'This preview is no longer active. Return to Storystick Studio to open a new preview.',
+    commonCauses: [],
+};
+const PREVIEW_ADMISSION_MISSING = {
+    title: 'Preview access is missing',
+    body: 'The site did not receive the Preview admission cookie. Open a fresh Preview from Studio. If this continues, check the site’s HTTPS and cookie configuration.',
+    commonCauses: [
+        'The browser did not accept or send the Preview cookie in this context.',
+        'The Preview admission expired or was cleared.',
+    ],
+};
+const PREVIEW_RENDER_ADMISSION_MISSING = {
+    title: 'Preview needs a fresh activation',
+    body: 'The site could not confirm Preview for its current deployment. Reopen Preview from Studio.',
+    commonCauses: [
+        'The site was redeployed after Preview was opened.',
+        'The browser did not return the site’s Draft Mode cookie.',
+    ],
+};
+const PREVIEW_BINDING_MISMATCH = {
+    title: 'Preview binding mismatch',
+    body: 'This preview does not match the active project, origin, or session. Reopen the document from the correct Storystick Studio project.',
+    commonCauses: [],
+};
+const PREVIEW_VIEW_UNAVAILABLE = {
+    title: 'This preview has expired',
+    body: 'Open a new preview from Studio to continue.',
+    commonCauses: [],
+};
+const PREVIEW_ADMISSION_SUPERSEDED = {
+    title: 'Preview changed in another view',
+    body: 'This page could not reconnect to the current preview. Reopen it from Studio.',
+    commonCauses: [],
+};
+const PREVIEW_PROTOCOL_INVALID = {
+    title: 'Preview adapter mismatch',
+    body: 'The customer preview route returned an incompatible response. Update the Storystick packages together, then reopen the document.',
+    commonCauses: [],
+};
+/**
+ * Canonical map. Codes here MUST match `apps/studio/src/lib/preview-
+ * error-copy.ts` on overlap rows (contract-tested). Title + body
+ * fields share verbatim, commonCauses share as a set (order can
+ * differ).
+ */
+export const SDK_ERROR_COPY = {
+    'runtime.preview_read_unavailable': {
+        title: 'Preview content temporarily unavailable',
+        body: 'The content service could not answer this page’s request. Retry when the connection is restored.',
+        commonCauses: [],
+    },
+    'runtime.customer_render_failed': {
+        title: 'This page could not render',
+        body: 'The customer site reported a rendering error. You can open another document. Retry this page after its rendering error has been corrected.',
+        commonCauses: [],
+    },
+    // ─── D-category runtime warnings/errors (emitted by SDK boot/schema) ──
+    'runtime.cache_unavailable': {
+        title: 'Preview cache unavailable',
+        body: 'The preview cache could not be opened, so observed overlays are disabled. Authenticated preview still works; the editor will fall back to explicit rendering.',
+        commonCauses: [
+            'IndexedDB is disabled (private browsing on older Firefox / Safari).',
+            'A browser extension is blocking storage access.',
+        ],
+    },
+    'runtime.schema_sync_delayed': {
+        title: 'Loading schema is taking longer than usual',
+        body: 'Studio is still fetching the project schema. Field-level overlays will be limited until the schema arrives.',
+        commonCauses: [
+            'Slow network between the iframe and the Storystick gateway.',
+            'The gateway returned a transient error and the SDK is retrying.',
+        ],
+    },
+    'runtime.schema_delivery_failed': {
+        title: 'Schema delivery failed',
+        body: 'The preview schema could not be fetched after 5 attempts. Field-level overlays are unavailable for this session.',
+        commonCauses: [
+            'The Storystick gateway is unreachable from the iframe.',
+            'Network conditions prevented the schema HTTP request from completing.',
+            'Reload the iframe to retry from a fresh attempt cycle.',
+        ],
+    },
+    // ─── Grant / origin / session codes ────────────────────────────
+    identity_carrier_timeout: {
+        title: 'Preview identity could not be established',
+        body: 'Studio did not deliver a preview identity to this iframe in time. Reopen the document in Storystick Studio to retry.',
+        commonCauses: [],
+    },
+    PREVIEW_GRANT_MISSING: PREVIEW_ADMISSION_MISSING,
+    'storystick/PREVIEW_GRANT_MISSING': PREVIEW_ADMISSION_MISSING,
+    CONTENT_SHAPE_RELOAD_REQUIRED: PREVIEW_RENDER_ADMISSION_MISSING,
+    'storystick/CONTENT_SHAPE_RELOAD_REQUIRED': PREVIEW_RENDER_ADMISSION_MISSING,
+    PREVIEW_GRANT_MALFORMED: PREVIEW_ACCESS_ENDED,
+    'storystick/PREVIEW_GRANT_MALFORMED': PREVIEW_ACCESS_ENDED,
+    PREVIEW_GRANT_INVALID: PREVIEW_ACCESS_ENDED,
+    'storystick/PREVIEW_GRANT_INVALID': PREVIEW_ACCESS_ENDED,
+    PREVIEW_GRANT_REVOKED: PREVIEW_ACCESS_ENDED,
+    'storystick/PREVIEW_GRANT_REVOKED': PREVIEW_ACCESS_ENDED,
+    PREVIEW_GRANT_EXPIRED: PREVIEW_ACCESS_ENDED,
+    'storystick/PREVIEW_GRANT_EXPIRED': PREVIEW_ACCESS_ENDED,
+    PREVIEW_ACCESS_REVOKED: PREVIEW_ACCESS_ENDED,
+    'storystick/PREVIEW_ACCESS_REVOKED': PREVIEW_ACCESS_ENDED,
+    PREVIEW_VIEW_UNAVAILABLE,
+    'storystick/PREVIEW_VIEW_UNAVAILABLE': PREVIEW_VIEW_UNAVAILABLE,
+    PREVIEW_ADMISSION_SUPERSEDED,
+    'storystick/PREVIEW_ADMISSION_SUPERSEDED': PREVIEW_ADMISSION_SUPERSEDED,
+    PREVIEW_CONTEXT_INVALID: PREVIEW_ACCESS_ENDED,
+    'storystick/PREVIEW_CONTEXT_INVALID': PREVIEW_ACCESS_ENDED,
+    PREVIEW_CONTEXT_ENDED: PREVIEW_ACCESS_ENDED,
+    PREVIEW_CONTEXT_EXIT_UNAVAILABLE: {
+        title: 'Preview exit could not finish',
+        body: 'The shared preview ended, but this page could not clear its local preview access. Retry Exit Preview.',
+        commonCauses: [],
+    },
+    PREVIEW_GRANT_REQUIRED: PREVIEW_BINDING_MISMATCH,
+    PREVIEW_GRANT_FORBIDDEN: PREVIEW_BINDING_MISMATCH,
+    'storystick/PREVIEW_GRANT_FORBIDDEN': PREVIEW_BINDING_MISMATCH,
+    PREVIEW_GRANT_BINDING_MISMATCH: PREVIEW_BINDING_MISMATCH,
+    'storystick/PREVIEW_GRANT_BINDING_MISMATCH': PREVIEW_BINDING_MISMATCH,
+    PREVIEW_ORIGIN_MISMATCH: PREVIEW_BINDING_MISMATCH,
+    'storystick/PREVIEW_ORIGIN_MISMATCH': PREVIEW_BINDING_MISMATCH,
+    PREVIEW_PROJECT_MISMATCH: PREVIEW_BINDING_MISMATCH,
+    'storystick/PREVIEW_PROJECT_MISMATCH': PREVIEW_BINDING_MISMATCH,
+    PREVIEW_TOKEN_PROTOCOL_INVALID: PREVIEW_PROTOCOL_INVALID,
+    PREVIEW_REQUIRED: {
+        title: 'Preview mode required',
+        body: 'This route can only be rendered inside an active Storystick preview session. Open it from Studio to view.',
+        commonCauses: [],
+    },
+    UNKNOWN: {
+        title: 'Unknown preview error',
+        body: 'The Storystick SDK received an unrecognised error code. Reload the iframe ; if the issue persists, check the Studio logs.',
+        commonCauses: [],
+    },
+};
+/**
+ * Fallback entry. Returned by `lookupSdkCopy` for codes not in the map.
+ * Honest body — the SDK doesn't pretend to know.
+ */
+const FALLBACK_SDK_ENTRY = {
+    title: 'Storystick preview error',
+    body: 'Preview connection lost. Reopen the document in Storystick Studio to resume.',
+    commonCauses: [],
+};
+/**
+ * Look up the structured SDK copy for a code. Always returns an entry
+ * (never null) so the panel can render unconditionally.
+ */
+export function lookupSdkCopy(code) {
+    if (typeof code !== 'string' || code.length === 0) {
+        return FALLBACK_SDK_ENTRY;
+    }
+    return SDK_ERROR_COPY[code] ?? FALLBACK_SDK_ENTRY;
+}

package/dist/select-cursor.d.ts

@@ -0,0 +1,2 @@
+/** CSS cursor value, including the tip-aligned hotspot and native fallback. */
+export declare const PREVIEW_SELECT_CURSOR: string;