@workflow/web-shared 5.0.0-beta.2 → 5.0.0-beta.20

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

@@ -17,6 +17,11 @@ import type { MouseEvent as ReactMouseEvent, ReactNode } from 'react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { useToast } from '../lib/toast';
+import {
+  buildTrace,
+  filterSpanRawEvents,
+  type TraceWithMeta,
+} from '../lib/trace-builder';
 import { ErrorBoundary } from './error-boundary';
 import {
   EntityDetailPanel,
@@ -36,7 +41,6 @@ import {
   getCustomSpanClassName,
   getCustomSpanEventClassName,
 } from './workflow-traces/trace-colors';
-import { buildTrace, type TraceWithMeta } from '../lib/trace-builder';
 
 /**
  * While a run is live, continuously grow root.duration and rescale so the
@@ -776,7 +780,6 @@ export const WorkflowTraceViewer = ({
   encryptionKey,
   onDecrypt,
   isDecrypting = false,
-  hasEncryptedData = false,
 }: {
   run: WorkflowRun;
   events: Event[];
@@ -819,8 +822,6 @@ export const WorkflowTraceViewer = ({
   onDecrypt?: () => void;
   /** Whether the encryption key is currently being fetched */
   isDecrypting?: boolean;
-  /** Run-level hint: the run contains encrypted data (from probe). */
-  hasEncryptedData?: boolean;
 }) => {
   const toast = useToast();
   const [selectedSpan, setSelectedSpan] = useState<SelectedSpanInfo | null>(
@@ -865,12 +866,14 @@ export const WorkflowTraceViewer = ({
   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)
-          : [];
+        // Filter raw events for the selected span: child spans match on
+        // correlationId (stepId/hookId), the run root span gets run-level
+        // events. This bypasses the trace worker pipeline entirely.
+        const rawEvents = filterSpanRawEvents(
+          events,
+          info.resource,
+          info.spanId
+        );
         setSelectedSpan({ ...info, rawEvents });
       } else {
         setSelectedSpan(null);
@@ -884,8 +887,10 @@ export const WorkflowTraceViewer = ({
     const correlationId = selectedSpan?.spanId;
     if (!correlationId) return;
 
-    const nextRawEvents = events.filter(
-      (e) => e.correlationId === correlationId
+    const nextRawEvents = filterSpanRawEvents(
+      events,
+      selectedSpan?.resource,
+      correlationId
     );
     setSelectedSpan((prev) => {
       if (!prev || prev.spanId !== correlationId) {
@@ -907,7 +912,7 @@ export const WorkflowTraceViewer = ({
         rawEvents: nextRawEvents,
       };
     });
-  }, [events, selectedSpan?.spanId]);
+  }, [events, selectedSpan?.spanId, selectedSpan?.resource]);
 
   // Reset selected span when navigating to a different run
   useEffect(() => {
@@ -977,7 +982,7 @@ export const WorkflowTraceViewer = ({
   }
 
   return (
-    <div className="relative w-full h-full flex">
+    <div className="relative w-full h-full flex flex-row">
       {/* Timeline (takes remaining space) */}
       <div className="flex-1 min-w-0 relative">
         <TraceViewerContextProvider
@@ -1164,7 +1169,6 @@ export const WorkflowTraceViewer = ({
                 onDecrypt={onDecrypt}
                 isDecrypting={isDecrypting}
                 selectedSpan={selectedSpan}
-                hasEncryptedData={hasEncryptedData}
               />
             </ErrorBoundary>
           </div>

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

@@ -22,6 +22,7 @@ export interface EventColorPalette {
  * - Red for failures (step_failed, run_failed)
  * - Orange/yellow for retries (step_retrying)
  * - Purple for webhook-related events
+ * - Teal for attribute changes (attr_set)
  * - Blue otherwise (default)
  */
 export function getEventColor(
@@ -64,6 +65,17 @@ export function getEventColor(
     };
   }
 
+  // Attribute changes - Teal
+  if (eventType === 'attr_set') {
+    return {
+      color: 'var(--ds-teal-900)',
+      background: 'var(--ds-teal-200)',
+      border: 'var(--ds-teal-500)',
+      text: 'var(--ds-teal-900)',
+      secondary: 'var(--ds-gray-900)',
+    };
+  }
+
   // Default - Blue
   return {
     color: 'var(--ds-blue-600)',

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

@@ -26,6 +26,7 @@ const MARKER_EVENT_TYPES: Set<Event['eventType']> = new Set([
   'run_failed',
   'wait_created',
   'wait_completed',
+  'attr_set',
 ]);
 
 /**
@@ -59,7 +60,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');
@@ -73,7 +74,9 @@ export const waitEventsToWaitEntity = (
     waitId: startEvent.correlationId,
     runId: startEvent.runId,
     createdAt: startEvent.createdAt,
-    resumeAt: startEvent.eventData?.resumeAt,
+    resumeAt: startEvent.eventData?.resumeAt
+      ? new Date(startEvent.eventData.resumeAt)
+      : undefined,
     completedAt: completedEvent?.createdAt,
   };
 };
@@ -81,13 +84,29 @@ export const waitEventsToWaitEntity = (
 /**
  * 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);
@@ -296,7 +315,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,

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

@@ -14,6 +14,13 @@ export {
   waitEventsToWaitEntity,
 } from './components/workflow-traces/trace-span-construction';
 export type { EventAnalysis } from './lib/event-analysis';
+export {
+  parseExactWorkflowSearchId,
+  looksLikeWorkflowIdSearchInput,
+  type ExactWorkflowSearchId,
+  type ExactWorkflowSearchIdKind,
+  type ExactIdSearchResult,
+} from './lib/exact-event-search-id';
 export {
   analyzeEvents,
   hasPendingHooksFromEvents,
@@ -50,12 +57,14 @@ export {
   STREAM_REF_TYPE,
   truncateId,
 } from './lib/hydration';
+export type { DecodedStreamChunkSource } from './lib/stream-display';
 export type { ToastAdapter } from './lib/toast';
 export { ToastProvider, useToast } from './lib/toast';
 export type { StreamStep } from './lib/utils';
 export {
   extractConversation,
   formatDuration,
+  formatDurationPrecise,
   identifyStreamSteps,
   isDoStreamStep,
 } from './lib/utils';

package/src/lib/exact-event-search-id.ts

@@ -0,0 +1,67 @@
+import type { Event } from '@workflow/world';
+
+const WORKFLOW_ULID_BODY = '[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}';
+
+const STEP_ID_PATTERN = new RegExp(`^step_(${WORKFLOW_ULID_BODY})$`, 'i');
+const WAIT_ID_PATTERN = new RegExp(`^wait_(${WORKFLOW_ULID_BODY})$`, 'i');
+const HOOK_ID_PATTERN = new RegExp(`^hook_(${WORKFLOW_ULID_BODY})$`, 'i');
+const EVENT_ID_PATTERN = new RegExp(`^evnt_(${WORKFLOW_ULID_BODY})$`, 'i');
+
+const WORKFLOW_ID_PREFIX_PATTERN = /^(step_|wait_|hook_|evnt_|wrun_)/i;
+
+export type ExactWorkflowSearchIdKind = 'step' | 'wait' | 'hook' | 'event';
+
+export type ExactWorkflowSearchId = {
+  kind: ExactWorkflowSearchIdKind;
+  id: string;
+};
+
+export type ExactIdSearchResult =
+  | { status: 'ok'; events: Event[]; truncated?: boolean }
+  | { status: 'not_found' }
+  | { status: 'error'; message: string };
+
+function matchPrefixedId(
+  pattern: RegExp,
+  prefix: 'step' | 'wait' | 'hook' | 'evnt',
+  kind: ExactWorkflowSearchIdKind,
+  query: string
+): ExactWorkflowSearchId | null {
+  const match = query.match(pattern);
+  if (!match) {
+    return null;
+  }
+  return { kind, id: `${prefix}_${match[1].toUpperCase()}` };
+}
+
+/**
+ * Returns a parsed workflow ID when `query` is a full step, wait, hook, or event ID.
+ * Partial IDs and run IDs (`wrun_`) are ignored. ULID bodies are matched case-insensitively
+ * and normalized to uppercase in the returned ID.
+ */
+export function parseExactWorkflowSearchId(
+  query: string
+): ExactWorkflowSearchId | null {
+  const trimmed = query.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return (
+    matchPrefixedId(STEP_ID_PATTERN, 'step', 'step', trimmed) ??
+    matchPrefixedId(WAIT_ID_PATTERN, 'wait', 'wait', trimmed) ??
+    matchPrefixedId(HOOK_ID_PATTERN, 'hook', 'hook', trimmed) ??
+    matchPrefixedId(EVENT_ID_PATTERN, 'evnt', 'event', trimmed)
+  );
+}
+
+/** True when input looks like the user is attempting an ID search (including partial). */
+export function looksLikeWorkflowIdSearchInput(query: string): boolean {
+  const trimmed = query.trim();
+  if (!WORKFLOW_ID_PREFIX_PATTERN.test(trimmed)) {
+    return false;
+  }
+  // Distinguish IDs (contain digits) from event-type strings like step_started.
+  // Assumes workflow event types do not include digits in their names.
+  return /\d/.test(trimmed);
+}

package/src/lib/hydration.ts

@@ -58,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 {
@@ -83,10 +131,120 @@ 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` / `HookConflictError` /
+    // `RuntimeDecryptionError` 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;
+    },
+    HookConflictError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts) as Error & {
+        token?: string;
+        conflictingRunId?: string;
+      };
+      error.name = 'HookConflictError';
+      error.token = value.token;
+      if (value.conflictingRunId !== undefined) {
+        error.conflictingRunId = value.conflictingRunId;
+      }
+      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;
+    },
+    RuntimeDecryptionError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts) as Error & {
+        context?: unknown;
+      };
+      error.name = 'RuntimeDecryptionError';
+      if (value.context !== undefined) {
+        error.context = value.context;
+      }
+      if (value.stack !== undefined) error.stack = value.stack;
+      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)),
@@ -318,6 +476,13 @@ export async function hydrateResourceIOWithKey<T>(
     '@workflow/core/serialization-format'
   );
   const { importKey } = await import('@workflow/core/encryption');
+  // Payloads may be zstd-compressed (the Web DecompressionStream has no zstd);
+  // register the WASM-backed browser decoder before hydrating. Idempotent and
+  // lazy — the WASM is only compiled when a zstd payload is actually decoded.
+  const { ensureZstdDecoderRegistered } = await import(
+    './zstd-browser-decoder.js'
+  );
+  ensureZstdDecoderRegistered();
   const cryptoKey = await importKey(key);
   const revivers = getRevivers();
 

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