Phase 1 M2 task 4, desktop half (tools/DESKTOP_PHASE_PLAN.md §4). New
--backup-export-enc <path> + --backup-passphrase <pw> flags drive the
exact calls the RequirePassphrase/Passphrase dialogs make, headlessly.
Verified across two launches on fresh libraries:
run A: import plain(27) → reimport skipped=27 → exported-enc=27 magic ok
run B: preview encrypted=true → imported=27 → wrong-pw preview rejected
→ reimport imported=0 skipped=27
Gotcha found (and honoured): EncryptedBackupCodec zeroes the passphrase
CharArray in BOTH encrypt and decrypt — the array is single-use fuel.
The dialogs already comply (fresh toCharArray() per call); the scripted
block re-derives it via newPw() for the same reason.
Device half (4b: phone re-imports a desktop-made envelope + sees the
dedupe snackbar) follows on Waydroid with the M2 wrap-up.
23 KiB
Desktop feasibility spike (Phase 0) — findings
The forward plan — remaining Phase-1 milestones, invariants and traps — lives in
tools/DESKTOP_PHASE_PLAN.md, written as a cold-start handoff.
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, overflowDropdownMenu, a confirm dialog,SnackbarHost, editorOutlinedTextField, 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:
Dialogisandroidx.compose.ui.window.Dialog, not a material3 export (material3 shipsAlertDialog/BasicAlertDialog). Incido's dialogs useAlertDialog, so this only bites hand-rolled overlays.- CompositionLocals cannot be read inside
LaunchedEffect—LocalDensity.currenthad to be captured at composition time. Same rule applies on Android; the spike just happened to be the first place it was violated. VerticalDivider/HorizontalDividernaming 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"); thealias(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
MyObjectBoxinto the entity package (org.incido.data.entity), notorg.incido.data. - Resolved versions:
objectbox-java/kotlin/linux 4.0.3, runtime reports4.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 forObjectBoxKeyProvider(Android Keystore); the fix is aKeyProviderinterface 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_SECUREscreenshot blocking, and the Android Keystore itself. Desktop needs its own answers (keyring viasecret-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.
core:domainis already JVM-clean — convert it first (multiplatform, or keep itkotlin("jvm")and consume it from both targets). Zero code changes.- Keep ObjectBox entities + generated code in one JVM-consumable module and add
the spike-proven deps (
objectbox-java,objectbox-kotlin,objectbox-linux); Android keepsobjectbox-android. The model file is the shared contract — never regenerate UIDs. - Extract a
KeyProviderinterface soAesGcmFieldCipherbecomes portable: Android Keystore on one side, keyring/passphrase on the other. - Put
SettingsRepository's store construction behind an injectedDataStore<Preferences>factory (expect/actual if the code moves to common). - 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. - 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,Contexton Android, aFiledirectory on desktop. The modules are never on one classpath, which is also what keepsobjectbox-androidandobjectbox-java(sameio.objectbox.*classes) from colliding.ImageOrientationNormalizer— EXIF rotation needs a bitmap decoder; Android passesAndroidImageOrientationNormalizer(moved verbatim fromNoteRepositoryImpl), desktop passesNoOpuntil 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).
M2 task 1 — extract :core:backup: DONE. New plain-kotlin("jvm")
module holding BackupCodec.kt, EncryptedBackupCodec.kt and
EncryptedKeyCodec.kt (git mv — the Android diff is the three moves plus
one dependency line) and a new BackupBridge: the four BackupManager
operations re-expressed over InputStream/OutputStream instead of Uri.
The package name org.incido.compose.data.backup was kept on purpose, so no
consumer import changed; BackupManager stays in :composeApp as a thin
Uri → stream SAF shim with an identical public API (BackupPreview moved
to the bridge file, same package). Dedupe is task 3, desktop picker UI is
task 2 — deliberately not here.
Verification (all after the move, from a clean state):
./gradlew :core:backup:build BUILD SUCCESSFUL (serializers generated in the new module)
./gradlew assembleDebug BUILD SUCCESSFUL — Android unchanged
./gradlew :core:data-jvm:smoke RESULT: M1a PASS — the shared data layer runs on the JVM
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-desktop-smoke --self-test --exit-after 6"
SELFTEST wrote note id=1 → RENDER notes=1 selected=1
./gradlew :spike:data-jvm:run … recovery-key envelope (real codec) PASS — 84-byte envelope,
32-byte key round-tripped; wrong passphrase → AEADBadTagException
Housekeeping found on the way: :core:data-jvm:smoke does not clear
build/data-jvm-smoke/, and the script asserts on a fresh library — a
second consecutive run fails with "expected 1 note, got 2". Run it against
a deleted directory (worth fixing in a later milestone).
M2 — real-data round-trip probe + import-timestamp fix: DONE. New
./gradlew :core:data-jvm:backupSmoke --args="<export.incido.json> [libDir]"
feeds a real phone export (27 notes, 1 attachment, 14 orphan tags,
TASK_LIST+TEXT, colors, 1 favourite — file kept out of the repo, it's user
data) through the bridge on the JVM: preview → import into a fresh library
→ re-export and compare every field the format claims to preserve →
encrypted envelope export (wrong passphrase → null preview) → import of
the envelope into a second library with attachment-byte equality.
The probe immediately caught a pre-existing Android bug: upsert /
saveNoteWithHashtags overwrote createdAt AND updatedAt with "now"
for every insert, so even the phone's own import re-stamped the whole
library — silently breaking the (createdAt, updatedAt, sha256(content))
dedupe key M2 task 3 is built on. Fixed in the shared repository: a
caller-supplied non-zero timestamp is honoured, 0 still means "now"
(the Android editor already stamps both fields itself, verified at its two
Note(…) sites — so only the import path changes). Same for
addAttachment, which now takes createdAt: Long = 0L and
importSnapshot passes the phone's value through.
preview (plain, no passphrase) PASS — notes=27 attachments=1 app=0.4.0.0
import into fresh JVM library PASS — imported 27 notes, all readable back through the flow
re-export plain == original PASS — all 27 notes + 1 attachments identical
(content/times/fav/color/type/trash/draft/tags/bytes)
encrypted export + wrong-pw reject PASS — envelope=366739B, wrong passphrase → null
import encrypted into 2nd library PASS — attachment 260121B byte-identical to the phone's
RESULT: M2 round-trip PASS
Still open from the probe: importSnapshot never recreates orphaned
hashtag rows (the export carries them, the import ignores them) —
pre-existing on Android, noted for task 3. After the fix, full suite green:
assembleDebug, :core:data-jvm:smoke, desktop --self-test,
:spike:data-jvm:run — and the ObjectBox generator kept printing
ID model file unchanged.
M2 task 2 — desktop Import/Export UI: DONE. :desktopApp gained the
:core:backup dependency, a top-bar overflow menu (Import from file… /
Export plain / Export encrypted, BackupActions.kt) with Material3
passphrase + confirm dialogs, and AWT FileDialog (native GTK under
XWayland) driven on the IO dispatcher. Every flow ends in the same
BackupBridge calls the Android shim makes — the format is shared by
construction. The confirm dialog reuses BackupPreview counts and plainly
states that duplicates persist until task 3.
Scripted verification (--backup-import/--backup-export, the same bridge
calls as the menu, no dialog clicking):
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-m2-import4 --backup-import <real phone export> --backup-export /tmp/m2t4-exp.json --exit-after 8"
BACKUP preview notes=27 attachments=1 app=0.4.0.0
BACKUP imported=27 (same calls as the Import… menu)
RENDER notes=27 selected=1
BACKUP exported=27 notes to /tmp/m2t4-exp.json → exits cleanly
:core:data-jvm:backupSmoke on the DESKTOP-written file: all PASS
python cross-check phone file vs desktop export: notes (createdAt,
updatedAt, content) identical = True; attachment Base64 identical = True
That closes the phone → desktop → phone half of task 4 for plain format: byte-identical notes + attachment through the real app. Remaining task 4 items: encrypted file in each direction via the UI, and the phone-side re-import check on a device.
One anomaly worth recording: the very first scripted run hung post-export
(no thread dump obtainable; ~0.8% CPU, idle). Three subsequent identical
runs exited in 10s; the classic --self-test --exit-after path was also
re-verified green. Unreproduced — keep an eye on it during M5 (the trap
list already has an exit-time AWT/exitProcess quirk).
Full suite green after the change: assembleDebug, :core:data-jvm:smoke,
backupSmoke, :desktopApp:run --self-test.
M2 task 3 — import dedupe: DONE. BackupBridge.import now skips notes
whose (createdAt, updatedAt, sha256(content)) key already exists in the
library (default ON, skipExisting = false overrides), and returns
ImportSummary(imported, skipped) instead of a bare count. The existing
keys are snapshotted BEFORE the import, so two genuinely identical notes
inside one file still import into a fresh library — only a second import
of the same file adds nothing (matches the §4 wording exactly). Keys
include trashed notes, so restoring around the trash can't duplicate.
BackupManager.import (Android shim) passes the flag through and returns
the summary; SettingsViewModel's snackbar gained the skip count (one
line — the screen layouts are untouched). The desktop confirm dialog
replaced its "duplicates persist" warning with a working
"Skip notes that are already here" checkbox (default ON); the export
format did not change (formatVersion stays 1).
backupSmoke new step: re-import skipped=27; override added 27 (store=54) PASS
:desktopApp:run --backup-import <real export> --backup-export … --exit-after 8
BACKUP imported=27 skipped=0 → exported=27 → reimport imported=0 skipped=27
Known limitation (by design, per plan): attachments are not part of the key — two notes with identical text AND timestamps but different attachments dedupe as one. Phone side: second import now says "Imported 0 note(s), skipped 27 already imported." — device smoke still pending with the rest of task 4.
Full suite green: backupSmoke (9 steps incl. dedupe), assembleDebug,
:core:data-jvm:smoke, scripted desktop run (clean exit),
:desktopApp:run --self-test.
M2 task 4 (desktop leg) — encrypted round-trip via the app: DONE.
New scripted flags --backup-export-enc <path> + --backup-passphrase <pw> drive the passphrase dialogs' exact call chain headlessly:
exportEncrypted writes a real ICDBKP1 envelope, and importing it back
exercises preview(stream, pw) → import(stream, pw) → wrong-passphrase
preview → deduped re-import, in fresh libraries across two launches:
run A: plain import 27 → reimport skipped=27 → exported-enc=27 (magic=ICDBKP1 ok)
run B: preview encrypted=true → imported=27 → wrong-pw preview=null (rejected)
→ reimport imported=0 skipped=27
Caught while writing it: EncryptedBackupCodec zeroes the passphrase
CharArray it consumes — both in encrypt AND decrypt — so every
call needs a fresh array. The UI already complies (dialogs re-derive
toCharArray() per call); the scripted block initially reused one array
and died on the second decrypt with AEADBadTagException. Worth
remembering for the phone device pass and any future caller: treat the
passphrase array as single-use fuel. The envelope desktop produces is
byte-format-identical to the phone's because both sides now compile the
same :core:backup codec — the remaining proof for task 4 is the
on-device leg (Waydroid: phone re-imports a desktop-made encrypted file
- dedupe snackbar), tracked as M2 task 4b.