blomarchy/shell/README.md

Blob shell

blob-shell is a single long-running Quickshell instance that hosts the Blob desktop. Hyprland autostart launches one shell per graphical session; everything else — the bar, background switcher, panels, and overlays — runs inside the shell as a plugin.

Hosting everything inside one shell means:

• shared services and singletons live once, not once per process
• summoning a panel is an IPC call into a process that is already running, not a fresh quickshell -p ... cold start
• third-party plugins can be loaded from disk without changing any source code in Blob itself

The runtime layout:

shell/
  shell.qml              entry point (ShellRoot)
  services/
    PluginRegistry.qml   discovers, validates plugins, looks up enabled state in shell.json
    BarWidgetRegistry.qml unified registry for bar widgets (1p + 3p)
  plugins/
    bar/                 first-party plugins (see plugins/README.md)
    image-picker/
    menu/
    notifications/
    panels/
      audio/
      bluetooth/
      monitor/
      network/
      power/
      weather/
    services/
      battery/
      idle/
    osd/
    polkit/

The plugin discovery path is documented in plugins/README.md.

Plugin manifest

Every plugin ships a manifest.json describing what it is and how the shell should load it. Minimal example:

{
  "schemaVersion": 1,
  "id": "my.org.cool-clock",
  "name": "Cool clock",
  "version": "1.0.0",
  "author": "You",
  "description": "A clock that does cool things",
  "kinds": ["bar-widget"],
  "entryPoints": { "barWidget": "Widget.qml" },
  "barWidget": {
    "displayName": "Cool clock",
    "category": "Time",
    "allowMultiple": false,
    "defaultSection": "left",
    "defaults": { "format": "HH:mm" },
    "schema": [
      { "key": "format", "type": "string", "label": "Format" }
    ]
  }
}

Supported kinds:

Kind	What it is
bar-widget	A component that the active bar can drop into a section
panel	A persistent or summoned floating window (e.g. OSD)
overlay	A fullscreen overlay (e.g. background switcher)
menu	A summoned menu surface
service	A headless singleton, no UI
bar	A full bar option that can replace the built-in blob.bar

Only one bar plugin is active at a time. Missing or invalid selections fall back to the built-in blob.bar, so users always have a safe path home. Panels, overlays, and menus are loaded when summoned. Plugins that need to outlive a single summon can set keepLoaded: true (e.g. the image picker keeps its overlay window mounted between summons). The same flag keeps a service mounted across plugin hot-reload, so tearing down a changed bar widget cannot destroy blob.lock while Hyprland still holds the session lock. The kept instance is not replaced, so code changes to a keepLoaded service itself only take effect on a shell restart. First-party services are loaded at startup.

Entry points may declare blobPath, shell, manifest, pluginRegistry, and barWidgetRegistry properties for host injection. Built-in plugins receive the trusted host objects. Third-party plugins receive capability-scoped facades: ordinary plugins can look up and control only their own service and lifecycle, built-in clones retain narrow source-specific configuration and UI compatibility, menu plugins receive an application-library facade, and plugins can read detached scalar bar state. A full-bar plugin additionally receives detached bar configuration and widget-catalog snapshots, narrow proxies for the non-authentication services used by built-in bar widgets, and lifecycle control over configured non-authentication UI plugins. Authentication capabilities are stamped from trusted first-party manifests, authentication services are retained outside the host's public service map and QML object tree, and changing a third-party registry or configuration snapshot cannot mutate host state. Facades do not isolate visual widgets from the parent hierarchy of the shared QML scene, so sensitive state must remain outside that reachable graph.

Widgets rendered by a third-party replacement bar receive a service-less entry facade with target-scoped lifecycle and settings operations. Their live service objects are available only when the trusted built-in bar hosts them; otherwise the replacement bar could request and retain any configured widget's service.

The full schema lives in services/PluginRegistry.qml.

Installing a third-party plugin

A plugin is a git repo with a manifest.json at its root. Adding one clones it straight into ~/.config/blob/plugins/<id>/ (named by the manifest id); updating is a fast-forward pull of that checkout.

blob plugin add https://github.com/acme/blob-weather.git
blob plugin update acme.weather       # fetches, shows a diff, fast-forwards
blob plugin update                    # updates every git-managed plugin
blob plugin remove acme.weather

⚠️ Plugins run as unsandboxed code inside blob-shell. Adding warns you before cloning, plugins land disabled so you can review the code before enabling, and updates show a diff of the changes before touching anything. The scoped QML interfaces remove direct authentication-service and generic replacement-bar service lookups, but visual plugins still share and can traverse the ordinary host scene. Only add repos whose code you are willing to run.

Add, update, and remove commands confirm in a terminal even when given arguments; without a terminal they refuse rather than guess. Pass --yes to skip every prompt — this is the path for scripts and AI agents:

blob plugin add https://github.com/acme/blob-weather.git --enable --yes
blob plugin update --yes

The installer never runs plugin code, install hooks, or sudo — it only clones files, validates the manifest, and toggles enabled state over shell IPC. Since an installed plugin is a plain git checkout, anything beyond add/update (pinning a ref, switching branches) is ordinary git in the plugin directory.

Installing by hand

You can still drop a plugin in without git:

1. Put it in ~/.config/blob/plugins/<plugin-id>/ with a manifest.json plus the QML referenced from its entryPoints.
2. blob-shell shell rescanPlugins.
3. blob plugin enable <id>. Bar widgets start in barWidget.defaultSection, or in the center when it is omitted, and can be moved with blob bar move; a full bar replaces the one in use.

The lower-level IPC equivalents remain available via blob-shell shell rescanPlugins, blob-shell shell enablePlugin <id> '{}', and blob-shell shell listPlugins. The blob plugin commands wrap those calls. blob bar move and blob bar set edit the persisted widget layout in shell.json.

To hack on a built-in plugin safely, clone it into user config instead of editing the built-in source. The complete plugin directory is copied, including every declared kind and local dependency. A built-in id such as blob.clock becomes <username>.clock (e.g. dhh.clock), with My Clock as its display name. The username prefix keeps shared clones from colliding with each other or with other plugin authors.

blob plugin clone blob.clock

Cloning switches from the built-in to the new personal plugin, preserving an existing bar widget's position and settings. Setup > Plugins > Clone provides the interactive picker, then opens the new <username>.* directory in $EDITOR. Existing shortcuts and shell IPC calls made to the built-in id are routed to the enabled clone, so cloning does not require changing its callers. Removing an active clone switches back to its built-in source. Saving a file anywhere under ~/.config/blob/plugins/ reloads plugin code automatically; blob-shell shell rescanPlugins remains available to force a reload.

First-party plugins under shell/plugins/ are discovered the same way and load by default. Disabling a non-widget records it in disabledPlugins[]; disabling a widget removes it from the bar layout while leaving its component available to add again. A full bar has no off state and is replaced by enabling another.

IPC contract

The shell exposes a single shell IPC target plus whatever extra targets individual plugins register (e.g. the bar's bar target for refresh hooks, the image picker's image-selector target). blob-menu uses the shell target to summon the first-party blob.menu plugin instead of running a separate Quickshell instance.

Method	Returns	Effect
ping	ok	health check
summon <id> <payloadJson>	ok / unknown	load + open a panel/overlay plugin
hide <id>	—	close a previously-summoned plugin
toggle <id> <payloadJson>	—	summon if closed, hide if open
call <id> <method> <arg>	string	call a method on an already-loaded plugin
rescanPlugins	—	re-walk plugin dirs and hot-reload plugin code
reloadConfig	ok	reload ~/.config/blob/shell.json
setPluginEnabled <id> <enabled>	ok / unknown	flip the persisted enabled bit (see note)
listPlugins	JSON	every discovered plugin, sorted by name

Direct invocation:

quickshell ipc -p $BLOB_PATH/shell call shell ping

Hyprland autostart launches the shell directly with quickshell -p $BLOB_PATH/shell. Use blob-shell-restart to stop every running instance of that config and launch one fresh shell process.

A convenience wrapper, blob-shell, forwards IPC calls to the running shell. It does not start the shell.

blob-shell shell ping
blob-shell shell toggle blob.menu '{"menu":"root"}'
blob-shell shell listPlugins
blob-shell shell rescanPlugins

Note on setPluginEnabled: the enabled argument is a string. Only the literal "true" enables the plugin; every other value (including "True", "1", "yes", or omitted) disables it. This keeps the IPC surface type-stable across QML's string-only IPC arguments.

Persisted state

There is one user config file. Everything that distinguishes your customization from the shipped defaults lives in it.

Path	Owner	Purpose
~/.config/blob/shell.json	the shell	full layout + per-entry settings + enabled plugin list
~/.config/blob/plugins/<id>/	user	drop-in third-party plugin source files

The config/blob/shell.json default config describes the fresh-install state. When the user has no shell.json, the shell uses the defaults verbatim. Once the user customizes anything, shell.json becomes the authoritative file — we do not deep-merge defaults back in.

shell.json shape

{
  "version": 1,
  "idle": {
    "screensaver": 150,
    "lock": 300
  },
  "bar": {
    "id": "blob.bar",
    "position": "top",
    "transparent": false,
    "centerAnchor": "blob.clock",
    "layout": {
      "left":   [ { "id": "blob.menu" }, { "id": "blob.workspaces" } ],
      "center": [ { "id": "blob.clock", "format": "HH:mm" } ],
      "right": [
        { "id": "blob.audio" }
      ]
    }
  },
  "plugins": []
}

Storage rules

1. The active bar option is bar.id. Omit it or set it to blob.bar to use the built-in bar. Set it to another plugin id whose manifest declares kind: "bar" to replace the full bar.
2. Every plugin instance is one entry. Either in bar.layout.<section> for bar widgets, or in plugins[] for panels, overlays, services, menus, and anything else non-bar.
3. Settings are inline on the entry. No config: sub-object, no separate per-plugin settings file, no merge layers. The fields on each entry are the values the plugin sees.
4. Built-in widget ids are namespaced. Use ids such as blob.clock, blob.audio, and blob.network. The migration rewrites older ids like Clock and AudioPanel forward.
5. Third-party enabled ⇔ present. A third-party plugin is enabled iff its id appears somewhere in shell.json. For full bar options, that means bar.id; for bar widgets, plugin enable/disable adds/removes layout entries; other plugin kinds are enabled the same way. First-party non-bar plugins are enabled unless listed in disabledPlugins[].
6. Multiple instances are allowed when a manifest sets allowMultiple: true. Each instance is independent — e.g. two clock widgets in different timezones are just two {"id":"blob.clock", "timezone": ...} entries with their own values.
7. Idle timings are top-level. idle.screensaver and idle.lock are seconds since user idle began, so the default lock fires at 300s even if the 150s screensaver starts first.
8. version: 1 is required at the top level. The shell will fall back to defaults rather than load an unknown version.

Implementation history

Built up in phases on this branch:

• Phase 1 — blob-shell phase 1: host the existing bar in a single shell
• Phase 2 — blob-shell phase 2: plugin registry and bar widget registry
• Phase 3 — blob-shell phase 3: fold bar-settings into the shell as a panel plugin
• Phase 4 — blob-shell phase 4: absorb background-switcher as a plugin
• Phase 5 — blob-shell phase 5: docs, cleanup, and migration crumbs
• Phase 6 — blob-shell phase 6: reviewer cleanup (path traversal, collision, races)
• Phase 7 — blob-shell phase 7: replace socket with IpcHandler, rename to image-picker
• Phase 8a — blob-shell phase 8a: unified shell.json with inline plugin settings

Shared services and Pipewire/UPower/Hyprland consolidation are explicitly out of scope here and deferred to a follow-up after a review pass.