@telorun/debug-ui 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,14 @@
 # @telorun/debug-ui
 
-Browser-safe building blocks for watching a running Telo app's event stream:
-the debug **wire format**, **filter logic**, an **SSE client**, and **React
-components** — plus a standalone single-page app, built both multi-file
+Browser-safe building blocks for watching a running Telo app's debug stream:
+**filter logic**, an **SSE client**, and **React components** (a **Logs / Events**
+tab split) — plus a standalone single-page app, built both multi-file
 (`app-dist/`) and as one self-contained file (`app-single/index.html`).
 
+The **wire format** itself lives in [`@telorun/debug-wire`](../debug-wire); this
+package re-exports its types. A stream carries two frame kinds: `kind: "event"`
+(kernel events) and `kind: "log"` (stdout/stderr lines).
+
 This package is a **consumer**: it parses events, it never produces them. It has
 no Node-only dependency (no `fs`/`http`, not `@telorun/runner-core`) so it runs
 in any browser and in the editor webview.
@@ -18,22 +22,28 @@ runtime and is reimplemented per language. What's shared across runtimes is the
 that contract; the Node producer lives in the CLI.
 
 ```
-wire format (this README + wire-schema.json)   ← the cross-runtime contract
+wire format (@telorun/debug-wire)              ← the cross-runtime contract
   produced by → a kernel runtime's debug server (Node: the telo CLI)
   consumed by → the standalone app (served by the producer) + the editor panel
 ```
 
 ## Wire format
 
-Each event is one JSON object, delivered one-per-line over SSE and JSONL. Schema:
-[`wire-schema.json`](./wire-schema.json).
+Each frame is one JSON object, delivered one-per-line over SSE and JSONL. Schema
+and types: [`@telorun/debug-wire`](../debug-wire). An **event** frame:
 
 ```json
-{ "timestamp": "2026-06-13T07:00:00.000Z", "event": "Server.Listening",
+{ "kind": "event", "timestamp": "2026-06-13T07:00:00.000Z", "event": "Server.Listening",
   "payload": { "port": 5599, "mounts": [{ "path": "/v1", "mount": { "kind": "Http.Api", "name": "Api" } }] } }
 ```
 
-Producers reduce `payload` values to wire-safe forms before sending:
+A **log** frame (one stdout/stderr line):
+
+```json
+{ "kind": "log", "timestamp": "2026-06-13T07:00:00.000Z", "stream": "stdout", "line": "listening on :5599" }
+```
+
+Producers reduce event `payload` values to wire-safe forms before sending:
 
 | Value | Encodes as |
 |---|---|
@@ -65,8 +75,10 @@ still see *what* it was.
 - `GET /events.jsonl` — the full event log, for download.
 - `GET /blobs/:id` — a binary payload offloaded from an event (see Blobs below).
 - `GET /json/version` — discovery handshake: `{ protocol, protocolVersion, url,
-  events, eventsLog, blobs }`, so a consumer can confirm the wire format before
-  connecting.
+  events, eventsLog, blobs, appEndpoints }`, so a consumer can confirm the wire
+  format before connecting. `appEndpoints` is the running app's exposed addresses
+  (`{ host, port, protocol, url? }[]`); a blank `host` means the producer couldn't
+  know which hostname the viewer used — the UI fills it from the page origin.
 
 The Telo CLI exposes this server with `telo run <manifest> --inspect[=[host:]port]`
 (loopback `127.0.0.1:9230` by default). It serves the UI **same-origin**, fetching
@@ -78,12 +90,19 @@ it only writes the `.telo.debug.jsonl` event log.
 
 ```ts
 // Logic — framework-agnostic, browser-safe
-import { connectDebugStream, matchesFilter, distinctSuffixes,
-         isWireRef, eventSuffix, type DebugEvent, type EventFilter } from "@telorun/debug-ui";
+import { connectDebugStream, matchesFilter, distinctSuffixes, isWireRef, eventSuffix,
+         isLogFrame, endpointHref, type DebugFrame, type EventFilter,
+         type AppEndpoint } from "@telorun/debug-ui";
 
 // React components — for the standalone app and the editor panel
-import { DebugWatcher } from "@telorun/debug-ui/components";
-// <DebugWatcher url="http://localhost:9230/events" />
+import { DebugWatcher, DebugPanel } from "@telorun/debug-ui/components";
+// Standalone (owns its SSE + buffer; fetches `appEndpoints` from the handshake);
+// theme defaults to "system":
+//   <DebugWatcher url="http://localhost:9230/events" theme="system" />
+// Controlled (editor feeds frames it sourced itself, injects its own terminal as
+// the Logs tab, passes its own resolved theme + the app's run endpoints):
+//   <DebugPanel frames={frames} status={…} paused={…} onTogglePause={…} onClear={…}
+//               resolveBlobUrl={…} logsSlot={<Terminal/>} endpoints={…} theme="dark" />
 ```
 
 ## Scripts