@pygmalionjs/pygmalion 0.2.18 → 0.2.19

package/README.md

@@ -154,6 +154,26 @@ unapplied edits, `switchSource` refuses rather than leave the canvas on a
 revision those edits were never written against — apply or revert them first, or
 pass `{ discardEdits: true }`.
 
+### Screens that never stop moving
+
+A capture waits for the document to hold still. A screen with an elapsed clock, a
+level meter, or a marquee never does, so it fails on `stabilize` no matter how
+long it waits. Declare those regions and their mutations stop counting as churn:
+
+```ts
+captureStoryboardCase({
+  // ...
+  stability: {
+    volatileSelectors: ['[data-testid="elapsed-time"]', '[data-live-meter]'],
+  },
+});
+```
+
+The wait itself samples every 100ms and needs three identical samples, up to a
+4s ceiling — wide enough for a screen that repaints on a one-second beat.
+`attempts`, `requiredStableSamples`, `intervalMs`, and `minimumWaitMs` are
+adjustable for anything slower.
+
 ## Register screens and scenarios
 
 The host owns application-specific routes, fixtures, authentication, mock data,

package/node/storyboard-capture-runtime.mjs

@@ -651,22 +651,43 @@ export function collectStoryboardDomTree() {
  * This function is self-contained because Playwright serializes it into the
  * page.
  */
-export function storyboardDocumentStabilitySignature() {
+export function storyboardDocumentStabilitySignature(volatileSelectors = []) {
   const runtime = window;
   const trackerKey = '__PYGMALION_STORYBOARD_STABILITY__';
+  const selectors = Array.isArray(volatileSelectors) ? volatileSelectors : [];
+  const selectorKey = selectors.join(',');
   let tracker = runtime[trackerKey];
-  if (!tracker || tracker.document !== document) {
+  if (!tracker || tracker.document !== document || tracker.selectorKey !== selectorKey) {
     tracker?.observer?.disconnect?.();
     tracker = {
       document,
+      selectorKey,
       observer: null,
       revision: 0,
     };
+    // A screen can hold something that never stops changing — an elapsed clock, a
+    // level meter, a marquee. Counting those makes the document look unstable
+    // forever, so a caller can declare them and have their mutations ignored.
+    const isVolatile = (node) => {
+      if (!selectorKey) return false;
+      const element =
+        node && node.nodeType === 1 ? node : (node && node.parentElement) || null;
+      if (!element || typeof element.closest !== 'function') return false;
+      try {
+        return element.closest(selectorKey) != null;
+      } catch {
+        return false;
+      }
+    };
     if (
       document.documentElement &&
       typeof runtime.MutationObserver === 'function'
     ) {
-      tracker.observer = new runtime.MutationObserver(() => {
+      tracker.observer = new runtime.MutationObserver((records) => {
+        const batch = Array.isArray(records) ? records : [];
+        if (batch.length > 0 && batch.every((record) => isVolatile(record.target))) {
+          return;
+        }
         tracker.revision += 1;
       });
       tracker.observer.observe(document.documentElement, {
@@ -724,10 +745,13 @@ export function storyboardDocumentStabilitySignature() {
 export async function waitForStableStoryboardDocument(
   page,
   {
-    attempts = 20,
+    // A screen that repaints on a one-second beat needs a window wider than that
+    // beat to show a quiet stretch, so the ceiling is 4s rather than 2s.
+    attempts = 40,
     requiredStableSamples = 3,
     intervalMs = 100,
     minimumWaitMs = 400,
+    volatileSelectors = [],
   } = {},
 ) {
   await page.evaluate(async () => {
@@ -737,7 +761,10 @@ export async function waitForStableStoryboardDocument(
   let stable = 0;
   let elapsedMs = 0;
   for (let attempt = 0; attempt < attempts; attempt += 1) {
-    const current = await page.evaluate(storyboardDocumentStabilitySignature);
+    const current = await page.evaluate(
+      storyboardDocumentStabilitySignature,
+      volatileSelectors,
+    );
     if (current === previous) stable += 1;
     else stable = 0;
     previous = current;
@@ -890,13 +917,14 @@ async function collectStableEvidence(
     includePreviewSnapshot,
     previewBaseToken,
     screenshotOptions,
+    stability = {},
   },
 ) {
   const evidence = {};
   const errors = [];
   try {
     await page.addStyleTag({ content: FROZEN_STYLE });
-    const stable = await waitForStableStoryboardDocument(page);
+    const stable = await waitForStableStoryboardDocument(page, stability);
     if (!stable) {
       throw new Error(
         'The rendered document did not reach a stable DOM and overlay state.',
@@ -986,6 +1014,7 @@ export async function captureStoryboardCase({
   contextOptions = {},
   navigationOptions = {},
   screenshotOptions = {},
+  stability = {},
 } = {}) {
   if (!browser || typeof browser.newContext !== 'function') {
     throw new TypeError(
@@ -1081,7 +1110,7 @@ export async function captureStoryboardCase({
     }
     await atCaptureStage('stabilize', async () => {
       await page.addStyleTag({ content: FROZEN_STYLE });
-      const stable = await waitForStableStoryboardDocument(page);
+      const stable = await waitForStableStoryboardDocument(page, stability);
       if (!stable) {
         throw new Error(
           'The rendered document did not reach a stable DOM and overlay state.',
@@ -1104,6 +1133,7 @@ export async function captureStoryboardCase({
       includePreviewSnapshot,
       previewBaseToken,
       screenshotOptions,
+      stability,
     });
     evidence = collected.evidence;
     evidenceErrors.push(...collected.errors);

package/package.json

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

package/storyboard.d.ts

@@ -66,6 +66,21 @@ export interface StoryboardCaptureOptions<
   contextOptions?: Record<string, unknown>;
   navigationOptions?: Record<string, unknown>;
   screenshotOptions?: Record<string, unknown>;
+  /** How long to wait for a still document, and what may keep moving. */
+  stability?: StoryboardStabilityOptions;
+}
+
+export interface StoryboardStabilityOptions {
+  /** Samples before giving up. Default 40 at 100ms, so a 4s ceiling. */
+  attempts?: number;
+  requiredStableSamples?: number;
+  intervalMs?: number;
+  minimumWaitMs?: number;
+  /**
+   * Regions that are expected to keep changing — an elapsed clock, a level
+   * meter, a marquee. Mutations confined to them do not count as churn.
+   */
+  volatileSelectors?: readonly string[];
 }
 
 export declare const STORYBOARD_CAPTURE_STATUSES: Readonly<{
@@ -132,14 +147,11 @@ export declare function assertFinalStoryboardState(
 ): Promise<void>;
 export declare function waitForStableStoryboardDocument(
   page: unknown,
-  options?: {
-    attempts?: number;
-    requiredStableSamples?: number;
-    intervalMs?: number;
-    minimumWaitMs?: number;
-  },
+  options?: StoryboardStabilityOptions,
 ): Promise<boolean>;
-export declare function storyboardDocumentStabilitySignature(): string;
+export declare function storyboardDocumentStabilitySignature(
+  volatileSelectors?: readonly string[],
+): string;
 export declare function storyboardCaptureCandidateTexts(
   element: Element,
 ): string[];