# Screen Runtime Delivery Investigation

## Question
- TVs with limited connectivity should not have to download the broader Ballbox Next runtime just to play scheduled media.

## Current State
- Historical baseline: `/screens/[screenId]` was rendered from the Ballbox Next host app through a client component in `components/screen-player.tsx`.
- Current production direction: `/player/[screenId]` is served from Ballbox as plain HTML + JavaScript.
- Runtime behavior already depends mostly on browser primitives:
  - `fetch`
  - `CacheStorage`
  - `URL.createObjectURL`
  - `setInterval`
  - `localStorage`
  - `<video>`
- Measured current client chunks for the legacy `/screens/[screenId]` build:
  - `/_next/static/chunks/050hxdgi1a4mo.js`: 5,786 bytes
  - `/_next/static/chunks/15f4hissf3db_.js`: 54,628 bytes
  - `/_next/static/chunks/0-mbqwx08vb4q.js`: 13,855 bytes
  - total known route client JS: 74,269 bytes uncompressed
- That number excludes HTML, RSC payload, request overhead, and future shared-chunk drift.

## Why This Matters
- TVs are a constrained runtime, not a general app surface.
- Hydration and app-router plumbing add bytes and moving parts without helping actual playback.
- A player that is mostly timers, fetches, cache operations, and a `<video>` element is a poor fit for a framework-heavy delivery path when connectivity is the bottleneck.

## Constraints To Keep
- Ballbox should remain the source of truth for:
  - `/api/tvs/manifest/[screenId]`
  - `/api/tvs/heartbeat`
  - `/api/tvs/impression`
- Existing DB ownership, contracts, and admin flows should stay in Ballbox.
- Offline cache/object-URL behavior must remain first-class.
- Diagnostics for real-device verification should remain available.

## Options
### Option A
- Keep the current Next page.
- Pros:
  - no migration work
  - shared tooling and test setup
- Cons:
  - still ships Next/React client runtime to TVs
  - hydration cost remains
  - weakest fit for low-connectivity devices

### Option B
- Keep Ballbox APIs, but replace the screen page with a minimal HTML + vanilla JS player shell.
- Delivery shapes:
  - static shell under `public/`
  - or a dedicated `route.ts` HTML response that does not participate in layouts/client-side navigation
- Pros:
  - best byte reduction without creating another service
  - no React hydration requirement
  - runtime can be tuned directly for kiosk behavior
  - Ballbox still owns deployment and APIs
- Cons:
  - requires extracting runtime logic out of React component state/hooks
  - separate test surface for the lightweight shell

### Option C
- Split the player into a separate static app/repo/deployment.
- Pros:
  - strongest isolation from host app complexity
  - can optimize caching/CDN/deploy cadence independently
- Cons:
  - extra deployment surface
  - duplicated operational/debug burden
  - more auth/config coordination
  - likely unnecessary before Option B is tried

### Option D
- Keep React, but move the player into a separate lightweight SPA.
- Pros:
  - some UI ergonomics preserved
- Cons:
  - still ships framework/runtime bytes
  - weaker payoff than Option B
  - adds build complexity without removing the main problem

## Recommendation
- Choose Option B.
- Keep Ballbox as the API/backend host.
- Build a minimal player shell that uses plain browser APIs and no Next app-router/client-component runtime on the device path.
- Keep the runtime surface focused on the lightweight player.

## Suggested Shape
1. Extract playback/cache/reporting logic from `ScreenPlayer` into framework-agnostic modules.
2. Serve a dedicated player shell for TVs:
   - candidate path: `/player/[screenId]`
   - implementation: HTML response plus one small ES module
3. Reuse the current Ballbox APIs unchanged.
4. Keep the diagnostics panel in the lightweight shell.
5. Legacy `/screens/[screenId]` path removed in favor of `/player/[screenId]`.

## Migration Notes
- Start by extracting logic, not by creating a new deployment.
- Preserve Playwright coverage by pointing the offline/runtime specs at the new shell once ready.
- Do not move manifest/reporting/auth logic out of Ballbox in the same step.
- Treat the TV runtime as an explicit repo-level exception: inside Ballbox, but outside the Next client runtime.

## Sources
- Next.js route handlers: https://nextjs.org/docs/app/getting-started/route-handlers-and-middleware
- Next.js server/client component model: https://nextjs.org/docs/app/getting-started/server-and-client-components
- Next.js navigation behavior: https://nextjs.org/docs/app/getting-started/linking-and-navigating
- MDN CacheStorage: https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage
- Workbox runtime caching overview: https://developer.chrome.com/docs/workbox/caching-resources-during-runtime/