))}
@@ -46,4 +80,13 @@ function SeasonSkeleton() {
);
}
+/** One line of text in the type its parent or `className` sets. */
+function Line({ className, width }: { className?: string; width: string }) {
+ return (
+
+ );
+}
+
export { SeasonSkeleton };
diff --git a/components/show/show-detail-skeleton.tsx b/components/show/show-detail-skeleton.tsx
index 03fb181..b654a5d 100644
--- a/components/show/show-detail-skeleton.tsx
+++ b/components/show/show-detail-skeleton.tsx
@@ -2,9 +2,10 @@ import {
CastRowSkeleton,
DetailHeroSkeleton,
OverviewSkeleton,
+ SectionHeadingSkeleton,
} from "@/components/catalog/detail-skeletons";
import { PosterGrid } from "@/components/poster-grid";
-import { PosterCardSkeleton, Skeleton } from "@/components/skeleton";
+import { PosterCardSkeleton } from "@/components/skeleton";
/**
* The show page while TMDB answers (spec 0009, AC-17): the hero, the
@@ -18,18 +19,18 @@ function ShowDetailSkeleton() {
-
+
- {Array.from({ length: 6 }, (_, index) => (
+ {SEASON_CARD_VISIBILITY.map((visibility, index) => (
-
+
))}
@@ -41,22 +42,15 @@ function ShowDetailSkeleton() {
/**
* Cards past the column count at each width are hidden, so the placeholder
- * row never wraps: 2 at base, 3 at `sm`, 4 at `md`, 5 at `lg`, 6 at `xl`.
+ * row never wraps: 2 below `md`, 4 from it.
*/
-const SEASON_CARD_VISIBILITY = [
- "",
- "",
- "hidden sm:block",
- "hidden md:block",
- "hidden lg:block",
- "hidden xl:block",
-];
+const SEASON_CARD_VISIBILITY = ["", "", "hidden md:block", "hidden md:block"];
/** The cast heading and row, also the fallback of the cast's own boundary. */
function CastSectionSkeleton() {
return (
-
+
);
diff --git a/components/skeleton.test.tsx b/components/skeleton.test.tsx
index cd30a9e..903aa37 100644
--- a/components/skeleton.test.tsx
+++ b/components/skeleton.test.tsx
@@ -84,6 +84,31 @@ describe("PosterCardSkeleton", () => {
expect(container.querySelectorAll("[data-slot=skeleton]")).toHaveLength(2);
});
+ it("reserves one line of the caption's own type, not a bare bar", () => {
+ const { container } = render(
);
+ const { container: loaded } = render(
+
,
+ );
+
+ const line = container.querySelector(
+ "[data-slot=skeleton]:not(.aspect-2\\/3)",
+ );
+ expect(line?.parentElement).toHaveClass(
+ "h-[1lh]",
+ "text-sm",
+ "leading-snug",
+ );
+ expect(loaded.querySelector("h3")).toHaveClass("text-sm", "leading-snug");
+ });
+
+ it("adds the meta line only when asked, as on a season card", () => {
+ const { container: plain } = render(
);
+ const { container: withMeta } = render(
);
+
+ expect(plain.querySelectorAll("[data-slot=skeleton]")).toHaveLength(2);
+ expect(withMeta.querySelectorAll("[data-slot=skeleton]")).toHaveLength(3);
+ });
+
it("announces nothing at all while it is standing in", () => {
const { container } = render(
);
diff --git a/components/skeleton.tsx b/components/skeleton.tsx
index 7584b65..027a4f3 100644
--- a/components/skeleton.tsx
+++ b/components/skeleton.tsx
@@ -52,13 +52,38 @@ function Skeleton({
* The loading shape of one `PosterCard`, kept beside the card's real layout so
* the two cannot drift apart.
*/
-function PosterCardSkeleton() {
+function PosterCardSkeleton({ meta = false }: { meta?: boolean }) {
return (
-
+ {/*
+ * One line of the caption's own type tall (`h-[1lh]`), not a bare 16px
+ * bar: a 20 card grid of 16px stand ins grows by a row's worth when the
+ * 19px captions arrive. `meta` adds the season card's second line.
+ */}
+
+
+
+ {meta ? (
+
+
+
+ ) : null}
);
}
-export { PosterCardSkeleton, Skeleton };
+/**
+ * The stand in for `PaginationLinks` under a paged grid while it streams: one
+ * pill at the links' height (the 44px `touch` size, 36px from `md`), so the
+ * page does not grow by a row when the links arrive.
+ */
+function PaginationSkeleton() {
+ return (
+
+
+
+ );
+}
+
+export { PaginationSkeleton, PosterCardSkeleton, Skeleton };
diff --git a/components/tracking/card-bookmark.tsx b/components/tracking/card-bookmark.tsx
deleted file mode 100644
index 12f08c3..0000000
--- a/components/tracking/card-bookmark.tsx
+++ /dev/null
@@ -1,50 +0,0 @@
-import {
- getWatchlistedMovieIds,
- movieIdsKey,
-} from "@/lib/tracking/movie-state";
-
-import { CardBookmarkButton } from "./card-bookmark-button";
-
-/**
- * The bookmark in a `/movies` grid card, for a signed in user (spec 0007,
- * AC-16).
- *
- * Every card on the grid passes the same ids, so every card calls
- * `getWatchlistedMovieIds` with the same key, which React `cache()` collapses
- * into one Supabase read per render. Each card is
- * still its own Suspense boundary, so the posters never wait on the session.
- *
- * A visitor and a failed read both render nothing: the grid is catalog first,
- * and a missing bookmark is quieter than an error on twenty cards (AC-2,
- * AC-17). The failure is logged inside the read.
- *
- * @param movieId The card's movie.
- * @param title The TMDB title, for the accessible name.
- * @param gridMovieIds Every movie id on the grid, the same array for each card.
- * @param returnPath The grid page, for the session expired toast.
- */
-async function CardBookmark({
- movieId,
- title,
- gridMovieIds,
- returnPath,
-}: {
- movieId: number;
- title: string;
- gridMovieIds: readonly number[];
- returnPath: string;
-}) {
- const result = await getWatchlistedMovieIds(movieIdsKey(gridMovieIds));
- if (result.kind !== "ok") return null;
-
- return (
-
- );
-}
-
-export { CardBookmark };
diff --git a/components/tracking/card-rating-badge.tsx b/components/tracking/card-rating-badge.tsx
new file mode 100644
index 0000000..1ccf733
--- /dev/null
+++ b/components/tracking/card-rating-badge.tsx
@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+
+import { TmdbRatingBadge } from "@/components/rating-badges";
+import type { LibraryList } from "@/lib/catalog/library-list";
+
+/**
+ * The top right badge of a catalog poster card, shared by movies and shows
+ * (prompts/catalog-card-status.md, R1 to R5): the user's own rating when the
+ * title is on Watched with one, nothing on Upcoming, where the date pill
+ * speaks instead, and the TMDB rating otherwise. One rule for both media
+ * types, so the two grids cannot drift apart.
+ *
+ * @param page The library page the title sits on, or undefined when none.
+ * @param personal The personal badge, or null when there is no rating.
+ * @param tmdbRating The card's TMDB rating.
+ */
+function CardRatingBadge({
+ page,
+ personal,
+ tmdbRating,
+}: {
+ page: LibraryList | undefined;
+ personal: ReactNode;
+ tmdbRating: number | null;
+}) {
+ if (page === "watched" && personal !== null) return personal;
+ if (page === "upcoming") return null;
+ return
;
+}
+
+export { CardRatingBadge };
diff --git a/components/tracking/card-watched-button.test.tsx b/components/tracking/card-watched-button.test.tsx
new file mode 100644
index 0000000..66fdc0c
--- /dev/null
+++ b/components/tracking/card-watched-button.test.tsx
@@ -0,0 +1,88 @@
+import { act, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * covers: prompts/catalog-card-status.md, R3
+ */
+let settle: (value: unknown) => void = () => {};
+const setMovieWatched = vi.fn(
+ (..._args: unknown[]) =>
+ new Promise((resolve) => {
+ settle = resolve;
+ }),
+);
+const restoreMovieWatched = vi.fn(async (..._args: unknown[]) => ({
+ ok: true,
+}));
+vi.mock("@/app/movies/actions", () => ({
+ setMovieWatched: (...args: unknown[]) => setMovieWatched(...args),
+ restoreMovieWatched: (...args: unknown[]) => restoreMovieWatched(...args),
+}));
+vi.mock("next/navigation", () => ({ useRouter: () => ({ push: vi.fn() }) }));
+const toast = vi.fn();
+vi.mock("sonner", () => ({
+ toast: Object.assign((...args: unknown[]) => toast(...args), {
+ dismiss: vi.fn(),
+ }),
+}));
+
+const { CardWatchedButton } = await import("./card-watched-button");
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+function renderButton() {
+ render(
+
,
+ );
+ return screen.getByRole("button", { name: "Unmark Fight Club as watched" });
+}
+
+describe("CardWatchedButton", () => {
+ it("is the Watched page's round button with a 44px mobile target", () => {
+ expect(renderButton()).toHaveClass("size-11", "md:size-9");
+ });
+
+ it("unmarks the movie and offers the Undo that restores its mark and score", async () => {
+ const user = userEvent.setup();
+ const button = renderButton();
+ await user.click(button);
+ expect(setMovieWatched).toHaveBeenCalledWith(550, false);
+ expect(button).toBeDisabled();
+
+ const watchedAt = "2026-09-23T12:00:00Z";
+ await act(async () =>
+ settle({ ok: true, cleared: { watchedAt, rating: 8 } }),
+ );
+ const [message, options] = toast.mock.calls.at(-1) ?? [];
+ expect(message).toBe("Score removed too.");
+ await act(async () => options.action.onClick({ preventDefault: () => {} }));
+ expect(restoreMovieWatched).toHaveBeenCalledWith(550, watchedAt, 8);
+ });
+
+ it("shows no toast when no score went with the mark", async () => {
+ const user = userEvent.setup();
+ await user.click(renderButton());
+ await act(async () =>
+ settle({
+ ok: true,
+ cleared: { watchedAt: "2026-09-23T12:00:00Z", rating: null },
+ }),
+ );
+ expect(toast).not.toHaveBeenCalled();
+ });
+
+ it("rolls back and says so on a refusal", async () => {
+ const user = userEvent.setup();
+ const button = renderButton();
+ await user.click(button);
+ await act(async () => settle({ ok: false, error: "write_failed" }));
+ await waitFor(() => expect(button).toBeEnabled());
+ expect(toast).toHaveBeenCalledWith(
+ "Couldn't save that change. Try again.",
+ expect.objectContaining({ id: "movie-tracking-550-watched" }),
+ );
+ });
+});
diff --git a/components/tracking/card-watched-button.tsx b/components/tracking/card-watched-button.tsx
new file mode 100644
index 0000000..296a9bb
--- /dev/null
+++ b/components/tracking/card-watched-button.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { startTransition, useOptimistic } from "react";
+
+import { setMovieWatched } from "@/app/movies/actions";
+
+import { CardRoundButton } from "./card-round-button";
+import { WatchedIcon } from "./tracking-icons";
+import { settleResultCall, showTrackingError } from "./tracking-toast";
+import { useMovieClearedUndo } from "./use-movie-cleared-undo";
+
+/**
+ * The filled watched mark on a catalog poster card for a watched movie
+ * (prompts/catalog-card-status.md), the Watched page's button on `/movies`
+ * and `/search`.
+ *
+ * It only unmarks: a movie is marked watched on its own page. Unmarking also
+ * removes the score, so the movie page's toast and Undo follow
+ * (prompts/movie-plan-watched-exclusive.md). The action's `refresh()` then
+ * re-renders the card, which falls back to the TMDB rating and the Plan
+ * bookmark; until then the mark shows empty, and a failure rolls it back.
+ */
+function CardWatchedButton({
+ movieId,
+ title,
+ returnPath,
+}: {
+ movieId: number;
+ title: string;
+ returnPath: string;
+}) {
+ const router = useRouter();
+ const [watched, setWatched] = useOptimistic(true);
+ const showCleared = useMovieClearedUndo({ movieId, returnPath });
+
+ function unmark() {
+ startTransition(async () => {
+ setWatched(false);
+ const result = await settleResultCall(() =>
+ setMovieWatched(movieId, false),
+ );
+ if (!result.ok) {
+ showTrackingError(result.error, {
+ movieId,
+ control: "watched",
+ returnPath,
+ navigate: router.push,
+ });
+ return;
+ }
+ showCleared("unwatched", result.cleared);
+ });
+ }
+
+ return (
+
+
+
+ );
+}
+
+export { CardWatchedButton };
diff --git a/components/tracking/movie-card-slots.test.tsx b/components/tracking/movie-card-slots.test.tsx
new file mode 100644
index 0000000..57317c3
--- /dev/null
+++ b/components/tracking/movie-card-slots.test.tsx
@@ -0,0 +1,132 @@
+import { render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { MovieTrackingState } from "@/lib/tracking/types";
+
+/**
+ * covers: spec 0007, AC-2, AC-16, AC-17; prompts/catalog-card-status.md, R1
+ * to R4
+ *
+ * The two slots of a movie poster card show the movie the way its library
+ * page does. The grid read is the boundary, so it is what is replaced.
+ */
+const getMovieGridStates = vi.fn();
+vi.mock("@/lib/tracking/movie-state", () => ({
+ getMovieGridStates: (...args: unknown[]) => getMovieGridStates(...args),
+ movieIdsKey: (ids: number[]) => [...ids].sort((a, b) => a - b).join(","),
+}));
+vi.mock("@/lib/tracking/episode-state", () => ({
+ requestTodayUtc: () => "2026-10-10",
+}));
+vi.mock("@/app/movies/actions", () => ({}));
+vi.mock("next/navigation", () => ({ useRouter: () => ({ push: vi.fn() }) }));
+vi.mock("sonner", () => ({ toast: vi.fn() }));
+
+const { MovieCardBadge, MovieCardControls } = await import(
+ "./movie-card-slots"
+);
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe("MovieCardBadge and MovieCardControls", () => {
+ const props = {
+ movieId: 550,
+ title: "Fight Club",
+ releaseDate: "1999-10-15" as string | null,
+ gridMovieIds: [603, 550],
+ returnPath: "/movies",
+ };
+ const none: MovieTrackingState = {
+ inWatchlist: false,
+ watched: false,
+ rating: null,
+ };
+
+ function grid(state?: typeof none) {
+ getMovieGridStates.mockResolvedValue({
+ kind: "ok",
+ state: new Map(state ? [[550, state]] : []),
+ });
+ }
+
+ async function renderCard(overrides: Partial
= {}) {
+ const card = { ...props, ...overrides };
+ return render(
+ <>
+ {await MovieCardBadge({ ...card, tmdbRating: 8.4 })}
+ {await MovieCardControls(card)}
+ ,
+ );
+ }
+
+ it("asks for the whole grid under one shared key (AC-16)", async () => {
+ grid({ ...none, inWatchlist: true });
+ await renderCard();
+ expect(getMovieGridStates).toHaveBeenCalledWith("550,603");
+ expect(
+ screen.getByRole("button", { name: "Plan Fight Club" }),
+ ).toHaveAttribute("aria-pressed", "true");
+ expect(screen.getByText("TMDB rating")).toBeInTheDocument();
+ });
+
+ it("shows an untouched movie as the catalog does", async () => {
+ grid();
+ await renderCard();
+ expect(
+ screen.getByRole("button", { name: "Plan Fight Club" }),
+ ).toHaveAttribute("aria-pressed", "false");
+ expect(screen.getByText("TMDB rating")).toBeInTheDocument();
+ });
+
+ it("shows a scored watched movie as Watched does: the score and the watched mark", async () => {
+ grid({ ...none, watched: true, rating: 7 });
+ await renderCard();
+ expect(screen.getByText("Your score")).toBeInTheDocument();
+ expect(screen.queryByText("TMDB rating")).not.toBeInTheDocument();
+ expect(
+ screen.getByRole("button", { name: "Unmark Fight Club as watched" }),
+ ).toBeInTheDocument();
+ expect(
+ screen.queryByRole("button", { name: "Plan Fight Club" }),
+ ).not.toBeInTheDocument();
+ });
+
+ it("keeps the TMDB rating on an unscored watched movie", async () => {
+ grid({ ...none, watched: true });
+ await renderCard();
+ expect(screen.getByText("TMDB rating")).toBeInTheDocument();
+ expect(
+ screen.getByRole("button", { name: "Unmark Fight Club as watched" }),
+ ).toBeInTheDocument();
+ });
+
+ it("shows a planned unreleased movie as Upcoming does: the date and no rating", async () => {
+ grid({ ...none, inWatchlist: true });
+ await renderCard({ releaseDate: "2026-11-20" });
+ expect(screen.getByText("Releases Nov 20, 2026")).toBeInTheDocument();
+ expect(screen.queryByText("TMDB rating")).not.toBeInTheDocument();
+ expect(
+ screen.getByRole("button", { name: "Plan Fight Club" }),
+ ).toHaveAttribute("aria-pressed", "true");
+ });
+
+ it("shows Date TBA for a planned undated movie", async () => {
+ grid({ ...none, inWatchlist: true });
+ await renderCard({ releaseDate: null });
+ expect(
+ screen.getByText("Release date to be announced"),
+ ).toBeInTheDocument();
+ });
+
+ it.each([
+ ["a visitor", { kind: "signed_out" }],
+ ["a failed read", { kind: "failed" }],
+ ])("gives %s the catalog card (AC-2, AC-17)", async (_, read) => {
+ getMovieGridStates.mockResolvedValue(read);
+ await renderCard();
+ expect(screen.getByText("TMDB rating")).toBeInTheDocument();
+ expect(screen.queryByRole("button")).not.toBeInTheDocument();
+ });
+});
diff --git a/components/tracking/movie-card-slots.tsx b/components/tracking/movie-card-slots.tsx
new file mode 100644
index 0000000..98733bc
--- /dev/null
+++ b/components/tracking/movie-card-slots.tsx
@@ -0,0 +1,116 @@
+/**
+ * The two personal slots of a movie poster card on `/movies` and `/search`
+ * (spec 0007, AC-16; prompts/catalog-card-status.md): each card shows the
+ * movie the way the library page it sits on does.
+ *
+ * Every slot on the grid passes the same ids, so `getMovieGridStates` runs
+ * once per render for the whole grid. Each slot is still its own Suspense
+ * boundary, so the posters never wait on the session. A visitor and a failed
+ * read get the catalog card: the grid is catalog first, and a missing status
+ * is quieter than an error on twenty cards (AC-2, AC-17). The failure is
+ * logged inside the read.
+ */
+import { ReleasePill } from "@/components/library/dated-pill";
+import { PersonalScoreBadge } from "@/components/rating-badges";
+import { movieCardStatus } from "@/lib/catalog/movie-page";
+import { formatReleaseDate } from "@/lib/format";
+import { requestTodayUtc } from "@/lib/tracking/episode-state";
+import { getMovieGridStates, movieIdsKey } from "@/lib/tracking/movie-state";
+
+import { CardBookmarkButton } from "./card-bookmark-button";
+import { CardRatingBadge } from "./card-rating-badge";
+import { CardWatchedButton } from "./card-watched-button";
+
+type MovieCardProps = {
+ movieId: number;
+ /** The TMDB release date already on the card. */
+ releaseDate: string | null;
+ /** Every movie id on the grid, the same array for each card. */
+ gridMovieIds: readonly number[];
+};
+
+/** The card's status, or undefined for a visitor or a failed read. */
+async function readStatus({
+ movieId,
+ releaseDate,
+ gridMovieIds,
+}: MovieCardProps) {
+ const result = await getMovieGridStates(movieIdsKey(gridMovieIds));
+ if (result.kind !== "ok") return undefined;
+ const state = result.state.get(movieId);
+ return {
+ state,
+ status: movieCardStatus(state, releaseDate, requestTodayUtc()),
+ };
+}
+
+/**
+ * The top right badge. The page renders the TMDB rating as the fallback, so
+ * only the user's own titles swap: the cyan score on a scored watched movie,
+ * nothing on an Upcoming one, the TMDB rating otherwise.
+ *
+ * @param tmdbRating The card's TMDB rating.
+ */
+async function MovieCardBadge({
+ tmdbRating,
+ ...props
+}: MovieCardProps & { tmdbRating: number | null }) {
+ const status = (await readStatus(props))?.status;
+ return (
+
+ ) : null
+ }
+ tmdbRating={tmdbRating}
+ />
+ );
+}
+
+/**
+ * The bottom row: the filled watched mark on a watched movie, the release
+ * pill and the Planned bookmark on an Upcoming one, and the plan bookmark
+ * otherwise. Nothing for a visitor or a failed read.
+ *
+ * @param title The TMDB title, for the accessible names.
+ * @param returnPath The grid page, for the session expired toast.
+ */
+async function MovieCardControls({
+ title,
+ returnPath,
+ ...props
+}: MovieCardProps & { title: string; returnPath: string }) {
+ const read = await readStatus(props);
+ if (read === undefined) return null;
+ const { state, status } = read;
+
+ if (status?.page === "watched") {
+ return (
+
+ );
+ }
+
+ return (
+ <>
+ {status?.page === "upcoming" && (
+
+ )}
+
+
+ );
+}
+
+export { MovieCardBadge, MovieCardControls };
diff --git a/components/tracking/show-card-bookmark.tsx b/components/tracking/show-card-bookmark.tsx
deleted file mode 100644
index 3ea2151..0000000
--- a/components/tracking/show-card-bookmark.tsx
+++ /dev/null
@@ -1,44 +0,0 @@
-import { getTrackedShows, showIdsKey } from "@/lib/tracking/show-state";
-
-import { ShowCardBookmarkButton } from "./show-card-bookmark-button";
-
-/**
- * The TV bookmark on a `/shows` card or a `/search` TV result, for a signed in
- * user (spec 0020, AC-6), the `CardBookmark` pattern.
- *
- * Every card on the grid passes the same ids, so `getTrackedShows` runs once
- * per render for the whole grid. The bookmark is filled for a tracked show
- * and empty otherwise. A visitor and a failed read render
- * nothing, and each card is its own Suspense boundary, so the posters never
- * wait on the session.
- *
- * @param showId The card's show.
- * @param name The TMDB name, for the accessible name and the toasts.
- * @param gridShowIds Every show id on the grid, the same array for each card.
- * @param returnPath The grid page, for the session expired toast.
- */
-async function ShowCardBookmark({
- showId,
- name,
- gridShowIds,
- returnPath,
-}: {
- showId: number;
- name: string;
- gridShowIds: readonly number[];
- returnPath: string;
-}) {
- const result = await getTrackedShows(showIdsKey(gridShowIds));
- if (result.kind !== "ok") return null;
-
- return (
-
- );
-}
-
-export { ShowCardBookmark };
diff --git a/components/tracking/show-card-slots.test.tsx b/components/tracking/show-card-slots.test.tsx
new file mode 100644
index 0000000..44d5c0f
--- /dev/null
+++ b/components/tracking/show-card-slots.test.tsx
@@ -0,0 +1,132 @@
+import { render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * covers: spec 0020, AC-6; prompts/catalog-card-status.md, R5, R7
+ *
+ * The grid read is the boundary, so it is what is replaced.
+ */
+const getShowGridStatus = vi.fn();
+vi.mock("@/lib/tracking/show-grid-status", () => ({
+ getShowGridStatus: (...args: unknown[]) => getShowGridStatus(...args),
+}));
+vi.mock("@/lib/tracking/show-state", () => ({
+ showIdsKey: (ids: number[]) => [...ids].sort((a, b) => a - b).join(","),
+}));
+vi.mock("@/lib/tracking/episode-state", () => ({
+ requestTodayUtc: () => "2026-10-10",
+}));
+vi.mock("@/app/shows/actions", () => ({}));
+vi.mock("next/navigation", () => ({ useRouter: () => ({ push: vi.fn() }) }));
+vi.mock("sonner", () => ({ toast: vi.fn() }));
+
+const { ShowCardBadge, ShowCardControls, ShowCardMeta } = await import(
+ "./show-card-slots"
+);
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+const props = { showId: 1399, gridShowIds: [1400, 1399] };
+
+function grid(status?: unknown) {
+ getShowGridStatus.mockResolvedValue({
+ kind: "ok",
+ state: new Map(status === undefined ? [] : [[1399, status]]),
+ });
+}
+
+async function renderCard(base: string | null = null) {
+ return render(
+ <>
+ {await ShowCardBadge({ ...props, tmdbRating: 8.4 })}
+ {await ShowCardMeta({ ...props, base })}
+ {
+ await ShowCardControls({
+ ...props,
+ name: "Game of Thrones",
+ returnPath: "/shows",
+ })
+ }
+ ,
+ );
+}
+
+function trackedBookmark() {
+ return screen.getByRole("button", { name: "Stop tracking Game of Thrones" });
+}
+
+describe("show card slots", () => {
+ it("asks for the whole grid under one shared key (AC-6)", async () => {
+ grid();
+ await renderCard();
+ expect(getShowGridStatus).toHaveBeenCalledWith("1399,1400");
+ });
+
+ it("shows an untracked show as the catalog does", async () => {
+ grid();
+ await renderCard("2011");
+ expect(screen.getByText("TMDB rating")).toBeInTheDocument();
+ expect(screen.getByTestId("meta")).toHaveTextContent(/^2011$/);
+ expect(
+ screen.getByRole("button", { name: "Track Game of Thrones" }),
+ ).toBeInTheDocument();
+ });
+
+ it("keeps a tracked show on Watchlist as it is today", async () => {
+ grid({ page: "watchlist", next: { season: 2, episode: 3 }, rating: null });
+ await renderCard();
+ expect(screen.getByText("TMDB rating")).toBeInTheDocument();
+ expect(screen.getByTestId("meta")).toBeEmptyDOMElement();
+ expect(trackedBookmark()).toBeInTheDocument();
+ });
+
+ it("shows a show on Upcoming with its next episode date and no rating", async () => {
+ grid({
+ page: "upcoming",
+ airDate: "2026-10-20",
+ next: { season: 2, episode: 1 },
+ rating: null,
+ });
+ await renderCard();
+ expect(screen.getByText("S2E1 · Oct 20")).toBeInTheDocument();
+ expect(screen.queryByText("TMDB rating")).not.toBeInTheDocument();
+ expect(trackedBookmark()).toBeInTheDocument();
+ });
+
+ it("shows a rated finished show with its show rating and label", async () => {
+ grid({ page: "watched", label: "finished", rating: 7.25 });
+ await renderCard("2011");
+ expect(screen.getByText("Your show rating")).toBeInTheDocument();
+ expect(screen.queryByText("TMDB rating")).not.toBeInTheDocument();
+ expect(screen.getByTestId("meta")).toHaveTextContent("2011 · Finished");
+ expect(trackedBookmark()).toBeInTheDocument();
+ });
+
+ it("keeps the TMDB rating on an unrated caught up show", async () => {
+ grid({ page: "watched", label: "caught_up", rating: null });
+ await renderCard();
+ expect(screen.getByText("TMDB rating")).toBeInTheDocument();
+ expect(screen.getByTestId("meta")).toHaveTextContent(/^Caught up$/);
+ });
+
+ it("leaves a tracked show whose page is unknown a plain tracked card", async () => {
+ grid(null);
+ await renderCard("2011");
+ expect(screen.getByText("TMDB rating")).toBeInTheDocument();
+ expect(screen.getByTestId("meta")).toHaveTextContent(/^2011$/);
+ expect(trackedBookmark()).toBeInTheDocument();
+ });
+
+ it.each([
+ ["a visitor", { kind: "signed_out" }],
+ ["a failed read", { kind: "failed" }],
+ ])("gives %s the catalog card", async (_, read) => {
+ getShowGridStatus.mockResolvedValue(read);
+ await renderCard("2011");
+ expect(screen.getByText("TMDB rating")).toBeInTheDocument();
+ expect(screen.getByTestId("meta")).toHaveTextContent(/^2011$/);
+ expect(screen.queryByRole("button")).not.toBeInTheDocument();
+ });
+});
diff --git a/components/tracking/show-card-slots.tsx b/components/tracking/show-card-slots.tsx
new file mode 100644
index 0000000..d53f339
--- /dev/null
+++ b/components/tracking/show-card-slots.tsx
@@ -0,0 +1,119 @@
+/**
+ * The three personal slots of a TV poster card on `/shows` and `/search`
+ * (spec 0020, AC-6; prompts/catalog-card-status.md): a tracked show carries
+ * what its library page shows, and keeps the bookmark that stops tracking.
+ *
+ * Every slot on the grid passes the same ids, so `getShowGridStatus` runs
+ * once per render for the whole grid, and each slot is its own Suspense
+ * boundary, so the posters never wait on the session. A visitor and a failed
+ * read get the catalog card.
+ */
+import { UpcomingShowPill } from "@/components/library/show-cards";
+import { CalculatedRatingBadge } from "@/components/rating-badges";
+import { requestTodayUtc } from "@/lib/tracking/episode-state";
+import { WATCHED_SHOW_LABELS } from "@/lib/tracking/messages";
+import { getShowGridStatus } from "@/lib/tracking/show-grid-status";
+import { showIdsKey } from "@/lib/tracking/show-state";
+
+import { CardRatingBadge } from "./card-rating-badge";
+import { ShowCardBookmarkButton } from "./show-card-bookmark-button";
+
+type ShowCardProps = {
+ showId: number;
+ /** Every show id on the grid, the same array for each card. */
+ gridShowIds: readonly number[];
+};
+
+/**
+ * The grid's tracked shows mapped to their status, or undefined for a
+ * visitor or a failed read.
+ */
+async function readTrackedStatuses(gridShowIds: readonly number[]) {
+ const result = await getShowGridStatus(showIdsKey(gridShowIds));
+ return result.kind === "ok" ? result.state : undefined;
+}
+
+/**
+ * The top right badge. The page renders the TMDB rating as the fallback, so
+ * only tracked shows swap: the calculated show rating on a rated show on
+ * Watched, nothing on Upcoming, the TMDB rating otherwise.
+ *
+ * @param tmdbRating The card's TMDB rating.
+ */
+async function ShowCardBadge({
+ showId,
+ gridShowIds,
+ tmdbRating,
+}: ShowCardProps & { tmdbRating: number | null }) {
+ const status = (await readTrackedStatuses(gridShowIds))?.get(showId);
+ return (
+
+ ) : null
+ }
+ tmdbRating={tmdbRating}
+ />
+ );
+}
+
+/**
+ * The line under the name: Finished or Caught up for a show on Watched,
+ * after the catalog's own text (the year on `/search`) when there is one.
+ *
+ * @param base What the line shows today, and the Suspense fallback.
+ */
+async function ShowCardMeta({
+ showId,
+ gridShowIds,
+ base,
+}: ShowCardProps & { base: string | null }) {
+ const status = (await readTrackedStatuses(gridShowIds))?.get(showId);
+ if (status?.page !== "watched") return base;
+ const label = WATCHED_SHOW_LABELS[status.label];
+ return base === null ? label : `${base} · ${label}`;
+}
+
+/**
+ * The bottom row: the next episode's date pill or Date TBA on Upcoming, and
+ * the bookmark, filled for every tracked show. Nothing for a visitor or a
+ * failed read.
+ *
+ * @param name The TMDB name, for the accessible name and the toasts.
+ * @param returnPath The grid page, for the session expired toast.
+ */
+async function ShowCardControls({
+ showId,
+ gridShowIds,
+ name,
+ returnPath,
+}: ShowCardProps & { name: string; returnPath: string }) {
+ const grid = await readTrackedStatuses(gridShowIds);
+ if (grid === undefined) return null;
+ const status = grid.get(showId);
+
+ return (
+ <>
+ {status?.page === "upcoming" && (
+
+ )}
+
+
+ );
+}
+
+export { ShowCardBadge, ShowCardControls, ShowCardMeta };
diff --git a/components/tracking/tracking-slots.test.tsx b/components/tracking/tracking-slots.test.tsx
index 63b58f3..311fc4b 100644
--- a/components/tracking/tracking-slots.test.tsx
+++ b/components/tracking/tracking-slots.test.tsx
@@ -2,18 +2,14 @@ import { render, screen } from "@testing-library/react";
import { afterEach, describe, expect, it, vi } from "vitest";
/**
- * covers: spec 0007, AC-2, AC-16, AC-17
+ * covers: spec 0007, AC-2, AC-17
*
- * The two server slots decide between nothing, a failure line and the
+ * The server slot decides between nothing, a failure line and the
* controls. The reads are the boundary, so they are what is replaced.
*/
const getMovieTracking = vi.fn();
-const getWatchlistedMovieIds = vi.fn();
vi.mock("@/lib/tracking/movie-state", () => ({
getMovieTracking: (...args: unknown[]) => getMovieTracking(...args),
- getWatchlistedMovieIds: (...args: unknown[]) =>
- getWatchlistedMovieIds(...args),
- movieIdsKey: (ids: number[]) => [...ids].sort((a, b) => a - b).join(","),
}));
vi.mock("@/lib/tracking/episode-state", () => ({
requestTodayUtc: () => "2026-10-10",
@@ -23,7 +19,6 @@ vi.mock("next/navigation", () => ({ useRouter: () => ({ push: vi.fn() }) }));
vi.mock("sonner", () => ({ toast: vi.fn() }));
const { MovieTrackingSlot } = await import("./movie-tracking-slot");
-const { CardBookmark } = await import("./card-bookmark");
afterEach(() => {
vi.clearAllMocks();
@@ -100,33 +95,3 @@ describe("MovieTrackingSlot", () => {
).toBeInTheDocument();
});
});
-
-describe("CardBookmark", () => {
- const props = {
- movieId: 550,
- title: "Fight Club",
- gridMovieIds: [603, 550],
- returnPath: "/movies",
- };
-
- it("asks for the whole grid under one shared key (AC-16)", async () => {
- getWatchlistedMovieIds.mockResolvedValue({
- kind: "ok",
- state: new Set([550]),
- });
- render(await CardBookmark(props));
- expect(getWatchlistedMovieIds).toHaveBeenCalledWith("550,603");
- expect(
- screen.getByRole("button", { name: "Plan Fight Club" }),
- ).toHaveAttribute("aria-pressed", "true");
- });
-
- it.each([
- ["a visitor", { kind: "signed_out" }],
- ["a failed read", { kind: "failed" }],
- ])("renders nothing for %s (AC-2, AC-17)", async (_, read) => {
- getWatchlistedMovieIds.mockResolvedValue(read);
- const { container } = render(await CardBookmark(props));
- expect(container).toBeEmptyDOMElement();
- });
-});
diff --git a/lib/catalog/movie-page.test.ts b/lib/catalog/movie-page.test.ts
index fcb1b32..abe52fc 100644
--- a/lib/catalog/movie-page.test.ts
+++ b/lib/catalog/movie-page.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
import {
classifyMovie,
isMovieReleased,
+ movieCardStatus,
movieReleaseNote,
upcomingReleaseDate,
} from "./movie-page";
@@ -14,13 +15,13 @@ describe("classifyMovie (AC-13)", () => {
it("puts a released planned movie on Watchlist, release day included", () => {
expect(
classifyMovie(
- { releaseDate: "2026-01-01", inWatchlist: true, watchedAt: null },
+ { releaseDate: "2026-01-01", inWatchlist: true, watched: false },
today,
),
).toBe("watchlist");
expect(
classifyMovie(
- { releaseDate: today, inWatchlist: true, watchedAt: null },
+ { releaseDate: today, inWatchlist: true, watched: false },
today,
),
).toBe("watchlist");
@@ -29,7 +30,7 @@ describe("classifyMovie (AC-13)", () => {
it("puts a planned movie released after today on Upcoming", () => {
expect(
classifyMovie(
- { releaseDate: "2026-10-08", inWatchlist: true, watchedAt: null },
+ { releaseDate: "2026-10-08", inWatchlist: true, watched: false },
today,
),
).toBe("upcoming");
@@ -38,29 +39,28 @@ describe("classifyMovie (AC-13)", () => {
it("puts a planned movie with no date or a malformed one on Upcoming", () => {
expect(
classifyMovie(
- { releaseDate: null, inWatchlist: true, watchedAt: null },
+ { releaseDate: null, inWatchlist: true, watched: false },
today,
),
).toBe("upcoming");
expect(
classifyMovie(
- { releaseDate: "2026-02-30", inWatchlist: true, watchedAt: null },
+ { releaseDate: "2026-02-30", inWatchlist: true, watched: false },
today,
),
).toBe("upcoming");
});
it("puts a watched movie on Watched, planned or not (AC-14)", () => {
- const watchedAt = "2026-09-01T10:00:00Z";
expect(
classifyMovie(
- { releaseDate: "2026-01-01", inWatchlist: true, watchedAt },
+ { releaseDate: "2026-01-01", inWatchlist: true, watched: true },
today,
),
).toBe("watched");
expect(
classifyMovie(
- { releaseDate: "2026-01-01", inWatchlist: false, watchedAt },
+ { releaseDate: "2026-01-01", inWatchlist: false, watched: true },
today,
),
).toBe("watched");
@@ -69,7 +69,7 @@ describe("classifyMovie (AC-13)", () => {
it("puts an unplanned, unwatched movie on no page", () => {
expect(
classifyMovie(
- { releaseDate: "2026-01-01", inWatchlist: false, watchedAt: null },
+ { releaseDate: "2026-01-01", inWatchlist: false, watched: false },
today,
),
).toBeNull();
@@ -104,7 +104,7 @@ describe("isMovieReleased (release gate)", () => {
it("agrees with classifyMovie: markable exactly when on Watchlist (AC-6)", () => {
for (const releaseDate of [today, "2026-10-08", null, "2026-13-40"]) {
const page = classifyMovie(
- { releaseDate, inWatchlist: true, watchedAt: null },
+ { releaseDate, inWatchlist: true, watched: false },
today,
);
expect(page === "watchlist").toBe(isMovieReleased(releaseDate, today));
@@ -119,3 +119,46 @@ describe("movieReleaseNote (release gate)", () => {
expect(movieReleaseNote("2026-13-40")).toBe("Release date to be announced");
});
});
+
+describe("movieCardStatus (prompts/catalog-card-status.md)", () => {
+ const none = { inWatchlist: false, watched: false, rating: null };
+
+ it("is null with no row, or a row that is neither planned nor watched", () => {
+ expect(movieCardStatus(undefined, "2026-01-01", today)).toBeNull();
+ expect(movieCardStatus(none, "2026-01-01", today)).toBeNull();
+ });
+
+ it("carries the score on Watched, and null when unscored", () => {
+ expect(
+ movieCardStatus(
+ { ...none, watched: true, rating: 8 },
+ "2026-01-01",
+ today,
+ ),
+ ).toEqual({ page: "watched", rating: 8 });
+ expect(
+ movieCardStatus({ ...none, watched: true }, "2026-01-01", today),
+ ).toEqual({ page: "watched", rating: null });
+ });
+
+ it("puts a watched movie on Watched even before its release", () => {
+ expect(
+ movieCardStatus({ ...none, watched: true }, "2027-01-01", today),
+ ).toEqual({ page: "watched", rating: null });
+ });
+
+ it("places a planned movie by its release date, as the library does", () => {
+ const planned = { ...none, inWatchlist: true };
+ expect(movieCardStatus(planned, today, today)).toEqual({
+ page: "watchlist",
+ });
+ expect(movieCardStatus(planned, "2026-10-08", today)).toEqual({
+ page: "upcoming",
+ releaseDate: "2026-10-08",
+ });
+ expect(movieCardStatus(planned, null, today)).toEqual({
+ page: "upcoming",
+ releaseDate: null,
+ });
+ });
+});
diff --git a/lib/catalog/movie-page.ts b/lib/catalog/movie-page.ts
index 04c0185..7174589 100644
--- a/lib/catalog/movie-page.ts
+++ b/lib/catalog/movie-page.ts
@@ -1,6 +1,7 @@
import type { LibraryList } from "@/lib/catalog/library-list";
import { formatAirDate } from "@/lib/format";
import { UPCOMING_MESSAGES } from "@/lib/tracking/messages";
+import type { MovieTrackingState } from "@/lib/tracking/types";
import { airStatus } from "@/lib/tv/air-status";
/** The library pages a movie can sit on (spec 0020, AC-13). */
@@ -10,7 +11,7 @@ export type MoviePage = LibraryList;
export type MoviePlacement = {
releaseDate: string | null;
inWatchlist: boolean;
- watchedAt: string | null;
+ watched: boolean;
};
/**
@@ -30,7 +31,7 @@ export function classifyMovie(
movie: MoviePlacement,
today: string,
): MoviePage | null {
- if (movie.watchedAt !== null) return "watched";
+ if (movie.watched) return "watched";
if (!movie.inWatchlist) return null;
return isMovieReleased(movie.releaseDate, today) ? "watchlist" : "upcoming";
}
@@ -85,3 +86,40 @@ export function upcomingReleaseDate(
): string | null {
return airStatus(releaseDate, today) === "upcoming" ? releaseDate : null;
}
+
+/**
+ * What a catalog poster card shows of the user's own state for one movie
+ * (prompts/catalog-card-status.md): the library page the movie sits on, with
+ * what that page's card carries, or null when it sits on none.
+ *
+ * Placed by `classifyMovie` on the same request day, so a card on `/movies`
+ * or `/search` can never disagree with the library page it mirrors.
+ *
+ * @param state The stored state, or undefined when the user has no row.
+ * @param releaseDate The TMDB release date already on the card.
+ * @param today `requestTodayUtc()`, read once per request (AC-22).
+ */
+export function movieCardStatus(
+ state: MovieTrackingState | undefined,
+ releaseDate: string | null,
+ today: string,
+): MovieCardStatus | null {
+ if (state === undefined) return null;
+ const page = classifyMovie({ releaseDate, ...state }, today);
+ switch (page) {
+ case null:
+ return null;
+ case "watched":
+ return { page, rating: state.rating };
+ case "watchlist":
+ return { page };
+ case "upcoming":
+ return { page, releaseDate: upcomingReleaseDate(releaseDate, today) };
+ }
+}
+
+/** A movie card's library state, from `movieCardStatus`. */
+export type MovieCardStatus =
+ | { page: "watched"; rating: number | null }
+ | { page: "watchlist" }
+ | { page: "upcoming"; releaseDate: string | null };
diff --git a/lib/format.test.ts b/lib/format.test.ts
index 4519473..f4a1cbb 100644
--- a/lib/format.test.ts
+++ b/lib/format.test.ts
@@ -5,6 +5,7 @@ import {
formatAirSpan,
formatEpisodeCount,
formatPersonalScore,
+ formatReleaseDate,
formatRuntime,
formatShortDate,
formatVoteCount,
@@ -233,6 +234,23 @@ describe("formatShortDate · covers spec 0014 AC-5", () => {
});
});
+describe("formatReleaseDate · covers spec 0020 AC-13", () => {
+ it("gives the full date and the year aware short date", () => {
+ expect(formatReleaseDate("2027-02-03", "2026-09-28")).toEqual({
+ fullDate: "Feb 3, 2027",
+ shortDate: "Feb 3, 2027",
+ });
+ expect(formatReleaseDate("2026-12-25", "2026-09-28")).toEqual({
+ fullDate: "Dec 25, 2026",
+ shortDate: "Dec 25",
+ });
+ });
+
+ it("is null for Date TBA", () => {
+ expect(formatReleaseDate(null, "2026-09-28")).toBeNull();
+ });
+});
+
describe("parseTmdbDate · covers spec 0011 AC-3", () => {
it("is UTC midnight of the day TMDB wrote", () => {
expect(parseTmdbDate("2013-03-03")?.toISOString()).toBe(
diff --git a/lib/format.ts b/lib/format.ts
index 6ab3b30..face8c2 100644
--- a/lib/format.ts
+++ b/lib/format.ts
@@ -210,6 +210,33 @@ export function formatShortDate(
: AIR_DATE_FORMAT.format(utc);
}
+/**
+ * A movie's release date on an Upcoming card, formatted on the server beside
+ * the `today` that decided it (spec 0020, AC-13), or null for Date TBA.
+ */
+export type ReleaseDate = { shortDate: string; fullDate: string } | null;
+
+/**
+ * A movie's Upcoming release date in both pill forms (spec 0020, AC-13). The
+ * library Upcoming card and the catalog cards both format through it
+ * (prompts/catalog-card-status.md), so the two pills never disagree.
+ *
+ * @param releaseDate A date `upcomingReleaseDate` returned, or null.
+ * @param today `requestTodayUtc()`, for `formatShortDate`'s year rule.
+ * @returns Both forms, or null for Date TBA.
+ */
+export function formatReleaseDate(
+ releaseDate: string | null,
+ today: string,
+): ReleaseDate {
+ if (releaseDate === null) return null;
+ const fullDate = formatAirDate(releaseDate) ?? releaseDate;
+ return {
+ fullDate,
+ shortDate: formatShortDate(releaseDate, today) ?? fullDate,
+ };
+}
+
/**
* A TMDB calendar date as a UTC midnight `Date`, or null when it is missing,
* not `YYYY-MM-DD`, or not a real day.
diff --git a/lib/search/read.test.ts b/lib/search/read.test.ts
index 61d8c6b..cf2cea1 100644
--- a/lib/search/read.test.ts
+++ b/lib/search/read.test.ts
@@ -64,6 +64,7 @@ describe("fromMovie and fromShow", () => {
id: 438631,
title: "Dune",
year: 2021,
+ releaseDate: MOVIE.releaseDate,
posterUrl: "https://image.tmdb.org/t/p/w500/dune.jpg",
tmdbRating: 7.8,
tmdbVoteCount: 12000,
@@ -76,6 +77,7 @@ describe("fromMovie and fromShow", () => {
id: 90228,
title: "Dune: Prophecy",
year: 2024,
+ releaseDate: null,
posterUrl: null,
tmdbRating: null,
tmdbVoteCount: 3,
diff --git a/lib/search/read.ts b/lib/search/read.ts
index 90ae536..7665a99 100644
--- a/lib/search/read.ts
+++ b/lib/search/read.ts
@@ -24,6 +24,12 @@ export type SearchResult = {
id: number;
title: string;
year: number | null;
+ /**
+ * A movie's TMDB release date, which places a planned movie on Watchlist
+ * or Upcoming on its card (prompts/catalog-card-status.md). Null for a
+ * show: its card reads its own air dates.
+ */
+ releaseDate: string | null;
posterUrl: string | null;
tmdbRating: number | null;
tmdbVoteCount: number;
@@ -35,6 +41,7 @@ export function fromMovie(movie: MovieSummary): SearchResult {
id: movie.id,
title: movie.title,
year: movie.releaseYear,
+ releaseDate: movie.releaseDate,
posterUrl: movie.posterUrl,
tmdbRating: movie.tmdbRating,
tmdbVoteCount: movie.tmdbVoteCount,
@@ -47,6 +54,7 @@ export function fromShow(show: TvShowSummary): SearchResult {
id: show.id,
title: show.name,
year: show.firstAirYear,
+ releaseDate: null,
posterUrl: show.posterUrl,
tmdbRating: show.tmdbRating,
tmdbVoteCount: show.tmdbVoteCount,
diff --git a/lib/search/scan.test.ts b/lib/search/scan.test.ts
index 26ff321..161b697 100644
--- a/lib/search/scan.test.ts
+++ b/lib/search/scan.test.ts
@@ -17,6 +17,7 @@ function result(
id,
title: `Title ${id}`,
year: 2020,
+ releaseDate: "2020-05-01",
posterUrl: null,
tmdbRating: 8,
tmdbVoteCount: 500,
diff --git a/lib/tracking/library-lists.ts b/lib/tracking/library-lists.ts
index 3c6276b..8661157 100644
--- a/lib/tracking/library-lists.ts
+++ b/lib/tracking/library-lists.ts
@@ -396,9 +396,10 @@ function compareDesc(a: string, b: string): number {
* `getWatchedEpisodeIds` does, so a long history never loses rows to the
* response cap. The pages are read one at a time, also as that read does:
* every library tab runs this on each request, so a long history must not
- * open a connection per thousand episodes at once.
+ * open a connection per thousand episodes at once. The catalog grids read it
+ * too, for their tracked shows (prompts/catalog-card-status.md).
*/
-async function readWatchedRegular(
+export async function readWatchedRegular(
supabase: Awaited>,
userId: string,
showIds: readonly number[],
@@ -484,7 +485,7 @@ export async function getMovieLibraryTab(
read: getMoviesSettled,
place: (row, movie): MovieTabCard | null => {
const result = classifyMovie(
- { releaseDate: movie.releaseDate, inWatchlist: true, watchedAt: null },
+ { releaseDate: movie.releaseDate, inWatchlist: true, watched: false },
today,
);
if (result !== tab) return null;
diff --git a/lib/tracking/log.ts b/lib/tracking/log.ts
index c2b8560..9bdd6ae 100644
--- a/lib/tracking/log.ts
+++ b/lib/tracking/log.ts
@@ -34,6 +34,7 @@ export const TRACKING_EVENT = {
restoreShowTracking: "show_tracking.restore",
showTrackingRead: "show_tracking.read",
watchedEpisodesRead: "show_tracking.watched_read",
+ showGridRead: "show_tracking.grid_read",
} as const;
export type TrackingEvent =
diff --git a/lib/tracking/movie-state.test.ts b/lib/tracking/movie-state.test.ts
index b428d54..eed00d3 100644
--- a/lib/tracking/movie-state.test.ts
+++ b/lib/tracking/movie-state.test.ts
@@ -35,7 +35,7 @@ const createClient = vi.fn(async () => ({
}));
vi.mock("@/lib/supabase/server", () => ({ createClient }));
-const { getMovieTracking, getWatchlistedMovieIds, movieIdsKey } = await import(
+const { getMovieTracking, getMovieGridStates, movieIdsKey } = await import(
"./movie-state"
);
@@ -104,58 +104,64 @@ describe("getMovieTracking", () => {
});
});
-describe("getWatchlistedMovieIds", () => {
- it("reads the planned ids for the whole grid in one query (AC-16)", async () => {
- response = { data: [{ movie_id: 550 }], error: null };
- const result = await getWatchlistedMovieIds(movieIdsKey([603, 550, 550]));
- expect(result).toEqual({ kind: "ok", state: new Set([550]) });
+describe("getMovieGridStates", () => {
+ it("reads every grid movie's state in one query (AC-16)", async () => {
+ response = {
+ data: [
+ {
+ movie_id: 550,
+ in_watchlist: false,
+ watched_at: "2026-09-01T10:00:00Z",
+ rating: 8,
+ },
+ { movie_id: 603, in_watchlist: true, watched_at: null, rating: null },
+ ],
+ error: null,
+ };
+ const result = await getMovieGridStates(movieIdsKey([603, 550, 550]));
+ expect(result).toEqual({
+ kind: "ok",
+ state: new Map([
+ [550, { inWatchlist: false, watched: true, rating: 8 }],
+ [603, { inWatchlist: true, watched: false, rating: null }],
+ ]),
+ });
expect(calls).toContainEqual({
method: "in",
args: ["movie_id", [550, 603]],
});
- expect(calls).toContainEqual({
- method: "eq",
- args: ["in_watchlist", true],
- });
});
it("is signed out for a visitor (AC-2)", async () => {
getOptionalUser.mockResolvedValue(null);
- expect(await getWatchlistedMovieIds("550")).toEqual({ kind: "signed_out" });
+ expect(await getMovieGridStates("550")).toEqual({ kind: "signed_out" });
});
- it("returns an empty set with no query for an empty grid", async () => {
- expect(await getWatchlistedMovieIds("")).toEqual({
+ it("returns an empty map with no query for an empty grid", async () => {
+ expect(await getMovieGridStates("")).toEqual({
kind: "ok",
- state: new Set(),
+ state: new Map(),
});
expect(createClient).not.toHaveBeenCalled();
});
it("is signed out, with no session read, when the public env is missing (AC-2)", async () => {
vi.stubEnv("NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY", undefined);
- expect(await getWatchlistedMovieIds("550")).toEqual({
- kind: "signed_out",
- });
+ expect(await getMovieGridStates("550")).toEqual({ kind: "signed_out" });
expect(getOptionalUser).not.toHaveBeenCalled();
});
it("scopes the grid query to the session user (AC-18)", async () => {
response = { data: [], error: null };
- await getWatchlistedMovieIds("550,603");
+ await getMovieGridStates("550,603");
expect(calls).toContainEqual({ method: "eq", args: ["user_id", "user-a"] });
});
- it("logs a failed grid read with no identifiers (AC-17, AC-21)", async () => {
+ it("reports and logs a failed grid read with no identifiers (AC-17, AC-21)", async () => {
response = { data: null, error: { code: "PGRST000", message: "550" } };
- await getWatchlistedMovieIds("550,603");
+ expect(await getMovieGridStates("550,603")).toEqual({ kind: "failed" });
expect(warn).toHaveBeenCalledWith("movie_tracking.read refused db_error");
});
-
- it("reports a failed read (AC-17)", async () => {
- response = { data: null, error: { code: "PGRST000" } };
- expect(await getWatchlistedMovieIds("550,603")).toEqual({ kind: "failed" });
- });
});
describe("movieIdsKey", () => {
diff --git a/lib/tracking/movie-state.ts b/lib/tracking/movie-state.ts
index 61d0dac..5d2004a 100644
--- a/lib/tracking/movie-state.ts
+++ b/lib/tracking/movie-state.ts
@@ -69,33 +69,35 @@ export async function getMovieTracking(
}
/**
- * Which of a grid's movies the signed in user has planned, in one query for
- * the whole grid (spec 0007, AC-16).
+ * The signed in user's state for every movie on a grid, in one query for the
+ * whole grid (spec 0007, AC-16; prompts/catalog-card-status.md). A movie with
+ * no row is simply absent from the map: the user has never touched it.
*
- * Every card asks for the same set, so the argument is a primitive (a sorted,
- * comma joined id list) rather than an array: React `cache()` compares
- * arguments by identity, and only a string lets twenty cards share one read
- * per request.
+ * Every card's badge and controls ask for the same set, so the argument is a
+ * primitive (a sorted, comma joined id list) rather than an array: React
+ * `cache()` compares arguments by identity, and only a string lets every slot
+ * on the grid share one read per request.
*
* @param idsKey The grid's movie ids, sorted and joined with commas. Build it
* with `movieIdsKey`.
*/
-export const getWatchlistedMovieIds = cache(
- async (idsKey: string): Promise>> => {
+export const getMovieGridStates = cache(
+ async (
+ idsKey: string,
+ ): Promise>> => {
if (publicEnvProblems()) return { kind: "signed_out" };
const user = await getOptionalUser();
if (!user) return { kind: "signed_out" };
const ids = idsKey === "" ? [] : idsKey.split(",").map(Number);
- if (ids.length === 0) return { kind: "ok", state: new Set() };
+ if (ids.length === 0) return { kind: "ok", state: new Map() };
const supabase = await createClient();
const { data, error } = await supabase
.from("user_movie_state")
- .select("movie_id")
+ .select("movie_id, in_watchlist, watched_at, rating")
.eq("user_id", user.id)
- .eq("in_watchlist", true)
.in("movie_id", ids);
if (error) {
@@ -103,12 +105,24 @@ export const getWatchlistedMovieIds = cache(
return { kind: "failed" };
}
- return { kind: "ok", state: new Set(data.map((row) => row.movie_id)) };
+ return {
+ kind: "ok",
+ state: new Map(
+ data.map((row) => [
+ row.movie_id,
+ {
+ inWatchlist: row.in_watchlist,
+ watched: row.watched_at !== null,
+ rating: row.rating,
+ },
+ ]),
+ ),
+ };
},
);
/**
- * The cache key `getWatchlistedMovieIds` expects: the same ids in any order
+ * The cache key `getMovieGridStates` expects: the same ids in any order
* give the same key.
*
* @param ids The movie ids on the grid.
diff --git a/lib/tracking/show-grid-status.test.ts b/lib/tracking/show-grid-status.test.ts
new file mode 100644
index 0000000..f7c2a25
--- /dev/null
+++ b/lib/tracking/show-grid-status.test.ts
@@ -0,0 +1,150 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * covers: prompts/catalog-card-status.md, R5 to R8
+ *
+ * The composition is under test: the reads and the classifier are replaced,
+ * so each case says only what reaches the cards.
+ */
+vi.mock("server-only", () => ({}));
+const getTrackedShows = vi.fn();
+vi.mock("./show-state", () => ({
+ getTrackedShows: (...args: unknown[]) => getTrackedShows(...args),
+}));
+const getOptionalUser = vi.fn();
+vi.mock("@/lib/auth/user", () => ({ getOptionalUser }));
+vi.mock("@/lib/supabase/server", () => ({ createClient: async () => ({}) }));
+const readWatchedRegular = vi.fn();
+vi.mock("./library-lists", () => ({
+ readWatchedRegular: (...args: unknown[]) => readWatchedRegular(...args),
+}));
+class TmdbError extends Error {}
+const getTvShowsSettled = vi.fn();
+vi.mock("@/lib/tmdb", () => ({
+ TmdbError,
+ getTvShowsSettled: (...args: unknown[]) => getTvShowsSettled(...args),
+}));
+const classifyShow = vi.fn();
+vi.mock("@/lib/tv/library-page", () => ({
+ classifyShow: (...args: unknown[]) => classifyShow(...args),
+}));
+const getShowRatings = vi.fn();
+vi.mock("./show-ratings", () => ({
+ getShowRatings: (...args: unknown[]) => getShowRatings(...args),
+}));
+vi.mock("./episode-state", () => ({ requestTodayUtc: () => "2026-10-10" }));
+
+const { getShowGridStatus } = await import("./show-grid-status");
+
+const WATCHLIST = { page: "watchlist", next: { season: 1, episode: 2 } };
+const WATCHED = { page: "watched", label: "finished" };
+
+let warn: ReturnType;
+
+beforeEach(() => {
+ getOptionalUser.mockResolvedValue({ id: "user-a" });
+ getTrackedShows.mockResolvedValue({ kind: "ok", state: new Set([1, 2]) });
+ readWatchedRegular.mockResolvedValue(new Map());
+ getTvShowsSettled.mockResolvedValue({
+ found: new Map([
+ [1, { id: 1 }],
+ [2, { id: 2 }],
+ ]),
+ missingIds: [],
+ failedIds: [],
+ });
+ classifyShow.mockImplementation((show: { id: number }) =>
+ show.id === 1 ? WATCHLIST : WATCHED,
+ );
+ getShowRatings.mockResolvedValue({
+ kind: "ok",
+ ratings: new Map([[2, 7.5]]),
+ });
+ warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+afterEach(() => {
+ vi.clearAllMocks();
+ warn.mockRestore();
+});
+
+describe("getShowGridStatus", () => {
+ it("passes a visitor or a failed tracked read straight through", async () => {
+ getTrackedShows.mockResolvedValue({ kind: "signed_out" });
+ expect(await getShowGridStatus("1,2,3")).toEqual({ kind: "signed_out" });
+ getTrackedShows.mockResolvedValue({ kind: "failed" });
+ expect(await getShowGridStatus("1,2,4")).toEqual({ kind: "failed" });
+ });
+
+ it("places each tracked show, with the show rating only on Watched", async () => {
+ expect(await getShowGridStatus("1,2,3")).toEqual({
+ kind: "ok",
+ state: new Map([
+ [1, { ...WATCHLIST, rating: null }],
+ [2, { ...WATCHED, rating: 7.5 }],
+ ]),
+ });
+ expect(getTvShowsSettled).toHaveBeenCalledWith([1, 2]);
+ expect(readWatchedRegular).toHaveBeenCalledWith({}, "user-a", [1, 2]);
+ expect(getShowRatings).toHaveBeenCalledWith("user-a", [2]);
+ });
+
+ it("reads nothing more when no grid show is tracked", async () => {
+ getTrackedShows.mockResolvedValue({ kind: "ok", state: new Set() });
+ expect(await getShowGridStatus("5,6")).toEqual({
+ kind: "ok",
+ state: new Map(),
+ });
+ expect(getTvShowsSettled).not.toHaveBeenCalled();
+ });
+
+ it("leaves every tracked show plain when the episodes fail", async () => {
+ readWatchedRegular.mockResolvedValue(null);
+ expect(await getShowGridStatus("1,2,7")).toEqual({
+ kind: "ok",
+ state: new Map([
+ [1, null],
+ [2, null],
+ ]),
+ });
+ expect(warn).toHaveBeenCalledWith(
+ "show_tracking.watched_read refused db_error",
+ );
+ });
+
+ it("leaves every tracked show plain on a systemic TMDB failure", async () => {
+ getTvShowsSettled.mockRejectedValue(new TmdbError("rate limited"));
+ const result = await getShowGridStatus("1,2,8");
+ expect(result).toEqual({
+ kind: "ok",
+ state: new Map([
+ [1, null],
+ [2, null],
+ ]),
+ });
+ expect(warn).toHaveBeenCalledWith(
+ "show_tracking.grid_read refused tmdb_unavailable",
+ );
+ });
+
+ it("leaves a show plain when its own TMDB read failed", async () => {
+ getTvShowsSettled.mockResolvedValue({
+ found: new Map([[1, { id: 1 }]]),
+ missingIds: [],
+ failedIds: [2],
+ });
+ const result = await getShowGridStatus("1,2,9");
+ expect(result.kind === "ok" && result.state.get(2)).toBeNull();
+ expect(getShowRatings).not.toHaveBeenCalled();
+ });
+
+ it("leaves a Watched show plain, never unrated, when its rating read fails", async () => {
+ getShowRatings.mockResolvedValue({ kind: "failed" });
+ const result = await getShowGridStatus("1,2,10");
+ expect(result.kind === "ok" && result.state.get(2)).toBeNull();
+ expect(result.kind === "ok" && result.state.get(1)).toEqual({
+ ...WATCHLIST,
+ rating: null,
+ });
+ });
+});
diff --git a/lib/tracking/show-grid-status.ts b/lib/tracking/show-grid-status.ts
new file mode 100644
index 0000000..7a33f9a
--- /dev/null
+++ b/lib/tracking/show-grid-status.ts
@@ -0,0 +1,131 @@
+import "server-only";
+
+import { cache } from "react";
+
+import { getOptionalUser } from "@/lib/auth/user";
+import { createClient } from "@/lib/supabase/server";
+import { getTvShowsSettled, TmdbError } from "@/lib/tmdb";
+import { classifyShow, type ShowPage } from "@/lib/tv/library-page";
+
+import { requestTodayUtc } from "./episode-state";
+import { readWatchedRegular } from "./library-lists";
+import { logTrackingEvent, TRACKING_EVENT } from "./log";
+import { getShowRatings } from "./show-ratings";
+import { getTrackedShows } from "./show-state";
+import type { TrackingRead } from "./types";
+
+/**
+ * What a catalog card shows of one tracked show: the library page it sits on
+ * with that page's card data, and on Watched the calculated show rating.
+ * Null when the show is tracked but its page could not be worked out (its
+ * TMDB details or the user's episodes failed to load): the card is then a
+ * plain tracked card, never a wrong label.
+ */
+export type ShowCardStatus =
+ | (Exclude & { rating: null })
+ | (Extract & { rating: number | null });
+
+/**
+ * The signed in user's tracked shows on a grid, each with the library page it
+ * sits on (prompts/catalog-card-status.md). An untracked show is absent from
+ * the map; a tracked one is present, with its status or null.
+ *
+ * One pass per grid: the tracked set (`getTrackedShows`, shared with nothing
+ * else), then for the tracked ids only the watched regular episodes, the
+ * cached TMDB details and `classifyShow`, the same inputs the library pages
+ * read, on the same request day, so a card cannot disagree with its page.
+ * The calculated rating is read only for the shows that land on Watched.
+ *
+ * Request scoped and wrapped in `cache()` with a string key, so a card's
+ * badge, meta line and controls share one pass. Never inside `use cache`
+ * (`AGENTS.md` section 11).
+ *
+ * @param idsKey The grid's show ids, from `showIdsKey`.
+ */
+export const getShowGridStatus = cache(
+ async (
+ idsKey: string,
+ ): Promise>> => {
+ const tracked = await getTrackedShows(idsKey);
+ if (tracked.kind !== "ok") return tracked;
+
+ const ids = [...tracked.state];
+ const state = new Map(
+ ids.map((id) => [id, null]),
+ );
+ if (ids.length === 0) return { kind: "ok", state };
+
+ const user = await getOptionalUser();
+ if (!user) return { kind: "signed_out" };
+
+ const places = await placeShows(user.id, ids);
+ if (places === null) return { kind: "ok", state };
+
+ const watchedIds = [...places]
+ .filter(([, place]) => place.page === "watched")
+ .map(([id]) => id);
+ const ratings =
+ watchedIds.length === 0
+ ? null
+ : await getShowRatings(user.id, watchedIds);
+
+ for (const [id, place] of places) {
+ if (place.page !== "watched") {
+ state.set(id, { ...place, rating: null });
+ continue;
+ }
+ // A failed ratings read leaves the card plain rather than unrated.
+ if (ratings?.kind !== "ok") continue;
+ state.set(id, { ...place, rating: ratings.ratings.get(id) ?? null });
+ }
+ return { kind: "ok", state };
+ },
+);
+
+/**
+ * `classifyShow` for each show whose details loaded, or null when the
+ * episodes or TMDB failed as a whole (logged here, with no identifiers). A
+ * show whose own read failed, or that TMDB no longer has, is simply absent.
+ */
+async function placeShows(
+ userId: string,
+ ids: readonly number[],
+): Promise | null> {
+ const [watched, shows] = await Promise.all([
+ readWatched(userId, ids),
+ readShows(ids),
+ ]);
+ if (watched === null || shows === null) return null;
+
+ const today = requestTodayUtc();
+ const places = new Map();
+ for (const [id, show] of shows.found) {
+ places.set(id, classifyShow(show, watched.get(id) ?? new Set(), today));
+ }
+ return places;
+}
+
+async function readWatched(userId: string, ids: readonly number[]) {
+ try {
+ const supabase = await createClient();
+ const watched = await readWatchedRegular(supabase, userId, ids);
+ if (watched === null)
+ logTrackingEvent(TRACKING_EVENT.watchedEpisodesRead, "db_error");
+ return watched;
+ } catch {
+ // A network failure inside supabase-js. The error is dropped: its
+ // message can carry request details.
+ logTrackingEvent(TRACKING_EVENT.watchedEpisodesRead, "db_error");
+ return null;
+ }
+}
+
+async function readShows(ids: readonly number[]) {
+ try {
+ return await getTvShowsSettled(ids);
+ } catch (error) {
+ if (!(error instanceof TmdbError)) throw error;
+ logTrackingEvent(TRACKING_EVENT.showGridRead, "tmdb_unavailable");
+ return null;
+ }
+}
diff --git a/prompts/catalog-card-status.md b/prompts/catalog-card-status.md
new file mode 100644
index 0000000..a2e5e17
--- /dev/null
+++ b/prompts/catalog-card-status.md
@@ -0,0 +1,155 @@
+# Catalog cards show the title's real status
+
+No spec: it reuses the library pages' card states and classifiers, with no new architectural decision (decided in grilling, 2026-10-11). Branch `feat/catalog-card-status`, off `main`.
+
+## Goal
+
+A poster card on `/movies`, `/shows` and `/search` shows the signed-in user's actual state for that title, the same state its library page shows. Today a watched and scored movie still shows the TMDB rating and an empty Plan bookmark there.
+
+## Inspected code
+
+- `app/movies/page.tsx`, `app/shows/page.tsx` and `components/search/search-results.tsx` render `PosterCard` with a static `TmdbRatingBadge`. They put the bookmark in `controls` inside its own `Suspense fallback={null}`. Search also passes `meta={year}`.
+- `components/tracking/card-bookmark.tsx` reads only `getWatchlistedMovieIds` (a `cache()`d read, one query per grid). `CardBookmarkButton` can only plan or unplan.
+- `components/tracking/show-card-bookmark.tsx` reads only `getTrackedShows`.
+- `components/library/library-card.tsx` holds the movie cards:
+ - Watchlist: TMDB badge and the Planned button.
+ - Upcoming: `ReleasePill` (`DatedPill` or `DateTbaPill`), no badge, and the Planned button.
+ - Watched: `PersonalScoreBadge` when scored, and a filled `WatchedIcon` button labelled "Unmark … as watched".
+- `components/library/show-cards.tsx` holds the show cards. `UpcomingShowPill` shows "S2E1 · Oct 20" or Date TBA. `WatchedShowCard` shows `CalculatedRatingBadge` ("Your show rating") and puts `WATCHED_SHOW_LABELS` in `meta`.
+- `lib/catalog/movie-page.ts` provides the pure helpers `classifyMovie` and `upcomingReleaseDate`.
+- `lib/tv/library-page.ts` provides the pure `classifyShow(details, watchedRegularKeys, today)`, which returns `ShowPage`.
+- `lib/tracking/library-lists.ts` has two things to reuse:
+ - The private `readWatchedRegular`, which pages through the watched regular episodes.
+ - `getTvShowsSettled`, a cached TMDB details batch.
+- `lib/tracking/show-ratings.ts`: `getShowRatings(userId, ids)`.
+- `lib/tracking/episode-state.ts`: `requestTodayUtc()`.
+- `app/movies/actions.ts` and `app/shows/actions.ts` already call `refresh()` on success, so after any write the server re-renders a card's badge and pill. No client-side badge state is needed.
+- `components/tracking/use-movie-cleared-undo.ts` provides `showCleared("unwatched", cleared, …)`, the unmark toast and Undo the movie page uses.
+- `lib/search/read.ts`: `SearchResult` has `year` but no `releaseDate`. `MovieSummary.releaseDate` exists.
+
+## Skills
+
+- `next-dev-loop`, to drive the three grids in the running app.
+- `supabase` only for the local stack (`pnpm dev:docker`). There is no schema change, so the Postgres skill is not needed.
+
+## Decisions (settled in grilling, 2026-10-11)
+
+1. **Scope:** the poster grids on `/movies`, `/shows` and `/search` (both media types). Quick search rows, detail pages and the library pages themselves are unchanged.
+2. **Watched movie:** your cyan score replaces the TMDB rating. With no score, the TMDB rating stays.
+3. **The watched movie's button** is the filled watched mark from the Watched page.
+ - It unmarks the movie with `setMovieWatched(id, false)`, which also removes the score.
+ - The toast and Undo are the movie page's (`useMovieClearedUndo`, `"unwatched"`).
+ - After `refresh()`, the card falls back to the empty Plan bookmark and the TMDB rating.
+4. **Planned movie, released:** unchanged (TMDB badge and Planned bookmark), as on Watchlist.
+5. **Planned movie, unreleased or undated:** the Upcoming look, with the release date pill or Date TBA, no badge, and the Planned bookmark. The date comes from the TMDB result already on the card. The test is `classifyMovie` with `requestTodayUtc()`, so the card and `/upcoming` cannot disagree.
+6. **Untouched title:** unchanged.
+7. **Tracked show:** the filled bookmark (Stop tracking) stays on every tracked card. What else the card shows comes from `classifyShow`:
+ - **Watchlist:** nothing extra. The card is the same as today.
+ - **Upcoming:** the "S2E1 · Oct 20" pill or Date TBA bottom left, and no TMDB rating.
+ - **Watched:** `CalculatedRatingBadge` replaces the TMDB rating when a regular season is rated; with no rating the TMDB rating stays. The Finished or Caught up label goes under the name.
+8. **While status loads:** the badge falls back to the TMDB rating, so only your own titles swap. The controls fall back to nothing, as today. The meta line falls back to what it shows today (the year on `/search`, nothing on `/shows`).
+9. **Failure:** if the user-state read fails, the card renders exactly as it does for a visitor, as `CardBookmark` does today. If one tracked show's TMDB details or the ratings read fail, that card stays a plain tracked card (bookmark and TMDB rating) and is never labelled wrongly.
+10. **Search meta (assumption):** a Watched show on `/search` reads "2019 · Finished", appending the label to the year rather than replacing it.
+
+## Design
+
+One request-scoped read per grid and media type, shared by every card through React `cache()` with a string key, the `getWatchlistedMovieIds` pattern. Each card fills three slots, each in its own Suspense boundary: badge, meta (shows only) and controls. All three call the same cached read, so a grid still makes one Supabase round per media type.
+
+- `lib/tracking/movie-state.ts`:
+ - `getWatchlistedMovieIds` is replaced by `getMovieGridStates(idsKey)`, which returns `Map` from one `in()` query.
+ - The pure `movieCardStatus(state | undefined, releaseDate, today)` returns `"none" | "watchlist" | "upcoming" | "watched"` through `classifyMovie`, with `"upcoming"` carrying `upcomingReleaseDate`.
+- `lib/tracking/show-grid-status.ts` (new, server-only) provides `getShowGridStatus(idsKey)`:
+ 1. `getTrackedShows`.
+ 2. For the tracked ids only: the watched regular episodes (`readWatchedRegular`, exported from `library-lists.ts`), `getTvShowsSettled`, then `classifyShow` per show.
+ 3. `getShowRatings` for the shows that land on Watched.
+
+ It returns `Map`. A show whose own reads failed is just tracked.
+- `components/tracking/movie-card-slots.tsx` provides `MovieCardBadge` and `MovieCardControls`. The controls render one of three things:
+ - `CardBookmarkButton`
+ - the release pill plus `CardBookmarkButton`
+ - the new `CardWatchedButton`
+- `components/tracking/card-watched-button.tsx` (new client component): the round filled watched mark, which calls `setMovieWatched(id, false)`. It uses the same optimistic, error toast and `useMovieClearedUndo` handling as `CardBookmarkButton`.
+- `components/tracking/show-card-slots.tsx` provides `ShowCardBadge`, `ShowCardMeta` and `ShowCardControls` (the Upcoming pill plus `ShowCardBookmarkButton`).
+- `ReleasePill` (from `library-card.tsx`) and `UpcomingShowPill` (from `show-cards.tsx`) are exported and reused unchanged, so the pill copy and layout have one owner.
+- `card-bookmark.tsx` and `show-card-bookmark.tsx` are replaced by the slot components, and their callers are updated.
+
+## Expected files
+
+- Changed:
+ - `app/movies/page.tsx`
+ - `app/shows/page.tsx`
+ - `components/search/search-results.tsx`
+ - `lib/search/read.ts` (adds `releaseDate` to `SearchResult`, movies only, null for TV)
+ - `lib/tracking/movie-state.ts`
+ - `lib/tracking/library-lists.ts` (exports `readWatchedRegular`)
+ - `components/library/library-card.tsx` and `components/library/show-cards.tsx` (export the pills)
+- New:
+ - `lib/tracking/show-grid-status.ts`
+ - `components/tracking/movie-card-slots.tsx`
+ - `components/tracking/show-card-slots.tsx`
+ - `components/tracking/card-watched-button.tsx`
+- Removed: `components/tracking/card-bookmark.tsx` and `components/tracking/show-card-bookmark.tsx` (their tests move to the slot files).
+- Tests:
+ - `lib/tracking/movie-state.test.ts` (`movieCardStatus`)
+ - `lib/tracking/show-grid-status.test.ts`
+ - `components/tracking/movie-card-slots.test.tsx`
+ - `components/tracking/show-card-slots.test.tsx`
+ - `components/tracking/card-watched-button.test.tsx`
+ - updates to `search-results` and the page tests
+
+## Requirements
+
+- R1. A watched, scored movie on any grid shows `PersonalScoreBadge` and the filled watched button, and no Plan bookmark.
+- R2. A watched, unscored movie shows the TMDB badge and the filled watched button.
+- R3. Tapping the watched button unmarks the movie. A stored score shows the "score removed" toast with Undo, and Undo restores the mark and the score. Afterwards the card shows the TMDB badge and the empty Plan bookmark.
+- R4. A planned, unreleased or undated movie shows the release pill or Date TBA, no badge, and the pressed Planned bookmark. A planned, released movie looks as it does today.
+- R5. A tracked show on Upcoming shows its pill and no badge. On Watched it shows the calculated rating, or the TMDB rating if unrated, plus the Finished or Caught up label. On Watchlist it looks as it does today. Every tracked show keeps the filled bookmark.
+- R6. A card's status always matches the library page that title is on, because both use the same classifiers and the same `requestTodayUtc()`.
+- R7. Signed-out visitors, and any failed read, get today's catalog card. Nothing breaks the grid.
+- R8. A grid makes one movie-state query or one tracked-show pass per request, whatever the card count. TMDB details are read only for tracked shows on the grid (at most 20, cached).
+
+## Security
+
+- Every new read derives the user from `getOptionalUser()`, filters on `user_id` explicitly and through RLS, and never runs inside `use cache` (`AGENTS.md` section 11).
+- The grids' prerendered shells stay public. All user state streams inside per-card Suspense boundaries, so private state never enters a shared cache.
+- The unmark goes through the existing `setMovieWatched` Server Action, which already authenticates and validates.
+- `releaseDate` on `SearchResult` is public TMDB data.
+
+## Acceptance criteria
+
+- AC-1. R1 to R7 hold on `/movies`, `/shows`, `/search?type=movie` and `/search?type=tv`.
+- AC-2. `/movies` and `/shows` still prerender their shells (`pnpm build` reports them as partially prerendered, as now).
+- AC-3. Unchanged cards show no layout shift: the badge fallback is the TMDB badge.
+
+## Automated checks
+
+`pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm build`. No `pnpm test:db`: there is no database change.
+
+## Manual test steps (`pnpm dev:docker`, signed in)
+
+1. Mark a released movie watched with score 8. On `/movies` (or `/search?type=movie&q=`), its card shows the cyan 8 and the filled watched mark.
+2. Tap the watched mark. The toast offers Undo, and the card shows the TMDB rating and the empty Plan bookmark. Tap Undo, and the cyan 8 and watched mark return.
+3. Mark another movie watched without a score. Its card shows the TMDB rating and the watched mark.
+4. Plan an unreleased movie (find one in search). Its card switches to the release date pill with no badge, and it matches its `/upcoming?type=movie` card.
+5. On `/shows` or `/search?type=tv`, track three shows:
+ - one with an unwatched aired episode, which looks as it does today;
+ - one caught up with a dated next episode, which shows the S·E date pill and no rating;
+ - one ended show fully watched and rated, which shows your show rating and "Finished".
+
+ Each must match its library page.
+6. Stop tracking the Watched show from its card. The card returns to the TMDB rating with an empty bookmark.
+7. Sign out. All grids look as they did before this change.
+8. Narrow the window to phone width. The pills and badges don't overlap, and the tap targets stay 44px.
+
+## Amendments (2026-10-11, after code review)
+
+The shipped code differs from the design above in these places. Behaviour and requirements R1 to R8 are unchanged.
+
+- `movieCardStatus` lives in `lib/catalog/movie-page.ts` beside `classifyMovie`, not in `lib/tracking/movie-state.ts`, because it is pure and that file is server-only. It takes a `MovieTrackingState`.
+- `classifyMovie` takes a `watched` flag instead of `watchedAt` (commit 0a27029), so `getMovieGridStates` does not need the timestamp.
+- `ReleasePill` moved to `components/library/dated-pill.tsx` beside `DatedPill` and takes the formatted `release` instead of the whole card. The formatting is `formatReleaseDate` in `lib/format.ts`, shared by the library Upcoming card and the catalog cards.
+- The badge rule (your rating on Watched, nothing on Upcoming, the TMDB rating otherwise) is one component, `components/tracking/card-rating-badge.tsx`, used by both the movie and the show slots.
+- `/search` renders a `MovieResultCard` or a `ShowResultCard` per result instead of branching on the media type inside each slot, and its skeleton cards take `PosterCardSkeleton meta`, so the year line under each name is reserved and the cards do not grow when the results arrive.
+- The movie card slot tests are in `components/tracking/movie-card-slots.test.tsx`, as listed.
+- Decision 9 is kept as written: when the ratings read fails, a show on Watched stays a plain tracked card and loses its Finished or Caught up label too. A label with the TMDB rating would look like an unrated show, which is the wrong state the decision rules out.
+- A systemic TMDB failure while placing a grid's shows logs `show_tracking.grid_read`, not the tracked set's `show_tracking.read`.
diff --git a/prompts/grid-tabs-footer-legend.md b/prompts/grid-tabs-footer-legend.md
new file mode 100644
index 0000000..7fada5c
--- /dev/null
+++ b/prompts/grid-tabs-footer-legend.md
@@ -0,0 +1,95 @@
+# Four column grid, cyan selected tabs, footer icon key, honest skeletons
+
+## Goal
+
+Four UI changes, settled with the user in a grilling session on 2026-10-11:
+
+1. Stop the layout jumping when a page finishes loading: every skeleton matches the footprint of what replaces it.
+2. Regrid the poster grids to at most 4 columns, so the 20 cards a page holds fill 5 complete rows.
+3. Light the selected navbar tab in the personal score cyan, as a glass fill.
+4. Replace the per tab badge legend with one fixed icon key, centred at the top of the site footer on every route.
+
+Branch `feat/grid-tabs-footer-legend`. No spec: this plan records the decisions.
+
+## Inspected code
+
+- Grid: `components/poster-grid.tsx` (2/3/4/5/6 columns), `components/poster-card.tsx` (`POSTER_SIZES`), `app/shows/page.tsx` and `app/movies/page.tsx` (`PAGE_SIZE = 20`, `EAGER_POSTERS = 6`, skeletons), `components/library/library-grid.tsx` (`EAGER_POSTERS`), `components/show/season-grid.tsx` (also `PosterGrid`), `lib/tracking/library-lists.ts` (`LIBRARY_PAGE_SIZE = 20`)
+- Skeletons: `components/library/library-panels.tsx` (`LibrarySkeleton`, always 20 cards), `components/search/search-results.tsx` (`SearchResultsSkeleton`), `components/skeleton.tsx`, `components/movie/movie-detail-skeleton.tsx`, `components/show/show-detail-skeleton.tsx`, `components/show/season-skeleton.tsx`, `components/catalog/detail-skeletons.tsx`
+- Tabs: `components/layout/media-type-tabs.tsx`, `components/layout/library-nav.tsx` (bar and sheet variants), `glass-selected` in `app/globals.css`, `--color-score-personal: #50c6e5`
+- Legend: `components/library/badge-legend.tsx`, its callers `show-library-tab.tsx` and `movie-library-tab.tsx`, `components/library/library-section.test.tsx` (legend cases), `components/tracking/tracking-icons.tsx` (no `"use client"`, so usable from the server footer), `components/AGENTS.md` (badge legend line), `app/showcase/page.tsx`
+- Footer: `components/layout/site-footer.tsx`, `site-footer.test.tsx`, `app/layout.tsx`, `app/layout-purity.test.ts` (the footer must stay a request free Server Component)
+
+## Skills used
+
+`next-dev-loop` to measure skeletons against loaded pages and verify the result in the running app. No database change, so no Supabase skill.
+
+## Decisions
+
+1. **Page size stays 20 everywhere.** `/shows`, `/movies` and `/search` keep one TMDB page per BeStats page; the library pages keep `LIBRARY_PAGE_SIZE = 20`. No TMDB re-paging.
+2. **Grid columns: 2 below `md`, 4 from `md` (768px).** 20 fills every row at both counts (10 × 2, 5 × 4); 3 columns would leave a partial row, so there is no 3 column step. Applies to every `PosterGrid`, including the seasons on `/shows/{id}`.
+3. **Grid width capped at 1200px and centred** on every page (`mx-auto max-w-[1200px]` on `PosterGrid`; changed from left aligned at the owner's request after review), so a 4 column poster stays near 285px wide and a 5 row page stays a sensible length. Pagination and other content beside the grid keep their current width.
+4. **Image sizes follow the grid.** `POSTER_SIZES` becomes `(min-width: 1200px) 300px, (min-width: 768px) 25vw, 50vw`; every `EAGER_POSTERS` becomes 4 (one full row at the widest grid).
+5. **Skeletons.**
+ - `LibrarySkeleton` draws one row (4 cards): the real count is unknown until the read, and one row is the smallest honest guess.
+ - The `/shows`, `/movies` and search skeletons add a placeholder for the pagination row at its real height.
+ - Every other route (detail, season, search filters, auth, account) is measured in the browser: skeleton height against loaded height at 390px and 1440px. Any mismatch over a few pixels is fixed in its skeleton; the plan's report lists each route measured and what changed.
+6. **Selected tab: cyan glass.** A new `glass-selected-personal` utility in `app/globals.css`, the same layer stack as `glass-selected` (fill, plate, rim on the 1.5px border) with the gradient tinted from `--color-score-personal`, translucent so the glass reads. Text on it is near black (a token, e.g. `text-on-personal`) so it meets WCAG AA 4.5:1; the exact tint is checked with a contrast measurement, not assumed. Used by the selected tab in `MediaTypeTabsView` and in both `LibraryNav` variants. Unselected tabs do not change.
+7. **Footer icon key.**
+ - `BadgeLegend` and its per tab entries are deleted, with their test cases; the two library tabs no longer render it.
+ - A new `IconKey` Server Component (`components/layout/icon-key.tsx`) renders one fixed list, always all entries, in this order: TMDB rating, Your score, Plan, Planned, Mark watched, Watched, Next episode, Release date. Same icons and colours as the cards (`StarIcon` in `rating-tmdb` / `score-personal`, `PlanIcon`, `PlannedIcon`, `NextEpisodeIcon`, `WatchedIcon` outline and filled, `CalendarIcon`), `size-4`, `text-text-legend`.
+ - It is the footer's first row, on every route, inside the footer's 1600px container: a hairline (`border-t border-border`) above, centred `flex-wrap` with the current legend gaps, wrapping centred on mobile. The existing attribution and legal row sits below it unchanged.
+ - `<ul aria-label="Icon key">`, each `<li>` the icon (`aria-hidden`) and its text.
+ - It reads no request state, so the footer stays in every prerendered shell.
+8. **Docs.** `components/AGENTS.md` badge legend line now points at the footer icon key; the showcase's legend wording is updated to match.
+
+## Expected files
+
+- `components/poster-grid.tsx`, `components/poster-card.tsx`
+- `app/shows/page.tsx`, `app/movies/page.tsx`, `components/library/library-grid.tsx`, `components/library/show-library-tab.tsx`, `components/library/movie-library-tab.tsx` (eager count, legend removal)
+- `components/library/library-panels.tsx`, `components/search/search-results.tsx`, plus any detail or season skeleton the measurement flags
+- `app/globals.css`, `components/layout/media-type-tabs.tsx`, `components/layout/library-nav.tsx`
+- New `components/layout/icon-key.tsx` and `icon-key.test.tsx`; `components/layout/site-footer.tsx` and its test
+- Deleted `components/library/badge-legend.tsx`; `components/library/library-section.test.tsx` legend cases removed
+- `components/AGENTS.md`, `app/showcase/page.tsx`
+- Tests touching the grid, tabs or skeleton counts, updated
+
+## Requirements
+
+- No horizontal scroll at 390px; tap targets keep their current sizes (the tab `hit-area` utilities are unchanged).
+- The selected tab keeps `aria-current="page"`; colour is not the only signal.
+- No colour literal outside `app/globals.css` (`design-tokens-boundary.test.ts`).
+- Footer stays a Server Component with no cookie, header or session read (`layout-purity.test.ts`).
+- `POSTER_SIZES` and the grid columns change together (the comment in `poster-grid.tsx`).
+
+## Security
+
+UI only: no new data, input, route or credential. The footer key is static, so it is safe in shared prerendered shells.
+
+## Acceptance criteria
+
+1. At 1440px, `/shows`, `/movies`, `/search` and a 20 title library page show 5 full rows of 4; at 390px, 2 columns.
+2. The grid is no wider than 1200px and is centred on every page.
+3. Loading each route shows a skeleton whose height matches the loaded page; a library page with 3 titles no longer collapses from 5 rows to 1.
+4. The selected SHOWS | MOVIES tab and the selected Watchlist / Upcoming / Watched link are cyan glass with near black text at 4.5:1 or better; unselected tabs look as before.
+5. No library page renders a legend under its grid.
+6. Every route, including `/sign-in`, `/account`, `/privacy` and a 404, shows the icon key centred at the top of the footer, with all eight entries.
+7. The showcase and `components/AGENTS.md` describe the new key.
+
+## Automated checks
+
+`pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm build`.
+
+## Manual test steps (`pnpm dev:docker`)
+
+1. Open `/shows` at 1440px: 4 columns, 5 full rows, grid at most 1200px wide and centred, pagination below. Resize to 390px: 2 columns, no horizontal scroll.
+2. Throttle the network (DevTools, Slow 4G) and open `/shows?page=2`: the skeleton grid and pagination placeholder hold the page height; nothing jumps when cards arrive.
+3. Sign in with an account tracking 3 shows, open `/watchlist`: the skeleton is one row, and the page does not shrink when the cards load.
+4. Open `/shows/1399` and a season page with throttling: no visible resize when content arrives; seasons are 4 per row.
+5. Check the navbar on `/shows`, `/movies?page=2`, `/watchlist?type=movie`: the lit tab is cyan glass with dark text; keyboard Tab shows the focus ring on it.
+6. Scroll to the footer on `/shows`, `/sign-in`, `/privacy` and `/nope`: the icon key is the footer's centred first row with all eight entries; at 390px it wraps centred.
+7. Open `/showcase`: the tab and key examples match the shipped UI.
+
+## Amendments (2026-10-11, after code review)
+
+- Decision 4: `POSTER_SIZES` shipped as `(min-width: 1232px) 288px, (min-width: 768px) 25vw, 50vw`. The 1200px cap is the grid's content width, so the cap is reached at a 1232px viewport (two 16px gutters), and each column is 288px, not 300px, once the three 16px gaps are taken out.
+- Decision 4, `LibrarySkeleton`: "one row" means one row at the current column count, so 2 cards below `md` and 4 from it. Four cards on a two-column phone grid would be two rows and would shrink when a one-row library arrives.