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 },
+    );
+  }
 }

components/command-palette.tsx

@@ -6,6 +6,7 @@ import {
   IconKeyboard,
   IconMovie,
   IconSearch,
+  IconUser,
   IconX,
 } from "@tabler/icons-react";
 import { useHotkey, useHotkeySequence } from "@tanstack/react-hotkeys";
@@ -89,7 +90,11 @@ export function CommandPalette() {
   const handleSelect = useCallback(
     (result: SearchResult) => {
       setCommandPaletteOpen(false);
-      router.push(`/titles/tmdb-${result.tmdbId}-${result.type}`);
+      if (result.type === "person") {
+        router.push(`/person/tmdb-${result.tmdbId}`);
+      } else {
+        router.push(`/titles/tmdb-${result.tmdbId}-${result.type}`);
+      }
     },
     [router, setCommandPaletteOpen],
   );
@@ -168,35 +173,62 @@ export function CommandPalette() {
                       onSelect={() => handleSelect(r)}
                       className="flex items-center gap-3 py-2"
                     >
-                      <div className="h-12 w-8 shrink-0 overflow-hidden rounded bg-muted">
-                        {r.posterPath ? (
-                          <Image
-                            src={r.posterPath as string}
-                            alt={r.title}
-                            width={32}
-                            height={48}
-                            className="h-full w-full object-cover"
-                          />
-                        ) : (
-                          <div className="flex h-full items-center justify-center text-[8px] text-muted-foreground">
-                            ?
-                          </div>
-                        )}
-                      </div>
+                      {r.type === "person" ? (
+                        <div className="size-10 shrink-0 overflow-hidden rounded-full bg-muted">
+                          {r.profilePath ? (
+                            <Image
+                              src={r.profilePath as string}
+                              alt={r.title}
+                              width={40}
+                              height={40}
+                              className="h-full w-full object-cover"
+                            />
+                          ) : (
+                            <div className="flex h-full items-center justify-center">
+                              <IconUser className="size-4 text-muted-foreground" />
+                            </div>
+                          )}
+                        </div>
+                      ) : (
+                        <div className="h-12 w-8 shrink-0 overflow-hidden rounded bg-muted">
+                          {r.posterPath ? (
+                            <Image
+                              src={r.posterPath as string}
+                              alt={r.title}
+                              width={32}
+                              height={48}
+                              className="h-full w-full object-cover"
+                            />
+                          ) : (
+                            <div className="flex h-full items-center justify-center text-[8px] text-muted-foreground">
+                              ?
+                            </div>
+                          )}
+                        </div>
+                      )}
                       <div className="min-w-0 flex-1">
                         <p className="truncate text-xs font-medium">
                           {r.title}
                         </p>
                         <div className="flex items-center gap-1.5 text-[10px] text-muted-foreground">
-                          {r.type === "movie" ? (
+                          {r.type === "person" ? (
+                            <IconUser className="size-[11px]" />
+                          ) : r.type === "movie" ? (
                             <IconMovie className="size-[11px]" />
                           ) : (
                             <IconDeviceTv className="size-[11px]" />
                           )}
                           <span className="uppercase">{r.type}</span>
-                          {r.releaseDate && (
+                          {r.type !== "person" && r.releaseDate && (
                             <span>{r.releaseDate.slice(0, 4)}</span>
                           )}
+                          {r.type === "person" &&
+                            r.knownFor &&
+                            r.knownFor.length > 0 && (
+                              <span className="truncate">
+                                {r.knownFor.join(", ")}
+                              </span>
+                            )}
                         </div>
                       </div>
                     </CommandItem>

components/skeletons.tsx

@@ -82,6 +82,50 @@ export function TitleGridSectionSkeleton() {
   );
 }
 
+export function CastSkeleton() {
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-2">
+        <Skeleton className="size-5 rounded" />
+        <Skeleton className="h-6 w-20" />
+      </div>
+      <div className="flex gap-4 overflow-hidden">
+        {Array.from({ length: 8 }).map((_, i) => (
+          // biome-ignore lint/suspicious/noArrayIndexKey: static skeleton placeholders
+          <div key={i} className="flex shrink-0 flex-col items-center gap-2">
+            <Skeleton className="size-20 rounded-full sm:size-24" />
+            <Skeleton className="h-3 w-16" />
+            <Skeleton className="h-2.5 w-12" />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function PersonDetailSkeleton() {
+  return (
+    <div className="space-y-10">
+      <div className="flex flex-col gap-6 sm:flex-row sm:gap-8">
+        <Skeleton className="size-40 shrink-0 rounded-2xl sm:size-56" />
+        <div className="flex-1 space-y-4">
+          <Skeleton className="h-10 w-2/3 sm:h-14" />
+          <Skeleton className="h-5 w-24 rounded-full" />
+          <div className="flex gap-4">
+            <Skeleton className="h-4 w-28" />
+            <Skeleton className="h-4 w-36" />
+          </div>
+          <div className="space-y-2">
+            <Skeleton className="h-4 w-full" />
+            <Skeleton className="h-4 w-5/6" />
+            <Skeleton className="h-4 w-4/6" />
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
 export function RecommendationsSkeleton() {
   return (
     <div className="space-y-4">

drizzle/20260305193509_overjoyed_pestilence/migration.sql

@@ -0,0 +1,34 @@
+CREATE TABLE `persons` (
+	`id` text PRIMARY KEY,
+	`tmdbId` integer NOT NULL,
+	`name` text NOT NULL,
+	`biography` text,
+	`birthday` text,
+	`deathday` text,
+	`placeOfBirth` text,
+	`profilePath` text,
+	`knownForDepartment` text,
+	`popularity` real,
+	`imdbId` text,
+	`lastFetchedAt` integer
+);
+--> statement-breakpoint
+CREATE TABLE `titleCast` (
+	`id` text PRIMARY KEY,
+	`titleId` text NOT NULL,
+	`personId` text NOT NULL,
+	`character` text,
+	`department` text DEFAULT 'Acting' NOT NULL,
+	`job` text,
+	`displayOrder` integer DEFAULT 0 NOT NULL,
+	`episodeCount` integer,
+	`lastFetchedAt` integer,
+	CONSTRAINT `fk_titleCast_titleId_titles_id_fk` FOREIGN KEY (`titleId`) REFERENCES `titles`(`id`) ON DELETE CASCADE,
+	CONSTRAINT `fk_titleCast_personId_persons_id_fk` FOREIGN KEY (`personId`) REFERENCES `persons`(`id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `persons_tmdbId_unique` ON `persons` (`tmdbId`);--> statement-breakpoint
+CREATE INDEX `persons_name` ON `persons` (`name`);--> statement-breakpoint
+CREATE UNIQUE INDEX `titleCast_unique` ON `titleCast` (`titleId`,`personId`,`department`,`character`);--> statement-breakpoint
+CREATE INDEX `titleCast_titleId_displayOrder` ON `titleCast` (`titleId`,`displayOrder`);--> statement-breakpoint
+CREATE INDEX `titleCast_personId` ON `titleCast` (`personId`);

hooks/use-search.ts

@@ -4,11 +4,14 @@ import { fetcher } from "@/lib/swr/fetcher";
 interface SearchResponse {
   results: {
     tmdbId: number;
-    type: "movie" | "tv";
+    type: "movie" | "tv" | "person";
     title: string;
     posterPath: string | null;
+    profilePath?: string | null;
     releaseDate: string | null;
     voteAverage: number;
+    knownFor?: string[];
+    knownForDepartment?: string;
   }[];
 }
 

lib/cron.ts

@@ -5,6 +5,7 @@ import {
   availabilityOffers,
   cronRuns,
   seasons,
+  titleCast,
   titles,
   userTitleStatus,
 } from "@/lib/db/schema";
@@ -15,9 +16,11 @@ import {
   ensureBackupDir,
   pruneBackups,
 } from "@/lib/services/backup";
+import { refreshCredits } from "@/lib/services/credits";
 import {
   cacheEpisodeStills,
   cacheImagesForTitle,
+  cacheProfilePhotos,
   cacheProviderLogos,
   imageCacheEnabled,
 } from "@/lib/services/image-cache";
@@ -251,6 +254,7 @@ async function cacheImagesJob() {
         cacheImagesForTitle(titleId),
         cacheEpisodeStills(titleId),
         cacheProviderLogos(titleId),
+        cacheProfilePhotos(titleId),
       ]);
     } catch (err) {
       log.warn(`Failed to cache images for title ${titleId}:`, err);
@@ -259,6 +263,31 @@ async function cacheImagesJob() {
   }
 }
 
+// Refresh credits for library titles where cast is stale or missing
+async function refreshCreditsJob() {
+  const libraryIds = getLibraryTitleIds();
+  log.debug(`Checking credits for ${libraryIds.length} library titles`);
+  const stale = new Date(Date.now() - 30 * DAY);
+
+  for (const titleId of libraryIds) {
+    const castEntry = db
+      .select()
+      .from(titleCast)
+      .where(eq(titleCast.titleId, titleId))
+      .limit(1)
+      .get();
+
+    const needsRefresh =
+      !castEntry ||
+      (castEntry.lastFetchedAt && castEntry.lastFetchedAt < stale);
+
+    if (needsRefresh) {
+      await refreshCredits(titleId);
+      await Bun.sleep(RATE_LIMIT_MS);
+    }
+  }
+}
+
 async function scheduledBackupJob() {
   const enabled = getSetting("scheduledBackups");
   if (enabled !== "true") {
@@ -324,6 +353,7 @@ export function startJobs() {
   schedule("refreshRecommendations", "0 */12 * * *", refreshRecommendationsJob);
   schedule("refreshTvChildren", "30 */12 * * *", refreshTvChildrenJob);
   schedule("cacheImages", "0 1,13 * * *", cacheImagesJob);
+  schedule("refreshCredits", "0 2 * * *", refreshCreditsJob);
   schedule("updateCheck", "0 */6 * * *", async () => {
     await performUpdateCheck();
   });

lib/db/schema.ts

@@ -289,6 +289,62 @@ export const titleRecommendations = sqliteTable(
   ],
 );
 
+// ─── Persons & Cast ─────────────────────────────────────────────────
+
+export const persons = sqliteTable(
+  "persons",
+  {
+    id: uuidPk(),
+    tmdbId: int("tmdbId").notNull(),
+    name: text("name").notNull(),
+    biography: text("biography"),
+    birthday: text("birthday"),
+    deathday: text("deathday"),
+    placeOfBirth: text("placeOfBirth"),
+    profilePath: text("profilePath"),
+    knownForDepartment: text("knownForDepartment"),
+    popularity: real("popularity"),
+    imdbId: text("imdbId"),
+    lastFetchedAt: int("lastFetchedAt", { mode: "timestamp" }),
+  },
+  (table) => [
+    uniqueIndex("persons_tmdbId_unique").on(table.tmdbId),
+    index("persons_name").on(table.name),
+  ],
+);
+
+export const titleCast = sqliteTable(
+  "titleCast",
+  {
+    id: uuidPk(),
+    titleId: text("titleId")
+      .notNull()
+      .references(() => titles.id, { onDelete: "cascade" }),
+    personId: text("personId")
+      .notNull()
+      .references(() => persons.id, { onDelete: "cascade" }),
+    character: text("character"),
+    department: text("department").notNull().default("Acting"),
+    job: text("job"),
+    displayOrder: int("displayOrder").notNull().default(0),
+    episodeCount: int("episodeCount"),
+    lastFetchedAt: int("lastFetchedAt", { mode: "timestamp" }),
+  },
+  (table) => [
+    uniqueIndex("titleCast_unique").on(
+      table.titleId,
+      table.personId,
+      table.department,
+      table.character,
+    ),
+    index("titleCast_titleId_displayOrder").on(
+      table.titleId,
+      table.displayOrder,
+    ),
+    index("titleCast_personId").on(table.personId),
+  ],
+);
+
 // ─── Webhook Connections ─────────────────────────────────────────────
 
 export const webhookConnections = sqliteTable(

lib/services/credits.ts

@@ -0,0 +1,241 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/lib/db/client";
+import { persons, titleCast, titles } from "@/lib/db/schema";
+import { createLogger } from "@/lib/logger";
+import { getMovieCredits, getTvAggregateCredits } from "@/lib/tmdb/client";
+import { tmdbImageUrl } from "@/lib/tmdb/image";
+import type { CastMember } from "@/lib/types/title";
+import { cacheProfilePhotos, imageCacheEnabled } from "./image-cache";
+
+const log = createLogger("credits");
+
+const NOTABLE_DEPARTMENTS = new Set([
+  "Director",
+  "Writer",
+  "Screenplay",
+  "Creator",
+  "Executive Producer",
+]);
+
+function upsertPerson(
+  tmdbId: number,
+  name: string,
+  profilePath: string | null,
+  popularity?: number,
+): string {
+  const existing = db
+    .select()
+    .from(persons)
+    .where(eq(persons.tmdbId, tmdbId))
+    .get();
+  if (existing) return existing.id;
+
+  const row = db
+    .insert(persons)
+    .values({
+      tmdbId,
+      name,
+      profilePath,
+      popularity: popularity ?? null,
+    })
+    .onConflictDoNothing()
+    .returning()
+    .get();
+
+  if (row) return row.id;
+
+  // Race condition: another insert beat us
+  const found = db
+    .select()
+    .from(persons)
+    .where(eq(persons.tmdbId, tmdbId))
+    .get();
+  // biome-ignore lint/style/noNonNullAssertion: guaranteed by onConflictDoNothing + prior existence check
+  return found!.id;
+}
+
+function upsertTitleCast(
+  titleId: string,
+  personId: string,
+  character: string | null,
+  department: string,
+  job: string | null,
+  displayOrder: number,
+  episodeCount: number | null,
+) {
+  const now = new Date();
+  db.insert(titleCast)
+    .values({
+      titleId,
+      personId,
+      character,
+      department,
+      job,
+      displayOrder,
+      episodeCount,
+      lastFetchedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [
+        titleCast.titleId,
+        titleCast.personId,
+        titleCast.department,
+        titleCast.character,
+      ],
+      set: {
+        job,
+        displayOrder,
+        episodeCount,
+        lastFetchedAt: now,
+      },
+    })
+    .run();
+}
+
+export async function refreshCredits(titleId: string) {
+  const title = db.select().from(titles).where(eq(titles.id, titleId)).get();
+  if (!title) return;
+
+  log.debug(`Refreshing credits for "${title.title}" (${title.type})`);
+
+  try {
+    if (title.type === "movie") {
+      const credits = await getMovieCredits(title.tmdbId);
+
+      // Top 20 cast
+      const castSlice = credits.cast.slice(0, 20);
+      for (let i = 0; i < castSlice.length; i++) {
+        const c = castSlice[i];
+        const personId = upsertPerson(
+          c.id,
+          c.name,
+          c.profile_path,
+          c.popularity,
+        );
+        upsertTitleCast(
+          titleId,
+          personId,
+          c.character,
+          "Acting",
+          null,
+          i,
+          null,
+        );
+      }
+
+      // Notable crew
+      const seenCrew = new Set<string>();
+      let crewOrder = 100;
+      for (const c of credits.crew) {
+        if (!NOTABLE_DEPARTMENTS.has(c.job)) continue;
+        const key = `${c.id}-${c.job}`;
+        if (seenCrew.has(key)) continue;
+        seenCrew.add(key);
+
+        const personId = upsertPerson(
+          c.id,
+          c.name,
+          c.profile_path,
+          c.popularity,
+        );
+        upsertTitleCast(
+          titleId,
+          personId,
+          null,
+          c.department,
+          c.job,
+          crewOrder++,
+          null,
+        );
+      }
+    } else {
+      const credits = await getTvAggregateCredits(title.tmdbId);
+
+      // Top 20 cast
+      const castSlice = credits.cast.slice(0, 20);
+      for (let i = 0; i < castSlice.length; i++) {
+        const c = castSlice[i];
+        const personId = upsertPerson(
+          c.id,
+          c.name,
+          c.profile_path,
+          c.popularity,
+        );
+        const character = c.roles?.[0]?.character ?? null;
+        upsertTitleCast(
+          titleId,
+          personId,
+          character,
+          "Acting",
+          null,
+          i,
+          c.total_episode_count,
+        );
+      }
+
+      // Notable crew
+      const seenCrew = new Set<string>();
+      let crewOrder = 100;
+      for (const c of credits.crew) {
+        for (const j of c.jobs) {
+          if (!NOTABLE_DEPARTMENTS.has(j.job)) continue;
+          const key = `${c.id}-${j.job}`;
+          if (seenCrew.has(key)) continue;
+          seenCrew.add(key);
+
+          const personId = upsertPerson(
+            c.id,
+            c.name,
+            c.profile_path,
+            c.popularity,
+          );
+          upsertTitleCast(
+            titleId,
+            personId,
+            null,
+            c.department,
+            j.job,
+            crewOrder++,
+            j.episode_count,
+          );
+        }
+      }
+    }
+
+    log.debug(`Credits refreshed for "${title.title}"`);
+
+    if (imageCacheEnabled()) {
+      cacheProfilePhotos(titleId).catch((err) =>
+        log.debug("Profile photo caching failed:", err),
+      );
+    }
+  } catch (err) {
+    log.error(`Failed to refresh credits for title ${titleId}:`, err);
+  }
+}
+
+export function getCastForTitle(titleId: string): CastMember[] {
+  const rows = db
+    .select({
+      id: titleCast.id,
+      personId: titleCast.personId,
+      name: persons.name,
+      character: titleCast.character,
+      department: titleCast.department,
+      job: titleCast.job,
+      displayOrder: titleCast.displayOrder,
+      episodeCount: titleCast.episodeCount,
+      profilePath: persons.profilePath,
+      tmdbId: persons.tmdbId,
+    })
+    .from(titleCast)
+    .innerJoin(persons, eq(titleCast.personId, persons.id))
+    .where(eq(titleCast.titleId, titleId))
+    .orderBy(titleCast.displayOrder)
+    .all();
+
+  return rows.map((r) => ({
+    ...r,
+    profilePath: tmdbImageUrl(r.profilePath, "w185"),
+  }));
+}

lib/services/image-cache.ts

@@ -2,18 +2,31 @@ import { mkdir, rename } from "node:fs/promises";
 import path from "node:path";
 import { eq } from "drizzle-orm";
 import { db } from "@/lib/db/client";
-import { availabilityOffers, episodes, seasons, titles } from "@/lib/db/schema";
+import {
+  availabilityOffers,
+  episodes,
+  persons,
+  seasons,
+  titleCast,
+  titles,
+} from "@/lib/db/schema";
 import { createLogger } from "@/lib/logger";
 
 const log = createLogger("image-cache");
 
-export type ImageCategory = "posters" | "backdrops" | "stills" | "logos";
+export type ImageCategory =
+  | "posters"
+  | "backdrops"
+  | "stills"
+  | "logos"
+  | "profiles";
 
 const CATEGORY_SIZES: Record<ImageCategory, string> = {
   posters: "w500",
   backdrops: "w1280",
   stills: "w1280",
   logos: "w92",
+  profiles: "w185",
 };
 
 const IMAGE_BASE_URL =
@@ -218,3 +231,28 @@ export async function cacheProviderLogos(titleId: string) {
   }
   await Promise.allSettled(tasks);
 }
+
+export async function cacheProfilePhotos(titleId: string) {
+  const castRows = db
+    .select({ profilePath: persons.profilePath })
+    .from(titleCast)
+    .innerJoin(persons, eq(titleCast.personId, persons.id))
+    .where(eq(titleCast.titleId, titleId))
+    .all();
+
+  const tasks: Promise<unknown>[] = [];
+  const seen = new Set<string>();
+  for (const row of castRows) {
+    if (row.profilePath) {
+      const basename = path.basename(row.profilePath);
+      if (!seen.has(basename) && !(await isImageCached("profiles", basename))) {
+        seen.add(basename);
+        tasks.push(downloadAndCacheImage(row.profilePath, "profiles"));
+      }
+    }
+  }
+  if (tasks.length > 0) {
+    log.debug(`Caching ${tasks.length} profile photos for title ${titleId}`);
+  }
+  await Promise.allSettled(tasks);
+}

lib/services/metadata.ts

@@ -20,12 +20,14 @@ import { tmdbImageUrl } from "@/lib/tmdb/image";
 import type { TmdbVideo } from "@/lib/tmdb/types";
 import type {
   AvailabilityOffer,
+  CastMember,
   Episode,
   ResolvedTitle,
   Season,
 } from "@/lib/types/title";
 import { refreshAvailability } from "./availability";
 import { extractAndStoreColors, parseColorPalette } from "./colors";
+import { getCastForTitle, refreshCredits } from "./credits";
 import {
   cacheEpisodeStills,
   cacheImagesForTitle,
@@ -83,6 +85,9 @@ export async function importTitle(
             extractAndStoreColors(existing.id, show.poster_path).catch((err) =>
               log.debug("Color extraction failed:", err),
             ),
+            refreshCredits(existing.id).catch((err) =>
+              log.debug("Credits enrichment failed:", err),
+            ),
           ]);
         } else {
           refreshAvailability(existing.id).catch((err) =>
@@ -91,6 +96,9 @@ export async function importTitle(
           refreshRecommendations(existing.id).catch((err) =>
             log.debug("Recommendations enrichment failed:", err),
           );
+          refreshCredits(existing.id).catch((err) =>
+            log.debug("Credits enrichment failed:", err),
+          );
         }
         if (imageCacheEnabled()) {
           cacheImagesForTitle(existing.id).catch((err) =>
@@ -140,6 +148,9 @@ export async function importTitle(
         extractAndStoreColors(row.id, movie.poster_path).catch((err) =>
           log.debug("Color extraction failed:", err),
         ),
+        refreshCredits(row.id).catch((err) =>
+          log.debug("Credits enrichment failed:", err),
+        ),
       ]);
     } else {
       refreshAvailability(row.id).catch((err) =>
@@ -151,6 +162,9 @@ export async function importTitle(
       extractAndStoreColors(row.id, movie.poster_path).catch((err) =>
         log.debug("Color extraction failed:", err),
       );
+      refreshCredits(row.id).catch((err) =>
+        log.debug("Credits enrichment failed:", err),
+      );
     }
     refreshTrailer(row.id).catch((err) =>
       log.debug("Trailer enrichment failed:", err),
@@ -197,6 +211,9 @@ export async function importTitle(
       extractAndStoreColors(row.id, show.poster_path).catch((err) =>
         log.debug("Color extraction failed:", err),
       ),
+      refreshCredits(row.id).catch((err) =>
+        log.debug("Credits enrichment failed:", err),
+      ),
     ]);
   } else {
     refreshAvailability(row.id).catch((err) =>
@@ -208,6 +225,9 @@ export async function importTitle(
     extractAndStoreColors(row.id, show.poster_path).catch((err) =>
       log.debug("Color extraction failed:", err),
     );
+    refreshCredits(row.id).catch((err) =>
+      log.debug("Credits enrichment failed:", err),
+    );
   }
   refreshTrailer(row.id).catch((err) =>
     log.debug("Trailer enrichment failed:", err),
@@ -277,6 +297,9 @@ export async function refreshTitle(titleId: string) {
     refreshTrailer(updated.id).catch((err) =>
       log.debug("Trailer enrichment failed:", err),
     );
+    refreshCredits(updated.id).catch((err) =>
+      log.debug("Credits enrichment failed:", err),
+    );
     if (imageCacheEnabled()) {
       cacheImagesForTitle(updated.id).catch((err) =>
         log.debug("Image caching failed:", err),
@@ -516,6 +539,7 @@ export async function getTitleWithChildren(id: string): Promise<{
   title: ResolvedTitle;
   seasons: Season[];
   availability: AvailabilityOffer[];
+  cast: CastMember[];
 } | null> {
   let title = db.select().from(titles).where(eq(titles.id, id)).get();
   if (!title) return null;
@@ -671,7 +695,9 @@ export async function getTitleWithChildren(id: string): Promise<{
     trailerVideoKey: title.trailerVideoKey,
   };
 
-  return { title: resolvedTitle, seasons: titleSeasons, availability };
+  const cast = getCastForTitle(id);
+
+  return { title: resolvedTitle, seasons: titleSeasons, availability, cast };
 }
 
 export function pickBestTrailer(videos: TmdbVideo[]): string | null {

lib/services/person.ts

@@ -0,0 +1,240 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/lib/db/client";
+import { persons, titleCast, titles } from "@/lib/db/schema";
+import { createLogger } from "@/lib/logger";
+import { getPersonCombinedCredits, getPersonDetails } from "@/lib/tmdb/client";
+import { tmdbImageUrl } from "@/lib/tmdb/image";
+import type { PersonCredit, ResolvedPerson } from "@/lib/types/title";
+
+const log = createLogger("person");
+
+export async function getOrFetchPerson(
+  personId: string,
+): Promise<ResolvedPerson | null> {
+  const person = db
+    .select()
+    .from(persons)
+    .where(eq(persons.id, personId))
+    .get();
+  if (!person) return null;
+
+  // Shell record — lazily hydrate from TMDB
+  if (!person.lastFetchedAt) {
+    try {
+      const details = await getPersonDetails(person.tmdbId);
+      db.update(persons)
+        .set({
+          name: details.name,
+          biography: details.biography || null,
+          birthday: details.birthday,
+          deathday: details.deathday,
+          placeOfBirth: details.place_of_birth,
+          profilePath: details.profile_path,
+          knownForDepartment: details.known_for_department,
+          popularity: details.popularity,
+          imdbId: details.imdb_id,
+          lastFetchedAt: new Date(),
+        })
+        .where(eq(persons.id, personId))
+        .run();
+
+      return {
+        id: person.id,
+        tmdbId: person.tmdbId,
+        name: details.name,
+        biography: details.biography || null,
+        birthday: details.birthday,
+        deathday: details.deathday,
+        placeOfBirth: details.place_of_birth,
+        profilePath: tmdbImageUrl(details.profile_path, "w185"),
+        knownForDepartment: details.known_for_department,
+        imdbId: details.imdb_id,
+      };
+    } catch (err) {
+      log.error(`Failed to hydrate person ${personId}:`, err);
+    }
+  }
+
+  return {
+    id: person.id,
+    tmdbId: person.tmdbId,
+    name: person.name,
+    biography: person.biography,
+    birthday: person.birthday,
+    deathday: person.deathday,
+    placeOfBirth: person.placeOfBirth,
+    profilePath: tmdbImageUrl(person.profilePath, "w185"),
+    knownForDepartment: person.knownForDepartment,
+    imdbId: person.imdbId,
+  };
+}
+
+export async function getOrFetchPersonByTmdbId(
+  tmdbId: number,
+): Promise<ResolvedPerson | null> {
+  const existing = db
+    .select()
+    .from(persons)
+    .where(eq(persons.tmdbId, tmdbId))
+    .get();
+
+  if (existing) {
+    return getOrFetchPerson(existing.id);
+  }
+
+  // Create from TMDB
+  try {
+    const details = await getPersonDetails(tmdbId);
+    const row = db
+      .insert(persons)
+      .values({
+        tmdbId,
+        name: details.name,
+        biography: details.biography || null,
+        birthday: details.birthday,
+        deathday: details.deathday,
+        placeOfBirth: details.place_of_birth,
+        profilePath: details.profile_path,
+        knownForDepartment: details.known_for_department,
+        popularity: details.popularity,
+        imdbId: details.imdb_id,
+        lastFetchedAt: new Date(),
+      })
+      .onConflictDoNothing()
+      .returning()
+      .get();
+
+    const person =
+      row ?? db.select().from(persons).where(eq(persons.tmdbId, tmdbId)).get();
+    if (!person) return null;
+
+    return {
+      id: person.id,
+      tmdbId: person.tmdbId,
+      name: person.name,
+      biography: person.biography,
+      birthday: person.birthday,
+      deathday: person.deathday,
+      placeOfBirth: person.placeOfBirth,
+      profilePath: tmdbImageUrl(person.profilePath, "w185"),
+      knownForDepartment: person.knownForDepartment,
+      imdbId: person.imdbId,
+    };
+  } catch (err) {
+    log.error(`Failed to fetch person TMDB ${tmdbId}:`, err);
+    return null;
+  }
+}
+
+export function getLocalFilmography(personId: string): PersonCredit[] {
+  const rows = db
+    .select({
+      titleId: titles.id,
+      tmdbId: titles.tmdbId,
+      type: titles.type,
+      title: titles.title,
+      posterPath: titles.posterPath,
+      releaseDate: titles.releaseDate,
+      firstAirDate: titles.firstAirDate,
+      voteAverage: titles.voteAverage,
+      character: titleCast.character,
+      department: titleCast.department,
+      job: titleCast.job,
+    })
+    .from(titleCast)
+    .innerJoin(titles, eq(titleCast.titleId, titles.id))
+    .where(eq(titleCast.personId, personId))
+    .all();
+
+  return rows.map((r) => ({
+    titleId: r.titleId,
+    tmdbId: r.tmdbId,
+    type: r.type as "movie" | "tv",
+    title: r.title,
+    posterPath: tmdbImageUrl(r.posterPath, "w500"),
+    releaseDate: r.releaseDate,
+    firstAirDate: r.firstAirDate,
+    voteAverage: r.voteAverage,
+    character: r.character,
+    department: r.department,
+    job: r.job,
+  }));
+}
+
+export async function fetchFullFilmography(
+  personId: string,
+): Promise<PersonCredit[]> {
+  const person = db
+    .select()
+    .from(persons)
+    .where(eq(persons.id, personId))
+    .get();
+  if (!person) return [];
+
+  const credits = await getPersonCombinedCredits(person.tmdbId);
+
+  const results: PersonCredit[] = [];
+
+  for (const c of credits.cast) {
+    const type = c.media_type;
+    if (type !== "movie" && type !== "tv") continue;
+
+    // Create shell title if not in DB
+    const existing = db
+      .select()
+      .from(titles)
+      .where(eq(titles.tmdbId, c.id))
+      .get();
+    let titleId: string;
+    if (existing) {
+      titleId = existing.id;
+    } else {
+      const row = db
+        .insert(titles)
+        .values({
+          tmdbId: c.id,
+          type,
+          title: c.title ?? c.name ?? "Unknown",
+          overview: c.overview,
+          releaseDate: c.release_date,
+          firstAirDate: c.first_air_date,
+          posterPath: c.poster_path,
+          backdropPath: c.backdrop_path,
+          popularity: c.popularity,
+          voteAverage: c.vote_average,
+          voteCount: c.vote_count,
+          lastFetchedAt: null,
+        })
+        .onConflictDoNothing()
+        .returning()
+        .get();
+      if (!row) {
+        const found = db
+          .select()
+          .from(titles)
+          .where(eq(titles.tmdbId, c.id))
+          .get();
+        if (!found) continue;
+        titleId = found.id;
+      } else {
+        titleId = row.id;
+      }
+    }
+
+    results.push({
+      titleId,
+      tmdbId: c.id,
+      type,
+      title: c.title ?? c.name ?? "Unknown",
+      posterPath: tmdbImageUrl(c.poster_path, "w500"),
+      releaseDate: c.release_date ?? null,
+      firstAirDate: c.first_air_date ?? null,
+      voteAverage: c.vote_average,
+      character: c.character ?? null,
+      department: "Acting",
+      job: null,
+    });
+  }
+
+  return results;
+}

lib/tmdb/client.ts

@@ -2,10 +2,15 @@ import { createLogger } from "@/lib/logger";
 import type {
   TmdbFindResult,
   TmdbGenreListResponse,
+  TmdbMovieCreditsResponse,
   TmdbMovieDetails,
+  TmdbPersonCombinedCredits,
+  TmdbPersonDetails,
+  TmdbPersonSearchResponse,
   TmdbRecommendationResponse,
   TmdbSearchResponse,
   TmdbSeasonDetails,
+  TmdbTvAggregateCreditsResponse,
   TmdbTvDetails,
   TmdbVideosResponse,
   TmdbWatchProviderResponse,
@@ -155,4 +160,33 @@ export async function findByExternalId(
   });
 }
 
+// ─── Person / Credits endpoints ─────────────────────────────────────
+
+export async function getMovieCredits(tmdbId: number) {
+  return tmdbFetch<TmdbMovieCreditsResponse>(`/movie/${tmdbId}/credits`);
+}
+
+export async function getTvAggregateCredits(tmdbId: number) {
+  return tmdbFetch<TmdbTvAggregateCreditsResponse>(
+    `/tv/${tmdbId}/aggregate_credits`,
+  );
+}
+
+export async function getPersonDetails(tmdbId: number) {
+  return tmdbFetch<TmdbPersonDetails>(`/person/${tmdbId}`);
+}
+
+export async function getPersonCombinedCredits(tmdbId: number) {
+  return tmdbFetch<TmdbPersonCombinedCredits>(
+    `/person/${tmdbId}/combined_credits`,
+  );
+}
+
+export async function searchPerson(query: string, page = 1) {
+  return tmdbFetch<TmdbPersonSearchResponse>("/search/person", {
+    query,
+    page: String(page),
+  });
+}
+
 export { tmdbImageUrl } from "./image";

lib/tmdb/image.ts

@@ -5,6 +5,7 @@ const IMAGE_BASE_URL =
 
 function sizeToCategory(size: string): ImageCategory {
   if (size === "w92") return "logos";
+  if (size === "w185") return "profiles";
   if (size === "w1280") return "backdrops";
   return "posters";
 }

lib/tmdb/types.ts

@@ -149,3 +149,91 @@ export interface TmdbGenre {
 export interface TmdbGenreListResponse {
   genres: TmdbGenre[];
 }
+
+// ─── Person / Credits types ─────────────────────────────────────────
+
+export interface TmdbCastMember {
+  id: number;
+  name: string;
+  profile_path: string | null;
+  character: string;
+  order: number;
+  popularity: number;
+}
+
+export interface TmdbCrewMember {
+  id: number;
+  name: string;
+  profile_path: string | null;
+  department: string;
+  job: string;
+  popularity: number;
+}
+
+export interface TmdbMovieCreditsResponse {
+  id: number;
+  cast: TmdbCastMember[];
+  crew: TmdbCrewMember[];
+}
+
+export interface TmdbTvAggregateCastMember {
+  id: number;
+  name: string;
+  profile_path: string | null;
+  roles: { character: string; episode_count: number }[];
+  total_episode_count: number;
+  order: number;
+  popularity: number;
+}
+
+export interface TmdbTvAggregateCrewMember {
+  id: number;
+  name: string;
+  profile_path: string | null;
+  jobs: { job: string; episode_count: number }[];
+  department: string;
+  total_episode_count: number;
+  popularity: number;
+}
+
+export interface TmdbTvAggregateCreditsResponse {
+  id: number;
+  cast: TmdbTvAggregateCastMember[];
+  crew: TmdbTvAggregateCrewMember[];
+}
+
+export interface TmdbPersonDetails {
+  id: number;
+  name: string;
+  biography: string;
+  birthday: string | null;
+  deathday: string | null;
+  place_of_birth: string | null;
+  profile_path: string | null;
+  known_for_department: string;
+  imdb_id: string | null;
+  also_known_as: string[];
+  popularity: number;
+}
+
+export interface TmdbPersonCombinedCredits {
+  id: number;
+  cast: (TmdbSearchResult & { character?: string; episode_count?: number })[];
+  crew: (TmdbSearchResult & { department?: string; job?: string })[];
+}
+
+export interface TmdbPersonSearchResult {
+  id: number;
+  name: string;
+  profile_path: string | null;
+  known_for_department: string;
+  popularity: number;
+  known_for: TmdbSearchResult[];
+}
+
+export interface TmdbPersonSearchResponse {
+  page: number;
+  results: TmdbPersonSearchResult[];
+  total_pages: number;
+  total_results: number;
+}

lib/types/title.ts

@@ -42,6 +42,46 @@ export interface ColorPalette {
   lightMuted: string | null;
 }
 
+export interface CastMember {
+  id: string;
+  personId: string;
+  name: string;
+  character: string | null;
+  department: string;
+  job: string | null;
+  displayOrder: number;
+  episodeCount: number | null;
+  profilePath: string | null;
+  tmdbId: number;
+}
+
+export interface ResolvedPerson {
+  id: string;
+  tmdbId: number;
+  name: string;
+  biography: string | null;
+  birthday: string | null;
+  deathday: string | null;
+  placeOfBirth: string | null;
+  profilePath: string | null;
+  knownForDepartment: string | null;
+  imdbId: string | null;
+}
+
+export interface PersonCredit {
+  titleId: string;
+  tmdbId: number;
+  type: "movie" | "tv";
+  title: string;
+  posterPath: string | null;
+  releaseDate: string | null;
+  firstAirDate: string | null;
+  voteAverage: number | null;
+  character: string | null;
+  department: string;
+  job: string | null;
+}
+
 export interface ResolvedTitle {
   id: string;
   tmdbId: number;