0.2.82

server/internal/api/admin.go

@@ -44,6 +44,10 @@ func (s *Server) adminRoutes() http.Handler {
 	mux.Handle("POST /admin/api/accounts/{userID}/preferences/revisions/{revision}/restore",
 		s.adminAuth(s.handleAdminRestorePreferences))
 	mux.Handle("DELETE /admin/api/accounts/{userID}/recommendations", s.adminAuth(s.handleAdminResetRecommendations))
+	mux.Handle("GET /admin/api/accounts/{userID}/viewers", s.adminAuth(s.handleAdminViewers))
+	mux.Handle("POST /admin/api/accounts/{userID}/viewers", s.adminAuth(s.handleAdminViewers))
+	mux.Handle("PUT /admin/api/accounts/{userID}/viewers/{viewerID}", s.adminAuth(s.handleAdminViewer))
+	mux.Handle("DELETE /admin/api/accounts/{userID}/viewers/{viewerID}", s.adminAuth(s.handleAdminViewer))
 	mux.Handle("PUT /admin/api/accounts/{userID}/recommendations/prompt", s.adminAuth(s.handleAdminPromptRecommendations))
 	mux.Handle("PUT /admin/api/accounts/{userID}/themes", s.adminAuth(s.handleAdminUserThemes))
 	mux.Handle("GET /admin/api/recommendations", s.adminAuth(s.handleAdminRecommendations))

server/internal/api/admin_viewers.go

@@ -0,0 +1,137 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/ponzischeme89/memby/server/internal/store"
+)
+
+// The people under one account, from the operator's side.
+//
+// It lives on the **account page** rather than on a rail entry of its own, which is the
+// whole of the design decision: a viewer only exists under an account, and a top-level
+// page would have to begin by asking which account is being talked about — a question the
+// page an operator reached this from has already answered. It is the arrangement the
+// per-account preference editor and the device list already take.
+//
+// A television can now do all of this for itself, so this is the operator's copy rather
+// than the only way in: what it is for is a household that has asked for help over the
+// phone, and the case a remote genuinely cannot reach — a viewer created on a set that has
+// since been unplugged.
+
+type adminViewersResponse struct {
+	Viewers []store.Viewer `json:"viewers"`
+	// Whether the household's own switch is on. The page says so rather than quietly
+	// offering controls whose effect nothing on any television would show: an operator who
+	// has switched viewers off and then adds one has done something that looks like it
+	// worked and did nothing.
+	Enabled bool `json:"enabled"`
+	// What the gateway will accept, so the console can stop offering Add at the same point
+	// the television does rather than discovering the limit by being refused.
+	MaxShadowViewers int `json:"maxShadowViewers"`
+}
+
+func (s *Server) handleAdminViewers(w http.ResponseWriter, r *http.Request) {
+	userID := strings.TrimSpace(r.PathValue("userID"))
+	if userID == "" {
+		writeError(w, http.StatusBadRequest, "user is required")
+		return
+	}
+	if r.Method == http.MethodPost {
+		s.handleAdminCreateViewer(w, r, userID)
+		return
+	}
+	// The username is only used to name a main viewer that does not exist yet, and an
+	// operator is not the right person to be naming somebody — an account that has never
+	// had a request made against it gets the placeholder, and the television replaces it
+	// with the real Emby name on its first sign-in.
+	viewers, err := s.store.Viewers(r.Context(), userID, "")
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "could not load viewers")
+		return
+	}
+	writeJSON(w, http.StatusOK, adminViewersResponse{
+		Viewers:          viewers,
+		Enabled:          s.viewersEnabled(r.Context()),
+		MaxShadowViewers: store.MaxShadowViewers,
+	})
+}
+
+func (s *Server) handleAdminCreateViewer(w http.ResponseWriter, r *http.Request, userID string) {
+	var req viewerRequest
+	if json.NewDecoder(http.MaxBytesReader(w, r.Body, 4<<10)).Decode(&req) != nil {
+		writeError(w, http.StatusBadRequest, "malformed request body")
+		return
+	}
+	if strings.TrimSpace(req.Name) == "" || len([]rune(req.Name)) > 40 {
+		writeError(w, http.StatusBadRequest, "a name of up to 40 characters is required")
+		return
+	}
+	viewer, err := s.store.CreateShadowViewer(r.Context(), userID, req.Name, req.ShortName, req.Colour)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	// The televisions hold a cached list for viewerListTTL, so the write clears it here for
+	// the same reason it does on the client-facing route: a person added from the console
+	// must be pickable on the next request rather than at the end of the window.
+	s.forgetViewers(userID)
+	s.loggerFor(r.Context()).Info("viewer added by operator",
+		"account", userID, "viewer", viewer.ID, "name", viewer.Name)
+	writeJSON(w, http.StatusOK, viewer)
+}
+
+func (s *Server) handleAdminViewer(w http.ResponseWriter, r *http.Request) {
+	userID := strings.TrimSpace(r.PathValue("userID"))
+	viewerID := strings.TrimSpace(r.PathValue("viewerID"))
+	if userID == "" || viewerID == "" {
+		writeError(w, http.StatusBadRequest, "user and viewer are required")
+		return
+	}
+
+	if r.Method == http.MethodDelete {
+		if err := s.store.DeleteShadowViewer(r.Context(), userID, viewerID); err != nil {
+			if errors.Is(err, store.ErrViewerNotFound) {
+				writeError(w, http.StatusNotFound, "no such viewer")
+				return
+			}
+			writeError(w, http.StatusInternalServerError, "could not remove that viewer")
+			return
+		}
+		s.forgetViewers(userID)
+		// Everything cached under this viewer's own key is now about nobody.
+		if err := s.cache.InvalidateUser(r.Context(), viewerID); err != nil {
+			s.loggerFor(r.Context()).Warn("cache invalidation failed", "error", err)
+		}
+		s.loggerFor(r.Context()).Info("viewer removed by operator",
+			"account", userID, "viewer", viewerID)
+		w.WriteHeader(http.StatusNoContent)
+		return
+	}
+
+	var req viewerRequest
+	if json.NewDecoder(http.MaxBytesReader(w, r.Body, 4<<10)).Decode(&req) != nil {
+		writeError(w, http.StatusBadRequest, "malformed request body")
+		return
+	}
+	viewer, err := s.store.UpdateShadowViewer(
+		r.Context(), userID, viewerID, req.Name, req.ShortName, req.Colour,
+	)
+	if err != nil {
+		if errors.Is(err, store.ErrViewerNotFound) {
+			// The main viewer lands here too, and that is the honest answer: its name is
+			// the Emby account's, so as a *shadow* viewer to rename it does not exist.
+			writeError(w, http.StatusNotFound, "no such viewer")
+			return
+		}
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	s.forgetViewers(userID)
+	s.loggerFor(r.Context()).Info("viewer renamed by operator",
+		"account", userID, "viewer", viewer.ID, "name", viewer.Name)
+	writeJSON(w, http.StatusOK, viewer)
+}

server/internal/api/analytics.go

@@ -177,7 +177,7 @@ func (s *Server) handleRowAnalytics(w http.ResponseWriter, r *http.Request, sess
 	}
 	for _, event := range events {
 		if event.Event == store.RowEventSelect {
-			_ = s.cache.InvalidateUser(r.Context(), sess.EmbyUserID)
+			_ = s.cache.InvalidateUser(r.Context(), viewerKeyOf(r.Context(), sess))
 			if s.forYou != nil {
 				s.forYou.MarkDirty(context.WithoutCancel(r.Context()), sess)
 			}

server/internal/api/api.go

@@ -91,6 +91,8 @@ type Server struct {
 	openSubtitles    *opensubtitles.Client
 	openSubtitlesKey string
 	mdblistMu        sync.Mutex
+	// viewerLists spares every authenticated request a read of the account's people.
+	viewerLists viewerListCache
 	// mdblistSettingsCache spares every row and keystroke a settings read.
 	mdblistSettingsCache mdblistSettingsCache
 	// ratingsWarm fills and renews the durable rating cache behind the viewer, so a row
@@ -267,6 +269,13 @@ func (s *Server) Routes() http.Handler {
 	v1.Handle("PUT /v1/auth/devices/{deviceID}", s.authed(s.handleRenameDevice))
 	v1.Handle("DELETE /v1/auth/devices/{deviceID}", s.authed(s.handleDeleteDevice))
 
+	// Viewers: the people under one account. The list is what the picker draws; every
+	// other route learns who is watching from the X-Memby-Viewer header instead.
+	v1.Handle("GET /v1/viewers", s.authed(s.handleViewers))
+	v1.Handle("POST /v1/viewers", s.authed(s.handleViewers))
+	v1.Handle("PUT /v1/viewers/{viewerID}", s.authed(s.handleViewer))
+	v1.Handle("DELETE /v1/viewers/{viewerID}", s.authed(s.handleViewer))
+
 	v1.Handle("GET /v1/home", s.authed(s.handleHome))
 	v1.Handle("GET /v1/heroes/active", s.authed(s.handleActiveHero))
 	v1.Handle("GET /v1/screensaver", s.authed(s.handleScreensaver))
@@ -435,6 +444,12 @@ func (s *Server) authed(h authedFunc) http.Handler {
 		}
 		sess = s.captureClientIdentity(r, sess)
 		identify(r.Context(), sess)
+		// Resolved once, here, and read out of the context by everything downstream. The
+		// header short-circuits when it is absent, so a household running no viewers pays
+		// a map lookup and nothing else.
+		viewer := s.activeViewer(r.Context(), sess, r)
+		identifyViewer(r.Context(), viewer)
+		r = r.WithContext(withViewer(r.Context(), viewer))
 		policy := s.updatePolicy.get()
 		decision := appupdate.Decide(effectiveUpdatePolicy(policy), clientVersion(r))
 		retireBelow := destructiveUpdateFloor(policy)
@@ -446,7 +461,7 @@ func (s *Server) authed(h authedFunc) http.Handler {
 				s.loggerFor(r.Context()).Error("required-update session delete failed", "error", err)
 			}
 			_ = s.cache.Delete(r.Context(), cache.SessionKey(hexHash(sess.TokenHash)))
-			_ = s.cache.InvalidateUser(r.Context(), sess.EmbyUserID)
+			s.invalidateAccountViews(r.Context(), sess)
 			s.loggerFor(r.Context()).Info("signed out for required update",
 				"device_id", sess.DeviceID,
 				"from", clientLogValue(clientVersion(r)),

server/internal/api/auth.go

@@ -232,7 +232,7 @@ func (s *Server) handleLogout(w http.ResponseWriter, r *http.Request, sess store
 		s.log.Error("session delete failed", "error", err)
 	}
 	_ = s.cache.Delete(r.Context(), cache.SessionKey(hexHash(sess.TokenHash)))
-	_ = s.cache.InvalidateUser(r.Context(), sess.EmbyUserID)
+	s.invalidateAccountViews(r.Context(), sess)
 	s.loggerFor(r.Context()).Info("signed out", "device_id", sess.DeviceID)
 	s.publishAdmin(r.Context(), adminevents.Event{
 		Type:  adminevents.TypeLogout,

server/internal/api/features.go

@@ -27,6 +27,7 @@ const (
 	featureGenreBrowser        = "genre_browser"
 	featureTVCalendar          = "tv_calendar"
 	featureWatchTimeDigest     = "watch_time_digest"
+	featureViewers             = "viewers"
 )
 
 type featureDefinition struct {
@@ -146,6 +147,25 @@ var featureCatalogue = []featureDefinition{
 		DefaultEnabled: true, MinimumProtocol: 1,
 		Recovery: "Server-enforced; takes effect before the next summary is due.",
 	},
+	{
+		// 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 that
+		// arrives already on is one every server running this build starts using before
+		// anybody has decided to — so it is opted into rather than out of.
+		//
+		// Switching it on or off never deletes a viewer or their history: the rows stay
+		// in Postgres and come back intact. Off, the gateway routes nobody's state
+		// anywhere but Emby, which is the state a household was in before the feature
+		// existed; on, a shadow viewer's watching goes to Memby and is picked up exactly
+		// where they left it.
+		Key: featureViewers, Name: "Viewers", Area: "Accounts",
+		Description: "Let one Emby account hold several people, each with their own " +
+			"Continue Watching, watched history and favourites. Off by default; turning " +
+			"it off again returns every television to watching as the account itself, " +
+			"without losing what anybody has watched.",
+		DefaultEnabled: false, MinimumProtocol: 1, Capability: "viewers_v1",
+		Recovery: "Takes effect on the next request; nothing a viewer has watched is lost.",
+	},
 	{
 		Key: featureInstallPermission, Name: "Ask TVs for install permission", Area: "Setup",
 		Description: "Ask a signed-in TV that cannot install its own updates to grant the " +

server/internal/api/genres.go

@@ -76,7 +76,7 @@ func (s *Server) handleBrowseItems(
 	if genre != "" {
 		filterKey = "genre:" + genre
 	}
-	key := cache.UserKey(sess.EmbyUserID, "browse:"+itemType+":"+filterKey+":"+itoa(offset)+":"+itoa(limit))
+	key := cache.UserKey(viewerKeyOf(ctx, sess), "browse:"+itemType+":"+filterKey+":"+itoa(offset)+":"+itoa(limit))
 	if raw, err := s.cache.Get(ctx, key); err == nil {
 		w.Header().Set("X-Memby-Cache", "hit")
 		writeRaw(w, http.StatusOK, raw)
@@ -111,7 +111,7 @@ func (s *Server) handleBrowseItems(
 		return
 	}
 	items := nonNil(result.Items)
-	s.decorateItemRatings(ctx, items)
+	s.decorateItems(ctx, items)
 
 	total := genreTotal(result.TotalRecordCount, offset, len(items), limit)
 

server/internal/api/hero.go

@@ -1109,7 +1109,7 @@ func (s *Server) heroPremiereCandidates(ctx context.Context, now time.Time) []he
 	// The imported catalogue is shared by the household and deliberately carries no user
 	// data, so these cards arrive without ratings. Decorating them is one indexed read
 	// and is what lets a premiere be ranked on the same terms as a film.
-	s.decorateItemRatings(ctx, payloads)
+	s.decorateItems(ctx, payloads)
 
 	byID := make(map[string]json.RawMessage, len(payloads))
 	for _, raw := range payloads {

server/internal/api/hero_active.go

@@ -34,7 +34,7 @@ func (s *Server) handleActiveHero(w http.ResponseWriter, r *http.Request, sess s
 	// slot. That is what makes an operator's change reachable immediately without dropping
 	// anything else the household has cached: the old entry is not invalidated, it is
 	// simply no longer named. See heroRevision.
-	key := cache.UserKey(sess.EmbyUserID, "hero:active:v2:"+placement+":"+
+	key := cache.UserKey(viewerKeyOf(r.Context(), sess), "hero:active:v2:"+placement+":"+
 		heroRevision(s.currentHeroPolicy(r.Context()), sess.EmbyUserID, now, location))
 	if raw, err := s.cache.Get(r.Context(), key); err == nil {
 		w.Header().Set("X-Memby-Cache", "hit")
@@ -74,7 +74,7 @@ func (s *Server) resolveActiveHero(ctx context.Context, sess store.Session, plac
 	if err != nil {
 		return activeHeroResponse{}, err
 	}
-	s.decorateItemRatings(ctx, result.Items)
+	s.decorateItems(ctx, result.Items)
 	rows := []recommend.Row{{ID: "hero-candidates-" + placement, Kind: "catalogue", Items: result.Items}}
 
 	policy := s.currentHeroPolicy(ctx)

server/internal/api/home.go

@@ -83,7 +83,7 @@ func (s *Server) handleHome(w http.ResponseWriter, r *http.Request, sess store.S
 	// four cards. See heroRevision.
 	heroRev := heroRevision(s.currentHeroPolicy(ctx), sess.EmbyUserID, now, s.heroLocation())
 	key := cache.UserKey(
-		sess.EmbyUserID,
+		viewerKeyOf(ctx, sess),
 		"home:v4:"+itoa(limit)+":s"+strconv.FormatBool(sonarrSchedule)+
 			":r"+strconv.FormatBool(radarrSchedule)+":h"+strconv.FormatBool(hero)+
 			":hr"+heroRev+":d"+sess.DeviceID,
@@ -135,7 +135,19 @@ func (s *Server) handleHome(w http.ResponseWriter, r *http.Request, sess store.S
 		}()
 	}
 
+	// The three rows that are answers about a *person* rather than about the library.
+	// For the account's own viewer they are Emby's, exactly as they always were; for a
+	// shadow viewer they are built from that viewer's own state, and Emby is asked only to
+	// describe the titles. The fan-out, the failure counting and the merge below are
+	// unchanged either way — this is a substitution of one fetch for another, not a second
+	// code path through the launcher.
+	viewer := viewerOf(ctx, sess)
+	shadow := !viewer.IsMain() && s.store != nil
+
 	run("resume", &out.ContinueWatching, func(ctx context.Context) (*emby.ItemsResult, error) {
+		if shadow {
+			return s.viewerContinueRow(ctx, cred, viewer.ID, limit)
+		}
 		return s.emby.ResumeItems(ctx, cred, rowParams(url.Values{
 			"Recursive":  {"true"},
 			"MediaTypes": {"Video"},
@@ -143,6 +155,9 @@ func (s *Server) handleHome(w http.ResponseWriter, r *http.Request, sess store.S
 		}, fieldsContinue))
 	})
 	run("favourites", &out.Favorites, func(ctx context.Context) (*emby.ItemsResult, error) {
+		if shadow {
+			return s.viewerFavouritesRow(ctx, cred, viewer.ID, limit)
+		}
 		return s.emby.Items(ctx, cred, rowParams(url.Values{
 			"Filters":          {"IsFavorite"},
 			"IncludeItemTypes": {"Movie,Series"},
@@ -153,6 +168,9 @@ func (s *Server) handleHome(w http.ResponseWriter, r *http.Request, sess store.S
 		}, fieldsRow))
 	})
 	run("nextup", &out.NextUp, func(ctx context.Context) (*emby.ItemsResult, error) {
+		if shadow {
+			return s.viewerNextUpRow(ctx, cred, viewer.ID, limit)
+		}
 		return s.emby.NextUp(ctx, cred, rowParams(url.Values{
 			"Limit": {itoa(limit)},
 		}, fieldsContinue))
@@ -163,7 +181,16 @@ func (s *Server) handleHome(w http.ResponseWriter, r *http.Request, sess store.S
 	wg.Add(1)
 	go func() {
 		defer wg.Done()
-		played, err := s.recentlyPlayedSeries(timing.WithLabel(ctx, "emby.recent"), cred)
+		// What orders the two halves of the merge. For a shadow viewer it is one grouped
+		// query over their own state rather than a lookback over the account's plays —
+		// the same question, asked of the system that holds the answer.
+		var played map[string]time.Time
+		var err error
+		if shadow {
+			played, err = s.store.ViewerWatchedSeries(ctx, viewer.ID, continuePlayLookback)
+		} else {
+			played, err = s.recentlyPlayedSeries(timing.WithLabel(ctx, "emby.recent"), cred)
+		}
 		if err != nil {
 			s.loggerFor(ctx).Warn("recently played lookup failed", "error", err)
 			return
@@ -578,7 +605,7 @@ func (s *Server) handleSearch(w http.ResponseWriter, r *http.Request, sess store
 		return
 	}
 	limit := queryInt(r, "limit", 40, 100)
-	key := cache.UserKey(sess.EmbyUserID, "search:"+itoa(limit)+":"+term+":d"+sess.DeviceID)
+	key := cache.UserKey(viewerKeyOf(ctx, sess), "search:"+itoa(limit)+":"+term+":d"+sess.DeviceID)
 
 	// Every search the tab performs is recorded here, before the cache is consulted, so a
 	// query answered from Redis counts the same as one that reached Emby. The client also
@@ -606,7 +633,7 @@ func (s *Server) handleSearch(w http.ResponseWriter, r *http.Request, sess store
 		return
 	}
 	items := s.personalizeSearch(ctx, sess, term, result.Items, limit)
-	s.decorateItemRatings(ctx, items)
+	s.decorateItems(ctx, items)
 	// Instant search fires a request per keystroke past the second character, so this is
 	// DEBUG: it is the record of what somebody was looking for when nothing was found,
 	// not something to carry in the normal log.

server/internal/api/items.go

@@ -48,7 +48,7 @@ func (s *Server) handleItem(w http.ResponseWriter, r *http.Request, sess store.S
 		writeError(w, http.StatusBadRequest, "item id is required")
 		return
 	}
-	if raw, err := s.cache.Get(ctx, itemDetailKey(sess.EmbyUserID, itemID)); err == nil {
+	if raw, err := s.cache.Get(ctx, itemDetailKey(viewerKeyOf(ctx, sess), itemID)); err == nil {
 		w.Header().Set("X-Memby-Cache", "hit")
 		writeRaw(w, http.StatusOK, raw)
 		return
@@ -88,7 +88,7 @@ func (s *Server) detailItem(
 			// than after a second request. Anything not yet stored still arrives on
 			// /ratings.
 			decorated := []json.RawMessage{raw}
-			s.decorateItemRatings(ctx, decorated)
+			s.decorateItems(ctx, decorated)
 			return decorated[0], nil
 		})
 	return item, err
@@ -255,7 +255,7 @@ func (s *Server) handleSeriesEpisodes(w http.ResponseWriter, r *http.Request, se
 	// Watching card is focused, and the page asks again when somebody presses. A
 	// long-running show is a thousand records, so two of them is a real cost on the one
 	// press that must feel free.
-	key := cache.UserKey(sess.EmbyUserID, "series-episodes:"+seriesID)
+	key := cache.UserKey(viewerKeyOf(ctx, sess), "series-episodes:"+seriesID)
 	body, hit, err := s.cachedRead(ctx, key, s.cfg.ItemTTL,
 		func(ctx context.Context) (json.RawMessage, error) {
 			result, err := s.emby.Episodes(
@@ -278,6 +278,11 @@ func (s *Server) handleSeriesEpisodes(w http.ResponseWriter, r *http.Request, se
 			if items == nil {
 				items = []json.RawMessage{}
 			}
+			// The ticks down the episode list are the clearest statement this app makes
+			// about what somebody has seen, so they are the last place the account's
+			// answer may be left standing. The cache key is the viewer's, so this is
+			// stored per person rather than decorated on the way out.
+			s.decorateViewerState(ctx, items)
 			return json.Marshal(seriesEpisodesResponse{Items: items})
 		})
 	if err != nil {
@@ -307,33 +312,78 @@ func (s *Server) handleTrailer(w http.ResponseWriter, r *http.Request, sess stor
 	writeRaw(w, http.StatusOK, result.Items[0])
 }
 
+// The four routes below are the whole of what Memby writes back to Emby about a person:
+// a favourite, a watched flag, a hidden resume item and a playback report. Each one now
+// asks who is watching first, because that is the entire promise of a shadow viewer — the
+// Emby account lends them the library and never learns what they did with it.
+
 func (s *Server) handleFavorite(w http.ResponseWriter, r *http.Request, sess store.Session) {
-	s.setFlag(w, r, sess, func(itemID string, value bool) (json.RawMessage, error) {
+	s.setFlag(w, r, sess, func(viewer store.Viewer, itemID string, value bool) (json.RawMessage, error) {
+		if !viewer.IsMain() {
+			return s.setShadowFlag(r.Context(), viewer, itemID, func() error {
+				return s.store.SetViewerFavourite(r.Context(), viewer.ID, itemID, value)
+			})
+		}
 		return s.emby.SetFavorite(r.Context(), credentials(sess), itemID, value)
 	})
 }
 
 func (s *Server) handlePlayed(w http.ResponseWriter, r *http.Request, sess store.Session) {
-	s.setFlag(w, r, sess, func(itemID string, value bool) (json.RawMessage, error) {
+	s.setFlag(w, r, sess, func(viewer store.Viewer, itemID string, value bool) (json.RawMessage, error) {
+		if !viewer.IsMain() {
+			return s.setShadowFlag(r.Context(), viewer, itemID, func() error {
+				return s.store.SetViewerPlayed(r.Context(), viewer.ID, itemID, value)
+			})
+		}
 		return s.emby.SetPlayed(r.Context(), credentials(sess), itemID, value)
 	})
 }
 
+// setShadowFlag applies a Memby-side mutation and answers in the shape Emby would have.
+//
+// Re-reading the row rather than describing the write is deliberate: the response is what
+// the television draws the card from, and a favourite pressed on a title that is also part
+// way through has to come back carrying the position as well as the heart.
+func (s *Server) setShadowFlag(
+	ctx context.Context, viewer store.Viewer, itemID string, apply func() error,
+) (json.RawMessage, error) {
+	if err := apply(); err != nil {
+		return nil, err
+	}
+	state, err := s.store.ViewerStateFor(ctx, viewer.ID, itemID)
+	if err != nil {
+		return nil, err
+	}
+	return viewerUserData(state), nil
+}
+
 func (s *Server) handleHideFromResume(w http.ResponseWriter, r *http.Request, sess store.Session) {
 	itemID := r.PathValue("id")
 	if itemID == "" {
 		writeError(w, http.StatusBadRequest, "item id is required")
 		return
 	}
-	userData, err := s.emby.HideFromResume(r.Context(), credentials(sess), itemID)
+	viewer := s.activeViewer(r.Context(), sess, r)
+	var userData json.RawMessage
+	var err error
+	if viewer.IsMain() {
+		userData, err = s.emby.HideFromResume(r.Context(), credentials(sess), itemID)
+	} else {
+		userData, err = s.setShadowFlag(r.Context(), viewer, itemID, func() error {
+			return s.store.HideViewerFromResume(r.Context(), viewer.ID, itemID)
+		})
+	}
 	if err != nil {
 		s.writeUpstreamError(r.Context(), w, err, "could not remove the item from Continue Watching")
 		return
 	}
-	if err := s.cache.InvalidateUser(r.Context(), sess.EmbyUserID); err != nil {
+	if err := s.cache.InvalidateUser(r.Context(), viewer.ID); err != nil {
 		s.loggerFor(r.Context()).Warn("cache invalidation failed", "error", err)
 	}
-	if s.forYou != nil {
+	// For You is built from the Emby account's own history, so a shadow viewer's press
+	// says nothing about it. Marking it dirty would rebuild the main viewer's row out of
+	// somebody else's choice.
+	if s.forYou != nil && viewer.IsMain() {
 		s.forYou.MarkDirty(r.Context(), sess)
 	}
 	writeRaw(w, http.StatusOK, userData)
@@ -345,8 +395,9 @@ func (s *Server) setFlag(
 	w http.ResponseWriter,
 	r *http.Request,
 	sess store.Session,
-	apply func(itemID string, value bool) (json.RawMessage, error),
+	apply func(viewer store.Viewer, itemID string, value bool) (json.RawMessage, error),
 ) {
+	viewer := s.activeViewer(r.Context(), sess, r)
 	itemID := r.PathValue("id")
 	if itemID == "" {
 		writeError(w, http.StatusBadRequest, "item id is required")
@@ -358,15 +409,18 @@ func (s *Server) setFlag(
 		return
 	}
 
-	userData, err := apply(itemID, req.Value)
+	userData, err := apply(viewer, itemID, req.Value)
 	if err != nil {
 		s.writeUpstreamError(r.Context(), w, err, "could not update the item")
 		return
 	}
-	if err := s.cache.InvalidateUser(r.Context(), sess.EmbyUserID); err != nil {
+	if err := s.cache.InvalidateUser(r.Context(), viewer.ID); err != nil {
 		s.loggerFor(r.Context()).Warn("cache invalidation failed", "error", err)
 	}
-	if s.forYou != nil {
+	// For You is built from the Emby account's own history, so a shadow viewer's press
+	// says nothing about it. Marking it dirty would rebuild the main viewer's row out of
+	// somebody else's choice.
+	if s.forYou != nil && viewer.IsMain() {
 		s.forYou.MarkDirty(r.Context(), sess)
 	}
 	writeRaw(w, http.StatusOK, userData)

server/internal/api/logcontext.go

@@ -24,6 +24,7 @@ type requestIdentity struct {
 	component   string
 	userID      string
 	user        string
+	viewer      string
 	device      string
 	client      string
 	protocol    string
@@ -73,6 +74,21 @@ func identify(ctx context.Context, sess store.Session) {
 	}
 }
 
+// identifyViewer names the person watching, where that is somebody other than the account
+// itself. A main viewer is deliberately not recorded: its name is already the "user" field,
+// and printing it twice on every line would say nothing.
+func identifyViewer(ctx context.Context, viewer store.Viewer) {
+	identity := identityFrom(ctx)
+	if identity == nil || viewer.IsMain() {
+		return
+	}
+	if viewer.Name != "" {
+		identity.viewer = viewer.Name
+	} else {
+		identity.viewer = viewer.ID
+	}
+}
+
 func (i *requestIdentity) attrs() []any {
 	if i == nil {
 		return nil
@@ -124,6 +140,9 @@ func (i *requestIdentity) viewerAttrs() []any {
 	if i.user != "" {
 		attrs = append(attrs, "user", i.user)
 	}
+	if i.viewer != "" {
+		attrs = append(attrs, "viewer", i.viewer)
+	}
 	if i.device != "" {
 		attrs = append(attrs, "device", i.device)
 	}

server/internal/api/people.go

@@ -56,7 +56,7 @@ func (s *Server) handlePersonFilmography(w http.ResponseWriter, r *http.Request,
 		writeError(w, http.StatusBadRequest, "person id is required")
 		return
 	}
-	key := cache.UserKey(sess.EmbyUserID, "person-filmography:v1:"+personID)
+	key := cache.UserKey(viewerKeyOf(ctx, sess), "person-filmography:v1:"+personID)
 	body, hit, err := s.cachedRead(ctx, key, s.cfg.ItemTTL,
 		func(ctx context.Context) (json.RawMessage, error) {
 			result, err := s.emby.Items(ctx, credentials(sess), url.Values{

server/internal/api/playback.go

@@ -129,6 +129,7 @@ func (s *Server) handlePlayback(w http.ResponseWriter, r *http.Request, sess sto
 		return
 	}
 	cred := credentials(sess)
+	viewer := viewerOf(ctx, sess)
 
 	item, hinted := playbackHint(r, itemID)
 	if !hinted {
@@ -148,7 +149,7 @@ func (s *Server) handlePlayback(w http.ResponseWriter, r *http.Request, sess sto
 	title := item.Name
 
 	if strings.EqualFold(item.Type, "Series") {
-		episode, err := s.firstPlayableEpisode(ctx, cred, item.ID)
+		episode, err := s.firstPlayableEpisode(ctx, cred, viewer, item.ID)
 		if err != nil {
 			s.writeUpstreamError(ctx, w, err, "could not find an episode to play")
 			return
@@ -163,6 +164,26 @@ func (s *Server) handlePlayback(w http.ResponseWriter, r *http.Request, sess sto
 		}
 	}
 
+	// Where a shadow viewer resumes from is Memby's answer, and it is taken here rather
+	// than trusted from the card.
+	//
+	// The hint the television sends is read off a card this gateway already decorated with
+	// this 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. This is also the value handed to
+	// PlaybackInfo below, so taking it here fixes the negotiated stream as well as the
+	// number sent back.
+	if !viewer.IsMain() && s.store != nil {
+		if state, err := s.store.ViewerStateFor(ctx, viewer.ID, target.ID); err == nil {
+			target.UserData.PlaybackPositionTicks = state.PositionTicks
+		} else {
+			// Starting from the beginning is a recoverable disappointment; starting from
+			// where somebody else got to is not.
+			s.loggerFor(ctx).Warn("viewer resume position unavailable", "error", err)
+			target.UserData.PlaybackPositionTicks = 0
+		}
+	}
+
 	var subtitleIndex *int
 	if raw := strings.TrimSpace(r.URL.Query().Get("subtitleIndex")); raw != "" {
 		if parsed, err := strconv.Atoi(raw); err == nil && parsed >= 0 {
@@ -265,7 +286,26 @@ func playbackHint(r *http.Request, itemID string) (emby.Summary, bool) {
 }
 
 // firstPlayableEpisode prefers the server's next-up choice and falls back to episode one.
-func (s *Server) firstPlayableEpisode(ctx context.Context, cred emby.Credentials, seriesID string) (*emby.Summary, error) {
+// The viewer is threaded in because "where does this series start" is a question about a
+// person, and Emby's NextUp answers it for the account. A shadow viewer's answer is their
+// own: the first episode they have not finished.
+func (s *Server) firstPlayableEpisode(
+	ctx context.Context, cred emby.Credentials, viewer store.Viewer, seriesID string,
+) (*emby.Summary, error) {
+	if !viewer.IsMain() && s.store != nil {
+		episode, err := s.firstUnwatchedEpisodeFor(ctx, cred, viewer, seriesID)
+		if err != nil {
+			// Falling through to Emby's answer is wrong for this viewer, so it is not
+			// done: starting somebody at the account's next episode is the leak this
+			// feature exists to prevent.
+			return nil, err
+		}
+		if episode != nil {
+			return episode, nil
+		}
+		// Nothing recorded for this series yet: fall through and let Emby name its first
+		// episode, which is the right answer for somebody who has never watched any of it.
+	}
 	nextUp, err := s.emby.NextUp(ctx, cred, url.Values{
 		"SeriesId":       {seriesID},
 		"Limit":          {"1"},
@@ -376,6 +416,20 @@ func (s *Server) handleNextEpisode(w http.ResponseWriter, r *http.Request, sess
 		title = series + " – " + title
 	}
 
+	// Which episode follows is a property of the season and is the same for everybody;
+	// how far into it *this* viewer already is, is not. The item payload is rewritten as
+	// well as the summary, because the television draws the next-up banner from it.
+	viewer := viewerOf(ctx, sess)
+	if !viewer.IsMain() && s.store != nil {
+		state, stateErr := s.store.ViewerStateFor(ctx, viewer.ID, next.ID)
+		if stateErr != nil {
+			s.loggerFor(ctx).Warn("viewer next-episode position unavailable", "error", stateErr)
+			state = store.ViewerState{}
+		}
+		next.UserData.PlaybackPositionTicks = state.PositionTicks
+		raw = injectItemUserData(raw, viewerUserData(state))
+	}
+
 	// The metadata-only shape. Everything below this point is a PlaybackInfo negotiation,
 	// and a client that said it does not want one yet must not be given one anyway.
 	if !nextEpisodeWantsStream(r) {
@@ -798,6 +852,41 @@ func seriesNameOf(raw json.RawMessage) string {
 	return parsed.SeriesName
 }
 
+// recordShadowPlayback is the other side of the playback report: the same three phases,
+// written to Memby instead of to Emby.
+//
+// Where a title is *finished* is decided here rather than by the television, for the
+// reason the gateway decides which subtitle comes on: Emby applies its own completion
+// threshold on the main viewer's behalf, and a shadow viewer must be judged by the same
+// rule or one household would disagree with itself about whether an episode is watched
+// depending on who watched it.
+//
+// A paused progress report still records the position. Pausing is where somebody leaves a
+// film, and the ten seconds between reports is exactly the window a set switched off at
+// the wall would otherwise lose.
+func (s *Server) recordShadowPlayback(
+	ctx context.Context, viewer store.Viewer, phase string, report playbackReport,
+) error {
+	if s.store == nil {
+		return fmt.Errorf("no store for viewer playback")
+	}
+	// The pool's own tracer times this; nothing extra is recorded here.
+	position := max64(report.PositionMs, 0) * ticksPerMillisecond
+	runtime := max64(report.DurationMs, 0) * ticksPerMillisecond
+	state := store.ViewerState{
+		ItemID:        report.ItemID,
+		PositionTicks: position,
+		RuntimeTicks:  runtime,
+	}
+	// 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.
+	if phase == "stopped" {
+		state.Played = store.PlayedFromPosition(position, runtime)
+	}
+	return s.store.RecordViewerPlayback(ctx, viewer.ID, state)
+}
+
 // handlePlaybackReport forwards progress to Emby. Stopping invalidates the user's cache
 // so Continue Watching reflects the new position on the next home load.
 func (s *Server) handlePlaybackReport(w http.ResponseWriter, r *http.Request, sess store.Session) {
@@ -826,12 +915,24 @@ func (s *Server) handlePlaybackReport(w http.ResponseWriter, r *http.Request, se
 		"play_session_id", clientLogValue(report.PlaySessionID),
 	)
 
-	err := s.emby.ReportPlayback(
-		timing.WithLabel(r.Context(), "emby.report"),
-		credentials(sess), phase, report.ItemID, report.MediaSourceID,
-		report.PlaySessionID, report.PlayMethod, report.EventName,
-		max64(report.PositionMs, 0)*ticksPerMillisecond, report.IsPaused,
-	)
+	// Who is watching decides where this goes, and it is the only place that decision is
+	// made for progress. A shadow viewer's evening is Memby's: nothing below reaches
+	// /Sessions/Playing, so the Emby account lending them the library never learns what
+	// they watched or how far they got.
+	viewer := s.activeViewer(r.Context(), sess, r)
+	log = log.With("viewer", viewer.ID)
+
+	var err error
+	if viewer.IsMain() {
+		err = s.emby.ReportPlayback(
+			timing.WithLabel(r.Context(), "emby.report"),
+			credentials(sess), phase, report.ItemID, report.MediaSourceID,
+			report.PlaySessionID, report.PlayMethod, report.EventName,
+			max64(report.PositionMs, 0)*ticksPerMillisecond, report.IsPaused,
+		)
+	} else {
+		err = s.recordShadowPlayback(r.Context(), viewer, phase, report)
+	}
 	if err != nil {
 		log.Warn("playback report failed", "phase", phase, "error", err)
 		// Progress is advisory and another reading follows in ten seconds. A final stop is
@@ -876,7 +977,7 @@ func (s *Server) handlePlaybackReport(w http.ResponseWriter, r *http.Request, se
 
 	if phase == "stopped" {
 		invalidate := timing.Start(r.Context(), "invalidate")
-		if err := s.cache.InvalidateUser(r.Context(), sess.EmbyUserID); err != nil {
+		if err := s.cache.InvalidateUser(r.Context(), viewer.ID); err != nil {
 			s.loggerFor(r.Context()).Warn("cache invalidation failed", "error", err)
 		}
 		invalidate()
@@ -891,10 +992,10 @@ func (s *Server) handlePlaybackReport(w http.ResponseWriter, r *http.Request, se
 	// episode stops here rather than at the durable insert four upstream calls later;
 	// the feature check is a cached read; and only then is anything asked of Emby.
 	if shouldAutoFollowShow(phase, report.PositionMs, report.DurationMs) &&
-		s.followChecks.claim(sess.EmbyUserID, report.ItemID) &&
+		s.followChecks.claim(viewer.ID, report.ItemID) &&
 		s.featureEnabled(r.Context(), featureAutomaticMyShows) {
 		follow := timing.Start(r.Context(), "autofollow")
-		response.AutoFollowedShowTitle = s.autoFollowContinuingShow(r.Context(), sess, report.ItemID)
+		response.AutoFollowedShowTitle = s.autoFollowContinuingShow(r.Context(), sess, viewer, report.ItemID)
 		follow()
 	}
 	writeJSON(w, http.StatusOK, response)
@@ -907,7 +1008,12 @@ func shouldAutoFollowShow(phase string, positionMs, durationMs int64) bool {
 	return phase != "started" && durationMs > 0 && positionMs >= (durationMs+1)/2
 }
 
-func (s *Server) autoFollowContinuingShow(ctx context.Context, sess store.Session, episodeID string) string {
+// The Emby credential reads the catalogue; the viewer owns the list it is written to.
+// Following a show is a Memby preference and belongs to the person, so a shadow viewer
+// finishing an episode fills their own My Shows rather than the account's.
+func (s *Server) autoFollowContinuingShow(
+	ctx context.Context, sess store.Session, viewer store.Viewer, episodeID string,
+) string {
 	if s.sonarr == nil || s.store == nil {
 		return ""
 	}
@@ -949,7 +1055,7 @@ func (s *Server) autoFollowContinuingShow(ctx context.Context, sess store.Sessio
 		ItemID: episode.SeriesID, Title: seriesItem.Name, Year: seriesItem.ProductionYear,
 		ImageTag: seriesItem.ImageTags["Primary"],
 	}
-	inserted, err := s.store.SaveUserShowIfAbsent(ctx, sess.EmbyUserID, show)
+	inserted, err := s.store.SaveUserShowIfAbsent(ctx, viewer.ID, show)
 	if err != nil {
 		s.loggerFor(ctx).Warn("auto-follow save failed", "error", err)
 		return ""
@@ -957,7 +1063,7 @@ func (s *Server) autoFollowContinuingShow(ctx context.Context, sess store.Sessio
 	if !inserted {
 		return ""
 	}
-	prefs, err := s.store.NotificationPreferences(ctx, sess.EmbyUserID)
+	prefs, err := s.store.NotificationPreferences(ctx, viewer.ID)
 	if err != nil {
 		s.loggerFor(ctx).Warn("auto-follow notification preferences unavailable", "error", err)
 		return ""
@@ -965,8 +1071,8 @@ func (s *Server) autoFollowContinuingShow(ctx context.Context, sess store.Sessio
 	notification := notify.Notification{
 		Kind:      "auto-follow",
 		Source:    notifySourceAutoFollow,
-		UserID:    sess.EmbyUserID,
-		Username:  sess.Username,
+		UserID:    viewer.ID,
+		Username:  viewer.Name,
 		Title:     "Added to My Shows",
 		Body:      seriesItem.Name + " was added because you started watching it and it is still continuing.",
 		ItemID:    episode.SeriesID,

server/internal/api/ranking.go

@@ -586,7 +586,7 @@ func (s *Server) handleRecommendationAction(
 		writeError(w, http.StatusBadRequest, err.Error())
 		return
 	}
-	_ = s.cache.InvalidateUser(r.Context(), sess.EmbyUserID)
+	_ = s.cache.InvalidateUser(r.Context(), viewerKeyOf(r.Context(), sess))
 	if s.forYou != nil {
 		s.forYou.MarkDirty(context.WithoutCancel(r.Context()), sess)
 		s.forYou.RefreshAsync(sess, false)
@@ -640,7 +640,7 @@ func (s *Server) handleRecommendationPreferences(
 		writeError(w, http.StatusInternalServerError, "could not save onboarding preferences")
 		return
 	}
-	_ = s.cache.InvalidateUser(r.Context(), sess.EmbyUserID)
+	_ = s.cache.InvalidateUser(r.Context(), viewerKeyOf(r.Context(), sess))
 	if s.forYou != nil {
 		s.forYou.MarkDirty(context.WithoutCancel(r.Context()), sess)
 		s.forYou.RefreshAsync(sess, false)

server/internal/api/ratings_attach.go

@@ -231,7 +231,18 @@ func (s *Server) decorateHomeRatings(ctx context.Context, out *homeResponse) {
 	}
 	collections = append(collections,
 		out.ContinueWatching, out.NextUp, out.Favorites, out.LatestMovies)
+	s.decorateItems(ctx, collections...)
+}
+
+// decorateItems is the one door items leave the gateway through.
+//
+// It attaches both of the things Memby knows about a title that Emby's payload does not
+// carry: the stored review scores, and — for a shadow viewer — whose progress this is. The
+// two are separate concerns and stayed separate functions, but every call site wanted both,
+// and a decoration added at seven sites is a decoration missing from the eighth.
+func (s *Server) decorateItems(ctx context.Context, collections ...[]json.RawMessage) {
 	s.decorateItemRatings(ctx, collections...)
+	s.decorateViewerState(ctx, collections...)
 }
 
 // decorateItemRatings rewrites each item in place with whatever the database already
@@ -293,7 +304,7 @@ func (s *Server) decorateRowRatings(ctx context.Context, rows []recommend.Row) {
 	for _, row := range rows {
 		collections = append(collections, row.Items)
 	}
-	s.decorateItemRatings(ctx, collections...)
+	s.decorateItems(ctx, collections...)
 }
 
 // ratingKeysForItems resolves Emby ids to external titles, preferring the index built by

server/internal/api/related.go

@@ -40,7 +40,7 @@ func (s *Server) handleRelated(w http.ResponseWriter, r *http.Request, sess stor
 		writeError(w, http.StatusBadRequest, "item id is required")
 		return
 	}
-	key := cache.UserKey(sess.EmbyUserID, "related:v2:"+itemID)
+	key := cache.UserKey(viewerKeyOf(ctx, sess), "related:v2:"+itemID)
 	if raw, err := s.cache.Get(ctx, key); err == nil {
 		w.Header().Set("X-Memby-Cache", "hit")
 		writeRaw(w, http.StatusOK, raw)
@@ -64,7 +64,7 @@ func (s *Server) handleRelated(w http.ResponseWriter, r *http.Request, sess stor
 				return nil, err
 			}
 			items := nonNilRaws(recommend.Raws(related))
-			s.decorateItemRatings(ctx, items)
+			s.decorateItems(ctx, items)
 			return json.Marshal(relatedResponse{
 				Reasons: nonNilStrings(reasons),
 				Items:   items,

server/internal/api/viewer_rows.go

@@ -0,0 +1,174 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/url"
+	"strings"
+
+	"github.com/ponzischeme89/memby/server/internal/emby"
+	"github.com/ponzischeme89/memby/server/internal/store"
+	"github.com/ponzischeme89/memby/server/internal/timing"
+)
+
+// viewerRowLookupLimit bounds one row's worth of ids. A row is a shelf on a television and
+// nothing draws more than a screenful plus what the D-pad can reach.
+const viewerRowLookupLimit = 60
+
+// itemsByID fetches a named set of titles and returns them **in the order asked for**.
+//
+// Emby answers an Ids= query in its own order, and for a shadow viewer the order is the
+// whole answer: Continue Watching is "what am I in the middle of, most recent first", and
+// that ranking was decided in Postgres out of this viewer's own history. Handing back
+// Emby's order would keep the right titles and throw away the reason they were chosen.
+//
+// The metadata is still Emby's. Only the viewing state belongs to Memby, which is why this
+// asks for the ordinary row fields and lets decorateItems replace the UserData afterwards.
+func (s *Server) itemsByID(
+	ctx context.Context, cred emby.Credentials, ids []string, fields string,
+) (*emby.ItemsResult, error) {
+	if len(ids) == 0 {
+		return &emby.ItemsResult{}, nil
+	}
+	if len(ids) > viewerRowLookupLimit {
+		ids = ids[:viewerRowLookupLimit]
+	}
+	result, err := s.emby.Items(ctx, cred, rowParams(url.Values{
+		"Ids":       {strings.Join(ids, ",")},
+		"Recursive": {"true"},
+		"Limit":     {itoa(len(ids))},
+	}, fields))
+	if err != nil {
+		return nil, err
+	}
+	result.Items = orderItemsByID(result.Items, ids)
+	return result, nil
+}
+
+// orderItemsByID puts a set of items back into the order they were asked for.
+//
+// A title the catalogue still names but Emby no longer answers for is dropped rather than
+// left as a gap — the row is drawn from what comes back, and a missing card is better than
+// one that cannot be opened. A title Emby volunteers that was not asked for is dropped too:
+// the ids are the answer, and anything else in the response is not part of it.
+func orderItemsByID(items []json.RawMessage, ids []string) []json.RawMessage {
+	byID := make(map[string]json.RawMessage, len(items))
+	for _, raw := range items {
+		if id := itemIDOf(raw); id != "" {
+			if _, seen := byID[id]; !seen {
+				byID[id] = raw
+			}
+		}
+	}
+	ordered := make([]json.RawMessage, 0, len(ids))
+	for _, id := range ids {
+		if raw, ok := byID[id]; ok {
+			ordered = append(ordered, raw)
+			// Removed so a repeated id cannot draw the same card twice. The television
+			// keys its rows by item id and throws on a duplicate.
+			delete(byID, id)
+		}
+	}
+	return ordered
+}
+
+// viewerContinueRow is a shadow viewer's Continue Watching, built from their own playheads.
+func (s *Server) viewerContinueRow(
+	ctx context.Context, cred emby.Credentials, viewerID string, limit int,
+) (*emby.ItemsResult, error) {
+	ids, err := s.store.ViewerResumeItems(ctx, viewerID, limit)
+	if err != nil {
+		return nil, err
+	}
+	return s.itemsByID(timing.WithLabel(ctx, "emby.viewer_resume"), cred, ids, fieldsContinue)
+}
+
+// viewerNextUpRow is the next unwatched episode of each series this viewer is part-way
+// through. The ranking is Postgres's; Emby is only asked to describe the titles.
+func (s *Server) viewerNextUpRow(
+	ctx context.Context, cred emby.Credentials, viewerID string, limit int,
+) (*emby.ItemsResult, error) {
+	ids, err := s.store.ViewerNextUp(ctx, viewerID, limit)
+	if err != nil {
+		return nil, err
+	}
+	return s.itemsByID(timing.WithLabel(ctx, "emby.viewer_nextup"), cred, ids, fieldsContinue)
+}
+
+// viewerFavouritesRow is this viewer's own favourites rather than the account's.
+//
+// It is deliberately *not* re-sorted by name the way the Emby row is. A shadow viewer's
+// favourites are the ones they marked, and the order they marked them in is the only
+// ordering Memby has that means anything.
+func (s *Server) viewerFavouritesRow(
+	ctx context.Context, cred emby.Credentials, viewerID string, limit int,
+) (*emby.ItemsResult, error) {
+	ids, err := s.store.ViewerFavouriteItems(ctx, viewerID, limit)
+	if err != nil {
+		return nil, err
+	}
+	return s.itemsByID(timing.WithLabel(ctx, "emby.viewer_favourites"), cred, ids, fieldsRow)
+}
+
+// firstUnwatchedEpisodeFor is where a shadow viewer's series starts.
+//
+// It reads the series' episodes once from Emby and walks them against this viewer's own
+// played set, rather than asking Emby's NextUp — which answers for the account and is the
+// whole reason a shadow viewer pressing Play on a show they have never seen was being
+// dropped into the middle of somebody else's season.
+//
+// A part-watched episode wins over the first unwatched one: somebody eleven minutes into
+// an episode wants that episode, which is the same judgement the Continue Watching merge
+// makes.
+func (s *Server) firstUnwatchedEpisodeFor(
+	ctx context.Context, cred emby.Credentials, viewer store.Viewer, seriesID string,
+) (*emby.Summary, error) {
+	states, err := s.store.ViewerPlayedInSeries(ctx, viewer.ID, seriesID)
+	if err != nil {
+		return nil, err
+	}
+	if len(states) == 0 {
+		// Never watched. Emby's own first episode is the right answer and costs the
+		// caller nothing extra to ask for.
+		return nil, nil
+	}
+	episodes, err := s.emby.Episodes(timing.WithLabel(ctx, "emby.viewer_series"), cred, seriesID, url.Values{
+		"Fields":                 {"Overview,RunTimeTicks,SeriesName,ParentIndexNumber,IndexNumber"},
+		"EnableUserData":         {"false"},
+		"EnableTotalRecordCount": {"false"},
+	})
+	if err != nil {
+		return nil, err
+	}
+	resume, err := s.store.ViewerStates(ctx, viewer.ID, episodeIDsOf(episodes.Items))
+	if err != nil {
+		return nil, err
+	}
+	var firstUnplayed *emby.Summary
+	for _, raw := range episodes.Items {
+		summary, err := emby.Summarise(raw)
+		if err != nil || summary.ID == "" {
+			continue
+		}
+		state := resume[summary.ID]
+		if state.PositionTicks > 0 && !state.Played {
+			summary.UserData.PlaybackPositionTicks = state.PositionTicks
+			return &summary, nil
+		}
+		if !state.Played && firstUnplayed == nil {
+			episode := summary
+			firstUnplayed = &episode
+		}
+	}
+	return firstUnplayed, nil
+}
+
+func episodeIDsOf(items []json.RawMessage) []string {
+	ids := make([]string, 0, len(items))
+	for _, raw := range items {
+		if id := itemIDOf(raw); id != "" {
+			ids = append(ids, id)
+		}
+	}
+	return ids
+}

server/internal/api/viewer_state_attach.go

@@ -0,0 +1,172 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/ponzischeme89/memby/server/internal/store"
+)
+
+// userDataItemField is the block a television draws a progress bar, a tick and a heart
+// from. For a shadow viewer it is written here rather than by Emby.
+const userDataItemField = "UserData"
+
+// A launcher is a few hundred cards. This matches the ratings attach limit for the same
+// reason: it guards against a future row type asking for a thousand, not against anything
+// reached today.
+const viewerStateItemLimit = 600
+
+// decorateViewerState replaces the UserData on every item with this viewer's own.
+//
+// It is the read half of what the four gated mutations are the write half of, and it rides
+// exactly where decorateItemRatings rides — one indexed read for a whole launcher, at every
+// point items leave the gateway. A card then draws the right progress bar as the row
+// appears, and nothing above this line has to know which viewer it is drawing for.
+//
+// Three things to preserve:
+//
+// 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 in place on a title this viewer has
+// never touched is precisely the leak this feature exists to prevent: Alessandra would see
+// Matt's progress bars on everything neither of them had watched together. A title with no
+// row gets the zero state, which is the truth about it.
+//
+// A series and a season are aggregates, so they are rewritten from a *count* rather than
+// from a row of their own: Emby fills their block in from their children, and a shadow
+// viewer has no children Emby knows about. This was the last place they were still shown
+// the account's answer — a series ticked because somebody else had finished it.
+func (s *Server) decorateViewerState(ctx context.Context, collections ...[]json.RawMessage) {
+	// The viewer is read from the context alone. Outside a request there is none, and the
+	// zero session resolves to a main viewer, so a scheduled task or a test decorates
+	// nothing rather than blanking what it was given.
+	viewer := viewerOf(ctx, store.Session{})
+	if viewer.IsMain() || s.store == nil {
+		return
+	}
+	ids := itemIDsIn(collections, viewerStateItemLimit)
+	if len(ids) == 0 {
+		return
+	}
+	states, err := s.store.ViewerStates(ctx, viewer.ID, ids)
+	if err != nil {
+		// A state read that fails must not hand the viewer the account's watched state,
+		// so every item is blanked rather than left as it arrived. A launcher with no
+		// progress bars is a poor answer; one showing somebody else's is a wrong one.
+		s.loggerFor(ctx).Warn("viewer state read failed", "error", err)
+		states = map[string]store.ViewerState{}
+	}
+	// The aggregate half is a second read and is only paid for by a response that
+	// actually carries a series or a season card. Its failure is the same failure the leaf
+	// read has: an empty map, so every container is blanked rather than left carrying
+	// somebody else's progress.
+	seriesIDs, seasonIDs := containerIDsIn(collections)
+	containers := map[string]store.ViewerAggregate{}
+	if len(seriesIDs) > 0 || len(seasonIDs) > 0 {
+		found, err := s.store.ViewerContainerStates(ctx, viewer.ID, seriesIDs, seasonIDs)
+		if err != nil {
+			s.loggerFor(ctx).Warn("viewer container state read failed", "error", err)
+		} else {
+			containers = found
+		}
+	}
+
+	for _, items := range collections {
+		for index, raw := range items {
+			id := itemIDOf(raw)
+			if id == "" {
+				continue
+			}
+			if isAggregateItem(raw) {
+				items[index] = injectItemUserData(
+					raw, viewerAggregateUserData(states[id], containers[id]),
+				)
+				continue
+			}
+			items[index] = injectItemUserData(raw, viewerUserData(states[id]))
+		}
+	}
+}
+
+// isAggregateItem reports whether an item's UserData describes its children rather than
+// itself. Emby fills a series' and a season's block in from their episodes.
+func isAggregateItem(raw json.RawMessage) bool {
+	return itemTypeOf(raw) == "Series" || itemTypeOf(raw) == "Season"
+}
+
+func itemTypeOf(raw json.RawMessage) string {
+	var item struct {
+		Type string `json:"Type"`
+	}
+	if json.Unmarshal(raw, &item) != nil {
+		return ""
+	}
+	return item.Type
+}
+
+// containerIDsIn collects the series and seasons a response is carrying.
+//
+// A **series** is keyed by its own id, because that is what its episodes carry as their
+// series id. A **season** cannot be: its episodes carry its id in their payload, but the
+// catalogue's indexed column is the series, so a season is looked up by its own id *and*
+// its series is asked for alongside — which is what makes one query answer for a season
+// card sitting on a page about a show the response also carries.
+func containerIDsIn(collections [][]json.RawMessage) (seriesIDs, seasonIDs []string) {
+	seenSeries := map[string]bool{}
+	seenSeasons := map[string]bool{}
+	for _, items := range collections {
+		for _, raw := range items {
+			id := itemIDOf(raw)
+			if id == "" {
+				continue
+			}
+			switch itemTypeOf(raw) {
+			case "Series":
+				if !seenSeries[id] {
+					seenSeries[id] = true
+					seriesIDs = append(seriesIDs, id)
+				}
+			case "Season":
+				if !seenSeasons[id] {
+					seenSeasons[id] = true
+					seasonIDs = append(seasonIDs, id)
+				}
+				if parent := seriesIDOf(raw); parent != "" && !seenSeries[parent] {
+					seenSeries[parent] = true
+					seriesIDs = append(seriesIDs, parent)
+				}
+			}
+		}
+	}
+	return seriesIDs, seasonIDs
+}
+
+func seriesIDOf(raw json.RawMessage) string {
+	var item struct {
+		SeriesID string `json:"SeriesId"`
+	}
+	if json.Unmarshal(raw, &item) != nil {
+		return ""
+	}
+	return item.SeriesID
+}
+
+// injectItemUserData replaces one item's UserData block.
+//
+// It rewrites rather than merges: a partial overlay would leave whichever fields Memby had
+// nothing to say about carrying the account's values, which is the same leak from a
+// narrower angle.
+func injectItemUserData(raw, userData json.RawMessage) json.RawMessage {
+	var members map[string]json.RawMessage
+	if json.Unmarshal(raw, &members) != nil || members == nil {
+		return raw
+	}
+	members[userDataItemField] = userData
+	out, err := json.Marshal(members)
+	if err != nil {
+		return raw
+	}
+	return out
+}

server/internal/api/viewers.go

@@ -0,0 +1,414 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/ponzischeme89/memby/server/internal/store"
+)
+
+// viewerHeader names the person watching, as distinct from the account streaming.
+//
+// It is a header rather than part of the session because a viewer does not belong to a
+// television: somebody starts an episode in the lounge and finishes it in the bedroom, and
+// switching between two people on one set must not be a re-authentication. The session
+// still answers "which Emby account is this and what may it read"; this answers "whose
+// evening is it", and the two are separate questions.
+const viewerHeader = "X-Memby-Viewer"
+
+// The header is *stated, never inferred* — the stance Credentials.Gateway takes. An app
+// that predates viewers sends nothing and resolves to the account's main viewer, which is
+// exactly the behaviour it had before this existed; guessing from anything else would file
+// a household's ordinary watching under somebody who does not exist.
+
+// How long an account's viewer list is trusted in memory.
+//
+// Every authenticated request resolves a viewer, and /v1/status alone is every open
+// television every ten seconds — a Postgres round trip each, for a list that changes when
+// somebody adds a person to the household. A write clears it, so the window is "how long
+// until another instance notices" rather than "how long until my change takes effect", the
+// bargain featurePolicyCache already makes.
+const viewerListTTL = 30 * time.Second
+
+type viewerListCache struct {
+	mu      sync.Mutex
+	entries map[string]viewerListEntry
+}
+
+type viewerListEntry struct {
+	viewers  []store.Viewer
+	loadedAt time.Time
+}
+
+// viewersFor lists an account's viewers, from memory where it can.
+func (s *Server) viewersFor(ctx context.Context, sess store.Session) ([]store.Viewer, error) {
+	if s.store == nil {
+		return nil, errors.New("no store")
+	}
+	c := &s.viewerLists
+	now := time.Now()
+	c.mu.Lock()
+	entry, ok := c.entries[sess.EmbyUserID]
+	c.mu.Unlock()
+	if ok && now.Sub(entry.loadedAt) < viewerListTTL {
+		return entry.viewers, nil
+	}
+
+	viewers, err := s.store.Viewers(ctx, sess.EmbyUserID, sess.Username)
+	if err != nil {
+		// A list that will not load is not evidence that the household has no viewers, so
+		// a stale reading is preferred to none: losing it would silently move a shadow
+		// viewer's playback back onto the Emby account, which is the one failure this
+		// feature must never have.
+		if ok {
+			return entry.viewers, nil
+		}
+		return nil, err
+	}
+	c.mu.Lock()
+	if c.entries == nil {
+		c.entries = map[string]viewerListEntry{}
+	}
+	c.entries[sess.EmbyUserID] = viewerListEntry{viewers: viewers, loadedAt: now}
+	c.mu.Unlock()
+	return viewers, nil
+}
+
+// forgetViewers drops an account's cached list so a viewer added, renamed or removed is
+// live on the next request rather than at the end of the window.
+func (s *Server) forgetViewers(embyUserID string) {
+	c := &s.viewerLists
+	c.mu.Lock()
+	delete(c.entries, embyUserID)
+	c.mu.Unlock()
+}
+
+// activeViewer resolves who is watching.
+//
+// Every unknown case resolves to the main viewer, and that is deliberate: this is on the
+// path of every authenticated request, and the failure it is protecting against — a
+// television left unable to do anything because a header could not be checked — is far
+// worse than a shadow viewer's episode being attributed to the account for one request.
+// The one thing it will not do is accept an id it could not confirm belongs to this
+// account, because that would let one household's television read another's viewing.
+func (s *Server) activeViewer(ctx context.Context, sess store.Session, r *http.Request) store.Viewer {
+	fallback := store.Viewer{ID: sess.EmbyUserID, Name: sess.Username, Kind: store.ViewerMain}
+	// The operator's switch is read here rather than at each of the four mutations,
+	// because this is the one place a request learns who is watching: with it off there is
+	// no shadow viewer to resolve to, so 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.
+	if !s.viewersEnabled(ctx) {
+		return fallback
+	}
+	requested := strings.TrimSpace(r.Header.Get(viewerHeader))
+	if requested == "" || requested == sess.EmbyUserID {
+		return fallback
+	}
+	viewers, err := s.viewersFor(ctx, sess)
+	if err != nil {
+		s.loggerFor(ctx).Warn("viewer list unavailable", "error", err)
+		return fallback
+	}
+	for _, viewer := range viewers {
+		if viewer.ID == requested {
+			return viewer
+		}
+	}
+	// An id this account does not own. It is logged rather than refused: the ordinary
+	// cause is a television still holding a viewer somebody has since deleted, and
+	// answering 403 to every request would leave that set unable to reach the picker that
+	// would fix it.
+	s.loggerFor(ctx).Warn("unknown viewer requested", "viewer", requested)
+	return fallback
+}
+
+// viewersEnabled reports whether the household is running viewers at all.
+//
+// Off is not a deletion. A viewer's rows stay in Postgres untouched and come back intact
+// when it is switched on again; what stops is the gateway routing anybody's watching
+// anywhere but Emby, which is exactly the state a household was in before this existed.
+func (s *Server) viewersEnabled(ctx context.Context) bool {
+	return s.featureEnabled(ctx, featureViewers)
+}
+
+// mainViewerOnly is what an account's list looks like with the feature switched off.
+//
+// It is 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: one viewer is an
+// account nobody has added anybody to, which is the reading that makes a switched-off
+// household look like one that never used the feature rather than like one whose picker
+// has broken.
+func mainViewerOnly(viewers []store.Viewer) []store.Viewer {
+	for _, viewer := range viewers {
+		if viewer.IsMain() {
+			return []store.Viewer{viewer}
+		}
+	}
+	return nil
+}
+
+// --- carrying the viewer through one request --------------------------------
+
+type viewerContextKey struct{}
+
+// withViewer installs the resolved viewer for the rest of the request.
+//
+// It is resolved once, in [Server.authed], and read from the context everywhere else. The
+// alternative — every handler that needs a cache key calling activeViewer for itself —
+// is fifteen call sites that must each remember to, and the failure of forgetting one is
+// silent: the handler simply keys that view under the account, and one viewer is served
+// another viewer's rows. Resolving it at the boundary makes forgetting impossible.
+func withViewer(ctx context.Context, viewer store.Viewer) context.Context {
+	return context.WithValue(ctx, viewerContextKey{}, viewer)
+}
+
+// viewerOf reports who this request belongs to.
+//
+// A request with no viewer in its context is one that never passed through authed — a
+// scheduled task, a probe, a test — and the account's own id is the honest answer for it,
+// which is also the value every one of these keys held before viewers existed.
+func viewerOf(ctx context.Context, sess store.Session) store.Viewer {
+	if viewer, ok := ctx.Value(viewerContextKey{}).(store.Viewer); ok && viewer.ID != "" {
+		return viewer
+	}
+	return store.Viewer{ID: sess.EmbyUserID, Name: sess.Username, Kind: store.ViewerMain}
+}
+
+// viewerKeyOf is the shorthand the cache keys use: the id everything about this person is
+// filed under. For the main viewer it is the Emby user id, so an existing household's
+// cached views keep the names they already had.
+func viewerKeyOf(ctx context.Context, sess store.Session) string {
+	return viewerOf(ctx, sess).ID
+}
+
+// viewerID is the key everything about a *person* is stored under — preferences,
+// notifications, followed shows, row statistics, recommendation profiles.
+//
+// For the main viewer it is the Emby user id, which is why this feature needed no
+// migration: an existing household's rows are already filed under exactly this value.
+func viewerID(viewer store.Viewer) string { return viewer.ID }
+
+// --- the common state layer -------------------------------------------------
+
+// viewerUserData renders one viewer's state in the shape of Emby's UserData block.
+//
+// This is the seam the client never sees. A television asks for a row and draws a progress
+// bar, a tick and a heart from UserData; whether that block came from Emby or from Postgres
+// is not a question anything above this line asks, which is what keeps viewers from
+// becoming a special case in every screen.
+func viewerUserData(state store.ViewerState) json.RawMessage {
+	payload := map[string]any{
+		"IsFavorite":            state.Favourite,
+		"Played":                state.Played,
+		"PlaybackPositionTicks": state.PositionTicks,
+		"PlayCount":             state.PlayCount,
+	}
+	if state.RuntimeTicks > 0 && state.PositionTicks > 0 {
+		payload["PlayedPercentage"] = float64(state.PositionTicks) / float64(state.RuntimeTicks) * 100
+	}
+	if state.LastPlayedAt != nil {
+		payload["LastPlayedDate"] = state.LastPlayedAt.UTC().Format(time.RFC3339)
+	}
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return json.RawMessage(`{}`)
+	}
+	return raw
+}
+
+// viewerAggregateUserData renders a series' or a season's block from a count of episodes.
+//
+// Emby fills those in from an item's children, and a shadow viewer has no children Emby
+// has ever heard of — so the count comes from the shared catalogue and this viewer's own
+// state. The favourite is the one field that is genuinely the container's own: somebody
+// marks a *show* a favourite, not the sum of its episodes, so it is read from the row
+// against the series id rather than derived.
+//
+// Two things are omitted rather than sent as zero, the rule the leaf block follows. A
+// container the catalogue cannot count for — a library not yet imported, a show it has
+// never seen — has no unwatched count, because "0 left" and "I cannot say" are different
+// answers and only one of them is true. And a container nothing has been watched of has no
+// last-played date.
+func viewerAggregateUserData(state store.ViewerState, aggregate store.ViewerAggregate) json.RawMessage {
+	payload := map[string]any{
+		"IsFavorite": state.Favourite,
+		// A container is never resumable: what resumes is an episode, and Emby reports
+		// zero here for the same reason.
+		"PlaybackPositionTicks": 0,
+		"PlayCount":             aggregate.Played,
+		// Played only where there is something to have finished. An empty catalogue must
+		// not tick every show in the house.
+		"Played": aggregate.Total > 0 && aggregate.Played >= aggregate.Total,
+	}
+	if aggregate.Total > 0 {
+		unplayed := aggregate.Total - aggregate.Played
+		if unplayed < 0 {
+			unplayed = 0
+		}
+		payload["UnplayedItemCount"] = unplayed
+		payload["PlayedPercentage"] = float64(aggregate.Played) / float64(aggregate.Total) * 100
+	}
+	if aggregate.LastPlayedAt != nil {
+		payload["LastPlayedDate"] = aggregate.LastPlayedAt.UTC().Format(time.RFC3339)
+	}
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return json.RawMessage(`{}`)
+	}
+	return raw
+}
+
+// --- routes -----------------------------------------------------------------
+
+type viewersResponse struct {
+	Viewers []store.Viewer `json:"viewers"`
+	Active  string         `json:"active"`
+}
+
+type viewerRequest struct {
+	Name      string `json:"name"`
+	ShortName string `json:"shortName"`
+	Colour    string `json:"colour"`
+}
+
+func (s *Server) handleViewers(w http.ResponseWriter, r *http.Request, sess store.Session) {
+	if r.Method == http.MethodPost {
+		s.handleCreateViewer(w, r, sess)
+		return
+	}
+	viewers, err := s.viewersFor(r.Context(), sess)
+	if err != nil {
+		s.writeUpstreamError(r.Context(), w, err, "could not load viewers")
+		return
+	}
+	if !s.viewersEnabled(r.Context()) {
+		viewers = mainViewerOnly(viewers)
+	}
+	writeJSON(w, http.StatusOK, viewersResponse{
+		Viewers: viewers,
+		Active:  s.activeViewer(r.Context(), sess, r).ID,
+	})
+}
+
+func (s *Server) handleCreateViewer(w http.ResponseWriter, r *http.Request, sess store.Session) {
+	// A refusal rather than a silent success: the television is about to draw a card for
+	// somebody, and an operator who has switched the feature off has said the household
+	// does not use it. The wording names the reason, because a television has no log and
+	// no support channel and that sentence is the whole diagnosis.
+	if !s.viewersEnabled(r.Context()) {
+		writeError(w, http.StatusForbidden, "viewers are switched off for this server")
+		return
+	}
+	var req viewerRequest
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4<<10)).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "malformed request body")
+		return
+	}
+	if strings.TrimSpace(req.Name) == "" {
+		writeError(w, http.StatusBadRequest, "a name is required")
+		return
+	}
+	if len([]rune(req.Name)) > 40 {
+		writeError(w, http.StatusBadRequest, "that name is too long")
+		return
+	}
+	viewer, err := s.store.CreateShadowViewer(
+		r.Context(), sess.EmbyUserID, req.Name, req.ShortName, req.Colour,
+	)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	s.forgetViewers(sess.EmbyUserID)
+	s.loggerFor(r.Context()).Info("viewer added", "viewer", viewer.ID, "name", viewer.Name)
+	writeJSON(w, http.StatusOK, viewer)
+}
+
+func (s *Server) handleViewer(w http.ResponseWriter, r *http.Request, sess store.Session) {
+	id := r.PathValue("viewerID")
+	if id == "" {
+		writeError(w, http.StatusBadRequest, "viewer id is required")
+		return
+	}
+	if !s.viewersEnabled(r.Context()) {
+		writeError(w, http.StatusForbidden, "viewers are switched off for this server")
+		return
+	}
+	if r.Method == http.MethodDelete {
+		if err := s.store.DeleteShadowViewer(r.Context(), sess.EmbyUserID, id); err != nil {
+			if errors.Is(err, store.ErrViewerNotFound) {
+				writeError(w, http.StatusNotFound, "no such viewer")
+				return
+			}
+			s.writeUpstreamError(r.Context(), w, err, "could not remove that viewer")
+			return
+		}
+		s.forgetViewers(sess.EmbyUserID)
+		// Everything cached under this viewer's own key is now about nobody.
+		if err := s.cache.InvalidateUser(r.Context(), id); err != nil {
+			s.loggerFor(r.Context()).Warn("cache invalidation failed", "error", err)
+		}
+		s.loggerFor(r.Context()).Info("viewer removed", "viewer", id)
+		writeJSON(w, http.StatusOK, map[string]bool{"removed": true})
+		return
+	}
+
+	var req viewerRequest
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4<<10)).Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "malformed request body")
+		return
+	}
+	viewer, err := s.store.UpdateShadowViewer(
+		r.Context(), sess.EmbyUserID, id, req.Name, req.ShortName, req.Colour,
+	)
+	if err != nil {
+		if errors.Is(err, store.ErrViewerNotFound) {
+			writeError(w, http.StatusNotFound, "no such viewer")
+			return
+		}
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	s.forgetViewers(sess.EmbyUserID)
+	writeJSON(w, http.StatusOK, viewer)
+}
+
+// invalidateAccountViews drops the cached views of every viewer on an account.
+//
+// Signing a television out, or an operator resetting somebody, is a statement about the
+// account rather than about whoever happened to be watching — so invalidating the account's
+// own key alone would leave each shadow viewer's rows behind, to be served intact to the
+// next person who signs in on that set.
+//
+// The list is read directly rather than through the cache, because this is called at
+// exactly the moments the cached copy is least trustworthy, and it is best-effort: the
+// entries it misses expire on their own TTL, and nothing here is worth failing a sign-out
+// over.
+func (s *Server) invalidateAccountViews(ctx context.Context, sess store.Session) {
+	if err := s.cache.InvalidateUser(ctx, sess.EmbyUserID); err != nil {
+		s.loggerFor(ctx).Warn("cache invalidation failed", "error", err)
+	}
+	if s.store == nil {
+		return
+	}
+	viewers, err := s.store.Viewers(ctx, sess.EmbyUserID, sess.Username)
+	if err != nil {
+		s.loggerFor(ctx).Warn("viewer list unavailable for invalidation", "error", err)
+		return
+	}
+	for _, viewer := range viewers {
+		if viewer.IsMain() {
+			continue
+		}
+		if err := s.cache.InvalidateUser(ctx, viewer.ID); err != nil {
+			s.loggerFor(ctx).Warn("viewer cache invalidation failed",
+				"viewer", viewer.ID, "error", err)
+		}
+	}
+}

server/internal/api/viewers_test.go

@@ -0,0 +1,364 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/ponzischeme89/memby/server/internal/store"
+)
+
+// The television has one UserData reader and it must not be able to tell where the block
+// came from. This pins the field names against the client's UserItemData, which is the
+// contract that keeps viewers from becoming a special case in every screen.
+func TestViewerUserDataIsShapedLikeEmbys(t *testing.T) {
+	played := time.Date(2026, 8, 19, 21, 14, 0, 0, time.UTC)
+	raw := viewerUserData(store.ViewerState{
+		ItemID:        "982173",
+		PositionTicks: 15_420_000_000,
+		RuntimeTicks:  30_840_000_000,
+		PlayCount:     2,
+		Favourite:     true,
+		LastPlayedAt:  &played,
+	})
+
+	var parsed struct {
+		IsFavorite            bool     `json:"IsFavorite"`
+		Played                bool     `json:"Played"`
+		PlaybackPositionTicks int64    `json:"PlaybackPositionTicks"`
+		PlayCount             int      `json:"PlayCount"`
+		PlayedPercentage      *float64 `json:"PlayedPercentage"`
+		LastPlayedDate        string   `json:"LastPlayedDate"`
+	}
+	if err := json.Unmarshal(raw, &parsed); err != nil {
+		t.Fatalf("decode viewer user data: %v", err)
+	}
+	if !parsed.IsFavorite {
+		t.Error("favourite was not carried")
+	}
+	if parsed.Played {
+		t.Error("a part-watched title was reported as played")
+	}
+	if parsed.PlaybackPositionTicks != 15_420_000_000 {
+		t.Errorf("position = %d", parsed.PlaybackPositionTicks)
+	}
+	if parsed.PlayCount != 2 {
+		t.Errorf("play count = %d", parsed.PlayCount)
+	}
+	if parsed.PlayedPercentage == nil || *parsed.PlayedPercentage < 49 || *parsed.PlayedPercentage > 51 {
+		t.Errorf("played percentage = %v, want about 50", parsed.PlayedPercentage)
+	}
+	if parsed.LastPlayedDate != "2026-08-19T21:14:00Z" {
+		t.Errorf("last played = %q", parsed.LastPlayedDate)
+	}
+}
+
+// A title nobody has touched has to render as untouched rather than as a card claiming a
+// zero-length progress bar, so the two optional fields are omitted rather than sent empty.
+func TestViewerUserDataOmitsWhatItDoesNotKnow(t *testing.T) {
+	raw := viewerUserData(store.ViewerState{ItemID: "982173"})
+	var fields map[string]any
+	if err := json.Unmarshal(raw, &fields); err != nil {
+		t.Fatalf("decode viewer user data: %v", err)
+	}
+	if _, ok := fields["PlayedPercentage"]; ok {
+		t.Error("a percentage was claimed for a title with no runtime or position")
+	}
+	if _, ok := fields["LastPlayedDate"]; ok {
+		t.Error("a play date was claimed for a title that has never been played")
+	}
+	if fields["Played"] != false || fields["IsFavorite"] != false {
+		t.Errorf("untouched state rendered as %v", fields)
+	}
+}
+
+// IsMain is what every mutation branches on, so it is worth stating that it reads the
+// stored kind rather than guessing from the id.
+func TestViewerIsMainReadsTheStoredKind(t *testing.T) {
+	if !(store.Viewer{ID: "abc", Kind: store.ViewerMain}).IsMain() {
+		t.Error("a main viewer did not report as main")
+	}
+	if (store.Viewer{ID: "abc", Kind: store.ViewerShadow}).IsMain() {
+		t.Error("a shadow viewer reported as main")
+	}
+	if (store.Viewer{ID: "abc"}).IsMain() {
+		t.Error("a viewer with no kind reported as main")
+	}
+}
+
+// The ids are the answer, not just the selection: a shadow viewer's Continue Watching is
+// ordered by their own history in Postgres, and Emby answers an Ids= query in its own
+// order. Handing that back would keep the right titles and discard the reason for them.
+func TestOrderItemsByIDRestoresTheOrderAskedFor(t *testing.T) {
+	item := func(id string) json.RawMessage {
+		return json.RawMessage(`{"Id":"` + id + `","Name":"` + id + `"}`)
+	}
+	idsOf := func(items []json.RawMessage) []string {
+		out := []string{}
+		for _, raw := range items {
+			out = append(out, itemIDOf(raw))
+		}
+		return out
+	}
+
+	t.Run("emby's order is replaced", func(t *testing.T) {
+		got := orderItemsByID(
+			[]json.RawMessage{item("c"), item("a"), item("b")},
+			[]string{"b", "c", "a"},
+		)
+		want := []string{"b", "c", "a"}
+		if diff := idsOf(got); !equalStrings(diff, want) {
+			t.Fatalf("order = %v, want %v", diff, want)
+		}
+	})
+
+	// A title the catalogue still names but Emby will not answer for leaves a card that
+	// cannot be opened, so it is dropped instead.
+	t.Run("a missing title is dropped", func(t *testing.T) {
+		got := orderItemsByID([]json.RawMessage{item("a")}, []string{"a", "gone", "b"})
+		if diff := idsOf(got); !equalStrings(diff, []string{"a"}) {
+			t.Fatalf("order = %v, want [a]", diff)
+		}
+	})
+
+	// Every keyed list on the television throws on a repeated key, and a paging boundary
+	// or a duplicated row is exactly where an id comes back twice.
+	t.Run("a repeated id draws one card", func(t *testing.T) {
+		got := orderItemsByID([]json.RawMessage{item("a"), item("a")}, []string{"a", "a"})
+		if diff := idsOf(got); !equalStrings(diff, []string{"a"}) {
+			t.Fatalf("order = %v, want one card", diff)
+		}
+	})
+
+	// Anything Emby volunteers that was not asked for is not part of the answer.
+	t.Run("an unasked title is dropped", func(t *testing.T) {
+		got := orderItemsByID([]json.RawMessage{item("a"), item("z")}, []string{"a"})
+		if diff := idsOf(got); !equalStrings(diff, []string{"a"}) {
+			t.Fatalf("order = %v, want [a]", diff)
+		}
+	})
+}
+
+// The account's UserData must be replaced outright rather than merged: a partial overlay
+// leaves whichever fields Memby had nothing to say about carrying the account's values.
+func TestInjectItemUserDataReplacesRatherThanMerges(t *testing.T) {
+	raw := json.RawMessage(
+		`{"Id":"1","Name":"Anatomy of a Fall",` +
+			`"UserData":{"Played":true,"PlaybackPositionTicks":9999,"IsFavorite":true,"PlayCount":4}}`)
+	out := injectItemUserData(raw, viewerUserData(store.ViewerState{ItemID: "1"}))
+
+	var parsed struct {
+		Name     string `json:"Name"`
+		UserData struct {
+			Played                bool  `json:"Played"`
+			PlaybackPositionTicks int64 `json:"PlaybackPositionTicks"`
+			IsFavorite            bool  `json:"IsFavorite"`
+			PlayCount             int   `json:"PlayCount"`
+		} `json:"UserData"`
+	}
+	if err := json.Unmarshal(out, &parsed); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if parsed.Name != "Anatomy of a Fall" {
+		t.Errorf("the rest of the item was disturbed: name = %q", parsed.Name)
+	}
+	if parsed.UserData.Played || parsed.UserData.IsFavorite {
+		t.Error("the account's watched or favourite state survived")
+	}
+	if parsed.UserData.PlaybackPositionTicks != 0 || parsed.UserData.PlayCount != 0 {
+		t.Errorf("the account's position or play count survived: %+v", parsed.UserData)
+	}
+}
+
+// A series and a season are answered from a count of episodes rather than from a row of
+// their own, so they have to be told apart from the leaf items around them.
+func TestAggregateItemsAreRecognised(t *testing.T) {
+	for _, tc := range []struct {
+		itemType string
+		want     bool
+	}{
+		{"Series", true},
+		{"Season", true},
+		{"Episode", false},
+		{"Movie", false},
+		{"", false},
+	} {
+		raw := json.RawMessage(`{"Id":"1","Type":"` + tc.itemType + `"}`)
+		if got := isAggregateItem(raw); got != tc.want {
+			t.Errorf("isAggregateItem(%q) = %v, want %v", tc.itemType, got, tc.want)
+		}
+	}
+}
+
+// Everything downstream keys its cached views on this, so a request that never passed
+// through authed must still answer with the value those keys held before viewers existed.
+func TestViewerOfFallsBackToTheAccount(t *testing.T) {
+	sess := store.Session{EmbyUserID: "emby-user-1", Username: "Matt"}
+	viewer := viewerOf(context.Background(), sess)
+	if !viewer.IsMain() || viewer.ID != "emby-user-1" {
+		t.Fatalf("fallback viewer = %+v, want the account as main", viewer)
+	}
+	if got := viewerKeyOf(context.Background(), sess); got != "emby-user-1" {
+		t.Fatalf("cache key = %q, want the Emby user id", got)
+	}
+
+	shadow := store.Viewer{ID: "v0123", Name: "Alessandra", Kind: store.ViewerShadow}
+	ctx := withViewer(context.Background(), shadow)
+	if got := viewerKeyOf(ctx, sess); got != "v0123" {
+		t.Fatalf("cache key = %q, want the shadow viewer", got)
+	}
+}
+
+func equalStrings(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+// The last place a shadow viewer was shown the account's answer. A series card draws its
+// tick and its "left to watch" from these fields, and Emby fills them in from children it
+// has never heard of for this person.
+func TestViewerAggregateUserDataCountsWhatIsLeft(t *testing.T) {
+	played := time.Date(2026, 8, 18, 20, 5, 0, 0, time.UTC)
+	raw := viewerAggregateUserData(
+		store.ViewerState{ItemID: "series-1", Favourite: true},
+		store.ViewerAggregate{Total: 10, Played: 4, LastPlayedAt: &played},
+	)
+
+	var parsed struct {
+		IsFavorite            bool     `json:"IsFavorite"`
+		Played                bool     `json:"Played"`
+		PlaybackPositionTicks int64    `json:"PlaybackPositionTicks"`
+		UnplayedItemCount     *int     `json:"UnplayedItemCount"`
+		PlayedPercentage      *float64 `json:"PlayedPercentage"`
+		LastPlayedDate        string   `json:"LastPlayedDate"`
+	}
+	if err := json.Unmarshal(raw, &parsed); err != nil {
+		t.Fatalf("decode aggregate user data: %v", err)
+	}
+	// The favourite is the container's own — somebody marks a show, not the sum of its
+	// episodes — so it comes from the row rather than from the count.
+	if !parsed.IsFavorite {
+		t.Error("the viewer's own favourite on the series was dropped")
+	}
+	if parsed.Played {
+		t.Error("a part-watched series reported as finished")
+	}
+	if parsed.UnplayedItemCount == nil || *parsed.UnplayedItemCount != 6 {
+		t.Errorf("unplayed = %v, want 6", parsed.UnplayedItemCount)
+	}
+	if parsed.PlayedPercentage == nil || *parsed.PlayedPercentage < 39 || *parsed.PlayedPercentage > 41 {
+		t.Errorf("played percentage = %v, want about 40", parsed.PlayedPercentage)
+	}
+	// A container is never resumable; what resumes is an episode.
+	if parsed.PlaybackPositionTicks != 0 {
+		t.Errorf("a series carried a resume position: %d", parsed.PlaybackPositionTicks)
+	}
+	if parsed.LastPlayedDate != "2026-08-18T20:05:00Z" {
+		t.Errorf("last played = %q", parsed.LastPlayedDate)
+	}
+
+	finished := viewerAggregateUserData(
+		store.ViewerState{}, store.ViewerAggregate{Total: 10, Played: 10},
+	)
+	var done map[string]any
+	if err := json.Unmarshal(finished, &done); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if done["Played"] != true {
+		t.Errorf("a fully watched series did not report as played: %v", done)
+	}
+	if count, ok := done["UnplayedItemCount"].(float64); !ok || count != 0 {
+		t.Errorf("unplayed on a finished series = %v, want 0", done["UnplayedItemCount"])
+	}
+}
+
+// "Nothing left to watch" and "I cannot say how much there is" are different answers, and
+// only one of them is true for a library the catalogue has not imported yet. Ticking every
+// show in the house is the worst thing this could do.
+func TestViewerAggregateUserDataSaysNothingItCannotCount(t *testing.T) {
+	raw := viewerAggregateUserData(store.ViewerState{}, store.ViewerAggregate{})
+	var fields map[string]any
+	if err := json.Unmarshal(raw, &fields); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if _, ok := fields["UnplayedItemCount"]; ok {
+		t.Error("a count was claimed for a series the catalogue cannot count")
+	}
+	if _, ok := fields["PlayedPercentage"]; ok {
+		t.Error("a percentage was claimed with nothing to divide by")
+	}
+	if _, ok := fields["LastPlayedDate"]; ok {
+		t.Error("a play date was claimed for a series nobody has watched")
+	}
+	if fields["Played"] != false {
+		t.Errorf("an uncountable series reported as watched: %v", fields)
+	}
+}
+
+// A season is looked up by its own id, and its series is asked for alongside it, because
+// the catalogue's indexed column is the series. Getting that wrong costs the season card
+// its count on exactly the page — a series detail page — where seasons appear.
+func TestContainerIDsCollectSeriesAndSeasons(t *testing.T) {
+	items := []json.RawMessage{
+		json.RawMessage(`{"Id":"ep-1","Type":"Episode","SeriesId":"show-1"}`),
+		json.RawMessage(`{"Id":"show-1","Type":"Series"}`),
+		json.RawMessage(`{"Id":"season-2","Type":"Season","SeriesId":"show-2"}`),
+		json.RawMessage(`{"Id":"season-2","Type":"Season","SeriesId":"show-2"}`),
+		json.RawMessage(`{"Id":"film-1","Type":"Movie"}`),
+	}
+	seriesIDs, seasonIDs := containerIDsIn([][]json.RawMessage{items})
+
+	if !equalStrings(seasonIDs, []string{"season-2"}) {
+		t.Errorf("seasons = %v, want one season and no repeat", seasonIDs)
+	}
+	// show-2 is there because the season named it; show-1 because it is a card in its own
+	// right. Neither the episode nor the film contributes a container.
+	if !equalStrings(seriesIDs, []string{"show-1", "show-2"}) {
+		t.Errorf("series = %v, want the series card and the season's parent", seriesIDs)
+	}
+}
+
+// Switched off, an account looks like one nobody has added anybody to — which is how the
+// television decides not to offer the picker. It must never look like an account whose
+// list failed to load.
+func TestMainViewerOnlyLeavesTheAccount(t *testing.T) {
+	viewers := []store.Viewer{
+		{ID: "emby-user-1", Name: "Matt", Kind: store.ViewerMain},
+		{ID: "v01", Name: "Alessandra", Kind: store.ViewerShadow},
+		{ID: "v02", Name: "Guest", Kind: store.ViewerShadow},
+	}
+	got := mainViewerOnly(viewers)
+	if len(got) != 1 || !got[0].IsMain() || got[0].ID != "emby-user-1" {
+		t.Fatalf("switched-off list = %+v, want the account alone", got)
+	}
+	if mainViewerOnly(nil) != nil {
+		t.Error("a list with no main viewer invented one")
+	}
+}
+
+// The switch is the operator's and rides the ordinary feature machinery, so what is worth
+// pinning is that it is *in* the catalogue and gated on a capability — a household half of
+// whose televisions cannot choose between people must not be offered it.
+func TestViewersIsAnOperatorFeature(t *testing.T) {
+	definition, ok := knownFeature(featureViewers)
+	if !ok {
+		t.Fatal("viewers is not in the feature catalogue")
+	}
+	if definition.Capability != "viewers_v1" {
+		t.Errorf("capability = %q, want viewers_v1", definition.Capability)
+	}
+	// Off by default, and deliberately so: this is the switch deciding where a household's
+	// watched state is written, and a feature that arrives already on is one every server
+	// running this build starts using before anybody decided to.
+	if definition.DefaultEnabled {
+		t.Error("viewers defaults on; it is opted into rather than out of")
+	}
+}