@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.31

package/dist/components/ai/PromptInput/VoiceRecorder.js

@@ -0,0 +1,328 @@
+"use client";
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { motion } from 'motion/react';
+import { Play, Pause, Check } from '@phosphor-icons/react';
+import { cn } from '../../../utils/cn.js';
+import { Button } from '../../core/Button/Button.js';
+
+/**
+ * Format seconds into MM:SS display
+ */
+const formatTime = (seconds) => {
+    const mins = Math.floor(seconds / 60);
+    const secs = seconds % 60;
+    return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+};
+/**
+ * Helper to draw a 3D-like particle ribbon wave on the canvas.
+ * Composes multiple parallel rows of dots with depth offsets for a three-dimensional perspective.
+ */
+function drawParticleRibbon(ctx, width, centerY, basePhase, amplitude, color, frequency, direction, numRows = 8) {
+    for (let r = 0; r < numRows; r++) {
+        // Map row index to a depth value between -1.0 (back) and 1.0 (front)
+        const depth = (r - numRows / 2) / (numRows / 2);
+        // Shift phase and vertical offset based on depth to create a twisting ribbon effect
+        const phaseOffset = depth * 0.45;
+        const yOffset = depth * 0.65; // Thinner row spacing
+        ctx.fillStyle = color;
+        ctx.shadowBlur = 6;
+        ctx.shadowColor = color;
+        // Back rows are more transparent, front rows are more opaque
+        const opacity = 0.12 + (depth + 1.0) * 0.38; // range ~0.12 to ~0.88
+        ctx.globalAlpha = opacity;
+        // Draw dots across the horizontal axis
+        for (let x = 0; x < width; x += 3.5) {
+            // Taper at the left and right boundaries using a sine envelope
+            const envelope = Math.sin((x / width) * Math.PI);
+            // Calculate sine wave coordinate
+            const wave = Math.sin(x * frequency * direction + basePhase + phaseOffset);
+            const y = centerY + wave * amplitude * envelope + yOffset * envelope;
+            // Thinner particle sizes
+            const size = 0.25 + (depth + 1.0) * 0.35; // range ~0.25px to ~0.95px
+            ctx.beginPath();
+            ctx.arc(x, y, size, 0, Math.PI * 2);
+            ctx.fill();
+        }
+    }
+    ctx.shadowBlur = 0; // Reset shadows after drawing
+}
+/**
+ * Internal voice recorder sub-component.
+ * Handles MediaRecorder lifecycle, timer display, and recording controls.
+ * Implements a premium 3D Particle-Wave audio visualizer with glowing additive blend modes.
+ *
+ * Recording starts immediately on mount.
+ * Not exported from the library's public API.
+ */
+const VoiceRecorder = ({ onComplete, onCancel, maxDuration, className, }) => {
+    const [recordingState, setRecordingState] = useState("idle");
+    const [elapsed, setElapsed] = useState(0);
+    const mediaRecorderRef = useRef(null);
+    const chunksRef = useRef([]);
+    const timerRef = useRef(null);
+    const streamRef = useRef(null);
+    // Web Audio API & Canvas refs for visualizer
+    const audioContextRef = useRef(null);
+    const analyserRef = useRef(null);
+    const sourceRef = useRef(null);
+    const animationFrameRef = useRef(null);
+    const canvasRef = useRef(null);
+    // Keep recording state ref to read inside requestAnimationFrame loops without stale closures
+    const recordingStateRef = useRef("idle");
+    useEffect(() => {
+        recordingStateRef.current = recordingState;
+    }, [recordingState]);
+    /**
+     * Clean up timer
+     */
+    const clearTimer = useCallback(() => {
+        if (timerRef.current) {
+            clearInterval(timerRef.current);
+            timerRef.current = null;
+        }
+    }, []);
+    /**
+     * Stop all media tracks and clean up
+     */
+    const cleanup = useCallback(() => {
+        clearTimer();
+        // Clean up Audio API resources
+        if (animationFrameRef.current) {
+            cancelAnimationFrame(animationFrameRef.current);
+            animationFrameRef.current = null;
+        }
+        if (sourceRef.current) {
+            sourceRef.current.disconnect();
+            sourceRef.current = null;
+        }
+        if (audioContextRef.current) {
+            if (audioContextRef.current.state !== "closed") {
+                audioContextRef.current.close();
+            }
+            audioContextRef.current = null;
+        }
+        analyserRef.current = null;
+        if (mediaRecorderRef.current &&
+            mediaRecorderRef.current.state !== "inactive") {
+            mediaRecorderRef.current.stop();
+        }
+        if (streamRef.current) {
+            streamRef.current.getTracks().forEach((track) => track.stop());
+            streamRef.current = null;
+        }
+        mediaRecorderRef.current = null;
+    }, [clearTimer]);
+    /**
+     * Start the recording timer
+     */
+    const startTimer = useCallback(() => {
+        clearTimer();
+        timerRef.current = setInterval(() => {
+            setElapsed((prev) => prev + 1);
+        }, 1000);
+    }, [clearTimer]);
+    /**
+     * Start recording immediately on mount
+     */
+    useEffect(() => {
+        let cancelled = false;
+        const startRecording = async () => {
+            try {
+                const stream = await navigator.mediaDevices.getUserMedia({
+                    audio: true,
+                });
+                if (cancelled) {
+                    stream.getTracks().forEach((t) => t.stop());
+                    return;
+                }
+                streamRef.current = stream;
+                // Choose supported MIME type
+                const mimeType = MediaRecorder.isTypeSupported("audio/webm;codecs=opus")
+                    ? "audio/webm;codecs=opus"
+                    : MediaRecorder.isTypeSupported("audio/webm")
+                        ? "audio/webm"
+                        : "";
+                const recorder = new MediaRecorder(stream, mimeType ? { mimeType } : undefined);
+                mediaRecorderRef.current = recorder;
+                chunksRef.current = [];
+                recorder.ondataavailable = (e) => {
+                    if (e.data.size > 0) {
+                        chunksRef.current.push(e.data);
+                    }
+                };
+                recorder.start(100); // collect data every 100ms
+                setRecordingState("recording");
+                startTimer();
+                // Web Audio API visualizer setup
+                try {
+                    const audioContext = new (window.AudioContext || window.webkitAudioContext)();
+                    const analyser = audioContext.createAnalyser();
+                    analyser.fftSize = 64; // Small fftSize is enough for wave lines
+                    const source = audioContext.createMediaStreamSource(stream);
+                    source.connect(analyser);
+                    audioContextRef.current = audioContext;
+                    analyserRef.current = analyser;
+                    sourceRef.current = source;
+                    const bufferLength = analyser.frequencyBinCount;
+                    const dataArray = new Uint8Array(bufferLength);
+                    let phase = 0;
+                    const canvas = canvasRef.current;
+                    if (canvas) {
+                        const ctx = canvas.getContext("2d");
+                        if (ctx) {
+                            const drawFrame = () => {
+                                const currentCanvas = canvasRef.current;
+                                if (!analyserRef.current || !currentCanvas) {
+                                    animationFrameRef.current = requestAnimationFrame(drawFrame);
+                                    return;
+                                }
+                                // Paused/stopped: keep the loop alive so resuming works, but skip the expensive
+                                // per-frame redraw (clearRect + 3 particle ribbons = hundreds of arc/fill ops at
+                                // ~60fps) — nothing is changing, so redrawing only drains the battery.
+                                if (recordingStateRef.current !== "recording") {
+                                    animationFrameRef.current = requestAnimationFrame(drawFrame);
+                                    return;
+                                }
+                                analyserRef.current.getByteFrequencyData(dataArray);
+                                // Average the first 5 bins (0 to ~3400Hz) which contain the human vocal range
+                                let sum = 0;
+                                const activeBins = Math.min(5, bufferLength);
+                                for (let i = 0; i < activeBins; i++) {
+                                    sum += dataArray[i];
+                                }
+                                const average = sum / activeBins;
+                                const volumeFactor = average / 255;
+                                // Handle resolution resize with bounds guard (never set to 0)
+                                const targetWidth = currentCanvas.clientWidth || 128;
+                                const targetHeight = currentCanvas.clientHeight || 32;
+                                if (currentCanvas.width !== targetWidth || currentCanvas.height !== targetHeight) {
+                                    currentCanvas.width = targetWidth;
+                                    currentCanvas.height = targetHeight;
+                                }
+                                // Clear canvas
+                                ctx.clearRect(0, 0, currentCanvas.width, currentCanvas.height);
+                                const width = currentCanvas.width;
+                                const height = currentCanvas.height;
+                                const centerY = height / 2;
+                                // Set screen blending for bright glowing particle intersections
+                                ctx.globalCompositeOperation = "screen";
+                                // Base parameters (additive scaling ensures continuous reaction to all volume levels)
+                                const activeAmp = 2.0 + volumeFactor * 35.0;
+                                phase += 0.035;
+                                // Particle Ribbon 1: Cyan/Blue (flows forward)
+                                drawParticleRibbon(ctx, width, centerY, phase, activeAmp, "#06b6d4", // Cyan
+                                0.045, 1.0, 5);
+                                // Particle Ribbon 2: Pink/Rose (flows backward with offset phase)
+                                drawParticleRibbon(ctx, width, centerY, phase + Math.PI * 0.5, activeAmp * 0.9, "#ec4899", // Pink
+                                0.05, -1.0, 5);
+                                // Core White Ribbon: Bright central energy line
+                                drawParticleRibbon(ctx, width, centerY, phase * 1.5, activeAmp * 0.35, "#ffffff", // White Core
+                                0.065, 0.7, 3);
+                                // Reset composite operation to default
+                                ctx.globalCompositeOperation = "source-over";
+                                animationFrameRef.current = requestAnimationFrame(drawFrame);
+                            };
+                            animationFrameRef.current = requestAnimationFrame(drawFrame);
+                        }
+                    }
+                }
+                catch (e) {
+                    if (process.env.NODE_ENV !== "production") {
+                        console.warn("[VoiceRecorder] Audio context visualization failed:", e);
+                    }
+                }
+            }
+            catch (_a) {
+                if (process.env.NODE_ENV !== "production") {
+                    console.warn("[VoiceRecorder] Microphone access denied or unavailable.");
+                }
+                onCancel();
+            }
+        };
+        startRecording();
+        return () => {
+            cancelled = true;
+            cleanup();
+        };
+        // Only run on mount/unmount
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    /**
+     * Auto-stop at max duration
+     */
+    useEffect(() => {
+        if (elapsed >= maxDuration && recordingState === "recording") {
+            handleConfirm();
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [elapsed, maxDuration, recordingState]);
+    /**
+     * Handle cancel — stop recording and discard
+     */
+    const handleCancel = useCallback(() => {
+        cleanup();
+        chunksRef.current = [];
+        setRecordingState("idle");
+        onCancel();
+    }, [cleanup, onCancel]);
+    /**
+     * Handle confirm — stop recording and return blob
+     */
+    const handleConfirm = useCallback(() => {
+        if (!mediaRecorderRef.current) {
+            onCancel();
+            return;
+        }
+        const recorder = mediaRecorderRef.current;
+        recorder.onstop = () => {
+            const mimeType = recorder.mimeType || "audio/webm";
+            const blob = new Blob(chunksRef.current, { type: mimeType });
+            chunksRef.current = [];
+            if (streamRef.current) {
+                streamRef.current.getTracks().forEach((t) => t.stop());
+                streamRef.current = null;
+            }
+            onComplete(blob);
+        };
+        clearTimer();
+        if (recorder.state !== "inactive") {
+            recorder.stop();
+        }
+        setRecordingState("idle");
+    }, [clearTimer, onComplete, onCancel]);
+    /**
+     * Toggle pause/resume
+     */
+    const handleTogglePause = useCallback(() => {
+        const recorder = mediaRecorderRef.current;
+        if (!recorder)
+            return;
+        if (recordingState === "recording") {
+            recorder.pause();
+            clearTimer();
+            setRecordingState("paused");
+            if (audioContextRef.current && audioContextRef.current.state === "running") {
+                audioContextRef.current.suspend();
+            }
+        }
+        else if (recordingState === "paused") {
+            recorder.resume();
+            startTimer();
+            setRecordingState("recording");
+            if (audioContextRef.current && audioContextRef.current.state === "suspended") {
+                audioContextRef.current.resume();
+            }
+        }
+    }, [recordingState, clearTimer, startTimer]);
+    return (jsxs("div", { className: cn("flex items-center justify-between w-full", className), children: [jsx(Button, { variant: "soft", color: "mono", size: "sm", className: "rounded-full", onClick: handleCancel, "aria-label": "Cancel recording", children: "Cancel" }), jsxs("div", { className: "flex items-center gap-4", children: [jsxs("div", { className: "flex items-center gap-2", children: [jsx(motion.div, { className: "size-2 rounded-full bg-[var(--color-danger)]", animate: recordingState === "recording"
+                                    ? { scale: [1, 1.4, 1] }
+                                    : undefined, transition: {
+                                    duration: 1.5,
+                                    repeat: Infinity,
+                                    ease: "easeInOut",
+                                } }), jsx("span", { className: "text-sm font-medium tabular-nums text-[var(--color-text-primary)] min-w-[2.5rem] text-center", children: formatTime(elapsed) })] }), jsx("canvas", { ref: canvasRef, width: 128, height: 32, className: "w-32 h-8 bg-transparent" })] }), jsxs("div", { className: "flex items-center gap-2", children: [jsx(Button, { iconOnly: true, variant: "outline", color: "mono", size: "sm", className: "rounded-full", onClick: handleTogglePause, "aria-label": recordingState === "paused" ? "Resume recording" : "Pause recording", children: recordingState === "paused" ? (jsx(Play, { className: "size-4", weight: "bold" })) : (jsx(Pause, { className: "size-4", weight: "bold" })) }), jsx(Button, { iconOnly: true, variant: "filled", color: "primary", size: "sm", className: "rounded-full", onClick: handleConfirm, "aria-label": "Confirm recording", children: jsx(Check, { className: "size-4", weight: "bold" }) })] })] }));
+};
+VoiceRecorder.displayName = "VoiceRecorder";
+
+export { VoiceRecorder };

package/dist/components/ai/PromptInput/VoiceRecorder.types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Recording state machine states
+ */
+export type RecordingState = "idle" | "recording" | "paused";
+/**
+ * Props for the internal VoiceRecorder sub-component
+ */
+export interface VoiceRecorderProps {
+    /** Called when user confirms the recording */
+    onComplete: (audioBlob: Blob) => void;
+    /** Called when user cancels the recording */
+    onCancel: () => void;
+    /** Maximum recording duration in seconds (auto-stops at limit) */
+    maxDuration: number;
+    /** Theme class for the recorder container */
+    className?: string;
+}

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

@@ -1,3 +1,4 @@
 export { PromptInput } from "./PromptInput";
 export type { PromptInputProps, PromptInputState, PromptInputTheme, PromptInputThemeOverrides, ModelOption, AttachmentItem, AttachmentError, } from "./PromptInput.types";
+export type { RecordingState } from "./VoiceRecorder.types";
 export { promptInputTheme } from "./PromptInput.theme";

package/dist/components/ai/{PromptSuggestions → PromptSuggestion}/PromptSuggestion.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useCallback } from 'react';
 import { promptSuggestionTheme } from './PromptSuggestion.theme.js';

package/dist/components/ai/{PromptSuggestions → PromptSuggestion}/PromptSuggestion.theme.js

@@ -1,10 +1,10 @@
 const promptSuggestionTheme = {
-    baseStyle: "inline-flex items-center gap-2 py-2 px-3.5 rounded-full " +
-        "bg-white dark:bg-[var(--color-background)] " +
+    baseStyle: "inline-flex items-center gap-2 py-1 px-3 rounded-[var(--card-radius)] " +
+        "bg-[var(--color-surface)] " +
         "border border-[var(--color-border)] " +
-        "text-sm font-medium text-[var(--color-text-primary)] " +
+        "text-sm text-[var(--color-text-primary)] " +
         "cursor-pointer transition-all duration-300 " +
-        "hover:bg-[var(--color-background-secondary)] dark:hover:bg-[var(--color-background-secondary)] " +
+        "hover:bg-[var(--color-background-secondary)] " +
         "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)]",
     iconStyle: "size-4 flex-shrink-0",
 };

package/dist/components/ai/Reasoning/Reasoning.d.ts

@@ -0,0 +1,5 @@
+import React from "react";
+import type { ReasoningProps, ReasoningStepProps } from "./Reasoning.types";
+export declare const Reasoning: React.ForwardRefExoticComponent<ReasoningProps & React.RefAttributes<HTMLDivElement>> & {
+    Step: React.ForwardRefExoticComponent<ReasoningStepProps & React.RefAttributes<HTMLDivElement>>;
+};

package/dist/components/ai/Reasoning/Reasoning.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import React__default from 'react';
+import { AgentStatus } from '../AgentStatus/AgentStatus.js';
+
+// Reasoning is AgentStatus in its reasoning mode, with a discoverable name.
+const ReasoningRoot = React__default.forwardRef((props, ref) => jsx(AgentStatus, { ref: ref, mode: "reasoning", ...props }));
+ReasoningRoot.displayName = "Reasoning";
+// A step is just a status row; children carry its text.
+const ReasoningStep = React__default.forwardRef(({ children, status = "complete", ...rest }, ref) => (jsx(AgentStatus, { ref: ref, mode: "status", status: status, label: children, wrap: true, live: "off", ...rest })));
+ReasoningStep.displayName = "Reasoning.Step";
+const Reasoning = Object.assign(ReasoningRoot, {
+    Step: ReasoningStep,
+});
+
+export { Reasoning };

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

@@ -0,0 +1,20 @@
+import React from "react";
+import type { AgentStatusProps, AgentStatusState, AgentStatusStepData, AgentStatusThemeOverrides } from "../AgentStatus";
+/**
+ * Reasoning is a preset of AgentStatus fixed to `mode="reasoning"` — the
+ * collapsible "show the AI's thinking" disclosure. Every AgentStatus prop
+ * except `mode` applies.
+ */
+export type ReasoningProps = Omit<AgentStatusProps, "mode">;
+/** A structured reasoning step (an AgentStatus row). */
+export type ReasoningStepData = AgentStatusStepData;
+export type ReasoningThemeOverrides = AgentStatusThemeOverrides;
+export interface ReasoningStepProps {
+    /** Step state — drives the indicator glyph. @default "complete" */
+    status?: AgentStatusState;
+    /** Step text. */
+    children: React.ReactNode;
+    /** Elapsed or final step duration in seconds. */
+    duration?: number;
+    className?: string;
+}

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

@@ -0,0 +1,2 @@
+export { Reasoning } from "./Reasoning";
+export type { ReasoningProps, ReasoningStepProps, ReasoningStepData, ReasoningThemeOverrides, } from "./Reasoning.types";

package/dist/components/ai/SourceCitation/SourceCitation.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+import type { SourceCitationGroupProps, SourceCitationProps } from "./SourceCitation.types";
+export declare const SourceCitation: React.ForwardRefExoticComponent<SourceCitationProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const SourceCitationGroup: React.ForwardRefExoticComponent<SourceCitationGroupProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ai/SourceCitation/SourceCitation.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
+import React__default, { useMemo } from 'react';
+import { Link, ArrowSquareOut } from '@phosphor-icons/react';
+import { cn } from '../../../utils/cn.js';
+import { Link as Link$1 } from '../../core/Link/Link.js';
+import { Popover } from '../../core/Popover/Popover.js';
+import '../../core/Popover/PopoverContext.js';
+import '../../core/Popover/PopoverBody.js';
+import { sourceCitationTheme } from './SourceCitation.theme.js';
+
+const SourceCitation = React__default.forwardRef(({ index, title, domain, excerpt, href, icon, preview, placement = "top-start", open, defaultOpen, onOpenChange, openInNewTab = true, linkLabel = "Open source", className, theme: themeOverrides, disabled, ...props }, ref) => {
+    const theme = useMemo(() => ({ ...sourceCitationTheme, ...themeOverrides }), [themeOverrides]);
+    // `title` and `domain` are both ReactNode, so neither is guaranteed to yield a
+    // usable name. Fall back through the domain (already the visible chip text) before
+    // the generic word, so rich-titled citations stay distinguishable by ear.
+    const label = (typeof title === "string" && title) ||
+        (typeof domain === "string" && domain) ||
+        "source";
+    return (jsxs(Popover, { placement: placement, isOpen: open, defaultIsOpen: defaultOpen, onOpenChange: onOpenChange, children: [jsx(Popover.Trigger, { children: jsxs("button", { ref: ref, type: "button", className: cn(theme.triggerStyle, className), "aria-label": `View source: ${label}`, disabled: disabled, ...props, children: [icon ? (jsx("span", { className: theme.faviconStyle, "aria-hidden": "true", children: icon })) : (index !== undefined && (jsx("span", { className: theme.indexStyle, children: index }))), jsx("span", { className: theme.domainStyle, children: domain !== null && domain !== void 0 ? domain : title })] }) }), jsx(Popover.Body, { className: theme.popoverStyle, children: preview !== null && preview !== void 0 ? preview : (jsxs(Fragment, { children: [jsxs("div", { className: theme.previewHeaderStyle, children: [jsx("span", { className: theme.previewIconStyle, "aria-hidden": "true", children: icon !== null && icon !== void 0 ? icon : jsx(Link, { className: "size-4" }) }), jsxs("div", { className: "min-w-0", children: [jsx("div", { className: theme.previewTitleStyle, children: title }), domain && (jsx("div", { className: theme.previewDomainStyle, children: domain }))] })] }), excerpt && jsx("div", { className: theme.excerptStyle, children: excerpt }), href && (jsxs(Link$1, { href: href, target: openInNewTab ? "_blank" : undefined, rel: openInNewTab ? "noopener noreferrer" : undefined, className: theme.linkStyle, children: [linkLabel, jsx(ArrowSquareOut, { className: "size-3.5", "aria-hidden": "true", weight: "bold" })] }))] })) })] }));
+});
+SourceCitation.displayName = "SourceCitation";
+const SourceCitationGroup = React__default.forwardRef(({ children, className, theme: themeOverrides, ...props }, ref) => {
+    var _a;
+    return (jsx("div", { ref: ref, role: "group", "aria-label": "Sources", className: cn((_a = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.groupStyle) !== null && _a !== void 0 ? _a : sourceCitationTheme.groupStyle, className), ...props, children: children }));
+});
+SourceCitationGroup.displayName = "SourceCitation.Group";
+
+export { SourceCitation, SourceCitationGroup };

package/dist/components/ai/SourceCitation/SourceCitation.theme.d.ts

@@ -0,0 +1,2 @@
+import type { SourceCitationTheme } from "./SourceCitation.types";
+export declare const sourceCitationTheme: SourceCitationTheme;

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

@@ -0,0 +1,23 @@
+const sourceCitationTheme = {
+    // Asymmetric padding: the round leading token provides its own visual inset,
+    // so the left padding is tighter than the right where the domain text sits.
+    triggerStyle: "inline-flex max-w-52 cursor-pointer items-center gap-1.5 rounded-full border border-[var(--color-border)] bg-[var(--color-surface)] py-0.5 pl-0.5 pr-2.5 text-xs font-medium text-[var(--color-text-secondary)] transition-colors hover:border-[var(--color-border-hover)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text-primary)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)]",
+    // Quiet numbered token — a recessed well with a hairline, not a loud filled disc.
+    indexStyle: "flex size-[1.125rem] shrink-0 items-center justify-center rounded-full bg-[var(--color-surface-sunken)] text-[10px] font-semibold tabular-nums text-[var(--color-text-secondary)] ring-1 ring-inset ring-[var(--color-border)]",
+    // Favicon well (shown instead of the number when an icon is supplied).
+    faviconStyle: "flex size-[1.125rem] shrink-0 items-center justify-center overflow-hidden rounded-full bg-[var(--color-surface-sunken)] ring-1 ring-inset ring-[var(--color-border)] [&>img]:size-full [&>img]:object-cover [&>svg]:size-3",
+    domainStyle: "truncate",
+    popoverStyle: "w-80 space-y-3",
+    previewHeaderStyle: "flex items-start gap-2.5",
+    previewIconStyle: "flex size-10 shrink-0 items-center justify-center rounded-lg bg-[var(--color-surface-sunken)] text-[var(--color-text-muted)]",
+    previewTitleStyle: "line-clamp-2 text-sm font-semibold text-[var(--color-text-primary)]",
+    previewDomainStyle: "mt-0.5 truncate text-xs text-[var(--color-text-muted)]",
+    excerptStyle: "line-clamp-4 text-sm leading-5 text-[var(--color-text-secondary)]",
+    // Link's own base already provides layout (inline-flex/items-center/gap),
+    // color, hover underline, and focus-visible ring — only the size-specific
+    // bits need overriding here.
+    linkStyle: "text-xs font-medium",
+    groupStyle: "inline-flex flex-wrap items-center gap-1.5",
+};
+
+export { sourceCitationTheme };

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

@@ -0,0 +1,55 @@
+import React from "react";
+import type { PopoverPlacement } from "../../core/Popover";
+export interface SourceCitationTheme {
+    triggerStyle: string;
+    indexStyle: string;
+    faviconStyle: string;
+    domainStyle: string;
+    popoverStyle: string;
+    previewHeaderStyle: string;
+    previewIconStyle: string;
+    previewTitleStyle: string;
+    previewDomainStyle: string;
+    excerptStyle: string;
+    linkStyle: string;
+    groupStyle: string;
+}
+export type SourceCitationThemeOverrides = Partial<SourceCitationTheme>;
+export interface SourceCitationProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "title"> {
+    /** Citation number or compact identifier displayed in the chip. */
+    index?: React.ReactNode;
+    /** Source title displayed in the preview. */
+    title: React.ReactNode;
+    /** Source domain displayed in both the chip and preview. */
+    domain?: React.ReactNode;
+    /** Supporting source excerpt. */
+    excerpt?: React.ReactNode;
+    /** Destination URL. */
+    href?: string;
+    /** Optional source or favicon icon. */
+    icon?: React.ReactNode;
+    /** Fully custom preview content. */
+    preview?: React.ReactNode;
+    /** Popover placement relative to the citation chip. */
+    placement?: PopoverPlacement;
+    /** Controlled popover state. */
+    open?: boolean;
+    /** Initial popover state for uncontrolled usage. */
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Open the source link in a new tab. @default true */
+    openInNewTab?: boolean;
+    /**
+     * Label for the link at the foot of the preview. Overridable so the string is
+     * not trapped in English.
+     * @default "Open source"
+     */
+    linkLabel?: React.ReactNode;
+    className?: string;
+    theme?: SourceCitationThemeOverrides;
+}
+export interface SourceCitationGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    children: React.ReactNode;
+    className?: string;
+    theme?: Pick<SourceCitationThemeOverrides, "groupStyle">;
+}

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

@@ -0,0 +1,3 @@
+export { SourceCitation, SourceCitationGroup } from "./SourceCitation";
+export { sourceCitationTheme } from "./SourceCitation.theme";
+export type { SourceCitationProps, SourceCitationGroupProps, SourceCitationTheme, SourceCitationThemeOverrides, } from "./SourceCitation.types";

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

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { useRef, useMemo } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
@@ -17,7 +18,7 @@ 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 = 6, enabled = true, className, }) => {
+const AnimatedText = ({ text, isStreaming, animateLastN = 12, enabled = true, className, }) => {
     const shouldReduceMotion = useReducedMotion();
     const animate = enabled && !shouldReduceMotion;
     // Track which tokens have already been seen/animated
@@ -37,9 +38,9 @@ const AnimatedText = ({ text, isStreaming, animateLastN = 6, enabled = true, cla
     const animatedTokens = tokens.slice(settledCount);
     if (!animate || !isStreaming) {
         // No animation: render plain text
-        return (jsx("p", { className: className || 'whitespace-pre-wrap break-words', children: text }));
+        return (jsx("p", { className: className || 'whitespace-pre-wrap wrap-break-word', children: text }));
     }
-    return (jsxs("p", { className: className || 'whitespace-pre-wrap break-words', 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: tokenFadeIn, initial: "hidden", animate: "visible", transition: tokenTransition, style: { display: 'inline' }, children: token }, `${settledCount + i}-${token}`)))] }));
 };
 AnimatedText.displayName = 'AnimatedText';
 

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

@@ -1,5 +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';
 
@@ -28,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

@@ -1,7 +1,8 @@
 /**
  * MarkdownRenderer Component
  * Renders markdown content with syntax highlighting for code blocks
- * Supports optional block-level slide-in animations during streaming
+ * Supports word-by-word fade-in animation during streaming
+ * and an inline cursor that appears at the end of the last text element
  */
 import React from 'react';
 import type { MarkdownOptions } from './StreamingResponse.types';
@@ -16,10 +17,12 @@ export interface MarkdownRendererProps {
     animated?: boolean;
     /** Show a blinking cursor at end of content while streaming */
     showCursor?: boolean;
+    /** Number of recent words to animate (default: 6) */
+    animateLastN?: number;
 }
 /**
  * MarkdownRenderer component for rendering markdown with syntax highlighting
  * Supports GitHub Flavored Markdown (tables, task lists, strikethrough, etc.)
- * Optionally animates block-level elements during streaming with slide-in effect
+ * Animates individual words during streaming with a fade-in + blur effect
  */
 export declare const MarkdownRenderer: React.FC<MarkdownRendererProps>;