mirror of
https://github.com/storytold/wordcraft.git
synced 2026-11-01 06:16:58 -06:00
cbd9291909
* Add arcanii to the contributor names Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Caret: glide and fade like Word for Windows; File › Options › Animation turns it off The caret no longer jumps and switches on and off. A key or typing glides it to its new place in 100 ms along cubic-bezier(0, 0, 0, 1), the same for one character and for a whole line; a second key before it arrives makes it snap to where it was heading and set off from there. Clicks, and moves made by scripts or the control channel, don't glide. The blink is a pair of 100 ms fades (530 ms on, 530 ms off), and a key or a click turns the caret on from however visible it was. These are Word for Windows' numbers (16.0.20326, 100% zoom, 144 Hz), measured black-box: a synthetic document in a separate Word instance, its window captured frame by frame while key and mouse messages moved the caret. Fourteen consecutive frames match the curve to 0.003. Word for Mac was not measured. Nothing glides when the view changed (zoom, a resized window, scrolling, another document), when the caret wasn't drawn the frame before, or when a move starts or ends off screen. File › Options › Animation › "Animate the caret (it glides and fades)" turns it off: ui.caretAnimation {"value"} for agents, kept in ui.json, on by default, translated in the nine catalogs. Off, and whenever egui's animations are off (the headless harness, so ui_shot and scripted screenshots), the caret jumps and blinks exactly as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Brandon Thomas <echelon@gmail.com>
71 lines
5.1 KiB
Markdown
71 lines
5.1 KiB
Markdown
# Control protocol
|
||
|
||
Start the app with a control port: `wordcraft --control 7981` (or `WORDCRAFT_CONTROL_PORT=7981`).
|
||
It listens on `127.0.0.1` only. Send one JSON object per line, with the window's key (see
|
||
[Keys](#keys)); each gets one reply line:
|
||
|
||
```json
|
||
{"id": 1, "key": "…", "method": "engine.execute", "params": {"command": "text.insert", "params": {"text": "Hello"}}}
|
||
{"id": 1, "ok": true, "result": {"anchor": {...}, "focus": {...}}}
|
||
```
|
||
|
||
Errors come back as `{"id": …, "ok": false, "error": "message"}`. A failed command leaves the
|
||
document unchanged. A line that isn't valid JSON gets one error reply, then the server closes the
|
||
connection (so an HTTP request sent to the port can't run a command); reconnect to continue.
|
||
|
||
## Keys
|
||
|
||
Any local program (and possibly a web page) can reach a loopback port, so every request needs the
|
||
window's key. Once the port is bound, the app writes a random key (256 bits, as hex) to
|
||
`<settings>/control-key.<instance>` and removes the file when the window closes; a new start
|
||
writes a new key. `<settings>` is the folder that holds the preferences: on Linux
|
||
`$XDG_CONFIG_HOME/wordcraft` (by default `~/.config/wordcraft`), on macOS
|
||
`~/Library/Application Support/WordCraft`, on Windows `%APPDATA%\WordCraft`. `<instance>` is the
|
||
Flatpak instance id inside Flatpak, and `local-<port>` otherwise. On Unix the file has mode 0600.
|
||
|
||
```sh
|
||
cat ~/.config/wordcraft/control-key.local-7981 # Linux, outside Flatpak, port 7981
|
||
```
|
||
|
||
- Send the key as top-level `"key"` with every request, or once per connection with
|
||
`{"method": "auth", "key": "…"}` (reply `{"ok": true, "result": {}}`); later requests on that
|
||
connection may leave `key` out. Only `auth` reads `params.key`; for other methods `params.key`
|
||
is an ordinary parameter (`ui.key {"key": "Enter"}` presses Enter).
|
||
- The key is checked on every request. A missing or wrong key gets
|
||
`{"ok": false, "error": "unauthorized"}`, and the app closes the connection.
|
||
- A line over 1 MiB gets `{"ok": false, "error": "line too long"}`, and the app closes the
|
||
connection.
|
||
- A connection that sends no authorised request within 30 s of being accepted is closed. That is
|
||
one limit: blank lines and bad JSON do not extend it. After an authorised request the
|
||
connection may stay idle.
|
||
|
||
`wordcraft-cli mcp --connect` takes the key from `WORDCRAFT_CONTROL_KEY`, or else from the key
|
||
file for the port it connects to, and reads it again on every new connection (the app may have
|
||
restarted). It sends the key only to loopback addresses (`127.0.0.0/8`, `::1`, `localhost`). For
|
||
any other host it sends no key, says so, and the app refuses its requests: to drive an app on
|
||
another machine, forward its port to `127.0.0.1` (for example `ssh -L 7981:127.0.0.1:7981 host`)
|
||
and set `WORDCRAFT_CONTROL_KEY` to that app's key.
|
||
|
||
## Methods
|
||
|
||
| Method | Params | Result |
|
||
|---|---|---|
|
||
| `engine.execute` | `command`, `params` | the command's result (any id from `engine.commands`, including UI commands `ui.tab`, `ui.dialog`, `ui.backstage`, `ui.zotero.*` (see `docs/zotero.md`), `ui.language` (`{"value": "auto"|"en"|"zh-hans"|"zh-hant"|"ja"|"pt-br"|"es"|"uk"|"sr"|"sr-latn"|"et"|"tr"|"ru"}`), `ui.theme` (`{"value": "system"|"light"|"dark"}`; `system` follows the OS appearance, light when it reports none), `ui.interfaceSize` (`{"percent": 80–200}`, clamped; no value reads it; scales the interface on top of the system display scale, document zoom stays `view.zoom`), `ui.caretAnimation` (`{"value": true|false}`; no value reads it; off, the caret jumps and blinks on and off instead of gliding and fading)…) |
|
||
| `engine.commands` | — | every command: id, label, location, shortcut, params, enabled |
|
||
| `document.inspect` | `text?` | blocks (text, style, runs, lists, tables), parts, sections, selection, pages |
|
||
| `ui.inspect` | — | UI state, view, dialog, window size, page rects on screen, caret, comment balloons (`balloons`: id + screen rect; `balloon`: the selected one), perf |
|
||
| `ui.click` | `x`, `y`, `button?`, `count?`, `shift?`, `cmd?`, `alt?` | real pointer input at window coordinates |
|
||
| `ui.clickText` | `page` (0-based), `x`, `y` (points from the page's top-left), `count?` | click inside a page |
|
||
| `ui.move` / `ui.drag` | `x`,`y` / `x`,`y`,`toX`,`toY`,`steps?` | pointer move / drag |
|
||
| `ui.press` / `ui.release` | `x`,`y`, modifiers | primary button down / up there (with `ui.move` between: a drag you can screenshot halfway) |
|
||
| `ui.key` | `key` (`B`, `Enter`, `Left`…), `shift?`, `alt?`, `cmd?` | key press through egui (shortcuts apply) |
|
||
| `ui.text` | `text` | typed text through egui |
|
||
| `ui.screenshot` | `path?` | PNG of the window: written to `path`, or without one returned as base64 `png` in the reply |
|
||
| `ui.render` | `path?`, `page?` (1-based), `scale?` | PNG of a page, rendered by the engine: written to `path`, or without one returned as base64 `png` in the reply (never a fixed name in the shared temporary folder) |
|
||
| `ui.parity` | — | feature-catalog parity |
|
||
| `ui.resize` / `ui.focus` / `app.quit` | | window control |
|
||
|
||
Any other method name is treated as a command id: `{"method": "format.bold"}` works.
|
||
|
||
Positions are `{"story": "body" | {"part": n}, "path": [block, row, cell, block, …], "off": byteOffset}`.
|