@mavea/mavea 1.0.11 → 1.0.13

package/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to Mavéa are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.0.11] - 2026-07-23
 
 ### Fixed — the pre-launch pass
 
@@ -141,6 +141,23 @@ Everything below was found by measuring, not by reading.
 - **Canvas** — `BlockBoundary` now calls `console.error` in `componentDidCatch` so block render
   failures are visible in the browser console without crashing the canvas or the voice track.
 
+### Fixed — shipping the npm package
+
+- **`npx @mavea/mavea` silently did nothing.** npm/npx installs `bin` entries as a symlink, and
+  the CLI's "is this the main module" check compared an unresolved symlink path against the
+  module's real path — they never matched, so `main()` ran zero times with no error and exit
+  code 0. Fixed by resolving both sides through the real filesystem path before comparing, and
+  added a regression test that reproduces npm's actual symlink mechanism (the existing smoke
+  test invoked the file directly, with no symlink involved, so it could never have caught this).
+- **Published under `@mavea/mavea`, not `mavea`.** npm's anti-typosquatting check blocks new
+  unscoped package names it judges too similar to existing ones; scoping sidesteps it.
+- **The README's mascot images didn't render on npm's package page.** Relative image paths
+  resolve against GitHub's raw-content host, which requires authentication for a private repo —
+  they now load from jsDelivr's npm CDN instead, which serves straight from the published
+  package regardless of the source repo's visibility.
+- Release publishing no longer requests npm provenance attestation, which npm rejects outright
+  for a private source repository.
+
 ### Removed
 
 - Dead code — an unused descriptor system, an unused text-fitting module, and a chain of unused

package/README.md

@@ -28,20 +28,39 @@ and evidence you can check, marking the exact figure each line is about.
   <img src="https://img.shields.io/badge/Vite-8-646CFF?style=flat-square&logo=vite&logoColor=white" alt="Vite 8" />
 </p>
 
-**Try it in one command:** `npx @mavea/mavea`
+```sh
+npx @mavea/mavea
+```
+
+Opens `http://localhost:4173` — no install, no account, no model key required.
 
 </div>
 
 ---
 
+## Get started
+
+All you need is **Node 20.19+**. That command above opens the tour and demo replays immediately
+— nothing else to set up.
+
+**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
+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
+[docs/LIVE-SETUP.md](docs/LIVE-SETUP.md).
+
+**The voice:** Mavéa speaks through [Kokoro](https://github.com/remsky/Kokoro-FastAPI), a natural
+local text-to-speech model that runs in Docker. The first time you start it, Mavéa offers to set
+Docker up for you; without it, every line just appears as a caption instead — nothing else
+changes.
+
 ## What it does
 
 Mavéa is an AI you talk to and watch think. Ask out loud: a calm face listens, speaks the headline
 the instant it forms, then steps aside while a living canvas draws the answer in charts, timelines,
 and evidence you can check. As it talks, it draws on the answer, circling the exact figure each line
-is about. Sourced claims keep their links and estimates can be labelled. Provider keys stay in
-memory by default; optional remembering encrypts them locally. Live requests send them through the
-same-origin proxy you run or deploy, onward to the model provider you chose.
+is about. Sourced claims keep their links and estimates can be labelled.
 
 A few specific things worth trying:
 
@@ -60,176 +79,26 @@ A few specific things worth trying:
 The full tour — Atlas, Rehearsal, living dashboards, Ripple, Share-as-a-Mavéa-Story, and ~30 more —
 is in [docs/FEATURES.md](docs/FEATURES.md). In the app, press **⌘K**.
 
-## Two ways in
-
-- **Demo replays** — recorded persona sessions (for example, a CFO reviewing her quarter or a
-  parent planning dinner). Each answer was generated once by a real model and frozen; it replays
-  on the same Live surface, without a key. The characters are fictional; the answers are real
-  model output.
-- **Live** — bring your own model (Anthropic, OpenAI, Gemini, xAI Grok, or OpenRouter) and ask
-  anything by voice or text, answered on the same canvas.
-
-Honesty is built in, not bolted on: confidence labels, sourced claims, and a Live
-[eval harness](docs/BENCHMARK.md) that scores whether a model picks the right visualization and
-labels its estimates honestly.
-
-## Quick start
-
-Just want to run it? All you need is **Node 20.19+**:
-
-```sh
-npx @mavea/mavea                # → http://localhost:4173 — tour + demo replays, no model key required
-```
-
-Working on the source? Use pnpm instead (`corepack enable` once to get the pinned version):
-
-```sh
-pnpm install
-pnpm dev                  # → http://localhost:5173 — dev server, with voice
-pnpm build                # → dist/ — production build
-pnpm preview              # → http://localhost:4173 — serves dist/ exactly as npx @mavea/mavea does, voice included
-```
-
-| Command        | What it does                                                                                                                                                                                                                                                             |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `pnpm dev`     | Starts everything: brings up the Kokoro voice container, then Vite. If Docker isn't running, it says so and serves the app anyway — answers appear as captions instead of being spoken.                                                                                  |
-| `pnpm dev:web` | Vite alone, no voice container. Faster to start if you don't need speech.                                                                                                                                                                                                |
-| `pnpm build`   | Type-checks, then produces the production bundle in `dist/`.                                                                                                                                                                                                             |
-| `pnpm preview` | Serves the `dist/` build with the exact server `npx @mavea/mavea` runs: same-origin `/tts` + `/llm` proxies included, and it offers to bring up the Kokoro voice container when Docker is present. Without Docker it says so in one line and answers appear as captions. |
-| `pnpm test`    | Runs the Vitest suite once.                                                                                                                                                                                                                                              |
-| `pnpm verify`  | The full pre-PR gate: reference-example + gallery-fixture freshness → typecheck → lint → format check → test → build → bundle-size budget → artifact + package boundary checks. Run this before opening a PR.                                                            |
-
-That's the everyday set. The rest of the scripts (linting, evals, one-off audits, internal tooling)
-are documented in full in [CONTRIBUTING.md](./CONTRIBUTING.md#scripts-reference).
-
-**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 provider. Full options — models,
-actions, hosting, and the trust boundary — are in
-[docs/LIVE-SETUP.md](docs/LIVE-SETUP.md).
-
-**The voice:** Mavéa speaks through [Kokoro](https://github.com/remsky/Kokoro-FastAPI), a natural
-local TTS — the one thing that runs in Docker. `pnpm dev` and `pnpm preview` both start it for
-you; it's optional, and without it every line appears as captions. To run or stop it on its own:
-
-```sh
-docker compose up -d     # Kokoro TTS on :8880 — dev and preview both proxy /tts to it
-docker compose down      # stop it (it otherwise stays up between dev sessions)
-```
-
 ## What it needs
 
-Mavéa runs on your machine, not in a cloud. One set of numbers covers both using it and working on
-it, because the toolchain is the heavier of the two and it still isn't heavy.
+Mavéa runs on your machine, not in a cloud.
 
 |          | Minimum | Recommended |
 | -------- | ------- | ----------- |
 | **CPU**  | 4 cores | 8 cores     |
 | **RAM**  | 8 GB    | 16 GB       |
 | **Disk** | 3 GB    | 10 GB       |
-| **Node** | 24.11+  | 24.11+      |
-
-Both columns describe your whole machine rather than Mavéa's share of it, and neither is a bare
-floor. **Minimum** is the app and its toolchain with the voice off, alongside the browser and editor
-you already have open. **Recommended** adds the voice and Docker on top of that, with enough room
-left that you never think about any of it. Any browser in
-[Baseline Widely Available](https://web.dev/baseline) — current Chrome, Edge, Safari, or Firefox —
-on macOS, Windows, or Linux.
-
-For reference, Mavéa itself asks for far less, and it's worth knowing which part costs what.
-`npx @mavea/mavea` serves a static build and the work happens in your browser tab: the page it loads
-is 89 kB over the wire, and every surface becomes usable in under half a second on a CPU throttled
-6×. The toolchain is heavier and still modest — a production build peaks around 1.6 GB of memory and
-finishes in ~12 s, a full typecheck of all 2,200 TypeScript files peaks under 1 GB and takes ~3 s,
-and a checkout with dependencies and a build output on disk comes to ~750 MB. Everything caches, so
-only the first run after a fresh clone is slow.
-
-**The voice is the one part that costs real memory, and it's optional.** Kokoro's image is 4.9 GB on
-disk and holds ~1.3 GB resident, and Docker Desktop itself adds ~1.5 GB before a word is spoken.
-Synthesis briefly takes a few cores, and runs ahead of the playhead rather than at it. At the 8 GB
-minimum, leaving the voice off is usually the better trade: every line becomes a caption and nothing
-else changes. `docker compose down` reclaims all of it; the
-container otherwise stays up between sessions on purpose, so the next start is instant, and
-`pnpm dev:web` starts Vite without bringing Docker up at all.
-
-**Nothing here should make a fan audible.** The always-on costs are the animated face and the glass
-blur, so rather than guessing from core count, Mavéa watches its own frame pacing for the first few
-seconds and calms both if this particular machine is actually struggling — an integrated GPU choking
-on blurred glass is invisible to a spec sheet. It waits for two bad windows before demoting, so one
-hitch won't do it, and it never promotes back mid-session. You can also just decide for it:
-**Visual richness → Lite** in Live's settings is a per-device choice that takes effect immediately.
-Everything else is idle until you ask it something — the one part that will genuinely work a CPU is
-voice synthesis, and that only runs if you started Docker.
-
-## How it works
-
-Mavéa is one conversation surface (Live) plus a marketing landing, hash-routed in `main.tsx`.
-However a turn is triggered — voice, text, a chip, or a replayed demo frame — it resolves to
-the same shape:
+| **Node** | 20.19+  | 20.19+      |
 
-```
-ask ─▶ generateLive ─▶ validate/repair ─▶ settle (merge + tour) ─▶ Presence (the face) + Canvas (the blocks)
-```
+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,
+alongside the browser and whatever else you already have open. **Recommended** adds Kokoro
+(voice) and Docker on top, with enough room that you never think about it.
 
-The canvas is data, not components: every answer is a list of typed `{ type, props }` blocks
-(`data/conversation.ts`). A model never emits UI — it emits those same blocks, which
-`live/generateLive` streams, validates, and repairs into the `ConversationSpec` contract. The
-demo replays are frozen outputs of this exact pipeline, so they render through the same
-contract and renderer. The generated selection catalog contains **600 component contracts across
-23 families**, and the gallery production-renders every one of them — including the types that are
-gated or surface-owned rather than offered in ordinary model selection. Every provider sits behind
-one `ProviderAdapter`; Live credentials and
-prompts cross the same-origin proxy operated by whoever runs the deployment before reaching the
-selected provider. This repository does not include a hosted account, analytics, or data-retention
-service.
-
-The full design — the turn contract, the validation core, the BYOK proxy diagram, and the eval
-harness — is in [ARCHITECTURE.md](./ARCHITECTURE.md).
-
-## Built with
-
-A deliberately small stack — React 19, TypeScript 6, Vite 8 — with no chart library and no UI
-framework beyond React: every chart, dial, diagram, and the face is hand-rolled SVG/CSS. Beyond
-`react`/`react-dom`, the runtime stays lean: `@ricky0123/vad-web` (Silero VAD for end-of-speech)
-plus a handful of feature-scoped libraries — KaTeX, Leaflet, jsPDF, pdfjs-dist, openchemlib,
-mediabunny, modern-screenshot, pptxgenjs, and Shiki — each lazy-loaded only when that feature is used and
-bundled rather than fetched from a CDN. JavaScript/TypeScript snippets run only after an explicit
-click in a bounded Worker; Python execution is disabled until it has an equally isolated runtime.
-The face is one hand-drawn SVG animated purely by CSS off `data-*` attributes — JS never transforms
-it.
-
-## Documentation
-
-| Doc                                                        | What's in it                                               |
-| ---------------------------------------------------------- | ---------------------------------------------------------- |
-| [docs/FEATURES.md](./docs/FEATURES.md)                     | The detailed product feature tour                          |
-| [ARCHITECTURE.md](./ARCHITECTURE.md)                       | The turn lifecycle, the seams, and how the pieces fit      |
-| [docs/BENCHMARK.md](./docs/BENCHMARK.md)                   | The eval as a benchmark — score any model, leaderboard     |
-| [docs/LIVE-SETUP.md](./docs/LIVE-SETUP.md)                 | Running Live: models, voice, actions, troubleshooting      |
-| [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)                 | Edge contract: TLS, HTTP/2/3, compression, cache, headers  |
-| [docs/ADDING-A-COMPONENT.md](./docs/ADDING-A-COMPONENT.md) | The full contract + scaffold for a new canvas block        |
-| [CONTRIBUTING.md](./CONTRIBUTING.md)                       | Setup, the full script reference, conventions, and recipes |
-| [docs/ENGINEERING.md](./docs/ENGINEERING.md)               | The review rubric: security, scalability, readability      |
-| [SECURITY.md](./SECURITY.md)                               | The BYOK security model and how to report a vulnerability  |
-| [TERMS.md](./TERMS.md)                                     | Terms for using the software and connected features        |
-| [PRIVACY.md](./PRIVACY.md)                                 | Local, provider, proxy, storage, and transfer data flows   |
-| [DISCLAIMER.md](./DISCLAIMER.md)                           | Plain-language AI and third-party risk summary             |
-
-## Feedback and maintenance
-
-Issues with code-free bug reports and feature suggestions are welcome. This repository does not
-accept external code, patch, or documentation pull requests; see [CONTRIBUTING.md](./CONTRIBUTING.md)
-for the maintainer workflow and feedback rules. Maintainer changes are held to the
-[engineering bar](./docs/ENGINEERING.md) (security, scalability, readability), and CI runs
-`typecheck → lint → format → test → build` plus bundle, dependency, secret, and static-analysis
-checks.
-
-Two checks the unit suite can't make, both against a running `pnpm dev`:
-
-```bash
-pnpm audit:ui             # every block, 280px → 4K, both themes: clipped · overlapping · illegible
-pnpm perf                 # every surface under CPU throttling — and nothing heavy loaded unasked
-```
+**The voice is the one part that costs real memory, and it's optional.** Kokoro's image holds
+roughly 1.3 GB resident, and Docker Desktop itself adds another ~1.5 GB before a word is spoken.
+At the 8 GB minimum, leaving voice off is usually the better trade — every line becomes a caption
+and nothing else changes. `docker compose down` reclaims it whenever you want it back.
 
 ## 📄 License