Files
Incido/tools/DESKTOP_FEASIBILITY.md
T
Incido Developer 5f45b0921b feat(phase-1/m1b): :desktopApp — desktop shell over the real repository
Phase 1 milestone M1b: a Compose Multiplatform window driven by the same
NoteRepositoryImpl the Android app uses, over its own ObjectBox library.

  DesktopContainer  mirrors AppContainer's construction order (store,
                    CipherHolder, repository). Owns its library at
                    $XDG_DATA_HOME/incido — a separate library per machine,
                    since ObjectBox is single-writer; the backup file (M2)
                    is the only bridge to the phone. --data-dir opens
                    another library, e.g. one pulled off a phone.
  Main.kt           two panes, save-as-you-type with a 400ms debounce,
                    favourite toggle. Material 3 defaults on purpose: the
                    app's theme and screens arrive with the M4 composeApp
                    conversion, which deletes this stand-in.

Verified headlessly (--self-test drives the same repository calls the "+"
button and the star make, --exit-after auto-closes), against a library
previously written by :core:data-jvm:smoke — i.e. a different module's
generated MyObjectBox, same schema:

  RENDER notes=0 selected=null    first frame (collectAsState initial value)
  RENDER notes=1 selected=1       ObjectBox flow delivered
  SELFTEST wrote note id=2        write path through the UI's own calls
  RENDER notes=2 selected=2       and it came back through the flow
  reopen -> RENDER notes=2        persisted

Gotcha recorded in the findings doc: the first composition always sees the
empty initial value of collectAsState, so anything asserting on note counts
must watch the flow rather than the first frame.

Still synthetic: theme + screens. Not wired yet: settings, encryption (M3),
backup bridge (M2), packaging (M5). assembleDebug verified green.
2026-10-05 18:28:24 +13:00

266 lines
14 KiB
Markdown

# Desktop feasibility spike (Phase 0) — findings
Branch `spike/desktop-feasibility`. Throwaway code lives in `spike/` and is
**not** wired into the Android build: `settings.gradle.kts` only gained two
`include()` lines and `gradle/libs.versions.toml` four entries. Nothing under
`app/`, `core/` or `composeApp/` was touched.
Question asked: can Incido become a Compose Multiplatform desktop app without
abandoning ObjectBox, its encryption layer, or its UI layer?
## Verdict
| # | Question | Verdict | Evidence |
|---|---|---|---|
| Q1 | Compose Multiplatform window builds + renders on KDE/Wayland | **PASS** | `:spike:compose-jvm:run` opened a window; `WINDOW-READY density=1.0` printed from the first composition |
| Q2 | ObjectBox: kapt codegen + native runtime on plain JVM, reusing the existing model file | **PASS** | `build BoxStore (codegen + native) PASS`; ID model file unchanged across modules |
| Q3 | Does the app's own crypto format survive on the JVM (key envelope interop) | **PASS** | `EncryptedKeyCodec.kt` copied verbatim: 32-byte key → 84-byte envelope → same key; wrong passphrase → `AEADBadTagException` |
| Q4 | Theme layer + `core:domain` compile and drive real Material3 UI on JVM | **PASS** | `Color.kt`/`Type.kt`/`NoteColors.kt` copied verbatim; only 2 Android-only lines removed from `Theme.kt` |
| Q5 | Platform layer: settings store, clipboard, image decode without Android | **PASS with 3 API deltas** | DataStore writes/reads 3 keys with no `Context`; Compose clipboard round-trip PASS |
| Q6 | jpackage Linux distribution, native lib bundled and loadable | **PASS** | 168 MB app-image; `SPIKE-DB PASS — BoxStore built inside the image` |
**Bottom line: the conversion is feasible.** No blocker found. Phase 1 can be a
port, not a rewrite — the data layer, crypto, domain, theme and Material3 UI all
work as-is on the JVM.
## Q1/Q4 — Compose Desktop UI
`:spike:compose-jvm` reproduces the surface set Incido actually uses: `Scaffold`
+ top bar, `NavigationRail`, note-card list with colour stripe and title/body
split, hashtag chips, favourite toggles, colour-filter chip strip, overflow
`DropdownMenu`, a confirm dialog, `SnackbarHost`, editor `OutlinedTextField`, and
the wide-window two-pane layout.
Run log (KDE Plasma, Wayland session, XWayland AWT):
```
AWT toolkit : sun.awt.X11.XToolkit
Skiko : Library resolved
WINDOW-READY density=1.0 notes=6 — first composition succeeded
clipboard : PASS (read back: incido-spike-clipboard)
```
No GL workarounds were needed (`-Dskiko.renderingApi=software` unused). Density
was 1.0 under XWayland — HiDPI scaling under native Wayland is untested and
should be checked in Phase 1 (§6 risk list).
Three real API deltas found while porting the UI, all mechanical:
1. `Dialog` is `androidx.compose.ui.window.Dialog`, not a material3 export
(material3 ships `AlertDialog`/`BasicAlertDialog`). Incido's dialogs use
`AlertDialog`, so this only bites hand-rolled overlays.
2. CompositionLocals cannot be read inside `LaunchedEffect` — `LocalDensity.current`
had to be captured at composition time. Same rule applies on Android; the
spike just happened to be the first place it was violated.
3. `VerticalDivider`/`HorizontalDivider` naming differs between the versions the
app and the spike resolve — a rename, not a redesign.
## Q2 — ObjectBox on the JVM
`spike/data-jvm` applies `org.jetbrains.kotlin.kapt`, points
`objectbox-plugin.json`-equivalent config at a **copy** of the app's
`objectbox-models/default.json`, and generates against the real entities
(`NoteEntity`, `HashtagEntity`, `AttachmentEntity`, `NoteCrossRefEntity`).
```
build BoxStore (codegen + native) PASS — native lib loaded
put NoteEntity (plaintext row) PASS — id=1
put NoteEntity (cipherVersion=1) PASS — id=2
blob round-trip integrity PASS — 4096 bytes identical
close + reopen same directory PASS — notes=2 hashtags=1
```
The generator printed **"ID model file unchanged"**, so generating in a second
module does not churn UIDs — the property that makes a shared-source Phase 1
(option B, sibling modules over a common `kotlin()` source set) safe. A desktop
build can open the same `.objectbox` file the Android app writes.
Gotchas recorded for Phase 1:
* Apply kapt with `apply(plugin = "org.jetbrains.kotlin.kapt")`; the
`alias(libs.plugins.kotlinKapt)` form fails with "already on classpath with
unknown version".
* kapt logs `W: Kapt currently doesn't support language version 2.0+` and falls
back to 1.9 for the generated code. Harmless, but expect it.
* The generator emits `MyObjectBox` into the **entity package**
(`org.incido.data.entity`), not `org.incido.data`.
* Resolved versions: `objectbox-java/kotlin/linux 4.0.3`, runtime reports
`4.0.2-2024-10-15`. `hasEncryption()` is **not** present in the JVM build —
ObjectBox encryption is an Android/extra-tier feature, so Incido's
app-level field encryption (`AesGcmFieldCipher`) is the only cipher, which is
exactly what we want anyway.
## Q3/Q5b — Crypto portability
`EncryptedKeyCodec.kt` was copied in **unmodified** (it imports only
`javax.crypto` + `java.security`) and exercised end-to-end:
```
recovery-key envelope (real codec) PASS — envelope=84 bytes, 32-byte key round-tripped
wrong passphrase is rejected PASS — rejected with AEADBadTagException
AES-256-GCM field cipher layout PASS — 4KB ok; 500 encrypts in 81 ms
PBKDF2 200k cost (per unlock) PASS — samples=[53, 56] ms per unlock on this CPU
```
Consequences for Phase 1:
* A recovery key exported from the phone opens encrypted notes on desktop with
**zero format changes** — same magic header, same PBKDF2 parameters, same
envelope. Backup/restore interop between platforms comes for free.
* `AesGcmFieldCipher`'s blob layout (`nonce(12) | ciphertext | tag`) was
mirrored and round-tripped. The class is not portable only because it reaches
for `ObjectBoxKeyProvider` (Android Keystore); the fix is a `KeyProvider`
interface with a JVM implementation, not a re-crypto.
* PBKDF2 with 200k iterations costs **~55 ms** on desktop versus roughly two
seconds on the phone. A passphrase-derived desktop master key (unlock at
launch) is viable without the async gymnastics the Android side needs.
* Not portable: BiometricPrompt, `FLAG_SECURE` screenshot blocking, and the
Android Keystore itself. Desktop needs its own answers (keyring via
`secret-service`, or a passphrase), and "block screenshots" has no equivalent.
## Q5a — Settings without a Context
```
data dir — would be /home/nick/.local/share/incido
DataStore prefs (no Context) PASS — 3 keys, file=incido_settings.preferences_pb (73 bytes)
```
API delta worth knowing before Phase 1: the multiplatform artifact
`androidx.datastore:datastore-preferences-core` has **no**
`preferencesDataStore(name = …)` extension and **no** public
`PreferenceSerializer`. The JVM entry point is
`PreferenceDataStoreFactory.create(corruptionHandler, produceFile = { File })`
(plus a `createWithPath` overload taking an `okio.Path`), and the corruption
handler lives in `androidx.datastore.core.handlers`. Keys and the
`.preferences_pb` format are identical to Android, so `SettingsRepository` needs
only its store-construction line changed — the `Preferences.Key` definitions and
all read/write logic port verbatim.
Clipboard: Compose's `LocalClipboardManager` round-tripped (write → read →
compare) on desktop, so "copy to clipboard" needs no expect/actual. It is
deprecated in this Compose version in favour of `LocalClipboard` + `ClipEntry`;
that migration is the same on both platforms.
Image decode: the spike decodes attachment bytes via
`org.jetbrains.skia.Image.makeFromEncoded(bytes).toComposeImageBitmap()` — the
desktop replacement for `BitmapFactory.decodeByteArray`. Compiling code path;
runtime decode only runs when `--image <file>` is passed.
## Q6 — Packaging
```
./gradlew :spike:compose-jvm:createDistributable → 168 MB app-image
SPIKE-DB PASS — BoxStore built inside the image, notes=0
```
`jpackage` built a self-contained Linux app-image (bundled jlink runtime) with no
extra host tooling — no FUSE, no `rpmbuild`, no Docker. `objectbox-linux` rides
along as a jar carrying `native/libobjectbox-jni-linux-x64.so` (2.5 MB), and
ObjectBox self-extracts it at runtime **from inside the image**, which was the
specific thing at risk. `packageDistributionForCurrentOS` (deb/rpm) additionally
needs `rpmbuild`/`dpkg` and still cannot cross-compile — per-platform runners
(GitHub Actions matrix), not one build host.
Noise worth recording: the launcher prints `pure virtual method called` /
`terminate called without an active exception` on stderr when the app calls
`exitProcess` while AWT/GTK is tearing down. Exit code is 0 and all output is
complete; a real app should close the window and let the JVM exit naturally.
## Phase 1 recommendation
Confirmed shape: **sibling JVM modules sharing sources**, not one KMP module per
layer.
1. `core:domain` is already JVM-clean — convert it first (multiplatform, or keep
it `kotlin("jvm")` and consume it from both targets). Zero code changes.
2. Keep ObjectBox entities + generated code in one JVM-consumable module and add
the spike-proven deps (`objectbox-java`, `objectbox-kotlin`,
`objectbox-linux`); Android keeps `objectbox-android`. The model file is the
shared contract — never regenerate UIDs.
3. Extract a `KeyProvider` interface so `AesGcmFieldCipher` becomes portable:
Android Keystore on one side, keyring/passphrase on the other.
4. Put `SettingsRepository`'s store construction behind an injected
`DataStore<Preferences>` factory (expect/actual if the code moves to common).
5. UI: budget ~15 files of real `android.*` coupling (context/resources,
`Build.VERSION`, BiometricPrompt, `FLAG_SECURE`, `LocalClipboardManager`) plus
window management — multi-window, tray, shortcuts — which has no Android
analogue and is the largest genuinely new UI work.
6. Compose Multiplatform 1.7.3 works but is behind. Decide in Phase 1 whether to
move the app to 1.8.x first; the spike proves feasibility on the pinned
version, not that 1.7.3 is the right target.
Still unproven after this spike: native-Wayland rendering and HiDPI (only
XWayland was exercised), macOS/Windows targets (nothing here is platform
specific except jpackage's no-cross-compile rule), perf on a multi-thousand-note
library, and the desktop security story (no Keystore, no biometrics, no
screenshot blocking).
## Re-running the spike
```bash
./gradlew :spike:data-jvm:run --args="/tmp/incido-spike-db" # S1 + S4 (Q2, Q3, Q5a/b)
./gradlew :spike:compose-jvm:run --args="--exit-after 6" # S2 (Q1, Q4, clipboard)
./gradlew :spike:compose-jvm:run --args="--image /path/x.png" # attachment decode
./gradlew :spike:compose-jvm:createDistributable # S5 (Q6)
spike/compose-jvm/build/compose/binaries/main/app/incido-spike/bin/incido-spike \
--probe-db --exit-after 4 # ObjectBox inside the image
```
`spike/` is meant to be deleted once Phase 1 lands; keep this file.
## Phase 1 status (same branch)
**M1a — platform-neutral data layer: DONE.** `:core:data` now splits its
sources: `src/main/kotlin` is platform-neutral and is compiled by BOTH
`:core:data` (Android) and the new `:core:data-jvm` (desktop); Android-only
implementations live in `src/androidMain/kotlin`. Two seams were needed, both
found by this spike:
* `ObjectBoxStore` — same FQN in both modules, `Context` on Android, a
`File` directory on desktop. The modules are never on one classpath, which is
also what keeps `objectbox-android` and `objectbox-java` (same
`io.objectbox.*` classes) from colliding.
* `ImageOrientationNormalizer` — EXIF rotation needs a bitmap decoder; Android
passes `AndroidImageOrientationNormalizer` (moved verbatim from
`NoteRepositoryImpl`), desktop passes `NoOp` until M4 grows a JVM decoder.
`./gradlew :core:data-jvm:smoke` output: the real `NoteRepositoryImpl`
(save + hashtags + attachment round-trip + close/reopen) **PASS** on the JVM,
with the generator reporting `ID model file unchanged` — confirming the two
modules generate from one schema. `assembleDebug` stays green.
Also fixed while here: `.gitignore` had `**/objectbox-models/`, which meant the
schema contract was **not in version control** — a fresh clone regenerated
UIDs. `default.json` is now tracked (everything else in that directory stays
ignored). This matters more now that two modules generate against it.
**M1b — desktop shell over the real repository: DONE.** New `:desktopApp`
(Compose Multiplatform, `compose.desktop` DSL, no explicit `application`
plugin — see the spike finding). `DesktopContainer` mirrors Android's
`AppContainer` construction order and owns its own library at
`$XDG_DATA_HOME/incido`; `--data-dir` opens any other library.
Verified headlessly (`--self-test` drives the same repository calls the "+"
button and the star make, `--exit-after` auto-closes):
```
library : /tmp/incido-desktop-smoke # written by :core:data-jvm:smoke
RENDER notes=0 selected=null # first frame (collectAsState initial)
RENDER notes=1 selected=1 # ObjectBox flow delivered
SELFTEST wrote note id=2 # write path through the UI's calls
RENDER notes=2 selected=2 # and it came back through the flow
--- reopen ---
RENDER notes=2 selected=2 # persisted
```
Two things that run proves beyond what the spike did: the desktop build reads a
library written by a *different* module's generated `MyObjectBox` (one schema,
two codegens), and ObjectBox's reactive flow feeds a Compose Desktop
composition. Note the first frame is always the empty initial value — anything
asserting on note counts must wait for the flow, not the first composition.
Still synthetic in this build: the theme (Material 3 defaults, not Incido's)
and the screens (this is a two-pane stand-in). Both are replaced by the M4
`composeApp` commonMain conversion. Not yet wired: settings, encryption (M3),
backups (M2), packaging (M5).