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
typealias TerminalSession = weft.weft.TerminalSessionOwns 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:8Underlying weft API
TerminalSession
final class TerminalSessionOwns 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.
options
let options: TerminalOptionsThe policies selected when this session was opened.
Source · TerminalSession.swift:11mouseEnabled
var mouseEnabled: Bool { get }Whether the session currently captures mouse events.
Source · TerminalSession.swift:13mouseMotionEnabled
var mouseMotionEnabled: Bool { get }Whether unpressed pointer motion is currently reported as well as clicks and drags.
Source · TerminalSession.swift:15isSuspended
var isSuspended: Bool { get }True while raw mode, ANSI modes, and input observers have been released.
Source · TerminalSession.swift:21init(options:)
convenience init(options: TerminalOptions = TerminalOptions()) throwsOpens 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.
size()
static func size() -> RectReturns the terminal dimensions in cells, with an 80-by-24 fallback.
Returns Rect.
close()
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:95suspend()
func suspend() throwsReleases 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:120resume()
func resume() throwsReacquires 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:141withSuspendedTerminal(_:)
func withSuspendedTerminal<Value>(_ operation: () throws -> Value) throws -> ValueRuns 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.
suspendToShell()
func suspendToShell() throwsReleases 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.
requestQuery(_:timeoutMilliseconds:)
@discardableResult func requestQuery(_ query: TerminalQuery, timeoutMilliseconds: Int = 250) throws -> UUIDSends 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.
cancelQuery(_:)
@discardableResult func cancelQuery(_ id: UUID) -> BoolCancels 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.
setMouseEnabled(_:reportMotion:)
func setMouseEnabled(_ enabled: Bool, reportMotion: Bool = false) throwsEnables 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.
copyUsingOSC52(_:)
func copyUsingOSC52(_ text: String) throwsRequests 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.
writeBytes(_:)
func writeBytes(_ bytes: Data) throwsWrites 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.
pollBytes(timeoutMilliseconds:readInput:)
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].
poll(timeoutMilliseconds:)
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].