memby/VIEWERS.md

# Viewers

**A Memby account is the household's relationship with an Emby user. A viewer is one
person under it.** Every account has exactly one **main** viewer, whose state is Emby's,
and any number of **shadow** viewers, whose state is Memby's alone. A shadow viewer
watches through the account's Emby credentials and Emby never learns what they watched.

```
Emby user
  └── Memby account (Living Room)
      ├── Matt        main    → watched state, progress and favourites go to Emby
      ├── Alessandra  shadow  → state lives in Memby
      └── Guest       shadow  → state lives in Memby
```

A viewer does **not** belong to a television. Somebody starts an episode in the lounge and
finishes it in the bedroom, because the state is the gateway's.

## What was verified before any of this was written

**Every write of Emby viewer state passes through four methods** on `emby.Client`:
`ReportPlayback`, `SetFavorite`, `SetPlayed` and `HideFromResume`. All four are called
only from `api` handlers holding a `store.Session`. Nothing else writes viewer state, so
keeping a shadow viewer out of Emby is four branches rather than a sweep of the codebase.
That is the property this feature is built on, and it is the one to re-check before
adding any new call into `emby.Client`.

**Two things still reach Emby, and both are accepted deliberately.** `PlaybackInfo` is
sent with `IsPlayback: true`, which registers a play session — so shadow playback appears
in Emby's Now Playing and activity log as the account. And `tracearr` identifies viewers
by *Emby username* (`tracearr/client.go`), so a shadow viewer's watching feeds the
account's Tracearr history, watch-time figures and genre affinity. Neither touches watched
state or resume position, which is what the feature promises. Both are v2 problems.

**There is no second implementation on the direct path.** On the direct-to-Emby path the
television reports straight to Emby itself, so there is nothing in between to route a
viewer's state to — the stance the TV calendar and genre affinity already take. Viewers
are gateway-only, and a set with no gateway has one viewer, which is the account.

## The seam: a viewer id, not a second user

Before this, `sess.EmbyUserID` did two unrelated jobs — it was the Emby credential *and*
Memby's key for "who is watching". Viewers separate them:

- **The credential stays the account's.** `credentials(sess)` is unchanged, and every
  library read, image, stream URL and subtitle still goes out as the Emby user. A shadow
  viewer has no Emby identity and needs none.
- **The person is `viewer.ID`.** Preferences, notifications, followed shows, row
  statistics, search history, recommendation profiles and cache keys belong to whoever is
  watching.

**The main viewer's id *is* the Emby user id**, which is the whole reason this needed no
migration. Every table in the schema keys a person by a bare `emby_user_id TEXT` with no
foreign key behind it, so substituting a viewer id leaves an existing household's rows
exactly where they were, and the main viewer behaves as the account did by construction
rather than by care. A shadow id is `"v"` plus 32 hex characters, so it can be told apart
from Emby's 32-hex GUIDs by inspection in a log line or a cache key
(`store.IsShadowViewerID`).

`Viewer.Kind` is still stored and is what every branch reads. The id shape is a safety
property, not a source of truth.

## How a request learns who is watching

`X-Memby-Viewer`, resolved by `s.activeViewer` (`api/viewers.go`).

It is a header rather than part of the session because switching between two people on one
television must not be a re-authentication, and because the same person is one viewer on
every set in the house. The session still answers "which account is this and what may it
read".

Things to preserve:

- **It is stated, never inferred** — the stance `Credentials.Gateway` takes. An app that
  predates viewers sends nothing and resolves to the main viewer, which is exactly its
  previous behaviour.
- **Every unknown case falls back to the main viewer**, including a list that will not
  load. This is on the path of every authenticated request, and a television unable to do
  anything because a header could not be checked is a far worse failure than one request
  attributed to the account. The one thing it will not do is accept an id it could not
  confirm belongs to this account.
- **An unknown id is logged, not refused.** The ordinary cause is a set still holding a
  viewer somebody has since deleted, and a 403 on every request would leave it unable to
  reach the picker that would fix it.
- **The list is cached for `viewerListTTL`** and the write clears it, because `/v1/status`
  alone is every open television every ten seconds — the bargain `featurePolicyCache`
  already makes. A failed refresh keeps the previous reading rather than dropping to the
  main viewer, which would silently move a shadow viewer's playback back onto Emby.

## The common state layer

`viewerUserData` renders a viewer's state in the shape of Emby's `UserData` block, and the
television never learns which it received. That is what keeps viewers from becoming a
special case in every screen: a card draws its progress bar, tick and heart from
`UserData`, and where the block came from is not a question anything above that line asks.

The client reads exactly five fields (`UserItemData` in `EmbyModels.kt`), and
`viewers_test.go` pins them. Two are omitted rather than sent empty — a title with no
runtime has no percentage, and one never played has no date — because a card claiming a
zero-length progress bar is worse than one claiming nothing.

## Where state is written

`viewer_playback_state`, keyed `(viewer_id, item_id)`. The Emby item id is the common
identifier, so no library metadata is duplicated and nothing here needs invalidating when
the catalogue changes. **There is deliberately no row for a main viewer**: their state is
Emby's, and a copy here would be a second answer free to disagree with what the
household's other Emby clients see.

- **A completed title is stored at position zero**, the way Emby stores one. The position
  is what Continue Watching reads, and a finished episode left at its last frame is one the
  row keeps offering to resume four seconds from the end.
- **Only a stop can complete a title.** A progress report crossing the threshold is
  somebody still watching the closing minutes, and marking it played there would take the
  episode out of Continue Watching underneath them.
- **`PlayedFromPosition` is the completion rule and it matches Emby's own** (90%), so a
  household cannot disagree with itself about whether an episode is finished depending on
  who watched it. A runtime of zero means the length was not known rather than that the
  title is zero long, so it can never complete anything.
- **`play_count` moves only on the transition into played**, so the ten-second reports
  either side of the threshold cannot count one viewing several times.
- **The series is read out of `library_items` inside the upsert**, not asked of Emby and
  not carried by the television. It is already there, it is what will order this viewer's
  Continue Watching, and a report arrives every ten seconds.
- **Hiding keeps the position.** Hiding is a statement about the row, not about where
  somebody got to, and pressing Play again should still resume.

## What a viewer reads

The write side is four branches. The read side is the larger half, and it is deliberately
**one substitution rather than a second code path**: the fan-out, the failure counting and
the Continue Watching merge in `handleHome` are identical for both kinds of viewer, and
only the fetch behind three rows changes.

**Everything is keyed on `viewerKeyOf(ctx, sess)`.** The viewer is resolved once, in
`authed`, and carried in the request context (`withViewer` / `viewerOf`). That is the
point: the alternative is calling `activeViewer` at each of the fifteen sites that build a
cache key, and the failure of forgetting one is silent — that view is keyed under the
account, and one viewer is served another's rows. Resolving at the boundary makes
forgetting impossible. A request that never passed through `authed` — a scheduled task, a
probe, a test — resolves to the account, which is the value every one of these keys held
before viewers existed.

**Cache keys that moved to the viewer**: home, search, genre and library browse, item
detail, series episodes, person filmography, related, the active hero. **Keys that
deliberately did not**: genre affinity, trailers, the screensaver, recommendations and the
Magic pool. Those answer for the household or are computed from the account's Tracearr
history, and keying them per viewer would multiply the misses without changing the answer.
They are the v2 list.

**`decorateItems` is the one door items leave the gateway through.** It attaches the
stored review scores and, for a shadow viewer, replaces the `UserData` block. It rides
exactly where `decorateItemRatings` rode — one indexed read for a whole launcher, at every
point items are served. The two remained separate functions because they are separate
concerns, but every call site wanted both, and *a decoration added at seven sites is a
decoration missing from the eighth*.

Things to preserve in `decorateViewerState`:

- **A main viewer returns immediately.** Their state is Emby's and is already on the
  payload, so a household running no viewers pays one comparison for the whole launcher.
- **Every item is rewritten, not only the ones with something stored.** The `UserData`
  that arrived from Emby is the *account's*, and leaving it on a title this viewer has
  never touched is precisely the leak the feature exists to prevent. A title with no row
  gets the zero state, which is the truth about it. A failed state read blanks everything
  for the same reason: a launcher with no progress bars is a poor answer, one showing
  somebody else's is a wrong one.
- **The block is replaced, never merged.** A partial overlay leaves whichever fields Memby
  had nothing to say about carrying the account's values — the same leak from a narrower
  angle.
- **A series and a season are answered from a count**, not from a row of their own. Emby
  fills their block in from children it has never heard of for this person, so
  `ViewerContainerStates` counts the episodes the shared catalogue holds against this
  viewer's own played set and `viewerAggregateUserData` renders the result. This was the
  last place a shadow viewer was shown the account's answer — a series ticked because
  somebody else had finished it.

## What a series card says

`UnplayedItemCount` and `PlayedPercentage` are **omitted rather than sent as zero** when the
catalogue cannot count the title, the rule the leaf block follows: a library not yet
imported, and a show the import has never seen, would otherwise tick every series in the
house. `Played` is only true where there is something to have finished, for the same reason.

The **favourite is the container's own** and comes from the row against the series id, not
from the count: somebody marks a *show* a favourite, not the sum of its episodes. And a
container is never resumable — what resumes is an episode — so `PlaybackPositionTicks` is
zero, which is what Emby reports too.

The query groups by the **season/series pair** and the two rollups are done in Go
(`addViewerAggregate`). That is deliberately dull — no grouping sets, no second pass — and
it is exact for both answers because a season belongs to exactly one series. `containerIDsIn`
asks for a season's series alongside it, which is what keeps a partial series total from
belonging to anything drawn. `library_items_series_episodes_idx` is what makes it affordable;
without it, a series card costs a scan of every episode in the library, and it is also what
`ViewerNextUp` walks.

## The three rows that are about a person

`resume`, `favourites` and `nextup` are substituted in the home fan-out. The ranking is
Postgres's and Emby is asked only to *describe* the titles — which is why `orderItemsByID`
exists: Emby answers an `Ids=` query in its own order, and for these rows the order **is**
the answer. Handing Emby's order back would keep the right titles and throw away the reason
they were chosen. It also drops a title Emby will not answer for (a card that cannot be
opened is worse than a missing one) and collapses a repeated id, because every keyed list
on the television throws on a duplicate.

**Next Up is computed entirely in Postgres** (`store.ViewerNextUp`), out of the shared
catalogue and this viewer's own state. Emby's `NextUp` answers for the account and there is
nobody else to ask — and the alternative, walking each series' episode list over the wire,
is one Emby request per show on the tail of the launcher. It applies the same three rules
Emby's own answer does: an episode already resumable is left out (it is in Continue
Watching, and the merge would offer the show twice), specials are not next episodes, and a
series with nothing unwatched left contributes no row rather than an empty one.

**The merge is unchanged.** `ViewerWatchedSeries` returns exactly the
`map[string]time.Time` that `recentlyPlayedSeries` does, so `mergeContinueWatching` never
learns which viewer it is ordering for.

## Where a shadow viewer's playback starts

Taken from the store in `handlePlayback`, not trusted from the card. The hint the
television sends is read off a card this gateway already decorated with the viewer's own
state, so the two normally agree — but only normally: the store has heard about the episode
they were part-way through on the *other* television, and a card is only as fresh as the
last home refresh. It is also the value handed to `PlaybackInfo`, so taking it here fixes
the negotiated stream as well as the number sent back. A failed read starts from the
beginning, because that is a recoverable disappointment where starting from where somebody
else got to is not.

**Pressing Play on a series** resolves through `firstUnwatchedEpisodeFor` rather than
Emby's `NextUp`, which is what would otherwise drop a shadow viewer into the middle of
somebody else's season. A part-watched episode wins over the first unwatched one — somebody
eleven minutes in wants that episode, the same judgement the Continue Watching merge makes.
A viewer with nothing recorded for the series falls through to Emby's first episode, which
is the right answer for somebody who has never watched any of it.

**Auto-advance** keeps Emby's answer for *which* episode follows — that is a property of
the season and is the same for everybody — and replaces only how far into it this viewer
already is.

## Signing out is about the account

`invalidateAccountViews` drops every viewer's cached views, not only the account's.
Invalidating one key would leave each shadow viewer's rows behind, to be served intact to
the next person who signs in on that set. It is best-effort: what it misses expires on its
own TTL, and nothing there is worth failing a sign-out over.

## The television

**`X-Memby-Viewer` is sent by `GatewayAuthInterceptor`**, read on each request rather than
captured — the bargain the audio capability tokens already make. Switching between two
people must not rebuild the HTTP client, and the answer can change between any two
requests. The header is **omitted rather than sent empty** when nobody has been chosen,
because that is precisely what an app predating viewers sends and what the gateway reads as
the account's own viewer. The read is guarded, like the audio tokens, because the
interceptor also runs before the service locator exists in a screenshot context.

`viewers_v1` joins `MEMBY_CAPABILITIES`, so an operator cannot switch the feature on for a
household half of whose televisions have no way of choosing between people.

**The active viewer is device state**, and it is the one thing about viewers that is: a
viewer follows the person to every set in the house, but which of them is sitting in front
of *this* one is that set's own answer — the lounge and the bedroom are commonly two
different people at the same moment. `activeViewerId` and `activeViewerName` are written in
**one** edit (DataStore rewrites the whole file per edit, and a name landing apart from the
id it labels would leave the launcher greeting one person while every request named
another), and both are cleared with the session and on any account switch: the people under
one Emby account are not the people under another.

**The home cache is keyed per viewer**, `home_cache::<userId>@<serverUrl>#<viewerId>`. A
cold start draws the cache before the first refresh lands, so without this a shadow viewer
would open on the account's evening. **The account's own viewer keys exactly as it always
did, with no suffix**, so every existing install keeps the cache it already has. Removing a
profile now clears *every* viewer's key for it (`profileHomeCacheKeys`), or the largest
values this store holds would be orphaned.

`switchViewer` clears the playable, series-episode, local-resume and genre-affinity caches —
the same set a profile switch clears, for the same reason: they hold one person's watched
state, resume positions and reasons. It deliberately does **not** clear the persisted home
cache, which is keyed per viewer, so switching back is instant.

**The gateway's `active` field is adopted.** `viewers()` compares what the server resolved
the request to against what this set is sending, and takes the server's answer when the two
disagree and the id is not in the list. The case it exists for is a viewer deleted on
another television: this set is still sending an id nothing recognises, the gateway has
quietly fallen back, and without adopting that the picker would go on showing somebody who
no longer exists as selected.

## The picker

`ui/viewers/ViewerPicker.kt` — "Who's watching?", a full screen rather than another row in
the user switcher. That panel lists *accounts* and the actions beside them; a viewer is a
different grain of thing, and a household picks a person the way they pick one on any
television service, by looking at a row of faces. Folding them into the same 292dp column
would have made two unrelated questions look like one list.

Stateless, the stance `SignInContent` and the detail panes take, so
`ViewerPickerScreenshotTest` renders it with no gateway → `build/screenshots/viewers/`.
Things to preserve:

- **Focus opens on whoever is watching**, not on the first card: a television is switched on
  by the person who last used it far more often than not, so the common case is one confirm
  press rather than a walk along the row.
- **The scroll keeps one card of context behind the focused one**
  (`viewerPickerScrollIndex`). Scrolling straight to the focused card pins it against the
  left edge and the people before it vanish with nothing saying they are there — the capture
  is what caught it. Focus and scroll are separate functions because they answer different
  questions: where the remote is, and what the eye can see.
- **"Synced with Emby" is a reserved line, not a conditional one**, or a card without it
  sits taller than the one beside it — the rule the cast grid's character line follows. It
  is most of the difference between a household understanding this feature and being puzzled
  by it.
- **The scale is read only inside `graphicsLayer`**, so travelling the row redraws two cards
  rather than recomposing every card in it.
- **A blank active id means the account's own viewer**, because that is what the header's
  absence means to the gateway. Writing the main viewer's id instead would work on the wire
  and would be worse in one way: an app never told the account's Emby user id could not then
  express "nobody in particular", which is the state every existing install starts in.
- **The Add control is removed at the limit, never dimmed** — the stance the two optional
  transport controls take.
- `MAX_SHADOW_VIEWERS` mirrors `store.MaxShadowViewers`; the gateway is what enforces it,
  and this copy only decides whether to offer a button whose one possible outcome would be a
  refusal.

## The way in

A row in `UserSwitcherOverlay`, above Notifications, because it changes *whose* menu that
is — the notifications and requests below belong to whichever viewer it selects.
`viewerMenuLabel` names the person once somebody other than the account is watching
("Watching as Alessandra") and asks the question otherwise: a household running no viewers
must not have a badge appear over its launcher explaining a feature it is not using. The
panel's own subtitle becomes "Choose an account" when the row is present, since the list
above it is no longer the thing that answers "who is watching".

`shouldOfferViewerPicker` gates it on two conditions and both matter: there is nobody to ask
on the direct path, and an account nobody has added a viewer to would be offered a question
with one answer, which reads as a fault rather than as a feature waiting to be used.

**The switcher's rows are now a list** (`userSwitcherMenuItems`) rather than four
hand-written offsets (`profiles.size + 1`, `if (showRequests) 2 else 1`,
`actionCount - 1`). A count that disagrees with the rows actually drawn is how the last item
in a menu becomes unreachable, and a fifth conditional row is exactly the change that breaks
it — the shape `QuickAction` already moved to for the same reason. The D-pad test now runs
over every combination of optional rows.

## Built

- `viewers` and `viewer_playback_state` in `store/schema.sql`, with the main viewer created
  on demand so an account predating the feature resolves on its first request.
- `store/viewers.go`, `store/viewer_playback.go` — the viewer list, the state layer,
  Continue Watching, Next Up, favourites and the series-recency ordering.
- `api/viewers.go` — header resolution, the cached list, the context plumbing,
  `viewerUserData`, `invalidateAccountViews`, and the four CRUD routes.
- `api/viewer_state_attach.go`, `api/viewer_rows.go` — the read side.
- **The four mutations are gated**, and For You is marked dirty only for the main viewer.
- Every log line names the viewer when it is somebody other than the account.
- **The television**: the header and its capability, the active viewer as device state, the
  per-viewer home cache, `EmbyRepository`'s viewer operations, the picker, the row in the
  user menu that opens it, and the name-entry and manage screens behind it.
- **The operator's switch**, and the Viewers card on the console's account page.
- **Series and season aggregates**, so a shadow viewer no longer sees the account's progress
  anywhere.

## Naming somebody, from the television

`ui/viewers/ViewerNameEntry.kt` reuses the **search keyboard** rather than growing a second
one — the note `TvKeyboard` already carried, written before there was a second caller to
prove it. Two on-screen keyboards is two focus contracts to keep in step, and where the
letters are is the one thing a viewer must never have to relearn. Things to preserve:

- **The keyboard is the child that gives way, never the buttons.** A `Column` hands each
  child what the ones before it left over, so the confirm row — being last — was measured
  from the remainder and drew as two squeezed slivers with their labels pressed out. The
  keyboard takes `weight(1f, fill = false)`, and weighted children are measured from what
  the unweighted ones leave: the same inversion the home hero makes for its Play chip, and
  it broke here in exactly the same way. `viewers-name-empty.png` is the capture it is
  answerable to.
- **The rules are pure and refuse early** (`ViewerEditing.kt`). A blank name is refused
  because the gateway refuses it. A **repeated** name is refused by the app alone — the
  gateway is happy to hold two people called Sam — because the picker is a row of faces with
  a name under each, and two identical names is a choice nobody in the household can make.
  A rename skips the person being renamed, so correcting somebody's capitalisation is not
  refused as a duplicate of themselves.
- **The limit is enforced by refusing the keypress**, not by rejecting the save. A remote
  types one character at a time, and a limit that only announces itself at the end is one
  somebody discovers after typing a sentence.
- **A refusal is not drawn in the accent.** Every affirmative thing on a Memby screen is
  green, and a refusal wearing the confirmation colour reads at a glance as the name having
  been accepted. The message line is *reserved* rather than conditional, or it would push
  the keyboard down by a line at the moment somebody is typing into it.
- **A local rule and a server refusal are separate parameters.** One is true before anything
  is sent and the other is what came back; showing them in one slot would leave a stale
  refusal sitting under a name that has since been corrected. A refused save keeps what was
  typed — retyping a name somebody has just entered is the worst possible answer to a
  request that failed for a reason the television does not know.

`ViewerManageScreen` is the list beside it. It is a *list* where the picker is a row of
faces, because the two answer different questions — "who is watching" is a glance and one
press, "who is here" is read a line at a time and acted on per person. A row holds **two
focus targets** rather than opening a menu, the shape the alerts page settled on: a remote
has one confirm key, and a press that opened a list of actions would make renaming somebody
three presses deep for nothing. The **main viewer has neither** and is still listed, because
a list of the people here that omitted the one whose watching actually reaches Emby would be
the more confusing of the two. Removing somebody is a full-stop question following
`ExitConfirmation`'s rules — the two answers do not look alike, the safe one takes focus
first, and **Back means keep**.

Both open **over** the picker rather than instead of it, the arrangement the add-a-user
sign-in already takes over the manage-users page: Back is one step out of each and the row
of faces is still underneath, with nothing to restore because nothing was unmounted.
`ViewerActionButton` is the one button all three screens are built from — there were nearly
three of it, the same shape at the same size in the same green written on three different
days.

## The operator's switch

`viewers` in `featureCatalogue`, capability `viewers_v1`. It is read in **`activeViewer`**
and nowhere else: that is the one place a request learns who is watching, so with it off
every branch downstream — the gated writes, the substituted rows, the per-viewer cache keys
— falls back to the account by construction rather than by fifteen separate checks.

**Off is not a deletion.** A viewer's rows stay in Postgres untouched and come back intact;
what stops is the gateway routing anybody's watching anywhere but Emby, which is the state a
household was in before this existed. `/v1/viewers` answers with `mainViewerOnly`, a
*shortened list* rather than an error or an empty one, because the television decides whether
to offer the picker by counting what it was sent — so a switched-off household looks like one
that never used the feature rather than like one whose picker has broken. The four mutations
answer 403 with a sentence naming the reason, since a television has no log and no support
channel.

**Default off**, the stance the genre browser takes. This is the switch that decides where a
household's watched state is written, and a feature arriving already on is one every server
running the build starts using before anybody has decided to — so it is opted into rather
than out of. An account with no shadow viewers behaves identically either way, which is what
makes switching it on a safe thing to try rather than a migration.

## The operator's copy

`/admin/accounts/{userID}` carries a Viewers card (`admin_viewers.go`,
`admin-ui/src/pages/Account.tsx`). It is on the **account page** rather than a rail entry of
its own because a viewer only exists under an account, and a top-level page would open by
asking which account — the question the page an operator reached this from has answered. It
is the arrangement the per-account preference editor and the device list already take.

The televisions can do all of this themselves now, so this is the operator's copy rather than
the only way in: what it is for is a household asking for help, and the case a remote cannot
reach — a viewer created on a set that has since been unplugged. Two things to preserve: the
write clears the cached list (`forgetViewers`) for the same reason the client-facing route
does, and the card **states** that the feature is switched off rather than quietly offering
controls whose effect nothing on any television would show.

The list is its own request rather than a field on `/admin/api/accounts`: that response is the
whole household and this is a list per person, so folding it in would make every accounts poll
read one table per account for a page showing one of them.

## Not built yet, in the order it should be

1. **The personalisation layer** keyed on the viewer: recommendations, the Magic pool, genre
   affinity, journeys, notifications and watch time all still answer for the account.
2. **PINs**, and the Tracearr attribution problem.

## Untested

`ViewerContainerStates` is the one piece of this with no test behind its SQL: the store's
tests are pure and there is no Postgres in the build, so the query has been read but not run.
The Go either side of it — the rollup and the block it renders — is pinned. It is the first
thing to exercise against a real database.