Refine extension panel workflows and app surfaces (#56)

* Complete request blocking and blacklist rules

* Add interactive extension panel demo

* Refine extension workflows and app surfaces

- expand Twitch panel request, moderation, demo, and hosted-build flows
- preserve playlist ordering across VIP/current transitions and targeted edits
- refresh shared app surfaces, homepage messaging, and pagination motion

Author: Jamesllllllllll

docs/twitch-panel-extension-beta-rollout-checklist.md

@@ -95,6 +95,8 @@ When you build the Hosted Test artifact, make sure the shell sets the final app
 VITE_TWITCH_EXTENSION_API_BASE_URL=https://your-app-host npm run build:extension:panel
 ```
 
+The build requires `VITE_TWITCH_EXTENSION_API_BASE_URL` or `APP_URL`. If neither is set, it fails instead of falling back to the Twitch asset host.
+
 Upload the contents of:
 
 ```text

docs/twitch-panel-extension-feature-request.md

@@ -1,76 +1,24 @@
-# Feature Request: Twitch Panel Extension For Playlist Viewing And Viewer Song Requests
-
-## Scope
-
-RockList.Live includes a Twitch panel extension that gives viewers a Twitch-native request surface on the channel page.
-
-The panel supports:
-
-- read-only playlist viewing without identity sharing
-- current queue and now-playing state
-- linked viewer request actions:
-  - add regular request
-  - add VIP request
-  - edit current request
-  - remove own request
-- linked viewer summary:
-  - display name
-  - VIP token balance for the active channel
-  - current request count and limit
-- requester attribution on playlist items
-- owner and moderator playlist actions when the linked viewer has channel access:
-  - play now
-  - mark played
-  - delete item
-  - switch request kind between regular and VIP when VIP-token management is allowed
-
-## Auth And Access Model
-
-- The panel verifies the Twitch Extension JWT on the server.
-- The active Twitch `channel_id` resolves the RockList.Live channel.
-- The linked Twitch `user_id` resolves the same app user used by the website.
-- Panel write actions require linked identity.
-- Panel moderation actions require linked identity plus channel access for the current Twitch channel.
-- Moderator access follows the channel's existing moderator capability settings in RockList.Live.
-
-## MVP Experience
-
-### Viewers
-
-- open the panel on Twitch
-- view the playlist without leaving Twitch
-- share Twitch identity when they want to request songs
-- search the catalog
-- add, edit, or remove their own request
-- spend existing RockList.Live VIP tokens from the panel
-
-### Streamers And Moderators
-
-- open the panel on the live channel page
-- view the active queue
-- use compact playlist actions directly from the panel when they have access for that channel
-- rely on the same queue mutation rules and playlist state used by the main app
-
-## Current Technical Shape
-
-- Extension Backend Service routes live under `src/routes/api/extension`
-- linked viewers resolve through `users.twitchUserId`
-- playlist moderation uses the shared playlist-management service
-- viewer request actions use the shared viewer-request service
-
-## Recommended MVP Acceptance
-
-- A connected channel can install the panel and load playlist state.
-- Unlinked viewers can read the playlist.
-- Linked viewers can add, edit, and remove their own requests.
-- Linked viewers can see their VIP token balance for the current channel.
-- Stream owners can manage the playlist from the panel.
-- Twitch moderators can manage the playlist from the panel when the channel settings allow it.
-- Request behavior matches the website and chat request policy.
-- The panel is documented for Local Test, Hosted Test, and self-hosted deployment.
-
-## Notes
-
-- The panel identity-share flow and the website session are separate.
-- Opening the website from the panel does not create a website app session by itself.
-- Website sign-in still uses the normal Twitch OAuth flow on `rocklist.live`.
+# Twitch Panel Extension
+
+RockList.Live includes a Twitch panel extension that keeps playlist viewing and viewer requests on the channel page.
+
+## Viewer surface
+
+- Viewers can read the playlist without identity sharing.
+- Linked viewers can search the catalog, add regular requests, add VIP requests, edit the current request, and remove their own request.
+- Blocked viewers can still view the playlist and search the catalog. Request actions stay unavailable.
+- When the channel blacklist is enabled, blacklisted artists, charters, songs, and versions stay hidden in panel search.
+- Channel search filters such as official-only, allowed tunings, and required parts stay active in panel search.
+- The panel does not expose a toggle for showing blacklisted results.
+
+## Owner and moderator surface
+
+- Owners can manage the playlist from the panel.
+- Moderators can manage the playlist when the channel settings allow those actions.
+- Playlist actions use the same management service as the website.
+
+## Shared services
+
+- Viewer request actions use `src/lib/server/viewer-request.ts`.
+- Playlist management actions use `src/lib/server/playlist-management.ts`.
+- Search uses `src/lib/server/extension-panel.ts`.

docs/twitch-panel-extension-implementation-plan.md

@@ -1,178 +1,32 @@
-# Twitch Panel Extension Implementation Plan
-
-## Purpose
-
-The Twitch panel extension acts as a compact RockList.Live client inside Twitch. It lets viewers work with the active channel playlist without using chat commands, and it lets the channel owner or channel moderators perform core playlist actions directly from the panel.
-
-## Current MVP Surface
-
-### Viewer capabilities
-
-- read the playlist without linking identity
-- share Twitch identity from the panel
-- search the channel-aware catalog
-- add a regular request
-- add a VIP request when the viewer has a spendable RockList.Live VIP token
-- edit the current request
-- remove the current request
-- view VIP token balance and current request usage for the active channel
-
-### Owner and moderator capabilities
-
-- view the current queue in the panel
-- set a queued song as current
-- mark the current song as played
-- delete a playlist item
-- switch a request between regular and VIP when the channel permissions allow VIP-token management
-
-## Channel Access Model
-
-- The panel trusts only the verified Twitch Extension JWT.
-- The active `channel_id` resolves the RockList.Live channel.
-- The linked `user_id` resolves or creates the matching RockList.Live user by `twitchUserId`.
-- The panel resolves access for the current channel as one of:
-  - `owner`
-  - `moderator`
-  - `viewer`
-- Moderator access follows the channel's existing moderator capability settings.
-
-## Shared Services
-
-### Viewer request service
-
-Viewer request actions go through the shared viewer-request service.
-
-This keeps the same behavior for:
-
-- request-policy checks
-- duplicate checks
-- queue-limit checks
-- VIP-token spending
-- add, edit, and remove behavior
-
-### Playlist management service
-
-Owner and moderator playlist actions go through the shared playlist-management service.
-
-This keeps the same behavior for:
-
-- playlist mutation permissions
-- queue mutation calls into the backend worker
-- request-kind changes
-- audit and actor attribution
-
-## API Surface
-
-### Bootstrap and viewer request routes
-
-- `GET /api/extension/bootstrap`
-- `GET /api/extension/search`
-- `POST /api/extension/request`
-- `POST /api/extension/request/edit`
-- `POST /api/extension/request/remove`
-
-### Playlist management route
-
-- `POST /api/extension/playlist`
-
-Supported playlist actions:
-
-- `setCurrent`
-- `markPlayed`
-- `deleteItem`
-- `changeRequestKind`
-
-## Front-End Surface
-
-The panel UI lives in:
-
-- `src/extension/panel/index.html`
-- `src/extension/panel/main.tsx`
-- `src/extension/panel/app.tsx`
-
-The current panel UI includes:
-
-- compact header with channel title and linked-viewer summary
-- playlist and search tabs
-- dense queue rows with requester attribution and timestamps
-- linked-viewer request highlighting
-- transient success and error notices
-- loading skeletons during Twitch helper auth and bootstrap
-- inline remove confirmation for viewer-owned requests
-- compact moderation controls on playlist rows for authorized users
-
-## Twitch Setup
-
-The Twitch extension version should use:
-
-- panel anchor
-- request identity link enabled
-- URL fetch allowlist for the app origin that serves `/api/extension/*`
-
-Local Test can point at:
-
-- the in-app route: `/extension/panel`
-- or the standalone build artifact from `npm run build:extension:panel`
-
-## Hosted Test And Review
-
-The panel is ready for Local Test. Hosted Test and review still require the normal Twitch extension packaging and submission steps:
-
-- upload the built panel artifact
-- confirm final allowlists
-- confirm reviewer-facing assets and text
-- validate the Hosted Test install flow on real test channels
-
-## Recommended MVP Rollout Checklist
-
-Before broader tester rollout, validate these flows with real Twitch accounts:
-
-- viewer, unlinked:
-  - panel loads
-  - playlist is readable
-  - write actions require identity share
-- viewer, linked:
-  - search works
-  - regular request works
-  - VIP request works when balance is available
-  - edit and remove work
-- channel owner:
-  - playlist actions appear
-  - play now, mark played, delete, and request-kind changes work
-- channel moderator:
-  - playlist actions appear only when the channel settings allow them
-  - actions use the correct capability gates
-
-## Recommended Next Additions
-
-These items fit well after the first tester rollout, but they are not required for the MVP request loop:
-
-- optional link from the panel to the full playlist page on `rocklist.live`
-- read-only blacklist and setlist visibility in the panel
-- VIP token management tools in the panel
-- blacklist and setlist management tools in the panel
-- better cross-surface navigation between Twitch and the website
-
-## Website Auth Note
-
-The panel identity-share flow does not create a website session.
-
-If the panel opens `rocklist.live` in a new window:
-
-- the user is signed in on the website only when the browser already has the RockList.Live session cookie
-- otherwise the website still requires the normal Twitch OAuth flow
-
-## Main Files
-
-- `src/lib/server/extension-auth.ts`
-- `src/lib/server/extension-panel.ts`
-- `src/lib/server/viewer-request.ts`
-- `src/lib/server/playlist-management.ts`
-- `src/routes/api/extension/bootstrap.ts`
-- `src/routes/api/extension/search.ts`
-- `src/routes/api/extension/request.ts`
-- `src/routes/api/extension/request/edit.ts`
-- `src/routes/api/extension/request/remove.ts`
-- `src/routes/api/extension/playlist.ts`
-- `src/extension/panel/app.tsx`
-- `docs/twitch-panel-extension-local-test.md`
+# Twitch Panel Extension Architecture
+
+## Auth and channel resolution
+
+- The panel verifies the Twitch Extension JWT on the server.
+- `channel_id` resolves the RockList.Live channel.
+- Linked `user_id` resolves the matching RockList.Live user profile.
+- Access resolves as `owner`, `moderator`, or `viewer` for the active channel.
+
+## API surface
+
+- `GET /api/extension/bootstrap`
+- `GET /api/extension/search`
+- `POST /api/extension/request`
+- `POST /api/extension/request/edit`
+- `POST /api/extension/request/remove`
+- `POST /api/extension/playlist`
+
+## Shared behavior
+
+- `src/lib/server/extension-panel.ts` shapes bootstrap, live state, search, viewer request calls, and playlist management calls.
+- `src/lib/server/viewer-request.ts` enforces blocked-requester rules, request ownership, VIP token rules, and shared request policy checks.
+- `src/lib/request-policy.ts` applies blacklist, setlist, queue, and request-limit checks.
+- `src/lib/server/playlist-management.ts` enforces owner and moderator playlist permissions.
+
+## Search and request rules
+
+- The panel search applies channel request filters such as official-only, allowed tunings, and required parts.
+- The panel hides blacklisted search results when the channel blacklist is enabled.
+- The panel keeps playlist viewing available without identity sharing.
+- The panel requires linked identity for viewer request writes.
+- The panel keeps blocked viewers in a read-only request state.

docs/twitch-panel-extension-local-test.md

@@ -17,12 +17,12 @@ Add these values before testing the Twitch panel flow:
 - `TWITCH_EXTENSION_SECRET`
 - `VITE_TWITCH_EXTENSION_API_BASE_URL`
 
-Notes:
-
-- `TWITCH_EXTENSION_CLIENT_ID` is the Twitch Extension client ID from the Twitch developer console.
-- `TWITCH_EXTENSION_SECRET` must be the base64 shared secret from the Twitch Extensions developer console.
-- `VITE_TWITCH_EXTENSION_API_BASE_URL` should point at the app origin that serves the `/api/extension/*` endpoints.
-- For local development, `VITE_TWITCH_EXTENSION_API_BASE_URL` can be a tunnel URL if Twitch cannot reach `localhost`.
+Notes:
+
+- `TWITCH_EXTENSION_CLIENT_ID` is the Twitch Extension client ID from the Twitch developer console.
+- `TWITCH_EXTENSION_SECRET` must be the base64 shared secret from the Twitch Extensions developer console.
+- `VITE_TWITCH_EXTENSION_API_BASE_URL` points at the app origin that serves the `/api/extension/*` endpoints.
+- For local development, `VITE_TWITCH_EXTENSION_API_BASE_URL` can be a tunnel URL if Twitch cannot reach `localhost`.
 
 ## Useful commands
 
@@ -38,7 +38,7 @@ Build the standalone panel artifact:
 npm run build:extension:panel
 ```
 
-For any build that should call a deployed app origin, set the API base URL in the same shell before you build:
+For any build that calls a deployed app origin, set the API base URL in the same shell before you build:
 
 ```bash
 VITE_TWITCH_EXTENSION_API_BASE_URL=https://your-app-host npm run build:extension:panel
@@ -64,13 +64,15 @@ With Twitch Local Test:
 1. Run the app locally or expose it through a tunnel.
 2. Make sure `APP_URL` and `VITE_TWITCH_EXTENSION_API_BASE_URL` match the origin that Twitch can reach.
 3. Point the extension panel view to the app route or the built standalone artifact URL.
-4. Open Twitch Local Test and confirm:
-   - bootstrap succeeds
-   - unlinked viewers can read the queue
-   - linked viewers can search and submit requests
-   - VIP token balance is shown
-   - edit/remove works for the linked viewer
-   - channel owners can use playlist actions from the panel
+4. Open Twitch Local Test and confirm:
+   - bootstrap succeeds
+   - unlinked viewers can read the queue
+   - linked viewers can search and submit requests
+   - blocked viewers can read the queue and search, but request actions stay unavailable
+   - blacklisted search results stay hidden when the channel blacklist is enabled
+   - VIP token balance is shown
+   - edit/remove works for the linked viewer
+   - channel owners can use playlist actions from the panel
    - channel moderators can use playlist actions when the channel settings allow them
 
 ## Website auth note