ava-engine 0.0.0-stage → 0.2.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/setup.css

@@ -0,0 +1,94 @@
+@font-face { font-family: "Inter Tight"; src: url(/fonts/inter-tight-var.woff2) format("woff2"); font-weight: 100 900; font-display: swap; }
+@font-face { font-family: "Inter"; src: url(/fonts/inter-var.woff2) format("woff2"); font-weight: 100 900; font-display: swap; }
+@font-face { font-family: "Plex Mono"; src: url(/fonts/plex-mono-400.woff2) format("woff2"); font-weight: 400; font-display: swap; }
+
+:root {
+  --ink: #0A0A0C; --ink2: #4A4B55; --meta: #686975; --line: #E6E6EB; --soft: #F5F5F7; --card: #FFFFFF;
+  --accent: #4F46E5; --accent-tint: rgba(79,70,229,0.08); --ok: #15803D; --ok-tint: #ECFDF3; --err: #B42318; --err-tint: #FEF3F2;
+  --radius: 14px;
+}
+* { box-sizing: border-box; }
+[hidden] { display: none !important; } /* author display rules (e.g. .field) must not un-hide things */
+html, body { margin: 0; background: var(--soft); color: var(--ink); font: 16px/1.5 Inter, -apple-system, "Segoe UI", sans-serif; }
+a { color: var(--accent); }
+code { font: 13px "Plex Mono", ui-monospace, monospace; background: var(--soft); padding: 1px 5px; border-radius: 5px; }
+
+.shell { display: grid; grid-template-columns: 300px 1fr; min-height: 100vh; min-height: 100dvh; }
+.rail { background: var(--ink); color: #fff; padding: 36px 30px; display: flex; flex-direction: column; gap: 36px; }
+.brand { display: flex; align-items: center; gap: 12px; font: 600 20px "Inter Tight", sans-serif; }
+.brand svg { width: 34px; height: 34px; }
+.brand svg rect { fill: #fff; } .brand svg path { stroke: #0A0A0C; }
+.steps { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; counter-reset: s; }
+.steps li { counter-increment: s; display: flex; align-items: center; gap: 12px; padding: 10px 12px; border-radius: 10px; color: #9D9DAB; font-weight: 500; }
+.steps li::before { content: counter(s); width: 26px; height: 26px; flex: none; display: grid; place-items: center; border-radius: 50%; border: 1.5px solid #3A3A46; font: 500 13px "Plex Mono", monospace; }
+.steps li.done { color: #D6D6E0; } .steps li.done::before { content: "✓"; background: #2B2B36; border-color: #2B2B36; }
+.steps li.current { color: #fff; background: #1C1C24; } .steps li.current::before { border-color: #A5A0FF; color: #A5A0FF; }
+.rail-note { margin-top: auto; font-size: 13px; color: #9D9DAB; }
+.rail-note code { background: #1C1C24; color: #D6D6E0; }
+
+.panel { padding: 56px clamp(20px, 6vw, 88px); max-width: 860px; width: 100%; }
+.eyebrow { margin: 0 0 8px; font: 500 13px "Plex Mono", monospace; letter-spacing: .14em; text-transform: uppercase; color: var(--accent); }
+h1 { margin: 0 0 12px; font: 600 clamp(28px, 4vw, 40px)/1.1 "Inter Tight", sans-serif; letter-spacing: -0.025em; }
+.lead { margin: 0 0 28px; color: var(--ink2); font-size: 17px; max-width: 640px; }
+
+.cards { display: grid; gap: 12px; margin-bottom: 24px; }
+.card { position: relative; display: flex; gap: 14px; align-items: flex-start; padding: 18px 20px; background: var(--card); border: 1.5px solid var(--line); border-radius: var(--radius); cursor: pointer; transition: border-color .15s, box-shadow .15s; }
+.card:hover { border-color: #CFCFD8; }
+.card:has(input:checked) { border-color: var(--accent); box-shadow: 0 0 0 4px var(--accent-tint); }
+.card:has(input:focus-visible) { outline: 2px solid var(--accent); outline-offset: 3px; }
+.card input { margin: 4px 0 0; width: 18px; height: 18px; accent-color: var(--accent); flex: none; }
+.card-body { display: flex; flex-direction: column; gap: 3px; flex: 1; }
+.card-body b { font: 600 17px "Inter Tight", sans-serif; }
+.card-body span { color: var(--ink2); font-size: 14.5px; }
+.card:has(.badge) .card-body { padding-right: 84px; }
+.badge { position: absolute; top: 16px; right: 18px; font: 500 12px "Plex Mono", monospace; color: var(--ok); background: var(--ok-tint); padding: 2px 8px; border-radius: 99px; }
+
+.field { display: flex; flex-direction: column; gap: 8px; margin-bottom: 24px; }
+.field label { font-weight: 600; font-size: 15px; }
+.opt { font-weight: 400; color: var(--meta); }
+.row { display: flex; gap: 8px; flex-wrap: wrap; }
+input[type=text], input[type=password], input[type=number] { flex: 1; min-width: 200px; height: 46px; padding: 0 14px; border: 1.5px solid var(--line); border-radius: 10px; font: 15px "Plex Mono", monospace; background: #fff; color: var(--ink); }
+input:focus-visible { outline: none; border-color: var(--accent); box-shadow: 0 0 0 4px var(--accent-tint); }
+input.short { max-width: 160px; flex: none; }
+.hint { margin: 0; color: var(--meta); font-size: 14px; }
+.keep label, .check { font-weight: 400 !important; display: flex; gap: 10px; align-items: center; font-size: 15px; }
+.keep input, .check input { width: 18px; height: 18px; accent-color: var(--accent); }
+
+.status { margin: 0; min-height: 22px; font-size: 14.5px; }
+.status.ok { color: var(--ok); } .status.err { color: var(--err); }
+.banner { padding: 14px 18px; border-radius: 12px; margin-bottom: 24px; }
+.banner.error { background: var(--err-tint); color: var(--err); }
+
+.job { background: #fff; border: 1.5px solid var(--line); border-radius: 12px; padding: 14px 16px; margin-bottom: 12px; }
+.job-head { display: flex; justify-content: space-between; font-size: 14.5px; margin-bottom: 10px; font-weight: 500; }
+.job-head span:last-child { font-family: "Plex Mono", monospace; color: var(--meta); }
+.bar { height: 8px; background: var(--soft); border-radius: 99px; overflow: hidden; }
+.bar i { display: block; height: 100%; width: 0; background: var(--accent); border-radius: 99px; transition: width .3s; }
+.job.done .bar i { background: var(--ok); } .job.error .bar i { background: var(--err); }
+
+.summary { display: grid; grid-template-columns: max-content 1fr; gap: 14px 28px; background: #fff; border: 1.5px solid var(--line); border-radius: var(--radius); padding: 22px 24px; margin: 0 0 20px; }
+.summary dt { color: var(--meta); font-size: 14.5px; } .summary dd { margin: 0; font-weight: 500; word-break: break-word; }
+
+.nav { display: flex; justify-content: space-between; align-items: center; margin-top: 32px; gap: 12px; }
+.btn { height: 46px; padding: 0 22px; border-radius: 99px; font: 600 15px "Inter Tight", sans-serif; cursor: pointer; border: 1.5px solid transparent; }
+.btn.primary { background: var(--ink); color: #fff; }
+.btn.primary:hover { background: #24242C; }
+.btn.primary:disabled { background: #B9B9C3; cursor: not-allowed; }
+.btn.ghost { background: #fff; color: var(--ink); border-color: var(--line); }
+.btn.ghost:hover { border-color: #CFCFD8; }
+.btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+
+.launching { text-align: center; padding-top: 12vh; }
+.launching .lead { margin-inline: auto; }
+.orb { width: 120px; height: 120px; margin: 0 auto 36px; border-radius: 50%; background: radial-gradient(circle at 35% 30%, #C9C4FF 0%, #8B7CFF 28%, #5B4FF0 60%, #3B2FC4 100%); box-shadow: 0 0 80px rgba(124,108,246,.55); animation: pulse 1.6s ease-in-out infinite; }
+@keyframes pulse { 50% { transform: scale(1.06); box-shadow: 0 0 120px rgba(124,108,246,.75); } }
+@media (prefers-reduced-motion: reduce) { .orb { animation: none; } .bar i { transition: none; } }
+
+@media (max-width: 760px) {
+  .shell { grid-template-columns: 1fr; }
+  .rail { padding: 20px; gap: 16px; }
+  .steps { flex-direction: row; overflow-x: auto; gap: 4px; }
+  .steps li { padding: 6px 8px; font-size: 0; gap: 0; } .steps li.current { font-size: 14px; gap: 8px; }
+  .rail-note { display: none; }
+  .panel { padding: 32px 16px; }
+}

package/public/setup.html

@@ -0,0 +1,129 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Set up Ava</title>
+<link rel="icon" href="/favicon.svg" type="image/svg+xml">
+<link rel="stylesheet" href="/setup.css">
+<script src="/setup.js" defer></script>
+</head>
+<body>
+<div class="shell">
+  <aside class="rail" aria-label="Setup progress">
+    <div class="brand">
+      <svg viewBox="0 0 24 24" aria-hidden="true"><rect width="24" height="24" rx="6" fill="#0A0A0C"/><path transform="translate(2.67 8.4) scale(.3)" d="M0 24L9.5 0L19 24M21.6 0L31.1 24L40.6 0M43.2 24L52.7 0L62.2 24" stroke="#fff" fill="none" stroke-width="3.8" stroke-linecap="round" stroke-linejoin="round"/></svg>
+      <span>Ava Engine</span>
+    </div>
+    <ol class="steps" id="steps">
+      <li data-step="ai">AI replies</li>
+      <li data-step="voice">Voice</li>
+      <li data-step="speech">Speech recognition</li>
+      <li data-step="access">Access</li>
+      <li data-step="review">Launch</li>
+    </ol>
+    <p class="rail-note">Settings are saved on this computer only, in <code id="configFile">~/.ava-engine/.env</code>.</p>
+  </aside>
+
+  <main class="panel">
+    <div id="fatal" class="banner error" role="alert" hidden></div>
+
+    <!-- 1 · AI -->
+    <section class="step" data-step="ai" aria-labelledby="h-ai">
+      <p class="eyebrow">Step 1 of 5</p>
+      <h1 id="h-ai">How should Ava think?</h1>
+      <p class="lead">Ava's AI runs through <a href="https://openrouter.ai" target="_blank" rel="noopener">OpenRouter</a>: one key for every model. You can also look around first with canned replies.</p>
+      <div class="cards" role="radiogroup" aria-label="AI mode">
+        <label class="card"><input type="radio" name="mode" value="full" checked><span class="card-body"><b>With real AI</b><span>Recommended. Needs an OpenRouter key.</span></span></label>
+        <label class="card"><input type="radio" name="mode" value="mock"><span class="card-body"><b>Just look around first</b><span>No key. Canned replies; voice, screen sharing and everything else work.</span></span></label>
+      </div>
+      <div class="field" id="keyField">
+        <div id="keepKeyRow" class="keep" hidden><label><input type="checkbox" id="keepKey" checked> Keep my current key <code id="currentKey"></code></label></div>
+        <div id="newKeyRow">
+          <label for="orKey">OpenRouter API key</label>
+          <div class="row">
+            <input id="orKey" type="password" autocomplete="off" spellcheck="false" placeholder="sk-or-v1-…">
+            <button type="button" class="btn ghost" id="checkKey">Check key</button>
+          </div>
+          <p class="hint">Create one at <a href="https://openrouter.ai/keys" target="_blank" rel="noopener">openrouter.ai/keys</a>, and set a credit limit on it.</p>
+          <p class="status" id="keyStatus" role="status" aria-live="polite"></p>
+        </div>
+      </div>
+      <div class="nav"><span></span><button type="button" class="btn primary" data-next>Continue</button></div>
+    </section>
+
+    <!-- 2 · Voice -->
+    <section class="step" data-step="voice" aria-labelledby="h-voice" hidden>
+      <p class="eyebrow">Step 2 of 5</p>
+      <h1 id="h-voice">Which voice should Ava speak with?</h1>
+      <div class="cards" id="voiceCards" role="radiogroup" aria-label="Voice"></div>
+      <div class="job" id="kokoroJob" hidden>
+        <div class="job-head"><span id="kokoroLabel">Downloading the Kokoro voice</span><span id="kokoroPct">0%</span></div>
+        <div class="bar"><i id="kokoroBar"></i></div>
+      </div>
+      <div class="field" id="elevenField" hidden>
+        <div id="keepElevenRow" class="keep" hidden><label><input type="checkbox" id="keepEleven" checked> Keep my current ElevenLabs key <code id="currentEleven"></code></label></div>
+        <div id="newElevenRow">
+          <label for="elKey">ElevenLabs API key</label>
+          <div class="row"><input id="elKey" type="password" autocomplete="off" spellcheck="false"><button type="button" class="btn ghost" id="checkEleven">Check key</button></div>
+          <p class="status" id="elevenStatus" role="status" aria-live="polite"></p>
+        </div>
+        <label for="elVoice">Voice ID <span class="opt">optional, defaults to Matilda</span></label>
+        <input id="elVoice" type="text" autocomplete="off" spellcheck="false" placeholder="XrExE9yKIg1WjnnlVkGX">
+      </div>
+      <div class="nav"><button type="button" class="btn ghost" data-back>Back</button><button type="button" class="btn primary" data-next>Continue</button></div>
+    </section>
+
+    <!-- 3 · Speech -->
+    <section class="step" data-step="speech" aria-labelledby="h-speech" hidden>
+      <p class="eyebrow">Step 3 of 5</p>
+      <h1 id="h-speech">Offline speech recognition</h1>
+      <p class="lead">Turns your customers' speech into text on this computer, free. Skip it to use Chrome's built-in recognition instead.</p>
+      <div class="cards" id="packCards" aria-label="Speech models"></div>
+      <div id="packJobs"></div>
+      <div class="nav"><button type="button" class="btn ghost" data-back>Back</button><button type="button" class="btn primary" data-next>Continue</button></div>
+    </section>
+
+    <!-- 4 · Access -->
+    <section class="step" data-step="access" aria-labelledby="h-access" hidden>
+      <p class="eyebrow">Step 4 of 5</p>
+      <h1 id="h-access">Who will use this Ava?</h1>
+      <div class="cards" role="radiogroup" aria-label="Who will use Ava">
+        <label class="card"><input type="radio" name="audience" value="me" checked><span class="card-body"><b>Just me, on this computer</b><span>Safest. Reachable only at localhost.</span></span></label>
+        <label class="card"><input type="radio" name="audience" value="others"><span class="card-body"><b>My team or customers</b><span>Over a network or the internet. Needs a password, because every call spends your API credit.</span></span></label>
+      </div>
+      <div class="field" id="passwordField" hidden>
+        <div id="keepPassRow" class="keep" hidden><label><input type="checkbox" id="keepPass" checked> Keep my current password</label></div>
+        <div id="newPassRow">
+          <label for="password">Access password</label>
+          <div class="row"><input id="password" type="text" autocomplete="new-password" spellcheck="false" minlength="10"><button type="button" class="btn ghost" id="regen">New one</button><button type="button" class="btn ghost" id="copyPass">Copy</button></div>
+          <p class="hint">At least 10 characters. You'll type it when you open Ava.</p>
+        </div>
+        <label class="check"><input type="checkbox" id="proxy"> It will run behind a proxy or host (Fly.io, Cloudflare, nginx, Render…)</label>
+      </div>
+      <div class="field">
+        <label for="port">Port</label>
+        <input id="port" type="number" min="1" max="65535" inputmode="numeric" class="short">
+      </div>
+      <div class="nav"><button type="button" class="btn ghost" data-back>Back</button><button type="button" class="btn primary" data-next>Continue</button></div>
+    </section>
+
+    <!-- 5 · Review -->
+    <section class="step" data-step="review" aria-labelledby="h-review" hidden>
+      <p class="eyebrow">Step 5 of 5</p>
+      <h1 id="h-review">Ready to launch</h1>
+      <dl class="summary" id="summary"></dl>
+      <p class="status" id="launchStatus" role="status" aria-live="polite"></p>
+      <div class="nav"><button type="button" class="btn ghost" data-back>Back</button><button type="button" class="btn primary" id="launch">Launch Ava</button></div>
+    </section>
+
+    <!-- launching -->
+    <section class="step launching" data-step="launching" aria-live="polite" hidden>
+      <div class="orb" aria-hidden="true"></div>
+      <h1>Starting Ava…</h1>
+      <p class="lead" id="launchMsg">This takes a few seconds. The app opens here when it's ready.</p>
+    </section>
+  </main>
+</div>
+</body>
+</html>