Project Window

Overview

The primary IDE-style project window that composes multiple sub-components into a four-panel layout. An HSplitView arranges the sessions panel, file tree panel, and detail panel side by side; the detail panel is itself a VSplitView containing the code editor (top) and terminal (bottom). An optional inspector panel slides in from the right. Each pane's visibility and proportions are persisted per-project, and the window frame is auto-saved using a SHA256 hash of the project path.

Terminology

Layout

┌─────────────────────────────────────────────────────────────────────────┐
│ [Sessions] [Inspector] [⚙]                              Toolbar       │
├──────────┬──────────────┬───────────────────────────────┬──────────────┤
│          │ ▾ repo-name  │ ▾ Editor                      │              │
│          │              │                               │              │
│ Sessions │  📁 Sources  │   (code editor pane)          │  Inspector   │
│   list   │    📄 App... │                               │  (optional)  │
│          │  📁 Tests    │                               │              │
│          │  📄 Package  │                               │              │
│          │              ├───────────────────────────────┤              │
│          │              │ ▾ Terminal                     │              │
│          │              │                               │              │
│          │              │   (terminal pane)              │              │
│          │              │                               │              │
│          │ ┌──────────┐ │                               │              │
│          │ │ Syncing… │ │                               │              │
├──────────┴─┴──────────┴─┴───────────────────────────────┴──────────────┤

[Sessions | FileTree | Editor/Terminal VSplitView] + Inspector(optional)

• Sessions panel (left): Session list, togglable via toolbar button
• File tree panel: File browser with folder header showing repo root name; sync status bar overlay at bottom
• Detail panel (center): VSplitView with editor (top) and terminal (bottom), each preceded by a collapsible pane header
• Inspector panel (right, optional): Slides in from right via .inspector modifier

Behavioral Requirements

Window structure

• hsplit-three-panels: The window MUST use an HSplitView with three main sections: sessions panel (left), file tree panel (center-left), and detail panel (center-right/right).
• vsplit-editor-terminal: The detail panel MUST use a VSplitView with the code editor pane on top and the terminal pane on bottom.
• collapsible-pane-headers: Each section of the VSplitView (editor and terminal) MUST be preceded by a collapsible pane header (as defined in ui/collapsible-pane-header.md).
• inspector-slide-right: The inspector panel MUST slide in from the right using the .inspector modifier (as defined in ui/Recipes/inspector-panel.md).

Pane sizing and proportions

• proportional-sizing: Each HSplitView section MUST use proportional sizing with minimum, ideal, and maximum width frame constraints.
• sessions-default-15pct: The sessions panel MUST default to 15% of the window width (sessionPanelProportion = 0.15).
• filetree-default-20pct: The file tree panel MUST default to 20% of the window width (fileTreeProportion = 0.20).
• detail-fills-remaining: The detail panel MUST fill the remaining width after sessions and file tree.
• detail-split-50-50: The VSplitView within the detail panel MUST default to a 50/50 split between editor and terminal (detailSplitRatio = 0.5).
• persist-layout-proportions: All layout proportions MUST be persisted per-project in ProjectSettings (see Project Settings section).

Pane visibility

• toggle-sessions-panel: The sessions panel MUST be togglable via a toolbar button. Default: visible (isSessionPanelVisible = true).
• toggle-file-tree: The file tree panel MUST be togglable. Default: visible (isFileViewerVisible = true).
• toggle-terminal: The terminal pane MUST be togglable. Default: visible (isTerminalVisible = true).
• toggle-inspector: The inspector panel MUST be togglable via a toolbar button. Default: hidden (isInspectorPresented = false).
• persist-visibility-state: Visibility state for all panels MUST be persisted per-project in ProjectSettings.
• animate-pane-toggle: Pane visibility changes MUST animate with .easeInOut(duration: 0.2).

Toolbar

• toolbar-sessions-button: The toolbar MUST include a button to toggle the sessions panel.
• toolbar-inspector-button: The toolbar MUST include a button to toggle the inspector panel (SF Symbol sidebar.trailing).
• toolbar-gear-button: The toolbar MUST include a gear button that presents a project settings sheet.

File tree header

• folder-header-repo-name: A folder header MUST be displayed above the file tree showing the repository root directory name.

Window frame persistence

• persist-window-frame: The window frame (position and size) MUST be persisted using the window-frame-persistence component (as defined in ui/window-frame-persistence.md).
• sha256-autosave-id: The autosave identifier MUST be a SHA256 hash of the project's file path, ensuring uniqueness per project.

Status bar

• sync-status-overlay: During directory sync operations, a status bar overlay MUST appear at the bottom of the file tree panel (as defined in ui/status-bar.md).

Lifecycle

• load-initial-start-watch: On onAppear, the window MUST load initial project data (loadInitial) and start file system watching (startWatching).
• auto-open-terminal: On onAppear, if the user's settings enable auto-open terminal, the terminal pane MUST be opened automatically.
• terminate-on-close: On window close (onClose / onDisappear), the window MUST terminate all running processes (terminateAll) and stop file system watching (stopWatching).

Delegation to sub-components

• delegate-file-tree: The file tree panel MUST delegate to file-tree-browser.md for all file browsing behavior.
• delegate-terminal: The terminal pane MUST delegate to terminal-pane.md for all terminal behavior.
• delegate-inspector: The inspector panel MUST delegate to inspector-panel.md for all inspector behavior.
• delegate-editor: The code editor pane MUST delegate to code-editor-pane.md for all editor behavior.
• delegate-pane-headers: Collapsible pane headers MUST delegate to collapsible-pane-header.md for toggle and animation behavior.

Appearance

• Window minimum size: 800 x 600pt
• Sessions panel width: proportional (default 15%), min 120pt, max 250pt
• File tree panel width: proportional (default 20%), min 150pt, max 350pt
• Detail panel width: fills remaining space, min 300pt
• Inspector panel width: 250pt fixed (per inspector-panel spec)
• Folder header: Repo root name displayed in a compact header row above the file tree, caption font weight medium
• Pane headers: 24-28pt height, system tertiary background (per collapsible-pane-header spec)
• Pane animation: .easeInOut(duration: 0.2) for all visibility toggles
• Toolbar style: Standard macOS toolbar with icon-only buttons

States

Project Settings

Layout proportions and pane visibility are persisted per-project in ProjectSettings:

• persist-project-settings: All settings in this table MUST be persisted per-project and restored on next open.
• immediate-settings-save: Changes to visibility or proportions MUST be written to ProjectSettings immediately (no manual save action).

Accessibility

• sessions-toggle-label: The toolbar sessions toggle button MUST have an accessible label: "Toggle Sessions Panel".
• inspector-toggle-label: The toolbar inspector toggle button MUST have an accessible label: "Toggle Inspector" (inherited from inspector-panel spec).
• gear-button-label: The toolbar gear button MUST have an accessible label: "Project Settings".
• pane-header-accessible: Each collapsible pane header MUST follow the accessibility requirements defined in ui/collapsible-pane-header.md (button role, expand/collapse announcement, keyboard toggle).
• divider-accessible: The split view dividers MUST be accessible to VoiceOver and MUST announce their purpose (e.g., "Resize sessions panel").
• keyboard-region-nav: Keyboard navigation MUST allow moving focus between all major regions: sessions, file tree, editor, terminal, inspector, and toolbar.
• keyboard-panel-shortcuts: The window MUST support standard macOS keyboard shortcuts for panel toggling (to be defined at implementation time and recorded as Design Decisions).

Conformance Test Vectors

Edge Cases

• All side panels hidden: If sessions and file tree are both hidden, the detail panel fills the full window width. The toolbar toggle buttons remain accessible to restore them.
• Both editor and terminal collapsed: Only the two pane headers are visible stacked vertically. The user can re-expand either by clicking its header.
• Window at minimum size with all panels visible: Panels MUST respect their minimum width constraints. If the window is too narrow to satisfy all minimums simultaneously, the rightmost resizable panel (detail) SHOULD compress first down to its minimum, and the split view SHOULD prevent further shrinking.
• Project path changes (rename/move): The window frame autosave identifier is based on the original path's SHA256 hash. If the project is moved, the frame will not restore. This is expected — the window opens at default position for the new path.
• Very long repo root name: The folder header SHOULD truncate with trailing ellipsis rather than overflowing.
• No git repository: File tree renders without git status badges; inspector omits Git Status row. No error displayed.
• File watcher fails to start: The window SHOULD log an error and continue operating without live file updates. A manual refresh mechanism SHOULD be available.
• Terminal process crashes: The terminal pane SHOULD display an error state. Other panels MUST remain functional.
• Multiple project windows open: Each window has its own ProjectSettings and frame autosave identifier. Settings changes in one window MUST NOT affect another.
• Inspector toggled rapidly: Animation MUST not stack or glitch. Each toggle SHOULD cancel any in-flight animation and start fresh.
• Extremely large project (100k+ files): Lazy loading in the file tree (delegated to file-tree-browser) mitigates this. The window itself SHOULD remain responsive.
• visionOS volume placement: On visionOS, the window renders as a standard window volume. Panel layout is identical but the user cannot resize panes via drag on visionOS — pane proportions are controlled via settings.

Localization

Accessibility Options

Feature Flags

Analytics

Privacy

• Data collected: Panel visibility and proportion preferences per project; window frame position/size
• Storage: ProjectSettings persisted on-device only (platform standard persistence). Frame autosave via NSWindow.setFrameAutosaveName (on-device).
• Transmission: None — no layout data leaves the device
• Retention: Persisted until the user changes settings or the project is removed. Frame autosave cleaned up by the OS if the app is uninstalled.

Logging

Subsystem: {{bundle_id}} | Category: ProjectWindow

Platform Notes

• SwiftUI (macOS): Use HSplitView for the three-panel horizontal layout. Wrap sessions and file tree panels in conditional if isSessionPanelVisible / if isFileViewerVisible blocks, animated with .animation(.easeInOut(duration: 0.2), value:). Use VSplitView inside the detail panel for editor (top) and terminal (bottom), each preceded by a CollapsiblePaneHeader. Apply .inspector(isPresented: $isInspectorPresented) on the outer container for the inspector. Use .frame(minWidth:idealWidth:maxWidth:) on each panel for proportional sizing. Toolbar via .toolbar { } with ToolbarItem(placement:) for sessions toggle, inspector toggle, and gear button. Gear button presents a .sheet for project settings. Frame persistence via .background(WindowAccessor(name: sha256Hash(projectPath), onClose: { terminateAll(); stopWatching() })). The folder header is an HStack with a folder icon and the project root directory name, placed above the file tree List. Use @ObservedObject or @EnvironmentObject for ProjectSettings bindings.
• SwiftUI (visionOS): Same layout as macOS. The window opens as a standard visionOS window. HSplitView and VSplitView render within the window volume. Split view dividers are not user-draggable on visionOS — pane proportions are controlled exclusively through ProjectSettings. Inspector uses the same .inspector modifier. Toolbar adapts to visionOS ornament style automatically. Frame persistence is not applicable (visionOS manages window placement).

Design Decisions

Fixed 2-pane detail layout: The current spec uses a fixed VSplitView with editor (top) and terminal (bottom). A future version MAY evolve to a flexible N-pane layout supporting arbitrary pane configurations (file editor, terminal sessions, IDE integration panes). When this ships, the spec should be updated to document PaneType enum and PaneLayout struct.

File tree default width: Currently defaulting to 20% (fileTreeProportion = 0.20). Some implementations may prefer 40% for better file name readability. This is configurable per-project — the default can be adjusted based on user feedback.

Change History