@elabs-ai/components-ai 4.0.0 → 4.2.0

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/rules/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: the `trusted-types-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/_theme-scope-store.test.ts

@@ -0,0 +1,83 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  _debugActiveThemeScopeCount,
+  getThemeScope,
+  useThemeScopeRevision,
+} from "./_theme-scope-store";
+
+afterEach(() => {
+  document.documentElement.removeAttribute("data-theme");
+  document.body.innerHTML = "";
+});
+
+describe("getThemeScope", () => {
+  it("resolves the nearest data-theme ancestor, falling back to <html>", () => {
+    expect(getThemeScope(document.body)).toBe(document.documentElement);
+
+    const scoped = document.createElement("div");
+    scoped.setAttribute("data-theme", "dark");
+    document.body.append(scoped);
+    expect(getThemeScope(scoped)).toBe(scoped);
+  });
+});
+
+describe("useThemeScopeRevision (perf review §3.3)", () => {
+  it("bumps the revision when the scoped element's data-theme mutates", async () => {
+    const { result } = renderHook(() => useThemeScopeRevision(document.documentElement));
+    const before = result.current;
+
+    document.documentElement.setAttribute("data-theme", "dark");
+
+    await waitFor(() => expect(result.current).toBe(before + 1));
+  });
+
+  it("shares ONE MutationObserver across every subscriber of the same scope", async () => {
+    const before = _debugActiveThemeScopeCount();
+    const hookA = renderHook(() => useThemeScopeRevision(document.documentElement));
+    const hookB = renderHook(() => useThemeScopeRevision(document.documentElement));
+    const hookC = renderHook(() => useThemeScopeRevision(document.documentElement));
+
+    // Three subscribers to the SAME scope element register as exactly one
+    // tracked scope, not three — this is the fix: previously each caller
+    // (CodeBlockContent, useReactiveCodePlugin) instantiated its own
+    // MutationObserver on the same ancestor.
+    expect(_debugActiveThemeScopeCount()).toBe(before + 1);
+
+    document.documentElement.setAttribute("data-theme", "dark");
+
+    // Every subscriber still gets notified through the single observer.
+    await waitFor(() => expect(hookA.result.current).toBe(1));
+    expect(hookB.result.current).toBe(1);
+    expect(hookC.result.current).toBe(1);
+
+    hookA.unmount();
+    hookB.unmount();
+    expect(_debugActiveThemeScopeCount()).toBe(before + 1); // still one listener left (hookC)
+    hookC.unmount();
+    expect(_debugActiveThemeScopeCount()).toBe(before); // the observer is disconnected once unused
+  });
+
+  it("scopes to the closest [data-theme] ancestor, not always <html>", async () => {
+    const outer = document.createElement("div");
+    outer.setAttribute("data-theme", "light");
+    const inner = document.createElement("div");
+    inner.setAttribute("data-theme", "dark");
+    outer.append(inner);
+    document.body.append(outer);
+
+    const { result } = renderHook(() => useThemeScopeRevision(inner));
+    const before = result.current;
+
+    // A mutation on the OUTER (non-closest) ancestor must not affect a
+    // consumer scoped to the inner region. There is nothing to `waitFor`
+    // here (a NEGATIVE assertion), so flush the microtask queue directly.
+    outer.setAttribute("data-theme", "light-updated");
+    await Promise.resolve();
+    expect(result.current).toBe(before);
+
+    // A mutation on the actually-closest scope element does.
+    inner.setAttribute("data-theme", "light");
+    await waitFor(() => expect(result.current).toBe(before + 1));
+  });
+});

package/src/_theme-scope-store.ts

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * Shared, ref-counted `data-theme` observation (perf review §3.3).
+ *
+ * `code-block.tsx`'s `CodeBlockContent` and `_streamdown-i18n.ts`'s
+ * `useReactiveCodePlugin` each used to instantiate their OWN
+ * `MutationObserver` to notice a `data-theme` flip and re-derive the Shiki
+ * theme — one observer PER rendered `CodeBlock`/`MessageResponse`/
+ * `MarkdownView` instance, all typically watching the exact same ancestor. In
+ * a message-dense conversation that is dozens of redundant observers doing
+ * the same job.
+ *
+ * This module keeps exactly ONE `MutationObserver` per distinct scope
+ * element (ref-counted: the observer is created on the first subscriber and
+ * disconnected when the last one unsubscribes), and exposes it through
+ * `useSyncExternalStore` so React's own re-render batching applies.
+ */
+import { useCallback, useSyncExternalStore } from "react";
+
+/**
+ * Nearest ancestor (inclusive) carrying `data-theme`, defaulting to `<html>`.
+ * Lets a themed surface rendered inside a region-scoped
+ * `<div data-theme="…">` (a supported `ThemeProvider`/decorator pattern —
+ * see @.claude/rules/theming.md) resolve THAT region's tokens instead of
+ * always the document root's.
+ */
+export function getThemeScope(el: Element | null): Element | null {
+  return (
+    el?.closest("[data-theme]") ??
+    (typeof document !== "undefined" ? document.documentElement : null)
+  );
+}
+
+interface ScopeEntry {
+  observer: MutationObserver;
+  revision: number;
+  listeners: Set<() => void>;
+}
+
+const scopes = new Map<Element, ScopeEntry>();
+
+function subscribe(scope: Element | null, onStoreChange: () => void): () => void {
+  if (!scope) return () => {};
+
+  let entry = scopes.get(scope);
+  if (!entry) {
+    // `entry` is assigned before `observer` fires, but TypeScript can't see
+    // that through the closure — the callback only ever runs after this
+    // function returns and `entry` has been set, and every existing
+    // subscriber to this scope uses the SAME entry.
+    const created: ScopeEntry = {
+      listeners: new Set(),
+      observer: new MutationObserver(() => {
+        created.revision += 1;
+        for (const listener of created.listeners) listener();
+      }),
+      revision: 0,
+    };
+    created.observer.observe(scope, { attributeFilter: ["data-theme"], attributes: true });
+    scopes.set(scope, created);
+    entry = created;
+  }
+
+  entry.listeners.add(onStoreChange);
+  return () => {
+    const current = scopes.get(scope);
+    if (!current) return;
+    current.listeners.delete(onStoreChange);
+    if (current.listeners.size === 0) {
+      current.observer.disconnect();
+      scopes.delete(scope);
+    }
+  };
+}
+
+function getSnapshot(scope: Element | null): number {
+  if (!scope) return 0;
+  return scopes.get(scope)?.revision ?? 0;
+}
+
+const getServerSnapshot = () => 0;
+
+/**
+ * Subscribes to `data-theme` mutations on `el`'s closest `[data-theme]`
+ * ancestor (default `<html>`) and returns a revision number that increments
+ * on each mutation. Any number of callers scoped to the SAME ancestor share
+ * one `MutationObserver`.
+ */
+export function useThemeScopeRevision(el: Element | null): number {
+  const scope = getThemeScope(el);
+  const subscribeToScope = useCallback(
+    (onStoreChange: () => void) => subscribe(scope, onStoreChange),
+    [scope],
+  );
+  const getScopeSnapshot = useCallback(() => getSnapshot(scope), [scope]);
+  return useSyncExternalStore(subscribeToScope, getScopeSnapshot, getServerSnapshot);
+}
+
+/** Test-only: the number of scope elements currently under observation. */
+export function _debugActiveThemeScopeCount(): number {
+  return scopes.size;
+}

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");
+  });
+});