@pygmalionjs/pygmalion 0.5.18 → 0.5.20

package/node/preview-artifact-plugin.mjs

@@ -11,6 +11,24 @@ const MAX_IDENTITY_LENGTH = 1_024;
 const MAX_CAPTURE_BASE_URL_LENGTH = 2_048;
 const MAX_FRAME_REQUEST_BYTES = 64 * 1024;
 const MAX_FRAME_REQUEST_COUNT = 2_048;
+// A batch that generates carries a recipe per frame, which a query string
+// cannot hold past a handful of frames (Node refuses the request at 16KB of
+// headers). Those arrive as a JSON body instead; the ceiling keeps a stray
+// client from parking megabytes in memory.
+const MAX_FRAME_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
+/**
+ * Where a request sits among captures waiting on the same identity. Smaller
+ * runs first. The editor sends a frame the designer selected ahead of a
+ * canvas being filled, and a canvas being filled ahead of one nobody is
+ * looking at; a request that says nothing sits with the canvas.
+ */
+export const PREVIEW_CAPTURE_PRIORITY = Object.freeze({
+  selected: 0,
+  canvas: 10,
+  background: 20,
+});
+const DEFAULT_CAPTURE_PRIORITY = PREVIEW_CAPTURE_PRIORITY.canvas;
+const MAX_CAPTURE_PRIORITY = 1_000;
 
 function isLocalRequestHost(value) {
   const raw = Array.isArray(value) ? value[0] : value;
@@ -33,15 +51,25 @@ function sendJson(response, statusCode, body) {
   response.end(payload);
 }
 
-function requestedIdentity(url, key) {
-  const value = url.searchParams.get(key);
+function requestedIdentity(params, key) {
+  const value = params.get(key);
   return value && value === value.trim() && value.length <= MAX_IDENTITY_LENGTH
     ? value
     : null;
 }
 
-function requestedCaptureBaseUrl(url, requestHost) {
-  const value = url.searchParams.get('captureBaseUrl');
+function requestedPriority(params) {
+  const raw = params.get('priority');
+  if (raw == null || raw === '') return DEFAULT_CAPTURE_PRIORITY;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > MAX_CAPTURE_PRIORITY) {
+    return null;
+  }
+  return value;
+}
+
+function requestedCaptureBaseUrl(params, requestHost) {
+  const value = params.get('captureBaseUrl');
   if (!value) return undefined;
   if (value !== value.trim() || value.length > MAX_CAPTURE_BASE_URL_LENGTH) {
     return null;
@@ -79,27 +107,40 @@ function requestedCaptureBaseUrl(url, requestHost) {
  * without starting work — otherwise naming every frame on mount would capture
  * the whole catalog, which is the cost this mode exists to remove.
  */
-function generationAllowed(url) {
-  const raw = url.searchParams.get('generate');
+function generationAllowed(params) {
+  const raw = params.get('generate');
   if (raw == null) return true;
   return !['0', 'false', 'no'].includes(raw.trim().toLowerCase());
 }
 
-function resolutionOnly(url) {
-  const raw = url.searchParams.get('resolve');
+function resolutionOnly(params) {
+  const raw = params.get('resolve');
   return raw != null && ['1', 'true', 'yes'].includes(raw.trim().toLowerCase());
 }
 
-function requestedFrames(url) {
-  const raw = url.searchParams.get('frames');
+/**
+ * The frame list of a request, whichever way it arrived.
+ *
+ * A GET carries it as JSON in the `frames` query parameter, capped so it fits a
+ * query string; a POST carries it in the body, where a batch of recipes fits.
+ */
+function requestedFrames(params) {
+  const raw = params.get('frames');
   if (raw == null) return undefined;
-  if (Buffer.byteLength(raw) > MAX_FRAME_REQUEST_BYTES) return null;
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
+  const parsedBody = params.parsedFrames;
+  if (parsedBody === undefined && Buffer.byteLength(raw) > MAX_FRAME_REQUEST_BYTES) {
     return null;
   }
+  let parsed;
+  if (parsedBody !== undefined) {
+    parsed = parsedBody;
+  } else {
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
   if (!Array.isArray(parsed) || parsed.length > MAX_FRAME_REQUEST_COUNT) return null;
   const wanted = [];
   for (const entry of parsed) {
@@ -113,11 +154,75 @@ function requestedFrames(url) {
       if (typeof fingerprint !== 'string' || !fingerprint.trim()) return null;
       if (fingerprint.length > MAX_IDENTITY_LENGTH) return null;
     }
-    wanted.push(fingerprint === undefined ? { id } : { id, fingerprint });
+    // The recipe the fingerprint stands for. A fingerprint is a hash — a
+    // generator handed one alone can only re-capture what the host declared for
+    // that id, which is a different screen wearing the requested name. Carried
+    // through opaquely: this plugin never interprets it, and the whole request
+    // is already capped by MAX_FRAME_REQUEST_BYTES.
+    const recipe = item.recipe;
+    if (recipe !== undefined) {
+      if (typeof recipe !== 'object' || recipe === null || Array.isArray(recipe)) {
+        return null;
+      }
+    }
+    wanted.push({
+      id,
+      ...(fingerprint === undefined ? {} : { fingerprint }),
+      ...(recipe === undefined ? {} : { recipe }),
+    });
   }
   return wanted;
 }
 
+/**
+ * The parameters of a request, read the same way for both transports.
+ *
+ * GET keeps every field in the query string. POST carries a JSON object with
+ * the same field names; scalar fields are read as strings so the validators
+ * above apply unchanged, and `frames` is kept parsed so a large batch is not
+ * re-serialized only to be parsed again.
+ */
+function paramsFromQuery(url) {
+  return { get: (key) => url.searchParams.get(key), parsedFrames: undefined };
+}
+
+function paramsFromBody(body) {
+  const scalar = (value) => {
+    if (value === undefined || value === null) return null;
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+    return null;
+  };
+  return {
+    get: (key) => {
+      if (key === 'frames') return body.frames === undefined ? null : '[]';
+      return scalar(body[key]);
+    },
+    parsedFrames: body.frames,
+  };
+}
+
+async function readJsonBody(request, limit) {
+  const chunks = [];
+  let received = 0;
+  for await (const chunk of request) {
+    const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+    received += buffer.length;
+    if (received > limit) return { ok: false, error: 'body_too_large' };
+    chunks.push(buffer);
+  }
+  if (received === 0) return { ok: false, error: 'invalid_body' };
+  try {
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, error: 'invalid_body' };
+    }
+    return { ok: true, body: parsed };
+  } catch {
+    return { ok: false, error: 'invalid_body' };
+  }
+}
+
 function exactArtifact(artifact, namespace, sourceRevision) {
   const validation = validateRoutePreviewArtifactBundle(artifact);
   return (
@@ -140,6 +245,8 @@ export function pygmalionPreviewArtifactPlugin({
   disabled = () => false,
   generateArtifact,
   acquireLease,
+  requestRuntime,
+  runtimePrepared = () => true,
 } = {}) {
   const resolvedRoot = path.resolve(root);
   const resolvedArtifact = path.resolve(resolvedRoot, artifactFile);
@@ -165,6 +272,16 @@ export function pygmalionPreviewArtifactPlugin({
       'Preview artifact generator option must be a function.',
     );
   }
+  if (requestRuntime != null && typeof requestRuntime !== 'function') {
+    throw new TypeError(
+      'Preview artifact runtime request option must be a function.',
+    );
+  }
+  if (typeof runtimePrepared !== 'function') {
+    throw new TypeError(
+      'Preview artifact runtime readiness option must be a function.',
+    );
+  }
 
   const artifactStore = createPreviewArtifactStore({
     artifactFile: resolvedArtifact,
@@ -175,20 +292,52 @@ export function pygmalionPreviewArtifactPlugin({
   const identityQueues = new Map();
   const inFlightRequests = new Map();
 
-  function enqueueIdentity(namespace, sourceRevision, task) {
+  /**
+   * Captures on one identity run one at a time — they share the checkout and
+   * the worker — but not in the order they were asked. A frame the designer
+   * just selected must not sit behind a canvas being filled in the background,
+   * so the queue is ordered by priority and by arrival within a priority.
+   * The running capture is never interrupted; the next pick happens when it
+   * finishes.
+   */
+  function enqueueIdentity(namespace, sourceRevision, task, priority = DEFAULT_CAPTURE_PRIORITY) {
     const identity = `${namespace}\u0000${sourceRevision}`;
-    const previous = identityQueues.get(identity) ?? Promise.resolve();
-    const current = previous.catch(() => undefined).then(task);
-    identityQueues.set(identity, current);
-    void current.then(
-      () => {
-        if (identityQueues.get(identity) === current) identityQueues.delete(identity);
-      },
-      () => {
-        if (identityQueues.get(identity) === current) identityQueues.delete(identity);
-      },
-    );
-    return current;
+    let queue = identityQueues.get(identity);
+    if (!queue) {
+      queue = { pending: [], running: false, arrivals: 0 };
+      identityQueues.set(identity, queue);
+    }
+    return new Promise((resolve, reject) => {
+      queue.arrivals += 1;
+      queue.pending.push({
+        priority,
+        arrival: queue.arrivals,
+        run: task,
+        resolve,
+        reject,
+      });
+      queue.pending.sort(
+        (left, right) => left.priority - right.priority || left.arrival - right.arrival,
+      );
+      pumpIdentity(identity, queue);
+    });
+  }
+
+  function pumpIdentity(identity, queue) {
+    if (queue.running) return;
+    const next = queue.pending.shift();
+    if (!next) {
+      if (identityQueues.get(identity) === queue) identityQueues.delete(identity);
+      return;
+    }
+    queue.running = true;
+    Promise.resolve()
+      .then(next.run)
+      .then(next.resolve, next.reject)
+      .finally(() => {
+        queue.running = false;
+        pumpIdentity(identity, queue);
+      });
   }
 
   function deduplicateRequest(key, task) {
@@ -230,6 +379,26 @@ export function pygmalionPreviewArtifactPlugin({
     });
   }
 
+  /**
+   * Answers a frame whose capture cannot run yet, and starts what it needs.
+   *
+   * Asking for a frame is asking for the checkout — the capture reads it. The
+   * editor holds no preview origin until the mirror is ready, so this endpoint
+   * is the only place that demand arrives before one exists. Without starting
+   * the work here the canvas waited on a preparation nobody had ordered, and
+   * the only way out was a human pressing refresh.
+   */
+  function answerPreparing(response) {
+    requestRuntime?.();
+    sendJson(response, 503, {
+      ok: false,
+      error: 'artifact_generation_unavailable',
+      retryable: true,
+      preparing: true,
+      details: ['The dev screen checkout is being prepared.'],
+    });
+  }
+
   /**
    * A generator that ran and produced the wrong thing.
    *
@@ -300,7 +469,7 @@ export function pygmalionPreviewArtifactPlugin({
    * The stored bundle becomes a cache keyed per frame rather than one artifact
    * per revision, so replacing one screen no longer re-renders the others.
    */
-  function generateFrames(namespace, sourceRevision, captureBaseUrl, wanted) {
+  function generateFrames(namespace, sourceRevision, captureBaseUrl, wanted, priority) {
     const request = `frames\u0000${namespace}\u0000${sourceRevision}\u0000${wanted
       .map((frame) => `${frame.id}@${frame.fingerprint ?? ''}`)
       .sort()
@@ -346,7 +515,7 @@ export function pygmalionPreviewArtifactPlugin({
             wanted,
           )
         ).bundle;
-      }),
+      }, priority),
     );
   }
 
@@ -365,8 +534,8 @@ export function pygmalionPreviewArtifactPlugin({
           next();
           return;
         }
-        if (request.method !== 'GET') {
-          response.setHeader('allow', 'GET');
+        if (request.method !== 'GET' && request.method !== 'POST') {
+          response.setHeader('allow', 'GET, POST');
           sendJson(response, 405, {
             ok: false,
             error: 'method_not_allowed',
@@ -380,14 +549,33 @@ export function pygmalionPreviewArtifactPlugin({
           });
           return;
         }
-        const namespace = requestedIdentity(url, 'namespace');
-        const sourceRevision = requestedIdentity(url, 'sourceRevision');
+        let params;
+        if (request.method === 'POST') {
+          const read = await readJsonBody(request, MAX_FRAME_REQUEST_BODY_BYTES);
+          if (!read.ok) {
+            sendJson(response, read.error === 'body_too_large' ? 413 : 400, {
+              ok: false,
+              error: read.error,
+            });
+            return;
+          }
+          params = paramsFromBody(read.body);
+        } else {
+          params = paramsFromQuery(url);
+        }
+        const namespace = requestedIdentity(params, 'namespace');
+        const sourceRevision = requestedIdentity(params, 'sourceRevision');
         const captureBaseUrl = requestedCaptureBaseUrl(
-          url,
+          params,
           Array.isArray(request.headers.host)
             ? request.headers.host[0]
             : request.headers.host,
         );
+        const priority = requestedPriority(params);
+        if (priority === null) {
+          sendJson(response, 400, { ok: false, error: 'invalid_priority' });
+          return;
+        }
         if (!namespace || !sourceRevision) {
           sendJson(response, 400, {
             ok: false,
@@ -416,13 +604,13 @@ export function pygmalionPreviewArtifactPlugin({
           return;
         }
 
-        const wanted = requestedFrames(url);
+        const wanted = requestedFrames(params);
         if (wanted === null) {
           sendJson(response, 400, { ok: false, error: 'invalid_frames' });
           return;
         }
         if (wanted !== undefined) {
-          if (resolutionOnly(url)) {
+          if (resolutionOnly(params)) {
             const resolution = await artifactStore.resolveFrameSelection(
               namespace,
               sourceRevision,
@@ -449,7 +637,11 @@ export function pygmalionPreviewArtifactPlugin({
             wanted,
           );
           const absent = [...picked.missing, ...picked.stale];
-          if (absent.length && generateArtifact && generationAllowed(url)) {
+          if (absent.length && generateArtifact && generationAllowed(params)) {
+            if (!runtimePrepared()) {
+              answerPreparing(response);
+              return;
+            }
             const requested = new Set(absent);
             try {
               await generateFrames(
@@ -457,6 +649,7 @@ export function pygmalionPreviewArtifactPlugin({
                 sourceRevision,
                 captureBaseUrl,
                 wanted.filter((frame) => requested.has(frame.id)),
+                priority,
               );
               picked = await artifactStore.readFrameSelection(
                 namespace,
@@ -480,12 +673,16 @@ export function pygmalionPreviewArtifactPlugin({
         // A consumer that forbids capture must be obeyed in every mode. Honouring
         // it only for frame requests left the expensive path one missing
         // parameter away.
-        const mayGenerate = generateArtifact && generationAllowed(url);
+        const mayGenerate = generateArtifact && generationAllowed(params);
         let artifact = await artifactStore.readExactArtifact(
           namespace,
           sourceRevision,
         );
         if (!artifact && mayGenerate) {
+          if (!runtimePrepared()) {
+            answerPreparing(response);
+            return;
+          }
           try {
             artifact = await generateExactArtifact(
               namespace,

package/node/storyboard-capture-runtime.mjs

@@ -704,6 +704,11 @@ export function storyboardDocumentStabilitySignature(volatileSelectors = []) {
       selectorKey,
       observer: null,
       revision: 0,
+      // What kept changing, by element, so a screen that never settles can say
+      // which part of it would not stop — the alternative is a capture that
+      // reports "unstable" and a person guessing which widget to declare
+      // volatile. Bounded: a screen has a handful of movers, not thousands.
+      churn: new Map(),
     };
     // A screen can hold something that never stops changing — an elapsed clock, a
     // level meter, a marquee. Counting those makes the document look unstable
@@ -719,6 +724,35 @@ export function storyboardDocumentStabilitySignature(volatileSelectors = []) {
         return false;
       }
     };
+    const describe = (node) => {
+      const element =
+        node && node.nodeType === 1 ? node : (node && node.parentElement) || null;
+      if (!element) return '(text)';
+      const tag = String(element.tagName || '').toLowerCase();
+      const id = element.id ? `#${element.id}` : '';
+      const classes = String(element.getAttribute?.('class') ?? '')
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 2)
+        .map((name) => `.${name}`)
+        .join('');
+      const testId = element.getAttribute?.('data-testid');
+      return `${tag}${id}${classes}${testId ? `[data-testid=${testId}]` : ''}`;
+    };
+    const countChurn = (records) => {
+      for (const record of records) {
+        if (isVolatile(record.target)) continue;
+        const key = describe(record.target);
+        const known = tracker.churn.get(key);
+        if (known != null) {
+          tracker.churn.set(key, known + 1);
+        } else if (tracker.churn.size < 64) {
+          tracker.churn.set(key, 1);
+        } else {
+          tracker.churn.set('(other)', (tracker.churn.get('(other)') ?? 0) + 1);
+        }
+      }
+    };
     if (
       document.documentElement &&
       typeof runtime.MutationObserver === 'function'
@@ -728,6 +762,7 @@ export function storyboardDocumentStabilitySignature(volatileSelectors = []) {
         if (batch.length > 0 && batch.every((record) => isVolatile(record.target))) {
           return;
         }
+        countChurn(batch);
         tracker.revision += 1;
       });
       tracker.observer.observe(document.documentElement, {
@@ -782,6 +817,47 @@ export function storyboardDocumentStabilitySignature(volatileSelectors = []) {
   });
 }
 
+/**
+ * What kept the document from settling, most active first.
+ *
+ * Runs inside the page: the stability tracker keeps a bounded count of
+ * mutation targets that were not declared volatile, and this reads it back so
+ * a failed wait can name the mover instead of only saying "unstable".
+ */
+export function storyboardDocumentChurnReport(limit = 6) {
+  const tracker = window['__PYGMALION_STORYBOARD_STABILITY__'];
+  const churn = tracker?.churn;
+  if (!churn || typeof churn.entries !== 'function') return [];
+  return [...churn.entries()]
+    .sort((left, right) => right[1] - left[1])
+    .slice(0, Math.max(0, limit))
+    .map(([target, count]) => ({ target, count }));
+}
+
+/** One line naming what a screen kept changing, for a stability failure. */
+export function formatStoryboardChurn(report) {
+  if (!Array.isArray(report) || report.length === 0) return '';
+  const parts = report
+    .filter((entry) => entry && typeof entry.target === 'string')
+    .map((entry) => `${entry.target} ×${Number(entry.count) || 0}`);
+  return parts.length ? ` Still changing: ${parts.join(', ')}.` : '';
+}
+
+async function describeStoryboardChurn(page) {
+  try {
+    const report = await page.evaluate(storyboardDocumentChurnReport, 6);
+    return formatStoryboardChurn(report);
+  } catch {
+    return '';
+  }
+}
+
+function unstableDocumentError(churn) {
+  return new Error(
+    `The rendered document did not reach a stable DOM and overlay state.${churn}`,
+  );
+}
+
 export async function waitForStableStoryboardDocument(
   page,
   {
@@ -1148,17 +1224,23 @@ async function collectStableEvidence(
     screenshotOptions,
     screenshotScale = STORYBOARD_CAPTURE_SCREENSHOT_SCALE,
     stability = {},
+    // The stabilize stage already froze the page and saw it hold still. Waiting
+    // again here measured as the single largest cost of a capture (two rounds
+    // of the same wait, ~40% of the whole), and a document that was still a
+    // moment ago is not made stiller by asking twice.
+    frozenStyleApplied = false,
+    alreadyStable = false,
   },
 ) {
   const evidence = {};
   const errors = [];
   try {
-    await page.addStyleTag({ content: FROZEN_STYLE });
-    const stable = await waitForStableStoryboardDocument(page, stability);
-    if (!stable) {
-      throw new Error(
-        'The rendered document did not reach a stable DOM and overlay state.',
-      );
+    if (!frozenStyleApplied) await page.addStyleTag({ content: FROZEN_STYLE });
+    if (!alreadyStable) {
+      const stable = await waitForStableStoryboardDocument(page, stability);
+      if (!stable) {
+        throw unstableDocumentError(await describeStoryboardChurn(page));
+      }
     }
   } catch (error) {
     errors.push(new StoryboardCaptureStageError('stabilize', error));
@@ -1306,6 +1388,10 @@ export async function captureStoryboardCase({
   let primaryError = null;
   let evidence = {};
   const evidenceErrors = [];
+  // Set by the stabilize stage; evidence collection reuses both instead of
+  // freezing and waiting a second time.
+  let frozenStyleApplied = Boolean(session?.frozen);
+  let stabilized = false;
   try {
     throwIfAborted(signal);
     if (!warm) {
@@ -1394,12 +1480,12 @@ export async function captureStoryboardCase({
         await page.addStyleTag({ content: FROZEN_STYLE });
         if (session) session.frozen = true;
       }
+      frozenStyleApplied = true;
       const stable = await waitForStableStoryboardDocument(page, stability);
       if (!stable) {
-        throw new Error(
-          'The rendered document did not reach a stable DOM and overlay state.',
-        );
+        throw unstableDocumentError(await describeStoryboardChurn(page));
       }
+      stabilized = true;
     });
     await atCaptureStage('assertion', async () => {
       await assertFinalStoryboardState(page, screenCase.assertions ?? []);
@@ -1420,6 +1506,8 @@ export async function captureStoryboardCase({
       screenshotOptions,
       screenshotScale: resolveScreenshotScale(contextOptions),
       stability,
+      frozenStyleApplied,
+      alreadyStable: stabilized,
     });
     evidence = collected.evidence;
     evidenceErrors.push(...collected.errors);

package/node/vite.mjs

@@ -258,6 +258,10 @@ export function createPygmalionVitePlugins(config) {
         endpoint: project.preview.artifactEndpoint,
         generateArtifact,
         acquireLease: (label) => devMirror?.acquireLease(label) ?? null,
+        requestRuntime: () => devMirror?.requestRuntime?.(),
+        // No mirror plugin means no checkout to prepare, so generation is
+        // always allowed to proceed as it did before.
+        runtimePrepared: () => devMirror?.runtimePrepared?.() ?? true,
       }),
     );
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.5.18",
+  "version": "0.5.20",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {

package/dist-lib/types/canvas/StoryboardConnections.d.ts

@@ -1,31 +0,0 @@
-import type { StoryboardGraphViewModel } from '../editor/storyboardGraphView';
-export interface StoryboardFrameGeometry {
-    frameId: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-export interface StoryboardConnectionPath {
-    id: string;
-    sourceFrameId: string;
-    targetFrameId: string;
-    path: string;
-}
-export type StoryboardConnectionMode = 'story' | 'focus' | 'overview';
-export interface StoryboardConnectionPathOptions {
-    mode?: StoryboardConnectionMode;
-    activeFrameId?: string | null;
-}
-/**
- * Projects graph transitions into world-space paths. The calculation is kept
- * independent from camera pan and zoom because the SVG lives inside the same
- * transformed canvas layer as the frames.
- */
-export declare function createStoryboardConnectionPaths(model: StoryboardGraphViewModel, frames: readonly StoryboardFrameGeometry[], options?: StoryboardConnectionPathOptions): StoryboardConnectionPath[];
-export declare function StoryboardConnections({ model, frames, mode, activeFrameId, }: {
-    model: StoryboardGraphViewModel;
-    frames: readonly StoryboardFrameGeometry[];
-    mode?: StoryboardConnectionMode;
-    activeFrameId?: string | null;
-}): import("react").JSX.Element | null;

package/dist-lib/types/shell/AssetsPanel.d.ts

@@ -1,3 +0,0 @@
-export declare function AssetsPanel({ onFrameFocus, }: {
-    onFrameFocus?: (id: string) => void;
-}): import("react").JSX.Element;