breadclip/EVENTS.md

breadclip — bread event integration

breadclip is a standalone clipboard manager: it works exactly the same with or without breadd running. When breadd is present, breadclipd publishes events into the shared bread automation fabric and listens for a small set of commands. 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: clip. Transport: bread-utils's bread_client module (feature bread-client) — breadclipd links it directly rather than shelling out, since it's a long-running process for the command-subscription half (though each emit call is still its own short-lived connection, since capture_once() — the actual clipboard-read code — runs as a fresh per-clipboard-change process invocation, not inside a persistent loop).

Events published (bread.clip.*)

Event	Data	When
bread.clip.copied	{ "kind": "url" | "error" | "code" | "path" | "plain", "len": <bytes or chars> }	Every successful clipboard capture (text or image — images always get kind: "image"). kind is a heuristic classification (see breadclipd/src/content_kind.rs), not a guarantee — don't build a security decision on it.
bread.clip.clear.done	{}	bread.command.clip.clear was received and history was successfully cleared.
bread.clip.clear.failed	{ "error": "<message>" }	bread.command.clip.clear was received but clearing failed (e.g. DB error).

Content is never included in the payload — only its detected kind and length. History (including the actual copied content) stays local to breadclip's own SQLite database; the event bus is for notifications about clipboard activity, not a channel for clipboard content itself.

Commands honored (bread.command.clip.*)

Verb	Effect
clear	Deletes all clipboard history (text entries and stored image files). Emits bread.clip.clear.done/.failed.

Not implemented: pin / select

An earlier draft of this integration planned pin/select verbs, but breadclip's history schema has no "pinned" concept at all today — there's no column for it, and the GTK popup UI has no corresponding affordance. Adding real pin/select support is a product decision for breadclip itself (does it want pinning, and what should the UI look like?), not something to fabricate as a side effect of wiring up the event bus. If/when breadclip grows that feature, the corresponding bread.command.clip.pin/.select verbs (and matching bread.clip.pinned/.selected events) should be added at the same time, not stubbed out ahead of it.

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 — breadclip's actual clipboard-history functionality is entirely unaffected either way.
• If breadd restarts, the command subscription reconnects automatically (BreadClient::subscribe's background thread has its own backoff loop); no restart of breadclipd is needed.