improvement(ux): streaming

Author: emir-karabeg

apps/sim/app/workspace/[workspaceId]/home/components/message-content/components/agent-group/agent-group.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { ChevronDown } from '@/components/emcn'
 import { cn } from '@/lib/core/utils/cn'
 import type { ToolCallStatus } from '../../../../types'
@@ -18,12 +18,39 @@ interface AgentGroupProps {
   agentName: string
   agentLabel: string
   tools: ToolCallData[]
+  autoCollapse?: boolean
 }
 
-export function AgentGroup({ agentName, agentLabel, tools }: AgentGroupProps) {
+const FADE_MS = 300
+
+export function AgentGroup({
+  agentName,
+  agentLabel,
+  tools,
+  autoCollapse = false,
+}: AgentGroupProps) {
   const AgentIcon = getAgentIcon(agentName)
-  const [expanded, setExpanded] = useState(true)
   const hasTools = tools.length > 0
+  const allDone = hasTools && tools.every((t) => t.status === 'success' || t.status === 'error')
+
+  const [expanded, setExpanded] = useState(!allDone)
+  const [mounted, setMounted] = useState(!allDone)
+  const didAutoCollapseRef = useRef(allDone)
+
+  useEffect(() => {
+    if (!autoCollapse || didAutoCollapseRef.current) return
+    didAutoCollapseRef.current = true
+    setExpanded(false)
+  }, [autoCollapse])
+
+  useEffect(() => {
+    if (expanded) {
+      setMounted(true)
+      return
+    }
+    const timer = setTimeout(() => setMounted(false), FADE_MS)
+    return () => clearTimeout(timer)
+  }, [expanded])
 
   return (
     <div className='flex flex-col gap-1.5'>
@@ -47,8 +74,13 @@ export function AgentGroup({ agentName, agentLabel, tools }: AgentGroupProps) {
           />
         )}
       </button>
-      {hasTools && expanded && (
-        <div className='flex flex-col gap-1.5'>
+      {hasTools && mounted && (
+        <div
+          className={cn(
+            'flex flex-col gap-1.5 transition-opacity duration-300 ease-out',
+            expanded ? 'opacity-100' : 'opacity-0'
+          )}
+        >
           {tools.map((tool) => (
             <ToolCallItem
               key={tool.id}

apps/sim/app/workspace/[workspaceId]/home/components/message-content/components/chat-content/chat-content.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { Children, type ComponentPropsWithoutRef, isValidElement } from 'react'
+import { Children, type ComponentPropsWithoutRef, isValidElement, useMemo } from 'react'
 import ReactMarkdown from 'react-markdown'
 import remarkGfm from 'remark-gfm'
 import 'prismjs/components/prism-typescript'
@@ -10,6 +10,7 @@ import 'prismjs/components/prism-markup'
 import '@/components/emcn/components/code/code.css'
 import { Checkbox, highlight, languages } from '@/components/emcn'
 import { cn } from '@/lib/core/utils/cn'
+import { useStreamingReveal } from '@/app/workspace/[workspaceId]/home/hooks/use-streaming-reveal'
 import { useThrottledValue } from '@/hooks/use-throttled-value'
 
 const REMARK_PLUGINS = [remarkGfm]
@@ -177,15 +178,39 @@ const MARKDOWN_COMPONENTS: React.ComponentProps<typeof ReactMarkdown>['component
 
 interface ChatContentProps {
   content: string
+  isStreaming?: boolean
 }
 
-export function ChatContent({ content }: ChatContentProps) {
-  const throttled = useThrottledValue(content)
+const STREAMING_THROTTLE_MS = 50
+
+export function ChatContent({ content, isStreaming = false }: ChatContentProps) {
+  const throttled = useThrottledValue(content, isStreaming ? STREAMING_THROTTLE_MS : undefined)
+  const rendered = isStreaming ? throttled : content
+  const { committed, incoming, generation } = useStreamingReveal(rendered, isStreaming)
+
+  const committedMarkdown = useMemo(
+    () =>
+      committed ? (
+        <ReactMarkdown remarkPlugins={REMARK_PLUGINS} components={MARKDOWN_COMPONENTS}>
+          {committed}
+        </ReactMarkdown>
+      ) : null,
+    [committed]
+  )
+
   return (
     <div className={PROSE_CLASSES}>
-      <ReactMarkdown remarkPlugins={REMARK_PLUGINS} components={MARKDOWN_COMPONENTS}>
-        {throttled}
-      </ReactMarkdown>
+      {committedMarkdown}
+      {incoming && (
+        <div
+          key={generation}
+          className={cn(isStreaming && 'animate-stream-fade-in', '[&>:first-child]:mt-0')}
+        >
+          <ReactMarkdown remarkPlugins={REMARK_PLUGINS} components={MARKDOWN_COMPONENTS}>
+            {incoming}
+          </ReactMarkdown>
+        </div>
+      )}
     </div>
   )
 }

apps/sim/app/workspace/[workspaceId]/home/components/message-content/message-content.tsx

@@ -179,7 +179,12 @@ interface MessageContentProps {
   onOptionSelect?: (id: string) => void
 }
 
-export function MessageContent({ blocks, fallbackContent, onOptionSelect }: MessageContentProps) {
+export function MessageContent({
+  blocks,
+  fallbackContent,
+  isStreaming = false,
+  onOptionSelect,
+}: MessageContentProps) {
   const parsed = blocks.length > 0 ? parseBlocks(blocks) : []
 
   const segments: MessageSegment[] =
@@ -196,18 +201,34 @@ export function MessageContent({ blocks, fallbackContent, onOptionSelect }: Mess
       {segments.map((segment, i) => {
         switch (segment.type) {
           case 'text':
-            return <ChatContent key={`text-${i}`} content={segment.content} />
-          case 'agent_group':
             return (
-              <AgentGroup
-                key={segment.id}
-                agentName={segment.agentName}
-                agentLabel={segment.agentLabel}
-                tools={segment.tools}
-              />
+              <ChatContent key={`text-${i}`} content={segment.content} isStreaming={isStreaming} />
             )
+          case 'agent_group': {
+            const allToolsDone =
+              segment.tools.length > 0 &&
+              segment.tools.every((t) => t.status === 'success' || t.status === 'error')
+            const hasFollowingText = segments.slice(i + 1).some((s) => s.type === 'text')
+            return (
+              <div key={segment.id} className={isStreaming ? 'animate-stream-fade-in' : undefined}>
+                <AgentGroup
+                  agentName={segment.agentName}
+                  agentLabel={segment.agentLabel}
+                  tools={segment.tools}
+                  autoCollapse={allToolsDone && hasFollowingText}
+                />
+              </div>
+            )
+          }
           case 'options':
-            return <Options key={`options-${i}`} items={segment.items} onSelect={onOptionSelect} />
+            return (
+              <div
+                key={`options-${i}`}
+                className={isStreaming ? 'animate-stream-fade-in' : undefined}
+              >
+                <Options items={segment.items} onSelect={onOptionSelect} />
+              </div>
+            )
         }
       })}
     </div>

apps/sim/app/workspace/[workspaceId]/home/components/mothership-view/mothership-view.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import { cn } from '@/lib/core/utils/cn'
 import type { MothershipResource } from '@/app/workspace/[workspaceId]/home/types'
 import { ResourceContent, ResourceTabs } from './components'
 
@@ -8,6 +9,7 @@ interface MothershipViewProps {
   resources: MothershipResource[]
   activeResourceId: string | null
   onSelectResource: (id: string) => void
+  className?: string
 }
 
 /**
@@ -20,11 +22,17 @@ export function MothershipView({
   resources,
   activeResourceId,
   onSelectResource,
+  className,
 }: MothershipViewProps) {
   const active = resources.find((r) => r.id === activeResourceId) ?? resources[0] ?? null
 
   return (
-    <div className='flex h-full w-[50%] min-w-[400px] flex-col border-[var(--border)] border-l'>
+    <div
+      className={cn(
+        'flex h-full w-[50%] min-w-[400px] flex-col border-[var(--border)] border-l',
+        className
+      )}
+    >
       <ResourceTabs
         resources={resources}
         activeId={active?.id ?? null}

apps/sim/app/workspace/[workspaceId]/home/home.tsx

@@ -12,6 +12,7 @@ import {
   LandingWorkflowSeedStorage,
 } from '@/lib/core/utils/browser-storage'
 import { persistImportedWorkflow } from '@/lib/workflows/operations/import-export'
+import { useSidebarStore } from '@/stores/sidebar/store'
 import { MessageContent, MothershipView, UserInput } from './components'
 import type { FileAttachmentForApi } from './components/user-input/user-input'
 import { useChat } from './hooks'
@@ -111,6 +112,17 @@ export function Home({ chatId }: HomeProps = {}) {
     setActiveResourceId,
   } = useChat(workspaceId, chatId)
 
+  const prevResourceCountRef = useRef(resources.length)
+  const animateResourcePanel =
+    prevResourceCountRef.current === 0 && resources.length > 0 && isSending
+  useEffect(() => {
+    if (animateResourcePanel) {
+      const { isCollapsed, toggleCollapsed } = useSidebarStore.getState()
+      if (!isCollapsed) toggleCollapsed()
+    }
+    prevResourceCountRef.current = resources.length
+  })
+
   const handleSubmit = useCallback(
     (fileAttachments?: FileAttachmentForApi[]) => {
       const trimmed = inputValue.trim()
@@ -209,6 +221,7 @@ export function Home({ chatId }: HomeProps = {}) {
           resources={resources}
           activeResourceId={activeResourceId}
           onSelectResource={setActiveResourceId}
+          className={animateResourcePanel ? 'animate-slide-in-right' : undefined}
         />
       )}
     </div>

apps/sim/app/workspace/[workspaceId]/home/hooks/index.ts

@@ -1,3 +1,4 @@
 export { useAnimatedPlaceholder } from './use-animated-placeholder'
 export type { UseChatReturn } from './use-chat'
 export { useChat } from './use-chat'
+export { useStreamingReveal } from './use-streaming-reveal'

apps/sim/app/workspace/[workspaceId]/home/hooks/use-streaming-reveal.ts

@@ -0,0 +1,86 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+
+/**
+ * Finds the last paragraph break (`\n\n`) that is not inside a fenced code
+ * block. Returns the index immediately after the break — the start of the
+ * next paragraph — so the caller can slice cleanly.
+ */
+function findSafeSplitPoint(content: string): number {
+  let inCodeBlock = false
+  let lastSafeBreak = 0
+  let i = 0
+
+  while (i < content.length) {
+    if (content[i] === '`' && content[i + 1] === '`' && content[i + 2] === '`') {
+      inCodeBlock = !inCodeBlock
+      i += 3
+      continue
+    }
+
+    if (!inCodeBlock && content[i] === '\n' && content[i + 1] === '\n') {
+      lastSafeBreak = i + 2
+      i += 2
+      continue
+    }
+
+    i++
+  }
+
+  return lastSafeBreak
+}
+
+interface StreamingRevealResult {
+  /** Stable head — paragraphs that have fully arrived. Ideal for memoisation. */
+  committed: string
+  /** Active tail — the paragraph currently being streamed, animated on mount. */
+  incoming: string
+  /** Increments each time committed advances; use as React key to retrigger the fade animation. */
+  generation: number
+}
+
+/**
+ * Splits streaming markdown into a stable *committed* head and an animated
+ * *incoming* tail. The split always occurs at a paragraph boundary (`\n\n`)
+ * that is outside fenced code blocks, so both halves are valid markdown.
+ *
+ * Committed content changes infrequently (only at paragraph breaks), making
+ * it safe to wrap in `useMemo`. The incoming tail is small and re-renders at
+ * the caller's throttle rate.
+ *
+ * The split is preserved after streaming ends to prevent layout shifts caused
+ * by DOM restructuring. It only resets when content clears (new message).
+ */
+export function useStreamingReveal(content: string, isStreaming: boolean): StreamingRevealResult {
+  const [committedEnd, setCommittedEnd] = useState(0)
+  const [generation, setGeneration] = useState(0)
+  const prevSplitRef = useRef(0)
+
+  useEffect(() => {
+    if (content.length === 0) {
+      prevSplitRef.current = 0
+      setCommittedEnd(0)
+      return
+    }
+
+    if (!isStreaming) return
+
+    const splitPoint = findSafeSplitPoint(content)
+    if (splitPoint > prevSplitRef.current) {
+      prevSplitRef.current = splitPoint
+      setCommittedEnd(splitPoint)
+      setGeneration((g) => g + 1)
+    }
+  }, [content, isStreaming])
+
+  if (committedEnd > 0 && committedEnd < content.length) {
+    return {
+      committed: content.slice(0, committedEnd),
+      incoming: content.slice(committedEnd),
+      generation,
+    }
+  }
+
+  return { committed: content, incoming: '', generation }
+}

apps/sim/hooks/use-throttled-value.ts

@@ -2,24 +2,28 @@
 
 import { useEffect, useRef, useState } from 'react'
 
-const TEXT_RENDER_THROTTLE_MS = 100
+const DEFAULT_THROTTLE_MS = 100
 
 /**
  * Trailing-edge throttle for rendered string values.
  *
  * The underlying data accumulates instantly via the caller's state, but this
- * hook gates DOM re-renders to at most every {@link TEXT_RENDER_THROTTLE_MS}ms.
+ * hook gates DOM re-renders to at most every `intervalMs` milliseconds.
  * When streaming stops (i.e. the value settles), the final value is flushed
  * immediately so no trailing content is lost.
+ *
+ * @param value      The raw string that may update very frequently.
+ * @param intervalMs Throttle window in ms. Lower values = smoother updates
+ *                   at the cost of more renders. Defaults to 100ms.
  */
-export function useThrottledValue(value: string): string {
+export function useThrottledValue(value: string, intervalMs = DEFAULT_THROTTLE_MS): string {
   const [displayed, setDisplayed] = useState(value)
   const lastFlushRef = useRef(0)
   const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
 
   useEffect(() => {
     const now = Date.now()
-    const remaining = TEXT_RENDER_THROTTLE_MS - (now - lastFlushRef.current)
+    const remaining = intervalMs - (now - lastFlushRef.current)
 
     if (remaining <= 0) {
       if (timerRef.current !== undefined) {
@@ -44,7 +48,7 @@ export function useThrottledValue(value: string): string {
         timerRef.current = undefined
       }
     }
-  }, [value])
+  }, [value, intervalMs])
 
   return displayed
 }