@pygmalionjs/pygmalion 0.6.27 → 0.6.28

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-ziDz92ma.js";
+import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-Xm7o3urC.js";
 export {
   s as FrozenRoutePreviewView,
   a as NodeModel,

package/dist-lib/types/canvas/useFlowSession.d.ts

@@ -29,6 +29,7 @@ export declare function useInteractiveSessionPending(page: {
     interactiveStateId?: string;
     interactiveOptionId?: string;
     interactiveOptionIds?: readonly string[];
+    interactiveStateUsesDesiredState?: boolean;
 }, targetCacheKey?: string): boolean;
 /** The runner-owned live document currently reproducing this state. */
 export declare function useInteractiveSessionSurface(page: {
@@ -36,7 +37,8 @@ export declare function useInteractiveSessionSurface(page: {
     interactiveStateId?: string;
     interactiveOptionId?: string;
     interactiveOptionIds?: readonly string[];
-}): InteractiveSessionSurface | null;
+    interactiveStateUsesDesiredState?: boolean;
+}, preparedSurfaceId?: string | null): InteractiveSessionSurface | null;
 /**
  * True while this frame holds one of the host's live screen slots, meaning it
  * renders the running app rather than its frozen capture.

package/dist-lib/types/editor/designImport.d.ts

@@ -64,11 +64,27 @@ export interface DesignScreenInteraction {
 export interface DesignScreenInteractionRunOptions {
     /**
      * Fallback pause after click, focus, hover, fill, check, and press steps.
-     * The capture default is 600ms. A step's explicit `settleMs` always wins.
+     * The capture default is 600ms. A step's explicit `settleMs` wins unless
+     * target-driven replay can synchronize on the following observed wait.
      */
     defaultActionSettleMs?: number;
+    /**
+     * Uses observable wait steps as the synchronization point for the action
+     * immediately before them. This removes the action's fixed settle and the
+     * matched wait's implicit 500ms pause; an explicit settle on the wait and a
+     * timer-only wait remain authoritative. Capture replay keeps the default
+     * `authored` policy, while an already-visible interactive transition can use
+     * `target-driven` and let the final stability pass protect serialization.
+     */
+    settlePolicy?: 'authored' | 'target-driven';
     /** Called after boot presets succeed and immediately before actions begin. */
     onBeforeInteractions?: () => void;
+    /**
+     * Called as soon as every interaction succeeds, before capture assertions.
+     * Presentation can therefore hand over the live document while validation
+     * and snapshot persistence continue in the background.
+     */
+    onAfterInteractions?: () => void | Promise<void>;
 }
 /** A JSON-compatible value that conveys host-specific meaning without Pygmalion interpreting it. */
 export type DesignSerializable = string | number | boolean | null | readonly DesignSerializable[] | {
@@ -80,6 +96,15 @@ export type DesignSerializable = string | number | boolean | null | readonly Des
  * The meaning of keys and values ​​is entirely owned by the host adapter.
  */
 export type DesignScreenPreset = Readonly<Record<string, DesignSerializable>>;
+/**
+ * Complete host-owned UI state for a rendered preview document.
+ *
+ * Unlike an interaction recipe, this is applied after the application mounts
+ * and asks React to render the requested state directly. Every application is
+ * a full replacement — including an empty object — so a reused preview cannot
+ * retain an override from the frame that occupied it previously.
+ */
+export type DesignScreenDesiredState = Readonly<Record<string, DesignSerializable>>;
 export type StoryboardPermissionState = 'granted' | 'denied' | 'prompt';
 export type StoryboardMediaFailure = 'not-allowed' | 'not-found' | 'not-readable' | 'overconstrained';
 export interface StoryboardMediaDevice {
@@ -231,6 +256,8 @@ export interface DesignImportPage {
      */
     scenarioIds?: readonly string[];
     interactions?: readonly DesignScreenInteraction[];
+    /** Host-owned post-mount UI state rendered directly instead of replaying gestures. */
+    desiredState?: DesignScreenDesiredState;
     environment?: StoryboardEnvironment;
     preset?: DesignScreenPreset;
     assertions?: readonly DesignScreenAssertion[];
@@ -352,6 +379,8 @@ export interface DesignImportInitialPage {
     /** Every authored scenario this initial screen demonstrates. */
     scenarioIds?: readonly string[];
     interactions?: DesignScreenInteraction[];
+    /** Host-owned post-mount UI state rendered directly instead of replaying gestures. */
+    desiredState?: DesignScreenDesiredState;
     environment?: StoryboardEnvironment;
     preset?: DesignScreenPreset;
     assertions?: DesignScreenAssertion[];
@@ -375,8 +404,8 @@ export interface DesignScreenInteractionReport {
     failedLabel?: string;
     error?: string;
 }
-export type DesignScreenCaptureFailureStage = 'preset' | 'interaction' | 'assertion';
-export type DesignScreenCaptureFailureCode = 'preset_executor_missing' | 'preset_rejected' | 'preset_error' | 'interaction_failed' | 'invalid_selector' | 'existence_mismatch' | 'text_mismatch' | 'attribute_mismatch' | 'visibility_mismatch';
+export type DesignScreenCaptureFailureStage = 'preset' | 'state' | 'interaction' | 'assertion';
+export type DesignScreenCaptureFailureCode = 'preset_executor_missing' | 'preset_rejected' | 'preset_error' | 'state_executor_missing' | 'state_rejected' | 'state_error' | 'interaction_failed' | 'invalid_selector' | 'existence_mismatch' | 'text_mismatch' | 'attribute_mismatch' | 'visibility_mismatch';
 export interface DesignScreenCaptureFailure {
     stage: DesignScreenCaptureFailureStage;
     code: DesignScreenCaptureFailureCode;
@@ -434,10 +463,18 @@ export interface DesignScreenPresetExecutionResult {
     details?: DesignSerializable;
 }
 export type DesignScreenPresetExecutor = (request: DesignScreenPresetRequest, context: DesignScreenPresetContext) => Promise<DesignScreenPresetExecutionResult | void> | DesignScreenPresetExecutionResult | void;
+/** Serializable desired-state transport. The host alone owns the key semantics. */
+export interface DesignScreenDesiredStateRequest {
+    pageId: string;
+    route?: string;
+    state: DesignScreenDesiredState;
+}
+export type DesignScreenDesiredStateExecutor = (request: DesignScreenDesiredStateRequest, context: DesignScreenPresetContext) => Promise<DesignScreenPresetExecutionResult | void> | DesignScreenPresetExecutionResult | void;
 export interface DesignScreenCaptureSpec {
     pageId: string;
     route?: string;
     preset?: DesignScreenPreset;
+    desiredState?: DesignScreenDesiredState;
     interactions?: readonly DesignScreenInteraction[];
     assertions?: readonly DesignScreenAssertion[];
 }
@@ -495,6 +532,8 @@ export interface CreateDesignImportOptions {
     layerOptions?: DomImportOptions;
     /** The only boundary that enforces the host-specific semantics of the preset. The package does not interpret the payload. */
     executeScreenPreset?: DesignScreenPresetExecutor;
+    /** Applies complete host-owned UI state after mount and before gesture replay. */
+    executeDesiredState?: DesignScreenDesiredStateExecutor;
     /**
      * How screen pages spread across canvases. `single` (default) keeps every
      * screen on one canvas. `section` gives each section its own canvas

package/dist-lib/types/editor/flowSessionScheduler.d.ts

@@ -1,5 +1,5 @@
 import { type DesignImportController, type DesignScreenCaptureSpec } from './designImport';
-import type { ResolvedFlowPath } from './flowSessions';
+import type { FlowSessionRunner, ResolvedFlowPath } from './flowSessions';
 import type { ScreenFlowPath } from './screenFlows';
 import { type PageModel } from './store';
 /** Applies the active frame's own boot condition to a path-specific session. */
@@ -70,18 +70,31 @@ export declare function subscribeViewportSessions(listener: () => void): () => v
 type InteractivePreparationController = Pick<DesignImportController, 'prepareScreenCapture' | 'prepareScreenState'>;
 /**
  * Reproduces an editor-controlled state without capture-only quiescence.
- * The runner still waits for a trailing paint and stable geometry before it
- * serializes, but presentation begins only after the state recipe has
- * finished. Showing a runner before its clicks and fills finish makes the
- * reviewer watch the script operate the product instead of reviewing a state.
+ * Direct desired state is presented as soon as the host commits React; replay
+ * states remain hidden until their gestures finish. Frozen persistence may
+ * continue afterward without delaying either live presentation path.
  */
 export declare function prepareInteractiveSessionState(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec, controller?: InteractivePreparationController | null, onStateReady?: () => void): Promise<import("./designImport").DesignScreenCaptureReport>;
+/**
+ * Test seam: replaces the interactive runner with one whose boot/prepare/
+ * publish are injected fakes, so the variant-and-repark queueing can run
+ * headless. Passing null restores the default runner on next use.
+ */
+export declare function __setInteractiveSessionRunnerForTests(runner: FlowSessionRunner | null): void;
 export declare function interactiveSessionScreenId(page: {
     id: string;
     interactiveStateId?: string;
     interactiveOptionId?: string;
     interactiveOptionIds?: readonly string[];
 }): string;
+/** Direct sibling options render through one persistent React document. */
+export declare function interactiveSessionSurfaceId(page: {
+    id: string;
+    interactiveStateId?: string;
+    interactiveOptionId?: string;
+    interactiveOptionIds?: readonly string[];
+    interactiveStateUsesDesiredState?: boolean;
+}): string;
 /**
  * Materializes one screen in its declared interactive state through the
  * screen's flow path. The prefix walks as pass-through; the target publishes
@@ -97,15 +110,51 @@ export declare function interactiveSessionWillDeliver(page: {
     interactiveStateId?: string;
     interactiveOptionId?: string;
     interactiveOptionIds?: readonly string[];
+    interactiveStateUsesDesiredState?: boolean;
 }, targetCacheKey?: string): boolean;
 /** Subscribe to interactive-state delivery changes. */
 export declare function subscribeInteractiveSessions(listener: () => void): () => void;
+/** How one speculative enqueue attempt ended. */
+export type InteractiveVariantPrefetchOutcome = 'queued' | 'busy' | 'tracked' | 'unavailable';
+/** True when the interactive runner has nothing queued or walking. */
+export declare function interactiveSessionRunnerIsIdle(): boolean;
+/**
+ * True when the interactive runner already tracks this variant's delivery in
+ * any status. Unlike interactiveSessionWillDeliver, an untracked variant
+ * reads as false here: the prefetch policy asks "is anyone already on it",
+ * not "should the frame wait".
+ */
+export declare function interactiveSessionTracksVariant(variantPage: {
+    importPageId?: string;
+    id: string;
+    interactiveStateId?: string;
+    interactiveOptionId?: string;
+}): boolean;
+/**
+ * Queues one speculative walk for a hypothetical variant identity — a shallow
+ * page clone carrying the interactions/environment/state fields the store's
+ * applyInteractiveState would produce for the option (variantPrefetch.ts
+ * derives it). Sibling of materializePageInteractiveState, kept separate so
+ * speculation never changes the real request path.
+ *
+ * The user must never wait behind speculation: the runner is concurrency-1
+ * FIFO, so this enqueues only into an EMPTY runner ('busy' otherwise). At
+ * most one speculative walk is therefore ever queued or running, and a real
+ * selection made meanwhile queues behind that single walk at worst.
+ */
+export declare function prefetchPageInteractiveVariant(variantPage: PageModel, previewRevision: string): InteractiveVariantPrefetchOutcome;
 /** Diagnostic counters for the interactive-state path. */
 export declare const __interactiveSessionDebug: {
     requested: number;
     noPath: number;
     resolvedNull: number;
     queued: number;
+    /** Base-prefix re-park warming walks queued behind variant deliveries. */
+    reparkQueued: number;
+    /** Re-parks skipped because a parked base instance already serves the prefix. */
+    reparkAlreadyParked: number;
+    /** Re-parks skipped because the option adds no steps over the base screen. */
+    reparkNoExtraSteps: number;
 };
 /** Interactive-runner delivery states for the headless debug surface. */
 export declare function __debugInteractiveSessionStates(): Record<string, unknown>;

package/dist-lib/types/editor/flowSessions.d.ts

@@ -1,4 +1,4 @@
-import type { DesignScreenAssertion, DesignScreenCaptureReport, DesignScreenInteraction, DesignScreenPreset } from './designImport';
+import type { DesignScreenAssertion, DesignScreenCaptureReport, DesignScreenDesiredState, DesignScreenInteraction, DesignScreenPreset } from './designImport';
 export interface ResolvedFlowWaypoint {
     screenId: string;
     /**
@@ -12,6 +12,19 @@ export interface ResolvedFlowWaypoint {
     width: number;
     height: number;
     steps: readonly DesignScreenInteraction[];
+    /** Complete host-owned UI state applied before this waypoint's steps. */
+    desiredState?: DesignScreenDesiredState;
+    /**
+     * This waypoint is a synchronous host render over an already reproduced
+     * screen. Interactive supply may publish it after paint without repeating
+     * capture-only assertions and geometry waits. Authoritative capture still
+     * performs the full contract.
+     */
+    fastDesiredState?: boolean;
+    /** Stable live-presentation slot; sibling direct states share one document. */
+    interactiveSurfaceId?: string;
+    /** Activation warm-up may prepare a surface before an option is selected. */
+    prewarmSurfacePageId?: string;
     /** The waypoint's own capture assertions, checked after its steps settle. */
     assertions?: readonly DesignScreenAssertion[];
     /**
@@ -77,14 +90,16 @@ export interface FlowSessionRunnerOptions {
     /** Navigates the instance and resolves when the document loaded. */
     boot?: (iframe: HTMLIFrameElement, url: string) => Promise<void>;
     /**
-     * Prepares one waypoint on the instance: preset (host executor) ->
-     * interactions -> assertions, exactly the capture pipeline's contract.
+     * Prepares one waypoint on the instance: preset (host executor) -> desired
+     * state (host executor) -> interactions -> assertions, exactly the capture
+     * pipeline's contract.
      * Defaults to the design-import controller's prepareScreenCapture.
      */
     prepare?: (iframe: HTMLIFrameElement, spec: {
         pageId: string;
         route?: string;
         preset?: DesignScreenPreset;
+        desiredState?: DesignScreenDesiredState;
         interactions?: readonly DesignScreenInteraction[];
         assertions?: readonly DesignScreenAssertion[];
     }, waypoint: ResolvedFlowWaypoint) => Promise<DesignScreenCaptureReport>;
@@ -97,15 +112,21 @@ export interface FlowSessionRunnerOptions {
     publish?: (cacheKey: string, snapshot: string) => boolean;
     /** Releases a live document after its delivery finishes or is abandoned. */
     onWaypointFinish?: (iframe: HTMLIFrameElement, waypoint: ResolvedFlowWaypoint, outcome: 'completed' | 'failed' | 'cancelled') => void;
+    /** Keeps a parked document alive while another surface is presenting it. */
+    keepWarmInstanceAlive?: (iframe: HTMLIFrameElement) => boolean;
     onError?: (pathId: string, error: unknown) => void;
 }
 /**
  * Resolves when the document's layout stops moving: two consecutive
- * animation frames with an identical element-geometry hash. JS-driven
- * entrance animations (rAF springs writing inline transforms) are invisible
- * to the frozen stylesheet's animation:none — serializing mid-flight pins
+ * animation frames whose element geometry matches. JS-driven entrance
+ * animations (rAF springs writing inline transforms) are invisible to the
+ * frozen stylesheet's animation:none — serializing mid-flight pins
  * intermediate rects as overlapping boxes, so the walk waits them out.
- * Perpetual animations hit the timeout and serialize best-effort.
+ * Movement owned by effectively-infinite animations (spinners, pulses,
+ * loops) is exempt from the convergence check instead of blocking it, so
+ * screens with perpetual motion settle as fast as still ones; the timeout
+ * stays as the backstop for documents that never converge either way.
+ * The policy lives in ./geometryStability, where it is tested as pure data.
  */
 export declare function waitForGeometryStability(iframe: HTMLIFrameElement, timeoutMs?: number): Promise<void>;
 export declare function createFlowSessionIframe(): HTMLIFrameElement;
@@ -117,23 +138,35 @@ export declare const __flowSessionWarmDebug: {
     reuses: number;
     parks: number;
     evictions: number;
+    /** Warming walks answered by renewing an already-parked instance's lease. */
+    refreshes: number;
     /** Which supply booted, so a stray second boot is attributable. */
     bootsByRunner: Record<string, number>;
 };
-/** Drops every parked instance — identity change, canvas change, teardown. */
-export declare function evictFlowSessionWarmInstances(): void;
+/** Drops parked instances globally, or only those owned by one runner. */
+export declare function evictFlowSessionWarmInstances(ownerLabel?: string): void;
 /**
  * True when a walk of this path would resume on a parked instance. Activation
  * warming reads it to decide whether the frame already has a resumable
  * instance or one has to be walked in the background.
  */
 export declare function warmInstanceServesPath(path: ResolvedFlowPath): boolean;
+/** Returns an idle document already parked at this path's exact endpoint. */
+export declare function warmInstanceAtPathEnd(path: ResolvedFlowPath): HTMLIFrameElement | null;
 export declare function createFlowSessionRunner(options?: FlowSessionRunnerOptions): {
     /**
      * Queues paths for materialization. Screens already delivered, failed, or
      * claimed by a queued path are skipped — callers re-request freely.
      */
     materialize(paths: readonly ResolvedFlowPath[]): number;
+    /**
+     * Applies a path's terminal state on a known live document. The caller
+     * guarantees that this iframe already reached the path's route and base
+     * prefix; all gesture steps are therefore skipped and only the target's
+     * complete desired-state map is prepared. FIFO ordering keeps a document
+     * exposed by the current walk from being mutated until that walk finishes.
+     */
+    materializeOnInstance(path: ResolvedFlowPath, iframe: HTMLIFrameElement): number;
     /**
      * Drops queued paths the predicate rejects, releasing their pending
      * screens so a later materialize can queue them again. Running walks are
@@ -153,6 +186,13 @@ export declare function createFlowSessionRunner(options?: FlowSessionRunnerOptio
     forgetScreen(screenId: string): boolean;
     /** True while the session still owes this screen its snapshot. */
     willDeliver(screenId: string): boolean;
+    /**
+     * True when nothing is queued or walking. Speculative callers read this
+     * before enqueueing: the runner is FIFO, so speculative work queued ahead
+     * of a designer's real request would delay it — speculation may only
+     * enter an empty runner.
+     */
+    isIdle(): boolean;
     subscribe(listener: () => void): () => void;
     /**
      * Drops all session state. Running paths notice the round change at their

package/dist-lib/types/editor/geometryStability.d.ts

@@ -0,0 +1,122 @@
+/** Final backstop: a document that never settles is serialized best-effort. */
+export declare const GEOMETRY_STABILITY_TIMEOUT_MS = 3000;
+/**
+ * Secondary cap once perpetual motion is being ignored: when every rect that
+ * still moves belongs to an ignored element but structural churn (element
+ * count, sampled identity) keeps the strict check from passing, the document
+ * will not settle by waiting longer.
+ */
+export declare const PERPETUAL_RESIDUE_TIMEOUT_MS = 1000;
+/**
+ * An element that moved on every consecutive sample pair for this long is
+ * treated as perpetually driven even when no animation claims it. One-shot
+ * springs settle well inside this window, so they are never reclassified —
+ * and a mover that pauses for even one pair either settles the wait outright
+ * or is disqualified from reclassification for good.
+ */
+export declare const PERSISTENT_MOVER_MS = 1500;
+/**
+ * Floor on observed pairs before the persistent-mover rule may fire, so a
+ * slow sampling cadence cannot classify from a handful of observations.
+ */
+export declare const PERSISTENT_MOVER_MIN_PAIRS = 10;
+/** How many elements a geometry sample inspects, from the top of the body. */
+export declare const GEOMETRY_SAMPLE_LIMIT = 160;
+/** One sampled element: an opaque identity plus its rounded geometry. */
+export interface GeometryElementSample {
+    /** Stable identity across samples — in the DOM, the element itself. */
+    key: unknown;
+    /** Rounded rect signature, e.g. "12,40,300,24". */
+    rect: string;
+    /**
+     * True when an effectively-infinite animation drives this element or an
+     * ancestor, so its movement must not block convergence.
+     */
+    perpetual: boolean;
+}
+/** A point-in-time view of the document's geometry. */
+export interface GeometrySample {
+    /** Total rendered element count — a structure signal beyond the sampled window. */
+    elementCount: number;
+    elements: readonly GeometryElementSample[];
+    /** Sample timestamp from the caller's clock, in milliseconds. */
+    at: number;
+}
+export type GeometrySettleReason = 
+/** Everything held still for one full sample pair — the strict criterion. */
+'stable'
+/** Everything held still except elements owned by perpetual motion. */
+ | 'stable-ignoring-perpetual'
+/** Ignored motion plus structural churn: settled at the lower cap. */
+ | 'perpetual-residue'
+/** The final backstop: serialized best-effort. */
+ | 'timeout';
+export interface GeometryVerdict {
+    settled: boolean;
+    reason?: GeometrySettleReason;
+}
+export interface GeometryStabilityJudgeOptions {
+    timeoutMs?: number;
+    perpetualResidueTimeoutMs?: number;
+    persistentMoverMs?: number;
+    persistentMoverMinPairs?: number;
+}
+export interface GeometryStabilityJudge {
+    /** Consumes the next sample and reports whether the wait may end. */
+    next(sample: GeometrySample): GeometryVerdict;
+}
+/**
+ * Creates the convergence policy for one stability wait. The strict
+ * criterion is unchanged from the original hash comparison: one sample pair
+ * with identical element count, identical sampled identities in order, and
+ * identical rects. Movement owned by perpetual animations is exempt from
+ * the rect comparison; structure changes never are (they fall through to
+ * the residue cap or the timeout).
+ */
+export declare function createGeometryStabilityJudge(options?: GeometryStabilityJudgeOptions): GeometryStabilityJudge;
+export interface AnimationEffectLike {
+    target?: unknown;
+    getTiming?: () => {
+        iterations?: number;
+    };
+    getComputedTiming?: () => {
+        endTime?: unknown;
+    };
+}
+export interface AnimationLike {
+    effect?: AnimationEffectLike | null;
+}
+interface RectLike {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface GeometryElementLike {
+    nodeType: number;
+    getBoundingClientRect(): RectLike;
+    contains?(other: GeometryElementLike): boolean;
+}
+export interface GeometryDocumentLike {
+    body?: {
+        querySelectorAll(selectors: string): ArrayLike<GeometryElementLike>;
+    } | null;
+    getAnimations?(options?: {
+        subtree?: boolean;
+    }): AnimationLike[];
+}
+/** True for an animation that will never finish on its own. */
+export declare function isEffectivelyPerpetualAnimation(animation: AnimationLike): boolean;
+/**
+ * Elements owned by animations that will never finish on their own. CSS
+ * animations with an infinite iteration count and Web Animations API loops
+ * both surface here; one-shot animations never do.
+ */
+export declare function collectPerpetualMotionRoots(doc: GeometryDocumentLike): GeometryElementLike[];
+/**
+ * Reads one geometry sample from a document: rounded rects of the first
+ * `limit` elements, each flagged when a perpetual animation drives it or an
+ * ancestor (a transform loop on a container moves every descendant rect).
+ */
+export declare function sampleGeometry(doc: GeometryDocumentLike, at: number, limit?: number): GeometrySample;
+export {};

package/dist-lib/types/editor/heldPseudoStates.d.ts

@@ -2,6 +2,28 @@ import type { DesignScreenInteraction } from './designImport';
 export type HeldPseudoState = 'hover' | 'focus' | 'focus-visible' | 'active';
 /** The pseudo gestures still held after the complete recipe has run. */
 export declare function heldPseudoInteractionsFromRecipe(interactions: readonly DesignScreenInteraction[]): DesignScreenInteraction[];
+/** True when the interaction is a gesture the frozen preview can hold via CSS. */
+export declare function isHeldPseudoInteraction(interaction: DesignScreenInteraction): boolean;
+/**
+ * Why these steps cannot be held on the given frozen document, or an empty
+ * list when client-side holding reproduces them faithfully.
+ *
+ * A target stamped with script-driven pseudo events (PSEUDO_EVENT_ATTRIBUTE)
+ * answers the gesture in JavaScript, which a frozen document cannot replay —
+ * such steps need the ordinary walk. A missing non-optional target also
+ * blocks: the live app may still render it, so the walk keeps that chance.
+ */
+export declare function heldPseudoHoldBlockers(root: ParentNode, steps: readonly DesignScreenInteraction[]): string[];
+/**
+ * The recipe a preview must hold: the page's own interactions plus any
+ * presentation-layer held gestures (the pseudo fast path). The held steps
+ * come last, so they override the recipe's terminal gestures exactly as a
+ * rewritten recipe would.
+ */
+export declare function presentationInteractions(page: {
+    interactions?: readonly DesignScreenInteraction[];
+    heldPseudoInteractions?: readonly DesignScreenInteraction[];
+}): readonly DesignScreenInteraction[] | undefined;
 export declare function heldPseudoStatesFromInteractions(interactions: readonly DesignScreenInteraction[]): HeldPseudoState[];
 /**
  * Converts pseudo-class selectors into stable attribute selectors while

package/dist-lib/types/editor/interactiveSessionSurface.d.ts

@@ -10,9 +10,22 @@ export interface InteractiveSessionSurface {
     iframe: HTMLIFrameElement;
     screenId: string;
 }
+/** Stable presentation slot shared by sibling direct-state options. */
+export declare function directInteractiveSessionSurfaceId(pageId: string, stateId: string): string;
+/**
+ * Connects the store's synchronous option selection to the session scheduler
+ * without making the store import the scheduler that already depends on it.
+ */
+export declare function setDirectInteractiveStateRequestHandler(handler: ((pageId: string) => void) | null): void;
+/** Starts direct-state delivery in the same task as the right-panel click. */
+export declare function requestDirectInteractiveState(pageId: string): boolean;
 /** Exposes a runner-owned iframe without transferring its ownership. */
 export declare function exposeInteractiveSessionSurface(screenId: string, iframe: HTMLIFrameElement): void;
 /** Releases a surface only when the caller still owns the registered iframe. */
 export declare function releaseInteractiveSessionSurface(screenId: string, iframe: HTMLIFrameElement): void;
+/** Clears a presentation slot when its page returns to an authored state. */
+export declare function clearInteractiveSessionSurface(screenId: string): void;
+/** Active direct-state surfaces pin their warm React document against eviction. */
+export declare function hasInteractiveSessionSurfaceIframe(iframe: HTMLIFrameElement): boolean;
 export declare function getInteractiveSessionSurface(screenId: string): InteractiveSessionSurface | null;
 export declare function subscribeInteractiveSessionSurface(screenId: string, listener: () => void): () => void;

package/dist-lib/types/editor/interactiveStates.d.ts

@@ -1,4 +1,4 @@
-import type { DesignScreenInteraction, StoryboardEnvironment } from './designImport';
+import type { DesignScreenInteraction, DesignSerializable, StoryboardEnvironment } from './designImport';
 import type { PageModel } from './store';
 /**
  * Screen-state axes — same-frame variations reproduced by a gesture or a boot
@@ -10,16 +10,23 @@ import type { PageModel } from './store';
  * catalog (where each would cost a captured frame) and puts them in the
  * right panel, where a designer flips between them.
  *
- * The steps are ordinary interactions, so a selected option simply extends
- * the frame's recipe. Everything downstream — the preview cache key, the
- * live replay, the session walk — already keys off that recipe, which is
- * why no supply path needs to know this feature exists.
+ * An option either extends the ordinary interaction recipe, declares a boot
+ * condition, or supplies a host-owned desired-state value. Everything
+ * downstream keys off that complete reproduction contract.
  */
 export interface InteractiveStateOption {
     id: string;
     label: string;
     /** Absent or empty marks the base state — the screen as captured. */
     steps?: readonly DesignScreenInteraction[];
+    /**
+     * Host-owned value rendered directly after mount. Selecting the option puts
+     * it under the axis id in the frame's complete desired-state map.
+     *
+     * This is an alternative to both gesture replay and a boot environment: the
+     * host adapter translates the value into preview-only application state.
+     */
+    desiredState?: DesignSerializable;
     /**
      * Boot condition this option puts the frame under, for states no gesture can
      * reach: a failed request, an empty result, a stalled stream.
@@ -95,9 +102,9 @@ export interface InteractiveStateDef {
      * all, and declaring every combination as its own option is a power set.
      *
      * Selecting toggles the option in the set; the base option (the one with no
-     * steps and no condition) clears it. Steps run and conditions merge in
-     * declaration order, so the result is stable no matter what order they were
-     * clicked in.
+     * steps, condition, or desired state) clears it. Steps run, conditions merge,
+     * and desired values collect in declaration order, so the result is stable no
+     * matter what order they were clicked in.
      *
      * Not compatible with `capturedWhen`: a per-frame base answers "which single
      * option is already on screen", which a combination has no answer to.
@@ -119,21 +126,26 @@ export type ScreenStateAxisDiagnostic = InteractiveStateDiagnostic;
 /**
  * Whether selecting this option asks supply for a different screen.
  *
- * Two ways to do that — a gesture on the booted screen, or a boot condition —
- * and the base is the option that does neither: it reproduces the capture.
- * Judging the base by "no steps" alone would read an environment-only option as
- * a second base and refuse the declaration.
+ * Three ways do that: direct desired state, a gesture on the booted screen, or
+ * a boot condition. The base is the option that declares none of them and
+ * reproduces the capture. Judging the base by "no steps" alone would read a
+ * direct or environment-only option as a second base and refuse the declaration.
  */
 export declare function optionChangesSupply(option: InteractiveStateOption): boolean;
 export declare function validateInteractiveStates(defs: readonly InteractiveStateDef[]): InteractiveStateDiagnostic[];
 /** Validates both interaction and condition axes. */
 export declare const validateScreenStateAxes: typeof validateInteractiveStates;
+/** Reads only the control-presence evidence needed by the view-only inspector. */
+export declare function previewMarkupTestIds(markup: string | null | undefined): readonly string[];
 /**
  * Axes available on one frame. The test-id requirement is checked against
- * the imported tree, so an axis stays hidden until the frame actually shows
- * the control it drives — a frame without a sidebar never offers to fold it.
+ * either the imported tree or the frozen preview's lightweight test-id index.
+ * View-only can therefore offer a real screen control without importing the
+ * whole layer tree, while a frame without that control still hides the axis.
  */
 export declare function interactiveStatesForPage(page: PageModel, defs: readonly InteractiveStateDef[]): InteractiveStateDef[];
+/** The first axis whose options can render directly on a warm host document. */
+export declare function directInteractiveStateAxisForPage(page: PageModel, defs?: readonly InteractiveStateDef[]): InteractiveStateDef | undefined;
 /** Preferred public name for axes applicable to one frame. */
 export declare const screenStateAxesForPage: typeof interactiveStatesForPage;
 /**

package/dist-lib/types/editor/previewBootstrap.d.ts

@@ -10,7 +10,7 @@ export interface PreviewCacheNamespaceOptions {
     recipeVersion?: number;
     scope?: string;
 }
-export type StoryboardCaptureRecipeInput = Pick<DesignScreenCase, 'route' | 'previewRoute' | 'path' | 'componentName' | 'gallery' | 'width' | 'height' | 'environment' | 'preset' | 'interactions' | 'assertions'>;
+export type StoryboardCaptureRecipeInput = Pick<DesignScreenCase, 'route' | 'previewRoute' | 'path' | 'componentName' | 'gallery' | 'width' | 'height' | 'environment' | 'preset' | 'desiredState' | 'interactions' | 'assertions'>;
 export interface PreviewArtifactExpectation {
     namespace: string;
     sourceRevision: string;
@@ -18,6 +18,8 @@ export interface PreviewArtifactExpectation {
 export interface PreviewArtifactFrameRequest {
     id: string;
     fingerprint?: string;
+    /** Capture recipe identity without its source dependency digest. */
+    recipeFingerprint?: string;
     /** The recipe the fingerprint stands for; travels only where a capture may run. */
     recipe?: RoutePreviewFrameRecipe;
 }
@@ -174,6 +176,7 @@ export interface PreviewFramePage {
     height?: number;
     environment?: StoryboardEnvironment;
     preset?: unknown;
+    desiredState?: unknown;
     interactions?: unknown;
     assertions?: unknown;
 }
@@ -194,6 +197,7 @@ export interface RoutePreviewFrameRecipe {
     height?: number;
     environment?: StoryboardEnvironment;
     preset?: unknown;
+    desiredState?: unknown;
     interactions?: unknown;
     assertions?: unknown;
 }
@@ -218,6 +222,8 @@ export declare function resolveRoutePreviewFrameRequestPage(request: PreviewArti
  * now captures per frame instead of demanding the whole catalog up front.
  */
 export declare function createRoutePreviewFrameFingerprint(page: PreviewFramePage, previewRevision: string, baselineEnvironment?: StoryboardEnvironment): string;
+/** The reproducible capture recipe, kept separate from changing source content. */
+export declare function createRoutePreviewFrameRecipeFingerprint(page: PreviewFramePage, baselineEnvironment?: StoryboardEnvironment): string;
 export declare function createPreviewCacheNamespace({ sourceRevision, recipes, recipeVersion, scope, }: PreviewCacheNamespaceOptions): string;
 /**
  * Device pixels captured per CSS pixel. Must mirror