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

package/src/components/sidebar/events-list.tsx

@@ -7,6 +7,7 @@ import { RunClickContext, StreamClickContext } from '../ui/data-inspector';
 import { ErrorCard } from '../ui/error-card';
 import { ErrorStackBlock, isStructuredError } from '../ui/error-stack-block';
 import { Skeleton } from '../ui/skeleton';
+import { TimestampTooltip } from '../ui/timestamp-tooltip';
 import { AttrSetEventBlock } from './attributes-block';
 import { CopyableDataBlock, EncryptedDataBlock } from './copyable-data-block';
 import { DetailCard } from './detail-card';
@@ -34,6 +35,28 @@ const DATA_EVENT_TYPES = new Set([
   'attr_set',
 ]);
 
+const parseDateValue = (value: unknown): Date | null => {
+  if (value == null) return null;
+
+  const date = value instanceof Date ? value : new Date(String(value));
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+
+const getEffectiveEventDate = (
+  event: Pick<Event, 'createdAt' | 'occurredAt'>
+): Date => parseDateValue(event.occurredAt) ?? new Date(event.createdAt);
+
+const formatEventTimestamp = (date: Date): string =>
+  date.toLocaleString(undefined, {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: 'numeric',
+    second: 'numeric',
+    fractionalSecondDigits: 3,
+    timeZoneName: 'short',
+  });
+
 /**
  * A single event row that can lazy-load its eventData when expanded.
  */
@@ -41,6 +64,7 @@ function EventItem({
   event,
   onLoadEventData,
   encryptionKey,
+  showSeparateEventOccurrenceTimestamps = false,
 }: {
   event: Event;
   onLoadEventData?: (
@@ -49,6 +73,8 @@ function EventItem({
   ) => Promise<unknown | null>;
   /** When this changes (e.g., Decrypt was clicked), invalidate cached data */
   encryptionKey?: Uint8Array;
+  /** Show occurredAt separately instead of folding it into the Created timestamp. */
+  showSeparateEventOccurrenceTimestamps?: boolean;
 }) {
   const [loadedData, setLoadedData] = useState<unknown | null>(null);
   const [isLoading, setIsLoading] = useState(false);
@@ -101,11 +127,18 @@ function EventItem({
   }, [encryptionKey, loadEventData]);
 
   const createdAt = new Date(event.createdAt);
-  const createdAtTime = createdAt.toLocaleTimeString(undefined, {
-    hour: 'numeric',
-    minute: 'numeric',
-    second: 'numeric',
-  });
+  const occurredAt = parseDateValue(event.occurredAt);
+  const displayedCreatedAt = showSeparateEventOccurrenceTimestamps
+    ? createdAt
+    : getEffectiveEventDate(event);
+  const displayedCreatedAtTime = displayedCreatedAt.toLocaleTimeString(
+    undefined,
+    {
+      hour: 'numeric',
+      minute: 'numeric',
+      second: 'numeric',
+    }
+  );
 
   const displayPayload = isLoading ? loadedData : mergedDisplay;
 
@@ -119,7 +152,7 @@ function EventItem({
             {event.eventType}
           </span>
           <span className="shrink-0 text-label-13 text-gray-900">
-            {createdAtTime}
+            {displayedCreatedAtTime}
           </span>
         </div>
       }
@@ -133,6 +166,16 @@ function EventItem({
     >
       {/* Event attributes */}
       <div className="flex flex-col bg-background-200 [&:has(+_*)]:border-b [&:has(+_*)]:border-gray-alpha-400">
+        {showSeparateEventOccurrenceTimestamps && occurredAt && (
+          <div className="flex items-center justify-between gap-2 py-2 px-3">
+            <span className="text-label-12 text-gray-900">Occurred</span>
+            <TimestampTooltip date={occurredAt}>
+              <span className="max-w-[70%] truncate text-right text-label-12 font-mono">
+                {formatEventTimestamp(occurredAt)}
+              </span>
+            </TimestampTooltip>
+          </div>
+        )}
         <div className="flex items-center justify-between gap-2 py-2 px-3">
           <span className="text-label-12 text-gray-900">Event ID</span>
           <span className="max-w-[70%] truncate text-right text-label-12 font-mono">
@@ -268,6 +311,7 @@ export function EventsList({
   onStreamClick,
   onRunClick,
   encryptionKey,
+  showSeparateEventOccurrenceTimestamps = false,
 }: {
   events: Event[];
   isLoading?: boolean;
@@ -280,13 +324,16 @@ export function EventsList({
   onRunClick?: (runId: string) => void;
   /** When provided, signals that decryption is active (triggers re-load of expanded events) */
   encryptionKey?: Uint8Array;
+  /** Show occurredAt separately instead of folding it into the Created timestamp. */
+  showSeparateEventOccurrenceTimestamps?: boolean;
 }) {
-  // Sort by createdAt
+  // Sort by the timestamp shown as Created by default.
   const sortedEvents = useMemo(
     () =>
       [...events].sort(
         (a, b) =>
-          new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime()
+          getEffectiveEventDate(a).getTime() -
+          getEffectiveEventDate(b).getTime()
       ),
     [events]
   );
@@ -321,6 +368,9 @@ export function EventsList({
                   event={event}
                   onLoadEventData={onLoadEventData}
                   encryptionKey={encryptionKey}
+                  showSeparateEventOccurrenceTimestamps={
+                    showSeparateEventOccurrenceTimestamps
+                  }
                 />
               ))}
             </div>

package/src/components/sidebar/sidebar-data-context.tsx

@@ -1,16 +1,13 @@
 'use client';
 
-import { createContext, useContext, type ReactNode } from 'react';
-import type { Event, Hook, Step, WorkflowRun } from '@workflow/world';
-import type { SpanSelectionInfo } from './entity-detail-panel';
+import type { Event, Hook, WorkflowRun } from '@workflow/world';
+import { createContext, type ReactNode, useContext } from 'react';
+import type { FetchSpanDetail } from './use-selected-span-detail';
 
 export interface SidebarDataContextValue {
   run: WorkflowRun;
   events: Event[];
-  spanDetailData: WorkflowRun | Step | Hook | Event | null;
-  spanDetailError?: Error | null;
-  spanDetailLoading?: boolean;
-  onSpanSelect: (info: SpanSelectionInfo) => void;
+  fetchSpanDetail: FetchSpanDetail;
   onStreamClick?: (streamId: string) => void;
   onRunClick?: (runId: string) => void;
   onWakeUpSleep?: (
@@ -30,6 +27,8 @@ export interface SidebarDataContextValue {
   onDecrypt?: () => void;
   isDecrypting?: boolean;
   hasEncryptedData?: boolean;
+  /** Show occurredAt separately instead of folding it into the Created timestamp. */
+  showSeparateEventOccurrenceTimestamps?: boolean;
 }
 
 const SidebarDataContext = createContext<SidebarDataContextValue | null>(null);

package/src/components/sidebar/span-detail-merge.ts

@@ -3,6 +3,75 @@ const hasField = (
   key: string
 ): value is Record<string, unknown> => key in value;
 
+const RESOURCES_WITH_FETCHED_DETAIL = new Set(['run', 'step', 'sleep']);
+
+export function resourceNeedsFetchedDetail(
+  resource: string | undefined
+): boolean {
+  return resource !== undefined && RESOURCES_WITH_FETCHED_DETAIL.has(resource);
+}
+
+export type SpanDetailStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+export interface SpanDetailView {
+  status: SpanDetailStatus;
+  displayData: Record<string, unknown>;
+  detail: unknown;
+  error: Error | undefined;
+}
+
+export function deriveSpanDetailView(args: {
+  resource: string | undefined;
+  resourceId: string | undefined;
+  inlineData: unknown;
+  fetchedDetail: unknown;
+  fetchedError: Error | null;
+}): SpanDetailView {
+  const { resource, resourceId, inlineData, fetchedDetail, fetchedError } =
+    args;
+
+  const matchedDetail = spanDetailMatchesSelection(
+    fetchedDetail,
+    resource,
+    resourceId
+  )
+    ? fetchedDetail
+    : null;
+  const displayData = mergeSpanDetail(inlineData, matchedDetail) as Record<
+    string,
+    unknown
+  >;
+
+  if (!resource || !resourceId) {
+    return { status: 'idle', displayData, detail: null, error: undefined };
+  }
+  if (fetchedError) {
+    return {
+      status: 'error',
+      displayData,
+      detail: matchedDetail,
+      error: fetchedError,
+    };
+  }
+  if (!resourceNeedsFetchedDetail(resource)) {
+    return {
+      status: 'ready',
+      displayData,
+      detail: matchedDetail,
+      error: undefined,
+    };
+  }
+  if (matchedDetail !== null) {
+    return {
+      status: 'ready',
+      displayData,
+      detail: matchedDetail,
+      error: undefined,
+    };
+  }
+  return { status: 'loading', displayData, detail: null, error: undefined };
+}
+
 /**
  * Returns true when the fetched `detail` belongs to the current selection.
  * The fetch lags selection, so it can briefly hold a previously selected span

package/src/components/sidebar/use-selected-span-detail.ts

@@ -0,0 +1,146 @@
+'use client';
+
+import type { Event, Hook, Step, WorkflowRun } from '@workflow/world';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type {
+  SelectedSpanInfo,
+  SpanSelectionInfo,
+} from './entity-detail-panel';
+import {
+  deriveSpanDetailView,
+  resourceNeedsFetchedDetail,
+  type SpanDetailStatus,
+} from './span-detail-merge';
+
+export type DetailResource = WorkflowRun | Step | Hook | Event;
+
+export type FetchSpanDetail = (
+  selection: SpanSelectionInfo
+) => Promise<DetailResource>;
+
+function deriveSpanSelection(
+  selectedSpan: SelectedSpanInfo | null
+): SpanSelectionInfo | null {
+  if (!selectedSpan) return null;
+  const { resource, data } = selectedSpan;
+
+  if (
+    resource === 'step' &&
+    data &&
+    typeof data === 'object' &&
+    'stepId' in data
+  ) {
+    const step = data as Step;
+    return { resource: 'step', resourceId: step.stepId, runId: step.runId };
+  }
+  if (
+    resource === 'run' &&
+    data &&
+    typeof data === 'object' &&
+    'runId' in data
+  ) {
+    return { resource: 'run', resourceId: (data as WorkflowRun).runId };
+  }
+  if (
+    resource === 'hook' &&
+    data &&
+    typeof data === 'object' &&
+    'hookId' in data
+  ) {
+    return { resource: 'hook', resourceId: (data as Hook).hookId };
+  }
+  if (resource === 'sleep') {
+    if (!selectedSpan.spanId) return null;
+    const waitData = data as { runId?: string } | undefined;
+    return {
+      resource: 'sleep',
+      resourceId: selectedSpan.spanId,
+      runId: waitData?.runId,
+    };
+  }
+  return null;
+}
+
+export interface SelectedSpanDetailResult {
+  status: SpanDetailStatus;
+  resource: SpanSelectionInfo['resource'] | undefined;
+  resourceId: string | undefined;
+  runId: string | undefined;
+  displayData: Record<string, unknown>;
+  detail: DetailResource | null;
+  error: Error | undefined;
+}
+
+export function useSelectedSpanDetail(
+  selectedSpan: SelectedSpanInfo | null,
+  fetchSpanDetail: FetchSpanDetail
+): SelectedSpanDetailResult {
+  const selection = useMemo(
+    () => deriveSpanSelection(selectedSpan),
+    [selectedSpan]
+  );
+  const resource = selection?.resource;
+  const resourceId = selection?.resourceId;
+  const runId = selection?.runId;
+  const selectionKey =
+    resource && resourceId ? `${resource}:${resourceId}` : null;
+  const needsFetch = resourceNeedsFetchedDetail(resource);
+
+  const [fetched, setFetched] = useState<{
+    detail: DetailResource | null;
+    error: Error | null;
+    errorKey: string | null;
+  }>({ detail: null, error: null, errorKey: null });
+
+  const tokenRef = useRef(0);
+  const selectionRef = useRef(selection);
+  selectionRef.current = selection;
+
+  useEffect(() => {
+    if (!selectionKey || !needsFetch) {
+      return;
+    }
+    const activeSelection = selectionRef.current;
+    if (!activeSelection) {
+      return;
+    }
+    const token = ++tokenRef.current;
+    fetchSpanDetail(activeSelection)
+      .then((detail) => {
+        if (tokenRef.current !== token) return;
+        setFetched({ detail, error: null, errorKey: null });
+      })
+      .catch((err: unknown) => {
+        if (tokenRef.current !== token) return;
+        setFetched({
+          detail: null,
+          error: err instanceof Error ? err : new Error(String(err)),
+          errorKey: selectionKey,
+        });
+      });
+  }, [selectionKey, runId, needsFetch, fetchSpanDetail]);
+
+  const scopedError = fetched.errorKey === selectionKey ? fetched.error : null;
+
+  const view = useMemo(
+    () =>
+      deriveSpanDetailView({
+        resource,
+        resourceId,
+        inlineData: selectedSpan?.data,
+        fetchedDetail: fetched.detail,
+        fetchedError: scopedError,
+      }),
+    [resource, resourceId, selectedSpan?.data, fetched.detail, scopedError]
+  );
+
+  return {
+    status: view.status,
+    resource,
+    resourceId,
+    runId,
+    displayData: view.displayData,
+    detail: view.detail as DetailResource | null,
+    error: view.error,
+  };
+}

package/src/components/ui/alert.tsx

@@ -1,7 +1,7 @@
 import { cva, type VariantProps } from 'class-variance-authority';
 import * as React from 'react';
 
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/cn';
 
 const alertVariants = cva(
   'relative w-full rounded-lg border p-4 [&>svg~*]:pl-7 [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4',

package/src/components/ui/button.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { cva, type VariantProps } from 'class-variance-authority';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/cn';
 
 const buttonVariants = cva(
   [

package/src/components/ui/card.tsx

@@ -2,7 +2,7 @@
 
 import * as React from 'react';
 
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/cn';
 
 const Card = React.forwardRef<
   HTMLDivElement,

package/src/components/ui/context-card.tsx

@@ -14,7 +14,7 @@ import {
 import { createPortal } from 'react-dom';
 import useMeasure from 'react-use-measure';
 import { useReducedMotion } from '../../hooks/use-reduced-motion';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/cn';
 
 const INACTIVE_TIMEOUT_MS = 250;
 const ENTER_DELAY_MS = 0;

package/src/components/ui/error-card.tsx

@@ -2,7 +2,7 @@
 
 import { AlertCircle, ChevronDown } from 'lucide-react';
 import { useState } from 'react';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/cn';
 
 interface ErrorCardProps {
   /** Title shown in the header */

package/src/components/ui/icon-button.tsx

@@ -1,6 +1,6 @@
 import { cva, type VariantProps } from 'class-variance-authority';
 import * as React from 'react';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/cn';
 
 const iconButtonVariants = cva(
   [

package/src/components/ui/kbd.tsx

@@ -1,6 +1,6 @@
 import { cva, type VariantProps } from 'class-variance-authority';
 import type { ComponentProps, ReactNode } from 'react';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/cn';
 
 const kbdVariants = cva(
   'inline-flex items-center justify-center rounded px-1 text-center font-sans',

package/src/components/ui/skeleton.tsx

@@ -1,4 +1,4 @@
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/cn';
 
 function Skeleton({
   className,

package/src/components/ui/tooltip.tsx

@@ -2,7 +2,7 @@
 
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 import * as React from 'react';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/cn';
 
 const TooltipProvider = TooltipPrimitive.Provider;
 

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');
+  });
+});