@pygmalionjs/pygmalion 0.6.4 → 0.6.6

package/docs/screen-state-contract.md

@@ -37,6 +37,19 @@ Use a same-frame axis when all of these are true:
 Pseudo states such as hover, keyboard focus, and pointer active are always
 interaction states. They must not become duplicate frames.
 
+## Frame size
+
+The W and H controls in the frame inspector change the frame viewport, not the
+canvas camera. A committed size is part of the frame fingerprint and its exact
+capture recipe. The request carries the route, width, height, conditions, and
+interactions that produced that fingerprint, and a returned artifact is seeded
+under that requested recipe instead of the authored catalog key.
+
+This distinction is observable: resizing a frame may change responsive layout,
+while changing canvas zoom only changes how large the same frame appears in the
+editor. Hosts that implement an on-demand capture adapter must apply the
+requested `route`, `width`, and `height` overrides before launching the capture.
+
 ## Automatic pseudo-state coverage
 
 Pygmalion discovers pseudo-state surfaces while it serializes a screen. Every
@@ -66,15 +79,18 @@ Pygmalion discovers visible CSS animation owners, animated pseudo elements,
 matching animation rules, and Web Animations API targets while it serializes a
 screen. It stamps every target into the inert preview and lists them under
 **Motion**. Reviewers can play all motion together, isolate one target, pause
-it, reset it to the deterministic capture point, or scrub through one cycle
+it, reset it to the deterministic visual baseline, or scrub through one cycle
 with the Phase control.
 
 Motion discovery has no semantic or size threshold. Small progress dots,
 ordinary status indicators, shimmer bars, and full-surface animation receive
-the same control. The default preview remains frozen at the start of its
-animation timeline so screenshots and visual comparisons stay repeatable.
-Using a Motion control temporarily switches an imported frame back to its
-source DOM preview, including while the editor is in Editing mode.
+the same control. The default preview holds finite animations at their terminal
+state and repeating animations at the start of their cycle. This keeps entrance
+motion from hiding the base UI while screenshots and visual comparisons remain
+repeatable. Play, Pause, or Phase explicitly enters the motion timeline at the
+selected phase; Reset restores the visual baseline. Using a Motion control
+temporarily switches an imported frame back to its source DOM preview,
+including while the editor is in Editing mode.
 
 An animation does not need duplicate frames merely to show several points in
 its cycle. Preserve a separate frame only when the motion ends in an independent
@@ -157,6 +173,20 @@ result. This keeps empty strings and maximum-length samples out of the state
 panel while still allowing a search input to reproduce a real empty-result
 state.
 
+## Scroll positions
+
+A stable scroll endpoint is an interaction state. Use a `scroll` recipe step
+with absolute `scrollX` and/or `scrollY` coordinates. With no selector the step
+restores the document viewport; a selector targets a specific overflow
+container. An omitted axis keeps its current position.
+
+Absolute coordinates make the endpoint repeatable in both the in-editor replay
+and the capture worker. A free wheel gesture remains transient until the host
+preserves its endpoint as a recipe. The frame inspector enumerates the document
+viewport and independently scrollable nested surfaces. Preserving one records
+both its stable selector and coordinates; the target picker keeps nested list
+or panel scroll distinct from the document viewport.
+
 ## Held pseudo states
 
 Recipes support `hover`, `focus-visible`, and `active` in addition to `focus`.

package/node/storyboard-capture-runtime.mjs

@@ -94,11 +94,40 @@ function throwIfAborted(signal) {
   }
 }
 
-function resetStoryboardAnimations() {
+/**
+ * Holds one-shot motion at its terminal visual state while keeping repeating
+ * motion at a deterministic cycle origin. A frozen screen is the review
+ * baseline, so an entrance animation must not make its own content disappear.
+ *
+ * This function runs through page.evaluate and must remain self-contained.
+ */
+export function settleStoryboardAnimations() {
   for (const animation of document.getAnimations?.({ subtree: true }) ?? []) {
     try {
       animation.pause();
-      animation.currentTime = 0;
+      const timing = animation.effect?.getComputedTiming?.();
+      const computedEndTime = Number(timing?.endTime);
+      if (Number.isFinite(computedEndTime)) {
+        animation.currentTime = Math.max(0, computedEndTime);
+        continue;
+      }
+      if (computedEndTime === Number.POSITIVE_INFINITY) {
+        animation.currentTime = 0;
+        continue;
+      }
+
+      // Browser timing objects expose endTime, but the fallback keeps custom
+      // Animation implementations and older engines deterministic as well.
+      const duration = Number(timing?.duration);
+      const iterations =
+        timing?.iterations == null ? 1 : Number(timing.iterations);
+      const delay = Number(timing?.delay ?? 0);
+      const endDelay = Number(timing?.endDelay ?? 0);
+      const fallbackEndTime =
+        delay + duration * Math.max(0, iterations) + endDelay;
+      animation.currentTime = Number.isFinite(fallbackEndTime)
+        ? Math.max(0, fallbackEndTime)
+        : 0;
     } catch {
       // An animation owned by an unavailable timeline remains CSS-paused.
     }
@@ -112,7 +141,7 @@ async function freezeStoryboardMotion(page, addStyle = true) {
       element.setAttribute('data-pygmalion-preview', 'frozen');
     });
   }
-  await page.evaluate(resetStoryboardAnimations);
+  await page.evaluate(settleStoryboardAnimations);
 }
 
 async function atCaptureStage(stage, task, details = {}) {
@@ -394,6 +423,39 @@ export async function runStoryboardInteraction(page, interaction) {
     return;
   }
 
+  if (interaction.action === 'scroll') {
+    const position = {
+      x: Number.isFinite(interaction.scrollX) ? Math.max(0, interaction.scrollX) : null,
+      y: Number.isFinite(interaction.scrollY) ? Math.max(0, interaction.scrollY) : null,
+    };
+    if (interaction.selector || interaction.text) {
+      const timeoutMs = interaction.timeoutMs ?? 5_000;
+      const target = await waitForCandidateLocator(
+        page,
+        interaction,
+        timeoutMs,
+      );
+      if (!(await targetExists(target, Math.min(timeoutMs, 500)))) {
+        throw new Error(`"${interaction.label}" scroll target was not found.`);
+      }
+      await target.evaluate((element, next) => {
+        const left = next.x ?? element.scrollLeft;
+        const top = next.y ?? element.scrollTop;
+        if (typeof element.scrollTo === 'function') element.scrollTo(left, top);
+        else {
+          element.scrollLeft = left;
+          element.scrollTop = top;
+        }
+      }, position);
+    } else {
+      await page.evaluate((next) => {
+        window.scrollTo(next.x ?? window.scrollX, next.y ?? window.scrollY);
+      }, position);
+    }
+    await page.waitForTimeout(interaction.settleMs ?? 100);
+    return;
+  }
+
   const timeoutMs = interaction.timeoutMs ?? 5_000;
   const target = await waitForCandidateLocator(page, interaction, timeoutMs);
   if (!(await targetExists(target, Math.min(timeoutMs, 500)))) {

package/package.json

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