voyage-bulk-autoimporter/README.md

# voyage-bulk-autoimporter

Bulk-import your Path of Exile **Charts** into the
[Allflame Voyage Solver](https://one-more-map.github.io/allflame-voyage-solver/)
— on Linux / Wayland.

The solver ships `voyage-import.ahk`, an AutoHotkey bulk importer that only runs
on Windows. This is the Linux counterpart: it sweeps the in-game chart grid,
copies every chart with `Ctrl+C`, and hands the whole batch to the solver page
in the browser — no manual pasting, no per-item clicking.

Tested on KDE Plasma 6 / Wayland with PoE running through Proton.

## What you get

```
  PoE chart grid                 clipboard bridge              browser
  ┌──────────────┐   Ctrl+C     ┌────────────────┐   HTTP     ┌──────────────┐
  │ voyage-sweep │ ───────────► │ poe-clip-bridge│ ─────────► │  userscript  │
  │  hovers each │  per cell    │  127.0.0.1:8477│  polling   │ pastes into  │
  │     cell     │              │  (item filter) │            │  the solver  │
  └──────────────┘              └────────────────┘            └──────────────┘
```

Three independent pieces — each is useful on its own:

| Piece | What it does |
|---|---|
| `bin/poe-clip-bridge.py` | Watches the clipboard, keeps **only** PoE item text, serves it on loopback. Also starts a sweep on request, so a browser bookmark can trigger it. |
| `userscript/allflame-autopaste.user.js` | Polls the bridge and feeds copied items into the solver — works even while the browser is unfocused on another monitor. |
| `bin/voyage-sweep.py` | Sweeps the whole chart grid and produces one batch. |

Copy a single chart in game and it appears in the solver by itself. Or trigger a
sweep and get all of them at once.

## Requirements

- KDE Plasma 6 on Wayland (uses KWin's scripting API for one pointer read)
- `wl-clipboard`, `ydotool` (+ `ydotoold`), `xdotool`, `kdotool`, `qdbus6`, Python 3
- Firefox with [Violentmonkey](https://violentmonkey.github.io/) (or Tampermonkey)
- PoE in **Windowed** or **Windowed Fullscreen** mode

On Arch:

```bash
sudo pacman -S wl-clipboard ydotool xdotool python
paru -S kdotool          # AUR
```

`ydotool` injects input through `/dev/uinput`. Add yourself to the `input` group
(or whatever group owns `/dev/uinput` on your distro) so it works without root:

```bash
sudo usermod -aG input "$USER"   # log out and back in
systemctl --user enable --now ydotool.service
```

## Install

```bash
git clone https://git.opennerds.org/templis/voyage-bulk-autoimporter.git
cd voyage-bulk-autoimporter
./install.sh
```

`install.sh` copies the two scripts to `~/.local/bin`, installs the systemd user
unit and starts the bridge. Then install the userscript: open
`userscript/allflame-autopaste.user.js` in Firefox — Violentmonkey offers to
install it. If Firefox will not open `file://` URLs, paste the file contents
into a new Violentmonkey script instead.

## Calibrate the grid

The sweep needs to know where the chart grid is. Coordinates are stored
**relative to the PoE window**, so moving the window does not invalidate them.

1. Open the Voyage panel in game (the chart grid must be visible).
2. Run:

   ```bash
   voyage-sweep.py calibrate --cols 6 --rows 10
   ```

3. Put the mouse on the **centre of the top-left cell** — a 5 second countdown
   captures it. Then the **centre of the bottom-right cell**, even if it is empty.

Adjust `--cols/--rows` to your panel. The result lands in
`~/.config/voyage-sweep.json`:

```json
{
  "cols": 6,
  "rows": 10,
  "tl": [1759, 427],
  "br": [2093, 1026],
  "hover_delay": 0.14,
  "clip_timeout": 0.6,
  "poe_window": "Path of Exile"
}
```

If cells get missed, raise `hover_delay` (tooltip needs longer to appear) or
`clip_timeout`.

## Use it

Terminal:

```bash
voyage-sweep.py run            # whole grid
voyage-sweep.py run --rows 2   # only the first 2 rows, for testing
```

Or from the browser — get your personal trigger URL:

```bash
voyage-bookmarklet.sh
```

It prints a ready-made bookmarklet. Add it via the bookmark manager
(`Ctrl+Shift+O` → new bookmark, paste into the URL field). Clicking it starts a
sweep without leaving the solver page.

**Do not** open the raw trigger URL and then bookmark the open tab — visiting it
already starts a sweep.

Then: solver page open, Voyage panel open in game, click the bookmarklet. After
a 4 second countdown PoE is raised, the grid is swept (~90 s for 60 cells) and
the batch is imported automatically.

Hands off mouse and keyboard while it runs, and leave the Voyage panel open —
closing it mid-sweep produces garbage.

## Security

A clipboard watcher sees everything you copy, including passwords from your
password manager. This one is built so that never leaves the process:

- Clipboard content that does not match `^(Item Class|Rarity):` or
  `=== VOYAGE BORDER` is **discarded immediately** — not stored, not served.
- Item text is kept in memory only. Nothing is written to disk.
- The HTTP server binds to `127.0.0.1` exclusively.
- Endpoints that *act* (`/sweep`, `/pause`, `/resume`) require a random token
  from `~/.config/poe-clip-bridge/token` (mode `0600`, generated on first start).
  Without it any web page could fire `<img src="http://127.0.0.1:8477/sweep">`
  and take over your mouse and keyboard.
- If you sync bookmarks: the bookmarklet contains that token. Either keep it out
  of sync or use the terminal command.

`ydotoold` can inject input into any window while it runs. That is inherent to
this kind of tool — start it on demand instead of enabling it permanently if you
would rather not have it around all the time.

## Troubleshooting

**"skipped N uncharted (run them first to reveal their modifier)"** — not a bug.
The solver rejects charts whose Voyage modifier is still hidden. Chart them with
Valerie aboard the Sovereign first.

**"Every cell copied the SAME chart"** — calibration is off or the Voyage panel
was closed during the sweep. Re-calibrate and try again.

**"ydotoold is not running"** — `systemctl --user start ydotool.service`.

**Pointer lands next to the cells** — the pointer control loop learns how much
your display multiplies injected motion (2.0× on some setups). Give it room by
raising `hover_delay`, and make sure the PoE window is not scaled differently
from when you calibrated.

**Nothing appears in the browser** — check the bridge:

```bash
systemctl --user status poe-clip-bridge.service
curl -s http://127.0.0.1:8477/clip
```

`docs/wayland-pointer-notes.md` documents the pointer pitfalls behind these
workarounds — useful for anyone automating input on Wayland.

## Credits

- [Allflame Voyage Solver](https://one-more-map.github.io/allflame-voyage-solver/)
  by one-more-map, including the original Windows `voyage-import.ahk` this
  mirrors.

## License

MIT — see [LICENSE](LICENSE).