@telorun/debug-ui 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/debug-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Browser-safe debug event UI for Telo: wire types, filtering, SSE client, and React components for watching a running app's event stream.",
   "keywords": [
     "telo",
@@ -42,6 +42,10 @@
     "app-single/**",
     "src/**"
   ],
+  "dependencies": {
+    "lucide-react": "^1.8.0",
+    "@telorun/debug-wire": "0.1.0"
+  },
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18"

package/src/ansi.ts

@@ -0,0 +1,11 @@
+// Strip ANSI escape sequences for plain-text display. The raw line (escapes
+// intact) is preserved on the wire; richer in-place rendering can layer on later.
+// Built from string source so the ESC/CSI control bytes stay unambiguous.
+const ANSI = new RegExp(
+  "[\\u001b\\u009b][[\\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-PR-TZcf-ntqry=><]",
+  "g",
+);
+
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI, "");
+}

package/src/components/DebugPanel.tsx

@@ -0,0 +1,133 @@
+import { type ReactNode, useMemo, useState } from "react";
+import type { AppEndpoint } from "../endpoints.js";
+import { distinctSuffixes, type EventFilter, matchesFilter } from "../filter.js";
+import { type DebugTheme, loadStoredTheme, storeTheme, useResolvedTheme } from "../theme.js";
+import { type DebugEvent, type DebugFrame, isLogFrame } from "../wire.js";
+import { EndpointLinks } from "./EndpointLinks.js";
+import { EventTable } from "./EventTable.js";
+import { FilterBar } from "./FilterBar.js";
+import { LogView } from "./LogView.js";
+import { ThemeToggle } from "./ThemeToggle.js";
+import "./styles.css";
+
+export interface DebugPanelProps {
+  /** The frame buffer (events + logs) in arrival order. */
+  frames: readonly DebugFrame[];
+  /** Re-render signal: bump when `frames` mutates in place. Unneeded when the
+   *  parent passes a fresh array reference on every change. */
+  revision?: number;
+  status: "connecting" | "open" | "closed";
+  paused: boolean;
+  onTogglePause: () => void;
+  onClear: () => void;
+  /** Resolve a blob pointer (path relative to the producer origin) to a URL. */
+  resolveBlobUrl: (rel: string) => string;
+  /** When provided, the Logs tab renders this instead of the built-in read-only
+   *  {@link LogView} — e.g. the editor injects its interactive terminal here so
+   *  the panel is writable. Standalone hosts omit it and get the log line view. */
+  logsSlot?: ReactNode;
+  /** Which tab is shown first. Default `"events"`; the editor opens on `"logs"`
+   *  so its interactive terminal is front-and-centre. */
+  defaultTab?: Tab;
+  /** Exposed addresses of the running application, rendered as links in the
+   *  header. The standalone {@link DebugWatcher} sources these from the producer's
+   *  handshake; the editor passes its resolved run endpoints. */
+  endpoints?: readonly AppEndpoint[];
+  /** Color theme. Defaults to `"system"` (follows the OS); an embedding host
+   *  (e.g. the editor) passes its own resolved `"light"` / `"dark"`. */
+  theme?: DebugTheme;
+}
+
+type Tab = "events" | "logs";
+
+/**
+ * The presentation half of the debug watcher: a Logs / Events tab split over one
+ * frame stream, with event filtering. Fully controlled — the standalone
+ * {@link DebugWatcher} drives it from an SSE buffer; the editor drives it from
+ * frames relayed over the run session. Only the source and `resolveBlobUrl` differ.
+ */
+export function DebugPanel({
+  frames,
+  revision,
+  status,
+  paused,
+  onTogglePause,
+  onClear,
+  resolveBlobUrl,
+  logsSlot,
+  defaultTab = "events",
+  endpoints,
+  theme,
+}: DebugPanelProps) {
+  const [tab, setTab] = useState<Tab>(defaultTab);
+  const [filter, setFilter] = useState<EventFilter>({});
+  // Controlled when the host supplies a theme; otherwise the panel owns its mode
+  // (shows the toggle, persists the choice across reloads). `"system"` resolves
+  // against the OS, live.
+  const controlled = theme !== undefined;
+  const [ownTheme, setOwnTheme] = useState<DebugTheme>(loadStoredTheme);
+  const changeOwnTheme = (next: DebugTheme): void => {
+    setOwnTheme(next);
+    storeTheme(next);
+  };
+  const resolvedTheme = useResolvedTheme(controlled ? theme : ownTheme);
+
+  // `revision` is the in-place-mutation signal; `frames` covers the fresh-array
+  // pattern. Either changing recomputes the split.
+  const events = useMemo(
+    () => frames.filter((f): f is DebugEvent => !isLogFrame(f)),
+    [frames, revision],
+  );
+  const logs = useMemo(() => frames.filter(isLogFrame), [frames, revision]);
+  const suffixes = useMemo(() => distinctSuffixes(events), [events]);
+  const visible = useMemo(
+    () => events.filter((e) => matchesFilter(e, filter)),
+    [events, filter],
+  );
+
+  return (
+    <div className="tdbg-root" data-theme={resolvedTheme}>
+      <div className="tdbg-tabs">
+        <span className={`tdbg-status tdbg-status-${status}`} title={`stream ${status}`} />
+        <button
+          className={`tdbg-tab${tab === "events" ? " tdbg-tab-on" : ""}`}
+          onClick={() => setTab("events")}
+        >
+          Events <span className="tdbg-tabcount">{events.length}</span>
+        </button>
+        <button
+          className={`tdbg-tab${tab === "logs" ? " tdbg-tab-on" : ""}`}
+          onClick={() => setTab("logs")}
+        >
+          Logs{logsSlot ? null : <span className="tdbg-tabcount">{logs.length}</span>}
+        </button>
+        <span className="tdbg-tabs-spacer" />
+        {endpoints && endpoints.length > 0 && <EndpointLinks endpoints={endpoints} />}
+        <button className="tdbg-btn" onClick={onTogglePause}>
+          {paused ? "Resume" : "Pause"}
+        </button>
+        <button className="tdbg-btn" onClick={onClear}>
+          Clear
+        </button>
+        {!controlled && <ThemeToggle value={ownTheme} onChange={changeOwnTheme} />}
+      </div>
+      {tab === "events" ? (
+        <>
+          <FilterBar
+            filter={filter}
+            onChange={setFilter}
+            suffixes={suffixes}
+            total={events.length}
+            shown={visible.length}
+            paused={paused}
+          />
+          <EventTable events={visible} resolveUrl={resolveBlobUrl} />
+        </>
+      ) : logsSlot ? (
+        <div className="tdbg-slot">{logsSlot}</div>
+      ) : (
+        <LogView logs={logs} />
+      )}
+    </div>
+  );
+}

package/src/components/DebugWatcher.tsx

@@ -1,47 +1,65 @@
-import { useEffect, useMemo, useReducer, useRef, useState } from "react";
-import { distinctSuffixes, type EventFilter, matchesFilter } from "../filter.js";
+import { useEffect, useReducer, useRef, useState } from "react";
+import type { AppEndpoint } from "../endpoints.js";
 import { connectDebugStream } from "../sse-client.js";
-import type { DebugEvent } from "../wire.js";
-import { EventTable } from "./EventTable.js";
-import { FilterBar } from "./FilterBar.js";
-import "./styles.css";
+import type { DebugTheme } from "../theme.js";
+import type { DebugFrame } from "../wire.js";
+import { DebugPanel } from "./DebugPanel.js";
 
 export interface DebugWatcherProps {
   /** The producer's SSE endpoint, e.g. `http://localhost:9230/events`. */
   url: string;
-  /** Ring-buffer cap; oldest events drop past this. Default 5000. */
+  /** Ring-buffer cap; oldest frames drop past this. Default 5000. */
   maxEvents?: number;
+  /** Color theme. Defaults to `"system"` (follows the OS). */
+  theme?: DebugTheme;
 }
 
 /**
- * The full debug-watcher view: connects to `url`, retains a bounded ring buffer,
- * and renders a filterable, pausable, newest-first event stream. Pausing freezes
- * the *view* while still collecting into the buffer, so nothing is lost on resume.
- *
- * Self-contained and prop-driven — the standalone app and the editor panel both
- * mount this; only the `url` differs.
+ * The standalone debug watcher: connects to `url`, retains a bounded ring buffer
+ * of frames (events + logs), and renders the Logs / Events {@link DebugPanel}.
+ * Pausing freezes the *view* while still collecting into the buffer, so nothing
+ * is lost on resume.
  */
-export function DebugWatcher({ url, maxEvents = 5000 }: DebugWatcherProps) {
-  const bufferRef = useRef<DebugEvent[]>([]);
+export function DebugWatcher({ url, maxEvents = 5000, theme }: DebugWatcherProps) {
+  const bufferRef = useRef<DebugFrame[]>([]);
   const pausedRef = useRef(false);
-  const [, bump] = useReducer((n: number) => n + 1, 0);
-  const [filter, setFilter] = useState<EventFilter>({});
+  const [rev, bump] = useReducer((n: number) => n + 1, 0);
   const [status, setStatus] = useState<"connecting" | "open" | "closed">("connecting");
   const [paused, setPaused] = useState(false);
+  const [endpoints, setEndpoints] = useState<AppEndpoint[]>([]);
 
   useEffect(() => {
     bufferRef.current = [];
     return connectDebugStream(url, {
       onStatus: setStatus,
-      onEvent: (e) => {
+      onFrame: (f) => {
         const buf = bufferRef.current;
-        buf.push(e);
+        buf.push(f);
         if (buf.length > maxEvents) buf.splice(0, buf.length - maxEvents);
         if (!pausedRef.current) bump();
       },
     });
   }, [url, maxEvents]);
 
+  // The producer advertises the running app's exposed addresses in its discovery
+  // handshake. Endpoints whose host the producer couldn't know (loopback default)
+  // arrive blank — fill them from the page origin so the link points where the
+  // viewer actually reached the server (localhost locally, the bound host remotely).
+  useEffect(() => {
+    let cancelled = false;
+    const origin = new URL(url).hostname;
+    fetch(new URL("json/version", url).toString())
+      .then((r) => (r.ok ? r.json() : null))
+      .then((info: { appEndpoints?: AppEndpoint[] } | null) => {
+        if (cancelled || !info?.appEndpoints) return;
+        setEndpoints(info.appEndpoints.map((e) => ({ ...e, host: e.host || origin })));
+      })
+      .catch(() => {});
+    return () => {
+      cancelled = true;
+    };
+  }, [url]);
+
   function togglePause() {
     const next = !pausedRef.current;
     pausedRef.current = next;
@@ -56,31 +74,19 @@ export function DebugWatcher({ url, maxEvents = 5000 }: DebugWatcherProps) {
 
   // Blob pointers are relative to the producer origin; resolve them against the
   // SSE URL so the standalone page and the editor (cross-origin) both work.
-  const resolveUrl = (rel: string) => new URL(rel, url).toString();
-
-  const all = bufferRef.current;
-  // `all.length` + `paused` are the render signal (the ref array is mutated in
-  // place); recompute the derived views against the current buffer snapshot.
-  const suffixes = useMemo(() => distinctSuffixes(all), [all.length, paused]);
-  const visible = useMemo(
-    () => all.filter((e) => matchesFilter(e, filter)),
-    [all.length, filter, paused],
-  );
+  const resolveBlobUrl = (rel: string) => new URL(rel, url).toString();
 
   return (
-    <div className="tdbg-root">
-      <FilterBar
-        filter={filter}
-        onChange={setFilter}
-        suffixes={suffixes}
-        status={status}
-        paused={paused}
-        onTogglePause={togglePause}
-        onClear={clear}
-        total={all.length}
-        shown={visible.length}
-      />
-      <EventTable events={visible} resolveUrl={resolveUrl} />
-    </div>
+    <DebugPanel
+      frames={bufferRef.current}
+      revision={rev}
+      status={status}
+      paused={paused}
+      onTogglePause={togglePause}
+      onClear={clear}
+      resolveBlobUrl={resolveBlobUrl}
+      endpoints={endpoints}
+      theme={theme}
+    />
   );
 }

package/src/components/EndpointLinks.tsx

@@ -0,0 +1,42 @@
+import { ExternalLink } from "lucide-react";
+import { type AppEndpoint, endpointHref, endpointLabel } from "../endpoints.js";
+
+export interface EndpointLinksProps {
+  endpoints: readonly AppEndpoint[];
+}
+
+/** The running application's exposed addresses, rendered in the panel header.
+ *  tcp endpoints are clickable links to the app; udp endpoints show as a plain
+ *  label (not reachable over http). Renders nothing when there are no endpoints. */
+export function EndpointLinks({ endpoints }: EndpointLinksProps) {
+  if (endpoints.length === 0) return null;
+  return (
+    <span className="tdbg-endpoints">
+      {endpoints.map((endpoint) => {
+        const label = endpointLabel(endpoint);
+        const href = endpointHref(endpoint);
+        const key = `${endpoint.host}:${endpoint.port}/${endpoint.protocol}`;
+        if (!href) {
+          return (
+            <span key={key} className="tdbg-endpoint">
+              {label}
+            </span>
+          );
+        }
+        return (
+          <a
+            key={key}
+            className="tdbg-endpoint tdbg-endpoint-link"
+            href={href}
+            target="_blank"
+            rel="noreferrer"
+            title={`Open ${href}`}
+          >
+            <ExternalLink size={11} aria-hidden />
+            {label}
+          </a>
+        );
+      })}
+    </span>
+  );
+}

package/src/components/FilterBar.tsx

@@ -4,25 +4,15 @@ export interface FilterBarProps {
   filter: EventFilter;
   onChange: (filter: EventFilter) => void;
   suffixes: string[];
-  status: "connecting" | "open" | "closed";
-  paused: boolean;
-  onTogglePause: () => void;
-  onClear: () => void;
   total: number;
   shown: number;
+  paused: boolean;
 }
 
-export function FilterBar({
-  filter,
-  onChange,
-  suffixes,
-  status,
-  paused,
-  onTogglePause,
-  onClear,
-  total,
-  shown,
-}: FilterBarProps) {
+/** Event-filtering controls for the Events tab: free-text search, kind/resource
+ *  substring, and suffix facets. Connection status and pause/clear live on the
+ *  shared {@link DebugPanel} tab bar, not here. */
+export function FilterBar({ filter, onChange, suffixes, total, shown, paused }: FilterBarProps) {
   const active = new Set(filter.suffixes ?? []);
 
   function toggleSuffix(suffix: string) {
@@ -35,7 +25,6 @@ export function FilterBar({
   return (
     <div className="tdbg-bar">
       <div className="tdbg-bar-row">
-        <span className={`tdbg-status tdbg-status-${status}`} title={`stream ${status}`} />
         <input
           className="tdbg-search"
           placeholder="Search event name or payload…"
@@ -48,12 +37,6 @@ export function FilterBar({
           value={filter.kind ?? ""}
           onChange={(e) => onChange({ ...filter, kind: e.target.value || undefined })}
         />
-        <button className="tdbg-btn" onClick={onTogglePause}>
-          {paused ? "Resume" : "Pause"}
-        </button>
-        <button className="tdbg-btn" onClick={onClear}>
-          Clear
-        </button>
         <span className="tdbg-counts">
           {shown === total ? `${total}` : `${shown} / ${total}`} events
           {paused ? " · paused" : ""}

package/src/components/LogView.tsx

@@ -0,0 +1,33 @@
+import { useEffect, useRef } from "react";
+import { stripAnsi } from "../ansi.js";
+import type { DebugLog } from "../wire.js";
+
+export interface LogViewProps {
+  logs: readonly DebugLog[];
+}
+
+/** Chronological stdout/stderr view (oldest first), autoscrolled to the tail.
+ *  stderr lines are tinted. ANSI escapes are stripped for display. */
+export function LogView({ logs }: LogViewProps) {
+  const endRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    endRef.current?.scrollIntoView({ block: "end" });
+  }, [logs.length]);
+
+  if (logs.length === 0) {
+    return <div className="tdbg-empty">No output yet — waiting for the stream…</div>;
+  }
+
+  return (
+    <div className="tdbg-logs" role="log" aria-live="polite">
+      {logs.map((l, i) => (
+        <div className={`tdbg-logline tdbg-log-${l.stream}`} key={i}>
+          <span className="tdbg-time">{l.timestamp.slice(11, 23)}</span>
+          <span className="tdbg-logtext">{stripAnsi(l.line)}</span>
+        </div>
+      ))}
+      <div ref={endRef} />
+    </div>
+  );
+}

package/src/components/ThemeToggle.tsx

@@ -0,0 +1,34 @@
+import { Monitor, Moon, Sun } from "lucide-react";
+import type { DebugTheme } from "../theme.js";
+
+const NEXT: Record<DebugTheme, DebugTheme> = {
+  system: "light",
+  light: "dark",
+  dark: "system",
+};
+const ICON: Record<DebugTheme, typeof Monitor> = {
+  system: Monitor,
+  light: Sun,
+  dark: Moon,
+};
+
+export interface ThemeToggleProps {
+  value: DebugTheme;
+  onChange: (theme: DebugTheme) => void;
+}
+
+/** Cycles system → light → dark. Shown only when the host hasn't supplied a
+ *  `theme` (i.e. the panel owns its own mode). */
+export function ThemeToggle({ value, onChange }: ThemeToggleProps) {
+  const Icon = ICON[value];
+  return (
+    <button
+      className="tdbg-btn tdbg-icon-btn"
+      onClick={() => onChange(NEXT[value])}
+      title={`Theme: ${value} (click to change)`}
+      aria-label={`Theme: ${value}`}
+    >
+      <Icon size={14} aria-hidden />
+    </button>
+  );
+}

package/src/components/index.ts

@@ -1,5 +1,8 @@
 // React component surface, consumed by the editor panel and the standalone app.
 export { DebugWatcher, type DebugWatcherProps } from "./DebugWatcher.js";
+export { DebugPanel, type DebugPanelProps } from "./DebugPanel.js";
 export { EventTable } from "./EventTable.js";
 export { FilterBar, type FilterBarProps } from "./FilterBar.js";
+export { LogView, type LogViewProps } from "./LogView.js";
 export { PayloadInspector } from "./PayloadInspector.js";
+export type { DebugTheme } from "../theme.js";

package/src/components/styles.css

@@ -1,10 +1,15 @@
 .tdbg-root {
+  /* Dark theme (default; also applied for `data-theme="dark"`). */
   --tdbg-bg: #0f1115;
   --tdbg-panel: #161a21;
   --tdbg-line: #232a34;
   --tdbg-text: #d7dce3;
   --tdbg-muted: #7a8493;
   --tdbg-accent: #4f9cf0;
+  --tdbg-bad: #ff8079;
+  --tdbg-bad-bg: rgba(248, 81, 73, 0.2);
+  --tdbg-good: #5fd673;
+  --tdbg-good-bg: rgba(63, 185, 80, 0.18);
   display: flex;
   flex-direction: column;
   height: 100%;
@@ -13,6 +18,76 @@
   color: var(--tdbg-text);
   background: var(--tdbg-bg);
 }
+.tdbg-root[data-theme="light"] {
+  --tdbg-bg: #ffffff;
+  --tdbg-panel: #f6f7f9;
+  --tdbg-line: #e2e5e9;
+  --tdbg-text: #1f2328;
+  --tdbg-muted: #656d76;
+  --tdbg-accent: #2f6feb;
+  --tdbg-bad: #cf222e;
+  --tdbg-bad-bg: rgba(207, 34, 46, 0.1);
+  --tdbg-good: #1a7f37;
+  --tdbg-good-bg: rgba(26, 127, 55, 0.1);
+}
+
+.tdbg-tabs {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
+  background: var(--tdbg-panel);
+  border-bottom: 1px solid var(--tdbg-line);
+}
+.tdbg-tab {
+  padding: 4px 10px;
+  color: var(--tdbg-muted);
+  background: none;
+  border: 1px solid transparent;
+  border-radius: 6px;
+  cursor: pointer;
+  font: inherit;
+}
+.tdbg-tab:hover {
+  color: var(--tdbg-text);
+}
+.tdbg-tab-on {
+  color: var(--tdbg-text);
+  background: var(--tdbg-bg);
+  border-color: var(--tdbg-line);
+}
+.tdbg-tabcount {
+  margin-left: 4px;
+  color: var(--tdbg-muted);
+  font-size: 11px;
+}
+.tdbg-tabs-spacer {
+  flex: 1;
+}
+.tdbg-endpoints {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.tdbg-endpoint {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px 8px;
+  color: var(--tdbg-muted);
+  background: var(--tdbg-bg);
+  border: 1px solid var(--tdbg-line);
+  border-radius: 999px;
+  font-size: 11px;
+  white-space: nowrap;
+}
+.tdbg-endpoint-link {
+  color: var(--tdbg-accent);
+  text-decoration: none;
+}
+.tdbg-endpoint-link:hover {
+  border-color: var(--tdbg-accent);
+}
 
 .tdbg-bar {
   position: sticky;
@@ -54,6 +129,12 @@
 .tdbg-btn:hover {
   border-color: var(--tdbg-accent);
 }
+.tdbg-icon-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 5px 7px;
+}
 .tdbg-counts {
   color: var(--tdbg-muted);
   white-space: nowrap;
@@ -91,7 +172,7 @@
   font: inherit;
 }
 .tdbg-facet-on {
-  color: #fff;
+  color: var(--tdbg-text);
   border-color: var(--tdbg-accent);
   background: rgba(79, 156, 240, 0.18);
 }
@@ -143,15 +224,15 @@
 .tdbg-suffix-failed,
 .tdbg-suffix-rejected,
 .tdbg-suffix-cancelled {
-  background: rgba(248, 81, 73, 0.2);
-  color: #ff8079;
+  background: var(--tdbg-bad-bg);
+  color: var(--tdbg-bad);
 }
 .tdbg-suffix-invoked,
 .tdbg-suffix-listening,
 .tdbg-suffix-started,
 .tdbg-suffix-initialized {
-  background: rgba(63, 185, 80, 0.18);
-  color: #5fd673;
+  background: var(--tdbg-good-bg);
+  color: var(--tdbg-good);
 }
 .tdbg-name {
   white-space: nowrap;
@@ -217,3 +298,32 @@
 .tdbg-ref {
   color: var(--tdbg-accent);
 }
+
+.tdbg-slot {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+.tdbg-logs {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+  padding: 4px 0;
+}
+.tdbg-logline {
+  display: flex;
+  gap: 8px;
+  padding: 1px 10px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.tdbg-logline:hover {
+  background: var(--tdbg-panel);
+}
+.tdbg-logtext {
+  flex: 1;
+}
+.tdbg-log-stderr .tdbg-logtext {
+  color: var(--tdbg-bad);
+}

package/src/endpoints.ts

@@ -0,0 +1,35 @@
+/** A reachable address of the running application, surfaced as a link in the
+ *  debug panel header. Structurally matches the editor's `RunnerEndpoint` and the
+ *  runner contract's endpoint, but kept local to debug-ui so this package stays
+ *  browser-safe with no dependency on the Node-only runner / kernel packages. */
+export interface AppEndpoint {
+  /** Reachable host. May be empty when the producer can't know which hostname the
+   *  viewer used; {@link DebugWatcher} fills it from the page origin. */
+  host: string;
+  port: number;
+  protocol: "tcp" | "udp";
+  /** Fully-qualified URL when the producer already knows it (proxy / ingress);
+   *  preferred over deriving `http://host:port`. */
+  url?: string;
+}
+
+/** The link a tcp endpoint resolves to, or `null` for a non-linkable (udp)
+ *  endpoint. Prefers an explicit `url`; otherwise derives `http://host:port`. */
+export function endpointHref(endpoint: AppEndpoint): string | null {
+  if (endpoint.url) return endpoint.url;
+  if (endpoint.protocol !== "tcp") return null;
+  return `http://${formatHost(endpoint.host)}:${endpoint.port}`;
+}
+
+/** Display label for an endpoint, e.g. `localhost:8080` or `:9000/udp`. */
+export function endpointLabel(endpoint: AppEndpoint): string {
+  const host = endpoint.host ? formatHost(endpoint.host) : "";
+  const base = `${host}:${endpoint.port}`;
+  return endpoint.protocol === "tcp" ? base : `${base}/udp`;
+}
+
+/** IPv6 literals need bracketing when paired with a port. */
+function formatHost(host: string): string {
+  if (host.includes(":") && !host.startsWith("[")) return `[${host}]`;
+  return host;
+}