yazi-gui-app
main, initialization, window lifecycle, dependency injection.
Architecture & decisions
The final architecture and product contract.
OwlCommander is a full graphical file manager, not a TUI skin. The boundaries below must be recorded in docs/decisions/ before they change, and dependencies only flow downward.
Layers
Dependencies flow downward only.
The GUI may never touch std::fs or the Windows Shell directly; the engine may never reference GPUI types; COM details never escape their adapter.
gpui-shellWindow · Menu · Dock
WindowTitleBarMenuTabsSidebarDockDialogNotification
yazi-gui-uiGPUI views
FileViewportPreviewPaneOperation UISearchSettingsPluginHost
yazi-gui-applicationstate
ReducerAction dispatcherWindow sessionCommand registryDTO
yazi-gui-bridgestable boundary
Engine APIEvent streamRequest cancellationPlugin UI IRprivilege boundary
yazi-enginefrozen fork · headless core
CoreVFSFSSchedulerWatcherPluginRunnerConfigDDS
platform-windowsadapter
COM ShellIFileOperationRecycle BinD&DThumbnailsfile associationsIME
Plugins and the GUI exchange only GuiEvent, GuiCommand, GuiView (a restricted serialized UI description) and file DTOs.
Cargo workspace
Eleven crates, one clean path.
Every crate has a single responsibility; test doubles live in testkit.
yazi-gui-ui
GPUI Entities, views, theme and component assembly.
yazi-gui-viewport
High-performance FileViewport: list, grid, rubber-band select, drag & drop.
yazi-gui-preview
PreviewController and text/image/media/archive presenters.
yazi-gui-application
Commands, reducers, window/tab session.
yazi-gui-bridge
Engine facade, DTOs, event protocol, cancellation.
yazi-gui-engine
UI-free engine extracted and wrapped from vendor/yazi.
yazi-gui-plugin-host
Lua runtime, Yazi plugin adapter, GuiView IR.
yazi-gui-storage
SQLite: workspace, history, favorites, layout, cache index.
yazi-gui-platform
Platform traits — pure interfaces plus test fakes.
yazi-gui-platform-windows
Windows implementation; COM never escapes.
yazi-gui-testkit
Virtual filesystem, time, Shell, drag & drop and screenshot doubles.
Operation contract
There is exactly one write path.
Every OperationPlan is preflighted before it starts: capabilities, same-path conflicts, identical source/target, permissions, disk space and overwrites.
INTENT
With RequestId
Every request carries a RequestId, LocationRevision and CancellationToken.
PLAN
Preflight
Capabilities, conflicts, same source/target, permissions, space, overwrites; failures are rejected, never degraded to silent overwrite.
DISPATCH
Sole write authority
Chooses IFileOperation under WindowsShellLocal or the Yazi VFS executor.
EXECUTE
Cancellable
Progress lands in the task center; late results are discarded by revision.
Delete semantics: local deletes prefer the Recycle Bin; non-local providers go through the Yazi VFS executor; a non-recoverable delete is never presented as "recycling".
Decision records
32 recorded boundaries and acceptances.
Before changing an architectural boundary or safety semantic, a decision must be recorded here.
Verification gates
The door every commit must pass.
.\scripts\bootstrap.ps1 -VerifyOnly cargo +1.98.0 test --locked --offline cargo +1.98.0 clippy --locked --offline -- -D warnings git diff --check
Formatting uses cargo +1.98.0 fmt. UI work stays non-blocking; STA COM/OLE stays pinned to the documented broker thread; COM interface pointers never cross threads.
Upstream lock
One frozen baseline.
UPSTREAM_LOCK.json, Cargo.lock and .cargo/vendor form a single non-drifting baseline. No cargo update, no floating Git dependencies, no edits to vendored upstream source — unless an explicit upgrade/patch decision says so.