@telorun/debug-ui 0.1.0

package/src/filter.ts

@@ -0,0 +1,52 @@
+import { type DebugEvent, eventSuffix } from "./wire.js";
+
+/**
+ * A debug-event filter. All fields are AND-combined; an empty filter matches
+ * everything. Pure and framework-agnostic so the standalone app and the editor
+ * panel filter identically.
+ */
+export interface EventFilter {
+  /** Free-text, case-insensitive; matched against the event name and the
+   *  JSON-stringified payload. */
+  text?: string;
+  /** Allowed event suffixes (`Invoked`, `Failed`, …). Empty/undefined = all. */
+  suffixes?: string[];
+  /** Substring matched against the event name's prefix (the kind/resource part). */
+  kind?: string;
+}
+
+const EMPTY: readonly string[] = [];
+
+/** True when `event` passes `filter`. */
+export function matchesFilter(event: DebugEvent, filter: EventFilter): boolean {
+  const suffixes = filter.suffixes ?? EMPTY;
+  if (suffixes.length > 0 && !suffixes.includes(eventSuffix(event.event))) {
+    return false;
+  }
+  if (filter.kind && !event.event.toLowerCase().includes(filter.kind.toLowerCase())) {
+    return false;
+  }
+  if (filter.text) {
+    const needle = filter.text.toLowerCase();
+    const haystack = `${event.event} ${safePayloadText(event.payload)}`.toLowerCase();
+    if (!haystack.includes(needle)) return false;
+  }
+  return true;
+}
+
+/** Distinct event suffixes present in `events`, sorted — drives the facet list. */
+export function distinctSuffixes(events: readonly DebugEvent[]): string[] {
+  const set = new Set<string>();
+  for (const e of events) set.add(eventSuffix(e.event));
+  return [...set].sort();
+}
+
+function safePayloadText(payload: unknown): string {
+  if (payload == null) return "";
+  if (typeof payload === "string") return payload;
+  try {
+    return JSON.stringify(payload);
+  } catch {
+    return "";
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// Browser-safe, framework-agnostic surface: wire types + filtering + SSE client.
+// No React, no Node built-ins — importable by the CLI (bun `source` condition),
+// the editor webview, and the standalone app alike.
+export {
+  type DebugEvent,
+  type WireRef,
+  type WireBlob,
+  isWireRef,
+  isWireBlob,
+  eventSuffix,
+} from "./wire.js";
+export { type EventFilter, matchesFilter, distinctSuffixes } from "./filter.js";
+export { type DebugStreamHandlers, connectDebugStream } from "./sse-client.js";
+export { type FoundBlob, collectBlobs, blobDimensions, formatBytes } from "./media.js";

package/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App.js";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/src/media.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { blobDimensions, collectBlobs, formatBytes } from "./media.js";
+
+const blob = (mediaType: string) => ({ $blob: "blobs/abc", mediaType, byteLength: 10 });
+
+describe("collectBlobs", () => {
+  it("finds a nested blob with its path and parent", () => {
+    const payload = { outputs: { image: blob("image/png"), width: 1024, height: 768 } };
+    const found = collectBlobs(payload);
+    expect(found).toHaveLength(1);
+    expect(found[0].path).toBe("outputs.image");
+    expect(found[0].parent).toBe(payload.outputs);
+    expect(blobDimensions(found[0].parent)).toBe("1024×768");
+  });
+
+  it("finds blobs in arrays", () => {
+    const payload = { files: [blob("application/pdf"), { nested: blob("image/jpeg") }] };
+    const found = collectBlobs(payload);
+    expect(found.map((f) => f.path)).toEqual(["files[0]", "files[1].nested"]);
+  });
+
+  it("returns nothing for a blob-free payload", () => {
+    expect(collectBlobs({ a: 1, b: "x", c: [1, 2] })).toEqual([]);
+  });
+
+  it("is cycle-safe", () => {
+    const p: Record<string, unknown> = { img: blob("image/png") };
+    p.self = p;
+    expect(collectBlobs(p)).toHaveLength(1);
+  });
+});
+
+describe("formatBytes", () => {
+  it("formats sizes", () => {
+    expect(formatBytes(512)).toBe("512 B");
+    expect(formatBytes(48211)).toBe("47 KB");
+    expect(formatBytes(2_200_000)).toBe("2.1 MB");
+  });
+});

package/src/media.ts

@@ -0,0 +1,55 @@
+import { isWireBlob, type WireBlob } from "./wire.js";
+
+export interface FoundBlob {
+  /** Dotted path to the blob within the payload, e.g. `outputs.image`. */
+  path: string;
+  blob: WireBlob;
+  /** The object the blob sits in — lets a consumer read sibling `width`/`height`. */
+  parent: Record<string, unknown> | null;
+}
+
+/**
+ * Walk a payload and collect every {@link WireBlob} with its path and parent.
+ * Pure and cycle-safe (a debug payload shouldn't be cyclic, but a defensive
+ * `seen` set keeps a malformed one from looping). Order is depth-first.
+ */
+export function collectBlobs(payload: unknown): FoundBlob[] {
+  const found: FoundBlob[] = [];
+  const seen = new WeakSet<object>();
+
+  const walk = (value: unknown, path: string, parent: Record<string, unknown> | null): void => {
+    if (isWireBlob(value)) {
+      found.push({ path, blob: value, parent });
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    if (seen.has(value)) return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+      value.forEach((v, i) => walk(v, `${path}[${i}]`, parent));
+      return;
+    }
+    const obj = value as Record<string, unknown>;
+    for (const [k, v] of Object.entries(obj)) {
+      walk(v, path ? `${path}.${k}` : k, obj);
+    }
+  };
+
+  walk(payload, "", null);
+  return found;
+}
+
+/** Sibling pixel dimensions of a blob, when the producer put them next to it. */
+export function blobDimensions(parent: Record<string, unknown> | null): string | null {
+  if (!parent) return null;
+  const w = parent.width;
+  const h = parent.height;
+  return typeof w === "number" && typeof h === "number" ? `${w}×${h}` : null;
+}
+
+/** Human-readable byte size, e.g. `47 KB`, `2.1 MB`. */
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${Math.round(n / 1024)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/sse-client.ts

@@ -0,0 +1,39 @@
+import type { DebugEvent } from "./wire.js";
+
+export interface DebugStreamHandlers {
+  onEvent: (event: DebugEvent) => void;
+  /** Connection state changes — drives a status indicator. */
+  onStatus?: (status: "connecting" | "open" | "closed") => void;
+}
+
+/**
+ * Connect to a producer's `/events` SSE endpoint. The browser's `EventSource`
+ * handles reconnection on its own; on each (re)connect the producer re-flushes
+ * its replay buffer, so a late or reconnected client always sees history.
+ *
+ * Returns a disposer that closes the connection. Runtime-agnostic: the URL can
+ * point at a Node CLI run, a Docker-mapped port, or a future Rust kernel —
+ * they all speak the same wire format.
+ */
+export function connectDebugStream(url: string, handlers: DebugStreamHandlers): () => void {
+  handlers.onStatus?.("connecting");
+  const source = new EventSource(url);
+
+  source.onopen = () => handlers.onStatus?.("open");
+
+  source.onmessage = (msg) => {
+    if (!msg.data) return;
+    try {
+      handlers.onEvent(JSON.parse(msg.data) as DebugEvent);
+    } catch {
+      // A malformed frame shouldn't kill the stream; skip it.
+    }
+  };
+
+  source.onerror = () => handlers.onStatus?.("connecting");
+
+  return () => {
+    source.close();
+    handlers.onStatus?.("closed");
+  };
+}

package/src/wire.ts

@@ -0,0 +1,77 @@
+/**
+ * The Telo debug event wire format — the language-neutral contract between a
+ * kernel runtime (the producer: Node today, Rust/Go later) and any consumer
+ * (this UI, the editor). A producer serializes each emitted event to this shape;
+ * consumers only ever parse it. The companion JSON Schema (`wire-schema.json`)
+ * is the source of truth a non-TypeScript producer conforms to.
+ */
+
+/** One event as it travels over the wire (one JSON object per SSE message / JSONL line). */
+export interface DebugEvent {
+  /** ISO-8601 timestamp set by the producer when the event was emitted. */
+  timestamp: string;
+  /** Dotted event name, e.g. `Server.Listening`, `MyKind.MyName.Invoked`. */
+  event: string;
+  /** Arbitrary event payload, already reduced to wire-safe values (see encoding rules). */
+  payload?: unknown;
+  /** Optional producer-attached metadata (namespace, resource, kind, name, …). */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Value-encoding rules a producer applies before a value enters `payload`:
+ *  - a resolved `!ref` (a live resource instance) → `{ kind, name }`
+ *  - any other live / unrepresentable value (controller instance, stream, client,
+ *    function, bigint) → a `"[Marker]"` string (e.g. `"[Stream]"`, `"[Kernel]"`)
+ *  - a reference cycle → `"[Circular]"`
+ *  - everything else → plain JSON
+ * Consumers shouldn't assume `payload` is any particular shape.
+ */
+
+/** A resolved-reference value as it appears in a payload. */
+export interface WireRef {
+  kind: string;
+  name: string;
+}
+
+/**
+ * A binary value offloaded to the producer's blob store. The bytes are NOT in the
+ * payload — `$blob` is a path (relative to the producer origin) the consumer
+ * fetches on demand (e.g. `<img src>`, a download link). The object key this sits
+ * under is preserved; only the bytes left the log.
+ */
+export interface WireBlob {
+  $blob: string;
+  mediaType: string;
+  byteLength: number;
+}
+
+/** Narrow a payload value to a {@link WireBlob}. */
+export function isWireBlob(value: unknown): value is WireBlob {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    typeof (value as WireBlob).$blob === "string" &&
+    typeof (value as WireBlob).mediaType === "string"
+  );
+}
+
+/** Narrow a payload value to a {@link WireRef} (e.g. to render it as a chip/link). */
+export function isWireRef(value: unknown): value is WireRef {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    typeof (value as WireRef).kind === "string" &&
+    typeof (value as WireRef).name === "string" &&
+    Object.keys(value as object).length === 2
+  );
+}
+
+/** The trailing segment of a dotted event name — the "kind" of event
+ *  (`Invoked`, `Failed`, `Listening`, …). Used for facet filtering and color. */
+export function eventSuffix(event: string): string {
+  const dot = event.lastIndexOf(".");
+  return dot >= 0 ? event.slice(dot + 1) : event;
+}