@vosjs/render-core 0.2.9 → 0.3.1

package/dist/record/index.d.ts

@@ -0,0 +1,813 @@
+import { RecordingMeta, CursorEvent, Backdrop, RecordingArtifact, ProjectDoc } from '@vosjs/studio-core';
+
+/**
+ * The recorder's driver: what it needs from a browser, as a STRUCTURAL
+ * contract. Playwright's own `Browser`/`BrowserContext`/`Page` satisfy it
+ * unchanged, and so does `@cloudflare/playwright`'s (the same client
+ * surface over Browser Rendering), so the CLI hands in a launched Node
+ * browser and the fleet hands in a connected one, and the recorder never
+ * imports either package. Only the members the recorder calls are named
+ * here; a driver that offers more is fine, one that offers less fails to
+ * type.
+ *
+ * Frames leave through a `FrameSink`, never through a filesystem: the CLI's
+ * sink writes a take directory, the fleet's puts each JPEG to R2.
+ */
+interface RecorderRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface RecorderLocator {
+    waitFor(opts: {
+        state: 'visible';
+        timeout: number;
+    }): Promise<unknown>;
+    scrollIntoViewIfNeeded(): Promise<unknown>;
+    boundingBox(): Promise<RecorderRect | null>;
+    click(): Promise<unknown>;
+    fill(value: string): Promise<unknown>;
+}
+interface RecorderLocatorRoot {
+    first(): RecorderLocator;
+}
+interface RecorderResponse {
+    status(): number;
+}
+interface RecorderConsoleMessage {
+    type(): string;
+    text(): string;
+}
+interface RecorderPage {
+    goto(url: string, opts: {
+        waitUntil: 'networkidle';
+        timeout: number;
+    }): Promise<RecorderResponse | null>;
+    url(): string;
+    title(): Promise<string>;
+    evaluate<T>(pageFunction: string | (() => T)): Promise<T>;
+    on(event: 'console', cb: (m: RecorderConsoleMessage) => void): unknown;
+    locator(selector: string): RecorderLocatorRoot;
+    mouse: {
+        move(x: number, y: number): Promise<void>;
+        down(): Promise<void>;
+        up(): Promise<void>;
+        wheel(dx: number, dy: number): Promise<void>;
+    };
+    keyboard: {
+        type(text: string): Promise<void>;
+        press(key: string): Promise<void>;
+    };
+}
+interface RecorderCdp {
+    on(event: 'Page.screencastFrame', cb: (ev: {
+        data: string;
+        sessionId: number;
+        metadata: {
+            timestamp?: number;
+        };
+    }) => void): unknown;
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+interface RecorderContext {
+    newPage(): Promise<RecorderPage>;
+    addInitScript(script: string): Promise<unknown>;
+    setExtraHTTPHeaders(headers: Record<string, string>): Promise<unknown>;
+    newCDPSession(page: unknown): Promise<RecorderCdp>;
+    close(): Promise<void>;
+}
+interface RecorderBrowser {
+    newContext(opts: {
+        viewport: {
+            width: number;
+            height: number;
+        };
+        deviceScaleFactor: number;
+        storageState?: string;
+        extraHTTPHeaders?: Record<string, string>;
+    }): Promise<RecorderContext>;
+}
+/**
+ * Where the screencast's frames go. `frame` is called in order with the
+ * JPEG bytes; the recorder keeps the index (`file`, `tMs`) itself. The CLI
+ * writes `frames/<file>`; the fleet puts to R2. A sink may be async and
+ * slow: the recorder never awaits it on the screencast's own thread, so a
+ * slow store costs no frames, only memory until it catches up.
+ */
+interface FrameSink {
+    frame(file: string, bytes: Uint8Array): Promise<void> | void;
+}
+/** The clock and the pauses, injectable so a rehearsal runs fast. */
+interface RecorderClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+declare const realSleep: (ms: number) => Promise<void>;
+
+/**
+ * The recorder's pace — the pure parts.
+ *
+ * A take of a scripted flow should run as long as the script asks, plus the
+ * gestures a person makes between the asks (the pointer's travel, the press,
+ * the settle after it) and no more. Measured before this module (§4.5 of
+ * the utility-clip retrospective), hovers ran 2× their ask, drags 4.8× and
+ * a 25 s script recorded 42 s, for two reasons the numbers here answer:
+ *
+ *  - The motion loops counted STEPS (one per 16 ms of the asked duration)
+ *    and awaited a `mouse.move` round trip per step, so a page that
+ *    re-renders per move (a slider) stretched every gesture by the round
+ *    trip. A gesture is now driven by the CLOCK: its position is a function
+ *    of the elapsed time, and it ends when the asked duration has elapsed,
+ *    however many samples the page allowed.
+ *  - The settles after a gesture were fixed sleeps (500 ms after a click,
+ *    250 after every selector lookup). A settle is DATA: `ms` on the step
+ *    overrides a small default, and the script's own `wait` steps carry
+ *    the intended pauses.
+ */
+/** Pointer travel: ms per CSS px, floor and ceiling — a person's hand. */
+declare const POINTER_MS_PER_PX = 0.7;
+declare const POINTER_MIN_MS = 250;
+declare const POINTER_MAX_MS = 800;
+/** The sample cadence a motion loop aims for. */
+declare const MOTION_TICK_MS = 16;
+/** The settle after a gesture when the step names none, by verb. */
+declare const SETTLE_MS: {
+    readonly click: 150;
+    readonly type: 150;
+    readonly scroll: 200;
+    readonly drag: 80;
+};
+/** The press: the pause before the button goes down, and the hold. */
+declare const PRESS_LEAD_MS = 80;
+declare const PRESS_HOLD_MS = 70;
+/** The pause between a selector lookup that scrolled the page and the move. */
+declare const SCROLL_SETTLE_MS = 120;
+/** The hold after the last step, so the take does not cut on a press. */
+declare const TRAILING_HOLD_MS = 400;
+/** How long the pointer takes to travel `dist` CSS px. */
+declare function pointerTravelMs(dist: number): number;
+/**
+ * A click's `ms` is READING time, held from the page's last visual change,
+ * and the recorder pays the settle itself: the same `ms` was read on one
+ * run and dead on the next because the hold started at the press and the
+ * page's settle varied run to run (0.3 s to 0.7 s on the same step).
+ *
+ * The settle is watched on the screencast, which emits only on change:
+ * after the press, a change that arrives within RESPONSE_MS says the page
+ * is answering, and it has settled once QUIET_MS pass with no new frame.
+ * No change within RESPONSE_MS means the page did not change (a click that
+ * only moves state) and the settle is over. SETTLE_CAP_MS bounds a page
+ * that never stops changing (a playing preview), which is a page nothing
+ * is dead on, so the hold simply starts.
+ */
+declare const RESPONSE_MS = 400;
+declare const QUIET_MS = 250;
+declare const SETTLE_CAP_MS = 1200;
+/**
+ * Is the page settled? Pure: the recorder feeds it what it knows at each
+ * tick since the press.
+ */
+declare function settleVerdict(t: {
+    /** ms since the press. */
+    sincePress: number;
+    /** ms since the last screencast frame, or null when none arrived since the press. */
+    sinceChange: number | null;
+}, c?: {
+    response: number;
+    quiet: number;
+    cap: number;
+}): 'wait' | 'settled';
+/**
+ * What is left of a hold once the settle is detected: the hold is measured
+ * from the last change, so the quiet already spent counts toward it.
+ */
+declare function holdLeftMs(holdMs: number, sinceChange: number | null): number;
+/** The settle after a step: its own `ms` when it names one, else the verb's. */
+declare function settleMs(step: {
+    do: string;
+    ms?: number;
+}): number;
+declare const easeInOutCubic: (u: number) => number;
+/**
+ * Drive a motion by the clock: `at(u)` is called with the eased progress
+ * for each sample, and the loop ends when `dur` ms have elapsed, with the
+ * last call at u = 1 exactly. Between samples it sleeps to the next tick
+ * only when the sample came back early; a slow sample (a page busy
+ * re-rendering) is followed at once, so the gesture keeps its length and
+ * loses samples, never the other way round.
+ */
+declare function clockMotion(dur: number, at: (u: number) => Promise<void>, clock: {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}): Promise<number>;
+/**
+ * Typing paced by the clock: the i-th character is due at `start + i·delay`;
+ * after each keystroke the loop sleeps to the next due time only if the
+ * keystroke came back early. A slow field (an editor re-rendering per key)
+ * types as fast as it can and says so in the pace report.
+ */
+declare function clockTyping(chars: readonly string[], delay: number, type: (ch: string, index: number) => Promise<void>, clock: {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}): Promise<void>;
+/** One step's pace: what the script asked for it and what it took. */
+interface StepPace {
+    step: number;
+    do: string;
+    /** The script's own ask: a wait's ms, a hover's dwell, a drag's ms, typing's chars × delay, a click's read after the settle; 0 for a scroll. */
+    askedMs: number;
+    /** The gesture the recorder adds by design: pointer travel, the press, the settle. */
+    gestureMs: number;
+    wallMs: number;
+}
+interface PaceReport {
+    askedMs: number;
+    gestureMs: number;
+    wallMs: number;
+    /** Wall time neither asked nor a gesture: what the page and the round trips cost. */
+    overheadMs: number;
+    overheadPct: number;
+    /** The steps whose wall ran past their ask plus gesture by more than a third. */
+    slow: {
+        step: number;
+        do: string;
+        askedMs: number;
+        wallMs: number;
+    }[];
+}
+/** What a script asks of a step, in ms: the part of its wall time that is the author's. */
+declare function askedMs(step: {
+    do: string;
+    ms?: number;
+    text?: string;
+    delayMs?: number;
+}): number;
+declare function paceReport(steps: readonly StepPace[]): PaceReport;
+/** The pace in one line for the log. */
+declare function paceLine(r: PaceReport): string;
+/**
+ * DEAD TIME, the smoothness fact that replaces the freeze share as the
+ * warning. A still frame is not a defect: a page the viewer is reading is
+ * content, and a workspace tour is mostly still. What is dead is a still
+ * frame under a PARKED cursor past the beat it takes to read what changed:
+ * after that the picture, the pointer and the camera all hold and nothing
+ * is being said. So the derivation reads, per step, when the page settled
+ * after the step's act, how long the settled frame was held, and whether
+ * the cursor moved in that hold; a hold past the reading beat is dead.
+ *
+ * The beat is longer after a page changed (a navigation shows a whole new
+ * page to take in) than after a control changed (one thing to see).
+ */
+declare const READ_BEAT_MS: {
+    readonly page: 1000;
+    readonly control: 600;
+};
+/** A dead stretch this long is a warning on its own, whatever the share. */
+declare const DEAD_STRETCH_WARN_MS = 1500;
+/** The share of the take past which dead time is a warning. */
+declare const DEAD_SHARE_WARN_PCT = 20;
+interface DeadStep {
+    step: number;
+    id?: string;
+    do: string;
+    /** ms from the step's act (its press, else its start) to the last frame change in the step. */
+    settledMs: number;
+    /** ms the settled frame was held before the step ended. */
+    heldMs: number;
+    /** the hold past the reading beat, while the cursor was parked; 0 when the hold was read or the pointer moved. */
+    deadMs: number;
+}
+interface DeadReport {
+    ms: number;
+    pct: number;
+    /** the steps that carried any dead time, in order. */
+    steps: DeadStep[];
+    /** the longest single dead hold. */
+    longestMs: number;
+}
+declare function deadTime(steps: readonly {
+    step: number;
+    id?: string;
+    do: string;
+    tStart: number;
+    tEnd: number;
+    navigated?: boolean;
+}[], frames: readonly {
+    tMs: number;
+}[], events: readonly {
+    t: number;
+    type: string;
+}[], durationMs: number): DeadReport;
+/** Whether a dead report earns a warning: the share, or one long hold. */
+declare function deadWarns(r: DeadReport): boolean;
+/** The dead time in words, naming the steps and what to cut. */
+declare function deadLine(r: DeadReport): 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
+ * email address in the header, a key on a settings page, a card number.
+ * Asking nicely does not hold this line (a person asked to sign in with a
+ * demo account signs in as themselves, because it is the account they have),
+ * so the recorder looks.
+ *
+ * Two pieces, both run IN the page:
+ *
+ * - the EXPOSURE scan reads the text that is visible in the viewport after
+ *   each step and reports the KIND of thing it saw and where. Never the
+ *   string itself: a report that quotes the secret is a second leak.
+ * - a MASK hides a selector before the first frame is captured and keeps it
+ *   hidden across navigations and re-renders, so the real value is never in
+ *   a frame, never in the recording, never pushed. `as: 'text'` swaps the
+ *   words (a product reads better than a redaction); `as: 'blur'` blurs.
+ *
+ * The matchers are ONE plain-JavaScript source string, evaluated in the page
+ * and, by the tests, in Node: a function serialized out of a bundle picks up
+ * the bundler's `__name` helper and dies in the page, and two copies of a
+ * regex drift.
+ */
+
+type ExposureKind = 'email' | 'key' | 'card' | 'card-tail';
+type Exposure = NonNullable<RecordingMeta['exposures']>[number];
+type MaskReport = NonNullable<RecordingMeta['masks']>[number];
+interface MaskRule {
+    selector: string;
+    /** `blur` (default) blurs the element; `text` swaps its words for `text`. */
+    as?: 'blur' | 'text';
+    text?: string;
+}
+/**
+ * `kindsIn(text)` → the kinds of sensitive-looking strings in `text`.
+ *
+ * - email: any address, EXCEPT one on a domain that can reach no one
+ *   (example.com/.org/.net, and the reserved .test/.example/.invalid/
+ *   .localhost TLDs), which is what demo data should use.
+ * - key: the prefixes of keys people actually paste into dashboards, and a
+ *   JWT's three base64url parts.
+ * - card: 13 to 19 digits that pass the Luhn check, so an order number or a
+ *   phone number is not a card.
+ * - 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 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.\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})()";
+/**
+ * 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
+ * MutationObserver re-applies it after a client-side re-render. A form
+ * control is blurred even when `as: 'text'` was asked for: writing into an
+ * input would change what the app submits.
+ */
+declare function maskInitScript(masks: MaskRule[]): string;
+/**
+ * Accumulates scans across a take: an exposure is reported ONCE, at the
+ * first step it was seen, with how many scans saw it.
+ */
+declare class ExposureLog {
+    private byKey;
+    private maskHits;
+    constructor(masks?: MaskRule[]);
+    add(step: number, scan: {
+        exposures?: Omit<Exposure, 'step' | 'seen'>[];
+        maskHits?: Record<string, number>;
+    } | null): void;
+    exposures(): Exposure[];
+    masks(rules: MaskRule[]): MaskReport[];
+}
+/** 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.";
+
+/**
+ * `setup`: the steps that run BEFORE the camera rolls. A sign-in form, a
+ * cookie banner, the "choose your editor" modal, an onboarding tour: things
+ * a take must get past and must not show. They run after the first
+ * navigation and before `Page.startScreencast`, with no cursor synthesis,
+ * no pace accounting and nothing written to `meta.steps`. Then the recorder
+ * navigates to `url` again and the take begins where the setup left it.
+ *
+ * A `type` step's `text` may be `{ "env": "DEMO_PASSWORD" }`: resolved at run
+ * time from the `env` the caller hands in (the shell's for the CLI, the
+ * job's own map for a hosted take), never logged, never stored. The
+ * guarantee is narrow and real: the secret is never in a file that travels
+ * (`actions.json` is committed and pushed with the take; `meta.json` is read
+ * by the digest) and never in the footage.
+ */
+
+type SetupText = string | {
+    env: string;
+};
+type SetupStep = ({
+    do: 'wait';
+    ms: number;
+} | {
+    do: 'click';
+    selector: string;
+    ms?: number;
+} | {
+    do: 'type';
+    selector: string;
+    text: SetupText;
+    ms?: number;
+} | {
+    do: 'press';
+    key: string;
+    ms?: number;
+} | {
+    do: 'goto';
+    url: string;
+}) & {
+    id?: string;
+};
+/** Structural validation, mirrored on `validateActions` for `steps`. */
+declare function validateSetup(value: unknown): string[];
+/** The names a setup reads from its env, so a host can say what it must supply. */
+declare function setupEnvNames(steps: SetupStep[] | undefined): string[];
+/** A `{ env }` text resolved, or thrown in words. The value is never returned to a log. */
+declare function resolveSetupText(t: SetupText, env: Record<string, string | undefined>): {
+    value: string;
+    secret: boolean;
+};
+interface SetupResult {
+    ran: number;
+    /** what the log may say about each step: the verb and the selector, never a typed value */
+    lines: string[];
+    /** a selector that never appeared; the take does not start */
+    failed?: {
+        step: number;
+        do: string;
+        selector?: string;
+    };
+}
+/**
+ * Run the setup on a page, with plain Playwright actions: no humanized
+ * pointer, no cursor events, no frames. A selector that never appears
+ * fails the setup, because a take that begins at a half-finished sign-in is
+ * the wall by another name.
+ */
+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>;
+}): Promise<SetupResult>;
+/** A `{ env }` the shell did not provide: a usage error, not a page's. */
+declare class SetupEnvError extends Error {
+    constructor(message: string);
+}
+/** A setup step whose selector never appeared: the take does not start. */
+declare class SetupError extends Error {
+    failed: NonNullable<SetupResult['failed']>;
+    constructor(failed: NonNullable<SetupResult['failed']>);
+}
+/** `--header name=value`, repeatable: extra request headers on every request. */
+declare function parseHeaders(given: string[] | undefined): Record<string, string>;
+
+/**
+ * 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
+ * executes it with humanized cursor motion and synthesizes the CursorTrack
+ * from its own dispatches.
+ */
+interface ActionsFile {
+    /** Page to record. `--url` overrides. */
+    url?: string;
+    /** Recording viewport in CSS px (default 1280x720). */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Hidden BEFORE the first frame is captured and kept hidden across
+     * navigations: what a signed-in account shows that must not ship. `blur`
+     * (default) blurs the element; `text` swaps its words for `text`, which is
+     * for IDENTIFIERS (an email, a name, an account id), never for product
+     * copy or numbers: the video must stay true to the product.
+     */
+    mask?: MaskRule[];
+    /**
+     * Run BEFORE the camera rolls, after the first navigation: a sign-in form,
+     * a cookie banner, an onboarding tour. Plain actions with no cursor, no
+     * frames, no pace and nothing in `meta.steps`; then the recorder opens
+     * `url` again and the take begins where the setup left it. A `type`
+     * step's text may be `{ env: 'NAME' }`, read at run time and never logged
+     * or stored.
+     */
+    setup?: SetupStep[];
+    steps: ActionStep[];
+}
+type ActionStep = ({
+    do: 'wait';
+    ms: number;
+} | {
+    do: 'hover';
+    selector: string;
+    ms?: number;
+}
+/** `ms` is the settle after the press (default 150). */
+ | {
+    do: 'click';
+    selector: string;
+    ms?: number;
+}
+/**
+ * Type into `selector`. The recorder clicks the field first, which is what
+ * opens the typing zoom on it; `focus: false` types into the field as it is
+ * already focused, for a keystroke that follows earlier typing (a submitting
+ * Enter) rather than starting it — a second click there rings a click effect
+ * on empty space beside the text.
+ */
+ | {
+    do: 'type';
+    selector: string;
+    text: string;
+    delayMs?: number;
+    focus?: boolean;
+    /** the settle after the last character (default 150) */
+    ms?: number;
+}
+/** `ms` is the settle after the scroll lands (default 200). */
+ | {
+    do: 'scroll';
+    dy: number;
+    ms?: number;
+} | {
+    do: 'move';
+    x: number;
+    y: number;
+}
+/**
+ * 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).
+ */
+ | {
+    do: 'drag';
+    selector?: string;
+    x?: number;
+    y?: number;
+    tx: number;
+    ty: number;
+    ms?: number;
+}) & {
+    /**
+     * 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
+     * edits without breaking the cut anchored to it. Unique when present.
+     */
+    id?: string;
+    /**
+     * A beat's caption, two to eight words: `vos deliver` lands it as a
+     * lower-third at this step's moment on the cuts that take words, and
+     * `vos actions script` leads the beat with it.
+     */
+    caption?: string;
+};
+/** Structural validation with actionable messages. Returns [] when valid. */
+declare function validateActions(value: unknown): string[];
+
+/**
+ * The wall check: did the recorder land where it was asked, or in front of
+ * a sign-in? A take of a product behind a login, recorded without a session,
+ * used to succeed: the footage was the login page (or wherever the site
+ * sends a stranger), and the only symptom was a skipped selector. This says
+ * it in words, before a frame is captured and before a re-record clears the
+ * footage it would have replaced.
+ *
+ * Pure: the recorder gathers the evidence, this decides. A heuristic is
+ * acceptable because both failure directions are cheap: a false refusal
+ * costs one flag (`--allow-wall`), a false pass costs what every such take
+ * cost before.
+ */
+/** What the recorder saw once the first navigation settled. */
+interface Arrival {
+    askedUrl: string;
+    landedUrl: string;
+    /** HTTP status of the main document, when the navigation produced one. */
+    status?: number;
+    /** `input[type=password]` fields that are visible on the page. */
+    passwordFields: number;
+    /** A password field marked `autocomplete="new-password"` (a settings or sign-up form). */
+    newPasswordField: boolean;
+    /** A visible one-time-code field (`autocomplete="one-time-code"`). */
+    oneTimeCodeField: boolean;
+}
+type WallKind = 
+/** the asked URL answered 401 or 403 */
+'status'
+/** landed on an identity provider's host */
+ | 'idp'
+/** landed on a sign-in form or a sign-in path */
+ | 'signin'
+/** sent somewhere else, with no sign-in in sight (a site that shows strangers a public page) */
+ | 'redirect';
+interface WallVerdict {
+    kind: WallKind;
+    /**
+     * `hard` is refused always; `soft` is refused under `--strict` and said as
+     * a warning otherwise, because a redirect alone is not proof of a wall.
+     */
+    level: 'hard' | 'soft';
+    /** origin + path, never the query or hash (they can carry tokens). */
+    asked: string;
+    landed: string;
+    message: string;
+}
+declare function isIdpHost(host: string): boolean;
+declare function isSignInPath(pathname: string): boolean;
+/**
+ * Sent AWAY, as opposed to sent deeper. `/` → `/en`, `/docs` → `/docs/start`
+ * and `/pricing` → `/en/pricing` are a site arranging itself; `/dashboard` →
+ * `/gallery` is a site declining to show the page. `www.` and the apex are
+ * one host.
+ */
+declare function redirectedAway(asked: URL, landed: URL): boolean;
+declare function wallVerdict(a: Arrival): WallVerdict | null;
+/** A take refused at the wall. Carries the verdict for `--json`. */
+declare class WallError extends Error {
+    verdict: WallVerdict;
+    constructor(verdict: WallVerdict);
+}
+/**
+ * Evidence gathered in the page. A STRING, never a function: a serialized
+ * function picks up the bundler's `__name` helper and dies in the page.
+ */
+declare const WALL_PROBE = "(() => {\n  const shown = (el) => {\n    const r = el.getBoundingClientRect()\n    if (r.width < 2 || r.height < 2) return false\n    const s = getComputedStyle(el)\n    return s.visibility !== 'hidden' && s.display !== 'none'\n  }\n  const pw = [...document.querySelectorAll('input[type=\"password\"]')].filter(shown)\n  const otp = [...document.querySelectorAll('input[autocomplete=\"one-time-code\"]')].filter(shown)\n  return {\n    passwordFields: pw.length,\n    newPasswordField: pw.some((el) => (el.getAttribute('autocomplete') || '').includes('new-password')),\n    oneTimeCodeField: otp.length > 0,\n  }\n})()";
+
+/**
+ * The recorder — a browser drives the action script while:
+ *  - CDP Page.startScreencast collects JPEG frames (epoch-timestamped;
+ *    hold-last-frame gaps are filled at encode time), and
+ *  - every dispatched input is logged as a CursorEvent (the synthesized track:
+ *    exact coords, exact times, fresh element rects — no capture needed).
+ *
+ * The MECHANISM, host-free (AN4): the browser arrives as a structural driver
+ * (a launched Node Playwright browser from the CLI, a connected
+ * @cloudflare/playwright browser from the fleet), frames leave through a
+ * sink, the platform and the setup env are handed in, and nothing here
+ * touches a filesystem or a process. The CLI's `recordTake` wraps this with
+ * a take directory; the fleet's consumer wraps it with R2. Both produce the
+ * same events, meta and frame index for the same script.
+ */
+
+interface FrameRec {
+    file: string;
+    /** ms since t0 */
+    tMs: number;
+}
+interface SkippedStep {
+    /** index into actions.steps */
+    step: number;
+    do: string;
+    selector: string;
+}
+/** A stretch with no screencast frames — the page pixels did not change. */
+interface FreezeSpan {
+    /** seconds into the take */
+    from: number;
+    to: number;
+    ms: number;
+}
+interface RecordResult {
+    events: CursorEvent[];
+    frames: FrameRec[];
+    meta: RecordingMeta;
+    /** The take's pace: what the script asked, what the gestures added, what the page cost. */
+    pace: PaceReport;
+    /** steps whose selector never became visible — the take continued without them. */
+    skipped: SkippedStep[];
+    /** the initial goto never reached networkidle (recording proceeded anyway). */
+    navTimeout: boolean;
+    /** 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']>;
+    /** The script's masks with how many elements each reached; hits 0 hid nothing. */
+    masks: NonNullable<RecordingMeta['masks']>;
+    /**
+     * Smoothness telemetry: stretches ≥400ms with no visual change. Frozen
+     * footage is the #1 enemy of a smooth product video — either the flow should
+     * keep motion in frame (animate, hover a preview, scroll) or the doc should
+     * trim/speed through these. freezePct = share of the take that is frozen.
+     */
+    freezes: FreezeSpan[];
+    freezePct: number;
+    /**
+     * The smoothness WARNING: still footage under a parked cursor past the
+     * beat it takes to read what changed, per step (`deadTime`). A still page
+     * being read is content; this is the part of a hold nobody is reading.
+     */
+    dead: DeadReport;
+    /** The take reached --max-duration and stopped there; later steps did not run. */
+    capped: boolean;
+    /** The actions as recorded, `url` resolved: what a take directory writes back. */
+    actions: ActionsFile;
+}
+interface RecordOpts {
+    /** Stop the capture at this many seconds (the hosted cap). */
+    maxDurationSeconds?: number;
+    /**
+     * Path to a Playwright storage state (cookies + origin storage), so the
+     * recorder drives a SIGNED-IN product. A demo of anything behind a login
+     * needs it, and a sign-in form cannot always be scripted (an emailed code,
+     * an SSO hop). Export one from a real browser, or with
+     * `context.storageState({ path })`.
+     */
+    storageState?: string;
+    /**
+     * REHEARSE the flow: every step runs against the real page, in order,
+     * because a later selector usually exists only after an earlier click. But
+     * nothing is captured (no screencast, no frames), nothing is written, the
+     * pointer lands instead of travelling and every pause is cut to a beat, so
+     * a script that misses a selector says so in seconds instead of after a
+     * full real-time take and its encode. Selector lookups keep their whole
+     * timeout, so a miss here is a miss in the take.
+     */
+    dryRun?: boolean;
+    /**
+     * Called once the first navigation has settled, BEFORE a frame is captured.
+     * The caller judges the wall here and only then prepares the take
+     * directory, so a take refused at a sign-in never clears the footage a
+     * re-record would have replaced. A throw closes the context and propagates.
+     */
+    onArrival?: (arrival: Arrival) => Promise<WallVerdict | null | void> | WallVerdict | null | void;
+    /** Extra request headers on every request (`--header name=value`). */
+    headers?: Record<string, string>;
+    /**
+     * A ready-made context to record IN, instead of one made from `browser`:
+     * `--session <name>`, a persistent profile the person signed in to. The
+     * recorder still sizes the viewport and closes it at the end.
+     */
+    context?: RecorderContext;
+    /**
+     * The environment a setup's `{ env }` texts resolve from: the shell's
+     * for the CLI, the job's own map on the fleet. Absent means no env at
+     * all, so a setup that reads one fails in words.
+     */
+    env?: Record<string, string | undefined>;
+    /** The platform the take is recorded on, for `meta.platform`. */
+    platform?: RecordingMeta['platform'];
+}
+/** Minimal JPEG SOF parse for real encoded dimensions. */
+declare function jpegDims(buf: Uint8Array): {
+    w: number;
+    h: number;
+} | null;
+/** 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>;
+
+/**
+ * The recording cap as the recorder applies it, pure. WHAT the cap is
+ * (the hosted plan's number, read from `GET /api/limits`) is a vos.so fact
+ * and stays in the CLI's platform client; the recorder only knows a number
+ * of seconds and stops there.
+ */
+/** True once the take has reached the cap — the recorder stops driving steps. */
+declare function capReached(elapsedMs: number, capSeconds: number): boolean;
+/** A wait step never sleeps past the cap. */
+declare function clampWait(waitMs: number, elapsedMs: number, capSeconds: number): number;
+/** `30 min`, `1 h 30 min`, `45 s` — the duration cap in words. */
+declare function formatDurationCap(seconds: number): string;
+/** The one line printed when the cap stopped the take. */
+declare function cappedLine(capSeconds: number): string;
+
+/**
+ * Frames → CFR WebM, as a PAGE. The VFR screencast JPEGs are drawn
+ * hold-last-frame onto a canvas at a fixed 30fps and encoded with
+ * mediabunny (WebCodecs) inside a headless page — no ffmpeg dependency.
+ * The CLI serves the take directory to it and reads the bytes back through
+ * its own `/save`; the fleet serves the frames through the ingest route and
+ * the page PUTs the recording to the same route. One page, two hosts: the
+ * URLs and the way out are the host's, the encode is not.
+ */
+interface EncodePageOptions {
+    /** Where `frames.json` (the index `[{file, tMs}]`) is fetched from. */
+    framesIndexUrl: string;
+    /** Where `meta.json` is fetched from. */
+    metaUrl: string;
+    /** `<framesBaseUrl><file>` is each JPEG. */
+    framesBaseUrl: string;
+    /** The way out: a POST to the CLI's take server, or a PUT to the ingest route. */
+    save: {
+        method: 'POST' | 'PUT';
+        url: string;
+    };
+    /** Optional `?rt=`-style query the frame fetches must carry (the fleet's token). */
+    frameQuery?: string;
+}
+declare function buildEncodePage(o: EncodePageOptions): string;
+
+interface FreshPlanOptions {
+    /** The backdrop the document opens on; absent keeps the bare frame. */
+    backdrop?: Backdrop | null;
+    /** A digest's activity bins, when one exists (the speed planner's witness). */
+    activity?: readonly number[] | null;
+}
+declare function planFreshTake(artifact: RecordingArtifact, recordingName: string, opts?: FreshPlanOptions): ProjectDoc;
+
+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_LEAD_MS, type PaceReport, 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, 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, holdLeftMs, isIdpHost, isSignInPath, jpegDims, maskInitScript, paceLine, paceReport, parseHeaders, planFreshTake, pointerTravelMs, realSleep, recordTake, redirectedAway, resolveSetupText, runSetup, settleMs, settleVerdict, setupEnvNames, validateActions, validateSetup, wallVerdict };