feresaria/docs/ipc.md

# feresectl and IPC events

`feresectl` controls a running Ferese session. Run `feresectl --help` for commands
and `feresectl COMMAND --help` for arguments.

## Queries

Queries print plain text by default. Add `-j` or `--json` when passing results to
another program. The flag works before or after a subcommand.

```sh
feresectl outputs
feresectl windows -j
feresectl -j workspaces
feresectl focused-window
feresectl idle-inhibition
feresectl keybindings
feresectl session-state
feresectl output-profiles
feresectl theme get
feresectl xwayland status
feresectl media
feresectl activity list
```

`feresectl keybindings` lists the active binding mode's shortcuts. Outside a
mode it lists the configured default shortcuts. Escape is always available to
leave a mode; see [Binding modes](configuration/bindings.md#binding-modes).

The `get-*` spellings remain hidden aliases for the corresponding queries and
print a deprecation warning on stderr. They use the same output rules: scripts
that previously parsed their JSON must add `-j`. New scripts should use the
canonical names. The aliases will be removed in a later release.

Screenshots still write PNG bytes to stdout, including when `-j` is present:

```sh
feresectl screenshot > desktop.png
feresectl screenshot -g '0,0 800x600' > region.png
feresectl screenshot-window 7 > window.png
```

## Window focus

```sh
feresectl focus-floating
```

`focus-floating` focuses the most recently focused window in the opposite
tiled/floating layer on the active workspace. It does nothing when that layer
has no candidate. `toggle-floating` changes placement; `focus-floating` changes focus.

`feresectl move left|right|up|down` and `feresectl resize left|right|up|down`
also handle floating windows. Moves use 32 logical pixels. Resizing shrinks
width/height with left/up and grows them with right/down by 32 logical pixels,
subject to client size limits. Fullscreen and maximized floating windows ignore
these actions.

`toggle-column-tabbed` changes a scrolling column between stacked rows and tabs.
In either layout, `join-tab left|right|up|down` joins the focused window to a
neighbouring tab group. `next-tab` and `previous-tab` switch tabs, and `leave-tab`
splits the focused tab out. See [Tabbed windows](tabbed-windows.md)
for grouping behavior and shortcuts.

## Live Activities

Use `feresectl run --title "Tests" -- cargo test` to publish a command's lifetime,
or `feresectl activity start`, `update`, `end` and `cancel` to publish status from
an integration. The [Live Activities guide](activities.md) covers setup and
examples; the [publishing guide](development/activities.md#publisher-ownership-and-lifecycle) explains ownership,
leases and the `activity-publish`, `activity-get` and `activity-watch` commands.

`feresectl activity setup --config PATH` updates a local config for shell
activities and the panel item without connecting to a session. It preserves an
explicit `shell-hook #false`; the installer uses it during first-time user setup.

## Choose a session

Every feresectl IPC command, including theme commands and subscriptions, resolves
its target in this order:

1. `--socket PATH`
2. A nonempty `FERESE_SOCKET`
3. `$XDG_RUNTIME_DIR/ferese/control.sock`

```sh
feresectl --socket "$XDG_RUNTIME_DIR/ferese/instances/12345-abcdef/control.sock" outputs
FERESE_SOCKET="$XDG_RUNTIME_DIR/ferese/instances/12345-abcdef/control.sock" feresectl theme get -j
```

`--socket` selects an existing server; it does not create one or change where the
compositor listens. DRM uses `$XDG_RUNTIME_DIR/ferese/control.sock`. Nested
instances use `$XDG_RUNTIME_DIR/ferese/instances/<id>/control.sock`; copy the
actual path from the compositor's startup log. Each instance removes its own
socket and directory on normal shutdown. A forced kill can leave the directory
behind; later instances allocate a different one.

Clients launched by a nested compositor inherit its `FERESE_SOCKET`, so
`feresectl outputs` inside that session connects to that instance.
`autostart` launches desktop entries locally and does not use IPC.

## Connection lifetimes

The server permits 64 simultaneous connections. A new connection must begin its
first request within five seconds; each frame then has five seconds to finish.
Ordinary connections close after 30 idle seconds and blocked response writes
expire after two seconds. These bounds release slots held by stalled clients.
Accepted portal leases remain connected while idle, and pending long polls and
event subscriptions do not have the ordinary idle deadline.

## Follow changes

```sh
feresectl event-stream
feresectl --socket "$XDG_RUNTIME_DIR/ferese/instances/12345-abcdef/control.sock" event-stream
```

`event-stream` writes one JSON value per line and flushes each line. It always
uses JSON, so `-j` is optional. `theme subscribe` also keeps its newline-delimited
JSON output.

The first event is a `snapshot` containing outputs, workspaces, windows, focus,
config status, the logical theme, and lock state. Later events contain replacement
values for changed domains:

| Type | Payload field |
| --- | --- |
| `outputs_changed` | `outputs` |
| `workspaces_changed` | `workspaces` |
| `windows_changed` | `windows` |
| `focus_changed` | `focus` |
| `config_changed` | `config` |
| `theme_changed` | `theme` |
| `lock_changed` | `lock` |

For example:

```json
{"version":1,"generation":12,"last":true,"type":"focus_changed","focus":{"window":7,"output":1,"workspace":3}}
```

Event schema version 1 is defined in `ferese-ipc::events`, independently of the
command protocol version. A subscriber requests that version using the framed
`event-stream` command. The server sends a normal response acknowledging the
subscription, followed by framed events on the same connection. That connection
is then reserved for events.

Changes are sampled after an event-loop dispatch. Output reconciliation must
finish before a desktop generation is published. Events from the same dispatch
share a `generation`; only its final event has `last: true`. Consumers maintaining
a desktop model should apply the whole generation together. Intermediate changes
within a dispatch are coalesced, so this stream is not an audit log of every input
or mutation. Generation numbers may have gaps.

Window events describe identity, title, activation, workspace, floating state,
and fullscreen state. They omit visual geometry, animation frames, and client
damage. Theme events omit the presented crossfade state and its frame revisions.
Config revisions advance when a changed configuration is accepted; rejected
reloads leave that revision intact and report an error. Lock events distinguish
`unlocked`, `acquiring`, `locked`, and `orphaned`, and include display sleep state.
While locked, snapshots and replacement events redact windows, workspaces,
focus, and output workspace/focus fields. Unlocking restores those domains.

## Delivery limits

The compositor allows at most 16 event subscribers within its existing limit of
64 IPC connection workers. Each subscriber has a queue of at most 32 events.
Publishing uses non-blocking sends. A full or disconnected queue removes that
subscriber; socket writes happen on its worker with a two-second write timeout.
Idle disconnected streams are checked every 250 milliseconds.

Events are not replayed. An overflow can end a stream partway through a generation.
Discard any generation without `last: true`, reconnect, and replace local state
with the new initial snapshot. Socket authentication and the existing one-MiB
frame limit also apply to event streams.

When there are no subscribers, event publication does not build desktop
snapshots. With subscribers, it compares logical domain snapshots after each
dispatch. Ordinary damage, cursor movement, and redraw code do not publish events
directly.

### Pomodoro controls

The `pomodoro` command uses the activity schema version:

```json
{"version":1,"type":"command","id":1,"command":"pomodoro","args":{"version":1,"action":"start","session":null}}
```

Actions are `start`, `pause`, `resume`, `next`, `stop`, `reset` and `status`.
The result is the current `{id, timer}` record, or `null` when no session exists.
Activity snapshots include this record in `pomodoro` and its Timer presentation
in `activities`. Running timers carry a host-authoritative BOOTTIME `deadline`;
paused timers carry their exact `remaining_ms` and no deadline. The
`paused-countdown` activity value preserves that duration without ticking.

Popup controls send the displayed activity ID in `session`. The host rejects
it if a reset or restart replaced that session, so a delayed action can't stop
a new timer. CLI commands use `null` to address the current session. These
commands use the same authenticated, same-user socket as other activity calls
and are unavailable while the desktop is locked.