left4me/docs/superpowers/specs/2026-05-17-server-detail-page-redesign-design.md

Server detail page redesign

Context

server_detail.html today renders six tall sections stacked vertically: server-info (config), actions, server log (SSE), live state (HTMX poll), console (transcript + input), and files (inline tree). The page reads as a chronological dump of every available subsystem rather than a focused control surface. Three of those sections — config, actions, live state — are conceptually one "what is this server right now" cluster but are visually disconnected. Log, console, and files are all inspection/debugging surfaces but compete for vertical real estate and force long scrolls.

The redesign groups state at the top, demotes inspection surfaces into a single tabbed strip at the bottom, and reuses the existing modal infrastructure to host the full versions of each surface on demand.

Goals

• Make "is the server running, who's on it, what map?" visible without scrolling.
• Treat Log, Console, and Files as peer inspection surfaces.
• Keep the page short enough that Delete/Rename remain reachable without scrolling on a typical desktop viewport.
• Minimize new components: reuse _overlay_file_tree.html, _console_line.html, and the existing <dialog> + modals.js pattern. _server_actions.html and _live_state.html get targeted edits (described below) rather than rewrites.

Non-goals: changing the server lifecycle, routes, or partial contracts. This is a template-level refactor with small JS/CSS additions.

New page structure

┌─ Heading: Server <name> ─────────────────────────────┐
│                                                       │
│ ┌─ State cluster (single panel) ────────────────────┐ │
│ │  [● Running]  Start  Stop  Reset                  │ │
│ │  ────────────────────────────────────────────────  │ │
│ │  Players 4/8   Map c1m1_hotel   Hibernating: no   │ │
│ │  (player avatars row from _live_state.html)       │ │
│ │  ────────────────────────────────────────────────  │ │
│ │  Port        Blueprint                            │ │
│ │  27015       survivor-mix                         │ │
│ │  RCON        Hostname                             │ │
│ │  ••• (show)  [my-server____]                      │ │
│ └───────────────────────────────────────────────────┘ │
│                                                       │
│ ┌─ Inspection strip (tabs) ─────────────────────────┐ │
│ │  [ Log ] [ Console ] [ Files ]            [ ⛶ ]   │ │
│ │  ────────────────────────────────────────────────  │ │
│ │  (active tab pane, fixed-height scrollable)       │ │
│ └───────────────────────────────────────────────────┘ │
│                                                       │
│  [Delete server]  Rename                              │
└───────────────────────────────────────────────────────┘

State cluster

One <section class="panel state-cluster"> replaces today's three separate sections. Three sub-blocks separated by horizontal rules:

1. Lifecycle — state badge, start/stop/reset, drift warning, and a one-line "latest job" indicator. The inline job-log SSE stream that currently appears while a job is running (the <pre class="log-stream job-log"> block at the bottom of _server_actions.html) is removed from this subblock entirely — it pops in and out as HTMX re-polls, shifting the rest of the page each time. Users who want the live job log click the latest-job link to open #job-log-modal (see Modals below). Polling is preserved. The HTMX 2s poll on #server-actions while a job is running stays in place — it's what keeps the state badge, start/stop/reset buttons, and the "starting since 4s ago" phrase current. The only thing the periodic swap no longer carries is the <pre> SSE element. Net result: the subblock keeps reflecting reality every 2s but its height stops changing, so the rest of the page doesn't jump.

2. Live state — player count, map, hibernation, and compact player cards. Still HTMX-polled every 5s.

   Current players grid. Fixed 4-column grid (grid-template-columns: repeat(4, 1fr)), one row per player, max 2 rows (L4D2 caps at 8). No section header — the player cards follow the summary line directly; the avatars + ping meta make the section self-identifying. Each card is a single horizontal item: 22px avatar + two-line text block (name on top, terse meta below). Meta drops prefix words — joined 4m ago · ping 22-31ms becomes 4m · 22-31ms. The unit m/s/h/d plus the ms suffix carry the meaning.

   Recent players chips. Fixed 5-column grid (grid-template-columns: repeat(5, 1fr)), capped to 10 entries inline. Each chip is a single line: 16px avatar + name + · Xd. The "last seen" prefix is dropped — the trailing time unit is unambiguous. Long names get text-overflow: ellipsis and a title attribute holding the full name.

   Header doubles as the modal trigger. The recent section's header is N Recent (count first, e.g. 13 Recent). When N > 10 it renders as a link/button that opens #recent-players-modal; when N ≤ 10 it renders as plain text (the modal would be redundant). No separate "view all" link. The route exposes recent_players_overview (sliced to 10) and recent_players_total_count for this header.

   Narrow-viewport rule. Below ~600px viewport width, both grids drop to repeat(auto-fit, minmax(110px, 1fr)) so chips don't crush. One media query, applied to both grids.

   #recent-players-modal. New modal alongside log/console/files. Body renders the same chip format in a single column, scrollable, full list. Driven by recent_players (the full unsliced list already in context). Header: Recent players (N). No new route — same context.

3. Config — port, blueprint, RCON, hostname. Rendered into a flat auto-fit CSS grid (grid-template-columns: repeat(auto-fit, minmax(220px, 1fr))) so the sub-block wraps to one or two columns based on available width, and accepts new fields with no layout decisions. Each field is one cell: small uppercase label above the value/control. Hostname keeps its existing inline edit form; other fields render as static text.

   Field macro. Define {% macro config_field(label, value, editable=false) %} in _macros.html (create if absent) and call it once per row. Adding a future field becomes a one-line change in the template — no new CSS, no new markup patterns to learn.

   Expandability path (not in v1). When the field count crosses ~6, or when a natural category emerges (e.g. a second auth credential beyond RCON), promote that subset into a <fieldset><legend>…</legend>…</fieldset> inside the same outer grid. The grid scaffold is unchanged; this is a CSS-and-grouping migration, not a rewrite. Document this trigger here so future-us doesn't redesign blindly.

No changes to the partials themselves — only the wrapper template changes. The dashed horizontal rules are a new CSS rule on .state-cluster > * + *.

Inspection strip

One <section class="panel inspection-strip"> containing:

• Tab bar: three <button role="tab"> elements (Log, Console, Files) plus an expand button <button class="strip-expand" aria-label="Expand active tab">.
• Tab panes: three <div role="tabpanel">, one of which has no hidden attribute.

Tab panes

Tab	Inline content	Source partial / element
Log	<pre class="log-stream" data-sse-url=…> (same SSE element as today), capped to ~12rem with overflow:auto	unchanged
Console	<div class="console-transcript"> (read-write — same partial loop) + the existing console <form>	_console_line.html, inline form
Files	The _overlay_file_tree.html include, wrapped to scroll within ~12rem	unchanged

Tab switching

Plain CSS + a tiny JS helper. Pattern:

// new file: l4d2web/static/js/tabs.js
function activateTab(strip, name) {
  strip.querySelectorAll('[role="tab"]').forEach(t => {
    const on = t.dataset.tab === name;
    t.setAttribute('aria-selected', on);
    t.tabIndex = on ? 0 : -1;
  });
  strip.querySelectorAll('[role="tabpanel"]').forEach(p => {
    p.hidden = p.dataset.tab !== name;
  });
  strip.dataset.activeTab = name;
}

Bound via data-tab-strip on the container. Default active tab is Log (matches today's "is the server alive?" affordance). Active tab is not persisted in localStorage for v1 — can be added later if it proves annoying.

Expand control

One <button class="strip-expand">⛶</button> reads strip.dataset.activeTab and opens the matching modal via the existing data-inline-modal-open plumbing in modals.js. Implementation detail: the button has no static data-inline-modal-open; a small JS handler synthesizes the open call based on the active tab.

New modals

Five new <dialog class="modal"> instances are added alongside the existing rename/delete/reset modals. All follow the existing pattern — no new CSS for chrome, only the body content differs.

#log-modal

• Body: a taller <pre class="log-stream" data-sse-url=…> plus a small toolbar (Download .log link → /servers/{id}/logs/download if it exists today; otherwise drop — do not invent a new route in v1).
• The inline log pane and modal log pane both stream from the same SSE endpoint. They're independent EventSource connections; that's acceptable (low volume).

#console-modal

• Body: a taller <div class="console-transcript"> and a copy of the console form, posting to the same /servers/{id}/console endpoint.
• Two console forms exist (inline + modal). To avoid them swapping into each other's transcripts, each form's hx-target references its own transcript ID: #console-transcript-inline-{id} and #console-transcript-modal-{id}.
• New POSTs go to the form the user submitted; the other transcript stays as it was at last render. Acceptable for v1 — both transcripts derive from the same server history on page load, divergence only occurs within a session.

#files-modal

• Body: _overlay_file_tree.html with files_base_url = "/servers/" ~ server.id, rendered in a much taller container. No new behavior.

#recent-players-modal

• Body: full list of recent players in single-column chip format, scrollable. Triggered by the "N Recent" header (when N > 10) in the live-state subblock.
• Driven by the full recent_players list already in the route context.

#job-log-modal

• Body: <pre class="log-stream" data-sse-url="/jobs/{latest_job.id}/stream"> — same SSE endpoint that drives the current inline stream. Header shows the job phrase ("starting", "stopping", "resetting") and a "open full job →" link to /jobs/{id} for users who want history or related metadata.
• Trigger. The latest_job_phrase text in _server_actions.html (currently <a href="/jobs/{id}">) becomes a <button> styled like a link, carrying data-inline-modal-open="job-log-modal". The plain /jobs/{id} page is still reachable via the "show all" link in the same line and via the modal's "open full job →" footer link.
• The modal renders the SSE pre regardless of whether the job is running. For completed jobs the endpoint serves the final captured log (existing behavior); for running jobs it streams live. Closing the modal closes the EventSource — same lifecycle the inline pre had before.

Files to modify

File	Change
l4d2web/l4d2web/templates/server_detail.html	Rewritten body: state cluster, inspection strip, five modals
l4d2web/l4d2web/templates/_server_actions.html	Remove inline job-log <pre>; latest-job link → modal trigger
l4d2web/l4d2web/templates/_live_state.html	4-col current grid (no header) + 5-col recent chips + N Recent header trigger
l4d2web/l4d2web/templates/_macros.html (new if absent)	config_field(label, value, editable) macro for config grid
l4d2web/l4d2web/static/css/components.css	.state-cluster, .inspection-strip, player-grid/chip, tabbar
l4d2web/l4d2web/static/js/tabs.js (new)	Tab activation + expand-to-modal handler
l4d2web/l4d2web/templates/base.html	Include tabs.js if scripts are listed centrally
l4d2web/l4d2web/routes/page_routes.py (server_detail)	Add recent_players_overview (sliced to 10) + total count

Reused, do not modify

• _console_line.html, _overlay_file_tree.html
• static/js/modals.js (Esc/backdrop/focus-trap)
• SSE log stream route, HTMX live-state route, console POST route

Verification

End-to-end check via the local dev server (see feedback_textarea_editor_v2_run.md / reference_left4me_dev_server.md):

scripts/dev-server.py

Then in a browser (or via Chromium e2e in tests):

1. Open a server detail page (demo seed creates one). The state cluster shows at top with badge, start/stop/reset, players, map, port/blueprint/RCON/hostname — no scroll needed on a 1080p viewport.
2. Inspection strip defaults to the Log tab; lines stream live.
3. Click Console tab → transcript and input visible; type status, submit → reply appended.
4. Click Files tab → file tree visible and navigable.
5. Click ⛶ on each tab → matching modal opens with the larger view.
6. In #console-modal, send a command; transcript inside the modal updates. Close modal; inline console transcript still has its prior state.
7. Live-state subblock shows ≤ 8 current players in a 4-column grid (no header) and ≤ 10 recent players as 5-column chips under an N Recent header. With

   10 recents, N Recent becomes a link that opens #recent-players-modal; with ≤ 10 it stays plain text.

8. Start the server. The lifecycle subblock shows starting since 2s ago but no inline streaming log — the page does not shift as the job progresses. Click the job phrase → #job-log-modal opens and streams the live job log. Close → SSE disconnects.
9. Delete/Rename buttons still trigger their respective modals.

Add or extend a Playwright e2e (see existing fixtures in l4d2web/tests/e2e/) covering tab switching and expand-to-modal for one tab.

Out of scope (v1)

• Persisting active tab across reloads.
• Download-log action (only if the route already exists; otherwise defer).
• Mobile/narrow-viewport polish beyond the player-grid breakpoint (<600px → auto-fit, minmax(110px, 1fr)) described above. The inspection strip and config grid rely on their auto-fit rules to collapse naturally; no additional bespoke responsive rules in v1.
• Replacing HTMX polling on live state with SSE.