Panama/docs/UPSTREAM-INSPIRATION.md

Upstream inspiration

Panama is its own desktop experience, but it should learn from strong open-source work without obscuring where an idea came from. This ledger records upstream projects that materially influence its architecture or interaction design.

Omarchy

• Project: basecamp/omarchy
• Reviewed revision: f32ebbdb730c4e8fe11e4046cef4267e466264ea
• License: MIT, copyright David Heinemeier Hansson
• Local reference at review time: /home/gib/Documents/Code/Projects/omarchy

Adopted ideas, rebuilt for Panama

• shell/plugins/osd/Osd.qml and OsdModel.js: inspired the separation between a pure presentation model and a single, click-through per-monitor OSD surface. Panama rebuilt the behavior around freedesktop symbolic icons, Tokyo Night Moon tokens, its Prism glass material, Hyprland's focused monitor, and the existing wpctl/brightnessctl/playerctl keybindings.
• test/shell.d/osd-test.sh and Omarchy's broader shell contract suite: reinforced Panama's use of fast model and integration contracts alongside live compositor verification.
• Omarchy's small shared visual primitives: reinforced the decision to maintain prism-gallery.qml, which renders Panama's production widgets and Theme tokens instead of duplicating mock-only controls.
• shell/plugins/menu/Menu.qml: inspired a searchable desktop-action inventory. Panama keeps Vicinae as its one launcher and exposes native script commands backed by a single panama-action dispatcher, rather than adding Omarchy's separate shell menu or plugin host.

No Omarchy user-facing layout or styling was transplanted. Panama keeps its GNOME-derived information architecture, Prism material, Tokyo Night Moon palette, app model, and established interaction choices.

Second round, 2026-08-22

A survey of omarchy, end-4/dots-hyprland, caelestia, DankMaterialShell, noctalia, HyDE, ML4W, JaKooLit and hyprdots, read against Panama's own feature inventory. This is the largest borrowing round the project has had, and what follows is what was taken, what was rebuilt rather than transplanted, and what was declined.

Omarchy (basecamp/omarchy, MIT, reviewed at f32ebbdb).

• bin/omarchy-migrate and migrations/: the idea that an installed machine needs a way to catch up, because installing only ever adds. Panama rebuilt it as bin/panama-migrate with the same shape -- commit-timestamp filenames so glob order is chronological, one marker file per migration written only on success -- and the same reasoning appears in the existing config/Migrations.qml, which already did this for the settings file. Panama's runner stops at the first failure rather than continuing, and root work goes through panama-sudo so the password prompt names the repair.
• bin/omarchy-launch-or-focus: focusing a window rather than opening a second one. Panama inverted the default after using it: the plain application keys keep opening a new window, and SUPER+ALT is the go-to chord. On a tiling desktop a second terminal beside the first is the normal case, not an edge one, and making that the awkward path was a worse trade than the parity.
• bin/omarchy-webapp-install: a site as an application. Rebuilt as bin/panama-webapp, following the desktop's own default browser rather than naming one, and refusing a browser that cannot do app mode instead of opening an ordinary window and pretending.
• bin/omarchy-hw-*: small exit-code hardware predicates. Rebuilt as one bin/panama-hw with subcommands, including reading sysfs vendor IDs rather than lspci, which wakes a runtime-suspended GPU.
• bin/omarchy-hyprland-monitor-clamshell: the definition that clamshell is a closed lid and an external monitor. Panama took the definition and rejected the mechanism: rather than a logind drop-in plus a watcher of its own, it holds a handle-lid-switch inhibitor, so a failure returns logind's default instead of leaving a lid that does nothing.
• manual/: user documentation as numbered prose chapters, and specifically a "coming from Mac or Windows" chapter. Panama's config/dot/quickshell/manual/ renders inside Settings rather than opening a browser.
• Nautilus context-menu extensions: rebuilt against Panama's existing panama-kdeconnect rather than adding a second way to talk to a phone.

end-4/dots-hyprland (repo) and omarchy: a keybind cheatsheet on one keypress, read from the live keymap rather than a written-down copy. Panama's version groups by categories the compositor config declares, written to a manifest at config load, because Hyprland reports Lua binds as __lua with a bytecode offset and nothing can ride along into hyprctl binds.

ML4W (dotfiles-welcome): a first-run welcome that teaches the handful of keys that matter and stays reachable afterwards. Panama's reads the chords from the live keymap so it cannot teach keys the machine does not have.

HyDE (wallbash templates) and omarchy's default/themed/: color values as data consumed by templates rather than restated per consumer. Panama took the principle and not the template engine: config/palette.json is now the single source for everything outside QML, which removed six hand-synced copies of the eight accents. A per-app template renderer was considered and deferred, because the concrete pain it would solve is gone and porting six working generators is risk without a waiting beneficiary.

caelestia (caelestia-dots/shell): lightweight system toasts as a category distinct from the OSD and the notification center. Panama already had this as StatusEvents, so what was taken was the observation that a charger belongs in it; the layer itself needed no work.

DankMaterialShell (repo): surfacing agent usage in the bar, and a plugin registry with a lockfile. The first shipped, as a bar widget with a switch of its own on Shell › Bar; the second remains deferred, see below.

Declined, and why

• Wallpaper-derived dynamic color (HyDE wallbash, matugen). The headline feature of this whole genre, and declined on identity: Tokyo Night Moon is a deliberate choice, and dynamic color is how rices end up looking like each other. Reconsider as one more theme profile, never as the default.
• A per-app template engine for theming. See above.
• Audio visualizers. A continuously repainting equalizer is exactly the GPU-pegging animation this project avoids on high-refresh displays.
• Theming applications by patching their internals (Spotify, Discord). Breaks on every application update; the maintenance is unbounded and falls on whoever is holding the desktop that day.
• A plugin host. Still premature, for the reason already recorded below. User hooks were the thirty-line version and shipped instead: panama-hook runs ~/.config/panama/hooks/<name> and its <name>.d/ directory for theme-set, post-upgrade and post-migrate.
• Package channels and pacman hooks. Arch-specific, and blocking dnf upgrade on a Fedora workstation would be hostile.

Candidates still under evaluation

• A plugin boundary for optional bar widgets and services once Panama has enough third-party modules to justify one.
• A small first-run health check for missing desktop dependencies and broken service integrations.

These are research directions, not commitments. They should only land when they improve the daily-driver experience without adding visible complexity or parallel configuration systems.