realtimeclipboard 0.3.0 → 0.5.0

package/src/core/keys.js

@@ -1,30 +1,19 @@
 /** Share-key generation and normalisation. */
 
 import { KEY, LOCK } from "./config.js";
+import * as state from "./state.js";
 
-/**
- * Cryptographically random key from the unambiguous alphabet.
- *
- * Note the modulo bias: 256 does not divide 30, so the first 16 letters of the
- * alphabet are very slightly likelier than the last 14. The effect is about
- * 0.03 bits over a 6-character key — irrelevant next to the 30-bit total, and
- * called out here so nobody has to rediscover it.
- */
+// Modulo bias: 256 does not divide 30, costing ~0.03 bits over a 6-char key.
 export function generate(length = KEY.LENGTH) {
   const bytes = crypto.getRandomValues(new Uint8Array(length));
   return Array.from(bytes, b => KEY.ALPHABET[b % KEY.ALPHABET.length]).join("");
 }
 
 /**
- * Bits of entropy in a key of this length, given the 30-letter alphabet.
+ * Bits of entropy in a key of this length: 6 chars ≈ 29.4, 10 chars ≈ 49.1.
  *
- *   6 chars  ≈ 29.4 bits   — the default. Convenient, and brute-forceable
- *                            offline by anyone who captured ciphertext.
- *  10 chars  ≈ 49.1 bits   — ~1.6 million times harder, still typeable.
- *
- * PBKDF2 at 250k iterations multiplies the cost of each guess, but it does not
- * change the shape of the problem: short keys are a convenience decision, and
- * this function exists so the UI can say so in numbers rather than adjectives.
+ * PBKDF2 multiplies the cost of each guess but does not change the shape of the
+ * problem. This exists so the UI can state the trade-off in numbers.
  */
 export function entropyBits(length) {
   return Math.log2(KEY.ALPHABET.length) * length;
@@ -32,13 +21,16 @@ export function entropyBits(length) {
 
 export const LENGTHS = { NORMAL: KEY.LENGTH, LONG: KEY.LONG_LENGTH };
 
+// One implementation: the first-run key and the collision retry both used to
+// emit six characters however the app was configured.
+export const nextLength = () =>
+  state.get().settings.longKeys ? LENGTHS.LONG : LENGTHS.NORMAL;
+
 /**
  * Normalise before ANY use — hashing, comparison, display.
  *
- * This matters more than it looks: the room name is a hash of the key, and
- * "D75LV" and "d75lv" hash differently. Skipping this silently drops two users
- * into different rooms while both believe they typed the same key.
- * Verified in docs/M0-RESULTS.md §6.
+ * The room name is a hash of the key, so "D75LV" and "d75lv" would drop two
+ * users into different rooms while both believe they typed the same thing.
  */
 export function normalise(raw) {
   return String(raw || "").trim().toUpperCase().replace(/[^A-Z0-9]/g, "");
@@ -47,16 +39,10 @@ export function normalise(raw) {
 /**
  * Deliberately more permissive than the generation alphabet.
  *
- * KEY.ALPHABET exists so generated keys are unambiguous when read aloud or
- * retyped — it is a constraint on what we PRODUCE. Validation must accept
- * anything a peer might legitimately hand us, because:
- *
- *   - a key shared from another build (or a future alphabet) is still valid;
- *     the room name is a hash, and a hash accepts any input
- *   - rejecting an in-use key strands the user with no way to join
- *
- * "D75LV" is the worked example throughout the docs and contains an L, which
- * the generator will never emit. It still has to work.
+ * KEY.ALPHABET constrains what we PRODUCE. Validation must accept anything a
+ * peer might legitimately hand us: a key from another build is still a valid
+ * hash input, and rejecting an in-use key strands the user with no way to join.
+ * "D75LV" contains an L, which the generator never emits, and still has to work.
  */
 export function isValid(raw) {
   const k = normalise(raw);
@@ -64,17 +50,12 @@ export function isValid(raw) {
 }
 
 /**
- * Bits of entropy in a PIN, estimated from the character classes it actually
- * uses rather than from its length alone.
+ * Bits of entropy in a PIN, from the character classes it actually uses.
  *
  * Deliberately pessimistic — it assumes an attacker who knows the alphabet you
- * drew from, which is the only assumption worth making about someone running an
- * offline attack. "123456" is counted as six digits, not six printable ASCII
- * characters, so the dialog reports ~20 bits and not a flattering ~39.
- *
- * The number matters more here than it does for a key. A key is guessed from
- * nothing; a PIN is guessed by someone who may already hold the link, and at
- * that point it is the entire remaining secret.
+ * drew from, so "123456" reports ~20 bits rather than a flattering ~39. A PIN is
+ * guessed by someone who may already hold the link, where it is the entire
+ * remaining secret.
  */
 export function pinEntropyBits(pin) {
   const p = String(pin ?? "");
@@ -87,61 +68,60 @@ export function pinEntropyBits(pin) {
   return Math.log2(alphabet) * p.length;
 }
 
-/* ------------------------------------------------------------------
-   The fragment
-
-   A locked session's link carries a marker but never the PIN: `#!ABCDEF`.
-   That a session is locked is not a secret — the PIN is — and the app has to
-   know before it derives anything, because the marker is what decides which of
-   two completely different derivations to run.
-
-   Parsing happens BEFORE normalise(), and that ordering is load-bearing:
-   normalise() strips everything outside [A-Z0-9], so running it first turns
-   "#!ABCDEF" into the perfectly valid, completely different key "ABCDEF".
-
-   An older build has no idea about any of this. It normalises the fragment,
-   drops the "!", and joins the UNLOCKED room named ABCDEF — a different room
-   from the locked one, which it cannot address. It finds an empty room and
-   learns nothing, which is the correct way for this to fail.
-------------------------------------------------------------------- */
-
+/**
+ * A locked session's link carries a marker but never the PIN: `#!ABCDEF`.
+ *
+ * Parsing happens BEFORE normalise(), and that order is load-bearing:
+ * normalise() strips everything outside [A-Z0-9], so running it first turns
+ * "#!ABCDEF" into the valid, completely different key "ABCDEF". That is also how
+ * an older build fails safely — it joins the empty unlocked room and learns
+ * nothing.
+ */
 export const LOCK_SIGIL = LOCK.SIGIL;
 
-/** Split a raw fragment into its key and its lock flag. */
 export function parseFragment(raw) {
   const s = String(raw ?? "").trim();
   const locked = s.startsWith(LOCK.SIGIL);
   return { key: normalise(locked ? s.slice(LOCK.SIGIL.length) : s), locked };
 }
 
-/** Build one. The inverse of parseFragment, and tested as such. */
+/** The inverse of parseFragment, and tested as such. */
 export function fragment(key, locked = false) {
   return (locked ? LOCK.SIGIL : "") + normalise(key);
 }
 
-/** Read the key from the URL fragment. The fragment is never sent to a server. */
+/**
+ * The fragment is never sent to a server. Read once at boot and then cleared —
+ * see clearUrl(), which openSession() calls immediately afterwards.
+ *
+ * There is deliberately no inverse. A `toUrl()` existed and was what kept the
+ * key in the address bar for the whole session; it is gone rather than merely
+ * unused, so that "put the key back in the URL" is not one import away. A link
+ * to share is built by shareLink() from state, which never touches `location`.
+ */
 export function fromUrl() {
+  if (typeof location === "undefined") return { key: "", locked: false };
   return parseFragment(location.hash.slice(1));
 }
 
-export function toUrl(key, locked = false) {
-  location.hash = fragment(key, locked);
-}
-
 /**
  * Drop the key out of the address bar without navigating.
  *
- * For the one case where the session in the URL is not merely over but closed
- * to this device: it was locked by somebody else and we were removed from it
- * (main.js onEvicted). The fragment is what boot() reads first, so leaving it
- * in place means every reload rejoins a room we have been ejected from and
- * gets ejected again.
+ * Called on every `openSession()`, so the key is in the URL only for the instant
+ * between the page loading and boot reading it — not for the life of the
+ * session, in every screenshot and screen share, and in reach of every script in
+ * the document. It is also what `onEvicted()` uses to make a reload stop
+ * rejoining a room this device was thrown out of.
+ *
+ * replaceState, not `location.hash = ""` — that leaves a bare "#" and pushes a
+ * history entry, so Back would restore the dead key.
  *
- * replaceState rather than `location.hash = ""`, which leaves a bare "#" on the
- * URL and pushes a history entry — so Back would put the dead key straight
- * back.
+ * Guarded because this directory has no DOM (see CLAUDE.md): `cli/` imports this
+ * module, and a bare `history` here threw during boot the moment this stopped
+ * being an eviction-only path. Silent no-op — there is no address bar to clear.
  */
 export function clearUrl() {
+  if (typeof history === "undefined" || typeof location === "undefined") return;
   history.replaceState(null, "", location.pathname + location.search);
 }
 

package/src/core/native.js

@@ -0,0 +1,55 @@
+/**
+ * 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 cli/ runs on.
+ *
+ * Three files used to feature-test `globalThis.__TAURI__` independently and all
+ * three failed at once: `withGlobalTauri` had never been switched on, so the
+ * global did not exist, T0 never started, and the desktop app silently degraded
+ * to a browser tab that cannot watch the clipboard.
+ */
+
+const g = globalThis;
+
+// `__TAURI_INTERNALS__` is injected into every Tauri webview; `__TAURI__` only
+// when `withGlobalTauri` is on. Both are checked so the answer survives that
+// flag being turned off again — 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/paths.js

@@ -1,45 +1,20 @@
 /**
  * Where the app is served from, resolved once for the whole codebase.
  *
- * Six modules used to compute this themselves with `new URL("../…",
- * import.meta.url)` — each one hard-coding how deep its own file sits in the
- * tree. That works exactly as long as every module keeps its own file, and
- * stops the moment the deploy bundles `src/ui/*.js` into `src/main.js`: every
- * one of those paths shifts by a directory level, all at once, and nothing
- * throws. `install.js` in particular resolved the app root to the GitHub Pages
- * ROOT rather than to `/RealtimeClipboard/`, which silently breaks the service-worker
- * scope and the PWA install criteria — PRD OI-9, the failure its own comment
- * warned about.
+ * From `document.baseURI`, never `import.meta.url` — see core/CLAUDE.md. A
+ * module's depth in the tree is not information it may depend on, and bundling
+ * shifts every such path at once without throwing.
  *
- * A module's depth in the tree is not information any module should depend on.
- * `document.baseURI` is: it is what the browser already resolved every relative
- * href on the page against, so it is right whether the code arrives as forty
- * modules or as one bundle.
- *
- * !! The app root is the ORIGIN root — `new URL("/", …)`, not `new URL(".", …)`.
- * That is a deliberate narrowing: this used to resolve the directory the current
- * page sits in, so the app could be served from a subpath like
- * `user.github.io/RealtimeClipboard/`. Subpath hosting is no longer supported, because
- * src/pages/ publishes its pages one level up from where they sit on disk and
- * therefore links to them root-absolutely — and a root-absolute link is wrong
- * under a subpath by construction. Supporting both would mean two link styles
- * in one site, which is how the depth bugs above happened in the first place.
- *
- * What that buys: the app's HTML no longer has to live at the app root for this
- * to be correct, so a page's depth stops being load-bearing anywhere. What it
- * costs: hosting under a path prefix. docs/SELF-HOSTING.md says so. !!
+ * APP_ROOT is the ORIGIN root, which is what retired subpath hosting: pages in
+ * `src/pages/` link root-absolutely, and a root-absolute link cannot be correct
+ * under a path prefix.
  */
 
-/**
- * Guarded the same way `config.js` guards `location`: `core/` is imported by
- * the node-based tests, where there is no document, and a bare reference would
- * throw at import time and take the whole module graph down with it.
- */
+// core/ is imported by the node tests, where there is no document.
 const BASE = typeof document !== "undefined" && document.baseURI
   ? document.baseURI
   : "http://localhost/";
 
-/** The origin root, with trailing slash — `https://realtimeclipboard.com/`. */
 export const APP_ROOT = new URL("/", BASE);
 
 /** A file sitting beside `app.html`: `sw.js`, `manifest.webmanifest`, `changelog.json`. */
@@ -48,21 +23,9 @@ export const atRoot = name => new URL(name, APP_ROOT).href;
 /**
  * A stylesheet under `src/styles/lazy/`, fetched on first open.
  *
- * Lazy sheets stay OUT of the bundle on purpose — a QR modal's stylesheet has
- * no business in the critical path of an app most people never open it in.
- *
- * !! The directory is the whole contract. `styles/` is bundled into main.css
- * and `styles/lazy/` is copied verbatim, so which loader a sheet belongs to is
- * a fact about where it sits rather than about who happens to reference it.
- * tools/build/build.mjs used to recover that by grepping every module for calls to
- * this function; it copies the directory now. Pointing this at `styles/` would
- * make an eager sheet loadable twice, once bundled and once over the wire. !!
- *
- * A sheet cannot be moved into `lazy/` on payload grounds alone. An injected
- * <link> lands AFTER main.css, and main.css ends with mobile.css, which
- * overrides earlier sheets at equal specificity and relies on source order to
- * win. So anything mobile.css restyles has to stay eager whatever it costs —
- * qr.css and history.css share ten classes with it and are the standing
- * example.
+ * A sheet cannot move into `lazy/` on payload grounds alone: an injected <link>
+ * lands after main.css, which ends with mobile.css and relies on source order to
+ * win at equal specificity. Anything mobile.css restyles stays eager — qr.css
+ * and history.css are the standing example.
  */
 export const lazyStyleHref = name => new URL(`src/styles/lazy/${name}`, APP_ROOT).href;

package/src/core/state.js

@@ -1,39 +1,29 @@
 /**
  * Single source of truth for session state.
  *
- * Deliberately not reactive. Modules mutate through the setters here and the
- * bus announces the change; nothing observes this object directly. That keeps
- * the data flow one-directional and greppable.
+ * Deliberately not reactive: modules mutate through the setters here and the bus
+ * announces the change. Nothing observes this object directly.
  */
 
 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,
   roomHash: null,
   aesKey: null,
+  locked: false,
   /**
-   * Locked session — a PIN outside the link (core/crypto.js).
-   *
-   * `verified` is a separate fact from `locked` and the difference is the whole
-   * honesty of the feature. A wrong PIN does not fail loudly: it derives a
-   * different, empty room, which looks exactly like being the first one to
-   * arrive. `verified` means something in this room actually decrypted, so we
-   * KNOW the PIN is right rather than assuming it.
+   * A wrong PIN does not fail loudly — it derives a different, empty room, which
+   * looks exactly like being first to arrive. `verified` means something here
+   * actually decrypted, so we KNOW the PIN is right rather than assuming it.
    */
-  locked: false,
   verified: false,
   /**
-   * Were we the first device into this room?
-   *
-   * `null` until the relay's `welcome` answers it — "not yet known" is a third
-   * state and must not be spelled `false`, or the lock button would be refused
-   * for the fraction of a second before the room reports itself and refused
-   * again for the whole of an offline session.
-   *
-   * Only locking reads it (see canLock). The relay's `existing` count is the
-   * source: it is the peers already present at the moment we joined.
+   * Were we first into this room? `null` until the relay's `welcome` answers.
+   * "Not yet known" must not be spelled `false`, or the lock button is refused
+   * for a moment on connect and for the whole of an offline session.
    */
   founder: null,
   authToken: null,           // proves PIN knowledge to the relay; not a secret
@@ -45,32 +35,90 @@ 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,
+    // Reading and writing the OS clipboard are both derived from this rung and
+    // neither gets a switch of its own — see config.js SYNC_MODES.
+    syncMode: DEFAULT_SYNC_MODE,
     autoaccept: false,
     thumbs: true,
     images: true,
     cursors: true,
+    longKeys: KEY.DEFAULT_LONG,    // installed builds default to the longer key
+    closeToTray: true,             // desktop only; the X button hides, Quit is in the tray
     poll: "1s",
+    // Whether the share key may be written to localStorage so a relaunch offers
+    // the room back (FR-1.7). Defaults on because that is the behaviour that
+    // shipped and losing it silently would be a regression — but it is the one
+    // setting that decides whether a secret touches disk, so it is a switch and
+    // it is named plainly in the UI. See storage.js saveLastKey.
+    rememberKey: true,
   },
 };
 
 export const get = () => state;
 
+/**
+ * Seed settings from storage. Runs first in boot(): resolveKey() asks how long
+ * the next key should be, and used to be answered from the defaults.
+ *
+ * A key absent from the saved object keeps its default above, which is what lets
+ * a setting be ADDED without turning it off for everyone who already saved.
+ */
+export function restore() {
+  const saved = storage.loadSettings();
+  if (saved) Object.assign(state.settings, saved);
+
+  migrateReceiving(saved);
+
+  /**
+   * Anyone who toggled any switch before this shipped has an explicit
+   * `longKeys: false` they never chose — persist() writes the whole object, so
+   * the old default was recorded as a decision. Gated on a marker so a later
+   * deliberate "off" stands. Only affects 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 independently of the mode,
+ * so Manual stopped this machine SENDING while arriving clips still landed on
+ * its clipboard. Anyone who turned it off asked for one thing: nothing arriving
+ * touches their clipboard. Only Manual honours that, so they move there rather
+ * than being promoted to a rung that does what they opted out of.
+ */
+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;
   state.aesKey = aesKey ?? state.aesKey;
   state.locked = locked;
   state.authToken = authToken;
-  // A new key is a new room: whatever we had proved about the old one does not
-  // carry over, and claiming otherwise would leave a stale padlock on screen.
+  // A new key is a new room, so both of these are re-asked. Left standing, the
+  // founder of one session would carry the right to lock into the next.
   state.verified = false;
-  // Likewise "we were first" — asked and answered per room. Left standing, the
-  // founder of one session would carry the right to lock into the next one it
-  // walked into, which is precisely the device that must not have it.
   state.founder = null;
   emit(EV.KEY_CHANGED, { key, locked });
   emit(EV.LOCK_STATE, { locked, verified: false });
@@ -78,12 +126,9 @@ export function setKey({ key, roomHash, aesKey, locked = false, authToken = null
 }
 
 /**
- * Record whether this device was the first one into the room.
- *
- * Fed from `welcome.existing` in main.js. Re-answered on every welcome, so a
- * relay restart — which empties every room (OI-13) — hands the title to
- * whoever reconnects into the empty room first, rather than to whoever held it
- * before the room stopped existing.
+ * Fed from `welcome.existing`. Re-answered on every welcome, so a relay restart
+ * — which empties every room (OI-13) — hands the title to whoever reconnects
+ * first rather than to whoever held it before the room stopped existing.
  */
 export function setFounder(first) {
   const next = first === null ? null : !!first;
@@ -95,17 +140,14 @@ export function setFounder(first) {
 /**
  * May THIS device lock the session?
  *
- * Alone, anyone may: there is nobody to be thrown out. With company, only the
- * device that opened the room, because locking is not a setting — it moves the
- * session to a different room and removes everybody else from it (see
- * LOCK.EVICT). A control that lets any arrival do that to the rest is a control
- * for taking a session over, and the person who started it is the one who
- * chose to share the key in the first place.
+ * Alone, anyone may. With company, only the device that opened the room, because
+ * locking moves the session to a different room and evicts everybody else
+ * (LOCK.EVICT) — a control that lets any arrival do that is a control for taking
+ * a session over.
  *
  * A rule the UI keeps, not one the relay enforces: every device in the room
- * already holds the key, so a modified client could send the goodbye itself.
- * That is not a new power — it could equally read every clip — and the honest
- * description of this is "the app will not help you do it", not "you cannot".
+ * holds the key, so a modified client could send the goodbye itself. The honest
+ * description is "the app will not help you", not "you cannot".
  */
 export function canLock() {
   if (state.locked) return false;
@@ -114,11 +156,9 @@ export function canLock() {
 }
 
 /**
- * Record that this device can actually read this room.
- *
  * Set from the first thing that decrypts — the beacon replayed in `welcome`, or
- * any real frame. Only ever moves false -> true within a session; setKey resets
- * it, because a different room is a different question.
+ * any real frame. Only moves false -> true; setKey resets it, because a
+ * different room is a different question.
  */
 export function setVerified() {
   if (!state.locked || state.verified) return;
@@ -132,15 +172,10 @@ export function setConnection(connection, detail = "") {
 }
 
 /**
- * Peer roster.
- *
- * Diffed rather than just counted, so arrivals can be announced. The key is a
- * bearer credential — a device appearing is the one observable moment that
- * tells you someone else has it, and a count quietly going 2 → 3 is not
- * something anyone notices.
- *
- * The first roster after connecting is not announced: those devices were
- * already there, and greeting them as arrivals would cry wolf on every reload.
+ * Diffed rather than counted, so arrivals can be announced: the key is a bearer
+ * credential, and a device appearing is the one observable moment telling you
+ * someone else has it. The first roster after connecting is not announced —
+ * those devices were already there, and greeting them would cry wolf on reload.
  */
 let roster = null;
 
@@ -167,9 +202,9 @@ export function setPeers(count, list = []) {
 export function resetRoster() { roster = null; }
 
 /**
- * The relay keeps rooms in process memory, so a changed instance id means we
- * may have landed on a different replica where our peers do not exist. Loud,
- * not silent — a quiet failure here looks exactly like "the network is slow".
+ * A changed instance id means we may have landed on a different replica where
+ * our peers do not exist. Loud, not silent — a quiet failure here looks exactly
+ * like "the network is slow".
  */
 export function setInstance(instance) {
   const previous = state.instance;
@@ -191,3 +226,13 @@ 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; }
+
+/**
+ * Precedence, not loop-suppression: for a few seconds after you copy something
+ * here, that is what you are about to paste, and an arriving clip 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;
+}