realtimeclipboard 0.3.0 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 # 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
+same short 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.
 
@@ -28,7 +28,8 @@ is proven, and [Known limitations](#known-limitations) for what is not.
 
 - **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
+- **No account, no sign-up, no email** — a short key is the whole identity of a session
+  (six characters on the web, ten in the installed apps, and either works on both)
 - **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
@@ -40,7 +41,7 @@ is proven, and [Known limitations](#known-limitations) for what is not.
 
 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.
+admin rights, or an email to yourself. This wants a short key.
 
 ## How RealtimeClipboard compares to Snapdrop, PairDrop, LocalSend and AirDrop
 
@@ -85,7 +86,7 @@ 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
+Open RealtimeClipboard on both, type the same short 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.
 

package/cli/realtimeclipboard.mjs

@@ -55,7 +55,14 @@ const VERSION = JSON.parse(
 /* ------------------------------------------------------------------ args -- */
 
 function parse(args) {
-  const opts = { relay: null, pin: null, once: false, json: false, timeout: 0, quiet: false };
+  const opts = {
+    relay: null, pin: null, once: false, json: false, timeout: 0, quiet: false,
+    // A CLI key gets pasted into shells, scripts and CI configs, where length is
+    // friction with no QR code to fall back on — so unlike the installed desktop
+    // app this stays short unless asked. REALTIMECLIPBOARD_LONG is the way to
+    // ask once, for a machine that generates a lot of them.
+    long: !!process.env.REALTIMECLIPBOARD_LONG,
+  };
   const rest = [];
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -86,6 +93,8 @@ Options
   --relay <url>    relay to use            (default ${DEFAULT_RELAY_URL})
                    or set REALTIMECLIPBOARD_RELAY
   --pin <pin>      join a locked session   (or set REALTIMECLIPBOARD_PIN)
+  --long           new: a 10-character key (~49 bits) instead of 6 (~29 bits)
+                   or set REALTIMECLIPBOARD_LONG
   --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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtimeclipboard",
-  "version": "0.3.0",
+  "version": "0.4.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": {
@@ -34,7 +34,7 @@
     "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",
+    "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/unit/syncmode.mjs && node tests/dom/dialog.mjs && node tests/dom/whatsnew.mjs && node tests/dom/tiles.mjs && node tests/dom/guide.mjs && node tests/dom/editor.mjs && node tests/dom/offer.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",

package/src/core/bus.js

@@ -31,8 +31,18 @@ export function emit(event, payload) {
 /** 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
+  TEXT_CAPTURED:   "text:captured",    // {text, how} — a clip settled here, needs sending
+  TEXT_RECEIVED:   "text:received",    // {text, from} — a clip arrived from a peer
+  /**
+   * Typing, not clips. {text, caret} out, {text, caret, name, from} in.
+   *
+   * The pair above is the COMMIT channel: a clip that settled, bound for
+   * history, the OS clipboard and the size cap. This pair is the VIEW channel —
+   * what the text looks like mid-keystroke. Keeping them apart is what stops a
+   * streamed sentence becoming six history entries and six clipboard writes.
+   */
+  TEXT_TYPED:      "text:typed",
+  TEXT_STREAMED:   "text:streamed",
   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
@@ -70,6 +80,13 @@ export const EV = {
    * way; the bus does no namespacing of its own and a collision is silent.
    */
   LOCK_STATE:      "session:lockstate",
+  /**
+   * {required} — a locked link is open and its PIN has not been given, so there
+   * is no session and nothing behind the UI is connected to anything. Reported
+   * separately from LOCK_STATE because `state.locked` is still false at that
+   * point: no session was ever opened to be locked.
+   */
+  LOCK_REQUIRED:   "session:lockrequired",
   FOUNDER:         "session:founder",  // {founder} — first into this room? null = not yet known
 
   // files

package/src/core/config.js

@@ -3,6 +3,8 @@
  * if you find a magic number elsewhere, it belongs here.
  */
 
+import { IS_DESKTOP } from "./native.js";
+
 /**
  * Relay endpoint.
  *
@@ -153,6 +155,46 @@ 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)
+
+  /**
+   * Typing is streamed for the far editor to render; a CLIP is still a discrete
+   * thing, made when the text settles. The split is what keeps history, the OS
+   * clipboard write, the dedupe and the size cap resting on whole thoughts
+   * instead of on `h`, `he`, `hel`.
+   *
+   * COMMIT_IDLE_MS is generous because the commit is invisible: the text is
+   * already on the far screen via the stream, so this only decides when it
+   * becomes a clip. A mid-sentence thinking pause is 300-500 ms, and anything
+   * under that would fragment one sentence into six history entries.
+   */
+  COMMIT_IDLE_MS: 800,
+
+  /** 10 sends/sec — half the relay's 20/s `stream` budget, as cursors.js does. */
+  STREAM_THROTTLE_MS: 100,
+
+  /**
+   * Above this, typing is not streamed at all and the text syncs on commit only.
+   *
+   * A stream frame carries the WHOLE text, which is what lets this feature exist
+   * without diffs, positions or operational transform. That trade only holds
+   * while the text is small: re-sending 20 KB per keystroke would be 200 KB/s
+   * through the relay for one person editing a stack trace.
+   *
+   * The degradation is invisible because big text is pasted, never typed —
+   * nobody collaboratively types a stack trace — so the case streaming is for
+   * (a URL, a token, a sentence) is entirely inside this bound.
+   */
+  STREAM_MAX_BYTES: 4096,
+
+  /**
+   * How long a local copy outranks an arriving clip.
+   *
+   * Two devices in Clipboard mode both being used by a human means every copy on
+   * one overwrites the other's system clipboard, and the moment that actually
+   * hurts is "I copied something, went to paste it, and it was gone". Inside
+   * this window the arriving clip is queued and offered instead of written.
+   */
+  LOCAL_COPY_GRACE_MS: 10_000,
 };
 
 export const FILES = {
@@ -204,8 +246,19 @@ export const FILES = {
 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
+  LENGTH: 6,                  // PRD D3 — the web default
+  LONG_LENGTH: 10,            // "high security" option, PRD §7.3
+
+  /**
+   * Installed builds default to the long key; the web keeps six.
+   *
+   * PRD §7.3's argument for six characters is convenience, and the convenience
+   * is a phone keyboard. An installed app links a device by QR or by a copied
+   * link, so it is the one surface that does not pay the typing cost the short
+   * key buys — and it is the surface running unattended all day reading every
+   * copy, which is the case §7.3 says should take the 10-character option.
+   */
+  DEFAULT_LONG: IS_DESKTOP,
 };
 
 export const CRYPTO = {
@@ -351,25 +404,38 @@ export const NET = {
 export const POLL_OPTIONS = { "Off": 0, "500ms": 500, "1s": 1000, "2s": 2000 };
 
 /**
- * How much of the OS clipboard the app takes on itself.
+ * How far the sync reaches on THIS device. One ladder, three rungs, each adding
+ * exactly one thing to the one below it:
+ *
+ *   off    — nothing leaves and nothing arrives. The editor is private again.
+ *   manual — the session syncs in the app window. The OS clipboard is neither
+ *            read nor written; the app is a window onto the room.
+ *   live   — the OS clipboard is wired to the room in both directions. What you
+ *            copy anywhere goes out; what arrives is copied here.
  *
- *   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.
+ * The room itself is unconditional: every connected device sees every clip in
+ * the app view whatever rung it is on. The rung only decides how deep into the
+ * machine the connection goes, which is why the labels name the destination
+ * (Off / App / Clipboard) rather than a manner of working.
  *
- * 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.
+ * The stored strings are a compatibility surface. "live" and "manual" are on
+ * disk for every existing user under STORAGE_PREFIX, and relabelling the UI is
+ * free while renaming these silently resets the one preference where being
+ * wrong matters most. Change the labels in ui/features/syncMode.js instead.
  */
 export const SYNC_MODES = {
-  LIVE: "live",
+  OFF: "off",
   MANUAL: "manual",
+  LIVE: "live",
 };
 export const DEFAULT_SYNC_MODE = SYNC_MODES.LIVE;
 
+/** Does this rung let the OS clipboard be read or written? */
+export const bindsClipboard = (mode) => mode === SYNC_MODES.LIVE;
+
+/** Does this rung put anything on the wire at all? */
+export const sharesSession = (mode) => mode !== SYNC_MODES.OFF;
+
 /**
  * The project's own addresses: where the code is, and where it asks for help.
  *
@@ -406,6 +472,18 @@ export const LINKS = {
   SPONSOR: `https://github.com/sponsors/${REPO.OWNER}`,
 };
 
+/**
+ * The app offer in the header — the desktop build and the PWA install, sharing
+ * one quiet row (ui/features/install.js).
+ *
+ * A minute is long enough to read a sentence you did not ask for, finish the
+ * paste you came here for, and come back to it; short enough that the header is
+ * the header again by the time you next look up. Only the × is remembered — a
+ * row that timed out has not been declined, so the offer returns on a later
+ * visit.
+ */
+export const OFFER = { DISMISS_MS: 60_000 };
+
 export const IMAGES = {
   /** Clipboard image types we will read and share. */
   TYPES: ["image/png", "image/jpeg", "image/webp", "image/gif"],

package/src/core/device.js

@@ -18,16 +18,25 @@
 
 import { read, write } from "./storage.js";
 
+/**
+ * Windows | Android | iOS | macOS | Linux | Unknown.
+ *
+ * Exported because the desktop guide describes the tray icon, and the tray
+ * behaves differently enough on each platform that one paragraph covering all
+ * three would be wrong on two of them.
+ */
+export function os() {
+  const ua = globalThis.navigator?.userAgent ?? "";
+  return /Windows/i.test(ua)            ? "Windows" :
+         /Android/i.test(ua)            ? "Android" :
+         /iPhone|iPad|iPod/i.test(ua)   ? "iOS"     :
+         /Mac OS X|Macintosh/i.test(ua) ? "macOS"   :
+         /Linux/i.test(ua)              ? "Linux"   : "Unknown";
+}
+
 function detect() {
   const ua = navigator.userAgent;
 
-  const os =
-    /Windows/i.test(ua)                    ? "Windows" :
-    /Android/i.test(ua)                    ? "Android" :
-    /iPhone|iPad|iPod/i.test(ua)           ? "iOS"     :
-    /Mac OS X|Macintosh/i.test(ua)         ? "macOS"   :
-    /Linux/i.test(ua)                      ? "Linux"   : "Unknown";
-
   // Order matters: Edge and Opera both contain "Chrome", Chrome contains "Safari".
   const browser =
     /Edg\//i.test(ua)                      ? "Edge"    :
@@ -36,7 +45,7 @@ function detect() {
     /Chrome\//i.test(ua)                   ? "Chrome"  :
     /Safari\//i.test(ua)                   ? "Safari"  : "Browser";
 
-  return `${browser} · ${os}`;
+  return `${browser} · ${os()}`;
 }
 
 /** Persisted so a device keeps its name across reloads, and stays renameable. */

package/src/core/keys.js

@@ -1,6 +1,7 @@
 /** Share-key generation and normalisation. */
 
 import { KEY, LOCK } from "./config.js";
+import * as state from "./state.js";
 
 /**
  * Cryptographically random key from the unambiguous alphabet.
@@ -32,6 +33,17 @@ export function entropyBits(length) {
 
 export const LENGTHS = { NORMAL: KEY.LENGTH, LONG: KEY.LONG_LENGTH };
 
+/**
+ * How long the NEXT key should be.
+ *
+ * One implementation, because there were three and two of them ignored the
+ * setting entirely: the first-run key and the collision retry both emitted six
+ * characters however the app was configured — which is precisely the two places
+ * a key is generated FOR the user rather than at their request.
+ */
+export const nextLength = () =>
+  state.get().settings.longKeys ? LENGTHS.LONG : LENGTHS.NORMAL;
+
 /**
  * Normalise before ANY use — hashing, comparison, display.
  *

package/src/core/native.js

@@ -0,0 +1,59 @@
+/**
+ * The one place that knows there is a native shell underneath.
+ *
+ * Rank 0 and DOM-free, because the answer also decides the default key length
+ * in config.js — and core/ is imported by the node tests and shipped in the npm
+ * package that cli/ runs on.
+ *
+ * Before this module existed, three files feature-tested `globalThis.__TAURI__`
+ * independently and all three failed the same way at once: `withGlobalTauri`
+ * had never been switched on in tauri.conf.json, so the global did not exist,
+ * T0 never started, and the desktop app silently degraded to a browser tab that
+ * cannot watch the clipboard. One owner, one feature test, one place to look.
+ */
+
+const g = globalThis;
+
+/**
+ * `__TAURI_INTERNALS__` is injected into every Tauri webview; `__TAURI__` only
+ * when `withGlobalTauri` is on. Both are checked so the SURFACE answer stays
+ * correct even if that flag is ever turned off again — which is exactly the
+ * failure this module was written after.
+ */
+const IN_TAURI = typeof g.__TAURI_INTERNALS__ === "object"
+              || typeof g.__TAURI__ === "object";
+
+/** `document` first: jsdom has both, and the DOM suites want to be "web". */
+const IN_NODE = typeof document === "undefined" && !!g.process?.versions?.node;
+
+export const SURFACE    = IN_TAURI ? "desktop" : IN_NODE ? "cli" : "web";
+export const IS_DESKTOP = SURFACE === "desktop";
+export const IS_WEB     = SURFACE === "web";
+export const IS_CLI     = SURFACE === "cli";
+
+/** Call a command in desktop/src-tauri/src/main.rs. Null anywhere else. */
+export async function invoke(command, args) {
+  const core = g.__TAURI__?.core;
+  if (!core?.invoke) return null;
+  try {
+    return await core.invoke(command, args);
+  } catch (err) {
+    console.warn(`[realtimeclipboard] native "${command}" failed:`, err);
+    return null;
+  }
+}
+
+/**
+ * Subscribe to an event the shell emits. Resolves to an unsubscribe function,
+ * or null off the desktop so callers can treat "no shell" as ordinary.
+ */
+export async function listen(event, fn) {
+  const api = g.__TAURI__?.event;
+  if (!api?.listen) return null;
+  try {
+    return await api.listen(event, ({ payload }) => fn(payload));
+  } catch (err) {
+    console.warn(`[realtimeclipboard] native listen "${event}" failed:`, err);
+    return null;
+  }
+}

package/src/core/state.js

@@ -7,7 +7,8 @@
  */
 
 import { emit, EV } from "./bus.js";
-import { DEFAULT_SYNC_MODE } from "./config.js";
+import { DEFAULT_SYNC_MODE, SYNC_MODES, KEY, TEXT } from "./config.js";
+import * as storage from "./storage.js";
 
 const state = {
   key: null,
@@ -45,20 +46,89 @@ const state = {
   tier: "T1",                // clipboard capture tier, see clipboard/capture.js
   lastSent: "",              // dedupe guard (FR-2.7)
   suppressUntil: 0,          // loop-suppression deadline (FR-2.6)
+  lastLocalCopyAt: 0,        // a local copy outranks an arriving clip — see recentLocalCopy()
   settings: {
-    syncMode: DEFAULT_SYNC_MODE,   // live | manual — see config.js
-    autowrite: true,
-    autoread: true,
+    // off | manual | live — one ladder, see config.js SYNC_MODES. Reading and
+    // writing the OS clipboard are both derived from this and neither has a
+    // switch of its own: two controls over one behaviour eventually disagree,
+    // and then the app looks like it is ignoring its own setting.
+    syncMode: DEFAULT_SYNC_MODE,
     autoaccept: false,
     thumbs: true,
     images: true,
     cursors: true,
+    longKeys: KEY.DEFAULT_LONG,    // installed builds default to 10 chars
+    closeToTray: true,             // desktop only; the X button hides, Quit is in the tray
     poll: "1s",
   },
 };
 
 export const get = () => state;
 
+/**
+ * Seed settings from storage.
+ *
+ * Runs first in boot(), and the ordering is the point: resolveKey() asks how
+ * long the next key should be, and used to be answered from the defaults
+ * because the panel that restored preferences had not initialised yet.
+ *
+ * A key absent from the saved object keeps its default above. That is what
+ * lets a setting be ADDED without silently turning it off for everyone who
+ * saved their preferences under an earlier build.
+ */
+export function restore() {
+  const saved = storage.loadSettings();
+  if (saved) Object.assign(state.settings, saved);
+
+  migrateReceiving(saved);
+
+  /**
+   * One-time move to the long key on installed builds.
+   *
+   * Anyone who toggled any switch before this shipped has an explicit
+   * `longKeys: false` they never chose — persist() writes the whole settings
+   * object, so the old default was recorded as a decision. Gated on a marker so
+   * it happens once and a later deliberate "off" stands.
+   *
+   * Nothing existing is invalidated: this only changes the NEXT key generated.
+   */
+  if (KEY.DEFAULT_LONG && !storage.read("longKeyDefault")) {
+    state.settings.longKeys = true;
+    storage.write("longKeyDefault", KEY.LONG_LENGTH);
+    storage.saveSettings(state.settings);
+  }
+}
+
+/**
+ * Receiving used to be its own switch, defaulting on and independent of the
+ * mode, so Manual stopped this machine SENDING while incoming clips still
+ * landed on its system clipboard. Both directions are the mode's now.
+ *
+ * Anyone who turned that switch off asked for exactly one thing: nothing
+ * arriving should touch their clipboard. On the new ladder only Manual honours
+ * that, so they are moved there rather than silently promoted to a Live rung
+ * that does the thing they opted out of. The dead keys go with them, which is
+ * also what makes this run once — after the next save they are not on disk.
+ */
+function migrateReceiving(saved) {
+  if (!saved) return;
+  if (!("autowrite" in saved) && !("autoread" in saved)) return;
+
+  if (saved.autowrite === false && state.settings.syncMode === SYNC_MODES.LIVE) {
+    state.settings.syncMode = SYNC_MODES.MANUAL;
+  }
+  delete state.settings.autowrite;
+  delete state.settings.autoread;
+  storage.saveSettings(state.settings);
+}
+
+/** Change a setting and remember it. The only path that persists one. */
+export function saveSetting(name, value) {
+  state.settings[name] = value;
+  storage.saveSettings(state.settings);
+  emit(EV.SETTINGS_CHANGED, { name, value });
+}
+
 export function setKey({ key, roomHash, aesKey, locked = false, authToken = null }) {
   state.key = key;
   state.roomHash = roomHash ?? state.roomHash;
@@ -191,3 +261,16 @@ export function setSetting(name, value) {
 /** Mute local capture briefly after applying a remote clip (FR-2.6). */
 export function suppress(ms) { state.suppressUntil = Date.now() + ms; }
 export function isSuppressed() { return Date.now() < state.suppressUntil; }
+
+/**
+ * When this machine last put something on its own clipboard.
+ *
+ * Distinct from `suppressUntil`, which is about not echoing our own writes back
+ * to the room. This is about precedence: for a few seconds after you copy
+ * something here, what you copied is what you are about to paste, and a clip
+ * arriving from another device does not get to take it away.
+ */
+export function markLocalCopy() { state.lastLocalCopyAt = Date.now(); }
+export function recentLocalCopy() {
+  return Date.now() - state.lastLocalCopyAt < TEXT.LOCAL_COPY_GRACE_MS;
+}

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,33 @@ 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, and the distinction from
+ * `clip` is the whole design:
+ *
+ *   clip   — a discrete thing that settled. Goes to history, to the OS
+ *            clipboard, through the dedupe and against the 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. Not
+ *            retained, not replayed, never written to anyone's clipboard.
+ *
+ * It carries the WHOLE text rather than a diff, which is what lets live typing
+ * exist here without positions or operational transform. That trade is bounded
+ * by TEXT.STREAM_MAX_BYTES — above it the editor stops streaming and the text
+ * syncs on commit only, because re-sending 20 KB per keystroke is not a thing
+ * anybody should do to a relay.
+ *
+ * `name` rides along for the same reason it does on a cursor frame: nothing
+ * replays these, so a device that joins mid-sentence would otherwise render an
+ * unattributed caret until the next roster frame happened to arrive.
+ *
+ * Everything but `t` and `originId` is sealed by main.js encryptFrame(), so the
+ * relay forwards a blob and never sees a keystroke.
+ */
+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 }) => ({