refactor(commons): consolidate package taxonomy + add architecture doc

Document the commons module's purpose, source-set layout, and the CLI-safe vs
UI boundary in commons/ARCHITECTURE.md, then clean up the clearest package
overlaps that had accumulated:

- merge duplicate util/utils -> util (all source sets)
- unify service/services -> service (jvmAndroid)
- move data/UserMetadataCache -> model/cache
- fold compose/ into ui/ (ui/article, editor, elements, layouts, markdown,
  nip53LiveActivities, and Compose helpers in ui/state + ui/text)
- move ProfileBroadcastBanner composable into profile/ui

All changes are whole-file/whole-package moves with import rewrites; no logic
changed. The chess logic/UI split is documented as deferred debt (it needs
file-level surgery, not moves). Marks docs/shared-ui-analysis.md superseded.

https://claude.ai/code/session_01KXLzsvx9Gyrm3Yz4Rims55

.claude/CLAUDE.md

@@ -76,7 +76,12 @@ amethyst/
 
 **Sharing Philosophy:**
 - `quartz/` = Nostr business logic, protocol, data (no UI)
-- `commons/` = Shared UI components, icons, composables, flows and ViewModels
+- `commons/` = Shared code for every front end (Android, Desktop, iOS, and the
+  headless `cli`): domain models, state holders, ViewModels, the relay client,
+  shared services, **and** the Compose UI that ≥1 GUI front end renders. The
+  package taxonomy, the CLI-safe / UI boundary, and a "where does my code go?"
+  guide are documented in **`commons/ARCHITECTURE.md`** — read it before adding
+  a new package or dropping code into `commons`.
 - `quic/` = Transport library (QUIC + HTTP/3 + WebTransport); reusable for any
   KMP project that needs MoQ. Has no Android-framework dependencies.
 - `nestsClient/` = MoQ + audio-rooms client; takes `:quic` as transport,

amethyst/src/main/java/com/vitorpamplona/amethyst/AppModules.kt

@@ -26,7 +26,7 @@ import coil3.disk.DiskCache
 import coil3.memory.MemoryCache
 import com.vitorpamplona.amethyst.commons.model.NoteState
 import com.vitorpamplona.amethyst.commons.robohash.CachedRobohash
-import com.vitorpamplona.amethyst.commons.services.lnurl.OkHttpLnurlEndpointResolver
+import com.vitorpamplona.amethyst.commons.service.lnurl.OkHttpLnurlEndpointResolver
 import com.vitorpamplona.amethyst.commons.tor.TorSettings
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache

amethyst/src/main/java/com/vitorpamplona/amethyst/model/LocalCache.kt

@@ -39,7 +39,7 @@ import com.vitorpamplona.amethyst.commons.model.observables.NewEventMatchingFilt
 import com.vitorpamplona.amethyst.commons.model.observables.NoteListMatchingFilter
 import com.vitorpamplona.amethyst.commons.model.observables.Observable
 import com.vitorpamplona.amethyst.commons.model.privateChats.ChatroomList
-import com.vitorpamplona.amethyst.commons.services.nwc.NwcPaymentTracker
+import com.vitorpamplona.amethyst.commons.service.nwc.NwcPaymentTracker
 import com.vitorpamplona.amethyst.isDebug
 import com.vitorpamplona.amethyst.model.LocalCache.observeEvents
 import com.vitorpamplona.amethyst.model.nip51Lists.HiddenUsersState

amethyst/src/main/java/com/vitorpamplona/amethyst/service/playback/composable/mediaitem/GetMediaItem.kt

@@ -23,7 +23,7 @@ package com.vitorpamplona.amethyst.service.playback.composable.mediaitem
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.remember
-import com.vitorpamplona.amethyst.commons.compose.produceCachedState
+import com.vitorpamplona.amethyst.commons.ui.state.produceCachedState
 import com.vitorpamplona.amethyst.service.playback.composable.WaveformData
 import com.vitorpamplona.quartz.nip94FileMetadata.tags.DimensionTag
 

amethyst/src/main/java/com/vitorpamplona/amethyst/service/playback/composable/mediaitem/MediaItemCache.kt

@@ -25,7 +25,7 @@ import androidx.core.net.toUri
 import androidx.media3.common.MediaItem
 import androidx.media3.common.MediaMetadata
 import androidx.media3.common.MimeTypes
-import com.vitorpamplona.amethyst.commons.compose.GenericBaseCache
+import com.vitorpamplona.amethyst.commons.ui.state.GenericBaseCache
 import com.vitorpamplona.quartz.utils.Log
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/actions/EditPostViewModel.kt

@@ -30,9 +30,9 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.text.input.TextFieldValue
 import androidx.lifecycle.ViewModel
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.currentWord
-import com.vitorpamplona.amethyst.commons.compose.insertUrlAtCursor
 import com.vitorpamplona.amethyst.commons.richtext.RichTextParser
+import com.vitorpamplona.amethyst.commons.ui.text.currentWord
+import com.vitorpamplona.amethyst.commons.ui.text.insertUrlAtCursor
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.Note
 import com.vitorpamplona.amethyst.model.User

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/components/RichTextViewer.kt

@@ -63,7 +63,6 @@ import androidx.compose.ui.unit.LayoutDirection
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.em
 import com.vitorpamplona.amethyst.Amethyst
-import com.vitorpamplona.amethyst.commons.compose.produceCachedState
 import com.vitorpamplona.amethyst.commons.emojicoder.EmojiCoder
 import com.vitorpamplona.amethyst.commons.model.EmptyTagList
 import com.vitorpamplona.amethyst.commons.model.ImmutableListOfLists
@@ -92,6 +91,7 @@ import com.vitorpamplona.amethyst.commons.richtext.SecretEmoji
 import com.vitorpamplona.amethyst.commons.richtext.Segment
 import com.vitorpamplona.amethyst.commons.richtext.VideoSegment
 import com.vitorpamplona.amethyst.commons.richtext.WithdrawSegment
+import com.vitorpamplona.amethyst.commons.ui.state.produceCachedState
 import com.vitorpamplona.amethyst.model.HashtagIcon
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/note/NoteCompose.kt

@@ -57,10 +57,10 @@ import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.unit.dp
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.produceCachedStateAsync
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
 import com.vitorpamplona.amethyst.commons.model.nip28PublicChats.PublicChatChannel
+import com.vitorpamplona.amethyst.commons.ui.state.produceCachedStateAsync
 import com.vitorpamplona.amethyst.model.AddressableNote
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/note/creators/previews/PreviewUrl.kt

@@ -40,8 +40,8 @@ import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.text.style.TextOverflow
 import coil3.compose.AsyncImage
-import com.vitorpamplona.amethyst.commons.compose.produceCachedState
 import com.vitorpamplona.amethyst.commons.richtext.RichTextParser
+import com.vitorpamplona.amethyst.commons.ui.state.produceCachedState
 import com.vitorpamplona.amethyst.model.UrlCachedPreviewer
 import com.vitorpamplona.amethyst.service.playback.composable.VideoView
 import com.vitorpamplona.amethyst.ui.actions.CrossfadeIfEnabled

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/note/nip22Comments/CommentPostViewModel.kt

@@ -33,11 +33,11 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.vitorpamplona.amethyst.Amethyst
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.currentWord
-import com.vitorpamplona.amethyst.commons.compose.insertUrlAtCursor
-import com.vitorpamplona.amethyst.commons.compose.replaceCurrentWord
-import com.vitorpamplona.amethyst.commons.compose.setTextAndPlaceCursorAtBeginning
 import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.EmojiPackState
+import com.vitorpamplona.amethyst.commons.ui.text.currentWord
+import com.vitorpamplona.amethyst.commons.ui.text.insertUrlAtCursor
+import com.vitorpamplona.amethyst.commons.ui.text.replaceCurrentWord
+import com.vitorpamplona.amethyst.commons.ui.text.setTextAndPlaceCursorAtBeginning
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/AccountViewModel.kt

@@ -38,8 +38,6 @@ import com.vitorpamplona.amethyst.Amethyst
 import com.vitorpamplona.amethyst.LocalPreferences
 import com.vitorpamplona.amethyst.R
 import com.vitorpamplona.amethyst.commons.call.CallManager
-import com.vitorpamplona.amethyst.commons.compose.GenericBaseCache
-import com.vitorpamplona.amethyst.commons.compose.GenericBaseCacheAsync
 import com.vitorpamplona.amethyst.commons.model.LiveHiddenUsers
 import com.vitorpamplona.amethyst.commons.model.emphChat.EphemeralChatChannel
 import com.vitorpamplona.amethyst.commons.model.nip28PublicChats.PublicChatChannel
@@ -48,6 +46,8 @@ import com.vitorpamplona.amethyst.commons.model.observables.CreatedAtComparator
 import com.vitorpamplona.amethyst.commons.tor.TorType
 import com.vitorpamplona.amethyst.commons.ui.feeds.FeedState
 import com.vitorpamplona.amethyst.commons.ui.notifications.CardFeedState
+import com.vitorpamplona.amethyst.commons.ui.state.GenericBaseCache
+import com.vitorpamplona.amethyst.commons.ui.state.GenericBaseCacheAsync
 import com.vitorpamplona.amethyst.logTime
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.AccountSettings

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/chats/feed/types/RenderChatClip.kt

@@ -35,7 +35,7 @@ import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.unit.dp
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.nip53LiveActivities.StreamSystemCard
+import com.vitorpamplona.amethyst.commons.ui.nip53LiveActivities.StreamSystemCard
 import com.vitorpamplona.amethyst.model.Note
 import com.vitorpamplona.amethyst.service.playback.composable.VideoView
 import com.vitorpamplona.amethyst.ui.navigation.navs.INav

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/chats/feed/types/RenderChatRaid.kt

@@ -35,9 +35,9 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.unit.dp
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.nip53LiveActivities.StreamSystemCard
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
+import com.vitorpamplona.amethyst.commons.ui.nip53LiveActivities.StreamSystemCard
 import com.vitorpamplona.amethyst.model.Note
 import com.vitorpamplona.amethyst.ui.navigation.navs.INav
 import com.vitorpamplona.amethyst.ui.navigation.routes.Route

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/chats/feed/types/RenderChatZap.kt

@@ -36,7 +36,7 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.unit.dp
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.nip53LiveActivities.StreamSystemCard
+import com.vitorpamplona.amethyst.commons.ui.nip53LiveActivities.StreamSystemCard
 import com.vitorpamplona.amethyst.model.Note
 import com.vitorpamplona.amethyst.ui.navigation.navs.INav
 import com.vitorpamplona.amethyst.ui.note.CrossfadeToDisplayComment

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/chats/privateDM/send/ChatNewMessageViewModel.kt

@@ -32,10 +32,10 @@ import androidx.compose.runtime.setValue
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.vitorpamplona.amethyst.Amethyst
-import com.vitorpamplona.amethyst.commons.compose.currentWord
-import com.vitorpamplona.amethyst.commons.compose.insertUrlAtCursor
-import com.vitorpamplona.amethyst.commons.compose.replaceCurrentWord
 import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.EmojiPackState
+import com.vitorpamplona.amethyst.commons.ui.text.currentWord
+import com.vitorpamplona.amethyst.commons.ui.text.insertUrlAtCursor
+import com.vitorpamplona.amethyst.commons.ui.text.replaceCurrentWord
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/chats/publicChannels/send/ChannelNewMessageViewModel.kt

@@ -33,15 +33,15 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.vitorpamplona.amethyst.Amethyst
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.currentWord
-import com.vitorpamplona.amethyst.commons.compose.insertUrlAtCursor
-import com.vitorpamplona.amethyst.commons.compose.replaceCurrentWord
 import com.vitorpamplona.amethyst.commons.model.Channel
 import com.vitorpamplona.amethyst.commons.model.emphChat.EphemeralChatChannel
 import com.vitorpamplona.amethyst.commons.model.nip28PublicChats.PublicChatChannel
 import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.EmojiPackState
 import com.vitorpamplona.amethyst.commons.model.nip53LiveActivities.LiveActivitiesChannel
 import com.vitorpamplona.amethyst.commons.richtext.UrlParser
+import com.vitorpamplona.amethyst.commons.ui.text.currentWord
+import com.vitorpamplona.amethyst.commons.ui.text.insertUrlAtCursor
+import com.vitorpamplona.amethyst.commons.ui.text.replaceCurrentWord
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/discover/nip23LongForm/LongFormPostViewModel.kt

@@ -34,10 +34,10 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.vitorpamplona.amethyst.Amethyst
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.currentWord
-import com.vitorpamplona.amethyst.commons.compose.insertUrlAtCursor
-import com.vitorpamplona.amethyst.commons.compose.replaceCurrentWord
 import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.EmojiPackState.EmojiMedia
+import com.vitorpamplona.amethyst.commons.ui.text.currentWord
+import com.vitorpamplona.amethyst.commons.ui.text.insertUrlAtCursor
+import com.vitorpamplona.amethyst.commons.ui.text.replaceCurrentWord
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/discover/nip99Classifieds/NewProductViewModel.kt

@@ -33,10 +33,10 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.vitorpamplona.amethyst.Amethyst
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.currentWord
-import com.vitorpamplona.amethyst.commons.compose.insertUrlAtCursor
-import com.vitorpamplona.amethyst.commons.compose.replaceCurrentWord
 import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.EmojiPackState
+import com.vitorpamplona.amethyst.commons.ui.text.currentWord
+import com.vitorpamplona.amethyst.commons.ui.text.insertUrlAtCursor
+import com.vitorpamplona.amethyst.commons.ui.text.replaceCurrentWord
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/home/ShortNotePostViewModel.kt

@@ -35,11 +35,11 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.vitorpamplona.amethyst.Amethyst
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.currentWord
-import com.vitorpamplona.amethyst.commons.compose.insertUrlAtCursor
-import com.vitorpamplona.amethyst.commons.compose.replaceCurrentWord
-import com.vitorpamplona.amethyst.commons.compose.setTextAndPlaceCursorAtBeginning
 import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.EmojiPackState.EmojiMedia
+import com.vitorpamplona.amethyst.commons.ui.text.currentWord
+import com.vitorpamplona.amethyst.commons.ui.text.insertUrlAtCursor
+import com.vitorpamplona.amethyst.commons.ui.text.replaceCurrentWord
+import com.vitorpamplona.amethyst.commons.ui.text.setTextAndPlaceCursorAtBeginning
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.BooleanType
 import com.vitorpamplona.amethyst.model.LocalCache

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/nests/room/chat/NestNewMessageViewModel.kt

@@ -33,12 +33,12 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.vitorpamplona.amethyst.Amethyst
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.currentWord
-import com.vitorpamplona.amethyst.commons.compose.insertUrlAtCursor
-import com.vitorpamplona.amethyst.commons.compose.replaceCurrentWord
 import com.vitorpamplona.amethyst.commons.model.AddressableNote
 import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.EmojiPackState
 import com.vitorpamplona.amethyst.commons.richtext.UrlParser
+import com.vitorpamplona.amethyst.commons.ui.text.currentWord
+import com.vitorpamplona.amethyst.commons.ui.text.insertUrlAtCursor
+import com.vitorpamplona.amethyst.commons.ui.text.replaceCurrentWord
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/notifications/EqualImmutableLists.kt

@@ -27,5 +27,5 @@ fun <T> equalImmutableLists(
     list1: ImmutableList<T>,
     list2: ImmutableList<T>,
 ): Boolean =
-    com.vitorpamplona.amethyst.commons.utils
+    com.vitorpamplona.amethyst.commons.util
         .equalImmutableLists(list1, list2)

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/notifications/publicMessages/NewPublicMessageViewModel.kt

@@ -33,10 +33,10 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.vitorpamplona.amethyst.Amethyst
 import com.vitorpamplona.amethyst.R
-import com.vitorpamplona.amethyst.commons.compose.currentWord
-import com.vitorpamplona.amethyst.commons.compose.insertUrlAtCursor
-import com.vitorpamplona.amethyst.commons.compose.replaceCurrentWord
 import com.vitorpamplona.amethyst.commons.model.nip30CustomEmojis.EmojiPackState
+import com.vitorpamplona.amethyst.commons.ui.text.currentWord
+import com.vitorpamplona.amethyst.commons.ui.text.insertUrlAtCursor
+import com.vitorpamplona.amethyst.commons.ui.text.replaceCurrentWord
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.model.Note

amethyst/src/play/java/com/vitorpamplona/amethyst/appfunctions/AmethystAppFunctions.kt

@@ -32,7 +32,7 @@ import com.vitorpamplona.amethyst.commons.actions.SearchActions
 import com.vitorpamplona.amethyst.commons.actions.ZapActions
 import com.vitorpamplona.amethyst.commons.defaults.DefaultNIP65RelaySet
 import com.vitorpamplona.amethyst.commons.relayClient.nip17Dm.unwrapAndUnsealOrNull
-import com.vitorpamplona.amethyst.commons.services.lnurl.LightningAddressResolver
+import com.vitorpamplona.amethyst.commons.service.lnurl.LightningAddressResolver
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.home.dal.HomeNewThreadFeedFilter
 import com.vitorpamplona.quartz.lightning.LnInvoiceUtil
 import com.vitorpamplona.quartz.marmot.RecipientRelayFetcher

cli/src/main/kotlin/com/vitorpamplona/amethyst/cli/commands/ZapCommand.kt

@@ -25,7 +25,7 @@ import com.vitorpamplona.amethyst.cli.Context
 import com.vitorpamplona.amethyst.cli.DataDir
 import com.vitorpamplona.amethyst.cli.Output
 import com.vitorpamplona.amethyst.commons.actions.ZapActions
-import com.vitorpamplona.amethyst.commons.services.lnurl.LightningAddressResolver
+import com.vitorpamplona.amethyst.commons.service.lnurl.LightningAddressResolver
 import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
 import com.vitorpamplona.quartz.nip01Core.metadata.MetadataEvent

commons/ARCHITECTURE.md

@@ -0,0 +1,210 @@
+# `commons` — Shared Module Architecture & Goals
+
+`commons` is the **shared layer** between every Amethyst front end:
+
+| Consumer       | Kind                         | Uses from `commons`                          |
+|----------------|------------------------------|----------------------------------------------|
+| `amethyst`     | Android app (touch-first)    | everything (models, state, ViewModels, UI)   |
+| `desktopApp`   | Desktop JVM app (mouse-first)| everything (models, state, ViewModels, UI)   |
+| `cli` (`amy`)  | Headless JVM CLI (no UI)     | **non-UI only** — models, actions, relay, services |
+| iOS (future)   | iOS app                      | everything; expected to share most UI with Android |
+
+`commons` sits **above** `quartz` (the protocol-only Nostr KMP library) and
+**below** the apps. The split between the three is:
+
+- **`quartz/`** — Nostr protocol: events, NIPs, crypto, relay framing. No app
+  state, no UI, no caches of "what this user follows."
+- **`commons/`** — everything an Amethyst *client* needs that isn't a
+  platform-native screen or navigation shell: domain models (`Note`, `User`),
+  in-memory state holders, ViewModels, the relay-subscription client, shared
+  business services, **and** the Compose UI components that more than one front
+  end renders.
+- **`amethyst/` & `desktopApp/`** — platform-native screens, navigation
+  (bottom-nav vs sidebar), gestures, system integration. They assemble
+  `commons` pieces; they should not re-implement them.
+
+> The goal is **"write it once in `commons`"**. Before adding a manager, cache,
+> filter, ViewModel, or composable to an app module, check whether it already
+> exists here or belongs here. See the "Where does my code go?" guide below.
+
+---
+
+## 1. The one rule that shapes the package tree: the **UI / non-UI boundary**
+
+`commons` is a single module that contains **both** Compose UI and headless
+logic. That is deliberate (it keeps a feature's model, state, and UI together —
+see §3), but it creates one hard constraint, because **`cli` and any headless
+consumer cannot use Compose**:
+
+> **CLI-safe code** = does not depend on Compose UI. It may use the
+> `androidx.compose.runtime` *annotations* `@Stable` / `@Immutable` (they are
+> just stability tags) and snapshot state, but it must **not** import
+> `androidx.compose.ui`, `androidx.compose.foundation`,
+> `androidx.compose.material3`, declare `@Composable` functions, or build
+> `ImageVector`s.
+>
+> **UI code** = anything that does. It is only usable by the GUI front ends
+> (Android, Desktop, iOS), never by `cli`.
+
+Compose is an `implementation` dependency of `commonMain`, so `cli` pulling in
+`commons` does **not** force it to render anything — but a `cli` command must
+only reach for CLI-safe packages. When you add code, know which side of this
+line it is on, and put it in a package that matches (§2).
+
+This boundary is **not** a top-level `ui/` vs `logic/` partition of the whole
+module (we chose to stay feature-oriented, §3). It is a property of each file
+that you keep track of via package placement and the table in §2.
+
+---
+
+## 2. Package taxonomy
+
+Top-level packages under
+`commonMain/.../commons/`, grouped by concern. **UI?** marks whether the
+package contains Compose UI (and is therefore *not* CLI-safe).
+
+### Domain models & data
+| Package        | UI? | Purpose |
+|----------------|-----|---------|
+| `model`        | no¹ | Core domain types (`Note`, `User`, `Channel`), thread assembly, and per-NIP event model extensions in `model/nipNN…` subpackages. `model/cache` holds the in-memory event-store interfaces + `UserMetadataCache`. `model/account`, `model/observables`. The largest package; keep it organized by NIP. |
+| `defaults`     | no  | Static bootstrap data (default relays, channels). |
+
+¹ `model` uses only the `@Stable`/`@Immutable` runtime annotations — CLI-safe.
+
+### Protocol-adjacent business logic (CLI-safe)
+| Package        | UI? | Purpose |
+|----------------|-----|---------|
+| `actions`      | no  | Event builders for user actions (follow, zap…). The canonical entry point for non-UI callers. |
+| `account`      | no  | New-account bootstrap events. |
+| `onchain`      | no  | On-chain zap splitting/broadcasting. |
+| `marmot`       | no  | MLS group-chat event processing. |
+| `nip53LiveActivities` | no | Live-activity zapper aggregation. |
+| `search`       | no  | Event search filtering/ranking, kind registry. |
+| `preview`      | no  | OpenGraph / meta-tag link-preview parsing. |
+| `emojicoder`   | no  | Variation-selector emoji encode/decode. |
+| `richtext`     | no  | URL/media/pattern parsing for rich text. |
+| `blurhash`     | no  | BlurHash encode/decode (pure math; platform image bridge in platform sets). |
+| `thumbhash`    | no  | ThumbHash encode/decode. |
+| `call`         | no  | NIP-AC WebRTC **call state machine** + peer-session abstraction. See `call/ARCHITECTURE.md`. |
+
+### State holders & ViewModels
+| Package        | UI? | Purpose |
+|----------------|-----|---------|
+| `state`        | no² | Small feature `StateFlow` machines (`FollowState`, `UserMetadataState`, `LoadingState`). |
+| `viewmodels`   | no² | Larger list/feed-backed ViewModels (`androidx.lifecycle.ViewModel`). Shared by all GUI front ends; `cli` usually drives the layers below instead. |
+| `feeds`        | no  | `FeedDefinitionRepository` — custom-feed definitions & ordering. |
+| `profile`      | mixed | `ProfileBroadcastStatus` (state) + `EditProfileFields` at the root; the `ProfileBroadcastBanner` composable lives in `profile/ui`. |
+
+² may touch `compose.runtime`/`foundation` state types (e.g. `LazyListState`);
+they are shared across the GUI apps. Treat as GUI-shared, not strictly headless.
+
+### Relay client
+| Package        | UI? | Purpose |
+|----------------|-----|---------|
+| `relayClient`  | no  | Compose-scoped subscription managers, filter assemblers, EOSE managers, preloaders. (Despite a `composeSubscriptionManagers` subpackage name, this is subscription-lifecycle logic, not UI.) |
+| `relays`       | no  | Low-level EOSE/relay-timing bookkeeping (`EOSECache`, `EOSERelayList`). |
+
+### Platform abstractions (`expect`/`actual`)
+| Package        | UI? | Purpose |
+|----------------|-----|---------|
+| `util`         | no  | KMP primitives: `KmpLock`, `WeakReference`, number/URL/codepoint helpers, list/debug helpers. **This is the only general-utility package** — there is no `utils`. |
+| `keystorage`   | no  | Secure key storage interface (Keystore / keychain / keyring actuals). |
+| `threading`    | no  | `checkNotInMainThread` assertion. |
+| `tor`          | no  | Tor manager interface + settings. |
+| `service`      | no  | Cross-cutting services: `BundledUpdate` batching (common); `service/upload` (JVM), `service/nwc`, `service/lnurl` (jvmAndroid). **Singular `service`** — there is no `services`. |
+
+### UI (Compose — **not** CLI-safe)
+| Package        | UI? | Purpose |
+|----------------|-----|---------|
+| `ui`           | yes | All shared composables, organized by area: `ui/components`, `ui/theme`, `ui/signing`, `ui/thread`, `ui/feeds` (feed DAL + filters — see debt §4), `ui/notifications`, `ui/screens`, `ui/article`, `ui/editor`, `ui/elements`, `ui/layouts`, `ui/markdown`, `ui/nip53LiveActivities`, plus Compose helpers in `ui/state` (cached-state) and `ui/text` (TextField extensions). |
+| `icons`        | yes | `ImageVector` icon definitions + builders. |
+| `hashtags`     | yes | Custom hashtag `ImageVector`s. |
+| `robohash`     | yes | Procedural robohash avatar `ImageVector` assembly. |
+
+### Mixed (documented debt — see §4)
+| Package        | UI? | Purpose |
+|----------------|-----|---------|
+| `chess`        | mixed | Live-chess feature: game/lobby/subscription logic **and** board/lobby composables in one flat package. Needs a `chess/ui` split. |
+| `domain`       | no  | Currently only `domain/nip46` (Nostr Connect signer flows). Sparse; candidate to fold into a clearer home. |
+
+---
+
+## 3. Conventions
+
+### Feature-oriented, not layer-partitioned
+We keep a feature's model, state, and UI **together** under one feature
+package rather than splitting the whole module into top-level `ui/` /
+`viewmodels/` / `model/` layers. Within a feature, separate UI from logic with a
+`ui` **subpackage** (e.g. `profile/ProfileBroadcastStatus` vs
+`profile/ui/ProfileBroadcastBanner`) so the CLI-safe boundary (§1) stays
+visible.
+
+The big shared cross-feature packages (`model`, `ui`, `relayClient`, `util`,
+`icons`) are the exception — they are organized by layer because many features
+share them.
+
+### Naming
+- **Singular, no synonyms.** `util` (not `utils`), `service` (not `services`).
+  One concept → one package name.
+- Per-NIP model code goes in `model/nipNN<slug>` (e.g. `model/nip51Lists`).
+- Composables that belong to a feature go in `<feature>/ui`; cross-cutting
+  composables go under `ui/<area>`.
+
+### Source sets
+| Source set    | For |
+|---------------|-----|
+| `commonMain`  | KMP code for **all** targets (Android, JVM, iOS). Gated by `verifyKmpPurity` — no Jackson/OkHttp/`System.currentTimeMillis`/`java.util.UUID`/JVM `@Synchronized`/`@Volatile`. Use the KMP replacements. |
+| `jvmAndroid`  | Shared by Android + Desktop, **not** iOS. Where JVM-bound deps live (`nestsClient`, Coil-OkHttp, markdown, `viewModel()` helper, NWC/LNURL). |
+| `jvmMain`     | Desktop-only (keyring, EXIF, `service/upload`). `dependsOn(jvmAndroid)`. |
+| `androidMain` | Android-only (Keystore, DataStore). `dependsOn(jvmAndroid)`. |
+| `iosMain`     | iOS `actual`s. Compile-only spike today. |
+
+When adding platform code, prefer the **most common** source set that still
+compiles: `commonMain` → `jvmAndroid` → platform-specific. See
+`/kotlin-multiplatform`.
+
+### Where does my code go? (quick guide)
+1. **Pure Nostr protocol** (events/NIPs/crypto)? → not here, it's `quartz`.
+2. **A composable** rendered by ≥2 front ends, or that you want iOS to share? →
+   `ui/<area>` or `<feature>/ui`. Never in `cli`.
+3. **A ViewModel / `StateFlow` state holder**? → `viewmodels` or `state` (or
+   `<feature>` if feature-scoped). Keep it CLI-safe where practical.
+4. **Relay subscription / filter assembly**? → `relayClient`.
+5. **A domain model or per-NIP event wrapper**? → `model` (`model/nipNN…`).
+6. **A platform capability behind `expect`/`actual`** (storage, crypto,
+   threading)? → the matching abstraction package + actuals in platform sets.
+7. **A generic helper**? → `util`. (Resist creating a new top-level package for
+   one file.)
+
+---
+
+## 4. Known debt / follow-ups
+
+These are intentionally *documented*, not silently tolerated. Fix opportunistically.
+
+- **`chess` is UI+logic in one flat package.** `LiveChessGame.kt` mixes a state
+  class with composables. Split into `chess/` (logic) + `chess/ui/`
+  (composables); this needs file-level surgery (extracting composables out of
+  logic files), not just moves, so it is deferred.
+- **`ui/feeds` holds the feed data-access layer** (`FeedFilter`,
+  `ChangesFlowFilter`, `FeedContentState`), which is logic, not UI, and overlaps
+  conceptually with the top-level `feeds` (custom-feed definitions). Consider
+  moving the DAL out of `ui/`.
+- **`domain` is sparse** (only `nip46`). Either grow it as the home for
+  use-case/flow types or fold `nip46` into a clearer location.
+- **`relays` vs `relayClient`** are coherent but close in name; `relays` is
+  low-level EOSE bookkeeping, `relayClient` is the subscription client. Keep the
+  distinction in mind when adding files.
+- Several **single-file feature packages** (`account`, `marmot`,
+  `nip53LiveActivities`, `keystorage`, `threading`) are kept as feature/abstraction
+  namespaces expected to grow; do not fold them into `util` just for size.
+
+---
+
+## 5. See also
+- `call/ARCHITECTURE.md` — WebRTC call state machine deep-dive.
+- Root `.claude/CLAUDE.md` — module overview, sharing philosophy, build commands.
+- `/kotlin-multiplatform`, `/compose-expert`, `/feed-patterns`, `/relay-client`,
+  `/account-state` skills for the patterns referenced above.
+</content>
+</invoke>

commons/src/androidDeviceTest/kotlin/com/vitorpamplona/amethyst/commons/ui/text/TextFieldValueExtensionTest.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose
+package com.vitorpamplona.amethyst.commons.ui.text
 
 import androidx.compose.ui.text.TextRange
 import androidx.compose.ui.text.input.TextFieldValue

commons/src/androidMain/kotlin/com/vitorpamplona/amethyst/commons/util/DebugUtils.android.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.utils
+package com.vitorpamplona.amethyst.commons.util
 
 // Debug flag for commons module - kept false to avoid application dependencies
 // Application-level modules (amethyst, desktopApp) can implement their own debug timing

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/model/cache/UserMetadataCache.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.data
+package com.vitorpamplona.amethyst.commons.model.cache
 
 import com.vitorpamplona.quartz.nip01Core.metadata.UserMetadata
 import kotlinx.coroutines.flow.MutableStateFlow

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/profile/ui/ProfileBroadcastBanner.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.profile
+package com.vitorpamplona.amethyst.commons.profile.ui
 
 import androidx.compose.animation.AnimatedVisibility
 import androidx.compose.animation.animateContentSize
@@ -52,6 +52,7 @@ import androidx.compose.ui.unit.dp
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbol
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
+import com.vitorpamplona.amethyst.commons.profile.ProfileBroadcastStatus
 
 /**
  * Shared banner showing profile metadata broadcast progress.

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/article/ArticleHeader.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose.article
+package com.vitorpamplona.amethyst.commons.ui.article
 
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/article/TableOfContents.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose.article
+package com.vitorpamplona.amethyst.commons.ui.article
 
 import androidx.compose.foundation.clickable
 import androidx.compose.foundation.layout.Column

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/editor/MarkdownEditorState.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose.editor
+package com.vitorpamplona.amethyst.commons.ui.editor
 
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/editor/MarkdownToolbar.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose.editor
+package com.vitorpamplona.amethyst.commons.ui.editor
 
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Row

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/editor/MetadataPanel.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose.editor
+package com.vitorpamplona.amethyst.commons.ui.editor
 
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/elements/BoostedMark.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose.elements
+package com.vitorpamplona.amethyst.commons.ui.elements
 
 import androidx.compose.foundation.layout.padding
 import androidx.compose.material3.MaterialTheme

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/feeds/AdditiveFeedFilter.kt

@@ -20,7 +20,7 @@
  */
 package com.vitorpamplona.amethyst.commons.ui.feeds
 
-import com.vitorpamplona.amethyst.commons.utils.logTime
+import com.vitorpamplona.amethyst.commons.util.logTime
 
 abstract class AdditiveFeedFilter<T> :
     FeedFilter<T>(),

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/feeds/FeedContentState.kt

@@ -28,7 +28,7 @@ import com.vitorpamplona.amethyst.commons.model.cache.ICacheProvider
 import com.vitorpamplona.amethyst.commons.service.BasicBundledInsert
 import com.vitorpamplona.amethyst.commons.service.BasicBundledUpdate
 import com.vitorpamplona.amethyst.commons.threading.checkNotInMainThread
-import com.vitorpamplona.amethyst.commons.utils.equalImmutableLists
+import com.vitorpamplona.amethyst.commons.util.equalImmutableLists
 import com.vitorpamplona.quartz.nip09Deletions.DeletionEvent
 import com.vitorpamplona.quartz.utils.flattenToSet
 import kotlinx.collections.immutable.ImmutableList

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/feeds/FeedFilter.kt

@@ -20,7 +20,7 @@
  */
 package com.vitorpamplona.amethyst.commons.ui.feeds
 
-import com.vitorpamplona.amethyst.commons.utils.logTime
+import com.vitorpamplona.amethyst.commons.util.logTime
 
 abstract class FeedFilter<T> : IFeedFilter<T> {
     override fun loadTop(): List<T> {

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/layouts/GenericRepostLayout.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose.layouts
+package com.vitorpamplona.amethyst.commons.ui.layouts
 
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.padding

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/nip53LiveActivities/StreamSystemCard.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose.nip53LiveActivities
+package com.vitorpamplona.amethyst.commons.ui.nip53LiveActivities
 
 import androidx.compose.foundation.background
 import androidx.compose.foundation.clickable

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/state/AsyncCachedState.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose
+package com.vitorpamplona.amethyst.commons.ui.state
 
 import androidx.collection.LruCache
 import androidx.compose.runtime.Composable

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/state/CachedState.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose
+package com.vitorpamplona.amethyst.commons.ui.state
 
 import androidx.collection.LruCache
 import androidx.compose.runtime.Composable

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/text/TextFieldStateExtensions.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose
+package com.vitorpamplona.amethyst.commons.ui.text
 
 import androidx.compose.foundation.text.input.TextFieldState
 import androidx.compose.ui.text.TextRange

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/ui/text/TextFieldValueExtensions.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose
+package com.vitorpamplona.amethyst.commons.ui.text
 
 import androidx.compose.ui.text.TextRange
 import androidx.compose.ui.text.input.TextFieldValue

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/util/DebugUtils.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.utils
+package com.vitorpamplona.amethyst.commons.util
 
 import com.vitorpamplona.quartz.utils.Log
 import kotlin.time.DurationUnit

commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/util/ListUtils.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.utils
+package com.vitorpamplona.amethyst.commons.util
 
 import kotlinx.collections.immutable.ImmutableList
 

commons/src/iosMain/kotlin/com/vitorpamplona/amethyst/commons/util/DebugUtils.ios.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.utils
+package com.vitorpamplona.amethyst.commons.util
 
 // iosApp (Phase 3) can flip this from a build flag (`DEBUG` Swift compile
 // condition surfaced through the framework). Compile-only target ships false.

commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/model/nip57Zaps/ZapAction.kt

@@ -20,7 +20,7 @@
  */
 package com.vitorpamplona.amethyst.commons.model.nip57Zaps
 
-import com.vitorpamplona.amethyst.commons.services.lnurl.LightningAddressResolver
+import com.vitorpamplona.amethyst.commons.service.lnurl.LightningAddressResolver
 import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
 import com.vitorpamplona.quartz.nip01Core.signers.NostrSigner

commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/service/lnurl/LightningAddressResolver.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.services.lnurl
+package com.vitorpamplona.amethyst.commons.service.lnurl
 
 import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import com.vitorpamplona.quartz.lightning.LnInvoiceUtil

commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/service/lnurl/OkHttpLnurlEndpointResolver.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.services.lnurl
+package com.vitorpamplona.amethyst.commons.service.lnurl
 
 import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import com.vitorpamplona.quartz.nip57Zaps.validate.LnurlEndpointCache

commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/service/nwc/NwcPaymentTracker.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.services.nwc
+package com.vitorpamplona.amethyst.commons.service.nwc
 
 import com.vitorpamplona.amethyst.commons.model.Note
 import com.vitorpamplona.quartz.nip01Core.core.HexKey

commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/ui/markdown/RenderMarkdown.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.compose.markdown
+package com.vitorpamplona.amethyst.commons.ui.markdown
 
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider

commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/util/DebugUtils.jvm.kt

@@ -18,6 +18,6 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.amethyst.commons.utils
+package com.vitorpamplona.amethyst.commons.util
 
 actual val isDebug: Boolean = System.getProperty("amethyst.debug", "false").toBoolean()

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/cache/DesktopLocalCache.kt

@@ -28,7 +28,7 @@ import com.vitorpamplona.amethyst.commons.model.UserContext
 import com.vitorpamplona.amethyst.commons.model.cache.ICacheEventStream
 import com.vitorpamplona.amethyst.commons.model.cache.ICacheProvider
 import com.vitorpamplona.amethyst.commons.model.cache.LargeSoftCache
-import com.vitorpamplona.amethyst.commons.services.nwc.NwcPaymentTracker
+import com.vitorpamplona.amethyst.commons.service.nwc.NwcPaymentTracker
 import com.vitorpamplona.quartz.nip01Core.core.Address
 import com.vitorpamplona.quartz.nip01Core.core.AddressableEvent
 import com.vitorpamplona.quartz.nip01Core.core.Event

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/chess/ChessScreen.kt

@@ -76,9 +76,9 @@ import com.vitorpamplona.amethyst.commons.chess.OverlappingAvatars
 import com.vitorpamplona.amethyst.commons.chess.PublicGame
 import com.vitorpamplona.amethyst.commons.chess.PublicGameCard
 import com.vitorpamplona.amethyst.commons.chess.SpectatingGameCard
-import com.vitorpamplona.amethyst.commons.data.UserMetadataCache
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
+import com.vitorpamplona.amethyst.commons.model.cache.UserMetadataCache
 import com.vitorpamplona.amethyst.commons.ui.components.UserAvatar
 import com.vitorpamplona.amethyst.desktop.account.AccountState
 import com.vitorpamplona.amethyst.desktop.network.DesktopRelayConnectionManager

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/chess/DesktopChessAdapter.kt

@@ -29,7 +29,7 @@ import com.vitorpamplona.amethyst.commons.chess.IUserMetadataProvider
 import com.vitorpamplona.amethyst.commons.chess.RelayFetchProgress
 import com.vitorpamplona.amethyst.commons.chess.RelayGameSummary
 import com.vitorpamplona.amethyst.commons.chess.subscription.ChessFilterBuilder
-import com.vitorpamplona.amethyst.commons.data.UserMetadataCache
+import com.vitorpamplona.amethyst.commons.model.cache.UserMetadataCache
 import com.vitorpamplona.amethyst.desktop.account.AccountState
 import com.vitorpamplona.amethyst.desktop.network.DesktopRelayConnectionManager
 import com.vitorpamplona.quartz.nip01Core.relay.filters.Filter

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/chess/DesktopChessViewModelNew.kt

@@ -28,7 +28,7 @@ import com.vitorpamplona.amethyst.commons.chess.ChessPollingDefaults
 import com.vitorpamplona.amethyst.commons.chess.ChessSyncStatus
 import com.vitorpamplona.amethyst.commons.chess.CompletedGame
 import com.vitorpamplona.amethyst.commons.chess.PublicGame
-import com.vitorpamplona.amethyst.commons.data.UserMetadataCache
+import com.vitorpamplona.amethyst.commons.model.cache.UserMetadataCache
 import com.vitorpamplona.amethyst.desktop.account.AccountState
 import com.vitorpamplona.amethyst.desktop.network.DesktopRelayConnectionManager
 import com.vitorpamplona.quartz.nip01Core.core.Event

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/ArticleEditorScreen.kt

@@ -62,13 +62,13 @@ import androidx.compose.ui.text.TextStyle
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
-import com.vitorpamplona.amethyst.commons.compose.editor.MarkdownEditorState
-import com.vitorpamplona.amethyst.commons.compose.editor.MarkdownToolbar
-import com.vitorpamplona.amethyst.commons.compose.editor.MetadataPanel
-import com.vitorpamplona.amethyst.commons.compose.markdown.RenderMarkdown
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
 import com.vitorpamplona.amethyst.commons.model.nip23LongContent.LongFormPublishAction
+import com.vitorpamplona.amethyst.commons.ui.editor.MarkdownEditorState
+import com.vitorpamplona.amethyst.commons.ui.editor.MarkdownToolbar
+import com.vitorpamplona.amethyst.commons.ui.editor.MetadataPanel
+import com.vitorpamplona.amethyst.commons.ui.markdown.RenderMarkdown
 import com.vitorpamplona.amethyst.desktop.account.AccountState
 import com.vitorpamplona.amethyst.desktop.network.DesktopRelayConnectionManager
 import com.vitorpamplona.amethyst.desktop.service.drafts.DesktopDraftStore

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/ArticleReaderScreen.kt

@@ -66,15 +66,15 @@ import androidx.compose.ui.input.key.onPreviewKeyEvent
 import androidx.compose.ui.input.key.type
 import androidx.compose.ui.platform.LocalClipboard
 import androidx.compose.ui.unit.dp
-import com.vitorpamplona.amethyst.commons.compose.article.ArticleHeader
-import com.vitorpamplona.amethyst.commons.compose.article.TableOfContents
-import com.vitorpamplona.amethyst.commons.compose.article.extractTableOfContents
-import com.vitorpamplona.amethyst.commons.compose.markdown.RenderMarkdown
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
 import com.vitorpamplona.amethyst.commons.model.nip23LongContent.ReadingTimeCalculator
+import com.vitorpamplona.amethyst.commons.ui.article.ArticleHeader
+import com.vitorpamplona.amethyst.commons.ui.article.TableOfContents
+import com.vitorpamplona.amethyst.commons.ui.article.extractTableOfContents
 import com.vitorpamplona.amethyst.commons.ui.components.EmptyState
 import com.vitorpamplona.amethyst.commons.ui.components.LoadingState
+import com.vitorpamplona.amethyst.commons.ui.markdown.RenderMarkdown
 import com.vitorpamplona.amethyst.desktop.account.AccountState
 import com.vitorpamplona.amethyst.desktop.cache.DesktopLocalCache
 import com.vitorpamplona.amethyst.desktop.getText

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/FeedScreen.kt

@@ -83,8 +83,6 @@ import androidx.compose.ui.text.TextRange
 import androidx.compose.ui.text.input.TextFieldValue
 import androidx.compose.ui.unit.dp
 import com.vitorpamplona.amethyst.commons.chess.RelaySyncStatus
-import com.vitorpamplona.amethyst.commons.compose.elements.BoostedMark
-import com.vitorpamplona.amethyst.commons.compose.layouts.GenericRepostLayout
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
 import com.vitorpamplona.amethyst.commons.model.Note
@@ -95,7 +93,9 @@ import com.vitorpamplona.amethyst.commons.search.SearchResultFilter
 import com.vitorpamplona.amethyst.commons.ui.components.EmptyState
 import com.vitorpamplona.amethyst.commons.ui.components.LoadingState
 import com.vitorpamplona.amethyst.commons.ui.components.UserAvatar
+import com.vitorpamplona.amethyst.commons.ui.elements.BoostedMark
 import com.vitorpamplona.amethyst.commons.ui.feeds.FeedState
+import com.vitorpamplona.amethyst.commons.ui.layouts.GenericRepostLayout
 import com.vitorpamplona.amethyst.desktop.DesktopPreferences
 import com.vitorpamplona.amethyst.desktop.SearchHistoryStore
 import com.vitorpamplona.amethyst.desktop.account.AccountState

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/NoteActions.kt

@@ -84,7 +84,7 @@ import com.vitorpamplona.amethyst.commons.model.nip18Reposts.RepostAction
 import com.vitorpamplona.amethyst.commons.model.nip25Reactions.ReactionAction
 import com.vitorpamplona.amethyst.commons.model.nip51Bookmarks.BookmarkAction
 import com.vitorpamplona.amethyst.commons.model.nip57Zaps.ZapAction
-import com.vitorpamplona.amethyst.commons.services.lnurl.LightningAddressResolver
+import com.vitorpamplona.amethyst.commons.service.lnurl.LightningAddressResolver
 import com.vitorpamplona.amethyst.commons.ui.components.UserAvatar
 import com.vitorpamplona.amethyst.desktop.account.AccountState
 import com.vitorpamplona.amethyst.desktop.cache.DesktopLocalCache

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/UserProfileScreen.kt

@@ -73,8 +73,8 @@ import androidx.compose.ui.unit.dp
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
 import com.vitorpamplona.amethyst.commons.model.nip02FollowList.FollowAction
-import com.vitorpamplona.amethyst.commons.profile.ProfileBroadcastBanner
 import com.vitorpamplona.amethyst.commons.profile.ProfileBroadcastStatus
+import com.vitorpamplona.amethyst.commons.profile.ui.ProfileBroadcastBanner
 import com.vitorpamplona.amethyst.commons.state.FollowState
 import com.vitorpamplona.amethyst.commons.ui.components.LoadingState
 import com.vitorpamplona.amethyst.commons.ui.components.UserAvatar

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/note/DesktopRichTextViewer.kt

@@ -53,7 +53,6 @@ import androidx.compose.ui.text.style.TextDecoration
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
 import coil3.compose.AsyncImage
-import com.vitorpamplona.amethyst.commons.compose.markdown.RenderMarkdown
 import com.vitorpamplona.amethyst.commons.emojicoder.EmojiCoder
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
@@ -81,6 +80,7 @@ import com.vitorpamplona.amethyst.commons.richtext.SecretEmoji
 import com.vitorpamplona.amethyst.commons.richtext.Segment
 import com.vitorpamplona.amethyst.commons.richtext.VideoSegment
 import com.vitorpamplona.amethyst.commons.richtext.WithdrawSegment
+import com.vitorpamplona.amethyst.commons.ui.markdown.RenderMarkdown
 import com.vitorpamplona.amethyst.desktop.cache.DesktopLocalCache
 import com.vitorpamplona.amethyst.desktop.service.DesktopCachedRichTextParser
 import com.vitorpamplona.quartz.lightning.LnInvoiceUtil

desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/ui/profile/EditProfileScreen.kt

@@ -76,8 +76,8 @@ import coil3.compose.AsyncImage
 import com.vitorpamplona.amethyst.commons.icons.symbols.Icon
 import com.vitorpamplona.amethyst.commons.icons.symbols.MaterialSymbols
 import com.vitorpamplona.amethyst.commons.profile.EditProfileFields
-import com.vitorpamplona.amethyst.commons.profile.ProfileBroadcastBanner
 import com.vitorpamplona.amethyst.commons.profile.ProfileBroadcastStatus
+import com.vitorpamplona.amethyst.commons.profile.ui.ProfileBroadcastBanner
 import com.vitorpamplona.amethyst.commons.service.upload.UploadOrchestrator
 import com.vitorpamplona.amethyst.desktop.DesktopPreferences
 import com.vitorpamplona.amethyst.desktop.account.AccountState

docs/shared-ui-analysis.md

@@ -1,5 +1,11 @@
 # Shared UI Components Analysis
 
+> **Superseded (2026-05-30).** This was the original feasibility analysis that
+> motivated the `commons` module (then called "shared-ui"). The module now
+> exists and is documented authoritatively in **`commons/ARCHITECTURE.md`**,
+> which defines the package taxonomy, the CLI-safe / UI boundary, and the
+> "where does my code go?" guide. Keep this file only as historical context.
+
 Analysis of Android vs Desktop UI to identify reusable Compose Multiplatform components.
 
 ## Executive Summary