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

package/dist/interaction-mode.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Iframe-side `interaction-mode` state (ADR-108 D2 + D7).
+ *
+ * Module-level state mirror of the Studio's authoritative
+ * `interactionMode`. Studio is the writer (via the imperative
+ * `bridge.setInteractionMode(mode)` method), the SDK is the reader
+ * (the click interceptors inside `@storystick/preview`'s overlay
+ * runtime + the customer's own gating if desired).
+ *
+ * Two modes:
+ *   - `'edit'` (default): iframe-local overlay click interceptors
+ *     `preventDefault()` on approved field targets and emit
+ *     `storystick.preview.overlay-click` so Studio validates the
+ *     `paintKey` before routing to the editor.
+ *   - `'browse'`: SDK click interceptors let the click bubble untouched
+ *     so the customer's `<a>` natively navigates. The reverse `location`
+ *     channel still flows so Studio mirrors the iframe's URL via
+ *     reverse doc lookup (D5).
+ *
+ * Realm-level (no React, no component/session ownership). Multiple SDK
+ * entrypoints can be bundled into separate physical module graphs in the same
+ * iframe. They must still observe one mode and one listener set, so browser
+ * state lives on the Window under a global-symbol key. Click interceptors live
+ * inside framework-agnostic overlay runtime; they read the mode through
+ * `getInteractionMode()` at click time.
+ */
+export type InteractionMode = 'edit' | 'browse';
+/**
+ * Read the current interaction mode. Click interceptors call this
+ * synchronously inside their handlers; the result is the mode the
+ * Studio last sent via `interaction-mode` envelope.
+ *
+ * Default is `'edit'` until Studio explicitly emits a mode. This
+ * matches today's behaviour pre-ADR-108 (everything is edit-mode by
+ * default) so existing customers see no behaviour change without an
+ * explicit toggle.
+ */
+export declare function getInteractionMode(): InteractionMode;
+/**
+ * Set the interaction mode. Invoked by `activate()`'s message
+ * listener after it validates an incoming `interaction-mode`
+ * envelope. Idempotent re-asserts deliberately notify subscribers: the
+ * in-memory value can outlive the runtime-owned stylesheet across iframe/head
+ * lifecycle changes, so each authoritative replay is also a reconciliation
+ * signal.
+ *
+ * Exposed (rather than module-private) so tests can drive the mode
+ * directly without going through the full envelope path; also so a
+ * future Studio dev-tool / hostile-actor mitigation can call it
+ * defensively.
+ */
+export declare function setInteractionMode(mode: InteractionMode): void;
+export declare function subscribeInteractionMode(listener: (mode: InteractionMode) => void): () => void;
+/**
+ * Test-only reset. Vitest modules are isolated per file but cases
+ * within a single file would otherwise share state.
+ */
+export declare function _resetInteractionModeForTests(): void;

package/dist/interaction-mode.js

@@ -0,0 +1,93 @@
+/**
+ * Iframe-side `interaction-mode` state (ADR-108 D2 + D7).
+ *
+ * Module-level state mirror of the Studio's authoritative
+ * `interactionMode`. Studio is the writer (via the imperative
+ * `bridge.setInteractionMode(mode)` method), the SDK is the reader
+ * (the click interceptors inside `@storystick/preview`'s overlay
+ * runtime + the customer's own gating if desired).
+ *
+ * Two modes:
+ *   - `'edit'` (default): iframe-local overlay click interceptors
+ *     `preventDefault()` on approved field targets and emit
+ *     `storystick.preview.overlay-click` so Studio validates the
+ *     `paintKey` before routing to the editor.
+ *   - `'browse'`: SDK click interceptors let the click bubble untouched
+ *     so the customer's `<a>` natively navigates. The reverse `location`
+ *     channel still flows so Studio mirrors the iframe's URL via
+ *     reverse doc lookup (D5).
+ *
+ * Realm-level (no React, no component/session ownership). Multiple SDK
+ * entrypoints can be bundled into separate physical module graphs in the same
+ * iframe. They must still observe one mode and one listener set, so browser
+ * state lives on the Window under a global-symbol key. Click interceptors live
+ * inside framework-agnostic overlay runtime; they read the mode through
+ * `getInteractionMode()` at click time.
+ */
+const INTERACTION_MODE_STATE_KEY = Symbol.for('storystick.preview.interaction-mode-state.v1');
+const serverState = createInteractionModeState();
+function createInteractionModeState() {
+    return {
+        currentMode: 'edit',
+        listeners: new Set(),
+    };
+}
+function getInteractionModeState() {
+    if (typeof window === 'undefined')
+        return serverState;
+    const existing = Reflect.get(window, INTERACTION_MODE_STATE_KEY);
+    if (existing !== undefined)
+        return existing;
+    const state = createInteractionModeState();
+    Reflect.set(window, INTERACTION_MODE_STATE_KEY, state);
+    return state;
+}
+/**
+ * Read the current interaction mode. Click interceptors call this
+ * synchronously inside their handlers; the result is the mode the
+ * Studio last sent via `interaction-mode` envelope.
+ *
+ * Default is `'edit'` until Studio explicitly emits a mode. This
+ * matches today's behaviour pre-ADR-108 (everything is edit-mode by
+ * default) so existing customers see no behaviour change without an
+ * explicit toggle.
+ */
+export function getInteractionMode() {
+    return getInteractionModeState().currentMode;
+}
+/**
+ * Set the interaction mode. Invoked by `activate()`'s message
+ * listener after it validates an incoming `interaction-mode`
+ * envelope. Idempotent re-asserts deliberately notify subscribers: the
+ * in-memory value can outlive the runtime-owned stylesheet across iframe/head
+ * lifecycle changes, so each authoritative replay is also a reconciliation
+ * signal.
+ *
+ * Exposed (rather than module-private) so tests can drive the mode
+ * directly without going through the full envelope path; also so a
+ * future Studio dev-tool / hostile-actor mitigation can call it
+ * defensively.
+ */
+export function setInteractionMode(mode) {
+    const state = getInteractionModeState();
+    state.currentMode = mode;
+    for (const listener of [...state.listeners]) {
+        listener(mode);
+    }
+}
+export function subscribeInteractionMode(listener) {
+    const state = getInteractionModeState();
+    state.listeners.add(listener);
+    return () => {
+        state.listeners.delete(listener);
+    };
+}
+/**
+ * Test-only reset. Vitest modules are isolated per file but cases
+ * within a single file would otherwise share state.
+ */
+export function _resetInteractionModeForTests() {
+    const state = getInteractionModeState();
+    state.currentMode = 'edit';
+    state.listeners.clear();
+}

package/dist/nav-handler.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Cross-frame navigation hook (ADR-087 §3.2).
+ *
+ * Studio → iframe `storystick.preview.navigate` postMessage drives
+ * SPA-internal navigation when the editor switches docs / changes
+ * the pathname / picks a variant with a different pathname. The
+ * handling is **best-effort CSR** (codex round 3 finding C9, ADR
+ * §3.2 honest claim) — Lane D' will provide framework adapters
+ * (Next, Astro, Vanilla). Lane D defines the contract.
+ *
+ * Two pieces :
+ *
+ *   1. `setNavigateHandler(fn)` — consumer registers a callback. The
+ *      framework adapters call this in their provider integration
+ *      with `(pathname) => router.push(pathname)`. The default is a
+ *      no-op so the iframe doesn't crash if no adapter is loaded.
+ *
+ *   2. `getNavigateHandler()` — internal getter for the iframe-side
+ *      `message` listener (in `index.ts` orchestrator). The listener
+ *      validates the envelope through `validateNavigate` and only
+ *      invokes the handler with a sanitized pathname.
+ *
+ * `pathname` validation is enforced upstream (in
+ * `validatePreviewEnvelope` from the foundation Lane C — same-origin
+ * absolute paths only, no `javascript:` / `//cross-origin` / scheme
+ * switches). The handler receives a value already cleared by that
+ * validator.
+ */
+import type { PreviewScopeSelection, PreviewContextCommandFence } from '@storystick/transport-allowlist';
+/**
+ * Optional metadata forwarded to the handler from the envelope payload.
+ *
+ * ADR-111 — `refresh` signals to framework adapters that the navigate
+ * accompanies a change in root-layout preview state (typically
+ * `draftDocumentId`). App Router adapters refresh the client Router Cache
+ * after the destination commits; they must not start `router.replace()` and
+ * `router.refresh()` as concurrent Flight transitions. Pages Router adapters
+ * ignore the flag (no cached layout to invalidate).
+ *
+ * Generic name on purpose — the contract is "layout preview state has
+ * changed." Future fields affecting `resolvePreviewDraft()` reuse the
+ * same flag without a handler signature bump.
+ */
+export interface NavigateHandlerOptions {
+    history?: 'push' | 'replace';
+    refresh?: boolean;
+    scope: PreviewScopeSelection;
+    commandId?: string;
+    contextCommand?: PreviewContextCommandFence;
+}
+/**
+ * Handler signature. The pathname is guaranteed to be an absolute
+ * same-origin path starting with `/` (validated by the foundation
+ * envelope validator, see Lane C foundation round 3 fix).
+ *
+ * `options` is optional for backward compatibility — handlers
+ * registered before ADR-111 keep their `(pathname) => …` signature and
+ * the new field is simply ignored by them. Adapters that want to react
+ * to `refresh: true` add it explicitly.
+ */
+export type NavigateHandler = (pathname: string, options?: NavigateHandlerOptions) => void;
+export interface ReloadHandlerOptions {
+    commandId: string;
+}
+export type ReloadMode = 'soft' | 'hard';
+export type ReloadHandler = (mode: ReloadMode, options: ReloadHandlerOptions) => void;
+interface PreviewNavigationHandlerCell {
+    navigate: NavigateHandler;
+    reload: ReloadHandler;
+}
+declare global {
+    var __storystick_preview_navigation_handlers__: PreviewNavigationHandlerCell | undefined;
+}
+/**
+ * Register a navigation handler. Replaces any previously registered
+ * handler — the framework adapter that wires up first wins, but a
+ * later override (e.g. customer's own router) takes precedence.
+ *
+ * Pass `null` to reset to the default no-op (useful for tests +
+ * Provider unmount cleanup).
+ */
+export declare function setNavigateHandler(fn: NavigateHandler | null): void;
+/** Internal accessor — used by the orchestrator's message listener. */
+export declare function getNavigateHandler(): NavigateHandler;
+/** True once a framework adapter has replaced the default no-op handler. */
+export declare function hasNavigateHandler(): boolean;
+export declare function setReloadHandler(fn: ReloadHandler | null): void;
+export declare function getReloadHandler(): ReloadHandler;
+/**
+ * Test-only reset. Vitest modules are isolated per file, but a
+ * single test file with multiple `setNavigateHandler` calls would
+ * otherwise share state across cases.
+ */
+export declare function _resetNavigateHandlerForTests(): void;
+export {};

package/dist/nav-handler.js

@@ -0,0 +1,84 @@
+/**
+ * Cross-frame navigation hook (ADR-087 §3.2).
+ *
+ * Studio → iframe `storystick.preview.navigate` postMessage drives
+ * SPA-internal navigation when the editor switches docs / changes
+ * the pathname / picks a variant with a different pathname. The
+ * handling is **best-effort CSR** (codex round 3 finding C9, ADR
+ * §3.2 honest claim) — Lane D' will provide framework adapters
+ * (Next, Astro, Vanilla). Lane D defines the contract.
+ *
+ * Two pieces :
+ *
+ *   1. `setNavigateHandler(fn)` — consumer registers a callback. The
+ *      framework adapters call this in their provider integration
+ *      with `(pathname) => router.push(pathname)`. The default is a
+ *      no-op so the iframe doesn't crash if no adapter is loaded.
+ *
+ *   2. `getNavigateHandler()` — internal getter for the iframe-side
+ *      `message` listener (in `index.ts` orchestrator). The listener
+ *      validates the envelope through `validateNavigate` and only
+ *      invokes the handler with a sanitized pathname.
+ *
+ * `pathname` validation is enforced upstream (in
+ * `validatePreviewEnvelope` from the foundation Lane C — same-origin
+ * absolute paths only, no `javascript:` / `//cross-origin` / scheme
+ * switches). The handler receives a value already cleared by that
+ * validator.
+ */
+/**
+ * Default no-op. The framework adapters override via
+ * `setNavigateHandler`. Without an adapter, the iframe simply does
+ * not navigate when Studio asks — the published preview content
+ * stays on the current page. The honest claim is "best-effort" so
+ * a silent ignore is acceptable when no router is wired.
+ */
+const NOOP = () => {
+    /* default = no-op */
+};
+const RELOAD_NOOP = () => {
+    /* default = no-op */
+};
+function handlerCell() {
+    const existing = globalThis.__storystick_preview_navigation_handlers__;
+    if (existing)
+        return existing;
+    const created = { navigate: NOOP, reload: RELOAD_NOOP };
+    globalThis.__storystick_preview_navigation_handlers__ = created;
+    return created;
+}
+/**
+ * Register a navigation handler. Replaces any previously registered
+ * handler — the framework adapter that wires up first wins, but a
+ * later override (e.g. customer's own router) takes precedence.
+ *
+ * Pass `null` to reset to the default no-op (useful for tests +
+ * Provider unmount cleanup).
+ */
+export function setNavigateHandler(fn) {
+    handlerCell().navigate = fn ?? NOOP;
+}
+/** Internal accessor — used by the orchestrator's message listener. */
+export function getNavigateHandler() {
+    return handlerCell().navigate;
+}
+/** True once a framework adapter has replaced the default no-op handler. */
+export function hasNavigateHandler() {
+    return handlerCell().navigate !== NOOP;
+}
+export function setReloadHandler(fn) {
+    handlerCell().reload = fn ?? RELOAD_NOOP;
+}
+export function getReloadHandler() {
+    return handlerCell().reload;
+}
+/**
+ * Test-only reset. Vitest modules are isolated per file, but a
+ * single test file with multiple `setNavigateHandler` calls would
+ * otherwise share state across cases.
+ */
+export function _resetNavigateHandlerForTests() {
+    const cell = handlerCell();
+    cell.navigate = NOOP;
+    cell.reload = RELOAD_NOOP;
+}

package/dist/overlay-label.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared visual primitive for non-interactive preview overlay labels.
+ *
+ * Studio renders slice labels in its React overlay while the preview runtime
+ * renders field labels directly in the customer iframe. They intentionally
+ * share these visual tokens so both surfaces remain one interaction system.
+ */
+export declare const PREVIEW_OVERLAY_LABEL_GAP_PX = 4;
+export declare const PREVIEW_OVERLAY_LABEL_HEIGHT_PX = 20;
+export type PreviewOverlayTone = 'default' | 'model';
+export declare const PREVIEW_OVERLAY_VISUAL_STYLES: {
+    readonly default: {
+        readonly color: "oklch(0.614 0.194 257 / 0.9)";
+        readonly revealColor: "oklch(0.614 0.194 257 / 0.95)";
+    };
+    readonly model: {
+        readonly color: "oklch(0.635 0.19 322 / 0.9)";
+        readonly revealColor: "oklch(0.635 0.19 322 / 0.95)";
+    };
+};
+export declare const PREVIEW_OVERLAY_LABEL_VISUAL_STYLES: {
+    readonly default: {
+        readonly background: "oklch(0.46 0.12 257 / 0.96)";
+        readonly borderRadius: "999px";
+        readonly padding: "3px 8px";
+        readonly font: "500 11px/14px system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+        readonly color: "white";
+        readonly boxShadow: "0 0 0 1px oklch(1 0 0 / 0.72)";
+    };
+    readonly model: {
+        readonly background: "oklch(0.46 0.11 322 / 0.96)";
+        readonly borderRadius: "999px";
+        readonly padding: "3px 8px";
+        readonly font: "500 11px/14px system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+        readonly color: "white";
+        readonly boxShadow: "0 0 0 1px oklch(1 0 0 / 0.72)";
+    };
+};
+export declare function previewOverlayVisualStyle(tone: PreviewOverlayTone): {
+    readonly color: "oklch(0.614 0.194 257 / 0.9)";
+    readonly revealColor: "oklch(0.614 0.194 257 / 0.95)";
+} | {
+    readonly color: "oklch(0.635 0.19 322 / 0.9)";
+    readonly revealColor: "oklch(0.635 0.19 322 / 0.95)";
+};
+export declare function previewOverlayLabelVisualStyle(tone: PreviewOverlayTone): {
+    readonly background: "oklch(0.46 0.12 257 / 0.96)";
+    readonly borderRadius: "999px";
+    readonly padding: "3px 8px";
+    readonly font: "500 11px/14px system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly color: "white";
+    readonly boxShadow: "0 0 0 1px oklch(1 0 0 / 0.72)";
+} | {
+    readonly background: "oklch(0.46 0.11 322 / 0.96)";
+    readonly borderRadius: "999px";
+    readonly padding: "3px 8px";
+    readonly font: "500 11px/14px system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif";
+    readonly color: "white";
+    readonly boxShadow: "0 0 0 1px oklch(1 0 0 / 0.72)";
+};
+export interface PreviewOverlayLabelHorizontalPositionInput {
+    targetLeft: number;
+    targetWidth: number;
+    labelWidth: number;
+    viewportWidth: number;
+    gap?: number;
+}
+export interface PreviewOverlayLabelHorizontalPosition {
+    left: number;
+    anchor: 'left' | 'right';
+}
+/**
+ * Prefer the target's right edge while the label fits inside it. A label wider
+ * than its target instead grows from the target's left edge, unless that would
+ * leave the viewport. The final clamp is the safety net for edge targets and
+ * labels wider than the available viewport.
+ */
+export declare function resolvePreviewOverlayLabelHorizontalPosition({ targetLeft, targetWidth, labelWidth, viewportWidth, gap, }: PreviewOverlayLabelHorizontalPositionInput): PreviewOverlayLabelHorizontalPosition;
+export declare function applyPreviewOverlayLabelVisualStyle(element: HTMLElement, tone?: PreviewOverlayTone): void;

package/dist/overlay-label.js

@@ -0,0 +1,73 @@
+/**
+ * Shared visual primitive for non-interactive preview overlay labels.
+ *
+ * Studio renders slice labels in its React overlay while the preview runtime
+ * renders field labels directly in the customer iframe. They intentionally
+ * share these visual tokens so both surfaces remain one interaction system.
+ */
+export const PREVIEW_OVERLAY_LABEL_GAP_PX = 4;
+export const PREVIEW_OVERLAY_LABEL_HEIGHT_PX = 20;
+export const PREVIEW_OVERLAY_VISUAL_STYLES = {
+    default: {
+        color: 'oklch(0.614 0.194 257 / 0.9)',
+        revealColor: 'oklch(0.614 0.194 257 / 0.95)',
+    },
+    model: {
+        color: 'oklch(0.635 0.19 322 / 0.9)',
+        revealColor: 'oklch(0.635 0.19 322 / 0.95)',
+    },
+};
+const PREVIEW_OVERLAY_LABEL_BASE_STYLE = {
+    borderRadius: '999px',
+    padding: '3px 8px',
+    font: '500 11px/14px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+    color: 'white',
+    boxShadow: '0 0 0 1px oklch(1 0 0 / 0.72)',
+};
+export const PREVIEW_OVERLAY_LABEL_VISUAL_STYLES = {
+    default: {
+        ...PREVIEW_OVERLAY_LABEL_BASE_STYLE,
+        background: 'oklch(0.46 0.12 257 / 0.96)',
+    },
+    model: {
+        ...PREVIEW_OVERLAY_LABEL_BASE_STYLE,
+        background: 'oklch(0.46 0.11 322 / 0.96)',
+    },
+};
+export function previewOverlayVisualStyle(tone) {
+    return PREVIEW_OVERLAY_VISUAL_STYLES[tone];
+}
+export function previewOverlayLabelVisualStyle(tone) {
+    return PREVIEW_OVERLAY_LABEL_VISUAL_STYLES[tone];
+}
+/**
+ * Prefer the target's right edge while the label fits inside it. A label wider
+ * than its target instead grows from the target's left edge, unless that would
+ * leave the viewport. The final clamp is the safety net for edge targets and
+ * labels wider than the available viewport.
+ */
+export function resolvePreviewOverlayLabelHorizontalPosition({ targetLeft, targetWidth, labelWidth, viewportWidth, gap = PREVIEW_OVERLAY_LABEL_GAP_PX, }) {
+    const safeLabelWidth = Math.max(0, labelWidth);
+    const viewportRight = Math.max(gap, viewportWidth - gap);
+    const leftAnchoredPosition = targetLeft;
+    const rightAnchoredPosition = targetLeft + targetWidth - safeLabelWidth;
+    const leftAnchorFits = leftAnchoredPosition >= gap &&
+        leftAnchoredPosition + safeLabelWidth <= viewportRight;
+    const preferLeft = safeLabelWidth > targetWidth && leftAnchorFits;
+    const anchor = preferLeft ? 'left' : 'right';
+    const idealLeft = preferLeft ? leftAnchoredPosition : rightAnchoredPosition;
+    const maxLeft = Math.max(gap, viewportRight - safeLabelWidth);
+    return {
+        left: Math.min(Math.max(idealLeft, gap), maxLeft),
+        anchor,
+    };
+}
+export function applyPreviewOverlayLabelVisualStyle(element, tone = 'default') {
+    const style = previewOverlayLabelVisualStyle(tone);
+    element.style.borderRadius = style.borderRadius;
+    element.style.padding = style.padding;
+    element.style.font = style.font;
+    element.style.color = style.color;
+    element.style.background = style.background;
+    element.style.boxShadow = style.boxShadow;
+}

package/dist/provenance/anchor-map.d.ts

@@ -0,0 +1,95 @@
+import { type PreviewReadScopeEcho } from '@storystick/client/internal';
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import type { PublicProvenanceSidecar } from './sidecar.js';
+import type { DirectEditLocator } from './direct-edit-locator.js';
+import type { MarkerRecord } from './types.js';
+import type { PreviewFrameDependencySet } from './frame-dependencies.js';
+export interface AnchorInput {
+    readonly markerId: string;
+    /** Preview-only identity of one concrete paint target, including memory-backed coded text. */
+    readonly paintId?: string;
+    readonly tagName: string;
+    readonly text: string;
+    readonly connected: boolean;
+    readonly carrier?: 'attribute' | 'coded-text';
+    readonly documentRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export type PreviewLifecycleSourceOfTruth = 'studio' | 'iframe' | 'system';
+export interface PreviewRenderIdentity {
+    readonly generation: number;
+    readonly sourceOfTruth: PreviewLifecycleSourceOfTruth;
+    readonly commandId?: string;
+    readonly sessionId?: string;
+    readonly pathname?: string;
+    readonly routeHash?: string;
+    readonly codeVersion?: string;
+    readonly renderId?: string;
+    readonly variantId?: string | null;
+    readonly readContext?: PreviewReadContext;
+    readonly routeLocale?: string | null;
+}
+/** Exact local paint projection of the canonical render identity. */
+export type PreviewPaintRenderIdentity = PreviewRenderIdentity & Required<Pick<PreviewRenderIdentity, 'sessionId' | 'pathname' | 'routeHash' | 'codeVersion' | 'renderId' | 'variantId'>>;
+export type PreviewPaintRenderIdentityMismatch = 'session-id' | 'generation' | 'source-of-truth' | 'command-id' | 'pathname' | 'route-hash' | 'code-version' | 'render-id' | 'variant-id' | 'read-context' | 'route-locale';
+export declare function previewPaintRenderIdentityEquals(left: PreviewPaintRenderIdentity, right: PreviewPaintRenderIdentity): boolean;
+export declare function previewPaintRenderIdentityMismatch(left: PreviewPaintRenderIdentity, right: PreviewPaintRenderIdentity): PreviewPaintRenderIdentityMismatch | null;
+export interface AnchorMap {
+    readonly sessionId: string;
+    readonly generation: number;
+    readonly sourceOfTruth: PreviewLifecycleSourceOfTruth;
+    readonly commandId?: string;
+    readonly pathname: string;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId: string | null;
+    readonly previewScope?: PreviewReadScopeEcho;
+    readonly renderId: string;
+    readonly renderNonce?: string;
+    readonly emissionRevision?: number;
+    readonly dependencySet?: PreviewFrameDependencySet;
+    readonly phase: string;
+    readonly pending: boolean;
+    readonly anchors: readonly AnchorInput[];
+    /** Public marker-to-owner addresses delivered with this exact render. */
+    readonly editLocators?: readonly DirectEditMarkerLocator[];
+    readonly sidecarMarkerIds: readonly string[];
+    readonly invalidMarkerIds: readonly string[];
+    /** Opaque sidecar marker ids absent from the rendered DOM, non-fatal. */
+    readonly unpaintedMarkerIds: readonly string[];
+    readonly missingMarkerIds: readonly string[];
+    readonly ambiguousMarkerIds: readonly string[];
+    readonly contentMismatchMarkerIds: readonly string[];
+    readonly fatalContentMismatchMarkerIds?: readonly string[];
+    readonly paintDiagnostics?: AnchorPaintDiagnostics;
+    readonly valid: boolean;
+}
+export interface DirectEditMarkerLocator {
+    readonly markerId: string;
+    readonly locator: DirectEditLocator;
+    readonly modality: MarkerRecord['modality'];
+    readonly presence?: MarkerRecord['presence'];
+}
+export interface AnchorPaintDiagnostics {
+    readonly codedTextOnlyNotPaintable: readonly string[];
+    readonly domTargetPainted: readonly string[];
+}
+export interface BuildAnchorMapInput {
+    readonly sessionId: string;
+    readonly generation: number;
+    readonly sourceOfTruth: PreviewLifecycleSourceOfTruth;
+    readonly commandId?: string;
+    readonly pathname: string;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId?: string | null;
+    readonly sidecar: PublicProvenanceSidecar;
+    readonly anchors: readonly AnchorInput[];
+    readonly phase: string;
+    readonly pending?: boolean;
+}
+export declare function buildAnchorMap(input: BuildAnchorMapInput): AnchorMap;