--- title: "feat(polls): extended poll results page (counts + who voted for what)" type: feature status: proposed date: 2026-08-03 owner: commons consumers: amethyst, desktopApp --- # feat(polls): extended poll results page > **Status:** proposal. Nothing implemented. This document surveys what exists, > names four correctness bugs the current tally has, and specifies a shared > results surface for Android and Desktop. _Authored 2026-08-03._ > > **Visual mockup:** [`assets/2026-08-03-poll-results-page.html`](assets/2026-08-03-poll-results-page.html) > — annotated screens for the Android page, the Desktop deck column, the loading / > closed / empty states, and a side-by-side of the two multi-choice percentage > readings from §10.1. Open it in a browser; it renders in Amethyst's own theme > tokens and follows the viewer's light/dark preference. ## 1. Motivation Today a NIP-88 poll (kind 1068) renders its results **inline in the feed**, and the results are deliberately tiny: a progress bar, a percentage, and up to four voter avatars per option (`Poll.kt:571 UserGallery` shows `take(4)` then `+N`). There is no way to answer the two questions people actually ask about a poll: 1. **How many votes did each answer get?** — the card shows only a percentage, never a count, and the percentage denominator is wrong for multi-choice polls (§3.1). 2. **Who voted for what?** — Android gives you at most four avatars and no way to see the fifth. Desktop already went further (`DesktopPollCard.kt:576 VoterListPopup`), which proves the demand but leaves the two platforms divergent and the logic unshared. A dedicated results page also unlocks the things a feed card can never host: filtering the voter list to people you follow, searching it, sorting it, and being honest about *how complete the tally is* — which today it silently is not (§3.4). ## 2. What exists today | Layer | Component | File | |---|---|---| | Protocol | `PollEvent` (1068): `options()`, `relays()`, `pollType()`, `endsAt()`, `hasEnded()` | `quartz/…/nip88Polls/poll/PollEvent.kt:63` | | Protocol | `PollResponseEvent` (1018): `responses()`, `poll()` | `quartz/…/nip88Polls/response/PollResponseEvent.kt:62` | | Tally | `PollResponsesCache` + `ResponseTally` + `TallyResults` — the single source of truth, hung off `Note.pollState()` | `commons/…/model/nip88Polls/PollResponsesCache.kt` | | Attach | `Note.poll` / `pollState()` | `commons/…/model/Note.kt:178` | | Ingest | `consume(PollResponseEvent)` → `getOrCreateNote(pollId).pollState().addResponse(...)` | `amethyst/…/model/LocalCache.kt:2936` | | Write | `Account.pollRespond(event, responses)` | `amethyst/…/model/Account.kt:2018` | | UI (Android) | `RenderPoll` / `RenderPollCard` / `RenderResults` / `RenderClosedItem` / `UserGallery`, view-state `PollCard` + `PollItemCard` | `amethyst/…/ui/note/types/Poll.kt` | | UI (Desktop) | `DesktopPollCard`, `PollResultRow`, `VoterGallery`, `VoterListPopup` | `desktopApp/…/ui/note/DesktopPollCard.kt:95` | | Feed | `Route.Polls` tab + `PollsFeedFilter` / `OpenPollsFeedFilter` / `ClosedPollsFeedFilter` | `amethyst/…/ui/screen/loggedIn/polls/` | | Zap polls | `ZapPollEvent` (6969) + `PollNoteViewModel` (amount-weighted, zap-receipt tally) | `quartz/…/experimental/zapPolls/`, `amethyst/…/ui/note/ZapPollNoteViewModel.kt` | **Reuse verdict:** `PollResponsesCache` is the right foundation and should not be replaced — but it must become *poll-aware* (§3). The results page needs **no new event kind, no new cache, and no new feed filter**; it needs a poll-aware tally, one shared subscription, one shared ViewModel, and two thin platform shells. ## 3. Correctness gaps to fix first These are not cosmetic. Three of them make the numbers on the current card wrong, and the results page would inherit all of them. Each is cheap to fix and the fix improves the inline card too. ### 3.1 Multi-choice percentages use the wrong denominator `ResponseTally.totalVotes()` (`PollResponsesCache.kt:52`) sums the per-option voter sets, so a voter who picks 3 options is counted 3 times. `filterTo` divides by that (`:88-95`). On a multi-choice poll the percentages therefore sum to 100% and read as "share of selections" — but users read a poll bar as "share of people". Desktop already diverges here, using `tallyState.votes.size` ("distinct voters", `DesktopPollCard.kt:196`) for its footer while its bars use the selections denominator. **Proposal:** make the basis explicit and platform-consistent. ```kotlin fun totalVoters(): Int = votes.size // distinct pubkeys fun totalSelections(): Int = tally.entries.sumOf { it.value.size } ``` - single-choice → identical, no visible change; - multi-choice → percent = `optionVoters / totalVoters`, bars may sum past 100%, and each row is captioned **"N of M voters"** so the reading is unambiguous. ### 3.2 Single-choice polls count every `response` tag NIP-88: *"for singlechoice polls, the first response tag is to be considered the actual response."* `votesByOption()` (`PollResponsesCache.kt:129-143`) iterates **all** response tags regardless of poll type, so one malformed (or hostile) 1018 with a `response` tag per option gets counted in every bucket. `ResponseTally` cannot fix this today because it never sees the `PollEvent`. ### 3.3 Votes outside the poll timeframe still count NIP-88 keeps the latest response *within the poll timeframe*. `latestByAuthor()` (`Note.kt:1685`) only compares `createdAt` — a vote stamped after `endsAt` wins over a legitimate earlier one, and a closed poll's totals keep moving. ### 3.4 Unknown option codes inflate the tally A `response` tag whose code isn't in `PollEvent.options()` creates a phantom bucket that still contributes to `totalVotes()`, dragging every real percentage down. It should be dropped (and counted separately, so the results page can show "3 responses ignored (invalid)"). ### 3.5 The fix: a poll-aware tally All four collapse into one change — give the tally the poll it belongs to: ```kotlin // commons/…/model/nip88Polls/PollTallyPolicy.kt (new) @Immutable class PollTallyPolicy( val validCodes: Set, val type: PollType, val createdAt: Long, val endsAt: Long?, ) { fun isInWindow(createdAt: Long) = createdAt >= this.createdAt && (endsAt == null || createdAt <= endsAt) fun accept(codes: List): Set = when (type) { PollType.SINGLE_CHOICE -> setOfNotNull(codes.firstOrNull { it in validCodes }) PollType.MULTI_CHOICE -> codes.filterTo(mutableSetOf()) { it in validCodes } } } ``` `PollResponsesCache` gains `var policy: PollTallyPolicy?`, set by `LocalCache.consume(PollEvent)` (and by `DesktopLocalCache.consume`) when the poll event itself arrives — responses routinely arrive **before** the poll they reference, so `ResponseTally` must recompute when the policy lands, and must degrade to today's permissive behaviour while `policy == null`. `ResponseTally` then also exposes `rejected: Int` for the "ignored" caption. Note the ordering hazard is real and already present: `consume(PollResponseEvent)` calls `getOrCreateNote(pollId).pollState().addResponse(...)` (`LocalCache.kt:2936`) on a note that may still be an empty placeholder. ## 4. Data completeness (the second reason to fix this now) **Android never queries a poll's own relays for votes.** Kind 1018 rides along in the generic engagement filter (`FilterRepliesAndReactionsToNotes.kt:75`), whose relay set is `Note.relayUrlsForReactions()` = *author inbox relays + relays the note was seen on* (`Note.kt:339`). NIP-88 votes are published to the relays listed in the poll's own `relay` tags (`EventBroadcaster.kt:233` does this on the write side), which the viewer usually isn't subscribed to. Desktop diagnosed and fixed this per-card (`DesktopPollCard.kt:132-157`); Android tallies are systematically short. That same filter also carries `limit = 100` and never pages, so any poll with more than 100 responses truncates silently. **Proposal — one shared assembler, used by both platforms and by the results page:** - `commons/…/relayClient/…/polls/PollResponsesFilterAssembler.kt` — a compose-scoped `Subscribable` keyed by poll id, filtering `kinds = [1018], tags = {"e": [pollId]}` over `PollEvent.relays() + the viewer's read relays` (this is desktop's fix, lifted out of the card). - The results page additionally does a one-shot backfill with **`fetchAllPages`** from `quartz/…/nip01Core/relay/client/accessories/` — do **not** hand-roll a paging loop; that package already has it. - Optional but cheap: a NIP-45 **`count`** call (same package) per relay gives "relay reports 412 responses, 380 loaded" — the page can then be honest about incompleteness instead of presenting a partial tally as final. ## 5. Screen design ### 5.1 Anatomy ``` ┌─────────────────────────────────────────────┐ │ ← Poll results ⟳ │ TopBarWithBackButton ├─────────────────────────────────────────────┤ │ [avatar] Alice · 2d ago │ author row (UserCompose-style) │ "Which relay should we default to?" │ poll question (content) │ ⬤ Open · closes in 4h ⬡ Single choice │ status + type chips │ 412 voters · 412 selections │ totals (§3.1) ├─────────────────────────────────────────────┤ │ ▸ nos.lol 189 46% ✓ │ option rows, winner marked, │ [▓▓▓▓▓▓▓▓▓░░░░░░░░░░] ◍◍◍◍ +185 │ animated bar + avatar stack │ ▸ relay.damus.io 142 34% │ │ [▓▓▓▓▓▓░░░░░░░░░░░░░] ◍◍◍◍ +138 │ │ ▸ purplepag.es 81 20% │ ├─────────────────────────────────────────────┤ │ You voted: nos.lol [Change vote] │ only when signed in + voted ├─────────────────────────────────────────────┤ │ [All] [nos.lol] [damus] [purplepag.es] │ option filter chips ├─────────────────────────────────────────────┤ │ ⬤ Ana Reis nos.lol 2d ago │ voter rows — UserLine as-is │ ana ✓ nostrcheck.me │ (§6.1): picture / name / │ ⬤ Bruno Sá damus 2d ago │ NIP-05, vote passed in as │ bruno ✓ nostrplebs.com │ trailingContent │ ⬤ npub1q8f…j3xw damus 22h ago│ (npub = no-NIP-05 fallback) │ … │ ├─────────────────────────────────────────────┤ │ 380 of ~412 loaded from 6 relays · 3 ignored│ completeness footer (§4) └─────────────────────────────────────────────┘ ``` Audience filter, sort and voter search are **deliberately not in the first version** — see §5.3. ### 5.2 Behaviour decisions | Question | Decision | Why | |---|---|---| | Percent basis | single-choice: % of voters; multi-choice: % of voters, bars may exceed 100% in sum, each row captioned "N of M voters" | §3.1 — matches how people read a poll | | Voter list default | flat list of **all** voters, each row showing which option(s) they chose | answers "who voted for what" in one screen without drilling | | Voter row | `UserLine` unmodified, with the vote passed as its existing `trailingContent` (§6.1) | a voter is a user; the app already has this row, and it already has the slot | | Option chips | filter the voter list to one option; the summary block never filters | keeps totals stable while browsing | | Muted users | excluded by default via `account.isHidden`, with a footer line "2 hidden by your mute list" | consistent with every other user list in the app | | Ordering | you first, then follows, then pubkey — today's `filterTo` comparator, no sort control | the ordering already exists and already does the useful thing | | Live updates | the page is a live view of `pollState().responses`; new votes animate in | it's a StateFlow already; no refresh button needed except for the relay backfill | | Closed polls | status chip flips to "Ended · 2d ago", "Change vote" disappears, late votes excluded (§3.3) with an "N late votes excluded" footnote | spec compliance, and it explains a number that would otherwise look wrong | | Empty state | "No votes yet" + the option rows at 0 | | ### 5.3 Deferred to a later pass Three controls are specified here so the layout leaves room for them, but are **not** part of the first version: - **audience filter** (`Everyone` / `Following` / `Following + WoT`), - **sort control** (`Newest` / `Oldest` on top of the default relevance order), - **voter search**. Each is cheap on its own — the follow set and the comparator both already exist — but none of them is needed to answer "how many votes did each answer get, and who voted for what". They land once the page is real and it's clear which of them people actually reach for. Until then the list is ordered you → follows → rest, and the option chips are the only filter. ## 6. Code structure Following `commons/ARCHITECTURE.md` (state + ViewModels + shared Compose in `commons`, screens/nav platform-native): ### 6.1 The voter row is `UserLine`, unmodified A voter is a user, and the app already has a user row with a trailing slot: **`UserLine`** (`amethyst/…/ui/note/creators/userSuggestions/ShowUserSuggestionList.kt:185`), the row the mention autocomplete and the follow-import screens use. It is `SlimListItem` (`ui/layouts/listItem/SlimListItemLayout.kt:168`) with: | Slot | Filled with | Renders | |---|---|---| | `leadingContent` | `ClickableUserPicture(user, Size55dp, …)` | avatar | | `headlineContent` | `UsernameDisplay(user, accountViewModel)` | petname → `bestName()` → `pubkeyDisplayHex()`, with custom-emoji support via `CreateTextWithEmoji` | | `supportingContent` | `WatchAndDisplayNip05Row(user, accountViewModel)` | the NIP-05 identifier — local part, verified symbol, domain — in `colorScheme.nip05` | | `trailingContent` | **caller-supplied, already `null`-able** | — | ```kotlin fun UserLine( baseUser: User, accountViewModel: AccountViewModel, trailingContent: (@Composable (User) -> Unit)? = null, colors: ListItemColors = ListItemDefaults.colors(), onClick: () -> Unit, ) ``` So the results screen writes **no row at all** and modifies **no existing composable** — it calls `UserLine` and passes the option label plus the relative timestamp as `trailingContent`. Voter rows then inherit for free the things a hand-rolled row silently loses: petname overrides, emoji in display names, live NIP-05 verification state, and the npub fallback when nothing else has arrived. Two consequences worth stating: - **The second line is the NIP-05 identifier, not the npub.** `WatchAndDisplayNip05Row` (`:214`) renders `pubkeyDisplayHex()` only in the `else` branch, when the user has no NIP-05 — it is a fallback, not the intended content. Note the app draws it as *name · verified symbol · domain* with no `@` (`:236-258`), and the `hasLocalPart()` check means a root identifier (`_@domain`) shows the domain alone. - **No bespoke "follows" or "you" chip.** No user row in the app has one, and the ordering (you → follows → rest) already carries that information. If a follow marker is wanted later it should come from the existing follow-state renderer, not a badge invented for this screen. The one loose end: `UserLine` lives under `note/creators/userSuggestions/`, a mention-autocomplete package, despite being a general-purpose row with three callers already. Moving it to `ui/note/` is a tidy-up this change makes worthwhile but does not require. ### 6.2 New and edited files **New in `commons` (shared):** | File | Contents | |---|---| | `model/nip88Polls/PollTallyPolicy.kt` | §3.5 | | `model/nip88Polls/PollResponsesCache.kt` *(edit)* | poll-aware `ResponseTally`, `totalVoters()`, `totalSelections()`, `rejected`, `lateVotes` | | `viewmodels/nip88Polls/PollResultsViewModel.kt` | holds the poll `Note`; exposes `StateFlow` (header + option rows + voter rows + completeness meta); owns the option-chip selection; drives the backfill. Sibling in style to `viewmodels/LiveStreamTopZappersViewModel.kt`, with the usual nested `Factory` | | `relayClient/…/polls/PollResponsesFilterAssembler.kt` | §4 | | `ui/note/polls/PollResultsHeader.kt`, `PollOptionBreakdown.kt` | slot-based shared composables for the header and the option bars, per `compose-slot-api-pattern`. **No shared voter-row composable** — each platform's own user row fills that job (§6.1) | **New in `amethyst` (Android):** - `ui/screen/loggedIn/polls/results/PollResultsScreen.kt` — `LoadNote(noteId) { … }` + `Scaffold(topBar = TopBarWithBackButton(...))` + `LazyColumn`, modelled on `ContactListUsersScreen.kt:51`, which is the established "users related to note X" screen in this codebase. - `Route.PollResults(val noteId: String)` in `ui/navigation/routes/Routes.kt`, registered with `composableFromEndArgs` in `AppNavigation.kt` (the slide-in detail-screen builder). **New in `desktopApp`:** - `DeckColumnType.PollResults(noteId)` in `ui/deck/DeckColumnType.kt` (plus the `title()` and `typeKey()` branches — those `when`s are exhaustive) and a render branch in `DeckColumnContainer.kt`. Keep `VoterListPopup` as the quick peek and add a **"See all voters"** footer that opens the column. Its voter rows follow the same rule as §6.1 against desktop's own user-row composable rather than the bespoke avatar+name pair in `VoterListPopup`. **Edited (entry points):** - `Poll.kt` — make the totals line and the `UserGallery` `+N` chip clickable → `nav.nav(Route.PollResults(noteId))`; add a "N votes" count next to the percentage (currently absent). - Note dropdown menu — a "Poll results" item when the note is a `PollEvent`. **Deliberately not built:** no new feed filter, no new event kind, no second cache, no per-platform tally logic. ## 7. Zap polls (kind 6969) — phase 4 `ZapPollEvent` results are **amount-weighted** (`PollNoteViewModel.refreshTallies()`, `ZapPollNoteViewModel.kt:102`), not one-person-one-vote, so they share the page *shell* but not the tally: - option rows show **sats per option** + zapper count, plus the poll's `consensusThreshold` drawn as a line on the bars; - voter rows are ordered by amount and show the amount; - private zaps are visible only where the viewer can decrypt them (`cachedIsPollOptionZappedBy`, `:230`) — the page must say "some zaps are private and not shown" rather than quietly under-count. Sequencing it last keeps the NIP-88 work from being blocked on reconciling two very different tally models. ## 8. Testing - Extend `commons/src/commonTest/…/model/nip88Polls/PollResponsesCacheTest.kt`: single-choice response carrying 3 tags counts once (§3.2); vote after `endsAt` excluded and counted as late (§3.3); unknown code rejected and excluded from the denominator (§3.4); multi-choice `totalVoters` vs `totalSelections` (§3.1); policy arriving *after* responses recomputes the tally (§3.5); duplicate pubkey latest-wins (existing behaviour, lock it in). - New `PollResultsViewModelTest` with Turbine: option-chip transitions, mute exclusion, live insertion of a new vote. - Manual: a >100-response poll (paging), a poll whose `relay` tags the viewer isn't connected to (completeness), a multi-choice poll (denominators). ## 9. Phasing | Phase | Scope | Ships value alone? | |---|---|---| | 0 | Poll-aware tally (§3) — commons + tests | yes — fixes the inline card's numbers on both platforms | | 1 | Shared subscription + backfill (§4) | yes — Android tallies stop being short | | 2 | `PollResultsViewModel` + shared composables + Android screen + route + entry points | yes — the feature | | 3 | Desktop column | parity | | 4 | Audience filter, sort, voter search (§5.3) | once it's clear which are actually reached for | | 5 | Zap polls (§7) | breadth | Phases 0 and 1 are worth landing even if the page itself is deferred: they are bug fixes wearing a feature's clothes. ## 10. Open questions 1. **Multi-choice bars summing past 100%** — the honest rendering, but visually unusual. Alternative: keep selections as the basis and caption "% of selections". Needs a call before §3.1 lands. 2. **Should the results page be reachable for polls you haven't voted on yet?** The inline card deliberately hides results until you vote / opt in (`Poll.kt:298-336`, `hasViewedPollResults`). Proposal: the page respects the same gate — reaching it counts as opting in and calls `markPollResultsViewed`, exactly like today's "View results" link. 3. **Move `UserLine` out of `userSuggestions/`?** It is a general-purpose row sitting in a mention-autocomplete package (§6.1). The poll screen is its fourth caller. Move it to `ui/note/` with this change, or leave it and import across packages? 4. **Export/share results** (copy as text, or a rendered image) — desirable, but listed as out of scope until the page exists.