@pygmalionjs/pygmalion 0.6.27 → 0.6.28

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.27",
+  "version": "0.6.28",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {