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

14 KiB

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

./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).