# Euterpe Studio — Desktop Shell (Tauri v2)

A native desktop wrapper around the Euterpe browser DAW
(`apps/euterpe/studio-web`). It hosts the statically-exported Next.js app in a
native window and adds native capabilities a sandboxed browser can't offer.

## What the native shell adds

The browser DAW degrades gracefully to its web behaviour when these aren't
present (see `src/daw/desktop-bridge.ts` — every helper resolves `null`
off-desktop), and uses them when running inside Euterpe Studio:

| Command (`src/commands.rs`)     | Capability                                                                                                                                                                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `export_stems(dir, stems)`      | Render every track and write one `.wav` per stem into a chosen folder in a single pass (browsers can only download files one at a time). Track labels are sanitized + de-duplicated so they can't escape the target directory. |
| `save_project` / `load_project` | Read/write a project document at an arbitrary path, validated as a well-formed Euterpe project (the `.eup` file association).                                                                                                  |
| `reveal_in_file_manager(path)`  | Select the exported folder/file in Finder / Explorer / Files.                                                                                                                                                                  |

The DAW needs cross-origin isolation (`SharedArrayBuffer` for the threaded audio
worklet / WASM). The static export can't emit HTTP headers, so Tauri serves the
`Cross-Origin-Opener-Policy` / `Cross-Origin-Embedder-Policy` headers itself —
see `app.security.headers` in `tauri.conf.json`.

## Layout

```
src-tauri/
  Cargo.toml            # the app crate (tauri 2, dialog/fs/opener plugins)
  tauri.conf.json       # window, security headers, bundle, .eup association
  build.rs              # tauri_build::build()
  src/main.rs           # entry point
  src/lib.rs            # Builder: plugins + invoke_handler
  src/commands.rs       # the native commands (thin wrappers over core/)
  core/                 # euterpe-desktop-core: pure, unit-tested logic
    src/lib.rs          #   path-safe stem naming + project-file validation
  capabilities/default.json  # permissions for the main window
  icons/                # PNG icon set + generate-icons.mjs (regenerates them)
```

The non-trivial logic lives in the dependency-light **`euterpe-desktop-core`**
crate (serde only) so it compiles and unit-tests in seconds — independent of the
heavy WebKit/wry tree. The Tauri commands are thin: decode args, call core, do
the OS I/O.

## Build / run

```bash
# Dev (hot-reload Next on :3041 inside the native window):
npx @tauri-apps/cli dev          # runs `EUTERPE_TAURI=1 next dev -p 3041`

# Production bundle (.app/.dmg/.msi/.deb/.appimage):
npx @tauri-apps/cli build        # runs `EUTERPE_TAURI=1 next build` → out/ → bundle
```

`EUTERPE_TAURI=1` switches `next.config.mjs` to `output: 'export'` (writes
`out/`, which `tauri.conf.json` `frontendDist` consumes) and drops the
dev-server headers (Tauri serves them instead).

To regenerate platform icon containers (`.icns` / `.ico`) from the 512px source:

```bash
node icons/generate-icons.mjs                 # regenerates the PNG set
npx @tauri-apps/cli icon icons/icon.png       # derives .icns/.ico for macOS/Windows
```

## Verification status

Verified here (low-memory laptop, no full compile):

- `euterpe-desktop-core`: **`cargo test` — 9 tests pass** (path-traversal
  safety, Windows-reserved escaping, de-dup, project validation).
- `desktop-bridge.ts`: **6 vitest tests** (global detection, base64 vectors,
  payload shaping, invoke args, browser fallback) + app `tsc` clean + full app
  suite (355).
- `tauri.conf.json` + `capabilities/default.json`: valid JSON; every permission
  id (`opener:allow-reveal-item-in-dir`,
  `fs:allow-write-file/-read-text-file/-mkdir`, the `*:default` sets) confirmed
  present in the resolved plugins.
- `Cargo.toml`: `cargo metadata` valid; **`cargo fetch` resolves the full
  graph** (tauri 2.11, dialog/fs/opener plugins, wry 0.55) with the
  `euterpe-desktop-core` path dep. The `OpenerExt::reveal_item_in_dir` API used
  in `commands.rs` is confirmed against the resolved `tauri-plugin-opener`
  source.

**Full compile — verified on-box (2026-06-06):** `cargo check -j2` finished in
~1m36s with zero errors/warnings, compiling the whole tauri 2.11 + wry/WebKit
tree and the `euterpe-studio` + `euterpe-desktop-core` crates. `tauri_build`
even ran, generating `gen/schemas/` (`capabilities.json`, `desktop-schema.json`,
`macOS-schema.json`) — which validates `tauri.conf.json`,
`capabilities/default.json`, and the `commands.rs` opener/fs/dialog usage end to
end. So the scaffold genuinely type-checks against real Tauri, not just by
resolution. (`-j2` kept peak memory safe on the 16 GB laptop.) The only
remaining step is `tauri build` to bundle the `.app`/`.dmg`/etc.
