@workflow/web-shared 5.0.0-beta.1 → 5.0.0-beta.11

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

@@ -0,0 +1,53 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import * as React from 'react';
+import { cn } from '../../lib/utils';
+
+const iconButtonVariants = cva(
+  [
+    'm-0 inline-flex shrink-0 appearance-none items-center justify-center border-0 bg-transparent p-0 align-baseline font-inherit no-underline [background:none] [-webkit-appearance:none] [-webkit-tap-highlight-color:transparent]',
+    'transition-colors duration-150 ease-in-out',
+    'enabled:cursor-pointer disabled:cursor-not-allowed disabled:opacity-40',
+    'focus-visible:outline focus-visible:outline-2 focus-visible:outline-[var(--ds-focus-color)] focus-visible:outline-offset-2',
+  ],
+  {
+    variants: {
+      variant: {
+        tertiary:
+          'text-gray-900 enabled:hover:bg-gray-alpha-200 enabled:hover:text-gray-1000 enabled:active:bg-gray-alpha-200 focus-visible:text-gray-1000',
+        muted:
+          'text-gray-900 enabled:hover:bg-gray-alpha-200 enabled:hover:text-gray-1000 enabled:active:bg-gray-alpha-200 focus-visible:text-gray-1000',
+      },
+      size: {
+        tiny: 'h-6 w-6 rounded-[4px] [&_svg]:h-4 [&_svg]:w-4',
+        small: 'h-8 w-8 rounded-md [&_svg]:h-4 [&_svg]:w-4',
+      },
+    },
+    defaultVariants: {
+      variant: 'tertiary',
+      size: 'tiny',
+    },
+  }
+);
+
+export type IconButtonProps = Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  'type'
+> &
+  VariantProps<typeof iconButtonVariants> & {
+    'aria-label': string;
+    type?: 'button' | 'submit' | 'reset';
+  };
+
+export const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
+  ({ className, variant, size, type = 'button', ...props }, ref) => (
+    <button
+      ref={ref}
+      type={type}
+      className={cn(iconButtonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+);
+IconButton.displayName = 'IconButton';
+
+export { iconButtonVariants };

package/src/components/ui/inspector-theme.ts

@@ -1,17 +1,16 @@
 /**
  * Shared theme configuration for react-inspector's ObjectInspector.
  *
- * Color choices are inspired by Node.js `util.inspect()` ANSI stylizing:
- *   - property names: unstyled (default foreground — dark text on light, light text on dark)
- *   - strings / symbols: green
- *   - numbers / booleans / bigint: yellow
- *   - null: bold (foreground)
- *   - undefined: grey
- *   - regexp: red
- *   - functions (special): cyan
- *   - date: magenta
+ * Colors follow Geist's Shiki JSON palette so the inspector reads the same
+ * as highlighted code blocks across the product:
+ *   - property names / punctuation: --ds-gray-1000 (default foreground)
+ *   - strings / numbers / booleans: --ds-green-900
+ *   - null / undefined: --ds-gray-900 (muted)
+ *   - regexp / function: --ds-purple-900
+ *   - date: --ds-pink-900
  *
- * See: https://github.com/nodejs/node/blob/main/lib/internal/util/inspect.js
+ * Because the `--ds-*` tokens adapt to theme automatically, the light and
+ * dark objects are intentionally identical.
  */
 
 // ---------------------------------------------------------------------------
@@ -25,11 +24,11 @@ export interface InspectorThemeExtended {
 }
 
 export const inspectorThemeExtendedLight: InspectorThemeExtended = {
-  OBJECT_VALUE_DATE_COLOR: '#a21caf', // fuchsia-700
+  OBJECT_VALUE_DATE_COLOR: 'var(--ds-pink-900)',
 };
 
 export const inspectorThemeExtendedDark: InspectorThemeExtended = {
-  OBJECT_VALUE_DATE_COLOR: '#e879f9', // fuchsia-400
+  OBJECT_VALUE_DATE_COLOR: 'var(--ds-pink-900)',
 };
 
 // ---------------------------------------------------------------------------
@@ -57,96 +56,55 @@ const shared = {
 // Light theme
 // ---------------------------------------------------------------------------
 
-export const inspectorThemeLight = {
+const geistTheme = {
   ...shared,
 
   // Base text
   BASE_COLOR: 'var(--ds-gray-1000)',
 
-  // Property names — unstyled, same as base foreground (Node: no style)
-  OBJECT_NAME_COLOR: 'var(--ds-gray-900)',
+  // Property names — default foreground (matches JSON key color in Geist Shiki)
+  OBJECT_NAME_COLOR: 'var(--ds-gray-1000)',
 
-  // Strings & symbols — green (Node: 'green')
-  OBJECT_VALUE_STRING_COLOR: '#16a34a', // green-600
-  OBJECT_VALUE_SYMBOL_COLOR: '#16a34a',
+  // Strings & symbols — green
+  OBJECT_VALUE_STRING_COLOR: 'var(--ds-green-900)',
+  OBJECT_VALUE_SYMBOL_COLOR: 'var(--ds-green-900)',
 
-  // Numbers & booleans — yellow/amber (Node: 'yellow')
-  OBJECT_VALUE_NUMBER_COLOR: '#b45309', // amber-700 (readable on white)
-  OBJECT_VALUE_BOOLEAN_COLOR: '#b45309',
+  // Numbers & booleans — green (Geist JSON tokens)
+  OBJECT_VALUE_NUMBER_COLOR: 'var(--ds-green-900)',
+  OBJECT_VALUE_BOOLEAN_COLOR: 'var(--ds-green-900)',
 
-  // null — bold foreground (Node: 'bold')
+  // null — muted foreground
   OBJECT_VALUE_NULL_COLOR: 'var(--ds-gray-900)',
 
-  // undefined — grey (Node: 'grey')
-  OBJECT_VALUE_UNDEFINED_COLOR: 'var(--ds-gray-500)',
+  // undefined — muted foreground
+  OBJECT_VALUE_UNDEFINED_COLOR: 'var(--ds-gray-900)',
 
-  // RegExp — red (Node regexp base uses green/red/yellow palette)
-  OBJECT_VALUE_REGEXP_COLOR: '#dc2626', // red-600
+  // RegExp — purple
+  OBJECT_VALUE_REGEXP_COLOR: 'var(--ds-purple-900)',
 
-  // Functions — cyan (Node: 'special' → 'cyan')
-  OBJECT_VALUE_FUNCTION_PREFIX_COLOR: '#0891b2', // cyan-600
+  // Functions — purple
+  OBJECT_VALUE_FUNCTION_PREFIX_COLOR: 'var(--ds-purple-900)',
 
-  // HTML (less relevant for data inspection, but reasonable defaults)
-  HTML_TAG_COLOR: 'var(--ds-gray-500)',
-  HTML_TAGNAME_COLOR: '#0891b2',
-  HTML_ATTRIBUTE_NAME_COLOR: '#b45309',
-  HTML_ATTRIBUTE_VALUE_COLOR: '#16a34a',
-  HTML_COMMENT_COLOR: 'var(--ds-gray-400)',
-  HTML_DOCTYPE_COLOR: 'var(--ds-gray-400)',
+  // HTML (rarely used here, kept consistent with the palette)
+  HTML_TAG_COLOR: 'var(--ds-gray-900)',
+  HTML_TAGNAME_COLOR: 'var(--ds-blue-900)',
+  HTML_ATTRIBUTE_NAME_COLOR: 'var(--ds-amber-900)',
+  HTML_ATTRIBUTE_VALUE_COLOR: 'var(--ds-green-900)',
+  HTML_COMMENT_COLOR: 'var(--ds-gray-700)',
+  HTML_DOCTYPE_COLOR: 'var(--ds-gray-700)',
 
   // Structural
-  ARROW_COLOR: 'var(--ds-gray-500)',
+  ARROW_COLOR: 'var(--ds-gray-700)',
   TABLE_BORDER_COLOR: 'var(--ds-gray-300)',
   TABLE_TH_BACKGROUND_COLOR: 'var(--ds-gray-100)',
   TABLE_TH_HOVER_COLOR: 'var(--ds-gray-200)',
-  TABLE_SORT_ICON_COLOR: 'var(--ds-gray-500)',
+  TABLE_SORT_ICON_COLOR: 'var(--ds-gray-700)',
 };
 
+export const inspectorThemeLight = geistTheme;
+
 // ---------------------------------------------------------------------------
 // Dark theme
 // ---------------------------------------------------------------------------
 
-export const inspectorThemeDark = {
-  ...shared,
-
-  // Base text
-  BASE_COLOR: 'var(--ds-gray-1000)',
-
-  // Property names — white/light foreground (Node: unstyled = white in dark terminal)
-  OBJECT_NAME_COLOR: 'var(--ds-gray-900)',
-
-  // Strings & symbols — green (Node: 'green')
-  OBJECT_VALUE_STRING_COLOR: '#4ade80', // green-400
-  OBJECT_VALUE_SYMBOL_COLOR: '#4ade80',
-
-  // Numbers & booleans — yellow (Node: 'yellow')
-  OBJECT_VALUE_NUMBER_COLOR: '#facc15', // yellow-400
-  OBJECT_VALUE_BOOLEAN_COLOR: '#facc15',
-
-  // null — bold foreground / white (Node: 'bold')
-  OBJECT_VALUE_NULL_COLOR: 'var(--ds-gray-1000)',
-
-  // undefined — grey (Node: 'grey')
-  OBJECT_VALUE_UNDEFINED_COLOR: 'var(--ds-gray-500)',
-
-  // RegExp — red (Node regexp palette)
-  OBJECT_VALUE_REGEXP_COLOR: '#f87171', // red-400
-
-  // Functions — cyan (Node: 'special' → 'cyan')
-  OBJECT_VALUE_FUNCTION_PREFIX_COLOR: '#22d3ee', // cyan-400
-
-  // HTML
-  HTML_TAG_COLOR: 'var(--ds-gray-500)',
-  HTML_TAGNAME_COLOR: '#22d3ee',
-  HTML_ATTRIBUTE_NAME_COLOR: '#facc15',
-  HTML_ATTRIBUTE_VALUE_COLOR: '#4ade80',
-  HTML_COMMENT_COLOR: 'var(--ds-gray-500)',
-  HTML_DOCTYPE_COLOR: 'var(--ds-gray-500)',
-
-  // Structural
-  ARROW_COLOR: 'var(--ds-gray-500)',
-  TABLE_BORDER_COLOR: 'var(--ds-gray-300)',
-  TABLE_TH_BACKGROUND_COLOR: 'var(--ds-gray-100)',
-  TABLE_TH_HOVER_COLOR: 'var(--ds-gray-200)',
-  TABLE_SORT_ICON_COLOR: 'var(--ds-gray-500)',
-};
+export const inspectorThemeDark = geistTheme;

package/src/components/ui/kbd.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import { cn } from '../../lib/utils';
+
+export function Kbd({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}): ReactNode {
+  return (
+    <kbd
+      className={cn(
+        'inline-flex h-5 min-w-5 items-center justify-center rounded bg-background-100/20 px-1 text-center font-sans text-xs leading-none',
+        className
+      )}
+    >
+      {children}
+    </kbd>
+  );
+}

package/src/components/ui/tooltip.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import * as React from 'react';
+import { cn } from '../../lib/utils';
+
+const TooltipProvider = TooltipPrimitive.Provider;
+
+const Tooltip = TooltipPrimitive.Root;
+
+const TooltipTrigger = TooltipPrimitive.Trigger;
+
+const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content> & {
+    showArrow?: boolean;
+  }
+>(
+  (
+    { className, sideOffset = 8, showArrow = true, children, ...props },
+    ref
+  ) => (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        ref={ref}
+        sideOffset={sideOffset}
+        className={cn(
+          'z-[99999] flex items-center gap-1 rounded-[10px] bg-gray-1000 px-2 py-1.5 !text-label-13 text-background-100 shadow-md select-none',
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showArrow ? (
+          <TooltipPrimitive.Arrow
+            width={11}
+            height={5}
+            className="fill-gray-1000"
+          />
+        ) : null}
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  )
+);
+TooltipContent.displayName = TooltipPrimitive.Content.displayName;
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };

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

@@ -17,6 +17,7 @@ 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, type TraceWithMeta } from '../lib/trace-builder';
 import { ErrorBoundary } from './error-boundary';
 import {
   EntityDetailPanel,
@@ -36,7 +37,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
@@ -767,6 +767,7 @@ export const WorkflowTraceViewer = ({
   onResolveHook,
   onCancelRun,
   onStreamClick,
+  onRunClick,
   onSpanSelect,
   onLoadEventData,
   onLoadMoreSpans,
@@ -796,6 +797,8 @@ export const WorkflowTraceViewer = ({
   onCancelRun?: (runId: string) => Promise<void>;
   /** Callback when a stream reference is clicked in the detail panel */
   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) */
@@ -903,6 +906,12 @@ export const WorkflowTraceViewer = ({
     });
   }, [events, selectedSpan?.spanId]);
 
+  // Reset selected span when navigating to a different run
+  useEffect(() => {
+    setSelectedSpan(null);
+    setDeselectTrigger((n) => n + 1);
+  }, [run?.runId]);
+
   const handleClose = useCallback(() => {
     setSelectedSpan(null);
     setDeselectTrigger((n) => n + 1);
@@ -965,7 +974,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
@@ -1140,6 +1149,7 @@ export const WorkflowTraceViewer = ({
               <EntityDetailPanel
                 run={run}
                 onStreamClick={onStreamClick}
+                onRunClick={onRunClick}
                 spanDetailData={spanDetailData ?? null}
                 spanDetailError={spanDetailError}
                 spanDetailLoading={spanDetailLoading}

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

@@ -59,7 +59,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 +73,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 +83,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);
@@ -225,7 +243,7 @@ export function stepToSpan(stepEvents: Event[], maxEndTime: Date): Span | null {
 
   return {
     spanId: String(step.stepId),
-    name: parsedName?.shortName ?? '',
+    name: parsedName?.shortName ?? String(step.stepName),
     kind: 1, // INTERNAL span kind
     resource,
     library: WORKFLOW_LIBRARY,
@@ -296,7 +314,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,
@@ -40,6 +47,7 @@ export {
   ENCRYPTED_PLACEHOLDER,
   extractStreamIds,
   getWebRevivers,
+  hasEncryptedFields,
   hydrateResourceIO,
   hydrateResourceIOWithKey,
   isClassInstanceRef,
@@ -49,6 +57,7 @@ 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';

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