@elabs-ai/components-ai 4.0.0 → 4.1.0

package/src/agent-event.tsx

@@ -0,0 +1,187 @@
+"use client";
+
+/**
+ * AgentEvent — the lifecycle/hook event line (#109).
+ *
+ * Nothing in the trace vocabulary (`Message` → `Tool` → `Task`/`AgentStep`)
+ * has a place for something the *runtime* did to the agent: a lifecycle hook
+ * (`user_prompt_submit`, `stop`) or a policy/guard check
+ * (`pre_tool_use`/`post_tool_use`) that fired around a tool call. `AgentEvent`
+ * fills that gap as an `AgentStep` VARIANT on the existing `AgentTimeline`
+ * rail — not a second spine. It sits in the same `<ol>` as ordinary steps,
+ * distinguished by glyph and label rather than by a different layout
+ * (docs/decisions/2026-09-01-brainless-adoption-architecture.md § 6, and the
+ * `Task`/`TaskItem` precedent this file follows in `./agent-timeline`).
+ *
+ * `outcome` maps onto the existing closed 7-state `Status` (`@elabs-ai/components-ui`) —
+ * no eighth status is introduced. `checks` renders a gate's verdicts: an
+ * array renders each check as icon + accessible pass/fail TEXT (never colour
+ * alone — the greyscale test in `.claude/rules/accessibility.md`); a count
+ * summary renders `passed/ran` as plain text.
+ */
+import { Webhook, type LucideIcon } from "lucide-react";
+import { forwardRef, type ReactNode } from "react";
+import {
+  StatusIcon,
+  agentEventOutcomeStatus,
+  formatElapsed,
+  useLocale,
+  type AgentEventOutcome,
+  type AgentEventPhase,
+  type CheckResult,
+  type CheckSummary,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { AgentStep, type AgentStepProps } from "./agent-timeline";
+
+// `AgentEventPhase`, `AgentEventOutcome` and the outcome→`Status` mapping
+// (`agentEventOutcomeStatus`, formerly this file's private `OUTCOME_STATUS`)
+// moved to `@elabs-ai/components-ui` (`lib/agent-event-model.ts`) — the
+// terminal CLI look-alike family's own event line (issue #117) reuses the
+// same model, and `@elabs-ai/components-ai`/`@elabs-ai/components-terminal`
+// are layer-2 DAG siblings that may not import each other (T0; see
+// docs/decisions/2026-09-01-brainless-adoption-architecture.md § 4). Imported
+// above; NOT re-exported from here — a consumer imports `AgentEventPhase`/
+// `AgentEventOutcome` from `@elabs-ai/components-ui`.
+
+export interface AgentEventProps extends Omit<
+  AgentStepProps,
+  "name" | "status" | "children" | "icon" | "timestamp"
+> {
+  /** The runtime event name, verbatim as the runtime emits it — e.g. `"user_prompt_submit"`, `"pre_tool_use"`, `"stop"`. */
+  label: string;
+  /** When this event fired relative to the action it gates. See `AgentEventPhase`. */
+  phase?: AgentEventPhase;
+  /** The event's verdict. @default "ok" */
+  outcome?: AgentEventOutcome;
+  /** Wall-clock duration of the event, in milliseconds. Rendered with the shared `formatElapsed`. */
+  durationMs?: number;
+  /** Gate checks the event ran: individual verdicts, or a count summary. */
+  checks?: CheckSummary | CheckResult[];
+  /** Optional leading glyph on the title row (Lucide). @default Webhook */
+  icon?: LucideIcon;
+}
+
+function isCheckResultList(checks: CheckSummary | CheckResult[]): checks is CheckResult[] {
+  return Array.isArray(checks);
+}
+
+/**
+ * A single gate-check verdict row: icon + label + accessible status word +
+ * optional duration + optional detail. Mirrors the anatomy of `ChangeReview`'s
+ * check row (`packages/ui/src/components/change-review/change-review.tsx`) so
+ * the two `CheckResult` surfaces read as one convention — reimplemented here
+ * (rather than imported) because that row is a private, unexported function.
+ *
+ * The pass/fail signal is carried by TWO non-colour cues — `StatusIcon`'s
+ * distinct glyph (decorative, `aria-hidden`) and the visible status word
+ * (what reaches assistive tech) — so it survives in greyscale (WCAG 1.4.1).
+ */
+function AgentEventCheckRow({ check }: { check: CheckResult }) {
+  const { t } = useLocale();
+  const { label, ok, detail, durationMs } = check;
+  const statusWord = t(ok ? "ai.agentEvent.checkPassed" : "ai.agentEvent.checkFailed");
+
+  return (
+    <div data-slot="agent-event-check" data-ok={ok} className="flex flex-col gap-1">
+      <div className="flex flex-wrap items-center gap-x-1.5 gap-y-0.5 min-w-0">
+        <StatusIcon status={ok ? "complete" : "failed"} className="size-3.5 shrink-0" />
+        <span className="text-caption font-medium text-foreground truncate">{label}</span>
+        <span
+          data-slot="agent-event-check-status"
+          className={cn("text-caption", ok ? "text-success-text" : "text-destructive-text")}
+        >
+          {statusWord}
+        </span>
+        {durationMs !== undefined && (
+          <span className="text-caption text-muted-foreground tabular-nums shrink-0">
+            {formatElapsed(durationMs)}
+          </span>
+        )}
+      </div>
+      {detail !== undefined && detail !== "" && (
+        <p
+          data-slot="agent-event-check-detail"
+          className="pl-5 text-caption text-muted-foreground break-words"
+        >
+          {detail}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/** The checks section: a flat list of verdict rows, or a `passed/ran` count line. */
+function AgentEventChecks({ checks }: { checks: CheckSummary | CheckResult[] }) {
+  const { t } = useLocale();
+
+  if (isCheckResultList(checks)) {
+    if (checks.length === 0) return null;
+    return (
+      <div data-slot="agent-event-checks" className="flex flex-col gap-1.5">
+        {checks.map((check, index) => (
+          <AgentEventCheckRow key={`${check.label}-${index}`} check={check} />
+        ))}
+      </div>
+    );
+  }
+
+  const { ran, passed } = checks;
+  return (
+    <p
+      data-slot="agent-event-checks-summary"
+      className="text-meta text-muted-foreground tabular-nums"
+    >
+      {t("ai.agentEvent.checksSummary", { passed, ran })}
+    </p>
+  );
+}
+
+const PHASE_KEY: Record<AgentEventPhase, string> = {
+  before: "ai.agentEvent.phaseBefore",
+  after: "ai.agentEvent.phaseAfter",
+  lifecycle: "ai.agentEvent.phaseLifecycle",
+};
+
+/**
+ * One lifecycle/hook event line on the `AgentTimeline` rail — an `AgentStep`
+ * variant, never a second spine. Composes `AgentStep` exactly as `TaskItem`
+ * does in `./agent-timeline`, so it rides the same `TimelineRoot`/`TimelineItem`
+ * primitives every other trace entry uses.
+ */
+export const AgentEvent = forwardRef<HTMLLIElement, AgentEventProps>(function AgentEvent(
+  { label, phase, outcome = "ok", durationMs, checks, icon: Icon = Webhook, summary, ...props },
+  ref,
+) {
+  const { t } = useLocale();
+  const status = agentEventOutcomeStatus(outcome);
+  const phaseLabel = phase === undefined ? undefined : t(PHASE_KEY[phase]);
+
+  const name: ReactNode = phaseLabel ? (
+    <>
+      {label}{" "}
+      <span data-slot="agent-event-phase" className="text-meta font-normal text-muted-foreground">
+        · {phaseLabel}
+      </span>
+    </>
+  ) : (
+    label
+  );
+
+  return (
+    <AgentStep
+      ref={ref}
+      icon={Icon}
+      name={name}
+      status={status}
+      summary={summary}
+      timestamp={durationMs === undefined ? undefined : formatElapsed(durationMs)}
+      data-slot="agent-event"
+      {...props}
+    >
+      {checks ? <AgentEventChecks checks={checks} /> : null}
+    </AgentStep>
+  );
+});
+
+AgentEvent.displayName = "AgentEvent";

package/src/agent-timeline.stories.tsx

@@ -6,7 +6,15 @@ import { ToolDetails, ToolInput, ToolOutput } from "./tool";
 const meta = {
   title: "AI/AgentTimeline",
   component: AgentTimeline,
-  parameters: { layout: "padded" },
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The agent EXECUTION trace on the canonical rail. A generic ordered-steps rail is `Core/Timeline`, and git history is `Data/RevisionTimeline` — see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). `AgentTimeline` is the convergence compound: sequenced, status-bearing steps on ONE spine (the `@elabs-ai/components-ui` Timeline rail) speaking ONE vocabulary (the closed seven-state `Status` enum). `AI/Task` and `AI/AgentEvent` compose it rather than hand-rolling rails.",
+      },
+    },
+  },
   tags: ["autodocs"],
 } satisfies Meta<typeof AgentTimeline>;
 export default meta;

package/src/agent.test.tsx

@@ -0,0 +1,47 @@
+import type { Tool } from "ai";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { AgentTool, AgentTools } from "./agent";
+
+const staticTool: Tool = {
+  description: "Search the web for a query.",
+  inputSchema: { type: "object" } as never,
+};
+
+// ai@7 widened `Tool.description` to `string | ((options) => string)` (a
+// per-call dynamic description). `AgentTool` renders a static list with no
+// call context to invoke that function with.
+const dynamicTool: Tool = {
+  description: () => "computed at call time",
+  inputSchema: { type: "object" } as never,
+};
+
+describe("AgentTool description (#30, ai@7 Tool.description can be a function)", () => {
+  it("renders a string description", () => {
+    render(
+      <AgentTools type="single" collapsible>
+        <AgentTool tool={staticTool} value="search" />
+      </AgentTools>,
+    );
+    expect(screen.getByText("Search the web for a query.")).toBeInTheDocument();
+  });
+
+  it("falls back to the empty-description copy instead of rendering a function as a node", () => {
+    render(
+      <AgentTools type="single" collapsible>
+        <AgentTool tool={dynamicTool} value="dynamic" />
+      </AgentTools>,
+    );
+    expect(screen.getByText("No description")).toBeInTheDocument();
+  });
+
+  it("falls back to the empty-description copy when there is no description at all", () => {
+    const bareTool: Tool = { inputSchema: { type: "object" } as never };
+    render(
+      <AgentTools type="single" collapsible>
+        <AgentTool tool={bareTool} value="bare" />
+      </AgentTools>,
+    );
+    expect(screen.getByText("No description")).toBeInTheDocument();
+  });
+});

package/src/agent.tsx

@@ -7,6 +7,7 @@ import {
   AccordionTrigger,
 } from "@elabs-ai/components-ui";
 import { Badge } from "@elabs-ai/components-ui";
+import { useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import type { Tool } from "ai";
 import { BotIcon } from "lucide-react";
@@ -51,24 +52,32 @@ export type AgentInstructionsProps = ComponentProps<"div"> & {
 };
 
 export const AgentInstructions = memo(
-  ({ className, children, ...props }: AgentInstructionsProps) => (
-    <div className={cn("space-y-2", className)} {...props}>
-      <span className="font-medium text-muted-foreground text-sm">Instructions</span>
-      <div className="rounded-md bg-muted/50 p-3 text-muted-foreground text-sm">
-        <p>{children}</p>
+  ({ className, children, ...props }: AgentInstructionsProps) => {
+    const { t } = useLocale();
+    return (
+      <div className={cn("space-y-2", className)} {...props}>
+        <span className="font-medium text-muted-foreground text-sm">
+          {t("ai.agent.instructions")}
+        </span>
+        <div className="rounded-md bg-muted/50 p-3 text-muted-foreground text-sm">
+          <p>{children}</p>
+        </div>
       </div>
-    </div>
-  ),
+    );
+  },
 );
 
 export type AgentToolsProps = ComponentProps<typeof Accordion>;
 
-export const AgentTools = memo(({ className, ...props }: AgentToolsProps) => (
-  <div className={cn("space-y-2", className)}>
-    <span className="font-medium text-muted-foreground text-sm">Tools</span>
-    <Accordion className="rounded-md border" {...props} />
-  </div>
-));
+export const AgentTools = memo(({ className, ...props }: AgentToolsProps) => {
+  const { t } = useLocale();
+  return (
+    <div className={cn("space-y-2", className)}>
+      <span className="font-medium text-muted-foreground text-sm">{t("ai.agent.tools")}</span>
+      <Accordion className="rounded-md border" {...props} />
+    </div>
+  );
+});
 
 export type AgentToolProps = ComponentProps<typeof AccordionItem> & {
   tool: Tool;
@@ -76,11 +85,16 @@ export type AgentToolProps = ComponentProps<typeof AccordionItem> & {
 
 export const AgentTool = memo(({ className, tool, value, ...props }: AgentToolProps) => {
   const schema = "jsonSchema" in tool && tool.jsonSchema ? tool.jsonSchema : tool.inputSchema;
+  // `tool.description` may be a fixed string OR (ai@7+) a function of the live
+  // call context (`(options) => string`) for a per-call dynamic description.
+  // AgentTool renders a static list, so it has no call context to invoke that
+  // function with — show it only when it is already a plain string.
+  const description = typeof tool.description === "string" ? tool.description : undefined;
 
   return (
     <AccordionItem className={cn("border-b last:border-b-0", className)} value={value} {...props}>
       <AccordionTrigger className="px-3 py-2 text-sm hover:no-underline">
-        {tool.description ?? "No description"}
+        {description ?? "No description"}
       </AccordionTrigger>
       <AccordionContent className="px-3 pb-3">
         <div className="rounded-md bg-muted/50">

package/src/agentic-workspace.stories.tsx

@@ -86,12 +86,12 @@ import {
   ApprovalCardTitle,
 } from "./confirmation";
 import {
-  Context,
-  ContextContent,
-  ContextContentFooter,
-  ContextContentHeader,
-  ContextTrigger,
-} from "./context";
+  TokenUsage,
+  TokenUsageContent,
+  TokenUsageContentFooter,
+  TokenUsageContentHeader,
+  TokenUsageTrigger,
+} from "./token-usage";
 import {
   ContextPanel,
   ContextPanelBody,
@@ -321,13 +321,15 @@ function WorkspaceSidebar({
       <SidebarHeader>
         <SidebarMenu>
           <SidebarMenuItem>
-            <SidebarMenuButton size="lg" tooltip="Atlas workspace">
+            <SidebarMenuButton size="lg" tooltip="Atlas workspace" className="group">
               <span className="flex aspect-square size-8 shrink-0 items-center justify-center group-data-[collapsible=icon]:size-4">
                 <BrandLogo variant="mark" className="size-full" aria-hidden />
               </span>
               <span className="grid flex-1 text-start leading-tight">
                 <span className="truncate text-body font-semibold">Atlas</span>
-                <span className="truncate text-meta text-muted-foreground">Agentic workspace</span>
+                <span className="truncate text-meta text-sidebar-muted-foreground group-hover:text-sidebar-accent-foreground">
+                  Agentic workspace
+                </span>
               </span>
             </SidebarMenuButton>
           </SidebarMenuItem>
@@ -378,13 +380,16 @@ function WorkspaceSidebar({
                           <SidebarMenuSubButton asChild isActive={activeProject === p.id}>
                             <a
                               href={`#project-${p.id}`}
+                              className="group"
                               onClick={(e) => {
                                 e.preventDefault();
                                 onSelectProject(p.id);
                               }}
                             >
                               <span className="flex-1 truncate">{p.name}</span>
-                              <span className="text-meta text-muted-foreground">{p.tag}</span>
+                              <span className="text-meta text-sidebar-muted-foreground group-hover:text-sidebar-accent-foreground group-data-[active=true]:text-sidebar-accent-foreground">
+                                {p.tag}
+                              </span>
                             </a>
                           </SidebarMenuSubButton>
                         </SidebarMenuSubItem>
@@ -455,9 +460,9 @@ function WorkspaceSidebar({
                       {ASSET_CATEGORIES.map((c) => (
                         <SidebarMenuSubItem key={c.id}>
                           <SidebarMenuSubButton asChild>
-                            <a href={`#assets-${c.id}`}>
+                            <a href={`#assets-${c.id}`} className="group">
                               <span className="flex-1 truncate">{c.name}</span>
-                              <span className="text-meta tabular-nums text-muted-foreground">
+                              <span className="text-meta tabular-nums text-sidebar-muted-foreground group-hover:text-sidebar-accent-foreground">
                                 {c.count}
                               </span>
                             </a>
@@ -478,13 +483,15 @@ function WorkspaceSidebar({
           <SidebarMenuItem>
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
-                <SidebarMenuButton size="lg" tooltip="Account">
+                <SidebarMenuButton size="lg" tooltip="Account" className="group">
                   <Avatar className="size-7 rounded-md">
                     <AvatarFallback className="rounded-md text-meta">AR</AvatarFallback>
                   </Avatar>
                   <span className="grid flex-1 text-start leading-tight">
                     <span className="truncate text-body font-medium">Avery Rao</span>
-                    <span className="truncate text-meta text-muted-foreground">avery@acme.co</span>
+                    <span className="truncate text-meta text-sidebar-muted-foreground group-hover:text-sidebar-accent-foreground">
+                      avery@acme.co
+                    </span>
                   </span>
                   <ChevronsUpDown className="ms-auto size-4" />
                 </SidebarMenuButton>
@@ -557,13 +564,13 @@ function WorkspaceContextPanel() {
   return (
     <ContextPanel>
       <ContextPanelHeader title="Context">
-        <Context usedTokens={42000} maxTokens={200000} modelId="anthropic/claude-opus-4">
-          <ContextTrigger />
-          <ContextContent>
-            <ContextContentHeader />
-            <ContextContentFooter />
-          </ContextContent>
-        </Context>
+        <TokenUsage usedTokens={42000} maxTokens={200000} modelId="anthropic/claude-opus-4">
+          <TokenUsageTrigger />
+          <TokenUsageContent>
+            <TokenUsageContentHeader />
+            <TokenUsageContentFooter />
+          </TokenUsageContent>
+        </TokenUsage>
       </ContextPanelHeader>
       <ContextPanelBody root={<ContextRailRoot />} detail={<ContextRailDetail />} />
     </ContextPanel>

package/src/artifact.tsx

@@ -67,18 +67,21 @@ export const ArtifactClose = ({
   size = "sm",
   variant = "ghost",
   ...props
-}: ArtifactCloseProps) => (
-  <Button
-    className={cn("size-8 p-0 text-muted-foreground hover:text-foreground", className)}
-    size={size}
-    type="button"
-    variant={variant}
-    {...props}
-  >
-    {children ?? <XIcon className="size-4" />}
-    <span className="sr-only">Close</span>
-  </Button>
-);
+}: ArtifactCloseProps) => {
+  const { t } = useLocale();
+  return (
+    <Button
+      className={cn("size-8 p-0 text-muted-foreground hover:text-foreground", className)}
+      size={size}
+      type="button"
+      variant={variant}
+      {...props}
+    >
+      {children ?? <XIcon className="size-4" />}
+      <span className="sr-only">{t("close")}</span>
+    </Button>
+  );
+};
 
 export type ArtifactTitleProps = HTMLAttributes<HTMLParagraphElement>;
 

package/src/audio-player.test.tsx

@@ -0,0 +1,78 @@
+/**
+ * Issue #33 — `media-chrome` is an OPTIONAL peer of `@elabs-ai/components-ai`,
+ * reached only through `lazy(() => import("./_audio-player-media-chrome"))`
+ * (ADR 0019, `lazyPart` in `audio-player.tsx`). A REJECTED `lazy()` import
+ * throws during render — `Suspense` alone does not catch that (it only covers
+ * the pending state) — so every exported part is wrapped in
+ * `LazyEngineBoundary` (`_lazy-engine-boundary.tsx`). This locks that the
+ * boundary falls back gracefully for the top-level `AudioPlayer` AND for a
+ * sub-control, instead of taking the tree down.
+ *
+ * `vi.mock` factories are hoisted, so the mock itself must resolve
+ * successfully (a factory that throws or rejects gets intercepted by
+ * Vitest's OWN "error when mocking a module" diagnostic instead of the
+ * message this test needs — see `interactive-terminal-missing-peer.test.tsx`
+ * for the same finding). So the module resolves fine and the simulated
+ * failure instead comes from each named export THROWING when React renders
+ * it — a real render-phase error, which is exactly what `LazyEngineBoundary`
+ * exists to catch.
+ *
+ * The top-level `AudioPlayer` case asserts a SETTLED, non-loading notice
+ * (never a permanent `Skeleton`) — a loading placeholder left in place after
+ * the load has definitively failed reads as "still loading, forever", which
+ * `.claude/rules/loading-states.md` treats as a defect, not a graceful
+ * fallback. See `AudioPlayerMissing` in `audio-player.tsx`.
+ */
+import { act, cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./_audio-player-media-chrome", () => ({
+  AudioPlayer: () => {
+    throw new Error("Cannot find module 'media-chrome'");
+  },
+  AudioPlayerPlayButton: () => {
+    throw new Error("Cannot find module 'media-chrome'");
+  },
+}));
+
+import { AudioPlayer, AudioPlayerPlayButton } from "./audio-player";
+
+afterEach(cleanup);
+
+const flush = () => act(async () => void (await new Promise((resolve) => setTimeout(resolve, 0))));
+
+describe("AudioPlayer — missing optional peer (#33)", () => {
+  it("falls back to a settled, actionable notice — never a permanent skeleton — when media-chrome fails to load", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    render(<AudioPlayer />);
+    await flush();
+
+    // The tree survived, and it settled: no permanent loading placeholder
+    // (a `Skeleton` left in place after a definitive failure would read as
+    // "still loading, forever" — the bug this locks against), and the
+    // notice names the exact missing package via `role="status"` (a missing
+    // optional peer is a capability gap, not a broken component).
+    const notice = screen.getByRole("status");
+    expect(notice).toHaveTextContent(/media-chrome/i);
+    expect(document.querySelector('[class*="animate-pulse"]')).toBeNull();
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  it("degrades a sub-control to nothing rather than crashing", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const { container } = render(<AudioPlayerPlayButton />);
+    await flush();
+
+    // `renderMissing={() => null}` for sub-controls — an empty, but intact,
+    // tree beats a crash.
+    expect(container).toBeEmptyDOMElement();
+    expect(errorSpy).toHaveBeenCalled();
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+
+    errorSpy.mockRestore();
+  });
+});