# Web UI

The daemon serves the debug web control UI. The owner uses it to observe the account the agent
sees, read and send messages, search users, and see voice membership. The shell follows the design
handoff in `poc/WebUIMockup.zip`; several panels are roadmap placeholders.

## Run

The UI starts with the daemon. No extra command is needed.

```sh
cd poc
pnpm control:bridge

# Page
http://<host>:8789/

# API
http://<host>:8789/api/health
```

| Setting | Default | Purpose |
| --- | --- | --- |
| `WEBUI_HOST` | `0.0.0.0` | Listen address |
| `WEBUI_PORT` | `8789` | Listen port |

## Security

The UI has **no authentication**. Anyone who can reach the port controls the bot, can start and
stop the client, and can start a QR login. Bind the daemon to a private LAN or a Tailscale address
only. Do not expose the port to the public internet. See [daemon.md](daemon.md).

The MCP server stays on `127.0.0.1:8788`. Only the UI binds outside localhost.

## TLS

The UI serves HTTPS with a self-signed certificate so browser media APIs have a secure context.
The daemon generates the certificate with `openssl` on first run (localhost plus the host's LAN
addresses) and stores it under `<state dir>/tls/`. The browser shows a warning once; accept it.

| Setting | Default | Purpose |
| --- | --- | --- |
| `WEBUI_TLS` | `1` | Set to `0` to serve plain HTTP. |
| `WEBUI_TLS_KEY` / `WEBUI_TLS_CERT` | unset | Use an existing certificate instead. |

With plain HTTP, `navigator.mediaDevices` only exists on localhost; remote browsers must use HTTPS.

## Page

- Plain HTML, CSS, and JavaScript in `poc/public/`. No build step and no frontend framework.
- The look follows the Nocturne design system (`poc/public/nocturne.css`) from the design handoff
  in `poc/WebUIMockup.zip`. Implemented screen: **7a**, the docked three-column debug shell.
- Layout: 50px header, conditional call strip, `236px | 1fr | 306px` body, and the agent console
  bar (35px collapsed, resizable drawer expanded).
- Header: wordmark, **Guild / DM** scope tabs, guild picker, health indicators, **Client audio**,
  Takeover switch, Settings. While the bridge is down a **Start server** button appears with a
  pulsing bloom; if the whole daemon is unreachable it becomes **Refresh** and reloads the page.
  The body dims and stops taking input while the bridge is down.
- Left rail (Guild tab): guild switcher, text channels, voice channels with inline participants,
  and **People** — users recently seen in a voice channel (click opens their cached DM). Clicking a
  voice channel joins it (muted); clicking the active channel leaves.
- Left rail (DM tab): every cached DM and group with unread badge, avatar, name, last-message time,
  and a favourite star.
- Right column: **In voice** (favourited users in a call, grouped by call), **Favourites**, and
  **Open DMs & groups** as quick access. The guild's own occupied channels live in the left rail.
- Speaking users show animated level bars and a bold name (design 2c: audio → video → share marks).
  The bars scale up when speaking starts and stay on until an explicit stop, a mute, or a channel
  change. A missing stop event leaves them on by design; they do not decay on their own. The
  fade-out runs the equalizer inside a shrinking container, so the amplitude drops to nothing
  instead of the block collapsing at full height. Muted members never show bars.
  Nicknames come from the guild member store; DMs fall back to the username.
- Console: Tool calls, Events (live SSE), Transcript. The ticker shows the newest event. The
  Transcript tab lists captured segments (time, speaker, text, WAV) and updates live. It has
  **Start**, **Stop**, and **Refresh** buttons; the status line shows `capturing` or `capture off`
  plus the segment count.
- Opening a chat fetches the latest 50 messages from Discord into the client cache. The refresh
  button by the channel header re-fetches. Live message events read the cache. Edited messages show
  an `edited` marker and replies show `↳ replying to <name>`.
- Attachments render from their Discord CDN links. Images display inline; other files are link
  chips. The daemon never downloads or stores attachment bytes.
- Avatars and guild icons load from the Discord CDN with a monogram fallback.
- Composer and TTS drafts persist in `localStorage` per channel. They survive re-renders, the
  bridge connecting, and a page reload. A successful send clears the channel draft.
- When the bridge connects after the page loaded, the page reloads state without touching drafts.
  The reload retries while the client boots, and the health poll keeps retrying if the first
  attempt failed.
- Roadmap gaps are shown, not hidden: TTS, transcript, tool-call tracing, favourites, and voice
  join/monitor appear as marked placeholders.

## Mobile

At 768px and below the shell becomes the 1c phone layout. One pane shows at a time behind a
four-tab bar (Users, Chat, Call, Activity), with 44px hit targets and the call bar pinned above
the content.

- **Users** is the left rail: guild switcher, channels, voice, and people.
- **Chat** is the centre column: messages, composer, TTS panel.
- **Call** is the live call: the whole right column, with the current call's members listed first
  (not only favourites).
- **Activity** is the full agent console (Tool calls, Events, Transcript).
- The Chat tab carries the total DM unread count. The header compresses to one line: scope tabs,
  guild picker, health dot and event rate, icon-only Client audio and Settings, and the Takeover
  switch.
- The selected tab persists in `localStorage`. Picking a channel from Users switches to Chat;
  picking a voice channel switches to Call.

The first draft renders headless at 390x844. Remaining gaps against 1c: the transcript and the TTS
box live in Chat, not Call, and the connection stats are not chips yet.

## DMs and favourites

- The **DM** scope tab shows all cached DMs in the rail and the conversation in the centre.
- Unread badges sit left of the avatar: purple for unread, orange for mentions while Takeover is
  on; while Takeover is off they are grey, meaning the bot saw them and you did not.
- The hollow star on a row adds it to favourites, stored in the daemon preferences. Starring a 1:1
  DM favourites that user; starring a group DM favourites the channel.
- Favourited users get presence tracking. If they are in a call, they appear under **In voice**,
  grouped per call. The right column's **Favourites** shows their status when they are not.
- The last-message time comes from the channel's last message snowflake: a time today, `yesterday`,
  or a short date.

## Media and Bot

- **Media** and **Bot** are scope buttons beside Guild and DM. They open a full-window view below
  the header and the call strip (the shell is covered; only the header, and the call strip when it
  is visible, stay on screen). Settings slides over the media view, and dialogs that Settings
  opens (for example **Clean media…**) render above Settings. Mobile is out of scope for the media
  feature.
- Media lists scraped items. The bar shows the common filters: filetype chips, source kind
  (attachments/stickers/embeds), origin (server channels or DMs), and a multi-select **People**
  popover. The **Advanced search** drawer holds aspect ratio, resolution, source channel,
  posted-date range, file-type chips (video mp4/webm/mov/mkv, image png/jpg/gif/webp/avif, audio),
  **Show only cached previews**, a default-on **Hide 4chan links (usually dead)**, and a
  **Do not include** and **Must include** groups, each with nested collapsibles. **Do not include**
  hides sources (the common providers in the archive — Discord, YouTube, Giphy/Tenor, Twitch,
  Twitter, Reddit, Streamable, Instagram, Facebook, Steam, Gyazo, TikTok, Medal, Sketchfab, Gfycat,
  2ch.hk, Imgur, FunnyJunk, Internet Archive — plus embeds, attachments, stickers) and file types.
  **Must include** requires them (same provider list and kinds, file-type chips, and size/length
  bounds with B/KB/MB/GB units or seconds). A provider entry may carry several substrings, shown as
  `Giphy/Tenor`. A title field searches embed titles (YouTube): default is multi-word prefix
  matching (each token must start a word of the title, order-free), and **Exact match (quotes)**
  treats the input as one phrase. A sort select orders the grid by newest, oldest, user, size, or
  length. Size and
  length bounds drop rows with no known value. The filter bar and the drawer are hidden on the Bot
  tab. Filters do not
  apply until **Apply filters** is pressed; **Reset** clears every filter and the zoom, unloads the
  grid, and brings back the initial Load media prompt.
- A **Card size** slider scales tiles from two-thirds of the old size up to one image per row; the
  page size follows the layout — full rows about 1.5 screens tall — and the grid streams: each page
  appends only its new cards (no image flash) and a buffer below the last row, capped at 1.5
  viewport heights, keeps the scroll alive while the next page loads. Auto-fill runs while the
  buffer is on screen, so short filtered pages never dead-stop; the note reads `Loading more…`,
  `Scroll for more`, or `End of results`, and an elastic nudge replaces the hard stop at the bottom
  while loading. The next page's JSON and previews are preloaded just before they are needed.
  **New scrape…** opens a popup with **Server** and **Group chat**
  tabs: servers expand into their text channels, each channel (and each group chat) has
  **Links** and **Download** buttons, and group chats always use the puppet. **History** lists
  each scrape with start time, duration, pages, messages, media counts, bytes, files, and previews,
  and offers **Resume** for paused ones and **Delete** for anything not running.
  The scrape strip shows live progress with a pulse and **Stop**: every running/queued scrape plus at
  most one paused scrape, whose **Stop** only dismisses it from the strip (it stays resumable and the
  next paused scrape can appear). The line turns red with `API limited, retry in Ns` while Discord
  throttles, and a translucent `N scrapes completed` note appears as scrapes finish and clears when
  the tab is reloaded. Images and GIFs render from the cached preview when one exists, then the local
  file, then the CDN URL; videos and audio are link cards with the poster and posted time in the
  tooltip.
- Bot shows the slopbot connection state, the backfill queue, and the media tunables. Backfill has
  totals and an ETA with a Bot/Puppet split, then one job card per chat with its member scrapes,
  per-kind pending, a progress bar, an ETA, and Start/Pause; the header has **Start backfill** and
  **Pause all**. A red banner reads `API timed out, increase timers` during a Discord cooldown. The
  three settings groups (Backfilling, Scraping, Timers) save to `preferences.json` and retune live
  jobs. The error list sits below with the Clear button.
- The views are self-contained: `poc/public/media.js` and `media.css`, over the `/api/media/*`
  routes in the table below. See [media.md](media.md).

## Takeover

Takeover is a read-only switch. Off, the composer is locked (a `read-only` tag sits next to the
lock) and the page cannot send. On, the composer unlocks and every manual send is written to the
action log as a `manual` entry. The choice is stored in `localStorage`. The setting is client-side
only; the API itself does not enforce it.

## Settings

The Settings button opens a slide-over:

- **Visible guilds** — top level. Checkboxes filter the guild switcher and picker live. **Save**
  writes the selection to the daemon preferences (`/api/preferences`); **Hide all** and **Show all**
  select none or every guild. All visible is stored as `null`, none as `[]`. All browsers share
  the saved state, and Save works while the client is disconnected.
- **Client** — a collapsible group with:
  - **Bot audio** — engine status, TTS provider state, a **Connect devices** button, and the
    capture toggle. These are the daemon host's devices.
  - **Speech** — the TTS engine (Auto plus every configured engine: espeak-ng, the command engine
    by its `VESKSLOP_TTS_NAME`, and the HTTP API), language, and voice. **Start engine** warms the
    selected engine (starts Xvfb, Wine, and the host for the command engine). Selecting an engine
    switches the voice list to that engine; the language row hides for single-language engines.
    Voices are grouped by base language and filtered by the chosen language; English, Swedish,
    German, Danish, Norwegian, Russian, and Cherokee are pinned on top. Stored in the daemon
    preferences. Speed (0.5x–2.0x with 0.5/0.75/1/1.25/1.5 presets), pitch (-12 to +12
    semitones), and an Expression slider (0–100, Flextalk voices only) live in the TTS panel and
    save to the same preferences; controls the selected voice does not support stay hidden. For
    Flextalk voices the TTS panel also opens the **Flextalk voice profile** window: a movable panel
    that recenters on each open, with character sliders, five named presets, radio-kit effects
    (high-pass, echo, word mode), and test lines (Attention, Laboratory, Critical, Health,
    Radiation, plus two custom) that speak immediately.
  - **Display** — the timestamp timezone. Defaults to the browser's zone
    (`Intl.DateTimeFormat().resolvedOptions().timeZone`); pick any IANA zone to override. Stored in
    `localStorage` and applied to messages, the transcript, the event log, the action log, and the
    core status.
  - **Browser audio** — puppeting controls: the browser output device for Client audio, a
    placeholder mic select, and the call-audio state. **Enable browser audio** asks for the
    microphone permission, which browsers require before they list output devices. Separate from
    the bot's devices. Clicking **Client audio** in the header does the same: it asks for the
    permission, unlocks the audio context in the same click, and then starts listening. A second
    click stops it.
- **Bot** — slopbot connection state, the media storage limit in GiB with an info tooltip (5% overrun
  and the warning rule), the usage bar segmented by image, GIF, video, audio, and other, and
  **Clean media…** with a 5 second confirmation countdown. See [media.md](media.md).
- **Server** — a collapsible group with:
  - **Core process** — state, last exit, output, Start / Stop / Restart.
  - **Account login** — token file state, QR login, captcha.
  - **Action log** — the persistent JSONL log, newest first.

## Core process

The Settings panel starts, stops, and restarts the Vesktop client. The daemon spawns the process
from the repo root and labels its output with `[core]` in the daemon log.

- The default command is `node_modules/.bin/electron .` with
  `--no-sandbox --disable-gpu --disable-dev-shm-usage`.
- Override the command with `VESKSLOP_CORE_CMD` and the flags with `VESKSLOP_CORE_ARGS`.
- The spawn sets `VESKSLOP_HEADLESS=1` and points `VESKSLOP_TOKEN_FILE` at the daemon token file.
- On Linux without a `DISPLAY`, the daemon starts Xvfb automatically. `VESKSLOP_XVFB=0` disables
  this. A real `DISPLAY` wins.
- Only a process started by the current daemon is managed. An externally started client shows as
  `external` and cannot be stopped from the UI.
- The status shows the last exit code or signal and the last 20 output lines. A failed start is
  visible on the page instead of only in the daemon log.

## Login

The Settings panel runs the same QR flow as `pnpm poc:qr`, with the QR rendered as an image.

1. Click **Start QR login**. The daemon opens the remote-auth gateway and shows the QR.
2. Scan the QR with the Discord mobile app and approve.
3. On success the token is written to the token file with mode 600. A running managed core
   restarts with `VESKSLOP_FORCE_TOKEN=1` so the new account takes effect.
4. If Discord asks for a captcha, the panel shows the sitekey and a field for the hCaptcha response
   token. Paste the token and submit.

The token never leaves the daemon. The API reports the account name and ID, not the token.

## API

The JSON API is the migration boundary. A future frontend calls the same routes. The page code is
replaceable.

| Method | Path | Body or query | Result |
| --- | --- | --- | --- |
| GET | `/api/health` | none | Core state, process state, owner, uptime, event count, query count |
| GET | `/api/core/status` | none | Bridge and core process state |
| POST | `/api/core/start` | `forceToken?` | Start the client |
| POST | `/api/core/stop` | none | Stop the managed client |
| POST | `/api/core/restart` | `forceToken?` | Restart the managed client |
| GET | `/api/auth` | none | Token file state and the QR session, with `qrDataUrl` when pending |
| POST | `/api/auth/qr` | none | Start a QR login session |
| POST | `/api/auth/qr/cancel` | none | Cancel the session |
| POST | `/api/auth/qr/captcha` | `key` | Submit an hCaptcha response token |
| GET | `/api/state` | none | User, guilds, and channels |
| GET | `/api/messages` | `channelId`, `limit`, `refresh?` | Messages from a channel. `refresh=1` fetches the latest from Discord and fills the client cache; otherwise cache-only. |
| POST | `/api/messages` | `channelId`, `content` | Send a message. Records a `manual` action. |
| POST | `/api/dm` | `userId` or `username`, `content` | Send a DM. Records a `manual` action. |
| GET | `/api/users` | `q`, `guildId?`, `limit?` | Search the client user cache |
| GET | `/api/dms` | `limit?` | Cached DM and group DM channels with recipients |
| GET | `/api/voice` | `userId?`, `guildId?` | One user's voice state |
| GET | `/api/voice/overview` | `guildId` | Occupied voice channels and members |
| GET | `/api/voice/volume` | `userIds?` comma-separated | Per-user volumes plus output volume; defaults to the current call |
| POST | `/api/voice/volume` | `userId`, `volume` | Set a user's playback volume (0 to 200) |
| POST | `/api/voice/join` | `channelId`, `mute?` | Join a voice channel (muted by default) |
| POST | `/api/voice/leave` | none | Leave the current voice channel |
| POST | `/api/voice/move` | `channelId` | Move to another voice channel |
| GET | `/api/preferences` | none | Web UI preferences (`visibleGuilds`, `tts`) |
| POST | `/api/preferences` | `visibleGuilds?`, `tts?` | Update preferences. Stored in `<state dir>/preferences.json`. |
| GET | `/api/audio` | none | Audio engine, TTS, queue, ducking, capture state |
| GET | `/api/audio/devices` | none | The client's input and output devices |
| GET | `/api/audio/tts/voices` | `engine?` | Voices for the selected engine (espeak-ng or `VESKSLOP_TTS_VOICES`) |
| POST | `/api/audio/connect` | none | Re-apply the virtual devices to the client |
| WS | `/audio` | `{"type":"listen","on":bool}` | Raw 48 kHz mono PCM of the call |
| POST | `/api/audio/devices` | `inputDeviceId?`, `outputDeviceId?` | Set the client's devices |
| POST | `/api/audio/speak` | `text`, `provider?`, `voice?`, `speed?`, `pitch?` | Queue text to speech |
| POST | `/api/audio/stop` | none | Stop speech and clear the queue |
| POST | `/api/audio/capture` | `start` | Start or stop capture |
| GET | `/api/transcript` | `limit?`, `sessionId?` | Sessions and captured segments |
| GET | `/api/media` | `kind?`, `source?`, `channelId?`, `authorId?` (comma list), `origin?` (`guild`/`dm`), `cachedOnly?`, `ext?` (comma list), `excludeHosts?` (comma list), `excludeExt?`, `excludeProviders?`, `excludeSources?`, `includeProviders?`, `includeSources?` (comma lists), `title?` (200 chars max), `titleExact?`, `sizeLt?`/`sizeGt?` (bytes), `lenLt?`/`lenGt?` (seconds), `sort?` (`newest` default, `oldest`, `user`, `size`, `length`), `aspect?`, `resolution?`, `after?`, `before?`, `limit?`, `offset?` | Media items across every scrape, newest first. `source` is `attachment`, `sticker`, or `embed`; `aspect` and `resolution` are the preset keys; `after`/`before` are ISO times on `posted_at`. Items carry `authorName`, `postedAt`, `width`, `height`, `aspectRatio`, `contentType`, `durationSecs`, `previewError`, `animUrl`; `localUrl`/`thumbUrl` when a file or preview exists |
| GET | `/api/media/:scrapeId/:itemId/file` | none | The downloaded file, content-typed from its extension |
| GET | `/api/media/:scrapeId/:itemId/thumb` | none | The cached preview (type from `preview_ext`) |
| GET | `/api/media/:scrapeId/:itemId/stream` | none | Playback/full-view source: the local file, or the remote URL refreshed from the source message. Supports `Range`. Non-media upstream responses (provider pages) return `415` |
| GET | `/api/media/scrapes` | none | Every scrape with state and counters |
| GET | `/api/media/status` | none | Slopbot connection state, the scrape list, `limitedUntil` while a Discord cooldown holds media traffic, and `providerFilters` (the curated provider list for the Advanced drawer) |
| GET | `/api/media/backfill` | none | Backfill jobs per chat with pending/cached/failed, per-kind pending, progress, throughput, `etaStartMs`/`etaRunMs`/`etaTotalMs`, totals with a Bot/Puppet split, the live settings, and `limitedUntil` |
| POST | `/api/media/backfill/start` | `chatId?` | Start every job with pending rows, or one chat's job |
| POST | `/api/media/backfill/pause` | `chatId?` | Pause all jobs, or one chat's job, after the current batch |
| GET | `/api/media/authors` | none | Distinct posters across every scrape, with counts |
| GET | `/api/media/stats` | same filters as `/api/media` | Counts per kind (`image`, `gif`, `video`, `audio`), each with `total`, `downloaded`, `cached`, `notDownloaded` |
| GET | `/api/media/storage` | none | Usage against the limit, per-kind sizes, `nearLimit`; marks old scrapes when over |
| POST | `/api/media/scrape` | `channelId`, `guildId?`, `mode?`, `backend?`, `confirm?`, `downloadDir?`, `after?`, `before?` | Start a media scrape. `backend` is `auto` (default), `slopbot`, or `puppet`; `downloadDir` is an absolute path for downloaded files (previews stay local); `after`/`before` are ISO dates bounding the walk. Near the limit: `409` with code `MEDIA_LIMIT` unless `confirm: true` |
| POST | `/api/media/count` | `channelId`, `guildId?`, `after?`, `before?` | Discord search total for the channel or range. Returns `{ count }` or `{ count: null, reason }` (slopbot guild channels only) |
| GET | `/api/media/errors` | none | Bot and scrape errors, newest first |
| POST | `/api/media/errors/clear` | none | Clear the error list |
| GET | `/api/media/preview-failures` | `limit?` | Rows whose preview failed, with the reason |
| GET | `/api/media/:scrapeId/:itemId/anim` | none | The cached animated GIF for hover playback |
| POST | `/api/daemon/restart` | none | Replace the daemon process with a fresh copy (the client keeps running) |
| POST | `/api/media/scrape/stop` | `id` | Stop a media scrape |
| POST | `/api/preferences` | `visibleGuilds?`, `tts?`, `audio?`, `favourites?`, `media?` | Also accepts `media.tunables` with `backfill`, `scrape`, and `timers` groups; changes apply to live jobs immediately |
| POST | `/api/media/scrape/resume` | `id` | Continue a paused scrape from its cursor |
| POST | `/api/media/clean` | `ids?` | Delete the given scrapes, or every scrape when `ids` is absent |
| GET | `/api/logs` | `limit` | The persistent action log |
| GET | `/api/events` | none | Server-sent events |

Every response is JSON: `{ "ok": true, "result": ... }` or `{ "ok": false, "error": "..." }`. A
core validation error adds `code`.

The channel detail routes use the same pacing as the MCP tools. Sends are paced; reads take a small
gap. See [daemon.md](daemon.md).

## Not started

- Web UI authentication and user accounts.
- Voice auto-leave and the `stay @user` command.
- TTS playback, transcript capture, and MCP tool-call tracing.
- Favourites, presence, member counts, and message editing/deletion/reactions.
- Pagination of channel history.
- The full DM scope from the mockup: the rail always shows text, voice, and direct lists.