>_EXECUTIVE SUMMARY
zpwr-embed-terminal is the shared embedded PTY terminal core of the MenkeTechnologies app stack — one Rust source of truth for spawning a persistent login shell with full ANSI support and streaming its output to a host. The TerminalSession core was lifted verbatim from the Audio-Haxor backend (src-tauri/src/terminal.rs) with the Tauri app.emit(...) calls replaced by host-supplied on_output / on_exit callbacks, making it framework-agnostic.
It builds three crate-types from one source: an rlib linked natively by the Tauri apps (Audio-Haxor, traderview, ztranslator), and a staticlib / cdylib linked over a hand-written C ABI by the JUCE-based zpwr-daw. The shared webui/terminal.js front end auto-detects its transport (Tauri vs JUCE), so every host runs byte-for-byte identical PTY handling.
~ARCHITECTURE
One library, two link models. The Rust side owns spawn / stream / resize / kill over portable-pty; consumers attach either natively (rlib) or over the C ABI (staticlib/cdylib). PTY output is delivered through host callbacks; no Tauri or JUCE types appear in the core.
| Layer | Implementation |
|---|---|
| Spawn | native_pty_system() opens a PTY; launches $SHELL -l (defaults to /bin/zsh), inherits HOME + sets cwd, exports TERM=xterm-256color; re-spawn kills the previous session first |
| Stream | a named terminal-reader thread reads 4 KiB chunks, tracks the last valid UTF-8 boundary and carries an incomplete multi-byte tail across reads (no premature U+FFFD); calls on_output per chunk, on_exit on EOF |
| Control | write sends raw keystrokes to the PTY writer; resize notifies the master of a new viewport; kill drops the writer/master and SIGKILLs the child under #[cfg(unix)] |
| Native consumer | Audio-Haxor / traderview / ztranslator link the rlib, wrap TerminalSession in tauri::State, forward callbacks to app.emit(...) |
| C ABI consumer | zpwr-daw links libzpwr_embed_terminal.a (or the cdylib); 6 zet_* exports, C callbacks, declared in hand-written include/zpwr_embed_terminal.h |
| Front end | webui/terminal.js auto-detects Tauri invoke/listen vs JUCE native functions; Ctrl+` or Cmd/Ctrl+T toggles; vendored xterm.js renders the viewport |
| Build | Cargo with crate-type = ["rlib", "staticlib", "cdylib"], publish = false, edition = "2024"; macOS aarch64 + Linux x86_64 |
&C ABI SURFACE
6 extern "C" exports plus two callback typedefs (ZetOutputCb / ZetExitCb), declared in include/zpwr_embed_terminal.h (no cbindgen). The text passed to OutputCb is valid only for the call; the user pointer is shuttled across the reader thread as a usize and never dereferenced by Rust.
| Export | Role |
|---|---|
zet_new / zet_free | create an opaque TerminalHandle; release it (kills the session first) |
zet_spawn | spawn the login shell with OutputCb + ExitCb + verbatim user pointer; returns 0 / -1 |
zet_write | write NUL-terminated UTF-8 keystrokes to the PTY; returns 0 / -1 |
zet_resize | resize the PTY viewport; returns 0 / -1 |
zet_kill | kill the session; handle stays valid and can be re-spawned; returns 0 |
/TRANSPORT SHIM
The shared webui/terminal.js abstracts the IPC so one file backs every host. When window.__TAURI__ is present, calls map to invoke('terminal_spawn'|'terminal_write'|'terminal_resize'|'terminal_kill') and events to listen('terminal-output'|'terminal-exit'). When window.Juce.getNativeFunction is present, the same commands resolve to JUCE native functions and backend events. termPrefs uses the host's global window.prefs if present, else a localStorage shim. Ctrl+` (Backquote) or Cmd/Ctrl+T toggles the embedded terminal popup. The host mounts it at #terminalPane > #terminalContainer.
$CI GATES
| Gate | Command |
|---|---|
| fmt | cargo fmt --all --check |
| clippy | cargo clippy --all-targets -- -D warnings |
| doc | RUSTDOCFLAGS=-D warnings cargo doc --no-deps |
| test | cargo test --verbose (headless; spawns a PTY, runs a command, streams output) |
The umbrella MenkeTechnologiesMeta repo additionally pins this crate's metadata across its gate suite — LICENSE present + canonical MIT text, authors/repository/homepage fields, and the four polish gates above.
#PROJECT METADATA
| Item | Value |
|---|---|
| Version | 0.1.0 |
| Edition | 2024 |
| License | MIT |
| Crate types | rlib + staticlib + cdylib (publish = false) |
| Dependencies | portable-pty (0.9.0), libc (0.2) |
| Consumers | Audio-Haxor, traderview, ztranslator (rlib), zpwr-daw (C ABI) |
| Author | MenkeTechnologies |
| Repository | github.com/MenkeTechnologies/zpwr-embed-terminal |
| Meta umbrella | MenkeTechnologiesMeta |