# 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.