@candor-ui/react 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,40 @@
+import * as React from "react";
+import type { UIMessage } from "ai";
+import type { UseChatHelpers } from "@ai-sdk/react";
+import type { EntityRef, Message } from "../lib/chat.js";
+import { type FromAiSdkOptions } from "./ai-sdk.js";
+export type PendingApproval = {
+    id: string;
+    toolCallId: string;
+    tool: string;
+    input: unknown;
+    reason?: string;
+};
+/**
+ * Wires a `useChat()` result to Candor: messages for <Thread>/<Message>, props
+ * for <Composer>, and the tool calls waiting on a person. Configure useChat
+ * however you like (transport, tools, onFinish); this only reads it.
+ *
+ * Mentions in the composer are sent as structured references in the request
+ * body (`references`), not pasted into the text, so the server gets ids.
+ *
+ *   const chat = useChat({ transport })
+ *   const { messages, composer, approvals, respond } = useCandorChat(chat, { agent })
+ *   <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>
+ */
+export declare function useCandorChat(chat: UseChatHelpers<UIMessage>, options: Omit<FromAiSdkOptions, "chatStatus">): {
+    messages: Message[];
+    approvals: PendingApproval[];
+    respond: (approvalId: string, approved: boolean, reason?: string) => void | PromiseLike<void>;
+    /** The request failed; say so, and offer to try again with `chat.regenerate()`. */
+    error: string | undefined;
+    composer: {
+        value: string;
+        onChange: React.Dispatch<React.SetStateAction<string>>;
+        state: "streaming" | "ready" | "sending";
+        references: EntityRef[];
+        onReferencesChange: React.Dispatch<React.SetStateAction<EntityRef[]>>;
+        onStop: () => Promise<void>;
+        onSubmit: (text: string, refs: EntityRef[]) => void;
+    };
+};

package/dist/adapters/use-candor-chat.js

@@ -0,0 +1,56 @@
+import * as React from "react";
+import { fromAiSdkMessages } from "./ai-sdk.js";
+/**
+ * Wires a `useChat()` result to Candor: messages for <Thread>/<Message>, props
+ * for <Composer>, and the tool calls waiting on a person. Configure useChat
+ * however you like (transport, tools, onFinish); this only reads it.
+ *
+ * Mentions in the composer are sent as structured references in the request
+ * body (`references`), not pasted into the text, so the server gets ids.
+ *
+ *   const chat = useChat({ transport })
+ *   const { messages, composer, approvals, respond } = useCandorChat(chat, { agent })
+ *   <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>
+ */
+export function useCandorChat(chat, options) {
+    const [value, setValue] = React.useState("");
+    const [references, setReferences] = React.useState([]);
+    const { agent, createdAt, toolTitle, summarize } = options;
+    const messages = React.useMemo(() => fromAiSdkMessages(chat.messages, { agent, createdAt, toolTitle, summarize, chatStatus: chat.status }), [chat.messages, chat.status, agent, createdAt, toolTitle, summarize]);
+    const state = chat.status === "submitted" ? "sending" : chat.status === "streaming" ? "streaming" : "ready";
+    const approvals = React.useMemo(() => {
+        const last = chat.messages.findLast((m) => m.role === "assistant");
+        if (!last)
+            return [];
+        return last.parts.flatMap((p) => {
+            const t = p;
+            if (t.state !== "approval-requested" || !t.approval || !t.toolCallId)
+                return [];
+            return [{ id: t.approval.id, toolCallId: t.toolCallId, tool: t.toolName ?? t.type.replace(/^tool-/, ""), input: t.input, reason: t.approval.requestReason }];
+        });
+    }, [chat.messages]);
+    const { sendMessage, stop, addToolApprovalResponse } = chat;
+    const respond = React.useCallback((approvalId, approved, reason) => addToolApprovalResponse({ id: approvalId, approved, reason }), [addToolApprovalResponse]);
+    return {
+        messages,
+        approvals,
+        respond,
+        /** The request failed; say so, and offer to try again with `chat.regenerate()`. */
+        error: chat.error?.message,
+        composer: {
+            value,
+            onChange: setValue,
+            state,
+            references,
+            onReferencesChange: setReferences,
+            onStop: stop,
+            onSubmit: (text, refs) => {
+                if (!text.trim())
+                    return;
+                void sendMessage({ text }, refs.length ? { body: { references: refs } } : undefined);
+                setValue("");
+                setReferences([]);
+            },
+        },
+    };
+}

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

@@ -0,0 +1,48 @@
+import * as React from "react";
+import type { EntityRef } from "../lib/chat.js";
+import { type FromClaudeAgentOptions } from "./claude-agent-sdk.js";
+export type UseClaudeAgentOptions = Omit<FromClaudeAgentOptions, "running"> & {
+    /** Your route that runs the agent with streamClaudeAgent. It receives `{ prompt, references, sessionId, ...body }`. */
+    api: string;
+    /** Your route that calls answerClaudeAgentApproval. It receives `{ id, approved, reason }`. */
+    approveApi: string;
+    /** Extra fields for every request, e.g. which project the agent works on. */
+    body?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    /** Replaces the global fetch, e.g. to add auth or to play a script in tests and demos. */
+    fetch?: typeof fetch;
+};
+/**
+ * Wires a Claude Agent SDK server route to Candor: messages for <Thread>/<Message>,
+ * props for <Composer>, and the tool calls waiting on a person. The same shape as
+ * useCandorChat, so screens work with either.
+ *
+ *   const { messages, composer, approvals, respond } = useClaudeAgent({ api: "/api/agent", approveApi: "/api/agent/approve", agent })
+ *   <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>
+ *
+ * Each message continues the same agent session (the SDK's `resume`). Mentions are
+ * sent as structured `references`, not pasted into the text.
+ */
+export declare function useClaudeAgent(options: UseClaudeAgentOptions): {
+    messages: import("../index.js").MessageData[];
+    approvals: import("./claude-agent-sdk.js").ClaudeApproval[];
+    respond: (approvalId: string, approved: boolean, reason?: string) => Promise<void>;
+    /** What the SDK measured for the session: cost (its estimate), tokens and turns. */
+    usage: import("./claude-agent-sdk.js").ClaudeAgentUsage | undefined;
+    /** A passing problem the agent is handling itself, such as a retried API call. */
+    notice: string | undefined;
+    /** The request failed; say so, and let the person send again. */
+    error: string | undefined;
+    sessionId: string | undefined;
+    /** Forget the conversation and start a new session. */
+    reset: () => void;
+    composer: {
+        value: string;
+        onChange: React.Dispatch<React.SetStateAction<string>>;
+        state: "streaming" | "ready" | "sending";
+        references: EntityRef[];
+        onReferencesChange: React.Dispatch<React.SetStateAction<EntityRef[]>>;
+        onStop: () => void | undefined;
+        onSubmit: (text: string, refs: EntityRef[]) => void;
+    };
+};

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

@@ -0,0 +1,143 @@
+import * as React from "react";
+import { fromClaudeAgentEvents } from "./claude-agent-sdk.js";
+/**
+ * Wires a Claude Agent SDK server route to Candor: messages for <Thread>/<Message>,
+ * props for <Composer>, and the tool calls waiting on a person. The same shape as
+ * useCandorChat, so screens work with either.
+ *
+ *   const { messages, composer, approvals, respond } = useClaudeAgent({ api: "/api/agent", approveApi: "/api/agent/approve", agent })
+ *   <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>
+ *
+ * Each message continues the same agent session (the SDK's `resume`). Mentions are
+ * sent as structured `references`, not pasted into the text.
+ */
+export function useClaudeAgent(options) {
+    const { api, approveApi, body, headers, agent, toolTitle, fetch: fetcher } = options;
+    const [events, setEvents] = React.useState([]);
+    const [running, setRunning] = React.useState(false);
+    const [error, setError] = React.useState();
+    const [value, setValue] = React.useState("");
+    const [references, setReferences] = React.useState([]);
+    const run = React.useRef(null);
+    const state = React.useMemo(() => fromClaudeAgentEvents(events, { agent, toolTitle, running }), [events, agent, toolTitle, running]);
+    const session = React.useRef(undefined);
+    React.useEffect(() => {
+        session.current = state.sessionId;
+    }, [state.sessionId]);
+    // Stop the agent if the component goes away mid-run.
+    React.useEffect(() => () => run.current?.abort(), []);
+    const send = React.useCallback(async (text, refs) => {
+        if (run.current)
+            return;
+        const controller = new AbortController();
+        run.current = controller;
+        setError(undefined);
+        setRunning(true);
+        setEvents((e) => [...e, { type: "candor_user", id: crypto.randomUUID(), text, references: refs.length ? refs : undefined }]);
+        // Streamed text arrives a few characters at a time; apply it once per frame.
+        const pending = { events: [], frame: 0 };
+        const flush = () => {
+            pending.frame = 0;
+            const batch = pending.events.splice(0);
+            if (batch.length)
+                setEvents((e) => [...e, ...batch]);
+        };
+        try {
+            const res = await (fetcher ?? fetch)(api, {
+                method: "POST",
+                headers: { "content-type": "application/json", ...headers },
+                body: JSON.stringify({ ...body, prompt: text, references: refs, sessionId: session.current }),
+                signal: controller.signal,
+            });
+            if (!res.ok || !res.body)
+                throw new Error(`The agent request failed (${res.status}).`);
+            for await (const event of readEvents(res.body)) {
+                pending.events.push(event);
+                pending.frame ||= requestAnimationFrame(flush);
+            }
+        }
+        catch (err) {
+            if (!controller.signal.aborted) {
+                const message = err instanceof Error ? err.message : "The agent request failed.";
+                pending.events.push({ type: "candor_error", message });
+                setError(message);
+            }
+        }
+        finally {
+            cancelAnimationFrame(pending.frame);
+            flush();
+            run.current = null;
+            setRunning(false);
+        }
+    }, [api, body, headers, fetcher]);
+    const respond = React.useCallback(async (approvalId, approved, reason) => {
+        try {
+            const res = await (fetcher ?? fetch)(approveApi, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify({ id: approvalId, approved, reason }) });
+            const ok = res.ok && (await res.json()).ok;
+            if (!ok)
+                setError("Your answer didn’t reach the agent. The request may have ended; try sending the message again.");
+        }
+        catch {
+            setError("Your answer didn’t reach the agent. Check your connection and try again.");
+        }
+    }, [approveApi, headers, fetcher]);
+    const stop = React.useCallback(() => run.current?.abort(), []);
+    const composerState = running ? (state.messages.at(-1)?.author.role === "agent" ? "streaming" : "sending") : "ready";
+    return {
+        messages: state.messages,
+        approvals: state.approvals,
+        respond,
+        /** What the SDK measured for the session: cost (its estimate), tokens and turns. */
+        usage: state.usage,
+        /** A passing problem the agent is handling itself, such as a retried API call. */
+        notice: state.notice,
+        /** The request failed; say so, and let the person send again. */
+        error,
+        sessionId: state.sessionId,
+        /** Forget the conversation and start a new session. */
+        reset: () => {
+            run.current?.abort();
+            setEvents([]);
+            setError(undefined);
+        },
+        composer: {
+            value,
+            onChange: setValue,
+            state: composerState,
+            references,
+            onReferencesChange: setReferences,
+            onStop: stop,
+            onSubmit: (text, refs) => {
+                if (!text.trim() || running)
+                    return;
+                void send(text, refs);
+                setValue("");
+                setReferences([]);
+            },
+        },
+    };
+}
+/** Newline-delimited JSON events from the server; a malformed line is skipped. */
+async function* readEvents(stream) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        buffer += decoder.decode(value, { stream: !done });
+        const lines = buffer.split("\n");
+        buffer = done ? "" : (lines.pop() ?? "");
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                yield JSON.parse(line);
+            }
+            catch {
+                /* a partial or corrupt line; the next one carries on */
+            }
+        }
+        if (done)
+            return;
+    }
+}

package/dist/ag-ui.d.ts

@@ -0,0 +1,2 @@
+export * from "./adapters/ag-ui.js";
+export * from "./adapters/use-ag-ui.js";

package/dist/ag-ui.js

@@ -0,0 +1,2 @@
+export * from "./adapters/ag-ui.js";
+export * from "./adapters/use-ag-ui.js";

package/dist/ai-sdk.d.ts

@@ -0,0 +1,2 @@
+export * from "./adapters/ai-sdk.js";
+export * from "./adapters/use-candor-chat.js";

package/dist/ai-sdk.js

@@ -0,0 +1,2 @@
+export * from "./adapters/ai-sdk.js";
+export * from "./adapters/use-candor-chat.js";

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

@@ -0,0 +1,13 @@
+/**
+ * A value a person copies somewhere else (a callback URL, a scope list). The
+ * whole field is the copy target; it says "Copied" only once the clipboard
+ * took the value.
+ */
+declare function CopyField({ label, value, className, }: {
+    /** What the value is, shown above it. */
+    label: string;
+    /** The text that is shown and copied. */
+    value: string;
+    className?: string;
+}): import("react").JSX.Element;
+export { CopyField };

package/dist/blocks/copy-field.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Check, Copy, X } from "lucide-react";
+import { cn } from "../lib/utils.js";
+import { useCopy } from "../lib/use-copy.js";
+/**
+ * A value a person copies somewhere else (a callback URL, a scope list). The
+ * whole field is the copy target; it says "Copied" only once the clipboard
+ * took the value.
+ */
+function CopyField({ label, value, className, }) {
+    const { state, copy } = useCopy();
+    return (_jsxs("div", { "data-slot": "copy-field", className: cn("flex flex-col gap-1", className), children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: label }), _jsxs("button", { type: "button", onClick: () => copy(value), className: "group/copy flex w-full items-center gap-2 rounded-lg border bg-sunken px-3 py-2 text-left outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/40", children: [_jsx("code", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: value }), _jsx("span", { "aria-live": "polite", className: "inline-flex shrink-0 items-center gap-1 text-xs text-muted-foreground group-hover/copy:text-foreground", children: state === "copied" ? (_jsxs(_Fragment, { children: [_jsx(Check, { className: "size-3 text-success-text" }), " Copied"] })) : state === "failed" ? (_jsxs(_Fragment, { children: [_jsx(X, { className: "size-3 text-destructive-text" }), " Couldn\u2019t copy"] })) : (_jsxs(_Fragment, { children: [_jsx(Copy, { className: "size-3" }), " Copy"] })) })] })] }));
+}
+export { CopyField };

package/dist/blocks/degraded-panel.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Something couldn't be done. Says what went wrong, what is missing because of
+ * it, and offers a retry only when the caller can actually retry (Candor's
+ * DegradedPanel: a degraded state names what's missing, never just looks sad).
+ */
+declare function DegradedPanel({ reason, missing, onRetry, retrying, variant, className, }: {
+    /** What went wrong, in a sentence. */
+    reason: React.ReactNode;
+    /** What the person won't see because of it. */
+    missing?: React.ReactNode;
+    /** Shows a Try again button that calls this. */
+    onRetry?: () => void;
+    /** Shows the retry as in progress. */
+    retrying?: boolean;
+    /** A boxed panel, or one line inside other content. */
+    variant?: "block" | "inline";
+    className?: string;
+}): import("react").JSX.Element;
+export { DegradedPanel };

package/dist/blocks/degraded-panel.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CircleAlert, RotateCw } from "lucide-react";
+import { cn } from "../lib/utils.js";
+import { Button } from "../ui/button.js";
+/**
+ * Something couldn't be done. Says what went wrong, what is missing because of
+ * it, and offers a retry only when the caller can actually retry (Candor's
+ * DegradedPanel: a degraded state names what's missing, never just looks sad).
+ */
+function DegradedPanel({ reason, missing, onRetry, retrying = false, variant = "block", className, }) {
+    return (_jsxs("div", { "data-slot": "degraded-panel", role: "status", className: cn("flex gap-2.5 text-sm", variant === "block" ? "items-start rounded-lg border border-warning/40 bg-warning-weak/60 p-3" : "items-center", className), children: [_jsx(CircleAlert, { "aria-hidden": true, className: "mt-0.5 size-4 shrink-0 text-warning-text" }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "text-foreground", children: reason }), missing && _jsxs("p", { className: "mt-0.5 text-xs text-muted-foreground", children: ["Missing: ", missing] })] }), onRetry && (_jsxs(Button, { size: "xs", variant: "outline", onClick: onRetry, disabled: retrying, "aria-busy": retrying, className: "shrink-0", children: [_jsx(RotateCw, { className: cn(retrying && "animate-spin") }), " ", retrying ? "Retrying" : "Retry"] }))] }));
+}
+export { DegradedPanel };

package/dist/blocks/locked.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+type Lockable = React.ReactElement<{
+    "aria-disabled"?: boolean | "true" | "false";
+    "aria-describedby"?: string;
+    onClick?: React.MouseEventHandler;
+    onKeyDown?: React.KeyboardEventHandler;
+    "data-locked"?: string;
+}>;
+/**
+ * The honest-state rule: a control that cannot be used says why.
+ *
+ * Wrap any single control. With a `reason`, the control stays focusable but is
+ * marked `aria-disabled`, its activation is blocked (click, Enter, Space), and
+ * it is described by the reason — so keyboard and screen-reader users reach
+ * the explanation on the control itself. The reason shows as a tooltip, or
+ * printed under the control with `inline`.
+ */
+declare function Locked({ reason, inline, children, className, }: {
+    /** Why the control can't be used. Without one, the control renders as normal. */
+    reason?: string | null;
+    /** Print the reason under the control instead of in a tooltip. */
+    inline?: boolean;
+    children: Lockable;
+    className?: string;
+}): React.JSX.Element;
+export { Locked };

package/dist/blocks/locked.js

@@ -0,0 +1,36 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { LockKeyhole } from "lucide-react";
+import { cn } from "../lib/utils.js";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../ui/tooltip.js";
+/**
+ * The honest-state rule: a control that cannot be used says why.
+ *
+ * Wrap any single control. With a `reason`, the control stays focusable but is
+ * marked `aria-disabled`, its activation is blocked (click, Enter, Space), and
+ * it is described by the reason — so keyboard and screen-reader users reach
+ * the explanation on the control itself. The reason shows as a tooltip, or
+ * printed under the control with `inline`.
+ */
+function Locked({ reason, inline = false, children, className, }) {
+    const id = React.useId();
+    if (!reason)
+        return children;
+    const block = (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+    };
+    const control = React.cloneElement(children, {
+        "aria-disabled": true,
+        "aria-describedby": id,
+        "data-locked": "",
+        onClick: block,
+        onKeyDown: (e) => {
+            if (e.key === "Enter" || e.key === " ")
+                block(e);
+        },
+    });
+    return (_jsxs("span", { "data-slot": "locked", className: cn("relative inline-flex flex-col items-start gap-1.5", className), children: [inline ? (control) : (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: control }), _jsx(TooltipContent, { children: reason })] })), _jsxs("span", { id: id, className: cn("items-center gap-1 text-xs text-muted-foreground", inline ? "inline-flex" : "sr-only"), children: [_jsx(LockKeyhole, { "aria-hidden": true, className: "size-3" }), reason] })] }));
+}
+export { Locked };

package/dist/blocks/relative-time.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+export declare function formatRelative(date: Date, now?: Date): string;
+/** The current time in milliseconds, updated every 30 seconds; null while rendering on the server. */
+export declare function useNow(): number | null;
+/** "3 minutes ago" / "in 6 days", kept fresh, with the exact time on hover. Shows the date until the clock is known. */
+declare function RelativeTime({ date, bare, className, }: {
+    /** When it happened. Shown as "5 minutes ago", with the exact time on hover. */
+    date: Date | string;
+    /** Drop "ago" and "in", for tight spaces: "5 minutes". */
+    bare?: boolean;
+    className?: string;
+}): React.JSX.Element;
+export { RelativeTime };

package/dist/blocks/relative-time.js

@@ -0,0 +1,62 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+const units = [
+    ["year", 31_536_000],
+    ["month", 2_592_000],
+    ["week", 604_800],
+    ["day", 86_400],
+    ["hour", 3_600],
+    ["minute", 60],
+    ["second", 1],
+];
+const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" });
+export function formatRelative(date, now = new Date()) {
+    const seconds = Math.round((date.getTime() - now.getTime()) / 1000);
+    if (Math.abs(seconds) < 10)
+        return "just now";
+    for (const [unit, size] of units) {
+        if (Math.abs(seconds) >= size || unit === "second")
+            return rtf.format(Math.round(seconds / size), unit);
+    }
+    return "";
+}
+/*
+ * One shared clock for every relative time on the page. During server rendering (and React's hydration pass) there's
+ * no "now" to read, so useNow returns null and components show a fixed date until the browser takes over. That keeps
+ * server and browser output identical, and lets frameworks prerender pages without reading the clock.
+ */
+const listeners = new Set();
+let now = 0;
+let timer;
+function subscribe(onChange) {
+    listeners.add(onChange);
+    if (!timer) {
+        now = Date.now();
+        timer = setInterval(() => {
+            now = Date.now();
+            listeners.forEach((l) => l());
+        }, 30_000);
+    }
+    return () => {
+        listeners.delete(onChange);
+        if (!listeners.size) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+    };
+}
+/** The current time in milliseconds, updated every 30 seconds; null while rendering on the server. */
+export function useNow() {
+    return React.useSyncExternalStore(subscribe, () => now || (now = Date.now()), () => null);
+}
+/** "3 minutes ago" / "in 6 days", kept fresh, with the exact time on hover. Shows the date until the clock is known. */
+function RelativeTime({ date, bare = false, className, }) {
+    const d = typeof date === "string" ? new Date(date) : date;
+    const current = useNow();
+    let text = current === null ? d.toISOString().slice(0, 10) : formatRelative(d, new Date(current));
+    if (bare)
+        text = text.replace(/ ago$/, "").replace(/^in /, "");
+    return (_jsx("time", { dateTime: d.toISOString(), title: current === null ? undefined : d.toLocaleString(), className: className, children: text }));
+}
+export { RelativeTime };

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

@@ -0,0 +1,16 @@
+import { type RunStatus } from "../lib/status.js";
+/**
+ * A small status mark. Running and waiting pulse, since they are the two
+ * states a person may need to watch or act on. The label is always available
+ * to assistive tech; pass `showLabel` to print it too.
+ */
+declare function StatusDot({ status, showLabel, label, className, }: {
+    /** Which status to show; running and waiting pulse. */
+    status: RunStatus;
+    /** Print the status name next to the dot. */
+    showLabel?: boolean;
+    /** Words to use instead of the status name. */
+    label?: string;
+    className?: string;
+}): import("react").JSX.Element;
+export { StatusDot };

package/dist/blocks/status-dot.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/utils.js";
+import { statusLabel } from "../lib/status.js";
+const dotColor = {
+    idle: "bg-faint-foreground/60",
+    queued: "bg-faint-foreground",
+    running: "bg-primary text-accent-text",
+    waiting: "bg-warning text-warning-text",
+    blocked: "bg-transparent ring-[1.5px] ring-inset ring-faint-foreground",
+    succeeded: "bg-success",
+    failed: "bg-destructive",
+    cancelled: "bg-faint-foreground/60",
+    skipped: "bg-faint-foreground/40",
+};
+/**
+ * A small status mark. Running and waiting pulse, since they are the two
+ * states a person may need to watch or act on. The label is always available
+ * to assistive tech; pass `showLabel` to print it too.
+ */
+function StatusDot({ status, showLabel = false, label, className, }) {
+    const text = label ?? statusLabel[status];
+    const live = status === "running" || status === "waiting";
+    return (_jsxs("span", { "data-slot": "status-dot", "data-status": status, className: cn("inline-flex items-center gap-1.5 text-xs text-muted-foreground", className), children: [_jsx("span", { "aria-hidden": true, className: cn("size-2 shrink-0 rounded-full", dotColor[status], live && "animate-pulse-dot") }), showLabel ? _jsx("span", { children: text }) : _jsx("span", { className: "sr-only", children: text })] }));
+}
+export { StatusDot };

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

@@ -0,0 +1,23 @@
+import * as React from "react";
+import { type RunStatus } from "../lib/status.js";
+export type Step = {
+    id: string;
+    title: React.ReactNode;
+    status: RunStatus;
+    detail?: React.ReactNode;
+    meta?: React.ReactNode;
+};
+declare function StepMark({ status, }: {
+    /** The step's status, which picks its mark. */
+    status: RunStatus;
+}): React.JSX.Element;
+/**
+ * An ordered list of steps joined by a rail: an agent's plan, its reasoning,
+ * a run's stages. The rail fills as steps finish.
+ */
+declare function StepList({ steps, className, }: {
+    /** The steps in order, each with a status, and optional detail and meta. */
+    steps: Step[];
+    className?: string;
+}): React.JSX.Element;
+export { StepList, StepMark };

package/dist/blocks/step-list.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Check, CircleSlash, Hand, LoaderCircle, X } from "lucide-react";
+import { cn } from "../lib/utils.js";
+import { statusLabel } from "../lib/status.js";
+function StepMark({ status, }) {
+    const base = "relative z-10 flex size-5 shrink-0 items-center justify-center rounded-full";
+    switch (status) {
+        case "succeeded":
+            return (_jsx("span", { className: cn(base, "bg-success text-on-success"), children: _jsx(Check, { className: "size-3", strokeWidth: 3 }) }));
+        case "failed":
+            return (_jsx("span", { className: cn(base, "bg-destructive text-on-destructive"), children: _jsx(X, { className: "size-3", strokeWidth: 3 }) }));
+        case "running":
+            return (_jsx("span", { className: cn(base, "bg-accent-weak text-accent-text"), children: _jsx(LoaderCircle, { className: "size-3.5 animate-spin", strokeWidth: 2.5 }) }));
+        case "waiting":
+            return (_jsx("span", { className: cn(base, "bg-warning-weak text-warning-text"), children: _jsx(Hand, { className: "size-3", strokeWidth: 2.5 }) }));
+        case "blocked":
+            return (_jsx("span", { className: cn(base, "border-[1.5px] border-dashed border-faint-foreground bg-card") }));
+        case "cancelled":
+        case "skipped":
+            return (_jsx("span", { className: cn(base, "bg-muted text-faint-foreground"), children: _jsx(CircleSlash, { className: "size-3", strokeWidth: 2.5 }) }));
+        default:
+            return (_jsx("span", { className: cn(base, "bg-background"), children: _jsx("span", { className: "size-2 rounded-full border-[1.5px] border-faint-foreground/70" }) }));
+    }
+}
+/**
+ * An ordered list of steps joined by a rail: an agent's plan, its reasoning,
+ * a run's stages. The rail fills as steps finish.
+ */
+function StepList({ steps, className, }) {
+    return (_jsx("ol", { "data-slot": "step-list", className: cn("flex flex-col", className), children: steps.map((step, i) => {
+            const last = i === steps.length - 1;
+            const done = step.status === "succeeded";
+            return (_jsxs("li", { className: "relative flex gap-3 pb-4 last:pb-0 animate-rise-in", style: { animationDelay: `${i * 40}ms` }, children: [!last && (_jsx("span", { "aria-hidden": true, className: cn("absolute top-5 bottom-0 left-[9.5px] w-px transition-colors duration-500", done ? "bg-success/50" : "bg-input") })), _jsx(StepMark, { status: step.status }), _jsxs("div", { className: "min-w-0 flex-1 pt-px", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsxs("p", { className: cn("text-sm font-medium", step.status === "idle" && "text-muted-foreground", (step.status === "skipped" || step.status === "cancelled") && "text-faint-foreground line-through"), children: [step.title, _jsxs("span", { className: "sr-only", children: [" \u2014 ", statusLabel[step.status]] })] }), step.meta && _jsx("span", { className: "shrink-0 text-xs tabular-nums text-faint-foreground", children: step.meta })] }), step.detail && _jsx("div", { className: "mt-1 text-[0.8125rem] text-muted-foreground", children: step.detail })] })] }, step.id));
+        }) }));
+}
+export { StepList, StepMark };

package/dist/blocks/streaming-text.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Text that is still arriving. Shows a caret while `streaming`, and announces
+ * politely so screen readers hear the finished text rather than every token.
+ */
+declare function StreamingText({ text, streaming, className, }: {
+    /** The text so far. */
+    text: string;
+    /** Show a caret while more is arriving; announced once when it stops. */
+    streaming?: boolean;
+    className?: string;
+}): import("react").JSX.Element;
+/** A label that shimmers while an agent is working ("Thinking", "Reading the docs"). */
+declare function ShimmerLabel({ children, className, }: {
+    children: React.ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+export { StreamingText, ShimmerLabel };