@pygmalionjs/pygmalion 0.6.2 → 0.6.4

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

package/vite.d.ts

@@ -71,6 +71,18 @@ export interface PygmalionPreviewCaptureWorkerConfig {
   jobTimeoutMs?: number;
 }
 
+export interface PygmalionPreviewCaptureProgressEvent {
+  phase: 'queued' | 'preparing' | 'capturing' | 'retrying' | 'finalizing';
+  completed: number;
+  total: number;
+  frameId?: string;
+  captureStatus?: string;
+}
+
+export interface PygmalionPreviewCaptureGeneratorOptions {
+  onProgress?: (progress: PygmalionPreviewCaptureProgressEvent) => void;
+}
+
 export interface PygmalionPreviewConfig {
   configFile?: string;
   viteConfig?: string;
@@ -88,12 +100,15 @@ export interface PygmalionPreviewConfig {
   sessionPort?: number;
   artifactFile?: string;
   artifactEndpoint?: string;
-  generateArtifact?: (request: {
-    namespace: string;
-    sourceRevision: string;
-    frames?: readonly { id: string; fingerprint?: string }[];
-    captureBaseUrl?: string;
-  }) => unknown | Promise<unknown>;
+  generateArtifact?: (
+    request: {
+      namespace: string;
+      sourceRevision: string;
+      frames?: readonly { id: string; fingerprint?: string }[];
+      captureBaseUrl?: string;
+    },
+    options?: PygmalionPreviewCaptureGeneratorOptions,
+  ) => unknown | Promise<unknown>;
   /**
    * Warm capture worker used to satisfy artifact generation requests when
    * `generateArtifact` is absent. When both are set, `generateArtifact` wins.
@@ -170,18 +185,22 @@ export declare function createPygmalionVitePlugins(
 ): PluginOption[];
 
 export declare const PYGMALION_PREVIEW_ARTIFACT_ENDPOINT: string;
+export declare const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX: string;
 export declare const DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE: string;
 export declare function pygmalionPreviewArtifactPlugin(options?: {
   root?: string;
   artifactFile?: string;
   endpoint?: string;
   disabled?: () => boolean;
-  generateArtifact?: (request: {
-    namespace: string;
-    sourceRevision: string;
-    frames?: readonly { id: string; fingerprint?: string }[];
-    captureBaseUrl?: string;
-  }) => unknown | Promise<unknown>;
+  generateArtifact?: (
+    request: {
+      namespace: string;
+      sourceRevision: string;
+      frames?: readonly { id: string; fingerprint?: string }[];
+      captureBaseUrl?: string;
+    },
+    options?: PygmalionPreviewCaptureGeneratorOptions,
+  ) => unknown | Promise<unknown>;
   acquireLease?: (
     reason: string,
   ) =>
@@ -190,12 +209,15 @@ export declare function pygmalionPreviewArtifactPlugin(options?: {
     | Promise<{ release(): void | Promise<void> } | null>;
 }): PluginOption;
 export interface PygmalionPreviewCaptureWorkerChannel {
-  generateArtifact(request: {
-    namespace: string;
-    sourceRevision: string;
-    frames?: readonly { id: string; fingerprint?: string }[];
-    captureBaseUrl?: string;
-  }): Promise<unknown>;
+  generateArtifact(
+    request: {
+      namespace: string;
+      sourceRevision: string;
+      frames?: readonly { id: string; fingerprint?: string }[];
+      captureBaseUrl?: string;
+    },
+    options?: PygmalionPreviewCaptureGeneratorOptions,
+  ): Promise<unknown>;
   dispose(): Promise<void>;
 }
 export declare function createPreviewCaptureWorkerChannel(