zhila/docs/P0.md

P0 · hello engine

The first phase proves the spine: Rust audio, a session with a journal, a protocol with two transports, and a surface that reacts to the sound. The demo in reference/demo is the visual reference; none of its code is used here.

What was built

Area	Deliverable
Protocol	zhila-protocol: JSON messages, five veins, pattern, state, binary meter frame; unit tests
Session	zhila-core: engine trait, validation, revisions, journal for tempo/gain, default sixteen-step phrase; tests
Engine	zhila-engine: cpal 0.18, 48 kHz stereo, fixed 256-frame buffer where available, 32-voice pool, five vein timbres, phrase clock, per-vein levels, master level; no allocation on the audio path
Daemon	zhila-daemon: WebSocket, hello/token/protocol/origin checks, snapshot, results, broadcast events, 30 Hz binary meters, current-thread Tokio, graceful Ctrl-C
Surface	Svelte 5 + Vite: audio-reactive descent, wire log, engine facts, cilia, signal trace, per-vein gain sliders, transport, keyboard
Verification	cargo test, cargo clippy, svelte-check, production build, live wire test, browser smoke + screenshots
Shell	Tauri 2 built and launched; native window against the daemon (below)

Decisions taken in P0

• cpal, not Web Audio. The browser is a surface; sound is native Rust. The cpal 0.18 API uses a unified cpal::Error, SampleRate = u32, Display for the device name and a by-value StreamConfig.
• JSON control + binary meters. Control metadata is small and debuggable; meters are 31-byte frames at 30 Hz.
• One daemon, one session. Loopback + token + origin guard are the P0 security boundary. No production auth yet.
• The journal is for project edits. Play/stop/strike are performance and do not pollute undo.
• The surface is a projection. The server owns state; the UI applies snapshots, results and events. The canvas owns only its visual phase.
• Every layer reacts to sound. The terrain alpha/offset, eye size/glow/rings, city lights, dust, road bands, stone glow, playhead, lane fills, chrome hairlines, cilia, signal trace and master line all read the five vein levels and the master. No decorative animation is independent of the audio.

Tauri verification (resolved)

The shell was built and launched on 2026-11-01 after the Fedora development packages were installed:

• webkit2gtk-4.1 2.54.2
• gtk+-3.0 3.24.52
• dbus-1 1.16.2
• javascriptcoregtk-4.1 2.54.2
• libsoup-3.0 3.8.1
• Tauri 2.12.5 · CLI 2.12.4

npm --prefix ui run build
cd app
./node_modules/.bin/tauri build --no-bundle
# with the daemon running:
./src-tauri/target/release/zhila-app

cargo check --manifest-path app/src-tauri/Cargo.toml and the release build pass. The native window loads the embedded surface, opens the wire (wire open, engine live), and renders the descent and the engine panel. The screenshot is preview-tauri.png at the repository root.

In P1f the Tauri app was given its own host: the engine, session, project store and wire run inside zhila-app, so the native window is self-contained. The standalone daemon remains the browser-development path. The earlier dbus-1/webkit2gtk/gtk failure is historical; those packages are now present.

P0 exit criteria

• A browser surface talks to a Rust daemon over a local protocol: passed.
• Real cpal output with five veins and non-zero meters: passed (Default Audio Device, 48 kHz, 256-frame buffer, master peak ~0.45 in the wire test).
• A session that validates and journals project edits: passed (Rust tests).
• A surface that visibly reacts to the five levels: passed (canvas, cilia, trace, gains; screenshots).
• A Tauri window on Linux: passed on 2026-11-01 (WebKitGTK 2.54.2; screenshot preview-tauri.png).

Next

P1: core session and material. Import/record, analysis, cores and faces, a zoomable waveform, a real pattern model, a flat precision view while the descent remains the primary arrangement, and the first journal-backed undo. The plan and cut lines are in PLAN.md.