@candor-ui/react 1.3.0 → 1.7.0

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

@@ -15,8 +15,8 @@ import { fromAiSdkMessages } from "./ai-sdk.js";
 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 { agent, createdAt, toolTitle, summarize, sourcesFrom } = options;
+    const messages = React.useMemo(() => fromAiSdkMessages(chat.messages, { agent, createdAt, toolTitle, summarize, sourcesFrom, chatStatus: chat.status }), [chat.messages, chat.status, agent, createdAt, toolTitle, summarize, sourcesFrom]);
     const state = chat.status === "submitted" ? "sending" : chat.status === "streaming" ? "streaming" : "ready";
     const approvals = React.useMemo(() => {
         const last = chat.messages.findLast((m) => m.role === "assistant");
@@ -30,7 +30,7 @@ export function useCandorChat(chat, options) {
         });
     }, [chat.messages]);
     const { sendMessage, stop, addToolApprovalResponse } = chat;
-    const respond = React.useCallback((approvalId, approved, reason) => addToolApprovalResponse({ id: approvalId, approved, reason }), [addToolApprovalResponse]);
+    const respond = React.useCallback((approvalId, approved, reason) => addToolApprovalResponse({ id: approvalId, approved, ...(reason !== undefined && { reason }) }), [addToolApprovalResponse]);
     return {
         messages,
         approvals,

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

@@ -1,16 +1,37 @@
 import * as React from "react";
 import type { EntityRef } from "../lib/chat.js";
-import { type FromClaudeAgentOptions } from "./claude-agent-sdk.js";
+import { type AgentEvent, type ClaudeApprovalAnswer, type ClaudePermissionMode, 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 }`. */
+    /** Your route that runs the agent with streamClaudeAgent. It receives `{ prompt, promptId, references, sessionId, ...body }`. */
     api: string;
-    /** Your route that calls answerClaudeAgentApproval. It receives `{ id, approved, reason }`. */
-    approveApi: string;
+    /**
+     * Your route that records an answer (answerClaudeApproval). It receives `{ id, approved, reason, updatedInput,
+     * answers, alwaysAllow }` and returns `{ ok }`. Not needed with `onRespond`.
+     */
+    approveApi?: string | undefined;
+    /**
+     * Answer through your own route instead, e.g. one that signals the workflow running the agent. Resolve true once
+     * the answer is recorded, false if it wasn't (the request had ended).
+     */
+    onRespond?: ((approvalId: string, answer: ClaudeApprovalAnswer) => Promise<boolean>) | undefined;
+    /** Events you kept from earlier (onEvent, a run store): the conversation is folded from them, as it was. */
+    initialEvents?: AgentEvent[] | undefined;
+    /**
+     * Where to re-attach to a run after a reload: `(runId, from) => \`/api/agent/${runId}?from=${from}\``, a route that
+     * returns attachClaudeAgentRun. With `runId`, the hook re-attaches when it mounts.
+     */
+    attachUrl?: ((runId: string, from: number) => string) | undefined;
+    /** A run to re-attach to when the hook mounts, e.g. the one you saved from `runId` before the reload. */
+    runId?: string | undefined;
+    /** Your route that calls stopClaudeAgentRun with `{ runId }`. Needed to stop a run that keeps going without the browser (`detach`). */
+    stopApi?: string | undefined;
+    /** Your route that calls setClaudeAgentPermissionMode with `{ runId, mode }`. Enables `setPermissionMode`. */
+    modeApi?: string | undefined;
     /** Extra fields for every request, e.g. which project the agent works on. */
-    body?: Record<string, unknown>;
-    headers?: Record<string, string>;
+    body?: Record<string, unknown> | undefined;
+    headers?: Record<string, string> | undefined;
     /** Replaces the global fetch, e.g. to add auth or to play a script in tests and demos. */
-    fetch?: typeof fetch;
+    fetch?: typeof fetch | undefined;
 };
 /**
  * Wires a Claude Agent SDK server route to Candor: messages for <Thread>/<Message>,
@@ -26,7 +47,7 @@ export type UseClaudeAgentOptions = Omit<FromClaudeAgentOptions, "running"> & {
 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>;
+    respond: (approvalId: string, approved: boolean, reason?: string, more?: Omit<ClaudeApprovalAnswer, "approved" | "reason">) => Promise<boolean>;
     /** 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. */
@@ -34,6 +55,14 @@ export declare function useClaudeAgent(options: UseClaudeAgentOptions): {
     /** The request failed; say so, and let the person send again. */
     error: string | undefined;
     sessionId: string | undefined;
+    /** Every event so far, to keep for replay (`initialEvents`). */
+    events: AgentEvent[];
+    /** The current or last run's id (from `x-candor-run-id`): save it to re-attach after a reload. */
+    runId: string | undefined;
+    attach: (id: string, from?: number) => Promise<void>;
+    /** The permission mode last reported by the SDK or set through `setPermissionMode`. */
+    permissionMode: ClaudePermissionMode | undefined;
+    setPermissionMode: (mode: ClaudePermissionMode) => Promise<boolean>;
     /** Forget the conversation and start a new session. */
     reset: () => void;
     composer: {
@@ -42,7 +71,7 @@ export declare function useClaudeAgent(options: UseClaudeAgentOptions): {
         state: "streaming" | "ready" | "sending";
         references: EntityRef[];
         onReferencesChange: React.Dispatch<React.SetStateAction<EntityRef[]>>;
-        onStop: () => void | undefined;
+        onStop: () => void;
         onSubmit: (text: string, refs: EntityRef[]) => void;
     };
 };

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

@@ -12,45 +12,54 @@ import { fromClaudeAgentEvents } from "./claude-agent-sdk.js";
  * 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 { api, approveApi, onRespond, body, headers, agent, toolTitle, sourcesFrom, fetch: fetcher, attachUrl, stopApi, modeApi } = options;
+    const [events, setEvents] = React.useState(() => options.initialEvents ?? []);
+    const [runId, setRunId] = React.useState(options.runId);
     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 state = React.useMemo(() => fromClaudeAgentEvents(events, { agent, toolTitle, sourcesFrom, running }), [events, agent, toolTitle, sourcesFrom, 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) => {
+    /** Reads one response's events into state, a frame at a time. */
+    const stream = React.useCallback(async (open, before, replace = false) => {
         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 }]);
+        if (before)
+            setEvents((e) => [...e, before]);
         // Streamed text arrives a few characters at a time; apply it once per frame.
-        const pending = { events: [], frame: 0 };
+        const pending = { events: [], frame: 0, first: replace };
         const flush = () => {
             pending.frame = 0;
             const batch = pending.events.splice(0);
-            if (batch.length)
-                setEvents((e) => [...e, ...batch]);
+            if (!batch.length)
+                return;
+            const first = pending.first ? batch[0] : undefined;
+            pending.first = false;
+            setEvents((e) => {
+                // Re-attaching to a run whose events are already here (from initialEvents): the stored run replaces them,
+                // found by the person's message that starts it, rather than being added a second time.
+                const at = first?.type === "candor_user" ? e.findIndex((x) => x.type === "candor_user" && x.id === first.id) : -1;
+                return [...(at >= 0 ? e.slice(0, at) : 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,
-            });
+            const res = await open(controller.signal);
             if (!res.ok || !res.body)
                 throw new Error(`The agent request failed (${res.status}).`);
+            const id = res.headers.get("x-candor-run-id");
+            if (id)
+                setRunId(id);
             for await (const event of readEvents(res.body)) {
                 pending.events.push(event);
                 pending.frame ||= requestAnimationFrame(flush);
@@ -69,19 +78,77 @@ export function useClaudeAgent(options) {
             run.current = null;
             setRunning(false);
         }
-    }, [api, body, headers, fetcher]);
-    const respond = React.useCallback(async (approvalId, approved, reason) => {
+    }, []);
+    const send = React.useCallback((text, refs) => {
+        const promptId = crypto.randomUUID();
+        return stream((signal) => (fetcher ?? fetch)(api, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...headers },
+            body: JSON.stringify({ ...body, prompt: text, promptId, references: refs, sessionId: session.current }),
+            signal,
+        }), { type: "candor_user", id: promptId, text, references: refs.length ? refs : undefined });
+    }, [api, body, headers, fetcher, stream]);
+    /**
+     * Re-attach to a run after a reload: its events from `from` on (default 0, the whole run), then live until it
+     * ends. Needs `attachUrl`. From 0, when the run store recorded the person's message (the server's `prompt`, with
+     * this hook's `promptId`), the run's events replace any copy of them already in `initialEvents`.
+     */
+    const attach = React.useCallback((id, from = 0) => {
+        if (!attachUrl)
+            return Promise.resolve();
+        setRunId(id);
+        return stream((signal) => (fetcher ?? fetch)(attachUrl(id, from), { ...(headers && { headers }), signal }), undefined, from === 0);
+    }, [attachUrl, fetcher, headers, stream]);
+    // Re-attach to the run named in options once, when the hook mounts.
+    const attachOnMount = React.useRef(options.runId);
+    React.useEffect(() => {
+        const id = attachOnMount.current;
+        attachOnMount.current = undefined;
+        if (id)
+            void attach(id);
+    }, [attach]);
+    const post = React.useCallback(async (url, payload) => {
+        const res = await (fetcher ?? fetch)(url, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(payload) });
+        return res.ok && !!(await res.json()).ok;
+    }, [fetcher, headers]);
+    /**
+     * Answer a waiting request. `more` carries an edited input (`updatedInput`), answers to the agent's questions
+     * (`answers`) and the "always allow" rules the person picked (`alwaysAllow`, indexes into its `suggestions`).
+     */
+    const respond = React.useCallback(async (approvalId, approved, reason, more) => {
+        const answer = { approved, ...(reason !== undefined && { reason }), ...more };
         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;
+            const ok = onRespond ? await onRespond(approvalId, answer) : approveApi ? await post(approveApi, { id: approvalId, ...answer }) : false;
             if (!ok)
                 setError("Your answer didn’t reach the agent. The request may have ended; try sending the message again.");
+            return ok;
         }
         catch {
             setError("Your answer didn’t reach the agent. Check your connection and try again.");
+            return false;
+        }
+    }, [approveApi, onRespond, post]);
+    const stop = React.useCallback(() => {
+        // A detached run carries on without this browser, so it's stopped on the server too.
+        if (stopApi && runId)
+            void post(stopApi, { runId }).catch(() => { });
+        run.current?.abort();
+    }, [stopApi, runId, post]);
+    /** Change the run's permission mode. Resolves false when there's no run, no `modeApi`, or the server refused. */
+    const setPermissionMode = React.useCallback(async (mode) => {
+        if (!modeApi || !runId || !running)
+            return false;
+        try {
+            const ok = await post(modeApi, { runId, mode });
+            if (!ok)
+                setError("The permission mode didn’t change.");
+            return ok;
+        }
+        catch {
+            setError("The permission mode didn’t change. Check your connection and try again.");
+            return false;
         }
-    }, [approveApi, headers, fetcher]);
-    const stop = React.useCallback(() => run.current?.abort(), []);
+    }, [modeApi, runId, running, post]);
     const composerState = running ? (state.messages.at(-1)?.author.role === "agent" ? "streaming" : "sending") : "ready";
     return {
         messages: state.messages,
@@ -94,10 +161,19 @@ export function useClaudeAgent(options) {
         /** The request failed; say so, and let the person send again. */
         error,
         sessionId: state.sessionId,
+        /** Every event so far, to keep for replay (`initialEvents`). */
+        events,
+        /** The current or last run's id (from `x-candor-run-id`): save it to re-attach after a reload. */
+        runId,
+        attach,
+        /** The permission mode last reported by the SDK or set through `setPermissionMode`. */
+        permissionMode: state.permissionMode,
+        setPermissionMode,
         /** Forget the conversation and start a new session. */
         reset: () => {
             run.current?.abort();
             setEvents([]);
+            setRunId(undefined);
             setError(undefined);
         },
         composer: {

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

@@ -14,6 +14,6 @@ declare function CopyField({ label, value, className, }: {
     label: string;
     /** The text that is shown and copied. */
     value: string;
-    className?: string;
+    className?: string | undefined;
 }): import("react").JSX.Element;
 export { CopyField };

package/dist/blocks/copy-field.js

@@ -18,6 +18,6 @@ export const copyFieldStrings = {
 function CopyField({ label, value, className, }) {
     const { state, copy } = useCopy();
     const t = useStrings("copyField", copyFieldStrings);
-    return (_jsxs("div", { "data-slot": "copy-field", className: cn("flex flex-col gap-1", className), children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: label }), _jsxs("button", { type: "button", onClick: () => copy(value), className: "group/copy flex w-full items-center gap-2 rounded-lg border bg-sunken px-3 py-2 text-start outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/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" }), " ", t("copied")] })) : state === "failed" ? (_jsxs(_Fragment, { children: [_jsx(X, { className: "size-3 text-destructive-text" }), " ", t("failed")] })) : (_jsxs(_Fragment, { children: [_jsx(Copy, { className: "size-3" }), " ", t("copy")] })) })] })] }));
+    return (_jsxs("div", { "data-slot": "copy-field", className: cn("flex flex-col gap-1", className), children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground", children: label }), _jsxs("button", { type: "button", onClick: () => copy(value), className: "group/copy flex w-full items-center gap-2 rounded-lg border bg-sunken px-3 py-2 text-start outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/80", children: [_jsx("code", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: value }), _jsx("span", { "aria-live": "polite", className: "inline-flex shrink-0 items-center gap-1 text-xs text-muted-foreground group-hover/copy:text-foreground", children: state === "copied" ? (_jsxs(_Fragment, { children: [_jsx(Check, { className: "size-3 text-success-text" }), " ", t("copied")] })) : state === "failed" ? (_jsxs(_Fragment, { children: [_jsx(X, { className: "size-3 text-destructive-text" }), " ", t("failed")] })) : (_jsxs(_Fragment, { children: [_jsx(Copy, { className: "size-3" }), " ", t("copy")] })) })] })] }));
 }
 export { CopyField };

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

@@ -13,13 +13,13 @@ declare function DegradedPanel({ reason, missing, onRetry, retrying, variant, cl
     /** What went wrong, in a sentence. */
     reason: React.ReactNode;
     /** What the person won't see because of it. */
-    missing?: React.ReactNode;
+    missing?: React.ReactNode | undefined;
     /** Shows a Try again button that calls this. */
-    onRetry?: () => void;
+    onRetry?: (() => void) | undefined;
     /** Shows the retry as in progress. */
-    retrying?: boolean;
+    retrying?: boolean | undefined;
     /** A boxed panel, or one line inside other content. */
-    variant?: "block" | "inline";
-    className?: string;
+    variant?: "block" | "inline" | undefined;
+    className?: string | undefined;
 }): import("react").JSX.Element;
 export { DegradedPanel };

package/dist/blocks/locale.d.ts

@@ -27,19 +27,19 @@ export type TextDirection = "ltr" | "rtl";
 export declare function directionOf(locale: string | undefined): TextDirection;
 declare function LocaleProvider({ locale, dir, timeZone, strings, children, }: {
     /** A BCP 47 tag such as "en-GB", "fr" or "ar-EG", for dates, numbers and plural forms. Left out, the browser's own is used once the page has hydrated. */
-    locale?: string;
+    locale?: string | undefined;
     /** Text direction. Left out, it follows the locale: "rtl" for Arabic, Hebrew, Persian, Urdu and the like. Set `dir` on `<html>` too, so the page's own layout flips with Candor's. */
-    dir?: TextDirection;
+    dir?: TextDirection | undefined;
     /** An IANA time zone such as "Europe/Paris". With `locale`, server and browser format dates the same way, so absolute times render on the server too. */
-    timeZone?: string;
+    timeZone?: string | undefined;
     /** Overrides by component name, e.g. `{ thread: { jumpToLatest: "…" } }`; any left out stay English. Nested providers merge. */
-    strings?: StringOverrides;
+    strings?: StringOverrides | undefined;
     children: React.ReactNode;
 }): React.JSX.Element;
 /** The locale, time zone and text direction in effect. */
 declare function useLocale(): {
-    locale?: string;
-    timeZone?: string;
+    locale?: string | undefined;
+    timeZone?: string | undefined;
     dir: TextDirection;
 };
 /**

package/dist/blocks/locked.d.ts

@@ -1,10 +1,10 @@
 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;
+    "aria-disabled"?: boolean | "true" | "false" | undefined;
+    "aria-describedby"?: string | undefined;
+    onClick?: React.MouseEventHandler | undefined;
+    onKeyDown?: React.KeyboardEventHandler | undefined;
+    "data-locked"?: string | undefined;
 }>;
 /**
  * The honest-state rule: a control that cannot be used says why.
@@ -17,10 +17,10 @@ type Lockable = React.ReactElement<{
  */
 declare function Locked({ reason, inline, children, className, }: {
     /** Why the control can't be used. Without one, the control renders as normal. */
-    reason?: string | null;
+    reason?: string | null | undefined;
     /** Print the reason under the control instead of in a tooltip. */
-    inline?: boolean;
+    inline?: boolean | undefined;
     children: Lockable;
-    className?: string;
+    className?: string | undefined;
 }): React.JSX.Element;
 export { Locked };

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

@@ -9,9 +9,9 @@ export declare const relativeTimeStrings: {
  * spaces: "5 minutes".
  */
 export declare function formatRelative(date: Date, now?: Date, { locale, justNow, bare }?: {
-    locale?: string;
-    justNow?: string;
-    bare?: boolean;
+    locale?: string | undefined;
+    justNow?: string | undefined;
+    bare?: boolean | undefined;
 }): string;
 /** The current time in milliseconds, updated every 30 seconds; null while rendering on the server. */
 export declare function useNow(): number | null;
@@ -23,9 +23,9 @@ declare function RelativeTime({ date, bare, format, 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;
+    bare?: boolean | undefined;
     /** "relative" (the default), or an absolute "date", "datetime" or "time" in the locale. */
-    format?: "relative" | DateStyle;
-    className?: string;
+    format?: "relative" | DateStyle | undefined;
+    className?: string | undefined;
 }): React.JSX.Element;
 export { RelativeTime };

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

@@ -8,9 +8,9 @@ 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;
+    showLabel?: boolean | undefined;
     /** Words to use instead of the status name. */
-    label?: string;
-    className?: string;
+    label?: string | undefined;
+    className?: string | undefined;
 }): import("react").JSX.Element;
 export { StatusDot };

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

@@ -4,8 +4,8 @@ export type Step = {
     id: string;
     title: React.ReactNode;
     status: RunStatus;
-    detail?: React.ReactNode;
-    meta?: React.ReactNode;
+    detail?: React.ReactNode | undefined;
+    meta?: React.ReactNode | undefined;
 };
 declare function StepMark({ status, }: {
     /** The step's status, which picks its mark. */
@@ -18,6 +18,6 @@ declare function StepMark({ status, }: {
 declare function StepList({ steps, className, }: {
     /** The steps in order, each with a status, and optional detail and meta. */
     steps: Step[];
-    className?: string;
+    className?: string | undefined;
 }): React.JSX.Element;
 export { StepList, StepMark };

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

@@ -6,12 +6,12 @@ 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;
+    streaming?: boolean | undefined;
+    className?: string | undefined;
 }): 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;
+    className?: string | undefined;
 }): import("react").JSX.Element;
 export { StreamingText, ShimmerLabel };

package/dist/chat/agent-avatar.d.ts

@@ -34,15 +34,15 @@ declare function AgentAvatar({ agent, size, className, }: {
     /** Who the agent is: id, display name and role. */
     agent: AgentIdentity;
     /** md for message headers, sm for lists and chips. */
-    size?: "sm" | "md";
-    className?: string;
+    size?: "sm" | "md" | undefined;
+    className?: string | undefined;
 }): React.JSX.Element;
 /** Avatar plus name, with the role spelled out for screen readers. */
 declare function AgentBadge({ agent, size, className, }: {
     /** Who the agent is: id, display name and role. */
     agent: AgentIdentity;
     /** md for message headers, sm for lists and chips. */
-    size?: "sm" | "md";
-    className?: string;
+    size?: "sm" | "md" | undefined;
+    className?: string | undefined;
 }): React.JSX.Element;
 export { AgentAvatar, AgentBadge, AgentRolesProvider, useAgentRoles };

package/dist/chat/ai-disclosure.d.ts

@@ -0,0 +1,37 @@
+import type { AgentIdentity } from "../lib/chat.js";
+/** AiDisclosure's fixed words; override them under `aiDisclosure` in LocaleProvider's `strings`. */
+export declare const aiDisclosureStrings: {
+    /** The line in the thread when the app names the agent. */
+    line: string;
+    /** The line in the thread when no name is given. */
+    lineUnnamed: string;
+    /** The badge's visible text. */
+    badge: string;
+    /** The badge's accessible name when the app names the agent. */
+    badgeLabel: string;
+    /** The badge's accessible name when no name is given. */
+    badgeLabelUnnamed: string;
+    /** The heading of the badge's explanation. */
+    about: string;
+    aboutUnnamed: string;
+    learnMore: string;
+};
+/**
+ * A plain notice that the person is interacting with an AI system: a first line in the thread (`variant="line"`) or
+ * a compact "AI" badge for a thread header (`variant="badge"`) that opens to the app's own explanation. It helps an
+ * app tell people they're talking to an AI, as transparency rules such as Article 50(1) of the EU AI Act ask; whether
+ * a given placement meets those rules, and what else applies, stays the deployer's call. The agent's name and any
+ * details come from the app, never from model text. It's static: read in place, never announced as a live update.
+ */
+declare function AiDisclosure({ agent, variant, details, onLearnMore, className, }: {
+    /** The agent, named by the app: an AgentIdentity or a plain name. Left out, the notice says "an AI system". Never model text. */
+    agent?: AgentIdentity | string | undefined;
+    /** "line" (the default) for a first line in the thread; "badge" for a compact mark in a header, e.g. ThreadHeader's. Place each where it fits. */
+    variant?: "line" | "badge" | undefined;
+    /** The app's own plain text about the system: who operates it, what data it uses, how to reach a person. Shown under the line, or in the badge's explanation. */
+    details?: string | undefined;
+    /** Opens the app's own page or dialog about its AI use. A callback, never a URL from the model. Shows a "Learn more" button. */
+    onLearnMore?: (() => void) | undefined;
+    className?: string | undefined;
+}): import("react").JSX.Element;
+export { AiDisclosure };

package/dist/chat/ai-disclosure.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Bot } from "lucide-react";
+import { cn } from "../lib/utils.js";
+import { useStrings } from "../blocks/locale.js";
+import { Button } from "../ui/button.js";
+import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover.js";
+/** AiDisclosure's fixed words; override them under `aiDisclosure` in LocaleProvider's `strings`. */
+export const aiDisclosureStrings = {
+    /** The line in the thread when the app names the agent. */
+    line: "{name} is an AI system, not a person.",
+    /** The line in the thread when no name is given. */
+    lineUnnamed: "You're interacting with an AI system, not a person.",
+    /** The badge's visible text. */
+    badge: "AI",
+    /** The badge's accessible name when the app names the agent. */
+    badgeLabel: "{name} is an AI system",
+    /** The badge's accessible name when no name is given. */
+    badgeLabelUnnamed: "AI system",
+    /** The heading of the badge's explanation. */
+    about: "About {name}",
+    aboutUnnamed: "About this AI system",
+    learnMore: "Learn more",
+};
+/**
+ * A plain notice that the person is interacting with an AI system: a first line in the thread (`variant="line"`) or
+ * a compact "AI" badge for a thread header (`variant="badge"`) that opens to the app's own explanation. It helps an
+ * app tell people they're talking to an AI, as transparency rules such as Article 50(1) of the EU AI Act ask; whether
+ * a given placement meets those rules, and what else applies, stays the deployer's call. The agent's name and any
+ * details come from the app, never from model text. It's static: read in place, never announced as a live update.
+ */
+function AiDisclosure({ agent, variant = "line", details, onLearnMore, className, }) {
+    const t = useStrings("aiDisclosure", aiDisclosureStrings);
+    const name = typeof agent === "string" ? agent : agent?.name;
+    const sentence = name ? t("line", { name }) : t("lineUnnamed");
+    const learnMore = onLearnMore && (_jsx(Button, { type: "button", variant: "link", size: "xs", className: "h-6 px-0 has-[>svg]:px-0", onClick: onLearnMore, children: t("learnMore") }));
+    if (variant === "badge") {
+        const label = name ? t("badgeLabel", { name }) : t("badgeLabelUnnamed");
+        const mark = (_jsxs(_Fragment, { children: [_jsx(Bot, { "aria-hidden": true, className: "size-3 shrink-0" }), _jsx("span", { "aria-hidden": true, children: t("badge") })] }));
+        const badgeClass = "inline-flex min-h-6 min-w-6 items-center justify-center gap-1 rounded-full border px-2 text-2xs font-medium text-muted-foreground";
+        // Nothing more to say: a static mark with a name, not a button that opens nothing.
+        if (!details && !onLearnMore)
+            return (_jsx("span", { "data-slot": "ai-disclosure", "data-variant": "badge", role: "img", "aria-label": label, className: cn(badgeClass, className), children: mark }));
+        return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { "data-slot": "ai-disclosure", "data-variant": "badge", "aria-label": label, className: cn(badgeClass, "outline-none hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80", className), children: mark }), _jsxs(PopoverContent, { align: "start", className: "flex w-72 flex-col gap-1.5 p-3 text-xs", children: [_jsx("p", { className: "text-sm font-medium", children: name ? t("about", { name }) : t("aboutUnnamed") }), _jsx("p", { children: sentence }), details && _jsx("p", { className: "text-muted-foreground", children: details }), learnMore && _jsx("div", { children: learnMore })] })] }));
+    }
+    return (_jsxs("div", { "data-slot": "ai-disclosure", "data-variant": "line", role: "note", className: cn("flex items-start justify-center gap-1.5 py-1 text-center text-xs text-muted-foreground", className), children: [_jsx(Bot, { "aria-hidden": true, className: "mt-0.5 size-3 shrink-0" }), _jsxs("p", { className: "flex flex-wrap items-center justify-center gap-x-1.5", children: [_jsx("span", { children: sentence }), details && _jsx("span", { children: details }), learnMore] })] }));
+}
+export { AiDisclosure };

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

@@ -27,8 +27,8 @@ declare function AttachmentChip({ attachment: a, onRemove, className, }: {
     /** The file, with progress (0–1) while uploading or an error if it failed. */
     attachment: Attachment;
     /** Shows a remove button. */
-    onRemove?: (id: string) => void;
-    className?: string;
+    onRemove?: ((id: string) => void) | undefined;
+    className?: string | 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
@@ -39,15 +39,15 @@ declare function AttachmentPreview({ attachment: a, onOpen, className, }: {
     /** The file. `previewUrl` must be one your app serves (a thumbnail, a blob: URL); it's shown only for images. */
     attachment: Attachment;
     /** Makes the tile a button that opens the file. */
-    onOpen?: (attachment: Attachment) => void;
-    className?: string;
+    onOpen?: ((attachment: Attachment) => void) | undefined;
+    className?: string | undefined;
 }): React.JSX.Element;
 /** Several sent files, as a wrapping row of tiles, announced as a list. */
 declare function AttachmentList({ attachments, onOpen, className, }: {
     /** The files. */
     attachments: Attachment[];
     /** Makes each tile a button that opens its file. */
-    onOpen?: (attachment: Attachment) => void;
-    className?: string;
+    onOpen?: ((attachment: Attachment) => void) | undefined;
+    className?: string | undefined;
 }): React.JSX.Element;
 export { AttachmentChip, AttachmentPreview, AttachmentList };

package/dist/chat/attachment-preview.js

@@ -58,7 +58,7 @@ function AttachmentChip({ attachment: a, onRemove, className, }) {
     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: "rounded-sm p-0.5 text-faint-foreground hover:bg-accent hover:text-foreground", children: _jsx(X, { className: "size-3" }) })), a.progress !== undefined && !a.error && _jsx("span", { "aria-hidden": true, className: "absolute bottom-0 start-0 h-0.5 bg-primary transition-[width] duration-300", style: { width: `${a.progress * 100}%` } })] }));
+    return (_jsxs("span", { "data-slot": "attachment-chip", className: cn("relative inline-flex max-w-56 items-center gap-1.5 overflow-hidden rounded-md border bg-card py-1 pe-1 ps-2 text-xs", a.error && "border-destructive/50", className), children: [thumb ? _jsx("img", { src: thumb, alt: "", className: "size-4 shrink-0 rounded-xs object-cover" }) : _jsx(Paperclip, { "aria-hidden": true, className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: a.name }), _jsx("span", { className: cn("shrink-0 tabular-nums", a.error ? "text-destructive-text" : "text-faint-foreground"), children: a.error ? a.error : a.progress !== undefined ? fmt.number(Math.round(a.progress * 100) / 100, { style: "percent" }) : formatFileSize(a.size, fmt.number, t) }), onRemove && (_jsx("button", { type: "button", "aria-label": t("remove", { name: a.name }), onClick: () => onRemove(a.id), className: "relative after:absolute after:-inset-1 rounded-sm p-0.5 text-faint-foreground hover:bg-accent hover:text-foreground", children: _jsx(X, { className: "size-3" }) })), a.progress !== undefined && !a.error && _jsx("span", { "aria-hidden": true, className: "absolute bottom-0 start-0 h-0.5 bg-primary transition-[width] duration-300", style: { width: `${a.progress * 100}%` } })] }));
 }
 /**
  * A sent file, as a tile in a message: an image preview when the app supplied one, else an icon for its type, with
@@ -72,7 +72,7 @@ function AttachmentPreview({ attachment: a, onOpen, className, }) {
     const size = formatFileSize(a.size, fmt.number, t);
     const body = (_jsxs(_Fragment, { children: [thumb ? (_jsx("img", { src: thumb, alt: "", className: "h-24 w-full rounded-md bg-muted object-cover" })) : (_jsx("span", { "aria-hidden": true, className: "flex size-8 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground", children: _jsx(FileGlyph, { attachment: a }) })), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-sm", children: a.name }), (size || a.error) && _jsx("span", { className: cn("block text-xs tabular-nums", a.error ? "text-destructive-text" : "text-faint-foreground"), children: a.error ?? size })] })] }));
     const frame = cn("flex w-56 max-w-full gap-2.5 rounded-lg border bg-card p-2 text-start", thumb ? "flex-col" : "items-center", className);
-    return onOpen ? (_jsx("button", { type: "button", "data-slot": "attachment-preview", "aria-label": t("open", { name: a.name }), onClick: () => onOpen(a), className: cn(frame, "outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/40"), children: body })) : (_jsx("div", { "data-slot": "attachment-preview", className: frame, children: body }));
+    return onOpen ? (_jsx("button", { type: "button", "data-slot": "attachment-preview", "aria-label": t("open", { name: a.name }), onClick: () => onOpen(a), className: cn(frame, "outline-none transition-colors duration-150 hover:border-border-strong focus-visible:ring-[3px] focus-visible:ring-ring/80"), children: body })) : (_jsx("div", { "data-slot": "attachment-preview", className: frame, children: body }));
 }
 /** Several sent files, as a wrapping row of tiles, announced as a list. */
 function AttachmentList({ attachments, onOpen, className, }) {

package/dist/chat/card-registry.js

@@ -32,7 +32,7 @@ class CardBoundary extends React.Component {
 }
 function Summary({ text, }) {
     const t = useStrings("cardRegistry", cardRegistryStrings);
-    return (_jsxs(Collapsible, { className: "group/summary", children: [_jsxs(CollapsibleTrigger, { className: "inline-flex items-center gap-1 text-xs text-muted-foreground outline-none hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/40 rounded-sm", children: [_jsx(ChevronRight, { "aria-hidden": true, className: "rtl:-scale-x-100 size-3 transition-transform group-data-[state=open]/summary:[transform:rotate(90deg)]" }), " ", t("showAsText")] }), _jsx(CollapsibleContent, { children: _jsx("p", { className: "mt-1.5 rounded-md bg-sunken px-3 py-2 text-sm whitespace-pre-wrap", children: text }) })] }));
+    return (_jsxs(Collapsible, { className: "group/summary", children: [_jsxs(CollapsibleTrigger, { className: "relative after:absolute after:inset-x-0 after:-inset-y-1 inline-flex items-center gap-1 text-xs text-muted-foreground outline-none hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/80 rounded-sm", children: [_jsx(ChevronRight, { "aria-hidden": true, className: "rtl:-scale-x-100 size-3 transition-transform group-data-[state=open]/summary:[transform:rotate(90deg)]" }), " ", t("showAsText")] }), _jsx(CollapsibleContent, { children: _jsx("p", { className: "mt-1.5 rounded-md bg-sunken px-3 py-2 text-sm whitespace-pre-wrap", children: text }) })] }));
 }
 /**
  * Renders one card from the registry. Three honest fallbacks, each with the