Skip to content

Latest commit

 

History

History
52 lines (43 loc) · 3.28 KB

swipe.md

File metadata and controls

52 lines (43 loc) · 3.28 KB
summary read_when
Perform gesture-style drags via peekaboo swipe
animating trackpad-like swipes between coordinates or elements
needing smooth, timed drags for carousels/cover flow UI

peekaboo swipe

swipe drives AutomationServiceBridge.swipe to move from one point to another over a fixed duration. You can describe the endpoints via element IDs (from see) or raw coordinates, which makes it flexible for both deterministic automation and exploratory scripts.

Key options

Flag Description
--from <id> / --from-coords x,y Source location (ID requires a valid snapshot).
--to <id> / --to-coords x,y Destination location (also supports IDs or literal coordinates).
--snapshot <id> Needed whenever you reference IDs so the command can look up bounds. Auto-resolves to the most recent snapshot if omitted.
Target flags --app <name>, --pid <pid>, --window-id <id>, --window-title <title>, --window-index <n> — focus a specific app/window before swiping. (--window-title/--window-index require --app or --pid; --window-id does not.)
Focus flags FocusCommandOptions control Space switching + retries.
--duration <ms> Default 500 ms; controls how long the swipe lasts.
--steps <count> Number of intermediate points for smoothing (default 20).
--right-button Currently rejected — the implementation throws a validation error because right-button drags are not yet wired up.
--profile <linear|human> Use human for gesture traces that look like real pointer motion.

Implementation notes

  • The command validates that both ends are provided (mixing IDs and coordinates is fine) before doing any work.
  • Element lookups reuse the [waitForElement + bounds.midpoint] flow with a 5 s timeout, so swipes tolerate elements that pop in slightly late.
  • Coordinate parsing accepts "x,y" with optional whitespace; invalid strings result in immediate validation errors.
  • After issuing the swipe it waits ~0.1 s before reporting success to give AppKit time to settle (matching what integration tests expect).
  • JSON output surfaces both endpoints and the computed Euclidean distance, which is handy when you need to assert coverage in tests.
  • --profile human enables adaptive durations/steps plus jittery arcs; see docs/human-mouse-move.md for the generator’s behavior.

Examples

# Swipe between two element IDs captured by `see`
polter peekaboo -- swipe --from card_1 --to card_2 --duration 650 --steps 30

# Drag from coordinates (x1,y1) to (x2,y2)
polter peekaboo -- swipe --from-coords 120,880 --to-coords 120,200

# Human-style swipe with adaptive easing
polter peekaboo -- swipe --from-coords 80,640 --to-coords 820,320 --profile human

# Mix coordinate → element drag using the most recent snapshot
polter peekaboo -- swipe --from-coords 400,400 --to drawer_toggle

Troubleshooting

  • Verify Screen Recording + Accessibility permissions (peekaboo permissions status).
  • Confirm your target (app/window/selector) with peekaboo list/peekaboo see before rerunning.
  • If you see SNAPSHOT_NOT_FOUND, regenerate the snapshot with peekaboo see (or omit --snapshot to use the most recent one).
  • Re-run with --json-output or --verbose to surface detailed errors.