@vosjs/render-core 0.9.0 → 0.11.0

package/dist/record/index.d.ts

@@ -416,6 +416,186 @@ 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.
+ *
+ * `if`: a guard, `{ "do": "if", "selector": "…" }`. When its selector is on
+ * the page the steps after it run as usual; when it is not, they are skipped
+ * and the list ends there, which is not a failure. A teardown that undoes
+ * what the take may already have removed on camera starts its undoing with
+ * one (`if` the new key's row is still listed), so a good take reports
+ * nothing to undo instead of a failure; a setup that signs in guards its
+ * sign-in the same way (`if` the email field shows), so a session that is
+ * already signed in passes. A failure AFTER a guard is still a failure.
+ */
+
+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;
+} | {
+    do: 'if';
+    selector: string;
+    ms?: number;
+}) & {
+    id?: string;
+};
+/** How long an `if` looks for its selector, when it names no `ms`. */
+declare const IF_LOOK_MS = 3000;
+/** 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;
+    };
+    /**
+     * An `if` whose selector was not on the page: the list ended there, and
+     * `rest` steps after it were skipped. Not a failure.
+     */
+    skipped?: {
+        step: number;
+        selector: string;
+        rest: number;
+    };
+}
+/** 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;
+    };
+    /** An `if` whose selector was gone: nothing left to undo, never a failure. */
+    skipped?: {
+        step: number;
+        selector: string;
+        rest: number;
+    };
+}
+/** 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
@@ -564,99 +744,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
@@ -1176,6 +1263,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;
@@ -1683,6 +1779,11 @@ interface RecordResult {
     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). */
@@ -1721,9 +1822,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`. */
@@ -2267,4 +2369,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, 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, StepSignals, type StoppedTake, type SurfaceFit, type SurfaceSize, TRAILING_HOLD_MS, TakeClock, 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, scriptFiles, scrollByScript, scrollTravelMs, settleMs, settleOn, settleVerdict, setupEnvNames, soundSrcForMeta, splitChord, splitSegmentsAtSkips, stageClipboardScript, stepBoundMs, syntheticPasteScript, typeOfName, untilReady, urlSchemeProblem, validateActions, validatePeers, 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, IF_LOOK_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 };