@pygmalionjs/pygmalion 0.5.17 → 0.5.19

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.17",
+  "version": "0.5.19",
   "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;