@pygmalionjs/pygmalion 0.6.27 → 0.6.29

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,15 @@ 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 **reachable** test-id index as well as an imported layer tree. A
+test id under `display: none`, hidden visibility, zero opacity, or an inert
+ancestor does not qualify merely because React kept that branch mounted. This
+keeps right-panel state controls available without turning selection into a
+layer import or live boot, while hiding axes that the captured frame cannot
+actually reach. Legacy snapshots without a capture-time index are measured
+after their inert DOM mounts.
+
 ## Automatic motion coverage
 
 Pygmalion discovers visible CSS animation owners, animated pseudo elements,
@@ -140,6 +150,11 @@ export const screenStateAxes: readonly ScreenStateAxisDef[] = [
           },
         ],
       },
+      {
+        id: 'collapsed',
+        label: 'Collapsed',
+        desiredState: 'collapsed',
+      },
     ],
   },
   {
@@ -167,11 +182,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) {
@@ -1020,6 +1056,56 @@ export function serializeStoryboardPreviewDocument(
   const clone = document.documentElement.cloneNode(true);
   if (!(clone instanceof HTMLElement)) return null;
 
+  // A frozen snapshot preserves branches that are mounted but visually absent
+  // (for example, two workspace panels cross-faded with opacity). Presence
+  // alone therefore cannot tell the inspector which controls this captured
+  // frame can actually reach. Record a compact, capture-time visibility index
+  // on the body; older snapshots without it are measured again after mount.
+  try {
+    const reachableTestIds = new Set();
+    const hasRenderedBox = (element) => {
+      const rect = element.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) return true;
+      return [...element.querySelectorAll('*')].some((descendant) => {
+        const descendantRect = descendant.getBoundingClientRect();
+        return descendantRect.width > 0 && descendantRect.height > 0;
+      });
+    };
+    const isReachable = (element) => {
+      for (
+        let current = element;
+        current;
+        current = current.parentElement
+      ) {
+        const style = window.getComputedStyle(current);
+        const opacity = Number.parseFloat(style.opacity || '1');
+        if (
+          current.hasAttribute('hidden') ||
+          current.hasAttribute('inert') ||
+          style.display === 'none' ||
+          style.visibility === 'hidden' ||
+          style.visibility === 'collapse' ||
+          (Number.isFinite(opacity) && opacity <= 0)
+        ) {
+          return false;
+        }
+      }
+      return hasRenderedBox(element);
+    };
+    for (const element of document.documentElement.querySelectorAll('*')) {
+      const testId = element.getAttribute('data-testid');
+      if (testId && isReachable(element)) reachableTestIds.add(testId);
+    }
+    const cloneBody = clone.querySelector('body');
+    cloneBody?.setAttribute(
+      'data-pygmalion-reachable-testids',
+      encodeURIComponent(JSON.stringify([...reachableTestIds].sort())),
+    );
+  } catch {
+    // Reachability metadata is additive. A constrained capture realm may not
+    // implement layout; the mounted-preview fallback handles that snapshot.
+  }
+
   const sourceInputs = [...document.querySelectorAll('input')];
   const cloneInputs = [...clone.querySelectorAll('input')];
   sourceInputs.forEach((source, index) => {
@@ -1564,6 +1650,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.27",
+  "version": "0.6.29",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {