EventStreamViewer

Dense append-only viewer for timestamped operational events. Use it for workflow run logs, job output streams, webhook traces, activity completion feeds, and other real-time or historical event consoles.

Overview

EventStreamViewer renders a scrollable list of timestamped events, each with a severity tone, optional source label, a one-line summary, and optional expandable JSON details. It handles follow-latest scrolling (auto-scroll to bottom as events arrive), a paused state when the user scrolls away, filtering hooks, copy actions, reconnect boundaries, and sequence-gap markers. Empty, loading, disconnected, and truncated states are built in.

Usage

<script lang="ts">
  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';
  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';

  let events: StreamEvent[] = $state([]);
</script>

<EventStreamViewer {events} label="Workflow run events" connectionState="connected" />

With filtering

When you pass an onFilter callback, the viewer renders a search input. Your component is responsible for filtering the events array in response to the callback.

<script lang="ts">
  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';
  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';

  let allEvents: StreamEvent[] = $state([]);
  let query = $state('');

  const filteredEvents = $derived(
    query
      ? allEvents.filter((e) => e.summary.toLowerCase().includes(query.toLowerCase()))
      : allEvents,
  );
</script>

<EventStreamViewer
  events={filteredEvents}
  filterQuery={query}
  onFilter={(q) => {
    query = q;
  }}
  label="Filtered event stream"
/>

With copy-visible action

<script lang="ts">
  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';
  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';

  let events: StreamEvent[] = $state([]);

  function handleCopyVisible(text: string) {
    navigator.clipboard.writeText(text);
  }
</script>

<EventStreamViewer {events} onCopyVisible={handleCopyVisible} label="Event stream" />

Follow-latest with bindable state

The followLatest prop is bindable. Bind it to read whether the viewer is paused or to programmatically resume following.

<script lang="ts">
  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';
  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';

  let events: StreamEvent[] = $state([]);
  let followLatest = $state(true);
</script>

<p>Status: {followLatest ? 'Following' : 'Paused'}</p>
<EventStreamViewer {events} bind:followLatest label="Event stream" />

Event structure

Each event in the events array can be a normal StreamEvent or an additive reconnect boundary:

type StreamEvent = {
  id: string; // Stable unique identifier (required)
  sequence?: number; // Optional integer sequence for gap detection
  datetime: string; // ISO 8601 datetime (required, used for machine-readable time)
  timestamp?: string; // Human-readable label e.g. "14:32:01" (falls back to datetime)
  severity?: 'debug' | 'info' | 'success' | 'warning' | 'error';
  source?: string; // Origin label e.g. "worker-1", "payment-service"
  summary: string; // One-line event description (required)
  details?: unknown; // Optional JSON payload rendered in a collapsible JsonViewer
};

type StreamReconnectedBoundary = {
  id: string; // Stable unique identifier (required)
  kind: 'reconnected';
  datetime?: string; // Optional ISO 8601 reconnect time
  timestamp?: string; // Optional human-readable reconnect label
  replayedCount: number; // Number of events replayed after reconnecting
};

type EventStreamEntry = StreamEvent | StreamReconnectedBoundary;

Reconnect and gap markers

Pass EventStreamEntry[] when a retained stream can resume after a network reconnect. A { kind: 'reconnected' } entry renders a visible divider labeled Reconnected — N events replayed.

Set detectSequenceGaps only when events is the complete, unfiltered stream. When consecutive rendered StreamEvent entries both provide integer sequence values and the later value is not the previous value plus one, the viewer inserts a sequence-gap marker before the later event. The marker shows the expected and received sequence numbers, for example Sequence gap — expected 8, received 10.

The onCopyVisible callback includes reconnect and sequence-gap markers in the copied text, so the copied stream preserves the same replay and continuity context users saw on screen.

Accessibility

The viewer exposes a role="log" region, which carries implicit polite live-region semantics so screen readers announce newly appended events. The region is keyboard focusable (tabindex="0") to support arrow-key scrolling.

Each event's timestamp is wrapped in a <time datetime="..."> element with the machine-readable ISO value, so assistive technology can parse the precise moment. The visible label is separate from the machine-readable datetime attribute.

Severity tones are conveyed both visually (color bar, badge text) and through an aria-label on the badge element. Source labels and summary text are part of the document flow and are read naturally.

The JSON details panel is toggled by a button with aria-expanded and aria-controls. Copy actions have descriptive aria-label attributes.

Reconnect boundaries render as visible dividers with role="separator" and a matching accessible label. Sequence gaps render as visible notes with role="note" and an accessible label that includes the expected and received sequence numbers.

A visually-hidden live region (always in the DOM, never removed with {#if}) announces copy confirmation to screen readers without double-announcing on the interactive buttons.

See event-stream-viewer.a11y.md for the full accessibility contract.