amethyst/commons/plans/2026-09-22-strings-to-compose-resources.md

# Wave 1: Android string resources → commons Compose resources

**Date:** 2026-09-22
**Scope:** every `R.string` / `R.plurals` reference in the `amethyst` module,
and the string catalog behind them.

This is the first wave of the "build the Android app for JVM/desktop" plan. It
is a precondition for every later wave: a screen cannot move to `commonsUI`
while its labels come from `amethyst/src/main/res`.

## Why this wave is not a search-and-replace

The obvious framing — "swap `R.string.x` for `Res.string.x`" — is wrong, and
the reason is worth writing down because it is what sets the wave's size.

Compose resources has exactly two accessors:

| | Android `R` | Compose resources |
|---|---|---|
| in composition | `stringResource(id)` | `stringResource(res)` |
| outside composition | `ctx.getString(id)` | `suspend getString(res)` — **no blocking form** |

The app had **458 call sites** shaped `stringRes(context, R.string.x)`, spread
across ViewModels, notification builders, foreground services, intent helpers
and Android callbacks. None of them can keep working after the key moves,
because there is no non-suspend Context-free way to read a Compose resource.

Deferring those keys does not help: only **167 of 1,912** keys are used
*exclusively* at composable call sites. `cancel`, `save`, `error` and friends
appear on both sides, and a key can only live in one resource system. So the
Context call sites had to be dealt with before any key could move.

**Decision (maintainer, 2026-09-22): no `runBlocking` bridge.** A
`stringResBlocking(id) = runBlocking { getString(id) }` shim would have made
all 458 sites a mechanical rename, but it puts a blocking resource read on
paths that can run on the main thread. Every site was converted properly
instead.

## What "converted properly" meant, by scope

| scope | count | conversion |
|---|---|---|
| `@Composable` | 264 | drop the `context` argument — `stringRes(id)` |
| already inside `launch { }` / `withContext { }` | 46 | `loadStringRes(id)` (the existing suspend bridge in `commonsUI/.../ui/StringRes.kt`) |
| plain function, caller already in a coroutine | ~80 | function becomes `suspend` |
| plain function, no coroutine in reach | ~68 | label hoisted into composition and passed as a `String` |

The interesting cases:

- **`TimeAgoFormatter`** — every caller handed it `LocalContext.current`, so the
  formatters became `@Composable` and lost the parameter entirely. `context`
  survives only in `timeAbsolute`, where `DateFormat.getTimeFormat` needs it.
  `RelayCompose` had one inside `derivedStateOf { }`, which a composable cannot
  enter; it now formats directly in composition (it is a cheap formatter).
- **The notification stack** is one connected component — `NotificationCategory`,
  `NotificationUtils`, `CallNotifier`, `SignerConsentNotifier`,
  `CalendarReminderNotifier`, `ZapNotification`, `InlineReplyFeedback`,
  `ConversationShortcuts`, `RelayPurposeSummary` — so it went `suspend` as a
  unit. Its two public entry points (`postStandard`, `postConversation`) already
  were. The ripple reached `NotificationChannels.Entry`, whose `channelId`/
  `ensure` lambdas are now `suspend`, and the notification settings screen,
  which drives them from `repeatOnLifecycle` + `produceState` instead of
  `LifecycleResumeEffect`.
- **`ScheduledPostNotifier`** (a `commons` interface) went `suspend` on both
  implementations; its only driver is `CoroutineWorker.doWork`.
- **`FlowProgressForegroundService.render`** is now `suspend`, which is what the
  POW-mining and Blossom-sync services needed.
- **`PowDuration`** is read from three composables *and* from the mining
  service, so it has a `@Composable` pair and a `suspend` pair
  (`loadApproxDuration` / `loadTimeLeft`) rather than forcing either caller into
  the wrong shape.
- **Biometric prompts** (`authenticate` in `UpdateZapAmountDialog`) run from
  `onClick` and from Android's own callbacks. Their four labels are resolved in
  composition into an `@Immutable AuthPromptLabels` and passed down.
- **Share sheets** (`shareIcs`, `startShareUrlIntent`, `shareRelayGroup`) take
  their chooser title as a `String` parameter now.
- **`ToastManager`** already carried resource *ids* and resolved them where the
  toast is drawn — so the two `ReusableZapButton` sites needed no lookup at all,
  just the id overload. The toast message classes now carry `StringResource`.
- **`Name.name(context)`** became `suspend nameOrDefault()`, and
  `FeedFilterSpinner` reads it through a `rememberDisplayName` helper that shows
  the plain `name()` for the frame the resource takes to arrive.

## The XML move

`tools/strings-migrate/migrate.py` moves elements verbatim so Crowdin sees a
pure move (both trees are Crowdin-managed with the same android layout). Two
changes were needed for a move this size:

- **`%%` was read as a bare conversion.** The old `BARE_FORMAT` scanned for a
  `%` not followed by `%`, but the *second* `%` of `%1$d%% of all` then started
  a fresh match, and the space flag in `[-#+ 0,(]*` let `% o` look like a
  conversion. Two keys (`active_subs_share`, `uptime`) were rejected for a
  format bug they did not have. The scanner now consumes `%%` as a unit and
  callers test `is_bare()` rather than `.search()`.
- **A bulk `@keyfile` mode.** The per-key path re-read and rewrote each locale
  file once per key: 1,900 keys × 58 files is ~110k rewrites of a 300 KB file.
  `extract_many()` does one pass per file. Verified byte-identical to the old
  path on a 40-key sample across all 57 locale dirs.

Nine keys used non-positional format specifiers (`%d`, `%s`), which
compose-resources cannot format. They were rewritten to `%1$d` / `%1$s` across
all 58 locale files (480 elements) — positional form is valid for Android too,
so behaviour is unchanged on both sides.

Result: **1,906 keys moved**, 67,275 elements across 57 locale dirs.
`amethyst/src/main/res/values/strings.xml` went 2,051 → 143 keys;
`commonsUI/.../composeResources/values/strings.xml` went 3,016 → 4,926.

Six keys did not move:

- `app_name`, `block_hide_user`, `rename`, `save` are referenced from
  `AndroidManifest.xml` / `res/xml`, so the Android copy stays and a copy was
  added to the Compose catalog for the Kotlin side.
- `podcast_value_for_value`, `show_less` already existed in commons; the
  duplicate app-side copies were dropped.

## Guard against silent key loss

A first attempt at the call-site rewrite ate the key in
`stringRes(Res.string.x, arg)` — the Context-detector matched *any* two-argument
call, so the first argument was consumed as if it were a `context`. 344
references disappeared with no error. Two things came out of that:

- The detector uses an **allowlist** of expressions that really are a Context in
  this tree (`context`, `ctx`, `appContext`, `applicationContext`, `actContext`,
  `localContext`, `targetContext`, `this`, and the two
  `Amethyst.instance.appContext` spellings), not "anything before the comma".
- `check_refs.py` (in the migration scratch, worth keeping alongside the tool)
  diffs the per-key, per-file multiset of `R.*` + `Res.*` references against
  HEAD. A rewrite may move a key between namespaces; it may not change the
  multiset. Every rewrite pass after that was run through it.

## Not every string could move: the synchronous-platform tier

The original goal — "zero `R.string` in Kotlin" — was wrong, not merely unmet.

Some strings are read by a platform API that resolves **synchronously and under
a deadline**, where neither Compose accessor can run. The clearest case is a
foreground service: `onStartCommand` must call `startForeground` promptly or
Android kills the service, so `FlowProgressForegroundService` builds its
notification on that thread (`runCatching { startForegroundCompat(...) }`).
A `suspend` accessor cannot be called there at all, and a `runBlocking` bridge
is exactly what the maintainer ruled out. The same holds for a notification
channel created during service startup and for a PiP `RemoteAction`, which is
assembled inside `onUserLeaveHint` / the PiP transition.

So `amethyst/src/main/res` keeps a small, deliberate tier, and
`ui/StringResourceCache.kt` keeps its Android-resource accessors (with the
`LruCache`, which exists because `Resources.getString` measured >1 ms on some
phones). What lives there:

| what | keys |
|---|---|
| always-on relay notification, call notification | restored with the six service files |
| PoW mining notification (`formatApproxDuration`/`formatTimeLeft` + `powKindLabelResId` twins) | 15 |
| nest foreground service + the two PiP activities | 12 |
| napplet capability labels (`labelResId` twin — the sandbox process has no resources of its own) | 11 |
| media PiP action labels | 4 |
| `AndroidManifest.xml` / `res/xml` references | 4 |

Most are **copies**, not moves: the same key is read from composition elsewhere,
so it lives in both trees. That is why the helpers come in pairs
(`powKindLabelRes` / `powKindLabelResId`, `formatApproxDuration(seconds)` /
`formatApproxDuration(context, seconds)`) rather than one being converted.

Two escaping traps came with the copies:

- **aapt and compose-resources do not share escaping rules.** A value moved back
  to `res/values` needs its apostrophes escaped again or the resource merge
  fails with `Invalid unicode escape sequence in string`. The inverse of
  `tools/strings-migrate/fix_escapes.py`; a value Android wrapped in quotes to
  protect whitespace, and a bare `@string/` alias, must be left alone.
- **A copy can duplicate a key** a locale already had, which fails
  `packagePlayDebugResources` — not the Kotlin compile, so it surfaces only
  after the module is otherwise green.

Where the deadline is *not* real, the string stays in the catalog and the read
moves instead. `NotificationRelayService`'s per-job breakdown now recomputes off
the notification path and reposts the card when the text changes, which keeps
those strings shared.

## What the compile-fix loop actually found

1,130 errors at first compile, cleared over eight rounds. The classes, and what
each one taught:

- **Suspend does not propagate to a fixed point.** Marking each caller `suspend`
  went 304 → 307 → 309 → 312 over four rounds and was abandoned. The direction
  that converges is the opposite: **hoist the read** to the nearest composition
  or existing coroutine. `WalletViewModel` went 22 errors → 1 by wrapping eight
  NWC callback *bodies* in `viewModelScope.launch { }` rather than trying to make
  the callbacks suspend (the relay dispatcher invokes them; they cannot be).
- **A callback's message belongs in its signature.** `payViaIntent` resolved one
  fixed "no wallet found" string, which made it `suspend`, which made it
  uncallable from the 20 `onPayViaIntent` lambdas that are its only callers. The
  message is now a parameter, resolved in the composable that owns the callback.
  `FavoriteAppLauncher.launch` took the same treatment.
- **Much of the `suspend` was never real.** Roughly 30 functions were marked
  `suspend` only because they once read a string; the read had since moved but
  the modifier had not, and every plain callback then refused to call them. The
  wallet entry points are the clearest: `fetchTransactions`, `sendPayment` and
  `createInvoice` hand straight off to `viewModelScope.launch`, which is the
  shape a ViewModel entry point should have anyway.
  *A script that removed the modifier wherever it could not find a suspension
  point was a mistake and was reverted: it has no parse of interface members
  (which have no body) and silently un-suspended `IAccount`, `ITorManager` and
  ~170 other files, including already-green modules.*
- **`derivedStateOf` is not composable scope.** `TimeAgo` builds its text there,
  so the formatters split: plain `timeAgoWith` / `timeAbsoluteWith` cores taking
  a `TimeAgoLabels` holder resolved once in composition, with the `@Composable`
  wrappers delegating. This is strictly better than the all-composable form —
  a composable formatter cannot be memoized in a `remember`.
- **A `StringResource` is not `Saveable` and not a valid LazyColumn key.**
  `NewConversationScreen`'s accordion keyed itself by the title resource; it now
  keys by the resource's `String` id.
- **Nullable format args.** The commonest argument is `Throwable.message`, and
  compose-resources takes a non-null `Any`. The bridge's varargs are `Any?` and
  a null renders as an empty string rather than the literal `"null"` that
  `Resources.getString` would have printed at the user.
- **`kotlin-errors=0` is not a green build.** A duplicate `app_name` broke
  `packagePlayDebugResources` *after* Kotlin reported zero errors. Check the
  `BUILD SUCCESSFUL` line, not the error count.

## Status

- `:amethyst:compilePlayDebugKotlin` — **green**
- `:quartz:jvmTest`, `:commons:jvmTest`, `:commonsUI:jvmTest`,
  `:amethyst:testPlayDebugUnitTest` — **pass** (1,636 tests in `:amethyst`)
- `.claude/hooks/orphan_strings_check.py` — passes
- `./gradlew spotlessApply` — clean
- `R.string` / `R.plurals` references left in Kotlin: **77**, over **68**
  distinct keys; `amethyst/src/main/res/values/strings.xml` holds **204**
  (the extras are manifest-referenced, or `plurals` a key reaches by quantity).
  All of it is the synchronous-platform tier described above — that is the
  correct end state, not a shortfall.

`:cli:test` could not be driven to completion here — its dependency resolution
is 429-throttled by the container's shared egress IP — but nothing in this wave
touches `cli`.