@pygmalionjs/pygmalion 0.6.26 → 0.6.28

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
 

package/node/dev-mirror.mjs

@@ -37,6 +37,47 @@ export function resolveDevMirrorInventoryOutputRoot(inventory, mirrorAppRoot) {
   return path.resolve(inventory?.outputRoot ?? mirrorAppRoot);
 }
 
+/** A running preview belongs to one immutable app root for its whole process. */
+export function devPreviewNeedsRestart({
+  force = false,
+  running = false,
+  activeAppRoot = null,
+  nextAppRoot,
+}) {
+  if (force) return true;
+  if (!running) return false;
+  if (typeof activeAppRoot !== 'string' || !activeAppRoot.trim()) return true;
+  return path.resolve(activeAppRoot) !== path.resolve(nextAppRoot);
+}
+
+/**
+ * A commit is not ready when the proxy child still serves another ref's root.
+ * Returning drifted makes the ordinary boot gate request the same resync that
+ * repairs a checkout whose HEAD moved underneath the server.
+ */
+export function devMirrorPreviewDriftStatus(
+  status,
+  { running = false, activeAppRoot = null, expectedAppRoot },
+) {
+  if (status?.state !== 'ready' || typeof expectedAppRoot !== 'string') {
+    return status;
+  }
+  const actual =
+    running && typeof activeAppRoot === 'string' && activeAppRoot.trim()
+      ? path.resolve(activeAppRoot)
+      : null;
+  const expected = path.resolve(expectedAppRoot);
+  if (actual === expected) return status;
+  return {
+    ...status,
+    state: 'drifted',
+    runtimeDrift: { expectedAppRoot: expected, actualAppRoot: actual },
+    error: actual
+      ? `dev screen runtime drifted: expected ${expected}, serving ${actual}`
+      : `dev screen runtime stopped: expected ${expected}`,
+  };
+}
+
 /**
  * Directory-safe form of a source ref, used to give each ref its own checkout.
  */
@@ -877,6 +918,7 @@ export function pygmalionDevMirrorPlugin(options) {
   let runtimeRequested = false;
   let previewChild = null;
   let previewPort = null;
+  let previewAppRoot = null;
   let syncPromise = null;
   let sharedLockPathPromise = null;
   // Assigned once the server is configured. A capture asks for the checkout
@@ -962,6 +1004,18 @@ export function pygmalionDevMirrorPlugin(options) {
    */
   const verifiedStatus = async () => {
     if (status.state !== 'ready' || !status.commit) return status;
+    const runtimeStatus = devMirrorPreviewDriftStatus(status, {
+      running:
+        previewChild != null &&
+        previewChild.exitCode == null &&
+        previewPort != null,
+      activeAppRoot: previewAppRoot,
+      expectedAppRoot: mirrorAppRoot,
+    });
+    if (runtimeStatus !== status) {
+      status = runtimeStatus;
+      return status;
+    }
     if (Date.now() - lastVerifiedAt < STATUS_VERIFY_TTL_MS) return status;
     lastVerifiedAt = Date.now();
     const actual = await git(mirrorRoot, 'rev-parse', 'HEAD').catch(() => null);
@@ -973,6 +1027,7 @@ export function pygmalionDevMirrorPlugin(options) {
     const child = previewChild;
     previewChild = null;
     previewPort = null;
+    previewAppRoot = null;
     if (!child || child.exitCode != null) return;
     child.kill('SIGTERM');
   };
@@ -1052,15 +1107,29 @@ export function pygmalionDevMirrorPlugin(options) {
     await run(command, args, { cwd: path.resolve(inventory.cwd ?? editorRoot) });
   };
 
-  const startPreview = async (restart, sourceIdentity = ref) => {
+  const startPreview = async (forceRestart, sourceIdentity = ref) => {
+    const running =
+      previewChild != null &&
+      previewChild.exitCode == null &&
+      previewPort != null;
+    const restart = devPreviewNeedsRestart({
+      force: forceRestart,
+      running,
+      activeAppRoot: previewAppRoot,
+      nextAppRoot: mirrorAppRoot,
+    });
     if (restart) await stopPreview();
     if (previewChild && previewChild.exitCode == null && previewPort != null) return;
 
+    // Keep the process identity local. `mirrorAppRoot` is mutable and can point
+    // at another ref by the time readiness or the exit callback runs.
+    const appRoot = mirrorAppRoot;
+    const appViteConfig = viteConfig;
     previewPort = await pickPort(preferredPreviewPort);
     const viteBin = path.resolve(
       options.viteBin ??
         path.join(
-          mirrorAppRoot,
+          appRoot,
           dependencies.modulesDirectory ?? 'node_modules',
           'vite',
           'bin',
@@ -1081,32 +1150,34 @@ export function pygmalionDevMirrorPlugin(options) {
         '--strictPort',
       ],
       {
-        cwd: mirrorAppRoot,
+        cwd: appRoot,
         env: {
           ...process.env,
           PYGMALION_PREVIEW_MODE: '1',
           // The child outlives a killed parent otherwise — it watches this pid.
           PYGMALION_PREVIEW_PARENT_PID: String(process.pid),
-          PYGMALION_APP_ROOT: mirrorAppRoot,
-          PYGMALION_VITE_CONFIG: viteConfig,
+          PYGMALION_APP_ROOT: appRoot,
+          PYGMALION_VITE_CONFIG: appViteConfig,
           PYGMALION_PREVIEW_BASE: `${prefix}/`,
           PYGMALION_VITE_CACHE_DIR: resolvePygmalionPreviewViteCacheDir({
-            appRoot: mirrorAppRoot,
+            appRoot,
             instance: `mirror:${sourceIdentity}:${prefix}`,
             modulesDirectory: dependencies.modulesDirectory,
           }),
           // Legacy names keep older preview configs working.
-          PYGMALION_DEV_FRONTEND_ROOT: mirrorAppRoot,
+          PYGMALION_DEV_FRONTEND_ROOT: appRoot,
           PYGMALION_DEV_BASE: `${prefix}/`,
         },
         stdio: ['ignore', 'inherit', 'inherit'],
       },
     );
     previewChild = child;
+    previewAppRoot = appRoot;
     child.once('exit', (code) => {
       if (previewChild !== child) return;
       previewChild = null;
       previewPort = null;
+      previewAppRoot = null;
       if (status.state === 'ready' && code !== 0) {
         status = {
           ...status,
@@ -1115,7 +1186,7 @@ export function pygmalionDevMirrorPlugin(options) {
         };
       }
     });
-    await waitUntilReady(previewPort, mirrorAppRoot, prefix);
+    await waitUntilReady(previewPort, appRoot, prefix);
   };
 
   const syncMirror = async (nextRef) => {
@@ -1201,6 +1272,7 @@ export function pygmalionDevMirrorPlugin(options) {
     pygmalion: {
       acquireLease: (label) => acquireDevMirrorLease({ repoRoot, mirrorRoot, label }),
       activeMirrorRoot: () => mirrorRoot,
+      activeAppRoot: () => mirrorAppRoot,
       // A capture needs the checkout as much as a live frame does, but it asks
       // at another plugin's endpoint. Without these two the demand never
       // reached the starter: the frame had no origin to request, so nothing

package/node/preview-artifact-plugin.mjs

@@ -170,6 +170,16 @@ function requestedFrames(params) {
       if (typeof fingerprint !== 'string' || !fingerprint.trim()) return null;
       if (fingerprint.length > MAX_IDENTITY_LENGTH) return null;
     }
+    const recipeFingerprint = item.recipeFingerprint;
+    if (recipeFingerprint !== undefined) {
+      if (
+        typeof recipeFingerprint !== 'string' ||
+        !recipeFingerprint.trim() ||
+        recipeFingerprint.length > MAX_IDENTITY_LENGTH
+      ) {
+        return null;
+      }
+    }
     // The recipe the fingerprint stands for. A fingerprint is a hash — a
     // generator handed one alone can only re-capture what the host declared for
     // that id, which is a different screen wearing the requested name. Carried
@@ -184,6 +194,7 @@ function requestedFrames(params) {
     wanted.push({
       id,
       ...(fingerprint === undefined ? {} : { fingerprint }),
+      ...(recipeFingerprint === undefined ? {} : { recipeFingerprint }),
       ...(recipe === undefined ? {} : { recipe }),
     });
   }
@@ -256,6 +267,7 @@ function exactArtifact(artifact, namespace, sourceRevision) {
  */
 export function pygmalionPreviewArtifactPlugin({
   root = process.cwd(),
+  sourceRoot,
   artifactFile = DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
   endpoint = PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
   disabled = () => false,
@@ -305,7 +317,7 @@ export function pygmalionPreviewArtifactPlugin({
     artifactFile: resolvedArtifact,
     // With the source root, a published frame records the files it actually
     // rendered, so freshness stops depending on which revision captured it.
-    sourceRoot: resolvedRoot,
+    sourceRoot: sourceRoot ?? resolvedRoot,
     ...(artifactStoreMaxBytes == null
       ? {}
       : { maxBytes: artifactStoreMaxBytes }),
@@ -644,6 +656,7 @@ export function pygmalionPreviewArtifactPlugin({
           await artifactStore.publishArtifact(generated, {
             sourceRevision,
             recordRevision: false,
+            frameRequests: remaining,
           });
           // Retention is allowed to decline a newly generated object when older
           // entries have earned higher read recency. That cache decision must not

package/node/preview-artifact-store.mjs

@@ -75,6 +75,8 @@ function validManifestEntry(entry, kind) {
     typeof entry.id === 'string' &&
     entry.id.length > 0 &&
     (entry.fingerprint == null || typeof entry.fingerprint === 'string') &&
+    (entry.recipeFingerprint == null ||
+      typeof entry.recipeFingerprint === 'string') &&
     (entry.sourceRevision == null || typeof entry.sourceRevision === 'string')
   );
 }
@@ -269,6 +271,13 @@ export function createPreviewArtifactStore({
   }
   const legacyFile = path.resolve(artifactFile);
   const root = path.resolve(storeDirectory);
+  const currentSourceRoot = () => {
+    const candidate =
+      typeof sourceRoot === 'function' ? sourceRoot() : sourceRoot;
+    return typeof candidate === 'string' && candidate
+      ? path.resolve(candidate)
+      : undefined;
+  };
   let legacyCache = null;
   const objectCache = new Map();
   let objectCacheBytes = 0;
@@ -451,7 +460,10 @@ export function createPreviewArtifactStore({
   const classifyFrameEntry = async (entry) => {
     const observed = normalizeObservedDependencies(entry.sourceFiles);
     if (!observed) return 'unknown';
-    return (await observedDependenciesUnchanged({ recorded: observed, sourceRoot }))
+    return (await observedDependenciesUnchanged({
+      recorded: observed,
+      sourceRoot: currentSourceRoot(),
+    }))
       ? 'valid'
       : 'invalid';
   };
@@ -626,6 +638,7 @@ export function createPreviewArtifactStore({
       recordRevision = true,
       sourceRevision = artifact?.sourceRevision,
       materializeLegacy = true,
+      frameRequests = [],
     } = {},
   ) => {
     const validation = validateRoutePreviewArtifactBundle(artifact);
@@ -680,6 +693,9 @@ export function createPreviewArtifactStore({
           }
         }
         if (artifact.version === 3) {
+          const requestsById = new Map(
+            frameRequests.map((request) => [request.id, request]),
+          );
           let frames = manifest.frames;
           for (const [id, frame] of Object.entries(artifact.frames)) {
             const selected = selectRoutePreviewArtifactFrames(artifact, [{ id }]);
@@ -690,7 +706,7 @@ export function createPreviewArtifactStore({
               normalizeObservedDependencies(frame.sourceFiles) ??
               (await recordObservedDependencies({
                 snapshot: selected.bundle?.frames?.[id]?.snapshot ?? frame.snapshot,
-                sourceRoot,
+                sourceRoot: currentSourceRoot(),
                 ...(observedAlwaysInclude
                   ? { alwaysInclude: observedAlwaysInclude }
                   : {}),
@@ -699,6 +715,12 @@ export function createPreviewArtifactStore({
               id,
               fingerprint:
                 typeof frame.fingerprint === 'string' ? frame.fingerprint : null,
+              ...(typeof requestsById.get(id)?.recipeFingerprint === 'string'
+                ? {
+                    recipeFingerprint:
+                      requestsById.get(id).recipeFingerprint,
+                  }
+                : {}),
               sourceRevision: sourceRevision ?? null,
               object,
               generation,
@@ -893,9 +915,23 @@ export function createPreviewArtifactStore({
     if (request.fingerprint != null && entry.fingerprint === request.fingerprint) {
       return true;
     }
+    // Source hashes cannot prove that viewport, environment, or interaction
+    // inputs stayed the same. They may bridge a changed source fingerprint only
+    // when the independently recorded capture recipe still matches.
+    if (
+      request.fingerprint != null &&
+      (request.recipeFingerprint == null ||
+        entry.recipeFingerprint == null ||
+        entry.recipeFingerprint !== request.recipeFingerprint)
+    ) {
+      return false;
+    }
     const observed = normalizeObservedDependencies(entry.sourceFiles);
     if (observed) {
-      return observedDependenciesUnchanged({ recorded: observed, sourceRoot });
+      return observedDependenciesUnchanged({
+        recorded: observed,
+        sourceRoot: currentSourceRoot(),
+      });
     }
     // Nothing content-based to go on: fall back to the old rule so a frame is
     // never treated as fresher than it was before.

package/node/storyboard-capture-runtime.mjs

@@ -752,6 +752,42 @@ async function executeStoryboardPreset(page, screenCase, route) {
   }, request);
 }
 
+/**
+ * Replaces host-owned post-mount UI state on the running application page.
+ * Empty state is still delivered when an adapter exists, because a warm page
+ * may carry the previous case's override. Only a non-empty request requires
+ * the host hook, preserving compatibility for hosts that do not use this path.
+ */
+export async function executeStoryboardDesiredState(page, screenCase, route) {
+  const state =
+    screenCase.desiredState && typeof screenCase.desiredState === 'object'
+      ? screenCase.desiredState
+      : {};
+  const request = {
+    pageId: screenCase.id,
+    route,
+    state,
+  };
+  const required = Object.keys(state).length > 0;
+  await page.evaluate(async ({ payload, required }) => {
+    const apply = window.__PYGMALION_APPLY_DESIRED_STATE__;
+    if (typeof apply !== 'function') {
+      if (required) {
+        throw new Error(
+          'There is a screen desired state, but the host adapter is not installed.',
+        );
+      }
+      return;
+    }
+    const result = await apply(payload);
+    if (result && result.complete === false) {
+      throw new Error(
+        result.message ?? 'The host refused to apply the screen desired state.',
+      );
+    }
+  }, { payload: request, required });
+}
+
 export function collectStoryboardDomTree() {
   const visit = (node) => {
     if (node.nodeType === Node.TEXT_NODE) {
@@ -1564,6 +1600,10 @@ export async function captureStoryboardCase({
         signal,
       });
     });
+    await atCaptureStage('state', async () => {
+      throwIfAborted(signal);
+      await executeStoryboardDesiredState(page, screenCase, route);
+    });
     for (const interaction of screenCase.interactions ?? []) {
       throwIfAborted(signal);
       await atCaptureStage(

package/node/vite.mjs

@@ -263,6 +263,7 @@ export function createPygmalionVitePlugins(config) {
         endpoint: project.preview.artifactEndpoint,
         generateArtifact,
         acquireLease: (label) => devMirror?.acquireLease(label) ?? null,
+        sourceRoot: () => devMirror?.activeAppRoot?.() ?? project.appRoot,
         requestRuntime: () => devMirror?.requestRuntime?.(),
         // No mirror plugin means no checkout to prepare, so generation is
         // always allowed to proceed as it did before.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.6.26",
+  "version": "0.6.28",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {