118 lines
6.7 KiB
Markdown
118 lines
6.7 KiB
Markdown
# First-party plugins
|
|
|
|
These plugins ship with Blob and are discovered by the shell at startup.
|
|
They use the same `manifest.json` contract as third-party plugins; the
|
|
only difference is that the shell flags them with `__isFirstParty: true`.
|
|
First-party non-bar plugins are enabled unless listed in `disabledPlugins[]`;
|
|
`blob.bar` is the default bar option and becomes inactive only while another
|
|
`kind: "bar"` plugin is selected. Services and keep-loaded panels are mounted
|
|
at startup; other panels, overlays, and menus are loaded on demand.
|
|
|
|
User-installed plugins live alongside these conceptually but on disk under
|
|
`~/.config/blob/plugins/<plugin-id>/` rather than in this directory.
|
|
|
|
| Plugin | id | kinds | entry point |
|
|
|---------------|---------------------------|-------------------------|---------------------------------------|
|
|
| Bar | `blob.bar` | `bar` | `bar/Bar.qml` |
|
|
| Image picker | `blob.image-picker` | `overlay` | `image-picker/ImagePicker.qml` |
|
|
| Emojis | `blob.emojis` | `overlay` | `emojis/Emojis.qml` |
|
|
| Clipboard mgr | `blob.clipboard` | `overlay` | `clipboard/Clipboard.qml` |
|
|
| Reminders | `blob.reminders` | `overlay` | `reminders/ReminderFlow.qml` |
|
|
| Blob menu | `blob.menu` | `menu`, `bar-widget` | `menu/Menu.qml`, `menu/BarWidget.qml` |
|
|
| Notifications | `blob.notifications` | `service` | `notifications/Service.qml` |
|
|
| Audio | `blob.audio` | `bar-widget` | `panels/audio/Panel.qml` |
|
|
| Bluetooth | `blob.bluetooth` | `bar-widget` | `panels/bluetooth/Panel.qml` |
|
|
| Clock | `blob.clock` | `bar-widget` | `panels/clock/BarWidget.qml` |
|
|
| Monitor | `blob.monitor` | `bar-widget` | `panels/monitor/Panel.qml` |
|
|
| Network | `blob.network` | `bar-widget` | `panels/network/Panel.qml` |
|
|
| Power | `blob.power` | `bar-widget` | `panels/power/Panel.qml` |
|
|
| Weather | `blob.weather` | `bar-widget` | `panels/weather/BarWidget.qml` |
|
|
| Media | `blob.media` | `service`, `bar-widget` | `services/media/Service.qml`, `services/media/BarWidget.qml` |
|
|
| Battery | `blob.battery` | `service` | `services/battery/Service.qml` |
|
|
| Idle | `blob.idle` | `service` | `services/idle/Service.qml` |
|
|
| Night light | `blob.nightlight` | `service` | `services/nightlight/Service.qml` |
|
|
| Lock screen | `blob.lock` | `service` | `lock/Service.qml` |
|
|
| OSD | `blob.osd` | `panel` | `osd/Osd.qml` |
|
|
| Polkit agent | `blob.polkit` | `service` | `polkit/PolkitAgent.qml` |
|
|
|
|
First-party bar-only widgets also carry manifests next to their QML files,
|
|
e.g. `bar/widgets/Workspaces.manifest.json`. Rich popup widgets live in their
|
|
own plugin directories, each with its own `manifest.json`.
|
|
|
|
## Bar
|
|
|
|
The built-in status bar and default full-bar option. Layout lives in the
|
|
top-level `bar:` subtree of `~/.config/blob/shell.json` (with the shell
|
|
providing [`config/blob/shell.json`](../../config/blob/shell.json) when
|
|
the user has no file). See [`bar/README.md`](bar/README.md) for the widget catalogue
|
|
and customization schema.
|
|
|
|
## Image picker
|
|
|
|
Fullscreen image-grid selector overlay. Used by `blob-menu-images`
|
|
(wallpaper picker) and `blob-theme-switcher` (theme picker) and any
|
|
other caller that wants to present a directory of images with previews.
|
|
|
|
Two ways to drive it:
|
|
|
|
- Shell-level summon: `blob-shell shell summon blob.image-picker '<jsonPayload>'`.
|
|
The payload can carry `imageDirs`, `imageRows`, `selectedImage`,
|
|
`selectionFile`, `doneFile`, `showLabels`, `filterable`. Best for
|
|
in-shell callers that already speak JSON.
|
|
- Direct IPC target: `blob-shell image-selector open <imageDirs> <imageRowsB64> <selectedImage> <selectionFile> <doneFile> <showLabels> <filterable>`.
|
|
Positional args; `imageRowsB64` is base64-encoded so embedded newlines /
|
|
tabs survive the bash argv handoff. This is what `blob-menu-images`
|
|
uses. Colors come from the central shell theme singleton; there is no
|
|
per-call override surface.
|
|
|
|
The selection round-trip remains file-based: callers create a
|
|
`selection_file` and `done_file` (both `mktemp`), pass the paths, and
|
|
poll `done_file` for existence. The plugin writes the chosen path into
|
|
`selection_file` and touches `done_file` when it's done. `cancel` IPC
|
|
clears it without writing a selection.
|
|
|
|
The plugin has `keepLoaded: true` so the layer-shell window survives
|
|
between summons within a single shell session.
|
|
|
|
## Lock screen
|
|
|
|
Session-lock surface using Quickshell's native `WlSessionLock` and two
|
|
separate PAM services: `blob-lock-password` for password auth and,
|
|
only when fingerprints are enrolled, `blob-lock-fingerprint` for
|
|
fingerprint auth. It mirrors the previous lock screen field dimensions,
|
|
colors, blurred wallpaper, placeholder, and Hyprland-driven corners.
|
|
The plugin sets `keepLoaded: true` so a plugin hot-reload (for example
|
|
an installed bar widget changing on disk) does not destroy the lock
|
|
client while Hyprland still holds the session lock.
|
|
|
|
## Polkit agent
|
|
|
|
Theme-aware authentication dialog for privileged actions. It uses
|
|
Quickshell's native `Quickshell.Services.Polkit.PolkitAgent` backend and
|
|
runs inside the long-lived `blob-shell` process, replacing the old
|
|
`polkit-gnome-authentication-agent-1` autostart.
|
|
|
|
## Blob menu
|
|
|
|
Quickshell-powered Blob command menu.
|
|
The menu UI lives in `menu/Menu.qml` as a first-party `menu` plugin and is
|
|
summoned through the shell (`blob-shell shell summon blob.menu ...`),
|
|
so it shares the long-running `blob-shell` process instead of starting a
|
|
second Quickshell instance.
|
|
|
|
The menu definition lives outside the shell host code:
|
|
|
|
- defaults: `default/blob/blob-menu.jsonc`
|
|
- user extensions: `~/.config/blob/extensions/blob-menu.jsonc`
|
|
|
|
The shell parses both JSONC files at startup (with `watchChanges: true`
|
|
so edits take effect without a restart), evaluates `when:` / `checked:`
|
|
bash expressions in a single batched subprocess, and executes the
|
|
selected `action:` string directly via `Quickshell.execDetached`. The
|
|
long-running shell process keeps the parsed menu in memory, so the
|
|
keybind → IPC → visible path costs ~30ms cold.
|
|
|
|
## Coming soon
|
|
|
|
- `blob.theme-switcher` — folds theme switching into the shell.
|