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

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

@@ -29,25 +29,14 @@ const MARKER_EVENT_TYPES: Set<Event['eventType']> = new Set([
   'attr_set',
 ]);
 
-const findEventByType = (
-  events: Event[],
-  eventTypes: Event['eventType'][]
-): Event | undefined => {
-  for (const eventType of eventTypes) {
-    const event = events.find((e) => e.eventType === eventType);
-    if (event) return event;
-  }
-  return undefined;
-};
+export const getEventTimestamp = (
+  event: Event | undefined
+): Date | undefined => {
+  const value = event?.occurredAt ?? event?.createdAt;
+  if (!value) return undefined;
 
-const withOccurredAt = <T extends object>(
-  entity: T,
-  occurredAt: Event['occurredAt'] | undefined
-): T & { occurredAt?: Date } => {
-  if (!occurredAt || (entity as { occurredAt?: unknown }).occurredAt != null) {
-    return entity;
-  }
-  return { ...entity, occurredAt };
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
 };
 
 /**
@@ -56,7 +45,8 @@ const withOccurredAt = <T extends object>(
  */
 export function convertEventsToSpanEvents(
   events: Event[],
-  filterTypes = true
+  filterTypes = true,
+  options: { preferOccurredAt?: boolean } = {}
 ): SpanEvent[] {
   return events
     .filter((event) =>
@@ -64,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,
@@ -81,7 +75,6 @@ export const waitEventsToWaitEntity = (
   waitId: string;
   runId: string;
   createdAt: Date;
-  occurredAt?: Date;
   resumeAt?: Date;
   completedAt?: Date;
 } | null => {
@@ -92,18 +85,15 @@ export const waitEventsToWaitEntity = (
   const completedEvent = events.find(
     (event) => event.eventType === 'wait_completed'
   );
-  return withOccurredAt(
-    {
-      waitId: startEvent.correlationId,
-      runId: startEvent.runId,
-      createdAt: startEvent.createdAt,
-      resumeAt: startEvent.eventData?.resumeAt
-        ? new Date(startEvent.eventData.resumeAt)
-        : undefined,
-      completedAt: completedEvent?.createdAt,
-    },
-    startEvent.occurredAt
-  );
+  return {
+    waitId: startEvent.correlationId,
+    runId: startEvent.runId,
+    createdAt: getEventTimestamp(startEvent) ?? startEvent.createdAt,
+    resumeAt: startEvent.eventData?.resumeAt
+      ? new Date(startEvent.eventData.resumeAt)
+      : undefined,
+    completedAt: getEventTimestamp(completedEvent),
+  };
 };
 
 /**
@@ -166,7 +156,6 @@ export const stepEventsToStepEntity = (
   attempt: number;
   createdAt: Date;
   updatedAt: Date;
-  occurredAt?: Date;
   startedAt?: Date;
   completedAt?: Date;
   specVersion?: number;
@@ -195,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';
@@ -217,24 +206,22 @@ export const stepEventsToStepEntity = (
   if (attempt === 0) attempt = 1;
 
   const lastEvent = events[events.length - 1];
-  const occurrenceEvent =
-    findEventByType(events, ['step_created', 'step_started']) ?? anchorEvent;
-
-  return withOccurredAt(
-    {
-      stepId: anchorEvent.correlationId ?? '',
-      runId: anchorEvent.runId,
-      stepName: createdEvent?.eventData?.stepName ?? '',
-      status,
-      attempt,
-      createdAt: anchorEvent.createdAt,
-      updatedAt: lastEvent?.createdAt ?? anchorEvent.createdAt,
-      startedAt,
-      completedAt,
-      specVersion: anchorEvent.specVersion,
-    },
-    occurrenceEvent.occurredAt
-  );
+
+  return {
+    stepId: anchorEvent.correlationId ?? '',
+    runId: anchorEvent.runId,
+    stepName: createdEvent?.eventData?.stepName ?? '',
+    status,
+    attempt,
+    createdAt: getEventTimestamp(anchorEvent) ?? anchorEvent.createdAt,
+    updatedAt:
+      getEventTimestamp(lastEvent) ??
+      lastEvent?.createdAt ??
+      anchorEvent.createdAt,
+    startedAt,
+    completedAt,
+    specVersion: anchorEvent.specVersion,
+  };
 };
 
 /**
@@ -253,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 {
@@ -303,7 +306,6 @@ export const hookEventsToHookEntity = (
   runId: string;
   token?: string;
   createdAt: Date;
-  occurredAt?: Date;
   receivedCount: number;
   lastReceivedAt?: Date;
   disposedAt?: Date;
@@ -321,18 +323,15 @@ export const hookEventsToHookEntity = (
     (event) => event.eventType === 'hook_disposed'
   );
   const lastReceivedEvent = receivedEvents.at(-1);
-  return withOccurredAt(
-    {
-      hookId: createdEvent.correlationId,
-      runId: createdEvent.runId,
-      token: createdEvent.eventData?.token,
-      createdAt: createdEvent.createdAt,
-      receivedCount: receivedEvents.length,
-      lastReceivedAt: lastReceivedEvent?.createdAt || undefined,
-      disposedAt: disposedEvents.at(-1)?.createdAt || undefined,
-    },
-    createdEvent.occurredAt
-  );
+  return {
+    hookId: createdEvent.correlationId,
+    runId: createdEvent.runId,
+    token: createdEvent.eventData?.token,
+    createdAt: getEventTimestamp(createdEvent) ?? createdEvent.createdAt,
+    receivedCount: receivedEvents.length,
+    lastReceivedAt: getEventTimestamp(lastReceivedEvent),
+    disposedAt: getEventTimestamp(disposedEvents.at(-1)),
+  };
 };
 
 /**
@@ -379,25 +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 occurrenceEvent = findEventByType(runEvents, [
-    'run_created',
-    'run_started',
-  ]);
   const attributes = {
     resource: 'run' as const,
-    data: withOccurredAt(runIdentity, occurrenceEvent?.occurredAt),
+    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

@@ -23,7 +23,6 @@ export interface MaterializedStep {
   status: StepStatus;
   attempt: number;
   createdAt: Date;
-  occurredAt?: Date;
   startedAt?: Date;
   completedAt?: Date;
   updatedAt: Date;
@@ -36,7 +35,6 @@ export interface MaterializedHook {
   runId: string;
   token?: string;
   createdAt: Date;
-  occurredAt?: Date;
   receivedCount: number;
   lastReceivedAt?: Date;
   disposedAt?: Date;
@@ -49,7 +47,6 @@ export interface MaterializedWait {
   runId: string;
   status: 'waiting' | 'completed';
   createdAt: Date;
-  occurredAt?: Date;
   resumeAt?: Date;
   completedAt?: Date;
   /** All events for this wait, in insertion order */
@@ -62,16 +59,6 @@ export interface MaterializedEntities {
   waits: MaterializedWait[];
 }
 
-const withOccurredAt = <T extends object>(
-  entity: T,
-  occurredAt: Event['occurredAt'] | undefined
-): T & { occurredAt?: Date } => {
-  if (!occurredAt || (entity as { occurredAt?: unknown }).occurredAt != null) {
-    return entity;
-  }
-  return { ...entity, occurredAt };
-};
-
 // ---------------------------------------------------------------------------
 // Helper: group events by correlationId prefix
 // ---------------------------------------------------------------------------
@@ -95,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
 // ---------------------------------------------------------------------------
@@ -117,55 +112,50 @@ 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;
       }
     }
 
-    steps.push(
-      withOccurredAt(
-        {
-          stepId: correlationId,
-          runId: created.runId,
-          stepName:
-            created.eventType === 'step_created'
-              ? (created.eventData?.stepName ?? correlationId)
-              : correlationId,
-          status,
-          attempt,
-          createdAt: created.createdAt,
-          startedAt,
-          completedAt,
-          updatedAt,
-          events: stepEvents,
-        },
-        created.occurredAt
-      )
-    );
+    steps.push({
+      stepId: correlationId,
+      runId: created.runId,
+      stepName:
+        created.eventType === 'step_created'
+          ? (created.eventData?.stepName ?? correlationId)
+          : correlationId,
+      status,
+      attempt,
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
+      startedAt,
+      completedAt,
+      updatedAt,
+      events: stepEvents,
+    });
   }
 
   return steps;
@@ -192,24 +182,19 @@ export function materializeHooks(events: Event[]): MaterializedHook[] {
     const disposed = hookEvents.find((e) => e.eventType === 'hook_disposed');
     const lastReceived = receivedEvents.at(-1);
 
-    hooks.push(
-      withOccurredAt(
-        {
-          hookId: correlationId,
-          runId: created.runId,
-          token:
-            created.eventType === 'hook_created'
-              ? created.eventData?.token
-              : undefined,
-          createdAt: created.createdAt,
-          receivedCount: receivedEvents.length,
-          lastReceivedAt: lastReceived?.createdAt,
-          disposedAt: disposed?.createdAt,
-          events: hookEvents,
-        },
-        created.occurredAt
-      )
-    );
+    hooks.push({
+      hookId: correlationId,
+      runId: created.runId,
+      token:
+        created.eventType === 'hook_created'
+          ? created.eventData?.token
+          : undefined,
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
+      receivedCount: receivedEvents.length,
+      lastReceivedAt: getEventTimestamp(lastReceived),
+      disposedAt: getEventTimestamp(disposed),
+      events: hookEvents,
+    });
   }
 
   return hooks;
@@ -232,23 +217,18 @@ export function materializeWaits(events: Event[]): MaterializedWait[] {
 
     const completed = waitEvents.find((e) => e.eventType === 'wait_completed');
 
-    waits.push(
-      withOccurredAt(
-        {
-          waitId: correlationId,
-          runId: created.runId,
-          status: completed ? 'completed' : 'waiting',
-          createdAt: created.createdAt,
-          resumeAt:
-            created.eventType === 'wait_created'
-              ? created.eventData?.resumeAt
-              : undefined,
-          completedAt: completed?.createdAt,
-          events: waitEvents,
-        },
-        created.occurredAt
-      )
-    );
+    waits.push({
+      waitId: correlationId,
+      runId: created.runId,
+      status: completed ? 'completed' : 'waiting',
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
+      resumeAt:
+        created.eventType === 'wait_created'
+          ? created.eventData?.resumeAt
+          : undefined,
+      completedAt: getEventTimestamp(completed),
+      events: waitEvents,
+    });
   }
 
   return waits;

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;