# TRoR Hello World POC Plan

## Goal

Build a small proof-of-concept that drives an in-game ComputerCraft computer (on an ATM10 server) from a local CraftOS-PC instance using TRoR (Terminal Redirection over Rednet).

The POC is intentionally minimal: see "Hello World" printed by an in-game computer rendered locally, and have a local keystroke produce a CC event in-game.

## Background

- `craftos --tror` enables the TRoR renderer but only reads/writes packets over **stdio** — it does not speak real rednet. See `docs/craftos_pc_glossary.md`.
- TRoR is a ComputerCraft standard (oeed/CraftOS-Standards #10): packet format `<Code>:<Meta>;<Payload>` (e.g. `TW` write, `TC` cursor, `EV` event).
- [`lyqyd/cc-netshell`](https://github.com/lyqyd/cc-netshell) already implements a TRoR server/client over rednet inside CC. We piggyback on it instead of reimplementing the protocol.

## Architecture

Three actors:

```text
[ local craftos --tror ] <-- stdio --> [ ws bridge ] <-- ws --> [ in-game relay CC ] <-- rednet --> [ in-game target CC ]
```

1. **Target CC** (in-game): runs `cc-netshell` server, prints "Hello World", reads `key`/`char` events.
2. **Relay CC** (in-game): has wireless modem + uses `http.websocket` to bridge TRoR packets between rednet and an external WS endpoint.
3. **WS bridge** (host): tiny Node/Python WS server that also pipes stdio to/from `craftos --tror`. Could be a single script that spawns `craftos` as a child process.

Why a relay: CC has no raw TCP socket; the only off-world transport is `http`/`websocket`. The ATM10 server must allow outbound HTTP/WS to our host (default CC:Tweaked config does).

## Milestones

1. **In-game baseline**: install `cc-netshell` on two test computers (creative world / single-player first), confirm server/client TRoR shell works over rednet alone.
2. **WS bridge skeleton**: minimal local WS server that logs frames. Verify a CC computer can connect via `http.websocket` and exchange text frames.
3. **Relay program**: in-game program that joins the WS server and forwards every WS frame as a rednet message to a configured target ID, and vice versa. Treat frames as opaque TRoR packets.
4. **Local TRoR client**: spawn `craftos --tror`, pipe its stdout to the WS bridge, pipe WS frames to its stdin. A "Hello World" written by the target CC should render in CraftOS-PC.
5. **Input loopback**: confirm keystrokes typed in local CraftOS-PC reach the target as `key`/`char` events (TRoR `EV` packets).
6. **ATM10 deployment**: copy the relay + target programs to the real server, point relay at the public host running the WS bridge.

## Open Questions

- Does `cc-netshell`'s wire format match the on-the-wire TRoR packet format byte-for-byte, or does it wrap packets in a rednet envelope? If wrapped, the relay must unwrap before forwarding to the WS bridge (and rewrap on the way back).
- ATM10 default CC:Tweaked config: is outbound WS to arbitrary hosts allowed? May need a whitelist entry in `computercraft-server.toml`.
- Auth: any pairing/handshake between local client and target CC, or do we rely on "obscure WS URL" for the POC?
- One target only, or do we want the relay to multiplex by target ID from day one?

## Out Of Scope

- Multi-user, auth, TLS hardening.
- Reconnect logic beyond "restart both ends".
- Packaging into this repo's `programs/` / `servers/` layout — that comes after the POC proves the loop works.

## Deliverables

- `programs/tror-relay.lua` (in-game relay, prototype quality).
- `tools/tror-bridge/` (host-side WS + craftos spawner script, language TBD).
- Notes appended to `docs/craftos_pc_glossary.md` once the stdio contract is verified.