@vosjs/render-core 0.6.0 → 0.7.0

package/dist/record/index.d.ts

@@ -1,4 +1,4 @@
-import { RecordingMeta, CursorEvent, Backdrop, RecordingArtifact, ProjectDoc } from '@vosjs/studio-core';
+import { RecordingMeta, CursorEvent, RecordingSkip, RecordingOutput, Backdrop, RecordingArtifact, ProjectDoc } from '@vosjs/studio-core';
 
 /**
  * The recorder's driver: what it needs from a browser, as a STRUCTURAL
@@ -21,13 +21,38 @@ interface RecorderRect {
 }
 interface RecorderLocator {
     waitFor(opts: {
-        state: 'visible';
+        state: 'visible' | 'attached';
         timeout: number;
     }): Promise<unknown>;
     scrollIntoViewIfNeeded(): Promise<unknown>;
     boundingBox(): Promise<RecorderRect | null>;
     click(): Promise<unknown>;
     fill(value: string): Promise<unknown>;
+    /** what an `expect` and an `await` read, and the disabled-click report */
+    isVisible(): Promise<boolean>;
+    isEnabled(opts?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /** a `download` src reads the media element's source through the locator engine */
+    evaluate<R>(fn: (el: RecorderMediaElement) => R): Promise<R>;
+}
+/** What a `download` src reads off the element its selector matched. */
+interface RecorderMediaElement {
+    currentSrc?: string;
+    src?: string;
+    getAttribute(name: string): string | null;
+}
+/** A browser download, as Playwright's `Download` answers it. */
+interface RecorderDownload {
+    suggestedFilename(): string;
+    createReadStream(): Promise<AsyncIterable<unknown> | null>;
+}
+/** The page's own request context (its cookies), as Playwright's `APIResponse` answers. */
+interface RecorderApiResponse {
+    ok(): boolean;
+    status(): number;
+    headers(): Record<string, string>;
+    body(): Promise<Uint8Array>;
 }
 interface RecorderLocatorRoot {
     first(): RecorderLocator;
@@ -46,6 +71,21 @@ interface RecorderPage {
     }): 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';
+        timeout: number;
+    }): Promise<RecorderResponse | null>;
+    /** A `download` step's click; absent, the recorder says the browser reports none. */
+    waitForEvent?(event: 'download', opts: {
+        timeout: number;
+    }): Promise<RecorderDownload>;
+    /** A `download` step's `src` fetch, with the page's cookies; absent, it fetches in the page. */
+    request?: {
+        get(url: string, opts?: {
+            timeout?: number;
+        }): Promise<RecorderApiResponse>;
+    };
     evaluate<T>(pageFunction: string | (() => T)): Promise<T>;
     on(event: 'console', cb: (m: RecorderConsoleMessage) => void): unknown;
     locator(selector: string): RecorderLocatorRoot;
@@ -114,6 +154,14 @@ interface RecorderBrowser {
 interface FrameSink {
     frame(file: string, bytes: Uint8Array): Promise<void> | void;
 }
+/**
+ * Where a `download` step's file goes: the CLI writes `outputs/<name>` in
+ * the take directory. A host that hands in none cannot keep a download,
+ * and the recorder refuses such a script before capturing anything.
+ */
+interface OutputSink {
+    save(name: string, bytes: Uint8Array, contentType?: string): Promise<void> | void;
+}
 /** The clock and the pauses, injectable so a rehearsal runs fast. */
 interface RecorderClock {
     now(): number;
@@ -332,6 +380,36 @@ declare function deadWarns(r: DeadReport): boolean;
 /** The dead time in words, naming the steps and what to cut. */
 declare function deadLine(r: DeadReport): string;
 
+/**
+ * The page's own console errors, as the recorder reports them. A page
+ * under recording is someone else's, and its errors are context, never the
+ * story: a third party's Content-Security-Policy violation runs to a few
+ * kilobytes and repeats on every load, which buried the step lines. So the
+ * log gets one line per distinct error, cut short, and a repeat is counted
+ * instead of printed; the full text stays in the result (and a verbose
+ * host prints every one whole).
+ */
+/** How much of an error a log line keeps. */
+declare const PAGE_ERROR_LINE_CHARS = 160;
+interface PageError {
+    /** the full text, whitespace as the page wrote it */
+    text: string;
+    count: number;
+}
+/** One line of an error: whitespace collapsed, cut to the line's length. */
+declare function pageErrorLine(text: string): string;
+declare class PageErrorLog {
+    private readonly verbose;
+    private readonly seen;
+    constructor(verbose?: boolean);
+    /** The line to log for this error now, or null when it repeats one already said. */
+    add(text: string): string | null;
+    /** Every distinct error with how often it came, in the order first seen. */
+    entries(): PageError[];
+    /** The closing lines: each error that repeated, with its count. */
+    repeats(): string[];
+}
+
 /**
  * What a signed-in take SHOWS. Getting past the login is half the problem;
  * the other half is that the account's own data is now in the frame: an
@@ -383,7 +461,7 @@ declare const EXPOSURE_MATCHERS_SRC = "(() => {\n  const EMAIL = /[A-Za-z0-9._%+
  * 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.\n  const segment = (el) => {\n    const tid = el.getAttribute('data-testid')\n    if (tid) return el.tagName.toLowerCase() + '[data-testid=\"' + tid + '\"]'\n    if (el.id && /^[A-Za-z_][\\w-]*$/.test(el.id)) return el.tagName.toLowerCase() + '#' + el.id\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 = "(() => {\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})()";
 /**
  * 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
@@ -611,7 +689,60 @@ type ActionStep = ({
     tx: number;
     ty: number;
     ms?: number;
+}
+/**
+ * Check that the page is as the flow expects, with no cursor move: an
+ * element visible (`selector`; with `enabled`, enabled or disabled), some
+ * visible text containing `text`, or `gone` no longer visible. Exactly
+ * one of the three. Waits up to `timeout` seconds (default 5); a
+ * condition that never holds is a skip with its reason.
+ */
+ | {
+    do: 'expect';
+    selector?: string;
+    text?: string;
+    gone?: string;
+    enabled?: boolean;
+    timeout?: number;
+}
+/**
+ * Wait OFF CAMERA for something slow (a render, a generated result, a
+ * deploy): the capture stops, the predicate is polled every `poll`
+ * seconds (default 2) for up to `timeout` (default 600), reloading the
+ * page between polls when `reload` is set, and the capture resumes when
+ * it holds. The footage has no gap and no frozen stretch; the cut lands
+ * in `meta.skips[]`. On timeout, `onTimeout: "fail"` (the default) stops
+ * the take and `"continue"` resumes it.
+ */
+ | {
+    do: 'await';
+    until: AwaitUntil;
+    timeout?: number;
+    poll?: number;
+    reload?: boolean;
+    onTimeout?: 'fail' | 'continue';
+}
+/**
+ * Keep a file the page makes: click `selector` and wait for the
+ * browser's download, or fetch the `currentSrc` of the video, audio or
+ * img element `src` names, with the page's own cookies. Saved under the
+ * take's `outputs/` as `as`, else the name the page suggested, and listed
+ * in `meta.outputs[]`.
+ */
+ | {
+    do: 'download';
+    selector?: string;
+    src?: string;
+    as?: string;
 }) & {
+    /**
+     * `"spend"`: the step costs something real (credits, a purchase, a
+     * message sent). Only a click, a press or a type carries it, and it
+     * needs an `id`. A rehearsal hovers it and never presses it; a recording
+     * presses it only when the command names it (`--confirm <id>`) and
+     * refuses before capturing anything otherwise.
+     */
+    guard?: StepGuard;
     /**
      * Optional stable identity: anchors in doc.json name a step by this
      * id (else by index), so a step can move or gain neighbours across script
@@ -634,11 +765,62 @@ type ActionStep = ({
      */
     read?: string;
 };
+/** What an `await` waits for: exactly one of the three. */
+interface AwaitUntil {
+    selector?: string;
+    text?: string;
+    gone?: string;
+}
+/** The guards a step may carry: one today, a step that spends. */
+declare const STEP_GUARDS: readonly ["spend"];
+type StepGuard = (typeof STEP_GUARDS)[number];
+/** How long an `expect` waits by default, in seconds. */
+declare const EXPECT_TIMEOUT_S = 5;
+/** An `await`'s defaults, in seconds. */
+declare const AWAIT_TIMEOUT_S = 600;
+declare const AWAIT_POLL_S = 2;
+/** How long a `download` click waits for the browser's download, in seconds. */
+declare const DOWNLOAD_TIMEOUT_S = 30;
 /** The keys a `press` step may name: navigation and control, never a character. */
 declare const PRESS_KEYS: readonly ["Escape", "Enter", "Tab", "Backspace", "Delete", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown", "Space"];
 type PressKey = (typeof PRESS_KEYS)[number];
 /** Structural validation with actionable messages. Returns [] when valid. */
 declare function validateActions(value: unknown): string[];
+/**
+ * Why a name is not one a download may be saved under, or null. A plain
+ * file name only: the file lands in the take's `outputs/` and nowhere
+ * else, so no separator, no `..`, nothing hidden, nothing empty.
+ */
+declare function fileNameProblem(name: string): string | null;
+/** A guarded step of a script: where it is, what it is, the id that confirms it. */
+interface GuardedStep {
+    step: number;
+    id: string;
+    do: string;
+    guard: StepGuard;
+}
+/** The guarded steps of a script, in order. */
+declare function guardedSteps(actions: Pick<ActionsFile, 'steps'>): GuardedStep[];
+/**
+ * Whether a recording may run with the confirmations it was given: every
+ * guarded step named by `--confirm`, and every name a guarded step. A
+ * refusal is one sentence naming the steps and the flag, said before
+ * anything is captured.
+ */
+declare function guardVerdict(actions: Pick<ActionsFile, 'steps'>, confirm: readonly string[]): {
+    ok: true;
+} | {
+    ok: false;
+    unconfirmed: string[];
+    unknown: string[];
+    message: string;
+};
+/**
+ * What a hosted recorder cannot do with a script, in words, or []: a
+ * guarded step has nobody to confirm it on a fleet, and a download has no
+ * take directory to land in there.
+ */
+declare function hostedRefusals(actions: Pick<ActionsFile, 'steps'>): string[];
 
 /**
  * The wall check: did the recorder land where it was asked, or in front of
@@ -724,6 +906,10 @@ declare const WALL_PROBE = "(() => {\n  const shown = (el) => {\n    const r = e
  * same events, meta and frame index for the same script.
  */
 
+/** How often a long `await` says it is still waiting, in ms. */
+declare const AWAIT_HEARTBEAT_MS = 30000;
+/** An `await` that held sooner than this cut nothing: no skip, no segment split. */
+declare const MIN_SKIP_MS = 250;
 /**
  * The headers a request carries, or null to leave it alone: a job's
  * headers (a preview's bypass token) go to the ORIGIN the take is of and
@@ -742,8 +928,27 @@ interface FrameRec {
 interface SkippedStep {
     /** index into actions.steps */
     step: number;
+    id?: string;
     do: string;
     selector: string;
+    /** why, when it is not a selector that never appeared: an expect that never held, a download that never came */
+    reason?: string;
+}
+/** A click whose target was disabled when it was pressed: the press happened, and likely did nothing. */
+interface DisabledClick {
+    step: number;
+    id?: string;
+    selector: string;
+}
+/** An `await` that timed out with `onTimeout: "fail"`: the take stopped there. */
+interface StoppedTake {
+    step: number;
+    id?: string;
+    reason: string;
+}
+/** Thrown before anything is captured: a guarded step the command did not confirm, a download with nowhere to land. */
+declare class RecordRefusedError extends Error {
+    constructor(message: string);
 }
 /** A stretch with no screencast frames — the page pixels did not change. */
 interface FreezeSpan {
@@ -784,6 +989,18 @@ interface RecordResult {
     dead: DeadReport;
     /** The take reached --max-duration and stopped there; later steps did not run. */
     capped: boolean;
+    /** Clicks pressed on a disabled target (reported; `--strict` fails on them). */
+    disabled: DisabledClick[];
+    /** The ids of the guarded steps this take pressed, because the command named them. */
+    confirmed: string[];
+    /** The cuts `await` steps made (also `meta.skips`). */
+    skips: RecordingSkip[];
+    /** The files `download` steps kept (also `meta.outputs`). */
+    outputs: RecordingOutput[];
+    /** 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[];
     /** The actions as recorded, `url` resolved: what a take directory writes back. */
     actions: ActionsFile;
 }
@@ -831,6 +1048,27 @@ interface RecordOpts {
     env?: Record<string, string | undefined>;
     /** The platform the take is recorded on, for `meta.platform`. */
     platform?: RecordingMeta['platform'];
+    /**
+     * The ids of the guarded steps this recording may press (`--confirm`).
+     * A guarded step not named here refuses the take before anything is
+     * captured; a rehearsal hovers every guarded step and presses none.
+     */
+    confirm?: readonly string[];
+    /**
+     * Where a `download` step's file goes. A host that hands in none cannot
+     * keep a download: such a script is refused before anything is captured.
+     * A rehearsal fetches the file and keeps nothing.
+     */
+    outputs?: OutputSink;
+    /** Print every page error whole, each time it comes; by default one cut line per distinct error. */
+    verbose?: boolean;
+    /**
+     * Structured progress for a host that reports it (the CLI's `--json`):
+     * an `await`'s start, a heartbeat while it waits, and its end.
+     */
+    onEvent?: (event: Record<string, unknown>) => void;
+    /** How often a long `await` reports it is still waiting (default 30 s). */
+    awaitHeartbeatMs?: number;
 }
 /**
  * The expression a scroll tick evaluates: move the first scrollable
@@ -847,6 +1085,11 @@ 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>;
+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): {
+    contentType?: string;
+};
 
 /**
  * The recording cap as the recorder applies it, pure. WHAT the cap is
@@ -898,5 +1141,176 @@ interface FreshPlanOptions {
     activity?: readonly number[] | null;
 }
 declare function planFreshTake(artifact: RecordingArtifact, recordingName: string, opts?: FreshPlanOptions): ProjectDoc;
+/**
+ * The footage's segments split at every cut an `await` made
+ * (`meta.skips[].at`, source seconds), so each cut is a real segment
+ * boundary: the timeline shows it, a transition can sit on it, a trim can
+ * take either side. A cut at an edge or outside a segment splits nothing,
+ * and a segment of another media is left alone. A split segment keeps its
+ * arrival on its first piece and its leaving on its last.
+ */
+declare function splitSegmentsAtSkips(segments: ProjectDoc['segments'], skips: readonly {
+    at: number;
+}[] | undefined): ProjectDoc['segments'];
+
+/**
+ * What an `expect` and an `await` wait for: a condition on the page, read
+ * without touching it (no cursor, no input), polled until it holds or the
+ * time runs out. `expect` polls on camera for a few seconds; `await` polls
+ * off camera for as long as a slow result takes. One reader for both, so
+ * "appeared" means the same thing in either.
+ */
+
+interface WaitCondition {
+    /** an element matching this selector is visible */
+    selector?: string;
+    /** some visible text on the page contains this */
+    text?: string;
+    /** no element matching this selector is visible */
+    gone?: string;
+    /** with `selector`: the element is enabled (true) or disabled (false) */
+    enabled?: boolean;
+}
+/** What the condition found the last time it looked: what a miss is said from. */
+interface ConditionState {
+    holds: boolean;
+    /** with `selector`: whether a match was visible */
+    visible?: boolean;
+}
+/**
+ * The visible text of the page contains `text`: `innerText` is what the
+ * page renders, so a hidden element's words never count.
+ */
+declare function visibleTextScript(text: string): string;
+/** Read the condition once. A page mid-navigation reads as "not yet". */
+declare function readCondition(page: RecorderPage, c: WaitCondition): Promise<ConditionState>;
+/** What a poll found: whether the condition held, after how long, and the last read. */
+interface PollResult {
+    ok: boolean;
+    ms: number;
+    last: ConditionState;
+}
+/**
+ * Poll the condition every `everyMs` until it holds or `timeoutMs` pass.
+ * `between` runs before each look but the first (an `await`'s reload).
+ * With `confirm`, a hold counts only once it has held on that many reads
+ * in a row, `confirm.gapMs` apart: a page that renders after network quiet
+ * reads half-built for a moment, and a `gone` condition holds on a list
+ * that has not been drawn yet. The clock is the wall's: a rehearsal waits
+ * as long as a take would, because how long a result takes is what a
+ * rehearsal is for.
+ */
+declare function pollCondition(page: RecorderPage, c: WaitCondition, opts: {
+    timeoutMs: number;
+    everyMs: number;
+    sleep: (ms: number) => Promise<void>;
+    now?: () => number;
+    between?: () => Promise<void>;
+    confirm?: {
+        reads: number;
+        gapMs: number;
+    };
+}): Promise<PollResult>;
+/** The DOM counts as settled after this long with no change. */
+declare const DOM_QUIET_MS = 800;
+/** The longest a settle waits on a page that never stops changing. */
+declare const DOM_SETTLE_CAP_MS = 5000;
+/**
+ * The page's own count of DOM changes: an observer installed once per
+ * document, read back as a number. A string, the one evaluate shape every
+ * driver shares.
+ */
+declare const DOM_CHANGE_PROBE = "(() => {\n  if (!window.__vosDomChanges) {\n    window.__vosDomChanges = { n: 0 };\n    new MutationObserver((list) => { window.__vosDomChanges.n += list.length })\n      .observe(document, { subtree: true, childList: true, attributes: true, characterData: true });\n  }\n  return window.__vosDomChanges.n;\n})()";
+/**
+ * Wait until the DOM has not changed for `quietMs`, at most `capMs`: what
+ * a page does after its network went quiet (a list rendered from data, a
+ * hydration). The count is polled from here rather than timed in the
+ * page, because a background tab throttles its own timers.
+ */
+declare function domSettled(page: RecorderPage, opts: {
+    sleep: (ms: number) => Promise<void>;
+    now?: () => number;
+    quietMs?: number;
+    capMs?: number;
+    tickMs?: number;
+}): Promise<{
+    settled: boolean;
+    ms: number;
+}>;
+/** Seconds as the recorder says them: `5 s`, `2.5 s`, `3 min 20 s`. */
+declare function sayDuration(ms: number): string;
+/** What the condition waits for, in words: `'#result' to appear`. */
+declare function sayCondition(c: WaitCondition): string;
+/** Why the condition did not hold, in words: `'Generate' stayed disabled for 5 s`. */
+declare function conditionMiss(c: WaitCondition, last: ConditionState, ms: number): string;
+
+/** The most a download keeps: a file the page made, never a disk's worth. */
+declare const OUTPUT_MAX_BYTES: number;
+/**
+ * A name the page suggested, made plain: its last path segment, control
+ * characters and leading dots removed, or `fallback` when nothing usable
+ * is left. A page chooses this name, so it is cleaned, never trusted.
+ */
+declare function plainName(suggested: string, fallback: string): string;
+/** The file name a URL's path ends in, decoded, or ''. */
+declare function nameFromUrl(url: string): string;
+/**
+ * The name a download is saved under: the step's `as` when it gave one,
+ * else the page's suggestion made plain, made unique among the names this
+ * take already used (`clip.mp4`, `clip-2.mp4`).
+ */
+declare function outputName(asked: string | undefined, suggested: string, fallback: string, used: ReadonlySet<string>): string;
+/** Read a stream of byte chunks whole, refusing past `max` bytes. */
+declare function readAllBytes(stream: AsyncIterable<unknown>, max?: number): Promise<Uint8Array>;
+/**
+ * Read a media element's source, run in the page on the element the
+ * step's selector matched through the locator engine: its `currentSrc`
+ * (what it is actually playing), else its `src`, else the attribute; ''
+ * while it has none yet. Self-contained, since it is serialized into the
+ * page.
+ */
+declare const readMediaSource: (el: RecorderMediaElement) => string;
+/**
+ * The expression that fetches a URL inside the page, for what the page
+ * alone can read (a `blob:` or a `data:` source): base64 and the type, or
+ * an error in words. Same-origin requests carry the page's cookies.
+ */
+declare function fetchInPageScript(url: string): string;
+
+/**
+ * The take's clock: ONE path from a wall-clock instant to footage time,
+ * for the cursor events and for every screencast frame alike.
+ *
+ * Footage time is wall time since `t0` minus every off-camera stretch (an
+ * `await`) that began before the instant; an instant inside a stretch reads
+ * as the stretch's start, which is where the cut is. A frame is placed by
+ * the instant it was CAPTURED, never by when its callback ran: a frame in
+ * flight when the capture paused lands after the resume and must still sit
+ * before the cut.
+ *
+ * Frame times are strictly increasing. The screencast does not promise it:
+ * a frame can arrive after a later one, and a frame without a capture
+ * timestamp is stamped by its arrival, a second clock. A frame whose time
+ * is not later than the last one kept holds older pixels than what the
+ * footage already shows, so it is DROPPED (never re-stamped forward, which
+ * would put a stale picture after a newer one).
+ */
+declare class TakeClock {
+    readonly t0: number;
+    private readonly pauses;
+    private lastFrameMs;
+    constructor(t0: number);
+    /** Footage ms at a wall-clock instant (`Date.now()` space). */
+    footageMs(wallMs: number): number;
+    /** The camera stops at this instant; returns the cut's footage ms. */
+    pause(wallMs: number): number;
+    /** The camera rolls again; returns the wall ms the stretch lasted. */
+    resume(wallMs: number): 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).
+     */
+    placeFrame(captureWallMs: number): number | null;
+}
 
-export { type ActionStep, type ActionsFile, type Arrival, DEAD_SHARE_WARN_PCT, DEAD_STRETCH_WARN_MS, type DeadReport, type DeadStep, EXPOSURE_ADVICE, EXPOSURE_MATCHERS_SRC, EXPOSURE_PROBE, type EncodePageOptions, type Exposure, type ExposureKind, ExposureLog, type FrameRec, type FrameSink, type FreezeSpan, type FreshPlanOptions, MOTION_TICK_MS, type MaskReport, type MaskRule, POINTER_MAX_MS, POINTER_MIN_MS, POINTER_MS_PER_PX, PRESS_HOLD_MS, PRESS_KEYS, PRESS_LEAD_MS, type PaceReport, type PressKey, QUIET_MS, READ_BEAT_MS, RESPONSE_MS, type RecordOpts, type RecordResult, type RecorderBrowser, type RecorderCdp, type RecorderClock, type RecorderConsoleMessage, type RecorderContext, type RecorderLocator, type RecorderLocatorRoot, 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, SetupEnvError, SetupError, type SetupResult, type SetupStep, type SetupText, type SkippedStep, type StepPace, TRAILING_HOLD_MS, WALL_PROBE, WallError, type WallKind, type WallVerdict, askedMs, base64Bytes, buildEncodePage, capReached, cappedLine, clampWait, clockMotion, clockTyping, deadLine, deadTime, deadWarns, easeInOutCubic, exposureLine, formatDurationCap, headersFor, holdLeftMs, isIdpHost, isSignInPath, jpegDims, maskInitScript, paceLine, paceReport, parseHeaders, planFreshTake, pointerTravelMs, publicUrl, realSleep, recordTake, redirectedAway, resolveSetupText, runSetup, scrollByScript, scrollTravelMs, settleMs, settleVerdict, setupEnvNames, urlSchemeProblem, validateActions, validateSetup, wallVerdict };
+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 };