Movie Bowl

Live app: moviebowl.app

Movie night decided the way a lot of households already do it: everyone writes a title on a slip of paper, the slips go in a bowl, and somebody pulls one out.

Movie Bowl is that bowl, shared and online. Everyone adds the titles they want to watch, and when it is time to pick, the app draws one.

A real bowl of slips gives the odds to the paper: someone who wrote twenty-five slips is twenty-five times likelier to win than someone who wrote one. The default draw here deliberately does not work that way. It picks a person first, evenly, from everyone who still has a title in the running — then a title from that person. Adding more movies gives you more ways to be chosen, not a better chance of being the one chosen.

A bowl's owner can switch it to the flat version, where the odds do follow the count, or to a rotation that gives the next turn to whoever has waited longest.

What It Does

Bowls

• Create bowls, invite people by email, and manage members.
• On a first run, name your bowl and create it directly from My Bowls. The new bowl opens immediately, with starter packs available to get it going.
• Land in your home bowl on arrival. Move it with Make [bowl] home in the bowl picker on the dashboard header — a home bowl can be moved but never unset, so nothing toggles it off. The bowl directory marks which one is home and offers no control to change it.
• Add movies with the header +. On a bowl page it uses that bowl; elsewhere it uses your home bowl. On the first-run card, it focuses the bowl name field.
• Manage who is allowed to draw, per bowl (everyone, or a selected allow-list).
• Create public add links so people without accounts can add a fixed number of titles.
• Share a bowl you own from its header, which opens Invitations on that bowl.
• Pour a starter pack (a filmography or Best Picture winners by decade) into a bowl you own so it can reach a first draw before everyone has added titles.

Movies

• Add movies from TMDB search, or add custom/manual entries. One field searches titles, people, and descriptions ("space movie where Matt Damon is stranded"); see Described search. Results mark titles already in this bowl, watched, or in another of your bowls.
• On Android, the installed app's long-press "Add a movie" shortcut and the share sheet open the add sheet on your home bowl (/quick-add).
• Mark one of your own titles as a favorite: when the draw picks you, that is the title that comes up, as long as the filters leave it in the pool.
• The add dialog keeps a compact count of movies added during the session. Open it to add or edit a comment, or remove a movie from its original bowl after confirming. Closing ends the list, not the saved additions; pending saves continue safely.
• Open full movie details from a newly drawn movie, from search results, or from a watched movie card.
• Watch TMDB trailers inline from movie detail views, preferring an official English trailer and falling back through teasers and unflagged studio uploads.

The draw

• Draw a random movie by first choosing an eligible contributor bucket uniformly, then choosing one movie from that bucket.
• Or let the bowl owner switch the bowl to a straight title-by-title draw, where every movie in the bowl is equally likely.
• Or use contributor rotation: people who have never had a title drawn go first, then the least recently selected eligible contributor gets the next turn. Ties and the title within that person's pool are random.
• Narrow the pool in the bowl’s Filters overlay with rating, genre, runtime, and streaming priority. Changes save automatically across your bowls, and a television follows them except where that television has been told otherwise. Reset clears filters without changing playback settings.
• Optionally prioritize titles on your streaming services. With service ranking on, the draw keeps only the highest-ranked service that actually matched, so an unmatched service falls through to the next one.
• Add a subscription service from the drawn movie's Where to watch list by tapping its + pill. It saves to your account's streaming preferences.
• See reported US departures from your saved services in search and movie details, with a small Leaving soon marker on My Movies cards. Departure dates come from Movie of the Night. Saved bowl titles refresh them on demand; search and unsaved details show only notices already in the shared cache.
• See the bowl's active draw method explained without surfacing competitive odds, and watch the draw replay it: a full-screen reveal sorts the pool into each person's pile (or one crowd) and lands on what was drawn.
• When none of your services carry the drawn movie, rent it from a store that does.
• Draw just for yourself with solo draw (/solo-draw), from the bowls you belong to.
• Put a drawn movie back for two hours after the draw, for when the group did not end up watching it. That window bounds the action, not just the cleanup: a return is refused afterwards, and a permitted one also removes the personal history the draw created, because the group did not watch it. Add the movie again to watch it another night.

History

• Track bowl activity in a horizontal watched-movie strip.
• Keep a personal watch list at /watch-list that survives leaving or deleting a bowl, including manually added entries.
• Export watched titles as a Letterboxd-compatible CSV.

TV

• A separate TV experience at /tv with D-pad/remote spatial navigation, a bowl picker, and a theater-mode trailer pre-roll before the pick is revealed.
• A draw is treated as the decision: the result appears without a second acceptance step, and configured theater-mode previews begin automatically.
• Provider actions hand off to installed television apps when possible and keep the drawn result available when the viewer returns to Movie Bowl.
• Change the draw settings from the couch. What the remote changes belongs to that television and not to the account: anyone in the room can pick it up, so relaxing a filter tonight must not rewrite what the account owner browses with tomorrow. While this television is deciding anything for itself, the panel offers Use my phone's settings, which hands it all back at once.

Tech Stack

• React 19 + Vite 7
• React Router 7
• Supabase (auth, Postgres, RLS)
• Vercel serverless functions for anything needing a secret
• Tailwind CSS
• Vitest + Testing Library for unit and component tests
• Playwright for the end-to-end smoke suite

Local Setup

New to the project? Start with ONBOARDING.md: it covers a first week, a local backend of your own, and what not to touch yet. The steps below are the full production configuration.

Provider title links are optional and off until configured; production has them enabled. See Provider title links for activation and cache maintenance.

1. Use Node 24 LTS and install dependencies (with nvm):

nvm install
nvm use
npm ci

2. Create .env with:

VITE_SUPABASE_URL=...
VITE_SUPABASE_ANON_KEY=...
TMDB_READ_ACCESS_TOKEN=...
SUPABASE_URL=...
SUPABASE_SECRET_KEY=...
TV_PAIRING_RATE_LIMIT_SECRET=...
CRON_SECRET=...
APP_BASE_URL=https://moviebowl.app
RESEND_API_KEY=...
INVITE_EMAIL_FROM="Movie Bowl <[email protected]>"

SUPABASE_URL should match VITE_SUPABASE_URL.

3. Run locally.

For full local behavior, including /api/* routes:

npm run dev:api

If you only need frontend-only iteration, you can still use:

npm run dev

npm run dev does not serve the serverless functions, so /api/* requests 404 — TMDB search, invite email, and public add links need npm run dev:api.

Run it through the script rather than a bare vercel dev. The CLI is pinned as a devDependency here, and a globally installed one can be old enough to reject this repo's vercel.json outright: has on a headers rule postdates CLI 21, and that rule is what scopes the no-cache header to HTML documents, so it cannot simply be removed.

Scripts

• npm run dev - start dev server (frontend only)
• npm run dev:api - dev server including the /api/* serverless routes
• npm run build - production build
• npm run preview - preview production build
• npm run lint - run ESLint
• npm run test - start Vitest in watch mode
• npm run test:run - run tests once
• npm run test:failures - name what failed in the last test:run
• npm run test:counts - check the last runs lost no test against main
• npm run test:coverage - run tests with coverage
• npm run test:e2e - run the local Playwright smoke suite
• node scripts/refresh-provider-logos.mjs - regenerate src/utils/providerLogos.js

Project Layout

src/
  main.jsx           AuthProvider -> App
  App.jsx            router, route guards, invite acceptance
  screens/           one screen per route, lazily imported
  components/        shared UI
  hooks/             stateful data layer (useBowl, useAuth, useAutosave, ...)
  lib/               external-service clients (supabase, tmdbApi, streamingProviders)
  utils/             pure logic (draw selection, filters, formatting, storage)
  tv/                self-contained TV experience: own screens, hooks, css
  index.css          design tokens + shared component classes
api/                 Vercel serverless functions (not part of the Vite build)
  _lib/              server-only helpers (supabaseAdmin, tmdb)
supabase/
  migrations/        source of truth for schema, RLS, functions
  tests/             pgTAP tests for security-sensitive migrations
  rollback/          staged reverts, kept out of migrations/ on purpose
tv-android/          Google TV WebView shell around /tv; now in an owner-only
                     Google Play internal test. Has its own README
android-mobile/      disposable Android App Actions probe. It does not contain
                     the product app
output/designs/      design specs and roadmaps for shipped + planned features

Routes

/ (resolves your home bowl, or /bowls when you have none), /bowls, /bowl/:bowlId, /bowl/:bowlId/settings, /settings, /watch-list, /invites, /about, /login, /accept-invite/:token, /add-to-bowl/:token, /activate-tv, /voice-probe/privacy, /tv/*.

Everything except /login, /about, /accept-invite/:token, /add-to-bowl/:token, /activate-tv, and /voice-probe/privacy requires a signed-in user.

/bowls never redirects. / computes a destination; /bowls computes nothing and always renders, which is what makes it the recovery surface every failed resolution links back to.

Key Files

• App shell/routes: src/App.jsx
• Bowl state and draw handlers: src/hooks/useBowl.js
• Draw filtering: src/utils/drawSelection.js
• Draw candidate selection: src/utils/selectDrawCandidate.js
• Contributor bucketing: src/utils/drawBuckets.js
• User streaming settings hook: src/hooks/useUserStreamingServices.js
• Bowl dashboard UI: src/screens/BowlDashboard.jsx
• Bowl settings UI: src/screens/BowlSettings.jsx
• User settings UI: src/screens/UserSettings.jsx
• Watch list UI: src/screens/WatchListPage.jsx
• TV experience: src/tv/TvApp.jsx
• Invite email route: api/invites/send.js
• Public add-link routes: api/add-links/*

For how the code is put together and the conventions to follow when changing it, see CLAUDE.md. For reliability guardrails and the release smoke checklist, see STABILITY.md. TODO.md is the live backlog.

Streaming-Service Logic

• User picks services in User Settings.
• Service names are normalized in src/utils/streamingServices.js.
• Provider availability is fetched from TMDB:
  • src/lib/streamingProviders.js
  • proxied through server routes in api/tmdb/* so the TMDB key stays server-side
  • includes in-memory caching + in-flight request deduping
  • the same response carries each provider's logo, which is why showing one costs no extra request
• Draw behavior:
  • if the prioritize toggle is on and matches exist, draw from matches
  • with service ranking on, keep only the highest-ranked service that actually matched, so an unmatched service falls through to the next one
  • if no matches, fall back to all titles that survived the other draw filters
• This narrowing happens before the draw method, so it changes which titles and contributors are eligible. Person-first still gives each represented contributor equal odds; rotation considers only represented contributors.

Environment Variables

Browser-visible

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY

These are visible in the browser bundle by design.

Server-only

• TMDB_READ_ACCESS_TOKEN
• SUPABASE_URL
• SUPABASE_SECRET_KEY (preferred) or SUPABASE_SERVICE_ROLE_KEY (legacy compatibility)
• TV_PAIRING_RATE_LIMIT_SECRET
• CRON_SECRET
• FILTER_METADATA_DAILY_MAX_TITLES (optional emergency override; defaults to 300)
• APP_BASE_URL
• RESEND_API_KEY
• INVITE_EMAIL_FROM
• FEEDBACK_EMAIL_TO (optional; where feedback is mailed, defaulting to the support address)
• WATCHMODE_API_KEY, PROVIDER_LINKS_ENABLED, PROVIDER_LINKS_MONTHLY_BUDGET — optional, and off unless set; production sets them. See Provider title links.
• MOVIE_OF_THE_NIGHT_API_KEY — optional server secret for US departure notices; no departure lookups run without it. MOVIE_OF_THE_NIGHT_REQUEST_BUDGET may lower the rolling 32-UTC-date cap: 900 in Production, 100 in nonproduction. Nonproduction cannot exceed 100; projects sharing a key must keep their combined budgets within its allowance. Set the secret separately in each deployment environment that should use it.
• GROQ_API_KEY, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_AI_TOKEN — optional; described search is off without them. See Described search.
• EMAIL_DAILY_WARN_THRESHOLD (optional; defaults to 80). See Usage counters.

Do not prefix server-only values with VITE_. The Supabase secret/service-role key bypasses RLS, so every route that uses it must do its own authorization.

TV_PAIRING_RATE_LIMIT_SECRET is a random server-only value of at least 32 characters. It HMAC-pseudonymizes client addresses and user IDs before the pairing rate limiter writes its short-lived counters; raw identifiers are never stored in the counter table.

CRON_SECRET protects the once-daily Vercel filter-metadata refresh. Vercel sends it as a bearer token when invoking the configured cron route.

Usage counters

public.service_usage_counters records how much metered vendor quota the app spends, one row per day per metric, so a cost or capacity question can be answered with a number. Writes go through record_service_usage; no role reaches the table directly, the service role included. Read it as the project owner in the SQL editor:

-- The last fortnight, by metric.
select usage_date, metric, event_count
from public.service_usage_counters
where usage_date >= current_date - 14
order by usage_date desc, metric;

-- This month's totals.
select metric, sum(event_count) as events
from public.service_usage_counters
where usage_date >= date_trunc('month', current_date)::date
group by metric;

Counters are daily rather than monthly on purpose. The mail cap that threatens this app is a daily one, and a monthly total cannot see a single day's burst inside it; a month is the sum of its days, so daily rows answer both questions.

The meter never refuses the action it measures, and every failure to record is swallowed with a logged error. Budgets that must actually hold belong in a function like begin_title_provider_link_fetch, which reserves before HTTP.

Two metrics are recorded today:

• invite_email — one per invite the send route attempted, counted whether or not the vendor accepted it, because a rejected send still spent the quota. Crossing EMAIL_DAILY_WARN_THRESHOLD logs a warning rather than refusing; the vendor enforces its own ceiling, and stopping early would turn "nearly out" into "nobody can be invited."
• tmdb_request — recorded once per daily refresh run with the number of titles claimed, rather than once per title. The run works inside a 60-second budget, and 300 extra round trips would make the meter a cost of its own.

Two things this cannot see. Magic-link authentication mail is sent by Supabase's SMTP after a client call that never reaches these functions, so it is absent from invite_email; the mail vendor's own dashboard is authoritative for total mail. The user-facing api/tmdb/* proxies are also unmetered, which keeps the service-role client out of routes that do not otherwise need it — Vercel's function metrics cover their volume.

Adding a metric means extending the check constraint on service_usage_counters.metric. The constraint is deliberate: a free text column turns one typo into a phantom metric that reads as zero usage forever.

Production Setup

Canonical app domain

• Production app URL: https://moviebowl.app
• Configure moviebowl.app as the primary production domain in Vercel
• In Supabase Auth settings:
  • Site URL should be https://moviebowl.app
  • Allowed Redirect URLs should include:
    • https://moviebowl.app
    • http://localhost:3000
    • optionally http://localhost:5173

Sending domain

• Use a dedicated sending subdomain for email:
  • mail.moviebowl.app
• Verify mail.moviebowl.app in Resend
• Add the DNS records Resend provides for that subdomain
• Recommended sender:
  • Movie Bowl <[email protected]>

Auth email delivery

• The app uses Supabase magic-link auth
• Televisions use /activate-tv for QR pairing while phones and ordinary web browsers retain the magic-link flow
• TV pairing is handled by POST /api/tv-pairing/start, POST /api/tv-pairing/approve, and POST /api/tv-pairing/poll
• Pairing requests expire after ten minutes; only a device-secret hash is stored, and the approved TV receives a single-use Supabase token hash
• Pairing starts are limited per client address, and approvals are limited per client address and authenticated user. Apply 20260905120000_rate_limit_tv_pairing.sql and set TV_PAIRING_RATE_LIMIT_SECRET before deploying the matching server routes.
• To avoid the default Supabase email rate limits, configure custom SMTP in Supabase Auth
• Recommended branded sender:
  • Movie Bowl <[email protected]>

Invite email delivery

• Bowl invites are stored in bowl_invites
• The app sends invite emails through:
  • POST /api/invites/send
• Invite links inside those emails use:
  • APP_BASE_URL

Public add-link delivery

• Bowl members can create public add links in Bowl Settings.
• Public add-link page:
  • /add-to-bowl/:token
• These routes use the Supabase service role on the server:
  • GET /api/add-links/:token
  • POST /api/add-links/consume
• Link users do not need to sign in.

Filter metadata refresh

• Vercel calls GET /api/cron/refresh-filter-metadata once per day.
• The worker uses combined TMDB certification/provider requests, processes at most six titles concurrently, and exits before the Hobby function deadline.
• Successful snapshots remain available when a later refresh fails.
• Every invocation stores attempted, successful, and failed title counts, run duration, completion status, and remaining stale backlog. Reports are private service-role data, retained for 90 days, and visible in the Supabase table editor under tmdb_filter_metadata_refresh_runs.
• Inactive cache rows are removed, and no TMDB-derived snapshot is retained beyond TMDB's six-month cache limit.
• The same run keeps the TMDB details saved beside slips, draws and watch history inside that limit. A title still in a bowl is refreshed from the filter fetch above at no extra cost; one that survives only in history is refreshed at 150 days by a pass of at most 100 titles, in whatever time the filter refresh leaves. Anything not refreshed by six months loses its poster, overview, runtime and genres and keeps its title. A personal history entry never has its title or date overwritten, because a person can edit those, and its freshness is counted from the slip its details were copied from, not from the day it was drawn.
• Adding a signed-in user's TMDB movie also starts a non-blocking single-title warmup through POST /api/tmdb/movie/warm-filter-metadata.

TMDB Attribution

Movie data, provider availability, and provider logos come from TMDB, and using them carries conditions the About page already satisfies:

• "This product uses the TMDB API but is not endorsed or certified by TMDB."
• Watch-provider data must credit JustWatch as its source. TMDB is explicit that access is revoked for usage that does not.

Two consequences worth knowing before changing anything here:

• Logos are shown as TMDB supplies them — not recoloured, cropped, or used as this app's own iconography. Displaying a provider's mark beside its own availability is the nominative case; restyling it is not, and every brand guideline forbids it anyway.
• TMDB content may not be cached beyond six months. src/lib/streamingProviders.js caches for minutes, so it is unaffected. The details copied onto saved rows are refreshed or cleared by the daily run (see "Filter metadata refresh"). src/utils/providerLogos.js is the exception: it is generated, stamped with the day it was made, and has to be regenerated with node scripts/refresh-provider-logos.mjs before that date ages out. A lapse degrades to service names rather than breaking, which is exactly why the deadline is written down in TODO.md.

Data Model

Tables the app touches:

• profiles
• bowls
• bowl_members
• bowl_movies
• bowl_invites
• bowl_draw_permissions
• tv_pairing_requests (server-only; no direct client access)
• tv_pairing_rate_limits (server-only pseudonymous fixed-window counters)
• tmdb_filter_metadata (server-maintained; read through a membership RPC)
• tmdb_filter_metadata_refresh_runs (private 90-day cron run history)
• bowl_add_links
• user_bowl_defaults — the account's home bowl
• bowl_draw_events — immutable bowl-side record of each draw
• user_watch_events — per-participant personal history
• bowl_movie_queue — legacy compatibility table; not written to

profiles.display_name is the only shared member identity. It is optional, non-unique, and limited to 40 characters; shared app and TV surfaces use a neutral Member XXXX fallback and never derive a name from an email address. Email remains visible only to its owner in Account settings and where an invite address is operationally required.

Account deletion is initiated from Settings and completed by the trusted /api/account/delete route. Owners must transfer or delete every bowl first. Cleanup removes suggestions, memberships, preferences, invitation data, and personal watch history; completed bowl history remains with its contributor anonymized as Former member before the Auth user is hard-deleted.

A draw writes one bowl_draw_events row plus one user_watch_events row per participant, which is why personal history survives leaving or deleting a bowl. Returning a movie to the bowl sets returned_at on the draw event rather than deleting it, and return_bowl_draw_to_bowl refuses more than two hours after the draw. Inside that window the return also deletes the personal history rows the draw created, because a return means the group did not watch it. Every surface reads active draws only.

Custom (non-TMDB) movies carry a negative synthetic tmdb_id, so anything that calls TMDB must filter for Number(tmdb_id) > 0 first.

RPCs the client calls (preferred over multi-statement client writes, because they are the atomic and permission-checked path):

get_my_bowls_with_counts, get_my_bowl_context, set_my_default_bowl, get_bowl_profile_directory, get_bowl_filter_metadata, get_my_invite_sender_directory, accept_bowl_invite, create_bowl_invites, revoke_bowl_invite, draw_bowl_movie, draw_bowl_movie_by_rotation, return_bowl_draw_to_bowl, remove_bowl_draw_from_history, save_bowl_draw_access, save_bowl_draw_method, create_owned_bowl, transfer_owned_bowl, delete_owned_bowl, set_own_bowl_movie_pin, update_own_bowl_movie_note, remove_own_bowl_movie, consume_bowl_add_link, install_bowl_starter_pack, remove_bowl_starter_pack, claim_bowl_starter_pack_movie, record_solo_draw, undo_solo_draw, create_manual_watch_event, update_user_watch_event, update_own_watch_event_note, delete_user_watch_event.

delete_account_data_for_user is intentionally absent from that client list: only the service role may execute it, immediately before the server deletes the matching Supabase Auth user.

The interface says home bowl where the database says default. That drift is deliberate — user_bowl_defaults, get_my_bowl_context and set_my_default_bowl are deployed objects and are not renamed to match the word on screen.

Supabase Schema & Policies (Git-tracked)

Store all Supabase schema and RLS/policy changes in supabase/migrations/ with a timestamped filename — never make dashboard-only edits.

Quick workflow:

1. Link CLI to your existing project:

supabase login
supabase link --project-ref YOUR_PROJECT_REF

2. Add new changes (never supabase db pull a baseline migration; the pre-migration schema is supabase/baseline/, kept out of migrations/ on purpose):

supabase migration new short_description

3. Apply to Supabase:

supabase db push

4. Commit migrations to git.

For permission-sensitive changes, add a pgTAP test in supabase/tests/ and a revert in supabase/rollback/. See supabase/README.md for details.

Tests

Tests live in __tests__/ next to the code they cover. Current coverage includes:

• Bowl dashboard and draw flow tests (src/screens/__tests__/BowlDashboard.*.test.jsx)
• Bowl settings and invite integration tests
• Public add-link API and page tests
• Draw selection unit tests (src/utils/__tests__/selectDrawCandidate.test.js)
• Hook-level bowl integration tests (src/hooks/__tests__/useBowl.test.js)
• TV navigation, theater-mode, and per-TV draw settings tests (src/tv/__tests__/)
• pgTAP tests for security-sensitive migrations (supabase/tests/)

Run all tests:

npm run test:run

The Playwright smoke suite exercises the release-critical flows in a real, headless Chromium browser at desktop and mobile sizes. It supplies an isolated in-memory Supabase/API boundary, so it never needs production credentials or data and does not require the serverless routes. Install Chromium once, then run it with:

npx playwright install chromium
npm run test:e2e

TV-specific checks run only in the desktop project. Failures retain a trace, screenshot, and video in test-results/; the HTML report is written to playwright-report/. Both directories are gitignored.

A clean checkout is expected to be fully green, with lint reporting zero warnings. Run npm run test:run, npm run test:e2e, and npm run build before committing anything non-trivial. npm run test:counts compares each suite's last run with the commit the branch grew from, so a lost test is visible rather than silent.

The end-to-end suite is in that list rather than in a release checklist because leaving it out did not hold: it was red on a clean checkout through three separate merges, every failure a selector still describing an interface that had been deliberately replaced. A suite that is red by default cannot report a regression.

Described search

A search that reads like a description ("space movie where Matt Damon is stranded") rather than a title or a name goes to a small language model, which turns it into TMDB terms and may name titles it recognizes from a quote or a scene; TMDB's discover endpoint finds the movies, and a named title is shown only when TMDB has a movie by exactly that name. A search that finds a title or a person never reaches the model; one of four or more letters that finds nothing does, since a misspelled name is what it reads well. Both providers are free tiers, tried in order:

GROQ_API_KEY=...            # console.groq.com, free plan
CLOUDFLARE_ACCOUNT_ID=...   # Workers AI, free daily allocation
CLOUDFLARE_AI_TOKEN=...     # API token with Workers AI read permission

Either one is enough. GROQ_MODEL, GROQ_REASONING_EFFORT and CLOUDFLARE_AI_MODEL override the models without a code deploy. With neither, or when both are over their daily limit or down, a described search shows ordinary title results with a struck-through sparkle and "Smart search is resting." It is offered to signed-in people only, so a public add link never spends the quota. Do not use Gemini's free tier here: Google may review what is sent, and its terms bar serving EU or UK users on it. See output/designs/described-search.md.

Provider title links

Phone and TV draw results can open the chosen service's title page instead of its search page. The saved service order and the phone's opt-in setting are unchanged. Only subscription/free sources open as a service. Rental and purchase links are filed under the store that sells them. Rental links alone feed the rent button a drawn movie offers when none of your services carry it; purchase links are cached but never used; the TV offers Apple TV and Prime Video, the two stores the Google TV app can hand off to. A title link does not guarantee automatic playback or bypass a subscription.

To activate. Production is already activated, so these steps are for a new environment, such as a local .env or a fresh Vercel project:

1. Apply supabase/migrations/20260830120000_add_title_provider_links.sql before deploying the server code. The new tables and maintenance RPCs are private to the service role; the lookup route verifies both the bearer token and access to the requested bowl/title.

2. Create a Watchmode key with US access. The intended free, non-commercial setup has no payment card attached. Store these server-only values in local .env and the relevant Vercel environment (never use VITE_):

   WATCHMODE_API_KEY=...
   PROVIDER_LINKS_ENABLED=false
   PROVIDER_LINKS_MONTHLY_BUDGET=500
   

3. Verify the existing daily /api/cron/refresh-filter-metadata job is running, then set PROVIDER_LINKS_ENABLED=true and restart/redeploy. Use npm run dev:api locally because Vite alone does not serve the lookup API.

Lookups happen after a signed-in member adds a TMDB movie and during a draw's animation. Public add links, custom titles, and detail/browse screens do not spend requests. A ten-minute browser cache deduplicates calls, and Supabase caches results for up to 30 days. Failures back off from five minutes to one day. The monthly budget is reserved atomically before HTTP and counts requests, including failed requests; Watchmode currently charges two credits per TMDB lookup, so the default caps this integration at 1,000 credits per UTC month. Requests made outside this integration are not counted by this budget.

The free plan requires attribution and deletion/refresh within 30 days. Direct links display Watchmode attribution. The existing daily job deletes rows at 29 days (no vendor requests), even when lookups are disabled; lookups and the browser cache also refuse expired data. Monitor failures of that daily job. If the Watchmode account is cancelled, disable lookups and delete the stored vendor data using delete from public.title_provider_links; as an administrator.

Missing key, disabled flag, lookup errors, and quota exhaustion all retain the existing search fallback. The immediate rollback is to disable the flag and redeploy (open clients can retain a cached result for ten minutes). The schema rollback is in supabase/rollback/20260830120000_remove_title_provider_links.sql; revert the server's cleanup call before removing its RPC.

The account-deletion, provider-lookup, filter-metadata warmup, starter-pack candidate and starter-pack photo URLs share api/movie-cache.js through explicit rewrites in vercel.json. Their private handlers live in api/_lib/; keeping them together holds the deployment at Vercel Hobby's 12-function limit without changing the client URLs or authentication checks.

Native iOS/Android URLs are optional: Watchmode's free plan does not include them. They are retained when supplied, but this phase uses web URLs only. Vendor details verified against Watchmode's API documentation, plan information, and caching terms on August 30, 2026.