@pygmalionjs/pygmalion 0.6.26 → 0.6.28

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

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

@@ -13,6 +13,11 @@ export interface PygmalionDevMirrorStatus {
     warning: string | null;
     error: string | null;
     appOrigin: string | null;
+    /** Present when the proxy child is absent or serves another ref's checkout. */
+    runtimeDrift?: {
+        expectedAppRoot: string;
+        actualAppRoot: string | null;
+    };
 }
 /** One revision the mirror can be repointed at. */
 export interface PygmalionSourceRef {

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

@@ -12,6 +12,7 @@ export interface RoutePreviewRecipe {
     height: number;
     environment?: unknown;
     preset?: unknown;
+    desiredState?: unknown;
     interactions?: unknown;
     assertions?: unknown;
 }
@@ -55,6 +56,7 @@ export interface RoutePreviewArtifactPage {
     height?: number;
     environment?: StoryboardEnvironment;
     preset?: unknown;
+    desiredState?: unknown;
     interactions?: unknown;
     assertions?: unknown;
 }
@@ -66,6 +68,8 @@ export interface RoutePreviewArtifactSeedResult {
 export interface RoutePreviewArtifactFrameIdentity {
     id: string;
     fingerprint?: string;
+    /** Capture recipe identity without its source dependency digest. */
+    recipeFingerprint?: string;
     /**
      * The recipe the fingerprint stands for, carried so a generator can reproduce
      * it. Without this a host can only re-capture what it declared for the id and
@@ -210,6 +214,7 @@ export declare function shouldRequestRoutePreviewArtifactFrame({ cacheHydrated,
  */
 export declare function requestRoutePreviewArtifactFrame(id: string, fingerprint?: string, options?: {
     retry?: boolean;
+    recipeFingerprint?: string;
     recipe?: RoutePreviewFrameRecipe;
     priority?: number;
 }): Promise<RoutePreviewArtifactResolution> | null;

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

@@ -0,0 +1,150 @@
+export type StateSwitchPhase = 'boot' | 'replay' | 'settle' | 'stability' | 'serialize' | 'publish';
+type Clock = () => number;
+/** Test hook: replace the phase clock (pass null to restore the default). */
+export declare function setStateSwitchMetricsClock(next: Clock | null): void;
+interface WaypointTiming {
+    screenId: string;
+    replayMs: number | null;
+    settleMs: number | null;
+    stabilityMs: number | null;
+    stabilityTimedOut: boolean;
+    serializeMs: number | null;
+    publishMs: number | null;
+}
+/**
+ * Live handle for one walk. Created by beginStateSwitchWalk, fed by the
+ * mark/record hooks inside walkPath, and closed by endStateSwitchWalk.
+ */
+export interface StateSwitchWalkTrace {
+    runner: string;
+    pathId: string;
+    /** True when the walk resumed on a parked warm instance (no boot). */
+    reused: boolean;
+    startedAtEpochMs: number;
+    startedAt: number;
+    markAt: number | null;
+    bootMs: number | null;
+    waypoints: WaypointTiming[];
+    current: WaypointTiming | null;
+    ended: boolean;
+}
+export interface PhaseAggregate {
+    count: number;
+    totalMs: number;
+    maxMs: number;
+}
+export interface WalkAggregate {
+    count: number;
+    completed: number;
+    coldBoots: number;
+    warmReuses: number;
+    stabilityTimeouts: number;
+    phases: Record<StateSwitchPhase, PhaseAggregate>;
+}
+export interface WalkRecord {
+    runner: string;
+    pathId: string;
+    reused: boolean;
+    completed: boolean;
+    startedAtEpochMs: number;
+    totalMs: number;
+    bootMs: number | null;
+    /** Per-phase sums across the walk's waypoints, for quick reading. */
+    totals: {
+        replayMs: number;
+        settleMs: number;
+        stabilityMs: number;
+        serializeMs: number;
+        publishMs: number;
+    };
+    waypoints: WaypointTiming[];
+}
+/** Opens a walk trace; called once per walkPath invocation. */
+export declare function beginStateSwitchWalk(runner: string, pathId: string, reused: boolean): StateSwitchWalkTrace;
+/** Opens the next waypoint's timing slot and drops any stale phase mark. */
+export declare function beginStateSwitchWaypoint(trace: StateSwitchWalkTrace, screenId: string): void;
+/** Stamps the start of the next phase; recordStateSwitchPhase reads it. */
+export declare function markStateSwitchPhase(trace: StateSwitchWalkTrace): void;
+/**
+ * Closes the phase opened by the last mark: attributes the elapsed time to
+ * the walk (boot) or the current waypoint, and feeds the aggregates. Without
+ * a preceding mark this records nothing.
+ */
+export declare function recordStateSwitchPhase(trace: StateSwitchWalkTrace, phase: StateSwitchPhase): void;
+/**
+ * Closes the walk: bumps the walk counters and pushes one record into the
+ * bounded history. Safe to call once per trace only; later calls no-op.
+ */
+export declare function endStateSwitchWalk(trace: StateSwitchWalkTrace, completed: boolean): void;
+/**
+ * One producer-gate evaluation. The gate is a pure predicate evaluated per
+ * frame render, so `allowed` is an upper bound on actual producer starts;
+ * the byTrigger ratio is the signal (which condition keeps opening the gate).
+ */
+export declare function recordRoutePreviewProducerDecision(input: {
+    endpointConfigured: boolean;
+    detailActive: boolean;
+    previewIntended: boolean;
+}): void;
+/**
+ * Plain JSON-safe snapshot for the headless debug surface. `walks.recent` is
+ * oldest-first and bounded to the last WALK_HISTORY_CAPACITY walks.
+ */
+export declare function getStateSwitchMetricsSnapshot(): {
+    walks: {
+        byRunner: {
+            [k: string]: {
+                count: number;
+                completed: number;
+                coldBoots: number;
+                warmReuses: number;
+                stabilityTimeouts: number;
+                phases: Record<StateSwitchPhase, PhaseAggregate>;
+            };
+        };
+        recent: {
+            totals: {
+                replayMs: number;
+                settleMs: number;
+                stabilityMs: number;
+                serializeMs: number;
+                publishMs: number;
+            };
+            waypoints: {
+                screenId: string;
+                replayMs: number | null;
+                settleMs: number | null;
+                stabilityMs: number | null;
+                stabilityTimedOut: boolean;
+                serializeMs: number | null;
+                publishMs: number | null;
+            }[];
+            runner: string;
+            pathId: string;
+            reused: boolean;
+            completed: boolean;
+            startedAtEpochMs: number;
+            totalMs: number;
+            bootMs: number | null;
+        }[];
+        count: number;
+        completed: number;
+        coldBoots: number;
+        warmReuses: number;
+        stabilityTimeouts: number;
+        phases: Record<StateSwitchPhase, PhaseAggregate>;
+    };
+    routePreviewProducer: {
+        evaluations: number;
+        allowed: number;
+        suppressed: number;
+        byTrigger: {
+            endpointNotConfigured: number;
+            detailActive: number;
+            previewIntended: number;
+        };
+    };
+};
+/** Drops every counter and the walk history; test and audit boundary hook. */
+export declare function resetStateSwitchMetrics(): void;
+export {};

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

@@ -3,7 +3,7 @@ import { type InteractiveStateDef } from './interactiveStates';
 import { type ScreenDimensionDef } from './screenDimensions';
 import { type CardBadgeOption, type CardSlotDef, type ScreenCardDef } from './screenCards';
 import { type ScreenListDef } from './screenLists';
-import { type DesignImportAsset, type DesignImportKind, type DesignFrameSizeMode, type DesignScreenAssertion, type DesignScreenInteraction, type DesignScreenPreset, type StoryboardEnvironment } from './designImport';
+import { type DesignImportAsset, type DesignImportKind, type DesignFrameSizeMode, type DesignScreenAssertion, type DesignScreenDesiredState, type DesignScreenInteraction, type DesignScreenPreset, type StoryboardEnvironment } from './designImport';
 import { type DomImportDiagnostic, type DomImportResult } from './domImport';
 import { type LayerImportFidelityReport, type MeasurableElement } from './importFidelity';
 import { type DesignFrameHeightMode } from './frameHeight';
@@ -204,6 +204,10 @@ export interface PageModel {
     interactions?: DesignScreenInteraction[];
     /** Captured recipe, kept while a declared interactive state extends it. */
     baseInteractions?: DesignScreenInteraction[];
+    /** Captured host-owned desired state, restored when a direct option is cleared. */
+    authoredDesiredState?: DesignScreenDesiredState;
+    /** Complete host-owned UI state applied after the preview application mounts. */
+    desiredState?: DesignScreenDesiredState;
     /** View-only scroll endpoint currently held on this frame's preview recipe. */
     previewScroll?: {
         x: number;
@@ -215,6 +219,8 @@ export interface PageModel {
     previewScrollInteraction?: DesignScreenInteraction;
     /** Declared interactive axis the frame is currently held in, if any. */
     interactiveStateId?: string;
+    /** The active option is rendered through host desired state, without replay. */
+    interactiveStateUsesDesiredState?: boolean;
     interactiveOptionId?: string;
     /**
      * Options held together on a combining axis (InteractiveStateDef.multiple).
@@ -222,6 +228,19 @@ export interface PageModel {
      * exclusive axis reads exactly as before.
      */
     interactiveOptionIds?: string[];
+    /**
+     * Held-pseudo steps applied as presentation only — the pseudo fast path.
+     *
+     * A pure-CSS pseudo option (hover/focus/focus-visible/active on a target
+     * without script-driven pseudo events) is a styling variation of the import
+     * already on screen, so the mounted frozen preview holds it client-side —
+     * exactly as it already holds the recipe's own terminal pseudo gestures.
+     * Kept OUTSIDE `interactions` on purpose: the recipe is the frame's cache
+     * identity (framePreviewKeys), and rewriting it would re-key the frame
+     * while its artifacts, snapshots, and fidelity verdicts still describe the
+     * base import.
+     */
+    heldPseudoInteractions?: DesignScreenInteraction[];
     /**
      * The case's own environment, kept so clearing an interactive option can put
      * `environment` back without reconstructing what the case declared. Same shape
@@ -241,6 +260,8 @@ export interface PageModel {
     assertions?: DesignScreenAssertion[];
     /** Host-declared warm instance group. Set when the screen state is declared, not replayed. */
     session?: string;
+    /** Test ids observed in the frozen preview before editable layers are imported. */
+    previewTestIds?: readonly string[];
     layerImportCount?: number;
     layerImportTruncated?: boolean;
     layerImportDiagnostics?: readonly DomImportDiagnostic[];
@@ -520,6 +541,7 @@ export declare class EditorStore {
         scenarioId?: string;
         scenarioIds?: readonly string[];
         interactions?: DesignScreenInteraction[];
+        desiredState?: DesignScreenDesiredState;
         environment?: StoryboardEnvironment;
         preset?: DesignScreenPreset;
         assertions?: DesignScreenAssertion[];
@@ -677,12 +699,43 @@ export declare class EditorStore {
      */
     applyCardBadge(pageId: string, def: ScreenCardDef, cardNodeId: string, slot: CardSlotDef, option: CardBadgeOption, present: boolean): boolean;
     /**
-     * Puts a frame into a declared interactive state by extending its recipe.
+     * Fast path for pure-CSS pseudo options: holds the state on the mounted
+     * frozen preview instead of re-walking the frame.
+     *
+     * Selecting "Hover" on a control is a CSS-only variation of the import
+     * already on screen, yet the ordinary path re-keys the recipe and drops the
+     * import — a hidden boot, a full recipe replay, and a re-import for a style
+     * the frozen mount can hold in place. A walk-produced snapshot for such an
+     * option shows nothing the client-side hold does not: the frozen mount
+     * re-applies held pseudo gestures from the recipe on every mount anyway
+     * (mountFrozenShadowPreview), so holding them over the existing verified
+     * base is the same pixels seconds earlier.
+     *
+     * When every step is a held-pseudo gesture whose target the mounted frozen
+     * preview resolves without a script-driven pseudo-event stamp, the
+     * selection is recorded as presentation state (`heldPseudoInteractions`)
+     * that the shadow preview merges into its held gestures. The recipe — and
+     * with it the preview cache key, artifact resolution, snapshot lookups,
+     * and fidelity verdicts — stays untouched, and returning to the base is
+     * removing the hold.
+     *
+     * Everything else falls back to the walk: combining axes, boot conditions,
+     * non-pseudo or missing-target steps, script-reactive targets, frames
+     * without imported layers or without a mounted non-stale frozen preview,
+     * and frames whose applied state was produced by a recipe rewrite.
+     */
+    private applyHeldPseudoInteractiveState;
+    /**
+     * Puts a frame into a declared interactive state through its reproduction
+     * contract: gesture recipe, boot environment, or direct desired state.
      *
      * The steps become part of `page.interactions`, which is what the preview
      * cache key, the live replay and the session walk all read — so the frame
      * asks for the variant through the ordinary supply instead of a parallel
      * path. Returning to the base option restores the captured recipe.
+     *
+     * Pure-CSS pseudo options short-circuit through the held-pseudo fast path
+     * (applyHeldPseudoInteractiveState) and never touch the recipe.
      */
     applyInteractiveState(pageId: string, def: InteractiveStateDef, optionId: string): boolean;
     /** The root viewport endpoint currently preserved in this frame recipe. */
@@ -731,6 +784,8 @@ export declare class EditorStore {
     /** Design importer automatically inserts the capture results into the existing frame. The route is maintained for live preview. */
     replacePageRootFromDom(pageId: string, rootJson: NodeJSON, result?: Pick<DomImportResult, 'count' | 'truncated'> & Partial<Pick<DomImportResult, 'diagnostics' | 'metrics' | 'geometry'>>): void;
     setPageLayerImportError(pageId: string, message: string): void;
+    /** Lets the view-only inspector classify axes from the frozen screen it already shows. */
+    setPagePreviewTestIds(pageId: string, testIds: readonly string[]): void;
     /**
      * Runs the fidelity measurement once the imported tree has committed and
      * laid out — one frame for React, one for layout. FrameView re-invokes the

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

@@ -57,6 +57,7 @@ export interface StoryboardResolvedPage {
     state?: string;
     scenarioId?: string;
     interactions?: DesignScreenCase['interactions'];
+    desiredState?: DesignScreenCase['desiredState'];
     environment?: StoryboardEnvironment;
     preset?: DesignScreenCase['preset'];
     assertions?: DesignScreenCase['assertions'];