>_EXECUTIVE SUMMARY
zmax-gui is a thin Tauri v2 desktop host (app/src-tauri) that runs the external zmax editor — a Helix fork — inside an embedded PTY terminal, behind the shared zgui-core app baseline. The Rust host is small by design (~4460 LOC across 15 modules): it resolves the bundled zmax/stryke sidecars, registers the PTY terminal (shared zpwr-embed-terminal crate), and exposes MacVim-style helpers (file-open intake, read-only directory listing, window chrome) plus the project workbench (fuzzy find-files, find-in-files, search & replace, go-to-symbol, find-definition, TODO/markers, bookmarks, tree file ops, batch rename, recent files, git status/diff, per-line git blame, per-file history, stage/unstage/discard, branch checkout/create, stash save/pop/drop, two-file compare, repo-wide log/graph, diff-revisions, align-columns, comment-toggle, encoding detect/convert, persisted snippets, project code-stats, file cleanup/convert and sort-lines transforms). All UI chrome — menu bar, dialogs, file tree, command palette, toasts — comes from the shared zgui-core submodule (window.ZGui.*); the app hand-rolls no widgets. The GUI never edits files itself: every action is bridged into the editor by writing into the PTY (e.g. :open <path>).
~MODULE MAP
The Rust host (app/src-tauri/src) is twelve small modules; the front end mounts the shared zgui baseline and bridges everything into the PTY. The zmax editor itself is external — it runs inside the terminal, not as host code.
| Module | Layer | Role |
|---|---|---|
| main.rs | Rust host | Tauri entry point — registers terminal + GUI commands, wires the PTY's output/exit to webview events, sets up single-instance, deep-link and opener plugins. |
| terminal.rs | Rust host | Embedded PTY adapter over the shared zpwr-embed-terminal crate; the editor runs inside this PTY, forwarding on_output/on_exit to the webview. |
| sidecar.rs | Rust host | Resolves the bundled zmax / stryke sidecars (env override → beside the executable → PATH) so the app is self-contained and never depends on PATH. |
| open_intake.rs | Rust host | File-open intake — the MacVim "open from Finder / mvim CLI / mvim:// URL" surface; queues + live-emits open-files. Carries the unit tests. |
| fs_ops.rs | Rust host | Read-only directory listing backing the zgui file-open dialog (ZGui.modal + ZGui.tree); the open itself happens by writing into the PTY. |
| window_ops.rs | Rust host | Window chrome the zgui menubar drives — MacVim fullscreen / transparency / blur analogs (no native UI). |
| project.rs | Rust host | The project workbench backend: fuzzy find-files, find-in-files (regex/case/word), tree file ops (create/rename/delete/copy), persisted recent files, file stats and git status/branch/diff. Carries its own unit tests. |
| editor_tools.rs | Rust host | The editor-tools backend beside project.rs: persisted bookmarks, project-wide search & replace (regex, preview then apply on disk), a workspace symbol outline (go-to-symbol) and a TODO/marker scan. Carries its own unit tests. |
| git_tools.rs | Rust host | A deeper git surface: per-line blame (line-porcelain parse + dep-free date), per-file history (log --follow) with show-commit diffs, working-tree staging (stage / unstage / discard), and a two-file compare (diff --no-index). Carries its own unit tests. |
| workbench_ext.rs | Rust host | Workbench extras: persisted code snippets (a named text library the front end pastes into the editor) and a read-only project code-stats report (file / line / byte counts by extension, reusing the project.rs tree walker). Carries its own unit tests. |
| git_ext.rs | Rust host | Branch and stash management beside git_tools.rs: list / checkout / create local branches (for-each-ref, flag-guarded refs) and drive the stash (save / list / pop / drop / show patch). Carries its own unit tests (round-trip against a throwaway repo). |
| text_tools.rs | Rust host | On-disk file transforms and navigation: file cleanup/convert (line endings, trailing whitespace, tab expand/tabify, final newline), sort-lines (reverse/case/numeric/unique), find-definition (reuses the editor_tools symbol rules), and batch rename of file base names (preview then apply, collision-guarded). Carries its own unit tests. |
| edit_ops.rs | Rust host | On-disk content transforms beside text_tools.rs: align columns on a delimiter (literal or regex, the way Emacs align-regexp lines up =/:///) and language-aware comment toggle over a line range (prefix chosen by extension). Preview then apply. Carries its own unit tests. |
| encoding_ops.rs | Rust host | Character-encoding detect + transcode: sniff BOM / UTF-8 / UTF-16LE/BE / Latin-1 and line ending, then convert to UTF-8 (BOM-free), UTF-16LE/BE (BOM-prefixed) or Latin-1. Preview then apply. Carries its own unit tests. |
| git_more.rs | Rust host | Repo-wide git surfaces beside git_tools.rs: whole-repository log (with ref decorations), full show-commit diff, diff between any two revisions (optionally path-scoped, flag-guarded) and the ASCII commit graph across all refs. Carries its own unit tests (round-trip against a throwaway repo). |
| frontend/main.js | Frontend | Shell entry — mounts ZGui.appShell baseline and execs zmax in the fullscreen embedded terminal. |
| frontend/menu.js | Frontend | MacVim-style menu bar, ⌘-shortcuts and Open/Save-As/Help dialogs, built entirely from zgui-core widgets and bridged to the PTY. |
| frontend/panels.js | Frontend | The project workbench overlays (quick-open, find-in-files, search & replace, go-to-symbol, find-definition, TODO/markers, bookmarks, recent, project files, batch rename, align columns, comment toggle, file encoding, snippets, project stats, sort-lines, file cleanup, compare files, git changes / blame / history / repo-log / commit-graph / diff-revisions / staging / branches / stash), added to the ⌘K palette; drives project.rs/editor_tools.rs/git_tools.rs/git_ext.rs/git_more.rs/text_tools.rs/edit_ops.rs/encoding_ops.rs/workbench_ext.rs and opens results via the PTY. |
| frontend/terminal.js | Frontend | Shared zpwr-embed-terminal xterm.js frontend (PTY transport, geometry persistence). |
| frontend/i18n.js | Frontend | Shared zpwr-i18n runtime (window.t), loading the 27 JSON locale catalogs. |
| lib/zgui-core | Submodule | Shared cyberpunk UI baseline — ZGui.appShell (⌘K palette, colour-scheme picker, settings, CRT/splash), modal, tree, menubar, toast. Sole source of UI elements. |
~DEPENDENCY FOOTPRINT
A deliberately lean dependency set: the Tauri runtime, three Tauri plugins for MacVim-style behaviour, and the shared embedded-terminal crate. Six git submodules are vendored, and the zmax/stryke binaries ship as Tauri externalBin sidecars — no PATH dependency.
| Dependency | Kind | Why |
|---|---|---|
| tauri 2 | Rust | Desktop host runtime + webview. |
| serde / serde_json 1 | Rust | Command payload (de)serialization. |
| tauri-plugin-single-instance 2 | Rust | Forward a 2nd launch's file args into the running window (MacVim behaviour). |
| tauri-plugin-deep-link 2 | Rust | Register the mvim / zmax URL schemes. |
| tauri-plugin-opener 2 | Rust | Open the log file / data dir from the appShell Diagnostics buttons. |
| zpwr-embed-terminal | Rust (path) | Shared embedded PTY terminal crate (also used by Audio-Haxor, ztunnel, ztranslator, zpwr-daw). |
| window-vibrancy 0.6 | Rust (macOS) | Translucent blurred window material (MacVim transparency analog). |
| @tauri-apps/cli ^2 | JS dev | Build / dev tooling; pnpm-managed. |
Six Vendored Submodules
frontend/lib/zgui-core (UI baseline), crates/zpwr-embed-terminal (PTY), crates/zmax (the editor itself, a Helix fork), crates/zpwr-file-browser, crates/zpwr-i18n, and crates/zmax-gui-core (shared GUI core + webui).
Self-Contained Sidecars
The zmax and stryke binaries are bundled as Tauri externalBin sidecars, so the app has no PATH dependency.
Project Workbench
An IDE layer in the ⌘K palette (and shortcuts): Quick Open fuzzy finder (⌘P), Find in Files with regex/case/word (⇧⌘J), Search & Replace across the tree with regex capture refs, preview and apply-on-disk (⇧⌘H), Go to Symbol workspace outline (⇧⌘O), Find Definition of an exact symbol (⇧⌘D), a TODO / Markers scan (⇧⌘T), persisted Bookmarks (⌘B), persisted Recent Files (⌘E), a Project Files tree manager (new/rename/delete/copy/info, ⇧⌘E), Batch Rename of file names (preview then apply), persisted Snippets inserted via bracketed paste (⇧⌘I), a Project Stats report and a two-file Compare. Results open at path:line:col in the editor.
Text Transforms
On-disk editing helpers that mutate a file then reload it in the editor: Sort Lines (reverse / ignore-case / numeric / unique), File Cleanup (line endings LF/CRLF, trailing whitespace, tab expand/tabify, final newline), Align Columns on a delimiter (literal or regex, align-regexp style), Comment / Uncomment a line range (⇧⌘/) with the language's prefix, and File Encoding detect + transcode (UTF-8 / UTF-16LE/BE / Latin-1). Each shows a dry-run preview before Apply. Binary/oversized files are skipped.
Git Tools
A deeper git surface: the Git Changes panel stages / unstages / discards each file inline (with refresh); per-line Blame (⇧⌘B) with commit / author / date and click-to-jump; per-file History (log --follow) with the diff each commit introduced (show); a repository-wide Log and ASCII Commit Graph; Diff Revisions between any two branches/tags/hashes (path-scopable); a general two-file Compare via diff --no-index (works outside a repo); Branches (list / checkout / create, flag-guarded); and Stash (save / list / pop / drop / show patch).
~VERIFICATION
pnpm test (scripts/test.sh) runs two suites — a headless JS bridge suite and a Rust unit suite. The runner is honest about what it can build offline, and no end-to-end / UI automation exists yet.
| Suite | Cases | What it guards |
|---|---|---|
| crates/zmax-gui-core/webui/menu.test.cjs | 32 | JS bridge tests — load menu.js in a vm context with a stubbed __TAURI__ and assert the exact escape sequences the menu actions write into the PTY, guarding the command mapping (zmax is a Helix fork, so buffers, not tabs). |
Rust #[test] (host modules) | 54 | Unit tests across open_intake.rs (open-intake parsing), project.rs (fuzzy score, walk pruning, file ops, search), editor_tools.rs (bookmarks, replace, symbols, markers), git_tools.rs (civil-date, blame parse, no-index diff), workbench_ext.rs (snippet round-trip, code-stats), git_ext.rs (ref guard, stash selector, branch/stash round-trip in a throwaway repo), text_tools.rs (text transform, sort, leading-number, rename guard, find-definition, on-disk apply), edit_ops.rs (align padding, comment prefix/round-trip, on-disk apply), encoding_ops.rs (BOM/UTF-16/Latin-1 sniff, decode/encode round-trip, transcode on disk) and git_more.rs (rev guard, repo-log parse, log/show/diff/graph round-trip in a throwaway repo). |
| e2e / UI automation | 0 | None yet — the app is an MVP. |
Honest Sidecar Skip
Because the Rust binary embeds tauri::generate_context!(), which validates the externalBin sidecars at compile time, the runner stages the sidecars first and honestly skips the Rust pass (rather than failing spuriously) when they can't be produced — e.g. offline with no zmax build.
MVP
No end-to-end / UI automation exists yet. The editor runs in the embedded terminal with the zgui baseline; native tabs, menu bar and open/save dialogs are on the roadmap.