loom & weft
Made for Swift.

Published release 0.2.1. Unreleased PR #2 reference.

LOOM 0.2.1 / TERMINAL ALIASES FROM WEFT

TerminalSession

Owns the process-wide active terminal session. Always close with defer, and stop TerminalEvents first. weft 0.2.1 supports POSIX terminals and native Windows raw consoles; Windows canonical input and POSIX shell suspension explicitly return unsupported errors. Native Windows input reconstructs UTF-8/VT from console records; original Kitty or paste framing is not guaranteed.

loom.TerminalSession is an alias for weft.TerminalSession. It is available through import loom. The underlying type’s members are documented here.

Standard inherited Swift protocol operations such as synthesized equality and OptionSet set operations are not repeated. The public declarations below are extracted from the exact source revision listed in the coverage manifest.

Example

let session = try TerminalSession(options: TerminalOptions(alternateScreen: true, hideCursor: true))
defer { session.close() }
_ = TerminalSession.size()
Members on this page

Feature guides and release status

TerminalSession

Type Alias
typealias TerminalSession = weft.weft.TerminalSession

Owns the process-wide active terminal session. Always close with defer, and stop TerminalEvents first. weft 0.2.1 supports POSIX terminals and native Windows raw consoles; Windows canonical input and POSIX shell suspension explicitly return unsupported errors. Native Windows input reconstructs UTF-8/VT from console records; original Kitty or paste framing is not guaranteed.

Source · TerminalExports.swift:8

Underlying weft API

TerminalSession

Class
final class TerminalSession

Owns terminal modes for one interactive session.

Only one process-wide session may own the terminal at a time. Use it from one serial execution context. Termination signals are delivered as input events; call close() on normal exit to restore settings and signal handlers. When TerminalEvents is attached, use the session on the main actor as well.

Source · TerminalSession.swift:9

options

Instance Property
let options: TerminalOptions

The policies selected when this session was opened.

Source · TerminalSession.swift:11

mouseEnabled

Instance Property
var mouseEnabled: Bool { get }

Whether the session currently captures mouse events.

Source · TerminalSession.swift:13

mouseMotionEnabled

Instance Property
var mouseMotionEnabled: Bool { get }

Whether unpressed pointer motion is currently reported as well as clicks and drags.

Source · TerminalSession.swift:15

isSuspended

Instance Property
var isSuspended: Bool { get }

True while raw mode, ANSI modes, and input observers have been released.

Source · TerminalSession.swift:21

init(options:)

Initializer Throws
convenience init(options: TerminalOptions = TerminalOptions()) throws

Opens raw input without changing screens or clearing history by default.

Pass explicit options for full-screen applications. Raw settings and signal handlers are restored after initialization failures as well as normal exits.

Parameters (1)
options
Terminal policies selected when opening.
Source · TerminalSession.swift:37

size()

Type Method
static func size() -> Rect

Returns the terminal dimensions in cells, with an 80-by-24 fallback.

Returns Rect.

Source · TerminalSession.swift:86

close()

Instance Method
func close()

Restores modes enabled by the session, terminal settings, and signal handlers.

Calling this more than once has no effect. ANSI modes return to conventional defaults; weft does not query their previous state. Clearing scrollback is irreversible. Forced termination such as SIGKILL cannot perform cleanup.

Source · TerminalSession.swift:95

suspend()

Instance Method Throws
func suspend() throws

Releases terminal ownership for an editor, pager, or shell.

Safe to repeat. Input sources pause automatically. Pending queries are cancelled, and partial input is discarded at this ownership boundary. Even if ANSI output fails, Native settings are restored and the session remains suspended.

Source · TerminalSession.swift:120

resume()

Instance Method Throws
func resume() throws

Reacquires the terminal and resumes input, then delivers .terminalResumed for a redraw.

Does not repeat explicit screen/scrollback clearing. If acquisition or output fails, the session remains suspended and another attempt is permitted.

Source · TerminalSession.swift:141

withSuspendedTerminal(_:)

Instance Method Throws
func withSuspendedTerminal<Value>(_ operation: () throws -> Value) throws -> Value

Runs application-selected work with normal terminal settings and resumes on success or failure.

Use a synchronous operation that finishes before returning. A child process may inherit the terminal here; command selection and process waiting belong to the application. If both work and resume fail, both errors are retained.

Parameters (1)
operation
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns Value.

Source · TerminalSession.swift:173

suspendToShell()

Instance Method Throws
func suspendToShell() throws

Releases the terminal, sends SIGTSTP to the process, and resumes after the shell continues the job.

Applications choose when to call this, such as for Ctrl-Z or a SIGTSTP event. Actual suspension depends on shell job control and the prior SIGTSTP disposition. Windows throws unsupportedOperation without releasing terminal ownership; use withSuspendedTerminal for editor/pager handoff on that platform.

Source · TerminalSession.swift:195

requestQuery(_:timeoutMilliseconds:)

Instance Method Throws
@discardableResult func requestQuery(_ query: TerminalQuery, timeoutMilliseconds: Int = 250) throws -> UUID

Sends a bounded query and delivers its result through poll or TerminalEvents.

One request per query may be pending; at most 32 unconsumed requests/results are retained. Zero expires immediately. Protocols have no request IDs on the wire: consume results before retrying and allow for late replies after timeout.

Parameters (2)
query
Text to search for.
timeoutMilliseconds
Poll timeout: 0 is nonblocking, -1 waits indefinitely.

Returns UUID.

Source · TerminalSession.swift:209

cancelQuery(_:)

Instance Method
@discardableResult func cancelQuery(_ id: UUID) -> Bool

Cancels a pending query; its completion event is delivered by the decoded reader.

Parameters (1)
id
Stable entry/icon identity, not an array index.

Returns Bool.

Source · TerminalSession.swift:220

setMouseEnabled(_:reportMotion:)

Instance Method Throws
func setMouseEnabled(_ enabled: Bool, reportMotion: Bool = false) throws

Enables or releases mouse capture so the terminal can provide native selection.

Opt into unpressed pointer motion for hover interactions. It is disabled when capture is released, and restored to conventional defaults on session close.

Parameters (2)
enabled
Argument type and any default are shown in the declaration; see the behavior notes above.
reportMotion
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TerminalSession.swift:250

copyUsingOSC52(_:)

Instance Method Throws
func copyUsingOSC52(_ text: String) throws

Requests clipboard copying through OSC 52, when supported by the terminal.

Requests larger than one mebibyte of UTF-8 text are ignored.

Parameters (1)
text
Source text.
Source · TerminalSession.swift:276

writeBytes(_:)

Instance Method Throws
func writeBytes(_ bytes: Data) throws

Writes bytes unchanged, without interpreting terminal control sequences.

The caller owns protocols emitted through this method and must balance their modes.

Parameters (1)
bytes
Input bytes to decode incrementally.
Source · TerminalSession.swift:286

pollBytes(timeoutMilliseconds:readInput:)

Instance Method Throws
func pollBytes(timeoutMilliseconds: Int = 16, readInput: Bool = true) throws -> [TerminalByteEvent]

Receives undecoded input for a terminal relay, plus resize and termination events.

Zero polls without blocking; -1 waits indefinitely. Escape, paste, UTF-8 and extended keyboard bytes retain their original encoding and chunk boundaries on POSIX. Windows console input is normalized from native key/mouse records into UTF-8 and VT sequences; it is not an original byte transport. Child ConPTY output remains a separate unmodified byte stream. A session chooses bytes or decoded input on its first poll and cannot mix them. With readInput false, poll only resize/termination without consuming stdin or waiting. This lets a relay respect child backpressure with bounded buffers.

Parameters (2)
timeoutMilliseconds
Poll timeout: 0 is nonblocking, -1 waits indefinitely.
readInput
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns [TerminalByteEvent].

Source · TerminalSession.swift:301

poll(timeoutMilliseconds:)

Instance Method Throws
func poll(timeoutMilliseconds: Int = 16) throws -> [InputEvent]

Waits for input and reports terminal resize and termination signals.

Zero polls without blocking; -1 waits indefinitely except for pending queries or a legacy Escape deadline. Escape uses escapeTimeoutMilliseconds. Closed sessions throw.

Parameters (1)
timeoutMilliseconds
Poll timeout: 0 is nonblocking, -1 waits indefinitely.

Returns [InputEvent].

Source · TerminalSession.swift:343