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

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

@@ -0,0 +1,241 @@
+import React from "react";
+/**
+ * What the agent is asking for.
+ *
+ * - `approval` — a permission gate. Approve / Deny (+ optional "always allow").
+ * - `choice`   — pick one of `options`.
+ * - `input`    — free text.
+ */
+export type AgentRequestKind = "approval" | "choice" | "input";
+/**
+ * How consequential the action is.
+ *
+ * The library paints NOTHING for this by default: a destructive question
+ * already reads as destructive through its `meta` line and the danger-outlined
+ * Deny action, and a coloured accent on top of those was noise. `destructive`
+ * lands on the row as `data-risk="destructive"` so a consumer can style it.
+ */
+export type AgentRequestRisk = "normal" | "destructive";
+/**
+ * How a question was settled.
+ *
+ * `deferred` is the escape hatch: the user declined to answer here (Skip). It
+ * is a first-class outcome, not a cancel — a composer takeover that cannot be
+ * escaped traps a user whose real answer isn't one of the offered options,
+ * which is also why a choice question can carry `allowOther`.
+ */
+export type AgentRequestOutcome = "resolved" | "rejected" | "deferred";
+export interface AgentRequestOption {
+    /** Serializable value handed back to `onAnswer`. */
+    value: string;
+    label: React.ReactNode;
+    /** Secondary line under the label — the trade-off, cost, or consequence. */
+    description?: React.ReactNode;
+}
+/** Fields every question kind shares. */
+export interface AgentRequestQuestionBase {
+    /** Stable identity. Required — answers are keyed by it, not by index. */
+    id: string;
+    /**
+     * Short summary shown in the collapsed row once answered, and in the
+     * dimmed row while pending. Keep it to a few words.
+     */
+    label: React.ReactNode;
+    /** The full question. Falls back to `label` when omitted. */
+    question?: React.ReactNode;
+    /** Secondary context line under the question. */
+    meta?: React.ReactNode;
+    /** @default "normal" */
+    risk?: AgentRequestRisk;
+    /**
+     * What is actually being approved — a command, a diff, a params list.
+     * Rendered in a monospace well. `ReactNode` on purpose: this is the one slot
+     * where a consumer legitimately needs to render their own component
+     * (a diff view, a table), so it is NOT part of the serializable schema.
+     */
+    payload?: React.ReactNode;
+}
+export interface AgentRequestApprovalQuestion extends AgentRequestQuestionBase {
+    /** @default "approval" */
+    kind?: "approval";
+    /** Overrides for the built-in action labels (i18n — §6: never trap strings). */
+    approveLabel?: string;
+    denyLabel?: string;
+    alwaysAllowLabel?: string;
+    /** Show the "always allow" action. @default false */
+    allowAlways?: boolean;
+    /**
+     * Renders a Skip action, recorded as `deferred`. @default false
+     *
+     * An approval has no free-text row to fall back on — Approve and Deny are
+     * both real answers — so this is its ONLY escape hatch, and a permission gate
+     * the user can neither approve, deny, nor step away from is the trap the
+     * `deferred` outcome exists to prevent.
+     */
+    optional?: boolean;
+    skipLabel?: string;
+}
+/** Fields shared by both choice shapes. */
+export interface AgentRequestChoiceBase extends AgentRequestQuestionBase {
+    kind: "choice";
+    options: AgentRequestOption[];
+    /**
+     * Append a free-text "something else" row to the bottom of the option list.
+     * Opt-in per question, NOT on by default: a closed question ("before or
+     * during the rollout?") is closed on purpose, and only the author of the
+     * question knows whether an answer off the list is meaningful. The typed
+     * answer is recorded as `resolved` with the text as its value.
+     * @default false
+     */
+    allowOther?: boolean;
+    /** Placeholder for the "something else" row. @default "Something else" */
+    otherPlaceholder?: string;
+    /** Label for the action that submits the "something else" text. @default "Send" */
+    otherSubmitLabel?: string;
+    /** Renders a Skip action. @default false */
+    optional?: boolean;
+    skipLabel?: string;
+}
+/** Pick exactly one — answers on selection. */
+export interface AgentRequestSingleChoiceQuestion extends AgentRequestChoiceBase {
+    multiple?: false;
+}
+/**
+ * Pick any number.
+ *
+ * Unlike single-choice this CANNOT auto-advance on click (the user isn't done
+ * until they say so), so it always renders an explicit confirm action.
+ */
+export interface AgentRequestMultiChoiceQuestion extends AgentRequestChoiceBase {
+    multiple: true;
+    /** Minimum selections before confirm enables. @default 0 */
+    minSelected?: number;
+    /** Maximum selections; further boxes disable once reached. */
+    maxSelected?: number;
+    confirmLabel?: string;
+}
+export interface AgentRequestInputQuestion extends AgentRequestQuestionBase {
+    kind: "input";
+    placeholder?: string;
+    /** Renders a Skip action. @default false */
+    optional?: boolean;
+    submitLabel?: string;
+    skipLabel?: string;
+}
+/**
+ * 🔴 A discriminated union, not one widened interface — `multiple` genuinely
+ * changes the shape of the ANSWER (`string` vs `string[]`), which §9 requires
+ * be modelled as a union rather than widened-and-cast. It also means `options`
+ * is required on a choice and meaningless on an approval, enforced by the
+ * compiler instead of by convention.
+ */
+export type AgentRequestQuestion = AgentRequestApprovalQuestion | AgentRequestSingleChoiceQuestion | AgentRequestMultiChoiceQuestion | AgentRequestInputQuestion;
+export interface AgentRequestAnswer {
+    /** The `id` of the question this answers. */
+    id: string;
+    /**
+     * Serializable answer value. `string[]` for a multi-choice question, `string`
+     * for every other kind — narrow with `Array.isArray`.
+     */
+    value: string | string[];
+    /** Human-readable answer, shown in the collapsed row. */
+    label: string;
+    outcome: AgentRequestOutcome;
+}
+export interface AgentRequestTheme {
+    baseStyle: string;
+    /**
+     * Geometry only. The panel's surface paint (rung background, elevation
+     * shadow, `--field-fill` for the controls inside) comes from `Card` and the
+     * relative-elevation engine, not from here.
+     */
+    panelStyle: string;
+    navStyle: string;
+    navButtonStyle: string;
+    navCountStyle: string;
+    /** The question-as-heading block. */
+    headerStyle: string;
+    /** Horizontal inset + bottom inset for the swapping question. */
+    contentStyle: string;
+    questionStyle: string;
+    metaStyle: string;
+    bodyStyle: string;
+    scrollAreaStyle: string;
+    fadeStyle: string;
+    fadeTopStyle: string;
+    fadeBottomStyle: string;
+    bodyInnerStyle: string;
+    answeredChipStyle: string;
+    badgeStyle: string;
+    /**
+     * Keyed by OUTCOME only. There are no `pending`/`active` badges any more —
+     * one question is on screen at a time, so there is no list of other
+     * questions to mark up.
+     */
+    badgeStates: Record<AgentRequestOutcome, string>;
+    answerStyle: string;
+    payloadStyle: string;
+    actionsStyle: string;
+    /** Left-anchored group inside the actions row (Skip). */
+    actionsStartStyle: string;
+    optionListStyle: string;
+    optionStyle: string;
+    otherInputStyle: string;
+    inputStyle: string;
+}
+export type AgentRequestThemeOverrides = Omit<Partial<AgentRequestTheme>, "badgeStates"> & {
+    badgeStates?: Partial<AgentRequestTheme["badgeStates"]>;
+};
+export interface AgentRequestProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "children" | "value" | "defaultValue" | "title"> {
+    /**
+     * The questions to ask, in order. Data-driven and serializable (except
+     * `payload`), so an LLM can emit a whole sequence as JSON.
+     */
+    questions?: AgentRequestQuestion[];
+    /**
+     * Escape hatch for a bespoke single-question body. Ignored when `questions`
+     * is provided (dev-warns if both).
+     */
+    children?: React.ReactNode;
+    /**
+     * The panel's accessible name, and only that — it is never painted. The
+     * QUESTION is the visible heading, so a second title line would be a heading
+     * competing with a heading. Pass a string; this is the i18n override for the
+     * default "Agent needs {n} decisions".
+     */
+    title?: React.ReactNode;
+    /** Controlled answers. */
+    value?: AgentRequestAnswer[];
+    /** Uncontrolled initial answers. @default [] */
+    defaultValue?: AgentRequestAnswer[];
+    /** Fires with the full answer list on every change. */
+    onValueChange?: (answers: AgentRequestAnswer[]) => void;
+    /** Fires once per answered question. */
+    onAnswer?: (answer: AgentRequestAnswer) => void;
+    /** Fires when the last question is answered. */
+    onComplete?: (answers: AgentRequestAnswer[]) => void;
+    /**
+     * Optional ceiling on the answering controls, as any CSS length. Unset by
+     * default: one question is on screen at a time, so the panel simply grows
+     * and shrinks to fit it. Set this when a question can be long enough to bury
+     * the conversation behind the composer (many options, a large `payload`) —
+     * beyond it the options scroll instead of growing, while the question itself
+     * stays put above them.
+     */
+    maxHeight?: string;
+    /** Accessible name for the back arrow. @default "Previous question" */
+    previousLabel?: string;
+    /** Accessible name for the forward arrow. @default "Next question" */
+    nextLabel?: string;
+    /**
+     * The progress line in the footer. A function rather than a string because it
+     * interpolates two numbers, and every visible string in the library has to be
+     * overridable for i18n. Whatever it returns is measured, and the actions row
+     * insets itself to clear it — a longer label is a layout choice, not a
+     * collision.
+     * @default "{current} of {total}"
+     */
+    progressLabel?: (current: number, total: number) => React.ReactNode;
+    className?: string;
+    theme?: AgentRequestThemeOverrides;
+}

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

@@ -0,0 +1,3 @@
+export { AgentRequest } from "./AgentRequest";
+export { agentRequestTheme } from "./AgentRequest.theme";
+export type { AgentRequestProps, AgentRequestKind, AgentRequestRisk, AgentRequestOutcome, AgentRequestOption, AgentRequestQuestion, AgentRequestAnswer, AgentRequestTheme, AgentRequestThemeOverrides, } from "./AgentRequest.types";

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

@@ -1,6 +1,6 @@
 const codeBlockTheme = {
     baseStyle: "relative rounded-[var(--codeblock-radius)] border border-[var(--color-border)] overflow-hidden bg-[var(--color-surface-sunken)] shadow-inner-real-sm",
-    header: "flex items-center justify-between px-3 py-1.5 bg-[var(--color-background-secondary)] border-b border-[var(--color-border)]",
+    header: "flex items-center justify-between px-3 py-1.5 bg-[var(--color-surface)] border-b border-[var(--color-border)]",
     headerLeft: "flex items-center gap-2 min-w-0 flex-1 ",
     headerRight: "flex items-center gap-2 flex-shrink-0",
     filename: "text-sm font-medium text-[var(--color-text-secondary)] truncate",

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

@@ -527,7 +527,7 @@ className, textareaClassName, footerClassName, theme = {},
                                         Link,
                                     ].map((Icon, i) => (jsx(motion.div, { variants: dropzoneActionIconVariants, className: "size-8 rounded-full bg-white/30 dark:bg-white/10 flex items-center justify-center", children: jsx(Icon, { className: "size-4 text-[var(--color-primary)]" }) }, i))) }))] })) }), currentAttachments.length > 0 && (jsx("div", { className: "flex flex-wrap gap-2 py-2 px-1", children: currentAttachments.map((attachment) => {
                             var _a;
-                            return (jsxs("div", { className: "relative group rounded-lg border border-[var(--color-border)] bg-white", children: [attachment.type === "image" ? (attachment.isCompressing ? (jsx("div", { className: "size-12 flex items-center justify-center bg-gray-100 rounded-lg", children: jsx("div", { className: "w-4 h-4 border-2 border-gray-300 border-t-[var(--color-primary)] rounded-full animate-spin" }) })) : (jsx("img", { src: attachment.previewUrl, alt: attachment.file.name, className: "size-12 object-cover rounded-lg" }))) : (jsxs("div", { className: "size-12 flex flex-col items-center justify-center text-center p-1 rounded-lg", children: [jsx(File$1, { className: "w-5 h-5 text-[var(--color-text-muted)]" }), jsx("span", { className: "text-[10px] text-[var(--color-text-secondary)] truncate w-full", children: (_a = attachment.file.name.split(".").pop()) === null || _a === void 0 ? void 0 : _a.toUpperCase() })] })), jsx("button", { onClick: () => removeAttachment(attachment.id), className: "absolute -top-1.5 -right-1.5 size-5 rounded-full bg-[var(--color-danger)] text-[var(--color-danger-contrast)] flex items-center justify-center opacity-0 translate-y-1 group-hover:translate-y-0 group-hover:opacity-100 transition-all duration-300 ease-in-out cursor-pointer shadow-md", "aria-label": `Remove ${attachment.file.name}`, children: jsx(X, { className: "size-3", weight: "bold" }) })] }, attachment.id));
+                            return (jsxs("div", { className: "relative group rounded-lg border border-[var(--color-border)] bg-white", children: [attachment.type === "image" ? (attachment.isCompressing ? (jsx("div", { className: "size-12 flex items-center justify-center bg-gray-100 rounded-lg", children: jsx("div", { className: "w-4 h-4 border-2 border-gray-300 border-t-[var(--color-primary)] rounded-full animate-spin" }) })) : (jsx("img", { src: attachment.previewUrl, alt: attachment.file.name, className: "size-12 object-cover rounded-lg" }))) : (jsxs("div", { className: "size-12 flex flex-col items-center justify-center text-center p-1 rounded-lg", children: [jsx(File$1, { className: "w-5 h-5 text-[var(--color-text-muted)]" }), jsx("span", { className: "text-[10px] text-[var(--color-text-secondary)] truncate w-full", children: (_a = attachment.file.name.split(".").pop()) === null || _a === void 0 ? void 0 : _a.toUpperCase() })] })), jsx("button", { onClick: () => removeAttachment(attachment.id), className: "absolute -top-1.5 -right-1.5 size-5 rounded-full bg-[var(--color-danger)] text-[var(--color-danger-contrast)] flex items-center justify-center opacity-0 translate-y-1 group-hover:translate-y-0 group-hover:opacity-100 transition-all duration-[var(--motion-duration-slow)] ease-in-out cursor-pointer shadow-md", "aria-label": `Remove ${attachment.file.name}`, children: jsx(X, { className: "size-3", weight: "bold" }) })] }, attachment.id));
                         }) })), jsxs("div", { className: cn("flex gap-2", variant === "simple" ? "items-end" : "items-start"), children: [jsx(AnimatePresence, { mode: "wait", initial: false, children: isRecording && enableVoiceRecording ? (jsx(motion.div, { variants: textareaSwapVariants, initial: "initial", animate: "animate", exit: "exit", className: "flex-1 min-w-0", children: jsx("p", { className: "text-center text-sm text-[var(--color-text-placeholder)]", children: placeholder }) }, "voice-recorder")) : (jsx(motion.div, { variants: textareaSwapVariants, initial: "initial", animate: "animate", exit: "exit", className: cn("flex-1 min-w-0", variant === "simple" && "flex items-end"), children: jsx(Textarea, { ref: textareaRef, id: id, unstyled: true, value: currentValue, onChange: handleChange, onKeyDown: handleKeyDown, onPaste: handlePaste, placeholder: placeholder, disabled: isDisabled, maxLength: maxLength, rows: rows, "aria-label": ariaLabel || "Prompt input", "aria-describedby": helperTextId, "aria-invalid": isInvalid, "aria-disabled": isDisabled, className: cn(mergedTheme.textareaStyle, variant === "simple" &&
                                             "!w-auto flex-1 min-w-0 justify-center", textareaClassName), style: {
                                             minHeight,
@@ -557,7 +557,7 @@ className, textareaClassName, footerClassName, theme = {},
                                                     : internalModel, onSelectionChange: handleModelChange, children: [jsx(Dropdown.Trigger, { children: jsxs(Button, { variant: "outline", color: "mono", size: "sm", 
                                                             // Hover + open active state now come from Dropdown.Trigger
                                                             // (unified surface-hover tint). `group` stays for the chevron flip.
-                                                            className: "group bg-transparent rounded-full border-0 font-medium text-[var(--color-text-secondary)]", "aria-label": "Select AI model", disabled: isDisabled, children: [modelMap[currentModel] || "Select Model", jsx(CaretDown, { className: "size-3 opacity-80 transition-transform duration-200 group-aria-[expanded=true]:rotate-180", weight: "bold" })] }) }), jsx(Dropdown.Menu, { children: models.map((model) => (jsx(Dropdown.Item, { itemKey: model.key, startContent: model.icon, children: model.label }, model.key))) })] }))] }), jsx("div", { children: renderSubmitButton("sm", "outline", "mono") })] }, "footer-controls")) }) }))] }), displayHelperText && (jsx("div", { id: helperTextId, className: cn("mt-1 text-sm", isInvalid
+                                                            className: "group bg-transparent rounded-full border-0 font-medium text-[var(--color-text-secondary)]", "aria-label": "Select AI model", disabled: isDisabled, children: [modelMap[currentModel] || "Select Model", jsx(CaretDown, { className: "size-3 opacity-80 transition-transform duration-[var(--motion-duration-base)] group-aria-[expanded=true]:rotate-180", weight: "bold" })] }) }), jsx(Dropdown.Menu, { children: models.map((model) => (jsx(Dropdown.Item, { itemKey: model.key, startContent: model.icon, children: model.label }, model.key))) })] }))] }), jsx("div", { children: renderSubmitButton("sm", "outline", "mono") })] }, "footer-controls")) }) }))] }), displayHelperText && (jsx("div", { id: helperTextId, className: cn("mt-1 text-sm", isInvalid
                     ? "text-[var(--color-danger)]"
                     : "text-[var(--color-text-muted)]"), role: isInvalid ? "alert" : undefined, "aria-live": isInvalid ? "polite" : undefined, children: displayHelperText }))] }));
 });

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

@@ -4,14 +4,14 @@ const promptInputTheme = {
     // self-contained here rather than importing the shared forms theme. Border is an inset
     // box-shadow (not `border`/`outline`) so it's clip-safe and reflow-free, like the inputs.
     baseStyle: "relative flex flex-col gap-2 p-4 rounded-[var(--card-radius)] " +
-        "bg-white dark:bg-[var(--color-background-secondary)] transition-all " +
+        "bg-white dark:bg-[var(--color-surface)] transition-all " +
         "outline-none shadow-[inset_0_0_0_1px_var(--color-border)] " +
         "focus-within:shadow-[inset_0_0_0_1px_var(--color-primary-600)] " +
         "focus-within:ring-4 focus-within:ring-[var(--color-primary)]/10 " +
         "not-focus-within:hover:shadow-[inset_0_0_0_1px_var(--color-border-secondary)] " +
         "dark:focus-within:shadow-[inset_0_0_0_1px_var(--color-primary-500)] " +
         "dark:focus-within:ring-[var(--color-primary-500)]/20",
-    textareaStyle: "w-full bg-transparent text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-placeholder)] focus:outline-none resize-none overflow-y-auto transition-[height] duration-200 ease-in-out",
+    textareaStyle: "w-full bg-transparent text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-placeholder)] focus:outline-none resize-none overflow-y-auto transition-[height] duration-[var(--motion-duration-base)] ease-in-out",
     footerStyle: "flex justify-between items-end",
     actionsStyle: "flex gap-1",
     submitButtonStyle: "rounded-full",

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

@@ -3,8 +3,8 @@ const promptSuggestionTheme = {
         "bg-[var(--color-surface)] " +
         "border border-[var(--color-border)] " +
         "text-sm text-[var(--color-text-primary)] " +
-        "cursor-pointer transition-all duration-300 " +
-        "hover:bg-[var(--color-background-secondary)] " +
+        "cursor-pointer transition-all duration-[var(--motion-duration-slow)] " +
+        "hover:bg-[var(--color-surface)] " +
         "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.js

@@ -1,10 +1,34 @@
 "use client";
 import { jsx } from 'react/jsx-runtime';
-import React__default from 'react';
+import React__default, { useMemo } from 'react';
+import { Sparkle } from '@phosphor-icons/react';
 import { AgentStatus } from '../AgentStatus/AgentStatus.js';
+import { reasoningTheme } from './Reasoning.theme.js';
+import { ReasoningTrace } from './ReasoningTrace.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 }));
+// Reasoning keeps AgentStatus's disclosure, timer, live-region, and reduced-motion
+// behavior, then adds a richer trace body for steps, prose, search, and coding.
+const ReasoningRoot = React__default.forwardRef(({ variant = "steps", steps, query, remainingCount, status = "active", icon, indicator, divider = false, children, theme: themeOverrides, ...rest }, ref) => {
+    const disclosureTheme = useMemo(() => {
+        const overrides = { ...themeOverrides };
+        delete overrides.trace;
+        return {
+            ...reasoningTheme.disclosure,
+            ...overrides,
+            stateStyles: {
+                ...reasoningTheme.disclosure.stateStyles,
+                ...overrides.stateStyles,
+            },
+            indicatorStyles: {
+                ...reasoningTheme.disclosure.indicatorStyles,
+                ...overrides.indicatorStyles,
+            },
+        };
+    }, [themeOverrides]);
+    const traceTheme = useMemo(() => ({ ...reasoningTheme.trace, ...themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.trace }), [themeOverrides]);
+    const body = steps ? (jsx(ReasoningTrace, { variant: variant, steps: steps, query: query, remainingCount: remainingCount, theme: traceTheme })) : (children);
+    return (jsx(AgentStatus, { ref: ref, mode: "reasoning", status: status, icon: icon !== null && icon !== void 0 ? icon : (jsx(Sparkle, { "data-reasoning-summary-icon": "", className: "size-3.5", weight: status === "active" ? "fill" : "regular" })), indicator: indicator !== null && indicator !== void 0 ? indicator : true, divider: divider, theme: disclosureTheme, ...rest, children: body }));
+});
 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 })));

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

@@ -0,0 +1,6 @@
+import type { ReasoningTraceTheme, ReasoningThemeOverrides } from "./Reasoning.types";
+export interface ReasoningTheme {
+    disclosure: ReasoningThemeOverrides;
+    trace: ReasoningTraceTheme;
+}
+export declare const reasoningTheme: ReasoningTheme;

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

@@ -0,0 +1,36 @@
+const reasoningTheme = {
+    disclosure: {
+        reasoningRootStyle: "w-full min-w-0",
+        triggerStyle: "-mx-1.5 flex w-fit max-w-full items-center rounded-[var(--form-radius)] px-1.5 py-1 text-left " +
+            "transition-colors duration-[var(--motion-duration-fast)] ease-out hover:bg-[var(--color-surface-hover)] " +
+            "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)]",
+        triggerContentStyle: "inline-flex min-w-0 items-center gap-1.5",
+        chevronStyle: "inline-flex size-3.5 shrink-0 items-center justify-center text-[var(--color-text-muted)]",
+        dividerStyle: "hidden",
+        contentStyle: "w-full min-w-0 overflow-hidden",
+        contentInnerStyle: "w-full min-w-0 pt-1",
+        proseStyle: "flex flex-col gap-2 pl-5 text-sm leading-relaxed text-[var(--color-text-secondary)] [&_p]:m-0",
+    },
+    trace: {
+        traceStyle: "relative min-w-0 py-1",
+        guideStyle: "pointer-events-none absolute bottom-3 left-[13px] top-3 w-px bg-[var(--color-border)]",
+        listStyle: "relative flex min-w-0 flex-col gap-0.5",
+        itemStyle: "relative flex min-h-7 min-w-0 items-start gap-2 rounded-[calc(var(--radius-base)*0.75)] px-1.5 py-1 text-left",
+        interactiveItemStyle: "transition-colors duration-[var(--motion-duration-fast)] ease-out hover:bg-[var(--color-surface-hover)] " +
+            "focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--color-primary)]",
+        indicatorStyle: "relative z-10 mt-0.5 flex size-3.5 shrink-0 items-center justify-center",
+        indicatorSurfaceStyle: "rounded-full bg-[var(--color-surface)] ring-2 ring-[var(--color-surface)]",
+        primaryStyle: "min-w-0 flex-1 text-sm font-medium leading-5 text-[var(--color-text-primary)]",
+        reasoningPrimaryStyle: "min-w-0 flex-1 text-sm font-normal leading-relaxed text-[var(--color-text-secondary)]",
+        secondaryStyle: "shrink-0 text-xs leading-5 text-[var(--color-text-muted)]",
+        queryStyle: "mb-0.5 flex min-h-7 min-w-0 items-center gap-2 rounded-[calc(var(--radius-base)*0.75)] px-1.5 py-1",
+        queryIconStyle: "ml-px flex size-3.5 shrink-0 items-center justify-center text-[var(--color-text-muted)]",
+        queryTextStyle: "min-w-0 truncate text-sm leading-5 text-[var(--color-text-secondary)]",
+        diffStyle: "shrink-0 font-mono text-xs leading-5 tabular-nums",
+        additionsStyle: "text-[var(--color-success)]",
+        deletionsStyle: "text-[var(--color-danger)]",
+        remainingStyle: "ml-5 px-1.5 py-1 text-xs text-[var(--color-text-muted)]",
+    },
+};
+
+export { reasoningTheme };

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

@@ -1,14 +1,67 @@
 import React from "react";
-import type { AgentStatusProps, AgentStatusState, AgentStatusStepData, AgentStatusThemeOverrides } from "../AgentStatus";
+import type { AgentStatusProps, AgentStatusState, AgentStatusThemeOverrides } from "../AgentStatus";
+export type ReasoningVariant = "steps" | "reasoning" | "search" | "coding";
+export type ReasoningStepKind = "step" | "source" | "read" | "edit" | "command";
+export interface ReasoningTraceTheme {
+    traceStyle: string;
+    guideStyle: string;
+    listStyle: string;
+    itemStyle: string;
+    interactiveItemStyle: string;
+    indicatorStyle: string;
+    indicatorSurfaceStyle: string;
+    primaryStyle: string;
+    reasoningPrimaryStyle: string;
+    secondaryStyle: string;
+    queryStyle: string;
+    queryIconStyle: string;
+    queryTextStyle: string;
+    diffStyle: string;
+    additionsStyle: string;
+    deletionsStyle: string;
+    remainingStyle: string;
+}
 /**
  * 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 ReasoningProps extends Omit<AgentStatusProps, "mode" | "steps" | "theme"> {
+    /** Trace presentation. @default "steps" */
+    variant?: ReasoningVariant;
+    /** Structured trace rows. Existing `{ label, status, duration }` rows remain valid. */
+    steps?: ReasoningStepData[];
+    /** Search query shown before source rows when `variant="search"`. */
+    query?: React.ReactNode;
+    /** Additional undisclosed results, rendered as “+N more”. */
+    remainingCount?: number;
+    theme?: ReasoningThemeOverrides;
+}
+/** A structured reasoning, search-source, or coding-tool trace row. */
+export interface ReasoningStepData {
+    id?: React.Key;
+    label: React.ReactNode;
+    status?: AgentStatusState;
+    /** Elapsed or final step duration in seconds. */
+    duration?: number;
+    /** Secondary metadata such as a domain, file path, result count, or command. */
+    description?: React.ReactNode;
+    /** Optional destination. Rows with an href render as links. */
+    href?: string;
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+    /** Uses the code font for secondary metadata. */
+    mono?: boolean;
+    /** Optional row glyph; inferred from `variant`/`kind` when omitted. */
+    icon?: React.ReactNode;
+    /** Tool/source semantics used to select a default glyph. */
+    kind?: ReasoningStepKind;
+    additions?: number;
+    deletions?: number;
+}
+export interface ReasoningThemeOverrides extends AgentStatusThemeOverrides {
+    trace?: Partial<ReasoningTraceTheme>;
+}
 export interface ReasoningStepProps {
     /** Step state — drives the indicator glyph. @default "complete" */
     status?: AgentStatusState;

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

@@ -0,0 +1,11 @@
+import React from "react";
+import type { ReasoningStepData, ReasoningTraceTheme, ReasoningVariant } from "./Reasoning.types";
+interface ReasoningTraceProps {
+    variant: ReasoningVariant;
+    steps: ReasoningStepData[];
+    query?: React.ReactNode;
+    remainingCount?: number;
+    theme: ReasoningTraceTheme;
+}
+export declare const ReasoningTrace: React.FC<ReasoningTraceProps>;
+export {};

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

@@ -0,0 +1,84 @@
+"use client";
+import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
+import { MagnifyingGlass, GlobeSimple, FileText, TerminalWindow, PencilSimple, WarningCircle, Clock, Check, CircleNotch } from '@phosphor-icons/react';
+import { useReducedMotion, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+
+const formatDuration = (duration) => {
+    const safe = Math.max(0, duration);
+    const rounded = safe < 60 ? Math.round(safe * 10) / 10 : Math.round(safe);
+    if (rounded < 60) {
+        return `${rounded.toFixed(Number.isInteger(rounded) ? 0 : 1)}s`;
+    }
+    return `${Math.floor(rounded / 60)}m ${rounded % 60}s`;
+};
+const statusTone = (status) => {
+    switch (status) {
+        case "active":
+            return "text-[var(--color-primary)]";
+        case "complete":
+            return "text-[var(--color-success)]";
+        case "pending":
+            return "text-[var(--color-text-placeholder)]";
+        case "error":
+            return "text-[var(--color-danger)]";
+        default:
+            return "text-[var(--color-text-muted)]";
+    }
+};
+const stateGlyph = (step) => {
+    var _a;
+    if (step.icon)
+        return step.icon;
+    switch ((_a = step.status) !== null && _a !== void 0 ? _a : "complete") {
+        case "active":
+            return jsx(CircleNotch, { className: "size-3.5 animate-spin" });
+        case "complete":
+            return jsx(Check, { className: "size-3.5", weight: "bold" });
+        case "pending":
+            return jsx(Clock, { className: "size-3.5" });
+        case "error":
+            return jsx(WarningCircle, { className: "size-3.5", weight: "fill" });
+        default:
+            return jsx("span", { className: "size-1.5 rounded-full bg-current" });
+    }
+};
+const traceGlyph = (variant, step) => {
+    if (step.icon)
+        return step.icon;
+    if (variant === "steps")
+        return stateGlyph(step);
+    if (variant === "search" || step.kind === "source") {
+        return jsx(GlobeSimple, { className: "size-3.5" });
+    }
+    if (variant === "coding") {
+        switch (step.kind) {
+            case "edit":
+                return jsx(PencilSimple, { className: "size-3.5" });
+            case "command":
+                return jsx(TerminalWindow, { className: "size-3.5" });
+            default:
+                return jsx(FileText, { className: "size-3.5" });
+        }
+    }
+    return jsx("span", { className: "size-1.5 rounded-full bg-current" });
+};
+const ReasoningTrace = ({ variant, steps, query, remainingCount = 0, theme, }) => {
+    const shouldReduceMotion = useReducedMotion();
+    return (jsxs("div", { className: theme.traceStyle, "data-reasoning-variant": variant, children: [steps.length > 1 && (jsx("span", { className: theme.guideStyle, "data-reasoning-trace-guide": "", "aria-hidden": "true" })), query !== undefined && (jsxs(motion.div, { className: theme.queryStyle, initial: shouldReduceMotion ? false : { opacity: 0, y: -3 }, animate: { opacity: 1, y: 0 }, transition: { duration: shouldReduceMotion ? 0 : 0.18 }, children: [jsx("span", { className: theme.queryIconStyle, "aria-hidden": "true", children: jsx(MagnifyingGlass, { className: "size-full" }) }), jsx("span", { className: theme.queryTextStyle, children: query })] })), jsx("ol", { className: theme.listStyle, children: steps.map((step, index) => {
+                    var _a, _b, _c, _d;
+                    const status = (_a = step.status) !== null && _a !== void 0 ? _a : "complete";
+                    const metadata = (_b = step.description) !== null && _b !== void 0 ? _b : (step.duration !== undefined ? formatDuration(step.duration) : undefined);
+                    const rowClassName = cn(theme.itemStyle, step.href && theme.interactiveItemStyle);
+                    const content = (jsxs(Fragment, { children: [jsx("span", { className: cn(theme.indicatorStyle, theme.indicatorSurfaceStyle, statusTone(variant === "steps" ? status : undefined)), "aria-hidden": "true", children: traceGlyph(variant, step) }), jsx("span", { className: variant === "reasoning"
+                                    ? theme.reasoningPrimaryStyle
+                                    : theme.primaryStyle, children: step.label }), metadata !== undefined && (jsx("span", { className: cn(theme.secondaryStyle, step.mono && "font-mono"), children: metadata })), (step.additions !== undefined || step.deletions !== undefined) && (jsxs("span", { className: theme.diffStyle, "aria-label": "Code changes", children: [step.additions !== undefined && (jsxs("span", { className: theme.additionsStyle, children: ["+", step.additions] })), step.additions !== undefined && step.deletions !== undefined && " ", step.deletions !== undefined && (jsxs("span", { className: theme.deletionsStyle, children: ["\u2212", step.deletions] }))] }))] }));
+                    return (jsx(motion.li, { initial: shouldReduceMotion ? false : { opacity: 0, y: -3 }, animate: { opacity: 1, y: 0 }, transition: {
+                            duration: shouldReduceMotion ? 0 : 0.2,
+                            delay: shouldReduceMotion ? 0 : index * 0.045,
+                            ease: [0.23, 1, 0.32, 1],
+                        }, className: "min-w-0", children: step.href ? (jsx("a", { href: step.href, target: step.target, rel: (_c = step.rel) !== null && _c !== void 0 ? _c : (step.target === "_blank" ? "noreferrer" : undefined), className: rowClassName, children: content })) : (jsx("div", { className: rowClassName, children: content })) }, (_d = step.id) !== null && _d !== void 0 ? _d : index));
+                }) }), remainingCount > 0 && (jsxs(motion.div, { className: theme.remainingStyle, initial: shouldReduceMotion ? false : { opacity: 0 }, animate: { opacity: 1 }, transition: { duration: shouldReduceMotion ? 0 : 0.2 }, children: ["+", remainingCount, " more"] }))] }));
+};
+
+export { ReasoningTrace };

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

@@ -1,2 +1,3 @@
 export { Reasoning } from "./Reasoning";
-export type { ReasoningProps, ReasoningStepProps, ReasoningStepData, ReasoningThemeOverrides, } from "./Reasoning.types";
+export { reasoningTheme } from "./Reasoning.theme";
+export type { ReasoningProps, ReasoningStepProps, ReasoningStepData, ReasoningStepKind, ReasoningTraceTheme, ReasoningVariant, ReasoningThemeOverrides, } from "./Reasoning.types";

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

@@ -4,6 +4,7 @@
  * Only animates the most recent tokens for performance
  */
 import React from 'react';
+import type { StreamingTokenEffect } from './StreamingResponse.types';
 export interface AnimatedTextProps {
     /** The full accumulated text */
     text: string;
@@ -15,6 +16,12 @@ export interface AnimatedTextProps {
     enabled?: boolean;
     /** Additional CSS classes */
     className?: string;
+    /** Optional inline indicator rendered immediately after the text */
+    cursor?: React.ReactNode;
+    /** Visual treatment for newly arrived words */
+    tokenEffect?: StreamingTokenEffect;
+    /** New-word transition duration in seconds */
+    tokenDuration?: number;
 }
 /**
  * AnimatedText renders streaming text with smooth per-token fade-in.

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';