@vosjs/render-core 0.8.0 → 0.10.0

package/dist/record/index.d.ts

@@ -1,4 +1,5 @@
-import { RecordingMeta, CursorEvent, RecordingSkip, RecordingOutput, Backdrop, RecordingArtifact, ProjectDoc, RecordingPageMedia } from '@vosjs/studio-core';
+import { RecordingMeta, PeerStepSpan, CursorEvent, RecordingSkip, RecordingOutput, Backdrop, RecordingArtifact, ProjectDoc, RecordingPageMedia } from '@vosjs/studio-core';
+export { PeerStepSpan } from '@vosjs/studio-core';
 
 /**
  * The recorder's driver: what it needs from a browser, as a STRUCTURAL
@@ -415,6 +416,156 @@ declare function deadWarns(r: DeadReport): boolean;
 /** The dead time in words, naming the steps and what to cut. */
 declare function deadLine(r: DeadReport): string;
 
+/**
+ * `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.
+ *
+ * `teardown`: the same steps, run AFTER the take, off camera too: what the
+ * take created in the product (an API key, a project, an invite) removed
+ * again, so a rehearsal or a re-record leaves the account as it found it.
+ * They run once the screencast has stopped, on the take's own page and
+ * context (a session's cookies apply), and also when the take stops early
+ * or throws once its first step has run. A teardown that fails never fails
+ * the take: the footage is fine, and what is left behind is reported.
+ */
+
+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;
+};
+/** Which list a step belongs to, as its messages and log lines name it. */
+type StepPhase = 'setup' | 'teardown';
+/**
+ * Why a page address is not one the recorder opens, or null. A script's
+ * `url` and a setup's `goto` open a browser, so only http and https are
+ * taken: a `file:` address would read this machine's disk into a take
+ * and a `javascript:` one would run in the page.
+ */
+declare function urlSchemeProblem(url: string): string | null;
+/**
+ * Structural validation, mirrored on `validateActions` for `steps`. The
+ * same verbs and rules hold for `teardown`; `phase` names the list.
+ */
+declare function validateSetup(value: unknown, phase?: StepPhase): 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[];
+/**
+ * Every name a script reads from its env, its setup's and its teardown's,
+ * each once: what a host must supply before the take begins.
+ */
+declare function scriptEnvNames(script: {
+    setup?: SetupStep[];
+    teardown?: SetupStep[];
+}): 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>, phase?: StepPhase): {
+    value: string;
+    secret: boolean;
+};
+/**
+ * The first `{ env }` a teardown reads that `env` does not hold, in words,
+ * or null. Asked BEFORE the take: a take that creates something its
+ * teardown cannot then remove is the one case teardown exists for.
+ */
+declare function teardownEnvProblem(steps: SetupStep[] | undefined, env: Record<string, string | undefined>): string | null;
+interface SetupResult {
+    ran: number;
+    /** what the log may say about each step: the verb and the selector, never a typed value */
+    lines: string[];
+    /**
+     * The step that failed: for a setup, a selector that never appeared (the
+     * take does not start); for a teardown, the step it stopped at. `error`
+     * is the driver's reason, one line, never a typed value.
+     */
+    failed?: {
+        step: number;
+        do: string;
+        selector?: string;
+        error?: string;
+    };
+}
+/** How long a whole teardown may take before it is stopped and reported. */
+declare const TEARDOWN_BOUND_MS = 60000;
+/**
+ * What a teardown did, on the take's result: how many of its steps ran,
+ * and where it stopped. Never a typed value.
+ */
+interface TeardownReport {
+    ran: number;
+    of: number;
+    failed?: {
+        step: number;
+        do: string;
+        selector?: string;
+        error: string;
+    };
+}
+/** The teardown in one line, for the end of a take or a rehearsal. */
+declare function teardownLine(report: TeardownReport): string;
+/**
+ * Run the setup (or the teardown) on a page, with plain Playwright actions:
+ * no humanized pointer, no cursor events, no frames. A selector that never
+ * appears fails the steps there, because a take that begins at a
+ * half-finished sign-in is the wall by another name. With `boundMs`, the
+ * steps together run no longer than that: the step running when it passes
+ * fails, and the call it left pending is abandoned.
+ */
+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>;
+    /** Which list these are, for the log and the messages (default `setup`). */
+    phase?: StepPhase;
+    /** The longest the steps may take together, in ms. */
+    boundMs?: number;
+    now?: () => number;
+}): 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 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
@@ -563,99 +714,6 @@ declare function noticeLine(n: Notice): string;
  */
 declare function noticeAdvice(notices: readonly Pick<Notice, 'kind'>[]): string;
 
-/**
- * `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;
-};
-/**
- * Why a page address is not one the recorder opens, or null. A script's
- * `url` and a setup's `goto` open a browser, so only http and https are
- * taken: a `file:` address would read this machine's disk into a take
- * and a `javascript:` one would run in the page.
- */
-declare function urlSchemeProblem(url: string): string | null;
-/** 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>;
-    /** 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 {
-    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>;
-
 /**
  * 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
@@ -872,6 +930,278 @@ 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;
 
+/**
+ * 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;
+    /**
+     * A JavaScript expression evaluated in the page (awaited when it answers
+     * a promise): the condition holds when its value is truthy, or, with
+     * `equals`, when its value equals that one. For an app that keeps its
+     * state in script rather than in the DOM (a canvas, a document model).
+     */
+    js?: string;
+    /** with `js`: the value the expression must equal (compared as JSON) */
+    equals?: unknown;
+}
+/** 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;
+    /**
+     * with `js`: what the expression answered the last time it was read, as
+     * JSON when it has a JSON form (absent for `undefined`), and in words
+     * either way (`said`), or the error it threw (`threw`).
+     */
+    value?: unknown;
+    said?: string;
+    threw?: string;
+}
+/**
+ * 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;
+/** The longest a js value is said in a line, in characters. */
+declare const JS_SAID_MAX = 120;
+/** The most a js value kept on the step holds, in characters of JSON. */
+declare const JS_VALUE_MAX = 2048;
+/**
+ * The page script that evaluates a step's expression and answers what it
+ * found, as a string (the one evaluate shape every driver shares). The
+ * expression is the script author's own, run on their own page: it is
+ * wrapped, never parsed, and a newline closes it before the paren so a
+ * trailing line comment cannot swallow the wrapper.
+ */
+declare function jsConditionScript(expr: string): string;
+/** Two JSON values alike: the same keys and values whatever the key order. */
+declare function sameJson(a: unknown, b: unknown): boolean;
+/**
+ * A js value as a step keeps it (`meta.steps[].value`): the value itself
+ * while its JSON fits, else its JSON cut short as a string.
+ */
+declare function keptValue(value: unknown): unknown;
+/** 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;
+/** An expression as a line names it: in backticks, cut short. */
+declare function sayJs(expr: string): string;
+/** A kept value as a line says it: its JSON, cut short. */
+declare function sayValue(value: unknown): string;
+
+/**
+ * `peers`: other people on the same page, off camera. A collaboration
+ * product shows best with a second person on the canvas: their cursor, the
+ * shape they drew, the comment they left, arriving in the filmed page the
+ * way the app syncs them. A peer is a second browser context (its own
+ * cookies, so its own user, from its own storage state or none) on the
+ * same URL, driven by its own step list, interleaved with the take's.
+ *
+ * What a peer is, and is not:
+ *
+ * - NOT FILMED. Only the take's own page is captured. A peer's page is
+ *   never screencast, scanned, masked or listened to; what it does reaches
+ *   the footage only through the app (its sync, its presence, its remote
+ *   cursors), which is what a viewer would see.
+ * - NOT ON THE CURSOR TRACK. A peer's pointer moves its own page; the take's
+ *   CursorTrack is synthesized from the take's own steps alone, so a zoom,
+ *   a click ring or a dwell is never planned on a peer's gesture.
+ * - ORDERED BY THE TAKE'S STEPS. A peer step may name a take step by id:
+ *   `with` starts it as that step starts (the two run together), `after` as
+ *   that step ends. A step naming neither follows the peer's previous step
+ *   at once; a peer's first step with neither starts as the camera rolls.
+ *   The take never waits on a peer: it waits on what the peer's work
+ *   SHOWS, with an `expect` or an `await` on its own page, so the footage
+ *   holds exactly the moment the sync landed. When the take's steps end,
+ *   a peer step still waiting on a trigger never runs (said), and one
+ *   already running finishes, bounded, before the trailing hold.
+ * - PACED, NOT INSTANT. A peer's pointer glides on the same clock as the
+ *   take's (an app that draws remote cursors shows it travelling) and its
+ *   typing is paced per key, so what it does reads as a person.
+ * - BOUNDED. Every peer step runs inside its own bound, as a take step
+ *   does; a selector that never appears or a check that never holds is a
+ *   skip with its reason, listed with the take's (`--strict` fails on it).
+ *
+ * A peer takes the take's gestures and checks (`wait`, `move`, `hover`,
+ * `click`, `type`, `press`, `scroll`, `drag` with an inline `path`, and
+ * `expect`), never a `paste`, a `download`, an `await` (a peer that must
+ * wait for a result is the take's `await`), a guard, a `read`, a `caption`
+ * or `settle`, which all belong to the filmed page.
+ */
+
+/** One other person on the page: their own context, their own steps. */
+interface Peer {
+    /** How the peer is named in lines and in `meta.peers`: a short word. */
+    id: string;
+    /** The page the peer opens; absent, the take's own `url`. */
+    url?: string;
+    /** The peer's viewport in CSS px; absent, the take's. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * A Playwright storage state the peer's context is made from: the second
+     * person's own sign-in. The host resolves the name (the CLI: a path from
+     * the actions file's directory) and never sends the file anywhere.
+     * Absent, the peer is signed out.
+     */
+    storageState?: string;
+    steps: PeerStep[];
+}
+/** A peer's step: one of the take's gestures or checks, and when it starts. */
+type PeerStep = ActionStep & {
+    /**
+     * Start as the take's step with this id starts: the two run together.
+     * (`with`, never `at`: a `type` step's `at` is where its caret goes.)
+     */
+    with?: string;
+    /** Start as the take's step with this id ends. */
+    after?: string;
+};
+/** The verbs a peer takes: the gestures and the on-page check. */
+declare const PEER_VERBS: readonly ["wait", "move", "hover", "click", "type", "press", "scroll", "drag", "expect"];
+/** The most peers a take may have: each is a whole browser context. */
+declare const MAX_PEERS = 4;
+/** The most steps one peer may take. */
+declare const MAX_PEER_STEPS = 200;
+/**
+ * Structural validation of `peers`, given the take's own steps (a trigger
+ * names one of their ids). `validate` is the take's step validator, run on
+ * each peer's list so a peer step is checked in exactly the take's words.
+ */
+declare function validatePeers(value: unknown, takeSteps: unknown, validate: (steps: unknown[]) => string[]): string[];
+/** What a hosted recorder says of a script with peers, or null. */
+declare function peersHostedRefusal(peers: unknown): string | null;
+/**
+ * The take's step boundaries, as promises a peer step waits on. The take
+ * calls `begin` as the camera rolls, `start`/`end` around each step and
+ * `close` once its steps are over; a trigger still pending then resolves
+ * false and its step never runs.
+ */
+declare class StepSignals {
+    private readonly started;
+    private readonly ended;
+    private readonly began;
+    private closed;
+    constructor(ids: Iterable<string>);
+    begin(): void;
+    start(id: string | undefined): void;
+    end(id: string | undefined): void;
+    close(): void;
+    get isClosed(): boolean;
+    /** When a step with this trigger may start: true, or false for never. */
+    when(trigger: {
+        with?: string;
+        after?: string;
+    }): {
+        ready: Promise<boolean>;
+        already: boolean;
+    };
+}
+
+/** The most a peer step's kept value holds, in characters of JSON (as a take step's). */
+declare const PEER_VALUE_MAX = 2048;
+/**
+ * What a peer's check last answered, kept on its step the way the take's
+ * own steps keep theirs (`meta.steps[].value`): the value itself while its
+ * JSON fits, else that JSON cut short as a string; absent when the read
+ * answered nothing JSON can hold, or no value at all (a check that only
+ * holds or not).
+ */
+declare function peerValue(last: ConditionState): unknown;
+/** What a peer did: its steps as they ran, and the ones that never did. */
+interface PeerRun {
+    id: string;
+    steps: PeerStepSpan[];
+    /** Steps whose trigger never fired before the take's steps were over. */
+    notRun: number[];
+}
+/**
+ * Drive one peer's steps on its page, each when its trigger fires. Never
+ * throws for a page's reasons: a miss is a skip on the run.
+ */
+declare function runPeer(peer: Peer, rawPage: RecorderPage, signals: StepSignals, opts: {
+    clock: RecorderClock;
+    /** The take's footage clock, ms: what a span is placed by. */
+    footageMs: () => number;
+    log: (msg: string) => void;
+    /** A rehearsal: no travel, every pause cut short. */
+    dry?: boolean;
+}): Promise<PeerRun>;
+
 /**
  * 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
@@ -903,6 +1233,15 @@ interface ActionsFile {
      * or stored.
      */
     setup?: SetupStep[];
+    /**
+     * Run AFTER the take, off camera, with the same verbs as `setup`: what
+     * the take created in the product (an API key, a project, an invite)
+     * removed again. They run once the screencast has stopped, on the take's
+     * own page, after a rehearsal too, and when the take stops early or
+     * throws after its first step. A failing teardown never fails the take;
+     * it stops at the step that failed and is reported.
+     */
+    teardown?: 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;
@@ -917,6 +1256,15 @@ interface ActionsFile {
      */
     settle?: boolean;
     steps: ActionStep[];
+    /**
+     * Other people on the page, OFF CAMERA: each a browser context of its
+     * own (its own storage state, so its own user) on the same `url`, driven
+     * by its own steps, each started `with` a take step or `after` one (by
+     * id). Only the take's page is filmed, and only its own steps make the
+     * cursor track; a peer's work reaches the footage through the app's own
+     * sync. A hosted take refuses peers.
+     */
+    peers?: Peer[];
 }
 type ActionStep = ({
     do: 'wait';
@@ -1037,9 +1385,12 @@ type ActionStep = ({
 /**
  * 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.
+ * visible text containing `text`, `gone` no longer visible, or `js`, an
+ * expression evaluated in the page that holds when its value is truthy
+ * (with `equals`, when its value equals that one): the state a canvas
+ * app keeps in script, never in the DOM. Exactly one of the four. Waits
+ * up to `timeout` seconds (default 5); a condition that never holds is a
+ * skip with its reason, which names the value a `js` last answered.
  */
  | {
     do: 'expect';
@@ -1047,6 +1398,8 @@ type ActionStep = ({
     text?: string;
     gone?: string;
     enabled?: boolean;
+    js?: string;
+    equals?: unknown;
     timeout?: number;
 }
 /**
@@ -1099,6 +1452,15 @@ type ActionStep = ({
      * `vos actions script` leads the beat with it.
      */
     caption?: string;
+    /**
+     * The cut's camera on this step: `true` marks the step as its beat's
+     * payoff, the moment worth the zoom (`vos plan --zooms per-beat` keeps
+     * the proposal on it, and only it); `false` means never zoom here (the
+     * planner's proposal on it is rejected). The planner still decides the
+     * level and the focus; a mark never invents a zoom. On a gesture only
+     * (ZOOM_MARK_VERBS).
+     */
+    zoom?: boolean;
     /**
      * A selector whose words the recorder keeps once the step has settled
      * (`meta.steps[].text`: trimmed, whitespace collapsed, at most 2 KB), so
@@ -1116,15 +1478,19 @@ type ActionStep = ({
      */
     settle?: boolean;
 };
-/** What an `await` waits for: exactly one of the three. */
+/** What an `await` waits for: exactly one of the four (`equals` rides with `js`). */
 interface AwaitUntil {
     selector?: string;
     text?: string;
     gone?: string;
+    js?: string;
+    equals?: unknown;
 }
 /** The guards a step may carry: one today, a step that spends. */
 declare const STEP_GUARDS: readonly ["spend"];
 type StepGuard = (typeof STEP_GUARDS)[number];
+/** The verbs a `zoom` mark may sit on: the gestures a camera can be about. */
+declare const ZOOM_MARK_VERBS: readonly string[];
 /** How long an `expect` waits by default, in seconds. */
 declare const EXPECT_TIMEOUT_S = 5;
 /** An `await`'s defaults, in seconds. */
@@ -1168,10 +1534,11 @@ declare function guardVerdict(actions: Pick<ActionsFile, 'steps'>, confirm: read
 };
 /**
  * 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.
+ * guarded step has nobody to confirm it on a fleet, a download has no
+ * take directory to land in there, and a `js` check is code a stranger's
+ * script would run in the fleet's browser.
  */
-declare function hostedRefusals(actions: Pick<ActionsFile, 'steps'>): string[];
+declare function hostedRefusals(actions: Pick<ActionsFile, 'steps' | 'peers'>): 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.
@@ -1293,6 +1660,8 @@ interface SkippedStep {
     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 PEER's step (`peers[].id`): `step` is then an index into that peer's steps. */
+    peer?: string;
 }
 /** A click whose target was disabled when it was pressed: the press happened, and likely did nothing. */
 interface DisabledClick {
@@ -1378,6 +1747,13 @@ interface RecordResult {
     overruns: StepOverrun[];
     /** The actions as recorded, `url` resolved: what a take directory writes back. */
     actions: ActionsFile;
+    /** What each peer did, off camera (also `meta.peers`); [] with none. */
+    peers: PeerRun[];
+    /**
+     * What the script's `teardown` did after the take, off camera; null when
+     * it has none. A failure here is reported and never fails the take.
+     */
+    teardown: TeardownReport | null;
 }
 interface RecordOpts {
     /** Stop the capture at this many seconds (the hosted cap). */
@@ -1416,9 +1792,10 @@ interface RecordOpts {
      */
     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.
+     * The environment a setup's and a teardown'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, and a
+     * teardown that reads one refuses the take before it begins.
      */
     env?: Record<string, string | undefined>;
     /** The platform the take is recorded on, for `meta.platform`. */
@@ -1462,6 +1839,14 @@ interface RecordOpts {
     stopOnHang?: boolean;
     /** How often a long `await` reports it is still waiting (default 30 s). */
     awaitHeartbeatMs?: number;
+    /**
+     * Where a peer's `storageState` is read from: the CLI resolves the name
+     * from the actions file's directory to a path the browser opens, and
+     * throws in words when there is none. A host that hands in none cannot
+     * sign a peer in, and such a script is refused before anything is
+     * captured.
+     */
+    peerStorageState?: (name: string) => Promise<string> | string;
 }
 /**
  * The expression a scroll tick evaluates: move the first scrollable
@@ -1567,97 +1952,6 @@ declare function splitSegmentsAtSkips(segments: ProjectDoc['segments'], skips: r
     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;
 /**
@@ -2045,4 +2339,4 @@ declare function inlinePoints(path: {
  */
 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 };
+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, JS_SAID_MAX, JS_VALUE_MAX, KEY_ROUNDTRIP_MS, KEY_SEQUENCE_GAP_MS, type LoadedFiles, MAX_KEYS, MAX_PATH_POINTS, MAX_PEERS, MAX_PEER_STEPS, 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, PEER_VALUE_MAX, PEER_VERBS, 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 Peer, type PeerRun, type PeerStep, 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 StepPhase, StepSignals, type StoppedTake, type SurfaceFit, type SurfaceSize, TEARDOWN_BOUND_MS, TRAILING_HOLD_MS, TakeClock, type TeardownReport, WAIT_MARGIN_MS, WALL_PROBE, type WaitCondition, WallError, type WallKind, type WallVerdict, ZOOM_MARK_VERBS, 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, jsConditionScript, keptValue, keySequencePlanMs, loadScriptFiles, maskInitScript, modifierBits, nameFromUrl, noticeAdvice, noticeLine, outputName, overrunLine, overrunOf, paceLine, paceReport, pageErrorLine, parseHeaders, pasteTypeOf, pathDurationMs, peerValue, peersHostedRefusal, plainName, planFreshTake, pointerTravelMs, pollCondition, pressSequence, publicUrl, readAllBytes, readCondition, readMediaSource, readPath, readyLine, readyProblem, realSleep, recordTake, redirectedAway, reloadUntilReady, resolveChord, resolveModifier, resolveSetupText, runPeer, runSetup, sameJson, sayCondition, sayDuration, sayJs, sayValue, schedulePath, scriptEnvNames, scriptFiles, scrollByScript, scrollTravelMs, settleMs, settleOn, settleVerdict, setupEnvNames, soundSrcForMeta, splitChord, splitSegmentsAtSkips, stageClipboardScript, stepBoundMs, syntheticPasteScript, teardownEnvProblem, teardownLine, typeOfName, untilReady, urlSchemeProblem, validateActions, validatePeers, validateSetup, visibleTextScript, wallVerdict, withFittingExport, withPageSound };