Files
jsonPrism/docs/TAURI-NOTES.md
T
poli0981andClaude Opus 4.8 b1d461a18e fix(android): open external links via opener plugin (shell.open broke on Android) (#105)
The v1.7.2 global link interceptor routed external URLs through
`@tauri-apps/plugin-shell`'s `open()`, but that throws on Android:
"Scoped shell IO error: No such file or directory (os error 2)" — the
shell plugin has no native URL handler on mobile, so every tapped link
did nothing. (The earlier ConsentGate per-link shell.open from #98 had
the same flaw; it was simply never tap-tested on Android.)

Switch to `@tauri-apps/plugin-opener`'s `openUrl()`, whose `open_url` has
a real cfg(mobile) split that routes to the native Intent.ACTION_VIEW
handler. Plain `openUrl(url)` — no inAppBrowser (that option regressed
os-error-2 on Android 16, plugins-workspace#2913).

Wiring: tauri-plugin-opener crate + init, @tauri-apps/plugin-opener npm,
"opener:default" capability (its allow-open-url permits any URL). Shell
plugin removed entirely (openExternal was its only consumer) — also from
vite optimizeDeps, knip ignore, and the THIRD-PARTY/TAURI-NOTES docs.

Verified on emulator API 33 (Android 13, WebView Chromium 109): tapping
the consent-gate License link and footer X link both fire ActivityManager
START ACTION_VIEW and open Chrome; no shell error.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 18:58:28 +07:00

9.1 KiB

Tauri runtime notes

Operational notes for the desktop builds. Aimed at maintainers, not end users.

Process lifecycle

src-tauri/src/lib.rs wires two cleanup hooks that should keep the host process from outliving the main webview:

  • on_window_event — when the main window receives CloseRequested, the app handle's exit(0) is called explicitly. This guards against Windows builds occasionally leaving JSONPrism.exe alive when the webview was the last live reference.
  • RunEvent::ExitRequested — calls app_handle.cleanup_before_exit() so any spawned shell children (none today, but the hook is in place) are signaled before the process exits.

If you ever add long-running spawned commands (e.g. via a shell/command plugin), remember to track their handles and kill them in the same hook.

WebView2 GDI leak (Windows, upstream)

Microsoft Edge WebView2 — the runtime Tauri uses on Windows — leaks GDI objects whenever the mouse hovers over the webview surface. Reported and acknowledged by Microsoft:

  • WebView2Feedback #5536 — ~2000 GDI objects leaked per 30 seconds of mouse movement.
  • Toggling visibility (SetIsVisible) compounds the leak (~6000 obj/30s).
  • The per-process GDI cap is 10 000 by default; the app eventually fails to draw and crashes once exhausted.

This is not a JSONPrism bug. The fix has to come from the WebView2 runtime team. Until then:

  • Watch the GDI object count in Task Manager (View → Select Columns) during long sessions. Above ~8000 means a restart is overdue.
  • For QA / release smoke tests, open and close the app five times in succession; verify no zombie JSONPrism.exe remains in Task Manager.

Permissions / capabilities

See src-tauri/capabilities/default.json. Scope is intentionally narrow:

  • Filesystem reads/writes only inside $HOME, $DOCUMENT, $DOWNLOAD, $DESKTOP.
  • Dialog plugin for open/save.
  • Opener plugin (opener:default) for handing external URLs to the system browser — shell:open has no native Android URL handler, so the opener plugin's openUrl is used instead.

Widening the scope requires both a capability edit and a CSP review in tauri.conf.json.

Bundle targets

  • Windows: MSI (via WiX) + NSIS .exe. Tested on Windows 10 22H2 and Windows 11.
  • macOS: DMG + .app, min version 12.0 (Monterey).
  • Linux: AppImage + Debian package.

The release matrix in .github/workflows/release.yml builds all four combinations (Linux, macOS Intel, macOS Apple Silicon, Windows) on a v* tag push.

Android (sideload APK)

JSONPrism ships an Android APK that users sideload. Minimum Android 12 (API 31) — set via bundle.android.minSdkVersion in tauri.conf.json; the OS installer refuses older devices. The build target is a universal APK (all ABIs in one file) so users only ever download one .apk.

Toolchain (local, Windows)

Environment variables Tauri's CLI reads:

  • JAVA_HOME → Android Studio's JBR, e.g. C:\Jetbrains\Android Studio\jbr
  • ANDROID_HOME → C:\Users\<you>\AppData\Local\Android\Sdk
  • NDK_HOME → …\Android\Sdk\ndk\<version>

Rust targets: rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android. Verify with npm run tauri info.

NDK selection. The CLI auto-picks the highest NDK under $ANDROID_HOME/ndk, regardless of NDK_HOME. If you keep multiple NDKs and want a specific one, leave only that version installed. Builds are validated against NDK r27+; CI pins ndk;27.2.12479018.

The gen/android project

src-tauri/gen/android/ (the Gradle project from tauri android init) is committed — source only. Its nested .gitignore files exclude build outputs (build/, .gradle/, .cxx/, *.so, local.properties, keystore.properties). Committing it keeps the signing edits in app/build.gradle.kts and minSdkVersion stable, and makes CI reproducible.

You normally do not run tauri android init again. Only re-run it after a major @tauri-apps/cli bump, and re-apply the signing block + verify minSdk = 31 in app/build.gradle.kts afterward (the init overwrites it).

Launcher icons (res/mipmap-*/ic_launcher*.png) are generated by npm run tauri:icon and gitignored, like the desktop icons — both the local tauri:android:build script and CI regenerate them before building.

versionCode

bundle.android.versionCode in tauri.conf.json must increase monotonically (needed for in-place upgrades). Derive it deterministically from semver:

versionCode = MAJOR*10000 + MINOR*100 + PATCH

e.g. 1.6.1 → 10601, 1.7.0 → 10700. Bump it together with version in package.json / Cargo.toml / tauri.conf.json at release time.

Signing

Release signing is read from src-tauri/gen/android/keystore.properties (gitignored), which points at a keystore .jks (also gitignored, kept outside the repo). If the file is absent the release variant builds unsigned — fine for contributors, but a release APK must be signed so it installs and so future versions can upgrade in place.

Generate a keystore once:

& "$env:JAVA_HOME\bin\keytool.exe" -genkeypair -v `
  -keystore "$env:USERPROFILE\jsonprism-upload-keystore.jks" -storetype JKS `
  -keyalg RSA -keysize 2048 -validity 10000 -alias upload

Then create src-tauri/gen/android/keystore.properties:

storePassword=…
keyPassword=…
keyAlias=upload
storeFile=C:/Users/<you>/jsonprism-upload-keystore.jks

Use forward slashes in storeFile — .properties treats \ as an escape. Back up the .jks and its passwords (password manager). Losing the key means users can no longer upgrade in place — they'd have to uninstall first.

CI signing secrets

The android job in release.yml needs these repository secrets:

Secret Value
ANDROID_KEYSTORE_BASE64 base64 of the .jks (required)
ANDROID_KEYSTORE_PASSWORD the store password (required)
ANDROID_KEY_PASSWORD the key password (optional; defaults to store password)
ANDROID_KEY_ALIAS the alias (optional; defaults to upload)

Produce the base64 (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("$env:USERPROFILE\jsonprism-upload-keystore.jks")) | Set-Clipboard

CI decodes it to a temp path, writes keystore.properties, builds with tauri android build --apk, and uploads the universal APK to the same draft release as the desktop bundles. If ANDROID_KEYSTORE_BASE64 is unset the job fails fast rather than shipping an unsigned APK.

Output

src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk

Offline fonts

Fonts (Geist / Instrument Serif / JetBrains Mono) are self-hosted via @fontsource (imported in src/main.tsx), not loaded from Google Fonts, so the app renders correctly offline. The CSP in tauri.conf.json no longer allows the Google Fonts hosts — keep it that way unless fonts move back to a CDN.

WebView version requirement (important)

The Android app renders inside the device's Android System WebView, which is Chromium. Tailwind v4 (our CSS) requires Chromium ≥ 111 (@layer, oklch(), @property). On an older WebView the layout breaks badly (giant icons, unhidden elements, no responsive layout) even though the app installs and runs.

  • Real Android 12+ devices keep WebView updated via Play Store → modern Chromium → renders correctly. This is the normal case.
  • The bundled WebView in the API 31 emulator system image is Chromium 91 and shows the broken layout. Use a newer emulator image (e.g. android-34+, which ships Chromium ≥ 120) or update the emulator's WebView via Play to test rendering. The android-31 install/minSdk gate can still be tested on the stock API 31 image.

This is inherent to the Tailwind v4 stack (the web app has the same requirement); it is not Android-specific code. No action needed unless you must support devices with a very outdated WebView.

Native file I/O on Android

plugin-dialog open() returns a percent-encoded content:// URI on Android (not a filesystem path). plugin-fs readTextFile() reads it fine — validated on an emulator for both URI flavours. fileFromNativePath() (src/lib/tauri.ts) runs the URI through basenameFromPath() to recover a filename for the editor, the extension filter, and toasts. stat() on a content URI is unreliable, so lastModified falls back to a deterministic path hash — dedup still works.

Two URI flavours show up:

  • raw: URIs (most local/Downloads files) embed the real path → basenameFromPath() recovers data.json.
  • msf: URIs (MediaStore-indexed files) are opaque document ids with no filename → they collapse to a numeric id (e.g. 18) and carry no extension. The native open path therefore filters leniently (filterByExtension(..., true) / the extOf(name) && !allowed guard in InputPanel) so a file the user explicitly picked is never wrongly rejected. The real display name would need a content-resolver DISPLAY_NAME query via a custom Rust command — not worth it; the file content loads correctly either way.