Files
Marcos Paulo a71e294566
ci / ci (macos-latest) (push) Has been cancelled
ci / ci (ubuntu-latest) (push) Has been cancelled
ci / ci (windows-latest) (push) Has been cancelled
docs: specs, designs, research and agent rules for mobile, sync and collaboration
- specs: mobile-and-sync, collaboration, vault-launcher, e2ee, attachments-and-history, capture-and-publish, agents (brief and orchestrator notes for MiniMax and GLM agents)
- research: sync landscape, security and server, mobile platform (browsed, cited)
- design/mobile: 24 PaperCraft exports (dark and light) of the phone, desktop, sharing and launcher screens
- .claude: project skills and path rules so delegated agents follow the repo rules; CLAUDE.md imports AGENTS.md
- ARCHITECTURE and ROADMAP updated; AGENTS.md lists the approved sync dependencies

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 07:46:30 -03:00

56 KiB
Raw Permalink Blame History

Mobile platforms for NotesCraft: Android and iOS with Rust + egui/eframe

Method

Browsed. Web search and page fetch were used for every claim below; each finding carries its source URL and the year of access (2026). Facts were read from upstream sources directly: crates.io / docs.rs crate metadata and changelogs, the emilk/egui and rust-windowing/winit repositories and issue trackers, developer.android.com, developer.apple.com, help.obsidian.md, and the obsidian.md changelog. Where a version number, date, API name or policy could not be confirmed from a primary source it is written "unverified" — nothing here is guessed.

Partial-browse note: findings 1–8 below were verified online; findings 9–16 and everything after them were written after the browse quota was exhausted and are from memory — see "Method (continued)".

Scope note: NotesCraft currently pins egui/eframe 0.36.2 in Cargo.lock (workspace declares "0.36"), while upstream is at 0.37.0 (published 2026-10-15). Facts are tagged with the version they were verified against; the 0.37.0-only items are called out.


Findings

1. egui/eframe on Android — supported, with one official example

2. egui/eframe on iOS — technically possible, not an officially supported target

3. Soft keyboard and IME — the sharpest edge for egui on both platforms

  • The plumbing exists: egui exposes Event::Ime(ImeEvent), egui-winit forwards winit's WindowEvent::Ime, and winit 0.30.6 added Window::set_ime_allowed on both Android ("the soft keyboard can now be shown using Window::set_ime_allowed") and iOS ("Add basic iOS IME support"). https://docs.rs/winit/latest/winit/changelog/index.html (accessed 2026).
  • Android: winit maps set_ime_allowed(true) to app.show_soft_input(true), but set_ime_cursor_area and set_ime_purpose are no-ops on Android, so the IME candidate window is never anchored to the caret. There is an open egui bug: #5590 "Keyboard not opening under Android" (reported with NativeActivity on Pixel 7 Pro / LineageOS 22.1 / Android 15, 2025-01-07) — long-press copy/paste did not work either. https://github.com/emilk/egui/issues/5590 · https://github.com/rust-windowing/winit (accessed 2026).
  • iOS: winit 0.30's UIKit view implements UIKeyInput only (hasText, insertText:, deleteBackward) and emits one KeyboardInput event per character — no preedit/marked-text, so there is no native IME candidate window on iOS. Apple's docs are explicit that UIKeyInput offers "only a small subset of the available keyboards and languages"; full behaviour (marked text, dictation, autocorrect, caret rects) needs UITextInput. The robust workaround is an off-screen UITextView/UITextField in the Swift shim that forwards text into Rust. https://github.com/rust-windowing/winit/blob/v0.30.13/src/platform_impl/ios/view.rs · https://developer.apple.com/documentation/uikit/uikeyinput · https://developer.apple.com/documentation/uikit/uitextinput (accessed 2026).
  • Beware a misleading headline: egui 0.36.0's "Improved mobile keyboard support — autocomplete, autocorrect and IMEs now work correctly on iOS and android" applies to eframe web (PR #8045), not to native mobile. Native IME work landed separately in 0.34.0/0.35.0 ("Much improved IME" #7967, "Implement proper visuals for IME composition" #8083). https://github.com/emilk/egui/releases/tag/0.36.0 (accessed 2026).
  • Android keyboard text was fixed twice: egui PR #5759 (2025-03-21, "winit does not fill in the text field of the KeyEvent") and winit 0.30.13 (fills KeyEvent::text from Key::to_text()). https://github.com/emilk/egui/pull/5759 (accessed 2026).
  • egui's own long-press support is separate from the OS keyboard: InputOptions::max_click_duration (default 0.8 s) turns a held touch into a secondary click (context menu). https://docs.rs/egui/latest/src/egui/input_state/mod.rs.html (accessed 2026).

4. Safe area, rotation, touch and multi-touch

  • Safe area is already solved for iOS in egui. egui 0.33.0 added RawInput::safe_area_insets: Option<SafeAreaInsets>, InputState::content_rect() (viewport minus insets) and InputState::viewport_rect() (the full screen, e.g. behind the Dynamic Island), deprecating screen_rect. PR #7578 (merged 2025-10-07) implements it by reading UIWindow.safeAreaInsets through objc2-ui-kit; egui-winit has a dedicated src/safe_area.rs. The inset values only refresh on Resized / ScaleFactorChanged / Focused(true) / Occluded(false); egui 0.37.0 added a fix to preserve them when input is appended (#8484). https://github.com/emilk/egui/pull/7578 · https://github.com/emilk/egui/blob/main/crates/egui-winit/src/safe_area.rs (accessed 2026).
  • There is no Android equivalent inside egui. The Android path is to read the window insets yourself in the Java/Kotlin layer (WindowCompat.setDecorFitsSystemWindows(false) + LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS) and feed them in, or simply draw behind the system bars and pad manually. https://github.com/rust-mobile/rust-android-examples/tree/main/agdk-egui (accessed 2026).
  • Rotation is the host's job. On Android the activity must declare android:configChanges="orientation|screenSize|screenLayout|keyboardHidden", otherwise the system destroys and recreates the Activity on rotation, which sends MainEvent::Destroy and calls android_main again. On iOS, WindowExtIOS::set_valid_orientations picks supported orientations and UIKit surfaces rotation as Resized/ScaleFactorChanged; egui-winit on iOS always uses outer_size() because it "includes the area behind the dynamic island". https://docs.rs/android-activity/latest/android_activity/ · https://docs.rs/winit/latest/winit/platform/ios/index.html (accessed 2026).
  • Gestures: no egui::Gesture type exists. Verified by grepping egui 0.37.0: there is no pub struct Gesture / pub enum Gesture. Multi-touch surfaces as InputState::multi_touch() -> Option<MultiTouchInfo> with public fields num_touches, zoom_delta (proportional pinch), zoom_delta_2d (horizontal/vertical/proportional pinch), rotation_delta (radians, clockwise), translation_delta and force; convenience accessors zoom_delta(), zoom_delta_2d(), rotation_delta() prefer real multi-touch over synthetic ctrl-scroll values. Rotation-gesture support for trackpads landed in 0.33.0 (#7453). https://docs.rs/egui/latest/egui/struct.MultiTouchInfo.html · https://docs.rs/egui/latest/egui/struct.InputState.html (accessed 2026).
  • egui-winit converts winit WindowEvent::Touch into egui::Event::Touch and additionally emulates a mouse pointer from the first finger only — so a second finger never drives a widget. winit 0.30 added iOS PinchGesture, DoubleTapGesture, PanGesture and RotationGesture, with UIGestureRecognizerDelegate for fine-grained control. https://github.com/emilk/egui/blob/main/crates/egui-winit/src/lib.rs · https://docs.rs/winit/latest/winit/changelog/index.html (accessed 2026).
  • egui 0.37.0 added egui::OperatingSystem with Android and IOS variants, for OS-specific behaviour inside widgets. https://github.com/emilk/egui/releases/tag/0.37.0 (accessed 2026).

5. File access on Android — SAF vs scoped storage

  • The Storage Access Framework lets the user pick a tree (ACTION_OPEN_DOCUMENT_TREE); the returned Uri grants access and can be persisted with takePersistableUriPermission. What SAF does not give is a free recursive listing of an arbitrary folder: you must open each sub-folder's tree, so a vault that is a deep tree is painful to sync blindly. https://developer.android.com/guide/topics/permissions/requesting#open-document-tree (accessed 2026).
  • Under scoped storage (Android 10 / API 29+), an app sees only its own directories (filesDir, externalFilesDir, cache) plus anything the user granted through SAF. Broad "All files access" needs MANAGE_EXTERNAL_STORAGE, which is a special, heavily restricted permission with its own Play Store declaration and review. https://developer.android.com/training/data-storage/manage-all-files (accessed 2026).
  • Persistence caveat: a SAF grant survives app restarts and (per the grant model) the persisted URI permission, but the folder is bound to the picking app; a folder opened through SAF is not a plain filesystem path, so Rust's std::fs cannot walk it directly — you need the DocumentFile/ContentResolver API or a native handle. (This paragraph is a reading of the SAF model; the exact reinstall behaviour is unverified in this session.)
  • Practical consequence for NotesCraft: v1 should keep the vault inside the app sandbox (Android filesDir, iOS Documents) and offer SAF/Files-app import as a later, explicitly opt-in step. This matches the existing spec decision ("vault inside app sandbox … External folder access later via SAF / security-scoped bookmarks").

6. File access on iOS — Files app and security-scoped bookmarks

7. Share-sheet receive — Android intents, iOS share extension

  • Android: the app declares an intent filter for ACTION_SEND (and ACTION_SEND_MULTIPLE) with text/plain and */* mime types, and reads the incoming content:// URI through the ContentResolver. Two Rust-side implications: (a) android-activity/winit do not surface the intent to Rust for you — the Java/Kotlin layer must forward it (a MainActivity override of onNewIntent/onCreate is the usual hook); (b) the shared file arrives as a content URI, not a path, so it must be copied into the vault (or streamed) through the resolver. (The intent-filter mechanics are standard Android; the exact Rust hook points are unverified here.)
  • iOS: a share extension is a separate executable (.appex) whose Info.plist carries NSExtensionPointIdentifier = com.apple.share-services, an NSExtensionPrincipalClass, and an NSExtensionActivationRule (keys: NSExtensionActivationSupportsText, NSExtensionActivationSupportsFileWithMaxCount, …SupportsImageWithMaxCount, …SupportsWebURLWithMaxCount). Narrow activation rules control when the app appears in the share sheet. https://developer.apple.com/library/archive/documentation/General/Conceptual/ExtensibilityPG/Share.html · https://developer.apple.com/documentation/bundleresources/information-property-list/nsextension (accessed 2026).
  • The extension and the host app exchange data through an App Group (group. prefixed container URL / shared UserDefaults); the group id must be registered for iOS/iPadOS/tvOS/visionOS/watchOS and can double as a Keychain access group. https://developer.apple.com/documentation/xcode/configuring-app-groups (accessed 2026).
  • Privacy trap: "For each executable or dynamic library in an app that uses a required reason API, the bundle that includes the executable or dynamic library needs to include a privacy manifest file" — the .appex needs its own PrivacyInfo.xcprivacy. https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api (accessed 2026).
  • Prerequisite for both platforms: a NotesCraft command such as note.new_from_share must exist in the engine command registry with an enabled flag, because on mobile the share action is a command invoked by the OS, not a menu item.

8. Widgets and quick capture

  • iOS widgets are SwiftUI/WidgetKit extensions and cannot be rendered by egui — a NotesCraft widget must be native Swift and read from the shared App Group container. Home-screen widgets need iOS 18+ per Obsidian's own requirement (Obsidian's iOS widget documentation). https://help.obsidian.md/ios (accessed 2026).
  • Android app widgets are also native (AppWidgetProvider); Obsidian ships home-screen widgets (Open Note, New Note, Search, Daily Note) and app shortcuts (long-press the app icon). https://help.obsidian.md/android (accessed 2026).
  • The cheapest and most valuable "quick capture" is not a widget: it is an OS-level share action (share text → new note) plus an in-app "quick add" that lands the note in a configured folder. Obsidian's own model: new notes go to Vault folder | Same folder as current file | A specific folder (Settings → Files and links), and an internal link that carries a folder path ([[Projects/X]]) overrides that. https://help.obsidian.md/settings (accessed 2026).
  • egui-side helpers that exist today: egui::CompletionPopup (added 0.37.0) gives autocomplete over a TextEdit; egui::Event::PasteImage (0.37.0) accepts images from the clipboard. Both are usable in a mobile quick-capture sheet. https://github.com/emilk/egui/releases/tag/0.37.0 (accessed 2026).

Method (continued)

The browse quota for this session was exhausted mid-research: web_search and web_fetch both return HTTP 429 (session usage limit) from the local Ollama web API, and no MCP web server is connected. Findings 9–16 and everything below them are therefore written from memory and are flagged as such. No version number, price or API name is invented: where I could not confirm a value I wrote "unverified". The URLs listed for the appended part under Sources are the canonical pages to re-verify; they were not re-fetched in this session. Findings 1–8 above were verified against primary sources and keep their citations.

9. Biometric app lock — platform code, not egui

  • Android: androidx.biometric.BiometricPrompt with BIOMETRIC_STRONG (or DEVICE_CREDENTIAL as fallback) — from memory.
  • iOS: LocalAuthentication — LAContext.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, …) then evaluatePolicy; .deviceOwnerAuthentication also accepts the device passcode — from memory.
  • egui cannot show a system biometric prompt. The prompt lives in the platform layer (apps/notescraft-mobile: the Kotlin/Java Activity on Android, the Swift shim on iOS) and hands Rust a boolean. The egui side is trivial — a TextEdit with the password flag for a fallback PIN — but it is not an egui problem.
  • Secret storage is also platform code: Android Keystore / EncryptedSharedPreferences, iOS Keychain. NotesCraft's desktop keychain.rs is already a per-platform seam; the mobile app wants its own small sibling module, not a new generic trait (ponytail: two thin modules beat one abstraction).
  • Threat model: a biometric gate protects a lost device, not data at rest. The vault stays plain .md in the app sandbox. Store copy must not imply "encrypted vault".
  • Risk for egui: low. Only friction: the prompt suspends the egui event loop; resume the shell when the callback returns.

10. Background sync — the OS decides when, so the client must be resumable

  • Android: WorkManager for deferrable work. PeriodicWorkRequest has a minimum interval of 15 minutes (from memory; Android also applies its own batching and backoff). Use constraints (NetworkType.CONNECTED) — "sync when a network is available", never "poll every minute". Expedited work (setExpedited) has a tight quota; reserve it for a user-triggered sync now.
  • Android foreground service: a long upload needs a foreground service with a visible notification and (Android 14+) foregroundServiceType="dataSync" plus FOREGROUND_SERVICE_DATA_SYNC — from memory.
  • iOS: BGTaskScheduler with BGAppRefreshTask. The identifier must be listed in Info.plist under BGTaskSchedulerPermittedIdentifiers, and the handler must be re-registered on every launch; a missed registration means no refresh. The system grants a small, non-guaranteed window — commonly quoted at ~30 seconds (from memory, treat as unverified). The legacy UIApplication.setMinimumBackgroundFetchInterval path is deprecated.
  • Design consequence: the sync client must be idempotent and resumable. last_seq lives in .notescraft/sync/state.json, so any task may start, upload what it can, and be killed at any point. That is exactly the split already in the spec — pure manifest diff and conflict rules in crates/sync, IO driven by the caller.
  • Do not keep the long-poll socket alive in the background: it wakes the radio, drains the battery, and the OS will kill the app regardless. Long-poll only while foregrounded; in the background, one short poll per scheduled window.
  • The spec already says "Mobile: sync on foreground, on save, and by OS background task (WorkManager / BGAppRefreshTask)". This finding confirms that shape.

11. Notifications — mostly platform code, and mostly unnecessary in v1

  • Android: NotificationChannel plus the POST_NOTIFICATIONS runtime permission on API 33+ — from memory. The permission must be requested in context; asking at first launch without a reason is a review risk.
  • iOS: UNUserNotificationCenter.requestAuthorization(options: [.alert, .sound, .badge]) — from memory. A denial is effectively sticky for that authorization.
  • egui has no native notification API; the system notification must be posted from the platform layer.
  • For NotesCraft v1, notifications are about trust ("3 notes synced"). An in-app toast in the status bar is enough; system notifications only for a long, user-initiated background sync. Push (APNs/FCM) would require a hosted push provider — a homelab server is not one, so push is P2.

12. Performance and battery

  • egui is immediate-mode and repaints on demand: eframe only redraws when there is input unless continuous repaint is requested. Keep continuous repaint off on mobile — it is the single biggest battery drain. (From memory; confirm the exact eframe/eframe::NativeOptions option name in 0.36/0.37 before relying on it.)
  • Renderer choice is the other big lever: glow (OpenGL ES) vs wgpu (Vulkan on Android, Metal on iOS). Old/odd Android Vulkan drivers are the classic source of blank screens and crashes, and egui's own Android example uses glow. On iOS, Metal via wgpu is the better long-term path, but the open iOS startup crash in finding 2 (egui #8052, traced to wgpu 29) says: pin wgpu and keep a known-good lockfile.
  • 16 KB page size (finding 1) is not only packaging: an NDK below r28 emits a .so that will not load on 16 KB devices. Ship NDK r28+ or pass -Wl,-z,max-page-size=16384.
  • The real cost on a phone is the vault index, not the pixels: an 8,000-note vault must not be indexed on the UI thread at startup. Build it lazily and in chunks, persist it (the crates/index plan already assumes this), and show progress instead of blocking the first frame.
  • File watching does not transfer to mobile: iOS suspends the app and sandbox FSEvents are not a useful trigger; Android inotify on the app's own directory is unreliable once the process is killed. The OS background task is the trigger, not the watcher (crates/vault/src/watch.rs stays desktop-only).
  • Traffic shape: long-poll /changes in the foreground; one short poll per background window; /batch/check (already in the spec) so an unchanged vault costs a single request.

13. Accessibility — the weakest area, treat it as an explicit gap

  • egui draws every widget itself, so there is no platform accessibility tree by default. egui ships an accesskit integration (feature accesskit on egui/eframe) that produces a platform accessibility tree on desktop (macOS/Windows/Linux backends). Whether usable Android/iOS backends exist is unverified — from memory, accesskit's Android support is young and iOS is unconfirmed.
  • Practical consequence: design the mobile shell for accessibility even if the screen-reader bridge is not ready yet — 44 pt minimum touch targets, text that follows the OS font scale, visible focus rings, no colour-only state, sane semantic order, and every gesture has a visible button equivalent.
  • Do not ship swipe-only navigation (swipe to open the drawer): it is an accessibility failure and it collides with the Android/iOS edge-back gesture (finding 4).
  • VoiceOver/TalkBack testing on a Rust app means checking focus order and labels by hand. Budget it as a P1 item, not a checkbox.

14. Store rules that apply to a Rust app

  • Play: new apps and updates must target a recent API level — Android 15 / API 35 became the floor for new apps in Aug 2025; the 2026 floor is unverified in this session. Ship an Android App Bundle (.aab); keep the upload key separate from the app-signing key and let Play App Signing hold the app key. Apps containing native code must be uploadable for symbolication — upload the native debug symbols for the Rust .so alongside the bundle.
  • Play Data safety form: the honest answer for NotesCraft is "no data collected by the developer" (the sync server is the owner's own, outside Google) — but only while the app does not send data to anyone else. A privacy policy URL is required; keep it in the repo and host it under owner control.
  • Android 13+ requires the notification permission to be requested in context; Android 14+ requires a foreground-service type for the sync foreground service.
  • App Store: Guideline 2.5.2 (self-contained container — cited in finding 6), 4.2 Minimum Functionality (editing a local vault is real functionality; a web wrapper is not), 5.1.1 / 5.1.2 (the App Privacy "nutrition label" must match what actually leaves the device — self-hosted sync is still transmission, so the label must mention it and a privacy policy URL is required), 2.3.x (accurate metadata), 4.7 (mini apps). Generic, but they are the ones a notes app can trip.
  • iOS privacy manifest per executable (finding 7): the Rust static lib does not need one, the app and the share extension each do.
  • iPad: an iPhone-only app is allowed, but universal (iPhone + iPad) is the better default — Obsidian ships universal, and the graph/canvas views benefit from the bigger screen. winit/eframe surface iPad split-view resizing as a Resized event (from memory).

15. Signing and CI

  • Android: a debug keystore for development, a separate upload keystore for release, both outside Git (and mirrored in the owner's password manager / CI secrets). cargo-ndk only produces jniLibs/ output; it does not build a bundle. The realistic AAB path is a small hand-written Gradle project that consumes cargo ndk -t arm64-v8a -t armeabi-v7a build --release output copied into src/main/jniLibs, then ./gradlew bundleRelease. cargo-apk (finding 1) is stale and NativeActivity-only, so it does not fit a GameActivity + AAB build.
  • Android CI: GitHub Actions (or equivalent) with the NDK installed and pinned, cargo ndk for the two ABIs, then Gradle with bundleRelease; zipalign/apksigner/bundletool come from AGP. Keep the release job on a protected environment so the upload key is only exposed there.
  • iOS: needs a Mac with Xcode and an Apple Developer Program membership (annual fee — amount unverified here). Signing is Xcode's job: a team, automatic signing, a provisioning profile. For CI the certificate and an App Store Connect API key (.p8) go into the runner's keychain; the release path is xcodebuild -archive → .xcarchive → upload via xcrun altool / xcrun notarytool. The Rust side produces a fat static lib (lipo, cargo-lipo) that the Xcode project links; cargo-xcode generates the project (finding 2) but produces no bridging headers, so the Swift↔Rust bridge is hand-written or generated with cbindgen/uniffi.
  • Both platforms: pin the Rust toolchain (rust-toolchain.toml), the NDK version and the Xcode version in CI. A mobile build that only compiles on one person's Mac is the real delivery risk.
  • Third-party mobile CI services exist for Rust apps (names and pricing unverified in this session) — only worth it if the self-hosted runners become a bottleneck.

16. Obsidian Mobile features worth copying — and what is risky in egui

Worth copying (Obsidian behaviour, from memory of the app and its help site; the widget/app-shortcut items were browsed in finding 8):

  • Mobile toolbar — a row of buttons above the keyboard (bold, italic, link, heading, checklist) that scrolls with the note. Copy: a compact egui row pinned above the keyboard, driven by the same command registry as the desktop.
  • Quick switcher — fuzzy search over note titles, opened with one gesture. Copy: the single most-used mobile navigation feature; cheap in egui (TextEdit + fuzzy list).
  • Quick capture — a small modal to create a note fast (title, body, target folder). Copy as a bottom sheet.
  • Command palette — the same commands as desktop in one searchable list. Copy: expose the crates/engine command registry, do not build a second mobile-only command set (SPEC 10).
  • Long-press context menu on file rows — rename, move, duplicate, delete, copy link.
  • Swipe gestures — swipe the tab bar to switch tabs, edge swipe to open the file drawer. Copy selectively.
  • Tabs — a top tab bar with pinned tabs; Obsidian Mobile keeps desktop-style tabs. Copy: bottom tab bar for the app, note tabs inside the note view.
  • Daily note on open — a community plugin, but the behaviour (open today's daily note on launch) is widely relied on.
  • Share sheet receive — share a page or text into Obsidian and it becomes a note (finding 7).
  • Home-screen widgets (Android: Open Note, New Note, Search, Daily Note) and app shortcuts (long-press the app icon) — browsed in finding 8.
  • Link autocomplete while typing ([[ suggestions); Obsidian's core link suggestion behaviour is from memory.
  • Bookmarks, recent files, a simplified graph on mobile, and Canvas on mobile — from memory.
  • Deep link scheme (obsidian://open?vault=…&file=…) — a notescraft:// equivalent is cheap and unlocks widgets, app shortcuts and share integrations.

Risky for egui (this is the honest risk column):

  • Swipe gestures — high risk. egui has no gesture abstraction (finding 4): only InputState::multi_touch() (pinch/rotate/translate) and single-touch pointer emulation. A horizontal-drag detector must be hand-written, and an edge swipe is consumed by the OS back gesture (Android and iOS) before the app sees the touch.
  • Long-press menus — medium risk. egui's secondary click fires at max_click_duration (default 0.8 s) and only if the pointer did not move; it competes with the OS text-selection handles and with drag-to-scroll inside a ScrollArea.
  • Momentum/inertial scrolling — medium-high risk. egui's ScrollArea is immediate-mode with no physics, so a flick will not glide (from memory; verify before promising a native feel). This is the single most visible "desktop app on a phone" tell.
  • Link autocomplete popup — medium risk. egui 0.37 added CompletionPopup, but the popup must survive the keyboard opening and the viewport shrinking (safe-area + keyboard-aware layout must land first).
  • Widgets / app shortcuts — low technical risk, high maintenance cost. They must be native Swift/Kotlin; they cannot be egui, so each is a second surface to keep in step with the Rust app.
  • Pull-to-refresh and swipe row actions — medium risk, same gesture problem as above.
  • Text selection and handles — high risk. The OS owns selection gestures inside the native text view; an egui-drawn TextEdit cannot offer native handles. Combined with the iOS IME gap (finding 3), an egui editor will feel less native than a UITextView/EditText-backed one. Mitigation for v1: treat the note editor as read-mostly on phones and route heavy editing through the native text view, or accept the compromise explicitly.

Feature table

Feature Who has it Why it matters for NotesCraft Effort Priority
Sandbox vault + Files-app visibility (UIFileSharingEnabled, Android filesDir) Obsidian Mobile, Apple Notes Keeps plain .md as the source of truth; user can copy files in/out without any permission dance S P0
External folder via SAF tree (ACTION_OPEN_DOCUMENT_TREE + persisted URI) Obsidian Android, most Android apps Lets the phone point at an existing folder (e.g. one a file-sync tool already manages) L P1
Security-scoped bookmark for an external folder Obsidian iOS, iOS apps Same on iOS (iCloud/Drive folders) — bookmark persistence + revocation handling L P1
Share-target receive (Android ACTION_SEND intent + iOS share extension) Obsidian Mobile, Apple Notes, Bear Capture a page or snippet as a note in ~2 s; the classic mobile loop M P0
Quick capture sheet (title + body + target folder) Obsidian Mobile, Bear, Apple Notes Lowest-friction capture path; reuses the "vault folder / same folder / specific folder" rule M P0
Quick switcher (fuzzy title search) Obsidian, Bear, Craft suite The main navigation affordance on a 390 pt screen M P0
Command palette on mobile over the engine registry Obsidian (plugin), VS Code, Craft suite One command surface for UI, CLI, control channel, MCP and plugins (SPEC 10) M P1
Bottom tab bar shell (Notes, Search, Graph, Calendar, More) Obsidian Mobile, Craft suite The one-column layout the spec's 390 pt acceptance criterion demands M P0
Mobile toolbar above the keyboard Obsidian Mobile, Craft suite editor Formatting without a hardware keyboard; needs keyboard-aware layout first L P1
Long-press context menu on rows (Rename/Move/Duplicate/Delete) Obsidian, iOS/Android OS convention Renaming and moving is the other half of note management M P1
Swipe tab switching / edge drawer Obsidian Mobile, Bear, Craft suite Fast navigation, but conflicts with OS edge-back — expect to drop the edge variant M P1
Safe-area + keyboard-aware layout (insets, content_rect) native apps, Obsidian Content must never sit under the home indicator or the keyboard; egui gives iOS insets for free, Android not M P0
Correct IME / marked text (candidate window) all native apps Non-latin input is broken without it; iOS needs a native UITextView shim L P0
Background sync (WorkManager, BGTaskScheduler) Obsidian Sync (proprietary), Joplin Convergence while the app is closed; the core of the mobile promise M P0
Sync status line + pending/offline queue UI Obsidian Sync, Craft suite Trust: the user must see what synced, what is pending, what conflicted S P0
Conflict resolution UI (list + side-by-side, never lose text) Obsidian Sync, git Direct spec acceptance criterion; also the safety net for a single-owner many-device vault M P0
Biometric app lock Obsidian, 1Password, Bear Protects a lost/borrowed device; plain .md at rest is not encrypted M P1
App shortcuts (long-press the app icon) Obsidian Android, iOS 16+ New note / daily note / search without opening the app S P1
Android home-screen widget Obsidian Android, Craft suite Open note, new note, search, daily note M P2
iOS WidgetKit widget (iOS 18+ per Obsidian) Obsidian iOS, Craft suite Same on iOS; native Swift reading an App Group container M P2
Deep link scheme notescraft:// Obsidian (obsidian://), Craft suite Unlocks widgets, shortcuts, share and "open in NotesCraft" S P1
Local notifications for sync results Obsidian Sync, Craft suite Trust when backgrounded S P2
Push notifications (APNs/FCM) Obsidian Sync Real-time; needs a hosted push provider a homelab does not have L P2
Screen-reader accessibility (labels, focus order, 44 pt targets) native apps, Obsidian Required for a credible a11y story; accesskit mobile support unverified L P1
Background vault index build with progress Craft suite 8,000 notes must not block the first frame on a phone M P1
Momentum / inertial scrolling native apps, Bear The most visible "not native" tell in an egui app M P1

Recommendations — the 10 to build next

  1. Android shell on GameActivity + cargo-ndk + Gradle AAB (L, P0) — the fastest route to a phone in the owner's hand; GameActivity is what Google recommends and NativeActivity tooling is stale. Acceptance: Given a clean checkout, when the release CI job runs, then it produces a signed .aab for arm64-v8a and armeabi-v7a that installs on a physical device and reaches the file list in under 3 s with no ANR in logcat.
  2. iOS static-lib wrapper in Xcode (L, P0) — iOS is the harder half, so start the spike early even though it is not officially supported upstream. Acceptance: Given a macOS machine with Xcode, when the project is archived, then the app starts the egui shell inside ApplicationHandler::resumed, and after a background→foreground cycle the same note is still open with the keyboard still working.
  3. Sandbox vault plus Files-app visibility (S, P0) — the vault stays plain .md, so this is the cheapest thing that satisfies "the vault is the source of truth" on a phone. Acceptance: Given a fresh install, when a note is created, then it appears under Documents/NotesCraft in the iOS Files app and under the Android filesDir, and the sync scan picks it up with no extra configuration.
  4. Soft-keyboard and IME correctness (L, P0) — the single hardest technical blocker; without it the editor is unusable for most people. Acceptance: Given a phone keyboard, when the user types accented and CJK text into a note, then the composed text is inserted (never per-key strokes), the candidate window opens, and the caret stays visible above the keyboard.
  5. Safe-area + keyboard-aware one-column shell (M, P0) — the spec's 390 pt acceptance criterion, and the prerequisite for the toolbar and autocomplete popup. Acceptance: Given a 390×844 phone with the keyboard open, when a note is open, then the text area and the mobile toolbar are fully visible, nothing is hidden under the home indicator, and the bottom tab bar shows exactly five items.
  6. Quick capture sheet plus share-target receive (M, P0) — the killer mobile loop: text from anywhere becomes a note, and it also forces the command registry to own note.new_from_share. Acceptance: Given text shared from Safari into NotesCraft, when the share sheet returns, then a note appears in the configured capture folder within 2 s and is visible in the file list with no further tap.
  7. Quick switcher and command palette over the engine registry (M, P0) — one search box that navigates and one that commands; both are thin because the engine already owns the command surface. Acceptance: Given the switcher, when three characters are typed, then notes are filtered by fuzzy title match and the top hit opens on Enter, and the palette lists exactly the command ids the desktop registry exposes.
  8. Background sync via WorkManager and BGTaskScheduler (M, P0) — the reason a phone build is worth having; the client is already resumable by design (last_seq in state.json). Acceptance: Given the app backgrounded for one hour with a network available, when the OS runs the scheduled task, then the vault converges with the server and the status line shows the last sync time, with no long-lived socket and at most one poll per window.
  9. Conflict resolution UI plus an offline queue view (M, P0) — never lose text is a hard product promise, and a single owner with many devices will hit it. Acceptance: Given the same note edited offline on two devices, when both reconnect, then each device lists a Conflicts entry showing both versions, and no character of either version is lost even if the user resolves nothing.
  10. Mobile toolbar and long-press context menu (L, P1) — the two things that make a phone build feel like a notes app rather than a shrunk desktop one; both are gated on the keyboard-aware layout from #5. Acceptance: Given a note open on a phone, when a toolbar button is tapped, then the corresponding formatting command applies, and when a file row is long-pressed, then a context menu offers Rename, Move, Duplicate and Delete, and a Delete can be undone.

Ordering note: #1 and #2 are the platform spikes; #3–#5 are the shell; #6–#10 are the product value. Biometrics, widgets, app shortcuts, notifications and push stay behind these (P1/P2 in the table) — they are cheap to add once the shell and the command surface exist.


Risks

  1. iOS is not an officially supported egui target (finding 2): winit's iOS backend is Tier 2, egui issue #3117 is open, there is no upstream iOS CI, and eframe's iOS entry (create_native) is a moving API. Mitigation: pin egui/winit/wgpu exactly, keep a private patch set if needed, and put our own iOS CI build on a macOS runner so an upstream break shows up in our pipeline, not on the owner's phone.
  2. The IME gap on iOS (finding 3): winit's UIKit view implements only UIKeyInput — no marked text, no candidate window, no autocorrect, no dictation — so a native UITextView shim in Swift is required. That means two UI stacks in one app, in a project whose rule is "Rust only". Mitigation: keep the shim minimal (text in, text out) and treat it as an adapter, not a feature.
  3. Android soft keyboard is not solved either (egui #5590 is still open): set_ime_cursor_area/set_ime_purpose are no-ops on Android, so the candidate window never anchors to the caret. Mitigation: plan for a Kotlin-side show_soft_input + caret-rect bridge from day one, not after the first bug report.
  4. GameActivity vs the Rust tooling: cargo-apk is NativeActivity-only and stale (2023), and egui's example depends on a patched fork. Mitigation: write our own thin Gradle template around cargo ndk; treat cargo-apk as optional.
  5. SAF is hostile to a vault (finding 5): a user-picked tree must be walked one DocumentFile at a time, and it is not a plain filesystem path, so std::fs cannot walk it. An 8,000-note vault over SAF is impractical. Mitigation: keep the sandbox as the only writable vault in v1; treat external folders as import-only and say so in the UI.
  6. Security-scoped access can be revoked (finding 6) at any moment in Settings → Privacy → Files and Folders; a bookmark that fails to resolve must become a clear Err and a re-pick flow, never a silent fallback to a different folder.
  7. No gesture layer in egui (finding 16): swipes, edge gestures, momentum scrolling and native text handles must be hand-built or dropped, and edge gestures fight the OS back gesture. Mitigation: ship buttons first, gestures later, and never make a gesture the only path.
  8. Accessibility may not ship with the first build (finding 13): accesskit's mobile backends are unverified. Mitigation: design to 44 pt targets and OS font scaling from the first layout, and treat screen-reader support as a follow-up milestone rather than a promise.
  9. Store compliance is real work, not paperwork (finding 14): Play's target-API floor (2026 level unverified), the 16 KB page-size requirement, the AAB-only rule, native debug-symbol upload, the Data safety form, and on Apple the privacy manifest per executable, the App Privacy label (self-hosted sync still counts as transmission), Background Modes declarations for BGTaskScheduler and a 4.2 minimum-functionality risk. Mitigation: keep a release checklist in the repo and re-read both stores' current pages before the first submission.
  10. Signing and CI are owner-only dependencies (finding 15): an Apple Developer membership, an upload keystore, CI secrets and a macOS runner with Xcode. A mobile release that only builds on one machine is a single point of failure. Mitigation: CI-only release path, secrets in CI, and a rehearsed "build from a clean checkout" run before every store submission.
  11. Energy and radio cost: long-polling in the background is killed by the OS and drains the battery; wake-ups must be scheduled, not spun. Mitigation: foreground long-poll only, one poll per background window, batch with /batch/check.
  12. Font coverage: egui's default fonts have limited CJK coverage, so a Chinese/Japanese vault renders as tofu without embedded fonts. Mitigation: subset and embed a font per script in the theme/packaging step, and size it for download budget.
  13. Activity recreation on Android (finding 4): without android:configChanges for orientation and screen size, rotation destroys and recreates the Activity — losing in-memory editor state. Mitigation: declare the config changes and persist the open-note state in the vault/session file.

Sources

Browsed and verified in this research (findings 1–8, accessed 2026)

Canonical pages to re-verify (findings 9–16 — not fetched, browse quota exhausted; accessed year unknown)