@mavea/mavea 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -6,6 +6,32 @@ All notable changes to Mavéa are documented here. The format is based on
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-08-18
+
+### Fixed
+
+- **A downloaded conversation video no longer ends inside a spotlight.** The closing beat hands
+  the canvas back and plays wide, carved out of the last scene so the cut still ends exactly
+  where the narration does; the closing caption and Pen marks stay.
+- **A map now names its places.** Each pin's name and detail line render in a numbered list
+  beside the map — numbered to the circles themselves — instead of living only in a click-away
+  popup. The list survives a map that fails to load, the same way a route keeps its stops.
+- **First run: the speech questions come before the browser opens.** The window used to open
+  over the terminal mid-prompt, so the voice and transcription setup was easy to never see and
+  the first impression was silently captions-only. `npx @mavea/mavea` now asks first, then opens.
+- **`npx @mavea/mavea` no longer reports a running voice as missing.** The reachability probe
+  hit the service roots, and Kokoro's root answers 404 — so every start offered to set up
+  speech services that were already up. It probes the health endpoints now.
+- **Repeat starts stop rebuilding speech images the machine already has.** Compose builds only a
+  missing image now (the whisper tag carries its version, so a version bump still builds), on
+  Docker and Podman alike.
+
+### Changed
+
+- The README and setup guide say plainly what is free and what is metered: the model call is
+  billed by the provider under your key; the app and both speech services run locally at no
+  per-use cost, and published transcripts or voiced videos owe no fee and no credit line.
+
 ## [2.0.0] - 2026-08-18
 
 ### Added

package/README.md

@@ -41,7 +41,9 @@ than fetching a newer one, so asking for `latest` is what reliably gets you the
 Prefer a pinned local copy? `npm install -g @mavea/mavea`, then run `mavea`.
 
 **To talk to a real model (Live):** click **"Open Mavéa"** and paste an Anthropic / OpenAI /
-Gemini / Grok / OpenRouter key. It stays in memory unless you opt into encrypted local
+Gemini / Grok / OpenRouter key. Model usage is billed by that provider under your key, at its
+rates — the model call is the part of a turn that costs money; the app and the speech services
+run on your machine for free. The key stays in memory unless you opt into encrypted local
 remembering, and each provider request carries it through your same-origin proxy to that
 provider — your key and prompts never pass through Mavéa's own servers, because there aren't
 any. Full options — models, actions, hosting, and the trust boundary — are in
@@ -49,7 +51,9 @@ any. Full options — models, actions, hosting, and the trust boundary — are i
 
 **Local speech:** Mavéa speaks through Apache-2.0
 [Kokoro weights and wrapper](https://github.com/remsky/Kokoro-FastAPI) and transcribes through MIT-licensed
-[whisper.cpp](https://github.com/ggml-org/whisper.cpp). The defaults run on your machine through
+[whisper.cpp](https://github.com/ggml-org/whisper.cpp). Both cost nothing per use, and what they
+produce is yours: publishing a transcript, or a video spoken in Mavéa's voices, owes no fee and no
+credit line — those licenses cover the software, not its output. The defaults run on your machine through
 loopback-only proxies; a deployment that overrides `WHISPER_URL` sends microphone audio to that
 configured endpoint. [Podman](https://podman.io/) is the recommended free/open-source
 container runtime. Docker also works, but Docker Desktop has separate commercial subscription

package/bin/mavea.mjs

@@ -1075,11 +1075,24 @@ async function tuneVoiceWhenReady(kokoroUrl, ranAt) {
   }
 }
 
+/**
+ * The compose invocation that starts speech, for whichever runtime is present — Docker, Podman and
+ * podman-compose all take the same verbs, so the caching behaviour below is identical on each.
+ *
+ * `--build` is deliberately absent. It forces a build pass on EVERY run, which re-resolves the
+ * whisper image on a machine that already has it; without it compose builds only when the image is
+ * missing and reuses what is already there. That is safe because the tag carries the version
+ * (`mavea-whisper-cpp:1.9.1` in docker-compose.yml), so a version bump is a new tag and does build,
+ * while a repeat run on the same version costs nothing. Kokoro is pinned by digest and compose's
+ * default `--pull missing` never re-pulls a digest it already holds.
+ */
+export function composeUpArgs(runtime, composeFile = COMPOSE_FILE) {
+  return [...runtime.prefix, '-f', composeFile, 'up', '-d'];
+}
+
 function startSpeechServices(runtime, threads) {
-  console.log(
-    '  Starting Kokoro TTS + whisper.cpp STT. The first run builds/downloads pinned models…',
-  );
-  spawn(runtime.command, [...runtime.prefix, '-f', COMPOSE_FILE, 'up', '-d', '--build'], {
+  console.log('  Starting Kokoro TTS + whisper.cpp STT. The first run downloads pinned models…');
+  spawn(runtime.command, composeUpArgs(runtime), {
     stdio: 'inherit',
     env: voiceThreadEnv(threads),
   });
@@ -1100,12 +1113,19 @@ const VOICE_INTRO =
   '\n◌ Configured speech — Kokoro reads replies and whisper.cpp transcribes your mic.\n' +
   '  The defaults are loopback-only. A custom WHISPER_URL receives microphone audio at that endpoint.\n';
 
+/** A speech service's health endpoint. Probed instead of the root because the roots differ —
+ *  Kokoro's answers 404 (FastAPI routes /health, not /) — so a root probe reported a running
+ *  voice as missing on every start and offered to set up services that were already up. */
+export function speechHealthUrl(base) {
+  return base.replace(/\/+$/, '') + '/health';
+}
+
 async function maybeOfferVoice() {
   const kokoroUrl = process.env.KOKORO_URL || 'http://localhost:8880';
   const whisperUrl = process.env.WHISPER_URL || 'http://localhost:8100';
   const [kokoroReady, whisperReady] = await Promise.all([
-    serviceReachable(kokoroUrl),
-    serviceReachable(whisperUrl),
+    serviceReachable(speechHealthUrl(kokoroUrl)),
+    serviceReachable(speechHealthUrl(whisperUrl)),
   ]);
   if (kokoroReady && whisperReady) return;
   if (!existsSync(COMPOSE_FILE) || !process.stdin.isTTY) {
@@ -1164,6 +1184,19 @@ async function maybeOfferVoice() {
   if (tuned === null && !kokoroReady) void tuneVoiceWhenReady(kokoroUrl, startedAt);
 }
 
+/**
+ * Speech is settled BEFORE the browser opens, and the order is the whole point: the setup questions
+ * live in this terminal, so a window opening over them is how a first run ends up permanently
+ * without voice or transcription — the reader never sees the prompt, the answer falls to a default
+ * nobody chose, and the experience they judge Mavéa on is the degraded one. Nothing here waits on
+ * containers (the compose spawn is detached), so the cost is one reachability probe plus however
+ * long the answers take.
+ */
+export async function settleStartup(args, { offerVoice, openApp }) {
+  if (args.voice) await offerVoice();
+  if (args.open) openApp();
+}
+
 async function main() {
   let args;
   try {
@@ -1228,8 +1261,7 @@ Podman is the recommended free/open-source container runtime. Docker Desktop has
   console.log(`Terms:   ${base}/legal/TERMS.md`);
   console.log(`Privacy: ${base}/legal/PRIVACY.md`);
   console.log(`License: ${base}/legal/LICENSE.txt (PolyForm Noncommercial 1.0.0)`);
-  if (args.open) openBrowser(base);
-  if (args.voice) await maybeOfferVoice();
+  await settleStartup(args, { offerVoice: maybeOfferVoice, openApp: () => openBrowser(base) });
 }
 
 // npm/npx installs `bin` entries as a symlink (node_modules/.bin/mavea -> ../@mavea/mavea/bin/