# Showpane Showpane turns a TV into a display for a user's AI agents: the agent sends a page, the TV shows it. ## What is stored - The user's paired TVs (name, when last connected). - Pages agents asked a TV to show (HTML or URL, title, which token), deleted after 30 days. - Personal access tokens and the tokens of connected apps, as hashes only. ## Access Send `Authorization: Bearer shp_...` with a personal access token. The user creates one at https://showpane.lbyte.app/ under Agent access (30 or 90 days, shown once). Never repeat the token in chat or write it to a file the user did not ask for. MCP clients that support OAuth need no pasted token: connect to https://showpane.lbyte.app/mcp and follow the 401. The server publishes `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, accepts a client ID metadata document (an https `client_id`) or registration at `/oauth/register`, and requires PKCE (S256). The user approves the scopes (`tv:read`, `tv:show`) and which TVs; access tokens last an hour and refresh for up to 90 days. - 401 `unauthenticated`: the token is wrong, revoked or expired. Ask the user for a new one, or sign in again. - 403 `insufficient-scope`: the user did not give this connected app that permission. - 403 `session-required`: browser-only action. Creating and revoking tokens and pairing or removing a TV are done by the user at https://showpane.lbyte.app/, not by agents. ## Task loop 1. `GET /api/tvs` lists TVs: `id`, `name`, `online`, `mode`, `showing`. With several TVs and no clear target, ask the user which one. 2. `POST /api/tvs/{tvId}/show-html` with `{"html": "...", "title": "Weekly report"}` for anything you generate. One self-contained page, at most 512 KB. The page is laid out 1920 CSS pixels wide and one screen is 1080 tall, on every TV. Use large type (body 36px or more) and high contrast. There is no mouse, touch or keyboard: the user holds a TV remote with up, down, left, right, OK and Back. Prefer a page that fits one screen and needs no remote: the user may be across the room, hands busy, or talking to you by voice. Longer content is fine when it is worth reading: a page taller than the screen scrolls, up and down move most of a screen, so let it flow down the page, lead with what matters, do not set overflow: hidden on html or body, and tell the user they can scroll with the remote. Arrows and OK also reach the page as keydown events (ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Enter), for slides or a menu you build yourself; call preventDefault to keep up and down from scrolling. Links and buttons cannot be clicked unless you handle those keys. Back always closes the page. While the TV is in screensaver mode (see mode in list_tvs) nobody holds the remote, so put what matters on the first screen. 3. `POST /api/tvs/{tvId}/show-url` with `{"url": "https://...", "title": "..."}` for an existing https page. The TV cannot sign in to sites. 4. `POST /api/tvs/{tvId}/open-link` with `{"url": "https://www.youtube.com/watch?v=..."}` for a link that belongs to an app on the TV (YouTube, Spotify and the like; these do not play through show-url). It answers `{"opened": true}` (which app took it is not disclosed), or `opened: false` with a `reason`: `offline` (nothing is queued), `no-app`, or `no-answer` (the TV app may need an update). That app takes the screen, so the TV is offline here until the user returns. 5. `POST /api/tvs/{tvId}/find-title` with `{"kind": "movie", "query": "Dune", "year": 2021}` (`kind` is `movie` or `show`; `year` is optional) when the user wants to watch or look up a title. The TV's movie app opens on its results (`opened: true`), or with no such app the TV shows a public search page (`shown: true`). `reason: offline` means nothing happened. For one exact title, open-link with its themoviedb.org or imdb.com title page opens it in that app. 6. show-html and show-url replace the current display and answer `{"tv": {...}, "delivered": true|false}`. `delivered: false` means the TV is offline, or its `mode` is `settings`; the page appears when the user opens Showpane there, or leaves its settings page. Tell them. 7. `GET /api/tvs/{tvId}` reports what is on screen. It covers this app only, not other apps on the TV. The person at the TV can dismiss a display with the remote. Ask before replacing something the user may still be looking at. ## Interfaces - OpenAPI: https://showpane.lbyte.app/openapi.json - MCP (Streamable HTTP, stateless, bearer token or OAuth): https://showpane.lbyte.app/mcp with tools `list_tvs`, `get_status`, `show_html`, `show_url`, `open_link`, `find_movie`, `find_show`