# Euterpe-studio-web — Systems Deep Dive

> The shipping browser-delivered DAW: a Next.js (App Router) + React product
> shell, a desktop Tauri wrapper, and ~135 framework-free DAW domain modules
> that drive the Rust/WASM real-time audio engine.

## What this area is

`apps/euterpe/studio-web/` is a single Nx application — project name
`@euterpe/studio-web` — that ships **Euterpe Studio**, the browser-delivered
digital audio workstation. It is the product front end for the whole Euterpe
domain: the place where a user actually arranges, synthesizes, mixes, masters,
and exports music. It is delivered three ways from one codebase — as a Next.js
web app, as an installable PWA (`public/sw.js`, `public/manifest.webmanifest`),
and as a native desktop binary via the Tauri v2 shell under `src-tauri/`.

The app is deliberately split into two layers. The **framework-free product
runtime** lives under `src/` and is pure deterministic TypeScript with no
React/Next imports: `src/index.ts` re-exports four product modules —
`shell-runtime`, `identity-billing`, `telemetry-launch`, and `realtime-mrt2` —
plus the large `src/daw/` directory of ~135 DAW domain modules (synthesis,
mixing, mastering, notation, MIDI/MPE/MIDI2, audio analysis, watermarking, C2PA
provenance, project I/O, and interchange formats such as DAWproject, FCPXML, and
SMF). The **framework binding layer** lives under `app/` (the App Router routes)
and `src/components/daw/` (57 React panels: channel strips, piano roll, drum
rack, arrangement view, mixer buses, mastering, and so on) — thin views that
render the deterministic logic and own the actual browser APIs (WebAudio,
WebMIDI, WebGPU, OPFS). This separation is why nearly every module ships with a
`.spec.ts` next to it: the logic is unit-testable without a DOM.

The DSP itself is **not** here — it is the Rust/WASM real-time engine
`@euterpe/audio-engine-web`, consumed as a workspace dependency. The `/daw`
route's `DawApp` client component drives that engine through the unit-tested DAW
session reducer (`src/daw/daw-session.ts`). The engine worklet + `.wasm` are
served from `/audio`, synced into `public/audio` by
`scripts/sync-engine-assets.mjs` on `predev`/`prebuild` — a stale-aware gate
that rebuilds the worklet when the engine source hash changed so a Rust edit
can't silently ship last build's DSP.

## How the app is shaped

The App Router surface (`app/`) is intentionally thin:

- `app/page.tsx` — the studio home, whose panel visibility is computed by the
  framework-agnostic `resolveLayout` from `shell-runtime`.
- `app/daw/page.tsx` — the DAW route; a `LocaleProvider` wrapping the `DawApp`
  client component, which wires `@euterpe/audio-engine-web`'s `AudioEngine` to
  the session reducer and the full panel set.
- `app/realtime/page.tsx` — the Magenta RealTime 2 panel; a thin WebSocket /
  WebAudio / WebMIDI binding over the deterministic `realtime-mrt2` controller.
- `app/api/copilot/route.ts` — a same-origin Node route that translates a
  natural-language instruction into validated `DawAction`s via the Anthropic
  Messages API (tool use), fail-closed (503 `copilot_not_configured` with no
  key) and always re-validated server-side by `validateActions`.

The four `src/` product modules are large, pure, and self-documenting (numbered
against an internal `38.45.x` spec): `shell-runtime.ts` (~1009 LOC) owns route
registry/resolution, the DAW-engine handshake, timeline renderer math (viewport
culling / LOD / frame budget), service-worker cache + OPFS layout, PWA install
eligibility, the Tauri menu model, the responsive layout resolver,
keyboard-shortcut sets, the MIDI/audio permission state machine, and crash-safe
autosave. `identity-billing.ts` (~973 LOC) and `telemetry-launch.ts` (~1017 LOC)
cover the account lifecycle and the launch-readiness surface respectively.

## How it fits the wider system

This app sits at the very top of the Euterpe stack: it is a leaf consumer, not a
dependency of anything else. Its `package.json` declares `workspace:*`
dependencies on the Euterpe engine and content libraries — `@euterpe/studio`,
`@euterpe/projects`, `@euterpe/studio-runtime`, `@euterpe/audio-engine-web`,
`@euterpe/core`, `@euterpe/master`, `@euterpe/transcribe`, `@euterpe/genesis`,
and `@euterpe/lyrics` — and composes them into a shippable product. The
real-time generation panel talks to the Oshun **BFF** over a WebSocket
(`/v1/generation/realtime`) using the BFF's generation-control envelope
contract; the copilot route talks to Anthropic. Both integrations fail closed
and honestly report "not configured" rather than fabricating a stream or an
action. The Tauri shell adds the native capabilities a sandboxed browser cannot
(folder-wide stem export, arbitrary project-file read/write for the `.eup`
association, reveal-in-file-manager) and serves the COOP/COEP
cross-origin-isolation headers the threaded audio worklet's `SharedArrayBuffer`
requires.

## Entity reference

### @euterpe/studio-web

The Euterpe Studio DAW application — the single Nx project in this area
(`apps/euterpe/studio-web/`, `projectType: "application"`, tags `scope:euterpe`
/ `layer:app` / `type:app`). It is a fully implemented product, not a scaffold:
a Next.js App Router web app (`app/`) over a deterministic, extensively
unit-tested product runtime (`src/`). The barrel `src/index.ts` exposes four
framework-free modules — `shellRuntime` (route registry, engine handshake,
timeline math, SW/OPFS, PWA, Tauri menu, layout, shortcuts, permission state
machine, autosave; `src/shell-runtime/shell-runtime.ts`), `identityBilling`
(onboarding, WebAuthn auth, tier gating, billing/proration, entitlements,
tax/VAT, referrals/seats, legal gates, team provisioning), `telemetryLaunch`
(consent-gated analytics, bug-report bundles, feature-flag rollout with
consistent-hash bucketing, TF-IDF/BM25 help search, A/B two-proportion testing,
SLO aggregation, artifact promotion, the staged launch playbook), and
`realtimeMrt2` (a pure WS session controller for the Magenta RealTime 2
generation stream). The bulk of the DAW lives in `src/daw/` (~135 domain modules
driving `@euterpe/audio-engine-web`, the Rust/WASM real-time engine, via the
`daw-session.ts` reducer) rendered by 57 React panels under
`src/components/daw/`. Native desktop delivery is the Tauri v2 shell in
`src-tauri/` (Rust commands `save_project` / `load_project` / `export_stems` /
`reveal_in_file_manager`, with path-safe logic factored into the unit-tested
`euterpe-desktop-core` crate; the `src-tauri/README.md` records an on-box
`cargo check` of the full tauri 2.11 tree). External integrations — the
`/api/copilot` Anthropic tool-use route and the BFF realtime WebSocket — are
fail-closed: with no credentials they return `503` / show "not configured"
rather than fabricating output.
