@swmansion/argent 0.22.2-next.0 → 0.22.2-next.1

package/dist/tool-server.cjs

@@ -93869,7 +93869,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.22.2-next.0";
+    return "0.22.2-next.1";
   }
   return "0.0.0";
 }
@@ -119417,18 +119417,39 @@ Before tapping, determine the correct coordinates by using discovery tools \u201
 // ../tool-server/src/tools/gesture-swipe/index.ts
 init_zod();
 var sleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
-var SETTLE_EASE_EXPONENT = 3;
+var MOMENTUM_FREE_EASE_EXPONENT = 3;
+var DEFAULT_DURATION_MS = 300;
+var MOMENTUM_FREE_MIN_DURATION_MS = 150;
+var MAX_DURATION_MS = 1e4;
 var zodSchema17 = external_exports.object({
   udid: external_exports.string().describe("Target device id from `list-devices` (iOS UDID or Android serial)."),
   fromX: external_exports.number().describe("Start x: normalized 0.0\u20131.0 (not pixels; same as tap)"),
   fromY: external_exports.number().describe("Start y: normalized 0.0\u20131.0 (not pixels; same as tap)"),
   toX: external_exports.number().describe("End x: normalized 0.0\u20131.0 (not pixels; same as tap)"),
   toY: external_exports.number().describe("End y: normalized 0.0\u20131.0 (not pixels; same as tap)"),
-  durationMs: external_exports.number().optional().describe("Total gesture duration in milliseconds (default 300)"),
-  settle: external_exports.boolean().optional().describe(
-    "Momentum-free swipe: decelerate into the end point (ease-out) so the OS reads ~0 release velocity and applies little to no fling. Use for scroll-to-element loops; default false (a natural flinging swipe)."
+  durationMs: external_exports.number().max(MAX_DURATION_MS, {
+    message: `durationMs must be at most ${MAX_DURATION_MS} (10s): every frame is a real 16ms sleep with the finger held down, so a larger value is that many milliseconds of wall clock spent holding a touch the device cannot shake off.`
+  }).optional().describe(
+    `Total gesture duration in milliseconds (default 300, at most ${MAX_DURATION_MS} - the gesture holds a finger down for exactly this long)`
+  ),
+  momentum: external_exports.boolean().optional().describe(
+    `Whether the swipe releases with momentum; default true (a natural flinging swipe). Pass false for a momentum-free swipe at the default durationMs: the finger decelerates into the end point (ease-out) so the OS reads ~0 release velocity and applies little to no fling. Use false for scroll-to-element loops. momentum: false needs durationMs >= ${MOMENTUM_FREE_MIN_DURATION_MS} and is rejected below it: a shorter ease-out gives the OS velocity fit too little wall clock to read the deceleration as a stop, and it flings harder than a plain swipe instead (on Android, backwards). At ${MOMENTUM_FREE_MIN_DURATION_MS} itself the swipe lands short of where the finger stopped, and 2 of 47 runs still flung backwards.`
+  ),
+  // `momentum`'s shipped spelling, with the opposite polarity. Declared so this
+  // non-strict object refuses it instead of stripping it and flinging - the exact
+  // inverse of the gesture the caller asked for.
+  settle: external_exports.never({
+    error: "gesture-swipe's `settle` was renamed to `momentum`, with the opposite sense \u2014 write `momentum: false` for the momentum-free swipe that `settle: true` used to mean (plain `settle: false` was the default, so just drop it)"
+  }).optional().describe(
+    "Retired: renamed to `momentum` with the opposite sense. Pass `momentum: false` for what `settle: true` meant; `settle: false` was the default, so drop the key."
   )
-});
+}).refine(
+  (p) => p.momentum !== false || (p.durationMs ?? DEFAULT_DURATION_MS) >= MOMENTUM_FREE_MIN_DURATION_MS,
+  {
+    message: `momentum: false needs durationMs of at least ${MOMENTUM_FREE_MIN_DURATION_MS}: below that the ease-out has too little wall clock for the OS velocity fit to read it as a stop rather than a flick, so it flings harder than a plain swipe and, on Android, backwards. Raise durationMs, or drop momentum: false for a plain flinging swipe at the duration you asked for.`,
+    path: ["durationMs"]
+  }
+);
 var capability9 = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
@@ -119441,11 +119462,13 @@ var gestureSwipeTool = {
     completedMsg: ({ params }) => `Swiped from (${Math.round(params.fromX * 100)}%, ${Math.round(params.fromY * 100)}%) to (${Math.round(params.toX * 100)}%, ${Math.round(params.toY * 100)}%)`,
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to swipe: ${failureSignal2.error_code}`
   },
+  // The bounds are spelled out rather than interpolated: extract-tools scans this
+  // description statically, so a `${}` in it drops the tool out of the scan.
   description: `Execute a smooth swipe / drag touch gesture between two points on the device (iOS simulator or Android emulator). All from/to positions are normalized 0.0\u20131.0 (fractions of screen width/height, not pixels), same as gesture-tap.
 Generates interpolated Move events for a natural feel (~60fps).
 Swipe up (fromY > toY) to scroll content down.
 Use when you need to scroll a list, dismiss a modal, drag an element, or navigate between pages. Not supported on Chromium \u2014 use gesture-scroll there instead.
-Pass settle:true for a momentum-free swipe that lands exactly where the finger lifts (no fling), when you need a deterministic scroll distance. Returns { swiped: true, timestampMs }. Fails if the simulator-server / emulator backend is not reachable for the given device.`,
+Pass momentum:false for a momentum-free swipe that lands where the finger lifts (little to no fling at the 300 default), when you need a deterministic scroll distance; it needs durationMs >= 150 and is rejected below that, a shorter ease-out leaving the OS too little wall clock to read the deceleration as a stop. At 150 it lands short of the lift point instead, and 2 of 47 runs still flung backwards. A plain swipe takes any duration up to 10000ms and is delivered as close to the speed it was authored as a 16ms frame allows: below ~32ms the whole travel lands in one or two frames, which the OS flings as hard as it flings anything. Returns { swiped: true, timestampMs }. Fails if the simulator-server / emulator backend is not reachable for the given device.`,
   alwaysLoad: true,
   searchHint: "swipe scroll drag pan gesture device simulator emulator touch move",
   zodSchema: zodSchema17,
@@ -119453,18 +119476,47 @@ Pass settle:true for a momentum-free swipe that lands exactly where the finger l
   services: (params) => ({
     simulatorServer: simulatorServerRef(resolveDevice(params.udid))
   }),
-  async execute(services, params) {
-    const duration3 = params.durationMs ?? 300;
-    const settle = params.settle ?? false;
+  async execute(services, params, ctx) {
+    const duration3 = params.durationMs ?? DEFAULT_DURATION_MS;
+    const momentumFree = params.momentum === false;
     const timestampMs = Date.now();
     const api = services.simulatorServer;
     const steps = Math.max(1, Math.round(duration3 / 16));
+    let lastX = 0;
+    let lastY = 0;
     for (let i = 0; i <= steps; i++) {
+      if (ctx?.signal?.aborted) {
+        if (i > 0) {
+          sendCommand(api, {
+            cmd: "touch",
+            type: "Up",
+            x: lastX,
+            y: lastY,
+            second_x: null,
+            second_y: null
+          });
+        }
+        const err = new Error(
+          `gesture-swipe aborted - cancelled mid-gesture after ${i} of ${steps + 1} frames`
+        );
+        err.name = "AbortError";
+        throw err;
+      }
       const t = i / steps;
-      const progress = settle ? 1 - Math.pow(1 - t, SETTLE_EASE_EXPONENT) : t;
+      const progress = momentumFree ? 1 - Math.pow(1 - t, MOMENTUM_FREE_EASE_EXPONENT) : t;
       const x = params.fromX + (params.toX - params.fromX) * progress;
       const y = params.fromY + (params.toY - params.fromY) * progress;
       const type = i === 0 ? "Down" : i === steps ? "Up" : "Move";
+      if (type === "Up") {
+        sendCommand(api, {
+          cmd: "touch",
+          type: "Move",
+          x,
+          y,
+          second_x: null,
+          second_y: null
+        });
+      }
       sendCommand(api, {
         cmd: "touch",
         type,
@@ -119473,6 +119525,8 @@ Pass settle:true for a momentum-free swipe that lands exactly where the finger l
         second_x: null,
         second_y: null
       });
+      lastX = x;
+      lastY = y;
       if (i < steps) await sleep3(16);
     }
     return { swiped: true, timestampMs };
@@ -119548,13 +119602,30 @@ Returns { scrolled: true, timestampMs }. Fails if the Chromium CDP session is no
 // ../tool-server/src/tools/gesture-drag/index.ts
 init_zod();
 var sleep5 = (ms) => new Promise((r) => setTimeout(r, ms));
+var MOMENTUM_FREE_EASE_EXPONENT2 = 3;
+var MOMENTUM_FREE_MIN_STEPS = 8;
+var MAX_DURATION_MS2 = 1e4;
 var zodSchema19 = external_exports.object({
   udid: external_exports.string().describe("Target Chromium device id from `list-devices` (chromium-cdp-<port>)."),
   fromX: external_exports.number().describe("Press x: normalized 0.0\u20131.0 (fraction of window width, not pixels)."),
   fromY: external_exports.number().describe("Press y: normalized 0.0\u20131.0 (fraction of window height, not pixels)."),
   toX: external_exports.number().describe("Release x: normalized 0.0\u20131.0 (not pixels; same space as tap)."),
   toY: external_exports.number().describe("Release y: normalized 0.0\u20131.0 (not pixels; same space as tap)."),
-  durationMs: external_exports.number().optional().describe("Total drag duration in milliseconds (default 300), interpolated at ~60fps.")
+  durationMs: external_exports.number().max(MAX_DURATION_MS2, {
+    message: `durationMs must be at most ${MAX_DURATION_MS2} (10s): the drag holds the left button down for exactly this long, one frame per ~16ms, so a larger value is that much wall clock spent mid-press.`
+  }).optional().describe(
+    `Total drag duration in milliseconds (default 300, at most ${MAX_DURATION_MS2} - the button stays down for exactly this long), interpolated at ~60fps.`
+  ),
+  momentum: external_exports.boolean().optional().describe(
+    "Whether the drag releases with momentum; default true (a constant-speed drag). Pass false to decelerate into the release point (ease-out) so an app deriving fling from pointer release velocity (carousels, drag libraries) reads ~0 and applies little to no momentum \u2014 use it when the drag must stop where it was aimed rather than fling past. Deceleration needs wall clock: under ~100ms the whole drag fits inside the velocity window a page averages over (tens of ms), so some fling survives, and under ~70ms its extra frames cannot dispatch fast enough to fit durationMs. Keep durationMs at its default when the fling must be fully suppressed."
+  ),
+  // `momentum`'s earlier spelling, with the opposite polarity. Declared so this
+  // non-strict object refuses it instead of stripping it and running the default.
+  settle: external_exports.never({
+    error: "gesture-drag's `settle` was renamed to `momentum`, with the opposite sense - write `momentum: false` for the momentum-free drag that `settle: true` used to mean (plain `settle: false` was the default, so just drop it)"
+  }).optional().describe(
+    "Retired: renamed to `momentum` with the opposite sense. Pass `momentum: false` for what `settle: true` meant; `settle: false` was the default, so drop the key."
+  )
 });
 var capability11 = {
   chromium: { app: true }
@@ -119566,9 +119637,9 @@ var gestureDragTool = {
     completedMsg: ({ params }) => `Dragged from (${Math.round(params.fromX * 100)}%, ${Math.round(params.fromY * 100)}%) to (${Math.round(params.toX * 100)}%, ${Math.round(params.toY * 100)}%)`,
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to drag: ${failureSignal2.error_code}`
   },
-  description: `Press the left mouse button at a start point, move to an end point, and release \u2014 a desktop mouse drag in a Chromium app. All positions are normalized 0.0\u20131.0 (fractions of the window, not pixels), same coordinate space as gesture-tap and describe. Interpolates mouse-move events at ~60fps over durationMs for a natural drag.
+  description: `Press the left mouse button at a start point, move to an end point, and release \u2014 a desktop mouse drag in a Chromium app. All positions are normalized 0.0\u20131.0 (fractions of the window, not pixels), same coordinate space as gesture-tap and describe, except that a coordinate of exactly 1.0 lands one pixel inside the window edge (gesture-tap maps it to the edge itself). Interpolates mouse-move events at ~60fps over durationMs for a natural drag (a momentum-free drag samples more finely when durationMs is short, so its ease-out has a curve).
 Use for slider thumbs, drag-and-drop, text selection, or draggable UI elements. Dragging never scrolls content on desktop \u2014 use gesture-scroll for lists/pages. Chromium only \u2014 on iOS/Android use gesture-swipe.
-Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not reachable for the given device.`,
+Pass momentum:false for a momentum-free drag that decelerates into the release, so apps that compute a fling from the pointer stream read ~0 velocity and the drag ends where it was aimed instead of flinging past it (a durationMs under ~100ms is too short for the deceleration to suppress the fling entirely). Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not reachable for the given device.`,
   alwaysLoad: true,
   searchHint: "drag drop slider mouse press move release chromium select",
   zodSchema: zodSchema19,
@@ -119576,15 +119647,49 @@ Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not
   services: (params) => ({
     chromium: chromiumCdpRef(resolveDevice(params.udid))
   }),
-  async execute(services, params) {
+  async execute(services, params, ctx) {
     const timestampMs = Date.now();
     const chromium = services.chromium;
     await assertChromiumWindowVisible(chromium, "drag", "chromium_drag_window_hidden");
     const vp = chromium.getViewport();
-    const startPx = { x: params.fromX * vp.width, y: params.fromY * vp.height };
-    const endPx = { x: params.toX * vp.width, y: params.toY * vp.height };
+    const clampPx2 = (px, size) => Math.min(Math.max(px, 0), size - 1);
+    const startPx = {
+      x: clampPx2(params.fromX * vp.width, vp.width),
+      y: clampPx2(params.fromY * vp.height, vp.height)
+    };
+    const endPx = {
+      x: clampPx2(params.toX * vp.width, vp.width),
+      y: clampPx2(params.toY * vp.height, vp.height)
+    };
     const durationMs = params.durationMs ?? 300;
-    const steps = Math.max(2, Math.round(durationMs / 16));
+    const momentumFree = params.momentum === false;
+    const steps = Math.max(momentumFree ? MOMENTUM_FREE_MIN_STEPS : 2, Math.round(durationMs / 16));
+    const frameMs = durationMs / steps;
+    const t0 = Date.now();
+    let lastX = startPx.x;
+    let lastY = startPx.y;
+    const abortError = (frame) => {
+      const err = new Error(
+        `gesture-drag aborted - cancelled mid-drag after ${frame} of ${steps + 1} frames`
+      );
+      err.name = "AbortError";
+      return err;
+    };
+    const releaseAndAbort = async (frame) => {
+      const err = abortError(frame);
+      try {
+        await chromium.dispatchMouseEvent({
+          type: "mouseReleased",
+          x: lastX,
+          y: lastY,
+          clickCount: 1
+        });
+      } catch (releaseErr) {
+        err.cause = releaseErr;
+      }
+      throw err;
+    };
+    if (ctx?.signal?.aborted) throw abortError(0);
     await chromium.dispatchMouseEvent({
       type: "mousePressed",
       x: startPx.x,
@@ -119592,15 +119697,19 @@ Returns { dragged: true, timestampMs }. Fails if the Chromium CDP session is not
       clickCount: 1
     });
     for (let i = 1; i < steps; i++) {
+      if (ctx?.signal?.aborted) await releaseAndAbort(i);
+      await sleep5(Math.max(0, t0 + i * frameMs - Date.now()));
       const t = i / steps;
-      await chromium.dispatchMouseEvent({
-        type: "mouseMoved",
-        x: startPx.x + (endPx.x - startPx.x) * t,
-        y: startPx.y + (endPx.y - startPx.y) * t,
-        button: "left"
-      });
-      await sleep5(16);
-    }
+      const progress = momentumFree ? 1 - Math.pow(1 - t, MOMENTUM_FREE_EASE_EXPONENT2) : t;
+      const x = startPx.x + (endPx.x - startPx.x) * progress;
+      const y = startPx.y + (endPx.y - startPx.y) * progress;
+      await chromium.dispatchMouseEvent({ type: "mouseMoved", x, y, button: "left" });
+      lastX = x;
+      lastY = y;
+    }
+    if (ctx?.signal?.aborted) await releaseAndAbort(steps);
+    await sleep5(Math.max(0, t0 + durationMs - Date.now()));
+    if (ctx?.signal?.aborted) await releaseAndAbort(steps);
     await chromium.dispatchMouseEvent({
       type: "mouseReleased",
       x: endPx.x,
@@ -127820,9 +127929,9 @@ a prior tap), use individual tool calls instead.
 Allowed tools and their args (udid is auto-injected, do NOT include it in args):
 
   gesture-tap:    { x: number, y: number, clickCount?: number }                                                        [ios/android/chromium]
-  gesture-swipe:  { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number }                       [ios/android]
+  gesture-swipe:  { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number, momentum?: boolean }   [ios/android]
   gesture-scroll: { x: number, y: number, deltaX?: number, deltaY?: number, durationMs?: number }                       [chromium only]
-  gesture-drag:   { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number }                       [chromium only]
+  gesture-drag:   { fromX: number, fromY: number, toX: number, toY: number, durationMs?: number, momentum?: boolean }   [chromium only]
   gesture-custom: { events: [{ type: "Down"|"Move"|"Up", x: number, y: number, x2?: number, y2?: number, delayMs?: number }], interpolate?: number }  [ios/android]
   gesture-pinch:  { centerX: number, centerY: number, startDistance: number, endDistance: number, endCenterX?: number, endCenterY?: number, angle?: number, durationMs?: number }  [ios/android]
   gesture-rotate: { centerX: number, centerY: number, radius?: number, radiusX?: number, radiusY?: number, startAngle: number, endAngle: number, durationMs?: number }  [ios/android]
@@ -140883,6 +140992,12 @@ function chromiumLaunchSpec(launch) {
   return typeof c === "string" ? { path: c } : { path: c.path, args: c.args };
 }
 function selectorToYaml(sel) {
+  const unknown2 = Object.keys(sel).filter((key2) => !WRITABLE_SELECTOR_KEYS.includes(key2));
+  if (unknown2.length > 0) {
+    throw new Error(
+      `Cannot serialize flow selector: ${describeUnknownKeys(unknown2, WRITABLE_SELECTOR_KEYS)} - allowed keys: ${WRITABLE_SELECTOR_KEYS.join(", ")}.`
+    );
+  }
   if (sel.text !== void 0 && sel.textMatches !== void 0) {
     throw new Error(
       'Cannot serialize flow selector without losing constraints: both `text` and `textMatches` are set, but flow YAML can represent only one `text` constraint (a literal string or `{ matches: "<regex>" }`). Use either literal or regex text matching.'
@@ -141005,6 +141120,79 @@ function targetToYaml(step) {
   }
   return { x: step.x, y: step.y };
 }
+function swipeTargetToYaml(target, label) {
+  const yaml = targetToYaml(target);
+  if (typeof yaml !== "string" && "x" in yaml && !Object.keys(target).every((key2) => key2 === "x" || key2 === "y")) {
+    throw new Error(`Cannot serialize flow ${label}: a coordinate target takes only { x, y }`);
+  }
+  return yaml;
+}
+var SWIPE_MIN_TRAVEL = 0.03;
+var SWIPE_MIN_DURATION_MS = 150;
+var SWIPE_MAX_DURATION_MS = 1e4;
+var LONG_PRESS_MAX_DURATION_MS = SWIPE_MAX_DURATION_MS;
+function swipeByToYaml(by) {
+  const keys = Object.keys(by);
+  if (keys.some((key2) => key2 !== "x" && key2 !== "y")) {
+    throw new Error("Cannot serialize flow swipe.by: accepts only x and y");
+  }
+  const axes = ["x", "y"].filter((axis) => by[axis] !== void 0);
+  if (axes.length === 0) {
+    throw new Error("Cannot serialize flow swipe.by: needs at least one of x or y");
+  }
+  const result = {};
+  for (const axis of axes) {
+    const value = by[axis];
+    if (!Number.isFinite(value) || value === 0 || value < -1 || value > 1) {
+      throw new Error(
+        `Cannot serialize flow swipe.by.${axis}: must be a non-zero fraction of the screen between -1 and 1`
+      );
+    }
+    result[axis] = value;
+  }
+  const magnitude = Math.hypot(result.x ?? 0, result.y ?? 0);
+  if (magnitude < SWIPE_MIN_TRAVEL) {
+    throw new Error(
+      `Cannot serialize flow swipe.by: travels only ${magnitude} \u2014 below the minimum swipe travel of ${SWIPE_MIN_TRAVEL} \u2014 a travel that small is a tap, not a swipe`
+    );
+  }
+  return result;
+}
+function swipeByLabel(by) {
+  return ["x", "y"].filter((axis) => by[axis] !== void 0).map((axis) => `${axis}=${by[axis]}`).join(", ");
+}
+function isPositiveMs(raw) {
+  return typeof raw === "number" && Number.isFinite(raw) && raw > 0;
+}
+function positiveMsToYaml(value, label) {
+  if (!isPositiveMs(value)) {
+    throw new Error(`Cannot serialize flow ${label}: needs a positive number of milliseconds`);
+  }
+  return value;
+}
+function swipeDurationToYaml(value) {
+  const duration3 = positiveMsToYaml(value, "swipe.duration");
+  if (duration3 < SWIPE_MIN_DURATION_MS) {
+    throw new Error(
+      `Cannot serialize flow swipe.duration: only ${duration3}ms \u2014 below the minimum swipe duration of ${SWIPE_MIN_DURATION_MS}ms \u2014 that leaves too few 16ms frames for the content to track the travel it was given, so it overshoots instead of landing on it`
+    );
+  }
+  if (duration3 > SWIPE_MAX_DURATION_MS) {
+    throw new Error(
+      `Cannot serialize flow swipe.duration: ${duration3}ms - above the maximum swipe duration of ${SWIPE_MAX_DURATION_MS}ms - the step would hold a finger on the screen for exactly that long, one dispatched frame per 16ms`
+    );
+  }
+  return duration3;
+}
+function longPressDurationToYaml(value) {
+  const duration3 = positiveMsToYaml(value, "long-press.duration");
+  if (duration3 > LONG_PRESS_MAX_DURATION_MS) {
+    throw new Error(
+      `Cannot serialize flow long-press.duration: ${duration3}ms - above the maximum long-press duration of ${LONG_PRESS_MAX_DURATION_MS}ms - the step would hold a finger down for exactly that long`
+    );
+  }
+  return duration3;
+}
 function waitToYaml(condition, selector, expectedText, textMatch, timeoutMs) {
   const sel = selectorToYaml(selector);
   let body;
@@ -141022,7 +141210,7 @@ function waitToYaml(condition, selector, expectedText, textMatch, timeoutMs) {
       body = textWaitToYaml(sel, expectedText, textMatch);
       break;
   }
-  if (timeoutMs !== void 0) body.timeout = timeoutMs;
+  if (timeoutMs !== void 0) body.timeout = positiveMsToYaml(timeoutMs, "await.timeout");
   return body;
 }
 function idleToYaml(step) {
@@ -141058,9 +141246,29 @@ function toYamlStep(step) {
     case "long-press": {
       const target = targetToYaml(step);
       return {
-        "long-press": step.duration !== void 0 ? { on: target, duration: step.duration } : target
+        "long-press": step.duration !== void 0 ? { on: target, duration: longPressDurationToYaml(step.duration) } : target
       };
     }
+    case "swipe": {
+      const travels = ["direction", "to", "by"].filter((key2) => step[key2] !== void 0);
+      if (travels.length !== 1) {
+        throw new Error("Cannot serialize flow swipe: needs exactly one of direction, to, or by");
+      }
+      if (step.momentum !== void 0 && typeof step.momentum !== "boolean") {
+        throw new Error("Cannot serialize flow swipe.momentum: must be true or false");
+      }
+      if (step.direction !== void 0 && step.from === void 0 && step.to === void 0 && step.by === void 0 && step.momentum !== false && step.duration === void 0) {
+        return { swipe: step.direction };
+      }
+      const body = {};
+      if (step.from !== void 0) body.from = swipeTargetToYaml(step.from, "swipe.from");
+      if (step.direction !== void 0) body.direction = step.direction;
+      if (step.to !== void 0) body.to = swipeTargetToYaml(step.to, "swipe.to");
+      if (step.by !== void 0) body.by = swipeByToYaml(step.by);
+      if (step.momentum === false) body.momentum = false;
+      if (step.duration !== void 0) body.duration = swipeDurationToYaml(step.duration);
+      return { swipe: body };
+    }
     case "type": {
       const body = {
         into: selectorToYaml(step.into),
@@ -141153,6 +141361,12 @@ function badEntry(raw, detail) {
     error_kind: "validation"
   });
 }
+function parsePositiveMs(raw, entry, label, example) {
+  if (!isPositiveMs(raw)) {
+    badEntry(entry, `${label} needs a positive number of milliseconds (e.g. \`${example}\`)`);
+  }
+  return raw;
+}
 function validatePattern(raw, pattern, where) {
   try {
     new RegExp(pattern);
@@ -141216,6 +141430,17 @@ var SELECTOR_KEYS = [
   "any",
   ...SELECTOR_RELATIONS
 ];
+var WRITABLE_SELECTOR_KEYS = Object.keys({
+  text: true,
+  textMatches: true,
+  identifier: true,
+  role: true,
+  any: true,
+  loose: true,
+  within: true,
+  after: true,
+  next: true
+});
 var MAX_SELECTOR_SCOPES = 6;
 function parseSelector(raw, where, budget = { scopes: MAX_SELECTOR_SCOPES }) {
   if (budget.scopes < 0) {
@@ -141346,7 +141571,7 @@ function parseWaitFields(raw, kind) {
         "assert has no timeout \u2014 it is an immediate check; use `await` for a timed wait"
       );
     }
-    timeout = parseAwaitTimeout({ [kind]: b }, b.timeout);
+    timeout = parsePositiveMs(b.timeout, { [kind]: b }, "await.timeout", "timeout: 10000");
   }
   rejectUnknownKeys(
     { [kind]: b },
@@ -141515,6 +141740,7 @@ var STEP_DIRECTIVE_KEYS = [
   "tool",
   "tap",
   "long-press",
+  "swipe",
   "type",
   "await",
   "assert",
@@ -141613,13 +141839,19 @@ function parseLongPress(body, entry) {
     }
     const step = { kind: "long-press", ...parseTarget(obj.on, "long-press.on") };
     if (obj.duration !== void 0) {
-      if (typeof obj.duration !== "number" || !Number.isFinite(obj.duration) || obj.duration <= 0) {
+      const duration3 = parsePositiveMs(
+        obj.duration,
+        entry,
+        "long-press.duration",
+        "duration: 1200"
+      );
+      if (duration3 > LONG_PRESS_MAX_DURATION_MS) {
         badEntry(
           entry,
-          "long-press.duration needs a positive number of milliseconds (e.g. `duration: 1200`)"
+          `long-press.duration is ${duration3}ms - above the maximum long-press duration of ${LONG_PRESS_MAX_DURATION_MS}ms; the step holds a finger down for exactly that long, and on Chromium it dispatches a gesture-drag that refuses more`
         );
       }
-      step.duration = obj.duration;
+      step.duration = duration3;
     }
     return step;
   }
@@ -141789,6 +142021,116 @@ function completeRunExtension(value) {
   const candidate = `${value}.yaml`;
   return FLOW_FILE_NAME_PATTERN.test(path32.posix.basename(candidate)) ? candidate : value;
 }
+var SWIPE_DIRECTIONS = ["up", "down", "left", "right"];
+var SWIPE_OPTION_KEYS = ["from", "direction", "to", "by", "momentum", "duration"];
+function parseSwipeBy(raw, entry) {
+  if (raw === null || typeof raw !== "object") {
+    badEntry(entry, "swipe.by needs { x } and/or { y } \u2014 signed 0\u20131 fractions of the screen");
+  }
+  const obj = raw;
+  rejectUnknownKeys(entry, obj, ["x", "y"], "swipe.by");
+  if (obj.x === void 0 && obj.y === void 0) {
+    badEntry(entry, "swipe.by needs at least one of x, y");
+  }
+  const by = {};
+  for (const axis of ["x", "y"]) {
+    const v = obj[axis];
+    if (v === void 0) continue;
+    if (typeof v !== "number" || !Number.isFinite(v) || v === 0 || v < -1 || v > 1) {
+      badEntry(
+        entry,
+        `swipe.by.${axis} must be a non-zero fraction of the screen between -1 and 1 (omit the axis instead of 0)`
+      );
+    }
+    by[axis] = v;
+  }
+  const magnitude = Math.hypot(by.x ?? 0, by.y ?? 0);
+  if (magnitude < SWIPE_MIN_TRAVEL) {
+    badEntry(
+      entry,
+      `swipe.by travels only ${magnitude} \u2014 below the minimum swipe travel of ${SWIPE_MIN_TRAVEL}; a travel that small is a tap, not a swipe`
+    );
+  }
+  return by;
+}
+function parseSwipe(body, entry) {
+  if (typeof body === "string") {
+    if (!SWIPE_DIRECTIONS.includes(body)) {
+      badEntry(
+        entry,
+        `swipe takes a direction (${SWIPE_DIRECTIONS.join(", ")}) \u2014 to anchor on an element use swipe: { from: <target>, direction: \u2026 }`
+      );
+    }
+    return { kind: "swipe", direction: body };
+  }
+  if (body === null || typeof body !== "object") {
+    badEntry(entry, `swipe needs a direction (${SWIPE_DIRECTIONS.join(", ")}) or an options map`);
+  }
+  const obj = body;
+  if (hasSelectorField(obj)) {
+    badEntry(
+      entry,
+      'the swipe options form takes a nested target \u2014 e.g. swipe: { from: { text: "Card" }, direction: left }'
+    );
+  }
+  if (obj.x !== void 0 || obj.y !== void 0) {
+    badEntry(
+      entry,
+      "the swipe options form takes a nested point \u2014 e.g. swipe: { from: { x: 0.5, y: 0.5 }, direction: left }"
+    );
+  }
+  if (obj.settle !== void 0) {
+    badEntry(
+      entry,
+      "swipe.settle was renamed to swipe.momentum, with the opposite sense \u2014 write `momentum: false` for the momentum-free swipe that `settle: true` used to mean (plain `settle: false` was the default, so just drop it)"
+    );
+  }
+  rejectUnknownKeys(entry, obj, SWIPE_OPTION_KEYS, "swipe");
+  const travels = ["direction", "to", "by"].filter((k) => obj[k] !== void 0);
+  if (travels.length !== 1) {
+    badEntry(entry, "swipe needs exactly one of `direction`, `to`, or `by`");
+  }
+  const step = { kind: "swipe" };
+  if (obj.from !== void 0) step.from = parseTarget(obj.from, "swipe.from");
+  switch (travels[0]) {
+    case "direction": {
+      if (typeof obj.direction !== "string" || !SWIPE_DIRECTIONS.includes(obj.direction)) {
+        badEntry(entry, `swipe.direction must be one of ${SWIPE_DIRECTIONS.join(", ")}`);
+      }
+      step.direction = obj.direction;
+      break;
+    }
+    case "to":
+      step.to = parseTarget(obj.to, "swipe.to");
+      break;
+    case "by":
+      step.by = parseSwipeBy(obj.by, entry);
+      break;
+  }
+  if (obj.momentum !== void 0) {
+    if (typeof obj.momentum !== "boolean") {
+      badEntry(entry, "swipe.momentum must be true or false");
+    }
+    if (!obj.momentum) step.momentum = false;
+  }
+  if (obj.duration !== void 0) {
+    const duration3 = parsePositiveMs(obj.duration, entry, "swipe.duration", "duration: 800");
+    if (duration3 < SWIPE_MIN_DURATION_MS) {
+      badEntry(
+        entry,
+        `swipe.duration is only ${duration3}ms \u2014 below the minimum swipe duration of ${SWIPE_MIN_DURATION_MS}ms; that leaves too few 16ms frames for the content to track the travel it was given, so it overshoots instead of landing on it`
+      );
+    }
+    if (duration3 > SWIPE_MAX_DURATION_MS) {
+      badEntry(
+        entry,
+        `swipe.duration is ${duration3}ms - above the maximum swipe duration of ${SWIPE_MAX_DURATION_MS}ms; the step holds a finger on the screen for exactly that long, one dispatched frame per 16ms, and nothing outside the run can cut it short`
+      );
+    }
+    step.duration = duration3;
+  }
+  return step;
+}
 function fromYamlStep(raw, blockDepth = 0) {
   const entry = raw;
   if ("optional" in raw) {
@@ -141830,6 +142172,7 @@ function fromYamlStep(raw, blockDepth = 0) {
   if ("long-press" in raw) {
     return parseLongPress(raw["long-press"], raw);
   }
+  if ("swipe" in raw) return parseSwipe(raw.swipe, raw);
   if ("type" in raw) {
     const body = raw.type;
     if (!body || typeof body !== "object") badEntry(raw, "type needs { into, text }");
@@ -142446,6 +142789,7 @@ function stepRequiresDevice(registry2, step) {
     case "launch":
     case "tap":
     case "long-press":
+    case "swipe":
     case "type":
     case "await":
     case "assert":
@@ -143287,22 +143631,32 @@ async function settleTree(env, opts = {}) {
     if (!await sleepOrAbort(SETTLE_POLL_MS, env.signal)) return void 0;
   }
 }
-async function waitForFrame(env, selector) {
+async function waitForFrames(env, selectors) {
+  const pending = selectors.flatMap((selector, i) => selector ? [{ i, selector }] : []);
+  if (pending.length === 0) return selectors.map(() => void 0);
   const deadline = Date.now() + DEFAULT_ACTION_TIMEOUT_MS;
+  let unresolved = pending[0].selector;
   for (; ; ) {
     if (env.signal?.aborted) return "aborted";
     const tree = await settleTree(env);
     if (tree) {
-      const frame = flowSelectorToFrame(tree, selector);
-      if (frame) return frame;
+      const frames = selectors.map((s) => s ? flowSelectorToFrame(tree, s) : void 0);
+      const missing = pending.find(({ i }) => frames[i] === void 0);
+      if (!missing) return frames;
+      unresolved = missing.selector;
     } else if (env.signal?.aborted) {
       return "aborted";
     }
-    if (Date.now() >= deadline) return void 0;
+    if (Date.now() >= deadline) return { unresolved };
     const sleepMs = Math.min(POLL_INTERVAL_MS, Math.max(0, deadline - Date.now()));
     if (!await sleepOrAbort(sleepMs, env.signal)) return "aborted";
   }
 }
+async function waitForFrame(env, selector) {
+  const frames = await waitForFrames(env, [selector]);
+  if (frames === "aborted") return "aborted";
+  return Array.isArray(frames) ? frames[0] : void 0;
+}
 function framesOverlap(a, b) {
   return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
 }
@@ -143366,14 +143720,19 @@ async function scrollIncrement(env, direction, region) {
       to = { x: clamp014(cx + dist), y: cy };
       break;
   }
-  await invokeOnDevice(env, "gesture-swipe", {
-    fromX: cx,
-    fromY: cy,
-    toX: to.x,
-    toY: to.y,
-    settle: true,
-    durationMs: 600
-  });
+  try {
+    await invokeOnDevice(env, "gesture-swipe", {
+      fromX: cx,
+      fromY: cy,
+      toX: to.x,
+      toY: to.y,
+      momentum: false,
+      durationMs: 600
+    });
+  } catch (err) {
+    if (env.signal?.aborted) return;
+    throw err;
+  }
 }
 async function scrollToVisible(env, target, direction, within) {
   let prevFp;
@@ -143407,7 +143766,7 @@ function offscreenHint(sel) {
   return `no visible element matched selector ${describeSelector(sel)} \u2014 if it is off-screen, add a scroll-to step before this one`;
 }
 async function runDirective(env, step) {
-  if (env.device.platform === "vega" && (step.kind === "tap" || step.kind === "long-press" || step.kind === "type" || step.kind === "scroll-to" || step.kind === "pinch" || step.kind === "rotate")) {
+  if (env.device.platform === "vega" && (step.kind === "tap" || step.kind === "long-press" || step.kind === "swipe" || step.kind === "type" || step.kind === "scroll-to" || step.kind === "pinch" || step.kind === "rotate")) {
     return {
       ok: false,
       reason: `${step.kind} is a touch directive and Vega is remote-driven \u2014 move focus with \`tool: tv-remote\` steps (and type via \`tool: keyboard\`) instead`
@@ -143424,6 +143783,8 @@ async function runDirective(env, step) {
       return runTap(env, step);
     case "long-press":
       return runLongPress(env, step);
+    case "swipe":
+      return runSwipe(env, step);
     case "type":
       return runType(env, step);
     case "await":
@@ -143471,10 +143832,16 @@ async function resolveTargetPoint(env, target) {
     }
     return { point: getDescribeTapPoint(frame) };
   }
+  const point = targetPointFromFrame(target, void 0);
+  if ("fail" in point) return point;
+  const settle = await settleForGesture(env);
+  if (settle.aborted) return { fail: ABORTED_OUTCOME };
+  return { point, ...warned(settle) };
+}
+function targetPointFromFrame(target, frame) {
+  if (frame) return getDescribeTapPoint(frame);
   if (typeof target.x === "number" && typeof target.y === "number") {
-    const settle = await settleForGesture(env);
-    if (settle.aborted) return { fail: ABORTED_OUTCOME };
-    return { point: { x: target.x, y: target.y }, ...warned(settle) };
+    return { x: target.x, y: target.y };
   }
   return { fail: { ok: false, reason: "gesture needs a selector or x/y coordinates" } };
 }
@@ -143494,13 +143861,18 @@ async function runLongPress(env, step) {
   const point = resolved.point;
   const duration3 = step.duration ?? DEFAULT_LONG_PRESS_MS;
   if (env.device.platform === "chromium") {
-    await invokeOnDevice(env, "gesture-drag", {
-      fromX: point.x,
-      fromY: point.y,
-      toX: point.x,
-      toY: point.y,
-      durationMs: duration3
-    });
+    try {
+      await invokeOnDevice(env, "gesture-drag", {
+        fromX: point.x,
+        fromY: point.y,
+        toX: point.x,
+        toY: point.y,
+        durationMs: duration3
+      });
+    } catch (err) {
+      if (env.signal?.aborted) return ABORTED_OUTCOME;
+      throw err;
+    }
   } else {
     await invokeOnDevice(env, "gesture-custom", {
       events: [
@@ -143620,6 +143992,132 @@ async function runRotate(env, step) {
   }
   return { ok: true, ...warned(settle) };
 }
+var SWIPE_GEOMETRY = {
+  left: { start: { x: 0.9, y: 0.5 }, axis: "x", end: 0.1 },
+  right: { start: { x: 0.1, y: 0.5 }, axis: "x", end: 0.9 },
+  down: { start: { x: 0.5, y: 0.2 }, axis: "y", end: 0.9 },
+  up: { start: { x: 0.5, y: 0.5 }, axis: "y", end: 0.1 }
+};
+async function runSwipe(env, step) {
+  const ends = [step.from, step.to];
+  const selectors = ends.map((end2) => end2 && "selector" in end2 ? end2.selector : void 0);
+  const frames = await waitForFrames(env, selectors);
+  if (frames === "aborted") return ABORTED_OUTCOME;
+  if (!Array.isArray(frames)) return { ok: false, reason: offscreenHint(frames.unresolved) };
+  const [fromFrame, toFrame] = frames;
+  let settle = {};
+  if (selectors.every((selector) => selector === void 0)) {
+    settle = await settleForGesture(env);
+    if (settle.aborted) return ABORTED_OUTCOME;
+  }
+  let toPoint;
+  if (step.to) {
+    const p = targetPointFromFrame(step.to, toFrame);
+    if ("fail" in p) return p.fail;
+    toPoint = p;
+  }
+  let start2;
+  if (step.from) {
+    const p = targetPointFromFrame(step.from, fromFrame);
+    if ("fail" in p) return p.fail;
+    start2 = p;
+  } else if (step.direction) {
+    start2 = { ...SWIPE_GEOMETRY[step.direction].start };
+  } else {
+    start2 = { x: 0.5, y: 0.5 };
+  }
+  if (!Number.isFinite(start2.x) || start2.x < 0 || start2.x > 1 || !Number.isFinite(start2.y) || start2.y < 0 || start2.y > 1) {
+    return {
+      ok: false,
+      reason: `swipe.from resolved outside the normalized screen: (${start2.x}, ${start2.y}); both coordinates must be between 0 and 1`
+    };
+  }
+  let end;
+  if (step.direction) {
+    const g = SWIPE_GEOMETRY[step.direction];
+    const startOnTravelAxis = start2[g.axis];
+    const endOnTravelAxis = step.from ? clamp014(startOnTravelAxis + (g.end - g.start[g.axis])) : g.end;
+    end = g.axis === "x" ? { x: endOnTravelAxis, y: start2.y } : { x: start2.x, y: endOnTravelAxis };
+    const travel2 = Math.abs(endOnTravelAxis - startOnTravelAxis);
+    if (travel2 < SWIPE_MIN_TRAVEL) {
+      return {
+        ok: false,
+        reason: `cannot swipe ${step.direction} from ${g.axis}=${startOnTravelAxis}: only ${travel2} of travel to the screen edge, less than the minimum swipe travel of ${SWIPE_MIN_TRAVEL} \u2014 a tap, not a swipe`
+      };
+    }
+  } else if (step.by) {
+    const overflowAxis = ["x", "y"].find((axis) => {
+      const d = step.by[axis];
+      return d !== void 0 && (start2[axis] + d < 0 || start2[axis] + d > 1);
+    });
+    if (overflowAxis === void 0) {
+      end = {
+        x: step.by.x !== void 0 ? start2.x + step.by.x : start2.x,
+        y: step.by.y !== void 0 ? start2.y + step.by.y : start2.y
+      };
+    } else if (step.from) {
+      const requested = step.by[overflowAxis];
+      const raw = start2[overflowAxis] + requested;
+      return {
+        ok: false,
+        reason: `swipe.by.${overflowAxis} of ${requested} from ${overflowAxis}=${start2[overflowAxis]} lands at ${raw}, off the normalized screen; reduce the delta so from + by stays within [0, 1]`
+      };
+    } else {
+      end = { x: start2.x, y: start2.y };
+      for (const axis of ["x", "y"]) {
+        const d = step.by[axis];
+        if (d === void 0) {
+          end[axis] = start2[axis];
+          continue;
+        }
+        const s = start2[axis];
+        const lo = Math.min(s, s + d);
+        const hi = Math.max(s, s + d);
+        const shift = lo < 0 ? -lo : hi > 1 ? 1 - hi : 0;
+        start2[axis] = s + shift;
+        end[axis] = s + d + shift;
+      }
+    }
+  } else {
+    end = toPoint;
+    if (!Number.isFinite(end.x) || end.x < 0 || end.x > 1 || !Number.isFinite(end.y) || end.y < 0 || end.y > 1) {
+      return {
+        ok: false,
+        reason: `swipe.to resolved outside the normalized screen: (${end.x}, ${end.y}); both coordinates must be between 0 and 1`
+      };
+    }
+    if (Math.hypot(end.x - start2.x, end.y - start2.y) < SWIPE_MIN_TRAVEL) {
+      return {
+        ok: false,
+        reason: `swipe.to (${end.x}, ${end.y}) resolved within the minimum swipe travel of the start point (${start2.x}, ${start2.y}); aim it at a point or element farther from the start`
+      };
+    }
+  }
+  const travel = {
+    fromX: start2.x,
+    fromY: start2.y,
+    toX: end.x,
+    toY: end.y,
+    ...step.duration !== void 0 ? { durationMs: step.duration } : {},
+    ...step.momentum === false ? { momentum: false } : {}
+  };
+  try {
+    await invokeOnDevice(
+      env,
+      env.device.platform === "chromium" ? "gesture-drag" : "gesture-swipe",
+      travel
+    );
+  } catch (err) {
+    if (env.signal?.aborted) return ABORTED_OUTCOME;
+    throw err;
+  }
+  try {
+    await settleTree(env);
+  } catch {
+  }
+  if (env.signal?.aborted) return ABORTED_OUTCOME;
+  return { ok: true, ...warned(settle) };
+}
 async function runType(env, step) {
   const frame = await waitForFrame(env, step.into);
   if (frame === "aborted") return ABORTED_OUTCOME;
@@ -143951,6 +144449,9 @@ function textConditionLabel(sel, expectedText, textMatch) {
   const expected = expectedText ?? "";
   return textMatch === "matches" ? `text ${selector} matches /${expected}/` : textMatch === "equals" ? `text ${selector} == ${JSON.stringify(expected)}` : `text ${selector} contains ${JSON.stringify(expected)}`;
 }
+function targetLabel(target) {
+  return "selector" in target ? selectorLabel(target.selector) : `(${target.x}, ${target.y})`;
+}
 var zodSchema62 = external_exports.object({
   name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
   project_root: external_exports.string().describe(
@@ -144078,11 +144579,23 @@ function summarizeStep(step, n) {
       return `${n}. run: ${step.flow}`;
     case "tap":
     case "long-press": {
-      const target = step.selector ? selectorLabel(step.selector) : `(${step.x}, ${step.y})`;
+      const target = targetLabel(
+        step.selector ? { selector: step.selector } : { x: step.x, y: step.y }
+      );
       const times = step.kind === "tap" && step.times !== void 0 && step.times > 1 ? ` \xD7${step.times}` : "";
       const held = step.kind === "long-press" && step.duration !== void 0 ? ` for ${step.duration}ms` : "";
       return `${n}. ${step.kind}: ${target}${times}${held}`;
     }
+    case "swipe": {
+      const travel = step.direction ?? (step.by ? `by ${swipeByLabel(step.by)}` : `to ${targetLabel(step.to)}`);
+      const from2 = step.from ? ` from ${targetLabel(step.from)}` : "";
+      const options = [
+        ...step.momentum === false ? ["momentum-free"] : [],
+        ...step.duration !== void 0 ? [`${step.duration}ms`] : []
+      ];
+      const tail = options.length > 0 ? ` (${options.join(", ")})` : "";
+      return `${n}. swipe: ${travel}${from2}${tail}`;
+    }
     case "type":
       return `${n}. type: ${selectorLabel(step.into)} \u2190 "${step.text}"`;
     case "await":
@@ -144124,7 +144637,7 @@ var zodSchema63 = external_exports.object({
     "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording this step belongs to."
   ),
   command: external_exports.string().describe(
-    'MCP tool name (e.g. "gesture-tap", "screenshot", "launch-app") \u2014 a TOOL, not a flow directive. A flow-file directive name ("tap", "launch", "run", "type", "await", "assert", "pinch", "echo", "wait", "long-press", "scroll-to", "snapshot", "when") is answered with guidance, and nothing runs or is recorded: most name the tool that records the directive, while "wait", "long-press", "scroll-to", "snapshot" and "when" have no recording tool at all and are answered with what to do instead. A recording tool (flow-add-step, flow-add-echo, flow-start-recording, flow-finish-recording) is refused the same way, each for its own reason \u2014 nesting one would erase this flow at replay, end the take, or write the step twice.'
+    'MCP tool name (e.g. "gesture-tap", "screenshot", "launch-app") \u2014 a TOOL, not a flow directive. A flow-file directive name ("tap", "launch", "run", "type", "await", "assert", "pinch", "swipe", "echo", "wait", "long-press", "scroll-to", "snapshot", "when") is answered with guidance, and nothing runs or is recorded: most name the tool that records the directive, while "wait", "long-press", "scroll-to", "snapshot" and "when" have no recording tool at all and are answered with what to do instead. A recording tool (flow-add-step, flow-add-echo, flow-start-recording, flow-finish-recording) is refused the same way, each for its own reason \u2014 nesting one would erase this flow at replay, end the take, or write the step twice.'
   ),
   args: external_exports.string().optional().describe(
     `Tool arguments as a JSON string, e.g. '{"udid": "ABC", "x": 0.5, "y": 0.3}'. Omit for tools with no arguments.`
@@ -144378,6 +144891,9 @@ function isToolNotFound(err, command) {
   return err instanceof ToolNotFoundError && err.toolId === command;
 }
 function directiveCommandHint(command) {
+  if (command === "swipe") {
+    return `"swipe" is a flow directive, not a tool. Record the movement by calling \`gesture-swipe\` (\`gesture-drag\` on chromium, where gesture-swipe is not supported) through flow-add-step. It is stored as the raw \`tool:\` step for whichever one you called; converting it to \`swipe:\` is part of the polish pass.`;
+  }
   if (command === "echo") {
     return `"echo" is a flow directive, not a tool. Call \`flow-add-echo\` DIRECTLY \u2014 not through flow-add-step, which would run it as a nested tool AND record a \`tool: flow-add-echo\` step that fails on every replay.`;
   }
@@ -147402,15 +147918,71 @@ function displayFlowName(params) {
   const stem = params.flow_path === void 0 ? void 0 : path36.basename(params.flow_path, ".yaml");
   return params.name || stem || params.flow_path || "(unspecified)";
 }
-function* walkSteps(steps) {
-  for (const step of steps) {
-    yield step;
+function* walkSteps(steps, within = "") {
+  for (const [i, step] of steps.entries()) {
+    const where = `step ${i + 1}${within}`;
+    yield { step, where };
     const inner = blockSteps(step);
-    if (inner) yield* walkSteps(inner);
+    if (inner) yield* walkSteps(inner, ` of the ${step.kind}: block at ${where}`);
+  }
+}
+function retiredKeyGuidance(prop) {
+  const schema = prop;
+  if (!schema?.not || Object.keys(schema.not).length > 0) return void 0;
+  return (schema.description ?? "").replace(/^Retired:\s*/, "");
+}
+function toolArgProps(registry2, tool) {
+  return registry2.getTool(tool)?.inputSchema?.properties;
+}
+function retiredArgIn(props, tool, args, where) {
+  for (const key2 of Object.keys(args)) {
+    const guidance = retiredKeyGuidance(props[key2]);
+    if (guidance !== void 0) return { where, tool, key: key2, guidance };
+  }
+  return void 0;
+}
+function* nestedInvocations(props, args) {
+  for (const [key2, value] of Object.entries(args)) {
+    if (!Object.hasOwn(props, key2)) continue;
+    const entries = Array.isArray(value) ? value : [value];
+    for (const [i, entry] of entries.entries()) {
+      const call = entry;
+      if (typeof call?.tool !== "string") continue;
+      if (typeof call.args !== "object" || call.args === null || Array.isArray(call.args)) continue;
+      yield {
+        tool: call.tool,
+        args: call.args,
+        at: Array.isArray(value) ? `step ${i + 1}` : `\`${key2}\``
+      };
+    }
+  }
+}
+function findRetiredToolArg(registry2, steps) {
+  for (const { step, where } of walkSteps(steps)) {
+    if (step.kind !== "tool") continue;
+    const props = toolArgProps(registry2, step.name);
+    if (!props) continue;
+    const direct = retiredArgIn(props, step.name, step.args, where);
+    if (direct) return direct;
+    for (const call of nestedInvocations(props, step.args)) {
+      const nestedProps = toolArgProps(registry2, call.tool);
+      if (!nestedProps) continue;
+      const hit = retiredArgIn(
+        nestedProps,
+        call.tool,
+        call.args,
+        `${call.at} of the ${step.name} step at ${where}`
+      );
+      if (hit) return hit;
+    }
   }
+  return void 0;
+}
+function retiredArgReason(use) {
+  return `${use.where} as written (echo included) passes ${use.tool}'s retired \`${use.key}\` key${use.guidance ? `: ${use.guidance}` : ""}`;
 }
 function assertUploadSelfContained(flow) {
-  for (const step of walkSteps(flow.steps)) {
+  for (const { step } of walkSteps(flow.steps)) {
     if (step.kind === "run") {
       throw new FailureError(
         `This flow uses run: composition ("run: ${step.flow}"), which requires a co-located client and tool server \u2014 an uploaded flow's referenced files are not available on this host.`,
@@ -147444,6 +148016,9 @@ function createRunFlowTool(registry2) {
       failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to run flow ${displayFlowName(params)}: ${failureSignal2.error_code}`
     },
     description: `Run a saved flow from the .argent/flows/ directory, or an explicit boundary-managed flow_path.
+Use when a scenario is already authored as YAML and the whole of it should replay in one call with a
+per-step verdict; reach for the individual gesture tools when nothing is authored yet, and for
+run-sequence when the steps are an ad-hoc list rather than a stored flow.
 Steps run in order: \`launch\` starts an app from scratch (terminate + relaunch) and waits until it is
 ready (on iOS it also pins later element lookups to that app rather than auto-detecting the frontmost
 one); \`tool\` calls dispatch through the registry (a raw \`tool\` step ends that iOS pin, so lookups
@@ -147458,6 +148033,11 @@ order), \`next: <selector>\` (CSS \`+\` \u2014 the nearest such follower, which
 non-matching neighbour rather than failing), plus \`any: true\` (CSS \`*\` \u2014 legal only WITH a scope and
 never beside text/id/role). Scopes nest to disambiguate \u2014 \`within: { id: card, within: { id: list } }\`
 reads "inside card inside list", each container's frame inside the next);
+\`swipe\` performs one finger flick (\`swipe: left\`, or \`swipe: { from?, direction|to|by, momentum?, duration? }\` \u2014
+direction is the FINGER's travel, the opposite sense of scroll-to's content direction; \`by: { x?, y? }\` \u2014 signed
+0\u20131 screen fractions, combined length at least 0.03 (a diagonal clears it where neither axis does); duration in ms,
+default 300, minimum 150, maximum 10000; each bound is a parse error that rejects the file before any step runs;
+\`momentum: false\` lands exactly where the finger lifts instead of flinging);
 \`scroll-to\` scrolls (momentum-free) until a target is visible; \`pinch\` zooms
 (\`pinch: { on?, scale }\` \u2014 scale > 1 in, < 1 out; screen center when \`on\` is omitted); \`rotate\` is the
 two-finger rotation gesture (\`rotate: { on?, by }\` \u2014 degrees, + clockwise, within \xB13000\xB0; screen center
@@ -147474,7 +148054,7 @@ baseline (a missing baseline fails the step \u2014 set updateBaselines to adopt
 cropped element whose size drifted fails on dimensions); \`echo\` annotates; \`run\` executes another flow
 inline \u2014 a YAML path resolved against the directory of the flow file that references it (co-located
 runs only).
-A selector-less gesture \u2014 a coordinate \`tap\`/\`long-press\`, or a \`pinch\`/\`rotate\` with no \`on\` \u2014 resolves
+A selector-less gesture \u2014 a coordinate \`tap\`/\`long-press\`/\`swipe\`, or a \`pinch\`/\`rotate\` with no \`on\` \u2014 resolves
 no frame out of the tree, so an unreadable tree source does NOT stop it the way it stops \`idle\`: it
 settles best-effort, dispatches anyway, and the step PASSES carrying a \`warning\` that quotes the source's
 own error. That green says the gesture was SENT, not that it landed. Restore the tree source (usually
@@ -147522,6 +148102,15 @@ Pass exactly one flow source: name for a saved flow under project_root, or flow_
       const flowsDir = path36.dirname(canonicalPath);
       const flow = parseFlow(await fs51.readFile(canonicalPath, "utf8"));
       if (viaUpload) assertUploadSelfContained(flow);
+      const retiredArg = findRetiredToolArg(registry2, flow.steps);
+      if (retiredArg) {
+        throw new FailureError(`Flow "${flowName}" ${retiredArgReason(retiredArg)}`, {
+          error_code: FAILURE_CODES.FLOW_FILE_INVALID,
+          failure_stage: "flow_run_validate",
+          failure_area: "tool_server",
+          error_kind: "validation"
+        });
+      }
       const rootEntry = { canonical: canonicalPath, display: flowName };
       if (flow.executionPrerequisite && !pinnedToChromium(params.device)) {
         const leading = await leadingLaunch(flow, [rootEntry]);
@@ -147792,6 +148381,9 @@ function conditionLabel(cond, renderSelector) {
   }
   return `${cond.condition} ${sel}`;
 }
+function gestureTargetLabel(target) {
+  return "selector" in target ? selectorLabel2(target.selector) : `(${target.x}, ${target.y})`;
+}
 function stepTarget(step) {
   switch (step.kind) {
     case "tap":
@@ -147799,6 +148391,19 @@ function stepTarget(step) {
       if (step.selector) return selectorLabel2(step.selector);
       if (step.x !== void 0 && step.y !== void 0) return `(${step.x}, ${step.y})`;
       return void 0;
+    case "swipe": {
+      let travel;
+      if (step.direction !== void 0) {
+        travel = step.direction;
+      } else if (step.by !== void 0) {
+        travel = `by ${swipeByLabel(step.by)}`;
+      } else if (step.to !== void 0) {
+        travel = `to ${gestureTargetLabel(step.to)}`;
+      } else {
+        return void 0;
+      }
+      return `${travel}${step.from ? ` from ${gestureTargetLabel(step.from)}` : ""}`;
+    }
     case "type":
       return `into ${selectorLabel2(step.into)}`;
     case "await":
@@ -148061,6 +148666,8 @@ async function execRunStep(state3, step, scope) {
   } catch (err) {
     return fail(`could not load fragment "${target}": ${errMsg3(err)}`);
   }
+  const retiredArg = findRetiredToolArg(state3.registry, fragment.steps);
+  if (retiredArg) return fail(`fragment "${target}" ${retiredArgReason(retiredArg)}`);
   pushReport(state3, {
     index,
     kind: "run",
@@ -148094,6 +148701,7 @@ async function execLeafStep(state3, step, index, scope) {
     }
     case "tap":
     case "long-press":
+    case "swipe":
     case "type":
     case "await":
     case "assert":
@@ -148221,6 +148829,9 @@ async function execLeafStep(state3, step, index, scope) {
         }
         return { ...base, status: "pass", tool: step.name, result, outputHint, args };
       } catch (err) {
+        if (signal?.aborted) {
+          return { ...base, status: "skip", tool: step.name, reason: ABORTED_OUTCOME.reason };
+        }
         const reframed = describeNestedParamError(registry2, err, step.name, args, step.args ?? {});
         return { ...base, status: "error", tool: step.name, reason: reframed ?? errMsg3(err) };
       }
@@ -148400,10 +149011,13 @@ var flowReadPrerequisiteTool = {
     failedMsg: ({ failureSignal: failureSignal2 }) => `Failed to read flow prerequisite: ${failureSignal2.error_code}`
   },
   description: `Read the execution prerequisite of a flow without running it \u2014 a saved flow from the .argent/flows/ directory, or an explicit boundary-managed flow_path.
-Returns the prerequisite description so you can verify the required state is met before calling flow-execute.
-Use when you need to check what app/simulator state is required before executing a flow; pass the same flow
-source (name or flow_path) you will pass to flow-execute, so the prerequisite you read is the contract of
-the flow that will actually run.
+Returns { flow, executionPrerequisite }: the logical name, plus the precondition its author recorded
+verbatim. Empty when none was declared, which is always so for a self-contained scenario: one opening
+on a launch may declare no prerequisite, because it builds its own start state.
+Use when deciding whether the device already sits where a fragment expects it (correct app foregrounded,
+correct account, correct screen) before committing to a run, or when relaying that requirement to a human.
+Touches no device: nothing is launched, tapped, dispatched or torn down, and no simulator or emulator
+needs booting, so calling this costs nothing but a file read.
 Fails if the flow file does not exist.
 Address the flow exactly as you will address it in flow-execute: name or flow_path, one and only one; supplying both or neither is rejected. The name goes in \`name\`, which resolves <project_root>/.argent/flows/<name>.yaml.`,
   zodSchema: zodSchema66,
@@ -148911,7 +149525,7 @@ var updateArgentTool = {
       });
       child.unref();
     }, 2e3);
-    const targetLabel = effectiveTarget === "both" ? "global and project-local installs" : `${effectiveTarget} install`;
+    const targetLabel2 = effectiveTarget === "both" ? "global and project-local installs" : `${effectiveTarget} install`;
     const otherHint = requested === "auto" && resolved !== "both" ? resolved === "local" ? ` If you also have a global install, call this tool again with target "global" to update it too.` : ` If you also have a project-local install, run \`argent update --local\` in that project to update it too.` : "";
     const bothDegradedNote = resolved === "both" && effectiveTarget === "global" ? ` The project-local install was skipped: no project declaring ${PACKAGE_NAME2} could be located from this server \u2014 run \`argent update --local\` in the project directory for it.` : "";
     const versionInfo = targetsOnlyRunningInstall ? `(v${currentVersion} -> v${installableVersion}) ` : "";
@@ -148919,7 +149533,7 @@ var updateArgentTool = {
     const coversRunningInstall = targetsOnlyRunningInstall || effectiveTarget === "both";
     const restartNote = coversRunningInstall ? ` The tool server will stop and restart automatically once the update is installed. Subsequent tool calls will reconnect to the updated server.` : ` This session's tool server is not affected and keeps running; the update applies only to the targeted install.`;
     return {
-      message: `Argent update initiated ${versionInfo}for the ${targetLabel}.` + crossTargetNote + restartNote + `${otherHint}${bothDegradedNote}`
+      message: `Argent update initiated ${versionInfo}for the ${targetLabel2}.` + crossTargetNote + restartNote + `${otherHint}${bothDegradedNote}`
     };
   }
 };