@pygmalionjs/pygmalion 0.6.5 → 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
@@ -160,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

@@ -423,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.5",
+  "version": "0.6.6",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {