@elabs-ai/components-ai 4.0.0 → 4.1.0

package/src/_mermaid-error-panel.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+/**
+ * The `errorComponent` Streamdown renders in place of a Mermaid diagram that
+ * failed (issue #33). Streamdown hands back the render failure as a plain
+ * STRING (`MermaidErrorComponentProps.error`, already reduced from whatever
+ * was thrown), so this distinguishes two different failures by matching that
+ * string rather than the original error object:
+ *
+ * - **The optional `mermaid` peer is not installed.** This is a CAPABILITY
+ *   GAP, not something wrong with the diagram or the app — the same class as
+ *   `@elabs-ai/components-viewer`'s `parser-missing`
+ *   (@.claude/rules/viewer-components.md "A capability gap is not a
+ *   failure"). Renders the neutral `StatePanel kind="empty"`, naming the
+ *   package to install, announced `role="status"`, with no retry action
+ *   (re-installing a dependency does not happen by clicking a button in the
+ *   page).
+ * - **Anything else is a genuine render/syntax failure** — a real error, so
+ *   it gets `StatePanel kind="error"` (`role="alert"`, set internally by
+ *   `StatePanel`) wired to Streamdown's own `retry()`, which increments the
+ *   render attempt and re-runs the diagram.
+ */
+import { Button, StatePanel, isModuleNotFoundMessage, useLocale } from "@elabs-ai/components-ui";
+import { EyeOffIcon } from "lucide-react";
+
+export interface MermaidErrorPanelProps {
+  chart: string;
+  error: string;
+  retry: () => void;
+}
+
+export function MermaidErrorPanel({ error, retry }: MermaidErrorPanelProps) {
+  const { t } = useLocale();
+
+  if (isModuleNotFoundMessage(error)) {
+    const feature = t("ai.mermaid.feature");
+    return (
+      <div className="my-4" role="status" aria-live="polite">
+        <StatePanel
+          kind="empty"
+          // A dashed edge invites a drop; this panel accepts nothing. Solid —
+          // mirrors `@elabs-ai/components-viewer`'s `FileViewerError`.
+          className="border-solid"
+          icon={<EyeOffIcon aria-hidden="true" />}
+          title={t("ai.error.engineMissing", { feature })}
+          description={t("ai.error.engineMissingBody", { feature, packages: "mermaid" })}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className="my-4">
+      <StatePanel
+        kind="error"
+        title={t("ai.mermaid.renderError")}
+        description={error}
+        actions={
+          <Button size="sm" variant="outline" onClick={retry}>
+            {t("ai.error.retry")}
+          </Button>
+        }
+      />
+    </div>
+  );
+}

package/src/_persona-rive.tsx

@@ -19,17 +19,45 @@
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { useReducedMotion } from "@elabs-ai/components-tokens";
 import type { RiveParameters } from "@rive-app/react-webgl2";
-import {
+// `import type` from an optional peer is safe HERE ONLY because this module is
+// reached exclusively through `lazy(() => import("./_persona-rive"))` — it is
+// never statically imported, so nothing in this file reaches the barrel's
+// `.d.ts` declaration graph. `persona.tsx`'s PUBLIC types must never do this
+// (issue #101) — see its module doc comment and `PersonaRiveEvent`/
+// `PersonaRiveEventCallback`, which this module imports below and proves
+// conformant against the real peer type at the bottom of this file.
+// A NAMED import (`import { useRive } from "@rive-app/react-webgl2"`) is a
+// static ESM binding a bundler must resolve at build time. Now that
+// `@rive-app/react-webgl2` is a genuinely optional peer (issue #33), a
+// consumer who has not installed it hits that resolution at the worst
+// possible time: Vite's own optional-peer-dependency handling swaps in a
+// build-time stub with no exports, and Rollup's static named-export check
+// then fails the WHOLE APP BUILD — not a runtime error `LazyEngineBoundary`
+// could ever see (confirmed against `fixtures/consumer-smoke`'s real Vite
+// build). A namespace import defers every one of these to a plain property
+// lookup, which Rollup does not statically validate, so the build always
+// succeeds; a genuinely missing peer instead resolves the destructured hooks
+// below to `undefined`, and the guard turns that into the render-phase throw
+// `LazyEngineBoundary` (see `persona.tsx`) already catches.
+import * as RiveModule from "@rive-app/react-webgl2";
+import type { ReactNode } from "react";
+import { memo, useEffect, useMemo, useRef, useState } from "react";
+
+import type { AssertAssignable } from "./_lazy-boundary-conformance";
+import type { PersonaRiveEventCallback } from "./persona";
+import type { PersonaSource, PersonaState } from "./persona-sources";
+
+const {
   useRive,
   useStateMachineInput,
   useViewModel,
   useViewModelInstance,
   useViewModelInstanceColor,
-} from "@rive-app/react-webgl2";
-import type { ReactNode } from "react";
-import { memo, useEffect, useMemo, useRef, useState } from "react";
+} = RiveModule;
 
-import type { PersonaSource, PersonaState } from "./persona-sources";
+if (!useRive) {
+  throw new Error("Cannot find module '@rive-app/react-webgl2'");
+}
 
 // Delays Rive initialization by one frame so that React Strict Mode's
 // immediate unmount cycle never creates a WebGL2 context. Only the
@@ -139,12 +167,12 @@ PersonaWithoutModel.displayName = "PersonaWithoutModel";
 
 export interface PersonaRiveProps {
   className?: string;
-  onLoad?: RiveParameters["onLoad"];
-  onLoadError?: RiveParameters["onLoadError"];
-  onPause?: RiveParameters["onPause"];
-  onPlay?: RiveParameters["onPlay"];
+  onLoad?: PersonaRiveEventCallback;
+  onLoadError?: PersonaRiveEventCallback;
+  onPause?: PersonaRiveEventCallback;
+  onPlay?: PersonaRiveEventCallback;
   onReady?: () => void;
-  onStop?: RiveParameters["onStop"];
+  onStop?: PersonaRiveEventCallback;
   source: PersonaSource;
   /** Resolved `.riv` URL — `Persona`'s `src` override, or the variant default. */
   src: string;
@@ -250,3 +278,27 @@ const PersonaRive = ({
 };
 
 export default PersonaRive;
+
+/**
+ * Conformance assertion (issue #101): compile-time proof that the owned
+ * `PersonaRiveEventCallback` (declared in `persona.tsx`, structurally free of
+ * `@rive-app/react-webgl2`/`@rive-app/webgl2`) is still assignable to the REAL
+ * `RiveParameters["onLoad"]` — and, since `onLoad`/`onLoadError`/`onPause`/
+ * `onPlay`/`onStop` all share Rive's one `EventCallback` type, this single
+ * check covers all five. `AssertAssignable`'s type parameter is constrained
+ * (`TOwned extends TReal`), so if a future Rive release changes `Event`'s
+ * shape in a way `PersonaRiveEvent` no longer satisfies, this line fails to
+ * typecheck — caught by `pnpm --filter @elabs-ai/components-ai typecheck`
+ * locally, never shipped as a silent mismatch to a consumer.
+ *
+ * `AssertAssignable` itself is shared with `_audio-player-media-chrome.tsx`
+ * via `_lazy-boundary-conformance.ts` — see that module's doc comment for
+ * what this check can and cannot prove (it is one-directional: it cannot
+ * catch the owned type being NARROWER than the real one, which is exactly
+ * what `PersonaRiveEvent["data"]` is — see the CHANGELOG's "Breaking (types)"
+ * entry).
+ */
+export type _PersonaRiveEventCallbackConformance = AssertAssignable<
+  PersonaRiveEventCallback,
+  NonNullable<RiveParameters["onLoad"]>
+>;

package/src/_streamdown-i18n.ts

@@ -36,6 +36,7 @@ import { useEffect, useMemo, useState } from "react";
 import type { StreamdownTranslations } from "streamdown";
 import { buildCodeBlockTheme } from "./_code-block-theme";
 import { lazyMermaid } from "./_lazy-mermaid";
+import { MermaidErrorPanel } from "./_mermaid-error-panel";
 
 /**
  * Reactive replacement for `@streamdown/code`'s pre-configured `code` export
@@ -47,7 +48,7 @@ import { lazyMermaid } from "./_lazy-mermaid";
  *
  * Streamdown's dual-theme mechanism (`createCodePlugin({ themes: [light, dark] })`)
  * expects exactly TWO themes and picks between them purely via the `.dark` CSS
- * selector — but brand-ui ships THREE themes (light/dark),
+ * selector — but brand-ui ships EVERY theme, not just Shiki's light/dark,
  * and any dark-declaring theme matches `.dark` too (see `_code-block-theme.ts`). Passing a real
  * light/dark PAIR would still force such a theme into the dark slot. Instead
  * this pins BOTH slots to `buildCodeBlockTheme()` — the SAME brand-token-derived
@@ -95,6 +96,25 @@ export function useStreamdownPlugins() {
   return useMemo(() => ({ cjk, code, math, mermaid: lazyMermaid }), [code]);
 }
 
+/**
+ * The top-level Streamdown `mermaid` prop (distinct from `plugins.mermaid`,
+ * the LAZY `DiagramPlugin` `useStreamdownPlugins()` wires above) — this is
+ * where a FAILED render is caught (issue #33). Streamdown hands its
+ * `errorComponent` a plain STRING describing what went wrong;
+ * `MermaidErrorPanel` decides whether that string names a missing optional
+ * peer (`mermaid` not installed — a capability gap, `StatePanel kind="empty"`)
+ * or a genuine diagram render failure (`StatePanel kind="error"`, with retry).
+ *
+ * A stable module-level object, not a fresh one per render: Streamdown only
+ * re-reads `mermaid.errorComponent` when this reference changes, and
+ * `MermaidErrorPanel` never varies at runtime. Exported as a hook to match
+ * `useStreamdownPlugins()`'s call-site shape.
+ */
+const MERMAID_OPTIONS = { errorComponent: MermaidErrorPanel };
+export function useStreamdownMermaidOptions() {
+  return MERMAID_OPTIONS;
+}
+
 /*
  * The translation MAP moved down to `@elabs-ai/components-ui`
  * (`lib/streamdown-translations.ts`) when `@elabs-ai/components-viewer`

package/src/_streamdown-safety.ts

@@ -0,0 +1,170 @@
+/**
+ * The runtime half of the #36 fix (the type-level `Omit` is the other half — see
+ * `MarkdownViewProps`/`MessageResponseProps`).
+ *
+ * Streamdown installs its sanitiser chain (`rehype-raw` → `rehype-sanitize` →
+ * `rehype-harden`) as the DEFAULT VALUE of its `rehypePlugins` prop — a plain
+ * JS default parameter. Supplying the prop REPLACES the whole chain; there is
+ * no merge (verified against `streamdown@2.5.0`'s `dist/chunk-BO2N2NFS.js`:
+ * `xt = { raw, sanitize, harden }; gn = Object.values(xt)` is the default, and
+ * the component signature reads `rehypePlugins: a = gn`).
+ *
+ * `MarkdownView`/`MessageResponse` render UNTRUSTED, model-authored markdown,
+ * so that prop may never reach `<Streamdown>` — not even through a plain
+ * JavaScript consumer, an `as any`/`as never` cast, or a wider
+ * `{...spreadProps}` object a type-level `Omit` cannot see at runtime. `Omit`
+ * closes the TypeScript surface; this function closes the runtime one. Both
+ * are required — see issue #36.
+ *
+ * `remarkPlugins` is deliberately NOT stripped (PR #74 review, round 1). It is
+ * the same *shape* of prop — a consumer array replaces Streamdown's own remark
+ * defaults (`gfm`, `codeMeta`) rather than merging with them — but it is NOT a
+ * sanitiser override: the remark stage runs strictly UPSTREAM of the rehype
+ * chain, and Streamdown derives its rehype list without reading `remarkPlugins`
+ * at all. Anything a remark plugin injects — a raw `html` mdast node, a
+ * `data.hName`/`hChildren` hast element, an `onerror` via `hProperties`, a
+ * `javascript:` link URL, a smuggled `raw` hast child — still passes through
+ * `rehype-raw` → `rehype-sanitize` → `rehype-harden` before it can reach the
+ * DOM. Measured with this strip removed: all five channels executed and none
+ * produced a `<script>`, an `[onerror]` attribute or a `javascript:` href,
+ * while the identical payload injected AFTER the sanitiser did. Stripping it
+ * therefore removed real capability (remark-directive, footnotes, custom
+ * syntax) and closed nothing.
+ *
+ * If a consumer needs to widen what survives SANITISATION, `allowedTags` /
+ * `literalTagContent` are the supported seam: they MERGE into the sanitize
+ * schema instead of replacing the pipeline outright.
+ *
+ * THIS LIST HAS A PARITY COUNTERPART, AND EDITING ONE SIDE FAILS CI (#75).
+ * `scripts/check-sanitizer-passthrough.mjs` declares the same key set as
+ * `SAFE_RENDERERS[streamdown].dangerousProps` and reads THIS array literal back
+ * out of this file, asserting set-equality in BOTH directions — so removing a
+ * key here (the runtime stops stripping it) and removing a key there (the gate
+ * stops looking for it) are each a red build, and so is renaming the constant
+ * or rewriting it into a shape the gate cannot parse. Change the key set in
+ * both places, in the same commit, or don't change it.
+ */
+const SANITIZER_OVERRIDE_KEYS = ["rehypePlugins"] as const;
+
+/**
+ * Deletes `rehypePlugins` off `props` in place (if present) and warns in dev.
+ * Call this BEFORE spreading `props` onto `<Streamdown>`.
+ *
+ * Takes a plain object rather than a typed `MarkdownViewProps`/
+ * `MessageResponseProps` on purpose: the whole point is to catch a value that
+ * reached this call with a wider runtime shape than its type says (a `.tsx`
+ * consumer with no type checking at all, a force-cast, a spread of a bigger
+ * object) — a parameter typed to the post-`Omit` props would only accept
+ * values TypeScript already believes are safe.
+ */
+export function stripSanitizerOverrides(props: object): void {
+  const record = props as Record<string, unknown>;
+  for (const key of SANITIZER_OVERRIDE_KEYS) {
+    if (key in record) {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          `[@elabs-ai/components-ai] \`${key}\` is not a supported prop on this component: ` +
+            "it would replace Streamdown's default sanitiser chain (rehype-raw → " +
+            "rehype-sanitize → rehype-harden) and let untrusted markdown execute " +
+            "script in the host page. The value was ignored. Use `allowedTags` / " +
+            "`literalTagContent` to widen sanitisation instead — see issue #36.",
+        );
+      }
+      delete record[key];
+    }
+  }
+}
+
+/**
+ * The CONVERSE of `SANITIZER_OVERRIDE_KEYS`: the plugin slots that deliberately
+ * stay reachable even though they land in the DOM *after* — or entirely outside
+ * — Streamdown's sanitiser chain (#76).
+ *
+ * - **`math.rehypePlugin` is APPENDED to the END of the rehype pipeline**, i.e.
+ *   after `rehype-raw` → `rehype-sanitize` → `rehype-harden` (verified against
+ *   `streamdown@2.5.0`'s `dist/chunk-BO2N2NFS.js`). Its output is never
+ *   re-sanitised.
+ * - **`mermaid` never enters the rehype/remark pipeline at all.** Its
+ *   `getMermaid().render()` result is written via `dangerouslySetInnerHTML`
+ *   (streamdown's only such sink). brand-ui's own default pins mermaid's
+ *   `securityLevel: "strict"` (`_lazy-mermaid.ts`).
+ *
+ * `cjk` (remark-stage, re-sanitised downstream), `code` (feeds `shikiTheme`
+ * only) and `renderers` (ordinary React components) are NOT trust-bearing and
+ * are deliberately absent — a warning that fired on them would be noise
+ * consumers learn to ignore.
+ *
+ * **This is not a live vulnerability and must not be described as one.**
+ * Supplying an executable `Pluggable` takes code in the consuming app's own
+ * bundle, and an app author who can do that can already run code. The real,
+ * non-hypothetical hazard is MISCONFIGURATION — most sharply KaTeX's `trust`
+ * option (needed for anything beyond `singleDollarTextMath`/`errorColor`),
+ * which silently disables KaTeX's own sanitisation for model-authored content
+ * the consumer never intended to trust. Hence: WARN, never strip. Stripping
+ * would break the legitimate trusted use and is the breaking change #76
+ * explicitly rejects — `markdown-view.test.tsx`/`message.test.tsx` pin the slot
+ * OPEN so a future "hardening" fails loudly.
+ */
+const TRUSTED_PLUGIN_SLOT_ADVICE =
+  "This is a supported, TRUSTED-CODE seam — the plugin still runs and nothing was " +
+  "dropped — so treat it as code you ship: it can put arbitrary markup in the page. " +
+  "If you only needed KaTeX options, prefer `createMathPlugin({ singleDollarTextMath, " +
+  "errorColor })` and leave KaTeX's `trust` option off for model-authored content. " +
+  "See docs/CSP-AND-NETWORK.md and issue #76.";
+
+const isPluginObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+/**
+ * Dev-only `console.warn` when a consumer's `plugins` override replaces one of
+ * the two slots that are NOT upstream of the sanitiser. Call it where the
+ * consumer's overrides are merged over the internal defaults, passing both.
+ *
+ * **Reference-equality comparator, deliberately — not truthiness, not a deep
+ * compare.** `useStreamdownPlugins()` returns a FRESH `code` object on every
+ * theme change but a STABLE `math`/`mermaid`, so a truthiness check would fire
+ * on every theme flip and a deep-equality check would stay silent for a consumer
+ * who rebuilds an equivalent-looking object each render. For `math` the
+ * comparison narrows further to the `rehypePlugin` member itself, so changing
+ * only `remarkPlugin`/`getStyles` (upstream of, or outside, the DOM sink) stays
+ * silent.
+ *
+ * Warns; never mutates. `stripSanitizerOverrides` is the other half of the
+ * boundary — the props that must never be reachable at all.
+ */
+export function warnOnTrustedPluginSlots(overrides: object | undefined, internal: object): void {
+  if (process.env.NODE_ENV === "production") return;
+  if (!overrides) return;
+  const consumer = overrides as Record<string, unknown>;
+  const defaults = internal as Record<string, unknown>;
+
+  if (isPluginObject(consumer.math)) {
+    const theirs = consumer.math.rehypePlugin;
+    const ours = isPluginObject(defaults.math) ? defaults.math.rehypePlugin : undefined;
+    if (theirs !== ours) {
+      console.warn(
+        "[@elabs-ai/components-ai] `plugins.math.rehypePlugin` is appended to the END of " +
+          "Streamdown's rehype pipeline, so it runs AFTER the sanitiser chain " +
+          "(rehype-raw → rehype-sanitize → rehype-harden) and whatever it emits is never " +
+          `re-sanitised. ${TRUSTED_PLUGIN_SLOT_ADVICE}`,
+      );
+    }
+  }
+
+  if (isPluginObject(consumer.mermaid) && consumer.mermaid !== defaults.mermaid) {
+    // The message describes React's `dangerouslySetInnerHTML` in prose rather than
+    // naming the identifier: `pnpm csp-sinks:check` preserves string literals on
+    // purpose (a sink hidden in a string is still a sink), so spelling the prop out
+    // inside this warning makes the gate read THIS file as a new HTML-assigning
+    // module. Comments like this one are stripped by that gate, so the name is safe
+    // here and in the TSDoc above — just not inside a runtime string.
+    console.warn(
+      "[@elabs-ai/components-ai] `plugins.mermaid` never enters the rehype pipeline at " +
+        "all: its rendered SVG is injected as raw HTML through React's dangerous " +
+        "inner-HTML prop, i.e. after and outside the sanitiser chain " +
+        "(rehype-raw → rehype-sanitize → rehype-harden). A " +
+        "replacement plugin must sanitise its own output — brand-ui's default pins " +
+        `mermaid's strict security level. ${TRUSTED_PLUGIN_SLOT_ADVICE}`,
+    );
+  }
+}

package/src/agent-event.stories.tsx

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { AgentEvent } from "./agent-event";
+import { AgentStep, AgentTimeline } from "./agent-timeline";
+
+const meta = {
+  title: "AI/AgentEvent",
+  component: AgentEvent,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT lifecycle/guard event line; the console skin is `Terminal/TerminalEventLine`, and both read the same `AgentEventPhase` / `AgentEventOutcome` / `CheckSummary` model from `@elabs-ai/components-ui` — see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). It is an `AgentStep` VARIANT on the existing `AI/AgentTimeline` rail, not a second spine: the same ordered list, distinguished by glyph and label.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof AgentEvent>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// A lifecycle event with no gated action — an AgentStep variant on the SAME
+// rail, distinguished from an ordinary step by glyph + label only (#109).
+export const Default: Story = {
+  render: () => (
+    <AgentTimeline className="max-w-prose">
+      <AgentEvent label="user_prompt_submit" phase="lifecycle" outcome="ok" />
+    </AgentTimeline>
+  ),
+};
+
+// One hook firing before a tool call and one firing after — the event-level
+// `phase` ("before" | "after" | "lifecycle") is a separate, wider prop than
+// any individual check's own `phase`.
+export const BeforeAndAfterHooks: Story = {
+  render: () => (
+    <AgentTimeline className="max-w-prose">
+      <AgentEvent label="pre_tool_use" phase="before" outcome="ok" durationMs={42} />
+      <AgentEvent label="post_tool_use" phase="after" outcome="ok" durationMs={128} />
+    </AgentTimeline>
+  ),
+};
+
+// checks as a count summary — "passed/ran" rendered as plain text.
+export const CheckSummaryCount: Story = {
+  render: () => (
+    <AgentTimeline className="max-w-prose">
+      <AgentEvent
+        label="pre_tool_use"
+        phase="before"
+        outcome="ok"
+        durationMs={210}
+        checks={{ ran: 4, passed: 4 }}
+      />
+    </AgentTimeline>
+  ),
+};
+
+// checks as individual verdicts — a blocked event whose gate had a failing
+// check. Pass/fail never rides colour alone: each row pairs a distinct icon
+// with visible "Passed"/"Failed" text (see accessibility.md's greyscale test).
+export const BlockedWithFailingCheck: Story = {
+  render: () => (
+    <AgentTimeline className="max-w-prose">
+      <AgentEvent
+        label="pre_tool_use"
+        phase="before"
+        outcome="blocked"
+        durationMs={340}
+        checks={[
+          { label: "policy: no secrets", ok: true, durationMs: 12 },
+          { label: "policy: write scope", ok: false, detail: "path escapes workspace root" },
+        ]}
+      />
+    </AgentTimeline>
+  ),
+};
+
+// A failed hook alongside ordinary AgentStep entries, proving AgentEvent
+// rides the same <ol> rail as any other step — no second spine (#109 AC1).
+export const WithinAgentTimeline: Story = {
+  name: "Alongside AgentStep on one rail",
+  render: () => (
+    <AgentTimeline className="max-w-prose">
+      <AgentEvent label="user_prompt_submit" phase="lifecycle" outcome="ok" />
+      <AgentStep status="complete" name="Searched financial filings" summary="3 documents" />
+      <AgentEvent
+        label="post_tool_use"
+        phase="after"
+        outcome="failed"
+        durationMs={95}
+        checks={[{ label: "output schema", ok: false, detail: "missing required field: total" }]}
+      />
+      <AgentEvent label="stop" phase="lifecycle" outcome="ok" durationMs={64200} />
+    </AgentTimeline>
+  ),
+};

package/src/agent-event.test.tsx

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { AgentEvent } from "./agent-event";
+import { AgentStep, AgentTimeline } from "./agent-timeline";
+
+describe("AgentEvent (#109)", () => {
+  it("renders on the same <ol> rail as an AgentStep — no second spine", () => {
+    render(
+      <AgentTimeline data-testid="timeline">
+        <AgentStep name="Queried finance.revenue" status="complete" />
+        <AgentEvent label="pre_tool_use" outcome="ok" />
+      </AgentTimeline>,
+    );
+    expect(screen.getByTestId("timeline").tagName).toBe("OL");
+    const items = screen.getAllByRole("listitem");
+    expect(items).toHaveLength(2);
+    // The AgentEvent item carries the same data-slot as any other li in this
+    // rail's list structure, and is reachable via getAllByRole("listitem")
+    // exactly like AgentStep — i.e. one list, not a nested second rail.
+    expect(items[1]).toHaveAttribute("data-slot", "agent-event");
+  });
+
+  it("maps outcome onto the existing closed Status — no new status value", () => {
+    const { rerender } = render(
+      <AgentTimeline>
+        <AgentEvent label="stop" outcome="ok" />
+      </AgentTimeline>,
+    );
+    expect(screen.getByRole("listitem")).toHaveAttribute("data-status", "complete");
+
+    rerender(
+      <AgentTimeline>
+        <AgentEvent label="pre_tool_use" outcome="blocked" />
+      </AgentTimeline>,
+    );
+    expect(screen.getByRole("listitem")).toHaveAttribute("data-status", "denied");
+
+    rerender(
+      <AgentTimeline>
+        <AgentEvent label="post_tool_use" outcome="failed" />
+      </AgentTimeline>,
+    );
+    expect(screen.getByRole("listitem")).toHaveAttribute("data-status", "failed");
+  });
+
+  it("renders the label and, when given, the event-level phase as visible text", () => {
+    render(
+      <AgentTimeline>
+        <AgentEvent label="user_prompt_submit" phase="lifecycle" outcome="ok" />
+      </AgentTimeline>,
+    );
+    expect(screen.getByText("user_prompt_submit")).toBeInTheDocument();
+    // The phase renders as its own data-slot part, distinct from the
+    // per-check `phase` field on CheckResult (never the same prop/slot), and
+    // carries real, non-empty visible text.
+    const phaseNode = document.querySelector('[data-slot="agent-event-phase"]');
+    expect(phaseNode).not.toBeNull();
+    expect(phaseNode?.textContent?.trim()).toBeTruthy();
+  });
+
+  it("renders no phase part when phase is omitted", () => {
+    render(
+      <AgentTimeline>
+        <AgentEvent label="post_tool_use" outcome="ok" />
+      </AgentTimeline>,
+    );
+    expect(document.querySelector('[data-slot="agent-event-phase"]')).toBeNull();
+  });
+
+  it("renders a failed check distinguishably from a passed one in ACCESSIBLE TEXT, not only a colour class", () => {
+    render(
+      <AgentTimeline>
+        <AgentEvent
+          label="post_tool_use"
+          outcome="failed"
+          checks={[
+            { label: "eslint", ok: true },
+            { label: "tsc", ok: false, detail: "2 errors" },
+          ]}
+        />
+      </AgentTimeline>,
+    );
+
+    const passRow = screen.getByText("eslint").closest('[data-slot="agent-event-check"]');
+    const failRow = screen.getByText("tsc").closest('[data-slot="agent-event-check"]');
+    expect(passRow).not.toBeNull();
+    expect(failRow).not.toBeNull();
+
+    // data-ok is a machine attribute — not itself sufficient (invisible to AT).
+    expect(passRow).toHaveAttribute("data-ok", "true");
+    expect(failRow).toHaveAttribute("data-ok", "false");
+
+    // The ACCESSIBLE TEXT differs between the two rows: the status-word node's
+    // text content is not the same string for a pass vs a fail. This holds
+    // whether `t()` resolves a registered translation or falls back to the
+    // raw key, so the assertion does not hardcode "Passed"/"Failed" copy that
+    // this package does not own.
+    const passStatus = passRow?.querySelector('[data-slot="agent-event-check-status"]');
+    const failStatus = failRow?.querySelector('[data-slot="agent-event-check-status"]');
+    expect(passStatus?.textContent).toBeTruthy();
+    expect(failStatus?.textContent).toBeTruthy();
+    expect(passStatus?.textContent).not.toBe(failStatus?.textContent);
+
+    // The failing check's detail line is also visible, real text (not only color).
+    expect(screen.getByText("2 errors")).toBeInTheDocument();
+  });
+
+  it("renders a CheckSummary as passed/ran text instead of a row list", () => {
+    // Numeric interpolation into the localized "passed/ran" copy is exercised
+    // by the shared `t()`/messages machinery elsewhere (this package does not
+    // own `messages.ts` — see the message keys reported alongside this
+    // component). Here we assert the STRUCTURAL contract: a count summary
+    // renders one text node in the summary slot, never the per-row list.
+    render(
+      <AgentTimeline>
+        <AgentEvent label="pre_tool_use" outcome="ok" checks={{ ran: 4, passed: 3 }} />
+      </AgentTimeline>,
+    );
+    const summary = document.querySelector('[data-slot="agent-event-checks-summary"]');
+    expect(summary).not.toBeNull();
+    expect(summary?.textContent?.trim()).toBeTruthy();
+    expect(document.querySelector('[data-slot="agent-event-checks"]')).toBeNull();
+  });
+
+  it("renders duration via the shared formatElapsed, not a second formatter", () => {
+    render(
+      <AgentTimeline>
+        <AgentEvent label="stop" outcome="ok" durationMs={8000} />
+      </AgentTimeline>,
+    );
+    // formatElapsed(8000) === "8.0s" (packages/ui/src/lib/format-duration.ts)
+    expect(screen.getByText("8.0s")).toBeInTheDocument();
+  });
+
+  it("merges className and spreads props on the underlying li, like AgentStep", () => {
+    render(
+      <AgentTimeline>
+        <AgentEvent label="stop" className="custom-event" aria-label="event" />
+      </AgentTimeline>,
+    );
+    const li = screen.getByRole("listitem");
+    expect(li).toHaveClass("custom-event");
+    expect(li).toHaveAttribute("aria-label", "event");
+  });
+});