Files

T

Gabriel Brown 41dd91eb75 Write down where all of this came from

Section G, the closeout.

UPSTREAM-INSPIRATION gains the second and largest borrowing round: what
was taken from omarchy, end-4, caelestia, ML4W and HyDE, what was
rebuilt rather than transplanted, and -- the part that matters more --
what was declined and why. Wallpaper-derived colour is declined on
identity, because dynamic colour is how rices end up looking like each
other. Audio visualisers are declined because a continuously repainting
equaliser is the GPU-pegging animation this project avoids. Patching
application internals to theme them is declined because the maintenance
is unbounded and lands on whoever is holding the desktop that day.

DESKTOP-PARITY gains a Portable machines section, which it has never
had, because until yesterday Panama was a desktop configuration in the
code as well as on the machine. Nine rows, one of them honest about not
having run on hardware with a lid. The remaining-gaps list gains the
four things now known to be missing rather than the one.

The README stops describing a desktop from before yesterday: migrations
in the install flow, the welcome and cheatsheet and manual, and laptops
working with every surface hiding itself where the hardware is absent.

The plan records its own outcome per section, including the two places
the work departed from it: D2's template renderer deferred once D1
removed the duplication it existed to fix, and E1 inverted after using
it for an afternoon.

2026-08-22 07:48:24 -04:00

7.5 KiB

Raw Blame History

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/: colour 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 centre. 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 is planned; the second remains deferred, see below.

Declined, and why

Wallpaper-derived dynamic colour (HyDE wallbash, matugen). The headline feature of this whole genre, and declined on identity: Tokyo Night Moon is a deliberate choice, and dynamic colour 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 visualisers. A continuously repainting equaliser 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 are the thirty-line version and are the next thing to build.
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.

7.5 KiB Raw Blame History