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

package/dist/types.d.ts

@@ -0,0 +1,446 @@
+/**
+ * Storystick Studio ↔ Preview iframe — postMessage protocol types.
+ *
+ * Authoritative reference for the protocol defined in
+ *   storystick-hq/spec/preview-system.md  §"Communication Protocol"
+ *   storystick-hq/architecture/decisions/059-studio-shell-redesign.md  §6
+ *   storystick-hq/architecture/decisions/065-field-level-navigation-primitive.md  §3.7
+ *
+ * Two orthogonal axes carried by the protocol itself:
+ *
+ *   render-mode  : 'navigation' | 'device'
+ *     Controls iframe internal viewport (1280px vs device width),
+ *     scale transform, pointer-events, and where overlays render
+ *     (parent DOM vs in-iframe).
+ *
+ *   overlay-mode : 'section' | 'field'
+ *     Controls overlay granularity (slice boundary vs individual
+ *     field). Independent of render-mode — pairings are defaults,
+ *     not constraints.
+ *
+ * Click handling is NOT in this protocol — by design. ADR-065 owns the
+ * cross-frame navigation entry point. A child iframe posts the canonical
+ * `{ action: 'navigate', verb, value, from }` message exported from
+ * `@storystick/preview`. The Studio's field-navigation listener routes that
+ * target through the shared arrival service. PR2' does not duplicate it.
+ *
+ * Versioning convention
+ * ---------------------
+ * The protocol is a flat discriminated union on `type`. New
+ * variants extend the union; existing variants are never mutated.
+ * If a wire-level break is ever required, introduce a new top-level
+ * variant (e.g. `type: 'v2-section-bounds'`) rather than versioning
+ * the envelope. This keeps the runtime check trivially exhaustive
+ * via TypeScript's `never` narrowing.
+ */
+export type RenderMode = 'navigation' | 'device';
+export type OverlayMode = 'section' | 'field';
+/** Switch the iframe's render configuration. */
+export interface MsgRenderMode {
+    type: 'render-mode';
+    mode: RenderMode;
+    /**
+     * ADR-119 D1/D3 — the Studio controller's instance-scoped
+     * generation counter. The SDK echoes it back verbatim on every
+     * `storystick.preview.form-contract` report so the controller can
+     * discard stale cross-doc async measurements soundly (the
+     * ratchet-class guard). Optional for legacy senders / tests; the
+     * SDK treats an absent epoch as `0`.
+     */
+    epoch?: number;
+    /**
+     * Experimental Studio-owned minimap projection. The customer keeps a
+     * regular 1440×900 viewport while the SDK temporarily compresses a bounded
+     * document window for Navigation paint. Absent/false preserves the existing
+     * Form contract and remains compatible with older Studio senders.
+     */
+    windowedMinimapProjection?: boolean;
+    /**
+     * Experimental provenance lifecycle mirror. This is distinct from
+     * `epoch`: `epoch` remains the ADR-119 viewport/snapshot ratchet,
+     * while `previewLifecycle` mirrors the Preview transition identity
+     * owned by Studio/ADR-143. Framework SDKs only echo/observe it.
+     */
+    previewLifecycle?: {
+        readonly generation: number;
+        readonly sourceOfTruth: 'studio' | 'iframe' | 'system';
+        readonly commandId?: string | null;
+    };
+}
+export type StudioToIframe = MsgRenderMode | {
+    type: 'storystick.preview.windowed-minimap';
+    epoch: number;
+    windowStart: number;
+    renderSpan: number;
+} | {
+    type: 'overlay-mode';
+    mode: OverlayMode;
+} | {
+    type: 'highlight';
+    path: string;
+} | {
+    type: 'scroll';
+    section: number;
+} | {
+    type: 'device-width';
+    width: number;
+} | {
+    type: 'storystick.preview.host-resize';
+    active: boolean;
+};
+/**
+ * Section bounding rects — emitted in Navigation mode by the
+ * `section-reporter` v2 runtime (ADR-112 D11). The observer
+ * triptyque (IntersectionObserver auxiliary + ResizeObserver +
+ * MutationObserver + `document.fonts.ready`) feeds a single rAF
+ * tick that publishes the full set.
+ *
+ * Coordinate space (ADR-112 D11b) — **document coordinates**, NOT
+ * viewport coordinates. `documentRect.{x,y}` is
+ * `getBoundingClientRect().{x,y} + window.scroll{X,Y}`, so the
+ * value is invariant under user scroll. Studio projects to its
+ * own visual pixels via
+ * `apps/studio/src/lib/preview-imperative-bridge.ts ::
+ * projectDocumentRectToStudio(documentRect, scrollTop, scrollLeft,
+ * scale)` — a non-optional `* scale` multiplication, since the
+ * iframe renders at logical CSS pixels and Studio displays a
+ * scaled mini-map.
+ *
+ * Wire-level rename (ADR-112 C4): field `rect` → `documentRect`.
+ * The break is intentional and loud — TypeScript fails compile on
+ * every legacy call site that wasn't migrated atomically.
+ *
+ * `DOMRect` does not survive structured-clone over postMessage in
+ * older browsers (Safari < 16). The SDK emits a plain
+ * `{ x, y, width, height }` shape that is structurally compatible
+ * with DOMRectReadOnly but JSON-safe.
+ */
+export interface SectionRect {
+    index: number;
+    documentRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * ADR-125 D2/D3 (PR2) — a single annotated field's bounding rect. `path`
+ * is the walker-canonical field path (ADR-068 grammar) read off the
+ * element's `data-ss-field`, relative to its nearest `data-ss-doc`
+ * scope; `docId` is that scope (the originating document — propagated
+ * across resolved refs by the Proxy, so a click on a cross-doc fragment
+ * resolves to the right document). Same coordinate contract as
+ * `SectionRect` (document-relative, scroll-invariant).
+ */
+export interface FieldRect {
+    path: string;
+    docId: string | null;
+    documentRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * ADR-125 D2/D3 (PR2) — field-level bounding rects, emitted by the
+ * section-reporter v2 runtime in the SAME rAF-coalesced pass as
+ * `section-bounds` (ONE pipeline — not a forked one: same observer
+ * triptyque, same schedule, same `epoch` echo). The parent feeds this
+ * through the SAME generic D7 settle core + the SAME bounded fail-safe
+ * clock as section-bounds, keyed by the SAME ADR-119 controller
+ * generation. Sibling message (not a field added to `section-bounds`)
+ * purely so the section path PR1b shipped + cross-model-reviewed is
+ * byte-unchanged; the shared machinery is the anti-fork requirement,
+ * and it is shared.
+ */
+export interface MsgFieldBounds {
+    type: 'field-bounds';
+    /** Always `'document'` — identical posture + rationale as the
+     *  `section-bounds` coordinate space. */
+    coordinateSpace: 'document';
+    fields: FieldRect[];
+    /** The `MsgRenderMode.epoch` last sent, echoed by the other geometry
+     *  and form-contract messages (ADR-125 D7
+     *  ratchet — a report whose epoch ≠ the live generation is
+     *  discarded). */
+    epoch: number;
+}
+/** User completed a section drag-and-drop. */
+export interface MsgDragEnd {
+    type: 'drag-end';
+    from: number;
+    to: number;
+}
+/**
+ * ADR-131 §D8.1 — canonical `CoverageTier` tagged union. Single source
+ * of truth for "what does this field's coverage look like" surfaced to
+ * the Coverage Panel + Studio overlay paint projection (§D8.4).
+ *
+ * Bound tiers (`explicit`, `observed`) PAINT overlays. `unsupported`
+ * records an annotation-model gap; `pending` and `stale` remain generic
+ * ambient states for the future Coverage Panel (zero producer today).
+ *
+ * Owner decision, 2026-08-10: the measurement vocabulary was retired.
+ * Field identity is authored by SDK annotations, never inferred from DOM
+ * output. Adding a new annotation tier is additive; reintroducing a
+ * measurement tier requires an explicit owner decision.
+ */
+export type CoverageTier = {
+    kind: 'explicit';
+} | {
+    kind: 'observed';
+} | {
+    kind: 'unsupported';
+    reason: 'no-annotation-carrier' | 'annotation-not-forwarded' | 'non-dom-output';
+} | {
+    kind: 'pending';
+    since: number;
+} | {
+    kind: 'stale';
+};
+/**
+ * ADR-129 — one item in the atomic preview snapshot. `method` carries
+ * the live authored (`explicit`) and provenance (`observed`) paths;
+ * `tier` carries their coverage semantics. ADR-138 §5.5 + ADR-139 §2.5
+ * extend the wire further with the anchor-typed fields below
+ * (`anchorKind`, `anchorKey`, `anchoredPath`),
+ * additive optional in v1 ; producers (ADR-140 walker) populate them
+ * as the cache-write layer lands. `method` records WHICH RESOLVER
+ * PRIORITY SLOT produced this item (provenance signal for the
+ * preview-surface gate); `tier` records the COVERAGE SEMANTICS surfaced
+ * to the panel + the paint projection at §D8.4. The two unions are NOT
+ * congruent (panel-only states have no `method`); both ship.
+ *
+ * Identity is `(documentId, anchored-canonical-path)` — D1. `path` is
+ * the numeric canonical path; `fromAnchors` carries the `_key` of each
+ * keyed array hop so the Studio resolver's `substituteAnchors` consumes
+ * it with no grammar change (ADR-066 transport shape).
+ */
+export interface SnapshotItem {
+    kind: 'slice' | 'field';
+    /**
+     * ADR-142 P0/P1 — iframe-produced sidecar lookup key for in-iframe
+     * Preview field painting. Opaque to Studio. This is NOT the Studio
+     * paint generation key; Studio mints `paintKey` when it sends an
+     * approved overlay-map back to the iframe.
+     */
+    snapshotItemKey?: string;
+    /**
+     * Resolver-provenance signal (ADR-131 §D6.1):
+     *   - `'explicit'`               — Layer 3 `data-ss-bind` attribute (was `'binding'`).
+     *   - `'observed'` — live coded-text provenance owner-map producer.
+     */
+    method: 'explicit' | 'observed';
+    /**
+     * Field-ownership / routing identity (ADR-139 §2.5). The doc the
+     * Studio click route opens. For Tier-1 explicit `<edit.* doc="X">`
+     * this is the customer-declared owner ; for cross-doc observed entries
+     * it may differ from the host page's doc.
+     */
+    documentId: string;
+    /**
+     * The `_key` of the owning slice (the snapshot↔island join key).
+     * PRESENT when `anchorKind === 'slice'` or absent (`'slice'`-by-
+     * construction items always set this) ; OMITTED when
+     * `anchorKind === 'doc'` or `'document-root'` per ADR-138 §5.5.
+     *
+     * The walker (ADR-140 §2.8) drives the optionality : for cross-doc /
+     * chrome items whose anchor is a `[data-ss-doc]` marker or the
+     * document root, there is no slice key, so emitting the empty string
+     * would mis-key downstream consumers ; emitting `undefined` makes
+     * the absence syntactic.
+     */
+    sliceKey?: string;
+    /** Numeric canonical path — `sections[0]` (slice) | `sections[0].headline` (field). */
+    path: string;
+    /** ADR-066 keyed-hop anchors for `path` (the slice `_key` hop). */
+    fromAnchors: ReadonlyArray<{
+        pathPrefix: string;
+        key: string;
+    }>;
+    /**
+     * Optional mounted Studio navigation path. C4 nested zone-container
+     * overlays keep `path` as the visual ancestry (`sections[0].sidebar[1]`)
+     * while Studio mounts the widget at the mapped document field
+     * (`sidebar[1]`). When omitted, `path` is already routable.
+     */
+    navigationPath?: string;
+    /** Keyed-hop anchors for `navigationPath`; omitted when `path` is routable. */
+    navigationAnchors?: ReadonlyArray<{
+        pathPrefix: string;
+        key: string;
+    }>;
+    /** Schema-relative field path; `''` for a `slice` item. */
+    field: string;
+    /** Document-space rect (`getBoundingClientRect` + scroll) — scroll-invariant. */
+    documentRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * ADR-131 §D6.5 — canonical coverage tier surfaced to the Coverage
+     * Panel + the §D8.4 `tierToVisualStyle(tier, devModeFlag)` paint
+     * projection. `method` (above) is the resolver-provenance signal;
+     * this is the coverage semantics. Both ship on the wire.
+     */
+    tier: CoverageTier;
+    /**
+     * ADR-138 §5.3 + ADR-139 §2.5 — DOM-marker / paint-identity discriminator.
+     * When set, narrows how the resolver locates the anchor element:
+     *   - `'slice'`         — DOM lookup via `[data-ss-slice="<anchorKey>"]` ;
+     *                          `anchorKey` is the slice `_key`.
+     *   - `'doc'`           — DOM lookup via `[data-ss-doc="<anchorKey>"]` ;
+     *                          `anchorKey` is the doc id of the host marker.
+     *                          ADR-139 §2.5 relaxes the §2.6 invariant
+     *                          `anchorKey === documentId` ; `anchorKey` is
+     *                          orthogonal to `documentId` (the latter remains
+     *                          field-ownership / routing identity).
+     *   - `'document-root'` — DOM lookup via `document.body` ; `anchorKey` is
+     *                          the empty string per ADR-138 §2 table.
+     *
+     * Additive optional in v1 — pre-138 items omit it ; v2+ producers
+     * (ADR-140 walker) populate.
+     */
+    anchorKind?: 'slice' | 'doc' | 'document-root';
+    /**
+     * DOM-marker key per `anchorKind` (see above). When `anchorKind ===
+     * 'document-root'` the value is the empty string (the unique
+     * `<body>` is implicit). When `anchorKind === 'doc'` the value lives
+     * in the Studio-authoritative document set per ADR-139 §2.3 (the
+     * gate validates membership). Additive optional in v1.
+     */
+    anchorKey?: string;
+    /**
+     * ADR-138 §5.5 — anchored path relative to the anchor element. The
+     * resolver walks from the anchor element along this path during the
+     * per-rAF DOM scan (ADR-140 territory). Additive optional in v1.
+     */
+    anchoredPath?: string | null;
+}
+/**
+ * ADR-129 D6 — the ATOMIC preview snapshot. One message per render
+ * carries everything the Studio overlay layer needs: the controller
+ * `epoch` (echoed from `MsgRenderMode`), the customer-side `renderId`
+ * (from the model island), the `pageDocId` the iframe is showing, the
+ * set of documentIds present, and every overlay `item`. `codeVersion`
+ * carries the upstream build signature and `timestamp` records the
+ * producing rAF tick.
+ */
+export interface MsgPreviewSnapshot {
+    type: 'storystick.preview.snapshot';
+    epoch: number;
+    renderId: string;
+    pageDocId: string;
+    /**
+     * Optional forward-capability bitmap. Studio must not send newer
+     * overlay-map item keys back to runtimes that did not explicitly
+     * advertise support for them because older SDK validators reject
+     * unknown keys with a strict allowlist.
+     */
+    capabilities?: {
+        crossDocumentOverlayLabels?: true;
+    };
+    /**
+     * ADR-139 §2.1 + §5 — formerly `visibleDocumentIds`, renamed at the
+     * wire level (codex R2 P1#3 absorbed at the ADR layer). The field is
+     * NEVER consulted by the Studio anti-bleed gate ; ADR-139 ships a
+     * Studio-side `authoritativeSet` derivation (`useAuthoritativeDocSet`)
+     * that composes membership from four trusted sources (commandedDoc +
+     * Studio-side chrome enumeration + Studio-side page-closure walker +
+     * SDK transport tap via `previewSessions.knownDocuments`). The
+     * iframe-declared set survives only as a debug hint surfaced to the
+     * Coverage Panel + harness — the rename makes the non-authoritative
+     * role syntactic ; a future producer cannot accidentally consult it
+     * for a trust decision because the name itself denies it. Pre-launch
+     * posture per the monorepo CLAUDE.md "no legacy support" rule —
+     * pre-rename `visibleDocumentIds` is removed entirely (no deprecation
+     * period).
+     */
+    iframeDeclaredDocumentIdsDebugHint: string[];
+    items: SnapshotItem[];
+    /**
+     * ADR-131 §D7.1a — upstream build/schema/config signature the iframe
+     * was hydrated with. Studio controller compares
+     * `snapshot.codeVersion !== controller.codeVersion` to detect a
+     * customer redeploy mid-stream (§D5.7).
+     */
+    codeVersion: string;
+    /**
+     * ADR-131 §D3.2 — Unix millis (Date.now()) at the rAF tick that
+     * produced this snapshot. The iframe correlation-window sampler
+     * subtracts the `T_edit` postMessage receipt timestamp to feed the
+     * EMA-based adaptive correlation window.
+     */
+    timestamp: number;
+    /**
+     * ADR-131 amendment-003 + ADR-139 §5.5 — SHA-256 hex of the live
+     * customer `routeUrl` the iframe is rendering against (post-redirect,
+     * NOT the bootstrap URL). Iframe-side `computeRouteHash` is the
+     * authoritative producer ; the Studio reads this verbatim and threads
+     * it into `useAuthoritativeDocSet` (which feeds
+     * `previewSessions.knownDocuments`). The Studio MUST NOT recompute
+     * from its own `effectiveSrc` (the iframe `src` attribute), which
+     * during the normal boot flow points at the preview-route bootstrap
+     * (`/api/storystick/preview?...redirect=...`) ; hashing the bootstrap
+     * URL would key a different `(sessionId, routeHash, codeVersion)`
+     * row than the SDK transport-tap wrote, and the gate would silently
+     * drop legitimate cross-doc overlays (codex R1 P1#2 absorbed).
+     *
+     * Optional in v1 because pre-amendment-003 runtimes never produced
+     * the field ; an absent value forces the Studio hook to pass `'skip'`
+     * to `knownDocuments`. The Studio treats `undefined` / `''` /
+     * pre-emit as "no SDK-tap data yet" (correct degradation : the gate
+     * doesn't paint cross-doc overlays until the iframe has a real route
+     * hash to report).
+     */
+    routeHash?: string;
+    /**
+     * Live customer URL the iframe is rendering against (post-redirect,
+     * NOT the Studio iframe `src` bootstrap URL). Studio uses this as
+     * debug context and to keep route-scoped document observations aligned.
+     */
+    routeUrl?: string;
+}
+export type IframeToStudio = {
+    type: 'ready';
+} | {
+    type: 'section-bounds';
+    coordinateSpace: 'document';
+    sections: SectionRect[];
+    epoch: number;
+} | MsgFieldBounds | {
+    type: 'section-hover';
+    index: number | null;
+} | {
+    type: 'sections';
+    data: unknown[];
+} | MsgDragEnd | {
+    type: 'add-section';
+    index: number;
+} | {
+    type: 'storystick.preview.form-contract';
+    epoch: number;
+    applied: boolean;
+    pageHeight: number;
+    viewportHeight: number;
+    windowedProjection?: 'pending' | 'active' | 'unsupported';
+    windowedProjectionReason?: string;
+    windowStart?: number;
+    renderSpan?: number;
+    compression?: number;
+} | MsgPreviewSnapshot;
+/**
+ * Best-effort runtime guard for messages the iframe sends to the
+ * Studio. Used by the bridge to ignore unrelated postMessage events
+ * (extensions, devtools, third-party scripts) without throwing.
+ *
+ * The discriminator (`type` string) is the only thing we trust — we
+ * narrow with the union after this guard.
+ */
+export declare function isIframeToStudio(value: unknown): value is IframeToStudio;
+/** Mirror guard for Studio → iframe (used iframe-side). */
+export declare function isStudioToIframe(value: unknown): value is StudioToIframe;

package/dist/types.js

@@ -0,0 +1,85 @@
+/**
+ * Storystick Studio ↔ Preview iframe — postMessage protocol types.
+ *
+ * Authoritative reference for the protocol defined in
+ *   storystick-hq/spec/preview-system.md  §"Communication Protocol"
+ *   storystick-hq/architecture/decisions/059-studio-shell-redesign.md  §6
+ *   storystick-hq/architecture/decisions/065-field-level-navigation-primitive.md  §3.7
+ *
+ * Two orthogonal axes carried by the protocol itself:
+ *
+ *   render-mode  : 'navigation' | 'device'
+ *     Controls iframe internal viewport (1280px vs device width),
+ *     scale transform, pointer-events, and where overlays render
+ *     (parent DOM vs in-iframe).
+ *
+ *   overlay-mode : 'section' | 'field'
+ *     Controls overlay granularity (slice boundary vs individual
+ *     field). Independent of render-mode — pairings are defaults,
+ *     not constraints.
+ *
+ * Click handling is NOT in this protocol — by design. ADR-065 owns the
+ * cross-frame navigation entry point. A child iframe posts the canonical
+ * `{ action: 'navigate', verb, value, from }` message exported from
+ * `@storystick/preview`. The Studio's field-navigation listener routes that
+ * target through the shared arrival service. PR2' does not duplicate it.
+ *
+ * Versioning convention
+ * ---------------------
+ * The protocol is a flat discriminated union on `type`. New
+ * variants extend the union; existing variants are never mutated.
+ * If a wire-level break is ever required, introduce a new top-level
+ * variant (e.g. `type: 'v2-section-bounds'`) rather than versioning
+ * the envelope. This keeps the runtime check trivially exhaustive
+ * via TypeScript's `never` narrowing.
+ */
+// ─── Type guards ─────────────────────────────────────────
+/**
+ * Best-effort runtime guard for messages the iframe sends to the
+ * Studio. Used by the bridge to ignore unrelated postMessage events
+ * (extensions, devtools, third-party scripts) without throwing.
+ *
+ * The discriminator (`type` string) is the only thing we trust — we
+ * narrow with the union after this guard.
+ */
+export function isIframeToStudio(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    if (typeof v.type !== 'string')
+        return false;
+    switch (v.type) {
+        case 'ready':
+        case 'section-bounds':
+        case 'field-bounds':
+        case 'section-hover':
+        case 'sections':
+        case 'drag-end':
+        case 'add-section':
+        case 'storystick.preview.form-contract':
+        case 'storystick.preview.snapshot':
+            return true;
+        default:
+            return false;
+    }
+}
+/** Mirror guard for Studio → iframe (used iframe-side). */
+export function isStudioToIframe(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    if (typeof v.type !== 'string')
+        return false;
+    switch (v.type) {
+        case 'render-mode':
+        case 'storystick.preview.windowed-minimap':
+        case 'overlay-mode':
+        case 'highlight':
+        case 'scroll':
+        case 'device-width':
+        case 'storystick.preview.host-resize':
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/validators.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Iframe-side preview-envelope validators (ADR-087 §3.2).
+ *
+ * Thin wrapper around `validatePreviewEnvelope` from
+ * `@storystick/transport-allowlist` (the foundation Lane C shipped).
+ * Adds the iframe-side context checks the foundation deliberately left out:
+ *
+ *   - `sessionId` and `projectId` match the iframe's known values
+ *     (they should never change mid-session).
+ *   - `event.origin === parentOrigin` once the parent origin is
+ *     learned (see "learn-and-lock" comment below).
+ *
+ * The foundation validator owns structure + anti-replay base
+ * (`MAX_ENVELOPE_AGE_MS`) + normative error wording. This module owns
+ * everything that needs *iframe context*: identity and the locked parent
+ * origin.
+ *
+ * Returning a discriminated `{ ok, ... }` keeps the call-site clean —
+ * the consumer handles `ok: false` by either ignoring the message
+ * (stale / mis-correlated) or transitioning to `error` (auth failed).
+ */
+import { type NavigateEnvelope, type PreviewOverlayClearEnvelope, type PreviewOverlayMapEnvelope, type PreviewV2RevealSourceEnvelope } from '@storystick/transport-allowlist';
+/**
+ * Reasons a context-aware validation can fail. Strings are stable —
+ * the state machine + tests grep on them. They surface only in
+ * iframe-internal logs; NEVER over the postMessage wire (the iframe
+ * → parent direction silent on rejections).
+ */
+export type ValidationFailure = 'envelope-invalid' | 'wrong-message-type' | 'origin-mismatch' | 'session-id-mismatch' | 'project-id-mismatch';
+export type ValidationResult<T> = {
+    ok: true;
+    envelope: T;
+} | {
+    ok: false;
+    reason: ValidationFailure;
+};
+/**
+ * Validate an incoming `navigate` envelope against the locked parent
+ * origin and the iframe's known sessionId / projectId. Navigate
+ * messages are unsolicited (no pending request to correlate against)
+ * — we only check origin lock + identity binding.
+ *
+ * **Pre-lock policy (codex Lane D round 1 P1 fix)** : `parentOrigin
+ * === null` means the iframe has not yet locked Studio's origin.
+ * Navigate messages received in that window are rejected
+ * unconditionally (`origin-mismatch`). Without this, any same-host
+ * script with a valid envelope shape could drive `history.pushState`
+ * on the iframe before the legitimate Studio handshake finishes.
+ * The identity broadcast is the only origin-learning path; navigation MUST
+ * wait for that lock.
+ */
+export declare function validateNavigate(raw: unknown, eventOrigin: string, knownSessionId: string, knownProjectId: string, parentOrigin: string | null, now?: number): ValidationResult<NavigateEnvelope>;
+export declare function validateOverlayMap(raw: unknown, eventOrigin: string, knownSessionId: string, knownProjectId: string, parentOrigin: string | null, now?: number): ValidationResult<PreviewOverlayMapEnvelope>;
+export declare function validateOverlayClear(raw: unknown, eventOrigin: string, knownSessionId: string, knownProjectId: string, parentOrigin: string | null, now?: number): ValidationResult<PreviewOverlayClearEnvelope>;
+export declare function validatePreviewV2RevealSource(raw: unknown, eventOrigin: string, knownSessionId: string, knownProjectId: string, parentOrigin: string | null, now?: number): ValidationResult<PreviewV2RevealSourceEnvelope>;
+/**
+ * Re-export so consumers can import the foundation types from one
+ * place. Keeping the wrapper module the surface helps grepping for
+ * preview-envelope usage during audits.
+ */
+export type { NavigateEnvelope, PreviewOverlayClearEnvelope, PreviewOverlayMapEnvelope, };