@pygmalionjs/pygmalion 0.5.34 → 0.6.1

package/node/automatic-pseudo-runtime.mjs

@@ -0,0 +1,376 @@
+/**
+ * Annotates visible pseudo-state targets in the running capture page.
+ *
+ * The function is intentionally self-contained: Playwright serializes it into
+ * the browser realm. Keep its metadata schema and discovery behavior aligned
+ * with src/editor/automaticPseudoStates.ts.
+ */
+export function annotateStoryboardAutomaticPseudoStates() {
+  const metadataAttribute = 'data-pygmalion-auto-pseudo';
+  const eventAttribute = 'data-pygmalion-pseudo-events';
+  const stateOrder = ['hover', 'focus-visible', 'active'];
+  const pseudoPattern =
+    /:(focus-visible|focus-within|hover|focus|active)(?![a-z0-9_-])/gi;
+  const focusableSelector = [
+    'button:not(:disabled)',
+    'a[href]',
+    'input:not(:disabled)',
+    'textarea:not(:disabled)',
+    'select:not(:disabled)',
+    'summary',
+    'area[href]',
+    'audio[controls]',
+    'video[controls]',
+    'iframe',
+    '[contenteditable]:not([contenteditable="false"])',
+    '[tabindex]:not(:disabled)',
+  ].join(',');
+  const hoverReactEventProps = [
+    'onMouseEnter',
+    'onMouseOver',
+    'onMouseMove',
+    'onPointerEnter',
+    'onPointerOver',
+    'onPointerMove',
+  ];
+  const focusReactEventProps = ['onFocus', 'onFocusCapture'];
+
+  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 focusTarget = (element) => {
+    try {
+      if (element.matches(focusableSelector) && visibleElement(element)) {
+        return element;
+      }
+      return (
+        [...element.querySelectorAll(focusableSelector)].find(visibleElement) ??
+        null
+      );
+    } catch {
+      return null;
+    }
+  };
+  const normalizedNegatedPseudo = (selector) =>
+    selector.replace(
+      /:not\(\s*:(focus-visible|focus-within|hover|focus|active)\s*\)/gi,
+      (_match, state) => `:${state}`,
+    );
+  const compoundEndAfter = (selector, start) => {
+    let round = 0;
+    let square = 0;
+    let quote = '';
+    for (let index = 0; index < selector.length; index += 1) {
+      const character = selector[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);
+      if (
+        index >= start &&
+        round === 0 &&
+        square === 0 &&
+        (character === '>' ||
+          character === '+' ||
+          character === '~' ||
+          /\s/.test(character))
+      ) {
+        return index;
+      }
+    }
+    return selector.length;
+  };
+  const pseudoSubjectSelector = (selectorText, pseudo) => {
+    const selector = normalizedNegatedPseudo(selectorText);
+    pseudoPattern.lastIndex = 0;
+    const matches = [...selector.matchAll(pseudoPattern)].filter((match) => {
+      const state = match[1].toLowerCase();
+      return pseudo === 'focus-visible'
+        ? state === 'focus' ||
+            state === 'focus-visible' ||
+            state === 'focus-within'
+        : state === pseudo;
+    });
+    pseudoPattern.lastIndex = 0;
+    const match = matches.at(-1);
+    if (!match || match.index == null) return null;
+    const end = compoundEndAfter(selector, match.index + match[0].length);
+    const prefix = selector
+      .slice(0, end)
+      .replace(pseudoPattern, '')
+      .replace(/::[a-z0-9_-]+(?:\([^)]*\))?/gi, '')
+      .replace(/:(?:is|where|not)\(\s*(?:,\s*)*\)/gi, '')
+      .trim();
+    pseudoPattern.lastIndex = 0;
+    return prefix || null;
+  };
+  const activeGroupingRule = (rule) => {
+    if (rule.type === CSSRule.MEDIA_RULE) {
+      return !rule.conditionText || matchMedia(rule.conditionText).matches;
+    }
+    if (rule.type === CSSRule.SUPPORTS_RULE) {
+      try {
+        return !rule.conditionText || CSS.supports(rule.conditionText);
+      } catch {
+        return true;
+      }
+    }
+    return true;
+  };
+  const found = new Map();
+  const add = (element, state) => {
+    if (!visibleElement(element)) return;
+    const states = found.get(element) ?? new Set();
+    states.add(state);
+    found.set(element, states);
+  };
+  const inspectRules = (rules) => {
+    for (const rule of [...rules]) {
+      const selectorText = rule.selectorText;
+      pseudoPattern.lastIndex = 0;
+      const carriesPseudo =
+        typeof selectorText === 'string' && pseudoPattern.test(selectorText);
+      pseudoPattern.lastIndex = 0;
+      if (carriesPseudo) {
+        for (const selector of splitSelectorList(selectorText)) {
+          const rawStates = new Set(
+            [...selector.matchAll(pseudoPattern)].map((match) =>
+              match[1].toLowerCase(),
+            ),
+          );
+          pseudoPattern.lastIndex = 0;
+          const states = [];
+          if (rawStates.has('hover')) states.push('hover');
+          if (
+            rawStates.has('focus') ||
+            rawStates.has('focus-visible') ||
+            rawStates.has('focus-within')
+          ) {
+            states.push('focus-visible');
+          }
+          if (rawStates.has('active')) states.push('active');
+          for (const state of states) {
+            const subjectSelector = pseudoSubjectSelector(selector, state);
+            if (!subjectSelector) continue;
+            let subjects;
+            try {
+              subjects = [...document.querySelectorAll(subjectSelector)];
+            } catch {
+              continue;
+            }
+            for (const subject of subjects) {
+              if (state === 'focus-visible') {
+                const target = focusTarget(subject);
+                if (target) add(target, state);
+              } else {
+                add(subject, state);
+              }
+            }
+          }
+        }
+      }
+      if (rule.cssRules && activeGroupingRule(rule)) {
+        inspectRules(rule.cssRules);
+      }
+    }
+  };
+  for (const sheet of [...document.styleSheets]) {
+    try {
+      inspectRules(sheet.cssRules);
+    } catch {
+      // Cross-origin stylesheets cannot be inspected.
+    }
+  }
+  for (const element of document.querySelectorAll('*')) {
+    if (!visibleElement(element)) continue;
+    const declared = new Set(
+      String(element.getAttribute(eventAttribute) ?? '')
+        .split(',')
+        .map((value) => value.trim()),
+    );
+    for (const key of Object.getOwnPropertyNames(element)) {
+      if (!key.startsWith('__reactProps$')) continue;
+      const props = element[key];
+      if (!props || typeof props !== 'object') continue;
+      if (hoverReactEventProps.some((name) => typeof props[name] === 'function')) {
+        declared.add('hover');
+      }
+      if (focusReactEventProps.some((name) => typeof props[name] === 'function')) {
+        declared.add('focus');
+      }
+    }
+    const states = found.get(element) ?? new Set();
+    if (declared.has('hover')) states.add('hover');
+    if (declared.has('focus') && focusTarget(element) === element) {
+      states.add('focus-visible');
+    }
+    if (states.size > 0) found.set(element, states);
+  }
+  const selectorForElement = (element) => {
+    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 sourceName = element
+      .getAttribute('data-pygmalion-source-style')
+      ?.split('#')
+      .at(-1);
+    return compactLabel(
+      element.getAttribute('aria-label') ||
+        element.getAttribute('title') ||
+        descendantLabel ||
+        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 pending = [...found].flatMap(([element, states]) => {
+    const identity = selectorForElement(element);
+    if (!identity) return [];
+    return [
+      {
+        element,
+        identity,
+        baseLabel: targetLabel(element),
+        states: stateOrder.filter((state) => states.has(state)),
+      },
+    ];
+  });
+  const totals = new Map();
+  for (const entry of pending) {
+    totals.set(entry.baseLabel, (totals.get(entry.baseLabel) ?? 0) + 1);
+  }
+  const seen = new Map();
+  return pending.map(({ element, identity, baseLabel, states }) => {
+    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-pseudo:${stableId(key)}`,
+      label,
+      selector: identity.selector,
+      index: identity.index,
+      states,
+    };
+    element.setAttribute(metadataAttribute, JSON.stringify(target));
+    return target;
+  });
+}

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-capture-runtime.mjs

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { annotateStoryboardAutomaticPseudoStates } from './automatic-pseudo-runtime.mjs';
 
 const DEFAULT_VIEWPORT = Object.freeze({ width: 1280, height: 800 });
 const QA_FAILURE_STAGES = new Set(['interaction', 'assertion']);
@@ -381,6 +382,13 @@ export async function runStoryboardInteraction(page, interaction) {
       await target.click({ timeout: timeoutMs });
     } else if (interaction.action === 'focus') {
       await target.focus({ timeout: timeoutMs });
+    } else if (interaction.action === 'hover') {
+      await target.hover({ timeout: timeoutMs });
+    } else if (interaction.action === 'focus-visible') {
+      await target.focus({ timeout: timeoutMs });
+    } else if (interaction.action === 'active') {
+      await target.hover({ timeout: timeoutMs });
+      await page.mouse.down();
     } else if (interaction.action === 'fill') {
       await target.fill(interaction.value ?? '', { timeout: timeoutMs });
     } else if (interaction.action === 'check') {
@@ -1245,6 +1253,13 @@ async function collectStableEvidence(
   } catch (error) {
     errors.push(new StoryboardCaptureStageError('stabilize', error));
   }
+  if (includePreviewSnapshot) {
+    try {
+      await page.evaluate(annotateStoryboardAutomaticPseudoStates);
+    } catch (error) {
+      errors.push(new StoryboardCaptureStageError('serialize', error));
+    }
+  }
   if (includeDomTree) {
     try {
       evidence.domTree = await page.evaluate(collectStoryboardDomTree);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.5.34",
+  "version": "0.6.1",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -32,7 +32,9 @@
   },
   "files": [
     "dist-lib",
+    "docs/screen-state-contract.md",
     "node/component-branches.mjs",
+    "node/automatic-pseudo-runtime.mjs",
     "node/design-session.mjs",
     "node/dev-mirror.mjs",
     "node/dev-view.vite.mjs",