realtimeclipboard 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akshay Nikhare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# RealtimeClipboard — an end-to-end encrypted online clipboard that syncs text between devices
+
+RealtimeClipboard is a free, open-source online clipboard: open it on two devices, type the
+same five-character key, and whatever you copy on one is ready to paste on the
+other. No account, no install, no database. Files travel peer-to-peer and never
+touch the server.
+
+**[Try it → realtimeclipboard.com](https://realtimeclipboard.com/)**
+
+```
+  Machine A  ──┐                                  ┌──  Machine B
+               │   text  ──►  relay  ──►  text    │
+               │   (encrypted in the browser)     │
+               │                                  │
+               └───  files ═══ direct P2P ═══─────┘
+                     (never touch the server)
+```
+
+**Status: pre-alpha, and it works end to end.** The relay is deployed and live,
+the frontend is wired to it over a WebSocket with an SSE fallback, and the
+17-check end-to-end suite runs two real peers with real crypto against the
+production relay. See [docs/M0-RESULTS.md](docs/M0-RESULTS.md) for exactly what
+is proven, and [Known limitations](#known-limitations) for what is not.
+
+---
+
+## What it does
+
+- **Sync clipboard text between devices** — Windows, macOS, Android, ChromeOS and Linux
+- **Works across different networks**, not just the same Wi-Fi, and not just the same LAN
+- **No account, no sign-up, no email** — a five-character key is the whole identity of a session
+- **End-to-end encrypted** in the browser with AES-GCM; `PBKDF2` derives the key, `SHA-256` routes the room
+- **Peer-to-peer file transfer** over a WebRTC data channel, 5 MB per file
+- **Copy and paste images** — a screenshot copied on one machine previews on the other
+- **Installable progressive web app** — own window, own icon, works offline
+- **Nothing written to disk**, on your machine or the server
+- **Self-hostable relay** — it is one small FastAPI service
+
+## Why
+
+Moving a snippet between a work laptop, a desktop and a phone is
+disproportionately annoying. The alternatives want an account, an install with
+admin rights, or an email to yourself. This wants a five-character key.
+
+## How RealtimeClipboard compares to Snapdrop, PairDrop, LocalSend and AirDrop
+
+The nearby tools are mostly *file droppers*: you pick a device and push a file at
+it. RealtimeClipboard is a clipboard — what you copy shows up ready to paste, without
+picking anything.
+
+| Tool | Account | Install | Across networks | Lands on system clipboard | Files |
+|---|---|---|---|---|---|
+| **RealtimeClipboard** | None | None — browser | Yes | **Yes** | P2P, 5 MB |
+| PairDrop | None | None — browser | Yes, via a 6-digit code | No — you send a message | P2P |
+| Snapdrop | Optional since the LimeWire acquisition | None — browser | Same network only | No | P2P |
+| LocalSend | None | Native app on both ends | Same network only | No | Unlimited, LAN |
+| AirDrop | None | Built in | Nearby devices only | No | Unlimited |
+| KDE Connect | None | App on both ends | Same network only | Yes | Yes |
+| Pushbullet | Required | App or extension | Yes | Paid tier | Paid above a small cap |
+
+Checked against each project's own documentation in August 2026. Corrections
+welcome — open an issue.
+
+## How it works
+
+| Layer | Choice |
+|---|---|
+| Frontend | Static HTML/JS on Cloudflare Pages, installable as a Chrome PWA |
+| Relay | FastAPI on FastAPI Cloud — in-memory rooms, no database, no disk |
+| Text | WebSocket through the relay, AES-GCM encrypted in the browser |
+| Blocked networks | If a proxy eats the WebSocket, the client moves itself to SSE + POST on the same host and says so |
+| Files | WebRTC data channel, direct between peers, 5 MB cap |
+| Key | `SHA-256(key)` routes the room; `PBKDF2(key)` encrypts. The key itself is never transmitted |
+
+The relay only ever sees a room hash and ciphertext. It cannot decrypt anything,
+and it stores nothing beyond the last message in RAM.
+
+## Frequently asked questions
+
+### What is an online clipboard?
+
+An online clipboard is a web page that holds what you copy on one device so you
+can paste it on another. Both devices open the same page, identify themselves
+with a short key, and share a single clipboard between them.
+
+### How do I sync my clipboard between my phone and my PC?
+
+Open RealtimeClipboard on both, type the same five-character key on each, and copy
+something. It arrives on the other device ready to paste. Nothing to install, so
+it works on a machine where you do not have admin rights.
+
+### Does it work if the two devices are on different networks?
+
+Yes. Text goes through a relay, so a laptop on home Wi-Fi and a phone on mobile
+data share a clipboard fine. This is the main difference from Snapdrop, LocalSend
+and AirDrop, which need both devices on the same network. Files are the
+exception — they go directly between machines, and that is the part corporate
+firewalls sometimes block.
+
+### Is an online clipboard safe?
+
+It depends on whether the server can read what you copy, and here it cannot. Text
+is encrypted in the browser before it is sent; the server sees a room hash and
+ciphertext and keeps neither. The honest caveat is that the key is a bearer
+credential — anyone who learns it can read that session while it is open.
+
+### Can it read my clipboard in the background?
+
+No, and neither can any other web app on any browser. `readText()` requires
+window focus. You switch to the RealtimeClipboard tab and it picks up what you copied.
+
+### Which browsers work?
+
+Chromium browsers get the full experience. Firefox and Safari can receive
+everything and can send anything you paste in by hand, but cannot read the
+clipboard on their own.
+
+## Repo layout
+
+```
+index.html              marketing landing page (indexable)
+app.html                the app itself (noindex) — served at /app; the .html is
+                        rewritten out by tools/build/build.mjs, in the deploy only
+src/
+  main.js               composition root — the only file that crosses layers
+  core/                 bus, config, state, crypto, keys, storage, paths — no DOM
+  transport/            relay facade + interchangeable WebSocket and SSE channels
+  clipboard/            OS clipboard read/write, capture tiers
+  files/                thumbnails, registry, chunking, P2P transfer
+  ui/                   primitives → shell + features → panels, in that order
+  styles/               design tokens + per-component CSS; lazy/ is fetched on demand
+  landing/              behaviour for index.html — a separate document from the app
+  pages/                help/ blog/ download/ — copied to the site root, not bundled
+cli/                    the same crypto and protocol, on the command line
+backend/                FastAPI relay — deployed separately, shares no code
+desktop/                Tauri shell around this very src/ — no second implementation
+assets/                 icons/ (precached whole) + social/ (the OG card, never)
+tests/                  unit/ needs nothing · dom/ needs jsdom · live/ needs a relay
+tools/                  build/ · check/ · release/ · seo/
+docs/                   PRD, architecture, clipboard design, P2P design, SEO
+```
+
+A directory **at the root** is served at its own path — `assets/icons/icon.svg` is
+`/assets/icons/icon.svg`. `src/` is the opposite: inputs that get bundled, plus `src/pages/`, which
+is lifted to the site root at build time. `app.html` and `index.html` stay at the root so the app
+keeps a dev loop where the disk path and the URL are the same string.
+
+**Every directory carries its own `CLAUDE.md` and `README.md`** — the rules that
+govern a change live next to the code they govern, and a static check fails if a
+directory has neither. Start at [src/CLAUDE.md](src/CLAUDE.md) for the import
+rules.
+
+Details and conventions: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Run it
+
+**Frontend** — any static server (ES modules need HTTP, not `file://`):
+```bash
+python -m http.server 8080
+# http://127.0.0.1:8080
+```
+
+**Relay:**
+```bash
+cd backend
+pip install -r requirements.txt
+python -m uvicorn main:app --port 8000
+python test_relay.py ws://127.0.0.1:8000    # 51-check protocol gate
+python test_sse.py http://127.0.0.1:8000    # 33-check fallback gate
+```
+
+The relay must be on **port 8000**: `src/core/config.js` points the app there
+automatically when the page is served from localhost, so nothing needs
+configuring — but nothing else will be found either. Open `app.html#DEVKEY` in
+two windows to watch a clip cross between them.
+
+`app.html` here, not `/app`: the clean URL is a deploy-time rewrite in
+`tools/build/build.mjs`, and `python -m http.server` does not strip extensions. The
+same is true of the desktop app, which ships this tree as it stands.
+
+With the relay running, `node tests/live/fallback.mjs ws://127.0.0.1:8000` exercises
+the client's WebSocket → SSE failover with WebSockets simulated as blocked.
+
+Full setup, the service-worker cache trap, and how to check a UI change:
+[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). For deployment see
+[backend/README.md](backend/README.md), **including the replica-pinning step
+that must not be skipped.**
+
+## Contributing and releasing
+
+```bash
+npm install                          # sets up the git hooks
+git switch -c fix/whatever           # main refuses direct commits
+git commit -m "fix(scope): what changed"
+```
+
+[CONTRIBUTING.md](CONTRIBUTING.md) has the full loop, the commit convention, and
+the boundaries the static checks enforce. Security problems go through
+[SECURITY.md](SECURITY.md), not the issue tracker.
+
+The tests run **locally, in a git hook, before the commit exists** — there is no
+CI. GitHub's only workflow copies files to Pages, and it runs on a version tag
+and nothing else. The reasoning, the trade that comes with it, and the commit
+message format the changelog is generated from are in
+[docs/RELEASING.md](docs/RELEASING.md).
+
+```bash
+npm run verify                       # what the pre-commit hook runs
+npm test                             # everything, needs a relay
+npm run release -- minor             # verify, changelog, tag, push, deploy
+```
+
+## Docs
+
+| Doc | What it covers |
+|---|---|
+| [PRD.md](docs/PRD.md) | Requirements, architecture, security model, open issues |
+| [DEVELOPMENT.md](docs/DEVELOPMENT.md) | Running it locally, the test suite, the landing-page grid and globe, and the traps |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Module layout, boundaries, and how to add a feature |
+| [RELEASING.md](docs/RELEASING.md) | Hooks instead of CI, tag-triggered deploys, and the generated changelog |
+| [CHANGELOG.md](CHANGELOG.md) | What shipped in each release — generated from the commits |
+| [CLIPBOARD-FLOW.md](docs/CLIPBOARD-FLOW.md) | How the browser reaches the OS clipboard, and why background capture is impossible |
+| [P2P-FILES.md](docs/P2P-FILES.md) | Thumbnails over the relay, bytes over WebRTC, and the corporate-network problem |
+| [M0-RESULTS.md](docs/M0-RESULTS.md) | Transport gate results |
+| [SEO.md](docs/SEO.md) | Search, answer-engine and distribution strategy |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Setup, the commit convention, and the boundaries the checks enforce |
+| [SECURITY.md](SECURITY.md) | Reporting a vulnerability privately, and what is in scope |
+| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Contributor Covenant 2.1 |
+
+## Known limitations
+
+- **No background clipboard capture.** No web app can do this on any browser —
+  `readText()` requires window focus. You switch to RealtimeClipboard and it grabs what you
+  copied. [Why](docs/CLIPBOARD-FLOW.md).
+- **P2P file transfer may fail on corporate networks**, which block the UDP that
+  WebRTC needs. Falls back to relay-chunked transfer, labelled visibly.
+- **The share key is a bearer credential.** Anyone holding it can read the session.
+- Chromium-first. Firefox and Safari can receive and can send via paste, but
+  cannot silently read the clipboard.
+
+## Licence
+
+[MIT](LICENSE).

package/cli/CLAUDE.md

@@ -0,0 +1,28 @@
+# cli/
+
+One file, and how little of it there is *is* the design.
+
+It imports the same modules the browser runs — `core/crypto.js`, `core/keys.js`,
+`transport/relay.js` — because none of them ever touched `window` or `document`, and Node has had
+`WebSocket`, `fetch` and `crypto.subtle` as globals since 22. The heartbeat, the jittered reconnect
+backoff, the WebSocket→SSE failover and the encryption all come for free and cannot drift, because
+there is nothing here to drift.
+
+## The one rule
+
+**Nothing in this file may reimplement a protocol detail.** If something is missing, it belongs in
+`src/` where both ends get it. A second implementation of the crypto is exactly how the two ends
+end up subtly and silently disagreeing.
+
+## Rules
+
+- **`import.meta.url` is allowed here and banned in `src/`.** This file is published as itself and
+  never goes through the bundler, so its depth in the tree is fixed. That is the whole exemption —
+  it does not extend to anything it imports.
+- **Made for pipes.** Clip content goes to stdout and nothing else does; diagnostics go to stderr;
+  the exit code is what a script branches on.
+- **The version is read from `package.json`**, never written here. It was a literal once and was
+  already wrong — the package said 0.2.1 while `--version` said 0.1.0.
+- `package.json` `files:` ships `cli/`, `src/core/` and `src/transport/`. Importing anything outside
+  those three from here breaks the published package, and only after publish.
+- `tests/live/cli.mjs` runs this against a real relay, and `prepublishOnly` runs that suite.

package/cli/README.md

@@ -0,0 +1,24 @@
+# cli/
+
+RealtimeClipboard on the command line — the same crypto and the same protocol as the browser, because
+it imports the same modules.
+
+```bash
+npx realtimeclipboard new              # print a fresh key
+npx realtimeclipboard <KEY>            # two-way: prints what arrives, sends what you type
+npx realtimeclipboard watch <KEY>      # print incoming clips and nothing else
+npx realtimeclipboard send <KEY>       # read stdin to EOF, send it, exit
+```
+
+Built for pipes — clip content is the only thing on stdout, and the exit code is what a script
+should branch on:
+
+```bash
+tail -f app.log | npx realtimeclipboard send WORK5
+npx realtimeclipboard watch WORK5 > incoming.txt
+```
+
+Needs Node 22+, for the global `WebSocket`, `fetch` and `crypto.subtle` that let it share the
+browser's transport and crypto unchanged.
+
+Rules that govern edits here: [CLAUDE.md](CLAUDE.md).

package/cli/realtimeclipboard.mjs

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * RealtimeClipboard on the command line.
+ *
+ * The interesting thing about this file is how little of it there is. It
+ * imports the SAME modules the browser runs — core/crypto.js, core/keys.js,
+ * transport/relay.js — because none of them ever touched `window` or
+ * `document`, and Node has had `WebSocket`, `fetch` and `crypto.subtle` as
+ * globals since 22. So the CLI gets the heartbeat, the jittered reconnect
+ * backoff, the WebSocket→SSE failover and the encryption for free, and cannot
+ * drift from the browser's behaviour, because there is nothing here to drift.
+ *
+ * That is also the constraint: nothing in this file may reimplement a protocol
+ * detail. If something is missing, it belongs in src/ where both ends get it.
+ *
+ *   realtimeclipboard <KEY>              two-way: prints what arrives, sends what you type
+ *   realtimeclipboard watch <KEY>        prints incoming clips and nothing else
+ *   realtimeclipboard send <KEY>         reads stdin to EOF, sends it, exits
+ *   realtimeclipboard new                prints a fresh key
+ *
+ * Made for pipes, so the rules are the usual ones: clip content goes to stdout
+ * and nothing else does, and the exit code is what a script should branch on.
+ */
+
+import { createInterface } from "node:readline";
+import { stdin, stdout, stderr, argv, exit, env } from "node:process";
+import { hostname } from "node:os";
+import { readFileSync } from "node:fs";
+
+import * as keys from "../src/core/keys.js";
+import * as cryptoBox from "../src/core/crypto.js";
+import * as relay from "../src/transport/relay.js";
+import * as proto from "../src/transport/protocol.js";
+import { on, EV } from "../src/core/bus.js";
+import { DEFAULT_RELAY_URL, normaliseRelay, TEXT, LOCK } from "../src/core/config.js";
+
+/**
+ * Read from package.json rather than written here.
+ *
+ * It was a literal, and it was already wrong: the package said 0.2.1 while
+ * `--version` said 0.1.0. That is the failure this codebase avoids everywhere
+ * else by deriving — RELAY_HTTP_URL from RELAY_URL, LINKS from REPO, the
+ * service worker's precache list from disk — and a version number is the worst
+ * place to have it, because the whole point of the number is telling someone
+ * which code they are running when they report a bug.
+ *
+ * import.meta.url is correct HERE and banned in src/: this file is published as
+ * itself and never goes through the bundler, so its depth in the tree is fixed.
+ * npm always includes package.json in a tarball, so this resolves after install.
+ */
+const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
+/* ------------------------------------------------------------------ args -- */
+
+function parse(args) {
+  const opts = { relay: null, pin: null, once: false, json: false, timeout: 0, quiet: false };
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const val = () => args[++i];
+    if (a === "--relay") opts.relay = val();
+    else if (a === "--pin") opts.pin = val();
+    else if (a === "--timeout") opts.timeout = Number(val()) * 1000;
+    else if (a === "--once") opts.once = true;
+    else if (a === "--long") opts.long = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "-q" || a === "--quiet") opts.quiet = true;
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a.startsWith("-")) die(`unknown option ${a}`, 2);
+    else rest.push(a);
+  }
+  return { opts, rest };
+}
+
+const USAGE = `realtimeclipboard ${VERSION} — an online clipboard, on the command line
+
+  realtimeclipboard <KEY>              two-way; prints what arrives, sends what you type
+  realtimeclipboard watch <KEY>        print incoming clips
+  realtimeclipboard send <KEY>         read stdin to EOF and send it
+  realtimeclipboard new [--long]       print a fresh key
+
+Options
+  --relay <url>    relay to use            (default ${DEFAULT_RELAY_URL})
+                   or set REALTIMECLIPBOARD_RELAY
+  --pin <pin>      join a locked session   (or set REALTIMECLIPBOARD_PIN)
+  --once           watch: exit after the first clip
+  --json           one JSON object per line instead of raw text
+  --timeout <s>    give up after this many seconds
+  -q, --quiet      no status on stderr
+  -h, --help       this
+  -v, --version    version
+
+Examples
+  echo "deploy key" | realtimeclipboard send D75LV
+  realtimeclipboard watch D75LV > clip.txt
+  realtimeclipboard watch D75LV --once --json | jq -r .text
+  ssh box 'cat /etc/hosts' | realtimeclipboard send D75LV
+
+The key is a bearer credential: anyone holding it can read the session while it
+is open. Clip contents are encrypted here, before they are sent; the relay only
+ever sees a room hash and ciphertext.`;
+
+/* ---------------------------------------------------------------- output -- */
+
+const note = (msg, opts) => { if (!opts.quiet) stderr.write(`${msg}\n`); };
+
+function die(msg, code = 1) {
+  stderr.write(`realtimeclipboard: ${msg}\n`);
+  exit(code);
+}
+
+/* --------------------------------------------------------------- session -- */
+
+/**
+ * Everything needed to talk in a room, derived exactly as the browser derives
+ * it — same salt, same iteration count, same HKDF info strings, because it is
+ * the same function.
+ */
+async function derive(rawKey, pin) {
+  const key = keys.normalise(rawKey);
+  if (!keys.isValid(key)) die(`"${rawKey}" is not a valid key`, 2);
+
+  if (pin) {
+    const clean = cryptoBox.normalisePin(pin);
+    if (!clean) die("that PIN is too short", 2);
+    const d = await cryptoBox.deriveLocked(key, clean);
+    return { key, roomHash: d.roomHash, aesKey: d.aesKey, auth: d.authToken, locked: true };
+  }
+  return {
+    key,
+    roomHash: await cryptoBox.roomHash(key),
+    aesKey: await cryptoBox.deriveKey(key),
+    auth: null,
+    locked: false,
+  };
+}
+
+/**
+ * Connect and resolve once the relay has welcomed us.
+ *
+ * relay.js announces state on the bus rather than returning a promise, because
+ * in the browser the connection outlives any one call. Here there is a script
+ * waiting, so the bus event is adapted back into a promise — and a timeout,
+ * since a pipe that hangs forever is worse than one that fails.
+ */
+function connect(session, opts, onClip) {
+  const url = opts.relay ?? env.REALTIMECLIPBOARD_RELAY ?? undefined;
+  if (opts.relay && !normaliseRelay(opts.relay)) die(`"${opts.relay}" is not a usable relay address`, 2);
+
+  return new Promise((resolve, reject) => {
+    // Connecting has its own bound, separate from --timeout below: "the relay
+    // never answered" and "nothing was ever sent to this room" are different
+    // failures, and a script that gets one when it expected the other has been
+    // told a lie about its own network.
+    const timer = setTimeout(
+      () => reject(new Error("the relay did not answer")),
+      Math.max(opts.timeout || 0, 20_000),
+    );
+
+    on(EV.CONN_STATE, ({ state, detail }) => {
+      if (state === "connected") { clearTimeout(timer); resolve(); }
+      if (state === "error" && detail) note(`  ${detail}`, opts);
+    });
+
+    relay.setFrameHandler(async msg => {
+      if (msg.t !== proto.T.CLIP || !msg.payload) return;
+      try {
+        const text = await cryptoBox.decrypt(session.aesKey, msg.payload, msg.iv);
+        // The lock beacon is a control frame wearing a clip's clothes: it is
+        // what lets a joiner tell "wrong PIN" from "first one here". Receivers
+        // drop it rather than render it, and a pipe must not see it either.
+        // Compared against the constant, not a guess at its shape: it starts
+        // with NUL, and "looks like a control character" would also
+        // swallow a legitimate clip that happened to.
+        if (text === LOCK.BEACON) return;
+        onClip(text, msg);
+      } catch {
+        // Undecryptable means a different secret, not a corrupt relay: someone
+        // in the room with another PIN, or a stale frame from a rotated key.
+        note("  (a clip arrived that this key cannot read)", opts);
+      }
+    });
+
+    relay.connect({
+      roomHash: session.roomHash,
+      intent: "join",
+      name: `cli@${hostname()}`,
+      auth: session.auth,
+      ...(url ? { url: normaliseRelay(url) } : {}),
+    });
+  });
+}
+
+async function sendText(session, text, opts) {
+  if (!text) die("nothing on stdin to send", 2);
+  if (text.length > TEXT.MAX_CHARS) {
+    die(`that is ${text.length} characters; the limit is ${TEXT.MAX_CHARS}`, 2);
+  }
+  const { payload, iv } = await cryptoBox.encrypt(session.aesKey, text);
+  relay.send(proto.clip({ payload, iv, originId: `cli-${Date.now().toString(36)}` }));
+  // The frame is handed to a socket, not delivered. Give it a moment to flush
+  // before the process exits out from under it.
+  await new Promise(r => setTimeout(r, 250));
+}
+
+const readStdin = () => new Promise(resolve => {
+  let buf = "";
+  stdin.setEncoding("utf8");
+  stdin.on("data", d => { buf += d; });
+  stdin.on("end", () => resolve(buf));
+});
+
+/**
+ * `seq` and `originId` are the only provenance there is, and that is on purpose:
+ * the relay rebuilds a clip envelope from scratch (backend/main.py, "clip") and
+ * carries neither a timestamp nor a sender identity on it. `at` is therefore
+ * when THIS process received it, and is labelled as such rather than implying a
+ * send time nobody recorded.
+ */
+const emitClip = (text, msg, opts) => stdout.write(
+  opts.json
+    ? `${JSON.stringify({ text, seq: msg.seq ?? null, origin: msg.originId ?? null, receivedAt: new Date().toISOString() })}\n`
+    : (text.endsWith("\n") ? text : `${text}\n`),
+);
+
+/* ------------------------------------------------------------------ main -- */
+
+const { opts, rest } = parse(argv.slice(2));
+if (opts.help) { stdout.write(`${USAGE}\n`); exit(0); }
+if (opts.version) { stdout.write(`${VERSION}\n`); exit(0); }
+
+opts.pin ??= env.REALTIMECLIPBOARD_PIN ?? null;
+
+let [cmd, keyArg] = rest;
+if (cmd === "new") {
+  stdout.write(`${keys.generate(opts.long ? keys.LENGTHS.LONG : keys.LENGTHS.NORMAL)}\n`);
+  exit(0);
+}
+// `realtimeclipboard D75LV` — no verb, so the first word is the key and the mode is both.
+if (cmd && !["send", "watch"].includes(cmd)) { keyArg = cmd; cmd = "both"; }
+if (!cmd) { stdout.write(`${USAGE}\n`); exit(2); }
+if (!keyArg) die(`${cmd} needs a key — try: realtimeclipboard ${cmd} D75LV`, 2);
+
+if (typeof WebSocket === "undefined") {
+  die("this needs Node 22 or newer (for the built-in WebSocket)", 3);
+}
+
+const session = await derive(keyArg, opts.pin);
+note(`realtimeclipboard · room ${session.roomHash.slice(0, 8)}…${session.locked ? " · locked" : ""}`, opts);
+
+/**
+ * --timeout bounds the WHOLE run, not just the connection.
+ *
+ * The distinction matters and was got wrong first time. `watch --once` on a
+ * room nobody sends to connects perfectly happily and then waits forever — and
+ * with a locked room that is not even an error, because the wrong PIN names a
+ * different room, which legitimately exists and is legitimately empty. A
+ * connect-only timeout leaves every one of those cases hanging a pipeline.
+ */
+if (opts.timeout) {
+  setTimeout(() => {
+    relay.close();
+    note(`  timed out after ${opts.timeout / 1000}s`, opts);
+    exit(5);
+  }, opts.timeout).unref?.();
+}
+
+let got = 0;
+try {
+  await connect(session, opts, (text, msg) => {
+    got++;
+    emitClip(text, msg, opts);
+    if (cmd === "watch" && opts.once) { relay.close(); exit(0); }
+  });
+} catch (err) {
+  die(err.message, 4);
+}
+note("  connected", opts);
+
+if (cmd === "send") {
+  await sendText(session, await readStdin(), opts);
+  relay.close();
+  exit(0);
+}
+
+if (cmd === "both") {
+  // Not readStdin(): that waits for EOF, and this mode has to send each line as
+  // it is typed while still printing what arrives in between.
+  const rl = createInterface({ input: stdin, terminal: false });
+  rl.on("line", line => { if (line.length) sendText(session, line, opts).catch(() => {}); });
+  rl.on("close", () => { relay.close(); exit(0); });
+}
+
+for (const sig of ["SIGINT", "SIGTERM"]) {
+  process.on(sig, () => {
+    relay.close();
+    note(`  ${got} clip${got === 1 ? "" : "s"} received`, opts);
+    exit(0);
+  });
+}