Convert Twitch controls to video overlay

docs/testing.md

@@ -36,6 +36,37 @@ Twitch identities; they do not require credentials.
 The local-only endpoints `/api/dev/spawn` and `/api/dev/redemption` exist only while
 `TWITCH_ENABLED` is false.
 
+## Local video-overlay verification
+
+The production viewer path is `/extension`. It is safe to open directly, but it
+waits for Twitch authorization when it is not inside Twitch. While running the
+synthetic local backend, open:
+
+```text
+http://localhost:3000/extension?dev=1&debug=1
+```
+
+`dev=1` exposes the existing **Local viewer login** inside the overlay so the
+same controller and API flow can be exercised without Twitch. `debug=1` draws a
+cyan control-region boundary and a pink controller boundary. Both switches are
+accepted only on `localhost`, `127.0.0.1`, or `[::1]`, so the diagnostics cannot
+be enabled on the deployed Extension origin.
+
+Verify at 1920×1080, 1280×720, and a narrower or 4:3 viewport:
+
+- the document and empty overlay canvas remain transparent;
+- controls stay within the upper-left debug boundary and remain readable;
+- the dungeon, log, branding, and status tiles are absent from `/extension`;
+- only buttons (and the local-only login form) accept pointer events;
+- Up, Down, Left, Right, Attack, Heal, and Pass reach the same backend routes;
+- missing character, dead character, non-player phase, and zero-AP states still
+  disable the controls; and
+- loading `/` still presents the full local game and controller.
+
+Remove the query string for the production-shaped local view. Twitch-hosted
+testing still must cover identity sharing, player ownership, theater mode,
+fullscreen, embeds, ads/pauses, and Twitch player-control safe zones.
+
 ## Live-channel campaign
 
 After completing `docs/twitch-setup.md`, use two follower accounts and one

docs/twitch-setup.md

@@ -70,18 +70,37 @@ token file inside the repository or a web-served directory.
 
 ## Extension configuration
 
+Twungeon's production viewer is a **Video Overlay Extension**. Twitch's current
+Extension Manager labels this asset type **Video - Fullscreen** and its path
+field **Video - Fullscreen View Path**. This is a manual dashboard setting; the
+repository has no manifest that can change an Extension version in Twitch.
+
 1. Create a Twitch Extension separately from the confidential OAuth
-   application. In the Extension Manager, use a testing base URI ending in
-   `/`, select a video component, and set its viewer path to `extension`.
-2. Enable **Request Identity Link**. The viewer must click **Share Twitch
-   identity** in the component; the Extension Helper then invokes
+   application, or create a new test version of the existing Twungeon
+   Extension.
+2. On **Asset Hosting**, set **Testing Base URI** to the public HTTPS Twungeon
+   origin with a trailing `/`.
+3. Under **Type of Extension**, enable **Video - Fullscreen** (the video-overlay
+   placement) and set **Video - Fullscreen View Path** to `extension`. Do not
+   use **Video - Component** for the production viewer. If a component entry is
+   retained temporarily for development, it may point at the same shared page,
+   but the overlay placement is the supported viewer experience.
+4. On **Capabilities**, enable **Request Identity Link**. The viewer must click
+   **Share Twitch identity** in the overlay; the Extension Helper then invokes
    `requestIdShare()` from that user gesture and supplies a new JWT through
    `onAuthorized`.
-3. A JWT without `user_id`, with the wrong
+5. Put the version in Local Test or Hosted Test and activate it in the channel's
+   video-overlay slot. Changing an already released version may require a new
+   Extension version and Twitch review; the repository cannot submit or
+   activate that version automatically.
+6. Test the overlay while live in normal, theater, fullscreen, and a narrow
+   player. The video player and stream supply the game frame; `/extension`
+   should show only the upper-left controls on a transparent canvas.
+7. A JWT without `user_id`, with the wrong
    `channel_id`, an expired signature, or an `external` role is rejected.
-4. Keep the Extension secret only in the backend environment. It must never be
+8. Keep the Extension secret only in the backend environment. It must never be
    included in the UI bundle or URL.
-5. Start with `npm run build && npm start`. Confirm `/health` returns `ready:
+9. Start with `npm run build && npm start`. Confirm `/health` returns `ready:
    true` and `twitchMode: "configured"` after chat connects.
 
 The Extension JWT is exchanged for a random 15-minute Twungeon session. A