@pygmalionjs/pygmalion 0.6.0 → 0.6.2

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) => {

package/node/inspect-plugin.mjs

@@ -45,8 +45,20 @@ const INTERNAL_SOURCE_ATTRIBUTES = new Set([
   'data-pygmalion-slot-count',
   'data-pygmalion-own-source',
   'data-pygmalion-own-props',
+  'data-pygmalion-pseudo-events',
 ]);
 
+const HOVER_EVENT_ATTRIBUTES = new Set([
+  'onMouseEnter',
+  'onMouseOver',
+  'onMouseMove',
+  'onPointerEnter',
+  'onPointerOver',
+  'onPointerMove',
+]);
+
+const FOCUS_EVENT_ATTRIBUTES = new Set(['onFocus']);
+
 function primitiveJsxAttributeValue(attribute, sourceFile) {
   if (!attribute.initializer) return true;
   if (ts.isStringLiteral(attribute.initializer)) return attribute.initializer.text;
@@ -144,6 +156,31 @@ function instrumentJsxInto(code, componentFile, magic) {
             : 0;
         injected.push(` data-pygmalion-slot-count="${slotCount}"`);
       }
+      if (
+        /^[a-z]/.test(elementName) &&
+        !authoredAttributes.has('data-pygmalion-pseudo-events')
+      ) {
+        const pseudoEvents = [];
+        if (
+          [...authoredAttributes].some((name) =>
+            HOVER_EVENT_ATTRIBUTES.has(name),
+          )
+        ) {
+          pseudoEvents.push('hover');
+        }
+        if (
+          [...authoredAttributes].some((name) =>
+            FOCUS_EVENT_ATTRIBUTES.has(name),
+          )
+        ) {
+          pseudoEvents.push('focus');
+        }
+        if (pseudoEvents.length > 0) {
+          injected.push(
+            ` data-pygmalion-pseudo-events="${pseudoEvents.join(',')}"`,
+          );
+        }
+      }
       if (injected.length > 0) {
         // Insert as first properties. Afterwards, if there are spread/explicit properties, they follow React's general property priority.
         magic.appendLeft(node.tagName.getEnd(), injected.join(''));

package/node/storyboard-canonical.mjs

@@ -10,7 +10,7 @@ const AUTO_ID_PATTERN =
 const TRANSIENT_ATTRIBUTE_PATTERN =
   /\s(?:data-pygmalion-source|data-pygmalion-slot-count|data-vite-dev-id|data-reactid|data-reactroot|nonce)=(?:"[^"]*"|'[^']*')/gi;
 const FROZEN_STYLE_PATTERN =
-  /<style(?:\s[^>]*)?>\s*\*,\*::before,\*::after\{animation:none!important;transition:none!important;caret-color:transparent!important\}html,body\{pointer-events:none!important\}\s*<\/style>/gi;
+  /<style(?:\s[^>]*)?>\s*\*,\*::before,\*::after\{(?:animation:none|animation-play-state:paused)!important;transition:none!important;caret-color:transparent!important\}(?:html,body\{pointer-events:none!important\})?\s*<\/style>/gi;
 
 function safeSnapshot(snapshot) {
   if (

package/node/storyboard-capture-runtime.mjs

@@ -1,10 +1,12 @@
 import { createHash } from 'node:crypto';
+import { annotateStoryboardAutomaticMotionTargets } from './automatic-motion-runtime.mjs';
+import { annotateStoryboardAutomaticPseudoStates } from './automatic-pseudo-runtime.mjs';
 
 const DEFAULT_VIEWPORT = Object.freeze({ width: 1280, height: 800 });
 const QA_FAILURE_STAGES = new Set(['interaction', 'assertion']);
 const STORYBOARD_ENVIRONMENT_QUERY = '__pygmalion_environment';
 const FROZEN_STYLE =
-  '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}';
+  '*,*::before,*::after{animation-play-state:paused!important;transition:none!important;caret-color:transparent!important}';
 const DOM_STABLE_ATTRIBUTES = new Set([
   'type',
   'name',
@@ -92,6 +94,27 @@ function throwIfAborted(signal) {
   }
 }
 
+function resetStoryboardAnimations() {
+  for (const animation of document.getAnimations?.({ subtree: true }) ?? []) {
+    try {
+      animation.pause();
+      animation.currentTime = 0;
+    } catch {
+      // An animation owned by an unavailable timeline remains CSS-paused.
+    }
+  }
+}
+
+async function freezeStoryboardMotion(page, addStyle = true) {
+  if (addStyle) {
+    const style = await page.addStyleTag({ content: FROZEN_STYLE });
+    await style?.evaluate?.((element) => {
+      element.setAttribute('data-pygmalion-preview', 'frozen');
+    });
+  }
+  await page.evaluate(resetStoryboardAnimations);
+}
+
 async function atCaptureStage(stage, task, details = {}) {
   try {
     return await task();
@@ -1185,7 +1208,7 @@ export function serializeStoryboardPreviewDocument(
   const frozenStyle = document.createElement('style');
   frozenStyle.setAttribute('data-pygmalion-preview', 'frozen');
   frozenStyle.textContent =
-    '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}html,body{pointer-events:none!important}';
+    '*,*::before,*::after{animation-play-state:paused!important;transition:none!important;caret-color:transparent!important}html,body{pointer-events:none!important}';
   head.append(frozenStyle);
 
   return `<!doctype html>${clone.outerHTML}`;
@@ -1242,7 +1265,7 @@ async function collectStableEvidence(
   const evidence = {};
   const errors = [];
   try {
-    if (!frozenStyleApplied) await page.addStyleTag({ content: FROZEN_STYLE });
+    if (!frozenStyleApplied) await freezeStoryboardMotion(page);
     if (!alreadyStable) {
       const stable = await waitForStableStoryboardDocument(page, stability);
       if (!stable) {
@@ -1252,6 +1275,14 @@ async function collectStableEvidence(
   } catch (error) {
     errors.push(new StoryboardCaptureStageError('stabilize', error));
   }
+  if (includePreviewSnapshot || includeDomTree) {
+    try {
+      await page.evaluate(annotateStoryboardAutomaticPseudoStates);
+      await page.evaluate(annotateStoryboardAutomaticMotionTargets);
+    } catch (error) {
+      errors.push(new StoryboardCaptureStageError('serialize', error));
+    }
+  }
   if (includeDomTree) {
     try {
       evidence.domTree = await page.evaluate(collectStoryboardDomTree);
@@ -1483,10 +1514,8 @@ export async function captureStoryboardCase({
       );
     }
     await atCaptureStage('stabilize', async () => {
-      if (!session?.frozen) {
-        await page.addStyleTag({ content: FROZEN_STYLE });
-        if (session) session.frozen = true;
-      }
+      await freezeStoryboardMotion(page, !session?.frozen);
+      if (session) session.frozen = true;
       frozenStyleApplied = true;
       const stable = await waitForStableStoryboardDocument(page, stability);
       if (!stable) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -34,6 +34,8 @@
     "dist-lib",
     "docs/screen-state-contract.md",
     "node/component-branches.mjs",
+    "node/automatic-motion-runtime.mjs",
+    "node/automatic-pseudo-runtime.mjs",
     "node/design-session.mjs",
     "node/dev-mirror.mjs",
     "node/dev-view.vite.mjs",