ava-engine 0.0.0-stage → 0.1.0

package/public/pcm-worklet.js

@@ -0,0 +1,11 @@
+// Taps raw PCM off the (echo-cancelled) mic graph and posts each 128-sample
+// block to the main thread, which downsamples to 16kHz and ships it to the
+// server's /asr WebSocket. Outputs silence so the node can sit in the graph.
+class PCMTap extends AudioWorkletProcessor {
+  process(inputs) {
+    const ch = inputs[0] && inputs[0][0];
+    if (ch && ch.length) this.port.postMessage(ch.slice(0));
+    return true;
+  }
+}
+registerProcessor("pcm-tap", PCMTap);

package/public/perceptionWorker.js

@@ -0,0 +1,103 @@
+// Off-main-thread screen-change detector. Reads the screen-share track's frames
+// via MediaStreamTrackProcessor (transferred from the main thread), computes a
+// dHash, and — only when the screen actually changes — encodes a JPEG and posts
+// it back. Runs in a Worker, so it is NOT throttled when the tab is backgrounded.
+
+// Two change signals, because one is not enough:
+// - a 32×32 dHash (2048 bits) catches structural/layout change
+// - a pixel-difference test at 128×72 catches TEXT-level change — a tab switch
+//   inside the same modal keeps the layout (tiny hash distance) but rewrites
+//   the words. Thresholds tuned on synthetic screens: a tab switch measures
+//   ~0.7% changed pixels across ~25 columns; a moving mouse cursor ~0.07%
+//   across ~4 columns; a blinking caret ~0%. Text must SPREAD (many columns)
+//   or be big to count, so the mouse never triggers vision calls.
+const THRESH = 20;         // bit hamming distance on the 2048-bit dHash — same units as the server's gate
+const PIX_DELTA = 10;      // per-pixel luma delta that counts as changed
+const RATIO_BIG = 0.003;   // this much of the screen changed → change, regardless of shape
+const RATIO_SMALL = 0.0005;// smaller changes count only when they spread wide…
+const COLS_MIN = 10;       // …across at least this many of the 128 columns
+let last = null, lastLuma = null, lastTime = 0, firstSent = false, running = false, reader = null;
+let lastBitmap = null; // most recent frame, kept so a "grab" answers instantly (screen-share tracks emit no frames while the screen is static)
+const PW = 128, PH = 72;
+let hc, pc, jc;
+function ensure() { if (!hc) { hc = new OffscreenCanvas(33, 33); pc = new OffscreenCanvas(PW, PH); jc = new OffscreenCanvas(8, 8); } }
+
+function dhash(bitmap) {
+  ensure();
+  const ctx = hc.getContext("2d"); ctx.drawImage(bitmap, 0, 0, 33, 33);
+  const d = ctx.getImageData(0, 0, 33, 33).data;
+  const g = (x, y) => { const i = (y * 33 + x) * 4; return d[i] * 0.299 + d[i + 1] * 0.587 + d[i + 2] * 0.114; };
+  let bits = "";
+  for (let y = 0; y < 32; y++) for (let x = 0; x < 32; x++) bits += g(x, y) > g(x + 1, y) ? "1" : "0";
+  for (let y = 0; y < 32; y++) for (let x = 0; x < 32; x++) bits += g(x, y) > g(x, y + 1) ? "1" : "0";
+  let hex = ""; for (let i = 0; i < bits.length; i += 4) hex += parseInt(bits.slice(i, i + 4), 2).toString(16);
+  return hex;
+}
+// Pixel-difference change test vs the frame we LAST ACTED ON (not the previous
+// sample, so slow transitions still add up). Returns true when the change is
+// big, or small-but-wide (real text spans many columns; a cursor doesn't).
+function pixChanged(bitmap) {
+  ensure();
+  const ctx = pc.getContext("2d"); ctx.drawImage(bitmap, 0, 0, PW, PH);
+  const d = ctx.getImageData(0, 0, PW, PH).data;
+  const luma = new Uint8Array(PW * PH);
+  for (let i = 0; i < luma.length; i++) { const j = i * 4; luma[i] = d[j] * 0.299 + d[j + 1] * 0.587 + d[j + 2] * 0.114; }
+  if (!lastLuma) { lastLuma = luma; return true; }
+  let changed = 0; const cols = new Set();
+  for (let i = 0; i < luma.length; i++) if (Math.abs(luma[i] - lastLuma[i]) > PIX_DELTA) { changed++; cols.add(i % PW); }
+  const ratio = changed / luma.length;
+  const isChange = ratio > RATIO_BIG || (ratio > RATIO_SMALL && cols.size >= COLS_MIN);
+  if (isChange) lastLuma = luma; // acted on → new reference
+  return isChange;
+}
+// Bit-accurate hamming distance (per hex digit), matching the server's gate exactly.
+function ham(a, b) {
+  if (!a || !b || a.length !== b.length) return 4096;
+  let d = 0;
+  for (let i = 0; i < a.length; i++) { let x = parseInt(a[i], 16) ^ parseInt(b[i], 16); while (x) { d += x & 1; x >>= 1; } }
+  return d;
+}
+async function encode(bitmap) {
+  // 1600px / q0.8 so small, low-contrast text (per-plan credits, tiny labels)
+  // stays legible to the vision model; larger frames don't cost noticeable latency.
+  const w = bitmap.width, h = bitmap.height, s = Math.min(1, 1600 / Math.max(w, h));
+  jc.width = Math.round(w * s); jc.height = Math.round(h * s);
+  jc.getContext("2d").drawImage(bitmap, 0, 0, jc.width, jc.height);
+  return await jc.convertToBlob({ type: "image/jpeg", quality: 0.8 });
+}
+
+async function loop() {
+  running = true;
+  while (running) {
+    let res; try { res = await reader.read(); } catch { break; }
+    if (res.done) break;
+    const frame = res.value;
+    const now = performance.now();
+    if (now - lastTime < 320) { frame.close(); continue; } // ~3 fps sampling
+    lastTime = now;
+    let bitmap; try { bitmap = await createImageBitmap(frame); } catch { frame.close(); continue; }
+    frame.close();
+    const hash = dhash(bitmap);
+    const textChanged = pixChanged(bitmap); // text-sensitive; keeps its own reference
+    if (last === null || ham(last, hash) > THRESH || textChanged) {
+      const announce = !firstSent; firstSent = true; last = hash;
+      try { const blob = await encode(bitmap); self.postMessage({ type: "change", hash, blob, announce }); } catch {}
+    }
+    if (lastBitmap) lastBitmap.close();
+    lastBitmap = bitmap; // keep for instant grabs; closed when replaced or on stop
+  }
+}
+
+self.onmessage = async (e) => {
+  const m = e.data || {};
+  if (m.type === "start") { last = null; lastLuma = null; firstSent = false; reader = m.readable.getReader(); loop(); }
+  else if (m.type === "stop") { running = false; try { reader && reader.cancel(); } catch {} if (lastBitmap) { try { lastBitmap.close(); } catch {} lastBitmap = null; } }
+  else if (m.type === "grab") {
+    // Answer from the cached frame immediately — waiting on the track stalls
+    // indefinitely when the screen is static (tracks only emit on change).
+    if (!lastBitmap) { self.postMessage({ type: "grabbed", hash: null, blob: null }); return; }
+    ensure();
+    try { const hash = dhash(lastBitmap); const blob = await encode(lastBitmap); self.postMessage({ type: "grabbed", hash, blob }); }
+    catch { self.postMessage({ type: "grabbed", hash: null, blob: null }); }
+  }
+};

package/public/rtc.js

@@ -0,0 +1,60 @@
+"use strict";
+// Minimal WebRTC peer for the specialist handoff. The user is the offerer, the
+// specialist the answerer; signaling is relayed by the server's /rtc socket.
+// Local tracks (screen video + mic on the user; mic on the specialist) are added
+// up front; the remote stream (real screen + voice) is delivered via onRemote.
+function makeRTC(opts) {
+  // opts: { sessionId (user) | key (specialist), role:'user'|'specialist', localStreams:[MediaStream], onRemote(stream), onStatus(str) }
+  const isOfferer = opts.role === "user";
+  const proto = location.protocol === "https:" ? "wss:" : "ws:";
+  const cred = opts.role === "specialist" ? `key=${encodeURIComponent(opts.key)}` : `session=${encodeURIComponent(opts.sessionId)}`;
+  const ws = new WebSocket(`${proto}//${location.host}/rtc?${cred}&role=${opts.role}`);
+  const remote = new MediaStream();
+  let pc = null, pendingIce = [], closed = false, offered = false;
+  const status = (s) => { try { opts.onStatus && opts.onStatus(s); } catch {} };
+  const sig = (m) => { try { if (ws.readyState === 1) ws.send(JSON.stringify(m)); } catch {} };
+
+  function ensurePC() {
+    if (pc) return pc;
+    pc = new RTCPeerConnection({ iceServers: [{ urls: "stun:stun.l.google.com:19302" }, { urls: "stun:stun1.l.google.com:19302" }] });
+    pc.onicecandidate = (e) => { if (e.candidate) sig({ type: "ice", candidate: e.candidate }); };
+    pc.ontrack = (e) => { const s = e.streams && e.streams[0]; if (s) s.getTracks().forEach((t) => { if (!remote.getTracks().includes(t)) remote.addTrack(t); }); else remote.addTrack(e.track); try { opts.onRemote && opts.onRemote(remote); } catch {} };
+    pc.onconnectionstatechange = () => status(pc.connectionState);
+    for (const st of (opts.localStreams || [])) for (const t of st.getTracks()) { try { pc.addTrack(t, st); } catch {} }
+    return pc;
+  }
+  // The peer left (e.g. the specialist refreshed): drop this connection so the
+  // next arrival gets a fresh offer instead of a dead one.
+  function resetPC() {
+    if (pc) { try { pc.close(); } catch {} pc = null; }
+    pendingIce = []; offered = false;
+    remote.getTracks().forEach((t) => remote.removeTrack(t));
+  }
+  async function flushIce() { const q = pendingIce; pendingIce = []; for (const c of q) { try { await pc.addIceCandidate(c); } catch {} } }
+  async function makeOffer() {
+    if (!isOfferer || offered) return; offered = true;
+    ensurePC();
+    try { const o = await pc.createOffer(); await pc.setLocalDescription(o); sig({ type: "offer", sdp: pc.localDescription }); } catch { offered = false; }
+  }
+  ws.onopen = () => status("signaling");
+  ws.onmessage = async (ev) => {
+    let m; try { m = JSON.parse(ev.data); } catch { return; }
+    if (m.type === "peer") {
+      status(m.present ? "peer-present" : "waiting");
+      if (!m.present && pc) resetPC();
+      if (m.present && isOfferer) { if (m.joined && pc) resetPC(); makeOffer(); }
+      return;
+    }
+    if (m.type === "offer") { ensurePC(); try { await pc.setRemoteDescription(m.sdp); await flushIce(); const a = await pc.createAnswer(); await pc.setLocalDescription(a); sig({ type: "answer", sdp: pc.localDescription }); } catch {} return; }
+    if (m.type === "answer") { if (pc) try { await pc.setRemoteDescription(m.sdp); await flushIce(); } catch {} return; }
+    if (m.type === "ice") { if (pc && pc.remoteDescription && pc.remoteDescription.type) { try { await pc.addIceCandidate(m.candidate); } catch {} } else pendingIce.push(m.candidate); return; }
+  };
+  ws.onclose = () => { if (!closed) status("closed"); };
+  return {
+    remote,
+    // Local tracks belong to the caller (the user's live mic and shared screen keep
+    // running after a handoff), so closing only tears down the connection.
+    close() { closed = true; try { ws.close(); } catch {} if (pc) { try { pc.close(); } catch {} pc = null; } },
+  };
+}
+if (typeof window !== "undefined") window.makeRTC = makeRTC;

package/public/specialist.html

@@ -0,0 +1,92 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" href="/favicon.svg" type="image/svg+xml">
+<title>Ava · Specialist console</title>
+<link rel="preload" href="/fonts/inter-tight-var.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>
+<link rel="stylesheet" href="style.css">
+<style>
+  body.spec { display: flex; flex-direction: column; height: 100vh; height: 100dvh; background: var(--canvas); overflow: hidden; }
+  .spec-top { height: 54px; flex-shrink: 0; display: flex; align-items: center; gap: 11px; padding: 0 20px; background: var(--chrome); border-bottom: 1px solid var(--divider); }
+  .spec-title { font-family: var(--disp); font-size: 14px; font-weight: 600; }
+  .spec-sid { font-size: 11px; color: var(--meta); padding: 3px 9px; border: 1px solid var(--edge2); border-radius: 6px; }
+  .spec-conn { display: flex; align-items: center; gap: 6px; font-size: 11px; color: var(--meta); }
+  .spec-conn .dot { width: 7px; height: 7px; border-radius: 50%; background: var(--null); }
+  .spec-conn.live .dot { background: var(--green); animation: livePulse 1.6s ease-in-out infinite; }
+  .spec-main { flex-grow: 1; min-height: 0; display: flex; }
+  .spec-ctx { width: 340px; flex-shrink: 0; overflow-y: auto; padding: 18px 20px; border-right: 1px solid var(--divider); background: var(--chrome); display: flex; flex-direction: column; gap: 18px; scrollbar-width: thin; scrollbar-color: var(--edge) transparent; }
+  .spec-block { display: flex; flex-direction: column; gap: 8px; }
+  .spec-lbl { font-size: 10px; font-weight: 600; letter-spacing: 0.12em; text-transform: uppercase; color: var(--meta); }
+  .spec-goal { font-size: 14px; font-weight: 500; color: var(--ink); line-height: 1.4; }
+  .spec-plat { display: flex; align-items: center; gap: 8px; font-size: 12px; color: var(--ink2); }
+  .spec-screen { font-size: 12px; color: var(--ink2); line-height: 1.5; background: var(--canvas); border: 1px solid var(--hairline); border-radius: 9px; padding: 10px 12px; }
+  .spec-screen b { color: var(--ink); font-weight: 600; }
+  .spec-els { display: flex; flex-wrap: wrap; gap: 5px; margin-top: 7px; }
+  .spec-el { font-family: var(--mono); font-size: 10px; color: var(--ink2); background: var(--chrome); border: 1px solid var(--edge2); border-radius: 5px; padding: 2px 6px; }
+  .spec-blocker { font-size: 12.5px; line-height: 1.5; color: var(--ink); background: rgba(14,140,140,0.08); border: 1px solid rgba(14,140,140,0.25); border-radius: 9px; padding: 10px 12px; }
+  .spec-blocker.none { color: var(--meta); background: var(--canvas); border-color: var(--hairline); }
+  .spec-live { width: 100%; border-radius: 9px; background: #0b0d12; border: 1px solid var(--edge2); display: block; margin-bottom: 8px; }
+  .spec-live[hidden] { display: none; }
+  .spec-mic { display: inline-flex; align-items: center; gap: 6px; font-size: 11px; color: var(--green); }
+  .spec-mic .dot { width: 7px; height: 7px; border-radius: 50%; background: var(--green); animation: livePulse 1.6s ease-in-out infinite; }
+
+  .spec-convo { flex-grow: 1; min-width: 0; display: flex; flex-direction: column; }
+  .spec-msgs { flex-grow: 1; min-height: 0; overflow-y: auto; padding: 20px 24px; display: flex; flex-direction: column; gap: 14px; scrollbar-width: thin; scrollbar-color: var(--edge) transparent; }
+  .sm { max-width: 78%; display: flex; flex-direction: column; gap: 3px; }
+  .sm .who { font-family: var(--mono); font-size: 10px; font-weight: 600; letter-spacing: 0.06em; color: var(--meta); }
+  .sm .bub { padding: 9px 13px; border-radius: 12px; font-size: 14px; line-height: 1.5; }
+  .sm.user { align-self: flex-end; align-items: flex-end; }
+  .sm.user .bub { background: var(--active); color: var(--ink); border-bottom-right-radius: 4px; }
+  .sm.ava .who { color: var(--amber); }
+  .sm.ava .bub { background: var(--brandtint); color: var(--ink); border: 1px solid var(--brandline); border-bottom-left-radius: 4px; }
+  .sm.specialist { align-self: flex-end; align-items: flex-end; }
+  .sm.specialist .who { color: var(--green); }
+  .sm.specialist .bub { background: var(--green); color: #fff; border-bottom-right-radius: 4px; }
+  .sm.system { align-self: center; max-width: 90%; }
+  .sm.system .bub { background: transparent; color: var(--meta); font-size: 12px; font-style: italic; padding: 2px 0; }
+
+  .spec-composer { flex-shrink: 0; display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid var(--divider); background: var(--chrome); }
+  .spec-composer input { flex-grow: 1; height: 44px; padding: 0 14px; border-radius: 10px; border: 1px solid var(--edge); background: var(--control); color: var(--ink); font-family: var(--sans); font-size: 14px; outline: none; }
+  .spec-composer input:focus { border-color: var(--amber); box-shadow: 0 0 0 3px var(--brandtint); }
+  .spec-composer input:disabled { background: var(--active); color: var(--meta); }
+  .spec-empty { margin: auto; text-align: center; color: var(--meta); font-size: 13px; max-width: 340px; line-height: 1.5; }
+  .grow { flex-grow: 1; }
+</style>
+</head>
+<body class="spec">
+  <header class="spec-top">
+    <svg class="wm" viewBox="0 0 66 27.8" role="img" aria-label="Ava"><path transform="translate(1.9 1.9)" d="M0 24L9.5 0L19 24M21.6 0L31.1 24L40.6 0M43.2 24L52.7 0L62.2 24" fill="none" stroke="currentColor" stroke-width="3.8" stroke-linecap="round" stroke-linejoin="round"/></svg>
+    <span class="spec-title">Specialist console</span>
+    <span class="spec-sid mono" id="sid">—</span>
+    <span class="spec-conn" id="conn"><span class="dot"></span><span id="conntext">connecting…</span></span>
+    <span class="spec-mic" id="micind" style="display:none"><span class="dot"></span>Your mic is live</span>
+    <div class="grow"></div>
+    <button id="joinbtn" class="amberbtn" style="height:38px">Join the call</button>
+    <button id="leavebtn" class="ghostbtn" style="height:38px;display:none">Leave</button>
+  </header>
+  <div class="spec-main">
+    <aside class="spec-ctx" id="ctx">
+      <div class="spec-block"><span class="spec-lbl">Session</span><div class="spec-plat" id="platline">—</div></div>
+      <div class="spec-block"><span class="spec-lbl">What they're trying to do</span><div class="spec-goal" id="goal">—</div></div>
+      <div class="spec-block"><span class="spec-lbl">Progress</span><div id="wfmount"></div></div>
+      <div class="spec-block"><span class="spec-lbl">On screen now</span>
+        <video id="liveScreen" class="spec-live" playsinline autoplay hidden></video>
+        <div class="spec-screen" id="screen">Waiting for a screen read…</div>
+      </div>
+      <div class="spec-block"><span class="spec-lbl">Where they may be stuck</span><div class="spec-blocker none" id="blocker">Nothing flagged yet.</div></div>
+    </aside>
+    <main class="spec-convo">
+      <div class="spec-msgs" id="msgs"><div class="spec-empty" id="empty">Loading the conversation…</div></div>
+      <form class="spec-composer" id="form">
+        <input id="input" placeholder="Join the call to message the user…" autocomplete="off" disabled>
+        <button type="submit" class="amberbtn" style="height:44px" id="send" disabled>Send</button>
+      </form>
+    </main>
+  </div>
+<script src="rtc.js"></script>
+<script src="specialist.js"></script>
+</body>
+</html>

package/public/specialist.js

@@ -0,0 +1,132 @@
+"use strict";
+/* global makeRTC -- from rtc.js */
+const $ = (id) => document.getElementById(id);
+const esc = (s) => String(s == null ? "" : s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+// The link carries a specialist key minted for this handoff (not the user's
+// session id); it stops working when the handoff ends.
+const key = new URLSearchParams(location.search).get("key") || "";
+$("sid").textContent = key ? "handoff " + key.slice(0, 8) : "no session";
+
+const S = { since: 0, joined: false, timer: null, seenSeq: 0, dead: false, rtc: null, mic: null, rtcStarting: false };
+const LABEL = { user: "USER", ava: "AVA", specialist: "YOU (SPECIALIST)", system: "" };
+
+function addMsg(e) {
+  if (e.seq <= S.seenSeq) return;
+  S.seenSeq = e.seq;
+  $("empty") && $("empty").remove();
+  const el = document.createElement("div");
+  el.className = "sm " + e.role;
+  if (e.role === "system") el.innerHTML = `<span class="bub">${esc(e.text)}</span>`;
+  else el.innerHTML = `<span class="who">${LABEL[e.role] || e.role}</span><span class="bub">${esc(e.text)}</span>`;
+  $("msgs").appendChild(el); $("msgs").scrollTop = $("msgs").scrollHeight;
+}
+
+function renderContext(c) {
+  if (!c) return;
+  $("platline").textContent = c.platform ? `${c.platform.name} onboarding` : (c.mode === "onboarding" ? "Onboarding" : "Flexible session");
+  $("goal").textContent = c.goal && c.goal !== "—" ? c.goal : "Still figuring out what they need.";
+  // screen
+  if (c.screen) {
+    const els = (c.screen.elements || []).slice(0, 10).map((x) => `<span class="spec-el">${esc(x)}</span>`).join("");
+    $("screen").innerHTML = `<b>${esc(c.screen.app || "?")}</b> · ${esc(c.screen.page || "")}${c.screen.state ? `<br>${esc(c.screen.state)}` : ""}${els ? `<div class="spec-els">${els}</div>` : ""}`;
+  } else $("screen").textContent = "They haven't shared a screen yet.";
+  // reasoning / blocker
+  const b = $("blocker"), r = c.reasoning;
+  if (r && (r.stuck || r.blocker)) { b.className = "spec-blocker"; b.textContent = r.blocker || r.thought || "They seem stuck."; }
+  else if (r && r.thought) { b.className = "spec-blocker none"; b.textContent = r.thought; }
+  else { b.className = "spec-blocker none"; b.textContent = "Nothing flagged yet."; }
+  // workflow
+  renderWf(c.workflow);
+  // connection + join state
+  if (c.specialist && !S.joined) markJoined();
+}
+
+function renderWf(wf) {
+  const m = $("wfmount");
+  if (!wf) { m.innerHTML = '<span style="font-size:12px;color:var(--meta)">No tracked workflow.</span>'; return; }
+  const pct = wf.total ? Math.round((wf.done / wf.total) * 100) : 0;
+  const steps = wf.steps.map((s) => {
+    const sub = s.status === "done" ? "Done" : s.status === "active" ? ("Happening now" + (wf.note ? " · " + esc(wf.note) : "")) : "";
+    return `<div class="wf-step ${s.status}"><span class="wf-mark"></span><div class="wf-stepbody"><span class="wf-steptitle">${esc(s.title)}</span>${sub ? `<span class="wf-substatus">${sub}</span>` : ""}</div></div>`;
+  }).join("");
+  m.innerHTML = `<div class="wf-titlerow" style="margin-bottom:8px"><span class="mono wf-count">${wf.done} / ${wf.total}</span><span class="mono wf-count">${pct}%</span></div><div class="wf-bar" style="margin-bottom:12px"><div class="wf-fill" style="width:${pct}%"></div></div><div class="wf-steps" style="padding:0;overflow:visible">${steps}</div>`;
+}
+
+async function poll() {
+  if (S.dead) return;
+  try {
+    const r = await fetch(`/api/bridge?key=${encodeURIComponent(key)}&since=${S.since}`);
+    if (r.status === 404) { fail("This handoff link has expired or the call ended. Ask the user for a fresh link."); return; }
+    const d = await r.json();
+    S.since = d.seq;
+    (d.events || []).forEach(addMsg);
+    renderContext(d.context);
+    setConn(true);
+  } catch { setConn(false); }
+  S.timer = setTimeout(poll, 1200);
+}
+function setConn(live) { const c = $("conn"); c.classList.toggle("live", live); $("conntext").textContent = live ? (S.joined ? "on the call" : "watching") : "reconnecting…"; }
+// The link is dead (handoff ended, call over): drop the call, the mic and the
+// customer's context — a revoked specialist keeps nothing on screen.
+function fail(msg) {
+  S.dead = true; S.joined = false; clearTimeout(S.timer);
+  stopRTC();
+  $("msgs").innerHTML = `<div class="spec-empty">${esc(msg)}</div>`;
+  for (const id of ["goal", "screen", "blocker"]) { const el = $(id); if (el) el.textContent = "—"; }
+  const wf = $("wfmount"); if (wf) wf.textContent = "";
+  $("joinbtn").style.display = "none"; $("leavebtn").style.display = "none";
+  $("conntext").textContent = "disconnected"; $("input").disabled = true; $("send").disabled = true;
+}
+function markJoined() {
+  S.joined = true;
+  $("joinbtn").style.display = "none"; $("leavebtn").style.display = "";
+  $("input").disabled = false; $("send").disabled = false; $("input").placeholder = "Message the user…"; $("input").focus();
+  setConn(true);
+  startRTC();
+}
+
+// Live A/V: send the specialist's mic, receive the user's screen + voice.
+async function startRTC() {
+  if (S.rtc || S.rtcStarting || !window.makeRTC) return; // set before the await so a second call can't race in
+  S.rtcStarting = true;
+  try { S.mic = await navigator.mediaDevices.getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true } }); $("micind").style.display = ""; } catch { S.mic = null; }
+  S.rtcStarting = false;
+  if (!S.joined) { stopRTC(); return; } // left while the mic prompt was up
+  S.rtc = makeRTC({ key, role: "specialist", localStreams: S.mic ? [S.mic] : [],
+    onRemote: (stream) => {
+      const v = $("liveScreen");
+      v.srcObject = stream; v.play().catch(() => {});
+      const hasVideo = stream.getVideoTracks().length > 0;
+      v.hidden = !hasVideo;
+      $("screen").style.display = hasVideo ? "none" : "";
+    },
+    onStatus: (s) => { if (s === "connected") setConn(true); } });
+}
+function stopRTC() {
+  if (S.rtc) { try { S.rtc.close(); } catch {} S.rtc = null; }
+  if (S.mic) { try { S.mic.getTracks().forEach((t) => t.stop()); } catch {} S.mic = null; }
+  $("micind").style.display = "none"; const v = $("liveScreen"); if (v) { try { v.srcObject = null; } catch {} v.hidden = true; } $("screen").style.display = "";
+}
+$("joinbtn").onclick = async () => {
+  if (!key) return;
+  try {
+    const r = await fetch("/api/bridge", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ key, action: "join" }) });
+    const d = await r.json();
+    if (r.status === 404) return fail("This handoff link has expired or the call ended. Ask the user for a fresh link.");
+    if (d.context) { markJoined(); (d.events || []).forEach(addMsg); S.since = d.seq; } // markJoined starts the A/V link
+  } catch {}
+};
+$("leavebtn").onclick = async () => {
+  try { await fetch("/api/bridge", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ key, action: "leave" }) }); } catch {}
+  stopRTC();
+  S.joined = false; $("joinbtn").style.display = ""; $("leavebtn").style.display = "none"; $("input").disabled = true; $("send").disabled = true; $("input").placeholder = "Join the call to message the user…"; setConn(true);
+};
+$("form").addEventListener("submit", async (e) => {
+  e.preventDefault();
+  const v = $("input").value.trim(); if (!v || !S.joined) return;
+  $("input").value = "";
+  try { await fetch("/api/bridge", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ key, action: "say", text: v }) }); } catch {}
+});
+
+if (!key) fail("No handoff key in the link. The user's call generates a link like /specialist?key=…");
+else poll();