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
┌───────────────────────────── 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
PTYProcessper session, three dispatch sources on one serial queue,deinithangs 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 fromtcgetpgrp. - Keyboard shortcuts: 45 default chords, overrides stored per action, conflicts detected in the editor, applied by rebuilding the menu bar.
- Windows and tabs:
NSWindowwithfullSizeContentView, 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:
tickinvalidates the whole chrome every second. Tab items, every pane, the sidebar, the status bar and the hosts panel readmodel.tick. Each second SwiftUI re-evaluates them all, includingTerminalHostView.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.- Scrollback search runs on the main thread on every keystroke of the search field, without debounce (2.5 s for 200 000 lines).
searchCountsscans every open session from inside aMenubuilder.- The palette probes the file system when it opens (
ToolLocator.agents(),ShellCatalog.installedShells(), tmux, zellij): synchronousisExecutableFilecalls over about ten directories. viewDidBecomeFirstResponderlooks up the pane by a linear scan of all sessions.currentSnapshot()mutateswindow.tabs(it writes working directories) each time it is called, so every autosave invalidates every view observing the tabs.- 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). - The 1 Hz sampler keeps probing
libprocfor 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 existingsettings.jsonloads unchanged.- App: one
Motionhelper 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,AIAssistantinternals (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.