LibTmux.Model

Description#

Captured graph

Snapshot captures observations over an interval. Its field accessors, raw bytes, relations and typed selections perform no I/O. It retains endpoint settings and incarnation values, never the Runtime that acquired it. Reference construction is local; reference commands create and close a fresh bounded client executor.

Physical windows and panes are unique by scoped ID. WindowLink represents one session/index association, including repeated links to the same physical window. Raw contextual rows preserve their multiplicity. Contradictory duplicate records and missing targets in complete collections raise InconsistentSnapshot. An incomplete relation raises MissingData rather than appearing empty.

same-entity compares daemon-scoped identity. WindowLink has no stable identity between captures, so its comparison is confined to one captured graph. A link reference checks its expected physical window before selecting or unlinking; renumbering between that check and the operation remains a documented race.

Window.decoded-layout parses captured layout bytes locally. Strict text access can fail for invalid UTF-8 while bytes remains available.

Explicit commands

SessionRef.new-window and PaneRef.split/new-floating return references from the command's declared identity projection. PaneRef.break returns the resulting WindowRef; older profiles that omit the identity for a single-pane break use an ID-filtered observation afterward. A new observation is acquired only by inspect. If the source window has several placements, break requires an explicit :from(WindowLinkRef) so tmux cannot choose which association to move. Other mutations return a command Result. Completion means the tmux client completed; pane input processing, rendering and child programs may continue afterward.

WindowRef.link and WindowLinkRef.move require a destination session and index. They return a WindowLinkRef for that placement. Moving, swapping or unlinking a placement is separate from WindowRef.kill, which destroys the physical window and all its links. tmux synchronizes placement changes across grouped sessions; unlinking a placement also removes its corresponding peer placements. Physical window linking prefers the destination session's existing source context when the window is already present there. Link checks and mutations are separate operations; concurrent renumbering can race between them. Cross-daemon targets are rejected.

References expose value-only options and hooks facades; SessionRef also exposes environment. Creating these facades performs no I/O. Their get, set and other methods explicitly acquire or mutate current configuration. See LibTmux::Configuration for typed option, environment and command-value rules.

Client.ref creates a ClientRef with the observed name bytes, PID and creation time. inspect requires that identity to remain attached. Client commands are inherited from LibTmux::Client; client disconnection and name reuse can still race between the identity check and the command.

Names and start directories are literal. Names that tmux would silently change are refused, and separator support follows the daemon's capability profile. PaneRef.set-title quotes one FORMAT expansion; tmux's title validation still applies. The low-level command method keeps native tmux argument semantics. Shell commands passed to creation and respawn run through tmux's shell-command contract. PaneRef.pipe deliberately accepts tmux FORMAT and strftime syntax as well as shell syntax. It closes an existing pipe when called without a command; :toggle follows pipe-pane -o, which closes an already open pipe.

Literal pane input uses send-text and never appends Enter. send-keys accepts key names and a positive :repeat. capture and capture-pending return Blob data without text conversion or whitespace removal. copy-command sends an explicit copy-mode command; it does not interpret arbitrary text as a key sequence. reset queues terminal-state reset followed by history clearing without a client roundtrip between them. It is not transactional: failure can leave partial effects. reset-terminal only resets terminal state. Running a shell's reset program is a separate application action: send-text('reset') followed by send-keys('Enter') requests it without promising what the pane application does.

Split dimensions use :size or :percent exclusively. Percentage splits use the size syntax across profiles, avoiding the known percentage-flag defect. Empty pane creation selects its documented profile encoding; empty windows require the corresponding capability. Floating creation, movement, stacking, modal panes and layout variants have independent capability checks. The defective break-pane profile is refused before either named or unnamed operations.

See LibTmux::Server for endpoint ownership and acquisition, LibTmux::Selection for captured collection operations, and LibTmux::Transport for Result and process cancellation contracts.