Kvaesitso/CLAUDE.md

Kvaesitso (fork with type-to-search)

Fork of Kvaesitso that adds type-to-search for phones with a physical keyboard. Built for, and installed on, a Unihertz Titan 2 Elite.

origin   = https://gitea.haugesenspil.dk/jonas/Kvaesitso   (our fork — push here)
upstream = https://github.com/MM2-0/Kvaesitso              (pull upstream changes from here)

The phone also has this repository checked out in its Termux home: ~/sources/Kvaesitso.

The feature

Pressing a printable key on the physical keyboard while the launcher home screen is shown opens the search page and inserts the character. Backspace deletes, enter launches the highlighted result. Only the home screen (and the open search page) reacts; the widgets, notifications and recents pages do not. Setting: Settings → Search → "Search on typing" (on by default, stored as searchOnTyping).

How it works, and why it is built this way

SharedLauncherActivity.dispatchKeyEvent is the only place that sees hardware key events while no view has focus, so the handler is installed there (launcherKeyEventHandler, registered by LauncherScaffold while it is shown). The handler itself is app/ui/.../ui/launcher/searchbar/TypeToSearchHandler.kt.

Two constraints shape the design:

1. The search bar's text field stays unfocused while the keyboard drives the search. A focused Compose text field makes the system show the on-screen keyboard. There is no public API to prevent that: View.setShowSoftInputOnFocus is a hidden API (TextView's version is public) and reflection fails with NoSuchMethodException, and hiding the IME reactively makes it flash. Leaving the field unfocused keeps the IME away completely — which is why the handler inserts and deletes the characters itself instead of relying on the text field.
2. No key may be lost. Characters can arrive before the text field would have focus, so the handler keeps handling keys until the field reports real focus (LauncherScaffoldState.isSearchBarTextFieldFocused). LauncherScaffoldState.isTypingSearch marks a keyboard-driven search: while it is set, SearchComponent.onPreActivate does not focus the field and the handler owns the keys, including backspace and enter. Tapping the search bar clears the flag and hands over to the normal editable field.

SearchBar keeps a TextFieldValue instead of a String so that changing the text from the outside moves the cursor to the end. Without that, the next typed character landed in front of the text.

The search is also cleared whenever the launcher is left, even for a short app switch — upstream keeps it for returns within five seconds, which leaves a stale query on screen.

Building

On the desktop:

JAVA_HOME=~/jdk21 ANDROID_HOME=~/android-sdk \
  ./gradlew :app:app:assembleDefaultRelease

Result: app/app/build/outputs/apk/default/release/app-default-release.apk, applicationId de.mm20.launcher2.release.

The release build type signs with the local signing config, which reads keystore.properties in the repository root (git-ignored) or the KEYSTORE_FILE, KEYSTORE_PASSWORD, KEY_ALIAS and KEY_PASSWORD environment variables. The desktop key is ~/android-keystores/kvaesitso-release.jks; the phone has its own copy under ~/android-keystores/ in the Termux home.

Building on the phone itself (Termux)

The phone builds this project without a desktop. scripts/ondevice.sh wraps the loop:

scripts/ondevice.sh build      # assemble the debug APK
scripts/ondevice.sh install    # build, then pm install it (root)
scripts/ondevice.sh start      # launch the debug build
scripts/ondevice.sh logs       # follow logcat of the debug build (Ctrl-C to stop)
scripts/ondevice.sh crash      # newest crash report for the debug build
scripts/ondevice.sh release    # assemble the signed release APK

Or call Gradle directly: ./gradlew :app:app:assembleDefaultDebug. A full build takes about 13 minutes (984 tasks), later ones 20-30 seconds; the release build (R8 plus lintVital) takes about 11 minutes. Run termux-wake-lock first so the screen lock does not throttle it.

The debug build is de.mm20.launcher2.debug (isDebuggable, its own empty data directory), so it installs next to the real launcher and can be logged with su -c 'logcat --pid=$(pidof de.mm20.launcher2.debug)'. Installing, reinstalling or uninstalling that package cannot affect the real launcher: different package, different data directory.

Never uninstall de.mm20.launcher2.release. It is the launcher the phone actually runs, and the config (widgets, pages, tags, search settings) lives in its data directory /data/user/0/de.mm20.launcher2.release, mostly under files/datastore. pm install -r of a build signed with the same key keeps that data, but it does replace the running launcher, so do it deliberately, after backing the data directory up. Reinstalling the debug build is always the safe way to try a change.

To try a fix in the real launcher with the real data, build the release APK and pm install -r it: same package (de.mm20.launcher2.release) and same key, so it replaces the installed build in place. The release APK is minified by R8, so this is the slow build. scripts/ondevice.sh release only builds it; it never installs anything.

The SDK on the phone

~/android-sdk (see ~/CLAUDE.md) provides everything Gradle needs:

• platforms/android-37.0 — the compileSdk 37 platform, installed with sdkmanager.
• build-tools/36.0.0 — the version AGP 9.3.1 defaults to. Google only ships x86_64 build-tools, so the three native tools are symlinks into build-tools/34.0.4, which is AndroidIDE's aarch64 build of the AOSP tools: aapt2, zipalign and aidl. Everything else in build-tools (d8, apksigner, jars) is Java and runs as is.
• ~/.gradle/gradle.properties points android.aapt2FromMavenOverride at Termux's own aarch64 aapt2 (2.20, newer than 34.0.4's) and lowers the Gradle/Kotlin daemon heaps to fit the phone.
• local.properties in the repo root sets sdk.dir; it is git-ignored. The SDK itself is machine-wide, not project-specific: another project just needs termux-sdk init <repo>, and termux-sdk install "platforms;android-35" "build-tools;35.0.0" adds other SDK versions (it patches their x86_64 native tools to aarch64, which plain sdkmanager cannot do). See ~/CLAUDE.md for what does and does not build on this phone.

Releasing (the phone updates through Obtanium)

1. Raise versionCode above the installed one and set a new versionName in app/app/build.gradle.kts (versionName may keep the upstream version, e.g. 1.40.2-typing.2).
2. Build the release APK (see above) and check the signature: apksigner verify --verbose.
3. Tag it and push main and the tag to origin (Gitea needs a token: the desktop keeps it in ~/.config/gitea/token).
4. Create a Gitea release for that tag and attach the APK as Kvaesitso-v<versionName>-Signed.apk. The repository is public so Obtanium can read it anonymously.
5. The phone's Obtanium entry for de.mm20.launcher2.release points at this Gitea repo with overrideSource: "Codeberg", versionDetection: true and apkFilterRegEx: "Kvaesitso-v". It picks the release up on the next check. The config file lives on the phone at /sdcard/Android/data/dev.imranr.obtainium.fdroid/files/app_data/de.mm20.launcher2.release.json (force-stop Obtanium before editing it as root).

Installing on the phone by hand

This is the destructive path: it costs the launcher config unless the backup is restored correctly. Do not do it without an explicit reason and a backup. The current config lives in /data/user/0/de.mm20.launcher2.release (uid of the release build, currently u0_a311); copy it out with root before touching anything.

The phone already runs this build. The official build is signed with the upstream key, so it cannot be updated in place and Obtanium cannot install over it either. The procedure is: back up /data/user/0/de.mm20.launcher2.release with root, pm uninstall (a -k uninstall keeps the package record and its signature, so the next install then fails with INSTALL_FAILED_UPDATE_INCOMPATIBLE), install this APK, then copy the data back — chown to the new app uid and chcon the label that installd created for the fresh data directory. The rest of the phone (bootloader, Magisk, microG, rescue steps) is documented in ~/titan2-elite/CLAUDE.md on the desktop.