@candor-ui/react 0.0.0-stage → 1.0.1

package/dist/blocks/streaming-text.js

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

package/dist/blocks/surface.d.ts

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

package/dist/blocks/surface.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/utils.js";
+// Candor's cards are borderless grey grounds with large radii; in an app they
+// also need a bordered and a floating form. One component carries all three so
+// no screen hand-rolls its own card.
+const surfaceVariants = cva("relative text-card-foreground", {
+    variants: {
+        tone: {
+            plain: "bg-card border",
+            muted: "bg-muted",
+            subtle: "bg-sunken border",
+            raised: "bg-card border shadow-raised",
+            floating: "bg-popover border shadow-float",
+            accent: "bg-accent-weak text-foreground",
+        },
+        radius: {
+            md: "rounded-lg",
+            lg: "rounded-xl",
+            xl: "rounded-2xl",
+        },
+        pad: {
+            none: "",
+            sm: "p-3",
+            md: "p-4",
+            lg: "p-6",
+        },
+    },
+    defaultVariants: { tone: "plain", radius: "xl", pad: "md" },
+});
+function Surface({ className, tone, radius, pad, ...props }) {
+    return _jsx("div", { "data-slot": "surface", className: cn(surfaceVariants({ tone, radius, pad }), className), ...props });
+}
+export { Surface, surfaceVariants };

package/dist/blocks/terms.d.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+/**
+ * The app's words for its own concepts, so components read like the product:
+ * one app says "org", another "project" or "workspace".
+ */
+export type Terms = {
+    /** One place agents act in. */
+    environment: string;
+    environments: string;
+    /** The paying customer that owns the environments. */
+    account: string;
+    /** The product's own name, for labels like "In the app" and "What the app will read". */
+    product: string;
+};
+declare function TermsProvider({ terms, children, }: {
+    /** The words to use; any left out fall back to the ones above. */
+    terms: Partial<Terms>;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** The app's terms; defaults are "environment" and "account". */
+declare function useTerms(): Terms;
+/** "Environment" from "environment": for headings and the start of a sentence. */
+declare const capitalise: (s: string) => string;
+export { TermsProvider, useTerms, capitalise };

package/dist/blocks/terms.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+const defaults = { environment: "environment", environments: "environments", account: "account", product: "the app" };
+const TermsContext = React.createContext(defaults);
+function TermsProvider({ terms, children, }) {
+    const parent = React.useContext(TermsContext);
+    const value = React.useMemo(() => ({ ...parent, ...terms }), [parent, terms]);
+    return _jsx(TermsContext.Provider, { value: value, children: children });
+}
+/** The app's terms; defaults are "environment" and "account". */
+function useTerms() {
+    return React.useContext(TermsContext);
+}
+/** "Environment" from "environment": for headings and the start of a sentence. */
+const capitalise = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+export { TermsProvider, useTerms, capitalise };

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

@@ -0,0 +1,34 @@
+import * as React from "react";
+import { type LucideIcon } from "lucide-react";
+import type { AgentIdentity } from "../lib/chat.js";
+export type AgentRoleInfo = {
+    Icon: LucideIcon;
+    noun: string;
+    hue: string;
+};
+export declare const baseAgentRoles: Record<string, AgentRoleInfo>;
+/** The app's agent roles; nested providers add to (and can override) the ones above. */
+declare function AgentRolesProvider({ roles, children, }: {
+    /** Role ids mapped to an icon, a noun and a hue. */
+    roles: Record<string, AgentRoleInfo>;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** Look up a role's glyph, noun and hue; unknown roles read as "Assistant". */
+declare function useAgentRoles(): (role: string) => AgentRoleInfo;
+/** An agent's mark: its role glyph on a tile tinted with the role's hue. */
+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;
+}): 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;
+}): React.JSX.Element;
+export { AgentAvatar, AgentBadge, AgentRolesProvider, useAgentRoles };

package/dist/chat/agent-avatar.js

@@ -0,0 +1,42 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Bot, ClipboardList, CodeXml, Compass, FlaskConical, PenTool, ScanSearch, SearchCheck, Workflow } from "lucide-react";
+import { cn } from "../lib/utils.js";
+// Each role keeps one glyph and one chart hue everywhere it appears, so a
+// person learns "the green flask is the tester" once.
+export const baseAgentRoles = {
+    assistant: { Icon: Bot, noun: "Assistant", hue: "var(--chart-1)" },
+    orchestrator: { Icon: Workflow, noun: "Orchestrator", hue: "var(--chart-1)" },
+    planner: { Icon: Compass, noun: "Planner", hue: "var(--chart-3)" },
+    researcher: { Icon: ScanSearch, noun: "Researcher", hue: "var(--chart-2)" },
+    analyst: { Icon: ClipboardList, noun: "Analyst", hue: "var(--chart-2)" },
+    designer: { Icon: PenTool, noun: "Designer", hue: "var(--chart-5)" },
+    coder: { Icon: CodeXml, noun: "Coder", hue: "var(--chart-1)" },
+    reviewer: { Icon: SearchCheck, noun: "Reviewer", hue: "var(--chart-3)" },
+    tester: { Icon: FlaskConical, noun: "Tester", hue: "var(--chart-4)" },
+};
+const unknownRole = { Icon: Bot, noun: "Assistant", hue: "var(--chart-1)" };
+const RolesContext = React.createContext(baseAgentRoles);
+/** The app's agent roles; nested providers add to (and can override) the ones above. */
+function AgentRolesProvider({ roles, children, }) {
+    const parent = React.useContext(RolesContext);
+    const value = React.useMemo(() => ({ ...parent, ...roles }), [parent, roles]);
+    return _jsx(RolesContext.Provider, { value: value, children: children });
+}
+/** Look up a role's glyph, noun and hue; unknown roles read as "Assistant". */
+function useAgentRoles() {
+    const roles = React.useContext(RolesContext);
+    return React.useCallback((role) => roles[role] ?? unknownRole, [roles]);
+}
+/** An agent's mark: its role glyph on a tile tinted with the role's hue. */
+function AgentAvatar({ agent, size = "md", className, }) {
+    const { Icon, hue } = useAgentRoles()(agent.role);
+    return (_jsx("span", { "data-slot": "agent-avatar", "aria-hidden": true, className: cn("inline-flex shrink-0 items-center justify-center rounded-md", size === "md" ? "size-7 [&_svg]:size-3.5" : "size-5 rounded-sm [&_svg]:size-3", className), style: { color: hue, background: `color-mix(in oklab, ${hue} 14%, var(--card))`, boxShadow: `inset 0 0 0 1px color-mix(in oklab, ${hue} 22%, transparent)` }, children: _jsx(Icon, { strokeWidth: 2.25 }) }));
+}
+/** Avatar plus name, with the role spelled out for screen readers. */
+function AgentBadge({ agent, size = "md", className, }) {
+    const { noun } = useAgentRoles()(agent.role);
+    return (_jsxs("span", { "data-slot": "agent-badge", className: cn("inline-flex min-w-0 items-center gap-2", className), children: [_jsx(AgentAvatar, { agent: agent, size: size }), _jsx("span", { className: cn("truncate font-medium", size === "sm" ? "text-xs" : "text-sm"), children: agent.name }), _jsxs("span", { className: "sr-only", children: [", ", noun, " agent"] })] }));
+}
+export { AgentAvatar, AgentBadge, AgentRolesProvider, useAgentRoles };

package/dist/chat/card-registry.d.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+/**
+ * A card an agent's reply can carry. `check` decides whether the props are
+ * the shape `render` needs: it returns null when they are, or a sentence
+ * saying what's wrong. Cards are data from a model; nothing renders until the
+ * check passes.
+ */
+export type CardDefinition<P = unknown> = {
+    /** What it is, in a few words, for fallbacks: "Query results". */
+    label: string;
+    check: (props: unknown) => string | null;
+    render: (props: P) => React.ReactNode;
+};
+type AnyCard = CardDefinition<any>;
+/** Define a card with typed props; the check is what makes the cast safe. */
+export declare function defineCard<P>(card: CardDefinition<P>): CardDefinition<P>;
+/** Makes cards available to every message below it. Cards not listed here fall back to their summary. */
+declare function CardRegistryProvider({ cards, children, }: {
+    /** Your app's cards by name, made with defineCard. */
+    cards: Record<string, AnyCard>;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * Renders one card from the registry. Three honest fallbacks, each with the
+ * service's text summary: the app doesn't know this card; its data doesn't
+ * fit (and how); or it failed while drawing.
+ */
+declare function Card({ name, props, summary, }: {
+    /** Which card to draw, from the registry. */
+    name: string;
+    /** The card's data, checked before it draws. */
+    props: unknown;
+    /** The plain-text version, shown when the card can't be. */
+    summary: string;
+}): React.JSX.Element;
+export declare const isObject: (v: unknown) => v is Record<string, unknown>;
+export declare const isArrayOf: <T>(v: unknown, item: (x: unknown) => x is T) => v is T[];
+export declare const isString: (v: unknown) => v is string;
+export { Card, CardRegistryProvider };

package/dist/chat/card-registry.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { ChevronRight, LayoutTemplate } from "lucide-react";
+import { DegradedPanel } from "../blocks/degraded-panel.js";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible.js";
+/** Define a card with typed props; the check is what makes the cast safe. */
+export function defineCard(card) {
+    return card;
+}
+const Registry = React.createContext({});
+/** Makes cards available to every message below it. Cards not listed here fall back to their summary. */
+function CardRegistryProvider({ cards, children, }) {
+    return _jsx(Registry.Provider, { value: cards, children: children });
+}
+class CardBoundary extends React.Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    render() {
+        return this.state.failed ? this.props.fallback : this.props.children;
+    }
+}
+function Summary({ text, }) {
+    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: "size-3 transition-transform group-data-[state=open]/summary:rotate-90" }), " Show it as text"] }), _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
+ * service's text summary: the app doesn't know this card; its data doesn't
+ * fit (and how); or it failed while drawing.
+ */
+function Card({ name, props, summary, }) {
+    const cards = React.useContext(Registry);
+    const def = cards[name];
+    if (!def) {
+        return (_jsxs("div", { "data-slot": "card", "data-card": name, "data-state": "unknown", className: "flex flex-col gap-1.5 rounded-lg border border-dashed px-3 py-2.5", children: [_jsxs("p", { className: "flex items-center gap-1.5 text-sm text-muted-foreground", children: [_jsx(LayoutTemplate, { "aria-hidden": true, className: "size-3.5" }), " This reply includes a \u201C", name, "\u201D card this app can\u2019t show."] }), _jsx(Summary, { text: summary })] }));
+    }
+    const problem = def.check(props);
+    if (problem) {
+        return (_jsxs("div", { "data-slot": "card", "data-card": name, "data-state": "invalid", className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: `The ${def.label.toLowerCase()} couldn’t be shown: ${problem}` }), _jsx(Summary, { text: summary })] }));
+    }
+    return (_jsx("div", { "data-slot": "card", "data-card": name, "data-state": "ready", children: _jsx(CardBoundary, { fallback: _jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: `The ${def.label.toLowerCase()} failed while drawing.` }), _jsx(Summary, { text: summary })] }), children: def.render(props) }) }));
+}
+/* ---------------------------------------------------------------- small checking helpers */
+export const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export const isArrayOf = (v, item) => Array.isArray(v) && v.every(item);
+export const isString = (v) => typeof v === "string";
+export { Card, CardRegistryProvider };

package/dist/chat/citation.d.ts

@@ -0,0 +1,29 @@
+import { type LucideIcon } from "lucide-react";
+import type { MessageSource } from "../lib/chat.js";
+/** Kinds of evidence most apps cite. Others read as "Source". */
+export declare const sourceKinds: Record<string, {
+    Icon: LucideIcon;
+    noun: string;
+}>;
+declare function SourceDetail({ source, }: {
+    /** The source this marker points to; without it the marker says it's unknown. */
+    source: MessageSource;
+}): import("react").JSX.Element;
+/**
+ * An inline [n]. Opens the source in a popover on click or Enter, so evidence is
+ * one step away without leaving the thread. A source the message doesn't list
+ * renders as a plain bracket rather than a guess.
+ */
+declare function Citation({ source, marker, }: {
+    /** The source this marker points to; without it the marker says it's unknown. */
+    source?: MessageSource;
+    /** The number to show when there's no source. */
+    marker?: number;
+}): import("react").JSX.Element;
+/** The sources under a reply, as chips that open the same detail. */
+declare function SourceList({ sources, className, }: {
+    /** Every source the reply used, in marker order. */
+    sources: MessageSource[];
+    className?: string;
+}): import("react").JSX.Element | null;
+export { Citation, SourceList, SourceDetail };

package/dist/chat/citation.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { BookOpen, Braces, Database, FileText, Globe, Table2, Waypoints } from "lucide-react";
+import { cn } from "../lib/utils.js";
+import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover.js";
+/** Kinds of evidence most apps cite. Others read as "Source". */
+export const sourceKinds = {
+    document: { Icon: FileText, noun: "Document" },
+    web: { Icon: Globe, noun: "Web page" },
+    query: { Icon: Database, noun: "Query" },
+    data: { Icon: Table2, noun: "Data" },
+    code: { Icon: Braces, noun: "Code" },
+    workflow: { Icon: Waypoints, noun: "Workflow" },
+    knowledge: { Icon: BookOpen, noun: "Knowledge" },
+};
+const kindOf = (kind) => sourceKinds[kind] ?? { Icon: FileText, noun: "Source" };
+function SourceDetail({ source, }) {
+    const { Icon, noun } = kindOf(source.kind);
+    return (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsxs("div", { className: "flex items-start gap-2", children: [_jsx("span", { className: "mt-0.5 flex size-5 shrink-0 items-center justify-center rounded-sm bg-muted text-muted-foreground", children: _jsx(Icon, { className: "size-3" }) }), _jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "text-sm font-medium leading-snug", children: source.label }), _jsx("p", { className: "text-xs text-muted-foreground", children: source.origin ?? noun })] })] }), source.snippet && (_jsx("blockquote", { className: "max-h-40 overflow-auto rounded-md bg-sunken px-2.5 py-2 text-xs leading-relaxed whitespace-pre-wrap text-muted-foreground", children: source.snippet })), source.provisional && (_jsx("p", { className: "text-xs text-provisional", children: "The agent cites this but hasn\u2019t verified it." }))] }));
+}
+/**
+ * An inline [n]. Opens the source in a popover on click or Enter, so evidence is
+ * one step away without leaving the thread. A source the message doesn't list
+ * renders as a plain bracket rather than a guess.
+ */
+function Citation({ source, marker, }) {
+    if (!source) {
+        return _jsxs("sup", { className: "text-faint-foreground", children: ["[", marker ?? "?", "]"] });
+    }
+    return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": `Source ${source.marker}: ${source.label}`, className: cn("mx-0.5 inline-flex h-4 min-w-4 -translate-y-px items-center justify-center rounded-sm px-1 align-middle text-2xs font-semibold tabular-nums transition-colors duration-150 outline-none focus-visible:ring-[3px] focus-visible:ring-ring/40", source.provisional
+                        ? "border border-dashed border-provisional/60 text-provisional hover:bg-muted"
+                        : "bg-accent-weak text-accent-text hover:bg-primary hover:text-primary-foreground"), children: source.marker }) }), _jsx(PopoverContent, { align: "start", className: "w-80 p-3", children: _jsx(SourceDetail, { source: source }) })] }));
+}
+/** The sources under a reply, as chips that open the same detail. */
+function SourceList({ sources, className, }) {
+    if (sources.length === 0)
+        return null;
+    return (_jsxs("div", { "data-slot": "source-list", className: cn("flex flex-wrap items-center gap-1.5", className), children: [_jsx("span", { className: "mr-0.5 text-xs text-faint-foreground", children: "Sources" }), [...sources]
+                .sort((a, b) => a.marker - b.marker)
+                .map((s) => {
+                const { Icon } = kindOf(s.kind);
+                return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { type: "button", className: cn("inline-flex max-w-56 items-center gap-1.5 rounded-md border bg-card py-0.5 pr-2 pl-1 text-xs text-muted-foreground transition-colors duration-150 outline-none hover:border-border-strong hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/40", s.provisional && "border-dashed"), children: [_jsx("span", { className: "flex h-4 min-w-4 items-center justify-center rounded-sm bg-muted px-1 text-2xs font-semibold tabular-nums", children: s.marker }), _jsx(Icon, { "aria-hidden": true, className: "size-3 shrink-0" }), _jsx("span", { className: "truncate", children: s.label })] }) }), _jsx(PopoverContent, { align: "start", className: "w-80 p-3", children: _jsx(SourceDetail, { source: s }) })] }, s.id));
+            })] }));
+}
+export { Citation, SourceList, SourceDetail };

package/dist/chat/composer.d.ts

@@ -0,0 +1,54 @@
+import * as React from "react";
+import type { Attachment, ComposerScope, EntityRef, MentionOption, SlashCommand } from "../lib/chat.js";
+export type ComposerState = "ready" | "sending" | "streaming" | {
+    kind: "locked";
+    reason: string;
+} | {
+    kind: "offline";
+    reason?: string;
+};
+/**
+ * Where a person asks. Mentions (@) attach things in the user's system as chips the agent
+ * receives as references, not as text it has to parse; slash commands (/) start
+ * a known action. The scope pill says which environment the ask runs
+ * against, and turns to a warning when that is production.
+ *
+ * Enter sends, Shift+Enter breaks a line. While an agent replies the send button
+ * becomes Stop. A locked composer says why; an offline one says so.
+ */
+declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onScopeClick, mentions, commands, references, onReferencesChange, attachments, onAttach, onRemoveAttachment, placeholder, label, className, }: {
+    /** The text in the box. */
+    value: string;
+    /** Called with the new text as the person types. */
+    onChange: (value: string) => void;
+    /** Called on send with the text and the entities mentioned. */
+    onSubmit: (value: string, references: EntityRef[]) => void;
+    /** Shown as Stop while a reply is streaming. */
+    onStop?: () => void;
+    /** ready, sending, streaming, locked (with a reason) or offline. */
+    state?: ComposerState;
+    /** Where the next message's work lands; production turns the pill to a warning. */
+    scope?: ComposerScope;
+    /** Makes the scope pill a button, e.g. to change environment. */
+    onScopeClick?: () => void;
+    /** What @ can insert, grouped under their headings. */
+    mentions?: MentionOption[];
+    /** What / can run, only at the start of a message. */
+    commands?: SlashCommand[];
+    /** Entities already attached, shown as chips. */
+    references?: EntityRef[];
+    /** Called when a chip is added or removed. */
+    onReferencesChange?: (references: EntityRef[]) => void;
+    /** Files attached, with upload progress or an error. */
+    attachments?: Attachment[];
+    /** Shows an attach button; called with the chosen files. */
+    onAttach?: (files: File[]) => void;
+    /** Called when a file is removed. */
+    onRemoveAttachment?: (id: string) => void;
+    /** Shown in the empty box. */
+    placeholder?: string;
+    /** The accessible name of the text box. */
+    label?: string;
+    className?: string;
+}): React.JSX.Element;
+export { Composer };

package/dist/chat/composer.js

@@ -0,0 +1,168 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { ArrowUp, LoaderCircle, Paperclip, Square, TriangleAlert, X } from "lucide-react";
+import { cn } from "../lib/utils.js";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../ui/tooltip.js";
+import { EntityChip, useEntityKinds } from "./entity-chip.js";
+/** The @ or / token the caret sits in, if any. A / only counts at the start of the message. */
+function findTrigger(value, caret) {
+    const before = value.slice(0, caret);
+    const m = /(^|\s)([@/])([\w.-]*)$/.exec(before);
+    if (!m)
+        return null;
+    const char = m[2];
+    const start = before.length - m[3].length - 1;
+    if (char === "/" && before.slice(0, start).trim() !== "")
+        return null;
+    return { char, start, query: m[3] };
+}
+const groupOf = (item) => (item.type === "command" ? "Commands" : item.option.group);
+function formatSize(bytes) {
+    if (bytes === undefined)
+        return null;
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+/**
+ * Where a person asks. Mentions (@) attach things in the user's system as chips the agent
+ * receives as references, not as text it has to parse; slash commands (/) start
+ * a known action. The scope pill says which environment the ask runs
+ * against, and turns to a warning when that is production.
+ *
+ * Enter sends, Shift+Enter breaks a line. While an agent replies the send button
+ * becomes Stop. A locked composer says why; an offline one says so.
+ */
+function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, onScopeClick, mentions = [], commands = [], references = [], onReferencesChange, attachments = [], onAttach, onRemoveAttachment, placeholder = "Ask a question, or describe a change", label = "Message", className, }) {
+    const kindOf = useEntityKinds();
+    const id = React.useId();
+    const textarea = React.useRef(null);
+    const fileInput = React.useRef(null);
+    const [trigger, setTrigger] = React.useState(null);
+    const [active, setActive] = React.useState(0);
+    const locked = typeof state === "object" ? state : null;
+    const busy = state === "sending" || state === "streaming";
+    const canSend = !locked && !busy && (value.trim().length > 0 || references.length > 0);
+    const items = React.useMemo(() => {
+        if (!trigger)
+            return [];
+        const q = trigger.query.toLowerCase();
+        if (trigger.char === "/") {
+            return commands
+                .filter((c) => c.name.toLowerCase().startsWith(q))
+                .map((command) => ({ type: "command", command }));
+        }
+        const taken = new Set(references.map((r) => `${r.kind}:${r.name}`));
+        return mentions
+            .filter((o) => !o.entity || !taken.has(`${o.entity.kind}:${o.entity.name}`))
+            .filter((o) => o.label.toLowerCase().includes(q) || o.entity?.name.toLowerCase().includes(q))
+            .slice(0, 8)
+            .map((option) => ({ type: "mention", option }));
+    }, [trigger, commands, mentions, references]);
+    const menuOpen = trigger !== null && items.length > 0;
+    React.useEffect(() => setActive(0), [trigger?.query, trigger?.char]);
+    const syncTrigger = () => {
+        const el = textarea.current;
+        if (!el)
+            return;
+        setTrigger(findTrigger(el.value, el.selectionStart));
+    };
+    // Where the caret goes once a replaced value renders. Applied in a layout
+    // effect on that render, so keystrokes typed afterwards are never moved.
+    const pendingCaret = React.useRef(null);
+    React.useLayoutEffect(() => {
+        const el = textarea.current;
+        if (el && pendingCaret.current !== null) {
+            el.setSelectionRange(pendingCaret.current, pendingCaret.current);
+            pendingCaret.current = null;
+        }
+    }, [value, references]);
+    const replaceTrigger = (text) => {
+        if (!trigger)
+            return;
+        const el = textarea.current;
+        const caret = el?.selectionStart ?? value.length;
+        const next = value.slice(0, trigger.start) + text + value.slice(caret);
+        pendingCaret.current = trigger.start + text.length;
+        onChange(next);
+        setTrigger(null);
+        el?.focus();
+    };
+    const choose = (item) => {
+        if (item.type === "command") {
+            replaceTrigger(`/${item.command.name} `);
+        }
+        else if (item.option.entity) {
+            onReferencesChange?.([...references, item.option.entity]);
+            replaceTrigger("");
+        }
+        else {
+            replaceTrigger(`@${item.option.label} `);
+        }
+    };
+    const submit = () => {
+        if (!canSend)
+            return;
+        onSubmit(value.trim(), references);
+    };
+    const onKeyDown = (e) => {
+        if (menuOpen) {
+            if (e.key === "ArrowDown") {
+                e.preventDefault();
+                setActive((a) => (a + 1) % items.length);
+                return;
+            }
+            if (e.key === "ArrowUp") {
+                e.preventDefault();
+                setActive((a) => (a - 1 + items.length) % items.length);
+                return;
+            }
+            if (e.key === "Enter" || e.key === "Tab") {
+                e.preventDefault();
+                choose(items[active]);
+                return;
+            }
+            if (e.key === "Escape") {
+                e.preventDefault();
+                setTrigger(null);
+                return;
+            }
+        }
+        if (e.key === "Backspace" && value === "" && references.length > 0) {
+            onReferencesChange?.(references.slice(0, -1));
+            return;
+        }
+        if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing) {
+            e.preventDefault();
+            submit();
+        }
+    };
+    const production = !!scope?.production;
+    const listId = `${id}-menu`;
+    const optionId = (i) => `${id}-opt-${i}`;
+    return (_jsxs("div", { "data-slot": "composer", className: cn("@container relative", className), children: [menuOpen && (_jsx("div", { id: listId, role: "listbox", "aria-label": trigger?.char === "/" ? "Commands" : "Mentions", className: "absolute inset-x-0 bottom-full z-20 mb-2 max-h-72 overflow-y-auto rounded-xl border bg-popover p-1 shadow-float animate-in fade-in-0 slide-in-from-bottom-1", children: items.map((item, i) => {
+                    const group = groupOf(item);
+                    const prev = items[i - 1];
+                    const header = !prev || groupOf(prev) !== group ? group : null;
+                    const Icon = item.type === "mention" && item.option.entity ? kindOf(item.option.entity.kind).Icon : null;
+                    return (_jsxs(React.Fragment, { children: [header && _jsx("p", { className: "px-2 pt-2 pb-1 text-2xs font-medium text-faint-foreground", children: header }), _jsx("div", { id: optionId(i), role: "option", tabIndex: -1, "aria-selected": i === active, onMouseDown: (e) => {
+                                    e.preventDefault();
+                                    choose(item);
+                                }, onMouseMove: () => setActive(i), className: "flex cursor-pointer items-center gap-2.5 rounded-md px-2 py-1.5 text-sm aria-selected:bg-accent", children: item.type === "command" ? (_jsxs(_Fragment, { children: [_jsxs("span", { className: "font-mono text-xs text-accent-text", children: ["/", item.command.name] }), item.command.args && _jsx("span", { className: "font-mono text-xs text-faint-foreground", children: item.command.args }), _jsx("span", { className: "ml-auto truncate text-xs text-muted-foreground", children: item.command.description })] })) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "flex size-6 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground", children: Icon ? _jsx(Icon, { className: "size-3.5" }) : _jsx("span", { className: "text-xs", children: "@" }) }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate", children: item.option.label }), (item.option.description ?? item.option.entity?.name) !== item.option.label && (item.option.description ?? item.option.entity?.name) && (_jsx("span", { className: "block truncate font-mono text-2xs text-faint-foreground", children: item.option.description ?? item.option.entity?.name }))] })] })) })] }, item.type === "command" ? item.command.id : item.option.id));
+                }) })), _jsxs("div", { className: cn("rounded-2xl border bg-card shadow-raised transition-[border-color,box-shadow] duration-150 focus-within:border-border-strong focus-within:shadow-float", locked && "bg-muted shadow-none"), children: [(references.length > 0 || attachments.length > 0) && (_jsxs("div", { className: "flex flex-wrap gap-1.5 px-3 pt-3", children: [references.map((r) => (_jsx(EntityChip, { entity: r, onRemove: (e) => onReferencesChange?.(references.filter((x) => x !== e)) }, `${r.kind}:${r.name}`))), attachments.map((a) => (_jsxs("span", { className: cn("relative inline-flex max-w-56 items-center gap-1.5 overflow-hidden rounded-md border bg-card py-1 pr-1 pl-2 text-xs", a.error && "border-destructive/50"), children: [_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 ? `${Math.round(a.progress * 100)}%` : formatSize(a.size) }), onRemoveAttachment && (_jsx("button", { type: "button", "aria-label": `Remove ${a.name}`, onClick: () => onRemoveAttachment(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 left-0 h-0.5 bg-primary transition-[width] duration-300", style: { width: `${a.progress * 100}%` } }))] }, a.id)))] })), _jsx("label", { htmlFor: id, className: "sr-only", children: label }), _jsx("textarea", { ref: textarea, id: id, rows: 1, value: value, disabled: Boolean(locked), placeholder: locked ? undefined : placeholder, onChange: (e) => {
+                            onChange(e.target.value);
+                            requestAnimationFrame(syncTrigger);
+                        }, onKeyDown: onKeyDown, onKeyUp: (e) => {
+                            if (e.key === "ArrowLeft" || e.key === "ArrowRight")
+                                syncTrigger();
+                        }, onClick: syncTrigger, onBlur: () => setTrigger(null), "aria-controls": menuOpen ? listId : undefined, "aria-activedescendant": menuOpen ? optionId(active) : undefined, "aria-autocomplete": "list", "aria-describedby": locked ? `${id}-locked` : undefined, className: cn("block max-h-60 min-h-12 w-full resize-none bg-transparent px-4 pt-3 pb-1 text-base leading-relaxed outline-none [field-sizing:content] placeholder:text-faint-foreground disabled:cursor-not-allowed", locked && !value && "min-h-0 h-3 pt-3 pb-0") }), locked && (_jsx("p", { id: `${id}-locked`, className: "flex items-center gap-1.5 px-4 pb-1 text-sm text-muted-foreground", children: locked.kind === "offline" ? locked.reason ?? "You’re offline. Your message will wait here." : locked.reason })), _jsxs("div", { className: "flex items-center gap-1.5 px-2 pt-1 pb-2", children: [onAttach && (_jsxs(_Fragment, { children: [_jsx("input", { ref: fileInput, type: "file", multiple: true, tabIndex: -1, "aria-label": "Attach files", className: "hidden", onChange: (e) => {
+                                            const files = Array.from(e.target.files ?? []);
+                                            if (files.length)
+                                                onAttach(files);
+                                            e.target.value = "";
+                                        } }), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": "Attach files", disabled: Boolean(locked), onClick: () => fileInput.current?.click(), className: "flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground disabled:opacity-40", children: _jsx(Paperclip, { className: "size-4" }) }) }), _jsx(TooltipContent, { children: "Attach files" })] })] })), scope && (_jsxs("button", { type: "button", onClick: onScopeClick, disabled: !onScopeClick, className: cn("inline-flex min-w-0 items-center gap-1.5 rounded-lg px-2 py-1 text-xs transition-colors duration-150 enabled:hover:bg-accent", production ? "bg-warning-weak text-warning-text enabled:hover:bg-warning-weak" : "text-muted-foreground"), children: [production ? _jsx(TriangleAlert, { "aria-hidden": true, className: "size-3 shrink-0" }) : _jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-success" }), _jsxs("span", { className: "truncate", children: [scope.environment, " \u00B7 ", production ? "Production" : (scope.detail ?? "Non-production")] })] })), _jsxs("span", { className: "ml-auto hidden text-2xs text-faint-foreground @lg:inline", children: [_jsx("kbd", { className: "font-sans", children: "\u21B5" }), " send \u00B7 ", _jsx("kbd", { className: "font-sans", children: "\u21E7\u21B5" }), " new line \u00B7 ", _jsx("kbd", { className: "font-sans", children: "@" }), " mention"] }), state === "streaming" && onStop ? (_jsx("button", { type: "button", "aria-label": "Stop", onClick: onStop, className: "ml-auto flex size-8 items-center justify-center rounded-lg bg-foreground text-background transition-transform duration-150 active:scale-95 @lg:ml-1", children: _jsx(Square, { className: "size-3 fill-current" }) })) : (_jsx("button", { type: "button", "aria-label": "Send", onClick: submit, disabled: !canSend, "aria-busy": state === "sending", className: "ml-auto flex size-8 items-center justify-center rounded-lg bg-primary text-primary-foreground transition-[background-color,opacity,transform] duration-150 enabled:hover:bg-primary-hover active:scale-95 disabled:opacity-30 @lg:ml-1", children: state === "sending" ? _jsx(LoaderCircle, { className: "size-4 animate-spin" }) : _jsx(ArrowUp, { className: "size-4", strokeWidth: 2.5 }) }))] })] })] }));
+}
+export { Composer };

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

@@ -0,0 +1,14 @@
+import type { ContextSegment } from "../lib/know.js";
+/**
+ * What fills the model's context budget, as a ring in the composer that
+ * opens to a breakdown: system, instructions, Know, the thread, tools, files.
+ * Counts are the service's own token counts; the ring warns past 80%.
+ */
+declare function ContextMeter({ segments, limit, className, }: {
+    /** What fills the context window, by kind, in tokens. */
+    segments: ContextSegment[];
+    /** The model's context window, in tokens. */
+    limit: number;
+    className?: string;
+}): import("react").JSX.Element;
+export { ContextMeter };

package/dist/chat/context-meter.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/utils.js";
+import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover.js";
+const kindColor = {
+    system: "var(--chart-5)",
+    instructions: "var(--chart-1)",
+    knowledge: "var(--chart-2)",
+    thread: "var(--chart-4)",
+    tools: "var(--chart-3)",
+    files: "var(--faint-foreground)",
+};
+function k(n) {
+    return n >= 1000 ? `${(n / 1000).toFixed(n >= 10_000 ? 0 : 1)}k` : String(n);
+}
+/**
+ * What fills the model's context budget, as a ring in the composer that
+ * opens to a breakdown: system, instructions, Know, the thread, tools, files.
+ * Counts are the service's own token counts; the ring warns past 80%.
+ */
+function ContextMeter({ segments, limit, className, }) {
+    const used = segments.reduce((n, s) => n + s.tokens, 0);
+    const pct = Math.min(1, used / limit);
+    const warn = pct > 0.8;
+    const r = 7;
+    const c = 2 * Math.PI * r;
+    return (_jsxs(Popover, { children: [_jsxs(PopoverTrigger, { "aria-label": `Context: ${k(used)} of ${k(limit)} tokens used`, className: cn("inline-flex items-center gap-1.5 rounded-md px-1.5 py-1 text-2xs tabular-nums outline-none hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/40", warn ? "text-warning-text" : "text-muted-foreground", className), children: [_jsxs("svg", { viewBox: "0 0 18 18", className: "size-4 -rotate-90", "aria-hidden": true, children: [_jsx("circle", { cx: "9", cy: "9", r: r, fill: "none", stroke: "var(--muted)", strokeWidth: "2.5" }), _jsx("circle", { cx: "9", cy: "9", r: r, fill: "none", stroke: warn ? "var(--warning)" : "var(--primary)", strokeWidth: "2.5", strokeDasharray: `${pct * c} ${c}`, strokeLinecap: "round" })] }), Math.round(pct * 100), "%"] }), _jsxs(PopoverContent, { align: "start", className: "w-72 p-3", children: [_jsxs("p", { className: "flex items-baseline justify-between text-sm font-medium", children: ["Context ", _jsxs("span", { className: "text-xs font-normal text-muted-foreground tabular-nums", children: [k(used), " / ", k(limit), " tokens"] })] }), _jsx("div", { "aria-hidden": true, className: "mt-2 flex h-2 overflow-hidden rounded-full bg-muted", children: segments.map((s) => (_jsx("span", { style: { width: `${(s.tokens / limit) * 100}%`, background: kindColor[s.kind] } }, s.label))) }), _jsx("ul", { className: "mt-3 flex flex-col gap-1.5", children: [...segments]
+                            .sort((a, b) => b.tokens - a.tokens)
+                            .map((s) => (_jsxs("li", { className: "flex items-center gap-2 text-xs", children: [_jsx("span", { "aria-hidden": true, className: "size-2 rounded-xs", style: { background: kindColor[s.kind] } }), _jsx("span", { className: "flex-1", children: s.label }), _jsx("span", { className: "text-muted-foreground tabular-nums", children: k(s.tokens) })] }, s.label))) }), warn && _jsx("p", { className: "mt-3 text-xs text-warning-text", children: "Nearly full. Older thread turns will be summarised to make room." })] })] }));
+}
+export { ContextMeter };