@workflow/web-shared 5.0.0-beta.2 → 5.0.0-beta.21

package/src/components/new-trace-viewer/types.ts

@@ -0,0 +1,2 @@
+export type { Span, SpanEvent, Trace } from '../trace-viewer/types';
+export type { TraceWithMeta } from '../../lib/trace-builder';

package/src/components/new-trace-viewer/utils.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'vitest';
+import type { Span, SpanEvent } from './types';
+import {
+  computeOffscreenMarkers,
+  computeSpanMarkers,
+  computeSpanSegments,
+} from './utils';
+
+/** Build a high-res timestamp tuple ([seconds, nanoseconds]) for a given ms. */
+function ts(ms: number): [number, number] {
+  return [Math.floor(ms / 1000), (ms % 1000) * 1e6];
+}
+
+function hookSpan(opts: {
+  startMs: number;
+  endMs: number;
+  receivesMs: number[];
+  disposedMs?: number;
+  attrSetMs?: number[];
+}): Span {
+  const events: SpanEvent[] = [
+    { name: 'hook_created', timestamp: ts(opts.startMs), attributes: {} },
+    ...opts.receivesMs.map((m) => ({
+      name: 'hook_received',
+      timestamp: ts(m),
+      attributes: {},
+    })),
+    ...(opts.attrSetMs ?? []).map((m) => ({
+      name: 'attr_set',
+      timestamp: ts(m),
+      attributes: {},
+    })),
+    ...(opts.disposedMs !== undefined
+      ? [
+          {
+            name: 'hook_disposed',
+            timestamp: ts(opts.disposedMs),
+            attributes: {},
+          } satisfies SpanEvent,
+        ]
+      : []),
+  ];
+
+  return {
+    name: 'hook',
+    kind: 0,
+    resource: 'hook',
+    library: { name: 'workflow' },
+    spanId: 'hook-1',
+    status: { code: 1 },
+    traceFlags: 0,
+    attributes: {},
+    links: [],
+    events,
+    startTime: ts(opts.startMs),
+    endTime: ts(opts.endMs),
+    duration: ts(opts.endMs - opts.startMs),
+  };
+}
+
+describe('computeSpanSegments (run)', () => {
+  function runSpan(status: string): Span {
+    return {
+      name: 'run',
+      kind: 0,
+      resource: 'run',
+      library: { name: 'workflow' },
+      spanId: 'run-1',
+      status: { code: 1 },
+      traceFlags: 0,
+      attributes: { data: { status } },
+      links: [],
+      events: [{ name: 'run_created', timestamp: ts(0), attributes: {} }],
+      startTime: ts(0),
+      endTime: ts(100_000),
+      duration: ts(100_000),
+    };
+  }
+
+  it('maps pending runs to a pending segment (not running)', () => {
+    expect(computeSpanSegments(runSpan('pending'))).toEqual([
+      { startFraction: 0, endFraction: 1, status: 'pending' },
+    ]);
+  });
+
+  it('maps running runs to a running segment', () => {
+    expect(computeSpanSegments(runSpan('running'))).toEqual([
+      { startFraction: 0, endFraction: 1, status: 'running' },
+    ]);
+  });
+});
+
+describe('computeSpanSegments (hook)', () => {
+  it('renders a single waiting segment for a hook resumed many times but not disposed', () => {
+    const span = hookSpan({
+      startMs: 0,
+      endMs: 100_000,
+      receivesMs: [1_000, 50_000, 99_000],
+    });
+
+    // A hook resumed N times still re-suspends after every resumption, so the
+    // bar must stay "waiting" for its whole life — not flip to a filled
+    // "received" segment after the first receive (which hid resumptions 2..N).
+    expect(computeSpanSegments(span)).toEqual([
+      { startFraction: 0, endFraction: 1, status: 'waiting' },
+    ]);
+  });
+
+  it('ends the waiting segment at disposal and appends a succeeded tail', () => {
+    const span = hookSpan({
+      startMs: 0,
+      endMs: 100_000,
+      receivesMs: [1_000, 50_000],
+      disposedMs: 80_000,
+    });
+
+    expect(computeSpanSegments(span)).toEqual([
+      { startFraction: 0, endFraction: 0.8, status: 'waiting' },
+      { startFraction: 0.8, endFraction: 1, status: 'succeeded' },
+    ]);
+  });
+
+  it('treats a never-resolved hook as fully waiting', () => {
+    const span = hookSpan({ startMs: 0, endMs: 100_000, receivesMs: [] });
+
+    expect(computeSpanSegments(span)).toEqual([
+      { startFraction: 0, endFraction: 1, status: 'waiting' },
+    ]);
+  });
+});
+
+describe('computeSpanMarkers', () => {
+  it('emits one marker per resumption, including those at the temporal edges', () => {
+    const span = hookSpan({
+      startMs: 0,
+      endMs: 100_000,
+      receivesMs: [1_000, 50_000, 99_000],
+    });
+
+    const markers = computeSpanMarkers(span);
+    expect(markers.map((m) => m.timeMs)).toEqual([1_000, 50_000, 99_000]);
+  });
+
+  it('merges hook_received and attr_set events, sorted by time', () => {
+    const span = hookSpan({
+      startMs: 0,
+      endMs: 100_000,
+      receivesMs: [50_000],
+      attrSetMs: [10_000, 70_000],
+    });
+
+    expect(computeSpanMarkers(span).map((m) => m.timeMs)).toEqual([
+      10_000, 50_000, 70_000,
+    ]);
+  });
+
+  it('returns no markers when the span has no marker events', () => {
+    const span = hookSpan({ startMs: 0, endMs: 100_000, receivesMs: [] });
+    expect(computeSpanMarkers(span)).toEqual([]);
+  });
+});
+
+describe('computeOffscreenMarkers', () => {
+  const mk = (timeMs: number) => ({ timeMs });
+
+  it('partitions markers by side with the nearest one per side', () => {
+    const markers = [mk(5), mk(8), mk(50), mk(92), mk(99)];
+    // Visible window [10, 90]: 5 & 8 off left (nearest 8), 92 & 99 off right
+    // (nearest 92), 50 in view.
+    expect(computeOffscreenMarkers(markers, 10, 90)).toEqual({
+      left: { count: 2, nearestMs: 8 },
+      right: { count: 2, nearestMs: 92 },
+    });
+  });
+
+  it('returns null for a side with nothing off-screen', () => {
+    expect(computeOffscreenMarkers([mk(20), mk(50)], 10, 90)).toEqual({
+      left: null,
+      right: null,
+    });
+  });
+});

package/src/components/new-trace-viewer/utils.ts

@@ -0,0 +1,519 @@
+import { formatDuration, getHighResInMs } from '../trace-viewer/util/timing';
+import type { Span, SpanEvent } from './types';
+
+// ---------------------------------------------------------------------------
+// Root bounds
+// ---------------------------------------------------------------------------
+
+export interface RootBounds {
+  startTime: number;
+  endTime: number;
+  duration: number;
+}
+
+export function computeRootBounds(spans: Span[]): RootBounds {
+  let minStart = Number.POSITIVE_INFINITY;
+  let maxEnd = Number.NEGATIVE_INFINITY;
+
+  for (const span of spans) {
+    const s = getHighResInMs(span.startTime);
+    const e = getHighResInMs(span.endTime);
+    if (s < minStart) minStart = s;
+    if (e > maxEnd) maxEnd = e;
+  }
+
+  if (!Number.isFinite(minStart) || !Number.isFinite(maxEnd)) {
+    return { startTime: 0, endTime: 1, duration: 1 };
+  }
+
+  const duration = Math.max(maxEnd - minStart, 1);
+  return { startTime: minStart, endTime: maxEnd, duration };
+}
+
+export function getSpanDurationMs(span: Span): number {
+  return Math.max(
+    0,
+    getHighResInMs(span.endTime) - getHighResInMs(span.startTime)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Time markers
+// ---------------------------------------------------------------------------
+
+export interface TimeMarker {
+  position: number;
+  label: string;
+  value: number;
+}
+
+const NICE_INTERVALS = [
+  1, 2, 5, 10, 20, 50, 100, 200, 500, 1_000, 2_000, 5_000, 10_000, 20_000,
+  50_000, 100_000, 200_000, 500_000, 1_000_000, 2_000_000, 5_000_000,
+  10_000_000, 20_000_000, 50_000_000, 100_000_000, 200_000_000, 500_000_000,
+  1_000_000_000, 2_000_000_000, 5_000_000_000,
+];
+
+const MAX_MARKERS = 8;
+
+function pickInterval(viewDuration: number, maxTicks: number): number {
+  for (const interval of NICE_INTERVALS) {
+    if (viewDuration / interval <= maxTicks) return interval;
+  }
+  return NICE_INTERVALS[NICE_INTERVALS.length - 1];
+}
+
+export function computeTimeMarkers(
+  viewDuration: number,
+  offset: number
+): TimeMarker[] {
+  if (viewDuration <= 0) return [];
+
+  const maxTicks = 6;
+  const interval = pickInterval(viewDuration, maxTicks);
+
+  const firstTick = Math.ceil(offset / interval) * interval;
+  const markers: TimeMarker[] = [];
+
+  for (let t = firstTick; t <= offset + viewDuration; t += interval) {
+    const position = (t - offset) / viewDuration;
+    if (position < -0.01 || position > 1.01) continue;
+    markers.push({
+      position: Math.min(Math.max(position, 0), 1),
+      label: formatDuration(Math.abs(t), true),
+      value: t,
+    });
+    if (markers.length >= MAX_MARKERS) break;
+  }
+
+  return markers;
+}
+
+// ---------------------------------------------------------------------------
+// Span gaps — time deltas between consecutive spans (Alt-key overlay)
+// ---------------------------------------------------------------------------
+
+export interface SpanGap {
+  gapMs: number;
+  leftFrac: number;
+  rightFrac: number;
+  rowIndex: number;
+}
+
+export function computeSpanGaps(
+  spans: Span[],
+  viewStart: number,
+  viewEnd: number
+): SpanGap[] {
+  const range = viewEnd - viewStart;
+  if (range <= 0) return [];
+
+  const gaps: SpanGap[] = [];
+  for (let i = 0; i < spans.length - 1; i++) {
+    const endTime = getHighResInMs(spans[i].endTime);
+    const startTime = getHighResInMs(spans[i + 1].startTime);
+    const gapMs = startTime - endTime;
+    if (gapMs <= 0) continue;
+
+    const leftFrac = Math.min(Math.max((endTime - viewStart) / range, 0), 1);
+    const rightFrac = Math.min(Math.max((startTime - viewStart) / range, 0), 1);
+    if (rightFrac - leftFrac < 0.001) continue;
+
+    gaps.push({ gapMs, leftFrac, rightFrac, rowIndex: i });
+  }
+  return gaps;
+}
+
+// ---------------------------------------------------------------------------
+// Resource colors
+// ---------------------------------------------------------------------------
+
+export const RESOURCE_COLORS: Record<
+  string,
+  {
+    bg: string;
+    border: string;
+    errorBg?: string;
+    errorBorder?: string;
+  }
+> = {
+  run: {
+    bg: 'var(--ds-blue-200)',
+    border: 'var(--ds-blue-500)',
+    errorBg: 'var(--ds-red-200)',
+    errorBorder: 'var(--ds-red-500)',
+  },
+  step: {
+    bg: 'var(--ds-green-200)',
+    border: 'var(--ds-green-500)',
+    errorBg: 'var(--ds-red-200)',
+    errorBorder: 'var(--ds-red-500)',
+  },
+  hook: {
+    bg: 'var(--ds-amber-200)',
+    border: 'var(--ds-amber-500)',
+    errorBg: 'var(--ds-red-200)',
+    errorBorder: 'var(--ds-red-500)',
+  },
+  sleep: {
+    bg: 'var(--ds-purple-200)',
+    border: 'var(--ds-purple-500)',
+    errorBg: 'var(--ds-red-200)',
+    errorBorder: 'var(--ds-red-500)',
+  },
+  default: {
+    bg: 'var(--ds-gray-200)',
+    border: 'var(--ds-gray-500)',
+    errorBg: 'var(--ds-red-200)',
+    errorBorder: 'var(--ds-red-500)',
+  },
+};
+
+export function getResourceColor(resource: string): {
+  bg: string;
+  border: string;
+  errorBg?: string;
+  errorBorder?: string;
+} {
+  return RESOURCE_COLORS[resource] ?? RESOURCE_COLORS.default;
+}
+
+// ---------------------------------------------------------------------------
+// Span segments — split a timeline bar into colored sections by event state
+// ---------------------------------------------------------------------------
+
+export type SegmentStatus =
+  | 'queued'
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'retrying'
+  | 'succeeded'
+  | 'waiting'
+  | 'sleeping'
+  | 'received';
+
+export interface Segment {
+  startFraction: number;
+  endFraction: number;
+  status: SegmentStatus;
+}
+
+function clampFraction(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function timeToFraction(
+  time: number,
+  spanStart: number,
+  spanDuration: number
+): number {
+  if (spanDuration <= 0) return 0;
+  return clampFraction((time - spanStart) / spanDuration);
+}
+
+interface EventMark {
+  time: number;
+  type: string;
+}
+
+function sortedEventMarks(
+  events: SpanEvent[],
+  relevantNames: string[]
+): EventMark[] {
+  return events
+    .filter((e) => relevantNames.includes(e.name))
+    .map((e) => ({ time: getHighResInMs(e.timestamp), type: e.name }))
+    .sort((a, b) => a.time - b.time);
+}
+
+function computeStepSegmentsFromSpan(
+  startMs: number,
+  duration: number,
+  events: SpanEvent[]
+): Segment[] {
+  const segments: Segment[] = [];
+  if (duration <= 0) return segments;
+
+  const marks = sortedEventMarks(events, [
+    'step_started',
+    'step_retrying',
+    'step_failed',
+    'step_completed',
+  ]);
+
+  if (marks.length === 0) {
+    segments.push({ startFraction: 0, endFraction: 1, status: 'queued' });
+    return segments;
+  }
+
+  const firstFraction = timeToFraction(marks[0].time, startMs, duration);
+  if (firstFraction > 0.001) {
+    segments.push({
+      startFraction: 0,
+      endFraction: firstFraction,
+      status: 'queued',
+    });
+  }
+
+  for (let i = 0; i < marks.length; i++) {
+    const mark = marks[i];
+    const markFrac = timeToFraction(mark.time, startMs, duration);
+    const nextMark = marks[i + 1];
+    const nextFrac = nextMark
+      ? timeToFraction(nextMark.time, startMs, duration)
+      : 1;
+
+    if (mark.type === 'step_started') {
+      if (i === marks.length - 1) {
+        segments.push({
+          startFraction: markFrac,
+          endFraction: 1,
+          status: 'succeeded',
+        });
+      } else {
+        const nextType = nextMark.type;
+        const attemptStatus: SegmentStatus =
+          nextType === 'step_retrying' || nextType === 'step_failed'
+            ? 'failed'
+            : nextType === 'step_completed'
+              ? 'succeeded'
+              : 'retrying';
+        segments.push({
+          startFraction: markFrac,
+          endFraction: nextFrac,
+          status: attemptStatus,
+        });
+      }
+    } else if (mark.type === 'step_retrying') {
+      segments.push({
+        startFraction: markFrac,
+        endFraction: nextFrac,
+        status: 'retrying',
+      });
+    } else if (mark.type === 'step_failed') {
+      if (markFrac < 0.999) {
+        segments.push({
+          startFraction: markFrac,
+          endFraction: 1,
+          status: 'failed',
+        });
+      }
+    }
+  }
+
+  return segments;
+}
+
+function computeHookSegmentsFromSpan(
+  startMs: number,
+  duration: number,
+  events: SpanEvent[]
+): Segment[] {
+  const segments: Segment[] = [];
+  if (duration <= 0) return segments;
+
+  const disposed = sortedEventMarks(events, ['hook_disposed'])[0];
+  const disposedFrac = disposed
+    ? timeToFraction(disposed.time, startMs, duration)
+    : null;
+
+  const waitingEnd = disposedFrac ?? 1;
+  if (waitingEnd > 0.001) {
+    segments.push({
+      startFraction: 0,
+      endFraction: waitingEnd,
+      status: 'waiting',
+    });
+  }
+
+  if (disposedFrac !== null && disposedFrac < 0.999) {
+    segments.push({
+      startFraction: disposedFrac,
+      endFraction: 1,
+      status: 'succeeded',
+    });
+  }
+
+  return segments;
+}
+
+function computeSleepSegmentsFromSpan(
+  _startMs: number,
+  duration: number,
+  _events: SpanEvent[]
+): Segment[] {
+  if (duration <= 0) return [];
+  return [{ startFraction: 0, endFraction: 1, status: 'sleeping' }];
+}
+
+function runSegmentStatus(runStatus: string | undefined): SegmentStatus {
+  if (runStatus === 'failed') return 'failed';
+  if (runStatus === 'pending') return 'pending';
+  if (runStatus === 'running') return 'running';
+  return 'completed';
+}
+
+function computeRunSegmentsFromSpan(
+  startMs: number,
+  duration: number,
+  activeStartMs: number | undefined,
+  events: SpanEvent[],
+  attributes: Record<string, unknown>
+): Segment[] {
+  const segments: Segment[] = [];
+  if (duration <= 0) return segments;
+
+  const sorted = [...events]
+    .map((e) => ({ name: e.name, time: getHighResInMs(e.timestamp) }))
+    .sort((a, b) => a.time - b.time);
+
+  const runData = attributes?.data as Record<string, unknown> | undefined;
+  const runStatus = runData?.status as string | undefined;
+
+  const hasRunCreated = sorted.some((e) => e.name === 'run_created');
+
+  if (!hasRunCreated) {
+    return computeV1RunSegments(startMs, duration, activeStartMs, runStatus);
+  }
+
+  const failedEvent = sorted.find((e) => e.name === 'run_failed');
+
+  let cursor = 0;
+  if (activeStartMs !== undefined && activeStartMs > startMs) {
+    const queuedFrac = timeToFraction(activeStartMs, startMs, duration);
+    if (queuedFrac > 0.001) {
+      segments.push({
+        startFraction: 0,
+        endFraction: queuedFrac,
+        status: 'queued',
+      });
+      cursor = queuedFrac;
+    }
+  }
+
+  segments.push({
+    startFraction: cursor,
+    endFraction: 1,
+    status: failedEvent ? 'failed' : runSegmentStatus(runStatus),
+  });
+
+  return segments;
+}
+
+function computeV1RunSegments(
+  startMs: number,
+  duration: number,
+  activeStartMs: number | undefined,
+  runStatus: string | undefined
+): Segment[] {
+  const segments: Segment[] = [];
+
+  let cursor = 0;
+  if (activeStartMs !== undefined && activeStartMs > startMs) {
+    const queuedFrac = timeToFraction(activeStartMs, startMs, duration);
+    if (queuedFrac > 0.001) {
+      segments.push({
+        startFraction: 0,
+        endFraction: queuedFrac,
+        status: 'queued',
+      });
+      cursor = queuedFrac;
+    }
+  }
+
+  segments.push({
+    startFraction: cursor,
+    endFraction: 1,
+    status: runSegmentStatus(runStatus),
+  });
+
+  return segments;
+}
+
+/**
+ * Compute event-based segments for a span. Dispatches on `span.resource`
+ * to the appropriate resource-type-specific segment builder.
+ * Returns an empty array for generic (non-workflow) spans.
+ */
+export function computeSpanSegments(span: Span): Segment[] {
+  const startMs = getHighResInMs(span.startTime);
+  const duration = getSpanDurationMs(span);
+  const activeStartMs = span.activeStartTime
+    ? getHighResInMs(span.activeStartTime)
+    : undefined;
+
+  switch (span.resource) {
+    case 'step':
+      return computeStepSegmentsFromSpan(startMs, duration, span.events);
+    case 'hook':
+      return computeHookSegmentsFromSpan(startMs, duration, span.events);
+    case 'sleep':
+      return computeSleepSegmentsFromSpan(startMs, duration, span.events);
+    case 'run':
+      return computeRunSegmentsFromSpan(
+        startMs,
+        duration,
+        activeStartMs,
+        span.events,
+        span.attributes
+      );
+    default:
+      return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Span markers — point-in-time events rendered as ticks on top of a bar
+// ---------------------------------------------------------------------------
+
+export interface SpanMarker {
+  timeMs: number;
+}
+
+// `hook_received` = a resumption; `attr_set` = attributes written mid-span.
+const MARKER_EVENT_NAMES = ['hook_received', 'attr_set'];
+
+export function computeSpanMarkers(span: Span): SpanMarker[] {
+  return sortedEventMarks(span.events, MARKER_EVENT_NAMES).map((mark) => ({
+    timeMs: mark.time,
+  }));
+}
+
+export interface OffscreenSide {
+  count: number;
+  /** Nearest off-screen marker — the one a reveal jumps to. */
+  nearestMs: number;
+}
+
+export interface OffscreenMarkers {
+  left: OffscreenSide | null;
+  right: OffscreenSide | null;
+}
+
+/** Partition markers outside `[visibleStartMs, visibleEndMs]` by side. */
+export function computeOffscreenMarkers(
+  markers: SpanMarker[],
+  visibleStartMs: number,
+  visibleEndMs: number
+): OffscreenMarkers {
+  let leftCount = 0;
+  let rightCount = 0;
+  let nearestLeft = Number.NEGATIVE_INFINITY;
+  let nearestRight = Number.POSITIVE_INFINITY;
+  for (const { timeMs } of markers) {
+    if (timeMs < visibleStartMs) {
+      leftCount++;
+      if (timeMs > nearestLeft) nearestLeft = timeMs;
+    } else if (timeMs > visibleEndMs) {
+      rightCount++;
+      if (timeMs < nearestRight) nearestRight = timeMs;
+    }
+  }
+  return {
+    left: leftCount > 0 ? { count: leftCount, nearestMs: nearestLeft } : null,
+    right:
+      rightCount > 0 ? { count: rightCount, nearestMs: nearestRight } : null,
+  };
+}