realtimeclipboard 0.3.0 → 0.5.0

package/src/core/storage.js

@@ -28,15 +28,12 @@ export const saveSettings = s => write("settings", s);
 
 /**
  * The relay this device talks to, when it is not the one the build ships with.
+ * config.js reads this key directly at module evaluation, because the URL has to
+ * resolve before anything imports it; this pair is for changing it afterwards.
  *
- * A preference, not session content, so it belongs here — nothing about a clip
- * or a key is being written. core/config.js READS this key directly at module
- * evaluation, because the URL has to be resolved before anything imports it;
- * this pair is for changing it afterwards.
- *
- * Normalised on the way in as well as on the way out. A value that got into
- * storage malformed would otherwise be re-read as malformed on every launch,
- * and the symptom — every connection refused — looks nothing like its cause.
+ * Normalised on the way in as well as out — a malformed stored value would
+ * otherwise be re-read as malformed on every launch, and the symptom (every
+ * connection refused) looks nothing like its cause.
  */
 export const loadRelayUrl = () => normaliseRelay(read("relayUrl", null));
 
@@ -48,14 +45,11 @@ export function saveRelayUrl(url) {
 }
 
 /**
- * The last room, so a relaunch can offer it back (FR-1.7, OI-10).
- *
- * Stores `{key, locked}` since locked sessions exist; it used to be a bare
- * string and still reads one, because an upgrade must not strand somebody in
- * "no room at all" on their first load of the new build.
+ * The last room, so a relaunch can offer it back (FR-1.7, OI-10). Stores
+ * `{key, locked}` and still reads the bare string it used to be, because an
+ * upgrade must not strand somebody in "no room at all".
  *
- * The lock FLAG is remembered here, in localStorage. The PIN is not, and never
- * will be — see saveLock below.
+ * The lock FLAG is remembered here. The PIN is not — see saveLock.
  */
 export function loadLastKey() {
   const saved = read("lastKey", null);
@@ -65,16 +59,61 @@ export function loadLastKey() {
     : { key: saved.key ?? null, locked: !!saved.locked };
 }
 
-export const saveLastKey = (key, locked = false) => write("lastKey", { key, locked });
+/**
+ * !! This is the share key in plain text, on disk, and it is the one store in
+ * this file that holds a secret rather than a preference. Anything running in
+ * the document reads it — including a third-party tag, which is why enabling
+ * AdSense is gated on this being opt-in rather than automatic. See
+ * docs/ARCHITECTURE.md §5. !!
+ *
+ * `remember` is the user's setting. False removes the record rather than merely
+ * declining to write one: turning the switch off has to forget the key already
+ * saved, or the setting only governs sessions you have not had yet.
+ */
+export function saveLastKey(key, locked = false, remember = true) {
+  if (!remember) { remove("lastKey"); return false; }
+  return write("lastKey", { key, locked });
+}
+
+export const forgetLastKey = () => remove("lastKey");
 
 /**
- * Which transport last worked (see transport/relay.js).
+ * The key for THIS tab, so a reload survives the fragment being cleared.
  *
- * Remembered because probing costs the user real seconds of "Connecting…" on
- * every load behind a proxy that blocks WebSockets, and the answer there is the
- * same every time. Expired rather than permanent because it is a fact about the
- * *network*, not the device: a laptop that leaves the office should go back to
- * the faster transport on its own, without anyone knowing there was a setting.
+ * The fragment used to be the memory: the key sat in `location.hash` for the
+ * lifetime of the session and boot() read it back. That put it in the address
+ * bar, in screen shares, in screenshots, and — the reason it moved — in reach of
+ * every script in the document, which now includes tags this repository does not
+ * write. main.js clears the fragment the moment it has been read, and this is
+ * what makes a refresh still work.
+ *
+ * sessionStorage, not localStorage: a reload is the same session, a new tab is
+ * not, and closing the tab should end it. Surviving a browser restart is what
+ * `lastKey` above is for, and that one is the user's choice.
+ */
+export function loadSessionKey() {
+  try {
+    const saved = JSON.parse(sessionStorage.getItem(PREFIX + "sessionKey") || "null");
+    return saved?.key ? { key: saved.key, locked: !!saved.locked } : null;
+  } catch { return null; }
+}
+
+export function saveSessionKey(key, locked = false) {
+  try {
+    sessionStorage.setItem(PREFIX + "sessionKey", JSON.stringify({ key, locked }));
+    return true;
+  } catch { return false; }
+}
+
+export function clearSessionKey() {
+  try { sessionStorage.removeItem(PREFIX + "sessionKey"); } catch { /* nothing to do */ }
+}
+
+/**
+ * Which transport last worked (transport/relay.js). Remembered because probing
+ * costs real seconds of "Connecting…" behind a proxy that blocks WebSockets.
+ * Expired rather than permanent because it is a fact about the *network*: a
+ * laptop leaving the office should return to the faster transport on its own.
  */
 export function loadTransport() {
   const saved = read("transport", null);
@@ -88,12 +127,11 @@ export function saveTransport(mode) {
 }
 
 /**
- * A transport the user picked by hand, which outranks anything measured.
- *
- * Kept apart from the remembered-working one above because they answer
- * different questions — "what worked last time" is an observation and expires;
- * "use HTTP" is an instruction and does not. Merging them would let a
- * successful automatic connection quietly overwrite a deliberate choice.
+ * A transport the user picked by hand, which outranks anything measured. Kept
+ * apart from the remembered-working one because they answer different questions:
+ * "what worked last time" is an observation and expires, "use HTTP" is an
+ * instruction and does not. Merged, a successful auto-connect would quietly
+ * overwrite a deliberate choice.
  */
 export const loadTransportChoice = () => read("transportChoice", null);
 
@@ -102,20 +140,15 @@ export function saveTransportChoice(mode) {
   write("transportChoice", mode);
 }
 
-/* ------------------------------------------------------------------
-   Session-scoped file allowances
-
-   sessionStorage, not localStorage, and this is the whole point of them: "allow
-   everything from this device" is a decision about the session you are in, and
-   it has to die with the tab. A permanent version of this setting is a standing
-   grant to whoever holds the share key, made once and then forgotten about.
-
-   Scoped to a room as well as a tab. The key is a bearer credential and rooms
-   are named after it, so an allowance granted in one session must not survive
-   into another — rotating the key is how someone throws a device out, and it
-   would be worth nothing if the allowance came along.
-------------------------------------------------------------------- */
-
+/**
+ * Session-scoped file allowances.
+ *
+ * sessionStorage is the whole point: "allow everything from this device" is a
+ * decision about the session you are in and has to die with the tab, or it is a
+ * standing grant to whoever holds the share key. Scoped to a room as well —
+ * rotating the key is how someone throws a device out, and it would be worth
+ * nothing if the allowance came along.
+ */
 export function loadAllowances(room) {
   if (!room) return [];
   try {
@@ -132,36 +165,22 @@ export function saveAllowances(room, peers) {
   } catch { return false; }
 }
 
-/* ------------------------------------------------------------------
-   The locked-session unlock, scoped to this tab
-
-   Two decisions here, both deliberate.
-
-   WHAT is stored is the PBKDF2 output, never the PIN. It unlocks exactly the
-   same room, so this is not a security improvement in itself — the point is
-   that a PIN is a human-chosen secret and humans reuse them. The string the
-   user typed should not be sitting in a browser store waiting to be read by
-   the next thing that gets to run in this origin. The derived value is useless
-   anywhere else, and reading it back skips 600k PBKDF2 iterations, so a refresh
-   is instant instead of a second of "Unlocking…".
-
-   WHERE is sessionStorage, for the same reason the file allowances above use
-   it: a refresh is the same session and must not re-prompt, but the tab closing
-   is the end of it. localStorage would put the unlock on disk next to the
-   plaintext key — at which point the link and the PIN are stored together and
-   the second secret has bought nothing.
-
-   Scoped to the share key, so rotating the key invalidates it automatically.
-------------------------------------------------------------------- */
-
 /**
- * The remembered unlock for a share key, or null.
+ * The locked-session unlock, scoped to this tab.
+ *
+ * WHAT is the PBKDF2 output, never the PIN. It unlocks the same room, so this is
+ * not a security win in itself — the point is that PINs are human-chosen and
+ * reused, and the typed string should not sit in a browser store. Reading it
+ * back skips 600k iterations, so a refresh is instant.
+ *
+ * WHERE is sessionStorage: a refresh is the same session and must not re-prompt,
+ * but the tab closing ends it. localStorage would put the unlock on disk beside
+ * the plaintext key, at which point the second secret has bought nothing.
  *
- * Matched on the KEY rather than on the room, and that is not interchangeable.
- * The room hash of a locked session is derived from the stretched PIN alone, so
- * a record left behind by a previous key would still look perfectly
- * self-consistent and would silently reconnect this tab to a room the current
- * link does not name. The key is the thing that has to agree.
+ * Matched on the KEY, not the room, and those are not interchangeable: a locked
+ * room hash derives from the stretched PIN alone, so a record left by a previous
+ * key would look self-consistent and silently reconnect this tab to a room the
+ * current link does not name.
  */
 export function loadLock(key) {
   if (!key) return null;

package/src/core/text.js

@@ -0,0 +1,51 @@
+/**
+ * Characters that let a string lie about what it is.
+ *
+ * One definition, because there are three places that need it and a security
+ * character class that drifts between them is worse than one that is wrong
+ * everywhere — at least the second is visible. The callers:
+ *
+ *   clipboard/guard.js   an arriving clip, before it reaches the OS clipboard
+ *   files/registry.js    a peer-supplied filename, before it reaches a download
+ *   cli/                 clip text, before it reaches a terminal (which adds
+ *                        escape SEQUENCES on top of these single characters)
+ *
+ * `clipboard/` and `files/` are peers and may not import each other, and `cli/`
+ * ships only `src/core/` and `src/transport/`. Rank 0 is the one place all
+ * three can reach.
+ *
+ * The ranges, and why each is here:
+ *
+ *   U+0000-0008, U+000B-001F, U+007F-009F   C0/C1 controls. A bare CR (U+000D)
+ *       returns a terminal's cursor to the start of the line, so what is
+ *       rendered is the tail of a string written over the head of it. NUL
+ *       truncates in anything that reaches C.
+ *   U+200E/200F, U+202A-202E, U+2066-2069   bidi marks, overrides and isolates.
+ *       These reverse rendered order: `invoice[RLO]txt.exe` displays as
+ *       `invoiceexe.txt`, and the extension you see is not the one that runs.
+ *
+ * TAB (U+0009) and LF (U+000A) fall inside those ranges and are deliberately
+ * excluded: both are ordinary text and neither hides anything. A filename has no
+ * business containing either, but that is a filename rule, not a text rule —
+ * files/registry.js applies it.
+ *
+ * Written as escapes, never as literals. A literal control character in source
+ * is invisible in a diff, which is the property being defended against.
+ */
+const INVISIBLE = "[\\u0000-\\u0008\\u000B-\\u001F\\u007F-\\u009F"
+                + "\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u2069]";
+
+/** The class itself, for a caller building a larger pattern around it. */
+export const INVISIBLE_SOURCE = INVISIBLE;
+
+// Two objects, and the second has no /g on purpose: test() on a global regex
+// advances lastIndex, so it answers differently every other call. That bug is
+// silent, intermittent, and exactly the kind a security check must not have.
+const STRIP = new RegExp(INVISIBLE, "g");
+const DETECT = new RegExp(INVISIBLE);
+
+export const stripInvisible = s =>
+  (typeof s === "string" ? s.replace(STRIP, "") : "");
+
+export const hasInvisible = s =>
+  typeof s === "string" && DETECT.test(s);

package/src/transport/protocol.js

@@ -8,6 +8,7 @@
 export const T = {
   HELLO:   "hello",
   CLIP:    "clip",
+  STREAM:  "stream",
   PING:    "ping",
   PONG:    "pong",
   WELCOME: "welcome",
@@ -33,6 +34,24 @@ export const clip = ({ payload, iv, originId }) => ({
   t: T.CLIP, payload, iv, originId, ts: Date.now(),
 });
 
+/**
+ * Typing, for the far editor to render — a VIEW frame:
+ *
+ *   clip   — a discrete thing that settled. History, OS clipboard, dedupe, size
+ *            cap. Retained by the relay and replayed to late joiners (FR-3.3).
+ *   stream — what the text looks like right now. Renders and nothing else.
+ *
+ * Carries the WHOLE text rather than a diff, which is what lets live typing
+ * exist without positions or operational transform, bounded by
+ * TEXT.STREAM_MAX_BYTES. `name` rides along because nothing replays these, so a
+ * device joining mid-sentence would otherwise render an unattributed caret.
+ *
+ * Everything but `t` and `originId` is sealed by main.js encryptFrame().
+ */
+export const stream = ({ text, caret, name, originId }) => ({
+  t: T.STREAM, text, caret, name, originId,
+});
+
 export const ping = () => ({ t: T.PING });
 
 export const fileMeta = ({ id, name, size, type, thumb, originId }) => ({
@@ -54,15 +73,12 @@ export const ERRORS = {
   ROOM_FULL:    "This session already has the maximum number of devices",
   BAD_JSON:     "The relay sent something unreadable",
   NO_STREAM:    "The connection expired — reconnecting",
-  // Only ever shown after the transport has given up retrying: the usual cause
-  // is our own just-closed connection still holding the name, which clears on
-  // its own. See relay.js reclaimIdentity().
+  // Only shown after the transport gives up retrying — the usual cause is our
+  // own just-closed connection still holding the name. See reclaimIdentity().
   PEER_ID_TAKEN: "Another device in this session is using the same id — files may not reach this one",
-  // Locked sessions. In practice unreachable from a correct client: a locked
-  // room's name is derived from the PIN, so a device that got the PIN wrong is
-  // addressing a different room entirely rather than being turned away from
-  // this one. It fires if a client's room derivation and key derivation ever
-  // disagree — which is a bug, and this is how it surfaces instead of a
-  // session that connects and then reads nothing.
+  // Unreachable from a correct client: a wrong PIN addresses a different room
+  // entirely rather than being turned away from this one. It fires if room and
+  // key derivation ever disagree, which is a bug, and this is how it surfaces
+  // instead of a session that connects and then reads nothing.
   AUTH_FAILED:  "This session's PIN does not match the one already in use here",
 };

package/src/transport/relay.js

@@ -1,32 +1,20 @@
 /**
  * The relay connection: protocol, liveness, and which transport carries it.
  *
- * Everything above this file (main.js, and through it the whole app) sees one
- * interface — connect / send / close / isOpen / setFrameHandler — and never
- * learns how the bytes actually leave the machine. That boundary was designed
- * in from the start (PRD §4.3, docs/ARCHITECTURE.md §3) against the risk that
- * the deployed relay would not pass WebSocket upgrades. It turned out to be
- * needed for a different reason: the *client's* network.
- *
- * On a managed corporate network — the primary deployment context (PRD §5.4) —
- * a TLS-inspecting proxy may refuse the HTTP Upgrade that a WebSocket needs, or
- * accept the connection and then swallow it, leaving a socket that never opens
- * and never closes. So the transport is not a build-time decision:
+ * Everything above sees one interface — connect / send / close / isOpen /
+ * setFrameHandler — and never learns how the bytes leave the machine. Designed
+ * against the risk that the deployed relay would not pass WebSocket upgrades; it
+ * turned out to be needed for the *client's* network instead, where a
+ * TLS-inspecting proxy may refuse the Upgrade or accept and then swallow it.
  *
  *   1. Try WebSocket. Give it NET.PROBE_MS to become usable.
  *   2. Two consecutive attempts that never become usable is a policy, not a
- *      flaky moment — switch to SSE+POST, which is plain HTTP and needs no
- *      Upgrade, and say so out loud.
- *   3. If that is blocked too, keep alternating rather than giving up on one:
- *      a network that refuses both is a different problem, and the user is told
- *      exactly that instead of watching "Reconnecting" forever.
- *
- * The choice is remembered (storage.js), so someone behind that proxy pays the
- * probe once rather than on every load, and re-probes when the memory expires
- * or they move to another network.
+ *      flaky moment — switch to SSE+POST and say so out loud.
+ *   3. If that is blocked too, keep alternating: a network refusing both is a
+ *      different problem, and the user is told that rather than watching
+ *      "Reconnecting" forever.
  *
- * The two channels live in ws.js and sse.js and implement one contract. All the
- * protocol handling, heartbeat and backoff is here, once, for both.
+ * The choice is remembered, so someone behind that proxy pays the probe once.
  */
 
 import { RELAY_URL, NET, TRANSPORT } from "../core/config.js";
@@ -72,14 +60,11 @@ let probe = null;
 let pingSentAt = 0;
 
 /**
- * Which attempt is the current one.
- *
- * Rejoining, rotating the key and recovering from a collision all close the
- * connection and open a new one — while a reconnect timer from the old one may
- * still be pending. Without a generation to compare against, that timer wakes
- * up, sees `wantOpen`, and opens a second connection alongside the live one:
- * the user is in the room twice, sees their own clips echoed back, and one of
- * the two sockets is unreachable by anything. Every callback and timer below
+ * Which attempt is the current one. Rejoin, rotate and collision recovery all
+ * close and reopen while a reconnect timer from the old attempt may still be
+ * pending — without a generation to compare, that timer wakes, sees `wantOpen`,
+ * and opens a second connection alongside the live one: the user is in the room
+ * twice and sees their own clips echoed back. Every callback and timer below
  * captures this and does nothing if it has moved on.
  */
 let epoch = 0;
@@ -88,10 +73,9 @@ let epoch = 0;
 export const transport = () => mode;
 
 /**
- * `auth` is a locked session's admission token (core/crypto.js `deriveLocked`).
- * It is HKDF output, not the PIN and not the key — the relay can check that two
- * peers agree without being able to reverse it into either. Absent for open
- * sessions, and a relay that predates it ignores the parameter.
+ * `auth` is a locked session's admission token — HKDF output, not the PIN and
+ * not the key, so the relay can check that two peers agree without being able to
+ * reverse it into either. A relay that predates it ignores the parameter.
  */
 export function connect({ roomHash, intent = "join", url = RELAY_URL, name = "", auth = null }) {
   channel?.close(1000);            // a second connect() replaces, never stacks
@@ -118,22 +102,13 @@ export function close() {
 
 export const isOpen = () => channel?.isOpen() === true;
 
-/* ------------------------------------------------------------------
-   transport selection
-------------------------------------------------------------------- */
+/* ---- transport selection ---- */
 
 /**
- * Where to start.
- *
- * A hand-picked transport wins outright, and never expires — it is an
- * instruction, not a measurement. Failing over would undo it, so a forced
- * transport keeps retrying itself and the status bar says it is locked.
- *
- * Failing that, a remembered choice: on a network that blocks WebSockets,
- * re-probing costs NET.PROBE_MS of "Connecting…" on every single load and the
- * answer is the same every time. storage.js expires that memory on its own, so
- * moving off that network re-probes rather than pinning the user to the slower
- * transport forever.
+ * A hand-picked transport wins outright and never expires — it is an
+ * instruction, not a measurement. Failing that, a remembered choice: re-probing
+ * costs NET.PROBE_MS of "Connecting…" on every load and the answer is the same
+ * every time. storage.js expires that memory, so moving network re-probes.
  */
 function preferred() {
   if (forced && CHANNELS[forced]?.available()) return forced;
@@ -143,12 +118,10 @@ function preferred() {
 }
 
 /**
- * Pin the transport, or hand it back to the app.
- *
- * Exists because "it works but it is on the slow one" and "it should be on the
- * slow one and is not" both need an answer a user can act on, and because
- * reproducing a blocked network to test the fallback otherwise means finding a
- * blocked network. `null` means auto.
+ * Pin the transport, or hand it back to the app. Exists because "it works but it
+ * is on the slow one" and "it should be on the slow one and is not" both need an
+ * answer a user can act on — and because reproducing a blocked network to test
+ * the fallback otherwise means finding a blocked network. `null` means auto.
  */
 export function setTransport(choice) {
   const next = choice === TRANSPORT.WS || choice === TRANSPORT.SSE ? choice : null;
@@ -160,8 +133,8 @@ export function setTransport(choice) {
 
   if (!wantOpen || !session) return announce();
 
-  // Reconnect now rather than at the next drop: the point of choosing is to
-  // see the choice take effect.
+  // Reconnect now rather than at the next drop: the point of choosing is to see
+  // the choice take effect.
   channel?.close(1000);
   channel = null;
   stopTimers();
@@ -177,9 +150,8 @@ export function setTransport(choice) {
 export const transportChoice = () => forced;
 
 function switchTransport() {
-  // A forced transport does not fail over. Someone asked for this one
-  // specifically, and silently moving them off it is exactly the behaviour the
-  // switch was added to be able to override.
+  // A forced transport does not fail over: silently moving someone off it is
+  // exactly what the switch was added to override.
   if (forced) return;
 
   const next = OTHER[mode];
@@ -189,9 +161,8 @@ function switchTransport() {
   failures[next] = 0;
   backoff = NET.BACKOFF_MIN_MS;    // the switch is a fresh start, not a retry
 
-  // Loud, never silent — the same rule the file layer follows when a P2P
-  // transfer falls back to the relay (FR-7.6). The fallback is slower and the
-  // user is entitled to know which pipe their clipboard is going down.
+  // Loud, never silent — the same rule the file layer follows on P2P fallback
+  // (FR-7.6). The user is entitled to know which pipe their clipboard goes down.
   emit(EV.TOAST, next === TRANSPORT.SSE
     ? "WebSocket blocked — switched to the HTTP fallback"
     : "Retrying the WebSocket connection");
@@ -211,20 +182,16 @@ function announce() {
     mode: stuck ? null : mode,
     label: CHANNELS[mode].LABEL,
     blocked: stuck,
-    // What the picker in the status bar shows as selected. `mode` is what is
-    // actually carrying frames right now; this is what the user asked for, and
-    // on auto they are not the same question.
+    // `mode` is what carries frames now; this is what the user asked for. On
+    // auto they are not the same question.
     forced,
     // "the relay is old" and "the network is blocking us" present identically
-    // and have opposite fixes, so the UI is given the difference rather than a
-    // single sentence that has to cover both.
+    // and have opposite fixes.
     unsupported,
   });
 }
 
-/* ------------------------------------------------------------------
-   one attempt
-------------------------------------------------------------------- */
+/* ---- one attempt ---- */
 
 function start() {
   stopTimers();
@@ -243,11 +210,9 @@ function start() {
     onDown: current(down),
   });
 
-  // A blocked transport does not always fail — it hangs. An intercepting proxy
-  // can accept the connection, drop the Upgrade (or buffer the event stream)
-  // and then do nothing at all, with no error to react to. Without this timer
-  // the app sits on "Connecting…" indefinitely and the fallback never runs,
-  // which is the whole failure this file exists to handle.
+  // A blocked transport hangs rather than fails, so there is no error to react
+  // to — only this timer notices. See transport/CLAUDE.md; do not replace it
+  // with an error handler.
   probe = setTimeout(() => {
     if (opened || gen !== epoch) return;
     channel?.close(4000);          // deliberate: the channel will not call down()
@@ -268,9 +233,8 @@ function up() {
   failures[mode] = 0;
 
   // Only an automatic success is evidence. A forced transport working proves
-  // nothing about what this network allows — it proves someone clicked it — and
-  // recording it would mean pinning HTTP once left "Automatic" choosing HTTP
-  // for the next twelve hours, which is the opposite of handing control back.
+  // someone clicked it, not what the network allows — recording it would mean
+  // pinning HTTP once left "Automatic" choosing HTTP for the next twelve hours.
   if (!forced) storage.saveTransport(mode);
 
   state.setConnection("connected", detail());
@@ -300,15 +264,12 @@ function down({ code, reason }) {
   }
 
   // 1012 = "service restart". Every push to main redeploys the relay and closes
-  // every live socket with this code (OI-13) — observed for real during the M0
-  // idle test. It is a planned, short outage rather than a fault, so reset the
-  // backoff and come back promptly instead of treating it like a flaky network
-  // and waiting out a doubled delay.
+  // every live socket with this code (OI-13) — a planned, short outage rather
+  // than a fault, so come back promptly instead of waiting out a doubled delay.
   if (code === 1012) backoff = NET.BACKOFF_MIN_MS;
 
   // Read before switching: switchTransport() zeroes the incoming transport's
-  // counter, so asking afterwards always says "not blocked" and the user would
-  // never be told that nothing at all is getting through.
+  // counter, so asking afterwards always says "not blocked".
   if (!opened && failures[mode] >= NET.SWITCH_AFTER) {
     if (blocked()) {
       stuck = true;
@@ -317,8 +278,7 @@ function down({ code, reason }) {
     switchTransport();
   }
 
-  // Jitter keeps a restart from producing a synchronised reconnect stampede
-  // from every client at the same instant.
+  // Jitter keeps a restart from producing a synchronised reconnect stampede.
   const wait = Math.round(backoff * (0.8 + Math.random() * 0.4));
   backoff = Math.min(backoff * 2, NET.BACKOFF_MAX_MS);
 
@@ -342,30 +302,24 @@ function stopTimers() {
 }
 
 /**
- * Status-bar text: whatever the state wants to say, plus the transport.
- *
- * "locked" is not decoration. A pinned transport does not fail over, so a user
- * who pinned WebSocket on a network that blocks it would otherwise watch an
- * endless reconnect with no hint that they are the reason.
+ * Status-bar text. "locked" is not decoration: a pinned transport does not fail
+ * over, so a user who pinned WebSocket on a network that blocks it would
+ * otherwise watch an endless reconnect with no hint that they are the reason.
  */
 const detail = (extra = "") =>
   [extra, NOTE[mode], forced ? "locked" : ""].filter(Boolean).join(" · ");
 
-/* ------------------------------------------------------------------
-   protocol
-------------------------------------------------------------------- */
+/* ---- protocol ---- */
 
 let idRetries = 0;
 
 /**
- * Our own id is still held — by the connection we just closed.
- *
- * A rejoin, a key rotation or a collision recovery reconnects within
- * milliseconds, and the relay only drops a peer once it *notices* the old
- * transport is gone. Reconnect faster than that and we meet our own ghost: the
- * relay keeps us under a provisional id, while the files layer goes on
- * addressing frames to our originId — so transfers to this device quietly stop
- * resolving. Ask again a moment later, by which time the ghost has been reaped.
+ * Our own id is still held — by the connection we just closed. A rejoin or
+ * rotation reconnects within milliseconds, and the relay only drops a peer once
+ * it notices the old transport is gone. Reconnect faster and we meet our own
+ * ghost: the relay keeps us under a provisional id while the files layer goes on
+ * addressing frames to our originId, so transfers to this device quietly stop
+ * resolving. Ask again once the ghost has been reaped.
  */
 function reclaimIdentity() {
   if (idRetries >= 3) return emit(EV.TOAST, proto.ERRORS.PEER_ID_TAKEN);
@@ -388,16 +342,13 @@ function handle(msg) {
         emit(EV.KEY_COLLISION, { existing: msg.existing });
         return;
       }
-      // A room's last clip is replayed to late joiners, so a device that
-      // arrives mid-session is immediately in sync (FR-3.3).
+      // A room's last clip is replayed to late joiners, so a device arriving
+      // mid-session is immediately in sync (FR-3.3).
       if (msg.last) onFrame(msg.last);
 
-      // What the room looked like at the moment we arrived. main.js needs both
-      // halves and can infer neither: a locked session plants its beacon only
-      // into a room that is empty AND has no retained clip, because the beacon
-      // is a clip and would otherwise overwrite the very thing the line above
-      // exists to deliver. Emitted after the replay so a listener that reacts
-      // to it cannot race the last clip.
+      // Both halves, because main.js can infer neither: a locked session plants
+      // its beacon only into a room that is empty AND has no retained clip.
+      // Emitted after the replay so a listener cannot race the last clip.
       emit(EV.ROOM_STATE, { existing: msg.existing ?? 0, hasLast: msg.last != null });
       break;