recordable 0.2.0 → 0.4.0

package/dist/browser/dom.js

@@ -1,11 +1,34 @@
-import { isPositionValue, resolveTarget } from "../targets.js";
-/** Resolve a target and wait for the element to exist in the DOM, then return its handle. */
+import { isPositionValue, resolveTarget } from "./targets.js";
+import { RecordableError } from "../errors.js";
+/** Jitter spread as a fraction of an element's dimension (±20% of each side). */
+const JITTER_FRACTION = 0.4;
+/** Frame interval in ms (≈ one 60fps frame). */
+const FRAME_MS = 16;
+/** Default viewport height (px) when the page has no viewport set. */
+const DEFAULT_VIEWPORT_HEIGHT = 900;
+/** Resolve a target and wait for the element to be *visible* in any frame, then
+ *  return its handle.
+ *
+ *  Two reasons this is more than a bare `page.locator(...).waitHandle()`:
+ *  - Visibility (not mere existence): callers immediately read `boundingBox()`
+ *    to click/scroll, but Puppeteer's default locator resolves the instant the
+ *    node enters the DOM (`waitForSelector(..., {visible:false})`) — so an
+ *    element inserted-but-not-yet-laid-out yields a null box. `setVisibility`
+ *    makes it wait for a real layout box.
+ *  - Frames: modal dialogs (e.g. APEX `apex.navigation.dialog`) render their
+ *    content in an `<iframe>`. The top frame can hold a hidden placeholder with
+ *    the same id, so we race every frame and take the first *visible* match.
+ *    An iframe element's `boundingBox()` is reported in main-frame coordinates,
+ *    so the coordinate-based click still lands correctly. */
 export async function getHandle(page, target) {
+    const selector = resolveTarget(target);
     try {
-        return await page.locator(resolveTarget(target)).waitHandle();
+        return await Promise.any(page
+            .frames()
+            .map((f) => f.locator(selector).setVisibility("visible").waitHandle()));
     }
     catch {
-        throw new Error(`Could not find target: "${target}"`);
+        throw new RecordableError("TARGET_NOT_FOUND", `Could not find target: "${target}"`);
     }
 }
 /** Centre coords of a target element, jittered up to 20% of each dimension. */
@@ -13,8 +36,8 @@ export async function getElementCenter(page, target) {
     const handle = await getHandle(page, target);
     const box = await handle.boundingBox();
     if (!box)
-        throw new Error(`No bounding box for "${target}"`);
-    const offset = (range) => (Math.random() - 0.5) * range * 0.4;
+        throw new RecordableError("TARGET_NOT_FOUND", `No bounding box for "${target}"`);
+    const offset = (range) => (Math.random() - 0.5) * range * JITTER_FRACTION;
     return {
         x: box.x + box.width / 2 + offset(box.width),
         y: box.y + box.height / 2 + offset(box.height),
@@ -54,81 +77,160 @@ export async function originToCoords(page, origin) {
         return { x: (vw * px) / 100, y: (vh * py) / 100 };
     }, origin);
 }
-/** Animate the page's scroll position to `targetY` over `duration` ms with an ease curve. */
-export async function smoothScroll(page, targetY, duration) {
-    await page.evaluate(({ targetY, duration }) => {
+/**
+ * Animate a scroller's vertical position to `targetTop` over `duration` ms with an
+ * ease curve. `container` null scrolls the window; a handle scrolls that element's
+ * `scrollTop`. The target is clamped to the scroller's range.
+ */
+export async function smoothScroll(page, targetTop, duration, container = null) {
+    await page.evaluate(
+    // frameMs is passed in: a module-level const isn't visible inside this
+    // browser-context closure.
+    (el, { targetTop, duration, frameMs }) => {
         return new Promise((resolve) => {
-            const startY = window.scrollY;
-            const dist = targetY - startY;
-            const frames = Math.ceil(duration / 16);
+            const max = el
+                ? el.scrollHeight - el.clientHeight
+                : document.documentElement.scrollHeight - window.innerHeight;
+            const end = Math.max(0, Math.min(targetTop, max));
+            const startY = el ? el.scrollTop : window.scrollY;
+            const dist = end - startY;
+            const frames = Math.ceil(duration / frameMs);
             let i = 0;
             const id = setInterval(() => {
                 i++;
                 const p = Math.min(i / frames, 1);
                 const e = p < 0.5 ? 4 * p * p * p : (p - 1) * (2 * p - 2) * (2 * p - 2) + 1;
-                window.scrollTo(0, startY + dist * e);
+                const y = startY + dist * e;
+                if (el)
+                    el.scrollTop = y;
+                else
+                    window.scrollTo(0, y);
                 if (p >= 1) {
                     clearInterval(id);
                     resolve();
                 }
-            }, 16);
+            }, frameMs);
         });
-    }, { targetY, duration });
+    }, container, { targetTop, duration, frameMs: FRAME_MS });
 }
 /**
- * Smooth-scroll to an element or position:
- * - `"top"` / `"bottom"` → page extremes
- * - number → absolute Y pixel position
- * - CSS selector or `text:` prefix → element centred in the viewport
+ * Smooth-scroll to an element or position. Without `container` the window scrolls;
+ * with one, `target` is resolved against that scroll container instead:
+ * - `"top"` / `"bottom"` → scroller extremes
+ * - number → absolute scrollTop (px)
+ * - CSS selector or `text:` prefix → element centred within the scroller
  */
-export async function smoothScrollToTarget(page, target, duration) {
+export async function smoothScrollToTarget(page, target, duration, container) {
+    const scroller = container ? await getHandle(page, container) : null;
     if (typeof target === "number")
-        return smoothScroll(page, target, duration);
+        return smoothScroll(page, target, duration, scroller);
     if (target === "top")
-        return smoothScroll(page, 0, duration);
+        return smoothScroll(page, 0, duration, scroller);
     if (target === "bottom") {
-        const bottom = await page.evaluate(() => document.body.scrollHeight);
-        return smoothScroll(page, bottom, duration);
+        const bottom = await page.evaluate((el) => (el ? el.scrollHeight : document.body.scrollHeight), scroller);
+        return smoothScroll(page, bottom, duration, scroller);
     }
     const handle = await getHandle(page, target);
-    const y = await page.evaluate((el, vh) => {
+    const top = await page.evaluate((el, scrollEl, vh) => {
         const rect = el.getBoundingClientRect();
+        if (scrollEl) {
+            // Centre the child within the container's visible area.
+            const box = scrollEl.getBoundingClientRect();
+            return (scrollEl.scrollTop +
+                (rect.top - box.top) +
+                rect.height / 2 -
+                scrollEl.clientHeight / 2);
+        }
         return window.scrollY + rect.top + rect.height / 2 - vh / 2;
-    }, handle, page.viewport()?.height ?? 900);
-    return smoothScroll(page, y, duration);
+    }, handle, scroller, page.viewport()?.height ?? DEFAULT_VIEWPORT_HEIGHT);
+    return smoothScroll(page, top, duration, scroller);
+}
+/** The scrollTop that brings the element comfortably into the scroller's view, or
+ *  null when it's already comfortably visible. Pure geometry, shared by the window
+ *  and container passes so both reveal an element the same way. */
+function comfortTarget(m, margin) {
+    const { relTop, height, vh, scrollTop } = m;
+    const relBottom = relTop + height;
+    const comfort = margin * 2;
+    if (relTop >= comfort && relBottom <= vh - comfort)
+        return null;
+    // Tall element: top-align with margin.
+    if (height > vh - margin * 2)
+        return scrollTop + relTop - margin;
+    // Below the bottom comfort zone: scroll just enough to show it fully (centring
+    // would often overshoot the scroller's max and leave it pinned to the edge).
+    if (relBottom > vh - margin)
+        return scrollTop + relBottom - (vh - margin);
+    // Above the top comfort zone: scroll to show the top.
+    if (relTop < margin)
+        return scrollTop + relTop - margin;
+    // Within the comfort band but not comfortable: centre it.
+    return scrollTop + relTop + height / 2 - vh / 2;
+}
+/** Read the target's position within `container` (an element scroller) or, when
+ *  null, within the window. */
+function readMetrics(page, handle, container) {
+    return page.evaluate((el, c) => {
+        const r = el.getBoundingClientRect();
+        if (c) {
+            const b = c.getBoundingClientRect();
+            return {
+                relTop: r.top - b.top,
+                height: r.height,
+                vh: c.clientHeight,
+                scrollTop: c.scrollTop,
+            };
+        }
+        return {
+            relTop: r.top,
+            height: r.height,
+            vh: window.innerHeight,
+            scrollTop: window.scrollY,
+        };
+    }, handle, container);
+}
+/** The nearest ancestor that actually scrolls vertically (overflow auto/scroll +
+ *  overflowing content), or null if none short of the document — in which case the
+ *  window is the scroller. */
+async function nearestScrollableAncestor(handle) {
+    const h = await handle.evaluateHandle((el) => {
+        let p = el.parentElement;
+        while (p && p !== document.body && p !== document.documentElement) {
+            const oy = getComputedStyle(p).overflowY;
+            if ((oy === "auto" || oy === "scroll" || oy === "overlay") &&
+                p.scrollHeight > p.clientHeight)
+                return p;
+            p = p.parentElement;
+        }
+        return null;
+    });
+    const el = h.asElement();
+    if (!el)
+        await h.dispose();
+    return el;
 }
 /**
- * Scroll `target` into view if it lies outside the visible viewport (keeping
- * `margin` px clear on each side). No-op when the element is already fully
- * visible. `speed` (px/s) sets the scroll duration.
+ * Scroll `target` into view if it lies outside the visible area (keeping `margin`
+ * px clear on each side). No-op when already comfortably visible. `speed` (px/s)
+ * sets the scroll duration. Scrolls the target's nearest scrollable container
+ * first (so it's revealed inside a modal / sidebar / pane), then the window so the
+ * container itself is on screen.
  */
 export async function scrollIntoView(page, target, margin, speed) {
     const handle = await getHandle(page, target);
-    const scrollY = await page.evaluate((el, margin) => {
-        const rect = el.getBoundingClientRect();
-        const vh = window.innerHeight;
-        const comfort = margin * 2;
-        if (rect.top >= comfort && rect.bottom <= vh - comfort)
-            return null;
-        // Tall element: top-align with margin
-        if (rect.height > vh - margin * 2)
-            return window.scrollY + rect.top - margin;
-        // Element extends below the bottom comfort zone: scroll just enough to
-        // show it fully, rather than trying to centre it (which often overshoots
-        // the page's max scroll and leaves the element at the viewport edge).
-        if (rect.bottom > vh - margin)
-            return window.scrollY + rect.bottom - (vh - margin);
-        // Element extends above the top comfort zone: scroll to show top
-        if (rect.top < margin)
-            return window.scrollY + rect.top - margin;
-        // In view but within the comfort band: centre it
-        return window.scrollY + rect.top + rect.height / 2 - vh / 2;
-    }, handle, margin);
-    if (scrollY === null)
-        return;
-    const currentY = await page.evaluate(() => window.scrollY);
-    const dist = Math.abs(scrollY - currentY);
-    const duration = Math.max(200, (dist / speed) * 1000);
-    await smoothScroll(page, scrollY, duration);
+    const container = await nearestScrollableAncestor(handle);
+    const reveal = async (scroller) => {
+        const metrics = await readMetrics(page, handle, scroller);
+        const top = comfortTarget(metrics, margin);
+        if (top === null)
+            return;
+        const dist = Math.abs(top - metrics.scrollTop);
+        const duration = Math.max(200, (dist / speed) * 1000);
+        await smoothScroll(page, top, duration, scroller);
+    };
+    if (container)
+        await reveal(container);
+    await reveal(null);
+    await container?.dispose();
 }
 //# sourceMappingURL=dom.js.map

package/dist/browser/dom.js.map

@@ -1 +1 @@
-{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../src/browser/dom.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../src/browser/dom.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,iFAAiF;AACjF,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,gDAAgD;AAChD,MAAM,QAAQ,GAAG,EAAE,CAAC;AACpB,sEAAsE;AACtE,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAQpC;;;;;;;;;;;;;6DAa6D;AAC7D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAU,EAAE,MAAc;IACxD,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,GAAG,CACtB,IAAI;aACD,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC,CACzE,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,eAAe,CACvB,kBAAkB,EAClB,2BAA2B,MAAM,GAAG,CACrC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAU,EACV,MAAc;IAEd,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,CAAC,GAAG;QACN,MAAM,IAAI,eAAe,CACvB,kBAAkB,EAClB,wBAAwB,MAAM,GAAG,CAClC,CAAC;IACJ,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,EAAE,CAC/B,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,KAAK,GAAG,eAAe,CAAC;IAClD,OAAO;QACL,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;QAC5C,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAU,EACV,MAAc;IAEd,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;QAAE,OAAO,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpE,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE;QAC9B,MAAM,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC;QAC7B,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACxD,MAAM,EAAE,GAA2B;YACjC,IAAI,EAAE,CAAC;YACP,GAAG,EAAE,CAAC;YACN,MAAM,EAAE,EAAE;YACV,KAAK,EAAE,GAAG;YACV,MAAM,EAAE,GAAG;SACZ,CAAC;QACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;YACnB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAC1C,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,QAAQ;gBAC/B,OAAO,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC;YAC1C,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,OAAO;gBAC/B,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;YAC1C,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC;QAClD,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAC3E,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC3C,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC3C,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC;IACpD,CAAC,EAAE,MAAM,CAAC,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAU,EACV,SAAiB,EACjB,QAAgB,EAChB,YAA2C,IAAI;IAE/C,MAAM,IAAI,CAAC,QAAQ;IACjB,uEAAuE;IACvE,2BAA2B;IAC3B,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE;QACvC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YACnC,MAAM,GAAG,GAAG,EAAE;gBACZ,CAAC,CAAC,EAAE,CAAC,YAAY,GAAG,EAAE,CAAC,YAAY;gBACnC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC;YAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;YAClD,MAAM,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;YAClD,MAAM,IAAI,GAAG,GAAG,GAAG,MAAM,CAAC;YAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,CAAC;YAC7C,IAAI,CAAC,GAAG,CAAC,CAAC;YACV,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE;gBAC1B,CAAC,EAAE,CAAC;gBACJ,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;gBAClC,MAAM,CAAC,GACL,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;gBACpE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC;gBAC5B,IAAI,EAAE;oBAAE,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC;;oBACpB,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC3B,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;oBACX,aAAa,CAAC,EAAE,CAAC,CAAC;oBAClB,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC,EAAE,OAAO,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC,EACD,SAAS,EACT,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAC3C,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAU,EACV,MAAuB,EACvB,QAAgB,EAChB,SAAkB;IAElB,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAErE,IAAI,OAAO,MAAM,KAAK,QAAQ;QAC5B,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACxD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACvE,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAChC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,EAC3D,QAAQ,CACT,CAAC;QACF,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAC7B,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE;QACnB,MAAM,IAAI,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;QACxC,IAAI,QAAQ,EAAE,CAAC;YACb,wDAAwD;YACxD,MAAM,GAAG,GAAG,QAAQ,CAAC,qBAAqB,EAAE,CAAC;YAC7C,OAAO,CACL,QAAQ,CAAC,SAAS;gBAClB,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;gBACpB,IAAI,CAAC,MAAM,GAAG,CAAC;gBACf,QAAQ,CAAC,YAAY,GAAG,CAAC,CAC1B,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC9D,CAAC,EACD,MAAM,EACN,QAAQ,EACR,IAAI,CAAC,QAAQ,EAAE,EAAE,MAAM,IAAI,uBAAuB,CACnD,CAAC;IACF,OAAO,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACrD,CAAC;AAWD;;mEAEmE;AACnE,SAAS,aAAa,CAAC,CAAgB,EAAE,MAAc;IACrD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC;IAC3B,IAAI,MAAM,IAAI,OAAO,IAAI,SAAS,IAAI,EAAE,GAAG,OAAO;QAAE,OAAO,IAAI,CAAC;IAChE,uCAAuC;IACvC,IAAI,MAAM,GAAG,EAAE,GAAG,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IACjE,+EAA+E;IAC/E,6EAA6E;IAC7E,IAAI,SAAS,GAAG,EAAE,GAAG,MAAM;QAAE,OAAO,SAAS,GAAG,SAAS,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;IAC1E,sDAAsD;IACtD,IAAI,MAAM,GAAG,MAAM;QAAE,OAAO,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IACxD,0DAA0D;IAC1D,OAAO,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAClD,CAAC;AAED;+BAC+B;AAC/B,SAAS,WAAW,CAClB,IAAU,EACV,MAA8B,EAC9B,SAAwC;IAExC,OAAO,IAAI,CAAC,QAAQ,CAClB,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE;QACR,MAAM,CAAC,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;QACrC,IAAI,CAAC,EAAE,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,CAAC,qBAAqB,EAAE,CAAC;YACpC,OAAO;gBACL,MAAM,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG;gBACrB,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,EAAE,EAAE,CAAC,CAAC,YAAY;gBAClB,SAAS,EAAE,CAAC,CAAC,SAAS;aACvB,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,CAAC,CAAC,GAAG;YACb,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,EAAE,EAAE,MAAM,CAAC,WAAW;YACtB,SAAS,EAAE,MAAM,CAAC,OAAO;SAC1B,CAAC;IACJ,CAAC,EACD,MAAM,EACN,SAAS,CACV,CAAC;AACJ,CAAC;AAED;;8BAE8B;AAC9B,KAAK,UAAU,yBAAyB,CACtC,MAA8B;IAE9B,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE;QAC3C,IAAI,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,IAAI,IAAI,CAAC,KAAK,QAAQ,CAAC,eAAe,EAAE,CAAC;YAClE,MAAM,EAAE,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACzC,IACE,CAAC,EAAE,KAAK,MAAM,IAAI,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,SAAS,CAAC;gBACtD,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY;gBAE/B,OAAO,CAAC,CAAC;YACX,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC;QACtB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,MAAM,EAAE,GAAG,CAAC,CAAC,SAAS,EAAmC,CAAC;IAC1D,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;IAC3B,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAU,EACV,MAAc,EACd,MAAc,EACd,KAAa;IAEb,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,MAAM,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAE1D,MAAM,MAAM,GAAG,KAAK,EAAE,QAAuC,EAAE,EAAE;QAC/D,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC3C,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QACtD,MAAM,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACpD,CAAC,CAAC;IAEF,IAAI,SAAS;QAAE,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IACvC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IAEnB,MAAM,SAAS,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC"}

package/dist/browser/page-zoom.d.ts

@@ -0,0 +1,11 @@
+export interface ZoomExtension {
+    /** Launch args that load the extension. */
+    args: string[];
+    /** Remove the generated temp directory. */
+    cleanup: () => void;
+}
+/** Generate the bundled page-zoom extension for `zoom` and return its launch args
+ *  plus a cleanup. Caller adds `args` to `puppeteer.launch` and calls `cleanup`
+ *  once the browser has closed. */
+export declare function createZoomExtension(zoom: number): ZoomExtension;
+//# sourceMappingURL=page-zoom.d.ts.map

package/dist/browser/page-zoom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-zoom.d.ts","sourceRoot":"","sources":["../../src/browser/page-zoom.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2CAA2C;IAC3C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAiBD;;mCAEmC;AACnC,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAkB/D"}

package/dist/browser/page-zoom.js

@@ -0,0 +1,37 @@
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+// Registers its listeners synchronously at top level (MV3 requirement) and
+// re-applies on create + every load — page zoom is per-origin persistent, so this
+// covers same-origin navigations and any `followNewTab` tabs.
+const background = (zoom) => `
+const ZOOM = ${zoom};
+const apply = (id) => chrome.tabs.setZoom(id, ZOOM).catch(() => {});
+chrome.tabs.onCreated.addListener((t) => apply(t.id));
+chrome.tabs.onUpdated.addListener((id, info) => {
+  if (info.status === "loading" || info.status === "complete") apply(id);
+});
+chrome.runtime.onInstalled.addListener(() =>
+  chrome.tabs.query({}, (tabs) => tabs.forEach((t) => apply(t.id))),
+);
+`;
+/** Generate the bundled page-zoom extension for `zoom` and return its launch args
+ *  plus a cleanup. Caller adds `args` to `puppeteer.launch` and calls `cleanup`
+ *  once the browser has closed. */
+export function createZoomExtension(zoom) {
+    const dir = mkdtempSync(join(tmpdir(), "recordable-zoom-"));
+    writeFileSync(join(dir, "manifest.json"), JSON.stringify({
+        manifest_version: 3,
+        name: "recordable-page-zoom",
+        version: "1.0",
+        permissions: ["tabs"],
+        host_permissions: ["<all_urls>"],
+        background: { service_worker: "bg.js" },
+    }));
+    writeFileSync(join(dir, "bg.js"), background(zoom));
+    return {
+        args: [`--disable-extensions-except=${dir}`, `--load-extension=${dir}`],
+        cleanup: () => rmSync(dir, { recursive: true, force: true }),
+    };
+}
+//# sourceMappingURL=page-zoom.js.map

package/dist/browser/page-zoom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-zoom.js","sourceRoot":"","sources":["../../src/browser/page-zoom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAwBjC,2EAA2E;AAC3E,kFAAkF;AAClF,8DAA8D;AAC9D,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC;eACtB,IAAI;;;;;;;;;CASlB,CAAC;AAEF;;mCAEmC;AACnC,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC5D,aAAa,CACX,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,EAC1B,IAAI,CAAC,SAAS,CAAC;QACb,gBAAgB,EAAE,CAAC;QACnB,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,CAAC,MAAM,CAAC;QACrB,gBAAgB,EAAE,CAAC,YAAY,CAAC;QAChC,UAAU,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE;KACxC,CAAC,CACH,CAAC;IACF,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,OAAO;QACL,IAAI,EAAE,CAAC,+BAA+B,GAAG,EAAE,EAAE,oBAAoB,GAAG,EAAE,CAAC;QACvE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;KAC7D,CAAC;AACJ,CAAC"}

package/dist/browser/play-button.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"play-button.d.ts","sourceRoot":"","sources":["../../src/browser/play-button.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,wBAAwB,CAAC;AACpD,eAAO,MAAM,YAAY,uBAAuB,CAAC;AA0EjD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,GACd,MAAM,CAGR"}
+{"version":3,"file":"play-button.d.ts","sourceRoot":"","sources":["../../src/browser/play-button.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,wBAAwB,CAAC;AACpD,eAAO,MAAM,YAAY,uBAAuB,CAAC;AAsEjD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,GACd,MAAM,CAGR"}

package/dist/browser/play-button.js.map

@@ -1 +1 @@
-{"version":3,"file":"play-button.js","sourceRoot":"","sources":["../../src/browser/play-button.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AACpD,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAEjD;;;GAGG;AACH,SAAS,gBAAgB,CACvB,OAAe,EACf,EAAU,EACV,OAAe;IAEf,wDAAwD;IACxD,IAAI,MAAM,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO;IACrC,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YAAE,OAAO;QACxC,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG;YACnB,gBAAgB;YAChB,UAAU;YACV,2EAA2E;YAC3E,iEAAiE;YACjE,UAAU;YACV,4BAA4B;YAC5B,oBAAoB;YACpB,qBAAqB;YACrB,cAAc;YACd,oBAAoB;YACpB,UAAU;YACV,6BAA6B;YAC7B,gCAAgC;YAChC,YAAY;YACZ,qBAAqB;YACrB,uCAAuC;YACvC,yDAAyD;SAC1D,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACZ,MAAM,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC7C,GAAG,CAAC,KAAK,CAAC,OAAO,GAAG;YAClB,WAAW;YACX,gBAAgB;YAChB,qBAAqB;YACrB,oBAAoB;YACpB,wBAAwB;YACxB,YAAY;YACZ,aAAa;YACb,mBAAmB;YACnB,oBAAoB;YACpB,YAAY;YACZ,gBAAgB;SACjB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACZ,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC;QACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAC7C,KAAK,CAAC,WAAW,GAAG,OAAO,CAAC;QAC5B,KAAK,CAAC,KAAK,CAAC,OAAO;YACjB,gEAAgE,CAAC;QACnE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,MAAM,IAAI,GAAG,GAAG,EAAE;YAChB,IAAI,KAAK;gBAAE,OAAO;YAClB,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,MAAM,EAAE,GAAI,MAAgD,CAAC,OAAO,CAAC,CAAC;YACtE,IAAI,OAAO,EAAE,KAAK,UAAU;gBAAE,EAAE,EAAE,CAAC;QACrC,CAAC,CAAC;QACF,sEAAsE;QACtE,iEAAiE;QACjE,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACpC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC,CAAC;IACF,IAAI,QAAQ,CAAC,IAAI;QAAE,KAAK,EAAE,CAAC;;QACtB,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,EAAU,EACV,OAAe;IAEf,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5E,OAAO,sCAAsC,gBAAgB,CAAC,QAAQ,EAAE,KAAK,IAAI,SAAS,CAAC;AAC7F,CAAC"}
+{"version":3,"file":"play-button.js","sourceRoot":"","sources":["../../src/browser/play-button.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,qBAAqB,CAAC;AACpD,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAEjD;;;GAGG;AACH,SAAS,gBAAgB,CAAC,OAAe,EAAE,EAAU,EAAE,OAAe;IACpE,wDAAwD;IACxD,IAAI,MAAM,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO;IACrC,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YAAE,OAAO;QACxC,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG;YACnB,gBAAgB;YAChB,UAAU;YACV,2EAA2E;YAC3E,iEAAiE;YACjE,UAAU;YACV,4BAA4B;YAC5B,oBAAoB;YACpB,qBAAqB;YACrB,cAAc;YACd,oBAAoB;YACpB,UAAU;YACV,6BAA6B;YAC7B,gCAAgC;YAChC,YAAY;YACZ,qBAAqB;YACrB,uCAAuC;YACvC,yDAAyD;SAC1D,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACZ,MAAM,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC7C,GAAG,CAAC,KAAK,CAAC,OAAO,GAAG;YAClB,WAAW;YACX,gBAAgB;YAChB,qBAAqB;YACrB,oBAAoB;YACpB,wBAAwB;YACxB,YAAY;YACZ,aAAa;YACb,mBAAmB;YACnB,oBAAoB;YACpB,YAAY;YACZ,gBAAgB;SACjB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACZ,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC;QACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAC7C,KAAK,CAAC,WAAW,GAAG,OAAO,CAAC;QAC5B,KAAK,CAAC,KAAK,CAAC,OAAO;YACjB,gEAAgE,CAAC;QACnE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,MAAM,IAAI,GAAG,GAAG,EAAE;YAChB,IAAI,KAAK;gBAAE,OAAO;YAClB,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,MAAM,EAAE,GAAI,MAAgD,CAAC,OAAO,CAAC,CAAC;YACtE,IAAI,OAAO,EAAE,KAAK,UAAU;gBAAE,EAAE,EAAE,CAAC;QACrC,CAAC,CAAC;QACF,sEAAsE;QACtE,iEAAiE;QACjE,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACpC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC,CAAC;IACF,IAAI,QAAQ,CAAC,IAAI;QAAE,KAAK,EAAE,CAAC;;QACtB,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,EAAU,EACV,OAAe;IAEf,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5E,OAAO,sCAAsC,gBAAgB,CAAC,QAAQ,EAAE,KAAK,IAAI,SAAS,CAAC;AAC7F,CAAC"}

package/dist/browser/runtime.d.ts

@@ -25,19 +25,34 @@ export declare class Runtime {
     restoreCursor(page: Page): Promise<void>;
     visit(page: Page, url: string, options?: GoToOptions): Promise<void>;
     waitFor(page: Page, target: string, options?: WaitForOptions): Promise<void>;
-    click(page: Page, target: string, options?: ClickOptions): Promise<void>;
+    /** Click a target. Returns the new tab's `Page` when `followNewTab` is set and the
+     *  click opened one — the session then switches recording to it. Otherwise void. */
+    click(page: Page, target: string, options?: ClickOptions): Promise<Page | void>;
+    /**
+     * Click a link that opens a new tab and resolve to the new `Page` (or warn and
+     * return void if none appears). The popup listener is armed *before* the click so a
+     * fast open can't be missed. The new tab is *not* waited on here — the session seals
+     * the current segment first, then waits for the load off-camera so it's trimmed.
+     */
+    private _clickNewTab;
+    /** Resolve to the next popup `page.once("popup")` opens, or null after `timeout`.
+     *  A late timer after the popup resolves is a harmless no-op; unref it so it can't
+     *  hold the process open. */
+    private _waitForPopup;
     hover(page: Page, target: string): Promise<void>;
     type(page: Page, target: string, text: string, options?: {
         duration?: number;
     }): Promise<void>;
     clear(page: Page, target: string): Promise<void>;
     select(page: Page, target: string, value: string): Promise<void>;
+    private _optionValue;
     key(page: Page, key: string): Promise<void>;
     mouse(page: Page, target: string | {
         x: number;
         y: number;
     }): Promise<void>;
     scroll(page: Page, target: string | number, options?: {
+        container?: string;
         duration?: number;
     }): Promise<void>;
     zoomTo(page: Page, level: number, options?: {
@@ -64,6 +79,11 @@ export declare class Runtime {
     private _moveTo;
     /** Scroll a target into view using the configured margin/speed. */
     private _scrollIntoView;
+    /** Fragile-selector lint: warn (once) when a target resolves to more than one
+     *  element, then act on the first. Best-effort — it does not wait for the
+     *  element, so it stays silent if the matches haven't rendered yet, and never
+     *  throws (a genuine miss surfaces later at getHandle). */
+    private checkAmbiguous;
     /**
      * Block until the user resumes — by clicking the in-page ▶ Play button, or by
      * pressing Enter in the *terminal*. The in-page button is click-only so the live

package/dist/browser/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/browser/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/browser/runtime.ts"],"names":[],"mappings":"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"}

package/dist/browser/runtime.js

@@ -1,6 +1,7 @@
 import { sleep, truncate } from "../utils.js";
-import { resolveTarget } from "../targets.js";
-import { getElementCenter, originToCoords, scrollIntoView, smoothScrollToTarget, } from "./dom.js";
+import { resolveTarget, parseOptionSpec } from "./targets.js";
+import { RecordableError } from "../errors.js";
+import { getElementCenter, getHandle, originToCoords, scrollIntoView, smoothScrollToTarget, } from "./dom.js";
 import { Cursor } from "./cursor.js";
 import { jitter, typingDuration, typingGaps, PRE_CLICK_MS } from "../timing.js";
 import { playButtonScript, PLAY_BINDING, PLAY_BUTTON_ID, } from "./play-button.js";
@@ -64,6 +65,7 @@ export class Runtime {
     async waitFor(page, target, options = {}) {
         const { state = "visible", timeout = this.getCfg().visitTimeout } = options;
         this.log("WaitFor", `${target} (${state})`);
+        await this.checkAmbiguous(page, target);
         await page.waitForSelector(resolveTarget(target), {
             timeout,
             visible: state === "visible",
@@ -72,12 +74,50 @@ export class Runtime {
         await this.injectCursor(page);
     }
     // ─── Interactions ──────────────────────────────────────────────────────────
+    /** Click a target. Returns the new tab's `Page` when `followNewTab` is set and the
+     *  click opened one — the session then switches recording to it. Otherwise void. */
     async click(page, target, options = {}) {
         this.log("Click", target);
+        await this.checkAmbiguous(page, target);
+        if (options.followNewTab)
+            return this._clickNewTab(page, target, options);
         await this._click(page, target, options);
     }
+    /**
+     * Click a link that opens a new tab and resolve to the new `Page` (or warn and
+     * return void if none appears). The popup listener is armed *before* the click so a
+     * fast open can't be missed. The new tab is *not* waited on here — the session seals
+     * the current segment first, then waits for the load off-camera so it's trimmed.
+     */
+    async _clickNewTab(page, target, options) {
+        const timeout = options.timeout ?? this.getCfg().visitTimeout;
+        const popup = this._waitForPopup(page, timeout);
+        // The nav happens in the new tab, so don't wait for a same-tab navigation here.
+        await this._click(page, target, { ...options, waitForNav: false });
+        const newPage = await popup;
+        if (!newPage) {
+            this.log.warn(`click: no new tab opened for "${target}" — staying on the current tab`);
+            return;
+        }
+        return newPage;
+    }
+    /** Resolve to the next popup `page.once("popup")` opens, or null after `timeout`.
+     *  A late timer after the popup resolves is a harmless no-op; unref it so it can't
+     *  hold the process open. */
+    _waitForPopup(page, timeout) {
+        return new Promise((resolve) => {
+            const onPopup = (p) => resolve(p ?? null);
+            page.once("popup", onPopup);
+            const timer = setTimeout(() => {
+                page.off("popup", onPopup);
+                resolve(null);
+            }, timeout);
+            timer.unref?.();
+        });
+    }
     async hover(page, target) {
         this.log("Hover", target);
+        await this.checkAmbiguous(page, target);
         if (this.getCfg().autoScroll)
             await this._scrollIntoView(page, target);
         const { x, y } = await getElementCenter(page, target);
@@ -85,6 +125,7 @@ export class Runtime {
     }
     async type(page, target, text, options = {}) {
         this.log("Type", `${target}  "${truncate(text)}"`);
+        await this.checkAmbiguous(page, target);
         await this._click(page, target);
         const total = options.duration ?? typingDuration(text, this.getCfg().typingSpeed);
         const gaps = typingGaps(text, this.getCfg().typingSpeed, total);
@@ -99,6 +140,7 @@ export class Runtime {
     }
     async clear(page, target) {
         this.log("Clear", target);
+        await this.checkAmbiguous(page, target);
         await this._click(page, target);
         const mod = process.platform === "darwin" ? "Meta" : "Control";
         await page.keyboard.down(mod);
@@ -108,6 +150,7 @@ export class Runtime {
     }
     async select(page, target, value) {
         this.log("Select", `${target}  ${value}`);
+        await this.checkAmbiguous(page, target);
         if (this.getCfg().autoScroll)
             await this._scrollIntoView(page, target);
         const { x, y } = await getElementCenter(page, target);
@@ -116,13 +159,38 @@ export class Runtime {
             await sleep(jitter(PRE_CLICK_MS));
             await this.cursor.clickEffect(page);
         }
-        await page.select(target, value);
+        // Resolve the handle through getHandle (frame-aware) and act on it directly —
+        // page.select() / page.$eval() only see the main frame, so a <select> inside
+        // an iframe (e.g. a dialog) would miss it or hit a same-id placeholder.
+        const el = await getHandle(page, target);
+        await el.select(await this._optionValue(el, target, value));
+    }
+    // Map a select value-spec to the concrete option `value` Puppeteer expects.
+    // Literal values pass through; `:option-index/-label(...)` read the live
+    // `<select>` via the element's own frame.
+    async _optionValue(el, target, value) {
+        const spec = parseOptionSpec(value);
+        if (!spec)
+            return value;
+        const resolved = await el.evaluate((node, spec) => {
+            const opts = [...node.options];
+            const hit = "index" in spec
+                ? opts[spec.index - 1]
+                : opts.find((o) => o.textContent?.trim() === spec.label);
+            return hit?.value;
+        }, spec);
+        if (resolved == null) {
+            throw new RecordableError("CONFIG_INVALID", `select("${target}", "${value}"): no matching <option>.`);
+        }
+        return resolved;
     }
     async key(page, key) {
         this.log("Key", key);
         await page.keyboard.press(key);
     }
     async mouse(page, target) {
+        if (typeof target === "string")
+            await this.checkAmbiguous(page, target);
         const { x, y } = typeof target === "string"
             ? await getElementCenter(page, target)
             : target;
@@ -132,7 +200,11 @@ export class Runtime {
     // ─── Scrolling ─────────────────────────────────────────────────────────────
     async scroll(page, target, options = {}) {
         this.log("Scroll", String(target));
-        await smoothScrollToTarget(page, target, options.duration ?? this.getCfg().scrollDuration);
+        if (typeof target === "string" && target !== "top" && target !== "bottom")
+            await this.checkAmbiguous(page, target);
+        if (options.container)
+            await this.checkAmbiguous(page, options.container);
+        await smoothScrollToTarget(page, target, options.duration ?? this.getCfg().scrollDuration, options.container);
     }
     // ─── Zoom ──────────────────────────────────────────────────────────────────
     async zoomTo(page, level, options = {}) {
@@ -217,6 +289,21 @@ export class Runtime {
         const cfg = this.getCfg();
         return scrollIntoView(page, target, cfg.scrollMargin, cfg.scrollSpeed);
     }
+    /** Fragile-selector lint: warn (once) when a target resolves to more than one
+     *  element, then act on the first. Best-effort — it does not wait for the
+     *  element, so it stays silent if the matches haven't rendered yet, and never
+     *  throws (a genuine miss surfaces later at getHandle). */
+    async checkAmbiguous(page, target) {
+        try {
+            const matches = await page.$$(resolveTarget(target));
+            if (matches.length > 1)
+                this.log.warn(`"${target}" matched ${matches.length} elements; using the first`);
+            await Promise.all(matches.map((m) => m.dispose()));
+        }
+        catch {
+            // ignore: resolution failures are reported where the element is fetched
+        }
+    }
     // ─── Resume gate (▶ Play button) ─────────────────────────────────────────────
     /**
      * Block until the user resumes — by clicking the in-page ▶ Play button, or by