recordable 0.1.0

package/dist/audio/track.d.ts

@@ -0,0 +1,45 @@
+/** One clip placed on the timeline (recorded-time milliseconds). */
+export interface AudioClip {
+    path: string;
+    startMs: number;
+    durationMs: number;
+    volume?: number;
+}
+/** An ordered set of audio clips, each pinned to a caller-supplied recorded-time
+ *  position. Mixed onto the finished video at finalise by `mix.ts`. */
+export declare class AudioTrack {
+    private readonly clips;
+    /** Number of clips on the track. */
+    get length(): number;
+    /** The clips in document order (read-only view for the mixer). */
+    list(): readonly AudioClip[];
+    /**
+     * Add a clip at `startMs` (recorded time). Probes its duration so the caller
+     * can block for it when `audio({ wait: true })`. Throws if the file is missing.
+     */
+    add(path: string, startMs: number, options?: {
+        volume?: number;
+    }): Promise<{
+        startMs: number;
+        durationMs: number;
+    }>;
+}
+/**
+ * Build the `filter_complex` chain that delays each clip to its `startMs`,
+ * applies volume, and mixes them. Input index `i+1` (input 0 is the video).
+ * Returns the filter parts and the label to `-map` as the output audio.
+ */
+export declare function audioFilterGraph(clips: readonly AudioClip[]): {
+    filters: string[];
+    mapLabel: string;
+};
+/**
+ * Clips that run past the video end (beyond `tolMs` slack). Per the timing
+ * contract the video defines the length, so an overrun is the author's cue to
+ * add a trailing `wait()`; the mixer warns and lets `-t` truncate.
+ */
+export declare function audioOverruns(clips: readonly AudioClip[], videoMs: number, tolMs?: number): {
+    path: string;
+    overMs: number;
+}[];
+//# sourceMappingURL=track.d.ts.map

package/dist/audio/track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../../src/audio/track.ts"],"names":[],"mappings":"AAYA,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;uEACuE;AACvE,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IAEzC,oCAAoC;IACpC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,kEAAkE;IAClE,IAAI,IAAI,SAAS,SAAS,EAAE;IAI5B;;;OAGG;IACG,GAAG,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAOpD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAeA;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,EAAE,MAAM,EACf,KAAK,SAAK,GACT;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,CAOpC"}

package/dist/audio/track.js

@@ -0,0 +1,61 @@
+import { existsSync } from "node:fs";
+import { getDuration } from "../ffmpeg.js";
+import { RecordableError } from "../errors.js";
+/** An ordered set of audio clips, each pinned to a caller-supplied recorded-time
+ *  position. Mixed onto the finished video at finalise by `mix.ts`. */
+export class AudioTrack {
+    clips = [];
+    /** Number of clips on the track. */
+    get length() {
+        return this.clips.length;
+    }
+    /** The clips in document order (read-only view for the mixer). */
+    list() {
+        return this.clips;
+    }
+    /**
+     * Add a clip at `startMs` (recorded time). Probes its duration so the caller
+     * can block for it when `audio({ wait: true })`. Throws if the file is missing.
+     */
+    async add(path, startMs, options = {}) {
+        if (!existsSync(path))
+            throw new RecordableError("FILE_NOT_FOUND", `audio: file not found: ${path}`);
+        const durationMs = (await getDuration(path)) * 1000;
+        this.clips.push({ path, startMs, durationMs, volume: options.volume });
+        return { startMs, durationMs };
+    }
+}
+/**
+ * Build the `filter_complex` chain that delays each clip to its `startMs`,
+ * applies volume, and mixes them. Input index `i+1` (input 0 is the video).
+ * Returns the filter parts and the label to `-map` as the output audio.
+ */
+export function audioFilterGraph(clips) {
+    const labels = [];
+    const filters = clips.map((c, i) => {
+        const chain = [`adelay=${Math.round(c.startMs)}:all=1`];
+        if (c.volume != null && c.volume !== 1)
+            chain.push(`volume=${c.volume}`);
+        labels.push(`[a${i}]`);
+        return `[${i + 1}:a]${chain.join(",")}[a${i}]`;
+    });
+    if (clips.length === 1)
+        return { filters, mapLabel: "a0" };
+    filters.push(`${labels.join("")}amix=inputs=${clips.length}:normalize=0[aout]`);
+    return { filters, mapLabel: "aout" };
+}
+/**
+ * Clips that run past the video end (beyond `tolMs` slack). Per the timing
+ * contract the video defines the length, so an overrun is the author's cue to
+ * add a trailing `wait()`; the mixer warns and lets `-t` truncate.
+ */
+export function audioOverruns(clips, videoMs, tolMs = 50) {
+    const over = [];
+    for (const c of clips) {
+        const overMs = Math.round(c.startMs + c.durationMs - videoMs);
+        if (overMs > tolMs)
+            over.push({ path: c.path, overMs });
+    }
+    return over;
+}
+//# sourceMappingURL=track.js.map

package/dist/audio/track.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.js","sourceRoot":"","sources":["../../src/audio/track.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAkB/C;uEACuE;AACvE,MAAM,OAAO,UAAU;IACJ,KAAK,GAAgB,EAAE,CAAC;IAEzC,oCAAoC;IACpC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,kEAAkE;IAClE,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CACP,IAAY,EACZ,OAAe,EACf,UAA+B,EAAE;QAEjC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YACnB,MAAM,IAAI,eAAe,CAAC,gBAAgB,EAAE,0BAA0B,IAAI,EAAE,CAAC,CAAC;QAChF,MAAM,UAAU,GAAG,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QACpD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACvE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IACjC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA2B;IAI1D,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACjC,MAAM,KAAK,GAAG,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxD,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACzE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAE3D,OAAO,CAAC,IAAI,CACV,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,eAAe,KAAK,CAAC,MAAM,oBAAoB,CAClE,CAAC;IACF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,KAA2B,EAC3B,OAAe,EACf,KAAK,GAAG,EAAE;IAEV,MAAM,IAAI,GAAuC,EAAE,CAAC;IACpD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,UAAU,GAAG,OAAO,CAAC,CAAC;QAC9D,IAAI,MAAM,GAAG,KAAK;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/browser/cursor.d.ts

@@ -0,0 +1,33 @@
+import { type Page } from "puppeteer";
+/** The page's current zoom transform, needed to position the overlay correctly. */
+export interface ZoomState {
+    tx: number;
+    ty: number;
+    s: number;
+}
+/**
+ * An animated cursor overlay drawn into the page. Tracks its own position so
+ * each move can ease from where it last was, and dips on click for a tactile
+ * press effect. Also drives the real Puppeteer mouse so hover/click still fire.
+ */
+export declare class Cursor {
+    private pos;
+    /**
+     * Draw the cursor SVG and hide the native pointer. Idempotent per document.
+     * Renders the overlay at the last-known position (carried across navigations)
+     * and syncs the real mouse there so hover state stays consistent.
+     */
+    inject(page: Page, zoom?: ZoomState): Promise<void>;
+    /** Ease the overlay (and the real mouse) to viewport coords `toX,toY`. */
+    moveTo(page: Page, toX: number, toY: number, zoom: ZoomState): Promise<void>;
+    /**
+     * Convert viewport coords → document coords for the overlay's transform.
+     * When documentElement has a CSS transform (zoom), position:fixed children
+     * are positioned relative to that ancestor (not the viewport) and scroll with
+     * the page, so we add scroll and apply the inverse zoom transform.
+     */
+    private _toDocCoords;
+    /** Briefly scale the cursor down to signal a press. */
+    clickEffect(page: Page): Promise<void>;
+}
+//# sourceMappingURL=cursor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/browser/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAMtC,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAIjB,OAAO,CAAC,GAAG,CAAkB;IAE7B;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAE,SAAkC,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDjF,0EAA0E;IACpE,MAAM,CACV,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,IAAI,CAAC;IAiChB;;;;;OAKG;YACW,YAAY;IAa1B,uDAAuD;IACjD,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAa7C"}

package/dist/browser/cursor.js

@@ -0,0 +1,118 @@
+import { sleep } from "../utils.js";
+import { cursorMoveMs, PRESS_DOWN_MS, PRESS_SETTLE_MS } from "../timing.js";
+const CURSOR_ID = "__recordable_cursor__";
+/**
+ * An animated cursor overlay drawn into the page. Tracks its own position so
+ * each move can ease from where it last was, and dips on click for a tactile
+ * press effect. Also drives the real Puppeteer mouse so hover/click still fire.
+ */
+export class Cursor {
+    // Persisted across injects so the overlay survives navigation: a fresh page
+    // re-injects, and we want the cursor to reappear where it last was (like a
+    // real pointer) rather than snapping to the top-left corner.
+    pos = { x: 0, y: 0 };
+    /**
+     * Draw the cursor SVG and hide the native pointer. Idempotent per document.
+     * Renders the overlay at the last-known position (carried across navigations)
+     * and syncs the real mouse there so hover state stays consistent.
+     */
+    async inject(page, zoom = { tx: 0, ty: 0, s: 1 }) {
+        // Bail early when there's nothing to do or we can't yet: already present, an
+        // iframe, or the new document's <body> hasn't parsed. A too-early call (e.g.
+        // from a navigation event) is a no-op; the next moveTo re-injects when ready.
+        const skip = await page.evaluate((id) => window !== window.parent ||
+            !document.body ||
+            !!document.getElementById(id), CURSOR_ID);
+        if (skip)
+            return;
+        const { cx, cy } = await this._toDocCoords(page, this.pos.x, this.pos.y, zoom);
+        await page.evaluate(({ id, cx, cy }) => {
+            const style = document.createElement("style");
+            style.textContent = `
+          * { cursor: none !important; }
+          #${id} {
+            position: fixed;
+            top: 0; left: 0;
+            margin: -2px 0 0 -4px;
+            z-index: 2147483647;
+            pointer-events: none;
+            will-change: transform;
+            transition: transform 0.15s;
+            filter: drop-shadow(0 1px 2px rgba(0,0,0,0.4));
+          }
+          #${id}.pressing {
+            transform: var(--recordable-pos) scale(0.88) !important;
+            transition: transform 0.08s !important;
+          }
+        `;
+            document.head.appendChild(style);
+            const cursor = document.createElement("div");
+            cursor.id = id;
+            // Place at the carried-over position with no transition, so it appears
+            // there immediately instead of animating in from the corner.
+            cursor.style.transition = "none";
+            cursor.style.setProperty("--recordable-pos", `translate(${cx}px, ${cy}px)`);
+            cursor.style.transform = `translate(${cx}px, ${cy}px)`;
+            cursor.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+          <path d="M4 2 L4 19 L8.5 14.5 L12 22 L14 21 L10.5 13.5 L17 13.5 Z"
+                fill="white" stroke="#1e1b4b" stroke-width="1.2" stroke-linejoin="round"/>
+        </svg>`;
+            document.body.appendChild(cursor);
+        }, { id: CURSOR_ID, cx, cy });
+        await page.mouse.move(this.pos.x, this.pos.y);
+    }
+    /** Ease the overlay (and the real mouse) to viewport coords `toX,toY`. */
+    async moveTo(page, toX, toY, zoom) {
+        // Self-heal: a navigation (incl. click-triggered ones with no following
+        // visit/waitFor) wipes the overlay. Re-inject at the carried position before
+        // animating, so the move is always visible — never an instant, cursor-less jump.
+        await this.inject(page, zoom);
+        const dx = toX - this.pos.x;
+        const dy = toY - this.pos.y;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        const dur = cursorMoveMs(dist);
+        const { cx, cy } = await this._toDocCoords(page, toX, toY, zoom);
+        await page.evaluate(({ id, cx, cy, dur }) => new Promise((resolve) => {
+            const cursor = document.getElementById(id);
+            if (!cursor) {
+                resolve();
+                return;
+            }
+            cursor.style.transition = `transform ${dur}ms cubic-bezier(0.4,0,0.2,1)`;
+            cursor.style.setProperty("--recordable-pos", `translate(${cx}px, ${cy}px)`);
+            cursor.style.transform = `translate(${cx}px, ${cy}px)`;
+            setTimeout(resolve, dur);
+        }), { id: CURSOR_ID, cx, cy, dur });
+        await page.mouse.move(toX, toY);
+        this.pos = { x: toX, y: toY };
+    }
+    /**
+     * Convert viewport coords → document coords for the overlay's transform.
+     * When documentElement has a CSS transform (zoom), position:fixed children
+     * are positioned relative to that ancestor (not the viewport) and scroll with
+     * the page, so we add scroll and apply the inverse zoom transform.
+     */
+    async _toDocCoords(page, x, y, { tx, ty, s }) {
+        const hasTransform = s !== 1 || tx !== 0 || ty !== 0;
+        const scroll = hasTransform
+            ? await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }))
+            : { x: 0, y: 0 };
+        return { cx: (x + scroll.x - tx) / s, cy: (y + scroll.y - ty) / s };
+    }
+    /** Briefly scale the cursor down to signal a press. */
+    async clickEffect(page) {
+        await page.evaluate((id) => {
+            const cursor = document.getElementById(id);
+            if (!cursor)
+                return;
+            cursor.classList.add("pressing");
+            void cursor.offsetWidth;
+        }, CURSOR_ID);
+        await sleep(PRESS_DOWN_MS);
+        await page.evaluate((id) => {
+            document.getElementById(id)?.classList.remove("pressing");
+        }, CURSOR_ID);
+        await sleep(PRESS_SETTLE_MS);
+    }
+}
+//# sourceMappingURL=cursor.js.map

package/dist/browser/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/browser/cursor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE5E,MAAM,SAAS,GAAG,uBAAuB,CAAC;AAS1C;;;;GAIG;AACH,MAAM,OAAO,MAAM;IACjB,4EAA4E;IAC5E,2EAA2E;IAC3E,6DAA6D;IACrD,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAE7B;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,IAAU,EAAE,OAAkB,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;QAC/D,6EAA6E;QAC7E,6EAA6E;QAC7E,8EAA8E;QAC9E,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAC9B,CAAC,EAAE,EAAE,EAAE,CACL,MAAM,KAAK,MAAM,CAAC,MAAM;YACxB,CAAC,QAAQ,CAAC,IAAI;YACd,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,EAC/B,SAAS,CACV,CAAC;QACF,IAAI,IAAI;YAAE,OAAO;QAEjB,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC/E,MAAM,IAAI,CAAC,QAAQ,CACjB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;YACjB,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YAC9C,KAAK,CAAC,WAAW,GAAG;;aAEf,EAAE;;;;;;;;;;aAUF,EAAE;;;;SAIN,CAAC;YACF,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAEjC,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YAC7C,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC;YACf,uEAAuE;YACvE,6DAA6D;YAC7D,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC;YACjC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,kBAAkB,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAC5E,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,aAAa,EAAE,OAAO,EAAE,KAAK,CAAC;YACvD,MAAM,CAAC,SAAS,GAAG;;;eAGZ,CAAC;YACR,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC,EACD,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,EAAE,CAC1B,CAAC;QACF,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,MAAM,CACV,IAAU,EACV,GAAW,EACX,GAAW,EACX,IAAe;QAEf,wEAAwE;QACxE,6EAA6E;QAC7E,iFAAiF;QACjF,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAE9B,MAAM,EAAE,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5B,MAAM,EAAE,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAE/B,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QAEjE,MAAM,IAAI,CAAC,QAAQ,CACjB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,CACtB,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5B,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;YAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,EAAE,CAAC;gBACV,OAAO;YACT,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,aAAa,GAAG,8BAA8B,CAAC;YACzE,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,kBAAkB,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAC5E,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,aAAa,EAAE,OAAO,EAAE,KAAK,CAAC;YACvD,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC,CAAC,EACJ,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,CAC/B,CAAC;QAEF,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,YAAY,CACxB,IAAU,EACV,CAAS,EACT,CAAS,EACT,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAa;QAExB,MAAM,YAAY,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,YAAY;YACzB,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;YACvE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IACtE,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,WAAW,CAAC,IAAU;QAC1B,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE;YACzB,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;YAC3C,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACjC,KAAK,MAAM,CAAC,WAAW,CAAC;QAC1B,CAAC,EAAE,SAAS,CAAC,CAAC;QACd,MAAM,KAAK,CAAC,aAAa,CAAC,CAAC;QAC3B,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE;YACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC5D,CAAC,EAAE,SAAS,CAAC,CAAC;QACd,MAAM,KAAK,CAAC,eAAe,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/browser/dom.d.ts

@@ -0,0 +1,31 @@
+import { type Page } from "puppeteer";
+/** Coordinates in viewport pixels. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** Resolve a target and wait for the element to exist in the DOM, then return its handle. */
+export declare function getHandle(page: Page, target: string): Promise<import("puppeteer").ElementHandle<Element>>;
+/** Centre coords of a target element, jittered up to 20% of each dimension. */
+export declare function getElementCenter(page: Page, target: string): Promise<Point>;
+/**
+ * Resolve an origin string to viewport pixel coordinates.
+ * Accepts CSS position keywords/percentages or an element selector.
+ */
+export declare function originToCoords(page: Page, origin: string): Promise<Point>;
+/** Animate the page's scroll position to `targetY` over `duration` ms with an ease curve. */
+export declare function smoothScroll(page: Page, targetY: number, duration: number): Promise<void>;
+/**
+ * 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
+ */
+export declare function smoothScrollToTarget(page: Page, target: string | number, duration: number): Promise<void>;
+/**
+ * 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.
+ */
+export declare function scrollIntoView(page: Page, target: string, margin: number, speed: number): Promise<void>;
+//# sourceMappingURL=dom.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/browser/dom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAGtC,sCAAsC;AACtC,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,6FAA6F;AAC7F,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,uDAMzD;AAED,+EAA+E;AAC/E,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,CAAC,CAShB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,CAAC,CA4BhB;AAED,6FAA6F;AAC7F,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/dist/browser/dom.js

@@ -0,0 +1,134 @@
+import { isPositionValue, resolveTarget } from "../targets.js";
+/** Resolve a target and wait for the element to exist in the DOM, then return its handle. */
+export async function getHandle(page, target) {
+    try {
+        return await page.locator(resolveTarget(target)).waitHandle();
+    }
+    catch {
+        throw new Error(`Could not find target: "${target}"`);
+    }
+}
+/** Centre coords of a target element, jittered up to 20% of each dimension. */
+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;
+    return {
+        x: box.x + box.width / 2 + offset(box.width),
+        y: box.y + box.height / 2 + offset(box.height),
+    };
+}
+/**
+ * Resolve an origin string to viewport pixel coordinates.
+ * Accepts CSS position keywords/percentages or an element selector.
+ */
+export async function originToCoords(page, origin) {
+    if (!isPositionValue(origin))
+        return getElementCenter(page, origin);
+    return page.evaluate((origin) => {
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
+        const tokens = origin.trim().toLowerCase().split(/\s+/);
+        const kw = {
+            left: 0,
+            top: 0,
+            center: 50,
+            right: 100,
+            bottom: 100,
+        };
+        if (tokens.length === 1) {
+            const [t] = tokens;
+            const p = t in kw ? kw[t] : parseFloat(t);
+            if (t === "top" || t === "bottom")
+                return { x: vw / 2, y: (vh * p) / 100 };
+            if (t === "left" || t === "right")
+                return { x: (vw * p) / 100, y: vh / 2 };
+            return { x: (vw * p) / 100, y: (vh * p) / 100 };
+        }
+        const yAxis = ["top", "bottom"];
+        const [a, b] = yAxis.includes(tokens[0]) ? [tokens[1], tokens[0]] : tokens;
+        const px = a in kw ? kw[a] : parseFloat(a);
+        const py = b in kw ? kw[b] : parseFloat(b);
+        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 }) => {
+        return new Promise((resolve) => {
+            const startY = window.scrollY;
+            const dist = targetY - startY;
+            const frames = Math.ceil(duration / 16);
+            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);
+                if (p >= 1) {
+                    clearInterval(id);
+                    resolve();
+                }
+            }, 16);
+        });
+    }, { targetY, duration });
+}
+/**
+ * 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
+ */
+export async function smoothScrollToTarget(page, target, duration) {
+    if (typeof target === "number")
+        return smoothScroll(page, target, duration);
+    if (target === "top")
+        return smoothScroll(page, 0, duration);
+    if (target === "bottom") {
+        const bottom = await page.evaluate(() => document.body.scrollHeight);
+        return smoothScroll(page, bottom, duration);
+    }
+    const handle = await getHandle(page, target);
+    const y = await page.evaluate((el, vh) => {
+        const rect = el.getBoundingClientRect();
+        return window.scrollY + rect.top + rect.height / 2 - vh / 2;
+    }, handle, page.viewport()?.height ?? 900);
+    return smoothScroll(page, y, duration);
+}
+/**
+ * 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.
+ */
+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);
+}
+//# sourceMappingURL=dom.js.map

package/dist/browser/dom.js.map

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

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

@@ -0,0 +1,11 @@
+export declare const PLAY_BUTTON_ID = "__recordable_play__";
+export declare const PLAY_BINDING = "__recordablePlay__";
+/**
+ * The button injection as a *string*, not the `injectPlayButton` function object.
+ * esbuild/tsx (via `keepNames`) rewrites the inner arrows to `__name(() => …)`;
+ * Puppeteer injects a function via `.toString()`, so that `__name` call would leak
+ * into the page and throw (it's undefined there). Wrapping in a closure that
+ * defines an `__name` shim makes the snippet bundler-proof.
+ */
+export declare function playButtonScript(message: string, id: string, binding: string): string;
+//# sourceMappingURL=play-button.d.ts.map

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

@@ -0,0 +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"}

package/dist/browser/play-button.js

@@ -0,0 +1,87 @@
+export const PLAY_BUTTON_ID = "__recordable_play__";
+export const PLAY_BINDING = "__recordablePlay__";
+/**
+ * Injected into the page to render the in-page ▶ Play button. Runs in the
+ * browser context, so it must be fully self-contained (no outer references).
+ */
+function injectPlayButton(message, id, binding) {
+    // Skip iframes — only the top document gets the button.
+    if (window !== window.parent)
+        return;
+    const build = () => {
+        if (document.getElementById(id))
+            return;
+        const wrap = document.createElement("div");
+        wrap.id = id;
+        wrap.style.cssText = [
+            "position:fixed",
+            "left:50%",
+            // Top-anchored: a headful window is shorter than the emulated viewport, so
+            // a bottom pill renders below the fold, out of the user's reach.
+            "top:24px",
+            "transform:translateX(-50%)",
+            "z-index:2147483647",
+            "pointer-events:auto",
+            "display:flex",
+            "align-items:center",
+            "gap:12px",
+            "padding:10px 18px 10px 12px",
+            "background:rgba(20,18,40,0.92)",
+            "color:#fff",
+            "border-radius:999px",
+            "box-shadow:0 8px 28px rgba(0,0,0,0.4)",
+            "font-family:system-ui,-apple-system,Segoe UI,sans-serif",
+        ].join(";");
+        const btn = document.createElement("button");
+        btn.style.cssText = [
+            "all:unset",
+            "cursor:pointer",
+            "display:inline-flex",
+            "align-items:center",
+            "justify-content:center",
+            "width:34px",
+            "height:34px",
+            "border-radius:50%",
+            "background:#5b54e8",
+            "color:#fff",
+            "font-size:13px",
+        ].join(";");
+        btn.textContent = "▶";
+        const label = document.createElement("span");
+        label.textContent = message;
+        label.style.cssText =
+            "font-size:14px;line-height:1;white-space:nowrap;cursor:default";
+        wrap.appendChild(btn);
+        wrap.appendChild(label);
+        let fired = false;
+        const fire = () => {
+            if (fired)
+                return;
+            fired = true;
+            wrap.remove();
+            const fn = window[binding];
+            if (typeof fn === "function")
+                fn();
+        };
+        // Click only — no Enter/Space binding, so the live page keeps its own
+        // keyboard (e.g. Enter to submit a form) during the manual step.
+        btn.addEventListener("click", fire);
+        document.body.appendChild(wrap);
+    };
+    if (document.body)
+        build();
+    else
+        document.addEventListener("DOMContentLoaded", build);
+}
+/**
+ * The button injection as a *string*, not the `injectPlayButton` function object.
+ * esbuild/tsx (via `keepNames`) rewrites the inner arrows to `__name(() => …)`;
+ * Puppeteer injects a function via `.toString()`, so that `__name` call would leak
+ * into the page and throw (it's undefined there). Wrapping in a closure that
+ * defines an `__name` shim makes the snippet bundler-proof.
+ */
+export function playButtonScript(message, id, binding) {
+    const args = [message, id, binding].map((a) => JSON.stringify(a)).join(",");
+    return `(() => { const __name = (f) => f; (${injectPlayButton.toString()})(${args}); })()`;
+}
+//# sourceMappingURL=play-button.js.map

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

@@ -0,0 +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"}

package/dist/browser/runtime.d.ts

@@ -0,0 +1,66 @@
+import { type Page, type GoToOptions } from "puppeteer";
+import type { ResolvedConfig, WaitForOptions } from "../config.js";
+import { type Logger } from "../logger.js";
+import { type ZoomState } from "./cursor.js";
+export declare class Runtime {
+    private readonly getCfg;
+    private readonly log;
+    private readonly cursor;
+    private zoom;
+    private playResolver;
+    private playBindingExposed;
+    constructor(getCfg: () => ResolvedConfig, log: Logger);
+    /** The current zoom transform — the session re-reads it when re-injecting the
+     *  cursor overlay across navigations. */
+    get zoomState(): ZoomState;
+    /** Drop any zoom transform (a fresh document carries none). */
+    resetZoomState(): void;
+    /** (Re-)inject the cursor overlay at the carried position, if enabled. */
+    injectCursor(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): Promise<void>;
+    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>;
+    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?: {
+        duration?: number;
+    }): Promise<void>;
+    zoomTo(page: Page, level: number, options?: {
+        origin?: string;
+        duration?: number;
+    }): Promise<void>;
+    resetZoom(page: Page, options?: {
+        duration?: number;
+    }): Promise<void>;
+    /** Click a target's centre. Uses page.mouse.click() not ElementHandle.click()
+     *  to avoid Puppeteer's built-in scrollIntoView overriding our centred scroll. */
+    private _click;
+    /**
+     * Click at viewport coords and, if the click triggers a navigation, wait for the
+     * new page to settle before returning — so a navigating `click()` behaves like a
+     * `visit()` and the next action lands on the loaded page rather than racing it.
+     * In-page clicks pay only a short probe.
+     */
+    private _clickPoint;
+    /** Move to viewport coords, animating the overlay when the cursor is enabled. */
+    private _moveTo;
+    /** Scroll a target into view using the configured margin/speed. */
+    private _scrollIntoView;
+    /**
+     * 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
+     * page keeps its own keyboard (Enter to submit a form, etc.); the terminal
+     * fallback means a resume is still reachable if the button fails to render.
+     */
+    waitForPlay(page: Page, message: string): Promise<void>;
+}
+//# sourceMappingURL=runtime.d.ts.map