@workflow/web-shared 5.0.0-beta.0 → 5.0.0-beta.10

package/src/lib/hydration.ts

@@ -11,9 +11,12 @@ import {
   hydrateResourceIO as hydrateResourceIOGeneric,
   isEncryptedData,
   isExpiredStub,
+  isRunRef,
   observabilityRevivers,
   type Revivers,
+  serializedInstanceToRef,
 } from '@workflow/core/serialization-format';
+import { EVENT_DATA_REF_FIELDS } from '@workflow/world';
 
 // Re-export types and utilities that consumers need
 export {
@@ -23,11 +26,15 @@ export {
   extractStreamIds,
   isClassInstanceRef,
   isEncryptedData,
+  isRunRef,
   isStreamId,
   isStreamRef,
   type Revivers,
+  RUN_REF_TYPE,
+  type RunRef,
   STREAM_REF_TYPE,
   type StreamRef,
+  serializedInstanceToRef,
   truncateId,
 } from '@workflow/core/serialization-format';
 
@@ -51,12 +58,60 @@ function base64ToArrayBuffer(base64: string): ArrayBuffer {
 // Web revivers (browser-safe, no Buffer dependency)
 // ---------------------------------------------------------------------------
 
+/**
+ * Build a reviver for one of the built-in `Error` subclasses (e.g.
+ * `TypeError`, `RangeError`). The constructor for the named subclass is
+ * resolved off `globalThis` at call time so the produced instance has the
+ * correct prototype chain in the consumer realm. Falls back to a generic
+ * `Error` (with `name` set) if the global isn't available, which keeps the
+ * o11y UI rendering even on exotic browsers.
+ *
+ * `cause` is passed through `ErrorOptions` to the constructor when present,
+ * matching `getCommonRevivers` in `@workflow/core` so the resulting `cause`
+ * property has the same semantics (non-enumerable, set by the engine) as a
+ * freshly thrown Error in the consumer realm. The `'cause' in value` check
+ * preserves the distinction between "no cause" and "cause is undefined".
+ */
+function makeWebErrorSubclassReviver(
+  name:
+    | 'EvalError'
+    | 'RangeError'
+    | 'ReferenceError'
+    | 'SyntaxError'
+    | 'TypeError'
+    | 'URIError'
+) {
+  return (value: { message: string; stack?: string; cause?: unknown }) => {
+    const opts = 'cause' in value ? { cause: value.cause } : undefined;
+    const Ctor = (globalThis as Record<string, any>)[name] as
+      | ErrorConstructor
+      | undefined;
+    let error: Error;
+    if (typeof Ctor === 'function') {
+      error = new Ctor(value.message, opts);
+    } else {
+      // Fallback path: no built-in subclass available (exotic env). Construct
+      // a plain Error with the right `name` and copy `cause` manually since
+      // the base Error constructor is what we actually called.
+      error = Object.assign(new Error(value.message, opts), { name });
+    }
+    if (value.stack !== undefined) error.stack = value.stack;
+    return error;
+  };
+}
+
 /**
  * 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.).
+ *
+ * NOTE: this set must mirror the keys in `SerializableSpecial` (see
+ * `@workflow/core/serialization/types`). Any reducer key added on the
+ * serialization side that isn't covered here will cause `devalue.unflatten`
+ * to throw `Unknown type X`, which `hydrateResourceIO` swallows and
+ * surfaces as a "Failed to load resource details" banner in the o11y UI.
  */
 export function getWebRevivers(): Revivers {
   function reviveArrayBuffer(value: string): ArrayBuffer {
@@ -76,10 +131,93 @@ export function getWebRevivers(): Revivers {
     BigUint64Array: (value: string) =>
       new BigUint64Array(reviveArrayBuffer(value)),
     Date: (value) => new Date(value),
+
+    // Error family. The reducer side (see
+    // `packages/core/src/serialization/reducers/common.ts`) emits a tagged
+    // entry for each built-in Error subclass plus the workflow-specific
+    // `FatalError` / `RetryableError` and `AggregateError`. Without
+    // matching revivers here, `devalue.unflatten` throws "Unknown type X"
+    // — which surfaces in the web o11y UI as "Failed to load resource
+    // details: Unknown type FatalError".
     Error: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts);
+      error.name = value.name;
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    EvalError: makeWebErrorSubclassReviver('EvalError'),
+    RangeError: makeWebErrorSubclassReviver('RangeError'),
+    ReferenceError: makeWebErrorSubclassReviver('ReferenceError'),
+    SyntaxError: makeWebErrorSubclassReviver('SyntaxError'),
+    TypeError: makeWebErrorSubclassReviver('TypeError'),
+    URIError: makeWebErrorSubclassReviver('URIError'),
+    AggregateError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const Ctor = (
+        globalThis as { AggregateError?: AggregateErrorConstructor }
+      ).AggregateError;
+      const error =
+        typeof Ctor === 'function'
+          ? new Ctor(value.errors, value.message, opts)
+          : Object.assign(new Error(value.message, opts), {
+              name: 'AggregateError',
+              errors: value.errors,
+            });
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    // `FatalError` and `RetryableError` are not built-in browser globals,
+    // so we can't resolve a constructor from globalThis. The web o11y UI
+    // doesn't need `instanceof FatalError` to pass (no user code runs
+    // here) — it just needs `name`, `message`, `stack`, and any extra
+    // enumerable fields to render. Construct a plain `Error` with `name`
+    // set; ObjectInspector reads `constructor.name` for the displayed
+    // class label, but we don't have the real class, so we emit a tagged
+    // Error whose `name` field carries the class identity. This matches
+    // how the existing base `Error` reviver presents unknown subclasses.
+    FatalError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts);
+      error.name = 'FatalError';
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    RetryableError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts) as Error & {
+        retryAfter?: Date;
+      };
+      error.name = 'RetryableError';
+      if (value.stack !== undefined) error.stack = value.stack;
+      // `retryAfter` is serialized as an epoch ms number (see the runtime
+      // RetryableError reducer for the rationale around realm-safety).
+      // Rehydrate as a Date so o11y consumers can render it directly.
+      // Guard against payloads from older runtime versions that predate
+      // the field — without this check, `new Date(undefined)` would
+      // produce an Invalid Date rather than omitting the property.
+      if (value.retryAfter != null) {
+        error.retryAfter = new Date(value.retryAfter);
+      }
+      return error;
+    },
+    DOMException: (value) => {
+      // Modern browsers and Node 18+ expose `DOMException` on globalThis.
+      // `AbortController.abort()` with no argument synthesizes one as the
+      // signal's reason, so this is a common payload for any aborted step.
+      const G = globalThis as { DOMException?: typeof DOMException };
+      if (typeof G.DOMException === 'function') {
+        const e = new G.DOMException(value.message, value.name);
+        if (value.stack !== undefined) e.stack = value.stack;
+        if ('cause' in value) (e as { cause?: unknown }).cause = value.cause;
+        return e;
+      }
       const error = new Error(value.message);
       error.name = value.name;
-      error.stack = value.stack;
+      if (value.stack !== undefined) error.stack = value.stack;
+      if ('cause' in value) {
+        (error as Error & { cause?: unknown }).cause = value.cause;
+      }
       return error;
     },
     Float32Array: (value: string) => new Float32Array(reviveArrayBuffer(value)),
@@ -136,6 +274,11 @@ export function getWebRevivers(): Revivers {
     // react-inspector shows the class name (it reads constructor.name).
     Class: (value) => `<class:${extractClassName(value.classId)}>`,
     Instance: (value) => {
+      // Run instances are rendered as clickable RunRef badges
+      const runRef = serializedInstanceToRef(value);
+      if (isRunRef(runRef)) {
+        return runRef;
+      }
       const className = extractClassName(value.classId);
       const data = value.data;
       const props =
@@ -274,9 +417,14 @@ function replaceEncryptedAndExpiredWithMarkers<T>(resource: T): T {
   }
 
   if (result.eventData && typeof result.eventData === 'object') {
+    const eventType =
+      typeof result.eventType === 'string' ? result.eventType : '';
+    const refKeys = EVENT_DATA_REF_FIELDS[eventType] ?? [];
     const ed = { ...(result.eventData as Record<string, unknown>) };
-    for (const key of EVENT_DATA_SERIALIZED_FIELDS) {
-      ed[key] = toDisplayMarker(ed[key]);
+    for (const key of refKeys) {
+      if (key in ed) {
+        ed[key] = toDisplayMarker(ed[key]);
+      }
     }
     result.eventData = ed;
   }
@@ -284,15 +432,6 @@ function replaceEncryptedAndExpiredWithMarkers<T>(resource: T): T {
   return result as T;
 }
 
-/** Known serialized subfields within eventData, matching hydrateEventData in core */
-const EVENT_DATA_SERIALIZED_FIELDS = [
-  'result',
-  'input',
-  'output',
-  'metadata',
-  'payload',
-];
-
 /**
  * Hydrate resource data with decryption support.
  *
@@ -300,7 +439,7 @@ const EVENT_DATA_SERIALIZED_FIELDS = [
  * This is the async version used when the user clicks "Decrypt" in the web UI.
  *
  * Handles both top-level fields (input, output, metadata) and nested
- * eventData subfields (result, input, output, metadata, payload).
+ * eventData subfields per `EVENT_DATA_REF_FIELDS` from `@workflow/world` for that event type.
  */
 export async function hydrateResourceIOWithKey<T>(
   resource: T,
@@ -344,8 +483,11 @@ export async function hydrateResourceIOWithKey<T>(
 
   // Decrypt + hydrate eventData subfields (events)
   if (result.eventData && typeof result.eventData === 'object') {
+    const eventType =
+      typeof result.eventType === 'string' ? result.eventType : '';
+    const refKeys = EVENT_DATA_REF_FIELDS[eventType] ?? [];
     const eventData = { ...(result.eventData as Record<string, unknown>) };
-    for (const field of EVENT_DATA_SERIALIZED_FIELDS) {
+    for (const field of refKeys) {
       if (field in eventData) {
         eventData[field] = await decryptField(
           eventData[field],
@@ -359,3 +501,29 @@ export async function hydrateResourceIOWithKey<T>(
 
   return result as T;
 }
+
+/**
+ * Check whether a hydrated resource (event, step, run, etc.) contains any
+ * encrypted display markers. Inspects the standard top-level fields
+ * (`input`, `output`, `error`, `metadata`) as well as the event-type-specific
+ * `eventData` ref fields.
+ */
+export function hasEncryptedFields(resource: unknown): boolean {
+  if (!resource || typeof resource !== 'object') return false;
+  const r = resource as Record<string, unknown>;
+
+  for (const key of ['input', 'output', 'metadata', 'error']) {
+    if (isEncryptedMarker(r[key])) return true;
+  }
+
+  if (r.eventData && typeof r.eventData === 'object') {
+    const eventType = typeof r.eventType === 'string' ? r.eventType : '';
+    const refKeys = EVENT_DATA_REF_FIELDS[eventType] ?? [];
+    const ed = r.eventData as Record<string, unknown>;
+    for (const key of refKeys) {
+      if (key in ed && isEncryptedMarker(ed[key])) return true;
+    }
+  }
+
+  return false;
+}

package/src/lib/stream-display.ts

@@ -0,0 +1,48 @@
+export interface DecodedStreamChunkSource {
+  type: string;
+  encoding: 'utf-8';
+  rawSummary: string;
+}
+
+export interface FormattedStreamChunkDisplay {
+  text: string;
+  decodedFrom?: DecodedStreamChunkSource;
+}
+
+export function summarizeArrayBufferView(value: ArrayBufferView): string {
+  const ta = value as unknown as {
+    length: number;
+    constructor: { name: string };
+  } & ArrayLike<number>;
+  const name = ta.constructor.name;
+  const preview = Array.from(
+    { length: Math.min(ta.length, 8) },
+    (_, i) => ta[i]
+  );
+  const suffix = ta.length > 8 ? ', …' : '';
+  return `${name}(${ta.length}) [${preview.join(', ')}${suffix}]`;
+}
+
+/**
+ * Decode a typed array as UTF-8 text when valid, otherwise return a compact
+ * raw-byte summary. Used by `DataInspector`'s `collapseRefs` pipeline so
+ * hydrated `Uint8Array` chunks (e.g. AI SDK text deltas) render as readable
+ * text while still exposing the underlying byte layout.
+ */
+export function formatArrayBufferViewForDisplay(
+  value: ArrayBufferView
+): FormattedStreamChunkDisplay {
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(value);
+    return {
+      text,
+      decodedFrom: {
+        type: value.constructor.name,
+        encoding: 'utf-8',
+        rawSummary: summarizeArrayBufferView(value),
+      },
+    };
+  } catch {
+    return { text: summarizeArrayBufferView(value) };
+  }
+}

package/src/lib/trace-builder.ts

@@ -117,6 +117,7 @@ function buildSpans(
   // unknown territory. Even when the run is completed, we may not have loaded
   // all events yet, so always use the latest event we've actually seen.
   const childMaxEnd = latestKnownTime;
+  const runMaxEnd = run.completedAt ?? now;
 
   const stepSpans = Array.from(groupedEvents.eventsByStepId.values())
     .map((events) => stepToSpan(events, childMaxEnd))
@@ -127,7 +128,7 @@ function buildSpans(
     .filter((span): span is Span => span !== null);
 
   const waitSpans = Array.from(groupedEvents.timerEvents.values())
-    .map((events) => waitToSpan(events, childMaxEnd))
+    .map((events) => waitToSpan(events, childMaxEnd, runMaxEnd))
     .filter((span): span is Span => span !== null);
 
   return {

package/src/lib/utils.ts

@@ -7,10 +7,6 @@ export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
 }
 
-const durationFormatter = new Intl.NumberFormat(undefined, {
-  maximumFractionDigits: 2,
-});
-
 const MS_IN_SECOND = 1000;
 const MS_IN_MINUTE = 60 * MS_IN_SECOND;
 const MS_IN_HOUR = 60 * MS_IN_MINUTE;
@@ -20,52 +16,53 @@ const MS_IN_DAY = 24 * MS_IN_HOUR;
  * Formats a duration in milliseconds to a human-readable string.
  *
  * @param ms - Duration in milliseconds
- * @param compact - If true, returns a single-unit format (e.g., "45s", "2.5m").
- *                  If false (default), returns multi-part format (e.g., "1h 30m", "2d 5h").
+ * @param compact - If true, returns a compact format (e.g., "380ms", "2m 30s").
+ *                  If false (default), returns multi-part format (e.g., "1m 13s", "2d 5h 3m 12s").
  *
- * Compact format:
- * - < 1s: shows milliseconds (e.g., "500ms")
+ * Compact format (timeline markers):
+ * - < 1s: shows milliseconds (e.g., "380ms")
  * - < 1m: shows seconds (e.g., "45s")
- * - < 1h: shows minutes (e.g., "45m")
- * - >= 1h: shows hours (e.g., "2.5h")
+ * - < 1h: shows minutes and seconds (e.g., "2m 30s")
+ * - >= 1h: shows hours and minutes (e.g., "2h 30m")
  *
  * Full format:
- * - < 1s: shows milliseconds (e.g., "500ms")
- * - < 1m: shows seconds (e.g., "45.5s")
- * - >= 1m: shows human-readable format (e.g., "1h 30m", "2d 5h")
+ * - < 1s: shows milliseconds (e.g., "380ms")
+ * - < 1m: shows seconds (e.g., "45s")
+ * - >= 1m: shows decomposed format with whole seconds (e.g., "1m 13s", "2m 13s")
  */
 export function formatDuration(ms: number, compact = false): string {
   if (ms === 0) {
-    return '0';
+    return '0s';
   }
 
-  // For durations less than 1 second, show milliseconds
   if (ms < MS_IN_SECOND) {
-    return `${durationFormatter.format(ms)}ms`;
+    const roundedMs = Math.round(ms);
+    return roundedMs < MS_IN_SECOND ? `${roundedMs}ms` : '1s';
   }
 
-  // For durations less than 1 minute, show seconds
-  if (ms < MS_IN_MINUTE) {
-    return `${durationFormatter.format(ms / MS_IN_SECOND)}s`;
+  const roundedMs = Math.round(ms / MS_IN_SECOND) * MS_IN_SECOND;
+
+  if (roundedMs < MS_IN_MINUTE) {
+    return `${Math.floor(roundedMs / MS_IN_SECOND)}s`;
   }
 
   // Compact format: multi-unit without decimals (e.g. "8m 20s", "2h 30m")
   if (compact) {
-    if (ms < MS_IN_HOUR) {
-      const m = Math.floor(ms / MS_IN_MINUTE);
-      const s = Math.floor((ms % MS_IN_MINUTE) / MS_IN_SECOND);
+    if (roundedMs < MS_IN_HOUR) {
+      const m = Math.floor(roundedMs / MS_IN_MINUTE);
+      const s = Math.floor((roundedMs % MS_IN_MINUTE) / MS_IN_SECOND);
       return s > 0 ? `${m}m ${s}s` : `${m}m`;
     }
-    const h = Math.floor(ms / MS_IN_HOUR);
-    const m = Math.floor((ms % MS_IN_HOUR) / MS_IN_MINUTE);
+    const h = Math.floor(roundedMs / MS_IN_HOUR);
+    const m = Math.floor((roundedMs % MS_IN_HOUR) / MS_IN_MINUTE);
     return m > 0 ? `${h}h ${m}m` : `${h}h`;
   }
 
-  // Full format: human-readable multi-part
-  const days = Math.floor(ms / MS_IN_DAY);
-  const hours = Math.floor((ms % MS_IN_DAY) / MS_IN_HOUR);
-  const minutes = Math.floor((ms % MS_IN_HOUR) / MS_IN_MINUTE);
-  const seconds = Math.floor((ms % MS_IN_MINUTE) / MS_IN_SECOND);
+  // Full format: decompose into larger units + whole seconds.
+  const days = Math.floor(roundedMs / MS_IN_DAY);
+  const hours = Math.floor((roundedMs % MS_IN_DAY) / MS_IN_HOUR);
+  const minutes = Math.floor((roundedMs % MS_IN_HOUR) / MS_IN_MINUTE);
+  const seconds = Math.floor((roundedMs % MS_IN_MINUTE) / MS_IN_SECOND);
 
   const parts: string[] = [];
 
@@ -78,9 +75,7 @@ export function formatDuration(ms: number, compact = false): string {
   if (minutes > 0) {
     parts.push(`${minutes}m`);
   }
-  if (hours <= 1 && (seconds > 0 || parts.length === 0)) {
-    parts.push(`${seconds}s`);
-  }
+  parts.push(`${seconds}s`);
 
   return parts.join(' ');
 }