@vosjs/render-core 0.10.0 → 0.12.0

package/dist/record/index.d.ts

@@ -438,6 +438,15 @@ declare function deadLine(r: DeadReport): string;
  * 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 | {
@@ -462,9 +471,15 @@ type SetupStep = ({
 } | {
     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';
 /**
@@ -515,6 +530,15 @@ interface SetupResult {
         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;
@@ -531,6 +555,12 @@ interface TeardownReport {
         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;
@@ -1847,6 +1877,16 @@ interface RecordOpts {
      * captured.
      */
     peerStorageState?: (name: string) => Promise<string> | string;
+    /**
+     * In a rehearsal only: stop after the step with this `id` and hand the
+     * page, as that step left it, to `at` (`vos look --until`). The steps
+     * after it never run; the teardown still does, since the walk clicked
+     * for real. Ignored by a take.
+     */
+    until?: {
+        id: string;
+        at: (page: RecorderPage) => Promise<void>;
+    };
 }
 /**
  * The expression a scroll tick evaluates: move the first scrollable
@@ -2339,4 +2379,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, 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 };
+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 };

package/dist/record/index.js

@@ -689,7 +689,8 @@ function noticeAdvice(notices) {
 }
 
 // src/record/setup.ts
-var VERBS = /* @__PURE__ */ new Set(["wait", "click", "type", "press", "goto"]);
+var VERBS = /* @__PURE__ */ new Set(["wait", "click", "type", "press", "goto", "if"]);
+var IF_LOOK_MS = 3e3;
 function urlSchemeProblem(url) {
   let u;
   try {
@@ -715,7 +716,7 @@ function validateSetup(value, phase = "setup") {
       errors.push(`${at}: "do" must be one of ${[...VERBS].join(", ")}`);
       return;
     }
-    if ((s.do === "click" || s.do === "type") && typeof s.selector !== "string")
+    if ((s.do === "click" || s.do === "type" || s.do === "if") && typeof s.selector !== "string")
       errors.push(`${at}: ${s.do} needs a selector`);
     if (s.do === "wait" && typeof s.ms !== "number")
       errors.push(`${at}: wait needs ms`);
@@ -779,6 +780,9 @@ function teardownEnvProblem(steps, env) {
 var TEARDOWN_BOUND_MS = 6e4;
 function teardownLine(report) {
   const f = report.failed;
+  const k = report.skipped;
+  if (!f && k)
+    return `teardown: nothing to undo, ${k.selector} is not on the page (teardown[${k.step}] if); ${report.ran} step(s) ran, ${k.rest} skipped`;
   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.`;
@@ -790,6 +794,7 @@ async function runSetup(page, steps, opts) {
   const deadline = opts.boundMs === void 0 ? void 0 : now() + opts.boundMs;
   const lines = [];
   let typed = "";
+  let gone = null;
   const runStep = async (step, i) => {
     const settle = "ms" in step && typeof step.ms === "number" ? step.ms : 150;
     switch (step.do) {
@@ -806,6 +811,12 @@ async function runSetup(page, steps, opts) {
         await page.keyboard.press(step.key);
         await opts.sleep(settle);
         return `${phase} #${i} press ${step.key}`;
+      case "if": {
+        const present = await page.locator(step.selector).first().waitFor({ state: "visible", timeout: step.ms ?? IF_LOOK_MS }).then(() => true).catch(() => false);
+        if (present) return `${phase} #${i} if ${step.selector}: on the page`;
+        gone = { step: i, selector: step.selector };
+        return `${phase} #${i} if ${step.selector}: not on the page, the ${steps.length - i - 1} step(s) after it skipped`;
+      }
       case "click": {
         const loc = page.locator(step.selector).first();
         await loc.waitFor({ state: "visible", timeout: 8e3 });
@@ -848,6 +859,13 @@ async function runSetup(page, steps, opts) {
         }
       };
     }
+    const ended = gone;
+    if (ended)
+      return {
+        ran: i + 1,
+        lines,
+        skipped: { ...ended, rest: steps.length - i - 1 }
+      };
   }
   return { ran: steps.length, lines };
 }
@@ -3270,7 +3288,8 @@ async function recordTakeSteps(browser, url, actions, sink, log, opts, late) {
             ...result.failed.selector !== void 0 ? { selector: result.failed.selector } : {},
             error: result.failed.error ?? "the step failed"
           }
-        } : {}
+        } : {},
+        ...result.skipped ? { skipped: result.skipped } : {}
       };
     } catch (e) {
       teardown = {
@@ -3577,6 +3596,7 @@ async function recordTakeSteps(browser, url, actions, sink, log, opts, late) {
   const outputNames = /* @__PURE__ */ new Set();
   const overruns = [];
   let stopped = null;
+  let untilReached = false;
   let unpressedGuard = null;
   let capped = false;
   const signals = new StepSignals(
@@ -4278,6 +4298,11 @@ async function recordTakeSteps(browser, url, actions, sink, log, opts, late) {
       ...hang.hung ? { hung: true } : {}
     });
     if (stopped) break;
+    if (dry && opts.until && step.id === opts.until.id) {
+      await opts.until.at(rawPage);
+      untilReached = true;
+      break;
+    }
   }
   signals.close();
   const peerRuns = await Promise.all(lanes);
@@ -4292,7 +4317,7 @@ async function recordTakeSteps(browser, url, actions, sink, log, opts, late) {
           ...ps.reason ? { reason: ps.reason } : {},
           peer: pr.id
         });
-  if (!capped && !stopped) await sleep(TRAILING_HOLD_MS);
+  if (!capped && !stopped && !untilReached) await sleep(TRAILING_HOLD_MS);
   if (capped || capReached(now(), maxSeconds)) {
     capped = true;
     log(`   ${cappedLine(maxSeconds)}`);
@@ -4673,6 +4698,7 @@ export {
   EXPOSURE_PROBE,
   ExposureLog,
   IDLE_CALL_MS,
+  IF_LOOK_MS,
   JS_SAID_MAX,
   JS_VALUE_MAX,
   KEY_ROUNDTRIP_MS,