@agent-native/toolkit 0.228.0-nightly-20261111212500 → 0.228.0

package/src/app/agentkit/react/code-block.spec.tsx

@@ -0,0 +1,154 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { loadCodeHighlighter } from "../../code-highlighter.js";
+import {
+  CodeBlock,
+  CodeBlockContent,
+  CodeBlockCopyButton,
+  CodeBlockLine,
+} from "./code-block.js";
+
+let root: Root;
+let container: HTMLDivElement;
+
+beforeEach(() => {
+  // Real throttle timers let a highlight pass land early under load.
+  vi.useFakeTimers();
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+async function render(node: React.ReactNode) {
+  await act(async () => root.render(node));
+}
+
+async function settle() {
+  await act(async () => {
+    vi.advanceTimersByTime(100);
+    await loadCodeHighlighter();
+    await Promise.resolve();
+  });
+}
+
+function lineText() {
+  return Array.from(
+    container.querySelectorAll(".agentkit-code-line"),
+    (line) => line.textContent,
+  );
+}
+
+describe("CodeBlock", () => {
+  it("renders plain lines first, then highlighted tokens with the same text", async () => {
+    const code = "const ready = true;\nexport { ready };\n";
+    await render(
+      <CodeBlock>
+        <CodeBlockContent language="ts">{code}</CodeBlockContent>
+      </CodeBlock>,
+    );
+    expect(container.querySelector(".agentkit-code-token")).toBeNull();
+    expect(lineText()).toEqual(["const ready = true;", "export { ready };"]);
+
+    await settle();
+    expect(container.querySelector(".agentkit-code-token")).not.toBeNull();
+    expect(lineText()).toEqual(["const ready = true;", "export { ready };"]);
+    expect(container.querySelector("code")?.textContent).toBe(
+      "const ready = true;\nexport { ready };",
+    );
+  });
+
+  it("keeps finished lines highlighted while a new line streams in", async () => {
+    const view = (code: string) => (
+      <CodeBlockContent language="ts">{code}</CodeBlockContent>
+    );
+    await render(view("const a = 1;"));
+    await settle();
+    await render(view("const a = 1;\nconst b"));
+    const [first, second] = Array.from(
+      container.querySelectorAll(".agentkit-code-line"),
+    );
+    expect(first?.querySelector(".agentkit-code-token")).not.toBeNull();
+    expect(second?.querySelector(".agentkit-code-token")).toBeNull();
+    expect(second?.textContent).toBe("const b");
+  });
+
+  it("colors terminal output and never shows its escape codes", async () => {
+    await render(
+      <CodeBlockContent language="ansi">
+        {"\u001b[31mfailed\u001b[0m 2 tests\nok"}
+      </CodeBlockContent>,
+    );
+    expect(lineText()).toEqual(["failed 2 tests", "ok"]);
+    await settle();
+    expect(lineText()).toEqual(["failed 2 tests", "ok"]);
+    const failed = container.querySelector<HTMLElement>(".agentkit-code-token");
+    expect(failed?.textContent).toBe("failed");
+    expect(failed?.style.getPropertyValue("--shiki-light")).not.toBe("");
+  });
+
+  it("renders an unknown language as plain text", async () => {
+    await render(
+      <CodeBlockContent language="cobol">{"DISPLAY 'HI'."}</CodeBlockContent>,
+    );
+    await settle();
+    expect(container.querySelector(".agentkit-code-token")).toBeNull();
+    expect(lineText()).toEqual(["DISPLAY 'HI'."]);
+  });
+
+  it("keeps diff markers and line numbers out of the text", async () => {
+    await render(
+      <CodeBlockContent lineNumbers startLine={10}>
+        <CodeBlockLine variant="removed">old</CodeBlockLine>
+        <CodeBlockLine variant="added">new</CodeBlockLine>
+      </CodeBlockContent>,
+    );
+    const pre = container.querySelector("pre")!;
+    expect(pre.dataset.lineNumbers).toBe("true");
+    expect(pre.style.getPropertyValue("--agentkit-code-start-line")).toBe("9");
+    expect(pre.getAttribute("dir")).toBe("ltr");
+    // The visible +/− is generated content; screen readers hear the word.
+    expect(pre.textContent).toBe("Removed old\nAdded new");
+    expect(
+      Array.from(pre.querySelectorAll(".agentkit-code-line-change"), (label) =>
+        label.classList.contains("agentkit-visually-hidden"),
+      ),
+    ).toEqual([true, true]);
+    expect(
+      Array.from(
+        pre.querySelectorAll<HTMLElement>(".agentkit-code-line"),
+        (line) => line.dataset.variant,
+      ),
+    ).toEqual(["removed", "added"]);
+  });
+
+  it("copies its value outside an AgentKit provider", async () => {
+    const writeText = vi.fn(async () => undefined);
+    vi.stubGlobal("navigator", { ...navigator, clipboard: { writeText } });
+    await render(<CodeBlockCopyButton value="pnpm build" />);
+    const button = container.querySelector("button")!;
+    expect(button.getAttribute("aria-label")).toBe("Copy code");
+    await act(async () => {
+      button.click();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(writeText).toHaveBeenCalledWith("pnpm build");
+    expect(button.getAttribute("aria-label")).toBe("Copied");
+    // Said once in a polite region; a renamed focused button is often silent.
+    expect(container.querySelector('[aria-live="polite"]')?.textContent).toBe(
+      "Copied",
+    );
+  });
+});

package/src/app/agentkit/react/code-block.tsx

@@ -0,0 +1,317 @@
+import { IconCheck, IconCopy } from "@tabler/icons-react";
+import {
+  Children,
+  useEffect,
+  useRef,
+  useState,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import type { ThemedToken } from "shiki/core";
+
+import { writeClipboardText } from "../../../agentkit.js";
+import { IconButton } from "../../../design-system/index.js";
+import {
+  CODE_THEMES,
+  loadCodeHighlighter,
+  resolveCodeLanguage,
+} from "../../code-highlighter.js";
+import { useAgentKitLabels } from "./context.js";
+
+export type CodeBlockLineVariant =
+  | "default"
+  | "added"
+  | "removed"
+  | "highlighted";
+
+function classes(...names: Array<string | false | null | undefined>): string {
+  return names.filter(Boolean).join(" ");
+}
+
+export function CodeBlock({
+  className,
+  size = "default",
+  variant = "default",
+  ...props
+}: ComponentProps<"div"> & {
+  size?: "default" | "sm";
+  variant?: "default" | "destructive";
+}) {
+  return (
+    <div
+      data-slot="code-block"
+      data-size={size}
+      data-variant={variant}
+      className={classes("agentkit-code-block", className)}
+      {...props}
+    />
+  );
+}
+
+export function CodeBlockHeader({
+  className,
+  ...props
+}: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="code-block-header"
+      className={classes("agentkit-code-block-header", className)}
+      {...props}
+    />
+  );
+}
+
+/** A filename, language, or command. Truncates. */
+export function CodeBlockTitle({
+  className,
+  ...props
+}: ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="code-block-title"
+      className={classes("agentkit-code-block-title", className)}
+      {...props}
+    />
+  );
+}
+
+/** Outside a header, floats over the content and shows on hover or focus. */
+export function CodeBlockActions({
+  className,
+  ...props
+}: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="code-block-actions"
+      className={classes("agentkit-code-block-actions", className)}
+      {...props}
+    />
+  );
+}
+
+export function CodeBlockCopyButton({
+  value,
+  label,
+  copiedLabel,
+}: {
+  value: string;
+  label?: string;
+  copiedLabel?: string;
+}) {
+  const labels = useAgentKitLabels();
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+  const copy = async () => {
+    if (!(await writeClipboardText(value))) return;
+    setCopied(true);
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => setCopied(false), 2_000);
+  };
+  const copiedText = copiedLabel ?? labels.codeCopied;
+  return (
+    <>
+      <IconButton
+        label={copied ? copiedText : (label ?? labels.copyCode)}
+        icon={
+          copied ? (
+            <IconCheck aria-hidden="true" size={16} />
+          ) : (
+            <IconCopy aria-hidden="true" size={16} />
+          )
+        }
+        size="compact"
+        className="size-6 rounded-[var(--agentkit-code-action-radius,var(--agentkit-radius-xs))]"
+        onPress={() => void copy()}
+      />
+      {/* A changed name on the focused button is not reliably read. */}
+      <span className="agentkit-visually-hidden" aria-live="polite">
+        {copied ? copiedText : ""}
+      </span>
+    </>
+  );
+}
+
+/** Diff variants carry a +/− marker, not color alone. */
+export function CodeBlockLine({
+  className,
+  variant = "default",
+  children,
+  ...props
+}: ComponentProps<"span"> & { variant?: CodeBlockLineVariant }) {
+  const labels = useAgentKitLabels();
+  // Screen readers hear this word, not the silent CSS +/−; it stays out of selections.
+  const change =
+    variant === "added"
+      ? labels.workStepLineAdded
+      : variant === "removed"
+        ? labels.workStepLineRemoved
+        : undefined;
+  return (
+    <span
+      data-slot="code-block-line"
+      data-variant={variant === "default" ? undefined : variant}
+      className={classes("agentkit-code-line", className)}
+      {...props}
+    >
+      {change ? (
+        <span className="agentkit-visually-hidden agentkit-code-line-change">
+          {`${change} `}
+        </span>
+      ) : null}
+      {children}
+    </span>
+  );
+}
+
+/** Line numbers stay out of copied text and the accessibility tree. */
+export function CodeBlockContent({
+  children,
+  language,
+  wrap = false,
+  lineNumbers = false,
+  startLine = 1,
+  tabIndex = 0,
+  className,
+  style,
+  ...props
+}: Omit<ComponentProps<"pre">, "children"> & {
+  children: string | ReactNode;
+  language?: string | undefined;
+  wrap?: boolean;
+  lineNumbers?: boolean;
+  startLine?: number;
+}) {
+  const source = typeof children === "string" ? children : "";
+  const highlighted = useHighlightedCode(
+    source,
+    typeof children === "string" ? language : undefined,
+  );
+  const lines =
+    typeof children === "string"
+      ? highlighted.map((line, index) => (
+          <CodeBlockLine key={index}>{line}</CodeBlockLine>
+        ))
+      : Children.toArray(children);
+  return (
+    <pre
+      data-slot="code-block-content"
+      data-wrap={wrap ? "true" : undefined}
+      data-line-numbers={lineNumbers ? "true" : undefined}
+      dir="ltr"
+      tabIndex={tabIndex}
+      className={classes("agentkit-code-block-content", className)}
+      style={
+        lineNumbers && startLine !== 1
+          ? ({
+              ...style,
+              "--agentkit-code-start-line": startLine - 1,
+            } as CSSProperties)
+          : style
+      }
+      {...props}
+    >
+      <code
+        className={language ? `language-${language}` : undefined}
+        data-language={language}
+      >
+        {lines.flatMap((line, index) => (index ? ["\n", line] : [line]))}
+      </code>
+    </pre>
+  );
+}
+
+export function CodeBlockFooter({
+  className,
+  ...props
+}: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="code-block-footer"
+      className={classes("agentkit-code-block-footer", className)}
+      {...props}
+    />
+  );
+}
+
+function codeLines(code: string): string[] {
+  return code.replace(/\n$/, "").split("\n");
+}
+
+// An `ansi` pass drops these from token text, so the plain line must too.
+const ANSI_SEQUENCE = /\u001b\[[0-9;]*m/g;
+
+function visibleLine(line: string, language: string | undefined): string {
+  return language === "ansi" ? line.replace(ANSI_SEQUENCE, "") : line;
+}
+
+function tokenText(tokens: ThemedToken[]): string {
+  return tokens.map((token) => token.content).join("");
+}
+
+interface HighlightPass {
+  language: string;
+  lines: ThemedToken[][];
+}
+
+const HIGHLIGHT_INTERVAL_MS = 80;
+
+/** A line keeps its last tokens until its text changes, so streaming never flashes it plain. */
+export function useHighlightedCode(
+  code: string,
+  language: string | undefined,
+): ReactNode[] {
+  const [pass, setPass] = useState<HighlightPass | null>(null);
+  const lastRun = useRef(0);
+  useEffect(() => {
+    if (!language) return;
+    let cancelled = false;
+    const wait = Math.max(
+      0,
+      HIGHLIGHT_INTERVAL_MS - (Date.now() - lastRun.current),
+    );
+    const timer = setTimeout(() => {
+      lastRun.current = Date.now();
+      void loadCodeHighlighter().then(
+        (highlighter) => {
+          if (cancelled) return;
+          const lang = resolveCodeLanguage(highlighter, language);
+          if (!lang) return setPass(null);
+          const { tokens } = highlighter.codeToTokens(code.replace(/\n$/, ""), {
+            lang,
+            themes: CODE_THEMES,
+            defaultColor: false,
+          });
+          setPass({ language, lines: tokens });
+        },
+        // Highlighting is decoration: the plain lines already show the code.
+        () => undefined,
+      );
+    }, wait);
+    return () => {
+      cancelled = true;
+      clearTimeout(timer);
+    };
+  }, [code, language]);
+  const usable = pass && pass.language === language ? pass.lines : undefined;
+  return codeLines(code).map((source, index) => {
+    const line = visibleLine(source, language);
+    const tokens = usable?.[index];
+    if (!tokens || tokenText(tokens) !== line) return line;
+    return tokens.map((token, tokenIndex) => (
+      <span
+        key={tokenIndex}
+        className="agentkit-code-token"
+        style={token.htmlStyle as CSSProperties | undefined}
+      >
+        {token.content}
+      </span>
+    ));
+  });
+}

package/src/app/agentkit/react/components.interaction.spec.tsx

@@ -183,6 +183,13 @@ describe("AgentActivityItem replay privacy", () => {
             ?.querySelector('a[href^="https://example.test/report"]')
             ?.closest(`[${SESSION_REPLAY_BLOCK_ATTRIBUTE}]`) !== null,
         ).toBe(status === "failed");
+
+        // Closing swaps in a fresh, blocked node rather than re-blocking the
+        // node replay recorded while it was open.
+        await act(async () => disclosure.click());
+        const closed = container.querySelector(".agentkit-activity-summary");
+        expect(summary?.isConnected).toBe(false);
+        expect(closed?.hasAttribute(SESSION_REPLAY_BLOCK_ATTRIBUTE)).toBe(true);
       } finally {
         await act(async () => root.unmount());
         await client.shutdown();

package/src/app/agentkit/react/components.papercuts.spec.tsx

@@ -13,7 +13,7 @@ import type {
   AgentEvent,
   AgentTask,
 } from "@agent-native/agentkit/protocol";
-import { act, createElement, type ReactNode } from "react";
+import { act, createElement, useEffect, useRef, type ReactNode } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -62,7 +62,7 @@ import {
   AgentTaskItem,
   useAgentKitFollowTranscript,
 } from "./components.js";
-import { AgentKitProvider } from "./context.js";
+import { AgentKitProvider, useAgentKit } from "./context.js";
 
 let container: HTMLDivElement;
 let root: Root;
@@ -160,6 +160,17 @@ function runningThread(threadId: string, runId: string): AgentThreadState {
   };
 }
 
+// Registered after the chat's own composer, so a focus request lands here.
+function ComposerFocusTarget() {
+  const { registerComposerFocus, threadId } = useAgentKit();
+  const target = useRef<HTMLButtonElement>(null);
+  useEffect(
+    () => registerComposerFocus(threadId, () => target.current?.focus()),
+    [registerComposerFocus, threadId],
+  );
+  return <button ref={target}>Composer focus target</button>;
+}
+
 describe("AgentKitChat papercuts", () => {
   it("offers a default Stop that cancels once however often it is clicked", async () => {
     const thread = runningThread("thread-stop", "run-stop");
@@ -195,6 +206,37 @@ describe("AgentKitChat papercuts", () => {
     expect(stop?.disabled).toBe(false);
   });
 
+  it("offers a skip link past the transcript to the composer", async () => {
+    const thread = runningThread("thread-skip", "run-skip");
+    const store = observableController(snapshotOf(thread));
+    await render(
+      <AgentKitProvider controller={store.controller} threadId={thread.id}>
+        <AgentKitChat
+          composerProps={{
+            autoFocus: false,
+            modelStatusChecksEnabled: false,
+            voiceEnabled: false,
+          }}
+        />
+        <ComposerFocusTarget />
+      </AgentKitProvider>,
+    );
+    const skip = container.querySelector<HTMLButtonElement>(
+      '[data-agentkit-skip-link="composer"]',
+    );
+    const transcript = container.querySelector(".agentkit-transcript");
+    expect(skip?.textContent).toBe("Skip to message box");
+    expect(
+      transcript && skip
+        ? skip.compareDocumentPosition(transcript) &
+            Node.DOCUMENT_POSITION_FOLLOWING
+        : 0,
+    ).toBeTruthy();
+
+    await act(async () => skip?.click());
+    expect(document.activeElement?.textContent).toBe("Composer focus target");
+  });
+
   it("announces a finished response once in the shared status region", async () => {
     const thread = runningThread("thread-announce", "run-announce");
     const store = observableController(snapshotOf(thread));
@@ -232,6 +274,105 @@ describe("AgentKitChat papercuts", () => {
     ).toHaveLength(1);
   });
 
+  it.each([
+    ["awaiting_approval", "Waiting for approval"],
+    ["awaiting_input", "Waiting for input"],
+    ["cancelled", "Stopped"],
+  ] as const)("announces a run that goes %s", async (status, announcement) => {
+    const thread = runningThread("thread-pause", "run-pause");
+    const store = observableController(snapshotOf(thread));
+    await render(
+      <AgentKitProvider controller={store.controller} threadId={thread.id}>
+        <AgentKitChat composer={false} />
+      </AgentKitProvider>,
+    );
+
+    await act(async () => {
+      store.update(
+        snapshotOf(
+          {
+            ...thread,
+            runs: {
+              "run-pause": { ...thread.runs["run-pause"]!, status },
+            },
+          },
+          1,
+        ),
+      );
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    expect(
+      container.querySelector("[data-agentkit-live-status]")?.textContent,
+    ).toBe(announcement);
+  });
+
+  it.each([
+    ["with an error, which its own alert reads", true, ""],
+    ["without an error", false, "Response failed"],
+  ] as const)(
+    "announces a failed run once: %s",
+    async (_case, withError, announcement) => {
+      const thread = runningThread("thread-fail", "run-fail");
+      const store = observableController(snapshotOf(thread));
+      await render(
+        <AgentKitProvider controller={store.controller} threadId={thread.id}>
+          <AgentKitChat composer={false} />
+        </AgentKitProvider>,
+      );
+      await act(async () => {
+        store.update(
+          snapshotOf(
+            {
+              ...thread,
+              activeRunIds: [],
+              runs: {
+                "run-fail": {
+                  ...thread.runs["run-fail"]!,
+                  status: "failed",
+                  ...(withError
+                    ? {
+                        error: {
+                          code: "provider_error",
+                          message: "The model provider returned an error.",
+                        },
+                      }
+                    : {}),
+                },
+              },
+            },
+            1,
+          ),
+        );
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
+      expect(
+        container.querySelector("[data-agentkit-live-status]")?.textContent,
+      ).toBe(announcement);
+      expect(container.querySelectorAll('[role="alert"]')).toHaveLength(
+        withError ? 1 : 0,
+      );
+    },
+  );
+
+  it("gives every turn a heading for heading navigation", async () => {
+    const thread = runningThread("thread-headings", "run-headings");
+    const store = observableController(snapshotOf(thread));
+    await render(
+      <AgentKitProvider controller={store.controller} threadId={thread.id}>
+        <AgentKitChat composer={false} />
+      </AgentKitProvider>,
+    );
+    const articles = [
+      ...container.querySelectorAll("article.agentkit-message"),
+    ];
+    expect(articles.length).toBeGreaterThan(0);
+    expect(
+      articles.map(
+        (article) => article.querySelector(":scope > h2")?.textContent,
+      ),
+    ).toEqual(articles.map((article) => article.getAttribute("aria-label")));
+  });
+
   it("marks a stopped run under its turn", async () => {
     const thread: AgentThreadState = {
       ...createAgentThreadState("thread-cancelled"),