@vosjs/render-core 0.7.0 → 0.8.0

package/dist/record/index.d.ts

@@ -1,4 +1,4 @@
-import { RecordingMeta, CursorEvent, RecordingSkip, RecordingOutput, Backdrop, RecordingArtifact, ProjectDoc } from '@vosjs/studio-core';
+import { RecordingMeta, CursorEvent, RecordingSkip, RecordingOutput, Backdrop, RecordingArtifact, ProjectDoc, RecordingPageMedia } from '@vosjs/studio-core';
 
 /**
  * The recorder's driver: what it needs from a browser, as a STRUCTURAL
@@ -54,6 +54,11 @@ interface RecorderApiResponse {
     headers(): Record<string, string>;
     body(): Promise<Uint8Array>;
 }
+/** Which button a press is, and which press of a multi-click. */
+interface RecorderButtonOpts {
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+}
 interface RecorderLocatorRoot {
     first(): RecorderLocator;
 }
@@ -66,14 +71,14 @@ interface RecorderConsoleMessage {
 }
 interface RecorderPage {
     goto(url: string, opts: {
-        waitUntil: 'networkidle';
+        waitUntil: 'networkidle' | 'load';
         timeout: number;
     }): Promise<RecorderResponse | null>;
     url(): string;
     title(): Promise<string>;
     /** An `await` with `reload: true`; absent, the recorder opens the page's URL again. */
     reload?(opts: {
-        waitUntil: 'networkidle';
+        waitUntil: 'networkidle' | 'load';
         timeout: number;
     }): Promise<RecorderResponse | null>;
     /** A `download` step's click; absent, the recorder says the browser reports none. */
@@ -91,13 +96,16 @@ interface RecorderPage {
     locator(selector: string): RecorderLocatorRoot;
     mouse: {
         move(x: number, y: number): Promise<void>;
-        down(): Promise<void>;
-        up(): Promise<void>;
+        down(opts?: RecorderButtonOpts): Promise<void>;
+        up(opts?: RecorderButtonOpts): Promise<void>;
         wheel(dx: number, dy: number): Promise<void>;
     };
     keyboard: {
         type(text: string): Promise<void>;
         press(key: string): Promise<void>;
+        /** A drag's modifiers, held from the press to the release. */
+        down(key: string): Promise<void>;
+        up(key: string): Promise<void>;
     };
 }
 interface RecorderCdp {
@@ -131,6 +139,13 @@ interface RecorderContext {
      */
     route?(pattern: string, handler: (route: RecorderRoute) => Promise<unknown> | unknown): Promise<unknown>;
     newCDPSession(page: unknown): Promise<RecorderCdp>;
+    /**
+     * A `paste` step's clipboard access, when the driver grants it; absent,
+     * the paste is dispatched in the page and the recorder says so.
+     */
+    grantPermissions?(permissions: string[], opts?: {
+        origin?: string;
+    }): Promise<unknown>;
     close(): Promise<void>;
 }
 interface RecorderBrowser {
@@ -162,6 +177,25 @@ interface FrameSink {
 interface OutputSink {
     save(name: string, bytes: Uint8Array, contentType?: string): Promise<void> | void;
 }
+/**
+ * Where the sound a page played during the take is kept: the CLI writes
+ * `page-sound/<name>` in the take directory and answers that take-relative
+ * key, which the plan's audio clips name. A host that hands in none (the
+ * fleet) still records `meta.media`; the plan then places nothing.
+ */
+interface SoundSink {
+    save(name: string, bytes: Uint8Array, contentType?: string): Promise<string> | string;
+}
+/**
+ * Where the files a script names beside itself come from: a drag's path
+ * file, a paste's file, by a plain name. The CLI reads the actions file's
+ * directory. A host that hands in none (a hosted recorder carries the
+ * script alone) cannot run such a step, and the recorder refuses it before
+ * capturing anything.
+ */
+interface ScriptFiles {
+    read(name: string): Promise<Uint8Array>;
+}
 /** The clock and the pauses, injectable so a rehearsal runs fast. */
 interface RecorderClock {
     now(): number;
@@ -200,6 +234,7 @@ declare const SETTLE_MS: {
     readonly click: 150;
     readonly type: 150;
     readonly press: 150;
+    readonly paste: 150;
     readonly scroll: 200;
     readonly drag: 80;
 };
@@ -437,6 +472,9 @@ declare class PageErrorLog {
 type ExposureKind = 'email' | 'key' | 'card' | 'card-tail';
 type Exposure = NonNullable<RecordingMeta['exposures']>[number];
 type MaskReport = NonNullable<RecordingMeta['masks']>[number];
+type Notice = NonNullable<RecordingMeta['notices']>[number];
+/** A notice as one scan reports it. */
+type ScannedNotice = Omit<Notice, 'step' | 'seen'>;
 interface MaskRule {
     selector: string;
     /** `blur` (default) blurs the element; `text` swaps its words for `text`. */
@@ -456,12 +494,28 @@ interface MaskRule {
  * - card-tail: a masked number's visible tail (•••• 4242).
  */
 declare const EXPOSURE_MATCHERS_SRC = "(() => {\n  const EMAIL = /[A-Za-z0-9._%+-]+@((?:[A-Za-z0-9-]+\\.)+[A-Za-z]{2,})/g\n  const SAFE_HOST = /(^|\\.)example\\.(com|org|net)$|\\.(test|example|invalid|localhost)$/i\n  const KEY = new RegExp([\n    '\\\\b[srp]k_(?:live|test)_[A-Za-z0-9]{8,}',\n    '\\\\bgh[pousr]_[A-Za-z0-9]{20,}',\n    '\\\\bgithub_pat_[A-Za-z0-9_]{20,}',\n    '\\\\bxox[abprs]-[A-Za-z0-9-]{10,}',\n    '\\\\bAKIA[0-9A-Z]{16}\\\\b',\n    '\\\\bAIza[0-9A-Za-z_-]{30,}',\n    '\\\\bvos_(?:sk|rg|ho)_[A-Za-z0-9]{8,}',\n    '\\\\beyJ[A-Za-z0-9_-]{8,}\\\\.eyJ[A-Za-z0-9_-]{8,}\\\\.[A-Za-z0-9_-]{8,}',\n  ].join('|'))\n  const CARD = /(?:^|[^0-9])((?:[0-9][ -]?){12,18}[0-9])(?![0-9])/g\n  const TAIL = /[\\u2022\\u00b7*xX]{2,}[ -]?[0-9]{4}(?![0-9])/\n  const luhn = (digits) => {\n    let sum = 0, alt = false\n    for (let i = digits.length - 1; i >= 0; i--) {\n      let d = digits.charCodeAt(i) - 48\n      if (alt) { d *= 2; if (d > 9) d -= 9 }\n      sum += d; alt = !alt\n    }\n    return sum % 10 === 0\n  }\n  const kindsIn = (text) => {\n    const kinds = []\n    if (!text || text.length < 6) return kinds\n    EMAIL.lastIndex = 0\n    for (let m; (m = EMAIL.exec(text)); ) {\n      if (!SAFE_HOST.test(m[1])) { kinds.push('email'); break }\n    }\n    if (KEY.test(text)) kinds.push('key')\n    CARD.lastIndex = 0\n    for (let m; (m = CARD.exec(text)); ) {\n      const digits = m[1].replace(/[ -]/g, '')\n      if (digits.length >= 13 && digits.length <= 19 && !/^0+$/.test(digits) && luhn(digits)) { kinds.push('card'); break }\n    }\n    if (TAIL.test(text)) kinds.push('card-tail')\n    return kinds\n  }\n  return { kindsIn }\n})()";
+/**
+ * The INFORMATION the scan reports beside the exposures (never a failure):
+ * the signed-in account's own display name, wherever the frame shows it,
+ * and a list of the account's recent items. Runs inside EXPOSURE_PROBE,
+ * after `seen` and before any selector is made: it sets `acct`, which
+ * `quiet` then keeps out of every selector. Never `$` + `{` in here: it is
+ * spliced into a template.
+ *
+ * The name is read conservatively, from where apps say whose account it
+ * is: a line that greets or names the account ("Signed in as …",
+ * "Welcome back, …"), the label of an account menu ("Account menu for …"),
+ * or the words on the account menu's own trigger (the button that opens
+ * a menu and holds the avatar), which are SURE; or a name-like label on an avatar (an image's alt, a
+ * button holding the picture), which MAY be the name.
+ */
+declare const NOTICE_SRC: string;
 /**
  * The scan: visible text in the viewport, plus the values of text inputs.
  * Skips anything inside a masked element, password fields, and text the eye
  * cannot see. Reports kind + a selector-ish name for the element + its rect.
  */
-declare const EXPOSURE_PROBE = "(() => {\n  const { kindsIn } = (() => {\n  const EMAIL = /[A-Za-z0-9._%+-]+@((?:[A-Za-z0-9-]+\\.)+[A-Za-z]{2,})/g\n  const SAFE_HOST = /(^|\\.)example\\.(com|org|net)$|\\.(test|example|invalid|localhost)$/i\n  const KEY = new RegExp([\n    '\\\\b[srp]k_(?:live|test)_[A-Za-z0-9]{8,}',\n    '\\\\bgh[pousr]_[A-Za-z0-9]{20,}',\n    '\\\\bgithub_pat_[A-Za-z0-9_]{20,}',\n    '\\\\bxox[abprs]-[A-Za-z0-9-]{10,}',\n    '\\\\bAKIA[0-9A-Z]{16}\\\\b',\n    '\\\\bAIza[0-9A-Za-z_-]{30,}',\n    '\\\\bvos_(?:sk|rg|ho)_[A-Za-z0-9]{8,}',\n    '\\\\beyJ[A-Za-z0-9_-]{8,}\\\\.eyJ[A-Za-z0-9_-]{8,}\\\\.[A-Za-z0-9_-]{8,}',\n  ].join('|'))\n  const CARD = /(?:^|[^0-9])((?:[0-9][ -]?){12,18}[0-9])(?![0-9])/g\n  const TAIL = /[\\u2022\\u00b7*xX]{2,}[ -]?[0-9]{4}(?![0-9])/\n  const luhn = (digits) => {\n    let sum = 0, alt = false\n    for (let i = digits.length - 1; i >= 0; i--) {\n      let d = digits.charCodeAt(i) - 48\n      if (alt) { d *= 2; if (d > 9) d -= 9 }\n      sum += d; alt = !alt\n    }\n    return sum % 10 === 0\n  }\n  const kindsIn = (text) => {\n    const kinds = []\n    if (!text || text.length < 6) return kinds\n    EMAIL.lastIndex = 0\n    for (let m; (m = EMAIL.exec(text)); ) {\n      if (!SAFE_HOST.test(m[1])) { kinds.push('email'); break }\n    }\n    if (KEY.test(text)) kinds.push('key')\n    CARD.lastIndex = 0\n    for (let m; (m = CARD.exec(text)); ) {\n      const digits = m[1].replace(/[ -]/g, '')\n      if (digits.length >= 13 && digits.length <= 19 && !/^0+$/.test(digits) && luhn(digits)) { kinds.push('card'); break }\n    }\n    if (TAIL.test(text)) kinds.push('card-tail')\n    return kinds\n  }\n  return { kindsIn }\n})()\n  const vw = innerWidth, vh = innerHeight\n  // A selector that reaches THIS element and no other, so it can be pasted\n  // into \"mask\" as it is: climb until the path is unique, and say which\n  // sibling wherever a tag-and-class alone would match several. What the\n  // page wrote for people and tests comes first (an id, a test id, an\n  // aria-label, a field's name or placeholder); utility classes are a\n  // layout's, and they come last. A value that itself holds what the scan\n  // looks for is never used: the selector would quote it.\n  const attr = (v) => '\"' + v.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"') + '\"'\n  const quiet = (v) => !!v && v.length <= 80 && !kindsIn(v).length\n  const segment = (el) => {\n    const tag = el.tagName.toLowerCase()\n    if (el.id && /^[A-Za-z_][\\w-]*$/.test(el.id) && !/\\d{2,}/.test(el.id) && quiet(el.id)) return tag + '#' + el.id\n    const tid = el.getAttribute('data-testid')\n    if (quiet(tid)) return tag + '[data-testid=' + attr(tid) + ']'\n    const label = el.getAttribute('aria-label')\n    if (quiet(label)) return tag + '[aria-label=' + attr(label) + ']'\n    if (/^(INPUT|TEXTAREA|SELECT)$/.test(el.tagName)) {\n      const nm = el.getAttribute('name')\n      if (quiet(nm)) return tag + '[name=' + attr(nm) + ']'\n      const ph = el.getAttribute('placeholder')\n      if (quiet(ph)) return tag + '[placeholder=' + attr(ph) + ']'\n    }\n    const cls = [...el.classList].filter((c) => /^[A-Za-z_-][\\w-]*$/.test(c)).slice(0, 2)\n    let seg = el.tagName.toLowerCase() + (cls.length ? '.' + cls.join('.') : '')\n    const p = el.parentElement\n    if (p && [...p.children].filter((c) => c.matches(seg)).length > 1)\n      seg += ':nth-child(' + ([...p.children].indexOf(el) + 1) + ')'\n    return seg\n  }\n  const name = (el) => {\n    const parts = []\n    for (let cur = el; cur && cur !== document.body && cur !== document.documentElement; cur = cur.parentElement) {\n      parts.unshift(segment(cur))\n      let n = 2\n      try { n = document.querySelectorAll(parts.join(' > ')).length } catch {}\n      // a bare tag is unique HERE and nowhere else: give it its parent too\n      const bare = parts.length === 1 && !/[#.\\[]/.test(parts[0])\n      if ((n === 1 && !bare) || parts.length >= 5) break\n    }\n    return parts.join(' > ')\n  }\n  const seen = (el) => {\n    if (el.closest('[data-vos-masked]')) return null\n    const r = el.getBoundingClientRect()\n    if (r.width < 2 || r.height < 2) return null\n    if (r.bottom <= 0 || r.right <= 0 || r.top >= vh || r.left >= vw) return null\n    const s = getComputedStyle(el)\n    if (s.visibility === 'hidden' || s.display === 'none' || +s.opacity === 0) return null\n    return r\n  }\n  const out = [], keys = new Set()\n  const add = (el, text) => {\n    const kinds = kindsIn(text)\n    if (!kinds.length) return\n    const r = seen(el)\n    if (!r) return\n    const selector = name(el)\n    for (const kind of kinds) {\n      const k = kind + '|' + selector\n      if (keys.has(k) || out.length >= 40) continue\n      keys.add(k)\n      out.push({ kind, selector, rect: { x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) } })\n    }\n  }\n  const walker = document.createTreeWalker(document.body || document.documentElement, NodeFilter.SHOW_TEXT)\n  for (let n; (n = walker.nextNode()); ) {\n    const el = n.parentElement\n    if (!el || /^(SCRIPT|STYLE|NOSCRIPT|TEMPLATE)$/.test(el.tagName)) continue\n    add(el, n.nodeValue)\n  }\n  for (const el of document.querySelectorAll('input, textarea')) {\n    if (/^(password|hidden|file|checkbox|radio)$/.test(el.type)) continue\n    add(el, el.value)\n  }\n  const hits = {}\n  for (const [sel, n] of Object.entries(window.__vosMaskHits || {})) hits[sel] = n\n  return { exposures: out, maskHits: hits }\n})()";
+declare const EXPOSURE_PROBE: string;
 /**
  * The mask, as an init script: it runs at document start on EVERY navigation,
  * so a masked value is hidden before the page's first paint, and a
@@ -488,6 +542,26 @@ declare class ExposureLog {
 /** One exposure, in words. `step` -1 is the page as it opened. */
 declare function exposureLine(e: Exposure): string;
 declare const EXPOSURE_ADVICE = "The recording shows these. Record from a demo account, or hide them before the camera rolls with \"mask\" in actions.json: { \"selector\": \"\u2026\", \"as\": \"text\", \"text\": \"demo@acme.test\" } swaps the words, \"as\": \"blur\" blurs. Then re-record.";
+/**
+ * Accumulates the notices across a take: the account's name is ONE notice,
+ * its places gathered from every scan; a recent-items list is one notice
+ * per list. Each keeps the first step it was seen at.
+ */
+declare class NoticeLog {
+    private byKey;
+    add(step: number, notices: ScannedNotice[] | undefined | null): void;
+    notices(): Notice[];
+}
+/**
+ * One notice, in words. The account's name is never printed: the line says
+ * where it showed, so each place can be masked.
+ */
+declare function noticeLine(n: Notice): string;
+/**
+ * What to do about the notices, in one line: the swap hint is about the
+ * account's name, so it is said only when the name was noticed.
+ */
+declare function noticeAdvice(notices: readonly Pick<Notice, 'kind'>[]): string;
 
 /**
  * `setup`: the steps that run BEFORE the camera rolls. A sign-in form, a
@@ -567,6 +641,8 @@ declare function runSetup(page: RecorderPage, steps: SetupStep[], opts: {
     sleep: (ms: number) => Promise<void>;
     /** Absent means no env at all: a `{ env }` text then fails in words. */
     env?: Record<string, string | undefined>;
+    /** How a `goto` opens its page and waits for it (the take's ready mode); absent, network idle. */
+    goto?: (url: string) => Promise<unknown>;
 }): Promise<SetupResult>;
 /** A `{ env }` the shell did not provide: a usage error, not a page's. */
 declare class SetupEnvError extends Error {
@@ -580,6 +656,222 @@ declare class SetupError extends Error {
 /** `--header name=value`, repeatable: extra request headers on every request. */
 declare function parseHeaders(given: string[] | undefined): Record<string, string>;
 
+/**
+ * When a page counts as ready for the take to begin. The default is the
+ * DOM: after `load`, the page must make no DOM change for a beat (counted
+ * from outside, the way an `await` reload's settle is), at most a few
+ * seconds. Network idle is the opt-in: plenty of real apps hold a socket
+ * open or keep an analytics beacon going and never go network-idle, so a
+ * take that waited for it started after its whole timeout, every time.
+ */
+
+/** How a page counts as ready: its DOM settled (default), or its network went idle. */
+type ReadyMode = 'networkidle' | 'dom';
+declare const READY_MODES: readonly ReadyMode[];
+declare const DEFAULT_READY: ReadyMode;
+/** The longest a navigation waits for `load` or network idle. */
+declare const NAV_TIMEOUT_MS = 45000;
+/** The longest the settle waits on a page that never stops changing. */
+declare const READY_SETTLE_CAP_MS = 8000;
+/** After network idle, the beat a hydration takes (what the recorder always gave it). */
+declare const NETWORKIDLE_HYDRATION_MS = 800;
+/** How the first load settled: the done event's `ready`. */
+interface ReadyReport {
+    mode: ReadyMode;
+    /** ms from the navigation's start until the page counted as ready */
+    ms: number;
+    /**
+     * The wait gave up instead of the page settling: the DOM never stopped
+     * changing within the cap (dom), or network idle never came within
+     * the navigation timeout (networkidle). Recorded anyway either way.
+     */
+    capped: boolean;
+}
+/** Why a ready mode is not one, or null. */
+declare function readyProblem(v: unknown): string | null;
+interface ReadyOpts {
+    sleep: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** the settle's cap (default `READY_SETTLE_CAP_MS`) */
+    capMs?: number;
+    /** the navigation's own timeout (default `NAV_TIMEOUT_MS`) */
+    timeoutMs?: number;
+}
+/**
+ * Wait for a page that is navigating (or has just navigated) to be ready:
+ * `navigate` starts the navigation with the `waitUntil` the mode asks for;
+ * in `dom` mode the DOM settle follows `load`. A navigation that times
+ * out is not fatal: the take goes on from whatever the page shows, and the
+ * report says it was capped.
+ */
+declare function untilReady(page: RecorderPage, mode: ReadyMode, navigate: (opts: {
+    waitUntil: 'networkidle' | 'load';
+    timeout: number;
+}) => Promise<RecorderResponse | null>, opts: ReadyOpts): Promise<{
+    response: RecorderResponse | null;
+    ready: ReadyReport;
+}>;
+/**
+ * An `await`'s reload between polls, under the take's ready mode: the
+ * reload waits for `load` (dom) or network idle (networkidle), at most
+ * the await's own timeout, and then the DOM settles either way, because
+ * network quiet is not a drawn page (a list rendered from its data lands
+ * after it). A page that never goes network-idle no longer costs a whole
+ * navigation timeout per poll.
+ */
+declare function reloadUntilReady(page: RecorderPage, mode: ReadyMode, timeoutMs: number, opts?: {
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<void>;
+/** The ready report in words, for the take's log. */
+declare function readyLine(r: ReadyReport): string;
+
+/**
+ * The canvas gestures, the pure parts: key chords and sequences, the
+ * modifiers a drag holds, a drawn path and its timing, a click's count and
+ * button, and the overrun report. What a whiteboard, a design tool or a
+ * timeline is recorded with, said as data so a script can carry it and
+ * both hosts validate it in the same words.
+ *
+ * None of it reaches the cursor track as key identity: a key is a typing
+ * ping (when and where), a modifier is nothing at all, and a path is its
+ * points.
+ */
+/** The modifiers a chord or a drag may hold. `Mod` is Meta on macOS, Control elsewhere. */
+declare const MODIFIERS: readonly ["Shift", "Control", "Alt", "Meta", "Mod", "ControlOrMeta"];
+type Modifier = (typeof MODIFIERS)[number];
+/** The modifiers a drag names (the platform-neutral one is `Mod`). */
+declare const DRAG_MODIFIERS: readonly ["Alt", "Shift", "Meta", "Control", "Mod"];
+type DragModifier = (typeof DRAG_MODIFIERS)[number];
+/** A key name the browser's keyboard answers: a character, a code, a named key. */
+declare function isKeyName(k: string): boolean;
+/**
+ * A chord split into its modifiers and its key: `Shift+D` is
+ * `{ mods: ['Shift'], key: 'D' }`, a bare `r` has no modifiers, and `+`
+ * names the plus key when it ends the chord (`Shift++`).
+ */
+declare function splitChord(chord: string): {
+    mods: string[];
+    key: string;
+};
+/** Why a chord is not one the recorder can press, or null. */
+declare function chordProblem(chord: unknown): string | null;
+/**
+ * A chord as the browser's keyboard takes it: `Mod` becomes
+ * `ControlOrMeta`, which the browser resolves to Meta on macOS and to
+ * Control elsewhere, where the browser runs.
+ */
+declare function resolveChord(chord: string): string;
+/** A `press` step's keys as a list: one chord or a sequence. */
+declare function pressSequence(step: {
+    key?: string;
+    keys?: string | string[];
+}): string[];
+/** The pause between two keys of a sequence, a person's hand: ms. */
+declare const KEY_SEQUENCE_GAP_MS = 150;
+/**
+ * What one key costs beyond the script's gaps: the browser's round trip for
+ * the press (a keydown and a keyup the page answers). Part of the plan, so a
+ * sequence on an idle page is never "slower than scripted".
+ */
+declare const KEY_ROUNDTRIP_MS = 50;
+/** A key sequence's plan, ms: its gaps, and each key's round trip. */
+declare const keySequencePlanMs: (keys: number) => number;
+/** The hold after a drag's release, ms: the recorder's, part of the gesture. */
+declare const DRAG_HOLD_MS = 400;
+/** The most keys one press step may name. */
+declare const MAX_KEYS = 50;
+/** A drag modifier as the keyboard holds it. */
+declare function resolveModifier(m: DragModifier): string;
+/**
+ * The modifier bits of a raw pointer event (the pen path): Alt 1, Control
+ * 2, Meta 4, Shift 8, with `Mod` read for the platform the browser runs on.
+ */
+declare function modifierBits(mods: readonly DragModifier[], platform: 'mac' | 'linux' | 'windows' | undefined): number;
+/** A click's button, and the pointer button number the cursor track records. */
+declare const CLICK_BUTTONS: readonly ["left", "right", "middle"];
+type ClickButton = (typeof CLICK_BUTTONS)[number];
+declare const buttonNumber: (b: ClickButton | undefined) => 0 | 1 | 2;
+/**
+ * The pause between the presses of a double or triple click, well inside
+ * every platform's double-click interval (500 ms on macOS and Windows by
+ * default), so the page reads one gesture.
+ */
+declare const MULTI_CLICK_GAP_MS = 90;
+/**
+ * One point of a drawn path: viewport CSS px, with an optional time in ms
+ * (from the path's start) and an optional pressure in [0, 1]. Written as a
+ * tuple `[x, y]`, `[x, y, t]`, `[x, y, t, pressure]`, or an object.
+ */
+type PathPoint = [number, number] | [number, number, number] | [number, number, number, number] | {
+    x: number;
+    y: number;
+    t?: number;
+    pressure?: number;
+};
+/** A path point as the recorder replays it. */
+interface PathSample {
+    x: number;
+    y: number;
+    /** ms from the path's first point */
+    at: number;
+    pressure?: number;
+}
+/** The most points one path may hold. */
+declare const MAX_PATH_POINTS = 20000;
+/** An untimed path's travel when the step names no ms. */
+declare const PATH_DEFAULT_MS = 700;
+/**
+ * A path's points read and checked, or the problems in words. The same
+ * reader takes an inline `path` and the contents of a path file (an array
+ * of points, or `{ "points": [...] }`).
+ */
+declare function readPath(raw: unknown): {
+    points: PathSample[];
+    timed: boolean;
+} | {
+    problems: string[];
+};
+/**
+ * The path's schedule: a timed path keeps its own times (from its first
+ * point), an untimed one spreads its points evenly over `ms` (default
+ * 700). The last point is at the path's whole duration.
+ */
+declare function schedulePath(path: {
+    points: PathSample[];
+    timed: boolean;
+}, ms: number | undefined): PathSample[];
+/** How long a scheduled path takes, ms. */
+declare const pathDurationMs: (s: readonly PathSample[]) => number;
+/**
+ * A paced gesture that ran past its script: the wall time it took against
+ * the time the script planned for it (a drag's travel, a path's timing,
+ * typing's characters × delay, a key sequence's gaps). Reported when the
+ * gesture took more than a fifth longer, the sign of a page that could not
+ * keep up with what it was sent.
+ */
+interface StepOverrun {
+    step: number;
+    id?: string;
+    do: string;
+    plannedMs: number;
+    tookMs: number;
+    overrunMs: number;
+}
+/** The share past the plan that counts as an overrun. */
+declare const OVERRUN_SHARE = 0.2;
+/** A plan shorter than this is not measured: its noise is the round trip. */
+declare const OVERRUN_MIN_PLANNED_MS = 100;
+/**
+ * The least a gesture must run over to count, ms: below it the difference
+ * is one slow sample or round trip on a busy machine, never a page that
+ * fell behind, however short the gesture.
+ */
+declare const OVERRUN_MIN_MS = 100;
+/** The overrun, ms, or null when the gesture kept to its plan. */
+declare function overrunOf(plannedMs: number, tookMs: number): number | null;
+/** The overruns in one line for the log and the done event, or null when none. */
+declare function overrunLine(overruns: readonly StepOverrun[]): string | null;
+
 /**
  * The action script — the declarative recipe an agent (or human) writes to
  * drive a take. Small on purpose: selectors + a handful of verbs. The recorder
@@ -611,21 +903,51 @@ interface ActionsFile {
      * or stored.
      */
     setup?: SetupStep[];
+    /**
+     * When the first page counts as ready for step 1: `dom` (default),
+     * once its DOM has made no change for a beat after `load`, at most 8 s;
+     * `networkidle`, once the network has gone quiet, at most 45 s, which a
+     * page holding a socket open never does. `--ready` overrides.
+     */
+    ready?: ReadyMode;
+    /**
+     * Every gesture waits on the app after it (`settle` on a step overrides):
+     * a canvas that falls behind under load finishes the last stroke before
+     * the next one starts.
+     */
+    settle?: boolean;
     steps: ActionStep[];
 }
 type ActionStep = ({
     do: 'wait';
     ms: number;
-} | {
+}
+/**
+ * Rest the pointer on `selector`'s centre, or on the viewport point
+ * (`x`, `y`) when no selector names the spot (a place on a canvas).
+ */
+ | {
     do: 'hover';
-    selector: string;
+    selector?: string;
+    x?: number;
+    y?: number;
     ms?: number;
 }
-/** `ms` is the settle after the press (default 150). */
+/**
+ * Press `selector`'s centre, or the viewport point (`x`, `y`). `ms` is
+ * the settle after the press (default 150). `count` 2 or 3 is a real
+ * double or triple click; `button` presses the right or middle one;
+ * `modifiers` are held for the press (a Shift-click) and released after.
+ */
  | {
     do: 'click';
-    selector: string;
+    selector?: string;
+    x?: number;
+    y?: number;
     ms?: number;
+    count?: 1 | 2 | 3;
+    button?: ClickButton;
+    modifiers?: DragModifier[];
 }
 /**
  * Type into `selector`. The recorder clicks the field first, which is what
@@ -655,14 +977,18 @@ type ActionStep = ({
     ms?: number;
 }
 /**
- * One named key, recorded as a typing ping where the pointer is (or on
- * `selector` when given, with no click): Escape closes what a click
- * opened, Enter submits what was typed, Tab moves on, an arrow nudges.
- * Never a character: words are typed with `type`.
+ * A key, a chord or a sequence, each recorded as a typing ping where the
+ * pointer is (or on `selector` when given, with no click), never as the
+ * key itself. `key` names one control key (Escape closes what a click
+ * opened, Enter submits what was typed); `keys` names a chord
+ * (`"Shift+D"`, `"Mod+Z"`, with `Mod` Meta on macOS and Control
+ * elsewhere), a plain key (`"r"`, a tool's shortcut) or a sequence
+ * (`["v", "Escape"]`). Words are typed with `type`.
  */
  | {
     do: 'press';
-    key: PressKey;
+    key?: PressKey;
+    keys?: string | string[];
     selector?: string;
     ms?: number;
 }
@@ -680,14 +1006,32 @@ type ActionStep = ({
  * Press-move-release — real edits (drag an element on the stage canvas,
  * slide a range input, move a timeline clip). Start = the selector's center
  * when given, else (x, y); end = (tx, ty); eased over ms (default 700).
+ * `path` draws instead: viewport points (inline, or a file beside the
+ * actions file), the press at the first and the release at the last,
+ * replayed by the points' own times or evenly over ms. `modifiers` are
+ * held for the whole drag.
  */
  | {
     do: 'drag';
     selector?: string;
     x?: number;
     y?: number;
-    tx: number;
-    ty: number;
+    tx?: number;
+    ty?: number;
+    path?: PathPoint[] | string;
+    modifiers?: DragModifier[];
+    ms?: number;
+}
+/**
+ * Put words or a file (an image, an SVG) on the clipboard and paste it
+ * the way a person's ⌘V does, into `selector` (clicked first) or where
+ * the focus is. A file is read beside the actions file, by a plain name.
+ */
+ | {
+    do: 'paste';
+    selector?: string;
+    text?: string;
+    file?: string;
     ms?: number;
 }
 /**
@@ -764,6 +1108,13 @@ type ActionStep = ({
      * what is read. Only what the flow names, never a secret it did not.
      */
     read?: string;
+    /**
+     * After the gesture, wait until the page has made no DOM change and
+     * painted no new frame for a beat (at most a few seconds): an app that
+     * falls behind catches up before the next step. The script's top-level
+     * `settle` is the default.
+     */
+    settle?: boolean;
 };
 /** What an `await` waits for: exactly one of the three. */
 interface AwaitUntil {
@@ -821,6 +1172,15 @@ declare function guardVerdict(actions: Pick<ActionsFile, 'steps'>, confirm: read
  * take directory to land in there.
  */
 declare function hostedRefusals(actions: Pick<ActionsFile, 'steps'>): string[];
+/**
+ * The files a script names beside itself, in order: a drag's path file
+ * and a paste's file. A host reads them before anything is captured.
+ */
+declare function scriptFiles(actions: Pick<ActionsFile, 'steps'>): {
+    step: number;
+    name: string;
+    as: 'path' | 'paste';
+}[];
 
 /**
  * The wall check: did the recorder land where it was asked, or in front of
@@ -965,12 +1325,19 @@ interface RecordResult {
     pace: PaceReport;
     /** steps whose selector never became visible — the take continued without them. */
     skipped: SkippedStep[];
-    /** the initial goto never reached networkidle (recording proceeded anyway). */
+    /** `ready: "networkidle"` was asked for and the first load never reached it (recording proceeded anyway). */
     navTimeout: boolean;
+    /** How the first load settled before step 1. */
+    ready: ReadyReport;
     /** A wall the caller let through; null when the recorder landed where it was asked. */
     wall: WallVerdict | null;
     /** Sensitive-looking text seen in the frame (kind + place, never the string). */
     exposures: NonNullable<RecordingMeta['exposures']>;
+    /**
+     * INFORMATION, never a failure and never in `exposures`: the signed-in
+     * account's own name and its recent-items lists (also `meta.notices`).
+     */
+    notices: NonNullable<RecordingMeta['notices']>;
     /** The script's masks with how many elements each reached; hits 0 hid nothing. */
     masks: NonNullable<RecordingMeta['masks']>;
     /**
@@ -997,10 +1364,18 @@ interface RecordResult {
     skips: RecordingSkip[];
     /** The files `download` steps kept (also `meta.outputs`). */
     outputs: RecordingOutput[];
+    /** The sound the page played, each heard stretch in footage seconds (also `meta.media`). */
+    media: NonNullable<RecordingMeta['media']>;
     /** An `await` timed out and the take stopped there; null when it ran to the end. */
     stopped: StoppedTake | null;
     /** The page's own console errors, each distinct one with its full text and how often it came. */
     pageErrors: PageError[];
+    /**
+     * Paced gestures that ran more than a fifth past their script (a drag's
+     * travel, a path's timing, typing, a key sequence): the page could not
+     * keep up with what it was sent. Also on `meta.steps[].overrunMs`.
+     */
+    overruns: StepOverrun[];
     /** The actions as recorded, `url` resolved: what a take directory writes back. */
     actions: ActionsFile;
 }
@@ -1060,6 +1435,18 @@ interface RecordOpts {
      * A rehearsal fetches the file and keeps nothing.
      */
     outputs?: OutputSink;
+    /**
+     * Where the sound the page played is kept, fetched with the page's own
+     * cookies at the end of the take. A host that hands in none still
+     * records `meta.media`, with no file; a rehearsal fetches nothing.
+     */
+    sounds?: SoundSink;
+    /**
+     * The files the script names beside itself (a drag's path file, a
+     * paste's file). A host that hands in none cannot run such a step: the
+     * script is refused before anything is captured.
+     */
+    files?: ScriptFiles;
     /** Print every page error whole, each time it comes; by default one cut line per distinct error. */
     verbose?: boolean;
     /**
@@ -1067,6 +1454,12 @@ interface RecordOpts {
      * an `await`'s start, a heartbeat while it waits, and its end.
      */
     onEvent?: (event: Record<string, unknown>) => void;
+    /**
+     * A step the page stopped answering in (it ran into its bound) stops the
+     * take there, as an `await` that timed out does (`--strict`). Without
+     * it the step is a skip and the take goes on.
+     */
+    stopOnHang?: boolean;
     /** How often a long `await` reports it is still waiting (default 30 s). */
     awaitHeartbeatMs?: number;
 }
@@ -1085,6 +1478,8 @@ declare function jpegDims(buf: Uint8Array): {
 /** Base64 to bytes without Node's Buffer, so the fleet's isolate runs it too. */
 declare function base64Bytes(data: string): Uint8Array;
 declare function recordTake(browser: RecorderBrowser, url: string, actions: ActionsFile, sink: FrameSink, log: (msg: string) => void, opts?: RecordOpts): Promise<RecordResult>;
+/** Why a step ended at its bound, with the real time it took. */
+declare function hangReason(verb: string, ms: number, boundMs: number): string;
 declare function extForType(type: string | undefined): string;
 /** A download's type from its name's extension, as `{ contentType }`, or `{}` when the extension says nothing. */
 declare function typeOfName(name: string): {
@@ -1141,6 +1536,25 @@ interface FreshPlanOptions {
     activity?: readonly number[] | null;
 }
 declare function planFreshTake(artifact: RecordingArtifact, recordingName: string, opts?: FreshPlanOptions): ProjectDoc;
+/**
+ * The export a FRESH document opens on, sized to what the footage holds:
+ * the ingest's default resolution, or the largest the recording supports
+ * without upscaling when that is less (a 1280×720 take exports 720p, not a
+ * 1080p that `vos validate` then warns upscales). Never raised. In place,
+ * and returned.
+ */
+declare function withFittingExport(doc: ProjectDoc): ProjectDoc;
+/**
+ * The sound the page played (`meta.media`) as the document's audio: one
+ * clip per heard stretch, keyed to the fetched file, placed at the OUTPUT
+ * time of the footage moment it was heard (through the segments, the speed
+ * spans and the freezes), stamped `source: 'page'`. A re-plan replaces only
+ * those clips, so a clip someone added stays. An auto speed span over a
+ * heard stretch is dropped first, or the footage would race ahead of what
+ * the page was saying. A stretch with no fetched file (a hosted take, a
+ * fetch that failed) places nothing. In place, and returned.
+ */
+declare function withPageSound(doc: ProjectDoc, media: readonly RecordingPageMedia[] | undefined): ProjectDoc;
 /**
  * The footage's segments split at every cut an `await` made
  * (`meta.skips[].at`, source seconds), so each cut is a real segment
@@ -1306,6 +1720,17 @@ declare class TakeClock {
     pause(wallMs: number): number;
     /** The camera rolls again; returns the wall ms the stretch lasted. */
     resume(wallMs: number): number;
+    /**
+     * The parts of a wall-clock stretch the camera saw: each sub-stretch
+     * outside every off-camera wait, as its wall start (`wallMs`), its
+     * footage start (`atMs`) and its length. A stretch an `await` cut in two
+     * comes back as two; one wholly off camera as none.
+     */
+    onCamera(fromWall: number, toWall: number): {
+        wallMs: number;
+        atMs: number;
+        ms: number;
+    }[];
     /**
      * A captured frame's footage ms, or null when it is not later than the
      * last frame kept (the frame is dropped; see the module comment).
@@ -1313,4 +1738,311 @@ declare class TakeClock {
     placeFrame(captureWallMs: number): number | null;
 }
 
-export { AWAIT_HEARTBEAT_MS, AWAIT_POLL_S, AWAIT_TIMEOUT_S, type ActionStep, type ActionsFile, type Arrival, type AwaitUntil, type ConditionState, DEAD_SHARE_WARN_PCT, DEAD_STRETCH_WARN_MS, DOM_CHANGE_PROBE, DOM_QUIET_MS, DOM_SETTLE_CAP_MS, DOWNLOAD_TIMEOUT_S, type DeadReport, type DeadStep, type DisabledClick, EXPECT_TIMEOUT_S, EXPOSURE_ADVICE, EXPOSURE_MATCHERS_SRC, EXPOSURE_PROBE, type EncodePageOptions, type Exposure, type ExposureKind, ExposureLog, type FrameRec, type FrameSink, type FreezeSpan, type FreshPlanOptions, type GuardedStep, MIN_SKIP_MS, MOTION_TICK_MS, type MaskReport, type MaskRule, OUTPUT_MAX_BYTES, type OutputSink, PAGE_ERROR_LINE_CHARS, POINTER_MAX_MS, POINTER_MIN_MS, POINTER_MS_PER_PX, PRESS_HOLD_MS, PRESS_KEYS, PRESS_LEAD_MS, type PaceReport, type PageError, PageErrorLog, type PollResult, type PressKey, QUIET_MS, READ_BEAT_MS, RESPONSE_MS, type RecordOpts, RecordRefusedError, type RecordResult, type RecorderApiResponse, type RecorderBrowser, type RecorderCdp, type RecorderClock, type RecorderConsoleMessage, type RecorderContext, type RecorderDownload, type RecorderLocator, type RecorderLocatorRoot, type RecorderMediaElement, type RecorderPage, type RecorderRect, type RecorderResponse, type RecorderRoute, SCROLL_MAX_MS, SCROLL_MIN_MS, SCROLL_MS_PER_PX, SCROLL_SETTLE_MS, SETTLE_CAP_MS, SETTLE_MS, STEP_GUARDS, SetupEnvError, SetupError, type SetupResult, type SetupStep, type SetupText, type SkippedStep, type StepGuard, type StepPace, type StoppedTake, TRAILING_HOLD_MS, TakeClock, WALL_PROBE, type WaitCondition, WallError, type WallKind, type WallVerdict, askedMs, base64Bytes, buildEncodePage, capReached, cappedLine, clampWait, clockMotion, clockTyping, conditionMiss, deadLine, deadTime, deadWarns, domSettled, easeInOutCubic, exposureLine, extForType, fetchInPageScript, fileNameProblem, formatDurationCap, guardVerdict, guardedSteps, headersFor, holdLeftMs, hostedRefusals, isIdpHost, isSignInPath, jpegDims, maskInitScript, nameFromUrl, outputName, paceLine, paceReport, pageErrorLine, parseHeaders, plainName, planFreshTake, pointerTravelMs, pollCondition, publicUrl, readAllBytes, readCondition, readMediaSource, realSleep, recordTake, redirectedAway, resolveSetupText, runSetup, sayCondition, sayDuration, scrollByScript, scrollTravelMs, settleMs, settleVerdict, setupEnvNames, splitSegmentsAtSkips, typeOfName, urlSchemeProblem, validateActions, validateSetup, visibleTextScript, wallVerdict };
+interface SurfaceSize {
+    width: number;
+    height: number;
+}
+interface SurfaceFit {
+    before: SurfaceSize;
+    after: SurfaceSize;
+}
+/**
+ * Make the surface the viewport. Returns what it measured, or null when
+ * nothing could be measured; never throws, because a take made as before
+ * is better than no take.
+ */
+declare function fitSurfaceToViewport(cdp: RecorderCdp, width: number, height: number): Promise<SurfaceFit | null>;
+
+/**
+ * The sound a page plays during a take. The recorder captures frames, and
+ * a product's sound (a voice preview, a video playing in the page) would
+ * be lost with nothing to say it was there. Most of it is a media element,
+ * so the recorder watches every `<video>` and `<audio>` the page plays, in
+ * the page and in its same-origin frames, and keeps WHEN each was heard
+ * and WHAT media time it played, so a clip of the same file can be placed
+ * exactly under the footage (`meta.media`, then the plan's audio clips).
+ *
+ * Two pieces run IN the page, both plain JavaScript strings (a function
+ * serialized out of a bundle picks up the bundler's helpers and dies in the
+ * page): an init script that notes every play, pause, seek, end and volume
+ * change into a log on the top window, and a drain that hands the log over
+ * with the page's clock. The rest is here, in the recorder's clock: the
+ * page's instants become wall instants, and the take clock turns those
+ * into footage stretches, split wherever an `await` took the camera away.
+ */
+
+/**
+ * The init script: runs at document start in every frame. A frame that
+ * cannot reach the top window (another origin) notes nothing. A media
+ * element out of the document (`new Audio(url).play()`) is reached by
+ * the play it is started with.
+ */
+declare const MEDIA_WATCH_SCRIPT = "(() => {\n  let host\n  try { host = window.top; void host.document.title } catch { return }\n  if (window.__vosMediaWatch) return\n  window.__vosMediaWatch = true\n  if (!host.__vosMedia) {\n    const M = { log: [], seq: 0, els: new Set(), doc: Math.random().toString(36).slice(2) }\n    M.fields = (el, kind) => ({\n      id: el.__vosMediaId,\n      tag: el.tagName === 'VIDEO' ? 'video' : 'audio',\n      src: el.currentSrc || el.src || '',\n      kind,\n      wall: Date.now(),\n      t: el.currentTime,\n      rate: el.playbackRate || 1,\n      paused: el.paused || el.ended,\n      audible: !el.muted && el.volume > 0,\n      volume: el.volume,\n      duration: isFinite(el.duration) ? el.duration : null,\n      ab: typeof el.webkitAudioDecodedByteCount === 'number' ? el.webkitAudioDecodedByteCount : null,\n    })\n    host.__vosMedia = M\n  }\n  const M = host.__vosMedia\n  const EVENTS = ['playing', 'pause', 'ended', 'seeking', 'seeked', 'volumechange', 'ratechange', 'emptied']\n  const note = (e) => {\n    const el = e.target\n    if (!el || typeof el.currentTime !== 'number' || !/^(VIDEO|AUDIO)$/.test(el.tagName || '')) return\n    if (e.__vosNoted) return\n    e.__vosNoted = true\n    if (!el.__vosMediaId) {\n      if (M.els.size >= 50) return\n      el.__vosMediaId = ++M.seq\n      M.els.add(el)\n    }\n    if (M.log.length < 2000) M.log.push(M.fields(el, e.type))\n  }\n  for (const type of EVENTS) document.addEventListener(type, note, true)\n  const proto = window.HTMLMediaElement && window.HTMLMediaElement.prototype\n  if (proto && proto.play) {\n    const play = proto.play\n    proto.play = function () {\n      if (!this.__vosListening && !this.isConnected) {\n        this.__vosListening = true\n        for (const type of EVENTS) this.addEventListener(type, note)\n      }\n      return play.apply(this, arguments)\n    }\n  }\n})()";
+/**
+ * The drain: the notes since the last drain, a `tick` for every element
+ * followed (what it is doing now, which catches a note that never came),
+ * the page's clock, and which document the log belongs to (a navigation
+ * starts a new one).
+ */
+declare const MEDIA_DRAIN_PROBE = "(() => {\n  const M = window.__vosMedia\n  if (!M) return { now: Date.now(), doc: null, notes: [] }\n  const notes = M.log.splice(0)\n  M.els.forEach((el) => notes.push(M.fields(el, 'tick')))\n  return { now: Date.now(), doc: M.doc, notes }\n})()";
+/** One note from the page. */
+interface MediaNote {
+    id: number;
+    tag: 'video' | 'audio';
+    src: string;
+    kind: string;
+    wall: number;
+    t: number;
+    rate: number;
+    paused: boolean;
+    audible: boolean;
+    volume: number;
+    duration: number | null;
+    ab: number | null;
+}
+interface MediaDrain {
+    now: number;
+    doc: string | null;
+    notes: MediaNote[];
+}
+/** A page sound with its full source, for the fetch; `meta` is what the take keeps. */
+interface HeardSound {
+    meta: RecordingPageMedia;
+    /** the address as the page played it, query and all: fetched, never stored */
+    src: string;
+}
+/** What `meta.media[].src` keeps of an address: origin and path; a `blob:` or `data:` by its scheme. */
+declare function soundSrcForMeta(src: string): string;
+/**
+ * Accumulates the page's notes across a take, in the recorder's clock.
+ * `add` takes each drain with the recorder's own `Date.now()` at the
+ * moment it came back; `heard` closes what is still playing at the end
+ * and maps every stretch to footage time.
+ */
+declare class PageSoundLog {
+    private byKey;
+    private openKeyOf;
+    private doc;
+    private lastWall;
+    add(drain: MediaDrain | null, nodeNow: number, step?: number): void;
+    private note;
+    private close;
+    private closeAll;
+    /**
+     * Every element the page played, each heard stretch as footage seconds
+     * `at` with media seconds `from`..`to`, none past `endMs` of footage.
+     * A video whose decoder never decoded a byte of sound played none.
+     */
+    heard(clock: TakeClock, endWall: number, endMs: number): HeardSound[];
+}
+
+/**
+ * A step never runs past its own bound, however the page behaves. A page
+ * that stops answering (a busy loop, a renderer stuck after a reload the
+ * page made itself) leaves every driver call pending for good, and a poll
+ * that reads it waits on the read, not on its clock: an `expect` that said
+ * "for 5 s" ran for fifteen minutes. So the page the recorder drives is
+ * BOUNDED: while a step runs, every call into it is raced against the
+ * step's deadline, and once the deadline has passed a pending call answers
+ * `undefined` (what an absent element answers) instead of waiting. The
+ * step then ends as a skip with the real time it took; the call it left
+ * pending is abandoned, never awaited.
+ *
+ * Between steps the same race holds with a looser bound, so the take's
+ * own finish (its last reads, the page's title) cannot hang either.
+ */
+/** A gesture's bound past what it planned to take. */
+declare const STEP_MARGIN_MS = 30000;
+/** A check's (`expect`, `await`) bound past its own timeout. */
+declare const WAIT_MARGIN_MS = 5000;
+/** One call's bound while no step runs (a navigation has its own 45 s timeout). */
+declare const IDLE_CALL_MS = 60000;
+/** The bound of one step, in ms: its own timeout for a check, its plan plus a margin for a gesture. */
+declare function stepBoundMs(step: {
+    do: string;
+    timeout?: number;
+    until?: unknown;
+    reload?: boolean;
+}, plannedMs: number, defaults: {
+    expectS: number;
+    awaitS: number;
+    downloadS: number;
+}): number;
+declare class StepBound {
+    private readonly now;
+    private readonly idleMs;
+    private deadline;
+    private started;
+    private hung;
+    constructor(now?: () => number, idleMs?: number);
+    /** A step begins: calls into the page answer within `boundMs` from now. */
+    start(boundMs: number): void;
+    /** The step ends: whether it ran into its bound, and how long it really took. */
+    end(): {
+        hung: boolean;
+        ms: number;
+        boundMs: number;
+    };
+    /** The pending call, or `undefined` once the bound has passed. */
+    race<T>(p: Promise<T>): Promise<T>;
+}
+/**
+ * `target` with every method that answers a promise raced through the
+ * guard, and every object it hands back (`page.mouse`, `locator()`,
+ * `.first()`) guarded the same way. A call is made on the real object, so
+ * nothing private to the driver is touched through the proxy.
+ */
+declare function bounded<T extends object>(target: T, bound: StepBound): T;
+
+/**
+ * The `paste` step, the pure parts: what a file is pasted as, and the two
+ * page scripts that put an item where a person's ⌘V finds it.
+ *
+ * The first rung is the browser's own clipboard: the item is written with
+ * `navigator.clipboard.write` (the context is granted clipboard access
+ * first), and the recorder then presses the platform's paste chord, so the
+ * page receives a TRUSTED keydown and a trusted `paste` event carrying the
+ * item, and a page that reads `navigator.clipboard.read()` itself sees it
+ * there too. A headless browser keeps its own clipboard, so nothing on the
+ * machine's clipboard is touched.
+ *
+ * When the browser refuses the write (no clipboard access on this driver,
+ * a type it will not hold), the second rung dispatches the paste in the
+ * page: a `paste` event with a `DataTransfer` holding the item on the
+ * focused element, and `navigator.clipboard.read`/`readText` answering the
+ * item for the rest of the take. Those events are untrusted, which the
+ * recorder says.
+ *
+ * Both scripts are strings, the one evaluate shape every driver shares,
+ * and neither carries anything the cursor track keeps: a paste is a typing
+ * ping, never its contents.
+ */
+/** How long after a dispatched paste is first read its item stays on the async reads, ms. */
+declare const PASTE_READ_WINDOW_MS = 300;
+/** How long a dispatched paste's item stays on the async reads when nothing reads it, ms. */
+declare const PASTE_UNREAD_MS = 3000;
+/** The most bytes a pasted file may hold. */
+declare const PASTE_MAX_BYTES: number;
+/** The file types a paste takes, by extension. */
+declare const PASTE_TYPES: Record<string, string>;
+/** A pasted file's type from its name, or null when a paste does not take it. */
+declare function pasteTypeOf(name: string): string | null;
+/** What a paste puts on the clipboard: words, or a file's bytes (base64) with its type and name. */
+interface PasteItem {
+    text?: string;
+    b64?: string;
+    type?: string;
+    name?: string;
+}
+/**
+ * Rung one: write the item to the browser's clipboard. Answers 'ok', or
+ * 'refused: <why>'. An SVG the clipboard will not hold as an image is
+ * written as its markup alone.
+ */
+declare function stageClipboardScript(item: PasteItem): string;
+/**
+ * Rung two: the paste dispatched in the page, on the focused element (or
+ * the body), with the item in its `clipboardData`; and the async clipboard
+ * reads answer the item from here on. A plain field the page did not take
+ * the paste for gets the words inserted, as the browser's own paste does.
+ * Answers 'ok', or 'failed: <why>'.
+ */
+declare function syntheticPasteScript(item: PasteItem, opts?: {
+    original?: boolean;
+}): string;
+
+/**
+ * A gesture that waits on the app (`settle`): after the gesture, the
+ * recorder waits until the page has made no DOM change and painted no new
+ * frame for a beat, at most a few seconds. A heavy canvas falls behind
+ * under load, and a script paced by the wall clock then outruns it: the
+ * next stroke is drawn before the app has processed the last one.
+ *
+ * The DOM half is the recorder's one DOM-settle reader (`domSettled`, the
+ * same an `await`'s reload lets the page finish with). The paint half is
+ * the screencast: it emits a frame only when the compositor painted
+ * something new, a canvas redrawn by `requestAnimationFrame` included, and
+ * it is read from here rather than by an animation frame in the page,
+ * which a background tab never fires. The two are one count: the page's
+ * DOM changes plus the frames captured so far. A rehearsal captures no
+ * frames, so there it waits on the DOM alone.
+ */
+
+/** The quiet a settle waits for: no DOM change and no new frame, ms. */
+declare const APP_QUIET_MS = 300;
+/** The longest a settle waits on a page that never stops changing, ms. */
+declare const APP_SETTLE_CAP_MS = 4000;
+/** The verbs a settle follows: the ones that send the page input. */
+declare const SETTLE_VERBS: Set<string>;
+/**
+ * How long ago the page last changed its DOM, in ms by the page's own clock,
+ * or -1 when this is the first look at this document (the reader is
+ * installed now and knows no history). A string, the one evaluate shape
+ * every driver shares.
+ */
+declare const CHANGE_AGE_PROBE = "(() => {\n  const w = window;\n  if (!w.__vosChangeAt) {\n    w.__vosChangeAt = { at: Date.now() };\n    new MutationObserver(() => { w.__vosChangeAt.at = Date.now() })\n      .observe(document, { subtree: true, childList: true, attributes: true, characterData: true });\n    return -1;\n  }\n  return Date.now() - w.__vosChangeAt.at;\n})()";
+/** Whether a step waits on the app after its gesture: its own `settle`, else the script's. */
+declare function settleOn(step: {
+    do: string;
+    settle?: boolean;
+}, scriptDefault: boolean | undefined): boolean;
+/**
+ * Wait for the app: no DOM change and no new captured frame for `quietMs`,
+ * at most `capMs`. `frames` reads how many frames the capture has kept.
+ */
+declare function appSettled(page: Pick<RecorderPage, 'evaluate'>, frames: () => number, opts: {
+    sleep: (ms: number) => Promise<void>;
+    now?: () => number;
+    quietMs?: number;
+    capMs?: number;
+    /** ms since the last captured frame, or null when none was captured */
+    sinceFrame?: () => number | null;
+}): Promise<{
+    settled: boolean;
+    ms: number;
+}>;
+
+/**
+ * The files a script names beside itself, read before the take: a drag's
+ * path file (points as JSON) and a paste's file (its bytes). The host
+ * hands in where they come from (`ScriptFiles`); the names are plain file
+ * names, checked by `validateActions`, so a script can only name what sits
+ * next to it.
+ */
+
+interface LoadedFiles {
+    /** a drag's path, read from its file, by step index */
+    paths: Map<number, {
+        points: PathSample[];
+        timed: boolean;
+    }>;
+    /** a paste's file, by step index */
+    pastes: Map<number, {
+        bytes: Uint8Array;
+        type: string;
+        name: string;
+    }>;
+}
+/**
+ * Read every file the script names. Answers the files, or the problem in
+ * words (the step, the file, what is wrong) for the caller to refuse the
+ * take with.
+ */
+declare function loadScriptFiles(actions: Pick<ActionsFile, 'steps'>, source: ScriptFiles | undefined): Promise<LoadedFiles | {
+    problem: string;
+}>;
+/** A read path as inline points: its own times when it had them, its pressure when it carried one. */
+declare function inlinePoints(path: {
+    points: PathSample[];
+    timed: boolean;
+}): PathPoint[];
+/**
+ * The script as it ran, self-contained: every path a file held is written
+ * inline, so the script a take keeps (and the one a push embeds, a fetch
+ * writes back and a hosted recorder runs) re-records the same strokes with
+ * the file gone. A paste's file stays a name: it is bytes, kept beside the
+ * script by the host.
+ */
+declare function inlineScript<T extends Pick<ActionsFile, 'steps'>>(actions: T, files: LoadedFiles): T;
+
+export { APP_QUIET_MS, APP_SETTLE_CAP_MS, AWAIT_HEARTBEAT_MS, AWAIT_POLL_S, AWAIT_TIMEOUT_S, type ActionStep, type ActionsFile, type Arrival, type AwaitUntil, CHANGE_AGE_PROBE, CLICK_BUTTONS, type ClickButton, type ConditionState, DEAD_SHARE_WARN_PCT, DEAD_STRETCH_WARN_MS, DEFAULT_READY, DOM_CHANGE_PROBE, DOM_QUIET_MS, DOM_SETTLE_CAP_MS, DOWNLOAD_TIMEOUT_S, DRAG_HOLD_MS, DRAG_MODIFIERS, type DeadReport, type DeadStep, type DisabledClick, type DragModifier, EXPECT_TIMEOUT_S, EXPOSURE_ADVICE, EXPOSURE_MATCHERS_SRC, EXPOSURE_PROBE, type EncodePageOptions, type Exposure, type ExposureKind, ExposureLog, type FrameRec, type FrameSink, type FreezeSpan, type FreshPlanOptions, type GuardedStep, type HeardSound, IDLE_CALL_MS, KEY_ROUNDTRIP_MS, KEY_SEQUENCE_GAP_MS, type LoadedFiles, MAX_KEYS, MAX_PATH_POINTS, MEDIA_DRAIN_PROBE, MEDIA_WATCH_SCRIPT, MIN_SKIP_MS, MODIFIERS, MOTION_TICK_MS, MULTI_CLICK_GAP_MS, type MaskReport, type MaskRule, type MediaDrain, type MediaNote, type Modifier, NAV_TIMEOUT_MS, NETWORKIDLE_HYDRATION_MS, NOTICE_SRC, type Notice, NoticeLog, OUTPUT_MAX_BYTES, OVERRUN_MIN_MS, OVERRUN_MIN_PLANNED_MS, OVERRUN_SHARE, type OutputSink, PAGE_ERROR_LINE_CHARS, PASTE_MAX_BYTES, PASTE_READ_WINDOW_MS, PASTE_TYPES, PASTE_UNREAD_MS, PATH_DEFAULT_MS, POINTER_MAX_MS, POINTER_MIN_MS, POINTER_MS_PER_PX, PRESS_HOLD_MS, PRESS_KEYS, PRESS_LEAD_MS, type PaceReport, type PageError, PageErrorLog, PageSoundLog, type PasteItem, type PathPoint, type PathSample, type PollResult, type PressKey, QUIET_MS, READY_MODES, READY_SETTLE_CAP_MS, READ_BEAT_MS, RESPONSE_MS, type ReadyMode, type ReadyOpts, type ReadyReport, type RecordOpts, RecordRefusedError, type RecordResult, type RecorderApiResponse, type RecorderBrowser, type RecorderButtonOpts, type RecorderCdp, type RecorderClock, type RecorderConsoleMessage, type RecorderContext, type RecorderDownload, type RecorderLocator, type RecorderLocatorRoot, type RecorderMediaElement, type RecorderPage, type RecorderRect, type RecorderResponse, type RecorderRoute, SCROLL_MAX_MS, SCROLL_MIN_MS, SCROLL_MS_PER_PX, SCROLL_SETTLE_MS, SETTLE_CAP_MS, SETTLE_MS, SETTLE_VERBS, STEP_GUARDS, STEP_MARGIN_MS, type ScannedNotice, type ScriptFiles, SetupEnvError, SetupError, type SetupResult, type SetupStep, type SetupText, type SkippedStep, type SoundSink, StepBound, type StepGuard, type StepOverrun, type StepPace, type StoppedTake, type SurfaceFit, type SurfaceSize, TRAILING_HOLD_MS, TakeClock, WAIT_MARGIN_MS, WALL_PROBE, type WaitCondition, WallError, type WallKind, type WallVerdict, appSettled, askedMs, base64Bytes, bounded, buildEncodePage, buttonNumber, capReached, cappedLine, chordProblem, clampWait, clockMotion, clockTyping, conditionMiss, deadLine, deadTime, deadWarns, domSettled, easeInOutCubic, exposureLine, extForType, fetchInPageScript, fileNameProblem, fitSurfaceToViewport, formatDurationCap, guardVerdict, guardedSteps, hangReason, headersFor, holdLeftMs, hostedRefusals, inlinePoints, inlineScript, isIdpHost, isKeyName, isSignInPath, jpegDims, keySequencePlanMs, loadScriptFiles, maskInitScript, modifierBits, nameFromUrl, noticeAdvice, noticeLine, outputName, overrunLine, overrunOf, paceLine, paceReport, pageErrorLine, parseHeaders, pasteTypeOf, pathDurationMs, plainName, planFreshTake, pointerTravelMs, pollCondition, pressSequence, publicUrl, readAllBytes, readCondition, readMediaSource, readPath, readyLine, readyProblem, realSleep, recordTake, redirectedAway, reloadUntilReady, resolveChord, resolveModifier, resolveSetupText, runSetup, sayCondition, sayDuration, schedulePath, scriptFiles, scrollByScript, scrollTravelMs, settleMs, settleOn, settleVerdict, setupEnvNames, soundSrcForMeta, splitChord, splitSegmentsAtSkips, stageClipboardScript, stepBoundMs, syntheticPasteScript, typeOfName, untilReady, urlSchemeProblem, validateActions, validateSetup, visibleTextScript, wallVerdict, withFittingExport, withPageSound };