realtimeclipboard 0.3.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "realtimeclipboard",
+  "version": "0.3.0",
+  "description": "Live clipboard sharing. Static frontend of native ES modules — development needs no build, and `npm run build` exists only to assemble the deploy. Nothing here is needed to READ the app.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akshaynikhare/RealtimeClipboard.git"
+  },
+  "homepage": "https://github.com/akshaynikhare/RealtimeClipboard",
+  "bugs": "https://github.com/akshaynikhare/RealtimeClipboard/issues",
+  "keywords": [
+    "clipboard",
+    "online-clipboard",
+    "clipboard-sync",
+    "share-text",
+    "end-to-end-encrypted",
+    "cli",
+    "pipe",
+    "ssh"
+  ],
+  "type": "module",
+  "bin": {
+    "realtimeclipboard": "cli/realtimeclipboard.mjs"
+  },
+  "files": [
+    "cli/",
+    "src/core/",
+    "src/transport/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "verify": "node tests/unit/static-check.mjs && node tests/unit/relay-url.mjs && node tests/unit/lock.mjs && node tests/unit/files.mjs && node tests/unit/transfer.mjs && node tests/unit/clipsize.mjs && node tests/dom/dialog.mjs && node tests/dom/whatsnew.mjs && node tests/dom/tiles.mjs",
+    "test": "npm run verify && node tests/dom/bundle.mjs && node tests/live/e2e.mjs && node tests/live/boot.mjs && node tests/live/boot.mjs --locked && node tests/live/fallback.mjs",
+    "test:static": "node tests/unit/static-check.mjs",
+    "test:lock": "node tests/unit/lock.mjs && node tests/dom/dialog.mjs",
+    "test:e2e": "node tests/live/e2e.mjs",
+    "test:boot": "node tests/live/boot.mjs && node tests/live/boot.mjs --locked",
+    "test:bundle": "node tests/dom/bundle.mjs",
+    "test:tiles": "node tests/dom/tiles.mjs",
+    "test:fallback": "node tests/live/fallback.mjs",
+    "test:cli": "node tests/live/cli.mjs",
+    "build": "node tools/build/build.mjs",
+    "build:site": "node tools/build/build.mjs _site && node tools/check/site-check.mjs _site",
+    "build:desktop": "node tools/build/build.mjs _desktop --desktop",
+    "build:og": "python tools/build/build-og-card.py",
+    "check:og": "python tools/build/build-og-card.py --check",
+    "check:csp": "node tools/build/build.mjs _site && node tools/check/csp-check.mjs",
+    "relay": "python -m uvicorn main:app --app-dir backend --port 8000",
+    "relay:up": "node tools/release/relay-up.mjs",
+    "changelog": "node tools/release/changelog.mjs",
+    "release": "node tools/release/release.mjs",
+    "serve": "python -m http.server 8080",
+    "prepare": "husky",
+    "prepublishOnly": "npm run verify && node tests/live/cli.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1",
+    "husky": "^9.1.7",
+    "jsdom": "^26.1.0"
+  },
+  "comment": "esbuild is used ONLY by tools/build/build.mjs, which assembles the deploy — src/ stays plain ES modules on disk, so `npm run serve` still needs no build and the .husky checks still run against real modules. Tests are filed by what they need to run: tests/unit needs nothing, tests/dom needs jsdom, tests/live needs a relay. `verify` is all of unit plus the three dom suites that need no build, which is what a pre-commit hook can afford; `test` adds dom/bundle.mjs and everything under live. Every suite skips cleanly when its prerequisite is absent. The app itself still ships with zero RUNTIME dependencies."
+}

package/src/README.md

@@ -0,0 +1,24 @@
+# src/
+
+The frontend. Plain ES modules — what is here is what the browser loads, so `python -m http.server`
+is the whole development setup. The deploy is bundled from this tree but never replaces it.
+
+`main.js` is the composition root: the one file that imports across layers and wires them together.
+Everything else talks through `core/bus.js`.
+
+| Directory | What it holds |
+|---|---|
+| [core/](core/) | bus, config, state, crypto, keys, storage, paths, device, history — no DOM, node-importable |
+| [transport/](transport/) | the relay connection and its two interchangeable channels |
+| [clipboard/](clipboard/) | the OS clipboard boundary and the capture tiers above it |
+| [files/](files/) | peer-to-peer file transfer, chunking, thumbnails, the in-memory registry |
+| [ui/](ui/) | everything that renders, split by role into primitives, shell, features and panels |
+| [styles/](styles/) | design tokens and per-component CSS; `lazy/` is fetched on demand |
+| [landing/](landing/) | the marketing page — a separate document from the app |
+| [pages/](pages/) | static content pages, copied to the site root rather than bundled |
+
+`core/` and `transport/` are also what the npm package ships, so the CLI in [../cli/](../cli/) runs
+the same crypto and the same protocol as the browser.
+
+Conventions and the import rules: [CLAUDE.md](CLAUDE.md). Design rationale:
+[../docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md).

package/src/core/CLAUDE.md

@@ -0,0 +1,31 @@
+# src/core/ — rank 0
+
+The bottom of the tree. **Nothing here may import from anywhere else in `src/`.**
+
+Also the boundary the npm package ships (`package.json` `files:`), so `cli/realtimeclipboard.mjs`
+runs these exact modules. Two consequences:
+
+- **No `window`, no `document`, no DOM.** Guard anything ambient the way `config.js` guards
+  `location` and `paths.js` guards `document` — a bare reference throws at import time and takes
+  the whole graph down, including in the node tests.
+- **A change here is a change to a published package**, not just to the site.
+
+## Compatibility surfaces — changing these strands existing users
+
+- **The key derivation is a wire format.** Salts, iteration counts and domain-separation strings in
+  `config.js` are baked into every share link in existence. `tests/unit/lock.mjs` holds golden
+  vectors that fail if you touch them; that failure is the feature. If the change is intended, say
+  so explicitly in the commit body.
+- **`STORAGE_PREFIX`** — changing it orphans everyone's saved history and settings.
+- **`paths.js` resolves from `document.baseURI`**, never from `import.meta.url`. Six modules used
+  to compute their own depth in the tree, and bundling moved all six at once with no error.
+
+## Rules
+
+- Every tunable constant in the app lives in `config.js`. A magic number anywhere else is a bug.
+- `state.js` is not reactive. Mutate through its setters, which emit on the bus.
+- Event names are `EV.*` constants in `bus.js`. Adding an event means adding a constant.
+- A bus event that **reports** is never named the same as one that **commands** — `EV.LOCK_STATE`
+  and `"session:lock"` once shared a name and every `setKey()` opened the PIN dialog by itself.
+- The share key and the session PIN are never logged, never stored, never transmitted. Only
+  `SHA-256(key)` and PBKDF2/HKDF output leave this directory.

package/src/core/README.md

@@ -0,0 +1,18 @@
+# src/core/
+
+Foundations. No DOM, no network, no imports from elsewhere in `src/` — which is what lets the CLI
+and the node test suites run these files unchanged.
+
+| File | What it does |
+|---|---|
+| `bus.js` | Tiny pub/sub. The only channel between modules, and the `EV.*` name constants |
+| `config.js` | Every tunable constant, the relay address, and the crypto parameters |
+| `state.js` | Session state and the setters that announce changes |
+| `crypto.js` | Room hashing, PBKDF2/HKDF derivation, AES-GCM. No libraries |
+| `keys.js` | Share-key generation, normalisation, and the URL fragment |
+| `storage.js` | localStorage, wrapped so a disabled-storage browser degrades instead of throwing |
+| `paths.js` | Where the app is served from, resolved once for the whole codebase |
+| `device.js` | A human-readable name for this device, shown in the peer list |
+| `history.js` | In-session clip history — the model behind the history pane |
+
+Rules that govern edits here: [CLAUDE.md](CLAUDE.md).

package/src/core/bus.js

@@ -0,0 +1,84 @@
+/**
+ * Tiny pub/sub. The only way modules talk to each other.
+ *
+ * The rule that keeps this codebase modular: UI modules never import transport
+ * or clipboard modules, and vice versa. They publish and subscribe to events
+ * here. main.js is the only file that knows the full graph.
+ */
+
+const listeners = new Map();
+
+export function on(event, fn) {
+  if (!listeners.has(event)) listeners.set(event, new Set());
+  listeners.get(event).add(fn);
+  return () => off(event, fn);        // call the return value to unsubscribe
+}
+
+export function off(event, fn) {
+  listeners.get(event)?.delete(fn);
+}
+
+export function emit(event, payload) {
+  const set = listeners.get(event);
+  if (!set) return;
+  // Copy first: a handler may unsubscribe itself mid-dispatch.
+  for (const fn of [...set]) {
+    try { fn(payload); }
+    catch (err) { console.error(`[bus] handler failed for "${event}"`, err); }
+  }
+}
+
+/** Canonical event names. Typos here are silent bugs, so use the constants. */
+export const EV = {
+  // clipboard
+  TEXT_CAPTURED:   "text:captured",    // {text, how} — local capture, needs sending
+  TEXT_RECEIVED:   "text:received",    // {text, from} — arrived from a peer
+  TIER_CHANGED:    "clipboard:tier",   // {tier, note}
+  PENDING_CLIP:    "clipboard:pending",// {pending, text} — arrived while unfocused
+  CLIP_OFFERED:    "clipboard:offered",// {text} — arrived, but the editor has unsent work
+  PEER_JOINED:     "peers:joined",     // {name} — a device entered the session
+  PEER_LEFT:       "peers:left",       // {name}
+  PERMISSION:      "clipboard:permission", // {state} granted|prompt|denied
+  IMAGE_CAPTURED:  "clipboard:image",  // {blob, name} — an image was copied or pasted
+  SYNC_MODE:       "clipboard:mode",   // {mode} live|manual
+
+  // transport
+  CONN_STATE:      "conn:state",       // {state, detail}
+  TRANSPORT:       "conn:transport",   // {mode, label, blocked, forced} — ws | sse, or nothing works
+  TRANSPORT_SELECT:"conn:transport:set",// {mode} — the user picked one; null = automatic
+  PEERS_CHANGED:   "peers:changed",    // {count, list}
+  INSTANCE_CHANGED:"conn:instance",    // {from, to} — split-brain warning (OI-3)
+  KEY_COLLISION:   "session:collision",// generated key was taken (OI-2)
+  ROOM_STATE:      "conn:room",        // {existing, hasLast} — what `welcome` said
+
+  // session
+  KEY_CHANGED:     "session:key",      // {key, locked}
+  /**
+   * {locked, verified} — see core/crypto.js.
+   *
+   * "lockstate", not "lock", and the extra syllable is load-bearing. The name
+   * used to be "session:lock", which is ALSO the imperative the UI emits to
+   * mean "lock this session" (main.js). One name, two opposite meanings: a
+   * report and an order. So every state.setKey() — one per session, on every
+   * single boot — delivered a report to the handler that acts on the order,
+   * and the app opened the "Lock this session" PIN dialog by itself the moment
+   * it started. Nothing failed, nothing was logged, and the dialog looked
+   * exactly like a feature.
+   *
+   * Announcements are past tense here (`session:key`, `peers:changed`) and
+   * commands are bare verbs (`session:lock`, `session:leave`). Keep it that
+   * way; the bus does no namespacing of its own and a collision is silent.
+   */
+  LOCK_STATE:      "session:lockstate",
+  FOUNDER:         "session:founder",  // {founder} — first into this room? null = not yet known
+
+  // files
+  FILES_CHANGED:   "files:changed",    // full list
+  FILE_ADDED:      "files:added",      // {file} — added locally, needs announcing
+  FILE_PROGRESS:   "files:progress",   // {id, percent}
+  TRANSFER_PATH:   "files:path",       // {id, path: "p2p" | "relay"}
+
+  // ui
+  TOAST:           "ui:toast",         // string
+  SETTINGS_CHANGED:"ui:settings",      // {name, value} — a preference was toggled
+};

package/src/core/config.js

@@ -0,0 +1,414 @@
+/**
+ * Every tunable constant. Nothing else in the app hard-codes a limit —
+ * if you find a magic number elsewhere, it belongs here.
+ */
+
+/**
+ * Relay endpoint.
+ *
+ * Must be wss:// in production: the site is served over HTTPS from GitHub
+ * Pages, and a browser refuses a ws:// connection from an https:// page as
+ * mixed content. Localhost is exempt from that rule, which is why the dev
+ * branch can stay ws://.
+ */
+// Guarded: this module is imported by node-based tests where `location` does
+// not exist, and a bare reference would throw at import time and take the whole
+// graph down.
+const IS_LOCAL = typeof location !== "undefined" &&
+  ["localhost", "127.0.0.1", "[::1]"].includes(location.hostname);
+
+/** The relay this build ships pointed at. Self-hosters change this one line. */
+export const DEFAULT_RELAY_URL = "wss://realtimeclipboard.fastapicloud.dev";
+const LOCAL_RELAY_URL = "ws://127.0.0.1:8000";
+
+/**
+ * Key under which the chosen relay is remembered.
+ *
+ * The storage PREFIX lives here rather than in core/storage.js so that this
+ * module can read a setting without importing storage.js — which imports this
+ * one, and a cycle between "every constant" and "the thing that persists them"
+ * is the sort that works until someone moves a line to module scope.
+ */
+export const STORAGE_PREFIX = "realtimeclipboard.";
+const RELAY_KEY = "relayUrl";
+
+/**
+ * Accept only something that can actually be a relay, and normalise it.
+ *
+ * `http(s)://` is accepted and converted, because that is what a person copies
+ * out of a browser bar when their IT department gives them an address, and
+ * rejecting it would be pedantry with a support ticket attached.
+ */
+export function normaliseRelay(raw) {
+  if (!raw || typeof raw !== "string") return null;
+  try {
+    const u = new URL(raw.trim());
+    const scheme = { "http:": "ws:", "https:": "wss:", "ws:": "ws:", "wss:": "wss:" }[u.protocol];
+    if (!scheme) return null;
+    // Path, query and hash are meaningless here — the routes are fixed (/ws,
+    // /sse, /pub, /health) and a trailing slash would produce "//ws/<room>".
+    return `${scheme}//${u.host}`;
+  } catch { return null; }
+}
+
+const stored = () => {
+  try { return JSON.parse(localStorage.getItem(STORAGE_PREFIX + RELAY_KEY)); }
+  catch { return null; }
+};
+
+/**
+ * `?relay=` in the address, for builds that are deployed rather than visited:
+ * a corporate MSI transform, a macOS config profile, or a desktop shell that
+ * launches the webview at its own relay.
+ *
+ * It wins over the stored setting on purpose — the deployment is more current
+ * than whatever the machine remembers — and main.js persists it, so the switch
+ * survives the next launch without the flag.
+ *
+ * !! This is NOT an attack surface on the hosted site, and the reason is worth
+ * knowing: the CSP pins `connect-src` to this origin and the default relay, so
+ * a link carrying `?relay=` to anywhere else cannot open a connection at all.
+ * The override only does anything on a build whose operator also edited that
+ * meta tag — which is precisely the self-hosting case it exists for. The CSP is
+ * the enforcement; this is only the plumbing. !!
+ */
+const fromQuery = () => {
+  try { return new URLSearchParams(location.search).get("relay"); }
+  catch { return null; }
+};
+
+export const RELAY_URL =
+  normaliseRelay(fromQuery())
+  ?? normaliseRelay(stored())
+  ?? (IS_LOCAL ? LOCAL_RELAY_URL : DEFAULT_RELAY_URL);
+
+/** True when the app is not talking to the relay it was built against. */
+export const RELAY_IS_CUSTOM = RELAY_URL !== DEFAULT_RELAY_URL && RELAY_URL !== LOCAL_RELAY_URL;
+
+/**
+ * The same relay over plain HTTP, for the SSE+POST fallback and /stats.
+ *
+ * One hostname, two ways in — which is what makes the fallback worth having:
+ * IT allowlists a single domain (PRD §5.4) and both transports are covered by
+ * it. Derived rather than written twice so the two can never drift.
+ */
+export const RELAY_HTTP_URL = RELAY_URL.replace(/^ws/i, "http");
+
+/**
+ * How we talk to the relay.
+ *
+ *   ws   — WebSocket. Lower latency, one connection, the default.
+ *   sse  — Server-Sent Events downstream + fetch POST upstream (PRD §4.3 R3).
+ *          Plain HTTP with no Upgrade, so it survives the TLS-inspecting
+ *          proxies that eat WebSockets on corporate networks (§5.4).
+ *
+ * Both carry the identical envelopes from §6 — see transport/protocol.js.
+ */
+export const TRANSPORT = { WS: "ws", SSE: "sse" };
+
+/**
+ * Clip size, derived — not chosen.
+ *
+ * A clip does not go on the wire as text. It is UTF-8 encoded, sealed with
+ * AES-GCM (which appends a 16-byte tag), base64'd, and dropped into a JSON
+ * envelope — and the relay rejects any frame over MAX_FRAME_BYTES
+ * (backend/main.py, 32 KB). Base64 alone inflates by a third, so the real
+ * limit is a BYTE budget on the wire and a character count is only an
+ * approximation of it.
+ *
+ * This is the same arithmetic files/chunker.js does for RELAY_CHUNK_BYTES, and
+ * it is here for the same reason: a hand-tuned second number drifts out of
+ * sync with the relay's cap, and the failure mode is silent.
+ *
+ * It had. MAX_CHARS was 50,000 — 66 KB on the wire against a 32 KB frame — and
+ * the constant cited FR-2.8 while contradicting it, because "max payload 32 KB"
+ * had been transcribed into a character count once and never recomputed. Every
+ * clip over ~24 KB was accepted by the editor, encrypted, sent, and dropped by
+ * the relay, with the rejection arriving as an async `error` frame long after
+ * the UI had said it went. Deriving the number is what stops that recurring;
+ * tests/unit/clipsize.mjs is what proves the derivation.
+ *
+ * MAX_CHARS is what the counter shows and what the editor guards on, because
+ * users think in characters and one ASCII character is one byte. MAX_BYTES is
+ * the truth, and is what the send path enforces: 24,000 CJK characters are
+ * 72,000 bytes and will not fit, whatever the counter says.
+ */
+const RELAY_FRAME_BYTES  = 32 * 1024;   // backend/main.py MAX_FRAME_BYTES
+const CLIP_ENVELOPE_BYTES = 512;        // {"t","originId","iv","payload"} + slack
+const BASE64_EXPANSION    = 4 / 3;
+const GCM_TAG_BYTES       = 16;
+
+const CLIP_MAX_BYTES = Math.floor(
+  (RELAY_FRAME_BYTES - CLIP_ENVELOPE_BYTES) / BASE64_EXPANSION - GCM_TAG_BYTES,
+);
+
+/**
+ * Wire size of a string. Exported beside the limit it is measured against so
+ * the editor and the send path cannot disagree about what "too big" means —
+ * `String.length` counts UTF-16 units, which is not what the relay counts.
+ */
+export const textBytes = (s) => new TextEncoder().encode(s).length;
+
+export const TEXT = {
+  MAX_BYTES: CLIP_MAX_BYTES,                          // the wire limit — authoritative
+  MAX_CHARS: Math.floor(CLIP_MAX_BYTES / 1000) * 1000, // the friendly one, for the counter
+  SUPPRESS_MS: 1500,          // loop-suppression window after applying a remote clip (FR-2.6)
+};
+
+export const FILES = {
+  MAX_BYTES: 5 * 1024 * 1024, // 5 MB per file (FR-7.1)
+  MAX_COUNT: 20,              // per session, memory only (FR-7.7)
+  THUMB_PX: 160,              // longest edge (FR-7.2)
+  THUMB_QUALITY: 0.7,
+  /**
+   * Chunk size for the P2P data channel, which carries raw binary.
+   *
+   * The relay fallback CANNOT use this value directly: a chunk there is
+   * base64'd inside a JSON frame, and base64 (plus the AES-GCM tag and the
+   * envelope fields) inflates it by roughly a third — a 32 KB chunk becomes a
+   * ~44 KB frame and is rejected by the relay's own 32 KB cap. The relay chunk
+   * size is therefore DERIVED from this, in files/chunker.js as
+   * RELAY_CHUNK_BYTES, rather than being a second hand-tuned number that could
+   * drift out of sync with it.
+   */
+  CHUNK_BYTES: 32 * 1024,
+
+  /**
+   * How long a file request lives before both ends give up on it.
+   *
+   * Both ends, deliberately: the holder's prompt counts down to a denial and
+   * the requester stops waiting, on the same number, so neither is left
+   * believing in a transfer the other has already abandoned. Approving into a
+   * peer that gave up thirty seconds ago sends 5 MB nowhere.
+   *
+   * Its own constant rather than a multiple of the ICE timeout, which is what
+   * it used to be. That coupling meant shortening the ICE race in a test also
+   * shortened how long a human had to answer a dialog, and tuning the network
+   * silently retuned the UI.
+   */
+  REQUEST_TIMEOUT_MS: 15_000,
+
+  /**
+   * How long the sender waits for a data channel it has closed to confirm the
+   * close, before dropping the peer connection out from under it.
+   *
+   * bufferedAmount reaching zero only means SCTP accepted the bytes, not that
+   * the peer has them. The stream reset dc.close() sends is ordered behind the
+   * data already queued on that stream, so the close event is the nearest thing
+   * the transport offers to a delivery signal — worth one round trip. Bounded,
+   * because a wedged association must not hold a finished transfer open.
+   */
+  CHANNEL_CLOSE_MS: 1_000,
+};
+
+export const KEY = {
+  // Crockford-ish: no 0/O, no 1/I/L. Ambiguity here becomes a support ticket.
+  ALPHABET: "23456789ABCDEFGHJKMNPQRSTVWXYZ",
+  LENGTH: 6,                  // PRD D3
+  LONG_LENGTH: 10,            // "high security" option
+};
+
+export const CRYPTO = {
+  SALT: "realtimeclipboard-v1",
+  ITERATIONS: 250_000,        // PBKDF2; derive once per session and cache (OI-8)
+  ROOM_HASH_BYTES: 16,
+
+  /**
+   * Locked sessions — see LOCK below and core/crypto.js `deriveLocked`.
+   *
+   * The salt is a PREFIX, completed with the share key: the key is random per
+   * session, which is exactly what a salt is for. The open-session salt above
+   * is one global constant, so a single precomputed table covers every user on
+   * earth; here an attacker has to build one per key.
+   *
+   * 600k rather than 250k because the threat is different. An open session's
+   * secret is a 29-bit key an attacker has to guess; a locked session's secret
+   * is a PIN held by someone who may ALREADY have the link, so the PIN is the
+   * whole defence and every doubling of the iteration count is a doubling of
+   * their cost. It is paid once per session, behind the "unlocking" state.
+   */
+  LOCK_SALT: "realtimeclipboard-lock-v1:",
+  LOCK_ITERATIONS: 600_000,
+
+  /**
+   * HKDF info strings: one PBKDF2 run, three independent outputs.
+   *
+   * Asking PBKDF2 itself for 64 bytes would cost DOUBLE — it reruns the full
+   * iteration count per 32-byte output block, and OI-8 already flags PBKDF2
+   * cost on a low-end Android. HKDF expansion is a couple of HMACs.
+   */
+  LOCK_INFO: {
+    AES:  "realtimeclipboard-lock/aes",
+    ROOM: "realtimeclipboard-lock/room",
+    AUTH: "realtimeclipboard-lock/auth",
+  },
+};
+
+/**
+ * Locked sessions: the share key in the link, a PIN that never travels with it.
+ *
+ * The key is a bearer credential (PRD §7.1) and a link is a leaky thing — it
+ * gets forwarded, screenshotted, pasted into a group chat. A locked session
+ * adds a second secret that is never in the URL, never on disk, and never sent
+ * to the relay, so holding the link is not sufficient to read the clipboard.
+ *
+ * MIN_PIN is 6 and the PIN is free-form rather than 4-6 digits, because against
+ * someone who already has the link the key contributes nothing and the PIN is
+ * the entire secret: a 4-digit PIN is ~13 bits, which is minutes of offline
+ * guessing. The dialog states the number rather than an adjective.
+ */
+export const LOCK = {
+  MIN_PIN: 6,
+
+  /**
+   * Fragment marker: `#!ABCDEF`. That a session is locked is not a secret — the
+   * PIN is — and the app has to know before it connects, so the flag rides in
+   * the link. Leading rather than trailing: chat clients that trim punctuation
+   * off a pasted URL trim the END of it.
+   */
+  SIGIL: "!",
+
+  /**
+   * Sent once on creating a locked room, retained by the relay as the room's
+   * last clip and replayed to every joiner — so a joiner can tell "wrong PIN"
+   * from "first one here" by whether it decrypts. Receivers drop it instead of
+   * rendering it. See core/crypto.js and the beacon note in main.js.
+   */
+  BEACON: String.fromCharCode(0) + "realtimeclipboard-lock-v1",
+
+  /**
+   * Sent into the room being ABANDONED when the session is locked.
+   *
+   * Locking is a room change (see main.js): the lock flag is part of the room
+   * name, so the locking device leaves for a new, locked room and everyone
+   * else is simply left behind in the old one — connected, in sync with
+   * nobody, with no way to tell that from a quiet afternoon. This sentinel is
+   * the goodbye. A device that decrypts it closes its connection and says what
+   * happened, which is the difference between being removed and being
+   * mysteriously alone.
+   *
+   * A clip rather than a new frame type, for the same reason BEACON is one: it
+   * needs no relay change, so it works against a deployed relay, and it is
+   * sealed with the room key — the relay forwards a sentinel it cannot read.
+   *
+   * It does overwrite the room's retained last clip (backend `room.last`), and
+   * that is deliberate: the retained copy is what a late joiner to the dead
+   * room receives, so they are told the session moved instead of being handed
+   * a clip from a session they are no longer part of.
+   */
+  EVICT: String.fromCharCode(0) + "realtimeclipboard-lock-evict-v1",
+
+  /**
+   * How long the goodbye gets to leave the machine before the socket is torn
+   * down under it.
+   *
+   * Not paranoia about WebSocket buffering — the SSE fallback batches upstream
+   * frames into a POST and its close() drops whatever is still queued
+   * (transport/sse.js), so closing in the same tick would send the sentinel to
+   * nobody on exactly the network where the fallback is in use. A quarter of a
+   * second, once, in a flow that is already opening a dialog.
+   */
+  EVICT_FLUSH_MS: 250,
+};
+
+export const NET = {
+  HEARTBEAT_MS: 30_000,       // must beat proxy idle reaping (PRD 5.4, FR-3.6)
+  BACKOFF_MIN_MS: 1_000,
+  BACKOFF_MAX_MS: 30_000,
+  ICE_TIMEOUT_MS: 5_000,      // then fall back to relay chunks (FR-7.6)
+
+  /**
+   * How long a transport gets to become usable before we give up on it.
+   *
+   * A blocked WebSocket frequently does NOT fail: an intercepting proxy accepts
+   * the TCP connection, swallows the Upgrade, and leaves the socket hanging
+   * with no open, no close and no error — forever. Without this timer the app
+   * sits on "Connecting…" indefinitely and never tries the fallback, which is
+   * the exact failure this whole path exists for.
+   *
+   * Generous enough to survive a scale-to-zero cold start (PRD R2), which is
+   * seconds rather than milliseconds.
+   */
+  PROBE_MS: 8_000,
+
+  /**
+   * Consecutive attempts that never became usable before switching transport.
+   *
+   * Two, not one: a single failure is far more often a cold start or a flaky
+   * moment than a policy, and switching on it would put users on the slower
+   * path for no reason. Two failures in a row is a proxy.
+   */
+  SWITCH_AFTER: 2,
+
+  /** Frames per upstream POST, and the byte budget for one (SSE path). */
+  POST_MAX_FRAMES: 16,
+  POST_MAX_BYTES: 256 * 1024,
+
+  /** How long the remembered transport choice is trusted. */
+  TRANSPORT_MEMORY_MS: 12 * 60 * 60 * 1000,
+};
+
+export const POLL_OPTIONS = { "Off": 0, "500ms": 500, "1s": 1000, "2s": 2000 };
+
+/**
+ * How much of the OS clipboard the app takes on itself.
+ *
+ *   live   — anything you copy anywhere is picked up when this window has
+ *            focus, and sent. The default, and what "shared clipboard" means.
+ *   manual — nothing leaves this machine until you paste it in here or press
+ *            Send. Receiving is unaffected.
+ *
+ * Manual exists because "live" means every password, token and private
+ * message you copy for any reason goes to every device in the session. That is
+ * the point of the product, and it is also a lot of trust to extend
+ * permanently — someone on a shared or work machine may want the sharing to be
+ * a deliberate act.
+ */
+export const SYNC_MODES = {
+  LIVE: "live",
+  MANUAL: "manual",
+};
+export const DEFAULT_SYNC_MODE = SYNC_MODES.LIVE;
+
+/**
+ * The project's own addresses: where the code is, and where it asks for help.
+ *
+ * Derived from OWNER/NAME rather than written out four times, for the same
+ * reason RELAY_HTTP_URL is derived from RELAY_URL — a fork, a rename, or a
+ * moved account is then one edit, and the four links cannot drift into pointing
+ * at three different projects.
+ *
+ * Every link below was checked against a live GitHub on 2026-08-07 and returned
+ * 200: the repo, the issue chooser, and the sponsors page. Re-check the sponsors
+ * page if the account ever moves — a donate link that 404s costs more goodwill
+ * than no donate link. The .github/FUNDING.yml button is the same destination
+ * and has to move with it.
+ */
+export const REPO = {
+  OWNER: "akshaynikhare",
+  NAME: "RealtimeClipboard",
+};
+
+export const LINKS = {
+  REPO:    `https://github.com/${REPO.OWNER}/${REPO.NAME}`,
+  ISSUES:  `https://github.com/${REPO.OWNER}/${REPO.NAME}/issues`,
+  /**
+   * The chooser, not a blank issue: "report" that lands on a list of other
+   * people's bugs asks the user to find the button themselves, and a blank box
+   * asks them to guess what we need.
+   *
+   * `/new/choose` picks between the bug and feature forms in
+   * .github/ISSUE_TEMPLATE/ — which is also where the "do not paste your share
+   * key" warning lives, and that warning is the single most valuable thing on
+   * the page for this product.
+   */
+  NEW_ISSUE: `https://github.com/${REPO.OWNER}/${REPO.NAME}/issues/new/choose`,
+  SPONSOR: `https://github.com/sponsors/${REPO.OWNER}`,
+};
+
+export const IMAGES = {
+  /** Clipboard image types we will read and share. */
+  TYPES: ["image/png", "image/jpeg", "image/webp", "image/gif"],
+  /** Named so a received screenshot does not land as "blob" on disk. */
+  NAME_PREFIX: "clipboard-image",
+};