@swmansion/argent 0.16.2-next.3 → 0.16.2-next.5

package/dist/tool-server.cjs

@@ -126717,6 +126717,12 @@ var zodSchema21 = external_exports.object({
   endDistance: external_exports.number().describe(
     "Final distance between the two fingers: normalized 0.0\u20131.0 (fraction of screen, not pixels). E.g. 0.6 = fingers 60% of screen apart. Use a larger endDistance than startDistance to pinch out (zoom in)."
   ),
+  endCenterX: external_exports.number().optional().describe(
+    "Final horizontal center of the pinch: normalized 0.0\u20131.0. When set, the centroid drifts linearly from centerX to endCenterX over the gesture (e.g. to keep expanding fingers on-screen near an edge). Omit for a fixed center."
+  ),
+  endCenterY: external_exports.number().optional().describe(
+    "Final vertical center of the pinch: normalized 0.0\u20131.0. When set, the centroid drifts linearly from centerY to endCenterY over the gesture. Omit for a fixed center."
+  ),
   angle: external_exports.number().optional().describe("Axis angle in degrees along which the fingers are placed (default 0 = horizontal)."),
   durationMs: external_exports.number().optional().describe("Total gesture duration in milliseconds (default 300)")
 });
@@ -126730,7 +126736,7 @@ var gesturePinchTool = {
   description: `Execute a pinch-to-zoom gesture by moving two fingers toward or away from a center point to change the scale of on-screen content. All positions and distances are normalized 0.0\u20131.0 (fractions of screen width/height, not pixels)\u2014same coordinate space as gesture-tap and gesture-swipe.
 startDistance > endDistance = pinch in (zoom out). startDistance < endDistance = pinch out (zoom in).
 Typical values: startDistance 0.2, endDistance 0.6 for a zoom-in pinch at screen center.
-Auto-generates interpolated frames at ~60fps. The angle parameter controls the axis (0 = horizontal, 90 = vertical).
+Auto-generates interpolated frames at ~60fps. The angle parameter controls the axis (0 = horizontal, 90 = vertical). Optional endCenterX/endCenterY drift the centroid linearly over the gesture (omitted = fixed center).
 Use when you need to zoom in or out on a map, image, or zoomable view. Returns { pinched: true, timestampMs }. Fails if the simulator-server / emulator backend is not reachable for the given device.`,
   zodSchema: zodSchema21,
   capability: capability13,
@@ -126745,15 +126751,19 @@ Use when you need to zoom in or out on a map, image, or zoomable view. Returns {
     const angleRad = angleDeg * Math.PI / 180;
     const cosA = Math.cos(angleRad);
     const sinA = Math.sin(angleRad);
+    const endCenterX = params.endCenterX ?? params.centerX;
+    const endCenterY = params.endCenterY ?? params.centerY;
     let timestampMs = 0;
     for (let i = 0; i <= steps; i++) {
       const t = i / steps;
       const dist = params.startDistance + (params.endDistance - params.startDistance) * t;
       const halfDist = dist / 2;
-      const x1 = params.centerX - halfDist * cosA;
-      const y1 = params.centerY - halfDist * sinA;
-      const x2 = params.centerX + halfDist * cosA;
-      const y2 = params.centerY + halfDist * sinA;
+      const cx = params.centerX + (endCenterX - params.centerX) * t;
+      const cy = params.centerY + (endCenterY - params.centerY) * t;
+      const x1 = cx - halfDist * cosA;
+      const y1 = cy - halfDist * sinA;
+      const x2 = cx + halfDist * cosA;
+      const y2 = cy + halfDist * sinA;
       const type = i === 0 ? "Down" : i === steps ? "Up" : "Move";
       if (i === 0) timestampMs = Date.now();
       sendTouchEvent(api, type, x1, y1, x2, y2);
@@ -133889,8 +133899,8 @@ Allowed tools and their args (udid is auto-injected, do NOT include it in args):
   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-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, angle?: number, durationMs?: number }              [ios only]
-  gesture-rotate: { centerX: number, centerY: number, radius: number, startAngle: number, endAngle: number, durationMs?: number }                    [ios only]
+  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, startAngle: number, endAngle: number, durationMs?: number }                    [ios/android]
   button:         { button: "home"|"back"|"power"|"volumeUp"|"volumeDown"|"appSwitch"|"actionButton" }                  [ios/android]
   keyboard:       { text?: string, key?: string, delayMs?: number }  (key pressed after text; TV: text only)            [ios/android/chromium/vega/tv]
                   text supports {{secret:<NAME>}} placeholders, resolved server-side from ARGENT_SECRET_<NAME> env vars (prefix mandatory) \u2014 credentials never enter agent context
@@ -145031,6 +145041,10 @@ function toYamlStep(step) {
         }
       };
     }
+    case "pinch":
+      return {
+        pinch: step.selector ? { on: selectorToYaml(step.selector), scale: step.scale } : { scale: step.scale }
+      };
     case "snapshot":
       return step.maxMismatch === void 0 ? { snapshot: step.name } : { snapshot: { name: step.name, maxMismatch: step.maxMismatch } };
     case "tool":
@@ -145303,6 +145317,7 @@ var STEP_DIRECTIVE_KEYS = [
   "assert",
   "wait",
   "scroll-to",
+  "pinch",
   "snapshot"
 ];
 function parseTapTimes(raw, entry) {
@@ -145399,6 +145414,28 @@ function parseLongPress(body, entry) {
   }
   return { kind: "long-press", ...parseTarget(body, "long-press") };
 }
+function parsePinch(body, entry) {
+  if (body === null || typeof body !== "object") {
+    badEntry(
+      entry,
+      'pinch takes an options map \u2014 e.g. pinch: { on: "Map", scale: 3 } (a bare "pinch: Map" is ambiguous: in or out?)'
+    );
+  }
+  const obj = body;
+  if (obj.text !== void 0 || obj.id !== void 0 || obj.identifier !== void 0 || obj.role !== void 0) {
+    badEntry(entry, 'pinch takes a nested selector \u2014 e.g. pinch: { on: "Map", scale: 3 }');
+  }
+  rejectUnknownKeys(entry, obj, ["on", "scale"], "pinch");
+  if (typeof obj.scale !== "number" || !Number.isFinite(obj.scale) || obj.scale <= 0 || obj.scale === 1) {
+    badEntry(
+      entry,
+      "pinch.scale must be a finite number > 0 and \u2260 1 (2 = zoom in 2\xD7, 0.5 = zoom out to half)"
+    );
+  }
+  const step = { kind: "pinch", scale: obj.scale };
+  if (obj.on !== void 0) step.selector = parseSelector(obj.on, "pinch.on");
+  return step;
+}
 function parseWhenCondition(raw) {
   const conditionKeys = `${WAIT_CONDITIONS.join(", ")}, platform`;
   if (raw === null || typeof raw !== "object") {
@@ -145566,6 +145603,7 @@ function fromYamlStep(raw, whenDepth = 0) {
     if (b.within !== void 0) step.within = parseSelector(b.within, "scroll-to.within");
     return step;
   }
+  if ("pinch" in raw) return parsePinch(raw.pinch, raw);
   if ("snapshot" in raw) {
     const body = raw.snapshot;
     if (body !== null && typeof body === "object" && !Array.isArray(body)) {
@@ -146462,6 +146500,8 @@ You can still edit the .yaml file directly afterwards to remove or reorder steps
         }
         case "scroll-to":
           return `${n}. scroll-to: ${selectorLabel(step.target)} (${step.direction})`;
+        case "pinch":
+          return `${n}. pinch: scale ${step.scale}${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
         case "snapshot":
           return `${n}. snapshot: ${step.name}`;
         case "tool":
@@ -146488,6 +146528,73 @@ var fs41 = __toESM(require("node:fs/promises"));
 var path31 = __toESM(require("node:path"));
 init_src();
 
+// ../tool-server/src/tools/flows/flow-pinch-geometry.ts
+var PINCH_RATIO_PER_GESTURE = 4;
+var PINCH_SETTLE_MS = 250;
+var TARGET_START_FRACTION = 0.82;
+var SCREEN_EDGE_INSET = 0.02;
+var MIN_VIABLE_TRAVEL = 0.03;
+function systemEdgeGuards(device) {
+  return device.platform === "android" ? { left: 0.13, right: 0.13, top: 0.08, bottom: 0.08 } : { left: 0.08, right: 0.08, top: 0.08, bottom: 0.08 };
+}
+function decomposePinch(scale) {
+  const n = Math.max(
+    1,
+    Math.ceil(Math.abs(Math.log(scale)) / Math.log(PINCH_RATIO_PER_GESTURE) - 1e-9)
+  );
+  return { n, per: scale ** (1 / n) };
+}
+function clamp2(v, lo, hi) {
+  return v < lo ? lo : v > hi ? hi : v;
+}
+function buildAxisCandidate(input) {
+  const { angle, center, targetSpan, per, guards } = input;
+  const c = angle === 0 ? center.x : center.y;
+  const gLow = angle === 0 ? guards.left : guards.top;
+  const gHigh = angle === 0 ? guards.right : guards.bottom;
+  const p = angle === 0 ? center.y : center.x;
+  const pLow = angle === 0 ? guards.top : guards.left;
+  const pHigh = angle === 0 ? guards.bottom : guards.right;
+  const screenEndSpan = 1 - 2 * SCREEN_EDGE_INSET;
+  const edgeSafeStartSpan = 2 * Math.max(0, Math.min(c - gLow, 1 - gHigh - c));
+  const insetStartSpan = 2 * Math.max(0, Math.min(c - SCREEN_EDGE_INSET, 1 - SCREEN_EDGE_INSET - c));
+  const screenStartLimit = edgeSafeStartSpan > 0 ? Math.min(screenEndSpan, edgeSafeStartSpan) : Math.min(screenEndSpan, insetStartSpan);
+  const startLimit = targetSpan !== void 0 ? Math.min(screenStartLimit, targetSpan * TARGET_START_FRACTION) : screenStartLimit;
+  const start2 = per > 1 ? Math.min(startLimit, screenEndSpan / per) : startLimit;
+  const end = Math.min(screenEndSpan, start2 * per);
+  const travel = Math.abs(end - start2);
+  if (!(travel > 0)) return void 0;
+  const endCenter = clamp2(c, SCREEN_EDGE_INSET + end / 2, 1 - SCREEN_EDGE_INSET - end / 2);
+  const downLow = c - start2 / 2;
+  const downHigh = c + start2 / 2;
+  const axisSafe = downLow >= gLow && downHigh <= 1 - gHigh;
+  const perpSafe = p >= pLow && p <= 1 - pHigh;
+  const clearance = Math.min(downLow - gLow, 1 - gHigh - downHigh, p - pLow, 1 - pHigh - p);
+  return {
+    angle,
+    start: start2,
+    end,
+    endCenter,
+    travel,
+    viable: travel >= MIN_VIABLE_TRAVEL,
+    axisSafe,
+    fullyEdgeSafe: axisSafe && perpSafe,
+    clearance
+  };
+}
+function selectPinchCandidate(candidates) {
+  if (candidates.length === 0) return void 0;
+  const rank2 = (c) => c.fullyEdgeSafe ? 0 : c.axisSafe ? 1 : 2;
+  return [...candidates].sort((a, b) => {
+    const byViable = Number(b.viable) - Number(a.viable);
+    if (byViable !== 0) return byViable;
+    const byRank = rank2(a) - rank2(b);
+    if (byRank !== 0) return byRank;
+    if (a.fullyEdgeSafe && b.fullyEdgeSafe) return b.travel - a.travel;
+    return b.clearance - a.clearance || b.travel - a.travel;
+  })[0];
+}
+
 // ../tool-server/src/tools/flows/flow-actions.ts
 var ABORTED_OUTCOME = {
   ok: false,
@@ -146701,12 +146808,18 @@ 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")) {
+  if (env.device.platform === "vega" && (step.kind === "tap" || step.kind === "long-press" || step.kind === "type" || step.kind === "scroll-to" || step.kind === "pinch")) {
     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`
     };
   }
+  if (step.kind === "pinch" && env.device.platform === "chromium") {
+    return {
+      ok: false,
+      reason: "pinch is unsupported on chromium \u2014 desktop apps have no uniform pinch-zoom mapping (they zoom via ctrl+wheel or their own controls); drive the app's zoom UI with tap/keyboard instead"
+    };
+  }
   switch (step.kind) {
     case "tap":
       return runTap(env, step);
@@ -146723,6 +146836,8 @@ async function runDirective(env, step) {
       if (r.aborted) return ABORTED_OUTCOME;
       return { ok: Boolean(r.frame), reason: r.reason };
     }
+    case "pinch":
+      return runPinch(env, step);
   }
 }
 async function resolveTargetPoint(env, target) {
@@ -146771,6 +146886,47 @@ async function runLongPress(env, step) {
   }
   return { ok: true };
 }
+async function runPinch(env, step) {
+  let center = { x: 0.5, y: 0.5 };
+  let frame;
+  if (step.selector) {
+    const resolved = await waitForFrame(env, step.selector);
+    if (resolved === "aborted") return ABORTED_OUTCOME;
+    if (!resolved) return { ok: false, reason: offscreenHint(step.selector) };
+    frame = resolved;
+    center = getDescribeTapPoint(resolved);
+  }
+  const { n, per } = decomposePinch(step.scale);
+  const guards = systemEdgeGuards(env.device);
+  const candidates = [
+    buildAxisCandidate({ angle: 0, center, targetSpan: frame?.width, per, guards }),
+    buildAxisCandidate({ angle: 90, center, targetSpan: frame?.height, per, guards })
+  ].filter((c) => c !== void 0);
+  const selected = selectPinchCandidate(candidates);
+  if (!selected) {
+    return {
+      ok: false,
+      reason: `pinch found no on-screen finger travel around (${center.x}, ${center.y})`
+    };
+  }
+  const args = {
+    centerX: center.x,
+    centerY: center.y,
+    startDistance: selected.start,
+    endDistance: selected.end,
+    angle: selected.angle
+  };
+  const startCenter = selected.angle === 0 ? center.x : center.y;
+  if (selected.endCenter !== startCenter) {
+    args[selected.angle === 0 ? "endCenterX" : "endCenterY"] = selected.endCenter;
+  }
+  for (let i = 0; i < n; i++) {
+    if (env.signal?.aborted) return ABORTED_OUTCOME;
+    await invokeOnDevice(env, "gesture-pinch", args);
+    if (i < n - 1 && !await sleepOrAbort(PINCH_SETTLE_MS, env.signal)) return ABORTED_OUTCOME;
+  }
+  return { ok: true };
+}
 async function runType(env, step) {
   const frame = await waitForFrame(env, step.into);
   if (frame === "aborted") return ABORTED_OUTCOME;
@@ -148394,7 +148550,7 @@ function formatSignedNumber(value) {
   return rounded > 0 ? `+${rounded}` : `${rounded}`;
 }
 function formatNormalizedPosition(value, divisor) {
-  return formatNormalizedNumber(clamp2(value / divisor, 0, 1));
+  return formatNormalizedNumber(clamp3(value / divisor, 0, 1));
 }
 function formatNormalizedNumber(value) {
   if (!Number.isFinite(value)) return "0";
@@ -148410,7 +148566,7 @@ function formatSignedNormalizedNumber(value) {
   const formatted = formatNormalizedNumber(value);
   return value > 0 && formatted !== "0" ? `+${formatted}` : formatted;
 }
-function clamp2(value, min, max) {
+function clamp3(value, min, max) {
   return Math.min(max, Math.max(min, value));
 }
 function formatPercentage(value) {
@@ -149230,8 +149386,9 @@ Steps run in order: \`launch\` starts an app from scratch (terminate + relaunch)
 ready; \`tool\` calls dispatch through the registry; \`tap\`/\`long-press\`/\`type\` resolve a selector to an
 element and act on it (\`tap: { on, times: 2 }\` double-taps; \`long-press: { on, duration }\` presses and
 holds; \`tap\`/\`long-press\` alternatively take a raw normalized point \u2014 bare \`{ x, y }\` or \`on: { x, y }\`);
-\`scroll-to\` scrolls (momentum-free) until a target is visible; \`await\` waits for a UI
-condition; \`wait\` pauses for a fixed number of milliseconds; \`assert\` checks one now; \`snapshot\`
+\`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); \`await\` waits
+for a UI condition; \`wait\` pauses for a fixed number of milliseconds; \`assert\` checks one now; \`snapshot\`
 diffs a screenshot against a stored baseline (a missing baseline fails the step \u2014 set updateBaselines
 to adopt the current screen); \`echo\` annotates; \`run\` executes a referenced fragment inline.
 A \`when:\` block (condition + \`steps:\`, no else) runs its steps only if the condition holds \u2014
@@ -149415,6 +149572,10 @@ function stepTarget(step) {
       const dir = step.direction !== "down" ? ` (${step.direction})` : "";
       return `${selectorLabel2(step.target)}${dir}`;
     }
+    case "pinch": {
+      const scale = `scale ${step.scale}`;
+      return step.selector ? `${selectorLabel2(step.selector)} (${scale})` : scale;
+    }
     case "snapshot":
       return `"${step.name}"`;
     default:
@@ -149596,7 +149757,8 @@ async function execLeafStep(state3, step, index, scope) {
     case "type":
     case "await":
     case "assert":
-    case "scroll-to": {
+    case "scroll-to":
+    case "pinch": {
       try {
         const r = await runDirective(state3, step);
         if (r.aborted) return { ...base, status: "skip", reason: r.reason };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.16.2-next.3",
+  "version": "0.16.2-next.5",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {

package/skills/argent-create-flow/SKILL.md

@@ -27,6 +27,7 @@ Beyond raw `tool:` steps and `echo:`, flows support declarative directives inter
 | `long-press` | `- long-press: Row 3`, `- long-press: { x: 0.5, y: 0.6 }`, `- long-press: { on: <sel>, duration: 1200 }`, `- long-press: { on: { x: 0.5, y: 0.6 }, duration: 1200 }` | press and hold an element or raw point (default 800ms; Chromium: mouse press-hold); `duration` needs the target nested under `on:` — a selector or a point      |
 | `type`       | `- type: { into: email, text: "a@b.com" }`                                                                                                                           | focus a field, type, then press Enter to submit + dismiss the keyboard                                                                                          |
 | `scroll-to`  | `- scroll-to: "Order #1234"` (scrolls down) or `- scroll-to: { target: …, direction: right, within: … }`                                                             | momentum-free scroll until the target is visible                                                                                                                |
+| `pinch`      | `- pinch: { on: "Map", scale: 3 }` or `- pinch: { scale: 0.5 }`                                                                                                      | two-finger zoom in (`scale` > 1) or out (`< 1`); big scales chain gestures; `on` optional — defaults to screen center; open-loop — assert the visible result    |
 | `await`      | `- await: { visible: Home }`                                                                                                                                         | wait for a UI condition                                                                                                                                         |
 | `wait`       | `- wait: 500`                                                                                                                                                        | pause for a fixed number of milliseconds (last resort — prefer `await`)                                                                                         |
 | `assert`     | `- assert: { visible: Welcome }`                                                                                                                                     | check a condition, hard-fail if it never holds                                                                                                                  |
@@ -67,7 +68,7 @@ Never record a real credential into a flow — the YAML is committed to the repo
 
 ### TV targets (Vega)
 
-A Vega (Fire TV) device is remote-driven — there is no touch input, so the touch directives (`tap`, `long-press`, `type`, `scroll-to`) fail on it with guidance. Drive focus with `tool: tv-remote` steps and type with `tool: keyboard` instead; everything else (`launch`, `await`, `assert`, `wait`, `snapshot`, `echo`, `run`, selectors) works unchanged — the tree comes from the on-device automation toolkit, which attaches at app launch (the `launch` step waits for it, so a leading `launch` also guarantees selectors resolve).
+A Vega (Fire TV) device is remote-driven — there is no touch input, so the touch directives (`tap`, `long-press`, `type`, `scroll-to`, `pinch`) fail on it with guidance. Drive focus with `tool: tv-remote` steps and type with `tool: keyboard` instead; everything else (`launch`, `await`, `assert`, `wait`, `snapshot`, `echo`, `run`, selectors) works unchanged — the tree comes from the on-device automation toolkit, which attaches at app launch (the `launch` step waits for it, so a leading `launch` also guarantees selectors resolve).
 
 ```yaml
 steps:
@@ -127,9 +128,10 @@ Record an `await-ui-element` step to **gate** the next step on a screen transiti
 5. **Polish**: **read the saved `.yaml` file** and convert the raw `tool:` steps that have a cleaner directive form (the recorder leaves these as tools):
    - `tool: keyboard` typing into a field → `type: { into: "<field>", text: "…" }`, folding in the `tap` that focused the field.
    - `tool: await-ui-element` gating a transition → `await: { visible: "…" }` / `{ hidden: … }` / `{ text: { in: …, equals: … } }`, carrying a custom `timeoutMs` over as a `timeout` sibling key. Converting also upgrades the wait from the trimmed `describe` tree to the flow's full-hierarchy tree (see Selectors). Keep the raw `tool: await-ui-element` step only when it sets a custom `pollIntervalMs`/`bundleId` the directive can't express.
-   - A scroll-to-reach-an-element — a `tool: gesture-swipe` used to bring a specific element on screen before interacting with it (a `tap`, `type`, `assert`, …) → `scroll-to: { target: "<that element>", direction: … }`, dropping the swipe. This is far more robust than a fixed-distance swipe: it scrolls momentum-free and stops exactly when the target appears, so it survives layout and content changes. (`tap`/`type` do not scroll, so a raw swipe whose fling lands differently on another device leaves the following tap unresolved — always prefer the `scroll-to` rewrite.) Keep a `gesture-swipe` as a raw `tool:` step when it isn't scrolling toward a specific element — especially a velocity-dependent gesture like swipe-to-dismiss, edge-swipe-back, or swipe-to-reveal a row action, which a momentum-free `scroll-to` would not reproduce.
+   - A scroll-to-reach-an-element — a `tool: gesture-swipe` (or its chromium analog, `gesture-scroll`) used to bring a specific element on screen before interacting with it (a `tap`, `type`, `assert`, …) → `scroll-to: { target: "<that element>", direction: … }`, dropping the swipe. This is far more robust than a fixed-distance swipe: it scrolls momentum-free and stops exactly when the target appears, so it survives layout and content changes. (`tap`/`type` do not scroll, so a raw swipe whose fling lands differently on another device leaves the following tap unresolved — always prefer the `scroll-to` rewrite.) Keep a `gesture-swipe` as a raw `tool:` step when it isn't scrolling toward a specific element — especially a velocity-dependent gesture like swipe-to-dismiss, edge-swipe-back, or swipe-to-reveal a row action, which a momentum-free `scroll-to` would not reproduce.
+   - `tool: gesture-pinch` → `pinch: { on: "<target>", scale: … }`, deriving `scale` as `endDistance / startDistance`. Set `on:` to the element under the pinch center when the pinch was aimed at one (the map or image being zoomed); omit it for a screen-center pinch. Don't carry the recorded distances/angle over — the directive re-derives the geometry (finger placement, system-edge avoidance, chaining of large scales) at run time, so the conversion swaps device-specific coordinates for a portable selector with auto-wait. Keep the raw `tool: gesture-pinch` step when the pinch is anchored at a specific point _inside_ a large element (zooming toward a particular map location, not the map's center) or deliberately pans via `endCenterX`/`endCenterY` — `on:` takes only a selector and re-centers the pinch on the element's frame center, so converting would silently move the zoom anchor.
 
-Every other recorded tool (`gesture-swipe`, `gesture-scroll`, `button`, `screenshot`, …) has no directive form — leave it as a `tool:` step. The recorder already handles the rest: coordinate `gesture-tap`s are captured as portable `tap:` selector steps, a `restart-app` is captured as a `launch:` step, a `flow-execute` of a sibling fragment is captured as a `run: <name>` composition directive, and device ids are stripped. Captured selectors are emitted in the strict map form (`tap: { text: General }`), never as a loose bare string — the recorder verified the exact element the tap hit, and a bare string would re-parse as loose and route through the identifier-first fallback it was never checked against. After editing, re-run with `flow-execute` to confirm the cleaned flow still passes.
+Every other recorded tool (a velocity-dependent `gesture-swipe`, a fixed-distance `gesture-scroll` not aimed at an element, `button`, `screenshot`, …) has no directive form — leave it as a `tool:` step. The recorder already handles the rest: coordinate `gesture-tap`s are captured as portable `tap:` selector steps, a `restart-app` is captured as a `launch:` step, a `flow-execute` of a sibling fragment is captured as a `run: <name>` composition directive, and device ids are stripped. Captured selectors are emitted in the strict map form (`tap: { text: General }`), never as a loose bare string — the recorder verified the exact element the tap hit, and a bare string would re-parse as loose and route through the identifier-first fallback it was never checked against. After editing, re-run with `flow-execute` to confirm the cleaned flow still passes.
 
 ### Example session
 

package/skills/argent-device-interact/SKILL.md

@@ -134,7 +134,7 @@ Swipe **up** (`fromY > toY`) = scroll content **down**. Default duration: 300ms.
 { "udid": "<UDID>", "centerX": 0.5, "centerY": 0.5, "startDistance": 0.2, "endDistance": 0.6 }
 ```
 
-All values are normalized 0.0–1.0 (fractions of screen, not pixels) — same as all other gesture tools. `startDistance: 0.2` means fingers start 20% of the screen apart; `endDistance: 0.6` means they end 60% apart. `startDistance < endDistance` = pinch out (zoom in). `startDistance > endDistance` = pinch in (zoom out). Defaults: `angle: 0` (horizontal), `durationMs: 300`. Optional: `"angle": 90` for vertical axis, `"durationMs": 500` for slower pinch.
+All values are normalized 0.0–1.0 (fractions of screen, not pixels) — same as all other gesture tools. `startDistance: 0.2` means fingers start 20% of the screen apart; `endDistance: 0.6` means they end 60% apart. `startDistance < endDistance` = pinch out (zoom in). `startDistance > endDistance` = pinch in (zoom out). Defaults: `angle: 0` (horizontal), `durationMs: 300`. Optional: `"angle": 90` for vertical axis, `"durationMs": 500` for slower pinch, `"endCenterX"`/`"endCenterY"` to let the centroid drift to a new center over the gesture (omitted = fixed center).
 
 ### gesture-rotate — Two-finger rotation