@lostgradient/cinder 0.3.0 → 0.4.0

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

@@ -4,7 +4,7 @@ Dense append-only viewer for timestamped operational events. Use it for workflow
 
 ## 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.
+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
 
@@ -84,11 +84,12 @@ The `followLatest` prop is bindable. Bind it to read whether the viewer is pause
 
 ## Event structure
 
-Each event in the `events` array follows the `StreamEvent` type:
+Each event in the `events` array can be a normal `StreamEvent` or an additive reconnect boundary:
 
 ```ts
 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';
@@ -96,24 +97,43 @@ type StreamEvent = {
   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.
+
 ## 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. |
+| Prop                 | Type                                                                                                                                                                                                                                                                                                                                         | Required | Default | Description                                                                                                                                                                                                                                                              |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `class`              | `string`                                                                                                                                                                                                                                                                                                                                     | no       | —       | Additional CSS classes applied to the root element.                                                                                                                                                                                                                      |
+| `connectionState`    | `"error"` \| `"connected"` \| `"connecting"` \| `"disconnected"`                                                                                                                                                                                                                                                                             | no       | —       | Current connection state. When provided, renders a StatusDot in the toolbar. Omit when the stream has no live transport.                                                                                                                                                 |
+| `detectSequenceGaps` | `boolean`                                                                                                                                                                                                                                                                                                                                    | no       | —       | Enables sequence-gap markers when `events` is the complete, unfiltered stream. Leave false for retained windows, severity-filtered subsets, search results, or any other caller-trimmed event array.                                                                     |
+| `events`             | ({ datetime: `string`; details?: `unknown`; id: `string`; sequence?: `integer`; severity?: `"debug"` \| `"info"` \| `"success"` \| `"warning"` \| `"error"`; source?: `string`; summary: `string`; timestamp?: `string` } \| { datetime?: `string`; id: `string`; kind: `"reconnected"`; replayedCount: `integer`; timestamp?: `string` })[] | yes      | —       | Events and additive boundary entries to render in chronological order, oldest first.                                                                                                                                                                                     |
+| `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.  |
+| `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 -->
 
@@ -126,7 +146,7 @@ type StreamEvent = {
 
 ## 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.
+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.
 
@@ -134,6 +154,8 @@ Severity tones are conveyed both visually (color bar, badge text) and through an
 
 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.
@@ -142,6 +164,6 @@ See `event-stream-viewer.a11y.md` for the full accessibility contract.
 
 <!-- generated:subcomponents:start -->
 
-This component composes `ConnectionIndicator`, `CopyButton`, and `JsonViewer` internally. They are not exposed as sub-namespace exports.
+This component composes `StatusDot`, `CopyButton`, and `JsonViewer` internally. They are not exposed as sub-namespace exports.
 
 <!-- generated:subcomponents:end -->

package/src/components/event-stream-viewer/event-stream-viewer-keys.ts

@@ -0,0 +1,74 @@
+import type { StreamEvent, StreamReconnectedBoundary } from './event-stream-viewer.types.ts';
+
+export function streamEventKey(event: StreamEvent): string {
+  const parts = [keyType('event'), keyField('id', event.id)];
+  if (typeof event.sequence === 'number') parts.push(keyField('sequence', event.sequence));
+  return parts.join('|');
+}
+
+export function reconnectedBoundaryKey(boundary: StreamReconnectedBoundary): string {
+  return [keyType('reconnected'), keyField('id', boundary.id)].join('|');
+}
+
+export function sequenceGapKey(
+  previousEventId: string | undefined,
+  event: StreamEvent,
+  expectedSequence: number,
+  actualSequence: number,
+): string {
+  return [
+    keyType('sequence-gap'),
+    previousEventId === undefined
+      ? keyField('previous-missing', true)
+      : keyField('previous', previousEventId),
+    keyField('next', event.id),
+    keyField('expected', expectedSequence),
+    keyField('actual', actualSequence),
+  ].join('|');
+}
+
+export function uniqueRenderedKey(baseKey: string, occurrences: Map<string, number>): string {
+  const occurrence = occurrences.get(baseKey) ?? 0;
+  occurrences.set(baseKey, occurrence + 1);
+  return occurrence === 0 ? baseKey : `${baseKey}|occurrence=${occurrence + 1}`;
+}
+
+export function detailsIdForKey(instanceId: string, key: string): string {
+  return `${escapeDomIdPart(instanceId)}-details-${hashString(key)}-${hashString(reverseString(key))}-${key.length}`;
+}
+
+function keyType(type: string): string {
+  return keyField('type', type);
+}
+
+function keyField(name: string, value: string | number | boolean): string {
+  const stringValue = String(value);
+  return `${name.length}:${name}:${stringValue.length}:${stringValue}`;
+}
+
+function escapeDomIdPart(value: string): string {
+  let result = '';
+  for (const character of value) {
+    result += /^[A-Za-z0-9_-]$/.test(character)
+      ? character
+      : `_${character.codePointAt(0)?.toString(16) ?? '0'}_`;
+  }
+  return result === '' ? 'empty' : result;
+}
+
+function reverseString(value: string): string {
+  let result = '';
+  for (const character of value) {
+    result = character + result;
+  }
+  return result;
+}
+
+function hashString(value: string): string {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = Math.imul(31, hash) + value.charCodeAt(index);
+    hash |= 0;
+  }
+  return (hash >>> 0).toString(36);
+}

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

@@ -1,4 +1,11 @@
 @layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+/* Compound composition aggregation: EventStreamViewer renders these primitives
+ * internally, so `cinder/event-stream-viewer/styles` must include their styling
+ * when consumers import the component-specific style sidecar. Sibling paths
+ * mirror between `src/` and generated `dist/`. */
+@import '../copy-button/copy-button.css';
+@import '../json-viewer/json-viewer.css';
+@import '../status-dot/status-dot.css';
 
 @layer cinder.components {
   /* ========================================
@@ -241,6 +248,45 @@
     padding: var(--cinder-space-1) 0;
   }
 
+  .cinder-event-stream-viewer__boundary-marker,
+  .cinder-event-stream-viewer__sequence-gap-marker {
+    padding: var(--cinder-space-1) var(--cinder-space-3);
+    border-block-end: 1px solid var(--cinder-border-muted);
+    background: var(--cinder-surface-inset);
+  }
+
+  .cinder-event-stream-viewer__marker-content {
+    display: flex;
+    align-items: center;
+    gap: var(--cinder-space-2);
+    color: var(--cinder-text-muted);
+    font-family: var(--cinder-font-sans);
+    font-size: var(--cinder-text-xs);
+    line-height: var(--cinder-leading-normal);
+  }
+
+  .cinder-event-stream-viewer__marker-content::before,
+  .cinder-event-stream-viewer__marker-content::after {
+    content: '';
+    flex: 1 1 auto;
+    block-size: 1px;
+    background: var(--cinder-border-muted);
+  }
+
+  .cinder-event-stream-viewer__boundary-marker .cinder-event-stream-viewer__marker-content {
+    color: var(--cinder-info);
+  }
+
+  .cinder-event-stream-viewer__sequence-gap-marker .cinder-event-stream-viewer__marker-content {
+    color: var(--cinder-warning);
+  }
+
+  .cinder-event-stream-viewer__marker-time {
+    color: var(--cinder-text-muted);
+    font-family: var(--cinder-font-mono);
+    white-space: nowrap;
+  }
+
   /* ----------------------------------------
    * Individual event entry
    * -------------------------------------- */

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

@@ -9,6 +9,12 @@
       "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": "reconnect-and-gap",
+      "title": "Reconnect replay with sequence gap",
+      "description": "Shows a reconnect boundary after retained events replay, followed by an advisory sequence-gap marker.",
+      "code": "<script lang=\"ts\">\n  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';\n  import type { EventStreamEntry } from '@lostgradient/cinder/event-stream-viewer';\n\n  const events: EventStreamEntry[] = [\n    {\n      id: 'evt-41',\n      sequence: 41,\n      datetime: '2026-05-12T16:04:10Z',\n      timestamp: '16:04:10',\n      severity: 'info',\n      source: 'orchestrator',\n      summary: 'Run resumed from retained stream cursor',\n    },\n    {\n      id: 'evt-42',\n      sequence: 42,\n      datetime: '2026-05-12T16:04:11Z',\n      timestamp: '16:04:11',\n      severity: 'success',\n      source: 'activity-worker',\n      summary: 'Replayed completion: ValidateInvoice',\n    },\n    {\n      id: 'reconnect-1',\n      kind: 'reconnected',\n      datetime: '2026-05-12T16:04:12Z',\n      timestamp: '16:04:12',\n      replayedCount: 2,\n    },\n    {\n      id: 'evt-45',\n      sequence: 45,\n      datetime: '2026-05-12T16:04:15Z',\n      timestamp: '16:04:15',\n      severity: 'warning',\n      source: 'stream-gateway',\n      summary: 'Received event after missing sequence 43 and 44',\n    },\n    {\n      id: 'evt-46',\n      sequence: 46,\n      datetime: '2026-05-12T16:04:16Z',\n      timestamp: '16:04:16',\n      severity: 'info',\n      source: 'orchestrator',\n      summary: 'Requested replay from last acknowledged sequence',\n    },\n  ];\n</script>\n\n<EventStreamViewer {events} label=\"Replay stream with reconnect and sequence gap\" />\n"
+    },
     {
       "id": "states",
       "title": "Loading and empty states",