@mavea/mavea 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -6,6 +6,102 @@ All notable changes to Mavéa are documented here. The format is based on
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-08-18
+
+### Added
+
+- **What a session cost is now visible** (Settings → Model): tokens sent, how much of that was
+  billed at the cached rate, tokens written back, and which pass spent them. Mavéa is BYOK, so
+  every one of those calls was billed to your key — tokens only, never a guessed currency figure,
+  and nothing is stored or sent anywhere.
+- The dock's explanation-level chip says what it is. It rendered a bare word ("Standard") beside
+  the voice and model chips, so the one control there that isn't self-evident read as a mystery.
+
+### Changed
+
+- **The gap between speaking and being answered isn't blank any more.** When the mic closed, every
+  "I'm hearing you" indicator vanished at once while the words were still being transcribed —
+  which read as not having been heard. The face now holds a working state through it, the
+  listening card holds with its bars stilled instead of unmounting, and the mic button keeps a
+  slowed pulse rather than just dimming. It starts about 1.3 seconds earlier than it could have:
+  the mic reports that you have plainly stopped before its own hangover window closes the
+  utterance, and takes that back if you were only pausing mid-thought. A transcription that lands
+  inside 300ms changes nothing, so a fast machine never flashes.
+- **A backgrounded tab stops animating.** Every ambient loop in the app — the landing's aurora, a
+  card's glow, a hundred-odd others — kept repainting for nobody while the tab sat behind another
+  window. They now pause while the tab is hidden, and a landing section pauses its own once it has
+  scrolled entirely out of view. Nothing you can see ever changes.
+- The demo images ship as AVIF (2.2MB → 1.6MB), and the component reference examples load per
+  answer instead of arriving as one 390KB block held for the whole session (~19KB now stays
+  resident). Both make the first load smaller and the session lighter.
+- Answers below the drawer are generated when you open it, not on every rich turn. Six blocks were
+  written into every answer whether or not anyone opened the drawer they live behind — the most
+  expensive tokens in a turn, spent on content nobody had asked to see. Opening it now generates
+  them once and caches them permanently.
+
+- **A video export no longer takes exactly as long as the video.** Frames were stamped at real
+  elapsed time, so a machine that rasterised slowly stretched them into a slideshow and a fast one
+  gained nothing. The export now runs on its own clock — frame `n` belongs at `n/fps` whenever it
+  finishes — so a weak machine produces the same sharp file, just later, and a strong one finishes
+  ahead of real time. The face is drawn as its own small layer over a cached background, the
+  preview stops rendering a second full-size copy while a render is in flight, and a rasterizer
+  that fails now says so instead of quietly writing a blank video.
+- **Audio is a choice in the export sheet**, on by default. Turning it off skips speech synthesis
+  entirely — captions still pace themselves from the same estimate that drives the duration meter
+  — which is also the cheapest path on a weak machine. Narration that does need synthesising is
+  now made two lines at a time instead of all at once, which is what used to peg the fan.
+- The in-sheet Share button is gone. On desktop it was a share that silently downloaded, then said
+  it had shared; there is now one honest "Download video" action on both tabs.
+- **What a turn costs the model has come down** without changing what it can do: only the leading
+  few components carry a worked example, the per-turn prompt now sits inside the cached prefix on
+  Anthropic instead of after it, a repair pass no longer resends the whole component menu, a
+  speculative glimpse is billed as a glimpse rather than at a reasoning model's floor, and a
+  prefetched suggestion is reused across turns instead of being thrown away and paid for twice.
+
+### Fixed
+
+- **Local storage stops silently losing data.** Every store capped itself, but they share one
+  browser quota and the caps sum past it, so whichever store wrote last simply failed — and said
+  nothing. A refused write now sheds the oldest entry of the largest cache and retries, never
+  touching anything that isn't a cache, and says so once if it still cannot land.
+- **The scrubber's waveform stops repainting itself sixty times a second** while a line plays: the
+  bars are drawn once per track and the playhead is a clip, so playback commits to React about
+  once a second instead of once a frame.
+- Speech no longer wakes up ~470 times to ask whether it can queue the next window, and the audio
+  thread parks itself after 30 seconds of silence rather than idling for the whole session.
+- **A streamed answer stops rebuilding itself as it arrives.** Each closed block used to land in
+  its own render, and a mid-stream flip (a new block family arriving, the first section-tagged
+  block landing) tore the whole grid down and replayed every card's entrance. Blocks now fold into
+  one paint per frame, the loading placeholders hand their grid cell to the real card instead of
+  being replaced wholesale, and the section decision is made once per answer.
+- **A returning dark-mode reader no longer gets a light flash on load.** The boot splash had no
+  way to know the stored choice before the bundle ran; it now takes the system setting as its
+  guess and yields to the real choice the instant it's known.
+- The hero no longer reflows when its display font lands: the fallback is now metric-matched to
+  Newsreader, so the text occupies the same box before and after.
+- **The on-device semantic model (~7MB) is fetched when you reach for the composer**, not on the
+  first keystroke or click anywhere in Live. The behaviour its own comment described was never
+  what the code did — scrolling the page or dismissing a hint counted as "about to ask".
+- Glass blur now goes away where it's supposed to. 29 stylesheets hardcoded their own blur radius
+  and so ignored the performance tier that exists to shed exactly that cost on weak machines.
+- The face's mouth keeps moving on the main conversation surface when another surface is also
+  showing a face. Live was the one mount that never registered as a voice-energy target.
+
+## [1.2.1] - 2026-08-17
+
+### Fixed
+
+- **The legal acknowledgement could not be scrolled, so on a short window there was no way past
+  it.** The gate is a document, but the app shell it appears over locks the viewport
+  (`html, body { overflow: hidden }`) and a hash route change never unloads that lock — so a card
+  taller than the window was clipped at the fold with the two consent checkboxes and Continue
+  underneath it, unreachable by wheel, keys or scrollbar. The gate now re-asserts document
+  scrolling the way the Terms and Privacy pages already did.
+- `pnpm dev` recovers from a broken Docker credential helper again. The retry handed Docker a
+  replacement config directory holding only empty auths, which also discarded the directory Docker
+  Desktop keeps `compose` in — so the rescue attempt failed with `unknown command: docker compose`
+  and local speech never started. It now keeps the real plugin directory in view.
+
 ## [1.2.0] - 2026-08-17
 
 ### Added

package/PRIVACY.md

@@ -25,6 +25,7 @@ Depending on the features you use, browser storage may contain:
 - drafts, tracked items, presentation settings, and recent feature state;
 - provider and model configuration;
 - remembered provider, search, or optional GitHub credentials;
+- a short-lived cache of recent questions and the answers to them, kept on the device so that asking the same thing again does not bill your key a second time; it expires within a day, and it deliberately excludes any answer that drew on attachments, ink, filled-in blanks, cited sources, or your remembered facts;
 - temporary in-progress and finished video-export files in origin-private browser storage until the export is consumed or discarded; and
 - short-lived demo, tour, route, and in-progress session data.
 

package/README.md

@@ -21,7 +21,7 @@ and evidence you can check, marking the exact figure each line is about.
 </p>
 
 ```sh
-npx @mavea/mavea
+npx @mavea/mavea@latest
 ```
 
 Opens `http://localhost:4173` — no install, no account, no model key required.
@@ -32,10 +32,14 @@ Opens `http://localhost:4173` — no install, no account, no model key required.
 
 ## Get started
 
-All you need is **Node 20.19+**. That command above opens the tour and demo replays immediately
+All you need is **Node 22.12+**. That command above opens the tour and demo replays immediately
 — nothing else to set up. Demo replays are fictional, curated prerecorded examples with scripted
 feature choreography; playback does not call a model provider.
 
+The `@latest` tag matters: for a bare package name `npx` can reuse a previously cached copy rather
+than fetching a newer one, so asking for `latest` is what reliably gets you the current release.
+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
 remembering, and each provider request carries it through your same-origin proxy to that
@@ -91,7 +95,7 @@ is in [docs/FEATURES.md](docs/FEATURES.md). In the app, press **⌘K**.
 ## What it looks like
 
 Twelve moments from the walkthrough and the recorded sessions. Every one replays with no key via
-`npx @mavea/mavea` — except the thought map, whose threads need a live model to draw.
+`npx @mavea/mavea@latest` — except the thought map, whose threads need a live model to draw.
 
 <!-- Generated, never hand-captured: `pnpm gen:media` re-shoots these against the current build
      (scripts/capture-media.mts), so a UI change can't quietly leave the README a version behind.
@@ -128,7 +132,7 @@ Mavéa runs on your machine, not in a cloud.
 | **CPU**  | 4 cores | 8 cores     |
 | **RAM**  | 8 GB    | 16 GB       |
 | **Disk** | 3 GB    | 10 GB       |
-| **Node** | 20.19+  | 20.19+      |
+| **Node** | 22.12+  | 24.11+      |
 
 Any browser in [Baseline Widely Available](https://web.dev/baseline) — current Chrome, Edge,
 Safari, or Firefox — on macOS, Windows, or Linux. **Minimum** covers the app with voice off,

package/TERMS.md

@@ -40,7 +40,7 @@ Mavéa can communicate with model, search, speech, media, hosting, OAuth, and ac
 
 You provide and control your own accounts, API keys, OAuth grants, and other credentials. Requests send relevant credentials and content through the deployment's same-origin proxy before reaching the selected third party. The proxy operator can access that material in transit. You must use a deployment operator you trust.
 
-All costs of using the Service are your responsibility, including hardware, electricity, network access, hosting, domains, model tokens, search requests, speech services, storage, OAuth applications, connected-account activity, taxes, and any other third-party charges. Labels such as "fast", "balanced", or "thorough" are relative product descriptions, not price quotes or spending limits. You are responsible for provider budgets, quotas, and billing alerts.
+All costs of using the Service are your responsibility, including hardware, electricity, network access, hosting, domains, model tokens, search requests, speech services, storage, OAuth applications, connected-account activity, taxes, and any other third-party charges. Labels such as "fast", "balanced", or "thorough" are relative product descriptions, not price quotes or spending limits. Any token counts or usage figures the Service displays are informational only: they report what a provider stated for the current session in this browser, are not a billing record, and may be incomplete, unavailable, or wrong — your provider's own account is the authoritative measure of what you were charged. You are responsible for provider budgets, quotas, and billing alerts.
 
 The repository's container definitions can be used with compatible container engines, but the engine or desktop application you choose is separate software. In particular, Docker Desktop is not free for every commercial organization under Docker's current subscription terms. You are responsible for selecting and licensing your development, build, hosting, and container tools; Mavéa does not grant rights in them.
 

package/THIRD-PARTY.txt

@@ -25244,7 +25244,9 @@ whisper.cpp v1.9.1	MIT	https://github.com/ggml-org/whisper.cpp
 Whisper small.en-q5_1	MIT	https://huggingface.co/ggerganov/whisper.cpp
   (local STT model; downloaded into a local volume and verified by SHA-256 before execution)
 Self-hosted fonts	OFL-1.1	public/fonts/LICENSE.txt carries exact notices; OFL-1.1.txt carries the full license; PROVENANCE.md pins every shipped file
-Demonstration media	Pexels License / NASA public domain	see public/demo-assets/CREDITS.md
+Demonstration media	CC0-1.0 / NASA public domain	see public/demo-assets/CREDITS.md
+  (bundled demo photos and the film plate are Wikimedia Commons CC0 dedications, verified per file
+  against the Commons API; the embedded report is a complete work of the US Government)
 Map rendering	MapLibre GL JS (BSD-3-Clause)	https://maplibre.org/maplibre-gl-js/
 Map tiles	OpenFreeMap public service / MIT server	https://openfreemap.org/
   (terms reviewed 2026-08-11 currently permit commercial use without request fees; attribution remains
@@ -25255,12 +25257,18 @@ PDF image decoders	BSD-3-Clause / BSD-2-Clause / MIT	https://github.com/mozilla/
   (jbig2.wasm from PDFium, openjpeg.wasm from OpenJPEG, and qcms_bg.wasm from Mozilla's qcms,
   redistributed via pdfjs-dist and served from dist/pdfjs/ so a scanned page renders; each carries
   its upstream notice beside it as dist/pdfjs/LICENSE_*)
-Syntax-highlighting grammars & themes	MIT and other permissive	https://github.com/shikijs/textmate-grammars-themes
-  (TextMate grammars and GitHub themes redistributed via @shikijs/langs / @shikijs/themes; upstream
-  sources and per-grammar licenses are documented in that repository's tm-grammars / tm-themes metadata)
+Syntax-highlighting grammars & themes	MIT, plus the textmate.org grant for yaml/toml	https://github.com/shikijs/textmate-grammars-themes
+  (25 TextMate grammars and the two GitHub themes redistributed via @shikijs/langs / @shikijs/themes.
+  Resolved per grammar against that repository's tm-grammars / tm-themes metadata, 2026-08-17: 23 are
+  MIT — 20 from microsoft/vscode, swift from jtbandes/swift-tmlanguage, kotlin from fwcd/vscode-kotlin,
+  both themes from primer/github-vscode-theme. yaml and toml come from textmate/yaml.tmbundle and
+  textmate/toml.tmbundle, which carry no SPDX tag but state in their bundle README: "Permission to
+  copy, use, modify, sell and distribute this software is granted." That is an unrestricted permissive
+  grant with no attribution clause; it is recorded here because an automated license scan reads it as
+  null, not because anything about it is unresolved)
 Embedded tour documents	per-document, see below	src/tour/corpus/prism.generated.json
   (byte-for-byte copies embedded for the key-free tour's document-reading chapter; each license
   permits redistribution with this notice)
-  NASA CFD education report excerpt	US-government work, public use permitted	https://ntrs.nasa.gov/citations/19950004435
+  NASA CFD education report (complete, 14pp)	US-government work, public use permitted	https://ntrs.nasa.gov/citations/19950004435
   react/README.md	MIT	https://github.com/facebook/react
   cars.json + seattle-weather.csv	BSD-3-Clause	https://github.com/vega/vega-datasets

package/bin/mavea.mjs

@@ -14,6 +14,7 @@ import {
   renameSync,
   unlinkSync,
   realpathSync,
+  writeFileSync,
 } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
@@ -941,12 +942,146 @@ async function serviceReachable(url) {
   }
 }
 
-function startSpeechServices(runtime) {
+// ---- Kokoro thread tuning ---------------------------------------------------
+//
+// The measured tuner `pnpm dev` runs (scripts/dev.mjs), ported here. Duplicated rather than
+// imported on purpose: the published package ships bin/ and dist/, never the repo's scripts/, and
+// this executable is deliberately dependency-free. Keep the two in step when either changes.
+//
+// There is no thread count that is right for every machine: the same 4 threads that leave a fast
+// box idling at 4x realtime are barely enough on an older one, and the answer depends on per-core
+// speed, which nothing in a compose file can see. Kokoro's throughput is near-linear in threads up
+// to its measured peak (1.12x / 2.47x / 3.38x / 4.23x at 1-4 threads), so one probe at a known
+// thread count yields per-thread speed, and the smallest count clearing the target follows.
+
+/** Speech plays at 1x, so anything above it is only margin — but the margin has to absorb a busy
+ *  machine mid-sentence, and falling behind is audible as a stutter. 2x is the smallest cushion. */
+const VOICE_TARGET_REALTIME = 2;
+/** The measured peak of Kokoro's thread-scaling curve; past this it gets slower AND hungrier. It
+ *  is also the compose default, so a tuned machine only ever comes DOWN from it. */
+const VOICE_MAX_THREADS = 4;
+const VOICE_PROBE_TEXT =
+  'Mavéa is a voice first thinking companion that draws what it means as it speaks.';
+/** Kokoro emits 24kHz mono 16-bit PCM, so byte length converts straight to seconds of audio. */
+const VOICE_PCM_BYTES_PER_SECOND = 24_000 * 2;
+/** Kokoro loads its voice model on first run; a cold pull can take a while, so poll generously. */
+const VOICE_READY_TIMEOUT_MS = 180_000;
+const VOICE_POLL_MS = 1_000;
+
+export function voiceThreadsCacheFile() {
+  return join(lazyCacheDir(), 'voice-threads.json');
+}
+
+/** The thread count this machine settled on last time, or null on a first run (or a cache written
+ *  by a build that measured a different ceiling). */
+export function readCachedVoiceThreads(file = voiceThreadsCacheFile()) {
+  try {
+    const { threads } = JSON.parse(readFileSync(file, 'utf8'));
+    return Number.isInteger(threads) && threads > 0 && threads <= VOICE_MAX_THREADS
+      ? threads
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function rememberVoiceThreads(threads, realtimePerThread, file = voiceThreadsCacheFile()) {
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ threads, realtimePerThread }, null, 2));
+    return true;
+  } catch {
+    // A cache that cannot be written costs one probe per run, which is not worth failing over.
+    return false;
+  }
+}
+
+/** The smallest thread count that clears the realtime target at this machine's measured speed. */
+export function voiceThreadsFor(realtimePerThread) {
+  if (!(realtimePerThread > 0)) return VOICE_MAX_THREADS;
+  return Math.min(
+    VOICE_MAX_THREADS,
+    Math.max(1, Math.ceil(VOICE_TARGET_REALTIME / realtimePerThread)),
+  );
+}
+
+/** The environment a compose spawn runs with: the tuned thread count, or the compose default. */
+export function voiceThreadEnv(threads, env = process.env) {
+  return threads ? { ...env, MAVEA_VOICE_THREADS: String(threads) } : env;
+}
+
+/** Synthesize one clause and return how many seconds of audio came back per second of wall clock. */
+async function measureVoiceRealtime(kokoroUrl) {
+  try {
+    const started = performance.now();
+    const res = await fetch(`${kokoroUrl}/v1/audio/speech`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: 'kokoro',
+        input: VOICE_PROBE_TEXT,
+        voice: 'af_heart',
+        response_format: 'pcm',
+      }),
+      signal: AbortSignal.timeout(60_000),
+    });
+    if (!res.ok) return null;
+    const bytes = (await res.arrayBuffer()).byteLength;
+    const seconds = (performance.now() - started) / 1000;
+    if (!bytes || seconds <= 0) return null;
+    return bytes / VOICE_PCM_BYTES_PER_SECOND / seconds;
+  } catch {
+    return null;
+  }
+}
+
+/** Measure this machine and record the answer for next time.
+ *
+ *  Deliberately does NOT restart the container to apply the new number now: a restart drops the
+ *  voice for as long as the model takes to reload, and the app probes speech availability once per
+ *  page session — a browser that asks during that window would go silent for the whole session
+ *  with nothing to show for it. The default is already safe; the tuned value takes effect on the
+ *  next run, so nobody waits and nothing goes quiet. */
+async function settleVoiceThreads(kokoroUrl, ranAt) {
+  // Best of three, not an average: a busy moment can only ever make synthesis look slower, so the
+  // fastest run is the one closest to what this machine can actually do. The first call also pays
+  // for warmup, which the later ones do not.
+  const runs = [];
+  for (let i = 0; i < 3; i++) {
+    const realtime = await measureVoiceRealtime(kokoroUrl);
+    if (realtime !== null) runs.push(realtime);
+  }
+  if (!runs.length) return;
+  const perThread = Math.max(...runs) / ranAt;
+  const want = voiceThreadsFor(perThread);
+  rememberVoiceThreads(want, Number(perThread.toFixed(3)));
+  if (want === ranAt) return;
+  console.log(
+    `  Voice: this machine only needs ${want} core${want === 1 ? '' : 's'} — applied from the next run.`,
+  );
+}
+
+/** Wait for Kokoro to actually answer before probing it — the model load is what takes the time on
+ *  a first run, and a measurement taken through it would over-provision every later session. Runs
+ *  in the background: the app is already being served while this waits. */
+async function tuneVoiceWhenReady(kokoroUrl, ranAt) {
+  const deadline = Date.now() + VOICE_READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (await serviceReachable(`${kokoroUrl}/health`)) {
+      await settleVoiceThreads(kokoroUrl, ranAt);
+      return;
+    }
+    await new Promise((resolvePoll) => setTimeout(resolvePoll, VOICE_POLL_MS));
+  }
+}
+
+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'], {
     stdio: 'inherit',
+    env: voiceThreadEnv(threads),
   });
 }
 
@@ -1020,7 +1155,13 @@ async function maybeOfferVoice() {
       return;
     }
   }
-  startSpeechServices(runtime);
+  const tuned = readCachedVoiceThreads();
+  const startedAt = tuned ?? VOICE_MAX_THREADS;
+  startSpeechServices(runtime, startedAt);
+  // First run on this machine, and we are the ones bringing the voice up: measure it once it
+  // answers and remember the answer for next time. A voice that was already running is left alone
+  // — the probe costs real CPU, and nothing about it is urgent.
+  if (tuned === null && !kokoroReady) void tuneVoiceWhenReady(kokoroUrl, startedAt);
 }
 
 async function main() {