Shell Layout & Navigation
Relevant source files
The following files were used as context for generating this wiki page:
The JARVIS Shell serves as the "Private Control Room," a native Electron interface designed with a focus on immediate feedback and flat information architecture. It provides a unified workspace for AI interaction, system telemetry, and automation management, adhering to the principle of "one home for settings, conversation, and the composer."
Sources: tests/shell-layout.test.ts:14-18, src/index.html:20-25
Primary Structural Layout
The application utilizes a three-tier architectural split where Electron owns the machine lifecycle, the agent backend owns the workload (sessions/streaming), and the renderer owns the experience and navigation presentation. The layout is structured as a CSS Grid consisting of three main vertical columns: the Navigation Sidebar, the Central Workspace, and the Context Rail.
Sources: instructions/AGENTS.md:16-21, src/renderer.css:179-185
Grid System Anatomy
The control-grid defines the primary interface boundaries. It is configured with dynamic column widths to accommodate a resizable context rail.
| Element | CSS Selector | Description |
|---|---|---|
| Header | .control-header | Contains the titlebar, telemetry, and global voice hard-mute toggle. |
| Sidebar | .shell-sidebar | Primary navigation navigation host with support for collapsed states. |
| Workspace | .workspace-stack | The central area containing the Orb Stage and the Command Dock. |
| Resizer | .panel-resizer | Draggable handle for adjusting the width of the Context Rail. |
| Context Rail | .control-stack | Right-side column containing system services and the conversation feed. |
| Footer | .control-footer | Displays build status, contracts, and system authority details. |
Sources: src/index.html:20-75, src/renderer.css:179-195
The diagram above represents the nested DOM hierarchy of the main application shell.
Sources: src/index.html:43-524, src/renderer.css:179-195
Navigation and View Routing
Navigation is centralized in the shell-sidebar, which categorizes destinations into Home, Workspace, Automation, and System groups. The system distinguishes between Durable Destinations (Pages) and Short Tasks (Route Overlays).
Stage View Management
Route destinations are rendered as central stage pages within the stage-view-wrapper rather than side-overlay cards. When a module (e.g., Memory, Files, Settings) is activated, the orb-stage transitions from a "hero" mode to a "mini" mode to provide space for the content.
- Hero Mode: Focuses on the Identity Orb core; active during idle or general chat states.
- Mini Mode: Shifts the Orb to the bottom-right of the stage to accommodate tool or module interfaces.
Sources: tests/shell-layout.test.ts:40-52, src/renderer.tsx:327-375
View transitions involve updating the DOM visibility of stage-view-item elements and adjusting the orb's container state.
Sources: src/renderer.tsx:327-375, src/renderer.css:917-945
Navigation Groups
The shell-nav structure uses the following grouping:
- HOME: Core, Chat, Briefing, Barehands, LifeOS.
- WORKSPACE: Memory, Files & RAG, Knowledge.
- AUTOMATION: Browser, Agents, Workflows.
- SYSTEM: Telemetry, Einstellungen (Settings).
Sources: src/index.html:45-75
Command and Conversation Components
The shell maintains exactly one location for conversation history and input to ensure interaction consistency.
Command Dock
The command-dock houses the command-form, featuring a microphone toggle, a text input field, and a send button. It is positioned below the central stage. Unlike traditional side-drawers, the JARVIS shell uses a "Hermes-style" composer where the input stays visible and accessible regardless of the active module on the stage.
Sources: tests/shell-layout.test.ts:21-27, src/index.html:438-450
Conversation Feed
The conversation transcript is located in the right-side Context Rail (conversation-panel). It features persistent filtering for "ALL", "CHAT", and "SYSTEM" messages. The feed is designed to preserve context; tool results or background updates may update badges but do not replace the foreground transcript or steal focus.
Sources: src/index.html:507-518, instructions/DESIGN.md:52-60
Visual Invariants and Theming
The layout adheres to a strict design contract emphasizing "flatness" and "glassmorphism."
Layout Constants & Tokens
| Constant/Token | Value | Application |
|---|---|---|
--shell-titlebar-height | 38px | Compact custom titlebar height. |
--shell-nav-width | 232px | Default width of the expanded sidebar. |
--shadow-nous | 0 20px 45px -10px... | Floating elevation for overlays and HUD panels. |
--stroke-nous | rgba(56, 189, 248, 0.35) | The only hairline allowed for floating surfaces. |
Sources: src/renderer.css:41-45, src/renderer.css:1062-1065, instructions/DESIGN.md:80-90
Floating Surfaces
Overlays, such as the hud-drawer-overlay or Settings confirmation modals, use "borderless elevation." They float on the shadow-nous token with a --stroke-nous hairline. These are never nested rounded boxes, groups are defined by whitespace or single hairlines instead.
Sources: instructions/DESIGN.md:32-35, src/renderer.css:262-277
Summary
The Shell Layout and Navigation system in JARVIS Desktop Glas creates a highly responsive, single-page interface that manages complex tool interactions without losing conversational context. By utilizing a fixed grid with a modular central stage, the shell ensures that primary AI capabilities remain at the forefront while system management tasks are easily accessible through a non-intrusive navigation sidebar.