realtimeclipboard 0.6.0 → 0.7.0

package/src/core/config.js

@@ -1,44 +1,38 @@
 /**
- * Every tunable constant. Nothing else in the app hard-codes a limit —
- * if you find a magic number elsewhere, it belongs here.
+ * Every tunable constant. A magic number anywhere else is a bug.
  */
 
-import { IS_DESKTOP } from "./native.js";
+import { IS_INSTALLED, IS_DESKTOP } from "./native.js";
 
-// Guarded: imported by node tests where `location` does not exist, and a bare
-// reference would throw at import time and take the whole graph down.
+// Guarded: node tests import this and have no `location`; a bare reference
+// throws at import time and takes the whole graph down.
 const IS_LOCAL = typeof location !== "undefined" &&
   ["localhost", "127.0.0.1", "[::1]"].includes(location.hostname);
 
 /**
- * Must be wss:// in production — a browser refuses ws:// from an https:// page
- * as mixed content. Localhost is exempt, which is why dev can stay ws://.
- * Self-hosters change this one line.
+ * Must be wss:// in production — a browser refuses ws:// from https:// as mixed
+ * content. Localhost is exempt. 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";
 
 /**
- * The storage prefix lives here rather than in core/storage.js so 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" works
- * until someone moves a line to module scope.
+ * Here rather than in core/storage.js so this module can read a setting without
+ * importing storage.js, which imports this one. The cycle works until someone
+ * moves a line to module scope.
  */
 export const STORAGE_PREFIX = "realtimeclipboard.";
 const RELAY_KEY = "relayUrl";
 
-/**
- * `http(s)://` is accepted and converted, because that is what a person copies
- * out of a browser bar when IT gives them an address.
- */
+/** `http(s)://` is converted, because that is what IT hands someone to paste. */
 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>".
+    // The routes are fixed (/ws, /sse, /pub, /health) and a trailing slash would
+    // produce "//ws/<room>".
     return `${scheme}//${u.host}`;
   } catch { return null; }
 }
@@ -49,14 +43,12 @@ const stored = () => {
 };
 
 /**
- * `?relay=` for builds that are deployed rather than visited: an MSI transform,
- * a config profile, a desktop shell launching the webview at its own relay. It
- * wins over the stored setting because the deployment is more current, and
- * main.js persists it so the switch survives the next launch.
+ * For builds that are deployed rather than visited — an MSI transform, a config
+ * profile, a desktop shell. Beats the stored setting because the deployment is
+ * more current; main.js persists it so it survives the next launch.
  *
- * NOT an attack surface on the hosted site: the CSP pins `connect-src` to this
- * origin and the default relay, so a link carrying `?relay=` elsewhere cannot
- * open a connection. The CSP is the enforcement; this is only the plumbing.
+ * Not an attack surface on the hosted site: the CSP pins `connect-src` to this
+ * origin and the default relay, so `?relay=` elsewhere cannot connect.
  */
 const fromQuery = () => {
   try { return new URLSearchParams(location.search).get("relay"); }
@@ -73,32 +65,27 @@ export const RELAY_IS_CUSTOM = RELAY_URL !== DEFAULT_RELAY_URL && RELAY_URL !==
 
 /**
  * The same relay over plain HTTP, for the SSE+POST fallback and /stats. One
- * hostname, two ways in, so IT allowlists a single domain (PRD §5.4) and both
- * transports are covered. Derived so the two can never drift.
+ * hostname so IT allowlists one domain (PRD §5.4); derived so the two cannot drift.
  */
 export const RELAY_HTTP_URL = RELAY_URL.replace(/^ws/i, "http");
 
 /**
- *   ws   — WebSocket. Lower latency, one connection, the default.
- *   sse  — Server-Sent Events down + fetch POST up (PRD §4.3 R3). Plain HTTP
- *          with no Upgrade, so it survives the TLS-inspecting proxies that eat
- *          WebSockets on corporate networks (§5.4).
+ *   ws   — lower latency, one connection, the default.
+ *   sse  — SSE down + fetch POST up (PRD §4.3 R3). 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.
+ * Both carry the identical envelopes — see transport/protocol.js.
  */
 export const TRANSPORT = { WS: "ws", SSE: "sse" };
 
 /**
- * Clip size, derived — not chosen.
+ * Clip size, derived — not chosen. A clip is UTF-8, AES-GCM sealed, base64'd and
+ * JSON-wrapped, and the relay drops any frame over MAX_FRAME_BYTES, so the real
+ * limit is a byte budget that a character count only approximates.
  *
- * A clip is UTF-8 encoded, sealed with AES-GCM (16-byte tag), base64'd and put
- * in a JSON envelope, and the relay rejects any frame over MAX_FRAME_BYTES. So
- * the real limit is a BYTE budget and a character count only approximates it.
- *
- * MAX_CHARS was once 50,000 — 66 KB on the wire against a 32 KB frame — because
- * "max payload 32 KB" had been transcribed into a character count and never
- * recomputed. Every clip over ~24 KB was accepted, encrypted, sent, and dropped
- * by the relay, the rejection arriving long after the UI said it went.
+ * MAX_CHARS was once 50,000 — 66 KB against a 32 KB frame — because "32 KB" had
+ * been transcribed as a character count. Every clip over ~24 KB was encrypted,
+ * sent and dropped, the rejection arriving long after the UI said it went.
  * tests/unit/clipsize.mjs proves the derivation.
  */
 const RELAY_FRAME_BYTES  = 32 * 1024;   // backend/main.py MAX_FRAME_BYTES
@@ -111,24 +98,20 @@ const CLIP_MAX_BYTES = Math.floor(
 );
 
 /**
- * Wire size of a string, exported beside the limit it is measured against so the
- * editor and the send path cannot disagree — `String.length` counts UTF-16
- * units, which is not what the relay counts.
+ * Exported beside the limit it is measured against so the editor and the send
+ * path cannot disagree — `String.length` counts UTF-16 units, not wire bytes.
  */
 export const textBytes = (s) => new TextEncoder().encode(s).length;
 
 export const TEXT = {
-  // MAX_CHARS is what the counter shows, because users think in characters.
-  // MAX_BYTES is the truth: 24,000 CJK characters are 72,000 bytes.
   MAX_BYTES: CLIP_MAX_BYTES,                          // the wire limit — authoritative
-  MAX_CHARS: Math.floor(CLIP_MAX_BYTES / 1000) * 1000, // the friendly one, for the counter
+  MAX_CHARS: Math.floor(CLIP_MAX_BYTES / 1000) * 1000, // shown in the counter; 24,000 CJK chars are 72,000 bytes
   SUPPRESS_MS: 1500,          // loop-suppression window after applying a remote clip (FR-2.6)
 
   /**
-   * 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 pause is 300-500 ms, and less would fragment one sentence into
-   * six history entries.
+   * Generous because the text is already on the far screen via the stream — this
+   * only decides when it becomes a clip. A mid-sentence pause is 300-500 ms, and
+   * less would fragment one sentence into six history entries.
    */
   COMMIT_IDLE_MS: 800,
 
@@ -136,42 +119,35 @@ export const TEXT = {
   STREAM_THROTTLE_MS: 100,
 
   /**
-   * Above this, typing is not streamed and the text syncs on commit only.
-   *
-   * A stream frame carries the WHOLE text, which is what lets this feature exist
-   * without diffs or operational transform — a trade that only holds while the
-   * text is small. The degradation is invisible because big text is pasted,
-   * never typed.
+   * Above this, typing syncs on commit only. A stream frame carries the WHOLE
+   * text, which is what lets this exist without diffs or OT — a trade that holds
+   * only while the text is small. Invisible, because big text is pasted.
    */
   STREAM_MAX_BYTES: 4096,
 
   /**
-   * How long a local copy outranks an arriving clip. The moment that actually
-   * hurts is "I copied something, went to paste it, and it was gone", so inside
-   * this window the arriving clip is queued and offered instead of written.
+   * How long a local copy outranks an arriving clip. "I copied something, went to
+   * paste it, and it was gone" is the moment that hurts, so inside this window
+   * the arriving clip is queued and offered instead of written.
    */
   LOCAL_COPY_GRACE_MS: 10_000,
 };
 
 /**
- * Pastejacking — see clipboard/guard.js for what is actually checked.
+ * Pastejacking — clipboard/guard.js does the checking. The room is joinable by
+ * anyone holding the key and an arriving clip reaches the OS clipboard with no
+ * gesture, so a peer chooses what you paste into your next terminal.
  *
- * The room is joinable by anyone holding the key, and an arriving clip is
- * written to the OS clipboard with no gesture from the person receiving it. So
- * a peer chooses what you paste into your next terminal.
- *
- * `ENABLED` governs only the heuristic that demands a click. Stripping the
- * trailing newline and the invisible characters is unconditional and has no
- * switch: it is not a policy, it is the difference between a clip that pastes
- * and a clip that runs.
+ * ENABLED governs only the heuristic that demands a click. Stripping the trailing
+ * newline and the invisible characters is unconditional: not a policy, the
+ * difference between a clip that pastes and a clip that runs.
  */
 export const PASTE_GUARD = {
   ENABLED: true,
 
   /**
    * Past this, do not scan. The patterns are anchored per line, so a pasted
-   * logfile is a lot of backtracking for a case that is not what this defends
-   * against — nobody is tricked into pasting 200 KB into a shell.
+   * logfile is a lot of backtracking for a case this does not defend against.
    */
   MAX_SCAN_CHARS: 8_192,
 };
@@ -181,10 +157,9 @@ export const FILES = {
   MAX_COUNT: 20,              // per session, memory only (FR-7.7)
 
   /**
-   * A filename is chosen by whoever sent the file, so it is bounded like every
-   * other piece of peer-supplied metadata. Long enough that no real name is
-   * truncated; short enough that a hostile one is a tile, not a layout.
-   * files/registry.js `safeName` applies it, along with the character rules.
+   * Peer-supplied, so bounded like every other piece of peer metadata. Long
+   * enough that no real name truncates, short enough that a hostile one is a
+   * tile rather than a layout. files/registry.js `safeName` applies it.
    */
   MAX_NAME_CHARS: 120,
   THUMB_PX: 160,              // longest edge (FR-7.2)
@@ -192,31 +167,25 @@ export const FILES = {
 
   /**
    * For the P2P data channel, which carries raw binary. The relay fallback
-   * cannot use this directly — base64 plus the tag and envelope inflate a 32 KB
-   * chunk into a ~44 KB frame, past the relay's own 32 KB cap — so
-   * RELAY_CHUNK_BYTES is DERIVED from this in files/chunker.js rather than being
-   * a second hand-tuned number.
+   * cannot reuse it — base64 plus tag and envelope inflate 32 KB into ~44 KB,
+   * past the relay's own cap — so files/chunker.js derives RELAY_CHUNK_BYTES
+   * from this rather than hand-tuning a second number.
    */
   CHUNK_BYTES: 32 * 1024,
 
   /**
    * How long a file request lives before BOTH ends give up, on the same number,
-   * so neither is left believing in a transfer the other 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: that coupling
-   * meant shortening the ICE race in a test also shortened how long a human had
-   * to answer a dialog.
+   * so neither believes in a transfer the other abandoned. Its own constant
+   * rather than a multiple of the ICE timeout: that coupling meant shortening
+   * the ICE race in a test also shortened how long a human had to answer.
    */
   REQUEST_TIMEOUT_MS: 15_000,
 
   /**
-   * How long a closed data channel gets to confirm the close.
-   *
-   * 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
-   * queued data, so the close event is the nearest thing to a delivery signal.
-   * Bounded, because a wedged association must not hold a transfer open.
+   * bufferedAmount hitting zero means SCTP accepted the bytes, not that the peer
+   * has them. dc.close()'s stream reset is ordered behind the queued data, so the
+   * close event is the nearest thing to a delivery signal. Bounded, because a
+   * wedged association must not hold a transfer open.
    */
   CHANNEL_CLOSE_MS: 1_000,
 };
@@ -225,33 +194,45 @@ export const KEY = {
   // Crockford-ish: no 0/O, no 1/I/L. Ambiguity here becomes a support ticket.
   ALPHABET: "23456789ABCDEFGHJKMNPQRSTVWXYZ",
   /**
-   * Ten, not six. PRD D3 chose six for the phone keyboard and that argument was
-   * sound about typing and wrong about arithmetic.
-   *
-   * The open room hash is derived through the same 250k PBKDF2 as the AES key
-   * (crypto.js `deriveOpen`), so a guess costs a full derivation rather than one
-   * SHA-256. But `SALT` is a single global constant, so the table an attacker
-   * builds is built ONCE and then opens every unlocked session of that length,
-   * for every user, for as long as the salt stands. That is the number that
-   * matters, and at six characters it is ~12 minutes on 100 rented GPUs:
+   * Ten, not the six PRD D3 chose — that argument was sound about phone typing
+   * and wrong about arithmetic. The open room hash goes through the same 250k
+   * PBKDF2 as the AES key, but `SALT` is one global constant, so the table an
+   * attacker builds is built ONCE and opens every unlocked session of that
+   * length, for everyone, for as long as the salt stands:
    *
-   *     6 chars   7.3e8 keys       12 min on 100 GPUs      29.4 bits
-   *    10 chars   5.9e14 keys      19 years on 100 GPUs    49.1 bits
-   *    16 chars   5.3e23 keys      out of reach            78.5 bits
+   *     6 chars   7.3e8 keys    12 min on 100 GPUs     29.4 bits
+   *    10 chars   5.9e14 keys   19 years on 100 GPUs   49.1 bits
+   *    16 chars   5.3e23 keys   out of reach           78.5 bits
    *
-   * Six is therefore not a preference, it is a defect, and no iteration count
-   * fixes a keyspace. Typing cost is paid once per session and only when someone
-   * declines the QR code and the copied link, both of which are in front of it.
+   * So six is a defect, not a preference, and no iteration count fixes a
+   * keyspace. Typing is paid once per session, and only by someone who declined
+   * both the QR code and the copied link.
    */
   LENGTH: 10,
   LONG_LENGTH: 16,            // "high security" option, PRD §7.3
 
   /**
-   * An installed app links a device by QR or copied link, so it does not pay the
-   * typing cost at all — and it is the surface running all day reading every
-   * copy, which is the one that should take the longer option.
+   * The floor for a key we will HASH, as opposed to one we produce.
+   *
+   * Validation is deliberately more permissive than generation — a key from an
+   * older build has to keep working, and no build ever emitted fewer than six.
+   * But it used to accept four, which is ~19.6 bits: the whole keyspace is
+   * 810,000 rooms, and the relay will happily route any of them. Someone typing
+   * `#F5H4` into the address bar got a session that a laptop can enumerate,
+   * with nothing on screen saying so.
+   *
+   * Six is the floor rather than ten because six is what earlier builds handed
+   * out, and stranding those links is a worse failure than a weak room the
+   * holder chose. New keys are still KEY.LENGTH.
    */
-  DEFAULT_LONG: IS_DESKTOP,
+  MIN_LENGTH: 6,
+  MAX_LENGTH: 32,
+
+  /**
+   * An installed app links by QR or link and never pays the typing cost — and it
+   * is the surface reading every copy all day, so it takes the longer option.
+   */
+  DEFAULT_LONG: IS_INSTALLED,
 };
 
 export const CRYPTO = {
@@ -262,12 +243,11 @@ export const CRYPTO = {
   /**
    * One PBKDF2 run, two outputs — see crypto.js `deriveOpen`.
    *
-   * The room hash used to be `SHA-256("realtimeclipboard:" + KEY)`: unsalted,
-   * unstretched, and the one value the relay holds by construction. Anyone with
-   * it could sweep the whole 6-character keyspace in 0.07s and read back the
-   * key, which made the 250k iterations on the AES key worth exactly one
-   * derivation to an attacker. Deriving both from the same PRK costs nothing —
-   * that PBKDF2 was already being awaited before the connection opened.
+   * The room hash used to be unsalted, unstretched SHA-256, and it is the one
+   * value the relay holds by construction: anyone with it could sweep the whole
+   * 6-character keyspace in 0.07s and read back the key, making the 250k
+   * iterations worth one derivation to an attacker. Sharing the PRK costs
+   * nothing — that PBKDF2 was already awaited before the connection opened.
    */
   OPEN_INFO: {
     AES:  "realtimeclipboard/aes",
@@ -275,14 +255,13 @@ export const CRYPTO = {
   },
 
   /**
-   * The lock salt is a PREFIX, completed with the share key — random per
-   * session, which is what a salt is for. The open-session salt above is one
-   * global constant, so a single precomputed table covers every user on earth;
-   * KEY.LENGTH is what has to make that table too large to build.
+   * A PREFIX, completed with the share key — so it is random per session, which
+   * is what a salt is for. The open-session salt above is one global constant,
+   * and KEY.LENGTH is what keeps its precomputed table too large to build.
    *
    * 600k rather than 250k because the threat differs: 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 doubles their cost. Paid once per session.
+   * whole defence and every doubling doubles their cost.
    */
   LOCK_SALT: "realtimeclipboard-lock-v1:",
   LOCK_ITERATIONS: 600_000,
@@ -298,46 +277,41 @@ export const CRYPTO = {
 /**
  * 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 links get forwarded,
- * screenshotted and pasted into group chats. MIN_PIN is 6 and free-form rather
- * than 4-6 digits because against someone who already has the link the key
- * contributes nothing: a 4-digit PIN is ~13 bits, minutes of offline guessing.
+ * MIN_PIN is 6 and free-form rather than 4-6 digits because against someone who
+ * already has the link — and links get forwarded, screenshotted and pasted into
+ * group chats — the key contributes nothing. A 4-digit PIN is ~13 bits.
  */
 export const LOCK = {
   MIN_PIN: 6,
 
   /**
-   * Fragment marker: `#!ABCDEF`. Leading rather than trailing — chat clients
-   * that trim punctuation off a pasted URL trim the END of it.
+   * Fragment marker: `#!ABCDEF`. 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 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.
+   * Sent on creating a locked room and replayed to joiners, so a joiner can tell
+   * "wrong PIN" from "first one here" by whether it decrypts. Receivers drop it.
    */
   BEACON: String.fromCharCode(0) + "realtimeclipboard-lock-v1",
 
   /**
-   * Sent into the room being ABANDONED when a session is locked.
-   *
-   * Locking is a room change: the locking device leaves for a new room and
-   * everyone else is left behind, connected, in sync with nobody, unable to tell
-   * that from a quiet afternoon. This sentinel is the goodbye.
+   * The goodbye sent into the room being ABANDONED. Locking is a room change: the
+   * locking device leaves and everyone else is left connected, in sync with
+   * nobody, unable to tell that from a quiet afternoon.
    *
-   * A clip rather than a new frame type, like BEACON — it needs no relay change
-   * and is sealed with the room key, so the relay forwards what it cannot read.
-   * It overwrites the room's retained last clip deliberately, so a late joiner
-   * to the dead room is told the session moved.
+   * A clip rather than a new frame type, like BEACON — no relay change, and
+   * sealed with the room key. It overwrites the room's retained last clip
+   * deliberately, so a late joiner is told the session moved.
    */
   EVICT: String.fromCharCode(0) + "realtimeclipboard-lock-evict-v1",
 
   /**
-   * How long the goodbye gets to leave before the socket is torn down. Not
-   * paranoia about buffering: the SSE fallback batches upstream frames into a
-   * POST and its close() drops whatever is queued, so closing in the same tick
-   * would send the sentinel to nobody on exactly the network using the fallback.
+   * How long the goodbye gets to leave. Not buffering paranoia: the SSE fallback
+   * batches upstream frames into a POST and close() drops the queue, so closing
+   * in the same tick would send the sentinel to nobody on exactly the network
+   * that needs the fallback.
    */
   EVICT_FLUSH_MS: 250,
 };
@@ -349,12 +323,10 @@ export const NET = {
   ICE_TIMEOUT_MS: 5_000,      // then fall back to relay chunks (FR-7.6)
 
   /**
-   * 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. Without this timer the app sits on
-   * "Connecting…" forever and never tries the fallback.
-   *
-   * Generous enough to survive a scale-to-zero cold start (PRD R2).
+   * A blocked WebSocket frequently does not fail: the proxy accepts the TCP
+   * connection, swallows the Upgrade, and leaves the socket hanging with no open,
+   * no close and no error. Without this the app sits on "Connecting…" forever and
+   * never tries the fallback. Generous enough for a cold start (PRD R2).
    */
   PROBE_MS: 8_000,
 
@@ -375,19 +347,16 @@ export const NET = {
 export const POLL_OPTIONS = { "Off": 0, "500ms": 500, "1s": 1000, "2s": 2000 };
 
 /**
- * How far the sync reaches on THIS device. One ladder, three rungs, each adding
- * exactly one thing to the one below:
+ * How far the sync reaches on THIS device. One ladder, each rung adding exactly
+ * one thing to the one below:
  *
- *   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.
+ *   off    — nothing leaves and nothing arrives.
+ *   manual — the session syncs in the app window; the OS clipboard is untouched.
  *   live   — the OS clipboard is wired to the room in both directions.
  *
- * The stored strings are a compatibility surface: "live" and "manual" are on
- * disk for every existing user, 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 — they read
- * Off / App / Clipboard, naming the destination rather than a manner of working.
+ * The stored strings are a compatibility surface: they are on disk for every
+ * existing user, so renaming them silently resets the one preference where being
+ * wrong matters most. Relabel in ui/features/syncMode.js instead.
  */
 export const SYNC_MODES = {
   OFF: "off",
@@ -396,6 +365,21 @@ export const SYNC_MODES = {
 };
 export const DEFAULT_SYNC_MODE = SYNC_MODES.LIVE;
 
+/**
+ * Appearance. `SYSTEM` means "do not decide" — no attribute is stamped and
+ * styles/tokens.css answers `prefers-color-scheme` on its own, which is also
+ * what renders before any of this JavaScript has run.
+ *
+ * The stored strings are a compatibility surface like SYNC_MODES: relabel the
+ * UI, never the values.
+ */
+export const THEMES = {
+  SYSTEM: "system",
+  LIGHT: "light",
+  DARK: "dark",
+};
+export const DEFAULT_THEME = THEMES.SYSTEM;
+
 /** Does this rung let the OS clipboard be read or written? */
 export const bindsClipboard = (mode) => mode === SYNC_MODES.LIVE;
 
@@ -403,28 +387,71 @@ export const bindsClipboard = (mode) => mode === SYNC_MODES.LIVE;
 export const sharesSession = (mode) => mode !== SYNC_MODES.OFF;
 
 /**
- * Derived from OWNER/NAME rather than written out four times, so a fork, rename
- * or moved account is one edit and the links cannot drift apart.
+ * The public address of the hosted app, for the one job `location` cannot do:
+ * build a link for somebody else to open.
+ *
+ * The desktop shell serves this tree from `http://tauri.localhost` and `cli/`
+ * has no `location` at all, so a share link built from the current URL there
+ * names a host that resolves in one process and nowhere else — the copied link
+ * and the QR code both pointed somewhere no other device could reach.
+ * keys.shareLink() falls back to this; a browser still links to itself, so a
+ * localhost dev pair and a self-hosted deploy keep pointing at themselves.
  *
- * Re-check the sponsors page if the account ever moves — a donate link that 404s
- * costs more goodwill than no donate link, and .github/FUNDING.yml is the same
- * destination and has to move with it.
+ * `/app`, not `/app.html`: the extensionless path is what the deploy publishes,
+ * and Pages 308s the `.html` form onto it through a redirect nobody needs.
+ */
+const SITE_ORIGIN = "https://realtimeclipboard.com";
+
+export const SITE = {
+  ORIGIN: SITE_ORIGIN,
+  HOST: SITE_ORIGIN.replace(/^https?:\/\//, ""),   // what the guide tells you to type
+  APP_URL: `${SITE_ORIGIN}/app`,
+  /** The published contact address — src/pages/contact/ and the AdSense
+      publisher identity name it, so a change here is a change there too. */
+  EMAIL: "info@realtimeclipboard.com",
+
+  /**
+   * `?qr=1` opens the share code as soon as the session is up.
+   *
+   * A QUERY parameter and not part of the fragment, deliberately: the fragment
+   * is the key, its grammar is a compatibility surface every existing share
+   * link depends on, and "show a QR" is a request about this visit rather than
+   * a property of the session. It rides beside ?relay= for the same reason.
+   *
+   * It exists so a surface with no way to draw one — the VS Code extension, the
+   * CLI — can hand the job to the app instead of growing its own renderer.
+   */
+  QR_PARAM: "qr",
+};
+
+/**
+ * Derived rather than written out four times, so a fork or rename is one edit.
+ * If the account moves, .github/FUNDING.yml is the same destination and has to
+ * move with it — a donate link that 404s costs more than no donate link.
  */
 export const REPO = {
   OWNER: "akshaynikhare",
   NAME: "RealtimeClipboard",
 };
 
+const GITHUB = `https://github.com/${REPO.OWNER}/${REPO.NAME}`;
+
 export const LINKS = {
-  REPO:    `https://github.com/${REPO.OWNER}/${REPO.NAME}`,
-  ISSUES:  `https://github.com/${REPO.OWNER}/${REPO.NAME}/issues`,
+  REPO:    GITHUB,
+  ISSUES:  `${GITHUB}/issues`,
   /**
    * The chooser, not a blank issue: `/new/choose` picks between the forms in
-   * .github/ISSUE_TEMPLATE/, which is where the "do not paste your share key"
-   * warning lives — the single most valuable thing on the page for this product.
+   * .github/ISSUE_TEMPLATE/, where the "do not paste your share key" warning is.
    */
-  NEW_ISSUE: `https://github.com/${REPO.OWNER}/${REPO.NAME}/issues/new/choose`,
+  NEW_ISSUE: `${GITHUB}/issues/new/choose`,
   SPONSOR: `https://github.com/sponsors/${REPO.OWNER}`,
+  /**
+   * The full changelog for a reader who is NOT in this origin. The web app links
+   * its own precached copy — offline, and the same file the build shipped — but
+   * the desktop shell's copy sits on `tauri.localhost`, an address that means
+   * nothing in the browser the link opens in. See ui/features/whatsNew.js.
+   */
+  CHANGELOG: `${GITHUB}/blob/main/CHANGELOG.md`,
 };
 
 export const IMAGES = {
@@ -435,24 +462,30 @@ export const IMAGES = {
 };
 
 /**
- * Google Analytics and AdSense.
- *
- * Empty by default and every consumer no-ops on empty, so a fork, a local
- * checkout and a self-hosted deploy load no third-party script at all. Filling
- * these in is the switch that turns tracking and ads on for a build.
+ * The phone breakpoint. CSS cannot read this file, so every media query in
+ * `styles/` is matched to it by hand and this is the copy the JavaScript uses.
+ * Three modules each carried their own string of it, and a module that
+ * disagrees with the stylesheet renders for a layout that is not on screen.
+ */
+const NARROW_MAX = 900;
+
+export const LAYOUT = {
+  NARROW_MAX,
+  NARROW_MQ: `(max-width:${NARROW_MAX}px)`,
+};
+
+/**
+ * Google Analytics and AdSense. Empty by default and every consumer no-ops on
+ * empty, so a fork or self-hosted deploy loads no third-party script at all.
  *
- * !! Analytics loads everywhere; ADSENSE loads on the 19 crawlable pages and
- * never in app.html, which holds the share key in its fragment and decrypted
- * clipboard text in its DOM. The difference is who controls what gets reported:
- * gtag takes `page_location` from us, so `pageLocation()` below strips the key
- * out of it, while the ad tag reports the URL itself with no override. That
- * boundary is enforced by app.html's own meta CSP naming no ad origin — not by
- * this file, and not by anyone remembering. docs/ARCHITECTURE.md §5 and
- * src/ui/features/ads.js have the argument. !!
+ * !! Both load everywhere, app.html included (the no-ads-in-the-app rule was
+ * removed 2026-08-09). The ad tag reports the page URL itself with no override,
+ * so what survives is TIMING: ui/features/ads.js must never load it while the
+ * share key is still in `location.hash`, and waits for keys.clearUrl(). gtag
+ * takes `page_location` from `pageLocation()` below, which strips it too. !!
  *
- * Adding an origin means adding it to the CSP in _headers AND in the crawlable
- * pages' meta tags, which tools/check/site-check.mjs asserts agree — and
- * leaving app.html's alone, which it also asserts.
+ * Adding an origin means adding it to the CSP in _headers AND every page's meta
+ * tag — app.html's included — which tools/check/site-check.mjs asserts agree.
  */
 export const GOOGLE = {
   /** GA4 measurement ID, "G-XXXXXXXXXX". Admin → Data streams → your stream. */
@@ -460,23 +493,62 @@ export const GOOGLE = {
   /** AdSense publisher ID, "ca-pub-################". Account → Settings. */
   ADSENSE_CLIENT: "ca-pub-6053041142492498",
   /**
-   * Per-unit slot IDs, the 10-digit number AdSense prints as `data-ad-slot`
-   * when you create a unit. One per placement, and a unit renders nothing
-   * until its own ID is filled in.
+   * `data-ad-slot` per placement. A unit renders nothing until its ID is filled.
    */
   ADSENSE_SLOTS: {
     /** index.html, the 728×90 after "how it works". */
     LEADERBOARD: "7038244690",
     /** index.html, the 300×600 rail beside the FAQ. */
     RAIL: "8299355473",
-    /**
-     * There is deliberately no APP slot. A unit exists in the AdSense account
-     * for it (6948680552) and is left unused: app.html carries the share key in
-     * its fragment and decrypted clipboard text in its DOM, and AdSense reports
-     * the page URL with no way to strip it. src/ui/features/ads.js has the
-     * argument; the app's own CSP is what enforces it.
-     */
+    /** app.html, under the editor — mounted only once the key has left the URL. */
+    APP: "6948680552",
+  },
+};
+
+/**
+ * The app's ad slot, independent of who fills it.
+ *
+ * Deliberately not under GOOGLE: the slot is reserved and collapsed by
+ * ui/features/ads.js, which dispatches between networks and must not know
+ * about any of them. That separation is what lets tests/unit/static-check.mjs
+ * assert AdSense identifiers appear in one module only.
+ */
+export const AD = {
+  /**
+   * What the slot asks for, per layout.
+   *
+   * NARROW is requested as a FIXED unit rather than a responsive one, because
+   * the slot sits `flex:none` under an editor that is `flex:1`: every pixel it
+   * takes comes straight out of the textarea. `data-full-width-responsive`
+   * answered a 390px phone with a ~300px creative and left no editor at all.
+   * WIDE is the responsive unit's usual size and is only what the placeholder
+   * claims — that column is drag-resizable, so it is not requested as a fixed
+   * one.
+   */
+  UNIT: {
+    NARROW: { W: 320, H: 50 },
+    WIDE:   { W: 728, H: 90 },
   },
+  /**
+   * How long the slot holds its reserved height before giving it back.
+   *
+   * An ad that never arrives — blocked, offline, or unfilled — used to leave an
+   * empty box above the status bar for the life of the session. Long enough
+   * that a slow fill is not thrown away, short enough that nobody stares at a
+   * hole.
+   */
+  SETTLE_MS: 4000,
+  /**
+   * How long a unit that reported "filled" gets to actually paint, and the
+   * height below which we conclude it did not.
+   *
+   * "filled" is the auction's answer, not the page's: an account still in
+   * review reports filled and renders nothing, which held the reserved 90px
+   * open for the whole session. The smallest unit requested here is 320x50, so
+   * anything under a couple of dozen pixels rendered nothing.
+   */
+  RENDER_GRACE_MS: 1200,
+  MIN_RENDERED_PX: 24,
 };
 
 /** Nothing loads unless the ID that drives it is present. */
@@ -484,9 +556,8 @@ export const analyticsEnabled = () => Boolean(GOOGLE.GA4_ID);
 export const adsEnabled = () => Boolean(GOOGLE.ADSENSE_CLIENT);
 
 /**
- * Consent Mode v2 starts denied in these jurisdictions and stays denied until
- * the CMP says otherwise; everywhere else the tags behave normally. EEA, plus
- * the UK and Switzerland.
+ * Consent Mode v2 starts denied here and stays denied until the CMP says
+ * otherwise; elsewhere the tags behave normally. EEA, plus UK and Switzerland.
  */
 export const CONSENT_REGIONS = [
   "AT", "BE", "BG", "CH", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GB",
@@ -495,15 +566,22 @@ export const CONSENT_REGIONS = [
 ];
 
 /**
- * The page URL with the fragment removed, for `page_location`.
- *
  * !! app.html carries the share key in `location.hash`, and gtag's default
- * `page_location` is `location.href`. The unmodified tag would therefore send
- * the key to Google on the first page_view — the one thing this project
- * promises never leaves the browser. Every gtag config passes this instead. !!
+ * `page_location` is `location.href` — the unmodified tag would send the key to
+ * Google on the first page_view. Every gtag config passes this instead. !!
  */
-export const pageLocation = () =>
-  typeof location === "undefined" ? "" : location.origin + location.pathname + location.search;
+export const pageLocation = () => {
+  if (typeof location === "undefined") return "";
+  /* The desktop webview answers at `tauri.localhost` on Windows and
+     `tauri://localhost` elsewhere — two hostnames for one surface, neither of
+     them ours, both landing in the same property as the real /app. SITE is the
+     public address, and `/app` rather than `/app.html` because that is what the
+     web publishes; the desktop build skips the pretty-URL rewrite, so its
+     on-disk name is not the name a report should show. Which surface a hit came
+     from is `rtc_surface`, not the hostname. */
+  if (IS_DESKTOP) return `${SITE.ORIGIN}/app`;
+  return location.origin + location.pathname + location.search;
+};
 
 export const GOOGLE_SRC = {
   gtag: (id) => `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(id)}`,