@flikk/ui 1.0.0-beta.30 → 1.0.0-beta.32

package/dist/components/ai/StreamingResponse/AnimatedText.js

@@ -1,8 +1,8 @@
 "use client";
-import { jsx, jsxs } from 'react/jsx-runtime';
-import { useRef, useMemo } from 'react';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { useMemo, useRef } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
-import { tokenTransition, tokenFadeIn } from './StreamingResponse.animations.js';
+import { getTokenFadeIn } from './StreamingResponse.animations.js';
 
 /**
  * Splits text into tokens (words) preserving whitespace
@@ -18,9 +18,10 @@ const tokenize = (text) => {
  * For performance, only the last N tokens are animated with motion.span,
  * while older tokens are rendered as static text.
  */
-const AnimatedText = ({ text, isStreaming, animateLastN = 12, enabled = true, className, }) => {
+const AnimatedText = ({ text, isStreaming, animateLastN = 12, enabled = true, className, cursor, tokenEffect = 'fade', tokenDuration = 0.12, }) => {
     const shouldReduceMotion = useReducedMotion();
-    const animate = enabled && !shouldReduceMotion;
+    const animate = enabled && tokenEffect !== 'none' && !shouldReduceMotion;
+    const tokenVariants = useMemo(() => getTokenFadeIn(tokenEffect), [tokenEffect]);
     // Track which tokens have already been seen/animated
     const settledCountRef = useRef(0);
     const tokens = useMemo(() => tokenize(text), [text]);
@@ -38,9 +39,9 @@ const AnimatedText = ({ text, isStreaming, animateLastN = 12, enabled = true, cl
     const animatedTokens = tokens.slice(settledCount);
     if (!animate || !isStreaming) {
         // No animation: render plain text
-        return (jsx("p", { className: className || 'whitespace-pre-wrap wrap-break-word', children: text }));
+        return (jsxs("p", { className: className || 'whitespace-pre-wrap wrap-break-word', children: [text, cursor] }));
     }
-    return (jsxs("p", { className: className || 'whitespace-pre-wrap wrap-break-word', children: [settledText, animatedTokens.map((token, i) => (jsx(motion.span, { variants: tokenFadeIn, initial: "hidden", animate: "visible", transition: tokenTransition, style: { display: 'inline' }, children: token }, `${settledCount + i}-${token}`)))] }));
+    return (jsxs("p", { className: className || 'whitespace-pre-wrap wrap-break-word', children: [settledText, animatedTokens.map((token, i) => (jsx(motion.span, { variants: tokenVariants, initial: "hidden", animate: "visible", transition: { duration: tokenDuration, ease: [0, 0, 0.2, 1] }, style: { display: 'inline' }, children: token }, `${settledCount + i}-${token}`))), cursor] }));
 };
 AnimatedText.displayName = 'AnimatedText';
 

package/dist/components/ai/StreamingResponse/ErrorDisplay.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
-import { ExclamationCircleIcon } from '@heroicons/react/24/outline';
+import { WarningCircle } from '@phosphor-icons/react';
 import { cn } from '../../../utils/cn.js';
 import { streamingResponseTheme } from './StreamingResponse.theme.js';
 
@@ -29,7 +29,7 @@ const getErrorTitle = (type) => {
  */
 const ErrorDisplay = ({ error, onRetry, retryAttempt, maxAttempts, className, }) => {
     const canRetry = error.retryable && retryAttempt < maxAttempts;
-    return (jsxs("div", { className: cn(streamingResponseTheme.errorContainerStyle, className), role: "alert", "aria-live": "assertive", children: [jsx(ExclamationCircleIcon, { className: "size-5 text-[var(--color-danger)] flex-shrink-0" }), jsxs("div", { className: "flex-1", children: [jsx("p", { className: cn(streamingResponseTheme.errorTitleStyle), children: getErrorTitle(error.type) }), jsx("p", { className: cn(streamingResponseTheme.errorMessageStyle), children: error.message }), canRetry && (jsxs("button", { onClick: onRetry, className: cn(streamingResponseTheme.errorRetryButtonStyle), type: "button", children: ["Retry (", retryAttempt + 1, "/", maxAttempts, ")"] }))] })] }));
+    return (jsxs("div", { className: cn(streamingResponseTheme.errorContainerStyle, className), role: "alert", "aria-live": "assertive", children: [jsx(WarningCircle, { className: "size-5 text-[var(--color-danger)] flex-shrink-0" }), jsxs("div", { className: "flex-1", children: [jsx("p", { className: cn(streamingResponseTheme.errorTitleStyle), children: getErrorTitle(error.type) }), jsx("p", { className: cn(streamingResponseTheme.errorMessageStyle), children: error.message }), canRetry && (jsxs("button", { onClick: onRetry, className: cn(streamingResponseTheme.errorRetryButtonStyle), type: "button", children: ["Retry (", retryAttempt + 1, "/", maxAttempts, ")"] }))] })] }));
 };
 ErrorDisplay.displayName = 'ErrorDisplay';
 

package/dist/components/ai/StreamingResponse/MarkdownRenderer.d.ts

@@ -6,6 +6,7 @@
  */
 import React from 'react';
 import type { MarkdownOptions } from './StreamingResponse.types';
+import type { StreamingTokenEffect } from './StreamingResponse.types';
 export interface MarkdownRendererProps {
     /** Markdown content to render */
     content: string;
@@ -19,6 +20,10 @@ export interface MarkdownRendererProps {
     showCursor?: boolean;
     /** Number of recent words to animate (default: 6) */
     animateLastN?: number;
+    /** Visual treatment for newly arrived words */
+    tokenEffect?: StreamingTokenEffect;
+    /** New-word transition duration in seconds */
+    tokenDuration?: number;
 }
 /**
  * MarkdownRenderer component for rendering markdown with syntax highlighting

package/dist/components/ai/StreamingResponse/MarkdownRenderer.js

@@ -52,7 +52,7 @@ const SkipWords = ({ children }) => {
  * Supports GitHub Flavored Markdown (tables, task lists, strikethrough, etc.)
  * Animates individual words during streaming with a fade-in + blur effect
  */
-const MarkdownRenderer = ({ content, options = {}, isStreaming = false, animated = true, showCursor = true, animateLastN = 12, }) => {
+const MarkdownRenderer = ({ content, options = {}, isStreaming = false, animated = true, showCursor = true, animateLastN = 12, tokenEffect = 'fade', tokenDuration = 0.12, }) => {
     const { allowHtml = false, syntaxTheme = 'light', renderCodeBlock } = options;
     const shouldReduceMotion = useReducedMotion();
     const shouldAnimate = animated && isStreaming && !shouldReduceMotion;
@@ -111,7 +111,7 @@ const MarkdownRenderer = ({ content, options = {}, isStreaming = false, animated
         },
         // Blockquotes — word-level animation
         blockquote({ children }) {
-            return (jsx("blockquote", { className: "border-l-4 border-(--color-primary) pl-4 py-2 my-3 bg-(--color-background-secondary) italic text-(--color-text-secondary)", children: children }));
+            return (jsx("blockquote", { className: "border-l-4 border-(--color-primary) pl-4 py-2 my-3 bg-(--color-surface) italic text-(--color-text-secondary)", children: children }));
         },
         // Links
         a({ href, children }) {
@@ -122,7 +122,7 @@ const MarkdownRenderer = ({ content, options = {}, isStreaming = false, animated
             return (jsxs(AnimatedBlock, { animate: shouldAnimate, children: [jsx(SkipWords, { children: children }), jsx("div", { className: "overflow-x-auto my-3", children: jsx("table", { className: "min-w-full border-collapse border border-(--color-border)", children: children }) })] }));
         },
         thead({ children }) {
-            return jsx("thead", { className: "bg-(--color-background-secondary)", children: children });
+            return jsx("thead", { className: "bg-(--color-surface)", children: children });
         },
         tbody({ children }) {
             return jsx("tbody", { children: children });
@@ -153,7 +153,7 @@ const MarkdownRenderer = ({ content, options = {}, isStreaming = false, animated
             return jsx("del", { className: "line-through text-(--color-text-secondary)", children: children });
         },
     }), [shouldAnimate, syntaxTheme, renderCodeBlock]);
-    return (jsx(WordAnimationProvider, { content: displayContent, enabled: shouldAnimate, animateLastN: animateLastN, hasCursor: isStreaming && showCursor, children: jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], skipHtml: !allowHtml, components: markdownComponents, children: displayContent }) }));
+    return (jsx(WordAnimationProvider, { content: displayContent, enabled: shouldAnimate, animateLastN: animateLastN, hasCursor: isStreaming && showCursor, tokenEffect: tokenEffect, tokenDuration: tokenDuration, children: jsx(ReactMarkdown, { remarkPlugins: [remarkGfm], skipHtml: !allowHtml, components: markdownComponents, children: displayContent }) }));
 };
 MarkdownRenderer.displayName = 'MarkdownRenderer';
 

package/dist/components/ai/StreamingResponse/StreamingCursor.d.ts

@@ -14,7 +14,7 @@ export interface StreamingCursorProps {
     className?: string;
 }
 /**
- * StreamingCursor renders a premium glowing caret that indicates active streaming.
- * Uses Framer Motion for a smooth breathing scale and opacity animation.
+ * StreamingCursor renders a quiet inline caret that indicates active streaming.
+ * Its held blink avoids the restless pulsing commonly associated with loaders.
  */
 export declare const StreamingCursor: React.FC<StreamingCursorProps>;

package/dist/components/ai/StreamingResponse/StreamingCursor.js

@@ -1,22 +1,25 @@
 "use client";
 import { jsx } from 'react/jsx-runtime';
-import { motion } from 'motion/react';
+import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { cursorPulse } from './StreamingResponse.animations.js';
 
 /**
- * StreamingCursor renders a premium glowing caret that indicates active streaming.
- * Uses Framer Motion for a smooth breathing scale and opacity animation.
+ * StreamingCursor renders a quiet inline caret that indicates active streaming.
+ * Its held blink avoids the restless pulsing commonly associated with loaders.
  */
 const StreamingCursor = ({ visible, enabled = true, cursor = "▏", className, }) => {
+    const shouldReduceMotion = useReducedMotion();
     if (!visible)
         return null;
     const isDefaultCursor = cursor === "▏";
-    if (!enabled) {
-        return isDefaultCursor ? (jsx("span", { className: cn("inline-block ml-1.5 w-2 h-2 rounded-full bg-[var(--color-primary)] align-middle mb-[3px]", className), "aria-hidden": "true" })) : (jsx("span", { className: cn("font-light ml-0.5 text-[var(--color-primary)]", className), "aria-hidden": "true", children: cursor }));
+    const shouldAnimate = enabled && !shouldReduceMotion;
+    if (!shouldAnimate) {
+        return isDefaultCursor ? (jsx("span", { className: cn("ml-0.5 inline-block h-[1.05em] w-px translate-y-[0.14em] rounded-full bg-current text-[var(--color-primary)]", className), "aria-hidden": "true" })) : (jsx("span", { className: cn("font-light ml-0.5 text-[var(--color-primary)]", className), "aria-hidden": "true", children: cursor }));
     }
-    return (jsx(motion.span, { variants: cursorPulse, initial: "initial", animate: "animate", className: cn("inline-block ml-1.5 text-[var(--color-primary)] drop-shadow-[0_0_5px_var(--color-primary-400)]", isDefaultCursor ? "w-2 h-2 rounded-full bg-[var(--color-primary)] align-middle mb-[3px]" : "font-light", className), "aria-hidden": "true", style: {
-            transformOrigin: "center center",
+    return (jsx(motion.span, { variants: cursorPulse, initial: "initial", animate: "animate", className: cn("ml-0.5 inline-block text-[var(--color-primary)]", isDefaultCursor
+            ? "h-[1.05em] w-px translate-y-[0.14em] rounded-full bg-current"
+            : "font-light", className), "aria-hidden": "true", style: {
             display: "inline-block",
         }, children: !isDefaultCursor && cursor }));
 };

package/dist/components/ai/StreamingResponse/StreamingResponse.animations.d.ts

@@ -3,6 +3,16 @@
  * Motion variants for streaming text animations
  */
 import type { Variants, Transition } from 'motion/react';
+import type { StreamingMotionOptions, StreamingMotionPreset, StreamingTokenEffect } from './StreamingResponse.types';
+export interface ResolvedStreamingMotion {
+    enabled: boolean;
+    smoothLayout: boolean;
+    tokenEffect: StreamingTokenEffect;
+    tokenDuration: number;
+    layoutDuration: number;
+}
+export declare const resolveStreamingMotion: (motion?: StreamingMotionPreset | StreamingMotionOptions, animated?: boolean) => ResolvedStreamingMotion;
+export declare const getTokenFadeIn: (effect: StreamingTokenEffect) => Variants;
 /**
  * Token fade-in animation
  * Each new token fades in with a slight upward movement

package/dist/components/ai/StreamingResponse/StreamingResponse.animations.js

@@ -1,9 +1,54 @@
-import { springs, easings } from '../../../theme/animations.js';
+import { easings } from '../../../theme/animations.js';
 
 /**
  * StreamingResponse Animation Variants
  * Motion variants for streaming text animations
  */
+const motionPresets = {
+    none: {
+        enabled: false,
+        smoothLayout: false,
+        tokenEffect: 'none',
+        tokenDuration: 0,
+        layoutDuration: 0,
+    },
+    subtle: {
+        enabled: true,
+        smoothLayout: true,
+        tokenEffect: 'fade',
+        tokenDuration: 0.12,
+        layoutDuration: 0.2,
+    },
+    expressive: {
+        enabled: true,
+        smoothLayout: true,
+        tokenEffect: 'fade-blur',
+        tokenDuration: 0.18,
+        layoutDuration: 0.26,
+    },
+};
+const resolveStreamingMotion = (motion = 'subtle', animated = true) => {
+    if (!animated)
+        return motionPresets.none;
+    if (typeof motion === 'string')
+        return motionPresets[motion];
+    const preset = motionPresets[motion.preset || 'subtle'];
+    return {
+        ...preset,
+        ...motion,
+        enabled: preset.enabled,
+    };
+};
+const getTokenFadeIn = (effect) => ({
+    hidden: {
+        opacity: 0,
+        filter: effect === 'fade-blur' ? 'blur(1px)' : 'blur(0px)',
+    },
+    visible: {
+        opacity: 1,
+        filter: 'blur(0px)',
+    },
+});
 /**
  * Token fade-in animation
  * Each new token fades in with a slight upward movement
@@ -11,17 +56,15 @@ import { springs, easings } from '../../../theme/animations.js';
 const tokenFadeIn = {
     hidden: {
         opacity: 0,
-        y: 3,
-        filter: 'blur(3px)',
+        filter: 'blur(0px)',
     },
     visible: {
         opacity: 1,
-        y: 0,
         filter: 'blur(0px)',
     },
 };
 const tokenTransition = {
-    duration: 0.25,
+    duration: 0.18,
     ease: easings.easeOut,
 };
 /**
@@ -31,15 +74,14 @@ const tokenTransition = {
 const blockSlideIn = {
     hidden: {
         opacity: 0,
-        y: 6,
     },
     visible: {
         opacity: 1,
-        y: 0,
     },
 };
 const blockTransition = {
-    ...springs.smooth,
+    duration: 0.28,
+    ease: easings.easeOut,
 };
 /**
  * Streaming cursor (caret/particle) animation
@@ -47,38 +89,22 @@ const blockTransition = {
  */
 const cursorPulse = {
     initial: {
-        opacity: 0.25,
-        scale: 0.85,
+        opacity: 1,
     },
     animate: {
-        opacity: [1, 0.25, 1],
-        scale: [1.1, 0.85, 1.1],
+        opacity: [1, 1, 0.18, 0.18, 1],
         transition: {
-            duration: 0.8,
+            duration: 1.1,
             repeat: Infinity,
-            ease: 'easeInOut',
+            repeatDelay: 0.05,
+            times: [0, 0.48, 0.5, 0.92, 1],
+            ease: 'linear',
         },
     },
 };
-/**
- * Inline token fade-in animation
- * Used for word-by-word animation inside markdown prose elements
- * No y-movement to prevent layout jitter in inline text
- */
-const inlineTokenFadeIn = {
-    hidden: {
-        opacity: 0,
-        filter: 'blur(3px)',
-    },
-    visible: {
-        opacity: 1,
-        filter: 'blur(0px)',
-    },
-};
-const inlineTokenTransition = {
-    duration: 0.25,
+({
     ease: easings.easeOut,
-};
+});
 /**
  * Container animation for staggered children
  */
@@ -90,4 +116,4 @@ const staggerContainer = {
     },
 };
 
-export { blockSlideIn, blockTransition, cursorPulse, inlineTokenFadeIn, inlineTokenTransition, staggerContainer, tokenFadeIn, tokenTransition };
+export { blockSlideIn, blockTransition, cursorPulse, getTokenFadeIn, resolveStreamingMotion, staggerContainer, tokenFadeIn, tokenTransition };

package/dist/components/ai/StreamingResponse/StreamingResponse.js

@@ -1,19 +1,20 @@
 "use client";
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { useRef, useEffect } from 'react';
+import { jsx } from 'react/jsx-runtime';
+import { useRef, useEffect, useMemo } from 'react';
+import { AnimatePresence, motion } from 'motion/react';
 import { useStreamingSSE } from '../../../hooks/useStreamingSSE.js';
 import { Message } from '../../core/Message/Message.js';
 import { TypeWriter } from '../../core/Message/TypeWriter.js';
 import '../../core/Message/MessageBody.js';
 import '../../../utils/cn.js';
 import '../../core/Link/Link.js';
-import '@heroicons/react/16/solid';
-import '@heroicons/react/24/outline';
-import '@heroicons/react/24/solid';
+import '@phosphor-icons/react';
 import { ErrorDisplay } from './ErrorDisplay.js';
 import { MarkdownRenderer } from './MarkdownRenderer.js';
 import { AnimatedText } from './AnimatedText.js';
 import { StreamingCursor } from './StreamingCursor.js';
+import { StreamingSurface } from './StreamingSurface.js';
+import { resolveStreamingMotion } from './StreamingResponse.animations.js';
 
 /**
  * StreamingResponse component for AI/LLM streaming responses
@@ -37,9 +38,9 @@ url, method = 'POST', headers, body, format = 'openai', autoStart = true,
 // Callbacks
 onToken, onComplete, onError, onStart, onAbort, 
 // Display options
-typingSpeed = 100, enableTypewriter = true, enableMarkdown = true, markdownOptions, 
+typingSpeed = 100, enableTypewriter = false, enableMarkdown = true, markdownOptions, 
 // Animation
-animated = true, showCursor = true, animateLastN = 12, 
+animated = true, showCursor = true, animateLastN = 12, motion: motion$1 = 'subtle', streamingIndicator = false, 
 // Message component props
 role = 'assistant', avatar, showTimestamp = true, showActions = true, onCopy, onRegenerate, 
 // Error handling
@@ -64,6 +65,7 @@ className, }) => {
         onStart,
         onAbort,
     });
+    const resolvedMotion = useMemo(() => resolveStreamingMotion(motion$1, animated), [animated, motion$1]);
     // Determine content to display
     let messageContent;
     if (error && showError) {
@@ -72,11 +74,11 @@ className, }) => {
     }
     else if (enableMarkdown) {
         // Render markdown with block-level slide-in animations and streaming cursor
-        messageContent = (jsx(MarkdownRenderer, { content: accumulatedText, options: markdownOptions, isStreaming: isStreaming, animated: animated, showCursor: showCursor, animateLastN: animateLastN }));
+        messageContent = (jsx(MarkdownRenderer, { content: accumulatedText, options: markdownOptions, isStreaming: isStreaming, animated: resolvedMotion.enabled && resolvedMotion.tokenEffect !== 'none', showCursor: showCursor, animateLastN: animateLastN, tokenEffect: resolvedMotion.tokenEffect, tokenDuration: resolvedMotion.tokenDuration }));
     }
     else if (isStreaming) {
         // During streaming without markdown: use per-token fade-in animation
-        messageContent = (jsxs(Fragment, { children: [jsx(AnimatedText, { text: accumulatedText, isStreaming: isStreaming, enabled: animated }), jsx(StreamingCursor, { visible: showCursor, enabled: animated })] }));
+        messageContent = (jsx(AnimatedText, { text: accumulatedText, isStreaming: isStreaming, animateLastN: animateLastN, enabled: resolvedMotion.enabled, tokenEffect: resolvedMotion.tokenEffect, tokenDuration: resolvedMotion.tokenDuration, cursor: jsx(StreamingCursor, { visible: showCursor, enabled: resolvedMotion.enabled }) }));
     }
     else if (enableTypewriter && isComplete && accumulatedText) {
         // Use typewriter animation after streaming completes
@@ -86,8 +88,10 @@ className, }) => {
         // Show raw text (streaming complete, typewriter disabled)
         messageContent = (jsx("p", { className: "whitespace-pre-wrap wrap-break-word", children: accumulatedText }));
     }
+    const contentState = error && showError ? 'error' : 'content';
+    const animatedContent = (jsx(StreamingSurface, { isStreaming: isStreaming, enabled: resolvedMotion.enabled && resolvedMotion.smoothLayout, duration: resolvedMotion.layoutDuration, children: jsx(AnimatePresence, { initial: false, mode: "popLayout", children: jsx(motion.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 }, transition: { duration: resolvedMotion.enabled ? 0.12 : 0 }, children: messageContent }, contentState) }) }));
     // Render with Message component
-    return (jsx(Message, { role: role, content: messageContent, avatar: avatar, timestamp: startTimeRef.current, showTimestamp: showTimestamp, isStreaming: isStreaming, showActions: showActions && !error, onCopy: onCopy, onRegenerate: onRegenerate, className: className }));
+    return (jsx(Message, { role: role, content: animatedContent, avatar: avatar, timestamp: startTimeRef.current, showTimestamp: showTimestamp, isStreaming: isStreaming, streamingIndicator: streamingIndicator, showActions: showActions && !error, onCopy: onCopy, onRegenerate: onRegenerate, className: className }));
 };
 StreamingResponse.displayName = 'StreamingResponse';
 

package/dist/components/ai/StreamingResponse/StreamingResponse.theme.js

@@ -1,5 +1,7 @@
 const streamingResponseTheme = {
-    errorContainerStyle: "flex items-start gap-3 rounded-[var(--radius-base)] border border-[var(--color-danger-200)] bg-[var(--color-danger-50)] px-4 py-3",
+    // Danger banner — same role as Alert, so it reuses --alert-radius rather
+    // than the bare --radius-base (which would be uncapped at extreme themes).
+    errorContainerStyle: "flex items-start gap-3 rounded-[var(--alert-radius)] border border-[var(--color-danger-200)] bg-[var(--color-danger-50)] px-4 py-3",
     errorTitleStyle: "text-sm font-medium text-[var(--color-danger)]",
     errorMessageStyle: "text-sm text-[var(--color-text-secondary)] mt-1",
     errorRetryButtonStyle: "mt-2 text-sm font-medium text-[var(--color-danger)] hover:text-[var(--color-danger-700)] transition-colors",

package/dist/components/ai/StreamingResponse/StreamingResponse.types.d.ts

@@ -25,6 +25,24 @@ export interface MarkdownOptions {
     /** Custom code block renderer */
     renderCodeBlock?: (code: string, language: string) => ReactNode;
 }
+export type StreamingMotionPreset = "none" | "subtle" | "expressive";
+export type StreamingTokenEffect = "none" | "fade" | "fade-blur";
+/**
+ * High-level motion controls for streamed content.
+ * Presets cover the common cases; individual fields are intended for product-level tuning.
+ */
+export interface StreamingMotionOptions {
+    /** Base motion treatment (default: "subtle") */
+    preset?: StreamingMotionPreset;
+    /** Smooth changes in rendered content height as lines wrap (default: true) */
+    smoothLayout?: boolean;
+    /** Treatment applied only to newly arrived words */
+    tokenEffect?: StreamingTokenEffect;
+    /** New-word transition duration in seconds */
+    tokenDuration?: number;
+    /** Content-height transition duration in seconds */
+    layoutDuration?: number;
+}
 /**
  * Props for StreamingResponse component
  */
@@ -53,7 +71,10 @@ export interface StreamingResponseProps {
     onAbort?: () => void;
     /** Typewriter animation speed in ms per word (default: 100) */
     typingSpeed?: number;
-    /** Enable typewriter animation after streaming completes (default: true) */
+    /**
+     * Replay completed plain text with a typewriter animation (default: false).
+     * Usually unnecessary when the user has already watched the response stream.
+     */
     enableTypewriter?: boolean;
     /** Enable markdown rendering (default: true) */
     enableMarkdown?: boolean;
@@ -63,8 +84,18 @@ export interface StreamingResponseProps {
     animated?: boolean;
     /** Show blinking cursor while streaming (default: true) */
     showCursor?: boolean;
-    /** Number of recent words to animate during streaming (default: 6) */
+    /** Number of recent words to animate during streaming (default: 12) */
     animateLastN?: number;
+    /**
+     * Streaming motion preset or focused overrides (default: "subtle").
+     * `animated={false}` continues to disable all motion for backwards compatibility.
+     */
+    motion?: StreamingMotionPreset | StreamingMotionOptions;
+    /**
+     * Optional footer status shown while streaming. Pass `false` to hide it.
+     * The premium default is false because the inline caret already communicates activity.
+     */
+    streamingIndicator?: ReactNode | false;
     /** Message role (default: 'assistant') */
     role?: MessageRole;
     /** Avatar configuration */

package/dist/components/ai/StreamingResponse/StreamingSurface.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+export interface StreamingSurfaceProps {
+    children: React.ReactNode;
+    isStreaming: boolean;
+    enabled?: boolean;
+    duration?: number;
+    className?: string;
+}
+/**
+ * Smooths intrinsic height changes without scaling or distorting text.
+ * ResizeObserver tracks the natural content height; only the clipping frame animates.
+ */
+export declare const StreamingSurface: React.FC<StreamingSurfaceProps>;

package/dist/components/ai/StreamingResponse/StreamingSurface.js

@@ -0,0 +1,38 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { useRef, useState, useLayoutEffect } from 'react';
+import { useReducedMotion, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { easings } from '../../../theme/animations.js';
+
+/**
+ * Smooths intrinsic height changes without scaling or distorting text.
+ * ResizeObserver tracks the natural content height; only the clipping frame animates.
+ */
+const StreamingSurface = ({ children, isStreaming, enabled = true, duration = 0.22, className, }) => {
+    const contentRef = useRef(null);
+    const hasMeasuredRef = useRef(false);
+    const shouldReduceMotion = useReducedMotion();
+    const [height, setHeight] = useState();
+    const shouldAnimate = enabled && !shouldReduceMotion;
+    useLayoutEffect(() => {
+        const element = contentRef.current;
+        if (!element || typeof ResizeObserver === "undefined")
+            return;
+        const measure = () => {
+            const nextHeight = element.getBoundingClientRect().height;
+            hasMeasuredRef.current = true;
+            setHeight((currentHeight) => currentHeight === nextHeight ? currentHeight : nextHeight);
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, []);
+    return (jsx(motion.div, { initial: false, animate: shouldAnimate && hasMeasuredRef.current && height !== undefined
+            ? { height }
+            : undefined, transition: { duration, ease: easings.easeOut }, className: cn(shouldAnimate && "overflow-hidden", className), style: !shouldAnimate && height !== undefined ? { height: "auto" } : undefined, "aria-busy": isStreaming, "aria-live": isStreaming ? "off" : "polite", children: jsx("div", { ref: contentRef, children: children }) }));
+};
+StreamingSurface.displayName = "StreamingSurface";
+
+export { StreamingSurface };

package/dist/components/ai/StreamingResponse/WordAnimationContext.d.ts

@@ -5,6 +5,7 @@
  * all markdown elements (paragraphs, headings, lists, blockquotes, etc.).
  */
 import React from "react";
+import type { StreamingTokenEffect } from "./StreamingResponse.types";
 interface WordAnimationContextValue {
     /** Process children of a prose element, animating recent words */
     processChildren: (children: React.ReactNode) => React.ReactNode;
@@ -22,6 +23,10 @@ export interface WordAnimationProviderProps {
     animateLastN?: number;
     /** Whether cursor is present in content */
     hasCursor?: boolean;
+    /** Visual treatment for newly arrived words */
+    tokenEffect?: StreamingTokenEffect;
+    /** New-word transition duration in seconds */
+    tokenDuration?: number;
 }
 export declare const WordAnimationProvider: React.FC<WordAnimationProviderProps>;
 export {};

package/dist/components/ai/StreamingResponse/WordAnimationContext.js

@@ -2,7 +2,7 @@
 import { jsx, Fragment } from 'react/jsx-runtime';
 import React__default, { createContext, useRef, useMemo, useContext } from 'react';
 import { motion } from 'motion/react';
-import { inlineTokenTransition, inlineTokenFadeIn } from './StreamingResponse.animations.js';
+import { getTokenFadeIn } from './StreamingResponse.animations.js';
 import { StreamingCursor } from './StreamingCursor.js';
 
 const WordAnimationContext = createContext(null);
@@ -32,7 +32,7 @@ const countWordsInChildren = (children) => {
     });
     return count;
 };
-const WordAnimationProvider = ({ children, content, enabled, animateLastN = 12, hasCursor = false, }) => {
+const WordAnimationProvider = ({ children, content, enabled, animateLastN = 12, hasCursor = false, tokenEffect = "fade", tokenDuration = 0.12, }) => {
     const settledCountRef = useRef(0);
     // Count total prose words in the raw content
     const totalWords = useMemo(() => {
@@ -48,6 +48,7 @@ const WordAnimationProvider = ({ children, content, enabled, animateLastN = 12,
     const wordIndexRef = useRef(0);
     wordIndexRef.current = 0;
     const settledCount = settledCountRef.current;
+    const tokenVariants = useMemo(() => getTokenFadeIn(tokenEffect), [tokenEffect]);
     const contextValue = useMemo(() => {
         if (!enabled) {
             return {
@@ -109,7 +110,7 @@ const WordAnimationProvider = ({ children, content, enabled, animateLastN = 12,
                         staticBuffer = "";
                     }
                     // Animated word
-                    result.push(jsx(motion.span, { variants: inlineTokenFadeIn, initial: "hidden", animate: "visible", transition: inlineTokenTransition, style: { display: "inline" }, children: token }, `word-${currentIndex}-${token.trim()}`));
+                    result.push(jsx(motion.span, { variants: tokenVariants, initial: "hidden", animate: "visible", transition: { duration: tokenDuration, ease: [0, 0, 0.2, 1] }, style: { display: "inline" }, children: token }, `word-${currentIndex}-${token.trim()}`));
                 }
             }
             // Flush any remaining static buffer
@@ -128,7 +129,7 @@ const WordAnimationProvider = ({ children, content, enabled, animateLastN = 12,
         };
         return { processChildren, skipChildren };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [enabled, settledCount, totalWords]);
+    }, [enabled, settledCount, tokenDuration, tokenVariants, totalWords]);
     return (jsx(WordAnimationContext.Provider, { value: contextValue, children: children }));
 };
 WordAnimationProvider.displayName = "WordAnimationProvider";

package/dist/components/ai/StreamingResponse/index.d.ts

@@ -7,11 +7,13 @@ export { ErrorDisplay } from './ErrorDisplay';
 export { MarkdownRenderer } from './MarkdownRenderer';
 export { AnimatedText } from './AnimatedText';
 export { StreamingCursor } from './StreamingCursor';
+export { StreamingSurface } from './StreamingSurface';
 export { WordAnimationProvider, useWordAnimation } from './WordAnimationContext';
 export { streamingResponseTheme } from './StreamingResponse.theme';
-export { tokenFadeIn, tokenTransition, blockSlideIn, blockTransition, inlineTokenFadeIn, inlineTokenTransition, cursorPulse, staggerContainer, } from './StreamingResponse.animations';
-export type { StreamingResponseProps, StreamingResponseTheme, MarkdownOptions, MessageAvatarProps, } from './StreamingResponse.types';
+export { tokenFadeIn, tokenTransition, blockSlideIn, blockTransition, inlineTokenFadeIn, inlineTokenTransition, cursorPulse, staggerContainer, resolveStreamingMotion, getTokenFadeIn, type ResolvedStreamingMotion, } from './StreamingResponse.animations';
+export type { StreamingResponseProps, StreamingResponseTheme, MarkdownOptions, MessageAvatarProps, StreamingMotionOptions, StreamingMotionPreset, StreamingTokenEffect, } from './StreamingResponse.types';
 export type { AnimatedTextProps } from './AnimatedText';
 export type { StreamingCursorProps } from './StreamingCursor';
+export type { StreamingSurfaceProps } from './StreamingSurface';
 export type { MarkdownRendererProps } from './MarkdownRenderer';
 export type { WordAnimationProviderProps } from './WordAnimationContext';

package/dist/components/ai/TokenCounter/TokenCounter.js

@@ -4,7 +4,7 @@ import React__default, { useMemo } from 'react';
 import { tokenCounterTheme } from './TokenCounter.theme.js';
 import { MODEL_CONFIGS, estimateTokens, calculateCost, formatTokenCount, formatCost } from './tokenUtils.js';
 import { cn } from '../../../utils/cn.js';
-import { CircleStackIcon } from '@heroicons/react/16/solid';
+import { Database } from '@phosphor-icons/react';
 
 /**
  * TokenCounter - Real-time token usage display with cost estimation
@@ -55,7 +55,7 @@ const TokenCounter = React__default.forwardRef(({ text = "", tokens: providedTok
     const costStyle = customTheme.costStyle || tokenCounterTheme.costStyle;
     const progressStyle = customTheme.progressStyle || tokenCounterTheme.progressStyle;
     const progressBarStyle = customTheme.progressBarStyle || tokenCounterTheme.progressBarStyle;
-    return (jsxs("div", { ref: ref, className: cn(baseStyle, sizeConfig.container, className), ...props, children: [icon || jsx(CircleStackIcon, { className: cn(iconStyle, sizeConfig.icon) }), jsx("span", { className: cn(countStyle, sizeConfig.text, isOverLimit && "text-[var(--color-danger)]"), children: formatTokenCount(tokenCount) }), maxTokens && format === "detailed" && (jsxs("span", { className: cn(labelStyle, sizeConfig.text), children: ["/ ", formatTokenCount(effectiveMaxTokens)] })), jsx("span", { className: cn(labelStyle, sizeConfig.text), children: "tokens" }), showCost && (jsxs("span", { className: cn(costStyle, sizeConfig.text), children: ["(", formatCost(cost), ")"] })), format === "detailed" && maxTokens && (jsx("div", { className: cn(progressStyle, "w-16 ml-2"), children: jsx("div", { className: cn(progressBarStyle, isOverLimit && "bg-[var(--color-danger)]"), style: { width: `${progressPercent}%` } }) }))] }));
+    return (jsxs("div", { ref: ref, className: cn(baseStyle, sizeConfig.container, className), ...props, children: [icon || jsx(Database, { className: cn(iconStyle, sizeConfig.icon) }), jsx("span", { className: cn(countStyle, sizeConfig.text, isOverLimit && "text-[var(--color-danger)]"), children: formatTokenCount(tokenCount) }), maxTokens && format === "detailed" && (jsxs("span", { className: cn(labelStyle, sizeConfig.text), children: ["/ ", formatTokenCount(effectiveMaxTokens)] })), jsx("span", { className: cn(labelStyle, sizeConfig.text), children: "tokens" }), showCost && (jsxs("span", { className: cn(costStyle, sizeConfig.text), children: ["(", formatCost(cost), ")"] })), format === "detailed" && maxTokens && (jsx("div", { className: cn(progressStyle, "w-16 ml-2"), children: jsx("div", { className: cn(progressBarStyle, isOverLimit && "bg-[var(--color-danger)]"), style: { width: `${progressPercent}%` } }) }))] }));
 });
 TokenCounter.displayName = "TokenCounter";
 

package/dist/components/ai/TokenCounter/TokenCounter.theme.js

@@ -5,7 +5,7 @@ const tokenCounterTheme = {
     labelStyle: "text-[var(--color-text-muted)]",
     costStyle: "text-[var(--color-text-muted)] font-mono",
     progressStyle: "h-1 bg-[var(--color-surface-sunken)] rounded-full overflow-hidden shadow-inner-real-sm",
-    progressBarStyle: "h-full bg-[var(--color-primary)] transition-all duration-200",
+    progressBarStyle: "h-full bg-[var(--color-primary)] transition-all duration-[var(--motion-duration-base)]",
     sizes: {
         sm: {
             container: "text-xs",