@workflow/web-shared 5.0.0-beta.23 → 5.0.0-beta.25

package/src/components/workflow-trace-view.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { parseStepName, parseWorkflowName } from '@workflow/utils/parse-name';
-import type { Event, Hook, Step, WorkflowRun } from '@workflow/world';
+import type { Event, Hook, WorkflowRun } from '@workflow/world';
 import {
   ChevronDown,
   ChevronUp,
@@ -29,6 +29,7 @@ import {
   type SpanSelectionInfo,
 } from './sidebar/entity-detail-panel';
 import { ResolveHookModal } from './sidebar/resolve-hook-modal';
+import type { FetchSpanDetail } from './sidebar/use-selected-span-detail';
 import {
   TraceViewerContextProvider,
   TraceViewerTimeline,
@@ -764,15 +765,12 @@ export const WorkflowTraceViewer = ({
   events,
   isLoading,
   error,
-  spanDetailData,
-  spanDetailLoading,
-  spanDetailError,
+  fetchSpanDetail,
   onWakeUpSleep,
   onResolveHook,
   onCancelRun,
   onStreamClick,
   onRunClick,
-  onSpanSelect,
   onLoadEventData,
   onLoadMoreSpans,
   hasMoreSpans = false,
@@ -780,14 +778,13 @@ export const WorkflowTraceViewer = ({
   encryptionKey,
   onDecrypt,
   isDecrypting = false,
+  showSeparateEventOccurrenceTimestamps = false,
 }: {
   run: WorkflowRun;
   events: Event[];
   isLoading?: boolean;
   error?: Error | null;
-  spanDetailData?: WorkflowRun | Step | Hook | Event | null;
-  spanDetailLoading?: boolean;
-  spanDetailError?: Error | null;
+  fetchSpanDetail: FetchSpanDetail;
   onWakeUpSleep?: (
     runId: string,
     correlationId: string
@@ -803,8 +800,6 @@ export const WorkflowTraceViewer = ({
   onStreamClick?: (streamId: string) => void;
   /** Callback when a run reference is clicked in the detail panel */
   onRunClick?: (runId: string) => void;
-  /** Callback when a span is selected. */
-  onSpanSelect?: (info: SpanSelectionInfo) => void;
   /** Callback to load event data for a specific event (lazy loading in sidebar) */
   onLoadEventData?: (
     correlationId: string,
@@ -822,6 +817,8 @@ export const WorkflowTraceViewer = ({
   onDecrypt?: () => void;
   /** Whether the encryption key is currently being fetched */
   isDecrypting?: boolean;
+  /** Show occurredAt separately instead of folding it into the Created timestamp. */
+  showSeparateEventOccurrenceTimestamps?: boolean;
 }) => {
   const toast = useToast();
   const [selectedSpan, setSelectedSpan] = useState<SelectedSpanInfo | null>(
@@ -856,13 +853,6 @@ export const WorkflowTraceViewer = ({
     }
   }, [error, isLoading]);
 
-  const handleSpanSelect = useCallback(
-    (info: SpanSelectionInfo) => {
-      onSpanSelect?.(info);
-    },
-    [onSpanSelect]
-  );
-
   const handleSelectionChange = useCallback(
     (info: SelectedSpanInfo | null) => {
       if (info) {
@@ -1158,10 +1148,7 @@ export const WorkflowTraceViewer = ({
                 run={run}
                 onStreamClick={onStreamClick}
                 onRunClick={onRunClick}
-                spanDetailData={spanDetailData ?? null}
-                spanDetailError={spanDetailError}
-                spanDetailLoading={spanDetailLoading}
-                onSpanSelect={handleSpanSelect}
+                fetchSpanDetail={fetchSpanDetail}
                 onWakeUpSleep={onWakeUpSleep}
                 onLoadEventData={onLoadEventData}
                 onResolveHook={onResolveHook}
@@ -1169,6 +1156,9 @@ export const WorkflowTraceViewer = ({
                 onDecrypt={onDecrypt}
                 isDecrypting={isDecrypting}
                 selectedSpan={selectedSpan}
+                showSeparateEventOccurrenceTimestamps={
+                  showSeparateEventOccurrenceTimestamps
+                }
               />
             </ErrorBoundary>
           </div>

package/src/components/workflow-traces/trace-span-construction.test.ts

@@ -0,0 +1,85 @@
+import type { Event, WorkflowRun } from '@workflow/world';
+import { describe, expect, it } from 'vitest';
+import { runToSpan } from './trace-span-construction';
+import { otelTimeToMs } from './trace-time-utils';
+
+const date = (ms: number) => new Date(ms);
+
+function run(overrides: Partial<WorkflowRun> = {}): WorkflowRun {
+  return {
+    runId: 'run_1',
+    status: 'completed',
+    deploymentId: 'dpl_1',
+    workflowName: 'workflow//./workflow//testWorkflow',
+    specVersion: 2,
+    attributes: {},
+    createdAt: date(1_000),
+    updatedAt: date(6_000),
+    startedAt: date(2_000),
+    completedAt: date(6_000),
+    output: null,
+    ...overrides,
+  } as WorkflowRun;
+}
+
+function event(overrides: Partial<Event>): Event {
+  return {
+    runId: 'run_1',
+    eventId: `evt_${overrides.eventType ?? 'unknown'}`,
+    eventType: 'run_created',
+    createdAt: date(1_000),
+    specVersion: 2,
+    eventData: {
+      deploymentId: 'dpl_1',
+      workflowName: 'workflow//./workflow//testWorkflow',
+      input: null,
+    },
+    ...overrides,
+  } as Event;
+}
+
+describe('runToSpan', () => {
+  it('prefers occurredAt for run span timing when available', () => {
+    const span = runToSpan(
+      run(),
+      [
+        event({
+          eventType: 'run_created',
+          createdAt: date(1_000),
+          occurredAt: date(100),
+        }),
+        event({
+          eventType: 'run_started',
+          createdAt: date(2_000),
+          occurredAt: date(200),
+        }),
+        event({
+          eventType: 'run_completed',
+          createdAt: date(6_000),
+          occurredAt: date(500),
+        }),
+      ],
+      date(10_000)
+    );
+
+    expect(otelTimeToMs(span.startTime)).toBe(100);
+    expect(
+      span.activeStartTime ? otelTimeToMs(span.activeStartTime) : undefined
+    ).toBe(200);
+    expect(otelTimeToMs(span.endTime)).toBe(500);
+    expect(
+      span.events.find((e) => e.name === 'run_created')?.timestamp
+    ).toEqual([0, 100_000_000]);
+
+    const data = span.attributes.data as {
+      createdAt: Date;
+      startedAt?: Date;
+      completedAt?: Date;
+      occurredAt?: Date;
+    };
+    expect(data.createdAt).toEqual(date(100));
+    expect(data.startedAt).toEqual(date(200));
+    expect(data.completedAt).toEqual(date(500));
+    expect(data).not.toHaveProperty('occurredAt');
+  });
+});

package/src/components/workflow-traces/trace-span-construction.ts

@@ -29,13 +29,24 @@ const MARKER_EVENT_TYPES: Set<Event['eventType']> = new Set([
   'attr_set',
 ]);
 
+export const getEventTimestamp = (
+  event: Event | undefined
+): Date | undefined => {
+  const value = event?.occurredAt ?? event?.createdAt;
+  if (!value) return undefined;
+
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+};
+
 /**
  * Convert workflow events to span events
  * Only includes events that should be displayed as markers
  */
 export function convertEventsToSpanEvents(
   events: Event[],
-  filterTypes = true
+  filterTypes = true,
+  options: { preferOccurredAt?: boolean } = {}
 ): SpanEvent[] {
   return events
     .filter((event) =>
@@ -43,7 +54,11 @@ export function convertEventsToSpanEvents(
     )
     .map((event) => ({
       name: event.eventType,
-      timestamp: dateToOtelTime(event.createdAt),
+      timestamp: dateToOtelTime(
+        options.preferOccurredAt
+          ? (getEventTimestamp(event) ?? event.createdAt)
+          : event.createdAt
+      ),
       attributes: {
         eventId: event.eventId,
         correlationId: event.correlationId,
@@ -73,11 +88,11 @@ export const waitEventsToWaitEntity = (
   return {
     waitId: startEvent.correlationId,
     runId: startEvent.runId,
-    createdAt: startEvent.createdAt,
+    createdAt: getEventTimestamp(startEvent) ?? startEvent.createdAt,
     resumeAt: startEvent.eventData?.resumeAt
       ? new Date(startEvent.eventData.resumeAt)
       : undefined,
-    completedAt: completedEvent?.createdAt,
+    completedAt: getEventTimestamp(completedEvent),
   };
 };
 
@@ -169,16 +184,16 @@ export const stepEventsToStepEntity = (
       case 'step_started':
         status = 'running';
         attempt += 1;
-        if (!startedAt) startedAt = e.createdAt;
+        if (!startedAt) startedAt = getEventTimestamp(e) ?? e.createdAt;
         completedAt = undefined;
         break;
       case 'step_completed':
         status = 'completed';
-        completedAt = e.createdAt;
+        completedAt = getEventTimestamp(e) ?? e.createdAt;
         break;
       case 'step_failed':
         status = 'failed';
-        completedAt = e.createdAt;
+        completedAt = getEventTimestamp(e) ?? e.createdAt;
         break;
       case 'step_retrying':
         status = 'pending';
@@ -191,14 +206,18 @@ export const stepEventsToStepEntity = (
   if (attempt === 0) attempt = 1;
 
   const lastEvent = events[events.length - 1];
+
   return {
     stepId: anchorEvent.correlationId ?? '',
     runId: anchorEvent.runId,
     stepName: createdEvent?.eventData?.stepName ?? '',
     status,
     attempt,
-    createdAt: anchorEvent.createdAt,
-    updatedAt: lastEvent?.createdAt ?? anchorEvent.createdAt,
+    createdAt: getEventTimestamp(anchorEvent) ?? anchorEvent.createdAt,
+    updatedAt:
+      getEventTimestamp(lastEvent) ??
+      lastEvent?.createdAt ??
+      anchorEvent.createdAt,
     startedAt,
     completedAt,
     specVersion: anchorEvent.specVersion,
@@ -221,25 +240,41 @@ export function stepToSpan(stepEvents: Event[], maxEndTime: Date): Span | null {
   };
 
   const resource = 'step';
-  const endTime = new Date(step.completedAt ?? maxEndTime);
 
   // Include ALL correlated events on the span so the sidebar detail view
   // can display them. The timeline uses the `showVerticalLine` flag to
   // determine which events appear as markers.
-  const events = convertEventsToSpanEvents(stepEvents, false);
+  const events = convertEventsToSpanEvents(stepEvents, false, {
+    preferOccurredAt: true,
+  });
 
-  // Use createdAt as span start time, with activeStartTime for when execution began
-  // This allows visualization of the "queued" period before execution
-  const spanStartTime = new Date(step.createdAt);
+  // Use the event occurrence timestamp for step spans when it is available,
+  // falling back to the ingest timestamp used by older event streams.
+  const spanStartEvent =
+    stepEvents.find((event) => event.eventType === 'step_created') ??
+    stepEvents[0];
+  const spanStartTime =
+    getEventTimestamp(spanStartEvent) ?? new Date(step.createdAt);
   let activeStartTime = step.startedAt ? new Date(step.startedAt) : undefined;
   const firstStartEvent = stepEvents.find(
     (event) => event.eventType === 'step_started'
   );
   if (firstStartEvent) {
-    // `step.startedAt` is the server-side creation timestamp, and `event.createdAt` is
-    // the client-side creation timestamp. For now, to align the event marker with the
-    // line we show for step.startedAt, we overwrite here to always use client-side time.
-    activeStartTime = new Date(firstStartEvent.createdAt);
+    activeStartTime =
+      getEventTimestamp(firstStartEvent) ?? new Date(firstStartEvent.createdAt);
+  }
+
+  let endTime = new Date(maxEndTime);
+  if (step.completedAt) {
+    const completedEvent = stepEvents
+      .slice()
+      .reverse()
+      .find(
+        (event) =>
+          event.eventType === 'step_completed' ||
+          event.eventType === 'step_failed'
+      );
+    endTime = getEventTimestamp(completedEvent) ?? new Date(step.completedAt);
   }
 
   return {
@@ -292,10 +327,10 @@ export const hookEventsToHookEntity = (
     hookId: createdEvent.correlationId,
     runId: createdEvent.runId,
     token: createdEvent.eventData?.token,
-    createdAt: createdEvent.createdAt,
+    createdAt: getEventTimestamp(createdEvent) ?? createdEvent.createdAt,
     receivedCount: receivedEvents.length,
-    lastReceivedAt: lastReceivedEvent?.createdAt || undefined,
-    disposedAt: disposedEvents.at(-1)?.createdAt || undefined,
+    lastReceivedAt: getEventTimestamp(lastReceivedEvent),
+    disposedAt: getEventTimestamp(disposedEvents.at(-1)),
   };
 };
 
@@ -343,21 +378,50 @@ export function runToSpan(
 ): Span {
   const now = nowTime ?? new Date();
 
+  // Prefer the event occurrence timestamp when available so the root span
+  // lines up with child spans that already use event occurrence time.
+  const runCreatedEvent = runEvents.find(
+    (event) => event.eventType === 'run_created'
+  );
+  const runStartedEvent = runEvents.find(
+    (event) => event.eventType === 'run_started'
+  );
+  const terminalEvent = runEvents
+    .slice()
+    .reverse()
+    .find(
+      (event) =>
+        event.eventType === 'run_completed' ||
+        event.eventType === 'run_failed' ||
+        event.eventType === 'run_cancelled'
+    );
+  const spanStartTime =
+    getEventTimestamp(runCreatedEvent) ?? new Date(run.createdAt);
+  const activeStartTime =
+    getEventTimestamp(runStartedEvent) ??
+    (run.startedAt ? new Date(run.startedAt) : undefined);
+  const completedAt =
+    getEventTimestamp(terminalEvent) ?? run.completedAt ?? undefined;
+  const endTime = completedAt ?? now;
+
   // Only embed identification fields — not the full object with
-  // input/output/error which may contain non-cloneable types.
+  // input/output/error which may contain non-cloneable types. Lifecycle
+  // timestamps are event-derived so detail rows align with the span timeline.
   const { input: _i, output: _o, error: _e, ...runIdentity } = run;
   const attributes = {
     resource: 'run' as const,
-    data: runIdentity,
+    data: {
+      ...runIdentity,
+      createdAt: spanStartTime,
+      startedAt: activeStartTime,
+      completedAt,
+    },
   };
 
-  // Use createdAt as span start time, with activeStartTime for when execution began
-  const spanStartTime = new Date(run.createdAt);
-  const activeStartTime = run.startedAt ? new Date(run.startedAt) : undefined;
-  const endTime = run.completedAt ?? now;
-
   // Convert run-level events to span events
-  const events = convertEventsToSpanEvents(runEvents, false);
+  const events = convertEventsToSpanEvents(runEvents, false, {
+    preferOccurredAt: true,
+  });
 
   return {
     spanId: String(run.runId),

package/src/lib/cn.ts

@@ -0,0 +1,93 @@
+import { type ClassValue, clsx } from 'clsx';
+import { extendTailwindMerge } from 'tailwind-merge';
+
+const twMergeConfig = {
+  extend: {
+    classGroups: {
+      'text-heading': [
+        {
+          'text-heading': [
+            '72',
+            '64',
+            '56',
+            '48',
+            '40',
+            '32',
+            '24',
+            '20',
+            '16',
+            '14',
+          ],
+        },
+      ],
+      'text-button': [
+        {
+          'text-button': ['16', '14', '12'],
+        },
+      ],
+      'text-label': [
+        {
+          'text-label': [
+            '20',
+            '18',
+            '16',
+            '14',
+            '14-mono',
+            '13',
+            '13-mono',
+            '12',
+            '12-mono',
+          ],
+        },
+      ],
+      'text-copy': [
+        {
+          'text-copy': ['24', '20', '18', '16', '14', '13', '13-mono'],
+        },
+      ],
+      material: [
+        {
+          material: [
+            'base',
+            'small',
+            'medium',
+            'large',
+            'tooltip',
+            'menu',
+            'modal',
+            'fullscreen',
+          ],
+        },
+      ],
+    },
+    // Make each category conflict with itself, so e.g. text-heading-32 overrides text-heading-24
+    conflictingClassGroups: {
+      'text-heading': ['text-heading'],
+      'text-button': ['text-button'],
+      'text-label': ['text-label'],
+      'text-copy': ['text-copy'],
+      material: ['material'],
+    },
+  },
+} as const;
+
+type CustomClassGroupIds =
+  | 'text-heading'
+  | 'text-button'
+  | 'text-label'
+  | 'text-copy'
+  | 'material';
+
+const customTwMerge = extendTailwindMerge<CustomClassGroupIds>(twMergeConfig);
+
+/**
+ * Merges Tailwind class names and resolves any conflicts using `clsx` with `tailwind-merge`.
+ *
+ * @param inputs - An array of class names to merge.
+ * @returns A string of merged and optimized class names.
+ */
+function cn(...classes: ClassValue[]) {
+  return customTwMerge(clsx(...classes));
+}
+
+export { cn };

package/src/lib/event-materialization.ts

@@ -82,6 +82,14 @@ function groupByCorrelationId(
   return groups;
 }
 
+function getEventTimestamp(event: Event | undefined): Date | undefined {
+  const value = event?.occurredAt ?? event?.createdAt;
+  if (!value) return undefined;
+
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
 // ---------------------------------------------------------------------------
 // materializeSteps
 // ---------------------------------------------------------------------------
@@ -104,31 +112,31 @@ export function materializeSteps(events: Event[]): MaterializedStep[] {
     let attempt = 0;
     let startedAt: Date | undefined;
     let completedAt: Date | undefined;
-    let updatedAt = created.createdAt;
+    let updatedAt = getEventTimestamp(created) ?? created.createdAt;
 
     for (const e of stepEvents) {
       switch (e.eventType) {
         case 'step_started':
           status = 'running';
           attempt += 1;
-          if (!startedAt) startedAt = e.createdAt;
+          if (!startedAt) startedAt = getEventTimestamp(e) ?? e.createdAt;
           completedAt = undefined;
-          updatedAt = e.createdAt;
+          updatedAt = getEventTimestamp(e) ?? e.createdAt;
           break;
         case 'step_completed':
           status = 'completed';
-          completedAt = e.createdAt;
-          updatedAt = e.createdAt;
+          completedAt = getEventTimestamp(e) ?? e.createdAt;
+          updatedAt = getEventTimestamp(e) ?? e.createdAt;
           break;
         case 'step_failed':
           status = 'failed';
-          completedAt = e.createdAt;
-          updatedAt = e.createdAt;
+          completedAt = getEventTimestamp(e) ?? e.createdAt;
+          updatedAt = getEventTimestamp(e) ?? e.createdAt;
           break;
         case 'step_retrying':
           status = 'pending';
           completedAt = undefined;
-          updatedAt = e.createdAt;
+          updatedAt = getEventTimestamp(e) ?? e.createdAt;
           break;
       }
     }
@@ -142,7 +150,7 @@ export function materializeSteps(events: Event[]): MaterializedStep[] {
           : correlationId,
       status,
       attempt,
-      createdAt: created.createdAt,
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
       startedAt,
       completedAt,
       updatedAt,
@@ -181,10 +189,10 @@ export function materializeHooks(events: Event[]): MaterializedHook[] {
         created.eventType === 'hook_created'
           ? created.eventData?.token
           : undefined,
-      createdAt: created.createdAt,
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
       receivedCount: receivedEvents.length,
-      lastReceivedAt: lastReceived?.createdAt,
-      disposedAt: disposed?.createdAt,
+      lastReceivedAt: getEventTimestamp(lastReceived),
+      disposedAt: getEventTimestamp(disposed),
       events: hookEvents,
     });
   }
@@ -213,12 +221,12 @@ export function materializeWaits(events: Event[]): MaterializedWait[] {
       waitId: correlationId,
       runId: created.runId,
       status: completed ? 'completed' : 'waiting',
-      createdAt: created.createdAt,
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
       resumeAt:
         created.eventType === 'wait_created'
           ? created.eventData?.resumeAt
           : undefined,
-      completedAt: completed?.createdAt,
+      completedAt: getEventTimestamp(completed),
       events: waitEvents,
     });
   }

package/src/lib/trace-builder.ts

@@ -9,6 +9,7 @@
 import type { Event, WorkflowRun } from '@workflow/world';
 import type { Span } from '../components/trace-viewer/types';
 import {
+  getEventTimestamp,
   hookToSpan,
   runToSpan,
   stepToSpan,
@@ -132,7 +133,7 @@ export function groupEventsByCorrelation(events: Event[]): GroupedEvents {
 function computeLatestKnownTime(events: Event[], run: WorkflowRun): Date {
   let latest = new Date(run.createdAt).getTime();
   for (const event of events) {
-    const t = new Date(event.createdAt).getTime();
+    const t = (getEventTimestamp(event) ?? new Date(event.createdAt)).getTime();
     if (t > latest) latest = t;
   }
   return new Date(latest);

package/src/lib/utils.ts

@@ -1,11 +1,5 @@
 import type { Step } from '@workflow/world';
 import type { ModelMessage } from 'ai';
-import { type ClassValue, clsx } from 'clsx';
-import { twMerge } from 'tailwind-merge';
-
-export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs));
-}
 
 const MS_IN_SECOND = 1000;
 const MS_IN_MINUTE = 60 * MS_IN_SECOND;