cthulhu-tentacles/wormhole/README.md

# Wormhole

An experimental Magic Wormhole Tentacle for Cthulhu. Suggested shortcut:
**Cthulhu+Ctrl+Shift+W**, on desktop and laptop layouts. It opens the reader's
internal **Wormhole menu**, preserving the underlying application's focus.

With a reader supporting Tentacle settings registration, global Preferences →
Tentacles → select Wormhole → Settings opens **Wormhole preferences** directly.
Save persists the two checkboxes and returns to reader preferences; Escape
discards the form's edits. This entry point works without the Wormhole CLI.
Use Wormhole 0.1.2 and rebuild the reader to obtain settings registration and the
Ctrl+Shift shortcut; the published 0.1.1 binary uses Alt+Shift and has no
registered settings entry point.

Install the `magic-wormhole` CLI using your distribution's package manager.
Clipboard operations require `xclip` on Xorg. Missing `wormhole` does not stop
reader startup: the shortcut speaks and brailles **Magic wormhole is not
installed**, with speech protected from ordinary interruption. Lock, shutdown,
disable and the reader's explicit stop policy still take precedence.

Use Up/Down and Enter in lists. Tab/Shift+Tab move through forms, Space toggles
checkboxes, and Escape closes the UI. Entries support editing, selection, Ctrl+C,
Ctrl+X and Ctrl+V. A transfer's Escape or Cancel transfer stops its process.
Changing native focus closes the UI and cancels the transfer. Only one transfer
runs at a time; keep the transfer UI open until it completes.

The menu offers:

- **Send focused item**: send one current text line, preserving spacing and
  replacing line breaks with spaces. Password fields are excluded. A reliably
  exposed local file URI/path is sent as one file or folder. File icons/list
  items/table rows without a path are rejected; a filename never silently
  becomes a text message. Flat review without an exact text range is unavailable.
- **Send from clipboard**: send text as a message, preserving its line breaks.
  A local file URI from a file manager sends the file or folder. Exactly one
  item is required; multiple files are rejected. Plain text that resembles a
  path remains a text message. If the clipboard supplies PNG data, create a
  private temporary `clipboard.png`, send it, and remove it after completion or
  cancellation. A missing file path without any file data cannot be reconstructed.
- **Receive**: type/paste a code in the internal Wormhole code entry, then press
  Enter. Files and folders are saved in `~/Downloads`, which is created if
  needed. Existing destinations are refused rather than overwritten. Text is
  read automatically when the transfer completes.
- **Preferences**: two independent checkboxes, both unchecked by default:
  **Save received text messages to clipboard** and **Copy send code to clipboard**.
  Checked means both speak and copy the respective text/code. Unchecked means
  speak it and preserve the clipboard. Save persists both choices in
  `$XDG_CONFIG_HOME/cthulhu-tentacles/wormhole.json` (normally `~/.config/...`).
  Escape discards changes.

Transfer controls offer **Read transfer status**, **Copy code**, and **Cancel
transfer**. Generated codes are automatically spoken and shown on braille, and
copied only when the preference is enabled. Copy code performs an explicit copy
regardless of that preference. There is no per-packet progress chatter. Errors
report failure, not success, and do not copy partial received messages.

File managers such as Thunar, PCManFM, Caja and Nautilus do not have a common
AT-SPI method that guarantees the selected file's full URI. The portable path
is to select one file/folder, press Ctrl+C, open the menu and choose **Send from
clipboard**. Direct selected-file sending without that copy remains unavailable
when the application does not expose an exact path. No path is guessed from a
window title, status bar, or filename.

Text transfers currently have an 8 KiB input limit; received text has an 8,000
byte limit so its complete announcement fits the reader's bounded output.
Oversized data is rejected, not silently truncated. Clipboard PNG data has a
32 MiB limit. Clipboard support currently uses Xorg; on Wayland a missing
clipboard service reports an unavailable item. The Wormhole CLI manages the
network protocol, directory archive and transport; the tentacle never executes
received text or launches a shell for transfers. Consult the
[Magic Wormhole documentation](https://magic-wormhole.readthedocs.io/en/latest/welcome.html).

## Build and local launch

Keep this repository beside the matching `cthulhu` checkout:

```sh
make build
make check
```

The binary is `wormhole/bin/wormhole-tentacle`. The current reader must support
`interaction` grants; an older presentation-only host will reject it.
Use a local launch entry with both grants:

```json
[
  {
    "ID": "wormhole",
    "Program": ["/home/angus/devel/cthulhu-tentacles/wormhole/bin/wormhole-tentacle"],
    "Presentation": true,
    "Interaction": true
  }
]
```

Development launches use `--tentacles /absolute/launch.json` and the existing
contained launcher. Alternatively, add a local entry to the reader's version-1
`tentacles.toml` beside its settings file (normally
`~/.local/share/cthulhu/tentacles.toml`), preserving existing entries:

```toml
[[tentacles]]
id = "wormhole"
program = ["/home/angus/devel/cthulhu-tentacles/wormhole/bin/wormhole-tentacle"]
enabled = true
presentation = true
interaction = true
```

The normal installation path is global Preferences → Tentacles → Add repository
with `https://git.stormux.org/storm/cthulhu-tentacles`, followed by selecting
Wormhole and Install and enable. Version 0.1.2 downloads use the normal
[`wormhole-v0.1.2` release attachments](https://git.stormux.org/storm/cthulhu-tentacles/releases/tag/wormhole-v0.1.2). The manifest
requests presentation and interaction permissions. Local metadata above is an
optional development path.
Prepare amd64/arm64 archives with
`python3 -B tools/package.py --tentacle wormhole`. Generated `dist/catalog.toml`
preserves other catalog entries. Nothing is published by that command.

## Live verification

After configuring the local entry:

1. Quit Cthulhu with Cthulhu+Q. Press Ctrl+Escape, then Shift+G. These are
   separate key presses. Shift+G rebuilds the reader and braille helper.
2. Focus an ordinary multiline text field. Open Cthulhu+Ctrl+Shift+W. Expect
   “Wormhole menu. Send focused item” in speech and the menu option on braille.
   Native application focus must stay on the original field. Send it to a
   second Wormhole endpoint; the recipient must get exactly the current line.
3. Open Preferences. Tab and Shift+Tab across both checkboxes and Save; Space
   toggles each. Enable Copy send code to clipboard and Save. Send text from
   the clipboard; expect the generated code spoken and shown on braille.
   The clipboard must contain that exact code. Cancel the transfer. Disable
   the preference and repeat; the original clipboard text must remain.
4. In a file manager, copy exactly one file with Ctrl+C. Choose Send from
   clipboard. Receive it at another endpoint and compare the contents.
   Repeat with one folder, then multiple selected files: multiple items must
   be refused. Sending a file icon without a usable path must give the copy
   instruction and must not send its filename as text.
5. Receive a file with the code entry. Test typing, cursor movement and Ctrl+V.
   After completion, expect “Wormhole transfer received in Downloads” and the
   actual file in Downloads. Repeat with an existing filename: expect failure
   and unchanged original contents. Test a folder too.
6. Receive text containing line breaks, quotes, backslashes and Unicode. With
   Save received text messages to clipboard off, expect the complete message
   spoken/shown and the previous clipboard preserved. Enable it and repeat:
   expect the exact original text in the clipboard. Restart and verify both
   checkbox choices persist.
7. Cancel a waiting transfer with Escape and with Cancel transfer. Ordinary
   typing must return to the original application, with no remaining modal
   key capture. Test focus change, reader quit, and tentacle disable during
   a waiting transfer. Check ordinary actions, learn mode, reading, and braille
   afterward.

Report the exact speech and braille, the focused control, the clipboard contents,
and any key that behaved differently. Unexpected results should be diagnosed
from `~/devel/cthulhu.log`. Automated and private Xorg checks do not establish
physical speech, keyboard or braille acceptance.