# Swift workspace builder API

Source: https://libtmux.org/en/swift/latest/workspace/reference/

> Internal reference for the Swift workspace builder and configuration APIs.

Import `TmuxWorkspace` for the configuration and builder, and [`LibTmux`](../../reference/) for
the server and returned session value.

## Configuration values

[`Workspace`](./workspace/) contains the session name, optional
working directory, and ordered windows. `WindowPlan` contains its name,
directory, layout, and panes. `PanePlan` contains its directory and commands.
The values conform to `Sendable`, `Hashable`, and `Codable`.

`Workspace.decode(json:)` reads JSON data. `Workspace.decode(yaml:)` reads a
string only when `YAMLWorkspaces` is enabled. Encoding these values writes the
existing description; it does not query tmux for a live export.

## Builder

[`WorkspaceBuilder`](./workspacebuilder/) exposes the async
`build(_:on:)` operation. It creates a new session on the supplied server and
returns a `Session`. Keep using the server for live observation; session
properties do not refresh themselves.

## Typed errors

[`WorkspaceBuilderError`](./workspacebuildererror/) distinguishes
an empty window list, an existing session name, a vanished session, underlying
tmux errors, and failure of rollback.

`rollbackFailed(original:cleanup:)` preserves both causes. The caller can
report the initiating problem and separately inspect whether cleanup left
objects behind. The supplied server remains owned by the caller.

[Value and decoding contracts](https://github.com/libtmux/libtmux-swift/blob/f02a4668570e1cc5198c941413750e021f42c214/Sources/TmuxWorkspace/Workspace.swift); [Builder contract](https://github.com/libtmux/libtmux-swift/blob/f02a4668570e1cc5198c941413750e021f42c214/Sources/TmuxWorkspace/WorkspaceBuilder.swift).

## API declarations

- [PanePlan](https://libtmux.org/en/swift/latest/workspace/reference/paneplan/)
- [TmuxShellCommand](https://libtmux.org/en/swift/latest/workspace/reference/tmuxshellcommand/)
- [WindowPlan](https://libtmux.org/en/swift/latest/workspace/reference/windowplan/)
- [Workspace](https://libtmux.org/en/swift/latest/workspace/reference/workspace/)
- [WorkspaceBuilder](https://libtmux.org/en/swift/latest/workspace/reference/workspacebuilder/)
- [WorkspaceBuilderError](https://libtmux.org/en/swift/latest/workspace/reference/workspacebuildererror/)