@candor-ui/react 2.3.0 → 2.5.0

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/prompt-suggestions.js

@@ -5,7 +5,10 @@ import { cn } from "../lib/utils.js";
 import { Skeleton } from "../ui/skeleton.js";
 import { useStrings } from "../blocks/locale.js";
 import { motion } from "../lib/motion.js";
-/** A suggestion pressed: 2.2's slight scale of 0.99. */
+/**
+ * @motion press:press A suggestion shrinks slightly while it is held down and returns when it is let go. Under
+ * reduced motion no suggestion changes size.
+ */
 const pressMotion = motion("prompt-suggestions", "press", "press", { amp: "0.98" });
 /** PromptSuggestions' fixed words; override them under `promptSuggestions` in LocaleProvider's `strings`. */
 export const promptSuggestionsStrings = {

package/dist/chat/reasoning.js

@@ -7,7 +7,15 @@ import { ShimmerLabel } from "../blocks/streaming-text.js";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible.js";
 import { useStrings } from "../blocks/locale.js";
 import { motion, useArrived } from "../lib/motion.js";
+/**
+ * @motion arrive:arrive A step of reasoning rises in when the agent adds it while the reasoning is on screen. A step
+ * added while it is folded rises in when it is opened. The steps it was drawn with are still.
+ */
 const arriveMotion = motion("reasoning", "arrive", "arrive");
+/**
+ * @motion reveal:open The steps open to their full height when the person opens the summary, or when the agent starts
+ * thinking, and the chevron turns with it; closing reverses both. Under reduced motion they snap open or shut.
+ */
 const turnMotion = motion("reasoning", "open", "reveal");
 /** Reasoning's fixed words; override them under `reasoning` in LocaleProvider's `strings`. */
 export const reasoningStrings = {

package/dist/chat/thread.js

@@ -6,11 +6,31 @@ import { cn } from "../lib/utils.js";
 import { useStrings } from "../blocks/locale.js";
 import { useVirtualList } from "../lib/use-virtual-list.js";
 import { motion, useMotionAllowed } from "../lib/motion.js";
-/** The smooth scroll to the latest message. */
+/**
+ * @motion move:scroll When the person presses Jump to latest, the thread glides down to the newest message. Under
+ * reduced motion it jumps. Opening the thread and following new messages while the person is at the bottom are never
+ * smooth scrolls.
+ */
 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;
+}
+/**
+ * @motion arrive:jump The Jump to latest control fades in when the person scrolls up from the bottom and goes when
+ * they return. It is not shown for a thread that has no messages.
+ */
 const jumpMotion = motion("thread", "jump", "arrive", { dur: 150 });
-/** Its ring when a message arrives while the reader is scrolled up. */
+/**
+ * @motion attention:arrival While the person is scrolled up, Jump to latest pulses once each time a new message
+ * arrives, then is still. Nothing pulses at the bottom, where the new message is already in view.
+ */
 const arrivalMotion = motion("thread", "arrival", "attention");
 /** Thread's fixed words; override them under `thread` in LocaleProvider's `strings`. */
 export const threadStrings = {
@@ -58,6 +78,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 +140,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 +212,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/chat/tool-call.js

@@ -10,8 +10,15 @@ import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/colla
 import { Payload } from "./payload.js";
 import { useStrings } from "../blocks/locale.js";
 import { motion } from "../lib/motion.js";
-/** A call's detail opening, and a group of calls. */
+/**
+ * @motion reveal:open A call's detail opens to its full height when the person opens it, and the chevron turns with
+ * it; closing reverses both. Under reduced motion it snaps open or shut.
+ */
 const openMotion = motion("tool-call", "open", "reveal");
+/**
+ * @motion reveal:group-open A group of calls opens to its full height when the person opens it, and its chevron turns
+ * with it; closing reverses both. Under reduced motion it snaps open or shut.
+ */
 const groupMotion = motion("tool-call", "group-open", "reveal");
 /** ToolCall's fixed words; override them under `toolCall` in LocaleProvider's `strings`. */
 export const toolCallStrings = {

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/accordion.d.ts

@@ -16,8 +16,8 @@ declare function AccordionTrigger(allProps: React.ComponentProps<typeof Accordio
  * The panel. It opens and closes to the height Radix measured, so a change is seen settling rather than snapping;
  * data-motion="none" and the OS's reduced-motion setting make it snap.
  *
- * @motion reveal:open The panel grows to its measured height when opened and shrinks back when closed, in the base
- * duration. Content the app puts in it is not animated.
+ * @motion reveal:open The panel grows to its full height when the person opens it and shrinks back when they close it.
+ * What the app puts inside it doesn't move. Under reduced motion the panel snaps open or shut.
  */
 declare function AccordionContent(allProps: React.ComponentProps<typeof AccordionPrimitive.Content> & RenderProp): React.JSX.Element;
 export { Accordion, AccordionItem, AccordionTrigger, AccordionContent };

package/dist/ui/accordion.js

@@ -32,8 +32,8 @@ function AccordionTrigger(allProps) {
  * The panel. It opens and closes to the height Radix measured, so a change is seen settling rather than snapping;
  * data-motion="none" and the OS's reduced-motion setting make it snap.
  *
- * @motion reveal:open The panel grows to its measured height when opened and shrinks back when closed, in the base
- * duration. Content the app puts in it is not animated.
+ * @motion reveal:open The panel grows to its full height when the person opens it and shrinks back when they close it.
+ * What the app puts inside it doesn't move. Under reduced motion the panel snaps open or shut.
  */
 function AccordionContent(allProps) {
     const { className, children, render, nativeButton: _nativeButton, style, ...props } = allProps;

package/dist/ui/alert.d.ts

@@ -7,7 +7,8 @@ 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 that the server rendered, is simply there; 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,15 @@ 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 that the server rendered, is simply there; 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/button.js

@@ -6,6 +6,10 @@ import { Slot } from "radix-ui";
 import { withRender } from "../lib/render-prop.js";
 import { cn } from "../lib/utils.js";
 import { motion } from "../lib/motion.js";
+/**
+ * @motion press:press The button shrinks a little while it is held down and returns when it is let go. A button that
+ * is locked or disabled never moves, and under reduced motion no button changes size.
+ */
 const pressMotion = motion("button", "press", "press");
 // The accent fills the one primary act, the radius is the theme's
 // --cd-radius-button, and buttons press down slightly on :active.

package/dist/ui/collapsible.js

@@ -4,6 +4,11 @@ import { Collapsible as CollapsiblePrimitive } from "radix-ui";
 import { cn } from "../lib/utils.js";
 import { withRender } from "../lib/render-prop.js";
 import { motion } from "../lib/motion.js";
+/**
+ * @motion reveal:open The content grows to its full height when the person opens it and shrinks when they close it. A
+ * collapsible that is already open when it first appears is shown open at once, and under reduced motion it snaps
+ * open or shut.
+ */
 const openMotion = motion("collapsible", "open", "reveal");
 function Collapsible({ ...props }) {
     return _jsx(CollapsiblePrimitive.Root, { "data-slot": "collapsible", ...props });

package/dist/ui/popover.js

@@ -5,6 +5,10 @@ import { cn } from "../lib/utils.js";
 import { Popover as PopoverPrimitive } from "radix-ui";
 import { withRender } from "../lib/render-prop.js";
 import { motion } from "../lib/motion.js";
+/**
+ * @motion overlay:open The popover fades in and scales up a little from its trigger when the person opens it, and
+ * fades out when it closes. Under reduced motion it is a short fade.
+ */
 const openMotion = motion("popover", "open", "overlay");
 function Popover({ ...props }) {
     return _jsx(PopoverPrimitive.Root, { "data-slot": "popover", ...props });

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