perf: record ime first-render benchmark baseline

Author: SysAdminDoc

AGENTS.md

@@ -11,7 +11,7 @@ mode, etc.). Tool-specific files like [`CLAUDE.md`](CLAUDE.md) carry
 ## Read this first
 
 1. [`PROJECT_CONTEXT.md`](PROJECT_CONTEXT.md) — single-page consolidated
-   project context. Pins the load-bearing invariants, the v1.8.158
+   project context. Pins the load-bearing invariants, the v1.8.159
    stack, the module layout, the roadmap-file routing, and the current
    sprint state.
 2. [`ARCHITECTURE.md`](ARCHITECTURE.md) — contributor-facing module,
@@ -80,7 +80,7 @@ and Definition-of-Done evidence.
 
 `gradle.properties` `projectVersionCode` + `projectVersionName` bump
 in lockstep with the release-notes commit. Tag the release commit at the
-   same time. Local and remote release tags are current through `v1.8.158`
+   same time. Local and remote release tags are current through `v1.8.159`
 as of 2026-05-18.
 
 ### 5. Definition of Done (per [ROADMAP.md](ROADMAP.md) §15)

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # SwiftFloris Architecture
 
-Last updated: 2026-05-18, against the v1.8.158 codebase.
+Last updated: 2026-05-18, against the v1.8.159 codebase.
 
 This file is the fast architectural map for contributors. It is intentionally
 shorter than `ROADMAP.md` and more code-oriented than `PROJECT_CONTEXT.md`.
@@ -30,9 +30,11 @@ The active Gradle modules are declared in `settings.gradle.kts`.
 | `:lib:compose` | Shared Compose resource, layout, and UI helpers |
 | `:lib:kotlin` | Pure Kotlin utility code |
 | `:lib:snygg` | Snygg theme parser and runtime engine |
+| `:benchmark` | AndroidX Macrobenchmark module plus adb-driven benchmark harness target |
 
-`benchmark/` and `lib/native/` are present on disk but are not active Gradle
-modules in the current settings file.
+`:benchmark` is included in settings for Macrobenchmark and adb performance
+harnesses. `:lib:native` remains present on disk but inactive until a native
+addon/runtime slice intentionally revives it.
 
 ## Runtime Entrypoints
 

IMPROVEMENT_PLAN.md

@@ -216,19 +216,28 @@ Acceptance criteria:
 
 ### 7. Performance Instrumentation
 
-Status: Planned
+Status: In progress
 Priority: P1
 
 Goal: Add lightweight evidence around typing responsiveness and startup quality.
 
 Tasks:
-- [ ] Measure keyboard cold start and first render.
+- [x] Measure keyboard cold start and first render.
 - [ ] Measure first suggestion latency.
 - [ ] Measure dictionary load and preload time.
 - [ ] Measure candidate row recomposition hotspots.
 - [ ] Measure theme switching cost.
 - [ ] Measure backup/restore duration on representative archives.
-- [ ] Add repeatable profiling notes using adb, simpleperf, Perfetto, or Compose tracing where appropriate.
+- [x] Add repeatable profiling notes using adb, simpleperf, Perfetto, or Compose tracing where appropriate.
+
+Progress:
+- 2026-05-18 (v1.8.159): `:benchmark` is active again, the benchmark
+  variant has a local-only input activity, and
+  `tools/benchmark-ime-first-render.ps1` records repeatable adb first-render
+  runs. Samsung SM-S938B / Android 16 baseline: `am start -W` median
+  `TotalTime` 31.0 ms, median `WaitTime` 34.0 ms, and benchmark-only
+  `swiftfloris.ime.firstRenderMs` median 18.335469 ms over five runs.
+  Evidence: `docs/benchmark-results/baseline-2026-05-18-ime-first-render.json`.
 
 Acceptance criteria:
 - Performance claims are backed by repeatable commands.

PROJECT_CONTEXT.md

@@ -3,7 +3,7 @@
 **Maintained at root for fast onboarding.**
 **Last consolidated:** 2026-05-18 (from the autonomous research run at
 [`.ai/research/2026-05-17/`](.ai/research/2026-05-17/) plus follow-up slices
-through v1.8.158).
+through v1.8.159).
 
 This file is the single fastest read for an AI session, new contributor, or
 maintainer-context refresh. It does **not** replace [ROADMAP.md](ROADMAP.md),
@@ -45,7 +45,7 @@ them requires changing both the relevant code *and* the gate.
 If a proposed change conflicts with any of these, the answer is "move that
 feature into an addon" — never "loosen the invariant."
 
-## 3. Stack at HEAD (v1.8.158)
+## 3. Stack at HEAD (v1.8.159)
 
 ```
 Kotlin 2.3.21 · Compose BOM 2026.05.00 · Material 3 + material-kolor 4.1.1
@@ -195,7 +195,7 @@ and in [`ROADMAP.md` §0 v5.5 + v5.4](ROADMAP.md). Net deltas to invariants:
   at `docs/outreach/2026-05-17-swiftkey-migration/` covering
   AlternativeTo, BGR, Android Authority, and r/Swiftkey.
 
-**v1.8.104 – v1.8.158** ships the seventh research-pass privacy,
+**v1.8.104 – v1.8.159** ships the seventh research-pass privacy,
 voice, clipboard, NLP, visual-regression, Addons trust/asset/catalog layer, and
 input-behavior testability plus conservative lint/dependency cleanup layer.
 v1.8.104 – v1.8.110 closed the
@@ -436,6 +436,14 @@ v1.8.158 closes the accessibility manual-QA documentation item.
 keyboard label, candidate-row announcement, high-font-scale, non-color-state,
 and theme/layout checks for changes that touch settings or keyboard surfaces.
 
+v1.8.159 starts Performance Instrumentation Workstream 7. `:benchmark` is
+active again on AGP 9, the benchmark variant has a local-only input activity,
+and `tools/benchmark-ime-first-render.ps1` records adb-driven cold IME
+first-render baselines. The first committed SM-S938B / Android 16 run records
+five iterations with `am start -W` medians of `TotalTime` 31.0 ms and
+`WaitTime` 34.0 ms, plus benchmark-only `swiftfloris.ime.firstRenderMs`
+median 18.335469 ms.
+
 ## 4. Module layout
 
 ```
@@ -445,7 +453,7 @@ lib/color               — color math
 lib/compose             — Compose helpers
 lib/kotlin              — pure-Kotlin utilities
 lib/snygg               — Snygg theme engine
-:benchmark              — Macrobenchmark (present on disk, NOT in active settings)
+:benchmark              — Macrobenchmark + adb benchmark harness (active in settings)
 :lib:native             — placeholder for future native add-ons (commented out)
 ```
 

README.md

@@ -1,6 +1,6 @@
 # SwiftFloris
 
-![Version](https://img.shields.io/badge/version-v1.8.158-blue) ![License](https://img.shields.io/badge/license-Apache%202.0-green) ![Platform](https://img.shields.io/badge/platform-Android%208.0+-orange) ![Network](https://img.shields.io/badge/network-none-lightgrey) ![SwiftKey migration](https://img.shields.io/badge/SwiftKey%20migration-window%20closes%202026--05--31-red)
+![Version](https://img.shields.io/badge/version-v1.8.159-blue) ![License](https://img.shields.io/badge/license-Apache%202.0-green) ![Platform](https://img.shields.io/badge/platform-Android%208.0+-orange) ![Network](https://img.shields.io/badge/network-none-lightgrey) ![SwiftKey migration](https://img.shields.io/badge/SwiftKey%20migration-window%20closes%202026--05--31-red)
 
 **SwiftFloris** is a privacy-first Android keyboard, forked from FlorisBoard and pushed toward SwiftKey-class multilingual typing without the cloud. It ships under Apache-2.0, holds no `INTERNET` permission, and binds zero accounts.
 
@@ -44,7 +44,7 @@
 
 ## Highlights
 
-| Area | What's in v1.8.158 | Privacy posture |
+| Area | What's in v1.8.159 | Privacy posture |
 |------|-------------------|-----------------|
 | **Autocorrect / prediction** | SCOWL 117k English dictionary, SymSpell d1+d2, bigram + trigram next-word, capitalization-aware completions, contraction handling, instant-remember user-dictionary overlay | On-device |
 | **Multilingual typing** | Bilingual subtype presets (EN+ES / EN+FR / EN+DE), per-token Latin language identification, top-two straddle guard, sentence-local context scoring | On-device |
@@ -124,7 +124,7 @@ Project-internal docs all live in the repository:
 - [`docs/VOICE_COMMANDS.md`](docs/VOICE_COMMANDS.md) — built-in and custom voice-command grammar reference.
 - [`docs/addons/dictionary-pack-spec.md`](docs/addons/dictionary-pack-spec.md) — external dictionary-pack APK descriptor and validation contract.
 - [`IMPROVEMENT_PLAN.md`](IMPROVEMENT_PLAN.md) — execution-focused quality / UX / a11y / perf / test / delivery plan.
-- [`ROADMAP.md`](ROADMAP.md) — current and historical roadmap (v5.55).
+- [`ROADMAP.md`](ROADMAP.md) — current and historical roadmap (v5.56).
 - `RELEASE_NOTES_v*.md` — per-release notes, one file per version, in the repository root.
 
 ## Architecture & Stack
@@ -149,7 +149,7 @@ lib/color                  — color math
 lib/compose                — Compose helpers
 lib/kotlin                 — pure-Kotlin utilities
 lib/snygg                  — Snygg theme engine
-:benchmark                 — Macrobenchmark module (present on disk, not yet wired in settings)
+:benchmark                 — Macrobenchmark + adb benchmark harness (active in settings)
 :lib:native                — placeholder for future native add-ons (commented out)
 ```
 
@@ -261,13 +261,13 @@ Six Macrobenchmark trace sections are emitted from production code paths:
 - `swiftfloris.dict.load` (`loadSpecificDictionary`)
 - `swiftfloris.nlp.symspell.build` (lazy index init)
 
-Real device-number collection is tracked in [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md). The repository deliberately does not publish hand-wavy latency tables; numbers go in the benchmark doc with the device, OS build, and trace section that produced them.
+Real device-number collection is tracked in [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md). The v1.8.159 SM-S938B / Android 16 baseline records `am start -W` medians of `TotalTime` 31.0 ms and `WaitTime` 34.0 ms, plus benchmark-only `swiftfloris.ime.firstRenderMs` median 18.335469 ms. The repository deliberately does not publish hand-wavy latency tables; numbers go in the benchmark doc with the device, OS build, and trace section or log marker that produced them.
 
 ## Testing
 
 - **Unit tests:** Kotest, run with `./gradlew test`. Last reported HEAD: 998+ tests (post-v1.8.40), expanding with each release. The v1.8.47 hardening pass added defensive tests around dictionary import limits, voice-model atomic install, theme asset traversal, and quick-action serializer fallback.
 - **Visual regression:** Roborazzi 1.60.0, plugin alias active. CI runs `:app:verifyRoborazziDebug` on every push / PR as a hard gate, backed by committed baselines for the maintainer chip, SwiftKey High Contrast, Aurora Animated, and Settings -> Addons surfaces.
-- **Macrobenchmark:** trace sections wired in production hot paths; device-number capture is tracked separately.
+- **Macrobenchmark:** `:benchmark` is wired for AndroidX trace/frame runs, and the adb first-render harness records repeatable IME cold-start baselines.
 - **No-network gate:** CI verifies the absence of `INTERNET` permission on every build.
 - **Repo hygiene gate:** CI runs `scripts/check-no-root-crash-logs.sh` so root
   `hs_err_pid*.log` / `replay_pid*.log` files cannot be committed.
@@ -276,6 +276,7 @@ Real device-number collection is tracked in [`docs/BENCHMARKS.md`](docs/BENCHMAR
 
 The full release stream lives in the `RELEASE_NOTES_v*.md` files in the repository root, and on [GitHub Releases](https://github.com/SysAdminDoc/SwiftFloris/releases).
 
+- **v1.8.159** (2026-05-18) — IME first-render benchmark baseline: `:benchmark` is active again, a benchmark-only input activity drives cold IME view creation, and SM-S938B / Android 16 first-render numbers are committed under `docs/benchmark-results/`. ([notes](RELEASE_NOTES_v1.8.159.md))
 - **v1.8.158** (2026-05-18) — Accessibility manual QA notes: contributor and accessibility docs now list TalkBack traversal, key-label, candidate-row, font-scale, non-color-state, and theme/layout checks. ([notes](RELEASE_NOTES_v1.8.158.md))
 - **v1.8.157** (2026-05-18) — Non-color state indicators: shared success/progress/neutral cards and extension-import row icons make readiness, progress, cancellation, and completion visible without relying on color alone. ([notes](RELEASE_NOTES_v1.8.157.md))
 - **v1.8.156** (2026-05-18) — Theme contrast audit: bundled keyboard/candidate/dialog styles and settings warning/error/dialog palettes now have selector-level AA coverage; low-contrast enter-key variants and card secondary text were tightened. ([notes](RELEASE_NOTES_v1.8.156.md))
@@ -424,7 +425,7 @@ limitations under the License.
 
 ## Status
 
-🚀 **Active development.** Current release: **v1.8.158** (2026-05-18). Migration window for SwiftKey users closes **2026-05-31** — 13 days from this release.
+🚀 **Active development.** Current release: **v1.8.159** (2026-05-18). Migration window for SwiftKey users closes **2026-05-31** — 13 days from this release.
 
 ---
 

RELEASE_NOTES_v1.8.159.md

@@ -0,0 +1,46 @@
+# SwiftFloris v1.8.159
+
+Date: 2026-05-18
+
+## IME First-Render Benchmark Baseline
+
+This release starts Performance Instrumentation Workstream 7 by reactivating
+the benchmark module and committing the first repeatable cold IME first-render
+baseline.
+
+### Changed
+
+- Re-enabled `:benchmark` in `settings.gradle.kts` and updated the benchmark
+  module for the AGP 9 / Gradle 9 build.
+- Retargeted benchmark sources at the `.bench` app id and added shared device
+  helpers for selecting the benchmark IME and launching benchmark activities.
+- Added a benchmark-only `BenchmarkInputActivity` so adb and Macrobenchmark
+  runs can show the IME without touching production UI.
+- Added a benchmark-build-only `SwiftFlorisPerf` first-render log marker in
+  `FlorisImeService.onCreateInputView`.
+- Added `tools/benchmark-ime-first-render.ps1`, which installs the benchmark
+  APK, selects the benchmark IME, records five adb runs, restores the previous
+  input method, and writes JSON to `docs/benchmark-results/`.
+
+### Baseline
+
+Samsung SM-S938B / Android 16 (SDK 36), five iterations:
+
+- `am start -W` median `TotalTime`: 31.0 ms.
+- `am start -W` median `WaitTime`: 34.0 ms.
+- `SwiftFlorisPerf` median `swiftfloris.ime.firstRenderMs`: 18.335469 ms.
+
+Evidence: `docs/benchmark-results/baseline-2026-05-18-ime-first-render.json`.
+
+### Tests
+
+- `git diff --check` passed.
+- `.\gradlew.bat :app:assembleBenchmark :benchmark:assembleBenchmark` passed.
+- `pwsh -NoProfile -ExecutionPolicy Bypass -File .\tools\benchmark-ime-first-render.ps1 -Iterations 5` passed on device `R5CY34G070L` and restored the previous IME.
+- `.\gradlew.bat :app:testDebugUnitTest :app:lintDebug :app:assembleDebug` passed.
+
+### Definition of Done
+
+- Version bumped to `1.8.159` / code `1959`.
+- `README.md`, `ROADMAP.md`, `PROJECT_CONTEXT.md`, `ARCHITECTURE.md`,
+  `AGENTS.md`, `IMPROVEMENT_PLAN.md`, and `docs/BENCHMARKS.md` updated.