Architecture and State

Architecture and State

One-Bit Bureau is a native Omarchy Quattro plugin plus a matching native Omarchy theme and reversible companion assets.

Plugin identity

Field	Value
Plugin ID	io.github.regionallyfamous.one-bit-bureau
Plugin kinds	service, panel, bar-widget
Service entry point	components/desktop/Service.qml
Panel entry point	Experience.qml
Bar widget entry point	components/active-window/BarWidget.qml
Theme	themes/one-bit-bureau
Coordinator	one-bit-bureau

keepLoaded is enabled so the desktop, dock, Inspector, overview, and app-context surfaces keep their models and lifecycle state while panels open and close.

Runtime components

Desktop service

components/desktop/ indexes the configured XDG Desktop directory, classifies objects, provides safe local icon and preview sources, stores positions, owns bounded multi-selection, resolves semantic routes, opens selected objects through Gio, and gates untrusted launchers.

The QML layer rejects remote and inline icon schemes. desktop-operation is the structured mutation boundary for inspect, copy, move, Trash, status, and Undo. It enforces local paths, no-follow access, type/count/byte limits, collision-free destinations, atomic private journals, cross-filesystem rollback, and one bounded JSON receipt. Undo requires unchanged regular files proven with filesystem identity, metadata, ownership, and SHA-256.

The desktop exposes a read-only route-state IPC boundary for authoritative acceptance assertions:

regionallyfamous.one-bit-bureau.desktop

It reports whether a route is visible and valid plus its bounded reason and summary, and retains the most recently resolved route long enough for post-release assertions. It cannot initiate a filesystem action.

Shared Inspector

components/inspector/ is instantiated exactly once by Experience.qml. It normalizes bounded desktop, app, and window contexts and renders Identity, Facts, and Actions without executing payload text. Action IDs and stable object IDs are routed back to the owning desktop, dock, or overview controller, which re-resolves live state before acting.

Dock panel

components/dock/ combines pinned applications with running windows, persists order, owns one output, manages auto-hide, launches or deterministically focuses apps, exposes previews, and hosts the Window Ledger, icon manager, and optional app-switcher HUD.

WindowLedger.js normalizes live addresses, prunes stale most-recent-window state, and derives active plus current/other-workspace summaries. The explicit list uses validated addresses for Activate and Close; a stale known-running app never falls through to a duplicate launch. Focus requests use the current Hyprland Lua dispatcher first, keep the legacy dispatcher as a compatibility fallback, and restore the pointer through a dispatched cursor move.

Dock IPC target:

regionallyfamous.one-bit-bureau.dock

The public coordinator forwards one-bit-bureau dock ... to that target.

Window overview

components/overview/ builds a searchable contact sheet from live toplevel metadata, maintains separate active and keyboard-selected states, supports workspace filtering and multi-monitor modes, and exposes settings plus a configurable hot corner. It normalizes Quickshell's array-like runtime collections before applying bounded window and workspace limits. Its workspace board includes only existing ordinary numeric workspaces; move requests pass a normalized window address and destination to a shell-interpreted separated-argument helper, use the current Hyprland Lua move dispatcher with a legacy fallback, verify the resulting client state, and keep the overview open after completion.

Overview IPC target:

regionallyfamous.one-bit-bureau.overview

Active-application widget

components/active-window/ resolves the current application name, optional secondary window title, and app icon. It is registered as a native Omarchy bar widget in the left section after omarchy.menu.

User configuration

One-Bit Bureau keeps feature preferences together:

~/.config/omarchy/one-bit-bureau/
  desktop-icon-positions.json
  dock-icons.json
  dock-pinned.json
  dock-settings.json
  icons/

These files are user data and intentionally survive removal.

Inline bar-widget settings remain in Omarchy’s normal shell configuration rather than a parallel One-Bit preference system. That includes title visibility, icon sizing, saturation, maximum width, and reduced motion.

Installation ownership

The installation transaction records its owned values in:

~/.local/state/omarchy/plugins/io.github.regionallyfamous.one-bit-bureau/install-state.json

The record includes:

• Canonical plugin origin and commit
• Theme installation mode, source identity, and commit
• Hashes for the installed command, font tree, About branding, and screensaver branding
• Previous theme, bar position, and transparency
• Whether prior branding files existed
• Ownership flags for every installed component

Update and removal validate this record before mutation. scripts/one_bit_bureau_secure_io.py is the shared descriptor-relative boundary used by setup, update, removal, diagnostics, the coordinator, dock/desktop state transactions, and the optional GTK3 preview. Update consumes one bounded record snapshot and binds its final replacement to the snapshot’s SHA-256, preventing a later pathname reopen from silently changing the object that authorized the operation.

Theme ownership modes

Verified public releases use one owned theme link into the commit-pinned plugin checkout. This removes a second mutable Git fetch from the installation path and guarantees that the theme and plugin resolve to the same verified commit.

Older installations may still have a source ownership record created by One-Bit Bureau 1.2.0 or earlier. Update and removal retain compatibility with that recorded mode. Local development uses a copied theme and is deliberately separate from the public release contract.

Installed paths

~/.config/omarchy/plugins/io.github.regionallyfamous.one-bit-bureau/
~/.config/omarchy/themes/one-bit-bureau
~/.local/share/fonts/one-bit-bureau/
~/.config/omarchy/branding/about.txt
~/.config/omarchy/branding/screensaver.txt
~/.local/bin/one-bit-bureau

The theme path is an ownership-managed link for public installations. Fonts and the command are ordinary user files with recorded hashes.

Security boundaries

• No helper runs as root.
• Setup does not invoke sudo, pkexec, Plymouth, or initramfs commands.
• Public installation requires an immutable GitHub Release, verifies its published SHA-256 asset digest before extraction, and validates the bundled full commit before activation.
• The plugin runs with the current user’s shell privileges.
• Remote and inline desktop preview/icon URLs are rejected.
• Launcher trust is explicit and defaults to Cancel.
• State readers reject unsafe symlinks, FIFOs, malformed JSON, oversized inputs, and excessive records.
• Install, command, shell-state, and GTK transactions hold validated no-follow parent descriptors; validate opened owner, type, mode, link count, identity, and hash; use random O_EXCL temporary files; atomically replace descriptor-relative names; and fsync both files and directories.
• Ownership JSON is bounded by raw bytes and lexical nesting before parsing, then by depth, nodes, keys, and UTF-8 string bytes. GTK theme inspection is bounded by total bytes, entries, files, directories, and depth, with each pass using a fresh descriptor-relative enumeration handle.
• Helper processes use bounded deadlines and escalate cancellation when a child refuses to exit.
• The Trash child has its own timeout and Linux parent-death signal, so cancelling or unloading the QML-owned helper cannot orphan a mutating gio process.
• Filesystem receipts never claim Undo for copies, directories, launcher demotion, Trash, partial batches, changed destinations, or occupied original paths.
• The icon system is offline.
• Update refuses a changed origin, dirty checkout, mismatched ownership record, or plugin/theme commit split.
• Removal refuses to delete an unowned or modified component.

Stock Omarchy behavior

One-Bit Bureau does not replace the shell root. Disabling the plugin restores the stock shell without deleting user state. Global Alt+Tab and normal Super navigation remain Omarchy-owned.

Wayland does not provide a reliable bridge from the desktop's manual icon drag into the dock's separate layer-shell window. The plugin deliberately keeps native external file drops and same-window semantic routes, and does not claim internal desktop-to-dock dragging.

The project follows Omarchy’s documented theme, background, branding, font, top-bar, and navigation boundaries. The design contract is recorded in docs/DIRECTION.md.