@workflow/web-shared 4.1.0-beta.50 → 4.1.0-beta.52

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

@@ -1,16 +1,19 @@
 'use client';
 
 import type { Event, Hook, Step, WorkflowRun } from '@workflow/world';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import { X } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { toast } from 'sonner';
 import { ErrorBoundary } from './error-boundary';
 import {
   EntityDetailPanel,
+  type SelectedSpanInfo,
   type SpanSelectionInfo,
 } from './sidebar/entity-detail-panel';
 import {
   TraceViewerContextProvider,
   TraceViewerTimeline,
+  useTraceViewer,
 } from './trace-viewer';
 import type { Span } from './trace-viewer/types';
 import { Skeleton } from './ui/skeleton';
@@ -28,6 +31,8 @@ import {
 import { otelTimeToMs } from './workflow-traces/trace-time-utils';
 
 const RE_RENDER_INTERVAL_MS = 2000;
+const DEFAULT_PANEL_WIDTH = 380;
+const MIN_PANEL_WIDTH = 240;
 
 type GroupedEvents = {
   eventsByStepId: Map<string, Event[]>;
@@ -184,6 +189,95 @@ const buildTrace = (
 /** Re-export SpanSelectionInfo for consumers */
 export type { SpanSelectionInfo };
 
+// ---------------------------------------------------------------------------
+// Bridge: reads selected span from trace viewer context and notifies parent
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge component that lives INSIDE the TraceViewerContextProvider and
+ * reads the selected span info, passing it up to the parent via callback.
+ * This allows the parent to render the detail panel OUTSIDE the context.
+ */
+function SelectionBridge({
+  onSelectionChange,
+}: {
+  onSelectionChange: (info: SelectedSpanInfo | null) => void;
+}) {
+  const { state } = useTraceViewer();
+  const { selected } = state;
+  const onSelectionChangeRef = useRef(onSelectionChange);
+  onSelectionChangeRef.current = onSelectionChange;
+
+  useEffect(() => {
+    if (selected) {
+      onSelectionChangeRef.current({
+        data: selected.span.attributes?.data,
+        resource: selected.span.attributes?.resource as string | undefined,
+        spanId: selected.span.spanId,
+      });
+    } else {
+      onSelectionChangeRef.current(null);
+    }
+  }, [selected]);
+
+  return null;
+}
+
+/**
+ * Bridge component to deselect from outside the context.
+ */
+function DeselectBridge({ triggerDeselect }: { triggerDeselect: number }) {
+  const { dispatch } = useTraceViewer();
+
+  useEffect(() => {
+    if (triggerDeselect > 0) {
+      dispatch({ type: 'deselect' });
+    }
+  }, [triggerDeselect, dispatch]);
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Panel chrome (header with name/duration, close button)
+// ---------------------------------------------------------------------------
+
+function PanelResizeHandle({
+  onResize,
+}: {
+  onResize: (deltaX: number) => void;
+}) {
+  const handlePointerDown = useCallback(
+    (e: React.PointerEvent) => {
+      e.preventDefault();
+      let lastX = e.clientX;
+      const onPointerMove = (moveEvent: PointerEvent) => {
+        const deltaX = lastX - moveEvent.clientX;
+        lastX = moveEvent.clientX;
+        onResize(deltaX);
+      };
+      const onPointerUp = () => {
+        document.removeEventListener('pointermove', onPointerMove);
+        document.removeEventListener('pointerup', onPointerUp);
+      };
+      document.addEventListener('pointermove', onPointerMove);
+      document.addEventListener('pointerup', onPointerUp);
+    },
+    [onResize]
+  );
+
+  return (
+    <div
+      className="absolute left-0 top-0 bottom-0 w-1 cursor-col-resize hover:bg-blue-400/50 z-10"
+      onPointerDown={handlePointerDown}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
 export const WorkflowTraceViewer = ({
   run,
   steps,
@@ -198,6 +292,7 @@ export const WorkflowTraceViewer = ({
   onResolveHook,
   onStreamClick,
   onSpanSelect,
+  onLoadEventData,
 }: {
   run: WorkflowRun;
   steps: Step[];
@@ -221,8 +316,18 @@ export const WorkflowTraceViewer = ({
   onStreamClick?: (streamId: 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,
+    eventId: string
+  ) => Promise<unknown | null>;
 }) => {
   const [now, setNow] = useState(() => new Date());
+  const [selectedSpan, setSelectedSpan] = useState<SelectedSpanInfo | null>(
+    null
+  );
+  const [panelWidth, setPanelWidth] = useState(DEFAULT_PANEL_WIDTH);
+  const [deselectTrigger, setDeselectTrigger] = useState(0);
 
   useEffect(() => {
     if (!run?.completedAt) {
@@ -250,27 +355,50 @@ export const WorkflowTraceViewer = ({
     }
   }, [error, isLoading]);
 
-  const DetailPanel = () => {
-    const handleSpanSelect = useCallback(
-      (info: SpanSelectionInfo) => {
-        onSpanSelect?.(info);
-      },
-      [onSpanSelect]
-    );
+  const handleSpanSelect = useCallback(
+    (info: SpanSelectionInfo) => {
+      onSpanSelect?.(info);
+    },
+    [onSpanSelect]
+  );
 
+  const handleSelectionChange = useCallback(
+    (info: SelectedSpanInfo | null) => {
+      if (info) {
+        // Filter raw events by the selected span's correlationId (stepId/hookId)
+        // This bypasses the trace worker pipeline entirely.
+        const correlationId = info.spanId;
+        const rawEvents = correlationId
+          ? events.filter((e) => e.correlationId === correlationId)
+          : [];
+        setSelectedSpan({ ...info, rawEvents });
+      } else {
+        setSelectedSpan(null);
+      }
+    },
+    [events]
+  );
+
+  const handleClose = useCallback(() => {
+    setSelectedSpan(null);
+    setDeselectTrigger((n) => n + 1);
+  }, []);
+
+  const handleResize = useCallback((deltaX: number) => {
+    setPanelWidth((w) => Math.max(MIN_PANEL_WIDTH, w + deltaX));
+  }, []);
+
+  // Get the selected span name and duration for the panel header
+  const selectedSpanName = useMemo(() => {
+    if (!selectedSpan?.data) return undefined;
+    const data = selectedSpan.data as Record<string, unknown>;
     return (
-      <EntityDetailPanel
-        run={run}
-        onStreamClick={onStreamClick}
-        spanDetailData={spanDetailData ?? null}
-        spanDetailError={spanDetailError}
-        spanDetailLoading={spanDetailLoading}
-        onSpanSelect={handleSpanSelect}
-        onWakeUpSleep={onWakeUpSleep}
-        onResolveHook={onResolveHook}
-      />
+      (data.stepName as string) ??
+      (data.workflowName as string) ??
+      (data.hookId as string) ??
+      'Details'
     );
-  };
+  }, [selectedSpan?.data]);
 
   if (isLoading || !trace) {
     return (
@@ -288,19 +416,69 @@ export const WorkflowTraceViewer = ({
   }
 
   return (
-    <div className="relative w-full h-full">
-      <TraceViewerContextProvider
-        withPanel
-        customSpanClassNameFunc={getCustomSpanClassName}
-        customSpanEventClassNameFunc={getCustomSpanEventClassName}
-        customPanelComponent={
-          <ErrorBoundary title="Failed to load entity details">
-            <DetailPanel />
-          </ErrorBoundary>
-        }
-      >
-        <TraceViewerTimeline height="100%" trace={trace} withPanel />
-      </TraceViewerContextProvider>
+    <div className="relative w-full h-full flex">
+      {/* Timeline (takes remaining space) */}
+      <div className="flex-1 min-w-0 relative">
+        <TraceViewerContextProvider
+          customSpanClassNameFunc={getCustomSpanClassName}
+          customSpanEventClassNameFunc={getCustomSpanEventClassName}
+        >
+          <SelectionBridge onSelectionChange={handleSelectionChange} />
+          <DeselectBridge triggerDeselect={deselectTrigger} />
+          <TraceViewerTimeline height="100%" trace={trace} />
+        </TraceViewerContextProvider>
+      </div>
+
+      {/* Detail panel (rendered outside the context, as a sibling) */}
+      {selectedSpan && (
+        <div
+          className="relative border-l flex-shrink-0 flex flex-col"
+          style={{
+            width: panelWidth,
+            borderColor: 'var(--ds-gray-200)',
+            backgroundColor: 'var(--ds-background-100)',
+          }}
+        >
+          <PanelResizeHandle onResize={handleResize} />
+          {/* Panel header */}
+          <div
+            className="flex items-center justify-between px-3 py-2 border-b flex-shrink-0"
+            style={{ borderColor: 'var(--ds-gray-200)' }}
+          >
+            <span
+              className="text-sm font-medium truncate"
+              style={{ color: 'var(--ds-gray-1000)' }}
+            >
+              {selectedSpanName}
+            </span>
+            <button
+              type="button"
+              aria-label="Close panel"
+              onClick={handleClose}
+              className="ml-2 p-1 rounded hover:bg-gray-100 dark:hover:bg-gray-800 flex-shrink-0"
+            >
+              <X size={16} />
+            </button>
+          </div>
+          {/* Panel body */}
+          <div className="flex-1 overflow-y-auto">
+            <ErrorBoundary title="Failed to load entity details">
+              <EntityDetailPanel
+                run={run}
+                onStreamClick={onStreamClick}
+                spanDetailData={spanDetailData ?? null}
+                spanDetailError={spanDetailError}
+                spanDetailLoading={spanDetailLoading}
+                onSpanSelect={handleSpanSelect}
+                onWakeUpSleep={onWakeUpSleep}
+                onLoadEventData={onLoadEventData}
+                onResolveHook={onResolveHook}
+                selectedSpan={selectedSpan}
+              />
+            </ErrorBoundary>
+          </div>
+        </div>
+      )}
     </div>
   );
 };

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

@@ -96,7 +96,7 @@ export function waitToSpan(
   const start = dateToOtelTime(startTime);
   const end = dateToOtelTime(endTime);
   const duration = calculateDuration(startTime, endTime);
-  const spanEvents = convertEventsToSpanEvents(events);
+  const spanEvents = convertEventsToSpanEvents(events, false);
   return {
     spanId: wait.waitId,
     name: 'sleep',
@@ -107,7 +107,7 @@ export function waitToSpan(
     traceFlags: 1,
     attributes: {
       resource: 'sleep' as const,
-      data: wait,
+      data: wait, // wait is a plain object built from events, no non-cloneable types
     },
     links: [],
     events: spanEvents,
@@ -128,19 +128,22 @@ export function stepToSpan(
   const now = nowTime ?? new Date();
   const parsedName = parseStepName(String(step.stepName));
 
-  // Simplified attributes: only store resource type and full data
+  // Only embed identification fields — not the full object with
+  // input/output/error which may contain non-cloneable types.
+  // The detail panel fetches full data separately via spanDetailData.
+  const { input: _i, output: _o, error: _e, ...stepIdentity } = step;
   const attributes = {
     resource: 'step' as const,
-    data: step,
+    data: stepIdentity,
   };
 
   const resource = 'step';
   const endTime = new Date(step.completedAt ?? now);
 
-  // Convert step-related events to span events (for markers like hook_created, step_retrying, etc.)
-  // This determines which events are displayed as markers. In the detail view,
-  // we'll show all events that correlate with the selected resource.
-  const events = convertEventsToSpanEvents(stepEvents);
+  // 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);
 
   // Use createdAt as span start time, with activeStartTime for when execution began
   // This allows visualization of the "queued" period before execution
@@ -225,7 +228,7 @@ export function hookToSpan(
   }
 
   // Convert hook-related events to span events
-  const events = convertEventsToSpanEvents(hookEvents);
+  const events = convertEventsToSpanEvents(hookEvents, false);
 
   // We display hooks as a minimum span size of 10 seconds, just to ensure
   // it's clickable even if there is no
@@ -262,10 +265,12 @@ export function runToSpan(
 ): Span {
   const now = nowTime ?? new Date();
 
-  // Simplified attributes: only store resource type and full data
+  // Only embed identification fields — not the full object with
+  // input/output/error which may contain non-cloneable types.
+  const { input: _i, output: _o, error: _e, ...runIdentity } = run;
   const attributes = {
     resource: 'run' as const,
-    data: run,
+    data: runIdentity,
   };
 
   // Use createdAt as span start time, with activeStartTime for when execution began
@@ -274,7 +279,7 @@ export function runToSpan(
   const endTime = run.completedAt ?? now;
 
   // Convert run-level events to span events
-  const events = convertEventsToSpanEvents(runEvents);
+  const events = convertEventsToSpanEvents(runEvents, false);
 
   return {
     spanId: String(run.runId),

package/src/index.ts

@@ -20,6 +20,19 @@ export {
   isTerminalStatus,
   shouldShowReenqueueButton,
 } from './lib/event-analysis';
+export type { Revivers, StreamRef } from './lib/hydration';
+export {
+  CLASS_INSTANCE_REF_TYPE,
+  ClassInstanceRef,
+  extractStreamIds,
+  getWebRevivers,
+  hydrateResourceIO,
+  isClassInstanceRef,
+  isStreamId,
+  isStreamRef,
+  STREAM_REF_TYPE,
+  truncateId,
+} from './lib/hydration';
 export type { StreamStep } from './lib/utils';
 export {
   extractConversation,

package/src/lib/hydration.ts

@@ -0,0 +1,137 @@
+/**
+ * Web-specific hydration for o11y display.
+ *
+ * Browser-safe revivers that use `atob()` for base64 decoding (no Node.js
+ * `Buffer` dependency). Produces `ClassInstanceRef` objects and `StreamRef`
+ * objects for UI rendering.
+ */
+
+import {
+  ClassInstanceRef,
+  extractClassName,
+  hydrateResourceIO as hydrateResourceIOGeneric,
+  observabilityRevivers,
+  type Revivers,
+} from '@workflow/core/serialization-format';
+
+// Re-export types and utilities that consumers need
+export {
+  CLASS_INSTANCE_REF_TYPE,
+  ClassInstanceRef,
+  extractStreamIds,
+  isClassInstanceRef,
+  isStreamId,
+  isStreamRef,
+  type Revivers,
+  STREAM_REF_TYPE,
+  type StreamRef,
+  truncateId,
+} from '@workflow/core/serialization-format';
+
+// ---------------------------------------------------------------------------
+// Browser-safe base64 decode
+// ---------------------------------------------------------------------------
+
+function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  if (base64 === '' || base64 === '.') {
+    return new ArrayBuffer(0);
+  }
+  const binaryString = atob(base64);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+// ---------------------------------------------------------------------------
+// Web revivers (browser-safe, no Buffer dependency)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the web-specific revivers for hydrating serialized data.
+ *
+ * Uses `atob()` for base64 decoding (no Node.js Buffer dependency).
+ * All types are revived as real instances (Date, Map, Set, URL,
+ * URLSearchParams, Headers, Error, etc.).
+ */
+export function getWebRevivers(): Revivers {
+  function reviveArrayBuffer(value: string): ArrayBuffer {
+    return base64ToArrayBuffer(value);
+  }
+
+  return {
+    // O11y-specific revivers (streams, step functions → display objects).
+    // Spread FIRST so web-specific overrides below take precedence.
+    ...observabilityRevivers,
+
+    // Binary types
+    ArrayBuffer: reviveArrayBuffer,
+    BigInt: (value: string) => BigInt(value),
+    BigInt64Array: (value: string) =>
+      new BigInt64Array(reviveArrayBuffer(value)),
+    BigUint64Array: (value: string) =>
+      new BigUint64Array(reviveArrayBuffer(value)),
+    Date: (value) => new Date(value),
+    Error: (value) => {
+      const error = new Error(value.message);
+      error.name = value.name;
+      error.stack = value.stack;
+      return error;
+    },
+    Float32Array: (value: string) => new Float32Array(reviveArrayBuffer(value)),
+    Float64Array: (value: string) => new Float64Array(reviveArrayBuffer(value)),
+    Int8Array: (value: string) => new Int8Array(reviveArrayBuffer(value)),
+    Int16Array: (value: string) => new Int16Array(reviveArrayBuffer(value)),
+    Int32Array: (value: string) => new Int32Array(reviveArrayBuffer(value)),
+    Map: (value) => new Map(value),
+    RegExp: (value) => new RegExp(value.source, value.flags),
+    Set: (value) => new Set(value),
+    Uint8Array: (value: string) => new Uint8Array(reviveArrayBuffer(value)),
+    Uint8ClampedArray: (value: string) =>
+      new Uint8ClampedArray(reviveArrayBuffer(value)),
+    Uint16Array: (value: string) => new Uint16Array(reviveArrayBuffer(value)),
+    Uint32Array: (value: string) => new Uint32Array(reviveArrayBuffer(value)),
+
+    Headers: (value) => new Headers(value),
+    URL: (value) => new URL(value),
+    URLSearchParams: (value) => new URLSearchParams(value === '.' ? '' : value),
+
+    // Web-specific overrides for class instances
+    Class: (value) => `<class:${extractClassName(value.classId)}>`,
+    Instance: (value) =>
+      new ClassInstanceRef(
+        extractClassName(value.classId),
+        value.classId,
+        value.data
+      ),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pre-built web revivers (cached for performance)
+// ---------------------------------------------------------------------------
+
+let cachedRevivers: Revivers | null = null;
+
+function getRevivers(): Revivers {
+  if (!cachedRevivers) {
+    cachedRevivers = getWebRevivers();
+  }
+  return cachedRevivers;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Hydrate the serialized data fields of a resource for web display.
+ *
+ * Uses browser-safe revivers (atob for base64, ClassInstanceRef for
+ * custom classes, StreamRef for streams). Call this on data received
+ * from the server before passing it to UI components.
+ */
+export function hydrateResourceIO<T>(resource: T): T {
+  return hydrateResourceIOGeneric(resource as any, getRevivers()) as T;
+}