reis-mobile 0.7.3 → 0.9.0

package/skills/mobile-performance/references/android.md

@@ -0,0 +1,96 @@
+# Performance on native Android
+
+Android gives you more first-party measurement than any other mobile platform: a lab harness (Macrobenchmark), a system trace (Perfetto), and field data from every install (Android vitals). Use them in that order — reproduce in the lab, explain with a trace, confirm in the field.
+
+Deep guides already in this plugin: [`mobile-android/references/build-and-performance.md`](../../mobile-android/references/build-and-performance.md), which links the Android Studio profiler and R8 analyzer material from the Android team.
+
+## Measure
+
+```bash
+adb shell am start -W -S com.example/.MainActivity   # TotalTime / WaitTime per cold start
+adb shell dumpsys gfxinfo com.example framestats     # per-frame timings
+adb shell dumpsys meminfo com.example                # PSS breakdown
+adb shell dumpsys batterystats --charged com.example # wakeups, wake locks, jobs
+```
+
+| Question | Tool |
+|---|---|
+| Startup, frame time, memory, power in a repeatable benchmark | Macrobenchmark (`androidx.benchmark:benchmark-macro-junit4`) |
+| Cost of one function or algorithm | Microbenchmark (`androidx.benchmark:benchmark-junit4`) |
+| Where the time actually goes inside a slow frame or a slow start | System trace / Perfetto (Android Studio "Capture System Activities", or `perfetto` on device) |
+| Allocation and leak hunting | Android Studio Profiler: Memory, heap dump, and LeakCanary in debug builds |
+| Which composables recompose | Layout Inspector recomposition counts, and composition tracing in a system trace |
+| Field jank, ANRs, wakeups, crash rate | Play Console → Android vitals; `JankStats` for your own aggregation |
+| Download size | Android Studio APK Analyzer; the Play Console size report for the delivered app |
+
+## Startup
+
+Cold start cost is dominated by four things:
+
+1. **`Application.onCreate` and content providers.** Every library that self-initializes through a `ContentProvider` runs before your first activity. Use `androidx.startup` (`App Startup`) to sequence and lazily defer initializers, and audit the merged manifest for providers you did not add yourself.
+2. **Dependency graph construction.** Hilt/Dagger graph building, a Room database opened synchronously, `SharedPreferences` read on the main thread (use `DataStore`, which is async by design).
+3. **Missing Baseline Profiles.** Without them, the hot startup and scroll paths run interpreted until JIT catches up. Generate them with `androidx.benchmark`'s `BaselineProfileRule`, ship them through `androidx.profileinstaller`, and add a Startup Profile so the DEX layout matches the startup path. This is often the single largest startup win and needs no application code change.
+4. **A first frame that is not the usable frame.** Call `reportFullyDrawn()` (or `FullyDrawnReporter` when several components must finish) so the platform, Macrobenchmark and Play vitals measure time to *usable* content, not time to a spinner.
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class StartupBenchmark {
+    @get:Rule val rule = MacrobenchmarkRule()
+
+    @Test fun coldStart() = rule.measureRepeated(
+        packageName = "com.example",
+        metrics = listOf(StartupTimingMetric()),
+        iterations = 10,
+        startupMode = StartupMode.COLD,
+    ) {
+        pressHome()
+        startActivityAndWait()
+    }
+}
+```
+
+`StartupTimingMetric` reports `timeToInitialDisplayMs` and, when `reportFullyDrawn()` is called, `timeToFullDisplayMs`.
+
+## Rendering and recomposition
+
+With `FrameTimingMetric` in Macrobenchmark you get `frameDurationCpuMs` percentiles and `frameOverrunMs` (how far past the deadline a frame went) over a scripted scroll. Anything with a positive P90 `frameOverrunMs` is visible jank.
+
+Compose-specific causes, in the order they usually bite:
+
+- **Unstable parameters.** A composable whose parameter type the compiler cannot prove stable is never skipped. `List<T>` is unstable; `kotlinx.collections.immutable`'s `ImmutableList`, or a `@Immutable`/`@Stable` annotated holder, is stable. Enable the compiler's stability report to see which composables are skippable.
+- **Reading state too high.** Reading a `MutableState` in a parent recomposes the parent and everything it emits. Pass a lambda (`() -> Int`) instead of a value, or read it in the smallest child — deferred reads are the standard Compose fix.
+- **A derived value recomputed on every frame.** `derivedStateOf` recomputes only when the result changes, which is what you want for `listState.firstVisibleItemIndex > 0`.
+- **Lambdas recreated each composition** captured into `remember`-less callbacks, forcing children to recompose.
+- **Backwards writes** — writing state during composition — which force an immediate extra pass.
+
+For Views: a deep hierarchy, `ConstraintLayout` nested inside `ConstraintLayout`, `wrap_content` in a `RecyclerView` row forcing remeasure, `notifyDataSetChanged` where `DiffUtil`/`ListAdapter` would update in place, and overdraw (Developer options → Debug GPU overdraw).
+
+## Memory
+
+- A heap dump after the journey, repeated three times, diffed. LeakCanary in debug catches the common lifecycle leaks: an `Activity`/`Fragment` captured in a static field, a listener never unregistered, an inner-class `Handler`, a coroutine launched outside a lifecycle scope.
+- Bitmaps dominate mobile heaps. Load at the target size (`BitmapFactory.Options.inSampleSize`, or let Coil/Glide size the request from the view). A full-resolution camera image decoded into a thumbnail is the classic OOM.
+- `onTrimMemory`/`ComponentCallbacks2` is a signal, not a fix, but caches should honour it.
+- `MemoryUsageMetric` in Macrobenchmark gives a comparable number per run for CI.
+
+## Battery
+
+See [background.md](background.md) for the scheduling rules. On Android specifically, Play Console → Android vitals reports **excessive wakeups** and **stuck partial wake locks** for your installed base; both are actionable without reproducing anything locally. `PowerMetric` in Macrobenchmark measures energy per benchmark on supported devices, and Battery Historian parses a `batterystats` dump into a timeline.
+
+## App size
+
+- `isMinifyEnabled = true` and `isShrinkResources = true` on release, with R8 full mode, plus per-ABI/density/language splits through the App Bundle — Play generates them automatically from an AAB.
+- APK Analyzer shows the DEX method counts and resource weight; compare two builds directly in it.
+- Check the size delta in CI by building the release AAB and comparing the `.aab` size with the previous baseline. Set the threshold as a percentage, since ordinary feature work moves it slowly.
+
+## Regression detection in CI
+
+Macrobenchmark emits JSON (`*-benchmarkData.json`) with the metric percentiles. Run it on a fixed emulator image or a device farm profile, store the JSON per build, and compare `timeToInitialDisplayMs` P50/P90 and `frameOverrunMs` P90 against the previous baseline. Microbenchmark output is more sensitive to CPU throttling; pin the device and discard the first iterations.
+
+## Official documentation
+
+- App startup time: https://developer.android.com/topic/performance/vitals/launch-time
+- Macrobenchmark: https://developer.android.com/topic/performance/benchmarking/macrobenchmark-overview
+- Baseline Profiles: https://developer.android.com/topic/performance/baselineprofiles/overview
+- Compose performance: https://developer.android.com/develop/ui/compose/performance
+- Android vitals: https://developer.android.com/topic/performance/vitals
+- Capture a system trace: https://developer.android.com/topic/performance/tracing

package/skills/mobile-performance/references/background.md

@@ -0,0 +1,87 @@
+# Background execution and battery
+
+Battery is not something an app spends; it is something the app makes the *device* spend by waking it, holding it awake, using the radio, or keeping a sensor on. Both platforms now assume that background work is a privilege they grant, not a thread you own — code written as if a background task runs whenever it wants will be deferred, throttled or killed, and the resulting bug report reads as "sync does not work", not as "battery".
+
+## The rule that covers both platforms
+
+**Say what the work needs, let the system choose when.** Declare the constraints (network, charging, idle, deadline), make the work idempotent and resumable, and let the scheduler batch it with other apps' work so the device wakes once instead of five times. Every API below is a variation on that.
+
+**Never poll on a timer.** A periodic wake to ask "is there anything new?" is the single most expensive pattern in mobile, and it is almost always replaceable by a push message that tells the app there *is* something new (see [mobile-firebase](../../mobile-firebase/SKILL.md) for FCM and APNs delivery).
+
+## Android
+
+| Need | API |
+|---|---|
+| Deferrable work that must survive process death and reboot | `WorkManager` — `OneTimeWorkRequest` / `PeriodicWorkRequest` with `Constraints` |
+| Work the user is actively waiting for, right now | `setExpedited(...)` on a `WorkRequest`, or a foreground service with the right type |
+| Work tied to a user-visible ongoing task (playback, navigation, an upload the user started) | A foreground service with a declared `foregroundServiceType` and a notification |
+| An exact time (an alarm clock, a calendar reminder) | `AlarmManager.setExactAndAllowWhileIdle` — requires the exact-alarm permission on recent versions, and Google Play restricts which apps may declare it |
+| A reaction to a server event | FCM data message, high priority only when it is genuinely time-critical |
+
+Rules that break naive code:
+
+- **Doze and App Standby.** With the screen off and the device still, network access and alarms are deferred to maintenance windows; rarely used apps land in restrictive standby buckets with tighter job and alarm quotas. Periodic `WorkManager` work has a minimum interval of 15 minutes and is never exact.
+- **Background start restrictions.** An app in the background generally cannot start a foreground service; the allowed cases are enumerated per platform version. Code that "starts a service when the push arrives" is the usual casualty — use expedited work instead.
+- **Foreground service types are enforced.** Recent Android versions require a declared `foregroundServiceType`, require a matching permission, and apply timeouts to some types (`dataSync` and `mediaProcessing` among them). Check the behaviour-changes page for the `targetSdk` you compile against before relying on a long-running service.
+- **Wake locks.** A partial wake lock never released is reported by Play Console → Android vitals as a stuck wake lock, against your installed base. `WorkManager` holds the wake lock for you; taking one manually is almost always a bug.
+- **Batch the radio.** Each transmission wakes the radio and keeps it in a high-power state for seconds afterwards. Batch analytics, logs and telemetry into one flush with a deadline rather than sending per event.
+
+Diagnose with `adb shell dumpsys batterystats --charged <package>` (Battery Historian renders it), and read the Excessive Wakeups and Stuck Partial Wake Locks metrics in Android vitals — those are field data from real installs, which no local run reproduces.
+
+## iOS
+
+| Need | API |
+|---|---|
+| Short refresh when the system decides the app is likely to be used | `BGAppRefreshTaskRequest` via `BGTaskScheduler` — seconds of runtime |
+| Longer maintenance (database compaction, ML model update, bulk upload) | `BGProcessingTaskRequest`, typically run while charging and idle |
+| A download or upload that must continue after the app is suspended or terminated | `URLSession` with a **background** configuration, which the system continues out of process |
+| Finish a short piece of work when the user leaves the app | `UIApplication.beginBackgroundTask` — roughly half a minute, not a general mechanism |
+| React to a server event | APNs; a background (`content-available`) push wakes the app opportunistically and is rate-limited, a user-visible notification is not |
+
+Rules that break naive code:
+
+- Every background identifier must be listed in `Info.plist` under `BGTaskSchedulerPermittedIdentifiers`, registered before the app finishes launching, and matched by the right `UIBackgroundModes` capability. A missing registration is a launch-time exception, not a silent no-op.
+- The system decides *whether and when*. There is no guaranteed schedule, and an app the user rarely opens may get no background time at all. Schedule the next request at the end of each run, and treat every run as "do as much as you can, then checkpoint".
+- Always set the task's `expirationHandler` and call `setTaskCompleted(success:)`. A task that neither finishes nor expires cleanly costs the app future background time.
+- Background `URLSession` delivers completion to the app delegate after relaunch: the download handler must work with no UI and no in-memory state.
+- Xcode Organizer and MetricKit report battery and disk-write metrics per release from real devices; `MXAppExitMetric` shows terminations. These are the iOS equivalent of Android vitals.
+
+## Flutter
+
+Flutter's own isolate model does not extend the platform's background allowances — the constraints above still apply, and the plugin you choose is a wrapper over `WorkManager` and `BGTaskScheduler`.
+
+- Background work runs in a **separate isolate** with its own memory: no access to the UI isolate's state, no plugin registry unless the entry point registers it (`@pragma('vm:entry-point')` on the callback, and a background isolate binary messenger for plugins that need one).
+- Persist everything the background run produces; the UI isolate will not see in-memory results.
+- Verify on both platforms separately. A background plugin that works on Android frequently does nothing on iOS, because Android's 15-minute periodic work has no iOS equivalent.
+- For downloads, prefer a plugin backed by the platform's own background transfer (`URLSession` background configuration / `DownloadManager` or `WorkManager`) over a Dart `HttpClient` call in a background isolate, which stops when the process is suspended.
+
+## React Native and Expo
+
+- Expo exposes background work through `expo-task-manager` plus a background task/fetch module; the module name and API have changed across SDK versions, so check the docs for the SDK the project pins before writing code against it.
+- Bare React Native uses Headless JS on Android (a JS task run without a UI, started from a native service or a push) and the `BGTaskScheduler`/background-`URLSession` bridges on iOS, usually through a community package.
+- The JavaScript runtime is not guaranteed to exist in the background. Any handler must boot its own dependencies, must not assume the navigation state or a store is hydrated, and must finish quickly.
+- Both platforms' limits apply unchanged: a JS background handler does not get more runtime than the native API it is wrapping.
+
+## Kotlin Multiplatform
+
+Scheduling is a host responsibility: `WorkManager` in `androidMain`, `BGTaskScheduler` in the iOS host app. Put the *work itself* — the sync algorithm, the queue drain, the conflict resolution — in `commonMain` behind a suspend function, and let each host's scheduler call it. That keeps the retry and idempotency logic in one place and tested once ([mobile-offline-sync](../../mobile-offline-sync/SKILL.md) covers the queue design).
+
+## Reviewing background code
+
+- [ ] Every periodic job has a justification that a push message cannot satisfy.
+- [ ] Work is idempotent: running it twice, or being killed halfway, leaves correct state.
+- [ ] Constraints are declared (network type, charging, battery not low) instead of checked in code after the wake.
+- [ ] Retries use exponential backoff with a cap and a jitter, not a fixed short interval.
+- [ ] Network calls are batched; analytics and logs are flushed with a deadline, not per event.
+- [ ] Location, Bluetooth scanning and sensors are started for a bounded window and explicitly stopped, at the coarsest accuracy that works.
+- [ ] The app degrades correctly when the system grants no background time at all — the user still gets correct data on next launch.
+
+## Official documentation
+
+- Android background work: https://developer.android.com/develop/background-work/background-tasks
+- WorkManager: https://developer.android.com/topic/libraries/architecture/workmanager
+- Android foreground service types: https://developer.android.com/develop/background-work/services/fgs/service-types
+- Optimize for Doze and App Standby: https://developer.android.com/training/monitoring-device-state/doze-standby
+- BGTaskScheduler: https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler
+- Using background tasks to update your app: https://developer.apple.com/documentation/backgroundtasks/using-background-tasks-to-update-your-app
+- Downloading files in the background: https://developer.apple.com/documentation/foundation/url_loading_system/downloading_files_in_the_background

package/skills/mobile-performance/references/flutter.md

@@ -0,0 +1,101 @@
+# Performance in Flutter
+
+Flutter splits every frame across two threads: the **UI thread** runs `build`, layout and paint (Dart), and the **raster thread** turns the resulting layer tree into GPU commands. A dropped frame belongs to one of them, and the fix is different. DevTools tells you which.
+
+Deep guides already in this plugin: [`mobile-flutter/references/performance.md`](../../mobile-flutter/references/performance.md), with [`app-size.md`](../../mobile-flutter/references/performance/app-size.md) and [`concurrency.md`](../../mobile-flutter/references/performance/concurrency.md).
+
+## Measure
+
+**Always in profile mode.** Debug builds run the Dart VM in JIT with assertions and unoptimized widget code; numbers from `flutter run` in debug are meaningless.
+
+```bash
+flutter run --profile                 # on a physical device, never an emulator, for frame data
+flutter build apk --analyze-size      # or appbundle / ipa / macos
+flutter build apk --split-debug-info=build/symbols --obfuscate
+```
+
+| Question | Tool |
+|---|---|
+| Which thread drops frames | DevTools → Performance → Frames chart (blue = UI, teal = raster) |
+| What runs inside a slow frame | DevTools → Performance → Timeline events, then the CPU profiler for the Dart stack |
+| Which widgets rebuild, and how often | DevTools → Performance → Track widget builds; `debugProfileBuildsEnabled`, `debugPrintRebuildDirtyWidgets` |
+| What repaints | `debugRepaintRainbowEnabled`, and DevTools' "Highlight repaints" |
+| Memory growth and leaks | DevTools → Memory: take a snapshot after the journey, repeat it, diff the retained set |
+| Startup cost | `flutter run --profile --trace-startup`, which writes `start_up_info.json` with `timeToFirstFrameMicros` and `timeToFrameworkInitMicros` |
+| Size | `--analyze-size` output opened in DevTools → App size |
+
+Mark your own expensive spans so they appear on the timeline:
+
+```dart
+import 'dart:developer' as developer;
+
+final task = developer.TimelineTask()..start('parseOrders');
+final orders = parseOrders(payload);
+task.finish();
+```
+
+## Rebuilds: the usual causes
+
+- **A `setState`, `notifyListeners` or stream emission high in the tree.** Move the state down to the smallest widget that needs it, or split the widget so only the changing part rebuilds.
+- **`const` missing.** A `const` constructor lets the framework skip the subtree entirely. Enable `prefer_const_constructors` in `analysis_options.yaml`.
+- **Rebuilding a constant child inside an animation.** Pass it through the `child:` parameter of `AnimatedBuilder`, `ValueListenableBuilder` or `StreamBuilder` so it is built once and reused.
+- **A selector that returns a new object every time.** `context.watch<Cart>()` rebuilds on every cart change; `context.select((Cart c) => c.itemCount)` rebuilds only when the count changes. The same applies to `BlocSelector`, Riverpod's `select`, and any `buildWhen`/`listenWhen`.
+- **Equality that never holds.** A state class without `==`/`hashCode` (or a freezed/equatable equivalent) makes every emission look new. A `List` field compares by identity: copy it or use an immutable collection.
+- **Work in `build`.** `build` can be called many times per second. No parsing, no sorting, no `Future` creation, no controller construction inside it.
+
+## Lists
+
+- `ListView.builder` / `GridView.builder` / `SliverList` with a builder — never a `ListView(children: [...])` over a long collection, which builds every child.
+- Give `itemExtent` (or `prototypeItem`) when rows have a fixed height: it lets the framework skip measuring and makes scrolling to an offset O(1).
+- Stable `ValueKey`s on items so reorders and inserts do not rebuild everything.
+- Wrap an item in `RepaintBoundary` only when it repaints independently of its neighbours (an animating row in a static list). Applied indiscriminately it costs memory and a layer per row.
+- `AutomaticKeepAlive` keeps offscreen items alive: useful for a video or a form, expensive for a plain row.
+
+## Painting
+
+- `Opacity` over a large subtree allocates an offscreen layer. Prefer `AnimatedOpacity` on a leaf, `Color.withValues(alpha: ...)`, or `FadeTransition`.
+- `ClipRRect` with antialiasing and `Clip.antiAliasWithSaveLayer` is the expensive variant; `Clip.hardEdge` is cheap. A rounded container is cheaper as a `BoxDecoration` with `borderRadius` than as a clip.
+- Shadows and blurs (`BackdropFilter`, `ImageFiltered`) scale with the area covered. Constrain them.
+- Decode images at the size they are displayed: `cacheWidth`/`cacheHeight` on `Image.asset`/`Image.network`, or `ResizeImage`. A 4000 px photo in a 100 px avatar costs ~64 MB of decoded pixels.
+- `SizedBox` instead of `Container` when you only need space; `Container` with no decoration still builds a `LimitedBox`/`ConstrainedBox` chain.
+
+## Off the UI thread
+
+Anything that takes more than a frame belongs in an isolate. `compute()` covers one-shot work (JSON parsing, image manipulation, crypto); `Isolate.run` is the modern equivalent for a single call; a long-lived worker isolate with `ReceivePort` covers repeated work. Remember that only transferable values cross the boundary, and that plugins that need the platform thread cannot be called from a background isolate unless they use a background isolate binary messenger. See [`concurrency.md`](../../mobile-flutter/references/performance/concurrency.md).
+
+## Startup
+
+- Nothing blocking in `main()` before `runApp`. `WidgetsFlutterBinding.ensureInitialized()` plus a single fast await is the ceiling; move plugin initialization, remote config fetches and database opens behind the first frame or into a splash state.
+- Deferred loading (`deferred as`) splits rarely used code on web; on mobile it does not remove the code from the binary, so it is not a size fix.
+- Confirm which renderer the project actually uses (`flutter --version` and the release notes for the pinned channel). Impeller and Skia have different shader-compilation behaviour, and shader jank fixes that apply to one do not apply to the other.
+
+## Regression detection in CI
+
+`integration_test` produces a machine-readable timeline summary:
+
+```dart
+// integration_test/scroll_perf_test.dart
+final binding = IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+testWidgets('feed scroll stays within budget', (tester) async {
+  app.main();
+  await tester.pumpAndSettle();
+
+  await binding.watchPerformance(() async {
+    await tester.fling(find.byType(ListView), const Offset(0, -500), 3000);
+    await tester.pumpAndSettle();
+  }, reportKey: 'feed_scroll');
+});
+```
+
+Run it with `flutter drive` (or `flutter test integration_test` with a driver that writes the report) and assert on the emitted summary: `average_frame_build_time_millis`, `worst_frame_build_time_millis`, `missed_frame_build_budget_count` and the raster equivalents. Store the numbers per build and compare against the previous baseline; fail the job when the worst frame or the missed-budget count crosses the threshold you set in §5 of the skill.
+
+For size, run `flutter build --analyze-size` in CI, extract the total from the JSON it writes, and compare with the baseline.
+
+## Official documentation
+
+- Flutter performance best practices: https://docs.flutter.dev/perf/best-practices
+- Flutter performance profiling: https://docs.flutter.dev/perf/ui-performance
+- DevTools performance view: https://docs.flutter.dev/tools/devtools/performance
+- Measuring app size: https://docs.flutter.dev/perf/app-size
+- Integration test performance profiling: https://docs.flutter.dev/cookbook/testing/integration/profiling

package/skills/mobile-performance/references/ios.md

@@ -0,0 +1,82 @@
+# Performance on native iOS
+
+iOS performance work is mostly main-thread work. The main thread renders, handles touch and runs SwiftUI/UIKit updates; anything that blocks it becomes a hitch, a hang or a watchdog termination. Instruments explains a single run, MetricKit and Xcode Organizer explain the installed base.
+
+Related material already in this plugin: [`mobile-ios/references/performance-release.md`](../../mobile-ios/references/performance-release.md).
+
+## Measure
+
+**Release configuration, physical device.** The Simulator has a different GPU path and no thermal or memory pressure; debug builds skip optimization and enable extra checks.
+
+| Question | Tool |
+|---|---|
+| Where CPU time goes | Instruments → Time Profiler, with "Record Waiting Threads" to catch blocking |
+| Why a scroll drops frames | Instruments → Animation Hitches (hitch time per frame, scroll and commit phases) |
+| What SwiftUI is doing and why a view updated | Instruments → SwiftUI template; `Self._printChanges()` inside `body` in debug |
+| Main thread blocked | Instruments → Hangs; the Thread Performance Checker in a debug run |
+| Allocations, growth and leaks | Instruments → Allocations (mark generations around the journey) and Leaks; the Memory Graph Debugger for retain cycles |
+| Launch cost | Instruments → App Launch; `DYLD_PRINT_STATISTICS=1` for pre-main dynamic linking time |
+| Field data from real users | MetricKit (`MXMetricManager`), and Xcode Organizer → Launch Time, Hangs, Memory, Disk Writes, Battery |
+| Download size | App Store Connect → App Store → the build's app size report, per device variant |
+
+Apple treats the main thread being blocked for more than about 250 ms as a hang; Organizer reports it as a hang rate per hour of use. A scroll hitch is measured as *hitch time ratio* — milliseconds of hitch per second of scrolling.
+
+## Launch
+
+Launch splits into pre-main (dynamic linker, runtime setup) and post-main (your `AppDelegate`/`App` initialization up to the first usable frame). Apple's guidance is to finish launch in roughly 400 ms, before the system's launch animation ends.
+
+- **Pre-main:** the number of dynamically linked frameworks dominates. Merge small dynamic frameworks into static libraries or use mergeable libraries; remove `+load` methods and heavy static initializers (`__attribute__((constructor))`, non-lazy Swift globals with side effects).
+- **Post-main:** every SDK initialized synchronously in `application(_:didFinishLaunchingWithOptions:)` is launch cost. Defer analytics, remote config, crash-symbol upload and network prefetch to after the first frame. Read persisted state asynchronously; `UserDefaults` is cheap but a Core Data or SwiftData stack opened on the main queue is not.
+- **Measure the right end point.** `os_signpost` a span from `didFinishLaunching` to the moment content is on screen, and query it in a UI test with `XCTOSSignpostMetric`.
+
+```swift
+import XCTest
+
+final class LaunchTests: XCTestCase {
+    func testLaunchPerformance() {
+        measure(metrics: [XCTApplicationLaunchMetric()]) {
+            XCUIApplication().launch()
+        }
+    }
+}
+```
+
+`measure(metrics:)` records a baseline in the test bundle and fails the test when a later run regresses past the configured deviation — this is the cheapest regression gate on iOS.
+
+## SwiftUI updates
+
+- **Identity drives everything.** A view whose identity changes is torn down and rebuilt; a `ForEach` over indices instead of stable `id`s rebuilds every row on any change. Use `Identifiable` with an id that survives a refresh.
+- **Narrow what `body` observes.** With `@Observable`, SwiftUI tracks the exact properties read inside `body`; reading a whole model object where one property is needed widens the dependency. With `ObservableObject`, every `@Published` change invalidates every observer — split the object instead.
+- `Self._printChanges()` at the top of `body` prints which dependency caused the update. It is the fastest way to answer "why did this redraw".
+- **Lazy containers for long content:** `LazyVStack`/`LazyHStack` inside a `ScrollView`, or `List`. A plain `VStack` in a `ScrollView` builds every row.
+- **`AnyView` and heavy type erasure** defeat structural identity and the diffing fast path; prefer `@ViewBuilder` and generics.
+- **Expensive work in `body`.** `body` may run many times per frame. Format dates, sort and filter outside it, in the model.
+
+For UIKit: cell reuse (`dequeueReusableCell`), self-sizing cells with cached heights, `UICollectionViewDiffableDataSource` over `reloadData`, image decoding off the main thread (`UIImage.prepareForDisplay`/`preparingForDisplay`), and avoiding `layoutIfNeeded` inside `layoutSubviews`.
+
+## Memory
+
+- Retain cycles are the dominant leak: a closure capturing `self` strongly in a long-lived object, a delegate declared `strong`, a `Timer` or `NotificationCenter` observer never invalidated, a `Task` that outlives its owner. `[weak self]` in escaping closures and the Memory Graph Debugger's cycle detection cover most of it.
+- Images: decode at display size (`UIGraphicsImageRenderer`, `prepareThumbnail(of:)`, or `ImageIO` with `kCGImageSourceThumbnailMaxPixelSize`). Full-resolution decoding into a small view is the standard memory spike.
+- `MXAppExitMetric` from MetricKit tells you how often users' apps were terminated for memory pressure in the field — the only reliable signal that the footprint is too large on the devices you actually ship to.
+
+## Concurrency and the main thread
+
+- `@MainActor` isolates UI state; work that is not UI should not be on it. An `actor` or a detached `Task` with an explicit priority keeps parsing and I/O off the main thread.
+- A synchronous call into a `DispatchQueue.sync`, a `NSLock`, or an `await` on an actor already busy on the main thread all produce a hang. The Hangs instrument names the blocking frame.
+- Background `URLSession` configurations continue transfers after suspension; ordinary sessions do not. See [background.md](background.md).
+
+## Regression detection in CI
+
+- `XCTMetric` based tests (`XCTApplicationLaunchMetric`, `XCTClockMetric`, `XCTMemoryMetric`, `XCTOSSignpostMetric`) with committed baselines fail the build on regression. Run them on a pinned simulator or device model; baselines are per-device.
+- Track binary size per build from the archive and compare against the previous baseline.
+- Feed MetricKit payloads into your backend so launch, hang and memory metrics have a per-release series. See [mobile-observability](../../mobile-observability/SKILL.md).
+
+## Official documentation
+
+- Improving your app's performance: https://developer.apple.com/documentation/xcode/improving-your-app-s-performance
+- Reducing your app's launch time: https://developer.apple.com/documentation/xcode/reducing-your-app-s-launch-time
+- Understanding hangs in your app: https://developer.apple.com/documentation/xcode/understanding-hangs-in-your-app
+- Analyzing responsiveness issues: https://developer.apple.com/documentation/xcode/analyzing-responsiveness-issues-in-your-shipping-app
+- MetricKit: https://developer.apple.com/documentation/metrickit
+- Performance tests with XCTest: https://developer.apple.com/documentation/xctest/performance-tests

package/skills/mobile-performance/references/kotlin-multiplatform.md

@@ -0,0 +1,62 @@
+# Performance in Kotlin Multiplatform
+
+A KMP performance problem is either **shared Kotlin cost**, which shows up on both targets, or a **target-specific consequence** — the Kotlin/Native binary on iOS, the interop boundary, or the host UI. Deciding which comes first is the whole job: optimizing shared code that is not the bottleneck is wasted work, and so is profiling the Android host for a cost that lives in `commonMain`.
+
+Related material already in this plugin: [`mobile-kmp/references/build-performance.md`](../../mobile-kmp/references/build-performance.md) and [`source-sets.md`](../../mobile-kmp/references/source-sets.md).
+
+## 1. Split shared cost from host cost
+
+Run the same journey on both hosts and compare:
+
+| Observation | Where the cost lives |
+|---|---|
+| Slow on Android and iOS, similar magnitude | Shared Kotlin: algorithm, serialization, database access in `commonMain` |
+| Slow only on iOS | Kotlin/Native: memory management, the Swift/Kotlin bridge, a suspend function crossing into Swift, framework initialization |
+| Slow only on Android | The Android host: Compose recomposition, main-thread work in the ViewModel, `ContentProvider` initializers |
+| Both slow, different symptoms | Two problems. Fix them separately |
+
+Then profile with the host's own tools — there is no KMP profiler. Android Studio Profiler and Macrobenchmark for the Android host ([android.md](android.md)); Instruments for the iOS host ([ios.md](ios.md)), where Kotlin frames appear once the framework's dSYM is available to the trace.
+
+Benchmark the shared code directly where you can: `kotlinx-benchmark` runs the same benchmark on JVM and Native targets, which is the only way to compare the two compilers' output for your algorithm rather than guessing.
+
+## 2. The interop boundary
+
+Every call from Swift into the generated framework crosses a bridge. One call per frame is free; one call per list row per frame is not.
+
+- **Batch the crossing.** Return a whole page of prepared view state in one call instead of exposing a getter per field. The shared layer should expose data already shaped for the screen.
+- **Suspend functions and `Flow` become callbacks in Swift.** Each emission crosses the boundary and hops a dispatcher. A `Flow` that emits per keystroke from shared code into SwiftUI is a per-keystroke bridge crossing plus a SwiftUI update — debounce or conflate in shared code, not in Swift.
+- **Collections cross by conversion.** A Kotlin `List` handed to Swift is bridged; a large list converted on every access is a hidden O(n) per call. Hold the reference, do not re-fetch.
+- **Objective-C interop erases generics and sealed hierarchies**, which pushes Swift callers into exhaustive `switch`es over erased types and sometimes into defensive copies. Design a flat, explicitly-typed API surface at the boundary.
+
+## 3. Kotlin/Native specifics
+
+- The current Kotlin/Native memory manager removes the old freezing rules, so shared mutable state across threads is allowed — but objects still cross into Objective-C autorelease pools, and retain cycles between a Kotlin object and a Swift closure leak exactly like they do in pure Swift. Break them with `[weak self]` on the Swift side and explicit cancellation on the Kotlin side.
+- **Framework initialization is launch cost on iOS.** Anything in a Kotlin top-level property with an initializer, or in a Koin/DI module built at framework load, runs before your first screen. Keep it lazy.
+- **Framework size** counts against the app's download size. Check `isStatic`, dead-code elimination and whether you export more modules than the host actually calls (`export(...)` in the framework block pulls whole modules into the public API and prevents their elimination).
+- Release builds only. Kotlin/Native debug binaries are dramatically slower than release ones, and a "KMP is slow" report measured on a debug framework is a measurement bug.
+
+## 4. Shared code that is usually the bottleneck
+
+- **Serialization.** `kotlinx.serialization` over a large payload on the main dispatcher blocks both hosts. Parse on `Dispatchers.Default`, and parse once — not per screen.
+- **Database access.** SQLDelight queries on the calling thread; map rows lazily and do not materialize a whole table to display twenty rows.
+- **Flow operators.** An unconfined chain of `map`/`combine` re-running on every upstream emission multiplies work across the boundary. `distinctUntilChanged`, `conflate` and `stateIn` with a sharing policy bound to the host lifecycle keep it bounded.
+- **`expect`/`actual` asymmetry.** A cheap JVM implementation and an expensive Native one for the same declaration produces the "slow only on iOS" case above. Measure both actuals.
+
+## 5. Compose Multiplatform UI
+
+When the UI is shared, the Compose performance rules in [android.md](android.md) apply unchanged — stability of parameters, deferred state reads, lazy layouts, `derivedStateOf`. What changes is measurement: the Android host gives you Layout Inspector recomposition counts and composition tracing; on iOS you have Instruments' time profile with Kotlin frames and no recomposition counter, so validate recomposition behaviour on Android and confirm the frame result on iOS.
+
+## 6. Regression detection in CI
+
+- Macrobenchmark on the Android host guards startup and frame time for the shared stack ([android.md](android.md)).
+- `XCTApplicationLaunchMetric` on the iOS host guards framework initialization cost ([ios.md](ios.md)).
+- `kotlinx-benchmark` on JVM and Native guards the shared algorithms themselves, and is the only gate that fails for a shared-code regression before either host notices.
+- Track the produced framework size and the Android AAB size per build; an `export(...)` added to the framework block can move both without any UI change.
+
+## Official documentation
+
+- Kotlin Multiplatform documentation: https://kotlinlang.org/docs/multiplatform.html
+- Kotlin/Native memory management: https://kotlinlang.org/docs/native-memory-manager.html
+- Swift/Objective-C interop: https://kotlinlang.org/docs/native-objc-interop.html
+- kotlinx-benchmark: https://github.com/Kotlin/kotlinx-benchmark
+- Compose Multiplatform: https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-multiplatform-and-jetpack-compose.html

package/skills/mobile-performance/references/react-native.md

@@ -0,0 +1,85 @@
+# Performance in React Native and Expo
+
+A React Native frame crosses three execution contexts: the **JavaScript thread** (your React code), the **native UI thread**, and — with the New Architecture — the shadow tree and Fabric's rendering pipeline. A slow app is slow in one of them, and the fix differs. Identify the thread first.
+
+Related material already in this plugin: [`mobile-rn/references/performance-release.md`](../../mobile-rn/references/performance-release.md).
+
+## Measure
+
+**Release build, physical device, Hermes enabled.** A Metro dev build carries the dev bundle, React strict-mode double renders, and the bridge dev listeners; its numbers are not the shipped app's.
+
+```bash
+npx react-native run-android --mode=release
+npx expo run:ios --configuration Release
+```
+
+| Question | Tool |
+|---|---|
+| Which React components render, and why | React DevTools Profiler (React Native DevTools), "Highlight updates" |
+| JavaScript CPU time | Hermes sampling profiler via React Native DevTools → Performance, or `.cpuprofile` capture |
+| Frame drops and native thread cost | The platform tools: Perfetto/system trace on Android, Instruments on iOS (see [android.md](android.md) and [ios.md](ios.md)) |
+| Startup cost breakdown | `performance.now()` marks around module require and first render; on Android, `adb shell am start -W` for the whole process |
+| Bundle size and what is in it | `npx react-native bundle --platform android --dev false --sourcemap-output bundle.map` then a source-map explorer; `npx expo export` for Expo |
+
+Instrument your own spans, and keep them in release behind a flag, so the same marks exist in the field:
+
+```js
+const start = performance.now();
+const parsed = parseOrders(payload);
+track('parse_orders_ms', performance.now() - start);
+```
+
+## The JavaScript thread
+
+- **Re-renders are the default problem.** A context value recreated each render, an inline object/array/function prop, or a parent that re-renders on every keystroke will cascade. `React.memo` on the child plus `useCallback`/`useMemo` on the props, or moving the state down so the parent is not involved at all.
+- **Selectors, not whole stores.** Subscribing to an entire Zustand/Redux store re-renders on every change; subscribe to the slice. With React Query/TanStack Query, `select` narrows what a component observes.
+- **Never block JS.** JSON parsing of a large payload, sorting thousands of rows, crypto, image manipulation — these freeze every touch handler. Move them to the native side, a worklet, or chunk them across frames with `InteractionManager.runAfterInteractions` and batched state updates.
+- **Text input and animation state** should not live in React state when they change per frame. Use `Animated` with `useNativeDriver: true`, or Reanimated shared values, so the animation runs on the UI thread and never touches JS.
+
+## Lists
+
+`FlatList`/`SectionList` are virtualized but still render through React. The props that matter:
+
+| Prop | Why |
+|---|---|
+| `keyExtractor` | Stable keys; without them React remounts rows on any change |
+| `getItemLayout` | Skips measurement, enables instant `scrollToIndex` — only valid for fixed-height rows |
+| `initialNumToRender` | Keep it to what a screen actually shows; the default renders more |
+| `maxToRenderPerBatch` / `updateCellsBatchingPeriod` | Trade blank space during fast scrolls against JS work per batch |
+| `windowSize` | How many screens are kept mounted around the viewport |
+| `removeClippedSubviews` | Detaches offscreen native views; helps on Android, test it — it has edge cases with absolute positioning |
+
+Memoize the row component (`React.memo`) and make `renderItem` stable. If the list is long and rows are heavy, `@shopify/flash-list` recycles native views instead of mounting new ones and is usually a larger win than tuning the props above.
+
+## Images
+
+- Size the remote image on the server or CDN; downloading a 3000 px JPEG for a 120 px avatar costs bandwidth, decode time and memory on every row.
+- `expo-image` (or `react-native-fast-image` on bare projects) adds disk/memory caching and progressive loading that the core `Image` does not.
+- Set explicit `width`/`height` so layout does not reflow when the image resolves.
+
+## Startup
+
+- **Enable Hermes** (the default in current React Native). Hermes precompiles to bytecode, which removes JS parse time at launch.
+- **Enable the New Architecture** where the project's dependencies support it: Fabric and TurboModules remove the asynchronous bridge serialization, and TurboModules load lazily instead of all at startup.
+- **Audit top-level requires.** Every module imported at the entry point is evaluated at launch. Lazy-import screens through the navigator's lazy options, and defer SDK initialization until after the first screen.
+- **Native side still counts.** Time to first JS frame includes the Android `Application.onCreate` and the iOS `didFinishLaunching` path; see the native references.
+
+## Bundle and app size
+
+- Inspect the release source map with a source-map explorer to find the heavy dependency. Moment/lodash-style full imports, duplicated polyfills and an icon font shipped whole are the usual entries.
+- On Android, enable Proguard/R8 for the release variant and ship an App Bundle. On iOS, check the App Store Connect size report per device variant.
+- Expo: `expo-updates` OTA payloads are downloaded by every user — size matters there too, and an update that grows the bundle grows every launch that has to apply it.
+
+## Regression detection in CI
+
+- Wrap a scripted journey in Detox or Maestro on a pinned device/emulator, capture the platform's frame data (see [android.md](android.md) and [ios.md](ios.md)), and compare percentiles against a baseline.
+- Assert bundle size in CI: build the release bundle, read its byte size, fail past a percentage delta.
+- `react-native-performance` exposes native startup marks (`nativeLaunchStart`, `runJsBundleStart/End`) as `PerformanceEntry`s, which gives a startup number you can assert on and also report from production.
+
+## Official documentation
+
+- React Native performance overview: https://reactnative.dev/docs/performance
+- Optimizing FlatList configuration: https://reactnative.dev/docs/optimizing-flatlist-configuration
+- Profiling with Hermes and React Native DevTools: https://reactnative.dev/docs/react-native-devtools
+- The New Architecture: https://reactnative.dev/architecture/landing-page
+- Expo performance guidance: https://docs.expo.dev/guides/analyzing-bundles/

package/skills/mobile-release/SKILL.md

@@ -19,10 +19,11 @@ One release process for every mobile stack. This file holds the process and what
 | Native iOS, or the iOS build of any app | [references/ios.md](references/ios.md) |
 | React Native or Expo app | [references/react-native.md](references/react-native.md) |
 | Kotlin Multiplatform shared module and both host apps | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+| In-app purchases and subscription lifecycle | [references/billing.md](references/billing.md) |
 | Release notes and store listing text | [references/store-copy.md](references/store-copy.md) |
 | A CI/CD pipeline that builds, signs and uploads | [references/ci-cd.md](references/ci-cd.md) |
 
-Flutter and React Native apps also need the Android and iOS references for signing and store details. Deeper platform guides live in the platform skills: Google Play policy and Play Billing in `mobile-android`, TestFlight and App Store Connect in `mobile-ios`, EAS in `mobile-rn`. Security hardening before release is in `mobile-security`.
+Flutter and React Native apps also need the Android and iOS references for signing and store details. Deeper platform guides live in the platform skills: Google Play policy and Play Billing in `mobile-android`, TestFlight and App Store Connect in `mobile-ios`, EAS in `mobile-rn`. Security hardening before release is in `mobile-security`, and production crash, error and release-health signals are in [mobile-observability](../mobile-observability/SKILL.md).
 
 ## 2. Readiness checklist