@pygmalionjs/pygmalion 0.6.1 → 0.6.3

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/preview-artifact-plugin.mjs

@@ -8,6 +8,7 @@ import { createPreviewArtifactStore } from './preview-artifact-store.mjs';
 
 export const PYGMALION_PREVIEW_ARTIFACT_ENDPOINT =
   '/__pygmalion-route-preview/artifact';
+export const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX = '/progress';
 export const DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE =
   'artifacts/pygmalion-route-previews.json';
 
@@ -33,6 +34,17 @@ export const PREVIEW_CAPTURE_PRIORITY = Object.freeze({
 });
 const DEFAULT_CAPTURE_PRIORITY = PREVIEW_CAPTURE_PRIORITY.canvas;
 const MAX_CAPTURE_PRIORITY = 1_000;
+const CAPTURE_PROGRESS_PHASES = new Set([
+  'queued',
+  'preparing',
+  'capturing',
+  'retrying',
+  'finalizing',
+]);
+
+function captureProgressEndpoint(endpoint) {
+  return `${endpoint.replace(/\/$/, '')}${PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX}`;
+}
 
 function isLocalRequestHost(value) {
   const raw = Array.isArray(value) ? value[0] : value;
@@ -287,6 +299,7 @@ export function pygmalionPreviewArtifactPlugin({
       'Preview artifact runtime readiness option must be a function.',
     );
   }
+  const progressEndpoint = captureProgressEndpoint(endpoint);
 
   const artifactStore = createPreviewArtifactStore({
     artifactFile: resolvedArtifact,
@@ -299,6 +312,103 @@ export function pygmalionPreviewArtifactPlugin({
   });
   const identityQueues = new Map();
   const inFlightRequests = new Map();
+  const captureJobs = new Map();
+  let captureJobCounter = 0;
+
+  function readCaptureProgress() {
+    const jobs = [...captureJobs.values()];
+    if (jobs.length === 0) {
+      return {
+        active: false,
+        phase: 'idle',
+        completed: 0,
+        total: 0,
+        jobCount: 0,
+      };
+    }
+    const phases = new Set(jobs.map((job) => job.phase));
+    const phase = phases.has('capturing')
+      ? 'capturing'
+      : phases.has('retrying')
+        ? 'retrying'
+        : phases.has('finalizing')
+          ? 'finalizing'
+          : phases.has('preparing')
+            ? 'preparing'
+            : 'queued';
+    const latest = jobs.reduce((left, right) =>
+      left.updatedAt >= right.updatedAt ? left : right,
+    );
+    return {
+      active: true,
+      phase,
+      completed: jobs.reduce((sum, job) => sum + job.completed, 0),
+      total: jobs.reduce((sum, job) => sum + job.total, 0),
+      jobCount: jobs.length,
+      ...(latest.frameId ? { frameId: latest.frameId } : {}),
+      ...(latest.captureStatus
+        ? { captureStatus: latest.captureStatus }
+        : {}),
+      updatedAt: latest.updatedAt,
+    };
+  }
+
+  function startCaptureProgress(expectedTotal = 0) {
+    captureJobCounter += 1;
+    const id = `preview-capture-${captureJobCounter}`;
+    const job = {
+      phase: 'preparing',
+      completed: 0,
+      total:
+        Number.isInteger(expectedTotal) && expectedTotal >= 0
+          ? expectedTotal
+          : 0,
+      updatedAt: Date.now(),
+    };
+    captureJobs.set(id, job);
+    return {
+      update(progress) {
+        if (!progress || typeof progress !== 'object') return;
+        if (
+          progress.phase != null &&
+          !CAPTURE_PROGRESS_PHASES.has(progress.phase)
+        ) {
+          return;
+        }
+        const completed = Number(progress.completed ?? job.completed);
+        const total = Number(progress.total ?? job.total);
+        if (
+          !Number.isInteger(completed) ||
+          !Number.isInteger(total) ||
+          completed < 0 ||
+          total < 0 ||
+          completed > total
+        ) {
+          return;
+        }
+        job.phase = progress.phase ?? job.phase;
+        job.completed = completed;
+        job.total = total;
+        job.frameId =
+          typeof progress.frameId === 'string' && progress.frameId.trim()
+            ? progress.frameId.trim()
+            : undefined;
+        job.captureStatus =
+          typeof progress.captureStatus === 'string' &&
+          progress.captureStatus.trim()
+            ? progress.captureStatus.trim()
+            : undefined;
+        job.updatedAt = Date.now();
+      },
+      finalizing() {
+        job.phase = 'finalizing';
+        job.updatedAt = Date.now();
+      },
+      finish() {
+        captureJobs.delete(id);
+      },
+    };
+  }
 
   /**
    * Captures on one identity run one at a time — they share the checkout and
@@ -446,27 +556,36 @@ export function pygmalionPreviewArtifactPlugin({
           sourceRevision,
         );
         if (existing) return existing;
-        const generated = await withCaptureLease(sourceRevision, () =>
-          generateArtifact({
-            namespace,
-            sourceRevision,
-            ...(captureBaseUrl ? { captureBaseUrl } : {}),
-          }),
-        );
-        const validation = validateRoutePreviewArtifactBundle(generated);
-        if (!validation.valid) {
-          throw badGeneratorOutput('Generated preview artifact is invalid.');
-        }
-        if (!exactArtifact(generated, namespace, sourceRevision)) {
-          throw badGeneratorOutput(
-            'Generated preview artifact identity does not match the request.',
+        const progress = startCaptureProgress();
+        try {
+          const generated = await withCaptureLease(sourceRevision, () =>
+            generateArtifact(
+              {
+                namespace,
+                sourceRevision,
+                ...(captureBaseUrl ? { captureBaseUrl } : {}),
+              },
+              { onProgress: progress.update },
+            ),
           );
+          const validation = validateRoutePreviewArtifactBundle(generated);
+          if (!validation.valid) {
+            throw badGeneratorOutput('Generated preview artifact is invalid.');
+          }
+          if (!exactArtifact(generated, namespace, sourceRevision)) {
+            throw badGeneratorOutput(
+              'Generated preview artifact identity does not match the request.',
+            );
+          }
+          progress.finalizing();
+          await artifactStore.publishArtifact(generated, {
+            sourceRevision,
+            recordRevision: true,
+          });
+          return generated;
+        } finally {
+          progress.finish();
         }
-        await artifactStore.publishArtifact(generated, {
-          sourceRevision,
-          recordRevision: true,
-        });
-        return generated;
       }),
     );
   }
@@ -494,39 +613,47 @@ export function pygmalionPreviewArtifactPlugin({
         const absent = new Set([...before.missing, ...before.stale]);
         const remaining = wanted.filter((frame) => absent.has(frame.id));
         if (remaining.length === 0) return before;
-
-        const generated = await withCaptureLease(sourceRevision, () =>
-          generateArtifact({
-            namespace,
+        const progress = startCaptureProgress(remaining.length);
+        try {
+          const generated = await withCaptureLease(sourceRevision, () =>
+            generateArtifact(
+              {
+                namespace,
+                sourceRevision,
+                frames: remaining,
+                ...(captureBaseUrl ? { captureBaseUrl } : {}),
+              },
+              { onProgress: progress.update },
+            ),
+          );
+          const validation = validateRoutePreviewArtifactBundle(generated);
+          if (!validation.valid || generated.version !== 3) {
+            throw new Error('Generated preview artifact is invalid.');
+          }
+          if (!exactArtifact(generated, namespace, sourceRevision)) {
+            throw new Error(
+              'Generated preview artifact identity does not match the request.',
+            );
+          }
+          progress.finalizing();
+          await artifactStore.publishArtifact(generated, {
             sourceRevision,
-            frames: remaining,
-            ...(captureBaseUrl ? { captureBaseUrl } : {}),
-          }),
-        );
-        const validation = validateRoutePreviewArtifactBundle(generated);
-        if (!validation.valid || generated.version !== 3) {
-          throw new Error('Generated preview artifact is invalid.');
-        }
-        if (!exactArtifact(generated, namespace, sourceRevision)) {
-          throw new Error(
-            'Generated preview artifact identity does not match the request.',
+            recordRevision: false,
+          });
+          // Retention is allowed to decline a newly generated object when older
+          // entries have earned higher read recency. That cache decision must not
+          // discard the result from the request that just paid to generate it.
+          const responseArtifact = mergeRoutePreviewArtifactV3(
+            before.bundle,
+            generated,
           );
+          return selectRoutePreviewArtifactFrames(responseArtifact, wanted, {
+            includeStale: true,
+            sourceRevision,
+          });
+        } finally {
+          progress.finish();
         }
-        await artifactStore.publishArtifact(generated, {
-          sourceRevision,
-          recordRevision: false,
-        });
-        // Retention is allowed to decline a newly generated object when older
-        // entries have earned higher read recency. That cache decision must not
-        // discard the result from the request that just paid to generate it.
-        const responseArtifact = mergeRoutePreviewArtifactV3(
-          before.bundle,
-          generated,
-        );
-        return selectRoutePreviewArtifactFrames(responseArtifact, wanted, {
-          includeStale: true,
-          sourceRevision,
-        });
       }, priority),
     );
   }
@@ -542,6 +669,28 @@ export function pygmalionPreviewArtifactPlugin({
       void artifactStore.applyRetention?.(undefined)?.catch?.(() => undefined);
       server.middlewares.use(async (request, response, next) => {
         const url = new URL(request.url ?? '/', 'http://localhost');
+        if (url.pathname === progressEndpoint) {
+          if (request.method !== 'GET') {
+            response.setHeader('allow', 'GET');
+            sendJson(response, 405, {
+              ok: false,
+              error: 'method_not_allowed',
+            });
+            return;
+          }
+          if (!isLocalRequestHost(request.headers.host)) {
+            sendJson(response, 403, {
+              ok: false,
+              error: 'local_host_required',
+            });
+            return;
+          }
+          sendJson(response, 200, {
+            ok: true,
+            progress: readCaptureProgress(),
+          });
+          return;
+        }
         if (url.pathname !== endpoint) {
           next();
           return;

package/node/preview-capture-worker.mjs

@@ -10,6 +10,13 @@ const DEFAULT_PING_TIMEOUT_MS = 10_000;
 const MAX_RESTART_BACKOFF_MS = 8_000;
 const STOP_KILL_GRACE_MS = 5_000;
 const STDERR_TAIL_LIMIT = 8_000;
+const PROGRESS_PHASES = new Set([
+  'queued',
+  'preparing',
+  'capturing',
+  'retrying',
+  'finalizing',
+]);
 
 function assertPositiveNumber(value, name, fallback) {
   if (value == null) return fallback;
@@ -127,6 +134,34 @@ function workerFailure(worker, fallbackMessage) {
   return new Error(tail ? `${fallbackMessage}\n${tail}` : fallbackMessage);
 }
 
+function normalizeProgressMessage(message) {
+  if (message?.type !== 'progress' || !PROGRESS_PHASES.has(message.phase)) {
+    return null;
+  }
+  const completed = Number(message.completed);
+  const total = Number(message.total);
+  if (
+    !Number.isInteger(completed) ||
+    !Number.isInteger(total) ||
+    completed < 0 ||
+    total < 0 ||
+    completed > total
+  ) {
+    return null;
+  }
+  return {
+    phase: message.phase,
+    completed,
+    total,
+    ...(typeof message.frameId === 'string' && message.frameId.trim()
+      ? { frameId: message.frameId.trim() }
+      : {}),
+    ...(typeof message.captureStatus === 'string' && message.captureStatus.trim()
+      ? { captureStatus: message.captureStatus.trim() }
+      : {}),
+  };
+}
+
 /**
  * Long-lived capture worker channel: one child process that keeps its expensive
  * boot (runtime preflight, case bundling, browser launch) warm across artifact
@@ -134,6 +169,7 @@ function workerFailure(worker, fallbackMessage) {
  *
  * Protocol: the channel writes `{ id, type: 'capture', payload }` — payload is
  * `{ namespace, sourceRevision, frames?, captureBaseUrl? }` — and the worker
+ * may emit `{ id, type: 'progress', phase, completed, total, frameId? }`, then
  * answers `{ id, ok: true, artifactFile }` with the bundle in a temp file the
  * channel reads, validates, and deletes, or `{ id, ok: false, error }`.
  * `{ id, type: 'ping' }` must be answered immediately even while booting; the
@@ -266,6 +302,17 @@ export function createPreviewCaptureWorkerChannel({
         settlePending(current, ({ resolve }) => resolve(message));
         return;
       }
+      if (message.type === 'progress') {
+        const progress = normalizeProgressMessage(message);
+        if (progress && pending.onProgress) {
+          try {
+            pending.onProgress(progress);
+          } catch {
+            // Progress observation must never fail the capture it observes.
+          }
+        }
+        return;
+      }
       if (message.ok === true) {
         settlePending(current, ({ resolve }) => resolve(message));
       } else {
@@ -324,7 +371,11 @@ export function createPreviewCaptureWorkerChannel({
     current.proc.kill('SIGKILL');
   }
 
-  function dispatch(current, message, { kind, timeoutMs, onTimeout }) {
+  function dispatch(
+    current,
+    message,
+    { kind, timeoutMs, onTimeout, onProgress },
+  ) {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         current.pending = null;
@@ -339,7 +390,14 @@ export function createPreviewCaptureWorkerChannel({
         );
       }, timeoutMs);
       timer.unref?.();
-      current.pending = { id: message.id, kind, resolve, reject, timer };
+      current.pending = {
+        id: message.id,
+        kind,
+        resolve,
+        reject,
+        timer,
+        onProgress,
+      };
       try {
         current.proc.stdin.write(`${JSON.stringify(message)}\n`);
       } catch (error) {
@@ -400,13 +458,14 @@ export function createPreviewCaptureWorkerChannel({
     return worker;
   }
 
-  function runWorkerJob(current, payload) {
+  function runWorkerJob(current, payload, onProgress) {
     return dispatch(
       current,
       { id: nextRequestId(), type: 'capture', payload },
       {
         kind: 'capture',
         timeoutMs: resolvedJobTimeoutMs,
+        onProgress,
         onTimeout: () => {
           recordCrash();
           killWorker(current);
@@ -419,7 +478,7 @@ export function createPreviewCaptureWorkerChannel({
    * Degraded path: one spawn per request with `--once`, the same protocol over
    * the child's own stdio. Slow again, but on-demand capture keeps answering.
    */
-  function runOnceJob(payload) {
+  function runOnceJob(payload, onProgress) {
     return new Promise((resolve, reject) => {
       const proc = spawn(
         process.execPath,
@@ -450,6 +509,17 @@ export function createPreviewCaptureWorkerChannel({
       const id = nextRequestId();
       attachLineParser(proc.stdout, (message) => {
         if (message.id !== id) return;
+        if (message.type === 'progress') {
+          const progress = normalizeProgressMessage(message);
+          if (progress && onProgress) {
+            try {
+              onProgress(progress);
+            } catch {
+              // Progress observation must never fail the capture it observes.
+            }
+          }
+          return;
+        }
         if (message.ok === true) {
           settle(() => resolve(message));
         } else {
@@ -493,10 +563,13 @@ export function createPreviewCaptureWorkerChannel({
     });
   }
 
-  async function generateArtifact(request) {
+  async function generateArtifact(request, { onProgress } = {}) {
     if (disposed) {
       throw new Error('Preview capture worker channel is disposed.');
     }
+    if (onProgress != null && typeof onProgress !== 'function') {
+      throw new TypeError('Preview capture worker onProgress must be a function.');
+    }
     // The artifact plugin serializes per identity; overlap here means a caller
     // bypassed that queue, and interleaving two captures on one warm browser
     // would let them poison each other.
@@ -509,8 +582,8 @@ export function createPreviewCaptureWorkerChannel({
     try {
       const current = degraded ? null : await ensureWorker();
       const response = current
-        ? await runWorkerJob(current, payload)
-        : await runOnceJob(payload);
+        ? await runWorkerJob(current, payload, onProgress)
+        : await runOnceJob(payload, onProgress);
       return await consumeArtifactFile(response);
     } finally {
       inFlight = false;

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/node/vite.mjs

@@ -67,6 +67,7 @@ import { resolvePreviewRouteDependencyDigest } from './route-dependency-digest.m
 import {
   DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
   PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
+  PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX,
   pygmalionPreviewArtifactPlugin,
 } from './preview-artifact-plugin.mjs';
 import { createPreviewCaptureWorkerChannel } from './preview-capture-worker.mjs';
@@ -433,6 +434,7 @@ export {
   validateRoutePreviewArtifactV3,
   DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
   PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
+  PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX,
   pygmalionPreviewArtifactPlugin,
   createPreviewCaptureWorkerChannel,
   DEFAULT_QA_CAPTURE_MAX_FRAMES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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",