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

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

@@ -16,7 +16,7 @@ import {
   type Revivers,
   serializedInstanceToRef,
 } from '@workflow/core/serialization-format';
-import { EVENT_DATA_REF_FIELDS } from '@workflow/world';
+import { getEventDataRefFields } from '@workflow/world';
 
 // Re-export types and utilities that consumers need
 export {
@@ -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)),
@@ -140,7 +298,7 @@ export function getWebRevivers(): Revivers {
 
     // Web-specific overrides for class instances.
     // Create objects with a dynamically-named constructor so that
-    // react-inspector shows the class name (it reads constructor.name).
+    // the data 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
@@ -153,7 +311,7 @@ export function getWebRevivers(): Revivers {
       const props =
         data && typeof data === 'object' ? { ...data } : { value: data };
       // Create a constructor with the right name using computed property
-      // so react-inspector's `object.constructor.name` shows the class name.
+      // so the data inspector's `object.constructor.name` shows the class name.
       // Must use `function` (not arrow) because arrow functions have no .prototype.
       // biome-ignore lint/complexity/useArrowFunction: arrow functions have no .prototype
       const ctor = { [className]: function () {} }[className]!;
@@ -288,7 +446,7 @@ 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 refKeys = getEventDataRefFields(eventType);
     const ed = { ...(result.eventData as Record<string, unknown>) };
     for (const key of refKeys) {
       if (key in ed) {
@@ -307,36 +465,62 @@ function replaceEncryptedAndExpiredWithMarkers<T>(resource: T): T {
  * When a key is provided, encrypted fields are decrypted before hydration.
  * 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 per `EVENT_DATA_REF_FIELDS` from `@workflow/world` for that event type.
+ * Handles both top-level fields (input, output, metadata) and nested eventData
+ * payload fields for that event type.
  */
 export async function hydrateResourceIOWithKey<T>(
   resource: T,
   key: Uint8Array
 ): Promise<T> {
-  const { hydrateDataWithKey } = await import(
+  return hydrateResourceIOAsync(resource, key);
+}
+
+/**
+ * Async hydration for web display.
+ *
+ * This follows the same resource-field mapping as {@link hydrateResourceIO},
+ * but can also inflate compressed browser payloads through the registered
+ * zstd WASM decoder. When a key is provided, encrypted fields are decrypted
+ * first and then inflated/hydrated.
+ */
+export async function hydrateResourceIOAsync<T>(
+  resource: T,
+  key?: Uint8Array
+): Promise<T> {
+  const { hydrateDataWithKey, deriveRunPayloadKeys } = await import(
     '@workflow/core/serialization-format'
   );
-  const { importKey } = await import('@workflow/core/encryption');
-  const cryptoKey = await importKey(key);
+  // 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();
+  // Resolve the *full* key capability, not just the symmetric key: a run's
+  // event log can contain sealed ('encp') payloads that another run wrote to
+  // it (a cross-deployment hook resumption, say), and opening those needs the
+  // run's X25519 scalar in addition to its AES key. Both are derived from the
+  // same 32 bytes the key-retrieval endpoint returns.
+  // Resolve the *full* key capability, not just the symmetric key: a run's
+  // event log can contain sealed ('encp') payloads that another run wrote to
+  // it (a cross-deployment hook resumption, say), and opening those needs the
+  // run's X25519 scalar in addition to its AES key. Both derive from the same
+  // 32 bytes the key-retrieval endpoint returns.
+  const cryptoKey = key ? await deriveRunPayloadKeys(key) : undefined;
   const revivers = getRevivers();
 
-  /** Extract original encrypted bytes from a marker or raw Uint8Array, then decrypt + hydrate */
-  async function decryptField(
-    value: unknown,
-    rev: Revivers,
-    k: Awaited<ReturnType<typeof importKey>>
-  ): Promise<unknown> {
+  async function hydrateField(value: unknown): Promise<unknown> {
     // Already-hydrated: encrypted marker with stored bytes
     if (isEncryptedMarker(value)) {
       const raw = (value as any).__encryptedData as Uint8Array;
-      return hydrateDataWithKey(raw, rev, k);
+      return cryptoKey ? hydrateDataWithKey(raw, revivers, cryptoKey) : value;
     }
-    // Raw encrypted Uint8Array (not yet hydrated)
+    // Raw Uint8Array: may be encrypted, compressed, or plain devalue.
     if (value instanceof Uint8Array) {
-      return hydrateDataWithKey(value, rev, k);
+      return hydrateDataWithKey(value, revivers, cryptoKey);
     }
-    // Not encrypted — return as-is
+    // Not serialized — return as-is.
     return value;
   }
 
@@ -346,29 +530,25 @@ export async function hydrateResourceIOWithKey<T>(
   // Decrypt + hydrate top-level serialized fields (runs, steps, hooks)
   for (const field of ['input', 'output', 'metadata', 'error']) {
     if (field in result) {
-      result[field] = await decryptField(result[field], revivers, cryptoKey);
+      result[field] = await hydrateField(result[field]);
     }
   }
 
-  // Decrypt + hydrate eventData subfields (events)
+  // 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 refKeys = getEventDataRefFields(eventType);
     const eventData = { ...(result.eventData as Record<string, unknown>) };
     for (const field of refKeys) {
       if (field in eventData) {
-        eventData[field] = await decryptField(
-          eventData[field],
-          revivers,
-          cryptoKey
-        );
+        eventData[field] = await hydrateField(eventData[field]);
       }
     }
     result.eventData = eventData;
   }
 
-  return result as T;
+  return replaceEncryptedAndExpiredWithMarkers(result as T);
 }
 
 /**
@@ -387,7 +567,7 @@ export function hasEncryptedFields(resource: unknown): boolean {
 
   if (r.eventData && typeof r.eventData === 'object') {
     const eventType = typeof r.eventType === 'string' ? r.eventType : '';
-    const refKeys = EVENT_DATA_REF_FIELDS[eventType] ?? [];
+    const refKeys = getEventDataRefFields(eventType);
     const ed = r.eventData as Record<string, unknown>;
     for (const key of refKeys) {
       if (key in ed && isEncryptedMarker(ed[key])) return true;

package/src/lib/trace-builder.ts

@@ -6,30 +6,54 @@
  * a fully-formed Trace ready for the trace viewer.
  */
 
-import type { Event, WorkflowRun } from '@workflow/world';
-import type { Span } from '../components/trace-viewer/types';
 import {
+  type Event,
+  isHookLifecycleEventType,
+  isStepEventType,
+  isWaitEventType,
+  type WorkflowRun,
+} from '@workflow/world';
+import {
+  getEventTimestamp,
   hookToSpan,
   runToSpan,
   stepToSpan,
-  waitToSpan,
   WORKFLOW_LIBRARY,
+  waitToSpan,
 } from '../components/workflow-traces/trace-span-construction';
 import { otelTimeToMs } from '../components/workflow-traces/trace-time-utils';
+import type { Span } from './trace-types';
 
-// ---------------------------------------------------------------------------
-// Event type classifiers
-// ---------------------------------------------------------------------------
-
-export const isStepEvent = (eventType: string) => eventType.startsWith('step_');
-
-export const isTimerEvent = (eventType: string) =>
-  eventType === 'wait_created' || eventType === 'wait_completed';
+/**
+ * Events that belong to the run root span rather than a child entity span.
+ * Mirrors the fallthrough logic in {@link groupEventsByCorrelation}: events
+ * without a correlationId (run lifecycle) plus correlated events that aren't
+ * step/timer/hook events (e.g. `attr_set`, whose correlationId is a dedup
+ * token rather than a child entity ID).
+ */
+export const isRunLevelEvent = (event: Event): boolean =>
+  !event.correlationId ||
+  (!isWaitEventType(event.eventType) &&
+    !isHookLifecycleEventType(event.eventType) &&
+    !isStepEventType(event.eventType));
 
-export const isHookLifecycleEvent = (eventType: string) =>
-  eventType === 'hook_received' ||
-  eventType === 'hook_created' ||
-  eventType === 'hook_disposed';
+/**
+ * Filter the raw event list down to the events for a selected span.
+ * For the run root span this returns run-level events (see
+ * {@link isRunLevelEvent}); for child spans it returns the events
+ * correlated to that span's ID.
+ */
+export function filterSpanRawEvents(
+  events: Event[],
+  resource: string | undefined,
+  spanId: string | undefined
+): Event[] {
+  if (resource === 'run') {
+    return events.filter(isRunLevelEvent);
+  }
+  if (!spanId) return [];
+  return events.filter((e) => e.correlationId === spanId);
+}
 
 // ---------------------------------------------------------------------------
 // Event grouping
@@ -68,17 +92,17 @@ export function groupEventsByCorrelation(events: Event[]): GroupedEvents {
       continue;
     }
 
-    if (isTimerEvent(event.eventType)) {
+    if (isWaitEventType(event.eventType)) {
       pushEvent(timerEvents, correlationId, event);
       continue;
     }
 
-    if (isHookLifecycleEvent(event.eventType)) {
+    if (isHookLifecycleEventType(event.eventType)) {
       pushEvent(hookEvents, correlationId, event);
       continue;
     }
 
-    if (isStepEvent(event.eventType)) {
+    if (isStepEventType(event.eventType)) {
       pushEvent(eventsByStepId, correlationId, event);
       continue;
     }
@@ -101,7 +125,7 @@ export function groupEventsByCorrelation(events: Event[]): GroupedEvents {
 function computeLatestKnownTime(events: Event[], run: WorkflowRun): Date {
   let latest = new Date(run.createdAt).getTime();
   for (const event of events) {
-    const t = new Date(event.createdAt).getTime();
+    const t = (getEventTimestamp(event) ?? new Date(event.createdAt)).getTime();
     if (t > latest) latest = t;
   }
   return new Date(latest);

package/src/lib/trace-types.ts

@@ -0,0 +1,56 @@
+export interface Span {
+  name: string;
+  kind: number;
+  resource: string;
+  library: {
+    name: string;
+    version?: string;
+  };
+  spanId: string;
+  parentSpanId?: string;
+  status: {
+    code: number;
+  };
+  traceFlags: number;
+  attributes: Record<string, unknown>;
+  links: Record<string, unknown>[];
+  events: SpanEvent[];
+  startTime: [number, number];
+  endTime: [number, number];
+  duration: [number, number];
+  /**
+   * The time when the span became active/started executing (optional).
+   * If provided and different from startTime, the portion between startTime
+   * and activeStartTime will be rendered as a "queued" period with different styling.
+   */
+  activeStartTime?: [number, number];
+}
+
+export interface SpanEvent {
+  name: string;
+  timestamp: [number, number];
+  attributes: Record<string, unknown>;
+  /**
+   * Optional custom color for this event marker (workflow-specific feature).
+   * If provided, this color will be used for the event marker line/diamond.
+   */
+  color?: string;
+  /**
+   * Whether to show a vertical line for this event in the timeline (workflow-specific feature).
+   * If false, only the diamond marker on the span will be shown.
+   * Defaults to true if not specified.
+   */
+  showVerticalLine?: boolean;
+}
+
+export interface Resource {
+  name: string;
+  attributes: Record<string, string>;
+}
+
+export interface Trace {
+  traceId: string;
+  resources?: Resource[];
+  spans: Span[];
+  rootSpanId?: string;
+}

package/src/lib/utils.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { formatDurationPrecise } from './utils';
+
+describe('formatDurationPrecise', () => {
+  it('shows whole milliseconds below 1s', () => {
+    expect(formatDurationPrecise(0)).toBe('0s');
+    expect(formatDurationPrecise(626)).toBe('626ms');
+  });
+
+  it('keeps sub-second precision instead of rounding up to a whole second', () => {
+    // The bug this guards: 1626ms must not read as "2s".
+    expect(formatDurationPrecise(1626)).toBe('1.63s');
+  });
+
+  it('trims trailing zeros so whole/half seconds read cleanly', () => {
+    expect(formatDurationPrecise(2000)).toBe('2s');
+    expect(formatDurationPrecise(1500)).toBe('1.5s');
+    expect(formatDurationPrecise(1600)).toBe('1.6s');
+    expect(formatDurationPrecise(45_000)).toBe('45s');
+  });
+
+  it('honors a custom fraction-digit count (used by the timeline ruler)', () => {
+    // Fewer digits also coarsen the rounding: 1 digit rounds to 100ms.
+    expect(formatDurationPrecise(1500, 1)).toBe('1.5s');
+    expect(formatDurationPrecise(1620, 1)).toBe('1.6s');
+    expect(formatDurationPrecise(2000, 1)).toBe('2s');
+  });
+
+  it('decomposes durations of a minute or more', () => {
+    expect(formatDurationPrecise(65_000)).toBe('1m 5s');
+    expect(formatDurationPrecise(63_450)).toBe('1m 3.45s');
+  });
+});

package/src/lib/utils.ts

@@ -1,11 +1,5 @@
 import type { Step } from '@workflow/world';
 import type { ModelMessage } from 'ai';
-import { type ClassValue, clsx } from 'clsx';
-import { twMerge } from 'tailwind-merge';
-
-export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs));
-}
 
 const MS_IN_SECOND = 1000;
 const MS_IN_MINUTE = 60 * MS_IN_SECOND;
@@ -80,6 +74,59 @@ export function formatDuration(ms: number, compact = false): string {
   return parts.join(' ');
 }
 
+/**
+ * Formats a duration in milliseconds without snapping to whole seconds.
+ *
+ * Unlike {@link formatDuration}, this keeps sub-second detail, so 1626ms
+ * renders as "1.63s" rather than "2s". `fractionDigits` sets both the number of
+ * decimals on the seconds component (trailing zeros trimmed, so 2000ms is "2s"
+ * and 1500ms is "1.5s") and the rounding granularity — the default of 2 rounds
+ * to 10ms; the timeline ruler passes fewer digits to match its tick step.
+ *
+ * - < 1s: shows whole milliseconds (e.g. "626ms")
+ * - 1s – 1m: shows seconds with trimmed decimals (e.g. "1.63s", "1.5s", "45s")
+ * - >= 1m: decomposes into d/h/m with trimmed-decimal seconds (e.g. "1m 13.45s")
+ */
+export function formatDurationPrecise(ms: number, fractionDigits = 2): string {
+  if (ms === 0) {
+    return '0s';
+  }
+
+  if (ms < MS_IN_SECOND) {
+    const roundedMs = Math.round(ms);
+    if (roundedMs < MS_IN_SECOND) {
+      return `${roundedMs}ms`;
+    }
+  }
+
+  const granularityMs = MS_IN_SECOND / 10 ** fractionDigits;
+  const normalizedMs = Math.round(ms / granularityMs) * granularityMs;
+
+  if (normalizedMs < MS_IN_MINUTE) {
+    return `${Number((normalizedMs / MS_IN_SECOND).toFixed(fractionDigits))}s`;
+  }
+
+  const days = Math.floor(normalizedMs / MS_IN_DAY);
+  const hours = Math.floor((normalizedMs % MS_IN_DAY) / MS_IN_HOUR);
+  const minutes = Math.floor((normalizedMs % MS_IN_HOUR) / MS_IN_MINUTE);
+  const seconds = (normalizedMs % MS_IN_MINUTE) / MS_IN_SECOND;
+
+  const parts: string[] = [];
+
+  if (days > 0) {
+    parts.push(`${days}d`);
+  }
+  if (hours > 0) {
+    parts.push(`${hours}h`);
+  }
+  if (minutes > 0) {
+    parts.push(`${minutes}m`);
+  }
+  parts.push(`${Number(seconds.toFixed(fractionDigits))}s`);
+
+  return parts.join(' ');
+}
+
 /**
  * Returns a formatted pagination display string
  * @param currentPage - The current page number