amethyst/commonsUI/ARCHITECTURE.md

commonsUI — the Compose half of the shared layer

commonsUI holds every piece of shared code that needs Compose UI and is therefore useless to the headless cli:

• composables (ui/<area>, <feature>/ui — e.g. nip64Chess/ui, profile/ui — and the historical flat audio renderers),
• ImageVector icons (icons, hashtags, robohash) and the icon fonts,
• theme, layouts, markdown rendering (ui/markdown, jvmAndroid),
• Coil (service/image: CoilImageBridge + BlurHash/ThumbHash/Base64/Blossom fetchers),
• the composeResources tree (translated strings, fonts, the napplet shell + shim files) and the generated com.vitorpamplona.amethyst.commons.resources.Res,
• the @Composable relay-client entry points (observeUser*, *FilterAssemblerSubscription, KeyDataSourceSubscription),
• state holders that carry a foundation/ui type (LevelFeedViewModel with its LazyListState, ChatNewMessageState with TextFieldValue, EmojiSuggestionState with TextFieldState).

Its end state is the whole app UI: every screen, the navigation host and the navigation chrome for every window size (bottom bar, rail, permanent drawer), with amethyst and a new JVM desktopApp as thin shims around it. Screens still in amethyst/ are waiting on their own app-only helpers and the app root, not staying there by design. AccountViewModel lives here (commons.viewmodels) as a thin subclass of commons' BaseAccountViewModel: it adds the ToastManager that headless UserNotices land in (worded by notices/ui/UserNoticeText.kt) and the call/nest bridges. See commons/plans/2026-09-27-one-ui-android-desktop.md and commons/plans/2026-10-09-headless-account-viewmodel.md.

It depends on :commons (and quartz, libs.quartz) as api, so a consumer that adds :commonsUI sees the headless layer transitively. amethyst, desktopApp, nappletHost and benchmark depend on it; cli and marmotBench must never.

Platform slots

Shared composables that need something only a front end can draw or do get it from a CompositionLocal the front end installs at its root (Android in AmethystTheme): LocalRichTextPlatform (rich-text leaves, markdown), LocalInlineQuoteRenderer, LocalTranslationPlatform, and LocalNotePlatform (media players, map, platform-engine note types, reactions/zap row, post editor; call it through the same-named shims in commons.ui.note.platform). Each default draws nothing or plain text, so previews and a front end still wiring its pieces never crash. Small platform verbs are expect/actuals instead: rememberTextSharer, rememberShortNotice, rememberBlossomUriOpener, rememberViewModel.

Same packages as commons

Every file keeps its com.vitorpamplona.amethyst.commons.* package. The split is a build-graph boundary, not a package rename: nothing in the apps had to change an import, and a file can move between the two modules with a git mv. The rule for which module a file lives in is mechanical:

imports androidx.compose.ui / foundation / material3 / animation, Coil, org.jetbrains.compose.resources, Res, org.jetbrains.skia, or declares a @Composable → commonsUI. Otherwise → commons.

The only cross-module gotcha is internal: a commonsUI file cannot see an internal declaration in commons. Make it public (or move the caller).

The full package taxonomy — including which packages are "mixed" (logic in commons, composables here, same package name) — is the table in commons/ARCHITECTURE.md §2. Read that first; this file only documents what is specific to the UI module.

Source sets

Source set	For
commonMain	Composables, icons, theme, Coil fetchers, composeResources. Gated by verifyKmpPurity like commons.
jvmAndroid	Markdown renderer (ui/markdown), Coil-OkHttp + Blossom read-auth fetcher, the viewModel() helper, and the avatar/image engine (ui/components/RobohashAsyncImage.kt: RobohashFallbackAsyncImage, GifProfilePicture) behind the UserAvatar AvatarImage actual. For a user avatar call the commonMain UserAvatar; don't add another avatar composable.
jvmMain	Desktop Coil bridge (CoilImageBridge.jvm.kt), a no-op AnimatedImageAutoPlay (Coil decodes only the first frame), compose.desktop.currentOs. dependsOn(jvmAndroid) + skikoMain.
androidMain	Android Coil bridge, the AnimatedImageAutoPlay actual that starts/stops GIF/AVIF drawables. dependsOn(jvmAndroid).
skikoMain	org.jetbrains.skia pixel helpers shared by desktop JVM + iOS (SkiaBitmapConverter).
iosMain	iOS Coil bridge, a plain AsyncImage AvatarImage actual. Compile-only spike today.

Tooling that points here

• Icon fonts: tools/material-symbols-subset/subset.sh and tools/icon-font/build_icon_font.py read icons/ and write composeResources/font/ in this module (see root AGENTS.md, "Icons").
• Translations: crowdin.yml and tools/strings-migrate/ target commonsUI/src/commonMain/composeResources/. This is where every new user-visible string goes, Android-only screens included; the app's own res/values/strings.xml holds only the synchronous-platform tier (see root AGENTS.md, "Strings").
• CI: .github/workflows/build.yml runs :commonsUI:jvmTest, :commonsUI:verifyKmpPurity and the iOS compile/test tasks next to the :commons ones.