@pygmalionjs/pygmalion 0.2.43 → 0.4.0

package/node/storyboard-capture-runtime.mjs

@@ -811,11 +811,35 @@ export async function waitForStableStoryboardDocument(
 /**
  * Serializes the current document into an inert, standalone DOM preview.
  *
- * This function is self-contained because Playwright serializes it into the page.
+ * Accepts either the base href string (the legacy form, byte-identical output)
+ * or `{ baseHref, sourceComponents }`. When `sourceComponents` — a map of
+ * component display name to `{ sourceId }` — is provided, elements that are
+ * the first host DOM of a matching component fiber are stamped with
+ * `data-pygmalion-source-*` attributes and the body receives the
+ * `data-pygmalion-source-stamped="1"` marker (see docs/perf-contracts.md).
+ *
+ * This function is self-contained because Playwright serializes it into the
+ * page: it must reference nothing from module scope. The fiber walk below is
+ * therefore a minimal copy of src/editor/fiberMap.ts rather than an import,
+ * and component matching is by display name because registry function
+ * references never cross into the captured realm.
  */
 export function serializeStoryboardPreviewDocument(
-  baseHref = '__PYGMALION_PREVIEW_BASE__',
+  baseHrefOrOptions = '__PYGMALION_PREVIEW_BASE__',
 ) {
+  const options =
+    typeof baseHrefOrOptions === 'string'
+      ? { baseHref: baseHrefOrOptions }
+      : (baseHrefOrOptions ?? {});
+  const baseHref =
+    typeof options.baseHref === 'string'
+      ? options.baseHref
+      : '__PYGMALION_PREVIEW_BASE__';
+  const sourceComponents =
+    options.sourceComponents && typeof options.sourceComponents === 'object'
+      ? options.sourceComponents
+      : null;
+
   const clone = document.documentElement.cloneNode(true);
   if (!(clone instanceof HTMLElement)) return null;
 
@@ -850,6 +874,162 @@ export function serializeStoryboardPreviewDocument(
     });
   });
 
+  if (sourceComponents) {
+    // Source metadata stamping. This must run before canvas replacement and
+    // script stripping mutate the clone: both element lists are read from the
+    // same still-parallel tree, so index N in the source maps to index N in
+    // the clone (the copyFormState pattern above relies on the same fact).
+    // Stamping is best-effort — a failure must never cost the snapshot.
+    try {
+      const findFiber = (el) => {
+        for (const key in el) {
+          if (key.startsWith('__reactFiber$')) return el[key];
+        }
+        return null;
+      };
+      // Strip React.memo (.type) and forwardRef (.render) wrappers, exactly
+      // as src/editor/fiberMap.ts unwrapType does.
+      const unwrapFiberType = (type) => {
+        let current = type;
+        while (current && typeof current === 'object') {
+          const next = current.type ?? current.render;
+          if (next == null) break;
+          current = next;
+        }
+        return current;
+      };
+      // First host DOM of a component fiber — the instance-root criterion
+      // (firstHostElement in src/editor/fiberMap.ts).
+      const firstHostElement = (from) => {
+        let fiber = from.child;
+        while (fiber) {
+          const stateNode = fiber.stateNode;
+          if (stateNode && stateNode.nodeType === 1) return stateNode;
+          if (fiber.child) {
+            fiber = fiber.child;
+            continue;
+          }
+          let node = fiber;
+          while (node && node !== from && !node.sibling) node = node.return;
+          fiber = node && node !== from ? node.sibling : null;
+        }
+        return null;
+      };
+      const resolveInstance = (el) => {
+        let hit = null;
+        let hitName = '';
+        for (let fiber = findFiber(el); fiber; fiber = fiber.return) {
+          const type = fiber.type;
+          if (type == null || typeof type === 'string') continue;
+          const unwrapped = unwrapFiberType(type);
+          if (typeof unwrapped !== 'function') continue;
+          const name = unwrapped.displayName ?? unwrapped.name;
+          if (!name || !sourceComponents[name]) continue;
+          // Walk the full return chain so the outermost registered boundary
+          // wins when nested matches share a root DOM.
+          if (firstHostElement(fiber) === el) {
+            hit = fiber;
+            hitName = name;
+          }
+        }
+        if (!hit) return null;
+        const props = {};
+        let childrenText = '';
+        for (const [key, value] of Object.entries(hit.memoizedProps ?? {})) {
+          if (key === 'children') {
+            if (typeof value === 'string') childrenText = value;
+            continue;
+          }
+          if (
+            typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean'
+          ) {
+            props[key] = value;
+          }
+        }
+        return {
+          name: hitName,
+          sourceId: sourceComponents[hitName].sourceId ?? hitName,
+          props,
+          childrenText,
+        };
+      };
+      // CSS-module source map of the captured realm, injected by the inspect
+      // plugin (mirrors sourceTargetOf in src/editor/inspect.ts).
+      const styleByScopedClass = new Map();
+      for (const registration of window.__PYG_CSS_MODULES__ ?? []) {
+        for (const [localName, scoped] of Object.entries(
+          registration.classes ?? {},
+        )) {
+          if (typeof scoped === 'string' && !styleByScopedClass.has(scoped)) {
+            styleByScopedClass.set(
+              scoped,
+              `${registration.file}#${localName}`,
+            );
+          }
+        }
+      }
+      const resolveStyle = (el) => {
+        for (const cls of el.classList) {
+          const styleSource = styleByScopedClass.get(cls);
+          if (styleSource) return styleSource;
+        }
+        return null;
+      };
+      const sourceElements = document.documentElement.querySelectorAll('*');
+      const cloneElements = clone.querySelectorAll('*');
+      const total = Math.min(sourceElements.length, cloneElements.length);
+      for (let index = 0; index < total; index += 1) {
+        // One element failing to resolve must never break serialization.
+        try {
+          const sourceElement = sourceElements[index];
+          const cloneElement = cloneElements[index];
+          const hit = resolveInstance(sourceElement);
+          if (hit) {
+            cloneElement.setAttribute(
+              'data-pygmalion-source-component',
+              hit.sourceId,
+            );
+            cloneElement.setAttribute(
+              'data-pygmalion-source-component-name',
+              hit.name,
+            );
+            const propsJson = JSON.stringify(hit.props);
+            // Values above a cap are omitted, never truncated mid-JSON.
+            if (propsJson.length <= 8 * 1024) {
+              cloneElement.setAttribute(
+                'data-pygmalion-source-props',
+                propsJson,
+              );
+            }
+            if (hit.childrenText && hit.childrenText.length <= 2 * 1024) {
+              cloneElement.setAttribute(
+                'data-pygmalion-source-children',
+                hit.childrenText,
+              );
+            }
+          }
+          const styleSource = resolveStyle(sourceElement);
+          if (styleSource) {
+            cloneElement.setAttribute(
+              'data-pygmalion-source-style',
+              styleSource,
+            );
+          }
+        } catch {
+          // Skip the element; stamping is additive metadata.
+        }
+      }
+      const cloneBody = clone.querySelector('body');
+      if (cloneBody) {
+        cloneBody.setAttribute('data-pygmalion-source-stamped', '1');
+      }
+    } catch {
+      // An unstamped snapshot is still a valid snapshot.
+    }
+  }
+
   const sourceCanvases = [...document.querySelectorAll('canvas')];
   const cloneCanvases = [...clone.querySelectorAll('canvas')];
   sourceCanvases.forEach((source, index) => {
@@ -947,6 +1127,7 @@ async function collectStableEvidence(
     includeDomTree,
     includePreviewSnapshot,
     previewBaseToken,
+    sourceComponents = null,
     screenshotOptions,
     stability = {},
   },
@@ -975,7 +1156,9 @@ async function collectStableEvidence(
     try {
       const snapshot = await page.evaluate(
         serializeStoryboardPreviewDocument,
-        previewBaseToken,
+        sourceComponents
+          ? { baseHref: previewBaseToken, sourceComponents }
+          : previewBaseToken,
       );
       if (
         typeof snapshot !== 'string' ||
@@ -1061,6 +1244,7 @@ export async function captureStoryboardCase({
   includeDomTree = true,
   includePreviewSnapshot = true,
   previewBaseToken = '__PYGMALION_PREVIEW_BASE__',
+  sourceComponents = null,
   contextOptions = {},
   navigationOptions = {},
   screenshotOptions = {},
@@ -1210,6 +1394,7 @@ export async function captureStoryboardCase({
       includeDomTree,
       includePreviewSnapshot,
       previewBaseToken,
+      sourceComponents,
       screenshotOptions,
       stability,
     });

package/node/vite.mjs

@@ -69,6 +69,7 @@ import {
   PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
   pygmalionPreviewArtifactPlugin,
 } from './preview-artifact-plugin.mjs';
+import { createPreviewCaptureWorkerChannel } from './preview-capture-worker.mjs';
 import {
   DEFAULT_QA_CAPTURE_MAX_FRAMES,
   PYGMALION_QA_ARTIFACT_PREFIX,
@@ -217,17 +218,55 @@ export function createPygmalionVitePlugins(config) {
   // it lazily because a capture starts long after the plugin list is assembled.
   let devMirror = null;
 
-  if (project.preview.artifactFile || project.preview.generateArtifact) {
+  // A host either hands over a generator function or names a warm capture
+  // worker script; the function wins when both are present so existing
+  // configurations keep their exact behavior.
+  let generateArtifact = project.preview.generateArtifact;
+  let captureWorkerChannel = null;
+  if (!generateArtifact && project.preview.captureWorker) {
+    const captureWorker = optionalObject(project.preview.captureWorker);
+    if (
+      typeof captureWorker.script !== 'string' ||
+      captureWorker.script.trim() === ''
+    ) {
+      throw new Error(
+        'Pygmalion preview.captureWorker.script must be a non-empty string',
+      );
+    }
+    captureWorkerChannel = createPreviewCaptureWorkerChannel({
+      script: path.resolve(project.appRoot, captureWorker.script),
+      args: captureWorker.args,
+      env: captureWorker.env,
+      cwd: project.appRoot,
+      idleMs: captureWorker.idleMs,
+      jobTimeoutMs: captureWorker.jobTimeoutMs,
+    });
+    generateArtifact = captureWorkerChannel.generateArtifact;
+  }
+
+  if (project.preview.artifactFile || generateArtifact) {
     plugins.push(
       pygmalionPreviewArtifactPlugin({
         root: project.appRoot,
         artifactFile: project.preview.artifactFile,
         endpoint: project.preview.artifactEndpoint,
-        generateArtifact: project.preview.generateArtifact,
+        generateArtifact,
         acquireLease: (label) => devMirror?.acquireLease(label) ?? null,
       }),
     );
   }
+  if (captureWorkerChannel) {
+    const channel = captureWorkerChannel;
+    plugins.push({
+      name: 'pygmalion-preview-capture-worker',
+      apply: 'serve',
+      configureServer(server) {
+        server.httpServer?.once('close', () => {
+          void channel.dispose();
+        });
+      },
+    });
+  }
 
   if (
     project.qa !== false &&
@@ -380,6 +419,7 @@ export {
   DEFAULT_PYGMALION_PREVIEW_ARTIFACT_FILE,
   PYGMALION_PREVIEW_ARTIFACT_ENDPOINT,
   pygmalionPreviewArtifactPlugin,
+  createPreviewCaptureWorkerChannel,
   DEFAULT_QA_CAPTURE_MAX_FRAMES,
   PYGMALION_QA_ARTIFACT_PREFIX,
   PYGMALION_QA_CAPTURE_ENDPOINT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.2.43",
+  "version": "0.4.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -38,6 +38,7 @@
     "node/inspect-plugin.mjs",
     "node/preview-artifact-plugin.mjs",
     "node/preview-artifact-store.mjs",
+    "node/preview-capture-worker.mjs",
     "node/preview-vite-cache.mjs",
     "node/qa-capture-plugin.mjs",
     "node/route-preview-artifact-v2.mjs",
@@ -64,7 +65,7 @@
     "dev": "vite",
     "build": "tsc && vite build",
     "build:lib": "vite build --config vite.lib.config.ts",
-    "test": "node --test node/*.test.mjs src/**/*.test.mjs",
+    "test": "node --test node/*.test.mjs src/*.test.mjs src/**/*.test.mjs",
     "lint:language": "node scripts/lint-language.mjs",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run lint:language && npm test && npm run typecheck && npm run build:lib",
@@ -93,6 +94,7 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.0",
+    "happy-dom": "^20.11.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tailwindcss": "^4.0.0",

package/vite.d.ts

@@ -56,6 +56,21 @@ export interface PygmalionSessionConfig {
   worktreesRoot?: string;
 }
 
+export interface PygmalionPreviewCaptureWorkerConfig {
+  /**
+   * Host-owned warm capture worker script, relative to the application root.
+   * The script speaks the preview capture worker protocol (JSON lines over
+   * stdio) and keeps its expensive boot warm across artifact requests.
+   */
+  script: string;
+  args?: readonly string[];
+  env?: Record<string, string>;
+  /** Idle shutdown delay for the worker process. Default: 300000. */
+  idleMs?: number;
+  /** Per-job timeout before the worker is killed and restarted. Default: 1200000. */
+  jobTimeoutMs?: number;
+}
+
 export interface PygmalionPreviewConfig {
   configFile?: string;
   viteConfig?: string;
@@ -79,6 +94,11 @@ export interface PygmalionPreviewConfig {
     frames?: readonly { id: string; fingerprint?: string }[];
     captureBaseUrl?: string;
   }) => unknown | Promise<unknown>;
+  /**
+   * Warm capture worker used to satisfy artifact generation requests when
+   * `generateArtifact` is absent. When both are set, `generateArtifact` wins.
+   */
+  captureWorker?: PygmalionPreviewCaptureWorkerConfig;
 }
 
 export interface PygmalionQaConfig
@@ -169,6 +189,23 @@ export declare function pygmalionPreviewArtifactPlugin(options?: {
     | null
     | 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>;
+  dispose(): Promise<void>;
+}
+export declare function createPreviewCaptureWorkerChannel(
+  options: PygmalionPreviewCaptureWorkerConfig & {
+    cwd?: string;
+    maxRestarts?: number;
+    restartWindowMs?: number;
+    pingTimeoutMs?: number;
+  },
+): PygmalionPreviewCaptureWorkerChannel;
 export interface PygmalionGitSourceState {
   commit: string;
   revision: string;