53 lines
3.2 KiB
Markdown
53 lines
3.2 KiB
Markdown
# 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.
|