@pygmalionjs/pygmalion 0.6.27 → 0.6.29

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

@@ -1,5 +1,6 @@
-import type { DesignScreenInteraction, StoryboardEnvironment } from './designImport';
+import type { DesignScreenInteraction, DesignSerializable, StoryboardEnvironment } from './designImport';
 import type { PageModel } from './store';
+export { reachablePreviewTestIds } from './previewReachability';
 /**
  * Screen-state axes — same-frame variations reproduced by a gesture or a boot
  * condition.
@@ -10,16 +11,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 +103,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 +127,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, bodyAttributes?: string | null): 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 reachable 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/previewReachability.d.ts

@@ -0,0 +1,7 @@
+export declare const REACHABLE_TEST_IDS_ATTRIBUTE = "data-pygmalion-reachable-testids";
+/** Test ids whose rendered controls can actually be reached from this frame. */
+export declare function reachablePreviewTestIds(root: ParentNode): readonly string[];
+/** Stamps capture-time reachability without mutating the running document. */
+export declare function stampReachablePreviewTestIds(source: Document, clone: HTMLElement): void;
+/** Reads a capture-time reachability index, or null for a legacy snapshot. */
+export declare function indexedReachablePreviewTestIds(markup: string): readonly string[] | null;

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,14 @@ 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;
+    /**
+     * Imported layers still showing behind a direct live surface. The surface
+     * paints first; FrameView consumes this key and invalidates the old layers
+     * on the following frame so a large tree cannot block the visible switch.
+     */
+    interactiveLayerRefreshKey?: string;
     interactiveOptionId?: string;
     /**
      * Options held together on a combining axis (InteractiveStateDef.multiple).
@@ -222,6 +234,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 +266,8 @@ export interface PageModel {
     assertions?: DesignScreenAssertion[];
     /** Host-declared warm instance group. Set when the screen state is declared, not replayed. */
     session?: string;
+    /** Reachable test ids observed in the frozen preview before editable layers are imported. */
+    previewTestIds?: readonly string[];
     layerImportCount?: number;
     layerImportTruncated?: boolean;
     layerImportDiagnostics?: readonly DomImportDiagnostic[];
@@ -446,6 +473,8 @@ export declare class EditorStore {
     private pageEditRevisions;
     /** pageId → edit revision at the moment a frozen preview was promoted without a boot (D2). */
     private provisionalLayerImports;
+    /** Latest paint-first direct-state commit scheduled for each page. */
+    private directStateCommitRevisions;
     /** pageId → source geometry awaiting its post-mount fidelity measurement. */
     private pendingLayerImportGeometry;
     /** View-only motion playback never becomes part of a frame recipe or undo history. */
@@ -520,6 +549,7 @@ export declare class EditorStore {
         scenarioId?: string;
         scenarioIds?: readonly string[];
         interactions?: DesignScreenInteraction[];
+        desiredState?: DesignScreenDesiredState;
         environment?: StoryboardEnvironment;
         preset?: DesignScreenPreset;
         assertions?: DesignScreenAssertion[];
@@ -677,14 +707,49 @@ 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;
+    applyInteractiveState(pageId: string, def: InteractiveStateDef, optionId: string, options?: {
+        skipPaintFirstPreview?: boolean;
+    }): boolean;
+    /** Invalidates retained layers only after their direct live replacement painted. */
+    commitInteractiveLayerRefresh(pageId: string, refreshKey: string): boolean;
     /** The root viewport endpoint currently preserved in this frame recipe. */
     frameScrollRecipe(pageId: string): Readonly<{
         x: number;
@@ -731,6 +796,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'];

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

@@ -0,0 +1,69 @@
+import type { InteractiveStateDef, InteractiveStateOption } from './interactiveStates';
+import type { PageModel } from './store';
+/**
+ * Cheap kill switch, same shape as setCaptureSupplyMode: the host (or a
+ * console session) can turn speculation off without touching anything else.
+ * Disabling also drops any scheduled or in-progress round.
+ */
+export declare function setInteractiveStatePrefetchEnabled(enabled: boolean): void;
+export declare function interactiveStatePrefetchEnabled(): boolean;
+/** Test/tuning hook for the trigger debounce. */
+export declare function setInteractiveStatePrefetchDebounceMs(ms: number): void;
+/**
+ * The page identity the store's applyInteractiveState would produce for one
+ * exclusive-axis option, computed WITHOUT mutating the page.
+ *
+ * DUPLICATED DERIVATION — store.ts applyInteractiveState is the source of
+ * truth. Extracting the shared pure core would touch that method's body,
+ * which is deliberately left alone; the agreement test in
+ * variantPrefetch.test.mjs pins the two implementations to each other, so a
+ * change to either fails loudly. Only the single-option branch is mirrored:
+ * combining (`multiple`) axes hold sets and are out of prefetch's scope.
+ *
+ * Returns null when selecting the option asks supply for nothing new — the
+ * base option, or the option this frame's capture already shows — because
+ * the store would reset the frame to its base recipe.
+ */
+export declare function deriveInteractiveVariantIdentity(page: PageModel, def: InteractiveStateDef, option: InteractiveStateOption): PageModel | null;
+export interface InteractiveVariantPrefetchCandidate {
+    axisId: string;
+    optionId: string;
+    /** The recipe key the option's real selection would publish under. */
+    cacheKey: string;
+    /** Hypothetical identity handed to prefetchPageInteractiveVariant. */
+    variantPage: PageModel;
+}
+/**
+ * The unproduced variants of one frame, in declaration order, capped at
+ * `limit`. An option is skipped when it needs no work (base or captured),
+ * its future key already has a snapshot, or the runner already tracks its
+ * variant id (a prefetch or a real request is on it). Only declared
+ * exclusive axes participate: combining axes hold sets with no single next
+ * click to predict, and automatic pseudo axes are synthesized per element —
+ * both stay on the on-demand path.
+ */
+export declare function planInteractiveStatePrefetch(page: PageModel, previewRevision: string, limit?: number): InteractiveVariantPrefetchCandidate[];
+/** Diagnostic counters for the headless debug surface and tests. */
+export declare const __variantPrefetchDebug: {
+    requested: number;
+    rounds: number;
+    queued: number;
+    exhausted: number;
+    unavailable: number;
+};
+/**
+ * Starts a prefetch round for one frame immediately (no debounce): up to
+ * MAX_PREFETCH_WALKS_PER_ROUND idle-time walks, one at a time. Replaces any
+ * round already in progress — the newest selection is the best prediction.
+ */
+export declare function startInteractiveStatePrefetch(page: PageModel, previewRevision: string): void;
+/** Drops the scheduled trigger and the in-progress round, if any. */
+export declare function cancelScheduledInteractiveStatePrefetch(): void;
+/**
+ * Debounced trigger for the panel: called when a frame's axes become
+ * visible. The debounce keeps a designer stepping across frames from
+ * starting a round per keystroke of selection. Returns a cancel for the
+ * effect cleanup — cancelling stops the round, so speculation only runs
+ * while the frame is actually the selected one.
+ */
+export declare function requestInteractiveStatePrefetch(page: PageModel, previewRevision: string): () => void;

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

@@ -92,7 +92,7 @@ export type { ConditionCoverageRoute, ConditionCoverageScreen, ConformanceScreen
 export { clearPreviewEnvironmentControlValues, getPreviewEnvironmentControlValue, getPreviewEnvironmentControls, getPreviewEnvironmentOverride, setPreviewEnvironmentControlValue, setPreviewEnvironmentControls, subscribePreviewEnvironmentControls, } from './editor/previewEnvironmentControls';
 export type { PreviewEnvironmentControlDef, PreviewEnvironmentControlOptionDef, } from './editor/previewEnvironmentControls';
 export { createDesignImportController, createDesignScreenCollection, DESIGN_IMPORT_KINDS, expandDesignScreenCasesViewports, expandDesignScreenCollectionViewports, mergeScreenPresets, } from './editor/designImport';
-export type { CreateDesignImportOptions, DesignBehaviorScenario, DesignImportAsset, DesignImportCollection, DesignImportController, DesignImportCoverage, DesignImportCoverageItem, DesignImportInitialPage, DesignImportKind, DesignImportManifest, DesignImportPage, DesignFrameHeightMode, DesignFrameSizeMode, DesignScenarioCoverage, DesignScenarioSource, DesignScreenCase, DesignScreenAssertion, DesignScreenAssertionReport, DesignScreenAssertionVisibility, DesignScreenAttributeAssertion, DesignScreenCaptureFailure, DesignScreenCaptureFailureCode, DesignScreenCaptureFailureStage, DesignScreenCaptureDefaults, DesignScreenCaptureRequirements, DesignScreenCaptureReport, DesignScreenCaptureSpec, DesignScreenCollectionResult, DesignScreenInteraction, DesignScreenInteractionAction, DesignScreenInteractionRunOptions, DesignScreenInteractionReport, DesignScreenPreset, DesignScreenPresetContext, DesignScreenPresetExecutionResult, DesignScreenPresetExecutor, DesignScreenPresetRequest, DesignScreenViewport, DesignScreenViewportExpansionOptions, DesignScreenViewportPagePatch, DesignSerializable, StoryboardEnvironment, StoryboardMediaDevice, StoryboardMediaFailure, StoryboardNetwork, StoryboardPermissionState, StoryboardRequestCondition, StoryboardRequestOutcome, } from './editor/designImport';
+export type { CreateDesignImportOptions, DesignBehaviorScenario, DesignImportAsset, DesignImportCollection, DesignImportController, DesignImportCoverage, DesignImportCoverageItem, DesignImportInitialPage, DesignImportKind, DesignImportManifest, DesignImportPage, DesignFrameHeightMode, DesignFrameSizeMode, DesignScenarioCoverage, DesignScenarioSource, DesignScreenCase, DesignScreenAssertion, DesignScreenAssertionReport, DesignScreenAssertionVisibility, DesignScreenAttributeAssertion, DesignScreenCaptureFailure, DesignScreenCaptureFailureCode, DesignScreenCaptureFailureStage, DesignScreenCaptureDefaults, DesignScreenCaptureRequirements, DesignScreenCaptureReport, DesignScreenCaptureSpec, DesignScreenCollectionResult, DesignScreenDesiredState, DesignScreenDesiredStateExecutor, DesignScreenDesiredStateRequest, DesignScreenInteraction, DesignScreenInteractionAction, DesignScreenInteractionRunOptions, DesignScreenInteractionReport, DesignScreenPreset, DesignScreenPresetContext, DesignScreenPresetExecutionResult, DesignScreenPresetExecutor, DesignScreenPresetRequest, DesignScreenViewport, DesignScreenViewportExpansionOptions, DesignScreenViewportPagePatch, DesignSerializable, StoryboardEnvironment, StoryboardMediaDevice, StoryboardMediaFailure, StoryboardNetwork, StoryboardPermissionState, StoryboardRequestCondition, StoryboardRequestOutcome, } from './editor/designImport';
 export type { DomImportDiagnostic, DomImportMetrics, DomImportOptions, DomImportResult, } from './editor/domImport';
 export type { SharedSourceEditScope, SharedSourceFrameSummary, SharedSourceImpact, } from './editor/sharedSource';
 export type { NodeJSON } from './editor/store';
@@ -182,6 +182,9 @@ export declare const __debug: {
                 noPath: number;
                 resolvedNull: number;
                 queued: number;
+                reparkQueued: number;
+                reparkAlreadyParked: number;
+                reparkNoExtraSteps: number;
             };
             states: Record<string, unknown>;
         };
@@ -201,8 +204,71 @@ export declare const __debug: {
             reuses: number;
             parks: number;
             evictions: number;
+            refreshes: number;
         };
     }>;
+    /**
+     * State-switch instrumentation: phase timings of recent flow-session walks
+     * (boot/replay/settle/stability/serialize/publish, per runner label, warm
+     * reuse vs cold boot) plus route-preview producer-gate counters. JSON-safe.
+     */
+    stateSwitchMetrics(): Promise<{
+        walks: {
+            byRunner: {
+                [k: string]: {
+                    count: number;
+                    completed: number;
+                    coldBoots: number;
+                    warmReuses: number;
+                    stabilityTimeouts: number;
+                    phases: Record<import("./editor/stateSwitchMetrics").StateSwitchPhase, import("./editor/stateSwitchMetrics").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<import("./editor/stateSwitchMetrics").StateSwitchPhase, import("./editor/stateSwitchMetrics").PhaseAggregate>;
+        };
+        routePreviewProducer: {
+            evaluations: number;
+            allowed: number;
+            suppressed: number;
+            byTrigger: {
+                endpointNotConfigured: number;
+                detailActive: number;
+                previewIntended: number;
+            };
+        };
+    }>;
+    /** Clears the state-switch metrics between headless audit scenarios. */
+    resetStateSwitchMetrics(): Promise<void>;
 };
 /**
  * Called from the actual button handler of the host screen fixture — Switches to the name matching page (common in editor and preview).