@vosjs/render-core 0.9.0 → 0.10.0

package/dist/record/index.d.ts

@@ -416,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
@@ -564,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
@@ -1176,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;
@@ -1683,6 +1749,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 +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`. */
@@ -2267,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, 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, 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 };

package/dist/record/index.js

@@ -701,11 +701,11 @@ function urlSchemeProblem(url) {
     return `${url} is not an http(s) address, and the recorder opens only http and https pages`;
   return null;
 }
-function validateSetup(value) {
+function validateSetup(value, phase = "setup") {
   const errors = [];
-  if (!Array.isArray(value)) return ["setup must be an array of steps"];
+  if (!Array.isArray(value)) return [`${phase} must be an array of steps`];
   value.forEach((raw, i) => {
-    const at = `setup[${i}]`;
+    const at = `${phase}[${i}]`;
     if (typeof raw !== "object" || raw === null) {
       errors.push(`${at}: must be an object`);
       return;
@@ -750,73 +750,141 @@ function setupEnvNames(steps) {
   }
   return [...out];
 }
-function resolveSetupText(t, env) {
+function scriptEnvNames(script) {
+  return [
+    .../* @__PURE__ */ new Set([
+      ...setupEnvNames(script.setup),
+      ...setupEnvNames(script.teardown)
+    ])
+  ];
+}
+function resolveSetupText(t, env, phase = "setup") {
   if (typeof t === "string") return { value: t, secret: false };
   const v = env[t.env];
   if (v === void 0 || v === "")
     throw new SetupEnvError(
-      `setup: the environment variable ${t.env} is not set, and a type step reads it. Export it in the shell that runs vos record; it is never written to a file`
+      `${phase}: the environment variable ${t.env} is not set, and a type step reads it. Export it in the shell that runs vos record; it is never written to a file`
     );
   return { value: v, secret: true };
 }
+function teardownEnvProblem(steps, env) {
+  for (const [i, s] of (steps ?? []).entries()) {
+    if (s.do !== "type" || typeof s.text !== "object") continue;
+    const v = env[s.text.env];
+    if (v === void 0 || v === "")
+      return `teardown[${i}] reads the environment variable ${s.text.env}, which is not set, so the take could leave behind what its teardown removes. Export it in the shell that runs vos record; it is never written to a file. Nothing was recorded.`;
+  }
+  return null;
+}
+var TEARDOWN_BOUND_MS = 6e4;
+function teardownLine(report) {
+  const f = report.failed;
+  if (!f) return `teardown: ${report.ran} step(s) ran`;
+  const reason = f.error.replace(/[.\s]+$/, "");
+  return `TEARDOWN FAILED at teardown[${f.step}] (${f.do}${f.selector ? ` ${f.selector}` : ""}): ${reason}. What the take created may still be in the product; remove it by hand.`;
+}
 async function runSetup(page, steps, opts) {
   const env = opts.env ?? {};
+  const phase = opts.phase ?? "setup";
+  const now = opts.now ?? Date.now;
+  const deadline = opts.boundMs === void 0 ? void 0 : now() + opts.boundMs;
   const lines = [];
-  for (const [i, step] of steps.entries()) {
+  let typed = "";
+  const runStep = async (step, i) => {
     const settle = "ms" in step && typeof step.ms === "number" ? step.ms : 150;
-    try {
-      switch (step.do) {
-        case "wait":
-          await opts.sleep(step.ms);
-          lines.push(`setup #${i} wait ${step.ms}ms`);
-          break;
-        case "goto":
-          await (opts.goto ? opts.goto(step.url) : page.goto(step.url, {
-            waitUntil: "networkidle",
-            timeout: 45e3
-          })).catch(() => null);
-          lines.push(`setup #${i} goto ${step.url}`);
-          break;
-        case "press":
-          await page.keyboard.press(step.key);
-          await opts.sleep(settle);
-          lines.push(`setup #${i} press ${step.key}`);
-          break;
-        case "click": {
-          const loc = page.locator(step.selector).first();
-          await loc.waitFor({ state: "visible", timeout: 8e3 });
-          await loc.click();
-          await opts.sleep(settle);
-          lines.push(`setup #${i} click ${step.selector}`);
-          break;
-        }
-        case "type": {
-          const loc = page.locator(step.selector).first();
-          await loc.waitFor({ state: "visible", timeout: 8e3 });
-          const { value, secret } = resolveSetupText(step.text, env);
-          await loc.fill(value);
-          await opts.sleep(settle);
-          lines.push(
-            `setup #${i} type ${secret ? `\${${step.text.env}}` : `${value.length} chars`} into ${step.selector}`
-          );
-          break;
-        }
+    switch (step.do) {
+      case "wait":
+        await opts.sleep(step.ms);
+        return `${phase} #${i} wait ${step.ms}ms`;
+      case "goto":
+        await (opts.goto ? opts.goto(step.url) : page.goto(step.url, {
+          waitUntil: "networkidle",
+          timeout: 45e3
+        })).catch(() => null);
+        return `${phase} #${i} goto ${step.url}`;
+      case "press":
+        await page.keyboard.press(step.key);
+        await opts.sleep(settle);
+        return `${phase} #${i} press ${step.key}`;
+      case "click": {
+        const loc = page.locator(step.selector).first();
+        await loc.waitFor({ state: "visible", timeout: 8e3 });
+        await loc.click();
+        await opts.sleep(settle);
+        return `${phase} #${i} click ${step.selector}`;
       }
+      case "type": {
+        const loc = page.locator(step.selector).first();
+        await loc.waitFor({ state: "visible", timeout: 8e3 });
+        const { value, secret } = resolveSetupText(step.text, env, phase);
+        typed = value;
+        await loc.fill(value);
+        await opts.sleep(settle);
+        return `${phase} #${i} type ${secret ? `\${${step.text.env}}` : `${value.length} chars`} into ${step.selector}`;
+      }
+    }
+  };
+  for (const [i, step] of steps.entries()) {
+    typed = "";
+    try {
+      lines.push(
+        await withinDeadline(
+          runStep(step, i),
+          deadline,
+          now,
+          `the ${phase} ran past its ${sayBound(opts.boundMs ?? 0)} bound`
+        )
+      );
     } catch (e) {
-      if (e instanceof SetupEnvError) throw e;
+      if (e instanceof SetupEnvError && phase === "setup") throw e;
       return {
         ran: i,
         lines,
         failed: {
           step: i,
           do: step.do,
-          ..."selector" in step ? { selector: step.selector } : {}
+          ..."selector" in step ? { selector: step.selector } : {},
+          error: reasonWords(e, typed)
         }
       };
     }
   }
   return { ran: steps.length, lines };
 }
+function sayBound(ms) {
+  return ms >= 1e3 ? `${Math.round(ms / 1e3)} s` : `${ms} ms`;
+}
+function withinDeadline(p, deadline, now, message) {
+  if (deadline === void 0) return p;
+  const left = deadline - now();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => {
+        p.catch(() => {
+        });
+        reject(new Error(message));
+      },
+      Math.max(0, left)
+    );
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+var ANSI_COLOUR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+function reasonWords(e, typed) {
+  const raw = e instanceof Error ? e.message : String(e);
+  const line = (raw.replace(ANSI_COLOUR, "").split("\n")[0] ?? "").trim();
+  if (typed && line.includes(typed)) return "the field could not be filled";
+  return line || "the step failed";
+}
 var SetupEnvError = class extends Error {
   constructor(message) {
     super(message);
@@ -2405,6 +2473,8 @@ function validateActions(value) {
     }
   }
   if (obj.setup !== void 0) errors.push(...validateSetup(obj.setup));
+  if (obj.teardown !== void 0)
+    errors.push(...validateSetup(obj.teardown, "teardown"));
   const ready = readyProblem(obj.ready);
   if (ready) errors.push(ready);
   if (obj.settle !== void 0 && typeof obj.settle !== "boolean")
@@ -3071,6 +3141,18 @@ function base64Bytes(data) {
   return out;
 }
 async function recordTake(browser, url, actions, sink, log, opts = {}) {
+  const late = {};
+  try {
+    return await recordTakeSteps(browser, url, actions, sink, log, opts, late);
+  } catch (e) {
+    const teardown = late.teardown;
+    late.teardown = void 0;
+    if (teardown) await teardown().catch(() => {
+    });
+    throw e;
+  }
+}
+async function recordTakeSteps(browser, url, actions, sink, log, opts, late) {
   const dry = opts.dryRun === true;
   const sleep = dry ? (ms) => realSleep(Math.min(ms, DRY_PAUSE_MS)) : realSleep;
   const maxSeconds = dry ? Infinity : opts.maxDurationSeconds ?? Infinity;
@@ -3083,6 +3165,8 @@ async function recordTake(browser, url, actions, sink, log, opts = {}) {
         `steps[${download}] is a download, and this recorder has nowhere to keep a file. Nothing was recorded.`
       );
   }
+  const teardownEnv = teardownEnvProblem(actions.teardown, opts.env ?? {});
+  if (teardownEnv) throw new SetupEnvError(teardownEnv);
   const read = await loadScriptFiles(actions, opts.files);
   if ("problem" in read) throw new RecordRefusedError(read.problem);
   const files = read;
@@ -3126,8 +3210,9 @@ async function recordTake(browser, url, actions, sink, log, opts = {}) {
     noticeLog.add(step, scan?.notices);
   };
   const pageErrors = new PageErrorLog(opts.verbose === true);
+  let tearingDown = false;
   page.on("console", (m) => {
-    if (m.type() !== "error") return;
+    if (m.type() !== "error" || tearingDown) return;
     const line = pageErrors.add(m.text());
     if (line) log(line);
   });
@@ -3158,6 +3243,49 @@ async function recordTake(browser, url, actions, sink, log, opts = {}) {
     log(`goto ${url} (after setup)`);
     response = (await open(url)).response;
   }
+  const teardownSteps = actions.teardown ?? [];
+  let teardown = null;
+  let teardownRan = false;
+  const runTeardown = async () => {
+    if (!teardownSteps.length || teardownRan) return teardown;
+    teardownRan = true;
+    tearingDown = true;
+    log(`teardown: ${teardownSteps.length} step(s), off camera`);
+    try {
+      const result = await runSetup(page, teardownSteps, {
+        phase: "teardown",
+        sleep: realSleep,
+        env: opts.env ?? {},
+        goto: (target) => open(target),
+        boundMs: TEARDOWN_BOUND_MS
+      });
+      for (const line of result.lines) log(`   ${line}`);
+      teardown = {
+        ran: result.ran,
+        of: teardownSteps.length,
+        ...result.failed ? {
+          failed: {
+            step: result.failed.step,
+            do: result.failed.do,
+            ...result.failed.selector !== void 0 ? { selector: result.failed.selector } : {},
+            error: result.failed.error ?? "the step failed"
+          }
+        } : {}
+      };
+    } catch (e) {
+      teardown = {
+        ran: 0,
+        of: teardownSteps.length,
+        failed: {
+          step: 0,
+          do: teardownSteps[0].do,
+          error: e instanceof Error ? e.message : String(e)
+        }
+      };
+    }
+    if (teardown.failed) log(`   ${teardownLine(teardown)}`);
+    return teardown;
+  };
   let wall = null;
   if (opts.onArrival) {
     const seen = await page.evaluate(WALL_PROBE).catch(() => null);
@@ -3468,6 +3596,13 @@ async function recordTake(browser, url, actions, sink, log, opts = {}) {
     })
   );
   signals.begin();
+  late.teardown = async () => {
+    if (!dry) await cdp.send("Page.stopScreencast").catch(() => {
+    });
+    pageBound.end();
+    const report = await runTeardown();
+    if (report && !report.failed) log(`   ${teardownLine(report)}`);
+  };
   for (const [stepIdx, step] of actions.steps.entries()) {
     if (capReached(now(), maxSeconds)) {
       capped = true;
@@ -4179,6 +4314,8 @@ async function recordTake(browser, url, actions, sink, log, opts = {}) {
   const pageTitle = await page.title().catch(() => "") ?? "";
   for (const line of pageErrors.repeats()) log(line);
   pageBound.end();
+  late.teardown = void 0;
+  await runTeardown();
   pageBound.start(CLOSE_BOUND_MS);
   await pageBound.race(context.close().catch(() => {
   }));
@@ -4265,7 +4402,8 @@ async function recordTake(browser, url, actions, sink, log, opts = {}) {
     // Self-contained: a path a file held is inline, so the take re-records
     // from its own script with the file gone.
     actions: { ...inlineScript(actions, files), url },
-    peers: peerRuns
+    peers: peerRuns,
+    teardown
   };
 }
 async function keepPageSound(heard, sink, fetchSource, log) {
@@ -4592,6 +4730,7 @@ export {
   SetupError,
   StepBound,
   StepSignals,
+  TEARDOWN_BOUND_MS,
   TRAILING_HOLD_MS,
   TakeClock,
   WAIT_MARGIN_MS,
@@ -4681,6 +4820,7 @@ export {
   sayJs,
   sayValue,
   schedulePath,
+  scriptEnvNames,
   scriptFiles,
   scrollByScript,
   scrollTravelMs,
@@ -4694,6 +4834,8 @@ export {
   stageClipboardScript,
   stepBoundMs,
   syntheticPasteScript,
+  teardownEnvProblem,
+  teardownLine,
   typeOfName,
   untilReady,
   urlSchemeProblem,