@workflow/web-shared 5.0.0-beta.3 → 5.0.0-beta.30

package/src/components/workflow-traces/trace-colors.ts

@@ -2,7 +2,11 @@
  * Color utilities for workflow traces
  */
 
-import type { Step, WorkflowRun } from '@workflow/world';
+import {
+  isHookLifecycleEventType,
+  type Step,
+  type WorkflowRun,
+} from '@workflow/world';
 import styles from '../trace-viewer/trace-viewer.module.css';
 import type { SpanNode, SpanNodeEvent } from '../trace-viewer/types';
 
@@ -99,11 +103,7 @@ export const getCustomSpanEventClassName = (
   }
 
   // Webhook-related events - Purple
-  if (
-    eventName === 'hook_created' ||
-    eventName === 'hook_received' ||
-    eventName === 'hook_disposed'
-  ) {
+  if (isHookLifecycleEventType(eventName)) {
     return styles.eventHook;
   }
 

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

@@ -3,7 +3,11 @@
  */
 
 import { parseStepName, parseWorkflowName } from '@workflow/utils/parse-name';
-import type { Event, WorkflowRun } from '@workflow/world';
+import {
+  type Event,
+  isTerminalStepEventType,
+  type WorkflowRun,
+} from '@workflow/world';
 import type { Span, SpanEvent } from '../trace-viewer/types';
 import { shouldShowVerticalLine } from './event-colors';
 import { calculateDuration, dateToOtelTime } from './trace-time-utils';
@@ -26,15 +30,27 @@ const MARKER_EVENT_TYPES: Set<Event['eventType']> = new Set([
   'run_failed',
   'wait_created',
   'wait_completed',
+  '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) =>
@@ -42,7 +58,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,
@@ -59,7 +79,7 @@ export const waitEventsToWaitEntity = (
   waitId: string;
   runId: string;
   createdAt: Date;
-  resumeAt: Date;
+  resumeAt?: Date;
   completedAt?: Date;
 } | null => {
   const startEvent = events.find((event) => event.eventType === 'wait_created');
@@ -72,22 +92,40 @@ export const waitEventsToWaitEntity = (
   return {
     waitId: startEvent.correlationId,
     runId: startEvent.runId,
-    createdAt: startEvent.createdAt,
-    resumeAt: startEvent.eventData?.resumeAt,
-    completedAt: completedEvent?.createdAt,
+    createdAt: getEventTimestamp(startEvent) ?? startEvent.createdAt,
+    resumeAt: startEvent.eventData?.resumeAt
+      ? new Date(startEvent.eventData.resumeAt)
+      : undefined,
+    completedAt: getEventTimestamp(completedEvent),
   };
 };
 
 /**
  * Converts a workflow Wait to an OpenTelemetry Span
  */
-export function waitToSpan(events: Event[], maxEndTime: Date): Span | null {
+export function waitToSpan(
+  events: Event[],
+  maxEndTime: Date,
+  fallbackEndTime = maxEndTime
+): Span | null {
   const wait = waitEventsToWaitEntity(events);
   if (!wait) {
     return null;
   }
   const startTime = wait.createdAt;
-  const endTime = wait.completedAt ?? maxEndTime;
+  const startMs = startTime.getTime();
+  let endTime = wait.completedAt;
+  if (!endTime) {
+    const fallbackCap =
+      wait.resumeAt && wait.resumeAt.getTime() < fallbackEndTime.getTime()
+        ? wait.resumeAt
+        : fallbackEndTime;
+    endTime =
+      maxEndTime.getTime() > startMs &&
+      maxEndTime.getTime() < fallbackCap.getTime()
+        ? maxEndTime
+        : fallbackCap;
+  }
   const start = dateToOtelTime(startTime);
   const end = dateToOtelTime(endTime);
   const duration = calculateDuration(startTime, endTime);
@@ -150,16 +188,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';
@@ -172,14 +210,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,
@@ -202,25 +244,37 @@ 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) => isTerminalStepEventType(event.eventType));
+    endTime = getEventTimestamp(completedEvent) ?? new Date(step.completedAt);
   }
 
   return {
@@ -273,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)),
   };
 };
 
@@ -296,7 +350,7 @@ export function hookToSpan(hookEvents: Event[], maxEndTime: Date): Span | null {
 
   return {
     spanId: String(hook.hookId),
-    name: String(hook.hookId),
+    name: hook.token ?? String(hook.hookId),
     kind: 1, // INTERNAL span kind
     resource: 'hook',
     library: WORKFLOW_LIBRARY,
@@ -324,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/hooks/use-intersection-observer.ts

@@ -0,0 +1,57 @@
+'use client';
+
+import type { RefObject } from 'react';
+import { useEffect, useState } from 'react';
+
+interface UseIntersectionObserverArgs
+  extends Omit<IntersectionObserverInit, 'root'> {
+  /**
+   * Scroll container the target is observed within. Defaults to the viewport.
+   * Passed as a ref so it resolves after commit (when the node exists).
+   */
+  rootRef?: RefObject<Element | null>;
+  freezeOnceVisible?: boolean;
+}
+
+/**
+ * Returns the latest IntersectionObserverEntry for `elementRef`.
+ * Ported from vercel/front's `@vercel/hooks` `useIntersectionObserver`, with
+ * `root` threaded as a ref so we can observe inside a custom scroll container.
+ */
+export function useIntersectionObserver(
+  elementRef: RefObject<Element | null>,
+  {
+    threshold = 0,
+    rootRef,
+    rootMargin = '0%',
+    freezeOnceVisible = false,
+  }: UseIntersectionObserverArgs = {}
+): IntersectionObserverEntry | undefined {
+  const [entry, setEntry] = useState<IntersectionObserverEntry>();
+
+  const frozen = entry?.isIntersecting && freezeOnceVisible;
+
+  useEffect(() => {
+    const node = elementRef?.current;
+
+    const hasIOSupport = !!window.IntersectionObserver;
+
+    if (!hasIOSupport || frozen || !node) return;
+
+    const updateEntry = ([entry]: IntersectionObserverEntry[]): void => {
+      setEntry(entry);
+    };
+
+    const observer = new IntersectionObserver(updateEntry, {
+      threshold,
+      root: rootRef?.current ?? null,
+      rootMargin,
+    });
+
+    observer.observe(node);
+
+    return () => observer.disconnect();
+  }, [elementRef, threshold, rootRef, rootMargin, frozen]);
+
+  return entry;
+}

package/src/hooks/use-load-more-on-scroll.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import type { RefObject } from 'react';
+import { useEffect, useRef } from 'react';
+import { useIntersectionObserver } from './use-intersection-observer';
+
+interface UseLoadMoreOnScrollOptions {
+  hasMore: boolean;
+  isLoadingMore: boolean;
+  /** Scroll container the sentinel lives in. Defaults to the viewport. */
+  rootRef?: RefObject<Element | null>;
+  rootMargin?: string;
+}
+
+/**
+ * Triggers `loadMore` when a sentinel element scrolls into view.
+ * Returns a ref to attach to an invisible sentinel `<div>` placed after the
+ * list content. Ported from vercel/front's `@vercel/hooks`
+ * `useLoadMoreOnScroll`.
+ *
+ * Because it keys off `isIntersecting`/`isLoadingMore`, it self-continues:
+ * if the sentinel is still in view once a page finishes loading, the next
+ * page is requested automatically.
+ */
+export function useLoadMoreOnScroll(
+  loadMore: () => void,
+  {
+    hasMore,
+    isLoadingMore,
+    rootRef,
+    rootMargin = '400px',
+  }: UseLoadMoreOnScrollOptions
+) {
+  const sentinelRef = useRef<HTMLDivElement>(null);
+  const entry = useIntersectionObserver(sentinelRef, { rootRef, rootMargin });
+
+  const loadMoreRef = useRef(loadMore);
+  useEffect(() => {
+    loadMoreRef.current = loadMore;
+  }, [loadMore]);
+
+  useEffect(() => {
+    if (entry?.isIntersecting && hasMore && !isLoadingMore) {
+      loadMoreRef.current();
+    }
+  }, [entry?.isIntersecting, hasMore, isLoadingMore]);
+
+  return sentinelRef;
+}

package/src/hooks/use-reduced-motion.ts

@@ -0,0 +1,34 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+const QUERY = '(prefers-reduced-motion: reduce)';
+
+/**
+ * Hook that detects whether the user has requested reduced motion and reacts
+ * to changes. Mirrors the `prefers-reduced-motion: reduce` media query so
+ * components can skip or shorten animations for users with motion
+ * sensitivities (e.g. vestibular disorders).
+ *
+ * @returns `true` if the user prefers reduced motion, `false` otherwise
+ */
+export const useReducedMotion = (): boolean => {
+  const [reduced, setReduced] = useState(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return false;
+    return window.matchMedia(QUERY).matches;
+  });
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+
+    const media = window.matchMedia(QUERY);
+    const onChange = (): void => setReduced(media.matches);
+
+    media.addEventListener('change', onChange);
+    onChange();
+
+    return () => media.removeEventListener('change', onChange);
+  }, []);
+
+  return reduced;
+};

package/src/index.ts

@@ -33,6 +33,13 @@ export {
   materializeSteps,
   materializeWaits,
 } from './lib/event-materialization';
+export {
+  type ExactIdSearchResult,
+  type ExactWorkflowSearchId,
+  type ExactWorkflowSearchIdKind,
+  looksLikeWorkflowIdSearchInput,
+  parseExactWorkflowSearchId,
+} from './lib/exact-event-search-id';
 export type { Revivers, StreamRef } from './lib/hydration';
 export {
   CLASS_INSTANCE_REF_TYPE,
@@ -42,6 +49,7 @@ export {
   getWebRevivers,
   hasEncryptedFields,
   hydrateResourceIO,
+  hydrateResourceIOAsync,
   hydrateResourceIOWithKey,
   isClassInstanceRef,
   isEncryptedMarker,
@@ -57,6 +65,7 @@ export type { StreamStep } from './lib/utils';
 export {
   extractConversation,
   formatDuration,
+  formatDurationPrecise,
   identifyStreamSteps,
   isDoStreamStep,
 } from './lib/utils';

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-analysis.ts

@@ -3,7 +3,11 @@
  * Used by run-actions and trace viewer components.
  */
 
-import type { Event, WorkflowRunStatus } from '@workflow/world';
+import {
+  type Event,
+  isTerminalWorkflowRunStatus,
+  type WorkflowRunStatus,
+} from '@workflow/world';
 
 // Time thresholds for Re-enqueue button visibility
 const STEP_ACTIVITY_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
@@ -140,9 +144,7 @@ export function analyzeEvents(events: Event[] | undefined): EventAnalysis {
 export function isTerminalStatus(
   status: WorkflowRunStatus | undefined
 ): boolean {
-  return (
-    status === 'completed' || status === 'failed' || status === 'cancelled'
-  );
+  return status ? isTerminalWorkflowRunStatus(status) : false;
 }
 
 /**