autofirmer-expanded/clicker/README.md

Clicker

Moves the real desktop mouse and clicks an element you name with a CSS selector.

The extension can see the DOM but can't move the mouse; this script can move the mouse but can't see inside Chrome. They meet at the dashboard API:

clicker    --POST /api/autobuyer/locate------>  "where is button.buy?"
extension  --POST /api/autobuyer/locate/claim   takes the request
extension                                       raises the Chrome window, brings
                                                the tab to the front, scrolls the
                                                element to centre, measures it
extension  --POST /api/autobuyer/locate/result  desktop x,y
clicker    --GET  /api/autobuyer/locate?id=--->  reads the answer
clicker                                          moves the mouse, clicks

Setup

pip install -r requirements.txt

On macOS you must grant Accessibility permission to whatever runs the script (Terminal, iTerm, VS Code) — System Settings → Privacy & Security → Accessibility. Without it pyautogui moves nothing and fails silently.

Use

The AutoBuyer switch on the dashboard is the master arm: the script refuses to run while it's off.

# Measure only — no mouse movement. Start here.
python clicker.py locate "button.buy"

# Move the cursor to the target but don't press.
python clicker.py click "button.buy" --dry-run

# Actually click.
python clicker.py click "button.buy"

# Pin it to a specific tab, and pick the 3rd match.
python clicker.py click ".trade-btn" --index 2 --url "https://tradeify.co/*"

Flag	Meaning
--url	Chrome match pattern for the tab. Without it, the active tab is used.
--index	Which match, when the selector hits several (default 0).
--api	Dashboard URL (default http://localhost:3000).
--timeout	Seconds to wait for the extension (default 20).
--scale	CSS-to-desktop pixel ratio. Auto-detected; override if clicks land off.
--dry-run	Move the cursor, don't press.
--force	Click even when something is covering the element.
--robotic	Straight-line move and instant click, skipping the motion model.
--seed	Seed the motion RNG so a run replays identically (debugging).
--no-activate	Don't raise the browser first. The click may then be swallowed.

Window focus

A click on a window that isn't focused is consumed by the window manager activating that window — it never reaches the control underneath. That's why an automated click against a background Chrome appears to do nothing the first time and work the second: the first click only brought Chrome forward.

The extension calls chrome.windows.update({focused: true}), but that only orders windows within Chrome. If the frontmost application is your terminal — which it is, since that's where you launched this — Chrome is still in the background.

So focus.py raises the browser application itself immediately before the press, then confirms it actually came forward before committing to the click. If it can't verify, it refuses rather than firing a click that would be eaten (exit code 3).

On macOS this uses NSWorkspace via pyobjc, which needs no Automation permission — activating an app is not scripting it. Without pyobjc it falls back to osascript, which does prompt for Automation permission the first time.

Cursor motion

humanize.py moves the pointer the way a hand does rather than teleporting:

• a curved (cubic Bézier) path instead of a straight line, bowing to one side
• eased velocity — accelerate out, coast, decelerate in
• sub-pixel tremor that decays near the target, so the landing stays exact
• long throws (>260px) sometimes overshoot slightly and pull back
• a 60–170ms dwell after arriving, before the press
• the button held down 55–120ms rather than an instant down/up

This is about reliability as much as appearance. Plenty of web controls only arm once they have actually been hovered — dropdowns, tooltip-gated buttons, custom widgets — and a cursor that arrives and presses in the same tick can outrun the page's own mousemove handlers. The dwell is what lets those catch up.

Note pyautogui.PAUSE is set to 0 on import: it otherwise sleeps 0.1s after every call, which would add tens of seconds across a stepped path.

Exit codes: 0 ok, 1 error, 2 capture switch off, 3 refused to click (covered element, or coordinates off-screen).

Safety

• Failsafe: slam the cursor into a screen corner to abort mid-run.
• Covered elements: before reporting, the extension checks document.elementFromPoint() at the target centre. If a cookie banner or modal is on top, the click is refused rather than sent into the overlay — --force overrides.
• Off-screen check: coordinates outside the display bounds are refused, which catches a Chrome window on a second monitor or partly off the edge.
• The element is scrolled to the centre of the viewport before measuring, so a target below the fold is handled rather than mis-clicked.

Known limits

• Latency is bounded by the extension's poll interval (default 3s), so a click takes a few seconds to fire. Drop the interval in the extension popup if that matters.
• Multi-monitor: coordinates come from window.screenX/screenY, which are relative to the primary display's origin. A Chrome window on a secondary monitor usually still works, but verify with locate before trusting click.
• Display scaling: the scale factor is inferred by comparing the screen width the OS reports against the one the browser reports. On macOS and unscaled Windows this is 1:1. If clicks land at a consistent offset, set --scale explicitly.
• The measurement and the click are separate moments. If the page moves the element in between (a re-render, a late-loading banner), the click lands where it was.