af6ba1bd82
First-boot --autostart now walks Welcome, timezone, network hint, updates, and an optional snapper day-zero snapshot in the existing help window, then hands off to the live cheatsheet tour. Existing onboarded users are skipped.
68 lines
3.2 KiB
Markdown
68 lines
3.2 KiB
Markdown
# breadhelp — bread event integration
|
|
|
|
breadhelp is a standalone GTK help center: it works exactly the same with
|
|
or without `breadd` running. When breadd *is* present, it publishes one
|
|
event after the main window is actually shown. 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: **`help`**. Transport: `bread-utils`'s `bread_client` module
|
|
(feature `bread-client`) — breadhelp links it directly. Each `emit` is
|
|
its own short-lived connection. Command verbs are only received while
|
|
`breadhelp listen` is running — that process holds the
|
|
`bread.command.help.**` subscription open.
|
|
|
|
## Events published (`bread.help.*`)
|
|
|
|
| Event | Data | When |
|
|
|-------|------|------|
|
|
| `bread.help.opened` | `{ "autostart": bool }` | The main help window is presented (`ApplicationWindow::present`). `autostart` is `true` when that invocation was launched with `--autostart`. |
|
|
| `bread.help.open.done` | `{}` | `bread.command.help.open` was received and `breadhelp` was spawned. This is the command confirmation, not proof the window mapped — the spawned process is the same no-args invocation as SUPER+/. |
|
|
| `bread.help.open.failed` | `{ "error": "<message>" }` | `bread.command.help.open` was received but this binary could not be started. |
|
|
|
|
Not emitted when:
|
|
|
|
- every-login `--autostart` builds a hidden window because onboarding is
|
|
already done (silent autostart)
|
|
- first-run `--autostart` presents the main window on the day-zero
|
|
wizard; the tour overlay starts after that wizard finishes (or is
|
|
skipped). `bread.help.opened` **is** emitted for that first-run present.
|
|
- `--onboard` / `--tour-event` (tour only)
|
|
- `--screenshot` (capture, not a user-visible open)
|
|
|
|
## Commands honored (`bread.command.help.*`)
|
|
|
|
These are only received while `breadhelp listen` is running. Publishing a
|
|
command with no subscriber is a silent no-op — that is the documented
|
|
bread convention, not a breadhelp bug.
|
|
|
|
| Verb | Data | Effect |
|
|
|------|------|--------|
|
|
| `open` | none | Same as running `breadhelp` with no flags: present the main help window (GApplication forwards to an already-running primary instance). Emits `bread.help.open.done` / `.failed`. |
|
|
|
|
```lua
|
|
bread.spawn(function()
|
|
bread.emit("bread.command.help.open")
|
|
bread.wait("bread.help.open.done", { timeout = 5000 })
|
|
end)
|
|
```
|
|
|
|
### Not implemented: extra verbs
|
|
|
|
There is no `onboard` / `tour` / `suggest` command verb. Those already
|
|
exist as local CLI flags (`--onboard`, `--tour-event`, `--suggest`).
|
|
If/when a bus verb maps to real extra behavior, add it then — do not
|
|
stub one as a no-op 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 — the help
|
|
center, tour, and screenshots are entirely unaffected.
|
|
- If breadd restarts, the command subscription reconnects automatically
|
|
(`BreadClient::subscribe`'s background thread has its own backoff
|
|
loop); no restart of `breadhelp listen` is needed.
|
|
- If `breadhelp listen` is not running, commands are a graceful no-op at
|
|
the bus (no subscriber). The CLI still works.
|