spike(desktop): Phase 0 feasibility probes + findings
Adds the throwaway Phase-0 spike (Development Plan §6.3) that answers
whether Incido can become a Compose Multiplatform desktop app without
abandoning ObjectBox, its crypto layer, or its UI layer. All six
questions came back PASS; findings live in tools/DESKTOP_FEASIBILITY.md.
:spike:data-jvm ObjectBox kapt codegen + native runtime on a plain
JVM, DataStore Preferences without a Context, and
the app's own EncryptedKeyCodec round-tripping.
:spike:compose-jvm Compose Desktop rendering the app's real theme
layer + core:domain, plus jpackage packaging.
Additive only: nothing outside spike/ depends on these, and the Android
build is untouched (assembleDebug verified green).
This commit is contained in:
1 parent
f87ca17ded
commit
8b66e82acb
20 files changed
+1822
No files matched your search
@@ -0,0 +1,235 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user