@pygmalionjs/pygmalion 0.2.11 → 0.2.13

package/node/storyboard-capture-scheduler.mjs

@@ -0,0 +1,226 @@
+const CAPTURE_STATUSES = new Set([
+  'ready',
+  'rendered-with-qa-failure',
+  'capture-error',
+]);
+const NON_READY_STATUSES = new Set([
+  'rendered-with-qa-failure',
+  'capture-error',
+]);
+const EVIDENCE_KEYS = Object.freeze(['snapshot', 'screenshot', 'domTree']);
+
+export const STORYBOARD_CAPTURE_SCHEDULER_LIMITS = Object.freeze({
+  defaultConcurrency: 8,
+  maximumConcurrency: 16,
+});
+
+function assertCaptureResult(result, index, phase) {
+  if (
+    !result ||
+    typeof result !== 'object' ||
+    !CAPTURE_STATUSES.has(result.status)
+  ) {
+    throw new TypeError(
+      `Storyboard capture ${index} returned an invalid status during ${phase}.`,
+    );
+  }
+  return result;
+}
+
+function captureContext({
+  phase,
+  attempt,
+  index,
+  total,
+  previousResult,
+  signal,
+}) {
+  return {
+    phase,
+    attempt,
+    index,
+    total,
+    isolated: phase !== 'primary',
+    requiresFreshContext: true,
+    ...(previousResult == null ? {} : { previousResult }),
+    ...(signal == null ? {} : { signal }),
+  };
+}
+
+function throwIfAborted(signal) {
+  signal?.throwIfAborted?.();
+  if (signal?.aborted) {
+    throw signal.reason instanceof Error
+      ? signal.reason
+      : new Error('Storyboard capture scheduling was aborted.');
+  }
+}
+
+function mergeRetriedEvidence(previousResult, retryResult) {
+  if (!NON_READY_STATUSES.has(retryResult.status)) return retryResult;
+  let merged = retryResult;
+  for (const key of EVIDENCE_KEYS) {
+    if (
+      retryResult[key] == null &&
+      previousResult[key] != null
+    ) {
+      if (merged === retryResult) merged = { ...retryResult };
+      merged[key] = previousResult[key];
+    }
+  }
+  if (
+    (!Array.isArray(retryResult.diagnostics) ||
+      retryResult.diagnostics.length === 0) &&
+    Array.isArray(previousResult.diagnostics) &&
+    previousResult.diagnostics.length > 0
+  ) {
+    if (merged === retryResult) merged = { ...retryResult };
+    merged.diagnostics = previousResult.diagnostics;
+  }
+  return merged;
+}
+
+function resolveConcurrency(value) {
+  const concurrency =
+    value ?? STORYBOARD_CAPTURE_SCHEDULER_LIMITS.defaultConcurrency;
+  if (
+    !Number.isInteger(concurrency) ||
+    concurrency < 1 ||
+    concurrency > STORYBOARD_CAPTURE_SCHEDULER_LIMITS.maximumConcurrency
+  ) {
+    throw new RangeError(
+      `Storyboard capture concurrency must be an integer from 1 to ${STORYBOARD_CAPTURE_SCHEDULER_LIMITS.maximumConcurrency}.`,
+    );
+  }
+  return concurrency;
+}
+
+function resolveRetryAttempts(value) {
+  const retryAttempts = value ?? 1;
+  if (
+    !Number.isInteger(retryAttempts) ||
+    retryAttempts < 0 ||
+    retryAttempts > 3
+  ) {
+    throw new RangeError(
+      'Storyboard isolated retry attempts must be an integer from 0 to 3.',
+    );
+  }
+  return retryAttempts;
+}
+
+/**
+ * Schedules capture work without depending on a browser implementation.
+ *
+ * The first case completes globally before the bounded parallel pass begins.
+ * Capture adapters must create and close one fresh execution context for every
+ * invocation. Non-ready results receive bounded input-ordered, serial retry
+ * passes after the primary pass. A retry that remains non-ready inherits any
+ * stable evidence that an earlier attempt captured but the retry could not
+ * reproduce.
+ */
+export async function scheduleStoryboardCaptures(
+  items,
+  capture,
+  options = {},
+) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('Storyboard capture scheduling requires an item array.');
+  }
+  if (typeof capture !== 'function') {
+    throw new TypeError(
+      'Storyboard capture scheduling requires a capture function.',
+    );
+  }
+  const concurrency = resolveConcurrency(options.concurrency);
+  const isolatedRetryAttempts = resolveRetryAttempts(
+    options.isolatedRetryAttempts,
+  );
+  const signal = options.signal;
+  if (items.length === 0) return [];
+  throwIfAborted(signal);
+
+  const results = new Array(items.length);
+  results[0] = assertCaptureResult(
+    await capture(
+      items[0],
+      captureContext({
+        phase: 'warm-up',
+        attempt: 1,
+        index: 0,
+        total: items.length,
+        signal,
+      }),
+    ),
+    0,
+    'warm-up',
+  );
+
+  let nextIndex = 1;
+  async function primaryWorker() {
+    while (nextIndex < items.length) {
+      throwIfAborted(signal);
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = assertCaptureResult(
+        await capture(
+          items[index],
+          captureContext({
+            phase: 'primary',
+            attempt: 1,
+            index,
+            total: items.length,
+            signal,
+          }),
+        ),
+        index,
+        'primary',
+      );
+    }
+  }
+  await Promise.all(
+    Array.from(
+      {
+        length: Math.min(concurrency, Math.max(0, items.length - 1)),
+      },
+      () => primaryWorker(),
+    ),
+  );
+
+  for (
+    let retryAttempt = 1;
+    retryAttempt <= isolatedRetryAttempts;
+    retryAttempt += 1
+  ) {
+    const retryIndexes = results.flatMap((result, index) =>
+      NON_READY_STATUSES.has(result.status) ? [index] : [],
+    );
+    if (retryIndexes.length === 0) break;
+    options.onRetryPass?.({
+      attempt: retryAttempt,
+      totalAttempts: isolatedRetryAttempts,
+      indexes: [...retryIndexes],
+    });
+    for (const index of retryIndexes) {
+      throwIfAborted(signal);
+      const previousResult = results[index];
+      const retryResult = assertCaptureResult(
+        await capture(
+          items[index],
+          captureContext({
+            phase: 'isolated-retry',
+            attempt: retryAttempt + 1,
+            index,
+            total: items.length,
+            previousResult,
+            signal,
+          }),
+        ),
+        index,
+        'isolated-retry',
+      );
+      results[index] = mergeRetriedEvidence(previousResult, retryResult);
+    }
+  }
+  return results;
+}

package/node/storyboard.mjs

@@ -0,0 +1,44 @@
+export {
+  PYGMALION_STORYBOARD_CANONICAL_CONTROL,
+  canonicalizeStoryboardExecutions,
+  executeStoryboardCandidates,
+  fingerprintStoryboardSnapshot,
+  normalizeStoryboardSnapshot,
+  recommendedStoryboardExecutionConcurrency,
+} from './storyboard-canonical.mjs';
+
+export {
+  STORYBOARD_CAPTURE_STATUSES,
+  StoryboardCaptureStageError,
+  assertFinalStoryboardState,
+  captureStoryboardCase,
+  collectStoryboardDomTree,
+  createStoryboardArtifactRecord,
+  findUnassertedStoryboardModal,
+  hashStoryboardCapture,
+  normalizeStoryboardDomStructure,
+  resolveStoryboardCaptureRoute,
+  resolveStoryboardCaptureUrl,
+  resolveStoryboardFixedTime,
+  runStoryboardAssertion,
+  runStoryboardInteraction,
+  serializeStoryboardPreviewDocument,
+  storyboardDocumentStabilitySignature,
+  storyboardCaptureCandidateTexts,
+  waitForStableStoryboardDocument,
+} from './storyboard-capture-runtime.mjs';
+
+export {
+  STORYBOARD_CAPTURE_SCHEDULER_LIMITS,
+  scheduleStoryboardCaptures,
+} from './storyboard-capture-scheduler.mjs';
+
+export {
+  ROUTE_PREVIEW_ARTIFACT_V3_LIMITS,
+  createRoutePreviewArtifactV3,
+  reconstructRoutePreviewArtifactScreenshotV3,
+  reconstructRoutePreviewArtifactSnapshotV3,
+  reconstructRoutePreviewArtifactSnapshotsV3,
+  validateRoutePreviewArtifactBundle,
+  validateRoutePreviewArtifactV3,
+} from './route-preview-artifact-v3.mjs';

package/node/vite.mjs

@@ -51,6 +51,33 @@ import {
   ROUTE_PREVIEW_ARTIFACT_V2_LIMITS,
   validateRoutePreviewArtifactV2,
 } from './route-preview-artifact-v2.mjs';
+import {
+  ROUTE_PREVIEW_ARTIFACT_V3_LIMITS,
+  createRoutePreviewArtifactV3,
+  reconstructRoutePreviewArtifactScreenshotV3,
+  reconstructRoutePreviewArtifactSnapshotV3,
+  reconstructRoutePreviewArtifactSnapshotsV3,
+  validateRoutePreviewArtifactBundle,
+  validateRoutePreviewArtifactV3,
+} from './route-preview-artifact-v3.mjs';
+import {
+  DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
+  PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
+  pygmalionPreviewArtifactPlugin,
+} from './preview-artifact-plugin.mjs';
+import {
+  DEFAULT_QA_CAPTURE_MAX_FRAMES,
+  PYGMALION_QA_ARTIFACT_PREFIX,
+  PYGMALION_QA_CAPTURE_ENDPOINT,
+  QaCaptureError,
+  comparePngScreenshots,
+  createQaCaptureService,
+  normalizeLocalCaptureBasePath,
+  pygmalionQaCapturePlugin,
+  runCaptureScript,
+  validateQaCaptureRequest,
+} from './qa-capture-plugin.mjs';
+import { resolveGitSourceState } from './source-revision.mjs';
 
 function requiredPath(value, name, base) {
   if (typeof value !== 'string' || value.trim() === '') {
@@ -73,8 +100,14 @@ function optionalNonEmptyString(value, name) {
 
 function normalizeEndpoint(value, fallback, name) {
   const endpoint = value ?? fallback;
-  if (typeof endpoint !== 'string' || !endpoint.startsWith('/') || endpoint.endsWith('/')) {
-    throw new Error(`Pygmalion ${name} must start with "/" and must not end with "/"`);
+  if (
+    typeof endpoint !== 'string' ||
+    !endpoint.startsWith('/') ||
+    endpoint.endsWith('/')
+  ) {
+    throw new Error(
+      `Pygmalion ${name} must start with "/" and must not end with "/"`,
+    );
   }
   return endpoint;
 }
@@ -90,27 +123,45 @@ export function resolvePygmalionProject(config) {
   definePygmalionProject(config);
 
   const configRoot = path.resolve(config.configRoot ?? process.cwd());
-  const projectRoot = requiredPath(config.projectRoot, 'projectRoot', configRoot);
-  const appRoot = requiredPath(config.appRoot ?? projectRoot, 'appRoot', configRoot);
+  const projectRoot = requiredPath(
+    config.projectRoot,
+    'projectRoot',
+    configRoot,
+  );
+  const appRoot = requiredPath(
+    config.appRoot ?? projectRoot,
+    'appRoot',
+    configRoot,
+  );
   const editorRoot = path.resolve(configRoot, config.editorRoot ?? appRoot);
-  const appDirectory = (config.appDirectory ?? path.relative(projectRoot, appRoot) ?? '.')
-    .split(path.sep)
-    .join('/') || '.';
+  const appDirectory =
+    (config.appDirectory ?? path.relative(projectRoot, appRoot) ?? '.')
+      .split(path.sep)
+      .join('/') || '.';
   const source = optionalObject(config.source);
   const branch = source.branch ?? 'dev';
   const remote = source.remote ?? 'origin';
   const ref = optionalNonEmptyString(source.ref, 'source.ref');
-  const mirror = config.mirror === false ? false : optionalObject(config.mirror);
-  const sessions = config.sessions === false ? false : optionalObject(config.sessions);
-  const inspect = config.inspect === false ? false : optionalObject(config.inspect);
+  const mirror =
+    config.mirror === false ? false : optionalObject(config.mirror);
+  const sessions =
+    config.sessions === false ? false : optionalObject(config.sessions);
+  const inspect =
+    config.inspect === false ? false : optionalObject(config.inspect);
   const preview = optionalObject(config.preview);
+  const qa = config.qa === false ? false : optionalObject(config.qa);
   const dependencies = optionalObject(config.dependencies);
-  const inventory = config.inventory ? optionalObject(config.inventory) : undefined;
+  const inventory = config.inventory
+    ? optionalObject(config.inventory)
+    : undefined;
   const mirrorRoot = path.resolve(
     configRoot,
     config.mirrorRoot ??
       mirror?.root ??
-      path.join(path.dirname(projectRoot), `${path.basename(projectRoot)}-${branch}-view`),
+      path.join(
+        path.dirname(projectRoot),
+        `${path.basename(projectRoot)}-${branch}-view`,
+      ),
   );
   const mirrorAppRoot = path.resolve(
     configRoot,
@@ -119,7 +170,9 @@ export function resolvePygmalionProject(config) {
       (appDirectory === '.' ? mirrorRoot : path.join(mirrorRoot, appDirectory)),
   );
   const sourceDirectory =
-    (config.sourceDirectory ?? 'src').replace(/^\.?\//, '').replace(/\/$/, '') || '.';
+    (config.sourceDirectory ?? 'src')
+      .replace(/^\.?\//, '')
+      .replace(/\/$/, '') || '.';
 
   return {
     configRoot,
@@ -137,6 +190,7 @@ export function resolvePygmalionProject(config) {
     sessions,
     inspect,
     preview,
+    qa,
     dependencies,
     inventory,
   };
@@ -155,6 +209,32 @@ export function createPygmalionVitePlugins(config) {
     }),
   ];
 
+  if (project.preview.artifactFile || project.preview.generateArtifact) {
+    plugins.push(
+      pygmalionPreviewArtifactPlugin({
+        root: project.appRoot,
+        artifactFile: project.preview.artifactFile,
+        endpoint: project.preview.artifactEndpoint,
+        generateArtifact: project.preview.generateArtifact,
+      }),
+    );
+  }
+
+  if (
+    project.qa !== false &&
+    (project.qa.captureScript || project.qa.captureRunner)
+  ) {
+    plugins.push(
+      pygmalionQaCapturePlugin({
+        ...project.qa,
+        root: project.appRoot,
+        scriptPath: project.qa.captureScript
+          ? path.resolve(project.appRoot, project.qa.captureScript)
+          : undefined,
+      }),
+    );
+  }
+
   if (project.inspect !== false) {
     plugins.push(
       pygmalionInspectPlugin({
@@ -218,7 +298,8 @@ export function createPygmalionVitePlugins(config) {
         previewConfig: project.preview.configFile,
         viteConfig: project.preview.viteConfig,
         viteBin: project.preview.viteBin,
-        previewPort: project.sessions.previewPort ?? project.preview.sessionPort,
+        previewPort:
+          project.sessions.previewPort ?? project.preview.sessionPort,
         worktreesRoot: project.sessions.worktreesRoot,
         prefix: normalizeEndpoint(
           project.sessions.prefix,
@@ -274,4 +355,25 @@ export {
   reconstructRoutePreviewArtifactSnapshots,
   ROUTE_PREVIEW_ARTIFACT_V2_LIMITS,
   validateRoutePreviewArtifactV2,
+  ROUTE_PREVIEW_ARTIFACT_V3_LIMITS,
+  createRoutePreviewArtifactV3,
+  reconstructRoutePreviewArtifactScreenshotV3,
+  reconstructRoutePreviewArtifactSnapshotV3,
+  reconstructRoutePreviewArtifactSnapshotsV3,
+  validateRoutePreviewArtifactBundle,
+  validateRoutePreviewArtifactV3,
+  DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
+  PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
+  pygmalionPreviewArtifactPlugin,
+  DEFAULT_QA_CAPTURE_MAX_FRAMES,
+  PYGMALION_QA_ARTIFACT_PREFIX,
+  PYGMALION_QA_CAPTURE_ENDPOINT,
+  QaCaptureError,
+  comparePngScreenshots,
+  createQaCaptureService,
+  normalizeLocalCaptureBasePath,
+  pygmalionQaCapturePlugin,
+  runCaptureScript,
+  validateQaCaptureRequest,
+  resolveGitSourceState,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -19,6 +19,10 @@
       "types": "./vite.d.ts",
       "default": "./node/vite.mjs"
     },
+    "./storyboard": {
+      "types": "./storyboard.d.ts",
+      "default": "./node/storyboard.mjs"
+    },
     "./dev-view": "./node/dev-view.vite.mjs",
     "./testing": {
       "types": "./testing.d.ts",
@@ -32,13 +36,22 @@
     "node/dev-mirror.mjs",
     "node/dev-view.vite.mjs",
     "node/inspect-plugin.mjs",
+    "node/preview-artifact-plugin.mjs",
+    "node/qa-capture-plugin.mjs",
     "node/route-preview-artifact-v2.mjs",
+    "node/route-preview-artifact-v3.mjs",
+    "node/source-revision.mjs",
     "node/source-diff.mjs",
     "node/source-graph.mjs",
     "node/source-operations.mjs",
     "node/storyboard-canonical.mjs",
+    "node/storyboard-capture-scheduler.mjs",
+    "node/storyboard-capture-runtime.mjs",
     "node/storyboard-environment.mjs",
+    "node/storyboard.mjs",
     "node/vite.mjs",
+    "qa.d.ts",
+    "storyboard.d.ts",
     "types.d.ts",
     "testing.d.ts",
     "vite.d.ts"
@@ -67,6 +80,8 @@
     "magic-string": "^0.30.17",
     "mobx": "^6.13.0",
     "mobx-react-lite": "^4.0.7",
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0",
     "typescript": "^5.8.0"
   },
   "devDependencies": {

package/qa.d.ts

@@ -0,0 +1,201 @@
+import type { Plugin } from 'vite';
+
+export const PYGMALION_QA_CAPTURE_ENDPOINT: '/__pygmalion-qa/capture';
+export const PYGMALION_QA_ARTIFACT_PREFIX: '/__pygmalion-qa/artifacts/';
+export const DEFAULT_QA_CAPTURE_MAX_FRAMES: number;
+
+export interface QaCaptureHashes {
+  domStructureHash: string;
+  screenshotHash: string;
+  screenshotUrl?: string;
+}
+
+export interface QaCaptureFrame extends QaCaptureHashes {
+  id: string;
+  /** Runner-only PNG bytes; never serialized in a capture response. */
+  screenshotBytes?: Uint8Array;
+}
+
+export interface QaCaptureFailure {
+  id: string;
+  error: string;
+}
+
+export interface QaCaptureRunnerInput {
+  root: string;
+  scriptPath: string;
+  basePath: string;
+  frameIds: string[];
+  timeoutMs: number;
+  maxPngBytes?: number;
+  maxTotalPngBytes?: number;
+  signal?: AbortSignal;
+}
+
+export interface QaCaptureRunnerResult {
+  screens: QaCaptureFrame[];
+  failures: QaCaptureFailure[];
+}
+
+export type QaCaptureRunner = (
+  input: QaCaptureRunnerInput,
+) => Promise<QaCaptureRunnerResult>;
+
+export interface QaCaptureBaselineRequest {
+  phase: 'baseline';
+  basePath: string;
+  frameIds: string[];
+}
+
+export interface QaCaptureChangedRequest {
+  phase: 'changed';
+  basePath: string;
+  frameIds: string[];
+  baselineId: string;
+}
+
+export type QaCaptureRequest = QaCaptureBaselineRequest | QaCaptureChangedRequest;
+
+export interface QaCaptureBaselineResponse {
+  ok: true;
+  baselineId: string;
+  frames: QaCaptureFrame[];
+}
+
+export interface QaCaptureChangedFrame {
+  id: string;
+  before: QaCaptureHashes;
+  after: QaCaptureHashes | null;
+  domChanged: boolean | null;
+  screenshotChanged: boolean | null;
+  pixelDiff?: QaPixelDiff;
+}
+
+export interface QaPixelDimensions {
+  width: number;
+  height: number;
+}
+
+export interface QaPixelDiff {
+  before: QaPixelDimensions;
+  after: QaPixelDimensions;
+  dimensionsMatch: boolean;
+  changedPixels: number;
+  totalPixels: number;
+  diffRatio: number;
+  threshold: number;
+  heatmapUrl: string | null;
+}
+
+export interface QaCaptureChangedResponse {
+  ok: true;
+  baselineId: string;
+  beforeBasePath: string;
+  afterBasePath: string;
+  frames: QaCaptureChangedFrame[];
+  complete: boolean;
+  failures: QaCaptureFailure[];
+}
+
+export interface QaCaptureErrorResponse {
+  ok: false;
+  error: string;
+  message: string;
+  failures?: QaCaptureFailure[];
+}
+
+export type QaCaptureResponse =
+  | QaCaptureBaselineResponse
+  | QaCaptureChangedResponse
+  | QaCaptureErrorResponse;
+
+export class QaCaptureError extends Error {
+  statusCode: number;
+  code: string;
+  failures?: QaCaptureFailure[];
+  constructor(
+    statusCode: number,
+    code: string,
+    message: string,
+    failures?: QaCaptureFailure[],
+  );
+}
+
+export interface QaCaptureServiceOptions {
+  root?: string;
+  scriptPath?: string;
+  captureRunner?: QaCaptureRunner;
+  timeoutMs?: number;
+  maxFrameIds?: number;
+  maxBaselines?: number;
+  baselineTtlMs?: number;
+  maxBaselineBytes?: number;
+  maxArtifacts?: number;
+  maxArtifactBytes?: number;
+  artifactTtlMs?: number;
+  maxPngBytes?: number;
+  maxPngPixels?: number;
+  pixelThreshold?: number;
+  now?: () => number;
+  createBaselineId?: () => string;
+  createArtifactId?: () => string;
+}
+
+export interface QaCaptureService {
+  capture(
+    request: QaCaptureRequest | unknown,
+    context?: { allowedHost?: string | string[] },
+  ): Promise<QaCaptureBaselineResponse | QaCaptureChangedResponse>;
+  getArtifact(
+    id: string,
+  ): { bytes: Uint8Array; contentType: 'image/png' } | null;
+  readonly baselineCount: number;
+  readonly artifactCount: number;
+  readonly busy: boolean;
+}
+
+export interface QaPngComparison {
+  before: QaPixelDimensions;
+  after: QaPixelDimensions;
+  dimensionsMatch: boolean;
+  changedPixels: number;
+  totalPixels: number;
+  diffRatio: number;
+  threshold: number;
+  heatmapBytes: Uint8Array;
+}
+
+export function normalizeLocalCaptureBasePath(
+  value: unknown,
+  allowedHost?: string | string[],
+): string;
+
+export function validateQaCaptureRequest(
+  value: unknown,
+  options?: {
+    allowedHost?: string | string[];
+    maxFrameIds?: number;
+  },
+): QaCaptureRequest;
+
+export function runCaptureScript(
+  input: QaCaptureRunnerInput,
+): Promise<QaCaptureRunnerResult>;
+
+export function comparePngScreenshots(
+  beforeBytes: Uint8Array,
+  afterBytes: Uint8Array,
+  options?: {
+    maxPngBytes?: number;
+    maxPngPixels?: number;
+    threshold?: number;
+  },
+): QaPngComparison;
+
+export function createQaCaptureService(
+  options?: QaCaptureServiceOptions,
+): QaCaptureService;
+
+export function pygmalionQaCapturePlugin(
+  options?: QaCaptureServiceOptions,
+): Plugin;