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

package/dist/runtime/preview-overlay-sidecar.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ADR-142 P1 — in-iframe Preview overlay sidecar registry.
+ *
+ * Snapshot assembly can see the live Element for every produced item,
+ * but the Studio only receives serialisable SnapshotItems. The sidecar
+ * keeps the Element lookup in iframe memory and exposes opaque
+ * `snapshotItemKey` ids that Studio can echo back in an approved
+ * overlay-map.
+ */
+import type { SnapshotItem } from '../types.js';
+export interface PreviewOverlayRegistryTuple {
+    renderId: string;
+    routeHash: string | null;
+    codeVersion: string;
+    cacheVersion: number;
+}
+export interface PreviewOverlayRegistryDraft {
+    attach<T extends SnapshotItem>(item: T, element: Element): T;
+    entries(): ReadonlyMap<string, Element>;
+}
+export declare function createPreviewOverlayRegistryDraft(): PreviewOverlayRegistryDraft;
+export declare function attachPreviewOverlayRegistryTarget<T extends SnapshotItem>(item: T, element: Element, draft?: PreviewOverlayRegistryDraft): T;
+export declare function commitPreviewOverlayRegistryDraft(draft: PreviewOverlayRegistryDraft, tuple: PreviewOverlayRegistryTuple): void;
+export declare function clearPreviewOverlayRegistry(): void;
+export declare function getPreviewOverlayTarget(snapshotItemKey: string): Element | null;
+export declare function getPreviewOverlayRegistryTuple(): PreviewOverlayRegistryTuple | null;

package/dist/runtime/preview-overlay-sidecar.js

@@ -0,0 +1,45 @@
+/**
+ * ADR-142 P1 — in-iframe Preview overlay sidecar registry.
+ *
+ * Snapshot assembly can see the live Element for every produced item,
+ * but the Studio only receives serialisable SnapshotItems. The sidecar
+ * keeps the Element lookup in iframe memory and exposes opaque
+ * `snapshotItemKey` ids that Studio can echo back in an approved
+ * overlay-map.
+ */
+let activeTargets = new Map();
+let activeTuple = null;
+export function createPreviewOverlayRegistryDraft() {
+    let ordinal = 0;
+    const entries = new Map();
+    return {
+        attach(item, element) {
+            const snapshotItemKey = makeSnapshotItemKey(item, ordinal++);
+            entries.set(snapshotItemKey, element);
+            return { ...item, snapshotItemKey };
+        },
+        entries() {
+            return entries;
+        },
+    };
+}
+export function attachPreviewOverlayRegistryTarget(item, element, draft) {
+    return draft ? draft.attach(item, element) : item;
+}
+export function commitPreviewOverlayRegistryDraft(draft, tuple) {
+    activeTargets = new Map(draft.entries());
+    activeTuple = tuple;
+}
+export function clearPreviewOverlayRegistry() {
+    activeTargets.clear();
+    activeTuple = null;
+}
+export function getPreviewOverlayTarget(snapshotItemKey) {
+    return activeTargets.get(snapshotItemKey) ?? null;
+}
+export function getPreviewOverlayRegistryTuple() {
+    return activeTuple;
+}
+function makeSnapshotItemKey(_item, ordinal) {
+    return `snap1:${ordinal}`;
+}

package/dist/runtime/preview-perspective-alignment.d.ts

@@ -0,0 +1,15 @@
+import type { PreviewPerspective, PreviewReadContext } from '@storystick/types/preview-query-targeting';
+export type PreviewPerspectiveAlignmentObservation = {
+    readonly kind: 'unknown';
+} | {
+    readonly kind: 'aligned';
+    readonly context: PreviewReadContext;
+} | {
+    readonly kind: 'conflict';
+    readonly addressPerspective: PreviewPerspective | null;
+    readonly context: PreviewReadContext;
+};
+export declare const UNKNOWN_PREVIEW_PERSPECTIVE_ALIGNMENT: PreviewPerspectiveAlignmentObservation;
+export declare function derivePreviewPerspectiveAlignment(addressPerspective: PreviewPerspective | null, context: PreviewReadContext | null): PreviewPerspectiveAlignmentObservation;
+export declare function previewPerspectiveAlignmentEquals(left: PreviewPerspectiveAlignmentObservation, right: PreviewPerspectiveAlignmentObservation): boolean;
+export declare function previewPerspectivesEqual(left: PreviewPerspective, right: PreviewPerspective): boolean;

package/dist/runtime/preview-perspective-alignment.js

@@ -0,0 +1,40 @@
+export const UNKNOWN_PREVIEW_PERSPECTIVE_ALIGNMENT = Object.freeze({ kind: 'unknown' });
+export function derivePreviewPerspectiveAlignment(addressPerspective, context) {
+    if (context === null)
+        return UNKNOWN_PREVIEW_PERSPECTIVE_ALIGNMENT;
+    if (addressPerspective && previewPerspectivesEqual(addressPerspective, context.perspective)) {
+        return { kind: 'aligned', context };
+    }
+    return { kind: 'conflict', addressPerspective, context };
+}
+export function previewPerspectiveAlignmentEquals(left, right) {
+    if (left.kind !== right.kind)
+        return false;
+    if (left.kind === 'unknown' || right.kind === 'unknown')
+        return true;
+    if (!previewReadContextsEqual(left.context, right.context))
+        return false;
+    return (left.kind === 'aligned' ||
+        right.kind === 'aligned' ||
+        (left.addressPerspective === null || right.addressPerspective === null
+            ? left.addressPerspective === right.addressPerspective
+            : previewPerspectivesEqual(left.addressPerspective, right.addressPerspective)));
+}
+export function previewPerspectivesEqual(left, right) {
+    if (left.kind !== right.kind)
+        return false;
+    switch (left.kind) {
+        case 'published':
+        case 'living':
+            return true;
+        case 'variant':
+            return right.kind === 'variant' && left.variantId === right.variantId;
+        case 'release':
+            return right.kind === 'release' && left.releaseId === right.releaseId;
+    }
+}
+function previewReadContextsEqual(left, right) {
+    return (left.contextId === right.contextId &&
+        left.revision === right.revision &&
+        previewPerspectivesEqual(left.perspective, right.perspective));
+}

package/dist/runtime/preview-perspective-intent-state.d.ts

@@ -0,0 +1,23 @@
+import type { PreviewPerspective, PreviewReadContext } from '@storystick/types/preview-query-targeting';
+interface PreviewPerspectiveIntentObservationBase {
+    readonly perspective: PreviewPerspective;
+    readonly generation: number | null;
+    readonly commandId: string | null;
+}
+export type PreviewPerspectiveIntentObservation = {
+    readonly kind: 'idle';
+} | (PreviewPerspectiveIntentObservationBase & {
+    readonly kind: 'pending';
+}) | (PreviewPerspectiveIntentObservationBase & {
+    readonly kind: 'accepted';
+    readonly acceptance: 'applied' | 'local-noop';
+    readonly context: PreviewReadContext;
+}) | (PreviewPerspectiveIntentObservationBase & {
+    readonly kind: 'conflict';
+    readonly context: PreviewReadContext;
+}) | (PreviewPerspectiveIntentObservationBase & {
+    readonly kind: 'unavailable' | 'superseded';
+});
+export declare const IDLE_PREVIEW_PERSPECTIVE_INTENT: PreviewPerspectiveIntentObservation;
+export declare function previewPerspectiveIntentAppliesToGeneration(observation: PreviewPerspectiveIntentObservation, generation: number): boolean;
+export {};

package/dist/runtime/preview-perspective-intent-state.js

@@ -0,0 +1,5 @@
+export const IDLE_PREVIEW_PERSPECTIVE_INTENT = Object.freeze({ kind: 'idle' });
+export function previewPerspectiveIntentAppliesToGeneration(observation, generation) {
+    return (observation.kind !== 'idle' &&
+        (observation.generation === null || observation.generation === generation));
+}

package/dist/runtime/preview-transition-state.d.ts

@@ -0,0 +1,142 @@
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import type { PreviewPerspective } from '@storystick/types/preview-query-targeting';
+export declare const PREVIEW_TRANSITION_SLOW_MS = 1500;
+export declare const PREVIEW_TRANSITION_UNCONFIRMED_MS = 8000;
+export type PreviewTransitionReason = 'first-render' | 'document-open' | 'preview-intent' | 'resync' | 'host-loading' | 'host-loading-timeout';
+export type PreviewTransitionSourceOfTruth = 'studio' | 'iframe' | 'system';
+export type PreviewHostStatus = 'none' | 'loading' | 'valid' | 'invalid' | 'timed-out';
+export type PreviewTransitionPerspective = PreviewPerspective;
+export interface PreviewTransitionTarget {
+    sessionId: string | null;
+    editorDocumentId: string | null;
+    expectedPreviewDocumentId: string | null;
+    /** Locale selected by Studio. Required as an explicit coordinate when a
+     * draft has no public pathname from which the runtime could derive it. */
+    expectedLocale?: string | null;
+    expectedPathname: string | null;
+    /**
+     * Present when completion must prove the requested content perspective, not
+     * merely the route tuple. Route snapshots do not carry this evidence;
+     * command-correlated paint ACKs and provenance anchor maps do.
+     */
+    expectedPerspective?: PreviewTransitionPerspective;
+    expectedSearch: string;
+    expectedHash: string;
+    draftDocumentId?: string | null;
+    hostDocumentId?: string | null;
+    hostStatus: PreviewHostStatus;
+    commandId?: string | null;
+    sourceOfTruth?: PreviewTransitionSourceOfTruth;
+}
+export type NormalizedPreviewTransitionTarget = PreviewTransitionTarget & {
+    sourceOfTruth: PreviewTransitionSourceOfTruth;
+};
+export interface PreviousPreviewConfirmation {
+    /** Session whose rendered frame supplied this confirmation. */
+    sessionId: string | null;
+    /** Effective locale when known; null means the runtime confirmed no locale. */
+    locale?: string | null;
+    /** Content perspective proven by the same rendered frame when available. */
+    perspective?: PreviewPerspective;
+    documentId: string | null;
+    pathname: string | null;
+    search: string;
+    hash: string;
+}
+export type PreviewTransitionState = {
+    kind: 'idle';
+} | {
+    kind: 'pending';
+    generation: number;
+    reason: PreviewTransitionReason;
+    sourceOfTruth: PreviewTransitionSourceOfTruth;
+    target: NormalizedPreviewTransitionTarget;
+    previousConfirmed?: PreviousPreviewConfirmation;
+    startedAt: number;
+    slowAt: number;
+    deadlineAt: number;
+    slow: boolean;
+} | {
+    kind: 'unconfirmed';
+    generation: number;
+    sourceOfTruth: PreviewTransitionSourceOfTruth;
+    target: NormalizedPreviewTransitionTarget;
+    previousConfirmed?: PreviousPreviewConfirmation;
+    startedAt: number;
+    failedAt: number;
+    sourceReason: PreviewTransitionReason;
+    reason: 'soft-navigation-unconfirmed' | 'host-loading-timeout';
+};
+export type PreviewTransitionConfirmation = {
+    kind: 'presentation';
+    generation?: number;
+    pageDocId: string;
+    pathname: string;
+    locale: string;
+    context: PreviewReadContext;
+    acceptedContext: PreviewReadContext;
+} | {
+    kind: 'location';
+    generation?: number;
+    pathname: string;
+    search?: string;
+    hash?: string;
+    commandId?: string | null;
+} | {
+    kind: 'snapshot';
+    generation?: number;
+    pageDocId: string | null;
+    routeUrl?: string | null;
+    routeHash?: string | null;
+    codeVersion?: string | null;
+} | {
+    kind: 'route-rendered';
+    generation?: number;
+    commandId: string;
+    codeVersion?: string | null;
+};
+export interface PreviewTransitionAnchorMapCandidate {
+    generation: number;
+    sessionId: string;
+    sourceOfTruth: PreviewTransitionSourceOfTruth;
+    commandId?: string | null;
+    pathname: string;
+    routeHash: string;
+    perspective?: PreviewTransitionPerspective;
+    codeVersion: string;
+}
+export declare function previewTransitionPerspective(input: {
+    published?: boolean;
+    variantId: string | null | undefined;
+    releaseId: string | null | undefined;
+}): PreviewTransitionPerspective;
+export interface BeginPreviewTransitionInput {
+    generation: number;
+    reason: PreviewTransitionReason;
+    target: PreviewTransitionTarget;
+    previousConfirmed?: PreviousPreviewConfirmation;
+    now: number;
+    slowMs?: number;
+    unconfirmedMs?: number;
+}
+export declare function beginPreviewTransition({ generation, reason, target, previousConfirmed, now, slowMs, unconfirmedMs, }: BeginPreviewTransitionInput): PreviewTransitionState;
+export declare function advancePreviewTransitionClock(state: PreviewTransitionState, now: number): PreviewTransitionState;
+export declare function confirmPreviewTransition(state: PreviewTransitionState, confirmation: PreviewTransitionConfirmation): PreviewTransitionState;
+export declare function matchesTransitionTarget(target: PreviewTransitionTarget, confirmation: PreviewTransitionConfirmation): boolean;
+export declare function matchesTransitionRouteUrl(target: PreviewTransitionTarget, routeUrl: string | null | undefined): boolean;
+export declare function matchesAnchorMapCandidateTarget(target: PreviewTransitionTarget, candidate: PreviewTransitionAnchorMapCandidate): boolean;
+export declare function parsePreviewTransitionRoute(routeUrl: string | null | undefined): {
+    pathname: string;
+    search: string;
+    hash: string;
+} | null;
+export declare function targetKey(target: PreviewTransitionTarget): string;
+export declare function previewTransitionPerspectivesEqual(expected: PreviewTransitionPerspective, actual: PreviewTransitionPerspective | undefined): boolean;
+export declare function confirmationFromLocation(input: {
+    generation?: number;
+    pathname: string;
+    search?: string;
+    hash?: string;
+    commandId?: string | null;
+}): PreviewTransitionConfirmation;
+export declare function normalizeTransitionTarget(target: PreviewTransitionTarget): NormalizedPreviewTransitionTarget;

package/dist/runtime/preview-transition-state.js

@@ -0,0 +1,257 @@
+import { normalizePathname } from '@storystick/client/normalize-pathname';
+export const PREVIEW_TRANSITION_SLOW_MS = 1_500;
+export const PREVIEW_TRANSITION_UNCONFIRMED_MS = 8_000;
+export function previewTransitionPerspective(input) {
+    if (input.published)
+        return { kind: 'published' };
+    if (input.releaseId) {
+        return { kind: 'release', releaseId: input.releaseId };
+    }
+    if (input.variantId) {
+        return { kind: 'variant', variantId: input.variantId };
+    }
+    return { kind: 'living' };
+}
+export function beginPreviewTransition({ generation, reason, target, previousConfirmed, now, slowMs = PREVIEW_TRANSITION_SLOW_MS, unconfirmedMs = PREVIEW_TRANSITION_UNCONFIRMED_MS, }) {
+    const normalizedTarget = normalizeTransitionTarget(target);
+    return {
+        kind: 'pending',
+        generation,
+        reason,
+        sourceOfTruth: normalizedTarget.sourceOfTruth,
+        target: normalizedTarget,
+        previousConfirmed,
+        startedAt: now,
+        slowAt: now + slowMs,
+        deadlineAt: now + unconfirmedMs,
+        slow: false,
+    };
+}
+export function advancePreviewTransitionClock(state, now) {
+    if (state.kind !== 'pending')
+        return state;
+    if (now >= state.deadlineAt) {
+        return {
+            kind: 'unconfirmed',
+            generation: state.generation,
+            sourceOfTruth: state.sourceOfTruth,
+            target: state.target,
+            previousConfirmed: state.previousConfirmed,
+            startedAt: state.startedAt,
+            failedAt: now,
+            sourceReason: state.reason,
+            reason: state.reason === 'host-loading' ||
+                state.reason === 'host-loading-timeout'
+                ? 'host-loading-timeout'
+                : 'soft-navigation-unconfirmed',
+        };
+    }
+    if (!state.slow && now >= state.slowAt) {
+        return { ...state, slow: true };
+    }
+    return state;
+}
+export function confirmPreviewTransition(state, confirmation) {
+    if (state.kind === 'idle')
+        return state;
+    if (confirmation.generation !== undefined &&
+        confirmation.generation !== state.generation) {
+        return state;
+    }
+    // PR-1 — a post-paint route-rendered ack confirms the transition iff
+    // it echoes the commandId this transition is waiting on. This is the
+    // preferred (earliest, render-accurate) confirmation; the snapshot
+    // path below remains the fallback floor for transitions with no
+    // commandId and for SDKs/frameworks that never emit route-rendered.
+    if (confirmation.kind === 'route-rendered') {
+        if (state.target.commandId != null &&
+            confirmation.commandId === state.target.commandId) {
+            return { kind: 'idle' };
+        }
+        return state;
+    }
+    // A location envelope only proves that the iframe router reached the
+    // target URL. It can arrive before the target page is visibly rendered,
+    // so it must not confirm the transition — only a render snapshot or a
+    // route-rendered paint ack may.
+    if (confirmation.kind !== 'snapshot' && confirmation.kind !== 'presentation')
+        return state;
+    if (!matchesTransitionTarget(state.target, confirmation))
+        return state;
+    return { kind: 'idle' };
+}
+export function matchesTransitionTarget(target, confirmation) {
+    if (confirmation.kind === 'presentation') {
+        return confirmation.pageDocId === target.expectedPreviewDocumentId &&
+            confirmation.locale === target.expectedLocale &&
+            target.expectedPathname !== null && normalizePathname(confirmation.pathname) === normalizePathname(target.expectedPathname) &&
+            confirmation.context.contextId === confirmation.acceptedContext.contextId &&
+            confirmation.context.revision === confirmation.acceptedContext.revision &&
+            target.expectedPerspective !== undefined && previewTransitionPerspectivesEqual(target.expectedPerspective, confirmation.context.perspective);
+    }
+    if (confirmation.kind === 'location') {
+        if (target.expectedPathname === null)
+            return false;
+        const expectedPathname = normalizePathname(target.expectedPathname);
+        const actualPathname = normalizePathname(confirmation.pathname);
+        return (actualPathname === expectedPathname &&
+            normalizeTransitionSearch(confirmation.search ?? '') ===
+                normalizeTransitionSearch(target.expectedSearch) &&
+            (confirmation.hash ?? '') === target.expectedHash);
+    }
+    // route-rendered acks are correlated by commandId in
+    // `confirmPreviewTransition`, never by content identity here.
+    if (confirmation.kind !== 'snapshot')
+        return false;
+    if (target.expectedPreviewDocumentId === null)
+        return false;
+    if (confirmation.pageDocId !== target.expectedPreviewDocumentId)
+        return false;
+    if (target.expectedPathname !== null) {
+        const route = parsePreviewTransitionRoute(confirmation.routeUrl);
+        if (route === null)
+            return false;
+        if (normalizePathname(route.pathname) !==
+            normalizePathname(target.expectedPathname)) {
+            return false;
+        }
+        if (normalizeTransitionSearch(route.search) !==
+            normalizeTransitionSearch(target.expectedSearch)) {
+            return false;
+        }
+        if (route.hash !== target.expectedHash)
+            return false;
+    }
+    // A route snapshot can prove document + URL, but not which living, variant,
+    // or release content produced that render. Scope-aware transitions stay
+    // pending for a command-correlated paint ACK or provenance evidence.
+    if (target.expectedPerspective !== undefined)
+        return false;
+    return true;
+}
+export function matchesTransitionRouteUrl(target, routeUrl) {
+    const route = parsePreviewTransitionRoute(routeUrl);
+    if (route === null)
+        return false;
+    return matchesTransitionTarget(target, {
+        kind: 'location',
+        pathname: route.pathname,
+        search: route.search,
+        hash: route.hash,
+    });
+}
+export function matchesAnchorMapCandidateTarget(target, candidate) {
+    const normalizedTarget = normalizeTransitionTarget(target);
+    if (candidate.sessionId !== (normalizedTarget.sessionId ?? ''))
+        return false;
+    if (candidate.sourceOfTruth !== normalizedTarget.sourceOfTruth)
+        return false;
+    if (normalizedTarget.commandId !== null &&
+        normalizedTarget.commandId !== undefined &&
+        candidate.commandId !== null &&
+        candidate.commandId !== undefined &&
+        candidate.commandId !== normalizedTarget.commandId) {
+        return false;
+    }
+    if (normalizedTarget.expectedPathname === null)
+        return false;
+    if (normalizedTarget.expectedSearch !== '')
+        return false;
+    if (normalizedTarget.expectedHash !== '')
+        return false;
+    if (candidate.routeHash.length === 0)
+        return false;
+    if (candidate.codeVersion.length === 0)
+        return false;
+    if (normalizedTarget.expectedPerspective !== undefined &&
+        !previewTransitionPerspectivesEqual(normalizedTarget.expectedPerspective, candidate.perspective)) {
+        return false;
+    }
+    return (normalizePathname(candidate.pathname) ===
+        normalizePathname(normalizedTarget.expectedPathname));
+}
+export function parsePreviewTransitionRoute(routeUrl) {
+    if (typeof routeUrl !== 'string' || routeUrl.length === 0)
+        return null;
+    try {
+        const parsed = new URL(routeUrl, 'http://storystick.local');
+        return {
+            pathname: parsed.pathname,
+            search: normalizeTransitionSearch(parsed.search),
+            hash: parsed.hash,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeTransitionSearch(search) {
+    const raw = search.startsWith('?') ? search.slice(1) : search;
+    if (raw === '')
+        return '';
+    const params = new URLSearchParams(raw);
+    for (const key of [...params.keys()]) {
+        if (key.startsWith('_ss_'))
+            params.delete(key);
+    }
+    return params.toString();
+}
+export function targetKey(target) {
+    const t = normalizeTransitionTarget(target);
+    return [
+        t.sessionId ?? '',
+        t.editorDocumentId ?? '',
+        t.expectedPreviewDocumentId ?? '',
+        t.expectedLocale ?? '',
+        t.expectedPathname ?? '',
+        t.expectedPerspective === undefined
+            ? '<unscoped>'
+            : previewTransitionPerspectiveKey(t.expectedPerspective),
+        t.expectedSearch,
+        t.expectedHash,
+        t.draftDocumentId ?? '',
+        t.hostDocumentId ?? '',
+        t.hostStatus,
+        t.sourceOfTruth,
+    ].join('\x00');
+}
+export function previewTransitionPerspectivesEqual(expected, actual) {
+    if (actual === undefined || actual.kind !== expected.kind)
+        return false;
+    if (expected.kind === 'variant') {
+        return actual.kind === 'variant' && actual.variantId === expected.variantId;
+    }
+    if (expected.kind === 'release') {
+        return actual.kind === 'release' && actual.releaseId === expected.releaseId;
+    }
+    return true;
+}
+function previewTransitionPerspectiveKey(perspective) {
+    if (perspective.kind === 'variant')
+        return `variant:${perspective.variantId}`;
+    if (perspective.kind === 'release')
+        return `release:${perspective.releaseId}`;
+    return perspective.kind;
+}
+export function confirmationFromLocation(input) {
+    return {
+        kind: 'location',
+        generation: input.generation,
+        pathname: input.pathname,
+        search: input.search ?? '',
+        hash: input.hash ?? '',
+        commandId: input.commandId ?? null,
+    };
+}
+export function normalizeTransitionTarget(target) {
+    return {
+        ...target,
+        expectedPathname: target.expectedPathname === null
+            ? null
+            : normalizePathname(target.expectedPathname),
+        expectedSearch: target.expectedSearch ?? '',
+        expectedHash: target.expectedHash ?? '',
+        commandId: target.commandId ?? null,
+        sourceOfTruth: target.sourceOfTruth ?? 'studio',
+    };
+}

package/dist/runtime/render-mode-state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Module-level mutable state for the current render mode inside the
+ * developer's iframe. Read by framework SDKs to decide whether to
+ * debounce Convex subscriptions (Navigation mode = 100ms debounce
+ * per ADR-059 §Technical commitments + spec/preview-system.md
+ * §"Convex subscription debounced 100ms in Navigation mode").
+ *
+ * The snapshot reporter writes here when a `render-mode` postMessage
+ * arrives. Framework SDKs read here in their query hook. Subscribers
+ * can register a callback to be notified on changes — useful for
+ * triggering re-renders without polling.
+ *
+ * This intentionally lives at module scope (not React Context) for
+ * three reasons:
+ *
+ *   1. The state is iframe-global (one site rendered in one iframe).
+ *      Two providers in the same iframe with different render modes
+ *      would be a bug, not a feature.
+ *
+ *   2. The state is set by the postMessage runtime (vanilla JS,
+ *      no React tree). A Context API requires a Provider mounted
+ *      above every consumer; module state is observed regardless.
+ *
+ *   3. Tests can reset it deterministically via `_resetForTests()`.
+ *      Cross-test pollution is the only real risk and it's explicit.
+ */
+import type { RenderMode } from '../types.js';
+export declare function getRenderMode(): RenderMode;
+export declare function setRenderMode(mode: RenderMode): void;
+/**
+ * Subscribe to render-mode changes. Returns an unsubscribe function.
+ * Subscribers are called synchronously after `setRenderMode`. They
+ * MUST not call `setRenderMode` from within their handler — that
+ * would re-enter the dispatch.
+ */
+export declare function subscribeRenderMode(callback: (mode: RenderMode) => void): () => void;
+/**
+ * Returns the debounce window (ms) appropriate for the current
+ * render mode. Navigation mode = 100ms; Device mode = 0 (no debounce).
+ *
+ * Per ADR-059 §Technical commitments: "the editor reads structure
+ * (section order, slice type, slice count), not typography. Typo-
+ * graphic updates do not need to propagate to the Navigation
+ * miniature within one frame."
+ */
+export declare function debounceForRenderMode(mode?: RenderMode): number;
+/**
+ * Test-only reset. Not exported from index.ts to keep the public
+ * API small.
+ */
+export declare function _resetForTests(): void;