Add actor/cast information with person pages and search support

Integrate TMDB credits data into the app: cast carousels on title detail
pages, person detail pages with biography and filmography, and person
search results in the command palette. Includes new persons/titleCast
DB tables, profile image caching, and a nightly credits refresh cron job.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app/(pages)/person/[id]/_components/filmography-grid.tsx

@@ -0,0 +1,158 @@
+"use client";
+
+import { IconMovie } from "@tabler/icons-react";
+import { motion } from "motion/react";
+import Image from "next/image";
+import Link from "next/link";
+import { useMemo, useState } from "react";
+import type { PersonCredit } from "@/lib/types/title";
+
+type Filter = "all" | "movie" | "tv";
+type Sort = "newest" | "rating";
+
+const staggerContainer = {
+  hidden: {},
+  visible: { transition: { staggerChildren: 0.04 } },
+};
+
+const staggerItem = {
+  hidden: { opacity: 0, y: 12, scale: 0.98 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    scale: 1,
+    transition: { type: "spring" as const, stiffness: 300, damping: 24 },
+  },
+};
+
+interface FilmographyGridProps {
+  credits: PersonCredit[];
+}
+
+export function FilmographyGrid({ credits }: FilmographyGridProps) {
+  const [filter, setFilter] = useState<Filter>("all");
+  const [sort, setSort] = useState<Sort>("newest");
+
+  const filtered = useMemo(() => {
+    let list = credits;
+    if (filter !== "all") {
+      list = list.filter((c) => c.type === filter);
+    }
+
+    // Deduplicate by titleId (keep the first credit per title)
+    const seen = new Set<string>();
+    list = list.filter((c) => {
+      if (seen.has(c.titleId)) return false;
+      seen.add(c.titleId);
+      return true;
+    });
+
+    return list.sort((a, b) => {
+      if (sort === "rating") {
+        return (b.voteAverage ?? 0) - (a.voteAverage ?? 0);
+      }
+      const dateA = a.releaseDate ?? a.firstAirDate ?? "";
+      const dateB = b.releaseDate ?? b.firstAirDate ?? "";
+      return dateB.localeCompare(dateA);
+    });
+  }, [credits, filter, sort]);
+
+  if (credits.length === 0) return null;
+
+  const filters: { value: Filter; label: string }[] = [
+    { value: "all", label: "All" },
+    { value: "movie", label: "Movies" },
+    { value: "tv", label: "TV" },
+  ];
+
+  return (
+    <section className="space-y-4">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <IconMovie className="size-5 text-primary" />
+          <h2 className="font-display text-xl tracking-tight">Filmography</h2>
+          <span className="text-sm text-muted-foreground">
+            ({filtered.length})
+          </span>
+        </div>
+
+        <select
+          value={sort}
+          onChange={(e) => setSort(e.target.value as Sort)}
+          className="rounded-lg border border-border/50 bg-card px-2 py-1 text-xs text-foreground"
+        >
+          <option value="newest">Newest</option>
+          <option value="rating">Rating</option>
+        </select>
+      </div>
+
+      <div className="flex gap-2">
+        {filters.map((f) => (
+          <button
+            key={f.value}
+            type="button"
+            onClick={() => setFilter(f.value)}
+            className={`rounded-full px-3 py-1 text-xs font-medium transition-colors ${
+              filter === f.value
+                ? "bg-primary text-primary-foreground"
+                : "bg-muted text-muted-foreground hover:text-foreground"
+            }`}
+          >
+            {f.label}
+          </button>
+        ))}
+      </div>
+
+      <motion.div
+        key={`${filter}-${sort}`}
+        variants={staggerContainer}
+        initial="hidden"
+        animate="visible"
+        className="grid grid-cols-2 gap-4 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5"
+      >
+        {filtered.map((credit) => (
+          <motion.div key={credit.titleId} variants={staggerItem}>
+            <Link href={`/titles/${credit.titleId}`} className="group">
+              <div className="overflow-hidden rounded-xl bg-card ring-1 ring-white/[0.06] transition-all group-hover:ring-primary/25">
+                <div className="aspect-[2/3] w-full bg-muted">
+                  {credit.posterPath ? (
+                    <Image
+                      src={credit.posterPath}
+                      alt={credit.title}
+                      width={200}
+                      height={300}
+                      className="h-full w-full object-cover"
+                    />
+                  ) : (
+                    <div className="flex h-full items-center justify-center text-muted-foreground/30">
+                      <IconMovie className="size-10" />
+                    </div>
+                  )}
+                </div>
+                <div className="px-3 pb-3 pt-2.5">
+                  <p className="truncate text-xs font-medium">{credit.title}</p>
+                  <div className="mt-0.5 flex items-center gap-1.5 text-[10px] text-muted-foreground">
+                    <span className="uppercase">{credit.type}</span>
+                    {(credit.releaseDate ?? credit.firstAirDate) && (
+                      <span>
+                        {(credit.releaseDate ?? credit.firstAirDate)?.slice(
+                          0,
+                          4,
+                        )}
+                      </span>
+                    )}
+                  </div>
+                  {credit.character && (
+                    <p className="mt-1 truncate text-[10px] text-muted-foreground/70">
+                      as {credit.character}
+                    </p>
+                  )}
+                </div>
+              </div>
+            </Link>
+          </motion.div>
+        ))}
+      </motion.div>
+    </section>
+  );
+}

app/(pages)/person/[id]/_components/person-hero.tsx

@@ -0,0 +1,110 @@
+"use client";
+
+import { IconCalendar, IconMapPin } from "@tabler/icons-react";
+import { motion } from "motion/react";
+import Image from "next/image";
+import { useState } from "react";
+import type { ResolvedPerson } from "@/lib/types/title";
+
+interface PersonHeroProps {
+  person: ResolvedPerson;
+}
+
+function calculateAge(birthday: string, deathday?: string | null): number {
+  const birth = new Date(birthday);
+  const end = deathday ? new Date(deathday) : new Date();
+  let age = end.getFullYear() - birth.getFullYear();
+  const m = end.getMonth() - birth.getMonth();
+  if (m < 0 || (m === 0 && end.getDate() < birth.getDate())) {
+    age--;
+  }
+  return age;
+}
+
+export function PersonHero({ person }: PersonHeroProps) {
+  const [bioExpanded, setBioExpanded] = useState(false);
+  const age = person.birthday
+    ? calculateAge(person.birthday, person.deathday)
+    : null;
+
+  return (
+    <motion.div
+      className="flex flex-col gap-6 sm:flex-row sm:gap-8"
+      initial={{ opacity: 0, y: 16 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ type: "spring", stiffness: 300, damping: 28 }}
+    >
+      <div className="size-40 shrink-0 self-center overflow-hidden rounded-2xl ring-1 ring-white/10 shadow-2xl sm:size-56 sm:self-start">
+        {person.profilePath ? (
+          <Image
+            src={person.profilePath}
+            alt={person.name}
+            width={224}
+            height={224}
+            className="h-full w-full object-cover"
+            priority
+          />
+        ) : (
+          <div className="flex h-full w-full items-center justify-center bg-gradient-to-br from-muted to-muted/50">
+            <span className="font-display text-5xl text-muted-foreground/40">
+              {person.name.charAt(0)}
+            </span>
+          </div>
+        )}
+      </div>
+
+      <div className="min-w-0 flex-1 space-y-3">
+        <h1 className="font-display text-3xl tracking-tight sm:text-5xl">
+          {person.name}
+        </h1>
+
+        {person.knownForDepartment && (
+          <span className="inline-block rounded-full bg-primary/10 px-2.5 py-0.5 text-[10px] font-semibold uppercase tracking-wider text-primary">
+            {person.knownForDepartment}
+          </span>
+        )}
+
+        <div className="flex flex-wrap items-center gap-x-4 gap-y-1 text-sm text-muted-foreground">
+          {person.birthday && (
+            <span className="flex items-center gap-1.5">
+              <IconCalendar className="size-3.5" />
+              {person.birthday}
+              {age !== null && (
+                <span className="text-muted-foreground/60">
+                  ({person.deathday ? `died at ${age}` : `age ${age}`})
+                </span>
+              )}
+            </span>
+          )}
+          {person.placeOfBirth && (
+            <span className="flex items-center gap-1.5">
+              <IconMapPin className="size-3.5" />
+              {person.placeOfBirth}
+            </span>
+          )}
+        </div>
+
+        {person.biography && (
+          <div className="max-w-3xl">
+            <p
+              className={`text-sm leading-relaxed text-muted-foreground ${
+                !bioExpanded ? "line-clamp-6" : ""
+              }`}
+            >
+              {person.biography}
+            </p>
+            {person.biography.length > 400 && (
+              <button
+                type="button"
+                onClick={() => setBioExpanded(!bioExpanded)}
+                className="mt-1 text-xs font-medium text-primary transition-colors hover:text-primary/80"
+              >
+                {bioExpanded ? "Show less" : "Read more"}
+              </button>
+            )}
+          </div>
+        )}
+      </div>
+    </motion.div>
+  );
+}

app/(pages)/person/[id]/loading.tsx

@@ -0,0 +1,5 @@
+import { PersonDetailSkeleton } from "@/components/skeletons";
+
+export default function PersonLoading() {
+  return <PersonDetailSkeleton />;
+}

app/(pages)/person/[id]/not-found.tsx

@@ -0,0 +1,19 @@
+import Link from "next/link";
+
+export default function PersonNotFound() {
+  return (
+    <div className="flex flex-col items-center gap-4 py-24 text-center">
+      <h1 className="font-display text-4xl tracking-tight">Person not found</h1>
+      <p className="text-muted-foreground">
+        The person you&apos;re looking for doesn&apos;t exist or may have been
+        removed.
+      </p>
+      <Link
+        href="/explore"
+        className="inline-flex h-9 items-center rounded-lg bg-primary px-4 text-sm font-medium text-primary-foreground transition-all hover:shadow-md hover:shadow-primary/20"
+      >
+        Explore titles
+      </Link>
+    </div>
+  );
+}

app/(pages)/person/[id]/page.tsx

@@ -0,0 +1,57 @@
+import { eq } from "drizzle-orm";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { getSession } from "@/lib/auth/session";
+import { db } from "@/lib/db/client";
+import { persons } from "@/lib/db/schema";
+import {
+  getLocalFilmography,
+  getOrFetchPerson,
+  getOrFetchPersonByTmdbId,
+} from "@/lib/services/person";
+import { FilmographyGrid } from "./_components/filmography-grid";
+import { PersonHero } from "./_components/person-hero";
+
+const TMDB_PATTERN = /^tmdb-(\d+)$/;
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}): Promise<Metadata> {
+  const { id } = await params;
+  if (TMDB_PATTERN.test(id)) return { title: "Sofa" };
+
+  const person = db.select().from(persons).where(eq(persons.id, id)).get();
+  if (!person) return { title: "Not Found — Sofa" };
+
+  return {
+    title: `${person.name} — Sofa`,
+    description: person.biography?.slice(0, 160),
+  };
+}
+
+export default async function PersonDetailPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  await getSession();
+
+  const tmdbMatch = TMDB_PATTERN.exec(id);
+  const person = tmdbMatch
+    ? await getOrFetchPersonByTmdbId(Number(tmdbMatch[1]))
+    : await getOrFetchPerson(id);
+
+  if (!person) notFound();
+
+  const filmography = getLocalFilmography(person.id);
+
+  return (
+    <div className="space-y-10">
+      <PersonHero person={person} />
+      <FilmographyGrid credits={filmography} />
+    </div>
+  );
+}

app/(pages)/titles/[id]/_components/cast-carousel.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { IconUser, IconUsers } from "@tabler/icons-react";
+import { WheelGesturesPlugin } from "embla-carousel-wheel-gestures";
+import { motion } from "motion/react";
+import Image from "next/image";
+import Link from "next/link";
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+} from "@/components/ui/carousel";
+import type { CastMember } from "@/lib/types/title";
+
+const staggerContainer = {
+  hidden: {},
+  visible: { transition: { staggerChildren: 0.04 } },
+};
+
+const staggerItem = {
+  hidden: { opacity: 0, y: 12, scale: 0.98 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    scale: 1,
+    transition: { type: "spring" as const, stiffness: 300, damping: 24 },
+  },
+};
+
+interface CastCarouselProps {
+  actors: CastMember[];
+  crew: CastMember[];
+  titleType: "movie" | "tv";
+}
+
+export function CastCarousel({ actors, crew, titleType }: CastCarouselProps) {
+  return (
+    <section className="space-y-4">
+      <div className="flex items-center gap-2">
+        <IconUsers className="size-5 text-primary" />
+        <h2 className="font-display text-xl tracking-tight">Cast</h2>
+      </div>
+
+      {actors.length > 0 && (
+        <motion.div
+          variants={staggerContainer}
+          initial="hidden"
+          animate="visible"
+        >
+          <Carousel
+            opts={{
+              align: "start",
+              dragFree: true,
+              containScroll: "trimSnaps",
+            }}
+            plugins={[WheelGesturesPlugin({ forceWheelAxis: "x" })]}
+            className="-mx-4 sm:-mx-0"
+          >
+            <CarouselContent className="px-4 sm:px-0">
+              {actors.map((member) => (
+                <CarouselItem
+                  key={member.id}
+                  className="w-[100px] shrink-0 basis-auto pl-4 sm:w-[120px]"
+                >
+                  <motion.div variants={staggerItem}>
+                    <Link
+                      href={`/person/${member.personId}`}
+                      className="group flex flex-col items-center gap-2"
+                    >
+                      <div className="size-20 overflow-hidden rounded-full ring-1 ring-white/10 transition-all group-hover:ring-primary/25 sm:size-24">
+                        {member.profilePath ? (
+                          <Image
+                            src={member.profilePath}
+                            alt={member.name}
+                            width={96}
+                            height={96}
+                            className="h-full w-full object-cover transition-transform group-hover:scale-105"
+                          />
+                        ) : (
+                          <div className="flex h-full w-full items-center justify-center bg-gradient-to-br from-muted to-muted/50">
+                            <IconUser className="size-8 text-muted-foreground/50" />
+                          </div>
+                        )}
+                      </div>
+                      <div className="w-full text-center">
+                        <p className="truncate text-xs font-medium">
+                          {member.name}
+                        </p>
+                        {member.character && (
+                          <p className="truncate text-[10px] text-muted-foreground">
+                            {member.character}
+                          </p>
+                        )}
+                        {titleType === "tv" && member.episodeCount && (
+                          <p className="text-[10px] text-muted-foreground/70">
+                            {member.episodeCount} ep
+                            {member.episodeCount !== 1 ? "s" : ""}
+                          </p>
+                        )}
+                      </div>
+                    </Link>
+                  </motion.div>
+                </CarouselItem>
+              ))}
+            </CarouselContent>
+          </Carousel>
+        </motion.div>
+      )}
+
+      {crew.length > 0 && (
+        <div className="flex flex-wrap gap-x-3 gap-y-1 text-sm text-muted-foreground">
+          {crew.map((member) => (
+            <Link
+              key={member.id}
+              href={`/person/${member.personId}`}
+              className="transition-colors hover:text-foreground"
+            >
+              {member.name}
+              <span className="ml-1 text-xs text-muted-foreground/60">
+                ({member.job})
+              </span>
+            </Link>
+          ))}
+        </div>
+      )}
+    </section>
+  );
+}

app/(pages)/titles/[id]/_components/title-cast.tsx

@@ -0,0 +1,16 @@
+import type { CastMember } from "@/lib/types/title";
+import { CastCarousel } from "./cast-carousel";
+
+interface TitleCastProps {
+  cast: CastMember[];
+  titleType: "movie" | "tv";
+}
+
+export function TitleCast({ cast, titleType }: TitleCastProps) {
+  const actors = cast.filter((c) => c.department === "Acting");
+  const crew = cast.filter((c) => c.department !== "Acting");
+
+  if (actors.length === 0 && crew.length === 0) return null;
+
+  return <CastCarousel actors={actors} crew={crew} titleType={titleType} />;
+}

app/(pages)/titles/[id]/page.tsx

@@ -12,6 +12,7 @@ import { tmdbImageUrl } from "@/lib/tmdb/image";
 import { getTitleThemeStyle } from "@/lib/utils/title-theme";
 import { TitleActions } from "./_components/title-actions";
 import { TitleAvailability } from "./_components/title-availability";
+import { TitleCast } from "./_components/title-cast";
 import { TitleHero } from "./_components/title-hero";
 import { TitleKeyboardShortcuts } from "./_components/title-keyboard-shortcuts";
 import { TitleProvider } from "./_components/title-provider";
@@ -70,7 +71,7 @@ export default async function TitleDetailPage({
   ]);
   if (!result) notFound();
 
-  const { title, seasons, availability } = result;
+  const { title, seasons, availability, cast } = result;
 
   const themeStyle = getTitleThemeStyle(title.colorPalette);
 
@@ -93,6 +94,8 @@ export default async function TitleDetailPage({
           <TitleAvailability availability={availability} />
         </TitleHero>
 
+        <TitleCast cast={cast} titleType={title.type} />
+
         {title.type === "tv" && seasons.length > 0 && <TitleSeasons />}
 
         <TitleKeyboardShortcuts />

app/api/images/[...path]/route.ts

@@ -11,6 +11,7 @@ const VALID_CATEGORIES = new Set<ImageCategory>([
   "backdrops",
   "stills",
   "logos",
+  "profiles",
 ]);
 
 const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";

app/api/person/[id]/filmography/route.ts

@@ -0,0 +1,19 @@
+import { headers } from "next/headers";
+import { type NextRequest, NextResponse } from "next/server";
+import { auth } from "@/lib/auth/server";
+import { fetchFullFilmography } from "@/lib/services/person";
+
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const session = await auth.api.getSession({ headers: await headers() });
+  if (!session) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const { id } = await params;
+  const filmography = await fetchFullFilmography(id);
+
+  return NextResponse.json({ filmography });
+}

app/api/person/[id]/route.ts

@@ -0,0 +1,35 @@
+import { headers } from "next/headers";
+import { type NextRequest, NextResponse } from "next/server";
+import { auth } from "@/lib/auth/server";
+import {
+  getLocalFilmography,
+  getOrFetchPerson,
+  getOrFetchPersonByTmdbId,
+} from "@/lib/services/person";
+
+const TMDB_PATTERN = /^tmdb-(\d+)$/;
+
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const session = await auth.api.getSession({ headers: await headers() });
+  if (!session) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const { id } = await params;
+
+  const tmdbMatch = TMDB_PATTERN.exec(id);
+  const person = tmdbMatch
+    ? await getOrFetchPersonByTmdbId(Number(tmdbMatch[1]))
+    : await getOrFetchPerson(id);
+
+  if (!person) {
+    return NextResponse.json({ error: "Person not found" }, { status: 404 });
+  }
+
+  const filmography = getLocalFilmography(person.id);
+
+  return NextResponse.json({ person, filmography });
+}

app/api/search/route.ts

@@ -2,7 +2,12 @@ import { headers } from "next/headers";
 import { type NextRequest, NextResponse } from "next/server";
 import { auth } from "@/lib/auth/server";
 import { isTmdbConfigured } from "@/lib/config";
-import { searchMovies, searchMulti, searchTv } from "@/lib/tmdb/client";
+import {
+  searchMovies,
+  searchMulti,
+  searchPerson,
+  searchTv,
+} from "@/lib/tmdb/client";
 import { tmdbImageUrl } from "@/lib/tmdb/image";
 import type { TmdbSearchResponse } from "@/lib/tmdb/types";
 
@@ -26,12 +31,14 @@ export async function GET(req: NextRequest) {
 
   const query = req.nextUrl.searchParams.get("query")?.trim();
   const rawType = req.nextUrl.searchParams.get("type");
-  const type: "movie" | "tv" | null =
-    rawType === "movie" || rawType === "tv" ? rawType : null;
+  const type: "movie" | "tv" | "person" | null =
+    rawType === "movie" || rawType === "tv" || rawType === "person"
+      ? rawType
+      : null;
 
   if (rawType && !type) {
     return NextResponse.json(
-      { error: "type must be movie or tv" },
+      { error: "type must be movie, tv, or person" },
       { status: 400 },
     );
   }
@@ -42,8 +49,26 @@ export async function GET(req: NextRequest) {
       { status: 400 },
     );
 
-  let results: TmdbSearchResponse;
   try {
+    // Person-specific search
+    if (type === "person") {
+      const personResults = await searchPerson(query);
+      return NextResponse.json({
+        results: personResults.results.map((r) => ({
+          tmdbId: r.id,
+          type: "person" as const,
+          title: r.name,
+          profilePath: tmdbImageUrl(r.profile_path, "w185"),
+          knownForDepartment: r.known_for_department,
+          knownFor: r.known_for
+            ?.slice(0, 3)
+            .map((k) => k.title ?? k.name)
+            .filter(Boolean),
+        })),
+      });
+    }
+
+    let results: TmdbSearchResponse;
     if (type === "movie") {
       results = await searchMovies(query);
     } else if (type === "tv") {
@@ -51,22 +76,24 @@ export async function GET(req: NextRequest) {
     } else {
       results = await searchMulti(query);
     }
-  } catch {
-    return NextResponse.json(
-      { error: "Failed to fetch search results" },
-      { status: 502 },
-    );
-  }
 
-  // Filter out person results for multi search
-  const filtered =
-    type === "movie" || type === "tv"
-      ? results.results
-      : results.results.filter((r) => r.media_type !== "person");
-
-  return NextResponse.json({
-    results: filtered
+    const mapped = results.results
       .map((r) => {
+        // Include person results from multi search
+        if (r.media_type === "person") {
+          return {
+            tmdbId: r.id,
+            type: "person" as const,
+            title: r.name ?? "Unknown",
+            posterPath: null,
+            profilePath: tmdbImageUrl(r.poster_path, "w185"),
+            overview: "",
+            releaseDate: null,
+            popularity: r.popularity,
+            voteAverage: 0,
+          };
+        }
+
         const mediaType =
           r.media_type === "movie" || r.media_type === "tv"
             ? r.media_type
@@ -84,6 +111,13 @@ export async function GET(req: NextRequest) {
           voteAverage: r.vote_average,
         };
       })
-      .filter((r): r is NonNullable<typeof r> => r !== null),
-  });
+      .filter((r): r is NonNullable<typeof r> => r !== null);
+
+    return NextResponse.json({ results: mapped });
+  } catch {
+    return NextResponse.json(
+      { error: "Failed to fetch search results" },
+      { status: 502 },
+    );
+  }
 }