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 scaffold in app; build blocked by missing system development packages (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 blocker

cargo check in app/src-tauri failed on this machine because the GTK/WebKit/dbus development packages are absent and sudo needs a password:

Package 'dbus-1' was not found
The system library `dbus-1` required by crate `libdbus-sys` was not found.

pkg-config also reports missing webkit2gtk-4.1 and gtk+-3.0. The shell is scaffolded, not verified.

Install the Fedora development packages (one command, needs your password):

sudo dnf install dbus-devel webkit2gtk4.1-devel gtk3-devel libappindicator-gtk3-devel \
  librsvg2-devel openssl-devel libsoup3-devel javascriptcoregtk4.1-devel pkgconf-pkg-config

Then:

cargo check --manifest-path app/src-tauri/Cargo.toml
npm --prefix ui run build
npm --prefix app run tauri dev      # expects the daemon and Vite to be running

The Tauri window loads http://127.0.0.1:5173; the daemon remains a separate process in P0. Embedding the engine in the Tauri backend is P1 work, after the engine's lifecycle is settled.

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: blocked by system development packages; the exact command is above.

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.