Terminal Pane

Overview

A multi-session terminal pane that provides PTY-backed shell sessions within the workspace. Bundles five cooperating parts: terminal sessions (PTY lifecycle and state), a session manager (per-window session orchestration), a terminal view (SwiftTerm rendering with reparenting), a session list sidebar (selection and metadata display), and terminal profiles (shell and project-level settings). Derived from scratching-post terminal subsystem.

Terminology

Behavioral Requirements

Terminal session

• pty-backed-session: Each terminal session MUST be backed by a PTY using a terminal emulator library (SwiftTerm on Apple platforms).
• uuid-session-id: Each session MUST have a unique UUID-based identifier.
• observable-properties: Each session MUST publish the following observable properties:
  • name — user-visible session name (editable)
  • terminalTitle — title set by the shell via OSC 2
  • currentWorkingDirectory — path set via OSC 7
  • gitBranch — current git branch for the working directory
  • foregroundProcess — name of the currently running foreground process
  • dotColors — array of user-assignable colored indicators
  • customSubtitles — dictionary of key-value subtitle metadata
  • state — enum: .running or .terminated
• default-shell-env: The session MUST read the user's default shell from the $SHELL environment variable. If $SHELL is unset or empty, it MUST fall back to /bin/zsh.
• login-shell-launch: The shell MUST be launched as a login shell by prefixing the process name with "-" (e.g., "-zsh").
• term-256color: The session MUST set TERM=xterm-256color in the child process environment.
• preserve-env-vars: The session MUST preserve the following environment variables from the parent process: HOME, USER, LOGNAME, PATH, LANG, LC_ALL, LC_CTYPE.

OSC escape handling

• osc7-directory-update: The session MUST handle OSC 7 (directory update). On receipt, it MUST update currentWorkingDirectory by parsing the file:// URL and MUST trigger an asynchronous git branch detection for the new directory.
• osc2-title-update: The session MUST handle OSC 2 (title update). On receipt, it MUST update terminalTitle.
• osc7770-custom-commands: The session MUST handle custom OSC 7770 with the following sub-commands:
  • color=#rrggbb — sets a dot color on the session
  • subtitle:key=value — sets or updates a custom subtitle entry
  • clear-subtitle:key — removes a specific custom subtitle entry
  • clear-all-subtitles — removes all custom subtitle entries

Process monitoring

• poll-foreground-process: The session MUST poll the foreground process every 1.5 seconds using tcgetpgrp to get the foreground process group ID, then proc_pidpath to resolve the process name.
• update-foreground-name: When the foreground process changes, the session MUST update the foregroundProcess property.
• terminated-on-exit: When the shell process exits, the session MUST transition state to .terminated.

Git branch detection

• async-git-branch: Git branch detection MUST be performed asynchronously with a 2-second timeout by running git rev-parse --abbrev-ref HEAD in the session's current working directory.
• stale-branch-discard: Git branch detection MUST use a stale-request-tracking mechanism (UUID per request) so that results from outdated directory changes are discarded.
• non-git-nil-branch: If the directory is not a git repository, gitBranch MUST be set to nil.

Session manager

• per-window-manager: Each window MUST have its own session manager instance. Session managers MUST NOT be shared across windows.
• ordered-session-list: The session manager MUST maintain an ordered list of sessions and a selected session ID.
• auto-increment-names: Session names MUST be auto-incremented using the pattern "Session 1", "Session 2", etc. The counter MUST be monotonically increasing (not reused after deletion).
• optional-working-dir: The session manager MAY accept an optional working directory (for project context). When provided, new sessions MUST start in that directory.
• add-session-select: addSession() MUST create a new session, append it to the list, select it, and return it.
• remove-smart-select: removeSession(id:) MUST terminate the session's PTY, remove it from the list, and apply smart selection: prefer the previous session in the list, then the next session, then nil if none remain.
• terminate-all-cleanup: terminateAll() MUST terminate all sessions' PTYs and clear the list. This MUST be called on window close.

Terminal view

• nsview-representable: The terminal view MUST be implemented as an NSViewRepresentable (macOS) or UIViewRepresentable (iOS/visionOS) wrapper containing a container NSView/UIView.
• reparent-on-switch: On session change, the terminal view MUST reparent the selected session's terminal view into the container — not destroy and recreate it. This preserves scrollback history and cursor state.
• apply-color-profile: On profile change, the terminal view MUST apply the new color profile (foreground, background, cursor, selection, 16 ANSI colors, font, cursor style) without reparenting the view.
• palette-color-structure: Profile colors MUST be applied using the color-profile component's palette structure: FG, BG, cursor, selection, and exactly 16 ANSI colors (indices 0-15).

Session list sidebar

• sidebar-session-list: The session list MUST be displayed as a sidebar list showing one row per session.
• session-row-display: Each session row MUST display:
  • Dot color indicator(s) (if any assigned)
  • Session name (primary text)
  • Subtitle lines using the metadata-line component for: working directory (folder icon, middle-truncated path), git branch (branch icon), and foreground process (terminal icon)
• bind-selected-session: The session list MUST bind to the session manager's selected session ID for selection state.
• add-session-button: The session list MUST include an add button (+) that creates a new session via the session manager.
• row-context-menu: Each session row MUST have a context menu with at least: "Rename" and "Close" actions.

Empty state

• empty-state-no-sessions: When no sessions exist, the terminal pane MUST display an empty state (per ui/empty-state.md) with:
  • Icon: terminal (SF Symbol) or platform equivalent
  • Heading: "No active terminal session"
  • Description: "Click + to open a new terminal session"
  • Optional action button: "New Session" (calls addSession())

Project settings

• project-shell-settings: The following settings MUST be available per-project in the settings window:
  • defaultShell — a string picker with options: /bin/zsh, /bin/bash, /bin/sh, /usr/local/bin/fish, /opt/homebrew/bin/fish. Overrides $SHELL when set.
  • autoOpenTerminal — a boolean that, when enabled, automatically opens a terminal session when the project is opened.

Appearance

Terminal pane layout

┌───────────────┬────────────────────────────────────┐
│ Sessions  [+] │                                    │
├───────────────┤                                    │
│               │                                    │
│ ● Session 1   │  user@host ~ %                     │
│   ~/projects  │  ls -la                            │
│   main        │  total 42                          │
│   zsh         │  drwxr-xr-x  5 user staff  160 ...│
│               │  -rw-r--r--  1 user staff  230 ...│
│ ○ Session 2   │                                    │
│   ~/docs      │                                    │
│   bash        │                                    │
│               │                                    │
│               │                                    │
│               │                                    │
└───────────────┴────────────────────────────────────┘

Session row detail

┌───────────────────┐
│ ● Session 1       │  ← dot color + name
│  📁 ~/projects    │  ← metadata-line: working directory (middle-truncated)
│  🌿 main          │  ← metadata-line: git branch
│  ⬛ zsh           │  ← metadata-line: foreground process
└───────────────────┘

Empty state

┌────────────────────────────────────────────────────┐
│                                                    │
│                                                    │
│                   ⬛                               │
│         No active terminal session                 │
│     Click + to open a new terminal session         │
│              [New Session]                         │
│                                                    │
│                                                    │
└────────────────────────────────────────────────────┘

• Sidebar width: 180–220pt, resizable
• Session row spacing: 4pt between dot/name line and metadata lines
• Metadata lines: Use metadata-line component (12pt secondary icon + caption text)
• Dot color: 8pt filled circle, leading the session name
• Terminal background: Determined by active color profile
• Terminal font: Determined by active color profile (monospaced)

States

Accessibility

• keyboard-nav-sessions: The session list MUST be keyboard-navigable. Arrow keys MUST move selection between sessions.
• add-button-label: The add button MUST have an accessible label: "New Terminal Session".
• row-announce-details: Each session row MUST announce: session name, working directory, git branch (if present), and foreground process via a combined accessibility label.
• keyboard-context-menu: The context menu MUST be accessible via keyboard (e.g., Shift+F10 or Control+Click equivalent).
• voiceover-terminal-nav: The terminal view MUST support VoiceOver cursor navigation for reading terminal output.
• empty-state-accessible: The empty state MUST follow empty-state accessibility requirements (heading announced first, icon decorative).
• terminated-announce: The .terminated state MUST be announced to screen readers when a session's shell exits.

Conformance Test Vectors

Edge Cases

• Shell not found: If the configured shell path does not exist (e.g., fish not installed), the session MUST fall back to /bin/zsh and log a warning. It MUST NOT crash.
• PTY allocation failure: If PTY allocation fails, the session MUST display an error message in the terminal view area and log an error. It MUST NOT crash.
• Rapid session switching: Reparenting MUST complete without flicker. If a session switch occurs while a reparenting is in progress, the latest switch MUST win.
• Very long session name: Session name SHOULD truncate with trailing ellipsis in the sidebar row.
• Many sessions (50+): The session list MUST remain scrollable and performant. Consider virtualized/recycled list.
• Git branch detection timeout: If git rev-parse exceeds 2 seconds, the request MUST be cancelled and gitBranch left unchanged. No error shown to user.
• Git not installed: If git is not available on PATH, git branch detection MUST silently set gitBranch to nil. No error shown.
• OSC 7770 malformed payload: Invalid sub-commands or malformed hex colors MUST be silently ignored. Log at debug level.
• Process monitoring after shell exit: Polling MUST stop when the session transitions to .terminated. Timer MUST be invalidated.
• Large scrollback buffer: SwiftTerm should handle large scrollback (10,000+ lines) without excessive memory growth. Rely on library defaults.
• Session terminated while selected: The terminated session SHOULD remain visible (showing final output) until the user removes it or switches away.
• Multiple dot colors: A session MAY have multiple dot colors (from multiple OSC 7770 color commands). Display them in order.
• Window restored after crash: Session manager MUST NOT attempt to restore PTY sessions from a previous run. Sessions are ephemeral.
• Environment variable conflicts: If defaultShell project setting and $SHELL both exist, defaultShell MUST take precedence.
• Non-UTF-8 output: The terminal emulator library (SwiftTerm) handles encoding. Invalid sequences SHOULD be rendered as replacement characters, not cause a crash.

Configuration

This ingredient has no configurable options.

Logging

Subsystem: {{bundle_id}} | Category: TerminalPane

Platform Notes

• SwiftUI (macOS): Use NSViewRepresentable wrapping a container NSView. SwiftTerm provides TerminalView (an NSView subclass) — do not recreate it per session switch; instead, remove it from the old container and add it to the new container via addSubview / removeFromSuperview. Apply color profiles via SwiftTerm's installColors(foreground:background:cursor:selection:ansi:) and font property. PTY creation: use forkpty() or posix_openpt() + grantpt() + unlockpt(). Process monitoring: tcgetpgrp(fd) for PGID, proc_pidpath(pid, buf, bufSize) for process path. Session list: List(selection:) with ForEach over session manager's sessions. Context menu via .contextMenu. The + button in the sidebar header via a toolbar item scoped to the sidebar.
• SwiftUI (iOS / visionOS): Use UIViewRepresentable wrapping a container UIView. SwiftTerm provides TerminalView as a UIView subclass. Reparenting approach is identical. On iOS, the session list may be presented as a sheet or popover rather than a persistent sidebar, depending on size class. On visionOS, use a NavigationSplitView with the session list in the sidebar column. PTY APIs (forkpty, tcgetpgrp) are available on iOS but sandboxing restrictions may limit shell execution to developer/enterprise contexts.
• General: The terminal emulator library (SwiftTerm) handles VT100/xterm escape sequence parsing, scrollback buffer management, and text rendering. The session layer is responsible for PTY lifecycle, environment setup, OSC dispatch, and process monitoring. The view layer is responsible for reparenting and profile application.

Privacy

• Data collected: Terminal output is rendered in-memory by SwiftTerm. Custom subtitles and dot colors are session-ephemeral.
• Storage: No terminal content is persisted to disk. Project settings (defaultShell, autoOpenTerminal) are stored in the project's settings file.
• Transmission: None — terminal content never leaves the device.
• Retention: Session data exists only for the lifetime of the session. Settings persist until changed.

Design Decisions

None yet — decisions made during implementation should be recorded here.

Change History