@workflow/web-shared 5.0.0-beta.4 → 5.0.0-beta.41

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

@@ -3,8 +3,12 @@
  */
 
 import { parseStepName, parseWorkflowName } from '@workflow/utils/parse-name';
-import type { Event, WorkflowRun } from '@workflow/world';
-import type { Span, SpanEvent } from '../trace-viewer/types';
+import {
+  type Event,
+  isTerminalStepEventType,
+  type WorkflowRun,
+} from '@workflow/world';
+import type { Span, SpanEvent } from '../../lib/trace-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,
@@ -72,11 +92,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),
   };
 };
 
@@ -168,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';
@@ -190,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,
@@ -220,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 {
@@ -291,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)),
   };
 };
 
@@ -314,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,
@@ -342,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

@@ -1,7 +1,4 @@
-export type {
-  HealthCheckEndpoint,
-  HealthCheckResult,
-} from '@workflow/core/runtime';
+export type { HealthCheckResult } from '@workflow/core/runtime';
 export {
   parseStepName,
   parseWorkflowName,
@@ -33,6 +30,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 +46,7 @@ export {
   getWebRevivers,
   hasEncryptedFields,
   hydrateResourceIO,
+  hydrateResourceIOAsync,
   hydrateResourceIOWithKey,
   isClassInstanceRef,
   isEncryptedMarker,
@@ -57,6 +62,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;
 }
 
 /**

package/src/lib/event-materialization.ts

@@ -10,7 +10,13 @@
  * of making separate API calls for each entity type.
  */
 
-import type { Event, StepStatus } from '@workflow/world';
+import {
+  type Event,
+  isHookLifecycleEventType,
+  isStepEventType,
+  isWaitEventType,
+  type StepStatus,
+} from '@workflow/world';
 
 // ---------------------------------------------------------------------------
 // Materialized entity types
@@ -60,18 +66,18 @@ export interface MaterializedEntities {
 }
 
 // ---------------------------------------------------------------------------
-// Helper: group events by correlationId prefix
+// Helper: group events by correlationId
 // ---------------------------------------------------------------------------
 
 function groupByCorrelationId(
   events: Event[],
-  prefixes: string[]
+  matchesEventType: (eventType: string) => boolean
 ): Map<string, Event[]> {
   const groups = new Map<string, Event[]>();
   for (const event of events) {
     const cid = event.correlationId;
     if (!cid) continue;
-    if (!prefixes.some((p) => cid.startsWith(p))) continue;
+    if (!matchesEventType(event.eventType)) continue;
     const existing = groups.get(cid);
     if (existing) {
       existing.push(event);
@@ -82,6 +88,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
 // ---------------------------------------------------------------------------
@@ -93,7 +107,7 @@ function groupByCorrelationId(
  * step_created event with no completion yet.
  */
 export function materializeSteps(events: Event[]): MaterializedStep[] {
-  const groups = groupByCorrelationId(events, ['step_']);
+  const groups = groupByCorrelationId(events, isStepEventType);
   const steps: MaterializedStep[] = [];
 
   for (const [correlationId, stepEvents] of groups) {
@@ -104,31 +118,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 +156,7 @@ export function materializeSteps(events: Event[]): MaterializedStep[] {
           : correlationId,
       status,
       attempt,
-      createdAt: created.createdAt,
+      createdAt: getEventTimestamp(created) ?? created.createdAt,
       startedAt,
       completedAt,
       updatedAt,
@@ -161,7 +175,7 @@ export function materializeSteps(events: Event[]): MaterializedStep[] {
  * Group hook_* events by correlationId and build Hook-like entities.
  */
 export function materializeHooks(events: Event[]): MaterializedHook[] {
-  const groups = groupByCorrelationId(events, ['hook_']);
+  const groups = groupByCorrelationId(events, isHookLifecycleEventType);
   const hooks: MaterializedHook[] = [];
 
   for (const [correlationId, hookEvents] of groups) {
@@ -181,10 +195,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,
     });
   }
@@ -200,7 +214,7 @@ export function materializeHooks(events: Event[]): MaterializedHook[] {
  * Group wait_* events by correlationId and build Wait-like entities.
  */
 export function materializeWaits(events: Event[]): MaterializedWait[] {
-  const groups = groupByCorrelationId(events, ['wait_']);
+  const groups = groupByCorrelationId(events, isWaitEventType);
   const waits: MaterializedWait[] = [];
 
   for (const [correlationId, waitEvents] of groups) {
@@ -213,12 +227,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,
     });
   }