@telorun/debug-ui 0.1.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@telorun/debug-ui",
+  "version": "0.1.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",
+    "debug",
+    "events",
+    "sse"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "packages/debug-ui"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./components": {
+      "source": "./src/components/index.ts",
+      "types": "./src/components/index.ts",
+      "bun": "./src/components/index.ts",
+      "import": "./dist/components/index.js",
+      "default": "./dist/components/index.js"
+    },
+    "./app-dist/*": "./app-dist/*",
+    "./app-single/*": "./app-single/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**",
+    "app-dist/**",
+    "app-single/**",
+    "src/**"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^4",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "typescript": "^5.0.0",
+    "vite": "^6",
+    "vite-plugin-singlefile": "^2.3.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "vite build && vite build --config vite.single.config.ts",
+    "build:lib": "tsc -p tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/App.tsx

@@ -0,0 +1,10 @@
+import { DebugWatcher } from "./components/DebugWatcher.js";
+
+/**
+ * Standalone debug-watcher page. Served by a Telo runtime's debug server at `/`,
+ * so the SSE endpoint is `/events` on the same origin — no configuration needed.
+ */
+export function App() {
+  const url = new URL("events", window.location.href).toString();
+  return <DebugWatcher url={url} />;
+}

package/src/components/DebugWatcher.tsx

@@ -0,0 +1,86 @@
+import { useEffect, useMemo, useReducer, useRef, useState } from "react";
+import { distinctSuffixes, type EventFilter, matchesFilter } from "../filter.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";
+
+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. */
+  maxEvents?: number;
+}
+
+/**
+ * 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.
+ */
+export function DebugWatcher({ url, maxEvents = 5000 }: DebugWatcherProps) {
+  const bufferRef = useRef<DebugEvent[]>([]);
+  const pausedRef = useRef(false);
+  const [, bump] = useReducer((n: number) => n + 1, 0);
+  const [filter, setFilter] = useState<EventFilter>({});
+  const [status, setStatus] = useState<"connecting" | "open" | "closed">("connecting");
+  const [paused, setPaused] = useState(false);
+
+  useEffect(() => {
+    bufferRef.current = [];
+    return connectDebugStream(url, {
+      onStatus: setStatus,
+      onEvent: (e) => {
+        const buf = bufferRef.current;
+        buf.push(e);
+        if (buf.length > maxEvents) buf.splice(0, buf.length - maxEvents);
+        if (!pausedRef.current) bump();
+      },
+    });
+  }, [url, maxEvents]);
+
+  function togglePause() {
+    const next = !pausedRef.current;
+    pausedRef.current = next;
+    setPaused(next);
+    if (!next) bump();
+  }
+
+  function clear() {
+    bufferRef.current = [];
+    bump();
+  }
+
+  // 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],
+  );
+
+  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>
+  );
+}

package/src/components/EventTable.tsx

@@ -0,0 +1,65 @@
+import { useState } from "react";
+import { type DebugEvent, eventSuffix } from "../wire.js";
+import { PayloadInspector } from "./PayloadInspector.js";
+
+export interface EventTableProps {
+  events: readonly DebugEvent[];
+  resolveUrl: (rel: string) => string;
+}
+
+/** Newest-first list of events; each row expands to its payload. Expansion is
+ *  keyed by event identity so it survives re-renders as new events stream in. */
+export function EventTable({ events, resolveUrl }: EventTableProps) {
+  const [open, setOpen] = useState<Set<DebugEvent>>(new Set());
+
+  function toggle(e: DebugEvent) {
+    setOpen((prev) => {
+      const next = new Set(prev);
+      if (next.has(e)) next.delete(e);
+      else next.add(e);
+      return next;
+    });
+  }
+
+  if (events.length === 0) {
+    return <div className="tdbg-empty">No events match — waiting for the stream…</div>;
+  }
+
+  return (
+    <div className="tdbg-table" role="log" aria-live="polite">
+      {events
+        .map((e, i) => ({ e, i }))
+        .reverse()
+        .map(({ e, i }) => {
+          const suffix = eventSuffix(e.event);
+          return (
+            <div className="tdbg-row" key={i}>
+              <button
+                className="tdbg-rowhead"
+                onClick={() => toggle(e)}
+                aria-expanded={open.has(e)}
+              >
+                <span className="tdbg-caret">{open.has(e) ? "▾" : "▸"}</span>
+                <span className="tdbg-time">{e.timestamp.slice(11, 23)}</span>
+                <span className={`tdbg-badge tdbg-suffix-${suffix.toLowerCase()}`}>{suffix}</span>
+                <span className="tdbg-name">{e.event}</span>
+                <span className="tdbg-preview">{preview(e.payload)}</span>
+              </button>
+              {open.has(e) && <PayloadInspector value={e.payload} resolveUrl={resolveUrl} />}
+            </div>
+          );
+        })}
+    </div>
+  );
+}
+
+function preview(payload: unknown): string {
+  if (payload == null) return "";
+  let text: string;
+  try {
+    text = typeof payload === "string" ? payload : JSON.stringify(payload);
+  } catch {
+    return "";
+  }
+  return text.length > 120 ? `${text.slice(0, 120)}…` : text;
+}

package/src/components/FilterBar.tsx

@@ -0,0 +1,77 @@
+import type { EventFilter } from "../filter.js";
+
+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;
+}
+
+export function FilterBar({
+  filter,
+  onChange,
+  suffixes,
+  status,
+  paused,
+  onTogglePause,
+  onClear,
+  total,
+  shown,
+}: FilterBarProps) {
+  const active = new Set(filter.suffixes ?? []);
+
+  function toggleSuffix(suffix: string) {
+    const next = new Set(active);
+    if (next.has(suffix)) next.delete(suffix);
+    else next.add(suffix);
+    onChange({ ...filter, suffixes: next.size ? [...next] : undefined });
+  }
+
+  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…"
+          value={filter.text ?? ""}
+          onChange={(e) => onChange({ ...filter, text: e.target.value || undefined })}
+        />
+        <input
+          className="tdbg-kind"
+          placeholder="kind / resource…"
+          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" : ""}
+        </span>
+      </div>
+      {suffixes.length > 0 && (
+        <div className="tdbg-facets">
+          {suffixes.map((s) => (
+            <button
+              key={s}
+              className={`tdbg-facet${active.has(s) ? " tdbg-facet-on" : ""}`}
+              onClick={() => toggleSuffix(s)}
+            >
+              {s}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/PayloadInspector.tsx

@@ -0,0 +1,71 @@
+import { blobDimensions, collectBlobs, formatBytes, type FoundBlob } from "../media.js";
+import { isWireRef } from "../wire.js";
+
+export interface PayloadInspectorProps {
+  value: unknown;
+  /** Turns a relative blob path (`blobs/<id>`) into a fetchable URL against the
+   *  producer origin. */
+  resolveUrl: (rel: string) => string;
+}
+
+/** Pretty-prints an event payload. Binary lives in the blob store, not the
+ *  payload — any `{ $blob }` pointers are rendered as media (images inline, other
+ *  files as download links) above the JSON, which itself only carries the small
+ *  pointer descriptors. */
+export function PayloadInspector({ value, resolveUrl }: PayloadInspectorProps) {
+  if (value === undefined) {
+    return <div className="tdbg-payload tdbg-muted">(no payload)</div>;
+  }
+  if (isWireRef(value)) {
+    return (
+      <div className="tdbg-payload">
+        <span className="tdbg-ref">
+          {value.kind} <span className="tdbg-muted">·</span> {value.name}
+        </span>
+      </div>
+    );
+  }
+
+  const blobs = collectBlobs(value);
+  let text: string;
+  try {
+    text = JSON.stringify(value, null, 2);
+  } catch {
+    text = String(value);
+  }
+
+  return (
+    <div className="tdbg-payload-wrap">
+      {blobs.length > 0 && (
+        <div className="tdbg-media">
+          {blobs.map((b, i) => (
+            <BlobView key={i} found={b} resolveUrl={resolveUrl} />
+          ))}
+        </div>
+      )}
+      <pre className="tdbg-payload">{text}</pre>
+    </div>
+  );
+}
+
+function BlobView({ found, resolveUrl }: { found: FoundBlob; resolveUrl: (rel: string) => string }) {
+  const { path, blob, parent } = found;
+  const src = resolveUrl(blob.$blob);
+  const dims = blobDimensions(parent);
+  const caption = [path, blob.mediaType, formatBytes(blob.byteLength), dims].filter(Boolean).join(" · ");
+
+  return (
+    <figure className="tdbg-blob">
+      {blob.mediaType.startsWith("image/") ? (
+        <a href={src} target="_blank" rel="noreferrer">
+          <img className="tdbg-blob-img" src={src} alt={path} loading="lazy" />
+        </a>
+      ) : (
+        <a className="tdbg-blob-file" href={src} target="_blank" rel="noreferrer" download>
+          ⬇ {blob.mediaType}
+        </a>
+      )}
+      <figcaption className="tdbg-blob-cap">{caption}</figcaption>
+    </figure>
+  );
+}

package/src/components/index.ts

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

package/src/components/styles.css

@@ -0,0 +1,219 @@
+.tdbg-root {
+  --tdbg-bg: #0f1115;
+  --tdbg-panel: #161a21;
+  --tdbg-line: #232a34;
+  --tdbg-text: #d7dce3;
+  --tdbg-muted: #7a8493;
+  --tdbg-accent: #4f9cf0;
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+  font: 13px/1.5 ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  color: var(--tdbg-text);
+  background: var(--tdbg-bg);
+}
+
+.tdbg-bar {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  padding: 8px 10px;
+  background: var(--tdbg-panel);
+  border-bottom: 1px solid var(--tdbg-line);
+}
+.tdbg-bar-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.tdbg-search {
+  flex: 1;
+}
+.tdbg-search,
+.tdbg-kind {
+  padding: 5px 8px;
+  color: var(--tdbg-text);
+  background: var(--tdbg-bg);
+  border: 1px solid var(--tdbg-line);
+  border-radius: 5px;
+  font: inherit;
+}
+.tdbg-kind {
+  width: 140px;
+}
+.tdbg-btn {
+  padding: 5px 10px;
+  color: var(--tdbg-text);
+  background: var(--tdbg-bg);
+  border: 1px solid var(--tdbg-line);
+  border-radius: 5px;
+  cursor: pointer;
+  font: inherit;
+}
+.tdbg-btn:hover {
+  border-color: var(--tdbg-accent);
+}
+.tdbg-counts {
+  color: var(--tdbg-muted);
+  white-space: nowrap;
+}
+.tdbg-status {
+  width: 9px;
+  height: 9px;
+  border-radius: 50%;
+  background: var(--tdbg-muted);
+  flex: 0 0 auto;
+}
+.tdbg-status-open {
+  background: #3fb950;
+}
+.tdbg-status-connecting {
+  background: #d29922;
+}
+.tdbg-status-closed {
+  background: #f85149;
+}
+
+.tdbg-facets {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: 8px;
+}
+.tdbg-facet {
+  padding: 2px 8px;
+  color: var(--tdbg-muted);
+  background: var(--tdbg-bg);
+  border: 1px solid var(--tdbg-line);
+  border-radius: 999px;
+  cursor: pointer;
+  font: inherit;
+}
+.tdbg-facet-on {
+  color: #fff;
+  border-color: var(--tdbg-accent);
+  background: rgba(79, 156, 240, 0.18);
+}
+
+.tdbg-table {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+.tdbg-empty {
+  padding: 24px;
+  color: var(--tdbg-muted);
+  text-align: center;
+}
+.tdbg-row {
+  border-bottom: 1px solid var(--tdbg-line);
+}
+.tdbg-rowhead {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  width: 100%;
+  padding: 4px 10px;
+  background: none;
+  border: none;
+  color: inherit;
+  cursor: pointer;
+  text-align: left;
+  font: inherit;
+}
+.tdbg-rowhead:hover {
+  background: var(--tdbg-panel);
+}
+.tdbg-caret {
+  width: 12px;
+  color: var(--tdbg-muted);
+}
+.tdbg-time {
+  color: var(--tdbg-muted);
+  white-space: nowrap;
+}
+.tdbg-badge {
+  padding: 1px 6px;
+  border-radius: 4px;
+  background: var(--tdbg-line);
+  color: var(--tdbg-text);
+  white-space: nowrap;
+}
+.tdbg-suffix-failed,
+.tdbg-suffix-rejected,
+.tdbg-suffix-cancelled {
+  background: rgba(248, 81, 73, 0.2);
+  color: #ff8079;
+}
+.tdbg-suffix-invoked,
+.tdbg-suffix-listening,
+.tdbg-suffix-started,
+.tdbg-suffix-initialized {
+  background: rgba(63, 185, 80, 0.18);
+  color: #5fd673;
+}
+.tdbg-name {
+  white-space: nowrap;
+}
+.tdbg-preview {
+  color: var(--tdbg-muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.tdbg-payload-wrap {
+  background: var(--tdbg-panel);
+}
+.tdbg-payload {
+  margin: 0;
+  padding: 8px 10px 10px 30px;
+  background: var(--tdbg-panel);
+  overflow: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.tdbg-media {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  padding: 10px 10px 4px 30px;
+}
+.tdbg-blob {
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  max-width: 320px;
+}
+.tdbg-blob-img {
+  max-width: 320px;
+  max-height: 240px;
+  border: 1px solid var(--tdbg-line);
+  border-radius: 6px;
+  background:
+    repeating-conic-gradient(#1b202840 0% 25%, transparent 0% 50%) 50% / 16px 16px;
+  object-fit: contain;
+}
+.tdbg-blob-file {
+  display: inline-block;
+  padding: 8px 12px;
+  color: var(--tdbg-accent);
+  border: 1px solid var(--tdbg-line);
+  border-radius: 6px;
+  text-decoration: none;
+}
+.tdbg-blob-file:hover {
+  border-color: var(--tdbg-accent);
+}
+.tdbg-blob-cap {
+  color: var(--tdbg-muted);
+  font-size: 11px;
+  word-break: break-all;
+}
+.tdbg-muted {
+  color: var(--tdbg-muted);
+}
+.tdbg-ref {
+  color: var(--tdbg-accent);
+}

package/src/css.d.ts

@@ -0,0 +1,3 @@
+// Allow `import "./styles.css"` from component modules under tsc (Vite handles
+// the actual asset at build time).
+declare module "*.css";

package/src/filter.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { distinctSuffixes, matchesFilter } from "./filter.js";
+import type { DebugEvent } from "./wire.js";
+
+const ev = (event: string, payload?: unknown): DebugEvent => ({
+  timestamp: "2026-01-01T00:00:00.000Z",
+  event,
+  payload,
+});
+
+describe("matchesFilter", () => {
+  it("empty filter matches everything", () => {
+    expect(matchesFilter(ev("A.B.Invoked"), {})).toBe(true);
+  });
+
+  it("filters by suffix", () => {
+    const f = { suffixes: ["Failed"] };
+    expect(matchesFilter(ev("A.B.Failed"), f)).toBe(true);
+    expect(matchesFilter(ev("A.B.Invoked"), f)).toBe(false);
+  });
+
+  it("filters by kind substring (case-insensitive)", () => {
+    expect(matchesFilter(ev("Http.Server.Listening"), { kind: "server" })).toBe(true);
+    expect(matchesFilter(ev("Sql.Query.Invoked"), { kind: "server" })).toBe(false);
+  });
+
+  it("text searches name and payload", () => {
+    expect(matchesFilter(ev("A.Invoked", { port: 5599 }), { text: "5599" })).toBe(true);
+    expect(matchesFilter(ev("A.Invoked", { port: 1 }), { text: "listening" })).toBe(false);
+    expect(matchesFilter(ev("Server.Listening"), { text: "listening" })).toBe(true);
+  });
+
+  it("AND-combines fields", () => {
+    const f = { suffixes: ["Invoked"], text: "5599" };
+    expect(matchesFilter(ev("A.Invoked", { port: 5599 }), f)).toBe(true);
+    expect(matchesFilter(ev("A.Failed", { port: 5599 }), f)).toBe(false);
+  });
+
+  it("tolerates a non-serializable payload in text search", () => {
+    const cyclic: Record<string, unknown> = {};
+    cyclic.self = cyclic;
+    expect(matchesFilter(ev("A.Invoked", cyclic), { text: "A" })).toBe(true);
+  });
+});
+
+describe("distinctSuffixes", () => {
+  it("returns sorted distinct suffixes", () => {
+    expect(distinctSuffixes([ev("A.Invoked"), ev("B.Failed"), ev("C.Invoked")])).toEqual([
+      "Failed",
+      "Invoked",
+    ]);
+  });
+});