watchwhere 0.3.0 → 0.4.0

package/README.md

@@ -44,7 +44,7 @@ ww init
 ## commands
 
 ```
-ww <title>       search and show providers
+ww <title>       search a movie, show, or person
 ww init          set up region, subscriptions (and token, if not using proxy)
 ww subs          edit subscriptions
 ww lang          change UI language (en / tr)
@@ -54,6 +54,21 @@ ww --help
 ww --version
 ```
 
+## search by people
+
+sometimes you don't have a title in mind, you have a person. type a name:
+
+```bash
+ww paul thomas anderson   # films he directed
+ww daniel day-lewis       # films he's in
+```
+
+pick the person from the list and you get their films that are on your subs,
+in your region, first. one lookup, no clicking through each app. hit "see full
+filmography" to browse everything they did.
+
+directors get the films they directed, actors get the ones they acted in.
+
 ## notes
 
 - config lives in `~/.watchwhere/config.json`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchwhere",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "region-aware streaming availability CLI — find which of your subs has a given title",
   "type": "module",
   "bin": {

package/src/checkbox.ts

@@ -0,0 +1,262 @@
+import {
+  createPrompt,
+  isDownKey,
+  isEnterKey,
+  isUpKey,
+  makeTheme,
+  useKeypress,
+  usePagination,
+  usePrefix,
+  useRef,
+  useState,
+} from "@inquirer/core";
+import { cursorHide } from "@inquirer/ansi";
+import { c } from "./colors.ts";
+
+const GG_TIMEOUT_MS = 500;
+
+export interface CheckboxChoice<Value> {
+  readonly name: string;
+  readonly value: Value;
+  readonly checked?: boolean;
+}
+
+export interface CheckboxHints {
+  readonly navigate: string;
+  readonly jump: string;
+  readonly toggle: string;
+  readonly search: string;
+  readonly filter: string;
+  readonly apply: string;
+  readonly clear: string;
+  readonly save: string;
+  readonly cancel: string;
+  readonly searchLabel: string;
+  readonly filterLabel: string;
+  readonly selectedCount: (n: number) => string;
+  readonly noMatch: string;
+}
+
+export interface CheckboxConfig<Value> {
+  readonly message: string;
+  readonly choices: ReadonlyArray<CheckboxChoice<Value>>;
+  readonly pageSize?: number;
+  readonly hints: CheckboxHints;
+}
+
+const checkboxTheme = {
+  prefix: { idle: c.green("?"), done: c.green("✓") },
+  spinner: { interval: 80, frames: ["⠋"] },
+  style: {
+    answer: (text: string) => c.cyan(text),
+    message: (text: string) => c.bold(text),
+    error: (text: string) => c.red(text),
+    defaultAnswer: (text: string) => c.dim(text),
+    help: (text: string) => c.dim(text),
+    highlight: (text: string) => c.cyan(text),
+    key: (text: string) => c.cyan(text),
+    description: (text: string) => c.cyan(text),
+    disabled: (text: string) => c.dim(text),
+  },
+  helpMode: "always" as const,
+};
+
+// printable single character that should land in the search query.
+// excludes space (reserved for toggle in nav mode) and control bytes.
+function isTypeableChar(seq: string | undefined): seq is string {
+  return (
+    typeof seq === "string" &&
+    seq.length === 1 &&
+    seq !== " " &&
+    seq.charCodeAt(0) >= 0x20 &&
+    seq.charCodeAt(0) !== 0x7f
+  );
+}
+
+type Mode = "nav" | "search";
+
+const promptImpl = createPrompt<unknown[] | null, CheckboxConfig<unknown>>(
+  (config, done) => {
+    const pageSize = config.pageSize ?? 12;
+    const theme = makeTheme(checkboxTheme, undefined);
+    const h = config.hints;
+    const [status, setStatus] = useState<"idle" | "done">("idle");
+    const [cancelled, setCancelled] = useState(false);
+    const prefix = usePrefix({ status, theme });
+
+    const all = config.choices;
+    const [mode, setMode] = useState<Mode>("nav");
+    const [query, setQuery] = useState("");
+    const [active, setActive] = useState(0);
+    const lastGAt = useRef(0);
+    // selection as a Set replaced on every change so state updates fire
+    const [selected, setSelected] = useState<ReadonlySet<unknown>>(
+      () => new Set(all.filter((ch) => ch.checked).map((ch) => ch.value)),
+    );
+
+    const needle = query.toLowerCase();
+    const filtered = needle
+      ? all.filter((ch) => ch.name.toLowerCase().includes(needle))
+      : all;
+
+    const clampedActive = Math.min(active, Math.max(0, filtered.length - 1));
+
+    const moveUp = () => setActive(clampedActive > 0 ? clampedActive - 1 : 0);
+    const moveDown = () =>
+      setActive(
+        clampedActive < filtered.length - 1 ? clampedActive + 1 : clampedActive,
+      );
+
+    useKeypress((key) => {
+      const seq = (key as unknown as { sequence?: string }).sequence;
+
+      // ---- search mode: keystrokes build the query ----
+      if (mode === "search") {
+        if (key.name === "escape") {
+          // clear the search and return to navigation
+          setQuery("");
+          setActive(0);
+          setMode("nav");
+          return;
+        }
+        if (isEnterKey(key)) {
+          // apply the filter, keep it, go navigate the matches
+          setMode("nav");
+          return;
+        }
+        if (key.name === "backspace") {
+          if (query.length > 0) {
+            setQuery(query.slice(0, -1));
+            setActive(0);
+          } else {
+            setMode("nav");
+          }
+          return;
+        }
+        // arrows still move the cursor while searching
+        if (isUpKey(key, [])) return moveUp();
+        if (isDownKey(key, [])) return moveDown();
+        if (isTypeableChar(seq)) {
+          setQuery(query + seq);
+          setActive(0);
+        }
+        return;
+      }
+
+      // ---- nav mode: vim-style movement, space toggles, / searches ----
+      if (key.name === "escape") {
+        setCancelled(true);
+        setStatus("done");
+        done(null);
+        return;
+      }
+      if (isEnterKey(key)) {
+        setStatus("done");
+        // preserve original choice order in the result
+        done(all.filter((ch) => selected.has(ch.value)).map((ch) => ch.value));
+        return;
+      }
+      if (seq === "/") {
+        setMode("search");
+        return;
+      }
+      if (key.name === "space" || seq === " ") {
+        const item = filtered[clampedActive];
+        if (item) {
+          const next = new Set(selected);
+          if (next.has(item.value)) next.delete(item.value);
+          else next.add(item.value);
+          setSelected(next);
+        }
+        return;
+      }
+      if (seq === "G") {
+        setActive(Math.max(0, filtered.length - 1));
+        return;
+      }
+      if (seq === "g") {
+        const now = Date.now();
+        if (now - lastGAt.current < GG_TIMEOUT_MS) {
+          setActive(0);
+          lastGAt.current = 0;
+        } else {
+          lastGAt.current = now;
+        }
+        return;
+      }
+      if (isUpKey(key, []) || seq === "k") return moveUp();
+      if (isDownKey(key, []) || seq === "j") return moveDown();
+    });
+
+    const message = theme.style.message(config.message);
+    const countStr = theme.style.help(h.selectedCount(selected.size));
+
+    if (status === "done") {
+      if (cancelled) return "";
+      return [prefix, message, theme.style.answer(h.selectedCount(selected.size))]
+        .filter(Boolean)
+        .join(" ");
+    }
+
+    const page = usePagination({
+      items: filtered,
+      active: clampedActive,
+      renderItem({ item, isActive }) {
+        const isChecked = selected.has(item.value);
+        const box = isChecked ? c.green("◉") : c.dim("◯");
+        const cursor = isActive ? c.cyan(">") : " ";
+        const label = isActive ? theme.style.highlight(item.name) : item.name;
+        return `${cursor} ${box} ${label}`;
+      },
+      pageSize,
+      loop: false,
+    });
+
+    // status line: search box while typing, applied-filter hint while navigating
+    let statusLine: string;
+    if (mode === "search") {
+      statusLine = `  ${c.dim(h.searchLabel)} ${query}${c.cyan("▏")} ${countStr}`;
+    } else if (query) {
+      statusLine = `  ${c.dim(h.filterLabel)} ${c.cyan(query)} ${countStr}`;
+    } else {
+      statusLine = `  ${countStr}`;
+    }
+
+    const body = filtered.length === 0 ? `  ${c.dim(h.noMatch)}` : page;
+
+    const keys: ReadonlyArray<readonly [string, string]> =
+      mode === "search"
+        ? [
+            ["↑↓", h.navigate],
+            ["a-z", h.filter],
+            ["⏎", h.apply],
+            ["esc", h.clear],
+          ]
+        : [
+            ["↑↓ jk", h.navigate],
+            ["gg/G", h.jump],
+            ["space", h.toggle],
+            ["/", h.search],
+            ["⏎", h.save],
+            ["esc", h.cancel],
+          ];
+    const helpLine = keys
+      .map(([k, a]) => `${c.bold(k)} ${c.dim(a)}`)
+      .join(c.dim(" • "));
+
+    return (
+      [[prefix, message].filter(Boolean).join(" "), statusLine, body, helpLine]
+        .filter((line) => line !== "")
+        .join("\n") + cursorHide
+    );
+  },
+);
+
+export async function filterableCheckbox<Value>(
+  config: CheckboxConfig<Value>,
+): Promise<Value[] | null> {
+  const result = (await promptImpl(
+    config as CheckboxConfig<unknown>,
+  )) as Value[] | null;
+  return result;
+}

package/src/commands/init.ts

@@ -1,5 +1,6 @@
-import { checkbox, input, password } from "@inquirer/prompts";
+import { input, password } from "@inquirer/prompts";
 import { c } from "../colors.ts";
+import { filterableCheckbox } from "../checkbox.ts";
 import { loadConfig, saveConfig } from "../config.ts";
 import { resolveLocale, t } from "../i18n.ts";
 import { getCachedRegionProviders } from "../cache.ts";
@@ -72,13 +73,35 @@ export async function runInit(): Promise<void> {
     checked: existing?.subscriptions.includes(p.provider_id) ?? false,
   }));
 
-  const subscriptions = await checkbox<number>({
-    message: `${m.yourSubsLabel(region)} ${c.dim(m.toggleHintConfirm)}:`,
+  const subscriptions = await filterableCheckbox<number>({
+    message: `${m.yourSubsLabel(region)}:`,
     choices,
     pageSize: 15,
-    loop: false,
+    hints: {
+      navigate: m.hintNavigate,
+      jump: m.hintJump,
+      toggle: m.hintToggle,
+      search: m.hintSearch,
+      filter: m.hintFilter,
+      apply: m.hintApply,
+      clear: m.hintClear,
+      save: m.hintSave,
+      cancel: m.hintCancel,
+      searchLabel: m.searchLabel,
+      filterLabel: m.filterLabel,
+      selectedCount: m.selectedCount,
+      noMatch: m.noFilterMatch,
+    },
   });
 
+  // esc at the subs step cancels init entirely — never overwrite an
+  // existing config with an empty subscription list.
+  if (subscriptions === null) {
+    console.log();
+    console.log(`  ${c.dim(m.cancelled)}`);
+    return;
+  }
+
   const saved = await saveConfig({
     tmdbToken: tmdbToken.trim(),
     region,

package/src/commands/search.ts

@@ -4,10 +4,17 @@ import { resolveLocale, t } from "../i18n.ts";
 import { picker } from "../picker.ts";
 import { editableInput } from "../prompts.ts";
 import {
+  discoverPersonFilms,
+  getPersonCredits,
   getReleaseDates,
   getWatchProviders,
   searchAll,
+  searchPeople,
+  toFilmography,
+  type CreditRole,
   type MediaItem,
+  type PersonDepartment,
+  type PersonItem,
   type TmdbProvider,
   type TmdbReleaseDate,
 } from "../tmdb.ts";
@@ -15,6 +22,19 @@ import {
 const PAGE_SIZE = 10;
 const SOFT_LIMIT = 25;
 const OVERVIEW_MAX = 140;
+const OLDEST_FILM_YEAR = 1888;
+
+function parseQuery(input: string): { query: string; year?: number } {
+  const match = input.match(/^(.+?)\s+(\d{4})$/);
+  if (match && match[1] && match[2]) {
+    const year = Number.parseInt(match[2], 10);
+    const maxYear = new Date().getFullYear() + 2;
+    if (year >= OLDEST_FILM_YEAR && year <= maxYear) {
+      return { query: match[1].trim(), year };
+    }
+  }
+  return { query: input };
+}
 
 function year(date: string | null): string {
   return date && date.length >= 4 ? date.slice(0, 4) : "????";
@@ -84,25 +104,101 @@ function printPhysical(
   }
 }
 
-async function pickItem(
-  results: ReadonlyArray<MediaItem>,
+type SearchHit =
+  | { readonly kind: "title"; readonly item: MediaItem }
+  | { readonly kind: "person"; readonly person: PersonItem };
+
+// keep incidental name-collisions from flooding the list: searching "matrix"
+// otherwise surfaces dozens of obscure people whose first name is Matrix.
+const MAX_INCIDENTAL_PEOPLE = 5;
+
+function normalize(s: string): string {
+  return s
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase()
+    .replace(/[\s._-]+/g, " ")
+    .trim();
+}
+
+// ordering: people whose full name you typed exactly lead (you clearly meant
+// the person), then titles in their own relevance order, then a few incidental
+// people whose name merely contains the query. titles and people sit on
+// different popularity scales, so the two are never compared directly.
+function rankHits(
+  titles: ReadonlyArray<MediaItem>,
+  people: ReadonlyArray<PersonItem>,
+  query: string,
+): ReadonlyArray<SearchHit> {
+  const q = normalize(query);
+  const isExactName = (p: PersonItem): boolean => normalize(p.name) === q;
+  const named = people.filter(isExactName);
+  const incidental = people
+    .filter((p) => !isExactName(p))
+    .slice(0, MAX_INCIDENTAL_PEOPLE);
+  return [
+    ...named.map((person): SearchHit => ({ kind: "person", person })),
+    ...titles.map((item): SearchHit => ({ kind: "title", item })),
+    ...incidental.map((person): SearchHit => ({ kind: "person", person })),
+  ];
+}
+
+function deptLabel(d: PersonDepartment, m: ReturnType<typeof t>): string {
+  if (d === "directing") return m.personDirector;
+  if (d === "acting") return m.personActor;
+  return m.personCrew;
+}
+
+function roleTag(role: CreditRole, m: ReturnType<typeof t>): string {
+  return c.dim(`[${role === "directing" ? m.roleDir : m.roleAct}]`);
+}
+
+function titleChoiceName(mi: MediaItem, m: ReturnType<typeof t>): string {
+  const orig = mi.title !== mi.originalTitle ? c.dim(` — ${mi.originalTitle}`) : "";
+  return `${tag(mi.mediaType, m)} ${mi.title} ${c.dim(`(${year(mi.date)})`)}${orig}`;
+}
+
+function personChoiceName(p: PersonItem, m: ReturnType<typeof t>): string {
+  const meta = [deptLabel(p.department, m), ...p.knownFor.slice(0, 2)]
+    .filter((s) => s !== "")
+    .join(" · ");
+  return `${c.dim(`[${m.tagPerson}]`)} ${p.name} ${c.dim(`(${meta})`)}`;
+}
+
+function filmChoiceName(item: MediaItem, m: ReturnType<typeof t>): string {
+  const prefix = item.role ? `${roleTag(item.role, m)} ` : "";
+  const orig =
+    item.originalTitle && item.title !== item.originalTitle
+      ? c.dim(` — ${item.originalTitle}`)
+      : "";
+  return `${prefix}${item.title} ${c.dim(`(${year(item.date)})`)}${orig}`;
+}
+
+async function pickHit(
+  hits: ReadonlyArray<SearchHit>,
   m: ReturnType<typeof t>,
-): Promise<MediaItem | null> {
-  const visible = results.slice(0, SOFT_LIMIT);
-  const dropped = results.length - visible.length;
-
-  const choices = visible.map((mi) => ({
-    name: `${tag(mi.mediaType, m)} ${mi.title} ${c.dim(`(${year(mi.date)})`)}${mi.title !== mi.originalTitle ? c.dim(` — ${mi.originalTitle}`) : ""}`,
-    value: mi,
-    description: mi.overview.slice(0, OVERVIEW_MAX),
+): Promise<SearchHit | null> {
+  const visible = hits.slice(0, SOFT_LIMIT);
+  const dropped = hits.length - visible.length;
+
+  const choices = visible.map((hit) => ({
+    name:
+      hit.kind === "person"
+        ? personChoiceName(hit.person, m)
+        : titleChoiceName(hit.item, m),
+    value: hit,
+    description:
+      hit.kind === "person"
+        ? hit.person.knownFor.join(", ")
+        : hit.item.overview.slice(0, OVERVIEW_MAX),
   }));
 
   const headerParts: string[] = [m.whichOne];
   if (dropped > 0) {
-    headerParts.push(c.dim(`(${visible.length}/${results.length})`));
+    headerParts.push(c.dim(`(${visible.length}/${hits.length})`));
   }
 
-  return picker<MediaItem>({
+  return picker<SearchHit>({
     message: headerParts.join(" "),
     pageSize: PAGE_SIZE,
     choices,
@@ -216,19 +312,184 @@ async function displayItem(
   }
 }
 
+type FilmChoice =
+  | { readonly kind: "film"; readonly item: MediaItem }
+  | { readonly kind: "full" }
+  | { readonly kind: "subs" };
+
+async function pickFilm(
+  films: ReadonlyArray<MediaItem>,
+  total: number,
+  header: string,
+  action: { readonly value: FilmChoice; readonly label: string } | null,
+  m: ReturnType<typeof t>,
+): Promise<FilmChoice | null> {
+  const visible = films.slice(0, SOFT_LIMIT);
+  // `total` can exceed films.length when the source is paginated (discover
+  // returns one page); never report fewer than we actually hold.
+  const grandTotal = Math.max(total, films.length);
+
+  const choices = visible.map((item) => ({
+    name: filmChoiceName(item, m),
+    value: { kind: "film", item } as FilmChoice,
+    description: item.overview.slice(0, OVERVIEW_MAX),
+  }));
+  if (action) {
+    choices.push({ name: c.dim(`› ${action.label}`), value: action.value, description: "" });
+  }
+
+  const headerParts: string[] = [header];
+  if (grandTotal > visible.length) {
+    headerParts.push(c.dim(`(${visible.length}/${grandTotal})`));
+  }
+
+  return picker<FilmChoice>({
+    message: headerParts.join(" "),
+    pageSize: PAGE_SIZE,
+    choices,
+    extraKeys: [["esc", "back"]],
+  });
+}
+
+// a person opens to two views: what's on your subs right now (one discover
+// call, region- and provider-filtered server-side) and their full filmography
+// (combined credits). you can flip between them; picking a film drops into the
+// usual provider breakdown.
+async function runPerson(
+  person: PersonItem,
+  cfg: Config,
+  m: ReturnType<typeof t>,
+): Promise<void> {
+  const hasSubs = cfg.subscriptions.length > 0;
+  let view: "subs" | "full" = hasSubs ? "subs" : "full";
+  if (!hasSubs) {
+    console.log();
+    console.log(c.dim(`  ${m.personNoSubsConfigured}`));
+  }
+
+  // fetched lazily, then reused as you flip between views.
+  let onSubs: { films: ReadonlyArray<MediaItem>; total: number } | null = null;
+  let filmography: ReadonlyArray<MediaItem> | null = null;
+
+  while (true) {
+    if (view === "subs") {
+      if (onSubs === null) {
+        process.stdout.write(c.dim(`  ${m.loadingFilms(person.name)}`));
+        onSubs = await discoverPersonFilms({
+          personId: person.id,
+          department: person.department,
+          region: cfg.region,
+          providerIds: cfg.subscriptions,
+          token: cfg.tmdbToken,
+          language: cfg.language,
+        });
+        console.log(c.dim(m.resultsCount(onSubs.films.length)));
+      }
+      if (onSubs.films.length === 0) {
+        console.log();
+        console.log(
+          `  ${c.yellow("●")} ${m.personSubsEmpty(person.name, cfg.region)}`,
+        );
+        view = "full";
+        continue;
+      }
+      const picked = await pickFilm(
+        onSubs.films,
+        onSubs.total,
+        m.personSubsTitle(person.name, cfg.region),
+        { value: { kind: "full" }, label: m.personSeeFull },
+        m,
+      );
+      if (picked === null) return;
+      if (picked.kind === "film") {
+        await displayItem(picked.item, cfg, m);
+        return;
+      }
+      view = "full";
+      continue;
+    }
+
+    if (filmography === null) {
+      process.stdout.write(c.dim(`  ${m.loadingFilms(person.name)}`));
+      const credits = await getPersonCredits(person.id, cfg.tmdbToken, {
+        language: cfg.language,
+      });
+      filmography = toFilmography(credits, person.department);
+      console.log(c.dim(m.resultsCount(filmography.length)));
+    }
+    if (filmography.length === 0) {
+      console.log();
+      console.log(`  ${m.personNoCredits(person.name)}`);
+      return;
+    }
+    // only offer "back to your subs" when there's actually something there.
+    const canReturnToSubs =
+      hasSubs && onSubs !== null && onSubs.films.length > 0;
+    const picked = await pickFilm(
+      filmography,
+      filmography.length,
+      m.personFullTitle(person.name),
+      canReturnToSubs ? { value: { kind: "subs" }, label: m.personSeeSubs } : null,
+      m,
+    );
+    if (picked === null) return;
+    if (picked.kind === "film") {
+      await displayItem(picked.item, cfg, m);
+      return;
+    }
+    view = "subs";
+    continue;
+  }
+}
+
+async function searchTitles(
+  raw: string,
+  cfg: Config,
+  m: ReturnType<typeof t>,
+): Promise<ReadonlyArray<MediaItem>> {
+  const parsed = parseQuery(raw);
+  const displayQ = parsed.year ? `${parsed.query} (${parsed.year})` : parsed.query;
+  process.stdout.write(c.dim(`  ${m.searching(displayQ)}`));
+  const all = await searchAll(parsed.query, cfg.tmdbToken, {
+    language: cfg.language,
+  });
+  const results = parsed.year
+    ? all.filter((r) => r.date?.slice(0, 4) === String(parsed.year))
+    : all;
+  console.log(c.dim(m.resultsCount(results.length)));
+  return results;
+}
+
+async function searchUnified(
+  raw: string,
+  cfg: Config,
+  m: ReturnType<typeof t>,
+): Promise<ReadonlyArray<SearchHit>> {
+  const parsed = parseQuery(raw);
+  const displayQ = parsed.year ? `${parsed.query} (${parsed.year})` : parsed.query;
+  process.stdout.write(c.dim(`  ${m.searching(displayQ)}`));
+  const [titlesAll, people] = await Promise.all([
+    searchAll(parsed.query, cfg.tmdbToken, { language: cfg.language }),
+    // a trailing year filters titles; people don't have one, so the person
+    // lookup ignores it but still runs on the bare query.
+    searchPeople(parsed.query, cfg.tmdbToken, { language: cfg.language }),
+  ]);
+  const titles = parsed.year
+    ? titlesAll.filter((r) => r.date?.slice(0, 4) === String(parsed.year))
+    : titlesAll;
+  const hits = rankHits(titles, people, parsed.query);
+  console.log(c.dim(m.resultsCount(hits.length)));
+  return hits;
+}
+
 export async function runSearch(query: string, cfg: Config): Promise<void> {
   const m = t(resolveLocale(cfg.language));
   let currentQuery = query.trim();
   if (!currentQuery) throw new Error(m.searchEmpty);
 
-  // pipe mode: no prompts
+  // pipe mode: deterministic, titles only. person lookups are interactive.
   if (!process.stdin.isTTY) {
-    process.stdout.write(c.dim(`  ${m.searching(currentQuery)}`));
-    const results = await searchAll(currentQuery, cfg.tmdbToken, {
-      region: cfg.region,
-      language: cfg.language,
-    });
-    console.log(c.dim(m.resultsCount(results.length)));
+    const results = await searchTitles(currentQuery, cfg, m);
     if (results.length === 0) throw new Error(m.noMatch);
     if (results.length > 1) throw new Error(m.ambiguousQuery(results.length));
     await displayItem(results[0]!, cfg, m);
@@ -236,22 +497,18 @@ export async function runSearch(query: string, cfg: Config): Promise<void> {
   }
 
   while (true) {
-    process.stdout.write(c.dim(`  ${m.searching(currentQuery)}`));
-    const results = await searchAll(currentQuery, cfg.tmdbToken, {
-      region: cfg.region,
-      language: cfg.language,
-    });
-    console.log(c.dim(m.resultsCount(results.length)));
-
-    let picked: MediaItem | null = null;
-    if (results.length > 0) {
-      picked = await pickItem(results, m);
+    const hits = await searchUnified(currentQuery, cfg, m);
+
+    let picked: SearchHit | null = null;
+    if (hits.length > 0) {
+      picked = await pickHit(hits, m);
     } else {
       console.log(`\n  ${m.noMatch}`);
     }
 
     if (picked !== null) {
-      await displayItem(picked, cfg, m);
+      if (picked.kind === "person") await runPerson(picked.person, cfg, m);
+      else await displayItem(picked.item, cfg, m);
       return;
     }
 

package/src/commands/subs.ts

@@ -1,5 +1,5 @@
-import { checkbox } from "@inquirer/prompts";
 import { c } from "../colors.ts";
+import { filterableCheckbox } from "../checkbox.ts";
 import { loadConfig, saveConfig } from "../config.ts";
 import { resolveLocale, t } from "../i18n.ts";
 import { getCachedRegionProviders } from "../cache.ts";
@@ -26,17 +26,38 @@ export async function runSubs(): Promise<void> {
 
   const current = new Set(cfg.subscriptions);
 
-  const subscriptions = await checkbox<number>({
-    message: `${m.yourSubsLabel(cfg.region)} ${c.dim(m.toggleHintSave)}:`,
+  const subscriptions = await filterableCheckbox<number>({
+    message: `${m.yourSubsLabel(cfg.region)}:`,
     choices: providers.map((p) => ({
       name: p.provider_name,
       value: p.provider_id,
       checked: current.has(p.provider_id),
     })),
     pageSize: 15,
-    loop: false,
+    hints: {
+      navigate: m.hintNavigate,
+      jump: m.hintJump,
+      toggle: m.hintToggle,
+      search: m.hintSearch,
+      filter: m.hintFilter,
+      apply: m.hintApply,
+      clear: m.hintClear,
+      save: m.hintSave,
+      cancel: m.hintCancel,
+      searchLabel: m.searchLabel,
+      filterLabel: m.filterLabel,
+      selectedCount: m.selectedCount,
+      noMatch: m.noFilterMatch,
+    },
   });
 
+  // esc → cancel: leave the existing config untouched
+  if (subscriptions === null) {
+    console.log();
+    console.log(`  ${c.dim(m.cancelled)}`);
+    return;
+  }
+
   const added = subscriptions.filter((id) => !current.has(id)).length;
   const removed = cfg.subscriptions.filter((id) => !subscriptions.includes(id)).length;
 

package/src/i18n.ts

@@ -53,6 +53,22 @@ interface Catalog {
   rent: string;
   buy: string;
 
+  // person search / filmography
+  tagPerson: string;
+  personActor: string;
+  personDirector: string;
+  personCrew: string;
+  roleDir: string;
+  roleAct: string;
+  loadingFilms: (name: string) => string;
+  personSubsTitle: (name: string, region: string) => string;
+  personFullTitle: (name: string) => string;
+  personSubsEmpty: (name: string, region: string) => string;
+  personSeeFull: string;
+  personSeeSubs: string;
+  personNoCredits: (name: string) => string;
+  personNoSubsConfigured: string;
+
   // config (show)
   noConfigYet: string;
   resolvingNames: string;
@@ -82,11 +98,24 @@ interface Catalog {
   providersFound: (n: number) => string;
   noProviders: (region: string) => string;
   yourSubsLabel: (region: string) => string;
-  toggleHintConfirm: string;
-  toggleHintSave: string;
   savedTo: string;
   updatedConfigFile: string;
 
+  // filterable checkbox (subs picker)
+  filterLabel: string;
+  searchLabel: string;
+  selectedCount: (n: number) => string;
+  hintNavigate: string;
+  hintJump: string;
+  hintToggle: string;
+  hintSearch: string;
+  hintFilter: string;
+  hintApply: string;
+  hintClear: string;
+  hintSave: string;
+  hintCancel: string;
+  noFilterMatch: string;
+
   // validation
   corruptConfig: (path: string) => string;
 
@@ -118,6 +147,7 @@ interface Catalog {
   tokenExpired: string;
   networkOffline: string;
   networkTimeout: string;
+  rateLimited: string;
   relativeNow: string;
   relativeMinutes: (n: number) => string;
   relativeHours: (n: number) => string;
@@ -167,6 +197,23 @@ const en: Catalog = {
   rent: "rent",
   buy: "buy",
 
+  tagPerson: "person",
+  personActor: "actor",
+  personDirector: "director",
+  personCrew: "crew",
+  roleDir: "dir",
+  roleAct: "act",
+  loadingFilms: (name) => `loading ${name}'s films… `,
+  personSubsTitle: (name, region) => `${name} — on your subs in ${region}`,
+  personFullTitle: (name) => `${name} — full filmography`,
+  personSubsEmpty: (name, region) =>
+    `nothing of ${name}'s is on your subs in ${region} — showing full filmography.`,
+  personSeeFull: "see full filmography",
+  personSeeSubs: "back to your subs",
+  personNoCredits: (name) => `no filmography found for ${name}.`,
+  personNoSubsConfigured:
+    "no subscriptions set yet — showing full filmography. run `ww subs` to add some.",
+
   noConfigYet: "no config yet — run `ww init` first.",
   resolvingNames: "resolving subscription names… ",
   configTitle: "watchwhere config",
@@ -196,11 +243,23 @@ const en: Catalog = {
   noProviders: (region) =>
     `no providers found for region ${region}. check the code.`,
   yourSubsLabel: (region) => `your subscriptions in ${region}`,
-  toggleHintConfirm: "(space to toggle, enter to confirm)",
-  toggleHintSave: "(space to toggle, enter to save)",
   savedTo: "saved to",
   updatedConfigFile: "updated",
 
+  filterLabel: "filter:",
+  searchLabel: "search:",
+  selectedCount: (n) => `${n} selected`,
+  hintNavigate: "navigate",
+  hintJump: "top/bottom",
+  hintToggle: "toggle",
+  hintSearch: "search",
+  hintFilter: "filter",
+  hintApply: "apply",
+  hintClear: "clear",
+  hintSave: "save",
+  hintCancel: "cancel",
+  noFilterMatch: "no match — esc to clear the search",
+
   corruptConfig: (path) => `corrupt config file: ${path}`,
 
   languageUpdated: (code) => `language updated to ${code}`,
@@ -213,7 +272,7 @@ const en: Catalog = {
   usageTagline: "where can I stream it?",
   usageSectionUsage: "usage",
   usageSectionConfig: "config",
-  usageDescTitle: "search a movie or show in your region",
+  usageDescTitle: "search a movie, show, or person in your region",
   usageDescInit: "set up token, region, language, subscriptions",
   usageDescSubs: "edit your subscriptions only",
   usageDescLang: "change display language",
@@ -228,6 +287,7 @@ const en: Catalog = {
   tokenExpired: "TMDB token rejected (401). run `ww init` to re-enter it.",
   networkOffline: "couldn't reach TMDB. check your internet connection.",
   networkTimeout: "TMDB request timed out. try again, or check your connection.",
+  rateLimited: "rate limit hit. try again in an hour, or set WATCHWHERE_PROXY=off to use your own TMDB token.",
   relativeNow: "just now",
   relativeMinutes: (n) => `${n} min ago`,
   relativeHours: (n) => `${n} hr ago`,
@@ -276,6 +336,23 @@ const tr: Catalog = {
   rent: "kirala",
   buy: "satın al",
 
+  tagPerson: "kişi",
+  personActor: "oyuncu",
+  personDirector: "yönetmen",
+  personCrew: "ekip",
+  roleDir: "yön",
+  roleAct: "oyun",
+  loadingFilms: (name) => `${name} filmleri yükleniyor… `,
+  personSubsTitle: (name, region) => `${name} — ${region} aboneliklerinde`,
+  personFullTitle: (name) => `${name} — tüm filmografi`,
+  personSubsEmpty: (name, region) =>
+    `${name} için ${region} aboneliklerinde bir şey yok — tüm filmografi gösteriliyor.`,
+  personSeeFull: "tüm filmografiyi gör",
+  personSeeSubs: "aboneliklerine dön",
+  personNoCredits: (name) => `${name} için filmografi bulunamadı.`,
+  personNoSubsConfigured:
+    "henüz abonelik yok — tüm filmografi gösteriliyor. eklemek için `ww subs`.",
+
   noConfigYet: "henüz config yok — önce `ww init` çalıştır.",
   resolvingNames: "abonelik isimleri çözümleniyor… ",
   configTitle: "watchwhere config",
@@ -306,11 +383,23 @@ const tr: Catalog = {
   noProviders: (region) =>
     `${region} bölgesi için sağlayıcı bulunamadı. kodu kontrol edin.`,
   yourSubsLabel: (region) => `${region} bölgesindeki aboneliklerin`,
-  toggleHintConfirm: "(seçmek için space, onaylamak için enter)",
-  toggleHintSave: "(seçmek için space, kaydetmek için enter)",
   savedTo: "kaydedildi:",
   updatedConfigFile: "güncellendi",
 
+  filterLabel: "filtre:",
+  searchLabel: "ara:",
+  selectedCount: (n) => `${n} seçili`,
+  hintNavigate: "gezin",
+  hintJump: "baş/son",
+  hintToggle: "seç",
+  hintSearch: "ara",
+  hintFilter: "filtrele",
+  hintApply: "uygula",
+  hintClear: "temizle",
+  hintSave: "kaydet",
+  hintCancel: "iptal",
+  noFilterMatch: "eşleşme yok — temizlemek için esc",
+
   corruptConfig: (path) => `bozuk config dosyası: ${path}`,
 
   languageUpdated: (code) => `dil ${code} olarak güncellendi`,
@@ -323,7 +412,7 @@ const tr: Catalog = {
   usageTagline: "nerede izleyebilirim?",
   usageSectionUsage: "kullanım",
   usageSectionConfig: "config",
-  usageDescTitle: "bölgendeki bir film veya diziyi ara",
+  usageDescTitle: "bölgendeki bir film, dizi veya kişiyi ara",
   usageDescInit: "token, bölge, dil ve abonelikleri ayarla",
   usageDescSubs: "sadece abonelikleri düzenle",
   usageDescLang: "görüntüleme dilini değiştir",
@@ -338,6 +427,7 @@ const tr: Catalog = {
   tokenExpired: "TMDB token reddedildi (401). yenilemek için `ww init` çalıştır.",
   networkOffline: "TMDB'ye ulaşılamadı. internet bağlantını kontrol et.",
   networkTimeout: "TMDB isteği zaman aşımına uğradı. tekrar dene veya bağlantını kontrol et.",
+  rateLimited: "rate limit doldu. bir saat sonra dene veya WATCHWHERE_PROXY=off ile kendi TMDB token'ını kullan.",
   relativeNow: "şimdi",
   relativeMinutes: (n) => `${n} dk önce`,
   relativeHours: (n) => `${n} saat önce`,

package/src/index.ts

@@ -162,6 +162,7 @@ main().then(maybeNotifyUpdate).catch(async (err: unknown) => {
   let displayMsg = err instanceof Error ? err.message : String(err);
   if (err instanceof TmdbError) {
     if (err.status === 401) displayMsg = m.tokenExpired;
+    else if (err.status === 429) displayMsg = m.rateLimited;
     else if (err.status === 0 && err.message.includes("timed out")) {
       displayMsg = m.networkTimeout;
     } else if (err.status === 0) {

package/src/picker.ts

@@ -7,10 +7,14 @@ import {
   useKeypress,
   usePagination,
   usePrefix,
+  useRef,
   useState,
 } from "@inquirer/core";
+import { cursorHide } from "@inquirer/ansi";
 import { c } from "./colors.ts";
 
+const GG_TIMEOUT_MS = 500;
+
 export interface PickerChoice<Value> {
   readonly name: string;
   readonly value: Value;
@@ -50,9 +54,14 @@ const promptImpl = createPrompt<unknown | null, PickerConfig<unknown>>(
     const prefix = usePrefix({ status, theme });
     const items = config.choices;
     const [active, setActive] = useState(0);
+    const lastGAt = useRef(0);
 
     useKeypress((key) => {
-      if (key.name === "escape") {
+      // sequence is present at runtime but not in the type; cast to read it
+      const seq = (key as unknown as { sequence?: string }).sequence;
+
+      // esc or q: cancel
+      if (key.name === "escape" || seq === "q") {
         setCancelled(true);
         setStatus("done");
         done(null);
@@ -64,11 +73,29 @@ const promptImpl = createPrompt<unknown | null, PickerConfig<unknown>>(
         if (chosen) done(chosen.value);
         return;
       }
-      if (isUpKey(key, [])) {
+      // G (shift+g): bottom
+      if (seq === "G") {
+        setActive(items.length - 1);
+        return;
+      }
+      // gg: top (two g within timeout)
+      if (seq === "g") {
+        const now = Date.now();
+        if (now - lastGAt.current < GG_TIMEOUT_MS) {
+          setActive(0);
+          lastGAt.current = 0;
+        } else {
+          lastGAt.current = now;
+        }
+        return;
+      }
+      // up or k
+      if (isUpKey(key, []) || seq === "k") {
         if (active > 0) setActive(active - 1);
         return;
       }
-      if (isDownKey(key, [])) {
+      // down or j
+      if (isDownKey(key, []) || seq === "j") {
         if (active < items.length - 1) setActive(active + 1);
         return;
       }
@@ -98,7 +125,7 @@ const promptImpl = createPrompt<unknown | null, PickerConfig<unknown>>(
 
     const description = items[active]?.description;
     const helpLine = [
-      ["↑↓", "navigate"],
+      ["↑↓ jk", "navigate"],
       ["⏎", "select"],
       ...(config.extraKeys ?? []),
     ]
@@ -112,7 +139,7 @@ const promptImpl = createPrompt<unknown | null, PickerConfig<unknown>>(
       helpLine,
     ]
       .filter((line) => line !== "")
-      .join("\n");
+      .join("\n") + cursorHide;
   },
 );
 

package/src/tmdb.ts

@@ -32,6 +32,13 @@ export interface TmdbTv {
   readonly popularity: number;
 }
 
+// how a person is credited on a title, used to tag filmography entries.
+export type CreditRole = "acting" | "directing";
+
+// a person's primary department on TMDB. drives whether we match them as
+// cast or crew when discovering what's streamable.
+export type PersonDepartment = "acting" | "directing" | "other";
+
 export interface MediaItem {
   readonly id: number;
   readonly mediaType: MediaType;
@@ -40,6 +47,16 @@ export interface MediaItem {
   readonly date: string | null;
   readonly overview: string;
   readonly popularity: number;
+  // set only on filmography results (person lookups); absent for title search.
+  readonly role?: CreditRole;
+}
+
+export interface PersonItem {
+  readonly id: number;
+  readonly name: string;
+  readonly department: PersonDepartment;
+  readonly knownFor: ReadonlyArray<string>;
+  readonly popularity: number;
 }
 
 export interface TmdbSearchResponse<T> {
@@ -47,6 +64,48 @@ export interface TmdbSearchResponse<T> {
   readonly total_results: number;
 }
 
+export interface TmdbPerson {
+  readonly id: number;
+  readonly name: string;
+  readonly known_for_department: string | null;
+  readonly popularity: number;
+  readonly profile_path: string | null;
+  readonly known_for?: ReadonlyArray<{
+    readonly title?: string;
+    readonly name?: string;
+  }>;
+}
+
+// one entry from /person/{id}/combined_credits. cast entries carry a
+// `character`, crew entries carry a `job` ("Director", "Writer", …).
+export interface TmdbPersonCredit {
+  readonly id: number;
+  readonly media_type: MediaType;
+  readonly title?: string;
+  readonly original_title?: string;
+  readonly name?: string;
+  readonly original_name?: string;
+  readonly release_date?: string;
+  readonly first_air_date?: string;
+  readonly overview?: string;
+  readonly popularity?: number;
+  readonly character?: string;
+  readonly job?: string;
+}
+
+export interface TmdbCombinedCreditsResponse {
+  readonly id: number;
+  readonly cast: ReadonlyArray<TmdbPersonCredit>;
+  readonly crew: ReadonlyArray<TmdbPersonCredit>;
+}
+
+export interface TmdbDiscoverResponse {
+  readonly page: number;
+  readonly results: ReadonlyArray<TmdbMovie>;
+  readonly total_results: number;
+  readonly total_pages: number;
+}
+
 export interface TmdbProvider {
   readonly provider_id: number;
   readonly provider_name: string;
@@ -243,6 +302,142 @@ export async function searchAll(
   return items.sort((a, b) => b.popularity - a.popularity);
 }
 
+function toPersonDepartment(knownForDepartment: string | null): PersonDepartment {
+  switch ((knownForDepartment ?? "").toLowerCase()) {
+    case "acting":
+      return "acting";
+    case "directing":
+      return "directing";
+    default:
+      return "other";
+  }
+}
+
+function toPersonItem(p: TmdbPerson): PersonItem {
+  const knownFor = (p.known_for ?? [])
+    .map((k) => k.title ?? k.name ?? "")
+    .filter((s) => s !== "");
+  return {
+    id: p.id,
+    name: p.name,
+    department: toPersonDepartment(p.known_for_department),
+    knownFor,
+    popularity: p.popularity,
+  };
+}
+
+export async function searchPeople(
+  query: string,
+  token: string,
+  opts: { language?: string } = {},
+): Promise<ReadonlyArray<PersonItem>> {
+  const data = await tmdbFetch<TmdbSearchResponse<TmdbPerson>>(
+    "/search/person",
+    token,
+    {
+      query,
+      include_adult: "false",
+      language: opts.language ?? DEFAULT_TMDB_LANGUAGE,
+    },
+  );
+  assertResultsArray(data, "/search/person");
+  return data.results
+    .map(toPersonItem)
+    .sort((a, b) => b.popularity - a.popularity);
+}
+
+function creditToMediaItem(credit: TmdbPersonCredit, role: CreditRole): MediaItem {
+  const isMovie = credit.media_type === "movie";
+  return {
+    id: credit.id,
+    mediaType: credit.media_type,
+    title: (isMovie ? credit.title : credit.name) ?? "",
+    originalTitle: (isMovie ? credit.original_title : credit.original_name) ?? "",
+    date: (isMovie ? credit.release_date : credit.first_air_date) ?? null,
+    overview: credit.overview ?? "",
+    popularity: credit.popularity ?? 0,
+    role,
+  };
+}
+
+export function getPersonCredits(
+  id: number,
+  token: string,
+  opts: { language?: string } = {},
+): Promise<TmdbCombinedCreditsResponse> {
+  return tmdbFetch<TmdbCombinedCreditsResponse>(
+    `/person/${id}/combined_credits`,
+    token,
+    { language: opts.language ?? DEFAULT_TMDB_LANGUAGE },
+  );
+}
+
+// a person's filmography, scoped to their primary role so the list stays
+// coherent: a director gets the films they directed, an actor gets the films
+// they acted in. people with no clear department get both, and when someone
+// directed and acted in the same title the directing credit wins.
+export function toFilmography(
+  credits: TmdbCombinedCreditsResponse,
+  department: PersonDepartment,
+): ReadonlyArray<MediaItem> {
+  const byKey = new Map<string, MediaItem>();
+  const put = (item: MediaItem): void => {
+    const key = `${item.mediaType}:${item.id}`;
+    const existing = byKey.get(key);
+    // directing overrides a prior acting credit; never the reverse.
+    if (!existing || existing.role === "acting") byKey.set(key, item);
+  };
+  if (department !== "directing") {
+    for (const credit of credits.cast ?? []) {
+      put(creditToMediaItem(credit, "acting"));
+    }
+  }
+  if (department !== "acting") {
+    for (const credit of credits.crew ?? []) {
+      if (credit.job === "Director") put(creditToMediaItem(credit, "directing"));
+    }
+  }
+  return [...byKey.values()].sort((a, b) => b.popularity - a.popularity);
+}
+
+// what of a person's work is streamable on the given subs, in one request.
+// TMDB's discover endpoint filters by provider + region server-side, so we
+// avoid a watch/providers call per title. actors are matched as cast,
+// everyone else (directors, writers) as crew. movies only — discover has no
+// reliable person filter for tv.
+//
+// returns the first page (up to 20) plus the true total, so the caller can
+// show "20 of N". providerIds must be non-empty: an empty list makes TMDB
+// drop the provider filter and return everything.
+export async function discoverPersonFilms(opts: {
+  personId: number;
+  department: PersonDepartment;
+  region: string;
+  providerIds: ReadonlyArray<number>;
+  token: string;
+  language?: string;
+}): Promise<{ films: ReadonlyArray<MediaItem>; total: number }> {
+  const personParam = opts.department === "acting" ? "with_cast" : "with_crew";
+  const data = await tmdbFetch<TmdbDiscoverResponse>(
+    "/discover/movie",
+    opts.token,
+    {
+      [personParam]: String(opts.personId),
+      watch_region: opts.region,
+      with_watch_providers: opts.providerIds.join("|"),
+      with_watch_monetization_types: "flatrate",
+      sort_by: "popularity.desc",
+      include_adult: "false",
+      language: opts.language ?? DEFAULT_TMDB_LANGUAGE,
+    },
+  );
+  assertResultsArray(data, "/discover/movie");
+  return {
+    films: data.results.map((m) => toMediaItem(m, "movie")),
+    total: data.total_results ?? data.results.length,
+  };
+}
+
 export async function getRegionProviders(
   region: string,
   token: string,
@@ -296,6 +491,18 @@ const REGION_PIN_ORDER: Record<string, ReadonlyArray<number>> = {
     11,   // MUBI
     188,  // YouTube Premium
   ],
+  US: [
+    8,    // Netflix
+    9,    // Amazon Prime Video
+    1899, // HBO Max
+    337,  // Disney Plus
+    15,   // Hulu
+    350,  // Apple TV+
+    386,  // Peacock Premium
+    2303, // Paramount Plus Premium
+    43,   // Starz
+    526,  // AMC+
+  ],
 };
 
 export function applyRegionPinning(