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

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+export type { PreviewLifecyclePayload } from '@storystick/transport-allowlist';
+declare global {
+    interface Window {
+        __storystickPreviewOverlayMapOwner?: 'boot';
+    }
+}
+export type { RenderMode, OverlayMode, StudioToIframe, IframeToStudio, SectionRect, FieldRect, MsgRenderMode, MsgFieldBounds, MsgDragEnd, MsgPreviewSnapshot, SnapshotItem, CoverageTier, } from './types.js';
+export { isIframeToStudio, isStudioToIframe } from './types.js';
+export type { PreviewPerspectiveCommandResult } from './context-command.js';
+export { startSnapshotReporter, type SnapshotReporterHandle, type SnapshotReporterOptions, } from './runtime/snapshot-reporter.js';
+export { assembleSnapshot, type AssembledSnapshot, type Measure, type PlainRect, } from './runtime/snapshot-assembly.js';
+export { startFormContractReporter, getStorystickViewport, FORM_PREVIEW_ATTR, type FormContractReporterHandle, type FormContractReporterOptions, type FormContractReport, } from './runtime/form-contract-reporter.js';
+export { getRenderMode, setRenderMode, subscribeRenderMode, debounceForRenderMode, } from './runtime/render-mode-state.js';
+export { validateNavigate, validateOverlayClear, validateOverlayMap, type ValidationFailure, type ValidationResult, } from './validators.js';
+export { legacyPreviewAuthState, transitionPreviewGrantLifecycle, type LegacyPreviewAuthState, type PreviewGrantLifecycle, type PreviewGrantLifecycleEvent, type PreviewGrantFailureCause, } from './grant-lifecycle.js';
+export { PREVIEW_TOKEN_ROUTE, PREVIEW_GRANT_RETRY_BACKOFF_MS, PreviewGrantRequestError, acquirePreviewBrowserGrant, createPreviewGrantCoordinator, type PreviewBrowserGrant, type PreviewGrantCoordinator, } from './grant-coordinator.js';
+export { setNavigateHandler, getNavigateHandler, setReloadHandler, getReloadHandler, type NavigateHandler, type ReloadHandler, type ReloadMode, _resetNavigateHandlerForTests, } from './nav-handler.js';
+export { setRouterSubscriber, getRouterSubscriber, notifyRouterTransition, type RouterSubscriber, type RouterTransition, _resetRouterSubscriberForTests, } from './router-subscriber.js';
+export { getInteractionMode, setInteractionMode, type InteractionMode, _resetInteractionModeForTests, } from './interaction-mode.js';
+export { subscribePreviewSession, mapPreviewSessionError, type PreviewSessionData, type PreviewSessionErrorCode, type SubscribeOptions, type SubscribeCallable, } from './session-subscriber.js';
+export interface PreviewConfig {
+    /** Storystick endpoint URL */
+    endpoint: string;
+    /** Preview session ID from URL parameter */
+    sessionId: string;
+    /**
+     * Project shortId. When set, `activate()` installs the secret-free
+     * navigation/overlay control plane. Browser grant acquisition is owned by
+     * `previewRuntime`, never by this postMessage listener.
+     */
+    projectId?: string;
+    /**
+     * Studio origin learned from the identity broadcast. It may be null on the
+     * URL/storage bootstrap pass; callers can restart `activate()` after the
+     * same-session identity is promoted without restarting the browser grant.
+     */
+    parentOrigin?: string | null;
+    /**
+     * Internal adapter proof that a standalone tab acquired the origin's
+     * HttpOnly preview capability. Public URL selectors alone never enable
+     * overlays.
+     */
+    standaloneCapability?: true;
+    /** Re-emit the current secret-free lifecycle after Studio re-broadcasts identity. */
+    onSessionBroadcast?: () => void;
+    /** Called when a field overlay is clicked */
+    onFieldClick?: (fieldPath: string) => void;
+    /** Called when a section is dragged to a new position */
+    onSectionDrag?: (fromIndex: number, toIndex: number) => void;
+    /** Called when the "+" button is clicked between sections */
+    onAddSection?: (atIndex: number) => void;
+}
+export type { TrackedField, RegisteredRoot } from './runtime/field-proxy.js';
+export { wrapWithProxy, getTrackedFields, clearTrackedFields, collectFieldModel, collectFieldModelFromRoots, registerIslandRoots, clearIslandRoots, isFieldTrackingActive, __setFieldTrackingForcedForTests, } from './runtime/field-proxy.js';
+export declare function activate(config: PreviewConfig): () => void;
+/**
+ * Test-only hook to drop the singleton between cases. Vitest modules
+ * are isolated per file, but a single file with multiple `activate`
+ * calls would share state without this reset.
+ */
+export declare function _resetActivateForTests(): void;
+/**
+ * ADR-081 §3.8 — postMessage shape emitted FROM the preview iframe TO
+ * the parent Studio. The Studio's `cross-frame-listener` consumes the
+ * same shape.
+ *
+ * Telemetry attribution (`from`) is required so the studio's field-nav
+ * counters can attribute the resulting nav (`'preview'`,
+ * `'preview-overlay'`, etc.) without inventing a default at the
+ * receiver.
+ */
+export interface PreviewNavMessage {
+    action: 'navigate';
+    verb: 'field' | 'slice' | 'mark' | 'embed';
+    value: string;
+    from: string;
+}
+/**
+ * Emit a `PreviewNavMessage` to the parent Studio. No-op when not
+ * embedded (top-level window or SSR) — same guard as `activate`.
+ *
+ * Origin :
+ *   - When `targetOrigin` is omitted, defaults to `window.location.origin`.
+ *     Per ADR-041 the studio + preview share a cookie domain, which means
+ *     they share an origin in practice — same-origin posting works.
+ *   - Pass an explicit `targetOrigin` if a future deployment puts the
+ *     preview on a different origin (cross-domain) ; the studio listener
+ *     would then need a documented allowlist on its side.
+ */
+export declare function postNavigateToParent(msg: PreviewNavMessage, targetOrigin?: string): void;