@candor-ui/react 2.3.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/blocks/locked.js

@@ -5,6 +5,16 @@ 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 });
@@ -28,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);
@@ -57,6 +71,9 @@ function Locked({ reason, inline = false, children, className, }) {
                 block(e);
         },
     });
-    return (_jsxs("span", { "data-slot": "locked", "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] })] }));
+    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/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

@@ -56,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 cd-fill", style: { ...progressMotion, 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

package/dist/chat/card-registry.js

@@ -46,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 cd-tint 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 }) })] }));
 }

package/dist/chat/composer.js

@@ -218,7 +218,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 cd-tint 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("span", { "data-slot": "composer-chip", style: chipMotion, className: cn("inline-flex max-w-full min-w-0", referenceArrived(referenceKey(r)) && "cd-pop"), children: _jsx(EntityChip, { entity: r, onRemove: (e) => onReferencesChange?.(references.filter((x) => x !== e)) }) }, referenceKey(r)))), referenceMotion.leaving.map((r) => (_jsx(LeavingChip, { onDone: () => referenceMotion.left(r), children: _jsx(EntityChip, { entity: r }) }, `leaving:${referenceKey(r)}`))), attachments.map((a) => (_jsx("span", { "data-slot": "composer-chip", style: chipMotion, className: cn("inline-flex max-w-full min-w-0", attachmentArrived(a.id) && "cd-pop"), children: _jsx(AttachmentChip, { attachment: a, onRemove: onRemoveAttachment }) }, 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) => {
+                }) })), _jsxs("div", { className: cn("rounded-2xl border bg-card shadow-raised cd-tint 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)), style: chipMotion, className: cn(referenceArrived(referenceKey(r)) && "cd-pop") }, 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, style: chipMotion, className: cn(attachmentArrived(a.id) && "cd-pop") }, 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) => {

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

@@ -15,6 +15,11 @@ export declare const contextMeterStrings: {
  * 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.
+ *
+ * @motion fill:fill The ring moves from the old measured value to the new one when the count changes while the meter is
+ * on screen, and changes colour at the warning line. The first value is drawn in place, never swept from empty.
+ * @motion value:value The percentage beside the ring crossfades to the new figure in the quick duration when the count
+ * changes while the meter is on screen; it never counts through values that were not measured.
  */
 declare function ContextMeter({ segments, limit, className, }: {
     /** What fills the context window, by kind, in tokens. */

package/dist/chat/context-meter.js

@@ -4,9 +4,13 @@ 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";
-import { motion } from "../lib/motion.js";
+import { motion, useSettled } from "../lib/motion.js";
 /** The ring moving to a new measured value, after the first one was drawn in place. */
 const fillMotion = motion("context-meter", "fill", "fill");
+/** The percentage changing in place. */
+const valueMotion = motion("context-meter", "value", "value");
+/** Every new figure counts as a change worth showing. */
+const changed = { settled: () => true, over: () => false };
 /** ContextMeter's fixed words; override them under `contextMeter` in LocaleProvider's `strings`. */
 export const contextMeterStrings = {
     /** A token count in thousands; `{n}` is already formatted. */
@@ -36,6 +40,11 @@ function k(n, format, thousands) {
  * 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.
+ *
+ * @motion fill:fill The ring moves from the old measured value to the new one when the count changes while the meter is
+ * on screen, and changes colour at the warning line. The first value is drawn in place, never swept from empty.
+ * @motion value:value The percentage beside the ring crossfades to the new figure in the quick duration when the count
+ * changes while the meter is on screen; it never counts through values that were not measured.
  */
 function ContextMeter({ segments, limit, className, }) {
     const t = useStrings("contextMeter", contextMeterStrings);
@@ -49,7 +58,9 @@ function ContextMeter({ segments, limit, className, }) {
     // 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", style: fillMotion, className: cn(drawn && "cd-fill") })] }), 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]
+    const percent = fmt.number(Math.round(pct * 100) / 100, { style: "percent" });
+    const percentChanges = useSettled(percent, changed);
+    return (_jsxs(Popover, { children: [_jsxs(PopoverTrigger, { "data-slot": "context-meter", "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", style: fillMotion, className: cn(drawn && "cd-fill") })] }), percentChanges > 0 ? (_jsx("span", { style: valueMotion, className: "cd-value", children: percent }, percentChanges)) : (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/entity-chip.d.ts

@@ -44,7 +44,7 @@ declare function useEntityKinds(): (kind: string) => EntityKindInfo;
  * identifier is the label unless a friendlier one is given; then the
  * identifier is on hover and for screen readers.
  */
-declare function EntityChip({ entity, onOpen, onRemove, className, }: {
+declare function EntityChip({ entity, onOpen, onRemove, className, style, }: {
     /** The thing to show: its kind, identifier and optional label. */
     entity: EntityRef;
     /** Makes the chip a button that opens the thing. */
@@ -52,5 +52,7 @@ declare function EntityChip({ entity, onOpen, onRemove, className, }: {
     /** Adds a remove button, e.g. in the composer. */
     onRemove?: ((entity: EntityRef) => 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;
 export { EntityChip, EntityKindsProvider, useEntityKinds };

package/dist/chat/entity-chip.js

@@ -72,7 +72,7 @@ function useEntityKinds() {
  * identifier is the label unless a friendlier one is given; then the
  * identifier is on hover and for screen readers.
  */
-function EntityChip({ entity, onOpen, onRemove, className, }) {
+function EntityChip({ entity, onOpen, onRemove, className, style, }) {
     const { Icon, noun } = useEntityKinds()(entity.kind);
     const t = useStrings("entityChip", entityChipStrings);
     const shown = entity.label ?? entity.name;
@@ -81,6 +81,6 @@ function EntityChip({ entity, onOpen, onRemove, className, }) {
         : t("title", { noun, name: entity.name });
     const body = (_jsxs(_Fragment, { children: [_jsx(Icon, { "aria-hidden": true, className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: shown }), _jsxs("span", { className: "sr-only", children: [" (", title, ")"] })] }));
     const base = "inline-flex max-w-full items-center gap-1 rounded-sm border bg-card px-1.5 py-px align-baseline font-mono text-[0.92em] leading-[1.35] text-foreground";
-    return (_jsxs("span", { "data-slot": "entity-chip", "data-kind": entity.kind, title: title, className: cn("inline-flex max-w-full min-w-0 items-center sm:max-w-64", className), children: [onOpen ? (_jsx("button", { type: "button", onClick: () => onOpen(entity), className: cn(base, "cursor-pointer cd-tint hover:border-border-strong hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80 outline-none"), children: body })) : (_jsx("span", { className: base, children: body })), onRemove && (_jsx("button", { type: "button", "aria-label": t("remove", { name: shown }), onClick: () => onRemove(entity), className: "relative after:absolute after:-inset-1 -ms-px rounded-e-sm border border-s-0 bg-card px-1 py-px text-faint-foreground hover:text-foreground", children: "\u00D7" }))] }));
+    return (_jsxs("span", { "data-slot": "entity-chip", "data-kind": entity.kind, title: title, style: style, className: cn("inline-flex max-w-full min-w-0 items-center sm:max-w-64", className), children: [onOpen ? (_jsx("button", { type: "button", onClick: () => onOpen(entity), className: cn(base, "cursor-pointer cd-tint hover:border-border-strong hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80 outline-none"), children: body })) : (_jsx("span", { className: base, children: body })), onRemove && (_jsx("button", { type: "button", "aria-label": t("remove", { name: shown }), onClick: () => onRemove(entity), className: "relative after:absolute after:-inset-1 -ms-px rounded-e-sm border border-s-0 bg-card px-1 py-px text-faint-foreground hover:text-foreground", children: "\u00D7" }))] }));
 }
 export { EntityChip, EntityKindsProvider, useEntityKinds };

package/dist/chat/permission-prompt.d.ts

@@ -113,6 +113,11 @@ export type PermissionAnswer = {
  * nothing else is ever counted as a denial. While the decision waits, its shield pulses slowly; a press on inert
  * space outside it (the gesture that would dismiss a dialog) nudges it instead, so the person sees it is still
  * waiting. Both stop once the answer is being sent.
+ *
+ * @motion attention:waiting While the decision waits, a ring pulses out from the shield three times and then is still.
+ * It stops once the answer is being sent, and under calm it is one ring that fades.
+ * @motion attention:nudge A press on inert space outside the prompt rings it once, so the person sees it is still waiting.
+ * @motion refuse:nudge Under expressive the same press also shakes the prompt a little; nothing is dismissed.
  */
 declare function PermissionPrompt({ request, mode, suggestions, editable, onAllow, onDeny, busy, className, }: {
     /** The waiting request. */

package/dist/chat/permission-prompt.js

@@ -7,6 +7,16 @@ import { useStrings } from "../blocks/locale.js";
 import { Payload } from "./payload.js";
 import { Button } from "../ui/button.js";
 import { motion } from "../lib/motion.js";
+/** How long the animations running on `el` take in all, in milliseconds (the longest of duration × iteration count, capped at 6 s); undefined when it can't be read. */
+function animationMs(el) {
+    if (!el || typeof getComputedStyle === "undefined")
+        return undefined;
+    const style = getComputedStyle(el);
+    const durations = style.animationDuration.split(",").map((t) => (t.trim().endsWith("ms") ? Number.parseFloat(t) : Number.parseFloat(t) * 1000));
+    const counts = style.animationIterationCount.split(",").map((c) => (c.trim() === "infinite" ? Number.POSITIVE_INFINITY : Number.parseFloat(c)));
+    const totals = durations.map((d, i) => d * (counts[i % counts.length] || 1)).filter((n) => Number.isFinite(n) || n === Number.POSITIVE_INFINITY);
+    return totals.length ? Math.min(6000, Math.max(...totals)) : undefined;
+}
 /** Three pulses of 1.6 s while the decision waits (4.8 s, then still), shortened from 2.2's 7.2 s. */
 const waitingMotion = motion("permission-prompt", "waiting", "attention", { dur: 1600, amp: "3" });
 /** A press around the prompt instead of on it: one ring, and the refuse shake under expressive. */
@@ -88,6 +98,11 @@ function parseObject(text) {
  * nothing else is ever counted as a denial. While the decision waits, its shield pulses slowly; a press on inert
  * space outside it (the gesture that would dismiss a dialog) nudges it instead, so the person sees it is still
  * waiting. Both stop once the answer is being sent.
+ *
+ * @motion attention:waiting While the decision waits, a ring pulses out from the shield three times and then is still.
+ * It stops once the answer is being sent, and under calm it is one ring that fades.
+ * @motion attention:nudge A press on inert space outside the prompt rings it once, so the person sees it is still waiting.
+ * @motion refuse:nudge Under expressive the same press also shakes the prompt a little; nothing is dismissed.
  */
 function PermissionPrompt({ request, mode, suggestions, editable = false, onAllow, onDeny, busy = false, className, }) {
     // Keyed by the request, so an edit, a ticked rule or an answer never carries over to the next request.
@@ -116,6 +131,7 @@ function PromptBody({ request, mode, suggestions, editable, onAllow, onDeny, bus
     // A press on inert space outside every prompt, while it waits, nudges it rather than dismissing anything.
     const section = React.useRef(null);
     const [nudged, setNudged] = React.useState(false);
+    const ended = React.useRef(new Set());
     React.useEffect(() => {
         if (busy)
             return;
@@ -136,7 +152,11 @@ function PromptBody({ request, mode, suggestions, editable, onAllow, onDeny, bus
     React.useEffect(() => {
         if (!nudged)
             return;
-        const timer = window.setTimeout(() => setNudged(false), 1000);
+        // The nudge ends when its animations do (onAnimationEnd on the section). This timer is only the fallback for when
+        // none runs (motion off, or no Candor CSS), set from the duration and count the page resolved, so a brand's longer
+        // ring or shake isn't cut short.
+        ended.current = new Set();
+        const timer = window.setTimeout(() => setNudged(false), (animationMs(section.current) ?? 1200) + 100);
         return () => window.clearTimeout(timer);
     }, [nudged]);
     const word = (s) => {
@@ -171,7 +191,16 @@ function PromptBody({ request, mode, suggestions, editable, onAllow, onDeny, bus
             return;
         onAllow({ ...(edited && changedKeys.length && { updatedInput: edited }), ...(ticked.length && { alwaysAllow: ticked }) });
     };
-    return (_jsxs("section", { ref: section, "data-slot": "permission-prompt", "data-waiting": busy ? undefined : "", "data-nudged": nudged ? "" : undefined, "aria-label": t("label", { title: questions ? t("questions") : title }), style: nudgeMotion, className: cn("overflow-hidden rounded-xl border border-warning/50 bg-card text-sm shadow-xs [--cd-attention-color:var(--warning)]", nudged && "cd-nudge", className), children: [_jsxs("header", { className: "flex items-start gap-2.5 bg-warning-weak/50 px-3.5 py-2.5", children: [_jsx("span", { "aria-hidden": true, style: waitingMotion, className: cn("mt-0.5 flex size-4 shrink-0 items-center justify-center rounded-full text-warning-text", !busy && "cd-attention"), children: _jsx(ShieldQuestion, { className: "size-4" }) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("h3", { className: "font-semibold leading-snug", children: questions ? t("questions") : title }), request.description && _jsx("p", { className: "mt-0.5 text-muted-foreground", children: request.description })] }), _jsx("code", { className: "shrink-0 font-mono text-2xs text-muted-foreground", children: request.tool })] }), _jsxs("dl", { className: "flex flex-col gap-1.5 px-3.5 pt-2.5 text-sm", children: [request.reason && (_jsxs("div", { className: "flex gap-2", children: [_jsx("dt", { className: "shrink-0 text-muted-foreground", children: t("why") }), _jsx("dd", { className: "min-w-0", children: request.reason })] })), mode && (_jsxs("div", { className: "flex gap-2", children: [_jsx("dt", { className: "shrink-0 text-muted-foreground", children: t("mode") }), _jsx("dd", { "data-slot": "permission-mode", children: modeKeys[mode] ? t(modeKeys[mode]) : _jsx("code", { className: "font-mono text-xs", children: mode }) })] }))] }), (request.blockedPath || request.agentId || request.mcpServer) && (_jsxs("ul", { className: "mt-1.5 flex flex-col gap-0.5 px-3.5 text-xs text-muted-foreground", children: [request.blockedPath && _jsx("li", { children: t("blockedPath", { path: request.blockedPath }) }), request.agentId && _jsx("li", { children: t("subagent") }), request.mcpServer && _jsx("li", { children: t("server", { name: request.mcpServer.name, source: request.mcpServer.source }) })] })), questions ? (_jsx("div", { className: "flex flex-col gap-4 px-3.5 py-3", children: questions.map((q) => {
+    return (_jsxs("section", { ref: section, "data-slot": "permission-prompt", "data-waiting": busy ? undefined : "", "data-nudged": nudged ? "" : undefined, onAnimationEnd: (e) => {
+            // The nudge runs two animations (the shake and the ring) and ends with the last of them. A child's own
+            // animation, or one that isn't Candor's, doesn't end it.
+            if (e.target !== e.currentTarget || !e.animationName.startsWith("cd-"))
+                return;
+            ended.current.add(e.animationName);
+            const running = getComputedStyle(e.currentTarget).animationName.split(",").map((n) => n.trim()).filter((n) => n.startsWith("cd-"));
+            if (running.every((n) => ended.current.has(n)))
+                setNudged(false);
+        }, "aria-label": t("label", { title: questions ? t("questions") : title }), style: nudgeMotion, className: cn("overflow-hidden rounded-xl border border-warning/50 bg-card text-sm shadow-xs [--cd-attention-color:var(--warning)]", nudged && "cd-nudge", className), children: [_jsxs("header", { className: "flex items-start gap-2.5 bg-warning-weak/50 px-3.5 py-2.5", children: [_jsx("span", { "aria-hidden": true, style: waitingMotion, className: cn("mt-0.5 flex size-4 shrink-0 items-center justify-center rounded-full text-warning-text", !busy && "cd-attention"), children: _jsx(ShieldQuestion, { className: "size-4" }) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("h3", { className: "font-semibold leading-snug", children: questions ? t("questions") : title }), request.description && _jsx("p", { className: "mt-0.5 text-muted-foreground", children: request.description })] }), _jsx("code", { className: "shrink-0 font-mono text-2xs text-muted-foreground", children: request.tool })] }), _jsxs("dl", { className: "flex flex-col gap-1.5 px-3.5 pt-2.5 text-sm", children: [request.reason && (_jsxs("div", { className: "flex gap-2", children: [_jsx("dt", { className: "shrink-0 text-muted-foreground", children: t("why") }), _jsx("dd", { className: "min-w-0", children: request.reason })] })), mode && (_jsxs("div", { className: "flex gap-2", children: [_jsx("dt", { className: "shrink-0 text-muted-foreground", children: t("mode") }), _jsx("dd", { "data-slot": "permission-mode", children: modeKeys[mode] ? t(modeKeys[mode]) : _jsx("code", { className: "font-mono text-xs", children: mode }) })] }))] }), (request.blockedPath || request.agentId || request.mcpServer) && (_jsxs("ul", { className: "mt-1.5 flex flex-col gap-0.5 px-3.5 text-xs text-muted-foreground", children: [request.blockedPath && _jsx("li", { children: t("blockedPath", { path: request.blockedPath }) }), request.agentId && _jsx("li", { children: t("subagent") }), request.mcpServer && _jsx("li", { children: t("server", { name: request.mcpServer.name, source: request.mcpServer.source }) })] })), questions ? (_jsx("div", { className: "flex flex-col gap-4 px-3.5 py-3", children: questions.map((q) => {
                     const a = answers[q.id];
                     return (_jsxs("fieldset", { className: "flex flex-col gap-1.5", children: [_jsxs("legend", { className: "mb-1 font-medium", children: [q.tag && _jsx("span", { className: "me-1.5 rounded-xs bg-muted px-1 text-2xs font-medium text-muted-foreground", children: q.tag }), q.prompt] }), q.options.map((o) => (_jsxs("label", { className: "flex min-h-6 items-start gap-2", children: [_jsx("input", { type: q.multiple ? "checkbox" : "radio", name: `${id}-${q.id}`, checked: a?.choice.includes(o.id) ?? false, onChange: () => choose(q, o.id), className: "mt-0.5 size-4 accent-[var(--primary)]" }), _jsxs("span", { children: [o.label, o.detail && _jsx("span", { className: "block text-xs text-muted-foreground", children: o.detail })] })] }, o.id))), q.other && (_jsxs(_Fragment, { children: [_jsxs("label", { className: "flex min-h-6 items-start gap-2", children: [_jsx("input", { type: q.multiple ? "checkbox" : "radio", name: `${id}-${q.id}`, checked: a?.other ?? false, onChange: () => toggleOther(q), className: "mt-0.5 size-4 accent-[var(--primary)]" }), _jsx("span", { children: t("otherOption") })] }), a?.other && (_jsx("textarea", { "aria-label": t("otherLabel", { question: q.prompt }), rows: 2, value: a.text, onChange: (e) => setAnswers((prev) => ({ ...prev, [q.id]: { ...prev[q.id], text: e.target.value } })), className: "ms-6 block resize-none rounded-md border border-input bg-card px-2.5 py-1.5 text-sm outline-none [field-sizing:content] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/30" }))] }))] }, q.id));
                 }) })) : (_jsxs("div", { className: "flex flex-col gap-2 px-3.5 py-3", children: [editing ? (_jsxs(_Fragment, { children: [_jsx("label", { htmlFor: `${id}-edit`, className: "text-xs font-medium text-muted-foreground", children: t("editLabel") }), _jsx("textarea", { id: `${id}-edit`, value: draft, onChange: (e) => setDraft(e.target.value), spellCheck: false, rows: Math.min(12, draft.split("\n").length + 1), "aria-invalid": invalid || undefined, "aria-describedby": `${id}-changes`, className: "block w-full resize-y rounded-md border border-input bg-card px-2.5 py-1.5 font-mono text-xs outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/30 aria-invalid:border-destructive" }), _jsx("div", { id: `${id}-changes`, role: "status", className: "text-xs", children: invalid ? (_jsx("p", { className: "text-destructive-text", children: t("editInvalid") })) : changedKeys.length ? (_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("p", { className: "text-muted-foreground", children: t("changed") }), _jsx("ul", { className: "flex flex-col gap-1", children: changedKeys.map((k) => (_jsxs("li", { className: "grid gap-0.5 font-mono", children: [_jsx("span", { className: "text-muted-foreground", children: k }), k in proposed && _jsx("span", { className: "rounded-xs bg-destructive-weak/60 px-1 line-through", children: json(proposed[k]) }), k in edited && _jsx("span", { className: "rounded-xs bg-success-weak/70 px-1", children: json(edited[k]) })] }, k))) })] })) : (_jsx("p", { className: "text-muted-foreground", children: t("unchanged") })) }), _jsx(Button, { size: "sm", variant: "ghost", className: "self-start", onClick: () => (setEditing(false), setDraft(original)), children: t("cancelEdit") })] })) : (_jsxs(_Fragment, { children: [_jsx(Payload, { language: "json", title: t("input"), text: original }), editable && proposed && (_jsxs(Button, { size: "sm", variant: "outline", className: "self-start", onClick: () => setEditing(true), children: [_jsx(Pencil, { "aria-hidden": true }), " ", t("edit")] }))] })), suggestions && suggestions.length > 0 && (_jsxs("fieldset", { className: "mt-1 flex flex-col gap-1 rounded-lg border border-dashed px-3 py-2", children: [_jsx("legend", { className: "px-1 text-xs font-medium", children: t("remember") }), _jsxs("p", { className: "flex items-center gap-1 text-xs text-muted-foreground", children: [_jsx(Info, { "aria-hidden": true, className: "size-3" }), " ", t("rememberHint")] }), suggestions.map((s, i) => {

package/dist/chat/thread.js

@@ -9,6 +9,16 @@ import { motion, useMotionAllowed } from "../lib/motion.js";
 /** The smooth scroll to the latest message. */
 const scrollMotion = motion("thread", "scroll", "move");
 /** Jump to latest appearing while the reader is scrolled up: 2.2's 150 ms and 4 px rise. */
+/** How long the animations running on `el` take in all, in milliseconds (the longest of duration × iteration count, capped at 6 s); undefined when it can't be read. */
+function animationMs(el) {
+    if (!el || typeof getComputedStyle === "undefined")
+        return undefined;
+    const style = getComputedStyle(el);
+    const durations = style.animationDuration.split(",").map((t) => (t.trim().endsWith("ms") ? Number.parseFloat(t) : Number.parseFloat(t) * 1000));
+    const counts = style.animationIterationCount.split(",").map((c) => (c.trim() === "infinite" ? Number.POSITIVE_INFINITY : Number.parseFloat(c)));
+    const totals = durations.map((d, i) => d * (counts[i % counts.length] || 1)).filter((n) => Number.isFinite(n) || n === Number.POSITIVE_INFINITY);
+    return totals.length ? Math.min(6000, Math.max(...totals)) : undefined;
+}
 const jumpMotion = motion("thread", "jump", "arrive", { dur: 150 });
 /** Its ring when a message arrives while the reader is scrolled up. */
 const arrivalMotion = motion("thread", "arrival", "attention");
@@ -58,6 +68,7 @@ function Thread({ children, empty, footer, className, contentClassName, virtuali
     const [arrived, setArrived] = React.useState(false);
     const arrivedRef = React.useRef(false);
     const frame = React.useRef(0);
+    const jump = React.useRef(null);
     React.useEffect(() => {
         arrivedRef.current = arrived;
     }, [arrived]);
@@ -119,7 +130,10 @@ function Thread({ children, empty, footer, className, contentClassName, virtuali
     React.useEffect(() => {
         if (!arrived)
             return;
-        const timer = window.setTimeout(() => setArrived(false), 1000);
+        // The ring ends when its animation does (onAnimationEnd on the button). This timer is only the fallback for when
+        // no animation runs (motion off, or no Candor CSS), set from the duration and count the page resolved, so a brand's
+        // longer ring isn't cut short.
+        const timer = window.setTimeout(() => setArrived(false), (animationMs(jump.current) ?? 1200) + 100);
         return () => window.clearTimeout(timer);
     }, [arrived]);
     // Open at the anchor once, when it first appears.
@@ -188,7 +202,10 @@ function Thread({ children, empty, footer, className, contentClassName, virtuali
                             }
                             : undefined, onBlur: virtualize ? (e) => !e.currentTarget.contains(e.relatedTarget) && setFocused(null) : undefined, className: "h-full scroll-pb-14 overflow-y-auto overscroll-contain", children: _jsx("div", { ref: content, role: "log", "aria-label": t("messages"), className: cn("mx-auto flex w-full max-w-(--cd-thread-width) flex-col gap-7 px-4 py-6", contentClassName), children: !hasMessages ? (empty) : virtualize ? (_jsx(_Fragment, { children: list.rows.map((row) => "spacer" in row ? (_jsx("div", { "aria-hidden": true, style: { height: row.spacer } }, row.key)) : (_jsx("div", { ref: list.measure, "data-virtual-key": String(keyOf(row.index)), className: "flex flex-col", children: items[row.index] }, keyOf(row.index)))) })) : (children) }) }), !pinned && hasMessages && (
                     // The entrance is the wrapper's, so the pulse on the button never replays it.
-                    _jsx("span", { style: jumpMotion, className: "absolute bottom-3 left-1/2 z-10 -translate-x-1/2 cd-arrive", children: _jsxs("button", { type: "button", "data-slot": "thread-jump", "data-arrived": arrived ? "" : undefined, onClick: () => {
+                    _jsx("span", { style: jumpMotion, className: "absolute bottom-3 left-1/2 z-10 -translate-x-1/2 cd-arrive", children: _jsxs("button", { type: "button", ref: jump, "data-slot": "thread-jump", onAnimationEnd: (e) => {
+                                if (e.target === e.currentTarget && e.animationName.startsWith("cd-"))
+                                    setArrived(false);
+                            }, "data-arrived": arrived ? "" : undefined, onClick: () => {
                                 pinnedRef.current = true;
                                 setPinned(true);
                                 toBottom("smooth");

package/dist/index.d.ts

@@ -51,6 +51,7 @@ export * from "./ui/slider.js";
 export * from "./ui/progress.js";
 export * from "./ui/alert.js";
 export * from "./ui/accordion.js";
+export * from "./lib/sound.js";
 export * from "./lib/utils.js";
 export { ToolCall } from "./chat/tool-call.js";
 export type { ToolCall as ToolCallData } from "./lib/chat.js";

package/dist/index.js

@@ -51,6 +51,7 @@ export * from "./ui/slider.js";
 export * from "./ui/progress.js";
 export * from "./ui/alert.js";
 export * from "./ui/accordion.js";
+export * from "./lib/sound.js";
 export * from "./lib/utils.js";
 export { ToolCall } from "./chat/tool-call.js";
 export { Message } from "./chat/message.js";

package/dist/lib/motion.d.ts

@@ -350,6 +350,13 @@ export declare const motionFamilies: {
 export declare const motionFamilyNames: MotionFamily[];
 /** A family's variants, by name: `MotionVariant<"mark">` is `"draw" | "pop" | "drop"`. */
 export type MotionVariant<F extends MotionFamily> = (typeof motionFamilies)[F]["variants"][number];
+/**
+ * True when a family has one way of drawing its change (fill, move, press, tint, refuse, attention, live and clock).
+ * Its single variant is fixed: there is no `-variant` token to set, and `motion()` writes none, because the family's
+ * utility has nothing to choose between. The docs mark such a family "(fixed)" instead of listing a value that does
+ * nothing. A later release that adds a second word turns the token on without a new name.
+ */
+export declare const motionVariantIsFixed: (family: MotionFamily) => boolean;
 /**
  * The CSS value a variant is written as. CSS can only choose a drawing by keyframe name, so a variant's value is its
  * keyframe's: the word with Candor's prefix, which keeps an app's own `@keyframes rise` from taking over.
@@ -420,7 +427,8 @@ export declare function useSettled<T>(value: T, test: SettledTest<T>): number;
 export declare function useArrived(keys: readonly string[]): (key: string) => boolean;
 /**
  * Items that just left, kept as inert ghosts for the length of their out moment. Each ghost goes when `left(item)` is
- * called (from its `onAnimationEnd`), or after `fallbackMs` when nothing animated. An item that comes back while its
+ * called (from its `onAnimationEnd`), or after `fallbackMs` when nothing animated. The default, 600 ms, is longer than
+ * the longest out moment a brand can set (pop's 300 ms at the slowest speed, 1.5×, is 450 ms). An item that comes back while its
  * ghost is still leaving takes the ghost's place.
  */
 export declare function useLeaving<T>(items: readonly T[], keyOf: (item: T) => string, fallbackMs?: number): {
@@ -436,6 +444,13 @@ export type MotionMode = "full" | "calm" | "none";
  * panels) are ignored.
  */
 export declare function motionMode(el: Element | null | undefined): MotionMode;
+/**
+ * `motionMode` for a component that has to react to it: the person's setting where `ref`'s element is, read after
+ * mount and again whenever the app changes `data-motion` or the OS setting changes. It starts as `full` for the first
+ * render, since there is nothing to read until the element exists. Use it for behaviour (a timer that must stop),
+ * not for styling, which the CSS variants already answer.
+ */
+export declare function useMotionMode(ref: React.RefObject<Element | null>): MotionMode;
 /**
  * The level a moment resolves to on `el`, read from its computed style: the moment's token, its family's, the preset,
  * then capped by `data-motion`. A page without Candor's CSS reads as subtle.

package/dist/lib/motion.js

@@ -179,6 +179,13 @@ export const motionFamilies = {
 };
 /** The family names, in the order the docs and the theme builder list them. */
 export const motionFamilyNames = Object.keys(motionFamilies);
+/**
+ * True when a family has one way of drawing its change (fill, move, press, tint, refuse, attention, live and clock).
+ * Its single variant is fixed: there is no `-variant` token to set, and `motion()` writes none, because the family's
+ * utility has nothing to choose between. The docs mark such a family "(fixed)" instead of listing a value that does
+ * nothing. A later release that adds a second word turns the token on without a new name.
+ */
+export const motionVariantIsFixed = (family) => motionFamilies[family].variants.length < 2;
 /**
  * The CSS value a variant is written as. CSS can only choose a drawing by keyframe name, so a variant's value is its
  * keyframe's: the word with Candor's prefix, which keeps an app's own `@keyframes rise` from taking over.
@@ -215,7 +222,7 @@ export function motion(item, moment, family, defaults = {}) {
         style[`${local}-ease`] = `var(${own}-ease, var(${fam}-ease, ${motionEases[defaults.ease ?? spec.ease]}))`;
     if (spec.amp)
         style[`${local}-amp`] = `var(${own}-${spec.amp.name}, var(${fam}-${spec.amp.name}, ${defaults.amp ?? spec.amp.default}))`;
-    if (spec.variants.length > 1) {
+    if (!motionVariantIsFixed(family)) {
         const variant = motionVariantValue(defaults.variant ?? spec.variants[0]);
         style[`${local}-variant`] = `var(${own}-variant, var(${fam}-variant, ${variant}))`;
     }
@@ -272,10 +279,11 @@ export function useArrived(keys) {
 }
 /**
  * Items that just left, kept as inert ghosts for the length of their out moment. Each ghost goes when `left(item)` is
- * called (from its `onAnimationEnd`), or after `fallbackMs` when nothing animated. An item that comes back while its
+ * called (from its `onAnimationEnd`), or after `fallbackMs` when nothing animated. The default, 600 ms, is longer than
+ * the longest out moment a brand can set (pop's 300 ms at the slowest speed, 1.5×, is 450 ms). An item that comes back while its
  * ghost is still leaving takes the ghost's place.
  */
-export function useLeaving(items, keyOf, fallbackMs = 400) {
+export function useLeaving(items, keyOf, fallbackMs = 600) {
     const [leaving, setLeaving] = React.useState([]);
     const previous = React.useRef(null);
     React.useLayoutEffect(() => {
@@ -314,6 +322,28 @@ export function motionMode(el) {
         return "calm";
     return "full";
 }
+/**
+ * `motionMode` for a component that has to react to it: the person's setting where `ref`'s element is, read after
+ * mount and again whenever the app changes `data-motion` or the OS setting changes. It starts as `full` for the first
+ * render, since there is nothing to read until the element exists. Use it for behaviour (a timer that must stop),
+ * not for styling, which the CSS variants already answer.
+ */
+export function useMotionMode(ref) {
+    const [mode, setMode] = React.useState("full");
+    React.useEffect(() => {
+        const read = () => setMode(motionMode(ref.current));
+        read();
+        const observer = new MutationObserver(read);
+        observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-motion"], subtree: true });
+        const query = window.matchMedia?.("(prefers-reduced-motion: reduce)");
+        query?.addEventListener("change", read);
+        return () => {
+            observer.disconnect();
+            query?.removeEventListener("change", read);
+        };
+    }, [ref]);
+    return mode;
+}
 const number = (value) => {
     const n = Number.parseFloat(value);
     return Number.isFinite(n) ? n : undefined;

package/dist/lib/sound.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The names and the reading half of Candor's sound layer. A brand file names a sound per event
+ * (`--cd-sound-needs-you: "/sounds/needs-you.mp3"`); this file knows the five events, reads that token from the
+ * page's computed style, and holds the small arithmetic the Pro hooks share. It plays nothing: nothing is fetched
+ * until `useAttention` or `sound-setting` plays a sound, and a sound is always off until the person turns it on.
+ *
+ * Tokens, all optional, all read when a sound is about to play:
+ * - `--cd-sound-<event>`: a string, the path of an MP3 hosted by the app. No token, no sound, silently.
+ * - `--cd-sound-<event>-ogg`: a string, an Ogg/Opus alternative the browser may prefer.
+ * - `--cd-sound-volume`: 0 to 1, how loud every sound is. `--cd-sound-<event>-volume`: 0 to 1, scales that for one event.
+ *
+ * Safe to import on the server: the document is touched only inside `readSoundToken`.
+ */
+/** The five things the app may make a sound for. A closed list: `reply` and `silent` have no `AttentionKind` until 3.0. */
+export type SoundEvent = "needs-you" | "finished" | "failed" | "reply" | "silent";
+/** Every event, in the order the settings control lists them. */
+export declare const soundEvents: readonly SoundEvent[];
+/** The events a sound is offered for once the person turns sound on; `reply` and `silent` stay off until they pick them. */
+export declare const defaultSoundEvents: readonly SoundEvent[];
+/** A sound as the brand names it: where the file is, an optional Ogg alternative, and how loud (0 to 1). */
+export type SoundToken = {
+    src: string;
+    ogg?: string | undefined;
+    volume: number;
+};
+/** The longest a sound may be, in seconds. `theme check` measures what it can read. */
+export declare const maxSoundSeconds = 1.5;
+/** The least time between two plays of the same event, in milliseconds. A burst plays once. */
+export declare const soundCoalesceMs = 3000;
+/** A CSS custom property's value as the text it names: quotes removed, or the inside of `url(…)`. Empty when unset. */
+export declare function soundString(raw: string): string;
+/** How loud `event` is, 0 to 1: the global `--cd-sound-volume` times the event's own, each 1 when unset. 1 on the server. */
+export declare function readSoundVolume(event: SoundEvent, element?: Element | undefined): number;
+/**
+ * The brand's sound for `event`, read from the computed style of `element` (the document's root when left out), or
+ * `undefined` when the brand names none, or on the server.
+ */
+export declare function readSoundToken(event: SoundEvent, element?: Element | undefined): SoundToken | undefined;
+/**
+ * Whether a play at `now` is allowed, given when each event last played and when anything last played: the same event
+ * waits `soundCoalesceMs` after it played, and any sound in the same instant (a burst) is the one already playing.
+ * Pure; the caller keeps the clock.
+ */
+export declare function mayPlay(event: SoundEvent, last: Partial<Record<SoundEvent, number>>, now: number, burstMs?: number): boolean;

package/dist/lib/sound.js

@@ -0,0 +1,63 @@
+/**
+ * The names and the reading half of Candor's sound layer. A brand file names a sound per event
+ * (`--cd-sound-needs-you: "/sounds/needs-you.mp3"`); this file knows the five events, reads that token from the
+ * page's computed style, and holds the small arithmetic the Pro hooks share. It plays nothing: nothing is fetched
+ * until `useAttention` or `sound-setting` plays a sound, and a sound is always off until the person turns it on.
+ *
+ * Tokens, all optional, all read when a sound is about to play:
+ * - `--cd-sound-<event>`: a string, the path of an MP3 hosted by the app. No token, no sound, silently.
+ * - `--cd-sound-<event>-ogg`: a string, an Ogg/Opus alternative the browser may prefer.
+ * - `--cd-sound-volume`: 0 to 1, how loud every sound is. `--cd-sound-<event>-volume`: 0 to 1, scales that for one event.
+ *
+ * Safe to import on the server: the document is touched only inside `readSoundToken`.
+ */
+/** Every event, in the order the settings control lists them. */
+export const soundEvents = ["needs-you", "finished", "failed", "reply", "silent"];
+/** The events a sound is offered for once the person turns sound on; `reply` and `silent` stay off until they pick them. */
+export const defaultSoundEvents = ["needs-you", "finished", "failed"];
+/** The longest a sound may be, in seconds. `theme check` measures what it can read. */
+export const maxSoundSeconds = 1.5;
+/** The least time between two plays of the same event, in milliseconds. A burst plays once. */
+export const soundCoalesceMs = 3000;
+/** A CSS custom property's value as the text it names: quotes removed, or the inside of `url(…)`. Empty when unset. */
+export function soundString(raw) {
+    const v = raw.trim();
+    const url = /^url\(\s*(['"]?)(.*?)\1\s*\)$/.exec(v);
+    const text = url ? (url[2] ?? "") : v;
+    return text.replace(/^(['"])(.*)\1$/, "$2").trim();
+}
+const unit = (raw) => {
+    const n = Number.parseFloat(raw);
+    return Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : undefined;
+};
+const styleOf = (element) => typeof document === "undefined" || typeof getComputedStyle === "undefined" ? undefined : getComputedStyle(element ?? document.documentElement);
+/** How loud `event` is, 0 to 1: the global `--cd-sound-volume` times the event's own, each 1 when unset. 1 on the server. */
+export function readSoundVolume(event, element) {
+    const style = styleOf(element);
+    if (!style)
+        return 1;
+    return (unit(style.getPropertyValue("--cd-sound-volume")) ?? 1) * (unit(style.getPropertyValue(`--cd-sound-${event}-volume`)) ?? 1);
+}
+/**
+ * The brand's sound for `event`, read from the computed style of `element` (the document's root when left out), or
+ * `undefined` when the brand names none, or on the server.
+ */
+export function readSoundToken(event, element) {
+    const style = styleOf(element);
+    const src = style && soundString(style.getPropertyValue(`--cd-sound-${event}`));
+    if (!style || !src)
+        return undefined;
+    const ogg = soundString(style.getPropertyValue(`--cd-sound-${event}-ogg`));
+    return { src, ...(ogg && { ogg }), volume: readSoundVolume(event, element) };
+}
+/**
+ * Whether a play at `now` is allowed, given when each event last played and when anything last played: the same event
+ * waits `soundCoalesceMs` after it played, and any sound in the same instant (a burst) is the one already playing.
+ * Pure; the caller keeps the clock.
+ */
+export function mayPlay(event, last, now, burstMs = 400) {
+    const before = last[event];
+    if (before !== undefined && now - before < soundCoalesceMs)
+        return false;
+    return !soundEvents.some((e) => (last[e] ?? -Infinity) > now - burstMs);
+}

package/dist/styles.css

@@ -9,7 +9,6 @@
  * Tailwind skips node_modules when it scans your app.
  */
 @import "@fontsource-variable/inter/opsz.css";
-@import "tw-animate-css";
 
 @source "./**/*.js";
 
@@ -1104,3 +1103,22 @@
     animation: none !important;
   }
 }
+
+/*
+ * Sound (2.4). Candor sets no defaults here: no sound plays unless a brand file names one, and no sound plays at all
+ * until the person turns sound on in your app. These are the names a brand file may set, in `:root`. Each value is a
+ * string, the path of a file your app hosts (MP3, at most 1.5 s); nothing is fetched until a sound plays.
+ *
+ *   --cd-sound-needs-you   a new approval, question or disambiguation waits on the person
+ *   --cd-sound-finished    a run the person started finished
+ *   --cd-sound-failed      a run failed, or a guardrail stopped it
+ *   --cd-sound-reply       a person (not an agent) replied in a thread the person is in
+ *   --cd-sound-silent      a run the person started has not been heard from past its `staleAfter`
+ *
+ *   --cd-sound-<event>-ogg      optional Ogg/Opus alternative for the same event, as a string
+ *   --cd-sound-volume           0 to 1, how loud every sound is (1 when left out)
+ *   --cd-sound-<event>-volume   0 to 1, scales the global volume for one event (1 when left out)
+ *
+ * `useAttention` (Pro) reads them when a signal lands; `sound-setting` (Pro) plays them as a preview. Free items
+ * never play a sound. The starter set (`sounds`, Pro) installs /sounds/<event>.mp3 for all five.
+ */

package/dist/ui/alert.d.ts

@@ -7,7 +7,9 @@ import * as React from "react";
  * For a short notice that goes away by itself use a toast; an Alert doesn't dismiss itself.
  *
  * @motion arrive:enter An Alert that appears after the page has drawn rises in over a quarter of a second. One that is
- * there when the page first draws, or when it is rendered on the server, is simply there.
+ * there when the page first draws, or when it is rendered on the server, is simply there. "After the page has drawn" is
+ * counted from when the page loaded, not from the route: after a client-side navigation, an Alert on the new route
+ * rises in.
  */
 declare function Alert({ className, variant, role, style, ...props }: React.ComponentProps<"div"> & {
     /** The kind of message. `destructive` is for a failure or something that can't be undone; `warning` for care before acting; `attention` for something waiting on the person; `success` for a confirmed result. Defaults to a plain card. */

package/dist/ui/alert.js

@@ -5,8 +5,17 @@ import { cva } from "class-variance-authority";
 import { cn } from "../lib/utils.js";
 import { motion } from "../lib/motion.js";
 const enterMotion = motion("alert", "enter", "arrive");
-// Set once a first Alert has been drawn and the browser has painted; an Alert that mounts after that has arrived.
+// Set one frame after this file loads in the browser, which is when the page's first draw is done; an Alert that mounts
+// after that has arrived. It is per page load, not per route: after a client-side route change, an Alert on the new route
+// rises in, because it arrived after the page drew. An Alert in the first render, or on the server, is simply there.
 let pageDrawn = false;
+if (typeof window !== "undefined") {
+    const frame = typeof window.requestAnimationFrame === "function" ? window.requestAnimationFrame.bind(window) : (cb) => window.setTimeout(cb, 0);
+    frame(() => {
+        pageDrawn = true;
+    });
+}
+const subscribeNever = () => () => { };
 const alertVariants = cva("relative grid w-full grid-cols-[0_1fr] items-start gap-y-0.5 rounded-lg border px-4 py-3 text-sm has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] has-[>svg]:gap-x-3 [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current", {
     variants: {
         variant: {
@@ -27,17 +36,16 @@ const alertVariants = cva("relative grid w-full grid-cols-[0_1fr] items-start ga
  * For a short notice that goes away by itself use a toast; an Alert doesn't dismiss itself.
  *
  * @motion arrive:enter An Alert that appears after the page has drawn rises in over a quarter of a second. One that is
- * there when the page first draws, or when it is rendered on the server, is simply there.
+ * there when the page first draws, or when it is rendered on the server, is simply there. "After the page has drawn" is
+ * counted from when the page loaded, not from the route: after a client-side navigation, an Alert on the new route
+ * rises in.
  */
 function Alert({ className, variant, role, style, ...props }) {
-    // Whether this Alert mounted after the page's first draw. Decided once, so a re-render doesn't replay it.
-    const [arrived] = React.useState(() => pageDrawn);
-    React.useEffect(() => {
-        const raf = typeof window.requestAnimationFrame === "function" ? window.requestAnimationFrame : (cb) => window.setTimeout(cb, 0);
-        raf(() => {
-            pageDrawn = true;
-        });
-    }, []);
+    // Whether this Alert mounted after the page's first draw. The server and the hydrating render answer no, so what
+    // the server sent is what hydrates; an Alert the browser creates later answers from the page. Decided once, so a
+    // re-render doesn't replay it.
+    const drawn = React.useSyncExternalStore(subscribeNever, () => pageDrawn, () => false);
+    const [arrived] = React.useState(drawn);
     return (_jsx("div", { "data-slot": "alert", "data-variant": variant ?? "default", role: role ?? (variant === "destructive" ? "alert" : "status"), style: { ...enterMotion, ...style }, className: cn(alertVariants({ variant }), arrived && "cd-arrive", className), ...props }));
 }
 /** The alert's headline: what happened or what to know, in a few words. */

package/dist/ui/progress.d.ts

@@ -4,7 +4,7 @@ import { type RenderProp } from "../lib/render-prop.js";
 /**
  * A bar for work whose progress is measured: an upload, an import, an index. It moves only between values the service
  * reported, and it starts at the first value it is given rather than filling from empty. With no `value` it is
- * indeterminate: a moving sweep and the `label` as text, and never a made-up percentage.
+ * indeterminate: a pulsing bar and the `label` as text, and never a made-up percentage.
  *
  * @motion fill:value The filled part moves to each new measured value in the slow duration, and not on first draw.
  * @motion live:indeterminate While the total is unknown, the bar pulses (the live family's pulse) and the label shimmers

package/dist/ui/progress.js

@@ -10,7 +10,7 @@ const indeterminateMotion = motion("progress", "indeterminate", "live");
 /**
  * A bar for work whose progress is measured: an upload, an import, an index. It moves only between values the service
  * reported, and it starts at the first value it is given rather than filling from empty. With no `value` it is
- * indeterminate: a moving sweep and the `label` as text, and never a made-up percentage.
+ * indeterminate: a pulsing bar and the `label` as text, and never a made-up percentage.
  *
  * @motion fill:value The filled part moves to each new measured value in the slow duration, and not on first draw.
  * @motion live:indeterminate While the total is unknown, the bar pulses (the live family's pulse) and the label shimmers

package/dist/ui/switch.d.ts

@@ -7,7 +7,7 @@ import { type RenderProp } from "../lib/render-prop.js";
  * stays focusable, says why, and doesn't flip. Use a switch for a setting that takes effect at once; a choice the
  * person confirms belongs in a `Checkbox` or `RadioGroup` with a button.
  *
- * @motion move:thumb The thumb slides to the other end when the state changes, in the quick duration. It follows the
+ * @motion move:thumb The thumb slides to the other end when the state changes, over the move family's 200 ms. It follows the
  * reading direction, so it slides the other way in right-to-left text.
  */
 declare function Switch(allProps: React.ComponentProps<typeof SwitchPrimitive.Root> & RenderProp): React.JSX.Element;

package/dist/ui/switch.js

@@ -12,7 +12,7 @@ const thumbMotion = motion("switch", "thumb", "move");
  * stays focusable, says why, and doesn't flip. Use a switch for a setting that takes effect at once; a choice the
  * person confirms belongs in a `Checkbox` or `RadioGroup` with a button.
  *
- * @motion move:thumb The thumb slides to the other end when the state changes, in the quick duration. It follows the
+ * @motion move:thumb The thumb slides to the other end when the state changes, over the move family's 200 ms. It follows the
  * reading direction, so it slides the other way in right-to-left text.
  */
 function Switch(allProps) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@candor-ui/react",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Candor UI's free tier as an npm package: React components for agents that do real work, on shadcn/ui and Tailwind 4.",
   "license": "MIT",
   "author": "Methodic LLC",
@@ -50,8 +50,7 @@
     "clsx": "^2.1.1",
     "lucide-react": "^1.67.0",
     "radix-ui": "^1.8.1",
-    "tailwind-merge": "^3.7.0",
-    "tw-animate-css": "^1.4.0"
+    "tailwind-merge": "^3.7.0"
   },
   "peerDependencies": {
     "@ag-ui/client": "^1.0.3",