ava-engine 0.1.0 → 0.2.0

package/lib/cli/setup.mjs

@@ -1,12 +1,15 @@
-// `ava-engine setup`: the guided first-run wizard (and its non-interactive twin).
+// `ava-engine setup` in the terminal: the guided wizard (and its non-interactive twin).
+// The browser version lives in setup-server.mjs; both save through apply.mjs.
 import * as p from "@clack/prompts";
-import { AVA_HOME, CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, writeConfig, checkOpenRouterKey, checkElevenLabsKey, portFree, suggestPassword } from "./config.mjs";
+import { CONFIG_FILE, MODELS_DIR, DEFAULT_PORT, readConfig, writeConfig, checkOpenRouterKey, checkElevenLabsKey, portFree, suggestPassword } from "./config.mjs";
+import { buildConfig, VOICES } from "./apply.mjs";
 import { MODEL_PACKS, installedPacks, fetchPack } from "../fetch-models.mjs";
+import { loadKokoro, kokoroInstalled, KOKORO_SIZE } from "../kokoro-model.mjs";
 
 const mask = (v) => (v ? `${v.slice(0, 6)}…${v.slice(-4)}` : "");
 function bail(v) { if (p.isCancel(v)) { p.cancel("Setup cancelled. Nothing was changed."); process.exit(0); } return v; }
 
-/** Download model packs with a progress bar per file. */
+/** Download speech model packs with a progress bar per pack. */
 export async function downloadPacks(packs) {
   for (const pack of packs) {
     const spec = MODEL_PACKS[pack];
@@ -24,18 +27,37 @@ export async function downloadPacks(packs) {
       if (bar) bar.stop(`${spec.label} ready`); else p.log.success(`${spec.label} already installed`);
     } catch (e) {
       if (bar) bar.error(`${spec.label} failed`);
-      p.log.error(`${e.message}\nYou can retry later with: ava-engine models ${pack}`);
+      p.log.error(`${e.message}\nYou can retry later with: npx ava-engine models ${pack}`);
     }
   }
 }
 
+/** Download the Kokoro voice now, so the first call doesn't wait for it. */
+export async function downloadKokoro() {
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR;
+  if (kokoroInstalled()) { p.log.success("Kokoro voice already installed"); return true; }
+  const bar = p.progress({ max: 100, style: "heavy" });
+  bar.start(`Downloading the Kokoro voice (${KOKORO_SIZE})`);
+  let last = 0;
+  try {
+    await loadKokoro({ onProgress: ({ pct }) => { if (pct > last) { bar.advance(pct - last, `Downloading the Kokoro voice: ${pct}%`); last = pct; } } });
+    bar.stop("Kokoro voice ready");
+    return true;
+  } catch (e) {
+    bar.error("Kokoro voice download failed");
+    p.log.error(`${e.message}\nAva will retry when it starts, or use the browser's voice meanwhile.`);
+    return false;
+  }
+}
+
 /**
  * The interactive wizard. Returns { start: boolean, port }.
  * Existing settings are kept unless you change them.
  */
 export async function runSetup() {
+  process.env.AVA_MODELS_DIR ??= MODELS_DIR; // so "is Kokoro installed?" looks in ~/.ava-engine/models
   const prev = readConfig() || {};
-  const cfg = { ...prev };
+  const answers = {};
 
   console.log("");
   p.intro(" ΛVΛ  Ava Engine setup ");
@@ -43,29 +65,24 @@ export async function runSetup() {
     "A screen-aware voice agent: it joins a call, sees the tab your\n" +
     "customer shares, and talks them through it.\n\n" +
     "This takes about 2 minutes. You can change anything later with\n" +
-    "`ava-engine setup`, or by editing " + CONFIG_FILE,
+    "`npx ava-engine setup`, or by editing " + CONFIG_FILE,
     "Welcome",
   );
 
-  // 1 · how to start
+  // 1 · AI replies
   const mode = bail(await p.select({
-    message: "How do you want to start?",
+    message: "How should Ava think?",
     options: [
-      { value: "full", label: "Full setup", hint: "recommended: real AI replies, voice, speech recognition" },
-      { value: "mock", label: "Just look around", hint: "no API keys; canned replies, everything else works" },
+      { value: "full", label: "With real AI", hint: "recommended; needs an OpenRouter key" },
+      { value: "mock", label: "Just look around first", hint: "no key; canned replies, everything else works" },
     ],
   }));
-
-  // 2 · language models
   if (mode === "mock") {
-    delete cfg.OPENROUTER_API_KEY;
-    p.log.info("MOCK mode: Ava will use canned replies. Run `ava-engine setup` again any time to add a key.");
+    answers.openrouterKey = null;
+    p.log.info("MOCK mode: Ava will use canned replies. Add a key any time with `npx ava-engine setup`.");
   } else {
     let key = prev.OPENROUTER_API_KEY;
-    if (key) {
-      const keep = bail(await p.confirm({ message: `Keep your current OpenRouter key (${mask(key)})?`, initialValue: true }));
-      if (!keep) key = undefined;
-    }
+    if (key && !bail(await p.confirm({ message: `Keep your current OpenRouter key (${mask(key)})?`, initialValue: true }))) key = undefined;
     while (!key) {
       p.log.message("Ava's AI runs through OpenRouter: one key for every model.\nGet one at https://openrouter.ai/keys (set a credit limit on it).");
       const entered = bail(await p.password({ message: "Paste your OpenRouter API key", validate: (v) => (!v || v.trim().length < 20 ? "That doesn't look like a full key" : undefined) })).trim();
@@ -89,96 +106,88 @@ export async function runSetup() {
         if (next === "mock") break;
       }
     }
-    if (key) cfg.OPENROUTER_API_KEY = key; else delete cfg.OPENROUTER_API_KEY;
+    answers.openrouterKey = key || null;
+  }
 
-    // 3 · voice
-    const voice = bail(await p.select({
-      message: "Which voice should Ava speak with?",
-      initialValue: prev.TTS_DEFAULT || "kokoro",
-      options: [
-        { value: "kokoro", label: "Kokoro", hint: "free, runs on this machine; downloads ~90 MB on first start" },
-        { value: "elevenlabs", label: "ElevenLabs", hint: "premium cloud voices, needs an ElevenLabs key" },
-        { value: "browser", label: "The browser's voice", hint: "no setup, sounds robotic" },
-      ],
-    }));
-    cfg.TTS_DEFAULT = voice;
-    cfg.KOKORO = voice === "kokoro" ? "on" : prev.KOKORO === "on" ? "on" : "off";
-    if (voice === "elevenlabs") {
-      let ek = prev.ELEVENLABS_API_KEY;
-      if (ek && !bail(await p.confirm({ message: `Keep your current ElevenLabs key (${mask(ek)})?`, initialValue: true }))) ek = undefined;
-      while (!ek) {
-        const entered = bail(await p.password({ message: "Paste your ElevenLabs API key (elevenlabs.io → API keys)" })).trim();
-        const s = p.spinner(); s.start("Checking the key with ElevenLabs");
-        const r = await checkElevenLabsKey(entered);
-        if (r.ok || r.offline) { s.stop(r.ok ? "Key works" : `${r.error}; saved anyway`); ek = entered; }
-        else { s.error(r.error); if (!bail(await p.confirm({ message: "Try another key?", initialValue: true }))) { cfg.TTS_DEFAULT = "kokoro"; cfg.KOKORO = "on"; break; } }
-      }
-      if (ek) {
-        cfg.ELEVENLABS_API_KEY = ek;
-        const vid = bail(await p.text({ message: "ElevenLabs voice ID (Enter for the default voice, Matilda)", placeholder: "XrExE9yKIg1WjnnlVkGX", defaultValue: prev.ELEVEN_VOICE_ID || "" }));
-        if (vid) cfg.ELEVEN_VOICE_ID = vid.trim(); else delete cfg.ELEVEN_VOICE_ID;
+  // 2 · voice (free and offline by default, so offered in every mode)
+  answers.voice = bail(await p.select({
+    message: "Which voice should Ava speak with?",
+    initialValue: VOICES[prev.TTS_DEFAULT] ? prev.TTS_DEFAULT : "kokoro",
+    options: Object.entries(VOICES).map(([value, v]) => ({ value, label: v.label, hint: value === "kokoro" && kokoroInstalled() ? "free, runs on this computer (installed)" : v.hint })),
+  }));
+  if (answers.voice === "kokoro") await downloadKokoro();
+  if (answers.voice === "elevenlabs") {
+    let ek = prev.ELEVENLABS_API_KEY;
+    if (ek && !bail(await p.confirm({ message: `Keep your current ElevenLabs key (${mask(ek)})?`, initialValue: true }))) ek = undefined;
+    while (!ek) {
+      const entered = bail(await p.password({ message: "Paste your ElevenLabs API key (elevenlabs.io → API keys)" })).trim();
+      const s = p.spinner(); s.start("Checking the key with ElevenLabs");
+      const r = await checkElevenLabsKey(entered);
+      if (r.ok || r.offline) { s.stop(r.ok ? "Key works" : `${r.error}; saved anyway`); ek = entered; }
+      else {
+        s.error(r.error);
+        if (!bail(await p.confirm({ message: "Try another key?", initialValue: true }))) { answers.voice = "kokoro"; await downloadKokoro(); break; }
       }
     }
-
-    // 4 · speech recognition models
-    const have = installedPacks(MODELS_DIR);
-    const packs = bail(await p.multiselect({
-      message: "Download offline speech recognition? (space to toggle, enter to confirm)",
-      required: false,
-      initialValues: have.length ? have : ["english-small"],
-      options: Object.entries(MODEL_PACKS).map(([id, m]) => ({ value: id, label: `${m.label} · ${m.size}`, hint: have.includes(id) ? "installed" : m.hint })),
-    }));
-    const missing = packs.filter((x) => !have.includes(x));
-    if (missing.length) await downloadPacks(missing);
-    else if (!packs.length) p.log.info("No models: Ava will use the browser's speech recognition (Chrome).");
+    if (ek) {
+      answers.elevenKey = ek;
+      answers.elevenVoice = bail(await p.text({ message: "ElevenLabs voice ID (Enter for the default voice, Matilda)", placeholder: "XrExE9yKIg1WjnnlVkGX", defaultValue: prev.ELEVEN_VOICE_ID || "" })).trim() || null;
+    }
   }
 
-  // 5 · who can reach it
-  const audience = bail(await p.select({
+  // 3 · speech recognition (offered in every mode)
+  const have = installedPacks(MODELS_DIR);
+  const packs = bail(await p.multiselect({
+    message: "Download offline speech recognition? (space to toggle, enter to confirm)",
+    required: false,
+    initialValues: have.length ? have : ["english-small"],
+    options: Object.entries(MODEL_PACKS).map(([id, m]) => ({ value: id, label: `${m.label} · ${m.size}`, hint: have.includes(id) ? "installed" : m.hint })),
+  }));
+  const missing = packs.filter((x) => !have.includes(x));
+  if (missing.length) await downloadPacks(missing);
+  else if (!packs.length) p.log.info("No models: Ava will use the browser's speech recognition (Chrome). Add them later with `npx ava-engine models`.");
+
+  // 4 · who can reach it
+  answers.audience = bail(await p.select({
     message: "Who will use this Ava?",
-    initialValue: prev.HOST === "127.0.0.1" || !prev.ACCESS_PASSWORD ? "me" : "others",
+    initialValue: prev.ACCESS_PASSWORD ? "others" : "me",
     options: [
       { value: "me", label: "Just me, on this computer", hint: "safest; reachable only at localhost" },
       { value: "others", label: "My team or customers", hint: "over a network or the internet; needs a password" },
     ],
   }));
-  if (audience === "me") {
-    cfg.HOST = "127.0.0.1";
-    delete cfg.ACCESS_PASSWORD; delete cfg.TRUST_PROXY;
-  } else {
-    delete cfg.HOST;
+  if (answers.audience === "others") {
     const suggested = suggestPassword();
     const how = bail(await p.select({
       message: "Set an access password (every call spends your API credit)",
       options: [
         ...(prev.ACCESS_PASSWORD ? [{ value: "keep", label: "Keep the current password" }] : []),
-        { value: "gen", label: `Use a generated one: ${suggested}`, hint: "recommended; it's saved in the config file" },
+        { value: "gen", label: `Use a generated one: ${suggested}`, hint: "recommended; it's saved in the settings file" },
         { value: "own", label: "Choose my own" },
       ],
     }));
-    if (how === "gen") cfg.ACCESS_PASSWORD = suggested;
-    if (how === "own") cfg.ACCESS_PASSWORD = bail(await p.password({ message: "Access password (at least 10 characters)", validate: (v) => (!v || v.length < 10 ? "Use at least 10 characters" : undefined) }));
-    const proxied = bail(await p.confirm({ message: "Will it run behind a proxy or host (Fly.io, Cloudflare, nginx, Render…)?", initialValue: prev.TRUST_PROXY === "1" }));
-    if (proxied) cfg.TRUST_PROXY = "1"; else delete cfg.TRUST_PROXY;
+    answers.password = how === "keep" ? prev.ACCESS_PASSWORD : how === "gen" ? suggested
+      : bail(await p.password({ message: "Access password (at least 10 characters)", validate: (v) => (!v || v.length < 10 ? "Use at least 10 characters" : undefined) }));
+    answers.proxy = bail(await p.confirm({ message: "Will it run behind a proxy or host (Fly.io, Cloudflare, nginx, Render…)?", initialValue: prev.TRUST_PROXY === "1" }));
   }
 
-  // 6 · port
+  // 5 · port
   const portStr = bail(await p.text({
     message: "Port",
     defaultValue: String(prev.PORT || DEFAULT_PORT),
     placeholder: String(prev.PORT || DEFAULT_PORT),
     validate: (v) => { if (!v) return undefined; const n = Number(v); return Number.isInteger(n) && n > 0 && n < 65536 ? undefined : "Use a number between 1 and 65535"; },
   }));
-  cfg.PORT = String(Number(portStr) || DEFAULT_PORT);
-  if (!(await portFree(Number(cfg.PORT), cfg.HOST))) p.log.warn(`Port ${cfg.PORT} is in use right now. Stop that program, or run \`ava-engine start --port <other>\`.`);
+  answers.port = Number(portStr) || DEFAULT_PORT;
 
-  // 7 · save
-  cfg.AVA_MODELS_DIR = MODELS_DIR;
+  // 6 · save
+  const cfg = buildConfig(prev, answers);
+  if (!(await portFree(Number(cfg.PORT), cfg.HOST))) p.log.warn(`Port ${cfg.PORT} is in use right now. Stop that program, or run \`npx ava-engine start --port <other>\`.`);
   writeConfig(cfg);
   p.note(
     [
       `AI replies     ${cfg.OPENROUTER_API_KEY ? `OpenRouter (${mask(cfg.OPENROUTER_API_KEY)})` : "MOCK mode (canned replies)"}`,
-      `Voice          ${{ kokoro: "Kokoro (offline)", elevenlabs: "ElevenLabs", browser: "the browser's voice" }[cfg.TTS_DEFAULT] || "Kokoro (offline)"}`,
+      `Voice          ${VOICES[cfg.TTS_DEFAULT]?.label || "Kokoro"}`,
       `Speech models  ${installedPacks(MODELS_DIR).map((x) => MODEL_PACKS[x].label).join(", ") || "none (browser speech recognition)"}`,
       `Access         ${cfg.HOST === "127.0.0.1" ? "this computer only" : `password protected${cfg.ACCESS_PASSWORD ? ` (${cfg.ACCESS_PASSWORD})` : ""}`}`,
       `Address        http://localhost:${cfg.PORT}/app`,
@@ -209,11 +218,16 @@ export async function runSetupNonInteractive({ models = [], port } = {}) {
   cfg.AVA_MODELS_DIR = MODELS_DIR;
   writeConfig(cfg);
   for (const pack of models) {
-    console.log(`↓ ${MODEL_PACKS[pack]?.label || pack}`);
+    if (pack === "kokoro") {
+      process.env.AVA_MODELS_DIR ??= MODELS_DIR;
+      console.log("↓ Kokoro voice");
+      if (!kokoroInstalled()) await loadKokoro();
+      continue;
+    }
+    if (!MODEL_PACKS[pack]) throw new Error(`unknown model "${pack}" (choose: ${Object.keys(MODEL_PACKS).join(", ")}, kokoro)`);
+    console.log(`↓ ${MODEL_PACKS[pack].label}`);
     await fetchPack(pack, MODELS_DIR);
   }
   console.log(`Saved ${CONFIG_FILE}${cfg.OPENROUTER_API_KEY ? "" : " (MOCK mode: no OPENROUTER_API_KEY)"}`);
   return cfg;
 }
-
-export { AVA_HOME };

package/lib/kokoro-model.mjs

@@ -0,0 +1,51 @@
+// The offline Kokoro voice model: where it's cached, whether it's there, and
+// loading it with download progress. Shared by the server and the setup wizard.
+//
+// It's cached under the models folder (~/.ava-engine/models/kokoro for the CLI),
+// not inside node_modules, so it survives `npx` updates instead of downloading
+// again after every new version.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const KOKORO_MODEL = process.env.KOKORO_MODEL || "onnx-community/Kokoro-82M-v1.0-ONNX";
+export const KOKORO_DTYPE = process.env.KOKORO_DTYPE || "q8";
+export const KOKORO_SIZE = "~90 MB";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export function kokoroCacheDir() {
+  return process.env.KOKORO_CACHE_DIR || join(process.env.AVA_MODELS_DIR || join(ROOT, "models"), "kokoro");
+}
+
+/** True once the model's weights are on disk (no network needed to start). */
+export function kokoroInstalled(dir = kokoroCacheDir()) {
+  const onnx = join(dir, ...KOKORO_MODEL.split("/"), "onnx");
+  try { return existsSync(onnx) && readdirSync(onnx).some((f) => f.endsWith(".onnx")); } catch { return false; }
+}
+
+/**
+ * Load Kokoro, downloading it first if needed.
+ * onProgress({ loaded, total, pct }) reports the overall download.
+ */
+export async function loadKokoro({ onProgress } = {}) {
+  const { env } = await import("@huggingface/transformers");
+  env.cacheDir = kokoroCacheDir();
+  const { KokoroTTS } = await import("kokoro-js");
+  const files = new Map(); // file → { loaded, total }
+  // Count only the large files (the weights). The small config/tokenizer files
+  // finish first and would make the bar jump to 100% and back.
+  const progress_callback = (e) => {
+    if (!onProgress || e.status !== "progress" || !(e.total > 1_000_000)) return;
+    files.set(e.file, { loaded: e.loaded, total: e.total });
+    let loaded = 0, total = 0;
+    for (const f of files.values()) { loaded += f.loaded; total += f.total; }
+    onProgress({ loaded, total, pct: Math.min(100, Math.floor((loaded / total) * 100)) });
+  };
+  // transformers.js warns about a missing content-length on every download; it's
+  // harmless and would break the setup wizard's progress bar, so hide just that line.
+  const warn = console.warn;
+  console.warn = (...args) => { if (!String(args[0]).includes("content-length")) warn(...args); };
+  try { return await KokoroTTS.from_pretrained(KOKORO_MODEL, { dtype: KOKORO_DTYPE, device: "cpu", progress_callback }); }
+  finally { console.warn = warn; }
+}

package/lib/tts.mjs

@@ -3,6 +3,8 @@
 // audio — works on the oldest device. ElevenLabs/Hume are cloud (paid). "browser"
 // is the on-device Web Speech fallback.
 
+import { loadKokoro, kokoroInstalled } from "./kokoro-model.mjs";
+
 const HAS_ELEVEN = !!process.env.ELEVENLABS_API_KEY;
 const HAS_HUME = !!process.env.HUME_API_KEY;
 const HAS_KOKORO = process.env.KOKORO !== "off"; // local, free — on by default
@@ -13,9 +15,7 @@ const ELEVEN_LABEL = process.env.ELEVEN_LABEL || "Matilda";
 const HUME_VOICE = process.env.HUME_VOICE_ID || "a7ecc00a-6fc0-4546-8126-e12cfd8de3bf";
 const HUME_LABEL = process.env.HUME_LABEL || "Aria";
 const HUME_DESC = process.env.HUME_DESCRIPTION || "Warm, empathetic, natural and reassuring";
-const KOKORO_MODEL = process.env.KOKORO_MODEL || "onnx-community/Kokoro-82M-v1.0-ONNX";
 const KOKORO_VOICE = process.env.KOKORO_VOICE || "af_heart";
-const KOKORO_DTYPE = process.env.KOKORO_DTYPE || "q8";
 
 export const TTS_ENABLED = HAS_KOKORO || HAS_ELEVEN || HAS_HUME;
 const FETCH_TIMEOUT_MS = 20_000;
@@ -50,8 +50,8 @@ let kokoroTTS = null, kokoroInit = null;
 async function initKokoro() {
   if (kokoroTTS) return kokoroTTS;
   if (!kokoroInit) kokoroInit = (async () => {
-    const { KokoroTTS } = await import("kokoro-js");
-    kokoroTTS = await KokoroTTS.from_pretrained(KOKORO_MODEL, { dtype: KOKORO_DTYPE, device: "cpu" });
+    if (!kokoroInstalled()) console.log("  kokoro: downloading the voice model (~90 MB, first run only)…");
+    kokoroTTS = await loadKokoro();
     return kokoroTTS;
   })();
   return kokoroInit;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ava-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "A screen-aware voice agent: sees the tab a user shares, talks them through it, and hands off to a human when needed.",
   "keywords": [
@@ -45,16 +45,20 @@
     "lint": "eslint .",
     "test:all": "npm run lint && npm run check && npm test && npm run test:e2e",
     "demo:record": "node scripts/record-demo.mjs",
-    "cli": "node bin/ava-engine.mjs"
+    "cli": "node bin/ava-engine.mjs",
+    "prepare": "node -e \"if(require('fs').existsSync('.git')&&require('fs').existsSync('.githooks'))try{require('child_process').execFileSync('git',['config','core.hooksPath','.githooks'],{stdio:'ignore'})}catch{}\""
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",
+    "@huggingface/transformers": "3.8.1",
     "kokoro-js": "^1.2.1",
     "sherpa-onnx-node": "^1.13.8",
     "ws": "^8.21.3"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.13.0",
+    "@commitlint/cli": "21.2.4",
+    "@commitlint/config-conventional": "21.2.4",
     "eslint": "^9.39.5",
     "globals": "^15.15.0",
     "playwright": "1.61"
@@ -70,5 +74,9 @@
   "homepage": "https://github.com/Mr-vero/ava-engine#readme",
   "bugs": {
     "url": "https://github.com/Mr-vero/ava-engine/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   }
 }

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>