@pygmalionjs/pygmalion 0.6.1 → 0.6.2

package/node/automatic-motion-runtime.mjs

@@ -0,0 +1,279 @@
+/**
+ * Annotates visible CSS and Web Animation targets in the running capture page.
+ *
+ * This function is intentionally self-contained because Playwright serializes
+ * it into the browser realm. Keep its metadata contract and discovery behavior
+ * aligned with src/editor/automaticMotion.ts.
+ */
+export function annotateStoryboardAutomaticMotionTargets() {
+  const metadataAttribute = 'data-pygmalion-auto-motion';
+  const ledgerAttribute = 'data-pygmalion-auto-motions';
+  const declarationAttribute = 'data-pygmalion-motion';
+  const motionPseudoPattern =
+    /:(focus-visible|focus-within|hover|focus|active)(?![a-z0-9_-])/gi;
+  const normalizeText = (value) =>
+    String(value ?? '')
+      .replace(/\s+/g, ' ')
+      .trim();
+  const compactLabel = (value) => {
+    const normalized = normalizeText(value);
+    return normalized.length <= 52
+      ? normalized
+      : `${normalized.slice(0, 49).trimEnd()}…`;
+  };
+  const attributeSelector = (name, value) => {
+    const escaped = String(value)
+      .replaceAll('\\', '\\\\')
+      .replaceAll('"', '\\"')
+      .replaceAll('\n', '\\a ')
+      .replaceAll('\r', '\\d ');
+    return `[${name}="${escaped}"]`;
+  };
+  const splitSelectorList = (selectorText) => {
+    const selectors = [];
+    let start = 0;
+    let round = 0;
+    let square = 0;
+    let quote = '';
+    for (let index = 0; index < selectorText.length; index += 1) {
+      const character = selectorText[index];
+      if (quote) {
+        if (character === '\\') index += 1;
+        else if (character === quote) quote = '';
+        continue;
+      }
+      if (character === '"' || character === "'") {
+        quote = character;
+        continue;
+      }
+      if (character === '(') round += 1;
+      else if (character === ')') round = Math.max(0, round - 1);
+      else if (character === '[') square += 1;
+      else if (character === ']') square = Math.max(0, square - 1);
+      else if (character === ',' && round === 0 && square === 0) {
+        selectors.push(selectorText.slice(start, index).trim());
+        start = index + 1;
+      }
+    }
+    selectors.push(selectorText.slice(start).trim());
+    return selectors.filter(Boolean);
+  };
+  const visibleElement = (element) => {
+    let style;
+    try {
+      style = getComputedStyle(element);
+    } catch {
+      return false;
+    }
+    if (
+      style.display === 'none' ||
+      style.visibility === 'hidden' ||
+      style.visibility === 'collapse'
+    ) {
+      return false;
+    }
+    const rect = element.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  };
+  const computedStyleCarriesMotion = (style) => {
+    const names = String(style.animationName ?? '').trim();
+    if (names) {
+      return names
+        .split(',')
+        .some((name) => name.trim().toLowerCase() !== 'none');
+    }
+    const shorthand = String(style.animation ?? '').trim();
+    return Boolean(shorthand && shorthand.toLowerCase() !== 'none');
+  };
+  const computedMotionCandidate = (element) => {
+    try {
+      if (computedStyleCarriesMotion(getComputedStyle(element))) return true;
+      return ['::before', '::after'].some((pseudo) =>
+        computedStyleCarriesMotion(getComputedStyle(element, pseudo)),
+      );
+    } catch {
+      return false;
+    }
+  };
+  const declarationCarriesMotion = (style) => {
+    const names = String(style.getPropertyValue('animation-name') ?? '').trim();
+    if (
+      names &&
+      names.split(',').some((name) => name.trim().toLowerCase() !== 'none')
+    ) {
+      return true;
+    }
+    const shorthand = String(style.getPropertyValue('animation') ?? '').trim();
+    return Boolean(shorthand && shorthand.toLowerCase() !== 'none');
+  };
+  const motionSubjectSelector = (selector) => {
+    const subject = selector
+      .replace(/::[a-z0-9_-]+(?:\([^)]*\))?/gi, '')
+      .replace(
+        /:not\(\s*:(focus-visible|focus-within|hover|focus|active)\s*\)/gi,
+        '',
+      )
+      .replace(motionPseudoPattern, '')
+      .replace(/:(?:is|where|not|has)\(\s*(?:,\s*)*\)/gi, '')
+      .trim();
+    motionPseudoPattern.lastIndex = 0;
+    return subject || null;
+  };
+  const candidates = new Set();
+  const elements = [...document.querySelectorAll('*')];
+  for (const element of elements) {
+    if (!visibleElement(element)) continue;
+    if (
+      element.hasAttribute(declarationAttribute) ||
+      computedMotionCandidate(element)
+    ) {
+      candidates.add(element);
+    }
+  }
+  const inspectRules = (rules) => {
+    for (const rule of [...rules]) {
+      if (
+        typeof rule.selectorText === 'string' &&
+        rule.style &&
+        declarationCarriesMotion(rule.style)
+      ) {
+        for (const selector of splitSelectorList(rule.selectorText)) {
+          const subject = motionSubjectSelector(selector);
+          if (!subject) continue;
+          try {
+            for (const element of document.querySelectorAll(subject)) {
+              if (visibleElement(element)) candidates.add(element);
+            }
+          } catch {
+            // Continue through selectors the current engine can query.
+          }
+        }
+      }
+      if (rule.cssRules) inspectRules(rule.cssRules);
+    }
+  };
+  for (const sheet of [...document.styleSheets]) {
+    try {
+      inspectRules(sheet.cssRules);
+    } catch {
+      // Cross-origin stylesheets cannot expose their rules.
+    }
+  }
+  try {
+    for (const animation of document.getAnimations?.({ subtree: true }) ?? []) {
+      const target = animation.effect?.target;
+      if (target?.nodeType === 1 && visibleElement(target)) {
+        candidates.add(target);
+      }
+    }
+  } catch {
+    // CSS discovery remains available without getAnimations.
+  }
+  const selectorForElement = (element) => {
+    if (element === document.documentElement) {
+      return { selector: 'html', index: 0 };
+    }
+    if (element === document.body) return { selector: 'body', index: 0 };
+    for (const name of [
+      'data-testid',
+      'data-pygmalion-own-source',
+      'data-pygmalion-source',
+      'id',
+    ]) {
+      const value = element.getAttribute(name);
+      if (!value) continue;
+      const selector = attributeSelector(name, value);
+      try {
+        const matches = [...document.querySelectorAll(selector)];
+        const index = matches.indexOf(element);
+        if (index >= 0) return { selector, index };
+      } catch {
+        // Try the next identity source.
+      }
+    }
+    const segments = [];
+    let current = element;
+    while (current && current !== document.body) {
+      const parent = current.parentElement;
+      if (!parent) return null;
+      const tag = current.tagName.toLowerCase();
+      const siblings = [...parent.children].filter(
+        (candidate) => candidate.tagName === current.tagName,
+      );
+      segments.unshift(
+        `${tag}:nth-of-type(${siblings.indexOf(current) + 1})`,
+      );
+      current = parent;
+    }
+    return current && segments.length > 0
+      ? { selector: `body > ${segments.join(' > ')}`, index: 0 }
+      : null;
+  };
+  const targetLabel = (element) => {
+    const descendantLabel = element
+      .querySelector('[aria-label]')
+      ?.getAttribute('aria-label');
+    const ancestorLabel = element.parentElement
+      ?.closest('[aria-label]')
+      ?.getAttribute('aria-label');
+    const sourceName = element
+      .getAttribute('data-pygmalion-source-style')
+      ?.split('#')
+      .at(-1);
+    return compactLabel(
+      element.getAttribute('aria-label') ||
+        element.getAttribute('title') ||
+        descendantLabel ||
+        ancestorLabel ||
+        element.getAttribute('data-testid') ||
+        normalizeText(element.textContent) ||
+        sourceName ||
+        element.getAttribute('role') ||
+        element.tagName.toLowerCase(),
+    );
+  };
+  const stableId = (value) => {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < value.length; index += 1) {
+      hash ^= value.charCodeAt(index);
+      hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(36);
+  };
+  const order = new Map(elements.map((element, index) => [element, index]));
+  const pending = [...candidates]
+    .flatMap((element) => {
+      const identity = selectorForElement(element);
+      return identity
+        ? [{ element, identity, baseLabel: targetLabel(element) }]
+        : [];
+    })
+    .sort(
+      (left, right) =>
+        (order.get(left.element) ?? Number.MAX_SAFE_INTEGER) -
+        (order.get(right.element) ?? Number.MAX_SAFE_INTEGER),
+    );
+  const totals = new Map();
+  for (const entry of pending) {
+    totals.set(entry.baseLabel, (totals.get(entry.baseLabel) ?? 0) + 1);
+  }
+  const seen = new Map();
+  const targets = pending.map(({ element, identity, baseLabel }) => {
+    const ordinal = (seen.get(baseLabel) ?? 0) + 1;
+    seen.set(baseLabel, ordinal);
+    const total = totals.get(baseLabel) ?? 1;
+    const label =
+      total > 1 ? `${baseLabel} · ${ordinal}/${total}` : baseLabel;
+    const key = `${identity.selector}\u0000${identity.index}`;
+    const target = {
+      id: `auto-motion:${stableId(key)}`,
+      label,
+      selector: identity.selector,
+      index: identity.index,
+    };
+    element.setAttribute(metadataAttribute, JSON.stringify(target));
+    return target;
+  });
+  document.body?.setAttribute(ledgerAttribute, JSON.stringify(targets));
+  return targets;
+}

package/node/automatic-pseudo-runtime.mjs

@@ -7,6 +7,7 @@
  */
 export function annotateStoryboardAutomaticPseudoStates() {
   const metadataAttribute = 'data-pygmalion-auto-pseudo';
+  const ledgerAttribute = 'data-pygmalion-auto-pseudos';
   const eventAttribute = 'data-pygmalion-pseudo-events';
   const stateOrder = ['hover', 'focus-visible', 'active'];
   const pseudoPattern =
@@ -277,6 +278,10 @@ export function annotateStoryboardAutomaticPseudoStates() {
     if (states.size > 0) found.set(element, states);
   }
   const selectorForElement = (element) => {
+    if (element === document.documentElement) {
+      return { selector: 'html', index: 0 };
+    }
+    if (element === document.body) return { selector: 'body', index: 0 };
     for (const name of [
       'data-testid',
       'data-pygmalion-own-source',
@@ -356,7 +361,7 @@ export function annotateStoryboardAutomaticPseudoStates() {
     totals.set(entry.baseLabel, (totals.get(entry.baseLabel) ?? 0) + 1);
   }
   const seen = new Map();
-  return pending.map(({ element, identity, baseLabel, states }) => {
+  const targets = pending.map(({ element, identity, baseLabel, states }) => {
     const ordinal = (seen.get(baseLabel) ?? 0) + 1;
     seen.set(baseLabel, ordinal);
     const total = totals.get(baseLabel) ?? 1;
@@ -373,4 +378,6 @@ export function annotateStoryboardAutomaticPseudoStates() {
     element.setAttribute(metadataAttribute, JSON.stringify(target));
     return target;
   });
+  document.body?.setAttribute(ledgerAttribute, JSON.stringify(targets));
+  return targets;
 }

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/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,11 +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',
@@ -93,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();
@@ -1186,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}`;
@@ -1243,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) {
@@ -1253,9 +1275,10 @@ async function collectStableEvidence(
   } catch (error) {
     errors.push(new StoryboardCaptureStageError('stabilize', error));
   }
-  if (includePreviewSnapshot) {
+  if (includePreviewSnapshot || includeDomTree) {
     try {
       await page.evaluate(annotateStoryboardAutomaticPseudoStates);
+      await page.evaluate(annotateStoryboardAutomaticMotionTargets);
     } catch (error) {
       errors.push(new StoryboardCaptureStageError('serialize', error));
     }
@@ -1491,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.1",
+  "version": "0.6.2",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -34,6 +34,7 @@
     "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",