# Lios Integration
LiosBar offers two separate integration modes: the existing standalone
GTK4/VTE application and, since 0.1.2, an embeddable Rust GTK4 component.
Lios 0.1.81 adds an opt-in integrated workspace using an exact reviewed snapshot
of the 0.1.2 widget source, while the managed plugin card remains process-based.
These are separate modes with different trust and lifetime boundaries.
Lios 0.1.82 adopts the 0.1.3 component, including filtering and explicit
activation/focus routing.
Lios 0.1.83 adopts the 0.1.4 component's keyboard preview navigation.
Lios 0.1.84 adopts the 0.1.5 component's host-persisted layout menu.
Lios 0.1.85 adopts the 0.1.6 component's session reordering and keyboard moves.
Lios 0.1.86 updates the managed standalone plugin to LiosBar 0.1.7. That release
keeps the 0.1.6 widget source unchanged and improves standalone dotfile saves.
Lios 0.1.88 pins the standalone card to 0.1.8, adding per-session terminal Find.
This remains host-owned UI; the reusable 0.1.6 widget source is unchanged.
Lios 0.1.89 pins the standalone card and reviewed widget snapshot to 0.1.9.
Only the widget's GUI test timing changed; production layout and the Rust API
remain unchanged. Standalone diagnostics and graphics overrides stay outside
the embeddable component and do not affect the host's rendering choices.
## Integrated Lios workspace
In Lios, Ctrl+Shift+T opens a workspace from a normal terminal or adds a session
inside an existing workspace. Lios retains its original single-terminal startup
and appearance defaults. Each embedded widget is a full Lios terminal with its
own wallpaper, prompt, Preferences, search, and clipboard protection.
The static component runs in Lios's process. Lios routes actions and titles to
the active session, cancels pending pastes when a terminal becomes hidden, and
checks all sessions when closing a workspace. An exiting background child keeps
its output and cannot close another terminal. Session removal cancels pending
startup; a new session inherits the active directory without replaying commands.
Lios vendors an exact reviewed component with its licenses. The component is
also published on crates.io. Its `src/liosbar/README.md` records the source commit;
its package audit verifies the snapshot checksum. No unpublished Cargo
dependency is required.
The integrated sidebar saves position and display choices under `[workspace]`
in Lios's configuration through its existing serialized config writer. Width
and session names last for that workspace only. It does not read or change the
standalone application's `bar.toml`.
## Rust component contract
`lios-bar` with `default-features = false, features = ["widget"]` exports a
`SessionWorkspace`. It owns only a sidebar, a stack, bounded display labels,
and up to 32 host-supplied widgets. The standalone app uses this same API.
The component itself opens no PTYs, spawns no commands, reads no files or
terminal output, changes no environment variables, and installs no global CSS.
The host creates each complete terminal widget (including backgrounds and
overlays), chooses its settings, and retains the component handle. Selection
notifications run after internal state borrows are released. The host must
also release its own state borrows before invoking component mutations that
can emit callbacks. New/close controls emit requests; the host decides whether
to create a terminal or confirm removal. `remove` is an explicit destructive
operation for live terminals and never runs automatically on a close request.
Opaque session IDs are local bookkeeping, not authentication or persistence.
They are not reused within a workspace. Already-parented widgets and more than
32 entries are rejected without implicitly reparenting host content.
This is a statically linked Rust dependency, not a dynamically loaded plugin
ABI or sandbox. Hosts must review and pin the source they compile. A terminal
host must route copy/paste, search, Preferences, titles, and close/exit handling
by session ID; the library intentionally does not infer these policies.
Lios's integrated workspace implements these host policies; external hosts
must implement and test their own before exposing live terminals.
Filtering changes sidebar visibility only. `connect_activated` asks the host
to focus content, including when the selected ID has not changed. Hosts should
wire it separately from `connect_selected`. `focus_search` supports a host
shortcut without the component installing window-global keyboard handlers.
While the filter owns focus, Up/Down move a separate candidate through visible
IDs; only Enter or row activation changes content. Hosts should style
`.liosbar-session-preview` as a preview distinct from the active `:selected`
row. Candidate changes never emit selection or close requests.
The built-in layout menu exposes `SidebarPreferences`. Hosts apply saved choices
with `set_preferences` before connecting `connect_preferences_changed` to their
own persistence logic. Settings callbacks run without model borrows and do not
emit session selection events; they must not be treated as permission to launch
or close content. Reset affects display choices only.
Row reordering preserves stable IDs, content, and active selection. Hosts can
bind `move_active` to Ctrl+Shift+Page Up/Down; regular `select_relative` navigation
then follows the reordered sidebar. Hosts must not infer session identity from
a row index. Drag-and-drop only moves rows within this component instance; it
does not transfer terminals, PTYs, or settings between workspaces.
## Standalone plugin states
Lios tracks three separate facts:
- **Installed:** Cargo metadata proves that the executable is the exact
version-pinned `lios-bar` crates.io release.
- **Enabled:** the user's Lios configuration permits the plugin card to launch
that verified executable.
- **Running:** an independent LiosBar process is alive.
Disabling LiosBar changes only the Lios configuration. It does not uninstall
the executable, delete `~/.config/lios/bar.toml`, close terminal sessions, or
terminate a running LiosBar process.
## Launch contract
The curated Lios plugin card launches the verified `lios-bar` executable with
an empty argument list. LiosBar therefore uses its own saved sidebar setting
and normal working-directory behavior. Users can still launch it directly with
documented options such as:
```sh
lios-bar --sidebar right
lios-bar --working-directory /path/to/project
```
LiosBar does not expect a socket, environment token, terminal stream, or
callback channel from Lios. It must remain fully usable when installed and
launched without the core terminal.
## Compatibility
| 0.1.0 | Superseded | Initial standalone workspace release |
| 0.1.1 | Lios 0.1.69 | Version-pinned install, enable/disable, and launch |
| 0.1.2 source | Lios 0.1.81 integrated workspace | Pinned widget snapshot; same standalone CLI; external plugin pin remains 0.1.1 |
| 0.1.3 source | Lios 0.1.82 integrated workspace | Bounded filter, activation/focus callback, selection visibility |
| 0.1.4 source | Lios 0.1.83 integrated workspace | Keyboard preview, stable candidate IDs, explicit commit/cancel |
| 0.1.5 source | Lios 0.1.84 integrated workspace | Host-persisted density/title/hint preferences and layout menu |
| 0.1.6 source | Lios 0.1.85 integrated workspace | Same-workspace row reordering and focus-preserving keyboard moves |
| 0.1.7 standalone | Lios 0.1.86 plugin catalog | Reviewed exact registry release; dotfile-aware layout saves |
| 0.1.8 standalone | Lios 0.1.88 plugin catalog | Per-session literal scrollback search and cancellation |
Any future change that introduces arguments, IPC, shared state, credentials,
or process lifecycle control requires a new threat-model review in both
projects before either side adopts it.