@candor-ui/react 1.7.0 → 1.9.0

package/dist/adapters/claude-agent-sdk.d.ts

@@ -144,6 +144,21 @@ export type FromClaudeAgentOptions = {
      * Claude's own citations and web search results are read without it.
      */
     sourcesFrom?: ((tool: string, input: unknown, output: string) => ToolSource[] | undefined) | undefined;
+    /**
+     * The words for lines the adapter adds to the thread itself, as system messages: when the SDK summarised earlier
+     * messages to make room (`compacted`, given how it was started), and when the conversation was cleared (`cleared`).
+     * Defaults are in English; pass your own for other languages.
+     */
+    eventText?: {
+        compacted?: ((trigger: "manual" | "auto") => string) | undefined;
+        cleared?: string | undefined;
+    } | undefined;
+};
+/** A memory the SDK recalled for a reply: the file (or URL) it came from, and whose memory it is. */
+export type ClaudeRecalledMemory = {
+    path: string;
+    scope: "personal" | "team" | "organization";
+    content?: string | undefined;
 };
 export type ClaudeAgentState = {
     messages: Message[];
@@ -156,6 +171,8 @@ export type ClaudeAgentState = {
     notice?: string | undefined;
     /** The permission mode last reported, by the SDK or the app. Absent until one is. */
     permissionMode?: ClaudePermissionMode | undefined;
+    /** Memories the SDK recalled for each reply, by the reply's message id, for a `MemoryUsed` line under it. Only replies that recalled any. */
+    recalled?: Record<string, ClaudeRecalledMemory[]> | undefined;
 };
 /**
  * Turns Claude Agent SDK events into Candor messages, waiting approvals and usage.

package/dist/adapters/claude-agent-sdk.js

@@ -1,4 +1,8 @@
 import { markdownBlocks, plainBlocks } from "../lib/safe-markdown.js";
+const compactedText = (trigger) => trigger === "auto"
+    ? "Earlier messages were summarised to make room. The agent works from that summary now; the messages above are unchanged."
+    : "Earlier messages were summarised, as asked. The agent works from that summary now; the messages above are unchanged.";
+const clearedText = "The conversation was cleared. The agent doesn’t see the messages above.";
 /**
  * Turns Claude Agent SDK events into Candor messages, waiting approvals and usage.
  * Pure, so it can run on every render; useClaudeAgent calls it for you.
@@ -14,11 +18,35 @@ export function fromClaudeAgentEvents(events, options) {
     let lastCost = 0;
     let notice;
     let permissionMode;
-    const current = (id) => (reply ??= { id, parts: [], reasoning: [], tools: new Map(), live: new Map(), sources: new Map(), inputs: new Map() });
+    const recalled = {};
+    // Memories recalled before the reply they're for has started.
+    let recalling = [];
+    const current = (id) => {
+        if (!reply) {
+            reply = { id, parts: [], reasoning: [], tools: new Map(), live: new Map(), sources: new Map(), inputs: new Map(), memories: recalling };
+            recalling = [];
+        }
+        return reply;
+    };
+    // Lines that arrived while a reply was still going: shown after it, so one turn stays one reply.
+    let afterReply = [];
     const close = (last) => {
-        if (reply)
+        if (reply) {
             messages.push(render(reply, { ...options, model, last }));
+            if (reply.memories.length)
+                recalled[reply.id] = reply.memories;
+        }
         reply = null;
+        messages.push(...afterReply);
+        afterReply = [];
+    };
+    // A line the adapter adds between replies: the app's own words, drawn like any system message.
+    const systemLine = (id, text) => {
+        const line = { id, author: { role: "system" }, status: "complete", blocks: plainBlocks(text) };
+        if (reply)
+            afterReply.push(line);
+        else
+            messages.push(line);
     };
     for (const e of events) {
         // Subagents report through their parent's tool call; the main thread is what the person reads.
@@ -90,6 +118,21 @@ export function fromClaudeAgentEvents(events, options) {
                 else if (e.subtype === "api_retry") {
                     notice = `Claude’s API didn’t answer${e.error_status ? ` (${e.error_status})` : ""}; trying again, attempt ${e.attempt} of ${e.max_retries}.`;
                 }
+                else if (e.subtype === "compact_boundary") {
+                    // Without this line the person can't tell the agent no longer has the earlier messages word for word.
+                    const trigger = e.compact_metadata.trigger;
+                    systemLine(`compact-${e.uuid}`, options.eventText?.compacted?.(trigger) ?? compactedText(trigger));
+                }
+                else if (e.subtype === "memory_recall") {
+                    const found = e.memories.map((m) => ({ path: m.path, scope: m.scope, ...(m.content !== undefined && { content: m.content }) }));
+                    if (reply)
+                        reply.memories.push(...found);
+                    else
+                        recalling.push(...found);
+                }
+                break;
+            case "conversation_reset":
+                systemLine(`reset-${e.uuid}`, options.eventText?.cleared ?? clearedText);
                 break;
             case "stream_event": {
                 const r = current(e.uuid);
@@ -170,6 +213,7 @@ export function fromClaudeAgentEvents(events, options) {
         usage,
         notice: options.running ? notice : undefined,
         permissionMode,
+        recalled,
     };
 }
 /** Adds a source once (by key) and returns its id. Markers count up in the order sources first appear. */

package/dist/blocks/copy-field.d.ts

@@ -7,7 +7,8 @@ export declare const copyFieldStrings: {
 /**
  * A value a person copies somewhere else (a callback URL, a scope list). The
  * whole field is the copy target; it says "Copied" only once the clipboard
- * took the value.
+ * took the value, and its tick (or the cross of a refused write) appears then,
+ * never while the write is still pending.
  */
 declare function CopyField({ label, value, className, }: {
     /** What the value is, shown above it. */

package/dist/blocks/copy-field.js

@@ -13,11 +13,12 @@ export const copyFieldStrings = {
 /**
  * A value a person copies somewhere else (a callback URL, a scope list). The
  * whole field is the copy target; it says "Copied" only once the clipboard
- * took the value.
+ * took the value, and its tick (or the cross of a refused write) appears then,
+ * never while the write is still pending.
  */
 function CopyField({ label, value, className, }) {
     const { state, copy } = useCopy();
     const t = useStrings("copyField", copyFieldStrings);
-    return (_jsxs("div", { "data-slot": "copy-field", className: cn("flex flex-col gap-1", className), children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: label }), _jsxs("button", { type: "button", onClick: () => copy(value), className: "group/copy flex w-full items-center gap-2 rounded-lg border bg-sunken px-3 py-2 text-start outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/80", children: [_jsx("code", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: value }), _jsx("span", { "aria-live": "polite", className: "inline-flex shrink-0 items-center gap-1 text-xs text-muted-foreground group-hover/copy:text-foreground", children: state === "copied" ? (_jsxs(_Fragment, { children: [_jsx(Check, { className: "size-3 text-success-text" }), " ", t("copied")] })) : state === "failed" ? (_jsxs(_Fragment, { children: [_jsx(X, { className: "size-3 text-destructive-text" }), " ", t("failed")] })) : (_jsxs(_Fragment, { children: [_jsx(Copy, { className: "size-3" }), " ", t("copy")] })) })] })] }));
+    return (_jsxs("div", { "data-slot": "copy-field", className: cn("flex flex-col gap-1", className), children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: label }), _jsxs("button", { type: "button", onClick: () => copy(value), className: "group/copy flex w-full items-center gap-2 rounded-lg border bg-sunken px-3 py-2 text-start outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/80", children: [_jsx("code", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: value }), _jsx("span", { "aria-live": "polite", "data-copy": state, className: "inline-flex shrink-0 items-center gap-1 text-xs text-muted-foreground group-hover/copy:text-foreground", children: state === "copied" ? (_jsxs(_Fragment, { children: [_jsx(Check, { className: "size-3 text-success-text animate-pop-in" }), " ", t("copied")] })) : state === "failed" ? (_jsxs(_Fragment, { children: [_jsx(X, { className: "size-3 text-destructive-text animate-pop-in" }), " ", t("failed")] })) : (_jsxs(_Fragment, { children: [_jsx(Copy, { className: "size-3" }), " ", t("copy")] })) })] })] }));
 }
 export { CopyField };

package/dist/blocks/locked.d.ts

@@ -13,7 +13,10 @@ type Lockable = React.ReactElement<{
  * marked `aria-disabled`, its activation is blocked (click, Enter, Space), and
  * it is described by the reason — so keyboard and screen-reader users reach
  * the explanation on the control itself. The reason shows as a tooltip, or
- * printed under the control with `inline`.
+ * printed under the control with `inline`. Pressing the control reveals the
+ * reason (the tooltip is held open, the printed reason is emphasised) and,
+ * under data-motion="expressive" only, shakes it briefly; with reduced motion
+ * or the default subtle preset, only the reason is shown.
  */
 declare function Locked({ reason, inline, children, className, }: {
     /** Why the control can't be used. Without one, the control renders as normal. */

package/dist/blocks/locked.js

@@ -11,15 +11,37 @@ import { Tooltip, TooltipContent, TooltipTrigger } from "../ui/tooltip.js";
  * marked `aria-disabled`, its activation is blocked (click, Enter, Space), and
  * it is described by the reason — so keyboard and screen-reader users reach
  * the explanation on the control itself. The reason shows as a tooltip, or
- * printed under the control with `inline`.
+ * printed under the control with `inline`. Pressing the control reveals the
+ * reason (the tooltip is held open, the printed reason is emphasised) and,
+ * under data-motion="expressive" only, shakes it briefly; with reduced motion
+ * or the default subtle preset, only the reason is shown.
  */
 function Locked({ reason, inline = false, children, className, }) {
     const id = React.useId();
+    // The tooltip as hover and focus drive it, and a press, which holds the reason open and shakes (when expressive).
+    // `press` counts presses so a second one restarts both timers.
+    const [shown, setShown] = React.useState(false);
+    const [press, setPress] = React.useState(0);
+    const [shaking, setShaking] = React.useState(false);
+    const [held, setHeld] = React.useState(false);
+    React.useEffect(() => {
+        if (press === 0)
+            return;
+        const shake = window.setTimeout(() => setShaking(false), 400);
+        const hold = window.setTimeout(() => setHeld(false), 1800);
+        return () => {
+            window.clearTimeout(shake);
+            window.clearTimeout(hold);
+        };
+    }, [press]);
     if (!reason)
         return children;
     const block = (e) => {
         e.preventDefault();
         e.stopPropagation();
+        setPress((n) => n + 1);
+        setShaking(true);
+        setHeld(true);
     };
     const control = React.cloneElement(children, {
         "aria-disabled": true,
@@ -31,6 +53,6 @@ function Locked({ reason, inline = false, children, className, }) {
                 block(e);
         },
     });
-    return (_jsxs("span", { "data-slot": "locked", className: cn("relative inline-flex flex-col items-start gap-1.5", className), children: [inline ? (control) : (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: control }), _jsx(TooltipContent, { children: reason })] })), _jsxs("span", { id: id, className: cn("items-center gap-1 text-xs text-muted-foreground", inline ? "inline-flex" : "sr-only"), children: [_jsx(LockKeyhole, { "aria-hidden": true, className: "size-3" }), reason] })] }));
+    return (_jsxs("span", { "data-slot": "locked", "data-pressed": held ? "" : undefined, className: cn("relative inline-flex flex-col items-start gap-1.5", shaking && "animate-shake", className), children: [inline ? (control) : (_jsxs(Tooltip, { open: shown || held, onOpenChange: setShown, children: [_jsx(TooltipTrigger, { asChild: true, children: control }), _jsx(TooltipContent, { children: reason })] })), _jsxs("span", { id: id, "data-slot": "locked-reason", className: cn("items-center gap-1 text-xs text-muted-foreground transition-colors duration-(--cd-dur-base)", inline ? "inline-flex" : "sr-only", held && "text-foreground"), children: [_jsx(LockKeyhole, { "aria-hidden": true, className: "size-3" }), reason] })] }));
 }
 export { Locked };

package/dist/blocks/status-dot.d.ts

@@ -1,7 +1,10 @@
+import * as React from "react";
 import { type RunStatus } from "../lib/status.js";
 /**
  * A small status mark. Running and waiting pulse, since they are the two
- * states a person may need to watch or act on. The label is always available
+ * states a person may need to watch or act on. When one of them reaches done
+ * or failed while on screen, the new dot pops into place (too small for a drawn
+ * mark); a dot that mounts finished is still. The label is always available
  * to assistive tech; pass `showLabel` to print it too.
  */
 declare function StatusDot({ status, showLabel, label, className, }: {
@@ -12,5 +15,5 @@ declare function StatusDot({ status, showLabel, label, className, }: {
     /** Words to use instead of the status name. */
     label?: string | undefined;
     className?: string | undefined;
-}): import("react").JSX.Element;
+}): React.JSX.Element;
 export { StatusDot };

package/dist/blocks/status-dot.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
 import { cn } from "../lib/utils.js";
 import { useStatusLabel } from "../lib/status.js";
 const dotColor = {
@@ -13,15 +14,35 @@ const dotColor = {
     cancelled: "bg-faint-foreground/60",
     skipped: "bg-faint-foreground/40",
 };
+const finished = (status) => status === "succeeded" || status === "failed";
+const over = (status) => finished(status) || status === "cancelled" || status === "skipped";
+/**
+ * How many times the status reached done or failed from an unfinished one while the dot was on screen; zero when it
+ * mounted finished, so nothing moves for a change the reader never saw.
+ */
+function useSettled(status) {
+    const [settled, setSettled] = React.useState(0);
+    const previous = React.useRef(status);
+    React.useLayoutEffect(() => {
+        const was = previous.current;
+        previous.current = status;
+        if (was !== status && !over(was) && finished(status))
+            setSettled((n) => n + 1);
+    }, [status]);
+    return settled;
+}
 /**
  * A small status mark. Running and waiting pulse, since they are the two
- * states a person may need to watch or act on. The label is always available
+ * states a person may need to watch or act on. When one of them reaches done
+ * or failed while on screen, the new dot pops into place (too small for a drawn
+ * mark); a dot that mounts finished is still. The label is always available
  * to assistive tech; pass `showLabel` to print it too.
  */
 function StatusDot({ status, showLabel = false, label, className, }) {
     const statusLabel = useStatusLabel();
     const text = label ?? statusLabel(status);
     const live = status === "running" || status === "waiting";
-    return (_jsxs("span", { "data-slot": "status-dot", "data-status": status, className: cn("inline-flex items-center gap-1.5 text-xs text-muted-foreground", className), children: [_jsx("span", { "aria-hidden": true, className: cn("size-2 shrink-0 rounded-full", dotColor[status], live && "animate-pulse-dot") }), showLabel ? _jsx("span", { children: text }) : _jsx("span", { className: "sr-only", children: text })] }));
+    const settled = useSettled(status);
+    return (_jsxs("span", { "data-slot": "status-dot", "data-status": status, "data-settled": settled > 0 ? "" : undefined, className: cn("inline-flex items-center gap-1.5 text-xs text-muted-foreground", className), children: [_jsx("span", { "aria-hidden": true, className: cn("size-2 shrink-0 rounded-full", dotColor[status], live && "animate-pulse-dot", settled > 0 && "animate-pop-in") }, settled), showLabel ? _jsx("span", { children: text }) : _jsx("span", { className: "sr-only", children: text })] }));
 }
 export { StatusDot };

package/dist/blocks/step-list.d.ts

@@ -7,13 +7,18 @@ export type Step = {
     detail?: React.ReactNode | undefined;
     meta?: React.ReactNode | undefined;
 };
+/**
+ * A step's status as a mark. When the status reaches done or failed while the mark is on screen, the spinner
+ * becomes a tick or cross drawn along its path; a mark that mounts already finished is drawn still.
+ */
 declare function StepMark({ status, }: {
     /** The step's status, which picks its mark. */
     status: RunStatus;
 }): React.JSX.Element;
 /**
  * An ordered list of steps joined by a rail: an agent's plan, its reasoning,
- * a run's stages. The rail fills as steps finish.
+ * a run's stages. The rail fills to each step as it finishes, never ahead of
+ * it, and a step that finishes while on screen draws its mark.
  */
 declare function StepList({ steps, className, }: {
     /** The steps in order, each with a status, and optional detail and meta. */

package/dist/blocks/step-list.js

@@ -1,16 +1,48 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
-import { Check, CircleSlash, Hand, LoaderCircle, X } from "lucide-react";
+import { CircleSlash, Hand, LoaderCircle } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { useStatusLabel } from "../lib/status.js";
+const finished = (status) => status === "succeeded" || status === "failed";
+const over = (status) => finished(status) || status === "cancelled" || status === "skipped";
+/**
+ * How many times `status` has reached succeeded or failed from an unfinished status while this component was on
+ * screen. Zero for something that mounted already finished, so its mark is drawn still: motion reports a change
+ * that was seen, never one that happened before the reader arrived.
+ */
+function useSettled(status) {
+    const [settled, setSettled] = React.useState(0);
+    const previous = React.useRef(status);
+    React.useLayoutEffect(() => {
+        const was = previous.current;
+        previous.current = status;
+        if (was !== status && !over(was) && finished(status))
+            setSettled((n) => n + 1);
+    }, [status]);
+    return settled;
+}
+/** A tick, drawn along its path when `draw` is above zero (and again each time it changes). */
+function Tick({ draw }) {
+    return (_jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 3, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, className: "size-3", children: _jsx("path", { d: "M20 6 9 17l-5-5", pathLength: 1, className: cn(draw > 0 && "[stroke-dasharray:1] animate-tick-draw") }) }, draw));
+}
+/** A cross, its two strokes drawn one after the other when `draw` is above zero. */
+function Cross({ draw }) {
+    const drawn = draw > 0 && "[stroke-dasharray:1] animate-tick-draw";
+    return (_jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 3, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, className: "size-3", children: [_jsx("path", { d: "M18 6 6 18", pathLength: 1, className: cn(drawn) }), _jsx("path", { d: "m6 6 12 12", pathLength: 1, className: cn(drawn, drawn && "[animation-delay:var(--cd-dur-quick)]") })] }, draw));
+}
+/**
+ * A step's status as a mark. When the status reaches done or failed while the mark is on screen, the spinner
+ * becomes a tick or cross drawn along its path; a mark that mounts already finished is drawn still.
+ */
 function StepMark({ status, }) {
-    const base = "relative z-10 flex size-5 shrink-0 items-center justify-center rounded-full";
+    const settled = useSettled(status);
+    const base = "relative z-10 flex size-5 shrink-0 items-center justify-center rounded-full transition-colors duration-(--cd-dur-base) ease-standard";
     switch (status) {
         case "succeeded":
-            return (_jsx("span", { className: cn(base, "bg-success text-on-success"), children: _jsx(Check, { className: "size-3", strokeWidth: 3 }) }));
+            return (_jsx("span", { className: cn(base, "bg-success text-on-success"), "data-settled": settled > 0 ? "" : undefined, children: _jsx(Tick, { draw: settled }) }));
         case "failed":
-            return (_jsx("span", { className: cn(base, "bg-destructive text-on-destructive"), children: _jsx(X, { className: "size-3", strokeWidth: 3 }) }));
+            return (_jsx("span", { className: cn(base, "bg-destructive text-on-destructive"), "data-settled": settled > 0 ? "" : undefined, children: _jsx(Cross, { draw: settled }) }));
         case "running":
             return (_jsx("span", { className: cn(base, "bg-accent-weak text-accent-text"), children: _jsx(LoaderCircle, { className: "size-3.5 animate-spin", strokeWidth: 2.5 }) }));
         case "waiting":
@@ -24,16 +56,18 @@ function StepMark({ status, }) {
             return (_jsx("span", { className: cn(base, "bg-background"), children: _jsx("span", { className: "size-2 rounded-full border-[1.5px] border-faint-foreground/70" }) }));
     }
 }
+function StepRow({ step, index, last, }) {
+    const statusLabel = useStatusLabel();
+    const done = step.status === "succeeded";
+    const settled = useSettled(step.status);
+    return (_jsxs("li", { className: "relative flex gap-3 pb-4 last:pb-0 animate-rise-in", style: { animationDelay: `${index * 40}ms` }, children: [!last && (_jsx("span", { "aria-hidden": true, className: "absolute top-5 bottom-0 start-[9.5px] w-px bg-input", children: done && (_jsx("span", { "data-slot": "step-rail-fill", className: cn("absolute inset-0 origin-top bg-success/50", settled > 0 && "animate-fill [--cd-fill-from:1_0]") }, settled)) })), _jsx(StepMark, { status: step.status }), _jsxs("div", { className: "min-w-0 flex-1 pt-px", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsxs("p", { className: cn("text-sm font-medium", step.status === "idle" && "text-muted-foreground", (step.status === "skipped" || step.status === "cancelled") && "text-faint-foreground line-through"), children: [step.title, _jsxs("span", { className: "sr-only", children: [" \u2014 ", statusLabel(step.status)] })] }), step.meta && _jsx("span", { className: "shrink-0 text-xs tabular-nums text-faint-foreground", children: step.meta })] }), step.detail && _jsx("div", { className: "mt-1 text-[0.8125rem] text-muted-foreground", children: step.detail })] })] }));
+}
 /**
  * An ordered list of steps joined by a rail: an agent's plan, its reasoning,
- * a run's stages. The rail fills as steps finish.
+ * a run's stages. The rail fills to each step as it finishes, never ahead of
+ * it, and a step that finishes while on screen draws its mark.
  */
 function StepList({ steps, className, }) {
-    const statusLabel = useStatusLabel();
-    return (_jsx("ol", { "data-slot": "step-list", className: cn("flex flex-col", className), children: steps.map((step, i) => {
-            const last = i === steps.length - 1;
-            const done = step.status === "succeeded";
-            return (_jsxs("li", { className: "relative flex gap-3 pb-4 last:pb-0 animate-rise-in", style: { animationDelay: `${i * 40}ms` }, children: [!last && (_jsx("span", { "aria-hidden": true, className: cn("absolute top-5 bottom-0 start-[9.5px] w-px transition-colors duration-500", done ? "bg-success/50" : "bg-input") })), _jsx(StepMark, { status: step.status }), _jsxs("div", { className: "min-w-0 flex-1 pt-px", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsxs("p", { className: cn("text-sm font-medium", step.status === "idle" && "text-muted-foreground", (step.status === "skipped" || step.status === "cancelled") && "text-faint-foreground line-through"), children: [step.title, _jsxs("span", { className: "sr-only", children: [" \u2014 ", statusLabel(step.status)] })] }), step.meta && _jsx("span", { className: "shrink-0 text-xs tabular-nums text-faint-foreground", children: step.meta })] }), step.detail && _jsx("div", { className: "mt-1 text-[0.8125rem] text-muted-foreground", children: step.detail })] })] }, step.id));
-        }) }));
+    return (_jsx("ol", { "data-slot": "step-list", className: cn("flex flex-col", className), children: steps.map((step, i) => (_jsx(StepRow, { step: step, index: i, last: i === steps.length - 1 }, step.id))) }));
 }
 export { StepList, StepMark };

package/dist/chat/composer.d.ts

@@ -13,6 +13,7 @@ export declare const composerStrings: {
     hintSend: string;
     hintNewLine: string;
     hintMention: string;
+    hintCommand: string;
     stop: string;
     send: string;
     dropFiles: string;
@@ -42,7 +43,7 @@ export type ComposerState = "ready" | "sending" | "streaming" | {
  * (`{ kind: "held", reason }`) keeps typing open and says why sending waits.
  * `textareaRef` focuses the box from outside, e.g. after a new project starts.
  */
-declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onScopeClick, mentions, commands, references, onReferencesChange, attachments, onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, textareaRef, sendShape, className, }: {
+declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onScopeClick, mentions, commands, references, onReferencesChange, attachments, onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, textareaRef, sendShape, hints, className, }: {
     /** The text in the box. */
     value: string;
     /** Called with the new text as the person types. */
@@ -61,11 +62,11 @@ declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onS
     mentions?: MentionOption[] | undefined;
     /** What / can run, only at the start of a message. */
     commands?: SlashCommand[] | undefined;
-    /** Entities already attached, shown as chips. */
+    /** Entities already attached, shown as chips. A chip added after the composer drew pops in; a removed one pops out. */
     references?: EntityRef[] | undefined;
     /** Called when a chip is added or removed. */
     onReferencesChange?: ((references: EntityRef[]) => void) | undefined;
-    /** Files attached, with upload progress or an error. */
+    /** Files attached, with upload progress or an error, as chips that pop in when added and out when removed. */
     attachments?: Attachment[] | undefined;
     /** Shows an attach button; called with the chosen files. */
     onAttach?: ((files: File[]) => void) | undefined;
@@ -82,6 +83,11 @@ declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onS
     label?: string | undefined;
     /** Your own controls in the toolbar, after the attach button: a dictation button, a model picker. */
     tools?: React.ReactNode | undefined;
+    /**
+     * The keyboard hints shown at wide widths ("↵ send · ⇧↵ new line"), naming @ and / only when `mentions` or
+     * `commands` are given. Defaults to true; false hides them.
+     */
+    hints?: boolean | undefined;
     /** The text box, to focus it or read its selection from outside. */
     textareaRef?: React.Ref<HTMLTextAreaElement> | undefined;
     /** The send button's shape: "square" (the default, rounded corners) or "round". */

package/dist/chat/composer.js

@@ -20,6 +20,7 @@ export const composerStrings = {
     hintSend: "send",
     hintNewLine: "new line",
     hintMention: "mention",
+    hintCommand: "command",
     stop: "Stop",
     send: "Send",
     dropFiles: "Drop files to attach",
@@ -39,6 +40,53 @@ function findTrigger(value, caret) {
 const groupOf = (item, commandsLabel = "Commands") => (item.type === "command" ? commandsLabel : item.option.group);
 /** Whether a drag carries files (not text or a link being dragged around the page). */
 const hasFiles = (e) => Array.from(e.dataTransfer?.types ?? []).includes("Files");
+const referenceKey = (r) => `${r.kind}:${r.name}`;
+const attachmentKey = (a) => a.id;
+/**
+ * Which chips were added after the composer first drew (they pop in) and which were just removed (they pop out as
+ * inert ghosts, then go). Chips present at first render are drawn still: nothing moves for a state the reader
+ * already had. The ghosts are cleared by their animation's end, or after 400ms when nothing animates.
+ */
+function useChipMotion(items, keyOf) {
+    const [entered, setEntered] = React.useState(() => new Set());
+    const [leaving, setLeaving] = React.useState([]);
+    const previous = React.useRef(null);
+    React.useLayoutEffect(() => {
+        const before = previous.current;
+        previous.current = items;
+        if (!before)
+            return;
+        const now = new Set(items.map(keyOf));
+        const was = new Set(before.map(keyOf));
+        const added = items.filter((item) => !was.has(keyOf(item))).map(keyOf);
+        const gone = before.filter((item) => !now.has(keyOf(item)));
+        if (added.length || gone.length) {
+            setEntered((set) => {
+                const next = new Set(set);
+                for (const item of gone)
+                    next.delete(keyOf(item));
+                for (const key of added)
+                    next.add(key);
+                return next;
+            });
+        }
+        if (gone.length)
+            setLeaving((list) => [...list.filter((item) => !now.has(keyOf(item))), ...gone]);
+    }, [items, keyOf]);
+    React.useEffect(() => {
+        if (leaving.length === 0)
+            return;
+        const timer = window.setTimeout(() => setLeaving([]), 400);
+        return () => window.clearTimeout(timer);
+    }, [leaving]);
+    const entering = (item) => entered.has(keyOf(item));
+    const left = (item) => setLeaving((list) => list.filter((x) => x !== item));
+    return { entering, leaving, left };
+}
+/** A removed chip, kept for the length of its pop-out and hidden from assistive tech. */
+function LeavingChip({ onDone, children }) {
+    return (_jsx("span", { "aria-hidden": true, "data-leaving": true, className: "pointer-events-none inline-flex max-w-full animate-pop-out", onAnimationEnd: onDone, children: children }));
+}
 /**
  * Where a person asks. Mentions (@) attach things in the user's system as chips the agent
  * receives as references, not as text it has to parse; slash commands (/) start
@@ -52,7 +100,7 @@ const hasFiles = (e) => Array.from(e.dataTransfer?.types ?? []).includes("Files"
  * (`{ kind: "held", reason }`) keeps typing open and says why sending waits.
  * `textareaRef` focuses the box from outside, e.g. after a new project starts.
  */
-function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, onScopeClick, mentions = [], commands = [], references = [], onReferencesChange, attachments = [], onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, textareaRef, sendShape = "square", className, }) {
+function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, onScopeClick, mentions = [], commands = [], references = [], onReferencesChange, attachments = [], onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, textareaRef, sendShape = "square", hints = true, className, }) {
     const kindOf = useEntityKinds();
     const t = useStrings("composer", composerStrings);
     const placeholder = placeholderProp ?? t("placeholder");
@@ -65,6 +113,8 @@ function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, o
     const fileInput = React.useRef(null);
     const [trigger, setTrigger] = React.useState(null);
     const [active, setActive] = React.useState(0);
+    const referenceMotion = useChipMotion(references, referenceKey);
+    const attachmentMotion = useChipMotion(attachments, attachmentKey);
     const held = typeof state === "object" && state.kind === "held" ? state : null;
     const locked = typeof state === "object" && state.kind !== "held" ? state : null;
     const canAttach = Boolean(onAttach) && !locked;
@@ -197,7 +247,7 @@ function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, o
                                     e.preventDefault();
                                     choose(item);
                                 }, onMouseMove: () => setActive(i), className: "flex cursor-pointer items-center gap-2.5 rounded-md px-2 py-1.5 text-sm aria-selected:bg-accent", children: item.type === "command" ? (_jsxs(_Fragment, { children: [_jsxs("span", { className: "font-mono text-xs text-accent-text", children: ["/", item.command.name] }), item.command.args && _jsx("span", { className: "font-mono text-xs text-faint-foreground", children: item.command.args }), _jsx("span", { className: "ms-auto truncate text-xs text-muted-foreground", children: item.command.description })] })) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "flex size-6 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground", children: Icon ? _jsx(Icon, { className: "size-3.5" }) : _jsx("span", { className: "text-xs", children: "@" }) }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate", children: item.option.label }), (item.option.description ?? item.option.entity?.name) !== item.option.label && (item.option.description ?? item.option.entity?.name) && (_jsx("span", { className: "block truncate font-mono text-2xs text-faint-foreground", children: item.option.description ?? item.option.entity?.name }))] })] })) })] }, item.type === "command" ? item.command.id : item.option.id));
-                }) })), _jsxs("div", { className: cn("rounded-2xl border bg-card shadow-raised transition-[border-color,box-shadow] duration-150 focus-within:border-border-strong focus-within:shadow-float", locked && "bg-muted shadow-none"), children: [(references.length > 0 || attachments.length > 0) && (_jsxs("div", { className: "flex flex-wrap gap-1.5 px-3 pt-3", children: [references.map((r) => (_jsx(EntityChip, { entity: r, onRemove: (e) => onReferencesChange?.(references.filter((x) => x !== e)) }, `${r.kind}:${r.name}`))), attachments.map((a) => (_jsx(AttachmentChip, { attachment: a, onRemove: onRemoveAttachment }, a.id)))] })), _jsx("label", { htmlFor: id, className: "sr-only", children: label }), _jsx("textarea", { ref: textarea, id: id, rows: 1, value: value, disabled: Boolean(locked), placeholder: locked ? undefined : placeholder, onChange: (e) => {
+                }) })), _jsxs("div", { className: cn("rounded-2xl border bg-card shadow-raised transition-[border-color,box-shadow] duration-150 focus-within:border-border-strong focus-within:shadow-float", locked && "bg-muted shadow-none"), children: [(references.length > 0 || attachments.length > 0 || referenceMotion.leaving.length > 0 || attachmentMotion.leaving.length > 0) && (_jsxs("div", { className: "flex flex-wrap gap-1.5 px-3 pt-3", children: [references.map((r) => (_jsx(EntityChip, { entity: r, onRemove: (e) => onReferencesChange?.(references.filter((x) => x !== e)), className: cn(referenceMotion.entering(r) && "animate-pop-in") }, referenceKey(r)))), referenceMotion.leaving.map((r) => (_jsx(LeavingChip, { onDone: () => referenceMotion.left(r), children: _jsx(EntityChip, { entity: r }) }, `leaving:${referenceKey(r)}`))), attachments.map((a) => (_jsx(AttachmentChip, { attachment: a, onRemove: onRemoveAttachment, className: cn(attachmentMotion.entering(a) && "animate-pop-in") }, a.id))), attachmentMotion.leaving.map((a) => (_jsx(LeavingChip, { onDone: () => attachmentMotion.left(a), children: _jsx(AttachmentChip, { attachment: a }) }, `leaving:${a.id}`)))] })), _jsx("label", { htmlFor: id, className: "sr-only", children: label }), _jsx("textarea", { ref: textarea, id: id, rows: 1, value: value, disabled: Boolean(locked), placeholder: locked ? undefined : placeholder, onChange: (e) => {
                             onChange(e.target.value);
                             requestAnimationFrame(syncTrigger);
                         }, onKeyDown: onKeyDown, onKeyUp: (e) => {
@@ -216,6 +266,8 @@ function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, o
                                             if (files.length)
                                                 onAttach(files);
                                             e.target.value = "";
-                                        } }), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": t("attachFiles"), disabled: Boolean(locked), onClick: () => fileInput.current?.click(), className: "flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground disabled:opacity-40", children: _jsx(Paperclip, { className: "size-4" }) }) }), _jsx(TooltipContent, { children: t("attachFiles") })] })] })), tools, scope && (_jsxs("button", { type: "button", onClick: onScopeClick, disabled: !onScopeClick, className: cn("inline-flex min-w-0 items-center gap-1.5 rounded-lg px-2 py-1 text-xs transition-colors duration-150 enabled:hover:bg-accent", production ? "bg-warning-weak text-warning-text enabled:hover:bg-warning-weak" : "text-muted-foreground"), children: [production ? _jsx(TriangleAlert, { "aria-hidden": true, className: "size-3 shrink-0" }) : _jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-success" }), _jsxs("span", { className: "truncate", children: [scope.environment, " \u00B7 ", production ? t("production") : (scope.detail ?? t("nonProduction"))] })] })), _jsxs("span", { className: "ms-auto hidden text-2xs text-faint-foreground @lg:inline", children: [_jsx("kbd", { className: "font-sans", children: "\u21B5" }), " ", t("hintSend"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "\u21E7\u21B5" }), " ", t("hintNewLine"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "@" }), " ", t("hintMention")] }), state === "streaming" && onStop ? (_jsx("button", { type: "button", "aria-label": t("stop"), onClick: onStop, className: cn("ms-auto flex size-8 items-center justify-center bg-foreground text-background transition-transform duration-150 active:scale-95 @lg:ms-1", sendShape === "round" ? "rounded-full" : "rounded-lg"), children: _jsx(Square, { className: "size-3 fill-current" }) })) : (_jsx("button", { type: "button", "aria-label": t("send"), onClick: submit, disabled: !canSend, "aria-busy": state === "sending", className: cn("ms-auto flex size-8 items-center justify-center bg-primary text-primary-foreground transition-[background-color,opacity,transform] duration-150 enabled:hover:bg-primary-hover active:scale-95 disabled:opacity-30 @lg:ms-1", sendShape === "round" ? "rounded-full" : "rounded-lg"), children: state === "sending" ? _jsx(LoaderCircle, { className: "size-4 animate-spin" }) : _jsx(ArrowUp, { className: "size-4", strokeWidth: 2.5 }) }))] })] })] }));
+                                        } }), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": t("attachFiles"), disabled: Boolean(locked), onClick: () => fileInput.current?.click(), className: "flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground disabled:opacity-40", children: _jsx(Paperclip, { className: "size-4" }) }) }), _jsx(TooltipContent, { children: t("attachFiles") })] })] })), tools, scope && (_jsxs("button", { type: "button", onClick: onScopeClick, disabled: !onScopeClick, className: cn("inline-flex min-w-0 items-center gap-1.5 rounded-lg px-2 py-1 text-xs transition-colors duration-150 enabled:hover:bg-accent", production ? "bg-warning-weak text-warning-text enabled:hover:bg-warning-weak" : "text-muted-foreground"), children: [production ? _jsx(TriangleAlert, { "aria-hidden": true, className: "size-3 shrink-0" }) : _jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-success" }), _jsxs("span", { className: "truncate", children: [scope.environment, " \u00B7 ", production ? t("production") : (scope.detail ?? t("nonProduction"))] })] })), hints && (
+                            // Only what this composer can do: @ and / are named only when there's something for them to offer.
+                            _jsxs("span", { className: "ms-auto hidden text-2xs text-faint-foreground @lg:inline", children: [_jsx("kbd", { className: "font-sans", children: "\u21B5" }), " ", t("hintSend"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "\u21E7\u21B5" }), " ", t("hintNewLine"), mentions.length > 0 && (_jsxs(_Fragment, { children: [" · ", _jsx("kbd", { className: "font-sans", children: "@" }), " ", t("hintMention")] })), commands.length > 0 && (_jsxs(_Fragment, { children: [" · ", _jsx("kbd", { className: "font-sans", children: "/" }), " ", t("hintCommand")] }))] })), state === "streaming" && onStop ? (_jsx("button", { type: "button", "aria-label": t("stop"), onClick: onStop, className: cn("ms-auto flex size-8 items-center justify-center bg-foreground text-background transition-transform duration-150 active:scale-95", hints && "@lg:ms-1", sendShape === "round" ? "rounded-full" : "rounded-lg"), children: _jsx(Square, { className: "size-3 fill-current" }) })) : (_jsx("button", { type: "button", "aria-label": t("send"), onClick: submit, disabled: !canSend, "aria-busy": state === "sending", className: cn("ms-auto flex size-8 items-center justify-center bg-primary text-primary-foreground transition-[background-color,opacity,transform] duration-150 enabled:hover:bg-primary-hover active:scale-95 disabled:opacity-30", hints && "@lg:ms-1", sendShape === "round" ? "rounded-full" : "rounded-lg"), children: state === "sending" ? _jsx(LoaderCircle, { className: "size-4 animate-spin" }) : _jsx(ArrowUp, { className: "size-4", strokeWidth: 2.5 }) }))] })] })] }));
 }
 export { Composer };

package/dist/chat/context-meter.d.ts

@@ -1,3 +1,4 @@
+import * as React from "react";
 import type { ContextSegment } from "../lib/know.js";
 /** ContextMeter's fixed words; override them under `contextMeter` in LocaleProvider's `strings`. */
 export declare const contextMeterStrings: {
@@ -11,7 +12,9 @@ export declare const contextMeterStrings: {
 /**
  * What fills the model's context budget, as a ring in the composer that
  * opens to a breakdown: system, instructions, Know, the thread, tools, files.
- * Counts are the service's own token counts; the ring warns past 80%.
+ * Counts are the service's own token counts; the ring warns past 80%. When a
+ * new count arrives the ring sweeps to it and changes colour at the warning
+ * line; it draws its first value in place, with no sweep from zero.
  */
 declare function ContextMeter({ segments, limit, className, }: {
     /** What fills the context window, by kind, in tokens. */
@@ -19,5 +22,5 @@ declare function ContextMeter({ segments, limit, className, }: {
     /** The model's context window, in tokens. */
     limit: number;
     className?: string | undefined;
-}): import("react").JSX.Element;
+}): React.JSX.Element;
 export { ContextMeter };

package/dist/chat/context-meter.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
 import { cn } from "../lib/utils.js";
 import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover.js";
 import { useFormat, useStrings } from "../blocks/locale.js";
@@ -29,7 +30,9 @@ function k(n, format, thousands) {
 /**
  * What fills the model's context budget, as a ring in the composer that
  * opens to a breakdown: system, instructions, Know, the thread, tools, files.
- * Counts are the service's own token counts; the ring warns past 80%.
+ * Counts are the service's own token counts; the ring warns past 80%. When a
+ * new count arrives the ring sweeps to it and changes colour at the warning
+ * line; it draws its first value in place, with no sweep from zero.
  */
 function ContextMeter({ segments, limit, className, }) {
     const t = useStrings("contextMeter", contextMeterStrings);
@@ -40,7 +43,10 @@ function ContextMeter({ segments, limit, className, }) {
     const warn = pct > 0.8;
     const r = 7;
     const c = 2 * Math.PI * r;
-    return (_jsxs(Popover, { children: [_jsxs(PopoverTrigger, { "aria-label": t("label", { used: tokens(used), limit: tokens(limit) }), className: cn("inline-flex items-center gap-1.5 rounded-md px-1.5 py-1 text-2xs tabular-nums outline-none hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80", warn ? "text-warning-text" : "text-muted-foreground", className), children: [_jsxs("svg", { viewBox: "0 0 18 18", className: "size-4 -rotate-90", "aria-hidden": true, children: [_jsx("circle", { cx: "9", cy: "9", r: r, fill: "none", stroke: "var(--muted)", strokeWidth: "2.5" }), _jsx("circle", { cx: "9", cy: "9", r: r, fill: "none", stroke: warn ? "var(--warning)" : "var(--primary)", strokeWidth: "2.5", strokeDasharray: `${pct * c} ${c}`, strokeLinecap: "round" })] }), fmt.number(Math.round(pct * 100) / 100, { style: "percent" })] }), _jsxs(PopoverContent, { align: "start", className: "w-72 p-3", children: [_jsxs("p", { className: "flex items-baseline justify-between text-sm font-medium", children: [t("context"), " ", _jsx("span", { className: "text-xs font-normal text-muted-foreground tabular-nums", children: t("usage", { used: tokens(used), limit: tokens(limit) }) })] }), _jsx("div", { "aria-hidden": true, className: "mt-2 flex h-2 overflow-hidden rounded-full bg-muted", children: segments.map((s) => (_jsx("span", { style: { width: `${(s.tokens / limit) * 100}%`, background: kindColor[s.kind] } }, s.label))) }), _jsx("ul", { className: "mt-3 flex flex-col gap-1.5", children: [...segments]
+    // The sweep is a transition, so it runs only for a value that changed after the first one was drawn.
+    const [drawn, setDrawn] = React.useState(false);
+    React.useEffect(() => setDrawn(true), []);
+    return (_jsxs(Popover, { children: [_jsxs(PopoverTrigger, { "aria-label": t("label", { used: tokens(used), limit: tokens(limit) }), "data-warn": warn ? "" : undefined, className: cn("inline-flex items-center gap-1.5 rounded-md px-1.5 py-1 text-2xs tabular-nums outline-none hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80", warn ? "text-warning-text" : "text-muted-foreground", className), children: [_jsxs("svg", { viewBox: "0 0 18 18", className: "size-4 -rotate-90", "aria-hidden": true, children: [_jsx("circle", { cx: "9", cy: "9", r: r, fill: "none", stroke: "var(--muted)", strokeWidth: "2.5" }), _jsx("circle", { "data-slot": "context-meter-ring", cx: "9", cy: "9", r: r, fill: "none", stroke: warn ? "var(--warning)" : "var(--primary)", strokeWidth: "2.5", strokeDasharray: `${pct * c} ${c}`, strokeLinecap: "round", className: cn(drawn && "transition-[stroke-dasharray,stroke] duration-(--cd-dur-slow) ease-standard") })] }), fmt.number(Math.round(pct * 100) / 100, { style: "percent" })] }), _jsxs(PopoverContent, { align: "start", className: "w-72 p-3", children: [_jsxs("p", { className: "flex items-baseline justify-between text-sm font-medium", children: [t("context"), " ", _jsx("span", { className: "text-xs font-normal text-muted-foreground tabular-nums", children: t("usage", { used: tokens(used), limit: tokens(limit) }) })] }), _jsx("div", { "aria-hidden": true, className: "mt-2 flex h-2 overflow-hidden rounded-full bg-muted", children: segments.map((s) => (_jsx("span", { style: { width: `${(s.tokens / limit) * 100}%`, background: kindColor[s.kind] } }, s.label))) }), _jsx("ul", { className: "mt-3 flex flex-col gap-1.5", children: [...segments]
                             .sort((a, b) => b.tokens - a.tokens)
                             .map((s) => (_jsxs("li", { className: "flex items-center gap-2 text-xs", children: [_jsx("span", { "aria-hidden": true, className: "size-2 rounded-xs", style: { background: kindColor[s.kind] } }), _jsx("span", { className: "flex-1", children: s.label }), _jsx("span", { className: "text-muted-foreground tabular-nums", children: tokens(s.tokens) })] }, s.label))) }), warn && _jsx("p", { className: "mt-3 text-xs text-warning-text", children: t("nearlyFull") })] })] }));
 }

package/dist/chat/message-actions.d.ts

@@ -11,8 +11,10 @@ export declare const messageActionsStrings: {
 export type Rating = "up" | "down" | null;
 /**
  * Copy, retry and rate under an agent's reply. Each action appears only when
- * its handler is given. Copy reports what the clipboard did. A rating is the
- * caller's state, so it shows only what the service recorded.
+ * its handler is given. Copy reports what the clipboard did: the icon stays a
+ * copy icon until the write settles, then becomes a tick (or a cross when the
+ * clipboard refused). A rating is the caller's state, so it shows only what
+ * the service recorded.
  */
 declare function MessageActions({ text, onRetry, rating, onRate, meta, className, }: {
     /** What Copy copies; without it there's no Copy. */