@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/event-stream-viewer/README.md

@@ -0,0 +1,147 @@
+# 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, and copy actions. Empty, loading, disconnected, and truncated states are built in.
+
+## Usage
+
+```svelte
+<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.
+
+```svelte
+<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
+
+```svelte
+<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.
+
+```svelte
+<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 follows the `StreamEvent` type:
+
+```ts
+type StreamEvent = {
+  id: string; // Stable unique identifier (required)
+  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
+};
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop              | Type                                                             | Required | Default | Description                                                                                                                                                                                                                                                              |
+| ----------------- | ---------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `class`           | `string`                                                         | no       | —       | Additional CSS classes applied to the root element.                                                                                                                                                                                                                      |
+| `connectionState` | `"connected"` \| `"connecting"` \| `"disconnected"` \| `"error"` | no       | —       | Current connection state. When provided, renders a ConnectionIndicator in the toolbar. Omit when the stream has no live transport.                                                                                                                                       |
+| `filterQuery`     | `string`                                                         | no       | —       | Current filter query value, for controlled usage. Pairs with `onfilter`.                                                                                                                                                                                                 |
+| `followLatest`    | `boolean`                                                        | no       | —       | When true, new events automatically scroll the list to the bottom. Set to false to pause follow-latest (e.g. while the user reads earlier events). Bindable so the parent can read the paused state the component sets internally.                                       |
+| `label`           | `string`                                                         | no       | —       | Accessible label for the event list region. Required for accessibility. Defaults to "Event stream".                                                                                                                                                                      |
+| `loading`         | `boolean`                                                        | no       | —       | Show a loading skeleton instead of the event list. Use while the first batch of events is in flight.                                                                                                                                                                     |
+| `truncated`       | `boolean`                                                        | no       | —       | Whether to show the "events were truncated" notice. This is a boolean flag, not a count: the viewer never slices `events` itself. Set it to `true` when you have already trimmed the array (e.g. capped retention) and want users to know earlier events are not shown.  |
+| `events`          | `(opaque)`                                                       | yes      | —       | Events to render in chronological order, oldest first. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                        |
+| `oncopyvisible`   | `(opaque)`                                                       | no       | —       | Callback fired when the user clicks the "Copy visible" toolbar action. Receives the text of all currently visible events. When omitted the copy action is hidden. Not expressible in JSON Schema; see the component types for the signature.                             |
+| `onfilter`        | `(opaque)`                                                       | no       | —       | Callback fired when the user updates the filter query in the toolbar's search field. The consumer is responsible for filtering `events` in response. When omitted the filter input is hidden. Not expressible in JSON Schema; see the component types for the signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+- `--cinder-event-stream-viewer-severity-color`
+<!-- generated:variables:end -->
+
+## Accessibility
+
+The viewer exposes a `role="log"` region with `aria-live="polite"` and `aria-atomic="false"` 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.
+
+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.
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+This component composes `ConnectionIndicator`, `CopyButton`, and `JsonViewer` internally. They are not exposed as sub-namespace exports.
+
+<!-- generated:subcomponents:end -->

package/src/components/event-stream-viewer/event-stream-viewer.css

@@ -0,0 +1,474 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+
+@layer cinder.components {
+  /* ========================================
+   * EVENT STREAM VIEWER
+   * Dense append-only operational log with
+   * follow-latest scrolling and severity tones.
+   * ======================================== */
+
+  .cinder-event-stream-viewer {
+    display: flex;
+    flex-direction: column;
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-lg);
+    background: var(--cinder-surface);
+    overflow: hidden;
+    font-family: var(--cinder-font-mono);
+    font-size: var(--cinder-text-sm);
+  }
+
+  /* ----------------------------------------
+   * Toolbar
+   * -------------------------------------- */
+
+  .cinder-event-stream-viewer__toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--cinder-space-2);
+    padding: var(--cinder-space-2) var(--cinder-space-3);
+    border-block-end: 1px solid var(--cinder-border-muted);
+    background: var(--cinder-surface-inset);
+    flex-shrink: 0;
+  }
+
+  .cinder-event-stream-viewer__toolbar-start,
+  .cinder-event-stream-viewer__toolbar-end {
+    display: flex;
+    align-items: center;
+    gap: var(--cinder-space-2);
+  }
+
+  .cinder-event-stream-viewer__resume-button {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cinder-space-1);
+    padding: var(--cinder-space-0-5) var(--cinder-space-2);
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-md);
+    background: var(--cinder-surface);
+    color: var(--cinder-text);
+    font-size: var(--cinder-text-xs);
+    font-family: inherit;
+    cursor: pointer;
+    transition: background-color var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  @media (hover: hover) {
+    .cinder-event-stream-viewer__resume-button:hover {
+      background: var(--cinder-surface-hover);
+    }
+  }
+
+  /* The root .cinder-event-stream-viewer has `overflow: hidden`; an outset ring
+   * is clipped. Use Strategy B-inset so the ring stays within the button's own
+   * border box. Matches the pattern used by .cinder-drawer__close (drawer.css). */
+  .cinder-event-stream-viewer__resume-button:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: inset 0 0 0 var(--cinder-ring-width) var(--cinder-ring-color);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-event-stream-viewer__resume-button:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(var(--cinder-ring-width) * -1);
+      box-shadow: none;
+    }
+  }
+
+  .cinder-event-stream-viewer__filter-input {
+    padding: var(--cinder-space-0-5) var(--cinder-space-2);
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-md);
+    background: var(--cinder-surface);
+    color: var(--cinder-text);
+    font-size: var(--cinder-text-xs);
+    font-family: inherit;
+    inline-size: 14rem;
+  }
+
+  .cinder-event-stream-viewer__filter-input:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-event-stream-viewer__filter-input:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+    }
+  }
+
+  .cinder-event-stream-viewer__copy-all-button {
+    padding: var(--cinder-space-0-5) var(--cinder-space-2);
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-md);
+    background: var(--cinder-surface);
+    color: var(--cinder-text);
+    font-size: var(--cinder-text-xs);
+    font-family: inherit;
+    cursor: pointer;
+    transition: background-color var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  @media (hover: hover) {
+    .cinder-event-stream-viewer__copy-all-button:hover:not(:disabled) {
+      background: var(--cinder-surface-hover);
+    }
+  }
+
+  .cinder-event-stream-viewer__copy-all-button:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .cinder-event-stream-viewer__copy-all-button:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-event-stream-viewer__copy-all-button:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+    }
+  }
+
+  /* ----------------------------------------
+   * Truncation notice
+   * -------------------------------------- */
+
+  .cinder-event-stream-viewer__truncation-notice {
+    padding: var(--cinder-space-1) var(--cinder-space-3);
+    background: var(--cinder-surface-inset);
+    color: var(--cinder-warning);
+    font-size: var(--cinder-text-xs);
+    font-family: var(--cinder-font-sans);
+    border-block-end: 1px solid var(--cinder-border-muted);
+    flex-shrink: 0;
+  }
+
+  /* ----------------------------------------
+   * Scroll viewport / log region
+   * -------------------------------------- */
+
+  .cinder-event-stream-viewer__viewport {
+    overflow-y: auto;
+    flex: 1 1 auto;
+    min-block-size: 0;
+    /* Default height — consumer overrides with inline style or class */
+    max-block-size: 32rem;
+    outline: none;
+  }
+
+  .cinder-event-stream-viewer__viewport:focus-visible {
+    box-shadow: inset 0 0 0 var(--cinder-ring-width) var(--cinder-ring-color);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-event-stream-viewer__viewport:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: -2px;
+    }
+  }
+
+  /* ----------------------------------------
+   * Loading skeleton
+   * -------------------------------------- */
+
+  .cinder-event-stream-viewer__loading {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-2);
+    padding: var(--cinder-space-3);
+  }
+
+  .cinder-event-stream-viewer__skeleton {
+    block-size: 1.25rem;
+    border-radius: var(--cinder-radius-sm);
+    background: var(--cinder-surface-inset);
+    animation: cinder-event-stream-viewer-skeleton-pulse 1.4s ease-in-out infinite;
+  }
+
+  .cinder-event-stream-viewer__skeleton:nth-child(2) {
+    inline-size: 80%;
+  }
+
+  .cinder-event-stream-viewer__skeleton:nth-child(3) {
+    inline-size: 60%;
+  }
+
+  @keyframes cinder-event-stream-viewer-skeleton-pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.4;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cinder-event-stream-viewer__skeleton {
+      animation: none;
+    }
+  }
+
+  /* ----------------------------------------
+   * Empty state
+   * -------------------------------------- */
+
+  .cinder-event-stream-viewer__empty {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: var(--cinder-space-8) var(--cinder-space-4);
+  }
+
+  .cinder-event-stream-viewer__empty-message {
+    margin: 0;
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-sm);
+    font-family: var(--cinder-font-sans);
+  }
+
+  /* ----------------------------------------
+   * Event list
+   * -------------------------------------- */
+
+  .cinder-event-stream-viewer__list {
+    list-style: none;
+    margin: 0;
+    padding: var(--cinder-space-1) 0;
+  }
+
+  /* ----------------------------------------
+   * Individual event entry
+   * -------------------------------------- */
+
+  .cinder-event-stream-viewer__event {
+    --cinder-event-stream-viewer-severity-color: var(--cinder-text-muted);
+
+    display: grid;
+    grid-template-columns: 3px 1fr auto;
+    gap: 0 var(--cinder-space-2);
+    padding: var(--cinder-space-1) var(--cinder-space-3) var(--cinder-space-1) 0;
+    border-block-end: 1px solid var(--cinder-border-muted);
+  }
+
+  .cinder-event-stream-viewer__event:last-child {
+    border-block-end: none;
+  }
+
+  @media (hover: hover) {
+    .cinder-event-stream-viewer__event:hover {
+      background: var(--cinder-surface-hover);
+    }
+  }
+
+  .cinder-event-stream-viewer__event:hover .cinder-event-stream-viewer__event-actions {
+    opacity: 1;
+  }
+
+  /* Severity bar */
+  .cinder-event-stream-viewer__event-bar {
+    align-self: stretch;
+    background: var(--cinder-event-stream-viewer-severity-color);
+    border-radius: 0 var(--cinder-radius-sm) var(--cinder-radius-sm) 0;
+    flex-shrink: 0;
+  }
+
+  /* Severity color mapping */
+  .cinder-event-stream-viewer__event[data-cinder-severity='debug'] {
+    --cinder-event-stream-viewer-severity-color: var(--cinder-text-subtle);
+  }
+
+  .cinder-event-stream-viewer__event[data-cinder-severity='info'] {
+    --cinder-event-stream-viewer-severity-color: var(--cinder-info);
+  }
+
+  .cinder-event-stream-viewer__event[data-cinder-severity='success'] {
+    --cinder-event-stream-viewer-severity-color: var(--cinder-success);
+  }
+
+  .cinder-event-stream-viewer__event[data-cinder-severity='warning'] {
+    --cinder-event-stream-viewer-severity-color: var(--cinder-warning);
+  }
+
+  .cinder-event-stream-viewer__event[data-cinder-severity='error'] {
+    --cinder-event-stream-viewer-severity-color: var(--cinder-danger);
+  }
+
+  /* Event body */
+  .cinder-event-stream-viewer__event-body {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-0-5);
+    min-inline-size: 0;
+    padding-block: var(--cinder-space-1);
+  }
+
+  /* Meta row: timestamp, severity badge, source */
+  .cinder-event-stream-viewer__event-meta {
+    display: flex;
+    align-items: center;
+    gap: var(--cinder-space-2);
+    flex-wrap: wrap;
+  }
+
+  .cinder-event-stream-viewer__event-time {
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-xs);
+    white-space: nowrap;
+    flex-shrink: 0;
+  }
+
+  .cinder-event-stream-viewer__event-severity {
+    font-size: var(--cinder-text-xs);
+    font-weight: var(--cinder-font-medium);
+    color: var(--cinder-event-stream-viewer-severity-color);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    flex-shrink: 0;
+  }
+
+  .cinder-event-stream-viewer__event-source {
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-text-muted);
+    background: var(--cinder-surface-inset);
+    padding: 0 var(--cinder-space-1);
+    border-radius: var(--cinder-radius-sm);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-inline-size: 16rem;
+  }
+
+  /* Summary text */
+  .cinder-event-stream-viewer__event-summary {
+    margin: 0;
+    color: var(--cinder-text);
+    line-height: var(--cinder-leading-normal);
+    overflow-wrap: break-word;
+  }
+
+  /* Details expand/collapse */
+  .cinder-event-stream-viewer__event-details-section {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-1);
+  }
+
+  .cinder-event-stream-viewer__details-toggle {
+    align-self: flex-start;
+    padding: 0;
+    border: none;
+    background: transparent;
+    color: var(--cinder-accent-text);
+    font-size: var(--cinder-text-xs);
+    font-family: inherit;
+    cursor: pointer;
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+
+  @media (hover: hover) {
+    .cinder-event-stream-viewer__details-toggle:hover {
+      color: var(--cinder-accent-text-hover);
+    }
+  }
+
+  .cinder-event-stream-viewer__details-toggle:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+    border-radius: var(--cinder-radius-sm);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-event-stream-viewer__details-toggle:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+    }
+  }
+
+  .cinder-event-stream-viewer__event-details {
+    border: 1px solid var(--cinder-border-muted);
+    border-radius: var(--cinder-radius-md);
+    padding: var(--cinder-space-2);
+    background: var(--cinder-surface-inset);
+    overflow-x: auto;
+  }
+
+  /* Per-event action buttons */
+  .cinder-event-stream-viewer__event-actions {
+    display: flex;
+    align-items: flex-start;
+    padding-block-start: var(--cinder-space-1);
+    opacity: 0;
+    transition: opacity var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  /* Reveal the per-event actions when a keyboard user focuses a control inside
+   * them — otherwise the copy button is tabbable while its parent is opacity:0,
+   * leaving keyboard users on an invisible control. */
+  .cinder-event-stream-viewer__event-actions:focus-within {
+    opacity: 1;
+  }
+
+  .cinder-event-stream-viewer__copy-event-button {
+    padding: var(--cinder-space-0-5) var(--cinder-space-1-5);
+    border: 1px solid var(--cinder-border-muted);
+    border-radius: var(--cinder-radius-sm);
+    background: var(--cinder-surface);
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-xs);
+    font-family: inherit;
+    cursor: pointer;
+    transition:
+      background-color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      color var(--cinder-duration-fast) var(--cinder-ease-standard);
+    white-space: nowrap;
+  }
+
+  @media (hover: hover) {
+    .cinder-event-stream-viewer__copy-event-button:hover {
+      background: var(--cinder-surface-hover);
+      color: var(--cinder-text);
+    }
+  }
+
+  .cinder-event-stream-viewer__copy-event-button:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+    opacity: 1;
+  }
+
+  @media (forced-colors: active) {
+    .cinder-event-stream-viewer__copy-event-button:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+    }
+  }
+
+  /* ----------------------------------------
+   * Live region (visually hidden always-in-DOM)
+   * -------------------------------------- */
+
+  .cinder-event-stream-viewer__live-region {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  /* ----------------------------------------
+   * Paused state indicator on root
+   * -------------------------------------- */
+
+  .cinder-event-stream-viewer[data-cinder-paused] .cinder-event-stream-viewer__viewport {
+    /* Subtle visual hint: slightly dimmed when paused */
+    opacity: 0.95;
+  }
+}

package/src/components/event-stream-viewer/event-stream-viewer.examples.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "event-stream-viewer",
+  "import": "@lostgradient/cinder/event-stream-viewer",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic event stream",
+      "description": "A minimal operational event log with severity tones, timestamps, and source labels. Suitable for job runners, deploy logs, and webhook traces.",
+      "code": "<script lang=\"ts\">\n  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';\n  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';\n\n  const events: StreamEvent[] = [\n    {\n      id: 'evt-1',\n      datetime: '2026-05-12T14:30:00Z',\n      timestamp: '14:30:00',\n      severity: 'info',\n      source: 'orchestrator',\n      summary: 'Workflow run started',\n    },\n    {\n      id: 'evt-2',\n      datetime: '2026-05-12T14:30:02Z',\n      timestamp: '14:30:02',\n      severity: 'info',\n      source: 'activity-worker',\n      summary: 'Scheduled activity: SendWelcomeEmail',\n    },\n    {\n      id: 'evt-3',\n      datetime: '2026-05-12T14:30:05Z',\n      timestamp: '14:30:05',\n      severity: 'success',\n      source: 'activity-worker',\n      summary: 'Activity completed: SendWelcomeEmail',\n    },\n    {\n      id: 'evt-4',\n      datetime: '2026-05-12T14:30:08Z',\n      timestamp: '14:30:08',\n      severity: 'warning',\n      source: 'activity-worker',\n      summary: 'Retrying activity: ChargePayment (attempt 1 of 3)',\n    },\n    {\n      id: 'evt-5',\n      datetime: '2026-05-12T14:30:15Z',\n      timestamp: '14:30:15',\n      severity: 'error',\n      source: 'activity-worker',\n      summary: 'Activity failed: ChargePayment — payment gateway timeout',\n    },\n  ];\n</script>\n\n<EventStreamViewer {events} label=\"Basic workflow events\" />\n"
+    },
+    {
+      "id": "states",
+      "title": "Loading and empty states",
+      "description": "Demonstrates the loading skeleton, empty state, and truncated notice variants.",
+      "code": "<script lang=\"ts\">\n  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';\n  import { Button } from '@lostgradient/cinder/button';\n  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';\n\n  type ViewerState = 'loading' | 'empty' | 'truncated' | 'normal';\n  let activeState = $state<ViewerState>('loading');\n\n  const sampleEvents: StreamEvent[] = [\n    {\n      id: 'evt-1',\n      datetime: '2026-05-12T14:30:00Z',\n      timestamp: '14:30:00',\n      severity: 'info',\n      source: 'worker',\n      summary: 'Job started',\n    },\n    {\n      id: 'evt-2',\n      datetime: '2026-05-12T14:30:05Z',\n      timestamp: '14:30:05',\n      severity: 'success',\n      source: 'worker',\n      summary: 'Job completed',\n    },\n  ];\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div style=\"display: flex; gap: 0.5rem; flex-wrap: wrap;\">\n    <Button\n      onclick={() => {\n        activeState = 'loading';\n      }}\n      variant={activeState === 'loading' ? 'primary' : 'secondary'}>Loading</Button\n    >\n    <Button\n      onclick={() => {\n        activeState = 'empty';\n      }}\n      variant={activeState === 'empty' ? 'primary' : 'secondary'}>Empty</Button\n    >\n    <Button\n      onclick={() => {\n        activeState = 'truncated';\n      }}\n      variant={activeState === 'truncated' ? 'primary' : 'secondary'}>Truncated</Button\n    >\n    <Button\n      onclick={() => {\n        activeState = 'normal';\n      }}\n      variant={activeState === 'normal' ? 'primary' : 'secondary'}>Normal</Button\n    >\n  </div>\n\n  <EventStreamViewer\n    events={activeState === 'empty' || activeState === 'loading' ? [] : sampleEvents}\n    loading={activeState === 'loading'}\n    truncated={activeState === 'truncated'}\n    label=\"Event stream states demo\"\n  />\n</div>\n"
+    },
+    {
+      "id": "with-filtering",
+      "title": "With search filtering",
+      "description": "Consumer-controlled filtering via the onfilter callback. The viewer renders a search input; the consumer owns the filtered events array.",
+      "code": "<script lang=\"ts\">\n  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';\n  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';\n\n  const allEvents: StreamEvent[] = [\n    {\n      id: 'e1',\n      datetime: '2026-05-12T10:00:00Z',\n      timestamp: '10:00:00',\n      severity: 'info',\n      source: 'orchestrator',\n      summary: 'Run started: DataPipeline',\n    },\n    {\n      id: 'e2',\n      datetime: '2026-05-12T10:00:02Z',\n      timestamp: '10:00:02',\n      severity: 'debug',\n      source: 'extractor',\n      summary: 'Connecting to source database',\n    },\n    {\n      id: 'e3',\n      datetime: '2026-05-12T10:00:05Z',\n      timestamp: '10:00:05',\n      severity: 'success',\n      source: 'extractor',\n      summary: 'Extracted 10,432 records from source',\n    },\n    {\n      id: 'e4',\n      datetime: '2026-05-12T10:00:08Z',\n      timestamp: '10:00:08',\n      severity: 'info',\n      source: 'transformer',\n      summary: 'Applying transformation rules',\n    },\n    {\n      id: 'e5',\n      datetime: '2026-05-12T10:00:12Z',\n      timestamp: '10:00:12',\n      severity: 'warning',\n      source: 'transformer',\n      summary: 'Skipped 14 records with missing required fields',\n    },\n    {\n      id: 'e6',\n      datetime: '2026-05-12T10:00:15Z',\n      timestamp: '10:00:15',\n      severity: 'success',\n      source: 'loader',\n      summary: 'Loaded 10,418 records to destination',\n    },\n    {\n      id: 'e7',\n      datetime: '2026-05-12T10:00:16Z',\n      timestamp: '10:00:16',\n      severity: 'success',\n      source: 'orchestrator',\n      summary: 'Run completed: DataPipeline',\n    },\n  ];\n\n  let query = $state('');\n\n  const filteredEvents = $derived(\n    query.trim()\n      ? allEvents.filter(\n          (e) =>\n            e.summary.toLowerCase().includes(query.toLowerCase()) ||\n            (e.source ?? '').toLowerCase().includes(query.toLowerCase()) ||\n            (e.severity ?? '').toLowerCase().includes(query.toLowerCase()),\n        )\n      : allEvents,\n  );\n</script>\n\n<EventStreamViewer\n  events={filteredEvents}\n  filterQuery={query}\n  onfilter={(q: string) => {\n    query = q;\n  }}\n  label=\"DataPipeline run events\"\n/>\n"
+    },
+    {
+      "id": "workflow-run",
+      "title": "Workflow run with retries and signals",
+      "description": "A realistic workflow run event stream with activity completions, retry attempts, inbound signals, and a structured failure trace with expandable JSON details.",
+      "code": "<script lang=\"ts\">\n  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';\n  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';\n\n  const events: StreamEvent[] = [\n    {\n      id: 'run-start',\n      datetime: '2026-05-12T09:00:00Z',\n      timestamp: '09:00:00',\n      severity: 'info',\n      source: 'orchestrator',\n      summary: 'Workflow run started: OrderFulfillment/wf-83a1c',\n      details: { workflowId: 'wf-83a1c', runId: 'run-7f2b', input: { orderId: 'ord-991' } },\n    },\n    {\n      id: 'activity-1-scheduled',\n      datetime: '2026-05-12T09:00:01Z',\n      timestamp: '09:00:01',\n      severity: 'info',\n      source: 'activity-worker',\n      summary: 'Scheduled activity: ValidateInventory',\n    },\n    {\n      id: 'activity-1-complete',\n      datetime: '2026-05-12T09:00:03Z',\n      timestamp: '09:00:03',\n      severity: 'success',\n      source: 'activity-worker',\n      summary: 'Activity completed: ValidateInventory',\n      details: { available: true, reservedQty: 2 },\n    },\n    {\n      id: 'activity-2-scheduled',\n      datetime: '2026-05-12T09:00:04Z',\n      timestamp: '09:00:04',\n      severity: 'info',\n      source: 'payment-worker',\n      summary: 'Scheduled activity: ChargePayment',\n    },\n    {\n      id: 'activity-2-retry-1',\n      datetime: '2026-05-12T09:00:07Z',\n      timestamp: '09:00:07',\n      severity: 'warning',\n      source: 'payment-worker',\n      summary: 'Activity failed (attempt 1/3): ChargePayment — upstream timeout',\n      details: { attempt: 1, maxAttempts: 3, error: 'GatewayTimeoutError', retryIn: '5s' },\n    },\n    {\n      id: 'activity-2-retry-2',\n      datetime: '2026-05-12T09:00:13Z',\n      timestamp: '09:00:13',\n      severity: 'warning',\n      source: 'payment-worker',\n      summary: 'Activity failed (attempt 2/3): ChargePayment — upstream timeout',\n      details: { attempt: 2, maxAttempts: 3, error: 'GatewayTimeoutError', retryIn: '10s' },\n    },\n    {\n      id: 'signal-received',\n      datetime: '2026-05-12T09:00:18Z',\n      timestamp: '09:00:18',\n      severity: 'info',\n      source: 'orchestrator',\n      summary: 'Signal received: ApproveManualOverride',\n      details: { signalName: 'ApproveManualOverride', payload: { approvedBy: 'ops@example.com' } },\n    },\n    {\n      id: 'activity-2-complete',\n      datetime: '2026-05-12T09:00:20Z',\n      timestamp: '09:00:20',\n      severity: 'success',\n      source: 'payment-worker',\n      summary: 'Activity completed: ChargePayment (manual override)',\n      details: { chargeId: 'ch_9f3b', amount: 149.99, currency: 'USD' },\n    },\n    {\n      id: 'activity-3-scheduled',\n      datetime: '2026-05-12T09:00:21Z',\n      timestamp: '09:00:21',\n      severity: 'info',\n      source: 'fulfillment-worker',\n      summary: 'Scheduled activity: ShipOrder',\n    },\n    {\n      id: 'activity-3-failed',\n      datetime: '2026-05-12T09:00:25Z',\n      timestamp: '09:00:25',\n      severity: 'error',\n      source: 'fulfillment-worker',\n      summary: 'Activity permanently failed: ShipOrder — warehouse API returned 503',\n      details: {\n        attempt: 3,\n        maxAttempts: 3,\n        error: 'WarehouseUnavailableError',\n        message: 'Warehouse API returned 503 after 3 retries',\n        stack:\n          'WarehouseUnavailableError\\n  at ShipOrder.execute (ship-order.ts:42)\\n  at ActivityWorker.run (worker.ts:120)',\n      },\n    },\n    {\n      id: 'run-failed',\n      datetime: '2026-05-12T09:00:26Z',\n      timestamp: '09:00:26',\n      severity: 'error',\n      source: 'orchestrator',\n      summary: 'Workflow run failed: OrderFulfillment/wf-83a1c',\n      details: { failureReason: 'ChildWorkflowFailed', compensating: false },\n    },\n  ];\n</script>\n\n<EventStreamViewer {events} label=\"Workflow run: OrderFulfillment\" connectionState=\"disconnected\" />\n"
+    }
+  ]
+}