SPB Git

Repository Public

SPTERM-NEXT-AUDIT.md 22.6 KB

# SP Term Next — Audit of the existing application and upgrade plan

Date: 2026-11-19 · Audited revision: main @ 0c6078b (SP Term 1.0.0, build 1) · Branch of the upgrade: next Machine: MacBook Pro, Apple M5 Max, macOS 27.0, Xcode 27.2.

This document was written before any code of the upgrade. Everything in it comes from reading the 16 549 lines of Swift in the repository, the project files, the scripts and the existing reports, and from running the test suites. Where something was not measured or not verified, it says so.

# 1. Existing functionality inventory

State as documented in IMPLEMENTATION_STATUS.md and confirmed in the code. All of it must survive the upgrade.

Area What exists in 1.0.0 Where
Terminal core Real PTY (forkpty + exec-mode posix_spawn), job control, resize, signals, clean environment; SwiftTerm 1.99.2 emulation (pinned), CoreGraphics renderer, optional Metal renderer (experimental, off) PTYProcess, TerminalCore
Sessions Local shell, command, SSH kinds; restart, duplicate, rename, export with secret masking; foreground job, cwd, CPU and memory sampling (1 Hz, libproc) TerminalSession, AppModel
Tabs Create, select, reorder (drag), rename, close, detach to a window, ⌘1…⌘9 AppModel, TabBarView
Panes Recursive n-ary splits, divider drag, keyboard resize, equalize, directional focus, zoom, swap and move by drag, move to tab or window without ending the process WorkspaceKit.LayoutNode, PaneViews
Windows and displays Several windows, placement engine, rescue on display change, move to display, merge windows, native full screen WindowManager, WorkspaceWindowController
Workspaces Autosave and restore of the layout, named workspaces, 9 presets, private mode SessionStore, Presets
Safety Paste guard, OSC 52 clipboard policy, link policy, broadcast input with confirmation and held destructive lines, close/quit confirmation PasteGuard, AppModel
Search Plain, case, regex, match counter, counts across sessions Actions.swift, SearchBarView
Remote and tools ~/.ssh/config parser, host profiles and dashboard, known_hosts state, failure diagnosis and reconnect, read-only git panel, snippets with variables, tmux and zellij entries, agent CLI detection SPRemoteKit, panels
Assistant BYOK providers (Anthropic, OpenAI, compatible), Keychain, payload preview, secret redaction, risk analyzer, consent gate SPIntelligence
Chrome Custom tab bar in a transparent title bar, sidebar, 4 inspectors, status bar, pane headers, command palette, banners, 10 sheets, context menu App/Sources/SPTerm/Views
Preferences 6 settings panes, 6 themes (2 dark, 2 light, 2 high contrast), accent override, font, cursor, opacity, blur, customizable shortcuts SettingsModel, SettingsView
Extras Quick terminal on a global hotkey (Carbon), notifications, Finder "open folder" and Services entry, focus mode, presentation mode QuickTerminalController, Notifier, AppDelegate
Distribution XcodeGen project, universal Release build, Developer ID, hardened runtime, notarized and stapled app and DMG project.yml, Scripts/

64 actions are registered in one enum (AppAction) that feeds the menu bar, the palette, the context menu and the shortcut editor.

# 2. Architecture

text
┌───────────────────────────── SP Term.app (App/Sources/SPTerm, 5 100 lines) ─────────────────────────────┐
│ AppDelegate ── menus built from AppAction ── Settings window                                             │
│      │                                                                                                    │
│      ▼                                                                                                    │
│ AppModel  @MainActor @Observable  (969 lines)                                                            │
│   sessions [PaneID: TerminalSession] · windows [WindowState] · settings · stores · 1 Hz timer (tick)     │
│      │                         │                              │                                           │
│      ▼                         ▼                              ▼                                           │
│ WindowState (@Observable)   WorkspaceWindowController     QuickTerminalController                         │
│   tabs [TabModel], UI flags   SPWindow (NSWindow)           SPWindow borderless, Carbon hotkey             │
│      │                         │ NSHostingView                                                            │
│      ▼                         ▼                                                                          │
│ WindowRootView (SwiftUI) ─ TabBarView · SidebarView · PaneCanvasView · InspectorView · StatusBarView      │
│                              PaneCanvasView → PaneView → TerminalHostView (NSViewRepresentable)           │
│                                                   └→ TerminalContainerView (NSView) hosts session.view    │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
        │                         │                         │
        ▼                         ▼                         ▼
 Packages/SPTermKit        Packages/SPRemoteKit      Packages/SPIntelligence
  PTYProcess                SSHKit                    AIAssistant
  TerminalCore ─ SwiftTerm  GitKit
  WorkspaceKit (pure)       SPProcess
  WindowManager (pure)
  SessionStore
  SettingsModel
  DesignSystem (themes, contrast, metrics)

Data flow of a keystroke: SPWindow.sendEvent (marks user input) → SwiftTerm view → TerminalSession.send → PTYProcess write source. Output: PTY read source (serial queue) → SwiftTerm feed (thread-safe) → engine draws on the main thread. Process state reaches the UI through a 1 Hz timer that bumps AppModel.tick.

Points 5 to 8 of the brief:

  • PTY sessions: one PTYProcess per session, three dispatch sources on one serial queue, deinit hangs up and reaps. Sound; not touched by the upgrade.
  • Process spawning and shell integration: launch planning in ShellSupport (TERM, TERM_PROGRAM, login shell). OSC 7 (directory) and OSC 0/2 (title) are consumed. There is no semantic shell integration (OSC 133): the app does not know where a prompt starts, where a command ends or what its exit status was. The end of a foreground job is inferred from tcgetpgrp.
  • Keyboard shortcuts: 45 default chords, overrides stored per action, conflicts detected in the editor, applied by rebuilding the menu bar.
  • Windows and tabs: NSWindow with fullSizeContentView, transparent title bar, system tabbing disabled, tabs are SwiftUI views.

# 3. UI and UX assessment

What the 1.0.0 interface is today (see docs/evidence/*.png): correct, flat and anonymous.

Topic Finding
Visual identity One flat chrome colour derived from the theme background, 1 pt separators everywhere, no depth, no material in the default configuration. The window does not look like any product in particular.
Translucency Only "opacity + blur of the whole window", off by default. It dims the terminal text surface together with the chrome, which hurts readability, the opposite of what is wanted.
Typography and metrics Font sizes are literals scattered in the views (9, 10, 11, 12, 13, 15 pt); Metrics holds only 12 numbers. No type scale, no radius scale, no elevation scale.
Motion None. One .transition(.opacity) exists on the palette and never runs because no state change is wrapped in an animation. Tabs, panes, sidebar, inspector, banners and the palette appear and disappear in one frame.
Reduce Motion Not read (there is nothing to reduce).
Title bar Traffic lights sit at the system position of a 28 pt title bar while the tab bar is 34 pt: they are not vertically centred on the tabs. The spacer for them is a hard-coded 76 pt.
Full screen TabBarView reads controller.isFullScreen, which is not observable: after entering or leaving full screen the traffic-light spacer is stale until something else redraws the bar.
Toolbar Five fixed buttons; not customizable.
Modes Focus mode and presentation mode exist but switch in one frame; presentation mode merely forces focus mode. No compact or expanded density.
Panes Hairline gap, square corners, focused pane marked by a 1 pt accent rectangle and the others dimmed to 82 % (which lowers text contrast of unfocused panes).
Empty states Plain sentences ("Save the current arrangement with ⌘S", "No matching command").
Tooltips System .help only, without the shortcut of the action.
Feedback No feedback when a long command finishes, apart from an optional system notification.
Accessibility Labels and traits are present on tabs, panes, palette rows and status items. Keyboard coverage is complete through the menu. VoiceOver was never run (unchanged by this audit). Colour is doubled by text or an icon in most places; the tab status dot relies on colour plus an accessibility label only.
Liquid Glass Not used. The SDK of Xcode 27.2 exposes glassEffect(_:in:) (macOS 26+); the deployment target is macOS 14, so it needs an availability check and a material fallback.

# 4. Performance baseline

Tests re-run for this audit on 2026-11-19 (same machine): SPTermKit, SPRemoteKit and SPIntelligence package suites pass; the hosted app suite passes (all six XCTest suites, including PerformanceTests).

Reference numbers, measured on 2026-11-17 on the signed Release build (BENCHMARKS.md; not re-measured today):

Measure 1.0.0
Launch to first window 250–259 ms
Memory, 1 idle pane / 8 idle panes 57 MB / 64 MB footprint
CPU, 8 idle panes 1.2 %
cat of 51 MB (no drawing) 0.51 s, about 100 MB/s
Echo latency to the screen buffer median 0.26 ms
300 resizes under output 0.32 s

Typing latency to glass and drawing throughput were never measured. The upgrade must not degrade the table above; section 8 says how that is checked.

Bottlenecks and risks found in the code:

  1. tick invalidates the whole chrome every second. Tab items, every pane, the sidebar, the status bar and the hosts panel read model.tick. Each second SwiftUI re-evaluates them all, including TerminalHostView.updateNSView. Cheap today, but it is a fixed idle cost that grows with pane count, and any continuous animation added on top of it would multiply it.
  2. Scrollback search runs on the main thread on every keystroke of the search field, without debounce (2.5 s for 200 000 lines).
  3. searchCounts scans every open session from inside a Menu builder.
  4. The palette probes the file system when it opens (ToolLocator.agents(), ShellCatalog.installedShells(), tmux, zellij): synchronous isExecutableFile calls over about ten directories.
  5. viewDidBecomeFirstResponder looks up the pane by a linear scan of all sessions.
  6. currentSnapshot() mutates window.tabs (it writes working directories) each time it is called, so every autosave invalidates every view observing the tabs.
  7. Resizing a terminal view resizes the PTY (TIOCSWINSZ, SIGWINCH). Any animation that interpolates pane frames would send a resize per frame to the shell. This constrains how pane splitting can be animated (see 7.2).
  8. The 1 Hz sampler keeps probing libproc for sessions of hidden tabs and when no window is open.

# 5. Security assessment

Item State
Sandbox Off, by necessity for a terminal. Hardened runtime on.
Entitlements One: com.apple.security.automation.apple-events. No JIT, no library-validation exception, no get-task-allow in Release.
Privacy strings Present for Apple Events, Desktop, Documents, Downloads, removable and network volumes, local network. They describe programs run in a session, which is accurate.
Secrets API keys in the Keychain only; provider file holds no key; history is opt-in and redacted; private mode writes nothing. Files 0600 in a 0700 directory.
Untrusted terminal output Titles sanitized, OSC 52 write = ask and read = deny by default, links filtered by scheme, paste and drops guarded.
Child processes No descriptor inherited, clean environment (tested).
Signing and notarization Developer ID, timestamp, notarized and stapled app and DMG (1.0.0).
Updates No update channel (no Sparkle): a fix reaches the user only by a manual download.
Not covered Intel slice never executed; no installation test on another Mac.

Nothing in the upgrade needs a new entitlement or permission. Risk introduced by the upgrade: none on this axis as long as the terminal view, PTY layer and policies are left as they are.

# 6. Technical debt inventory

# Debt Severity
D1 AppModel is a 969-line object owning sessions, windows, broadcast, paste, links, workspaces and display changes Medium (works, tested; splitting it is not needed for this release)
D2 No design tokens: literals for sizes, radii, opacities in every view High for a redesign
D3 Status logic (running, busy, ended → colour) written three times (tab, sidebar, pane header) Low
D4 tick-driven refresh instead of observing session properties (item 1 above) Medium
D5 Full-screen state not observable (stale tab bar) Bug
D6 NSCursor.push()/pop() in DividerHandleView.onHover: if the handle disappears while hovered the pop never happens and the resize cursor can stick Bug
D7 AppModel.assistants[WindowID] entries are never removed when a window closes Small leak
D8 Focus mode and presentation mode overlap; the "draggable strip" of focus mode is an empty 22 pt band Low
D9 nonisolated(unsafe) static weak var current in the quick terminal controller Low, documented
D10 Search on the main thread, no debounce Medium
D11 Settings window is a fixed 640×520 TabView Low
D12 No shell integration (OSC 133), so no exit status, no prompt marks, no command blocks Feature gap, later phase
D13 Interface in English only, VoiceOver not audited, no update channel Known, out of scope here

Duplicated or incomplete functionality (point 16): D3 and D8 above; SFTP is only a tab running sftp; streaming exists in the AI client but the panel does not use it; ligatures and line spacing have no setting.

# 7. Prioritized improvements

The brief received covers Phase 0 and Phase 1 (sections 1.1 to 1.3; the text stops inside 1.3). The plan is limited to that.

# 7.1 Foundations (first, everything else depends on them)

  • DesignSystem: typed tokens (spacing, radii, type scale, elevation), motion tokens (durations and spring parameters as plain values), surface colours derived per theme, two new themes, a deterministic accent engine. Pure Swift, unit-tested, no UI import.
  • SettingsModel: new preferences with tolerant decoding (chrome material, density, motion, dynamic accent, ambient gradient, toolbar items). An existing settings.json loads unchanged.
  • App: one Motion helper that turns tokens into SwiftUI animations and returns no movement when Reduce Motion (system or setting) is on; shared surface, glass and tooltip components. Liquid Glass behind #available(macOS 26, *), materials below.

# 7.2 Visual design and motion (1.1, 1.2)

Item Decision
Depth Chrome becomes a material layer (vibrancy behind the window) and each pane a rounded, opaque card floating on it. The terminal text surface stays fully opaque by default: translucency is on the chrome, not under the text.
Focus Accent ring and soft glow on the focused card; unfocused panes are no longer dimmed through their text (a thin veil on the header only).
Dynamic accent Local sessions use the theme or user accent; each SSH host gets its own stable hue (derived from the host name, contrast-checked); broadcast uses the warning colour. The chrome tint follows the focused pane.
Ambient gradient A low-contrast accent gradient in the chrome that drifts only on events (focus change, tab switch, command finished). No continuous animation, so no idle cost.
Tabs Pill tabs, sliding selection, spring insertion and removal.
Pane splitting New panes fade and scale in, closed panes fade out, dividers and focus ring animate. Pane frames are not interpolated, because each intermediate size would be sent to the shell as a terminal resize (item 7 of section 4).
Tab switch Short cross-fade with a slight scale; terminal content itself is never animated.
Sidebar, inspector, banners, search bar Spring slide with fade.
Palette Scrim, spring scale-in, animated selection, glass surface, footer of key hints, designed empty state.
Tooltips Own tooltip with the action name and its current shortcut.
Completion feedback When a foreground command ends, the tab dot pulses and the status bar shows its name and duration for a few seconds. Without shell integration the exit status is unknown, so success or failure is not claimed.
Reduce Motion System setting honoured, plus a setting to force reduced motion. Movement becomes a plain short fade.

# 7.3 Window architecture (1.3)

Item Decision
Integrated title bar, native traffic lights Kept native. An empty unified toolbar gives the title bar the height of the tab bar so the lights are vertically centred; their real position is measured instead of the hard-coded 76 pt.
Customizable toolbar The toolbar buttons become a user-chosen, ordered set (settings and right-click on the bar).
Compact and expanded modes Density setting: compact (single-line tabs) and expanded (taller bar, two-line tabs with the running program).
Distraction-free mode Focus mode animated; chrome and traffic lights fade out and come back when the pointer reaches the top edge. Presentation mode kept.
Full-screen workspace mode New action: native full screen with the overview sidebar and status bar shown, restored on exit. Full-screen state becomes observable (fixes D5).

# 7.4 Debt fixed in passing

D2, D3, D5, D6, D7, D8, plus items 4 and 5 of section 4 (palette probes cached, first-responder lookup by view identity).

# 7.5 Explicitly not in this release

D1 (splitting AppModel), D4 as a whole (replacing tick), D10 (background search), D12 (OSC 133 shell integration), a GPU renderer by default, localization, an update channel. They belong to later phases of the brief, which were not received.

# 8. Migration and compatibility plan

Subject Rule
Features Nothing is removed. Every AppAction, menu item, shortcut, sheet, panel and setting of 1.0.0 remains. New actions get no default shortcut that is already in use.
settings.json Schema version unchanged. New keys are optional with defaults; unknown keys are still ignored, so going back to 1.0.0 with a newer file also works. backgroundOpacity and backgroundBlur keep their meaning.
Layout files last-session.json, workspaces.json, snippets.json, hosts.json, ai-providers.json untouched.
Kits PTYProcess, TerminalCore (except nothing), WorkspaceKit, WindowManager, SessionStore, SPRemoteKit, SPIntelligence: no behavioural change. Only DesignSystem and SettingsModel gain API.
Engine SwiftTerm stays pinned at 1.99.2; default renderer unchanged.
System Deployment target stays macOS 14. Liquid Glass on macOS 26 and later, materials before.
Tests The existing suites must stay green without weakening an assertion. New unit tests for tokens, accent engine, settings decoding of old files, new actions.
Performance Scripts/bench.sh and PerformanceTests on a Release build after the change, compared with section 4.
Version 2.0.0 (build 2). Bundle identifier, signing identity and data directory unchanged, so the new build replaces the old one in place.
Rollback Work happens on branch next; main and the published 1.0.0 DMG are untouched until the owner decides to release.

# 9. Verification status of this audit

  • Read: all app sources, DesignSystem, SettingsModel, TerminalSession, SPTerminalView, project, entitlements, Info.plist, scripts, existing reports.
  • Read only by outline: PTYProcess, LayoutNode, SSHKit, GitKit, AIAssistant internals (not modified by this plan; their state is taken from their test suites, which pass).
  • Run: the four test suites (pass). Not re-run: bench.sh, smoke.sh.

# 10. Outcome (added after implementation, 2026-11-19)

What was delivered against the plan of section 7, and where it differs.

Plan item Outcome
7.1 Foundations Done. Tokens.swift, accent engine, two themes, eight new settings with tolerant decoding.
7.2 Design and motion Done as planned. Pane frames snap; cards, focus ring, dividers, tabs, sidebar, inspector, banners, search bar and palette move.
7.3 Window architecture Done. The hover return of the title bar in focus mode and the native full-screen transition of the workspace mode were not exercised live.
D2 design tokens Partly: the window chrome, sidebar, palette and panes use the tokens. The four inspector panels, the sheets and the Settings window keep their literals.
D3, D5, D6, D7 Fixed.
D8 Partly: the focus-mode strip now has a function (drag, bring the title bar back); focus and presentation modes remain two actions.
Section 4, items 4 and 5 Fixed (palette probes cached for one minute; first-responder lookup by view identity).
Section 4, items 1, 2, 3, 6, 8 Not addressed, as stated in 7.5.

Found during implementation, not in the audit above: the window controller was not retained by anything and was released right after a window opened, leaving the window without a delegate. The audit missed it because the code reads as if the controller lived (WindowState.controller is used everywhere) and the hosted tests call the model directly. It was found when the traffic lights refused to hide: a trace showed the controller's deinit immediately after launch. Fixed by making the window state own the controller; one existing assertion had to tolerate a soft-wrapped line, because test windows now stay alive and give panes their real width instead of the default 80 columns.

Measured after the change: see "SP Term Next (2.0.0) against 1.0.0" in BENCHMARKS.md.

Files main
Menu

Theme