meow/README.md

# Meow

Meow is an accessible, voice-driven MUD client for [Elten](https://elten-net.eu/), the application platform for blind and visually impaired people.

The project is currently an early but usable Telnet client. Its interface is built from Elten's native spoken and Braille-aware controls rather than a graphical interface with accessibility added afterward.

## Current features

- Connection profiles with name, host, port, TLS, encoding, and automatic-reading preferences
- Plain Telnet and certificate-verified TLS connections
- UTF-8, Windows-1252, and ISO-8859-1 character encodings
- Streaming Telnet negotiation with ECHO, Suppress Go Ahead, Terminal Type, and MSP support
- MCCP2 compressed-stream negotiation and bounded streaming decompression
- GMCP negotiation with bounded UTF-8/JSON parsing and a raw diagnostic inspector
- Accessible live views for character, room, items, skills, group, and communication data
- Opt-in Client.Media and MSP audio with captions, per-profile volumes, bounded downloads, and cache limits
- Safe start-of-line MSP fallback for legacy servers, including explicitly disclosed HTTP media support
- Streaming ANSI control-sequence filtering
- Accessible scrollback and command entry
- Automatic reading of incoming lines and prompts
- Pause, resume, stop-current-speech, and resume-from-latest controls
- Bounded in-memory scrollback and speech queues
- In-memory command history
- Per-profile aliases, regular-expression triggers, repeating timers, and command shortcuts
- Ordered automation actions for rewriting, hiding, speaking, sending, and playing local or HTTPS media
- Optional bounded plain-text transcripts with in-session controls and a profile default
- Automatic password-prompt detection and an explicit sensitive-input mode
- Clean socket, worker-thread, and program resource shutdown

Passwords, command history, and scrollback are not persisted. Connection profiles and per-profile automation are stored in the program's private data directory. Transcripts are persisted there only when explicitly started for a session or enabled for a profile; sensitive commands and hidden trigger input are excluded.

## Using Meow

Meow targets Elten API 3.0.3 and is currently intended for Elten developer mode.

1. Load the `meow` source program in Elten.
2. Open **Meow** from the programs menu.
3. Create a connection profile with the MUD host and port.
4. Select the profile and choose **Connect**.
5. Enter commands in the Command field and press Enter to send them.

The output and command fields provide additional actions through their context menus, including command recall, sensitive input, jumping to the latest output, and skipping queued speech.

## Project structure

- `__app.rb` contains the Elten manifest and program entry point.
- `lib/meow/profile_repository.rb` stores and validates connection profiles.
- `lib/meow/transport.rb` owns TCP/TLS sockets and background I/O.
- `lib/meow/telnet.rb` implements the streaming Telnet state machine.
- `lib/meow/gmcp.rb` parses GMCP and maintains package state.
- `lib/meow/media.rb` provides protocol-neutral media requests, safe caching, and Elten audio playback.
- `lib/meow/msp.rb` parses line and Telnet-option MSP commands into shared media requests.
- `lib/meow/session_gmcp.rb` integrates GMCP packages with accessible session views.
- `lib/meow/text_pipeline.rb` handles ANSI filtering, decoding, lines, and prompts.
- `lib/meow/automation.rb` owns rule persistence, matching, templates, safety limits, and timers.
- `lib/meow/transcript.rb` provides bounded per-profile transcript storage.
- `lib/meow/session.rb` owns connected-session state, scrollback, input, automation, transcripts, and speech.
- `lib/meow/ui.rb` implements the connection manager and profile editor.

## Next steps

The protocol and session layers are intentionally separated so richer MUD functionality can be added without coupling it to the accessible interface.

Automated regression coverage now exercises the streaming Telnet parser and text pipeline, including negotiation, fragmented input, ANSI filtering, character decoding, and newline edge cases.

Planned work, roughly in order:

1. Add multiple simultaneous sessions with independent output, media, automation, transcripts, and speech queues.
2. Add localization catalogs and package/signing automation for releases.

## Running the tests

The suite uses no external gems. Run it with a standard Ruby installation:

```console
ruby test/run.rb
```

When developing inside Elten, load `test/run.rb` through the source program's evaluation context so the tests use Elten's bundled Ruby runtime.

## Development status

The current implementation is checked with Elten's Ruby syntax checker and its automated in-process protocol suite, and has also been exercised with a loopback TCP server. Real MUDs differ considerably in their Telnet behavior, so interoperability reports and reproducible protocol captures are welcome.

The application UUID is `51a92051-84e0-415f-84e3-98f08a320a15` and must remain stable across releases.