breadbox/EVENTS.md

breadbox — bread event integration

breadbox is a standalone app launcher: it works exactly the same with or without breadd running. When breadd is present, the GTK launcher publishes a single event into the shared bread automation fabric after a successful launch. See the parent bread repo's Documentation.md — specifically its "Namespaces" and "Integrating a bread* app" sections — for the general convention this follows.

App id: box. Transport: bread-utils's bread_client module (feature bread-client) — breadbox links it directly. One-shot launcher invocations each emit on their own fire-and-forget connection. Command verbs are only received while breadbox listen is running — that process holds the bread.command.box.** subscription open.

Under an [launcher] mode = "embedded" theme (spotlight), breadbar's own bar-drawer capsule is the launcher UI, and breadbox redirects instead of mapping its own overlay window — see the "Embedded launcher theme" section below. Everything else on this page describes the default (overlay-mode) behavior.

Events published (bread.box.*)

Event	Data	When
bread.box.launched	{ "id": "<desktop id or exec>", "name": "<display name>" }	The user launched an app (Enter / keypad Enter on the selected row, or activating a row) and the spawn succeeded. Not emitted if Command::spawn fails (missing terminal, exec that cannot start). id is the desktop-file id (the .desktop filename, e.g. firefox.desktop), falling back to the stripped Exec= line when that id is empty. name is the desktop-entry display name.
bread.box.open.done	{}	bread.command.box.open was received (via breadbox listen) and this binary was spawned — non-embedded themes only. Not proof the overlay mapped, just that the process was started (same toggle as a keybind). Never emitted under an embedded theme — see below.
bread.box.open.failed	{ "error": "<message>" }	bread.command.box.open was received but this binary could not be started — non-embedded themes only. Unreachable under an embedded theme, since that branch returns before ever attempting to spawn.
bread.box.open_requested	{}	Emitted by the plain breadbox binary itself (not breadbox listen) instead of mapping its own overlay window, only when the active theme's [launcher].mode is embedded. breadbar's capsule (launcher_command.rs) subscribes to this and opens itself. Own-namespace event, not a command — see dispatch_embedded_open's doc comment for why bread.command.box.open would be the wrong shape here.
bread.box.open.redirected	{}	Emitted by breadbox listen's handle_open, only when bread.command.box.open is received while an embedded theme is active. Replaces .done/.failed in that case: this process never spawns anything (breadbar's capsule is the intended handler) and has no way to confirm breadbar actually received or handled the event — pub/sub here is one-way with no ack. This event means "redirect happened, outcome unknown", not "succeeded".

Launch history is local to breadbox (~/.cache/breadbox/history.json); the event bus is a notification that a launch happened, not a channel for the exec line's arguments or the resulting process.

Commands honored (bread.command.box.*)

These are only received while breadbox listen is running. Publishing a command with no subscriber is a silent no-op — that is the documented bread convention, not a breadbox bug.

Verb	Data	Effect
open	none	Under a non-embedded theme: same as running breadbox (toggle the launcher overlay via the existing singleton). Emits bread.box.open.done / .failed. Under an embedded theme: never spawns; emits bread.box.open.redirected instead — see "Embedded launcher theme" below.

-- Non-embedded themes: `.done` is a real completion signal.
bread.spawn(function()
    bread.emit("bread.command.box.open")
    bread.wait("bread.box.open.done", { timeout = 5000 })
end)

Under an embedded theme this .done wait will time out — .done is never emitted there. A workflow that needs to work under every theme should wait on bread.box.open.redirected too (or treat a timeout as "probably fine, embedded themes have no ack" rather than a failure).

Not implemented: extra verbs

There is no launch / close / query command verb. Picking a desktop id from the bus would be a new product surface. If/when that exists, add the corresponding bread.command.box.* verb at the same time, not stubbed as a no-op ahead of it.

Embedded launcher theme (spotlight)

When the active shell theme's [launcher].mode is embedded, running breadbox directly (e.g. from a keybind) does not map this binary's overlay window — that would stack a second launcher on top of breadbar's own capsule. Instead:

1. breadbox's main checks BreadClient::health() — a real, bounded-timeout round trip to breadd, not just "did the socket exist".
2. If breadd is reachable, it emits bread.box.open_requested and returns. breadbar's capsule (subscribed only while its own active theme is also embedded) is expected to open itself in response. There is no ack for this — if breadbar isn't running, or is running under a different theme and therefore never subscribed, this is still a silent no-op on the bus with nothing further to fall back to. (BreadClient has no "is anyone subscribed" query.)
3. If breadd is not reachable, breadbox logs that to stderr and falls back to mapping its own overlay window anyway — a keybind press always opens something, rather than the historical fully silent no-op when the bus was down.

breadbox listen's handle_open (the bread.command.box.open handler) applies the same "never map a second launcher" rule but from the command side: under an embedded theme it never spawns, logs to stderr, and emits bread.box.open.redirected instead of .done — see the events table above for why .done would be a false claim here.

Fail-safe behavior

• If breadd isn't installed or isn't running, emit is a silent no-op (BreadClient::emit never blocks or errors the caller) and the command subscription simply never receives anything — launching, history, theming, and the singleton toggle are entirely unaffected. Under an embedded theme specifically, a direct breadbox invocation additionally checks reachability up front and falls back to mapping its own overlay window when breadd is down (see above) — so this invariant now holds there too, not just for every other theme.
• If breadd restarts, the command subscription reconnects automatically (BreadClient::subscribe's background thread has its own backoff loop); no restart of breadbox listen is needed.
• If breadbox listen is not running, commands are a graceful no-op at the bus (no subscriber). The CLI still works, and one-shot invocations still emit bread.box.launched on their own short-lived connection.
• Closing the launcher without launching anything emits nothing.
• What is not covered: under an embedded theme, if breadd is reachable but breadbar itself isn't running (or isn't subscribed), neither the direct-keybind path nor the command path can detect that or fall back further — both are fire-and-forget with no ack. This is a known limitation of the current transport, not an oversight.