@pygmalionjs/pygmalion 0.6.27 → 0.6.28

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'];

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).

package/docs/screen-state-contract.md

@@ -6,7 +6,7 @@ how the variation is reproduced, not from how different its pixels look.
 | Placement | Use when | Pygmalion declaration |
 | --- | --- | --- |
 | Frame | The variation is an independent task, journey checkpoint, structural composition, overlay context, or supported viewport that reviewers must navigate to directly. | `DesignScreenCase` |
-| Interaction state | The same booted screen reaches a deterministic, reversible visual endpoint through a local gesture. | `ScreenStateAxisDef` with `kind: 'interaction'` |
+| Interaction state | The same booted screen has a deterministic, reversible visual endpoint, reached either directly or through a local gesture. | `ScreenStateAxisDef` with `kind: 'interaction'` and `desiredState` or `steps` |
 | Condition state | The same screen needs external data, network, storage, permission, media, or timing conditions before it boots. | `ScreenStateAxisDef` with `kind: 'condition'` |
 | Editable parameter | The variation only samples text length, row count, content, or another freely editable value and has no distinct product endpoint. | Edit mode, component props, list controls, viewport controls, or QA data |
 | Motion preview | The same screen continuously changes through CSS or Web Animations without becoming a new product state. | Automatically discovered **Motion** controls |
@@ -41,9 +41,10 @@ interaction states. They must not become duplicate frames.
 
 The W and H controls in the frame inspector change the frame viewport, not the
 canvas camera. A committed size is part of the frame fingerprint and its exact
-capture recipe. The request carries the route, width, height, conditions, and
-interactions that produced that fingerprint, and a returned artifact is seeded
-under that requested recipe instead of the authored catalog key.
+capture recipe. The request carries the route, width, height, conditions,
+desired state, and interactions that produced that fingerprint. A returned
+artifact is seeded under that requested recipe instead of the authored catalog
+key.
 
 This distinction is observable: resizing a frame may change responsive layout,
 while changing canvas zoom only changes how large the same frame appears in the
@@ -73,6 +74,12 @@ axis targets the same element and pseudo action, Pygmalion suppresses that
 automatic duplicate. Click-driven toggles and other application states remain
 declared axes unless they already have their own review frame.
 
+In view-only mode, `requires.testId` is matched against the frozen preview's
+lightweight test-id index as well as an imported layer tree. This keeps right
+panel state controls available without turning selection into a layer import or
+live boot, and still hides an axis from screens whose captured DOM lacks its
+target.
+
 ## Automatic motion coverage
 
 Pygmalion discovers visible CSS animation owners, animated pseudo elements,
@@ -140,6 +147,11 @@ export const screenStateAxes: readonly ScreenStateAxisDef[] = [
           },
         ],
       },
+      {
+        id: 'collapsed',
+        label: 'Collapsed',
+        desiredState: 'collapsed',
+      },
     ],
   },
   {
@@ -167,11 +179,48 @@ export const screenStateAxes: readonly ScreenStateAxisDef[] = [
 ```
 
 An interaction option cannot declare `environment`. Every non-base condition
-option must declare one. An interaction option ending in `fill` is rejected
-unless a later targeted `wait` proves that the input reached a distinct visual
-result. This keeps empty strings and maximum-length samples out of the state
-panel while still allowing a search input to reproduce a real empty-result
-state.
+option must declare one. A direct `desiredState` value cannot be combined with
+steps or an environment on the same option. An interaction option ending in
+`fill` is rejected unless a later targeted `wait` proves that the input reached
+a distinct visual result. This keeps empty strings and maximum-length samples
+out of the state panel while still allowing a search input to reproduce a real
+empty-result state.
+
+## Direct desired state
+
+Use direct desired state for a locally controlled endpoint whose final visual
+state matters more than the gestures used to reach it. Pygmalion builds a
+complete map from selected axes, such as `{ sidebar: 'collapsed' }`, and calls
+the host's `executeDesiredState` adapter after mount and before any remaining
+interaction steps. The map participates in capture and preview identity.
+
+The adapter must replace its whole preview state, not merge it. Pygmalion calls
+it with `{}` as well, so a warm iframe reused for another frame cannot retain a
+previous override. A typical React host exposes the map through an external
+store and lets each component read only its own axis. The adapter is preview
+infrastructure: it must not dispatch the application's production store or
+write persistent product state. When a reviewer uses the real control, the
+component should release its preview override and continue from the currently
+displayed value.
+
+The right-panel selection starts delivery in the same input task. Once one
+option has a live document, sibling direct-state options share that document:
+Pygmalion skips boot, route entry, gesture replay, assertions, and geometry
+settling, then sends the replacement map to the host adapter. The React commit
+is the presentation boundary; snapshot serialization may continue afterward
+without blocking the visible state. A live direct-state document is pinned
+against normal warm-pool eviction and cannot be claimed through gesture-prefix
+matching, because those signatures do not describe host-owned state.
+Sibling delivery calls the live adapter directly rather than joining the replay
+runner's FIFO. Frames that expose a direct-state axis also reserve their
+activation-warmed document from unrelated gesture prefetch and align it
+invisibly behind the frozen frame. The first selection can therefore reveal the
+already-positioned React document after its adapter commit; speculative work
+cannot reintroduce a queue between the panel click and that commit.
+
+Keep gesture steps when the transition itself is under review, when effects
+outside local render state establish the endpoint, or when the host has no safe
+preview-only adapter for that state.
 
 ## Scroll positions