@candor-ui/react 2.2.0 → 2.4.0

package/README.md

@@ -17,8 +17,8 @@ copy code into their app. If you want to own and edit the source, install with t
 npm install @candor-ui/react
 ```
 
-Needs React 19 and Tailwind CSS 4. Radix, lucide-react, class-variance-authority, clsx, tailwind-merge, the Inter font
-and tw-animate-css come with it.
+Needs React 19 and Tailwind CSS 4. Radix, lucide-react, class-variance-authority, clsx, tailwind-merge and the Inter
+font come with it.
 
 ## Styles (Tailwind 4)
 
@@ -30,7 +30,7 @@ The components are styled with Tailwind classes and Candor's tokens. Import the
 ```
 
 `styles.css` brings Candor's tokens (colours, type scale, radii, shadows, motion), the light, dark and high-contrast
-themes, Inter, tw-animate-css and an `@source` for the package's own files, so Tailwind generates the classes the
+themes, Inter and an `@source` for the package's own files, so Tailwind generates the classes the
 components use even though it skips `node_modules` when scanning your app. If your setup doesn't follow `@source`
 from imported CSS, add it yourself, relative to your CSS file:
 

package/dist/adapters/use-ag-ui.d.ts

@@ -52,7 +52,7 @@ export declare function useAgUi(options: UseAgUiOptions): {
     composer: {
         value: string;
         onChange: React.Dispatch<React.SetStateAction<string>>;
-        state: "streaming" | "ready" | "sending";
+        state: "streaming" | "sending" | "ready";
         references: EntityRef[];
         onReferencesChange: React.Dispatch<React.SetStateAction<EntityRef[]>>;
         onStop: () => void | undefined;

package/dist/adapters/use-candor-chat.d.ts

@@ -31,7 +31,7 @@ export declare function useCandorChat(chat: UseChatHelpers<UIMessage>, options:
     composer: {
         value: string;
         onChange: React.Dispatch<React.SetStateAction<string>>;
-        state: "streaming" | "ready" | "sending";
+        state: "streaming" | "sending" | "ready";
         references: EntityRef[];
         onReferencesChange: React.Dispatch<React.SetStateAction<EntityRef[]>>;
         onStop: () => Promise<void>;

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

@@ -68,7 +68,7 @@ export declare function useClaudeAgent(options: UseClaudeAgentOptions): {
     composer: {
         value: string;
         onChange: React.Dispatch<React.SetStateAction<string>>;
-        state: "streaming" | "ready" | "sending";
+        state: "streaming" | "sending" | "ready";
         references: EntityRef[];
         onReferencesChange: React.Dispatch<React.SetStateAction<EntityRef[]>>;
         onStop: () => void;

package/dist/blocks/copy-field.js

@@ -4,6 +4,9 @@ import { Check, Copy, X } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { useCopy } from "../lib/use-copy.js";
 import { useStrings } from "./locale.js";
+import { motion } from "../lib/motion.js";
+/** The tick or cross after the clipboard write settles. */
+const tickMotion = motion("copy-field", "tick", "pop");
 /** CopyField's fixed words; override them under `copyField` in LocaleProvider's `strings`. */
 export const copyFieldStrings = {
     copy: "Copy",
@@ -19,6 +22,6 @@ export const copyFieldStrings = {
 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", "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")] })) })] })] }));
+    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 cd-tint 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, { style: tickMotion, className: "size-3 text-success-text cd-pop" }), " ", t("copied")] })) : state === "failed" ? (_jsxs(_Fragment, { children: [_jsx(X, { style: tickMotion, className: "size-3 text-destructive-text cd-pop" }), " ", t("failed")] })) : (_jsxs(_Fragment, { children: [_jsx(Copy, { className: "size-3" }), " ", t("copy")] })) })] })] }));
 }
 export { CopyField };

package/dist/blocks/degraded-panel.js

@@ -4,6 +4,8 @@ import { CircleAlert, RotateCw } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { Button } from "../ui/button.js";
 import { useStrings } from "./locale.js";
+import { motion } from "../lib/motion.js";
+const spinMotion = motion("degraded-panel", "busy", "live", { dur: 1000 });
 /** DegradedPanel's fixed words; override them under `degradedPanel` in LocaleProvider's `strings`. */
 export const degradedPanelStrings = {
     missing: "Missing:",
@@ -17,6 +19,6 @@ export const degradedPanelStrings = {
  */
 function DegradedPanel({ reason, missing, onRetry, retrying = false, variant = "block", className, }) {
     const t = useStrings("degradedPanel", degradedPanelStrings);
-    return (_jsxs("div", { "data-slot": "degraded-panel", role: "status", className: cn("flex gap-2.5 text-sm", variant === "block" ? "items-start rounded-lg border border-warning/40 bg-warning-weak/60 p-3" : "items-center", className), children: [_jsx(CircleAlert, { "aria-hidden": true, className: "mt-0.5 size-4 shrink-0 text-warning-text" }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "text-foreground", children: reason }), missing && _jsxs("p", { className: "mt-0.5 text-xs text-muted-foreground", children: [t("missing"), " ", missing] })] }), onRetry && (_jsxs(Button, { size: "xs", variant: "outline", onClick: onRetry, disabled: retrying, "aria-busy": retrying, className: "shrink-0", children: [_jsx(RotateCw, { className: cn(retrying && "animate-spin") }), " ", retrying ? t("retrying") : t("retry")] }))] }));
+    return (_jsxs("div", { "data-slot": "degraded-panel", role: "status", className: cn("flex gap-2.5 text-sm", variant === "block" ? "items-start rounded-lg border border-warning/40 bg-warning-weak/60 p-3" : "items-center", className), children: [_jsx(CircleAlert, { "aria-hidden": true, className: "mt-0.5 size-4 shrink-0 text-warning-text" }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "text-foreground", children: reason }), missing && _jsxs("p", { className: "mt-0.5 text-xs text-muted-foreground", children: [t("missing"), " ", missing] })] }), onRetry && (_jsxs(Button, { size: "xs", variant: "outline", onClick: onRetry, disabled: retrying, "aria-busy": retrying, className: "shrink-0", children: [_jsx(RotateCw, { style: spinMotion, className: cn(retrying && "cd-live-spin") }), " ", retrying ? t("retrying") : t("retry")] }))] }));
 }
 export { DegradedPanel };

package/dist/blocks/locked.js

@@ -4,6 +4,20 @@ import * as React from "react";
 import { LockKeyhole } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { Tooltip, TooltipContent, TooltipTrigger } from "../ui/tooltip.js";
+import { motion } from "../lib/motion.js";
+/** The running animation's duration on `el`, in milliseconds (its longest, if there are several); undefined when it can't be read. */
+function animationMs(el) {
+    if (!el || typeof getComputedStyle === "undefined")
+        return undefined;
+    const times = getComputedStyle(el)
+        .animationDuration.split(",")
+        .map((t) => (t.trim().endsWith("ms") ? Number.parseFloat(t) : Number.parseFloat(t) * 1000))
+        .filter((n) => Number.isFinite(n));
+    return times.length ? Math.max(...times) : undefined;
+}
+/** A press on the locked control: the reason is emphasised, and under expressive the control shakes. */
+const refuseMotion = motion("locked", "refuse", "refuse");
+const reasonMotion = motion("locked", "reason", "tint", { dur: 200 });
 /**
  * The honest-state rule: a control that cannot be used says why.
  *
@@ -24,10 +38,14 @@ function Locked({ reason, inline = false, children, className, }) {
     const [press, setPress] = React.useState(0);
     const [shaking, setShaking] = React.useState(false);
     const [held, setHeld] = React.useState(false);
+    const box = React.useRef(null);
     React.useEffect(() => {
         if (press === 0)
             return;
-        const shake = window.setTimeout(() => setShaking(false), 400);
+        // The shake ends when its animation does (onAnimationEnd below). This timer is only the fallback for when no
+        // animation runs (motion off, or no Candor CSS), set from the duration the page resolved: a brand's longer shake,
+        // or the speed token, isn't cut short.
+        const shake = window.setTimeout(() => setShaking(false), (animationMs(box.current) ?? 400) + 100);
         const hold = window.setTimeout(() => setHeld(false), 1800);
         return () => {
             window.clearTimeout(shake);
@@ -53,6 +71,9 @@ function Locked({ reason, inline = false, children, className, }) {
                 block(e);
         },
     });
-    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] })] }));
+    return (_jsxs("span", { ref: box, "data-slot": "locked", onAnimationEnd: (e) => {
+            if (e.target === e.currentTarget)
+                setShaking(false);
+        }, "data-pressed": held ? "" : undefined, style: refuseMotion, className: cn("relative inline-flex flex-col items-start gap-1.5", shaking && "cd-refuse", 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", style: reasonMotion, className: cn("items-center gap-1 text-xs text-muted-foreground cd-tint", inline ? "inline-flex" : "sr-only", held && "text-foreground"), children: [_jsx(LockKeyhole, { "aria-hidden": true, className: "size-3" }), reason] })] }));
 }
 export { Locked };

package/dist/blocks/relative-time.js

@@ -80,6 +80,6 @@ function RelativeTime({ date, bare = false, format = "relative", className, }) {
     // A bare time ("2 days") is read aloud without its direction, so a screen reader hears the whole phrase ("2 days ago")
     // while the page keeps the short one. "always" keeps the number ("1 day ago", not "yesterday"), so the spoken words match the shown ones.
     const spoken = bare && format === "relative" && current !== null ? formatRelative(d, new Date(current), { locale: fmt.tag, justNow: t("justNow"), numeric: "always" }) : text;
-    return (_jsx("time", { dateTime: d.toISOString(), title: current === null ? undefined : fmt.date(d, "datetime"), className: className, children: spoken === text ? (text) : (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, children: text }), _jsx("span", { className: "sr-only", children: spoken })] })) }));
+    return (_jsx("time", { "data-slot": "relative-time", dateTime: d.toISOString(), title: current === null ? undefined : fmt.date(d, "datetime"), className: className, children: spoken === text ? (text) : (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, children: text }), _jsx("span", { className: "sr-only", children: spoken })] })) }));
 }
 export { RelativeTime };

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

@@ -1,4 +1,3 @@
-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
@@ -6,14 +5,26 @@ import { type RunStatus } from "../lib/status.js";
  * 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.
+ *
+ * Live means heard from: with `lastHeardAt`, a running dot pulses only while the
+ * run has been heard from within `staleAfter`, and is still (with its word)
+ * once it hasn't, or before the page has a clock. Without it the app isn't
+ * tracking freshness, and running pulses as before.
  */
-declare function StatusDot({ status, showLabel, label, className, }: {
+declare function StatusDot({ status, showLabel, label, lastHeardAt, staleAfter, className, }: {
     /** Which status to show; running and waiting pulse. */
     status: RunStatus;
     /** Print the status name next to the dot. */
     showLabel?: boolean | undefined;
     /** Words to use instead of the status name. */
     label?: string | undefined;
+    /**
+     * When the run was last heard from (an event, a heartbeat). A running dot pulses only while this is within
+     * `staleAfter`; past it, or when the time can't be read, the dot is still. Left out, the dot doesn't claim to know.
+     */
+    lastHeardAt?: Date | string | undefined;
+    /** How long a running run may be silent, in milliseconds, before the dot stops pulsing. Two minutes by default. */
+    staleAfter?: number | undefined;
     className?: string | undefined;
-}): React.JSX.Element;
+}): import("react").JSX.Element;
 export { StatusDot };

package/dist/blocks/status-dot.js

@@ -1,8 +1,13 @@
 "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";
+import { useNow } from "./relative-time.js";
+import { motion, useSettled } from "../lib/motion.js";
+import { runLiveness, STALE_AFTER, useStatusLabel } from "../lib/status.js";
+/** The pulse while a run is heard from. */
+const liveMotion = motion("status-dot", "live", "live");
+/** The dot popping into its final colour when the run settles on screen. */
+const settleMotion = motion("status-dot", "settle", "pop");
 const dotColor = {
     idle: "bg-faint-foreground/60",
     queued: "bg-faint-foreground",
@@ -14,35 +19,25 @@ 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. 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.
+ *
+ * Live means heard from: with `lastHeardAt`, a running dot pulses only while the
+ * run has been heard from within `staleAfter`, and is still (with its word)
+ * once it hasn't, or before the page has a clock. Without it the app isn't
+ * tracking freshness, and running pulses as before.
  */
-function StatusDot({ status, showLabel = false, label, className, }) {
+function StatusDot({ status, showLabel = false, label, lastHeardAt, staleAfter = STALE_AFTER, className, }) {
     const statusLabel = useStatusLabel();
     const text = label ?? statusLabel(status);
-    const live = status === "running" || status === "waiting";
+    const now = useNow();
+    const liveness = runLiveness({ status, lastHeardAt }, now, staleAfter);
+    const live = (status === "running" || status === "waiting") && liveness === "live";
     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 })] }));
+    return (_jsxs("span", { "data-slot": "status-dot", "data-status": status, "data-settled": settled > 0 ? "" : undefined, "data-liveness": lastHeardAt === undefined ? undefined : liveness, className: cn("inline-flex items-center gap-1.5 text-xs text-muted-foreground", className), children: [_jsx("span", { "aria-hidden": true, style: live ? liveMotion : settleMotion, className: cn("size-2 shrink-0 rounded-full", dotColor[status], live && "cd-live-dot", settled > 0 && "cd-pop") }, settled), showLabel ? _jsx("span", { children: text }) : _jsx("span", { className: "sr-only", children: text })] }));
 }
 export { StatusDot };

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

@@ -18,7 +18,8 @@ declare function StepMark({ status, }: {
 /**
  * An ordered list of steps joined by a rail: an agent's plan, its reasoning,
  * 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.
+ * it, and a step that finishes while on screen draws its mark. A step added
+ * after the list first drew rises in; the steps it loaded with are still.
  */
 declare function StepList({ steps, className, }: {
     /** The steps in order, each with a status, and optional detail and meta. */

package/dist/blocks/step-list.js

@@ -3,33 +3,23 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { CircleSlash, Hand, LoaderCircle } from "lucide-react";
 import { cn } from "../lib/utils.js";
+import { motion, useArrived, useSettled } from "../lib/motion.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 step's tick or cross, drawn when its status settles on screen. */
+const markMotion = motion("step-list", "mark", "mark");
+/** The rail growing to a step that finished on screen. */
+const railMotion = motion("step-list", "rail", "fill");
+/** A step added after the list first drew. */
+const arriveMotion = motion("step-list", "arrive", "arrive");
+const workingMotion = motion("step-list", "working", "live", { dur: 1000 });
 /** 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));
+    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, style: markMotion, className: cn(draw > 0 && "cd-mark") }) }, 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));
+    const drawn = draw > 0 && "cd-mark";
+    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, style: markMotion, className: cn(drawn) }), _jsx("path", { d: "m6 6 12 12", pathLength: 1, style: markMotion, className: cn(drawn, drawn && "[--cd-mark-step:1]") })] }, draw));
 }
 /**
  * A step's status as a mark. When the status reaches done or failed while the mark is on screen, the spinner
@@ -37,14 +27,14 @@ function Cross({ draw }) {
  */
 function StepMark({ status, }) {
     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";
+    const base = "relative z-10 flex size-5 shrink-0 items-center justify-center rounded-full cd-tint";
     switch (status) {
         case "succeeded":
             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"), "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 }) }));
+            return (_jsx("span", { className: cn(base, "bg-accent-weak text-accent-text"), children: _jsx(LoaderCircle, { style: workingMotion, className: "size-3.5 cd-live-spin", strokeWidth: 2.5 }) }));
         case "waiting":
             return (_jsx("span", { className: cn(base, "bg-warning-weak text-warning-text"), children: _jsx(Hand, { className: "size-3", strokeWidth: 2.5 }) }));
         case "blocked":
@@ -56,18 +46,20 @@ 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, }) {
+function StepRow({ step, arrived, 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 })] })] }));
+    return (_jsxs("li", { style: arriveMotion, className: cn("relative flex gap-3 pb-4 last:pb-0", arrived && "cd-arrive"), 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", style: railMotion, className: cn("absolute inset-0 origin-top bg-success/50", settled > 0 && "cd-fill-grow [--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 to each step as it finishes, never ahead of
- * it, and a step that finishes while on screen draws its mark.
+ * it, and a step that finishes while on screen draws its mark. A step added
+ * after the list first drew rises in; the steps it loaded with are still.
  */
 function StepList({ steps, className, }) {
-    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))) }));
+    const arrived = useArrived(React.useMemo(() => steps.map((s) => s.id), [steps]));
+    return (_jsx("ol", { "data-slot": "step-list", className: cn("flex flex-col", className), children: steps.map((step, i) => (_jsx(StepRow, { step: step, arrived: arrived(step.id), last: i === steps.length - 1 }, step.id))) }));
 }
 export { StepList, StepMark };

package/dist/blocks/streaming-text.js

@@ -1,11 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../lib/utils.js";
+import { motion } from "../lib/motion.js";
+const caretMotion = motion("streaming-text", "caret", "live", { dur: 1000 });
 /**
  * Text that is still arriving. Shows a caret while `streaming`, and announces
  * politely so screen readers hear the finished text rather than every token.
  */
 function StreamingText({ text, streaming = false, className, }) {
-    return (_jsxs("div", { "data-slot": "streaming-text", "aria-live": "polite", "aria-busy": streaming, className: cn("whitespace-pre-wrap text-[0.9375rem] leading-relaxed text-foreground", className), children: [text, streaming && (_jsx("span", { "aria-hidden": true, className: "ms-0.5 inline-block h-[1.05em] w-[2px] translate-y-[0.18em] rounded-full bg-primary animate-caret" }))] }));
+    return (_jsxs("div", { "data-slot": "streaming-text", "aria-live": "polite", "aria-busy": streaming, className: cn("whitespace-pre-wrap text-[0.9375rem] leading-relaxed text-foreground", className), children: [text, streaming && (_jsx("span", { "aria-hidden": true, style: caretMotion, className: "ms-0.5 inline-block h-[1.05em] w-[2px] translate-y-[0.18em] rounded-full bg-primary cd-live-caret" }))] }));
 }
 /** A label that shimmers while an agent is working ("Thinking", "Reading the docs"). */
 function ShimmerLabel({ children, className, }) {

package/dist/blocks/surface.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const surfaceVariants: (props?: ({
-    tone?: "plain" | "muted" | "subtle" | "raised" | "floating" | "accent" | null | undefined;
+    tone?: "plain" | "subtle" | "muted" | "raised" | "floating" | "accent" | null | undefined;
     radius?: "md" | "lg" | "xl" | null | undefined;
     pad?: "none" | "md" | "sm" | "lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/dist/chat/attachment-preview.d.ts

@@ -22,13 +22,18 @@ export declare function fileIcon(a: Pick<Attachment, "name" | "mediaType">): Luc
 /**
  * A file waiting to be sent, as a chip in the composer: its name, then upload progress, an error, or its size, and a
  * remove button. Images show their preview when the app gives one.
+ *
+ * @motion fill:progress The upload bar under the chip moves from the old reported fraction to the new one as the service
+ * reports it. It is drawn at its first value in place, never grown from empty, and a file with no progress draws no bar.
  */
-declare function AttachmentChip({ attachment: a, onRemove, className, }: {
+declare function AttachmentChip({ attachment: a, onRemove, className, style, }: {
     /** The file, with progress (0–1) while uploading or an error if it failed. */
     attachment: Attachment;
     /** Shows a remove button. */
     onRemove?: ((id: string) => void) | undefined;
     className?: string | undefined;
+    /** Inline style for the chip's outer element, such as a motion chain from `motion()`. */
+    style?: React.CSSProperties | undefined;
 }): React.JSX.Element;
 /**
  * A sent file, as a tile in a message: an image preview when the app supplied one, else an icon for its type, with

package/dist/chat/attachment-preview.js

@@ -4,6 +4,9 @@ import * as React from "react";
 import { File, FileArchive, FileCode, FileImage, FileSpreadsheet, FileText, Music, Paperclip, Video, X } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { useFormat, useStrings } from "../blocks/locale.js";
+import { motion } from "../lib/motion.js";
+/** The upload bar moving between measured byte counts: 2.2's 300 ms. */
+const progressMotion = motion("attachment-preview", "progress", "fill", { dur: 300 });
 /** AttachmentPreview's fixed words; override them under `attachmentPreview` in LocaleProvider's `strings`. */
 export const attachmentPreviewStrings = {
     remove: "Remove {name}",
@@ -53,12 +56,15 @@ const thumbnail = (a) => (a.previewUrl && (a.mediaType ?? "").startsWith("image/
 /**
  * A file waiting to be sent, as a chip in the composer: its name, then upload progress, an error, or its size, and a
  * remove button. Images show their preview when the app gives one.
+ *
+ * @motion fill:progress The upload bar under the chip moves from the old reported fraction to the new one as the service
+ * reports it. It is drawn at its first value in place, never grown from empty, and a file with no progress draws no bar.
  */
-function AttachmentChip({ attachment: a, onRemove, className, }) {
+function AttachmentChip({ attachment: a, onRemove, className, style, }) {
     const t = useStrings("attachmentPreview", attachmentPreviewStrings);
     const fmt = useFormat();
     const thumb = thumbnail(a);
-    return (_jsxs("span", { "data-slot": "attachment-chip", className: cn("relative inline-flex max-w-56 items-center gap-1.5 overflow-hidden rounded-md border bg-card py-1 pe-1 ps-2 text-xs", a.error && "border-destructive/50", className), children: [thumb ? _jsx("img", { src: thumb, alt: "", className: "size-4 shrink-0 rounded-xs object-cover" }) : _jsx(Paperclip, { "aria-hidden": true, className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: a.name }), _jsx("span", { className: cn("shrink-0 tabular-nums", a.error ? "text-destructive-text" : "text-faint-foreground"), children: a.error ? a.error : a.progress !== undefined ? fmt.number(Math.round(a.progress * 100) / 100, { style: "percent" }) : formatFileSize(a.size, fmt.number, t) }), onRemove && (_jsx("button", { type: "button", "aria-label": t("remove", { name: a.name }), onClick: () => onRemove(a.id), className: "relative after:absolute after:-inset-1 rounded-sm p-0.5 text-faint-foreground hover:bg-accent hover:text-foreground", children: _jsx(X, { className: "size-3" }) })), a.progress !== undefined && !a.error && _jsx("span", { "aria-hidden": true, className: "absolute bottom-0 start-0 h-0.5 bg-primary transition-[width] duration-300", style: { width: `${a.progress * 100}%` } })] }));
+    return (_jsxs("span", { "data-slot": "attachment-chip", style: style, className: cn("relative inline-flex max-w-56 items-center gap-1.5 overflow-hidden rounded-md border bg-card py-1 pe-1 ps-2 text-xs", a.error && "border-destructive/50", className), children: [thumb ? _jsx("img", { src: thumb, alt: "", className: "size-4 shrink-0 rounded-xs object-cover" }) : _jsx(Paperclip, { "aria-hidden": true, className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: a.name }), _jsx("span", { className: cn("shrink-0 tabular-nums", a.error ? "text-destructive-text" : "text-faint-foreground"), children: a.error ? a.error : a.progress !== undefined ? fmt.number(Math.round(a.progress * 100) / 100, { style: "percent" }) : formatFileSize(a.size, fmt.number, t) }), onRemove && (_jsx("button", { type: "button", "aria-label": t("remove", { name: a.name }), onClick: () => onRemove(a.id), className: "relative after:absolute after:-inset-1 rounded-sm p-0.5 text-faint-foreground hover:bg-accent hover:text-foreground", children: _jsx(X, { className: "size-3" }) })), a.progress !== undefined && !a.error && _jsx("span", { "aria-hidden": true, className: "absolute bottom-0 start-0 h-0.5 bg-primary cd-fill", style: { ...progressMotion, width: `${a.progress * 100}%` } })] }));
 }
 /**
  * A sent file, as a tile in a message: an image preview when the app supplied one, else an icon for its type, with
@@ -72,7 +78,7 @@ function AttachmentPreview({ attachment: a, onOpen, className, }) {
     const size = formatFileSize(a.size, fmt.number, t);
     const body = (_jsxs(_Fragment, { children: [thumb ? (_jsx("img", { src: thumb, alt: "", className: "h-24 w-full rounded-md bg-muted object-cover" })) : (_jsx("span", { "aria-hidden": true, className: "flex size-8 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground", children: _jsx(FileGlyph, { attachment: a }) })), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-sm", children: a.name }), (size || a.error) && _jsx("span", { className: cn("block text-xs tabular-nums", a.error ? "text-destructive-text" : "text-faint-foreground"), children: a.error ?? size })] })] }));
     const frame = cn("flex w-56 max-w-full gap-2.5 rounded-lg border bg-card p-2 text-start", thumb ? "flex-col" : "items-center", className);
-    return onOpen ? (_jsx("button", { type: "button", "data-slot": "attachment-preview", "aria-label": t("open", { name: a.name }), onClick: () => onOpen(a), className: cn(frame, "outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/80"), children: body })) : (_jsx("div", { "data-slot": "attachment-preview", className: frame, children: body }));
+    return onOpen ? (_jsx("button", { type: "button", "data-slot": "attachment-preview", "aria-label": t("open", { name: a.name }), onClick: () => onOpen(a), className: cn(frame, "outline-none cd-tint hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/80"), children: body })) : (_jsx("div", { "data-slot": "attachment-preview", className: frame, children: body }));
 }
 /** Several sent files, as a wrapping row of tiles, announced as a list. */
 function AttachmentList({ attachments, onOpen, className, }) {

package/dist/chat/card-registry.js

@@ -5,6 +5,8 @@ import { ChevronRight, LayoutTemplate } from "lucide-react";
 import { DegradedPanel } from "../blocks/degraded-panel.js";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible.js";
 import { useStrings } from "../blocks/locale.js";
+import { motion } from "../lib/motion.js";
+const turnMotion = motion("card-registry", "open", "reveal");
 /** CardRegistry's fixed words; override them under `cardRegistry` in LocaleProvider's `strings`. */
 export const cardRegistryStrings = {
     showAsText: "Show it as text",
@@ -32,7 +34,7 @@ class CardBoundary extends React.Component {
 }
 function Summary({ text, }) {
     const t = useStrings("cardRegistry", cardRegistryStrings);
-    return (_jsxs(Collapsible, { className: "group/summary", children: [_jsxs(CollapsibleTrigger, { className: "relative after:absolute after:inset-x-0 after:-inset-y-1 inline-flex items-center gap-1 text-xs text-muted-foreground outline-none hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/80 rounded-sm", children: [_jsx(ChevronRight, { "aria-hidden": true, className: "rtl:-scale-x-100 size-3 transition-transform group-data-[state=open]/summary:[transform:rotate(90deg)]" }), " ", t("showAsText")] }), _jsx(CollapsibleContent, { children: _jsx("p", { className: "mt-1.5 rounded-md bg-sunken px-3 py-2 text-sm whitespace-pre-wrap", children: text }) })] }));
+    return (_jsxs(Collapsible, { className: "group/summary", children: [_jsxs(CollapsibleTrigger, { className: "relative after:absolute after:inset-x-0 after:-inset-y-1 inline-flex items-center gap-1 text-xs text-muted-foreground outline-none hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/80 rounded-sm", children: [_jsx(ChevronRight, { "aria-hidden": true, style: turnMotion, className: "rtl:-scale-x-100 size-3 cd-reveal-turn group-data-[state=open]/summary:[transform:rotate(90deg)]" }), " ", t("showAsText")] }), _jsx(CollapsibleContent, { style: turnMotion, children: _jsx("p", { className: "mt-1.5 rounded-md bg-sunken px-3 py-2 text-sm whitespace-pre-wrap", children: text }) })] }));
 }
 /**
  * Renders one card from the registry. Three honest fallbacks, each with the
@@ -44,13 +46,13 @@ function Card({ name, props, summary, }) {
     const cards = React.useContext(Registry);
     const def = cards[name];
     if (!def) {
-        return (_jsxs("div", { "data-slot": "card", "data-card": name, "data-state": "unknown", className: "flex flex-col gap-1.5 rounded-lg border border-dashed px-3 py-2.5", children: [_jsxs("p", { className: "flex items-center gap-1.5 text-sm text-muted-foreground", children: [_jsx(LayoutTemplate, { "aria-hidden": true, className: "size-3.5" }), " ", t("unknown", { name })] }), _jsx(Summary, { text: summary })] }));
+        return (_jsxs("div", { "data-slot": "card-registry", "data-card": name, "data-state": "unknown", className: "flex flex-col gap-1.5 rounded-lg border border-dashed px-3 py-2.5", children: [_jsxs("p", { className: "flex items-center gap-1.5 text-sm text-muted-foreground", children: [_jsx(LayoutTemplate, { "aria-hidden": true, className: "size-3.5" }), " ", t("unknown", { name })] }), _jsx(Summary, { text: summary })] }));
     }
     const problem = def.check(props);
     if (problem) {
-        return (_jsxs("div", { "data-slot": "card", "data-card": name, "data-state": "invalid", className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: t("invalid", { label: def.label.toLowerCase(), problem }) }), _jsx(Summary, { text: summary })] }));
+        return (_jsxs("div", { "data-slot": "card-registry", "data-card": name, "data-state": "invalid", className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: t("invalid", { label: def.label.toLowerCase(), problem }) }), _jsx(Summary, { text: summary })] }));
     }
-    return (_jsx("div", { "data-slot": "card", "data-card": name, "data-state": "ready", children: _jsx(CardBoundary, { fallback: _jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: t("failed", { label: def.label.toLowerCase() }) }), _jsx(Summary, { text: summary })] }), children: def.render(props) }) }));
+    return (_jsx("div", { "data-slot": "card-registry", "data-card": name, "data-state": "ready", children: _jsx(CardBoundary, { fallback: _jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: t("failed", { label: def.label.toLowerCase() }) }), _jsx(Summary, { text: summary })] }), children: def.render(props) }) }));
 }
 /* ---------------------------------------------------------------- small checking helpers */
 export const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);

package/dist/chat/citation.js

@@ -52,9 +52,9 @@ function SourceDetail({ source, }) {
 function Citation({ source, marker, }) {
     const t = useStrings("citation", citationStrings);
     if (!source) {
-        return _jsxs("sup", { className: "text-faint-foreground", children: ["[", marker ?? "?", "]"] });
+        return _jsxs("sup", { "data-slot": "citation", className: "text-faint-foreground", children: ["[", marker ?? "?", "]"] });
     }
-    return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": t("sourceLabel", { marker: source.marker, label: source.label }), className: cn("mx-0.5 inline-flex h-4 min-w-4 -translate-y-px items-center justify-center rounded-sm px-1 align-middle text-2xs font-semibold tabular-nums transition-colors duration-150 outline-none focus-visible:ring-[3px] focus-visible:ring-ring/80", source.provisional
+    return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx("button", { type: "button", "data-slot": "citation", "aria-label": t("sourceLabel", { marker: source.marker, label: source.label }), className: cn("mx-0.5 inline-flex h-4 min-w-4 -translate-y-px items-center justify-center rounded-sm px-1 align-middle text-2xs font-semibold tabular-nums cd-tint outline-none focus-visible:ring-[3px] focus-visible:ring-ring/80", source.provisional
                         ? "border border-dashed border-provisional/60 text-provisional hover:bg-muted"
                         : "bg-accent-weak text-accent-text hover:bg-primary hover:text-primary-foreground"), children: source.marker }) }), _jsx(PopoverContent, { align: "start", className: "w-80 max-w-[calc(100vw-2rem)] p-3", children: _jsx(SourceDetail, { source: source }) })] }));
 }
@@ -67,7 +67,7 @@ function SourceList({ sources, className, }) {
                 .sort((a, b) => a.marker - b.marker)
                 .map((s) => {
                 const { Icon } = kindOf(s.kind, t);
-                return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { type: "button", className: cn("relative after:absolute after:inset-x-0 after:-inset-y-0.5 inline-flex max-w-56 items-center gap-1.5 rounded-md border bg-card py-0.5 pe-2 ps-1 text-xs text-muted-foreground transition-colors duration-150 outline-none hover:border-border-strong hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/80", s.provisional && "border-dashed"), children: [_jsx("span", { className: "flex h-4 min-w-4 items-center justify-center rounded-sm bg-muted px-1 text-2xs font-semibold tabular-nums", children: s.marker }), _jsx(Icon, { "aria-hidden": true, className: "size-3 shrink-0" }), _jsx("span", { className: "truncate", children: s.label })] }) }), _jsx(PopoverContent, { align: "start", className: "w-80 max-w-[calc(100vw-2rem)] p-3", children: _jsx(SourceDetail, { source: s }) })] }, s.id));
+                return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { type: "button", className: cn("relative after:absolute after:inset-x-0 after:-inset-y-0.5 inline-flex max-w-56 items-center gap-1.5 rounded-md border bg-card py-0.5 pe-2 ps-1 text-xs text-muted-foreground cd-tint outline-none hover:border-border-strong hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/80", s.provisional && "border-dashed"), children: [_jsx("span", { className: "flex h-4 min-w-4 items-center justify-center rounded-sm bg-muted px-1 text-2xs font-semibold tabular-nums", children: s.marker }), _jsx(Icon, { "aria-hidden": true, className: "size-3 shrink-0" }), _jsx("span", { className: "truncate", children: s.label })] }) }), _jsx(PopoverContent, { align: "start", className: "w-80 max-w-[calc(100vw-2rem)] p-3", children: _jsx(SourceDetail, { source: s }) })] }, s.id));
             })] }));
 }
 export { Citation, SourceList, SourceDetail };