Plugins

Pearl can run small add-ons as WebAssembly components: a plugin package contains a manifest, a Wasm component and optional image assets, and each enabled plugin runs in its own isolated helper process. Plugins have no network access, no filesystem access and no access to other applications; the exact package bytes are fingerprinted and verified before execution. The feature is experimental and opt-in. A fingerprint identifies package bytes; you still need to trust their source.

Packaged builds enable the Wasm host. For custom builds, wasm-plugins defaults off; check the build if Settings reports the runtime unavailable.

Plugin management lives in Settings → Plugins, in the main Settings application only: the compact control-center flyout has no plugin controls. Open the page with pearl-settings --page plugins or pearlctl settings show --page plugins.

Writing plugins yourself is covered by the plugin development guide in the Pearl repository.

Installing plugins

The Pearl packages ship a few example plugins, including a timer, counters and the Pearl Cat companion. They appear automatically in Settings → Plugins after installation or upgrade, and stay disabled until you approve and enable them: installing never changes your preferences or adds bar widgets.

To install a plugin package yourself, copy its directory into $XDG_DATA_HOME/pearl/plugins/, normally ~/.local/share/pearl/plugins/. Pearl discovers it automatically, and the Plugins page also offers Refresh plugins. Your user directory takes priority over system-installed packages with the same ID, and two packages with one ID in the same location are a conflict: the page shows the selected source and the candidate paths, and removing the extra copy resolves it. Discovery never executes a plugin.

Approving and enabling

Review and enable a plugin in two steps:

1. Choose Review package directly on the plugin card. In Review plugin package, check the plugin ID, version, selected source path, fingerprint and optional permissions, then Save review to draft. This does not enable the plugin; Cancel leaves the draft unchanged.
2. Turn on the card’s enable switch and Apply & save. Expect Running and the chosen bar widget or overlay.

If the enable switch is gray, use Review package on the card first (#66). If it stays disabled, read the notice and Package details and diagnostics.

If the package changes or disappears during review, the dialog closes and the new package needs a fresh review. Changed package bytes can never reuse an old approval: an updated fingerprint retires the running instance and starts its optional permissions from off, so you review them again.

Enabling a plugin in Bar mode adds it to the bar’s end group, including in per-output overrides; an existing placement in another group is preserved. Desktop overlay mode, which also grants the overlay permission, floats the plugin above the wallpaper; turning that permission off returns an enabled plugin to the bar. Bar layout references have the form plugin:pearl.timer-c/main and can also be entered directly in Bar & dock or in per-output preferences. Unknown references stay harmless until a matching plugin runs.

Disable a plugin or revoke optional permissions

Turn the enable switch off and Apply & save to stop the plugin. Disabled means no widget or overlay is running; settings and approval are retained.

Under Settings and placement, turn off Allow keyboard and mouse activity or Allow desktop overlay, then apply. Activity notifications stop when revoked; removing overlay permission returns an enabled plugin to the bar. Use Discard for unsaved changes, or turn a permission back on and apply later.

Each plugin card shows live status and marks unsaved preference changes separately. Settings and placement exposes the plugin’s own controls (text, bounded numbers and switches, saved through the shared draft) plus immediate Retry and Preview actions. Package details and diagnostics contains source paths, the fingerprint, input-activity availability and runtime errors. Search and the All / Enabled in draft / Needs attention filters work on the current page without touching preferences.

Live updates

Plugins install, update, enable, disable and remove while Pearl runs, with no restart:

• An unchanged package at the same path keeps its running instance and state.
• Changing the package’s selected path restarts just that plugin, even for identical bytes; an identical fingerprint keeps its approval.
• A removed package retains its settings and bar references. Restoring the exact approved package resumes it if it is still enabled.
• A failed plugin waits for an explicit Retry; there is no automatic restart loop, and one failing plugin never takes the others or the shell down.
• Incomplete or invalid updates stay unavailable rather than falling back to an older copy. Stage a complete package directory outside the plugins folder and rename it into place.

Recover after an update or package error

What Settings reports	Recovery
Needs a fresh review after update	Check the new ID/version/path/fingerprint, review permissions again, enable if needed, then apply
InvalidPluginImage	Restore the complete original package; declared images must be PNGs with the manifest’s exact dimensions
Package unavailable or missing	Read candidate paths in diagnostics, restore a complete package from its original source, then refresh
Duplicate/conflicting ID	Move the unwanted user copy outside the discovery directory; refresh and check which source now wins
Settings changed/incompatible	Review the new package and use Reset settings for its plugin-owned controls, then apply; record custom values first
Stopped unexpectedly	Read the runtime error, then Retry after addressing the cause

An invalid user copy still shadows the system package. Move unwanted copies and backups outside plugin directories, then refresh. Do not edit assets under /usr/share/pearl/plugins or /usr/share/pearl-git/plugins to bypass review. Restore modified packaged files through their original distribution/channel, then refresh and review if requested. If that fails, report the error, source path and fingerprint rather than resetting all Pearl preferences.

Overlays and the Pearl Cat companion

The Pearl Cat companion animates in the bar or, with the overlay grant, as a desktop overlay. Overlay placement supports choosing the output, size and position, locking the position, click-through and hiding during fullscreen. Overlays reserve no screen space, never take keyboard focus, and disappear before the lock screen or an authentication prompt. Dragging an unlocked overlay saves its position when no Settings draft is pending. Reduced motion stops animation playback.

Can I give Pearl Cat a different skin?

There is no skin picker or separate skins directory yet; see Pearl #68. Use the available placement, size, interaction and animation settings.

The manifest, component and declared PNG assets make up the fingerprint. Replacing cat.png requires fresh validation and review, and the image must match the manifest’s format and dimensions. A user copy has the same checks. Creating a different package is covered by the plugin development guide.

Input activity

Pearl Cat can react to typing and mouse-button presses in other applications. This is a separate opt-in permission on top of approval:

1. Approve and enable the package.
2. Turn on Allow keyboard and mouse activity in Settings → Plugins and apply.
3. Set up the matching Aqueous integration service, described in the Pearl repository.

What a plugin actually receives is deliberately minimal: a coalesced “something happened” count, at most ten callbacks per second. No keys, text, button identities, device or window identities or timestamps ever reach a plugin; held-key repeats, releases, pointer motion, scrolling and touch do not count at all. Activity suspends during Pearl-managed authentication, session lock and inactive sessions, and Settings and pearlctl plugins list report the current availability and its reason.

Note

Activity availability depends on the compositor integration being present and authorized. Without it, plugins keep working from local clicks and the Settings Preview action, and the page reports why activity is unavailable.

Command line

pearlctl plugins refresh
pearlctl plugins list
pearlctl plugins list --offset 4
pearlctl plugins inspect --path pearl.timer-c
pearlctl plugins enable --path pearl.timer-c --text PACKAGE_SHA256 --revision N
pearlctl plugins disable --path pearl.timer-c --revision N
pearlctl plugins reload --path pearl.timer-c

refresh returns a ticket immediately; in plugins list, wait for completed to reach requested and pending: false, then read the error code and package status. Enable and disable need the current preferences revision from pearlctl preferences status and the package’s SHA-256 fingerprint from inspect, and they are rejected while a Settings draft is retained or the revision is stale. Enabling a new fingerprint clears previously granted optional permissions; review and grant them in Settings. reload retries a running plugin; it does not rescan. Replace PACKAGE_SHA256 with the full fingerprint you reviewed and N with the current numeric revision. Enabling can start the plugin immediately; use Settings to review optional permissions.

The inventory is bounded: at most 32 discovered packages and eight enabled instances. List and inspect responses page four entries at a time through next_offset.