135 lines
8.7 KiB
Markdown
135 lines
8.7 KiB
Markdown
# 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](https://github.com/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](https://github.com/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](https://github.com/end-4/dots-hyprland)) 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](https://github.com/mylinuxforwork/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](https://github.com/HyDE-Project/HyDE)) 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](https://github.com/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](https://github.com/AvengeMedia/DankMaterialShell)):
|
||
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.
|
||
|
||
**Omarchy** ([repo](https://github.com/basecamp/omarchy), MIT — DHH): the
|
||
crash-to-agent escalation ladder and the multi-agent usage collectors, both
|
||
taken as code, not just ideas, with attribution headers on every derived file.
|
||
Specifically: the command-as-notification-data hint (the shell runs the click,
|
||
so it survives shell restarts and never blocks the sender), the per-agent argv
|
||
launch table with the skill-path-as-fallback trick for harnesses without a
|
||
skill mechanism, the coredump PID+signal payload, and the Claude collector's
|
||
hard-won honesty — model-scoped limits, cached numbers that expire on window
|
||
rollover rather than age, waiting-vs-expired auth as distinct states, and
|
||
retry-on-transport-but-not-HTTP-error. The diagnose-crash skill's structure
|
||
("rule out OOM first", "never invent function names", "diagnosis reads; it
|
||
does not fix") was adapted rather than rewritten, because it was already
|
||
right. Their usage panel and menu system were not taken — Panama renders its
|
||
own surfaces in its own design language.
|
||
|
||
### 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.
|