SwiftTerm Documentation

SwiftTerm does not include a built-in SSH library. To connect a terminal to a remote host, you must implement a bidirectional data flow between the TerminalView and your chosen SSH library using the following pattern:

1. User input to SSH: Implement TerminalViewDelegate/send(source:data:) to capture keystrokes and bytes from the terminal and write them to your SSH channel.
2. SSH output to terminal: When your SSH library receives data from the remote host, call TerminalView/feed(byteArray:) to display that data in the terminal.
3. Terminal Resizing: When the terminal dimensions change, use TerminalViewDelegate/sizeChanged(source:newCols:newRows:) to notify the SSH server to resize the PTY (Pseudo-Terminal).

┌──────────────┐   send(data:)    ┌──────────────┐
│              │ ───────────────▶ │              │
│ TerminalView │                  │  SSH Channel  │
│              │ ◀──────────────  │              │
└──────────────┘  feed(byteArray:) └──────────────┘

To connect a terminal to a custom backend like SSH or a network socket, use TerminalView directly and implement the TerminalViewDelegate.

The core pattern is:

• Outgoing: Implement TerminalViewDelegate.send(source:data:) to forward user input from the terminal to your backend.
• Incoming: Call TerminalView.feed(byteArray:) when your backend sends data to the terminal.

This pattern is used for both macOS (via NSView) and iOS (via UIScrollView).

class MyTerminalController: NSViewController, TerminalViewDelegate {
    var terminalView: TerminalView!

    override func viewDidLoad() {
        super.viewDidLoad()
        terminalView = TerminalView(frame: view.bounds)
        terminalView.terminalDelegate = self
        view.addSubview(terminalView)
    }

    func send(source: TerminalView, data: ArraySlice<UInt8>) {
        // Send data to your backend (SSH channel, socket, etc.)
    }

    // Feed incoming data from the backend into the terminal:
    func onDataReceived(_ data: ArraySlice<UInt8>) {
        terminalView.feed(byteArray: data)
    }

    func sizeChanged(source: TerminalView, newCols: Int, newRows: Int) {}
    func setTerminalTitle(source: TerminalView, title: String) {}
    func hostCurrentDirectoryUpdate(source: TerminalView, directory: String?) {}
    func scrolled(source: TerminalView, position: Double) {}
    func requestOpenLink(source: TerminalView, link: String, params: [String: String]) {}
    func clipboardCopy(source: TerminalView, content: Data) {}
    func rangeChanged(source: TerminalView, startY: Int, endY: Int) {}
}

SwiftTerm can resolve links from two sources: Explicit links (OSC 8 hyperlinks) and Implicit links (URL-like text detected in content).

Link Reporting Modes

Use the linkReporting property to control discovery:

• .none: Disable link tracking.
• .explicit: Track OSC 8 links only.
• .implicit: Track OSC 8 links first, then fallback to implicit URL detection (Default).

Link Activation

Link activation is governed by linkHighlightMode. When a link is activated, TerminalView calls TerminalViewDelegate/requestOpenLink(source:link:params:).

• Explicit links: link is the target; params contains parsed OSC 8 key/value pairs.
• Implicit links: link is the detected URL text; params is empty.

Platform Specifics

• macOS: Default mode is .hoverWithModifier (Command-click to open). Tracking is driven by AppKit mouse movement.
• iOS/visionOS: Default mode is .hover. Tracking is driven by UIPointerInteraction and UIHoverGestureRecognizer. Activation requires the Command key from a hardware keyboard for modifier-based modes.

terminalView.linkReporting = .implicit // Default: explicit first, then implicit fallback