Obbystreams Frontend
Frontend
The frontend is a React 19 application built with Vite, TypeScript, Tailwind CSS, and Video.js. It is a build-time asset pipeline only; production serves static files from Starlette.
Source Layout
frontend/index.html
frontend/src/App.tsx Dashboard composition and player controls
frontend/src/api.ts Fetch helpers and auth handling
frontend/src/format.ts UI formatting helpers
frontend/src/main.tsx React entrypoint
frontend/src/styles.css Font faces, tokens, component styling, breakpoints
frontend/src/types.ts API payload types
frontend/src/fonts/*.woff2 Vendored Inter + JetBrains Mono variable subsets
Generated files:
static/index.html
static/assets/*
Do not hand-edit generated assets.
Development
Run the backend:
export OBBYSTREAMS_CONFIG=examples/obbystreams.example.yaml
uv run uvicorn app:app --reload --host 127.0.0.1 --port 8767
Run Vite:
npm ci
npm run dev
Open the Vite URL. API and HLS requests proxy to the backend.
Production Build
npm run typecheck
npm run lint
npm run build
The build command runs TypeScript project build and Vite production build.
Fonts
Inter (UI) and JetBrains Mono (URLs, PIDs, segment names, log feeds) are shipped
as vendored latin wght-axis woff2 files in frontend/src/fonts/, referenced by
relative url() from styles.css. Vite then treats them as asset imports,
content-hashes them into static/assets/, and rewrites the paths under
base: "/static/" — correct in both dev and production with no manual handling.
Two rules:
- Never reference a font CDN.
tools/responsive-check.mjsfails the build if any request leaves localhost. Self-hosting is also whytabular-numsworks at all — the previous setup declaredfont-family: Interwithout shipping it, so clients fell back to arbitrary faces with notnumfeature. - Keep the metrics-matched
"… Fallback"@font-facerules. They stopfont-display: swapfrom reflowing the page on first paint.
To refresh the files: npm i -D @fontsource-variable/inter
@fontsource-variable/jetbrains-mono, copy files/*-latin-wght-normal.woff2 into
frontend/src/fonts/, then uninstall the packages. Vendoring keeps every later
build offline and reproducible.
Layout And Breakpoints
Three regions, all 12-column grids: stageRow (player, vitals rail, GPU),
sourcesRow (the four source cards), telemetryRow (full-bleed telemetry).
- Media queries are mobile-first
min-widthonly, on Tailwind’s scale plus3xl(1600) /4xl(1920) /5xl(2560) from the@themeblock. Do not addmax-widthblocks — mixing directions is what previously left a dead band at 1040–1360. The one exception is@media (width < 40rem)for treatments that are genuinely small-screen-only, such as the dropdown bottom sheets, where undoingposition: fixed !importantupward would need a second!important. - Do not redefine
sm/md/lg/xl..statusStripand.rateBadgeuse those variants inline. sourcesRowuses multicol, not grid, because the four cards have very unequal heights and a grid strands whichever one wraps to a new row. This is safe only because none of those panels is sticky and each setsbreak-inside: avoid.- Size metric grids to their panel, not the viewport.
.metricGridusesrepeat(auto-fit, minmax(min(150px, 100%), 1fr)); the vitals rail (~390px) and full-bleed telemetry (~2060px) exist at the same viewport width, so a breakpoint-driven column count breaks labels and values mid-word in the rail. - Spacing comes from
--gutter/--pad-panel/--pad-panel-yand type from the fluid--text-*scale. Prefer those over one-off values, and use the surface/ink/status tokens rather than literal hexes.
UI Principles
- The first screen is the actual control surface, not a marketing landing page.
- The dashboard should stay readable under stream stress: state, action, health, and logs are all visible without hunting.
- Purple is the accent color. Green is reserved for positive state, not general theming.
- Controls must remain stable as state changes.
- Player controls must be usable with mouse, keyboard, and touch.
- Long URLs and process commands must wrap or truncate without breaking layout.
Use
<UrlChip>for URLs. Avoidoverflow-wrap: anywhere: besides shredding addresses across three lines, it shrinks min-content width, which propagates out and can widen the whole document. - Metric labels are small, dim and uppercase; values are large and near-white. Keep that inversion — it is what makes a wall of tiles scannable.
- Panels that are diagnostic rather than always-on should be collapsible, with
state persisted in
localStorage["obbystreams_ui_v1"].
Video.js Player
The live player uses Video.js for HLS playback and custom React controls for dashboard consistency.
Controls cover:
- play and pause
- mute and volume
- reload
- live-edge indication
- fullscreen
- player state and retry messages
The player prefers /hls/ufc.m3u8 when the managed process is running and the playlist is ready.
Authentication
The frontend stores the configured session token under obbystreams_token after login and sends it to guarded APIs. If the backend returns unauthorized, the UI clears local auth state and returns to the login screen.
Accessibility And Responsiveness
Keep interactive controls as real buttons and inputs. Check both desktop and mobile widths before publishing. Use stable grid and panel sizing so logs, metrics, and player state changes do not shift the page unexpectedly.
npm run test:responsive is the gate. It spins its own Vite dev server, mocks the
API, and checks eleven viewports from 320 to 3440 for:
- horizontal overflow and elements escaping the viewport
- tap targets under 34px (a control wrapped in a
<label>is exempt if the label itself clears it — so size the label, not the native checkbox) - dropdown panels escaping the viewport
- full-page height against a per-width budget in
HEIGHT_BUDGET - dead column space — a side-by-side child stopping >900px above the bottom of its own grid row
- any request leaving localhost, which keeps fonts self-hosted
Ratchet HEIGHT_BUDGET down whenever the layout tightens; that ratchet is what
stops the page silently re-inflating. If a change makes the source cards or
telemetry render differently, update mockStatus() too — the fixture has to
actually produce source cards, or the badge row, UrlChip and per-source menu go
unchecked.
Deploying a frontend change never needs a service restart, and must not get one:
restarting obbystreams kills the live ffmpeg encode and drops every viewer.
Because emptyOutDir briefly removes static/, prefer a staged swap during a
live card:
npx vite build --outDir ../.static-next --emptyOutDir
mv static static.prev && mv .static-next static # StaticFiles resolves per request