catacomb/docs/superpowers/specs/2026-07-12-peertube-browse-archive-design.md

# PeerTube Browse + Archive — Design (Federation Phase 3)

> Third and final phase of the federation/PeerTube project. Phase 1 shipped the
> backend `PeerTubeClient` (`docs/superpowers/specs/2026-07-10-peertube-client-backend-design.md`);
> phase 2 shipped the kind-aware remote editor
> (`docs/superpowers/specs/2026-07-10-federation-editor-phase2-kind-aware-design.md`).
> This phase adds the browse UI + per-video archive action to both front-ends.

## Goal

Let a user browse a configured PeerTube peer's channels and videos from inside
Catacomb (both the web SPA and the desktop GUI), play a video inline when the
instance exposes a direct MP4, and archive any video into the local library with
one click. Read-only browsing, one-video-at-a-time archiving.

## Locked decisions (from brainstorming)

1. **Lazy two-level navigation** — list channels, then click a channel to load
   its videos a page at a time. Not a one-shot whole-library load.
2. **Per-video archive only** — each video row has an Archive button. No
   bulk/whole-channel archive in this phase.
3. **Archive destination = existing `Other` platform** — PeerTube is federated
   with no fixed domain, so `Platform::from_url` classifies a `watch_url` as
   `Other`, landing archived videos in `other/<uploader>/`. No new `Platform`
   variant, no download-path override.
4. **Both front-ends in one spec** — web + desktop at parity, shared backend
   endpoints.
5. **On-demand media resolution** — resolve a video's playable MP4 only when
   Play is clicked, not eagerly for every listed video (eager would fire one
   extra HTTP call per video per page).

## Background: what already exists

`PeerTubeClient` (phase 1, `src/peertube.rs`) is a blocking client with:

- `list_channels() -> Result<Vec<RemoteChannelInfo>, String>` —
  `RemoteChannelInfo { handle, display_name, video_count: Option<u64>, avatar_url: Option<String> }`.
- `channel_videos(handle, page) -> Result<Vec<RemoteVideo>, String>` — page size
  24, newest first. Returns `crate::remote::RemoteVideo { id (uuid), title,
  channel, video_url: None, thumb_url, duration_secs }`. `video_url` is
  deliberately `None` here — the playable URL is resolved separately.
- `video_media(uuid) -> Result<Option<String>, String>` — the direct MP4 URL, or
  `None` when the video is HLS-only.
- `watch_url(uuid) -> String` — `{api_base}/w/{uuid}`, the canonical page URL
  handed to yt-dlp.

`RemoteClientKind` (phase 2, `src/remote.rs`) wraps `Catacomb(RemoteClient)` /
`Peertube(PeerTubeClient)`. Both front-ends hold `Vec<Arc<RemoteClientKind>>`
(web behind a `RwLock`). Browsing dispatches on kind; the phase-2 stopgap for a
Peertube remote is a "browsing arrives in a later update" message, replaced here.

The existing **catacomb** browse path is untouched: `GET /api/remotes/:id/library`
returns the whole peer library and the SPA swaps its `library` array to reuse the
normal grid (`enterRemote`/`exitRemote` in `index.html`); desktop uses
`start_remote_fetch` → `remote_library`.

## Architecture

Browsing remains **kind-dispatched**. Catacomb peers keep the one-shot `/library`
path. Peertube peers use new lazy endpoints and a new two-level browse view in
each UI. The new endpoints are Peertube-only: called against a catacomb remote
they return `400 Bad Request` ("not a PeerTube remote").

`RemoteClientKind` gains thin passthroughs used by the new web handlers and the
desktop threads:

```rust
impl RemoteClientKind {
    // Returns Err for the Catacomb arm ("not a PeerTube remote").
    pub fn pt_channels(&self) -> Result<Vec<crate::peertube::RemoteChannelInfo>, String>;
    pub fn pt_channel_videos(&self, handle: &str, page: usize) -> Result<Vec<RemoteVideo>, String>;
    pub fn pt_video_media(&self, uuid: &str) -> Result<Option<String>, String>;
    pub fn pt_watch_url(&self, uuid: &str) -> Result<String, String>;
}
```

(Alternatively the handlers `match` on the arm directly; the passthroughs keep the
`unreachable!()` noise out of both front-ends and give one kind-guard site.)

## Backend endpoints (`src/web.rs`)

All run the blocking PeerTube calls on `tokio::task::spawn_blocking` (as the
existing `get_remote_library` does) and 400 on a catacomb remote.

| Method / path | Returns |
|---|---|
| `GET /api/remotes/:id/channels` | `[{handle, display_name, video_count, avatar_url}]` |
| `GET /api/remotes/:id/channels/:handle/videos?page=N` | `[{id, title, channel, thumb_url, duration_secs}]` (page 24; `N` defaults 0) |
| `GET /api/remotes/:id/videos/:uuid/media` | `{url}` (200) or `204 No Content` when HLS-only |
| `POST /api/remotes/:id/archive` `{uuid}` | `202 "ok"` after `downloader.start(watch_url, …)`; 404 unknown remote, 400 catacomb remote |

`:handle` may contain `@host` for a federated channel, so it is a path segment
that is percent-decoded by axum; the handler passes it verbatim to
`channel_videos`. The archive handler resolves `watch_url(uuid)`, builds the
`UrlInfo` with the existing synchronous `classify_url(&url)` (no network probe;
`info.platform == Other` for a PeerTube URL), and calls the shared
`Downloader::start`. It mirrors `post_download`'s shape: `start` returns `()`,
so the response is `202 "ok"` and the job then appears in the normal downloads
panel via the existing progress stream (no job id is returned).

## Web UI (`src/web_ui/index.html`)

A new **PeerTube browse mode**, distinct from the existing flat-library
`remoteMode` (the PeerTube view is a two-level nav, not the reused grid):

- **Enter:** clicking a remote whose `kind === 'peertube'` in the sidebar enters
  PeerTube mode and calls `GET …/channels`. (A catacomb remote still calls
  `enterRemote`.) State: `ptRemoteId`, `ptChannel`, `ptPage`, `ptVideos`.
- **Channel list:** rows with avatar, display name, and video count. Click →
  load that channel's videos.
- **Video grid:** cards (thumbnail, title, duration) with **▶ Play** and
  **⬇ Archive**, plus a **[Load more]** button that fetches the next page and
  appends (hidden when a page returns < 24). 
- **Play:** `GET …/videos/:uuid/media`; on 200 open the existing custom player
  (`playVideo`) with the returned URL; on 204 the Play button is disabled with an
  "HLS-only — archive to watch" note.
- **Archive:** `POST …/archive {uuid}`; toast on success; the job shows up in the
  normal downloads panel via the existing progress stream.
- **Back navigation:** video grid → channel list → "Back to my library"
  (`exitRemote`-style reset). PeerTube mode reuses the sidebar remotes list for
  peer switching.

Sidebar: the existing `🌐 Remotes` block already lists every peer with
`enterRemote(id)`. Dispatch there on `r.kind` — peertube → `enterPeertube(id)`.

## Desktop UI (`src/app.rs`)

`remotes_screen` dispatches on `RemoteClientKind::kind()`. The Peertube arm
replaces the phase-2 stopgap with the same two-level nav in egui:

- New `App` state: `pt_channels: Option<Vec<RemoteChannelInfo>>`,
  `pt_selected_channel: Option<String>`, `pt_videos: Vec<RemoteVideo>`,
  `pt_page: usize`, and mpsc receivers for the background channel/video fetches
  (`pt_channels_rx`, `pt_videos_rx`) drained in `update()` — mirroring the
  existing `remote_rx` pattern (fetch on a thread, `request_repaint`).
- Channel list (selectable rows) → click loads page 0 of that channel's videos;
  a **Load more** button appends the next page.
- Per video row: **Play** — resolve `video_media` on a thread, then hand the URL
  to the existing `play_remote_url` (mpv); greyed when the resolve returns `None`.
  **Archive** — `self.downloader.start(watch_url, …)` (probe → `Other`).
- Status/errors surface on the existing `remote_status` line.

## Archive action (shared)

Both UIs route through the same `Downloader::start` a manual download uses, so
auto-retry, post-download transcode, and the hang watchdog all apply unchanged.
The archived video lands in `other/<uploader>/` and appears in the local library
after the next scan (the download pipeline already triggers this). No new
download settings, no per-remote archive options.

## HLS-only & error handling

- `video_media == None` (HLS-only): **Play disabled**, Archive still works
  (yt-dlp downloads HLS fine). The disabled Play carries an explanatory tooltip.
- Network / auth / not-found failures from the PeerTube client surface as an
  inline error line in the browse view (web: a status/toast; desktop:
  `remote_status`) — never a panic or a stuck "loading…".
- An empty channel (zero videos) shows an empty-state row, not a blank grid.
- Calling a new endpoint on a catacomb remote → `400` with a clear message; the
  UIs never do this (they dispatch on kind) but the guard documents intent and
  protects the API.

## Testing

- **Unit (web.rs):** the kind-guard — a new endpoint handler (or the
  `RemoteClientKind` passthrough) returns `Err`/400 for a `Catacomb` arm. An
  archive-path unit asserting a given `uuid` maps to the expected `watch_url`
  before hand-off.
- **Integration (`tests/api.rs`):** `PUT` a peertube remote, then `GET
  …/channels` against an unreachable host — asserts the route exists and returns
  a client/gateway error (not 404-route-missing), and that `GET …/channels` on a
  *catacomb* remote returns 400. No network required (unreachable host → fast
  connection error); skip-if-curl-absent like the file's other tests.
- **Mapping:** already fixture-tested in phase 1 (`map_channel`, `map_video`,
  `pick_media`) — no change.
- **Manual:** against `https://framatube.org` (public instance): browse
  channels, open one, Load more, play a direct-MP4 video inline (web) / via mpv
  (desktop), confirm an HLS-only video disables Play, archive one video and
  confirm it lands under `Other` and appears after a rescan.

## Out of scope (possible later)

- Bulk / whole-channel archive.
- A dedicated `Platform::Peertube` library section.
- Search within a peer, subscriptions/feeds, comments, or write actions.
- Caching channel/video lists (each browse is a live fetch).