mirror of
https://github.com/vitorpamplona/amethyst.git
synced 2026-10-30 07:37:38 +00:00
Claude
cf89d1868f
A Linux desktop at 125% or 150% tells X11 apps through Xft.dpi, but AWT only takes whole scales there, so the app drew at 100%: sharp but too small. That is also what JetBrains suggests for blurry fractional scaling on Wayland (JBR-10582): XWayland with KDE's "legacy apps apply scaling themselves", which only works if the app scales itself. DesktopUiScale reads Xft.dpi (XSETTINGS, then the X resource database via JNA; AMETHYST_SCALE overrides) and AppWindow and the crash dialog raise Compose's density by what AWT left out. Measured on Xvfb at Xft.dpi 120: a 1-px checkerboard stays pure black and white at the right size. LocalDensity no longer equals AWT's scale there, so the two places that converted AWT coordinates with it (fullscreen overlay origin, gutter wheel redispatch) now read the component's own AWT scale. The default window size cap scales with it. Native Wayland, macOS and Windows are unchanged. JNA (LGPL-2.1+ or Apache-2.0, used under Apache-2.0) was already shipped through nestsClient; desktopApp now declares it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YFyERkpgRiWgXWyc5Jg7Xa
109 lines
7.7 KiB
Markdown
109 lines
7.7 KiB
Markdown
---
|
||
name: desktop-expert
|
||
description: Desktop JVM shim in desktopApp/: AmethystDesktop window, DesktopMenuBar, platform ports, OS keyring; :desktopApp:run, packaging. Use when touching desktopApp, or to run/screenshot the shared UI headless (tools/desktop-run, Xvfb) to verify a UI change. NOT for writing shared screens.
|
||
---
|
||
|
||
# Desktop (JVM shim)
|
||
|
||
`desktopApp` is a **shim**: it opens a window and renders the same `AmethystApp` Android renders.
|
||
Screens, the navigation shell (bottom bar / rail / drawer, chosen by `ScreenLayoutSpec`) and the
|
||
deck are shared UI in `commonsUI` — see AGENTS.md "Navigation Shell" and "Feature Workflow", and
|
||
`compose-expert`. Never add a desktop-only screen or a desktop-specific navigation layout.
|
||
Background: `commons/plans/2026-09-27-one-ui-android-desktop.md`,
|
||
`commons/plans/2026-10-09-legacy-desktop-retirement.md` (the legacy desktop app is gone).
|
||
|
||
## Where things live (`desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/`)
|
||
|
||
| File | Role |
|
||
|---|---|
|
||
| `app/AmethystDesktop.kt` | `main()`: macOS AWT properties, data dir, `DesktopAppModules`, the `Window`, the CompositionLocals (`LocalAppPlatform`, `LocalNotePlatform`, …) around `AmethystApp`. `--publish-scheduled` runs headless (OS timer publishing scheduled posts). |
|
||
| `app/DesktopAppModules.kt` | The desktop graph (Android's `AppModules` minus phone-only parts). |
|
||
| `app/DesktopAppRoot.kt` | `AppRoot` impl; `jvmDestinations`. |
|
||
| `app/DesktopAppPlatform.kt` | `AppPlatform` (commonsUI `ui/platform/`); unoverridden members keep the default, which hides the feature. |
|
||
| `app/DesktopNotePlatform.kt`, `DesktopRichTextPlatform.kt` | `NotePlatform`, `RichTextPlatform` (commonsUI). |
|
||
| `app/DesktopAccountViewModelHost.kt`, `DesktopLocalCacheHost.kt`, `DesktopAppServices.kt` | `AccountViewModelHost`, `LocalCacheHost`, `AppServices` (commons). |
|
||
| `app/DesktopMenuBar.kt` | `DesktopNavigator`, the `Command` enum, `DesktopMenuBar`, `handleShortcut`. |
|
||
| `app/Legacy*Import.kt` | One-time import of the retired legacy app's accounts, deck, feeds, privacy lock. |
|
||
| `platform/PlatformInfo.kt` | `PlatformInfo.current` / `host`, `isMacOS`, `isWindows`, `isLinux`, `isGnome`, `isKde`. |
|
||
| `platform/SavedWindowBounds.kt` | Window position/size persisted to `window-bounds.properties`. |
|
||
| `platform/WaylandDisplay.kt`, `platform/AppWindow.kt` | Native Wayland: `WLToolkit` picked in `main()` on a Wayland session (`AMETHYST_X11=1` opts out); `AppWindow` is Compose's `Window` elsewhere and a Swing-drawn frame there. Open new top-level windows with `AppWindow`, never `Window`/`ComposeDialog`. |
|
||
| `platform/DesktopUiScale.kt` | X11 at a fractional scale (`Xft.dpi` 120 = 125%, `AMETHYST_SCALE` by hand): AWT draws whole scales only, so `AppWindow` raises Compose's density by the rest. `LocalDensity` is then not AWT's scale: convert AWT window/event coordinates with `awtPixelScale(component)`, and size AWT windows in AWT units. |
|
||
| `account/`, `tor/`, `network/`, `service/`, `ui/media/` | Account storage, Tor, HTTP, scheduled posts, video/audio players. |
|
||
|
||
A new shared feature that needs a desktop behaviour = a member on one of the ports above
|
||
(default in the interface, override here), not a desktop branch in the shared screen.
|
||
|
||
## Shortcuts and menu bar
|
||
|
||
- One `Command` enum in `DesktopMenuBar.kt` drives both. `Command.shortcut` is Cmd+key on macOS,
|
||
Ctrl+key elsewhere (`isMac = PlatformInfo.host == Platform.MACOS`).
|
||
- macOS: the system `MenuBar` carries the shortcuts. Linux/Windows get **no** menu bar (Swing draws
|
||
it inside the window); shortcuts go through `handleShortcut` from the window's `onPreviewKeyEvent`.
|
||
- Deck commands are ignored unless `DeckCommandBus.active`; held chords are de-duplicated
|
||
(`AUTO_REPEAT_WINDOW_MS`).
|
||
- Menu labels are `Res.string.*` (commonsUI strings, per AGENTS.md "Strings").
|
||
|
||
## OS detection
|
||
|
||
`PlatformInfo.current` honours an override (`-Damethyst.platform=GNOME` or `AMETHYST_PLATFORM`) to
|
||
preview another OS's theming; `PlatformInfo.host` is the real OS — use it for anything that touches
|
||
the actual system (menu bar, Cmd key, shell-outs).
|
||
|
||
## Keys
|
||
|
||
Keys go to the OS keyring through `SecureKeyStorage`
|
||
(`commons/src/jvmMain/.../commons/keystorage/SecureKeyStorage.kt`, `java-keyring`). Without one they
|
||
go to a NIP-49 password file (`PasswordKeyFile`), and a login can opt out of keeping its key. The
|
||
status, prompts and Settings › Key storage are shared (`KeyStorageController`, provided by
|
||
`DesktopAppRoot.keyStorage`); see `commons/plans/2026-10-12-desktop-key-storage.md`.
|
||
|
||
The keyring breaks in release builds only, so test the packaged app: `Amethyst --keyring-self-test`
|
||
(CI runs it through `keyring-self-test.sh` in the repo's top-level scripts folder). ProGuard must keep jkeychain's native library and
|
||
dbus-java's ServiceLoader transport, and drop the signatures of jars it rewrites (hkdf):
|
||
`desktopApp/compose-rules.pro`, `verifyJkeychainNativeSurvivesProguard`,
|
||
`verifyDbusTransportSurvivesProguard`.
|
||
|
||
## Run and package
|
||
|
||
```bash
|
||
./gradlew :desktopApp:run # JDK 21 toolchain (jvmToolchain(21))
|
||
./gradlew :desktopApp:run -Damethyst.dataDir=/tmp/amy-test # separate profile; -Damethyst.debug=true for DEBUG logs
|
||
./gradlew :desktopApp:packageDmg # macOS; packageMsi (Windows), packageDeb / packageRpm (Linux)
|
||
```
|
||
|
||
- `mainClass = "com.vitorpamplona.amethyst.desktop.app.AmethystDesktopKt"`. Data lives in
|
||
`~/.amethyst/app` unless `amethyst.dataDir` is set.
|
||
- Packages land in `desktopApp/build/compose/binaries/main/` (release variants in `main-release/`).
|
||
- **Stop a running app before rebuilding shared modules.** A build rewrites the jars the running
|
||
`:desktopApp:run` JVM loaded and it crashes with `NoClassDefFoundError`. Relaunch it afterwards.
|
||
- Build fails? Check `java -version` (21+), then that `./gradlew :quartz:build` compiles.
|
||
|
||
## Verify a UI change by running it (headless too)
|
||
|
||
The window renders the shared UI, so this is how an agent checks a `commonsUI`/`commons` change for
|
||
real (AGENTS.md "Run the app before calling a UI change done"). `tools/desktop-run/` does it without
|
||
a display or a window manager: `run-headless.sh start` runs Xvfb + `:desktopApp:run` on a scratch
|
||
profile (`/tmp/amethyst-desktop-run/profile`), waits for the first paint and saves `shot.png`;
|
||
`Drive.java` (pure JDK `java.awt.Robot`) clicks, types, presses keys, scrolls and takes screenshots.
|
||
Read the screenshots with the image-reading tool. Details: `tools/desktop-run/README.md`.
|
||
|
||
- Log in with a public `npub` for a read-only session. A throwaway Sign Up account is only for flows
|
||
that must sign, and only when asked, because it publishes to real relays.
|
||
- The screen size picks the shell: `AMETHYST_SCREEN=480x900x24` gives the phone layout (bottom bar),
|
||
the default 1600x1000 gives the permanent drawer + docked notifications. Use a new
|
||
`AMETHYST_DISPLAY` per size.
|
||
- Linux packages bundle the JetBrains Runtime (build on `jbrsdk` 21, see BUILDING.md "Wayland and X11
|
||
on Linux"); `scripts/wayland-smoke-test.sh <launcher>` checks one on a sway with no Xwayland.
|
||
- Under Xvfb: no GL (the script sets `SKIKO_RENDER_API=SOFTWARE`), no keyring (password-file
|
||
fallback), no native video player ("Can't play this video"). Those are the environment, not your
|
||
change. `run-headless.sh logs` lists exceptions first.
|
||
- Never `pkill -f AmethystDesktopKt` from a tool shell: it matches the shell itself. Use `stop`.
|
||
|
||
For a check that must keep passing, write a Compose UI test (`createComposeRule()`, see
|
||
`desktopApp/src/jvmTest/.../desktop/ui/BlockInteractionsUiTest.kt`); CI runs them under
|
||
`xvfb-run --auto-servernum ./gradlew :desktopApp:test`.
|
||
|
||
Tests: `./gradlew :desktopApp:test` (a plain JVM module: sources sit in `src/jvmTest` but the task
|
||
is `test`); `desktopApp/src/jvmTest/.../desktop/testrelay/` has an in-process relay fixture
|
||
(`LaunchFixtureRelay`).
|