For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Queue

Render a streamed todo list as grouped trace rows for pending and completed work.

Add dark mode to the settings page.
Add a dark variant to the theme tokensRead the theme from a cookieAdd a toggle to the settings pageCheck contrast on the charts

Dark mode is in. The toggle is under Settings, Appearance.

queue-demo.tsx
"use client";

import { useChat } from "@ai-sdk/react";
import type { UIDataTypes, UIMessage } from "ai";
import {
  CircleCheckIcon,
  CircleDotIcon,
  CircleIcon,
  ListChecksIcon,
  ListTodoIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import {
  Bubble,
  BubbleContent,
  Message,
  MessageContent,
} from "@/components/ui/message";
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";

type ChatMessage = UIMessage<
  unknown,
  UIDataTypes,
  {
    writeTodos: {
      input: {
        todos: {
          content: string;
          status: "pending" | "in_progress" | "completed";
        }[];
      };
      output: string;
    };
  }
>;

type Todo = Extract<
  ChatMessage["parts"][number],
  { type: "tool-writeTodos"; state: "input-available" }
>["input"]["todos"][number];

const TODOS = [
  "Add a dark variant to the theme tokens",
  "Read the theme from a cookie",
  "Add a toggle to the settings page",
  "Check contrast on the charts",
];

function todosAt(current: number) {
  return TODOS.map(
    (content, index) =>
      ({
        content,
        status:
          index < current
            ? "completed"
            : index === current
              ? "in_progress"
              : "pending",
      }) satisfies Todo
  );
}

const chat = createChat<ChatMessage>()
  .user("Add dark mode to the settings page.")
  .assistant(({ writer }) => {
    TODOS.forEach((_, index) => {
      writer
        .tool("writeTodos", { input: { todos: todosAt(index) } })
        .output("Updated the todo list.");
      writer.sleep(1400);
    });
    writer
      .tool("writeTodos", { input: { todos: todosAt(TODOS.length) } })
      .output("Updated the todo list.");
    writer.text("Dark mode is in. The toggle is under Settings, Appearance.");
  });

const transcript = chat.get();
const question = chat.get(1)[0];
const transport = chat.transport({ delayMs: 20 });

function TodoLine({ todo, streaming }: { todo: Todo; streaming: boolean }) {
  return (
    <TraceLine
      status={
        streaming && todo.status === "in_progress" ? "running" : undefined
      }
    >
      <TraceIcon>
        {todo.status === "completed" ? (
          <CircleCheckIcon />
        ) : todo.status === "in_progress" ? (
          <CircleDotIcon />
        ) : (
          <CircleIcon />
        )}
      </TraceIcon>
      <TraceTitle>{todo.content}</TraceTitle>
    </TraceLine>
  );
}

function TodoQueue({
  todos,
  streaming,
}: {
  todos: Todo[];
  streaming: boolean;
}) {
  const pending = todos.filter((todo) => todo.status !== "completed");
  const completed = todos.filter((todo) => todo.status === "completed");

  return (
    <Trace>
      {pending.length > 0 && (
        <TraceCollapsible defaultOpen>
          <TraceCollapsibleTrigger>
            <TraceLine>
              <TraceIcon>
                <ListTodoIcon />
              </TraceIcon>
              <TraceTitle>{pending.length} to do</TraceTitle>
            </TraceLine>
          </TraceCollapsibleTrigger>
          <TraceCollapsibleContent>
            <Trace>
              {pending.map((todo) => (
                <TodoLine
                  key={todo.content}
                  streaming={streaming}
                  todo={todo}
                />
              ))}
            </Trace>
          </TraceCollapsibleContent>
        </TraceCollapsible>
      )}
      {completed.length > 0 && (
        <TraceCollapsible defaultOpen>
          <TraceCollapsibleTrigger>
            <TraceLine>
              <TraceIcon>
                <ListChecksIcon />
              </TraceIcon>
              <TraceTitle>{completed.length} completed</TraceTitle>
            </TraceLine>
          </TraceCollapsibleTrigger>
          <TraceCollapsibleContent>
            <Trace>
              {completed.map((todo) => (
                <TodoLine
                  key={todo.content}
                  streaming={streaming}
                  todo={todo}
                />
              ))}
            </Trace>
          </TraceCollapsibleContent>
        </TraceCollapsible>
      )}
    </Trace>
  );
}

export function QueueDemo() {
  const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
    messages: transcript,
    transport,
  });
  const busy = status === "submitted" || status === "streaming";

  return (
    <div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      {messages.map((message) => {
        if (message.role === "user") {
          return (
            <Message align="end" key={message.id}>
              <MessageContent>
                <Bubble align="end" variant="muted">
                  <BubbleContent>{getMessageText(message)}</BubbleContent>
                </Bubble>
              </MessageContent>
            </Message>
          );
        }

        const streaming = busy && message === messages.at(-1);
        const todos = message.parts
          .filter((part) => part.type === "tool-writeTodos")
          .filter((part) => part.state !== "input-streaming")
          .at(-1)?.input?.todos;
        const text = getMessageText(message);

        return (
          <Message key={message.id}>
            <MessageContent className="gap-4">
              {todos && <TodoQueue streaming={streaming} todos={todos} />}
              {text && <p>{text}</p>}
            </MessageContent>
          </Message>
        );
      })}
      {!busy && question && (
        <Button
          className="mt-auto self-start"
          onClick={() => {
            if (!question) {
              return;
            }
            setMessages([]);
            sendMessage(question);
          }}
          size="sm"
          variant="outline"
        >
          Replay
        </Button>
      )}
    </div>
  );
}

Queue renders an agent todo list as two grouped trace sections: pending and completed. Each row carries a status glyph, the group headers show counts, and both groups collapse independently.

Queue is a composition, not a primitive. It composes Trace lines inside collapsibles and drives streaming status through a chat transport.

Installation

Usage

queue.tsx
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
import {
  CircleCheckIcon,
  CircleDotIcon,
  CircleIcon,
  ListChecksIcon,
  ListTodoIcon,
} from "lucide-react";
queue.tsx
<Trace>
  <TraceCollapsible defaultOpen>
    <TraceCollapsibleTrigger>
      <TraceLine>
        <TraceIcon>
          <ListTodoIcon />
        </TraceIcon>
        <TraceTitle>3 to do</TraceTitle>
      </TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent>
      <Trace>
        <TraceLine status="running">
          <TraceIcon>
            <CircleDotIcon />
          </TraceIcon>
          <TraceTitle>Add a toggle to the settings page</TraceTitle>
        </TraceLine>
      </Trace>
    </TraceCollapsibleContent>
  </TraceCollapsible>
</Trace>

Anatomy

queue.tsx
<Trace>
  <TraceCollapsible>
    <TraceCollapsibleTrigger>
      <TraceLine>
        <TraceIcon />
        <TraceTitle />
      </TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent>
      <Trace>
        <TraceLine>
          <TraceIcon />
          <TraceTitle />
        </TraceLine>
      </Trace>
    </TraceCollapsibleContent>
  </TraceCollapsible>
</Trace>
  • Trace — outer wrapper, flex column
  • TraceCollapsible — one per group (pending, completed)
  • TraceCollapsibleTrigger — header row with group icon and count
  • TraceCollapsibleContent — the todo list rows
  • TraceLine — individual todo row, accepts status
  • TraceTitle — todo content

Todo status

Each todo carries one of three states. The glyph and shimmer reflect the current one.

StatusIconEffect
pendingcirclemuted, no shimmer
in_progresscircle-dotrunning, shimmer on title
completedcircle-checkmuted, no shimmer

Grouped queue

Split the todo list by status. Pending rows and completed rows collapse independently so a long run stays scannable. The header count updates as items move between groups.

Descriptions

Each todo may carry a description that expands on demand. Wrap the todo row in a nested TraceCollapsible and pass the description as its content.

It is clipped by overflow-hidden on the field.
Update the registry snapshots
Typing, clearing and keyboard selection.
Cover the renamed props and the new data attributes.
Add a changeset
queue-descriptions.tsx
import {
  CircleCheckIcon,
  CircleIcon,
  ListChecksIcon,
  ListTodoIcon,
} from "lucide-react";

import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";

const todos: { title: string; description?: string; done: boolean }[] = [
  {
    description: "Cover the renamed props and the new data attributes.",
    done: true,
    title: "Write the migration guide",
  },
  { done: true, title: "Add a changeset" },
  {
    description: "It is clipped by overflow-hidden on the field.",
    done: false,
    title: "Fix the focus ring on the select trigger",
  },
  { done: false, title: "Update the registry snapshots" },
  {
    description: "Typing, clearing and keyboard selection.",
    done: false,
    title: "Add tests for the combobox",
  },
];

function TodoRow({ todo }: { todo: (typeof todos)[number] }) {
  const line = (
    <TraceLine>
      <TraceIcon>{todo.done ? <CircleCheckIcon /> : <CircleIcon />}</TraceIcon>
      <TraceTitle>{todo.title}</TraceTitle>
    </TraceLine>
  );

  if (!todo.description) {
    return line;
  }

  return (
    <TraceCollapsible>
      <TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
      <TraceCollapsibleContent>{todo.description}</TraceCollapsibleContent>
    </TraceCollapsible>
  );
}

export function QueueDescriptions() {
  const pending = todos.filter((todo) => !todo.done);
  const completed = todos.filter((todo) => todo.done);

  return (
    <Trace className="max-w-sm">
      <TraceCollapsible defaultOpen>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <ListTodoIcon />
            </TraceIcon>
            <TraceTitle>{pending.length} to do</TraceTitle>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent keepMounted>
          <Trace>
            {pending.map((todo) => (
              <TodoRow key={todo.title} todo={todo} />
            ))}
          </Trace>
        </TraceCollapsibleContent>
      </TraceCollapsible>
      <TraceCollapsible>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <ListChecksIcon />
            </TraceIcon>
            <TraceTitle>{completed.length} completed</TraceTitle>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent keepMounted>
          <Trace>
            {completed.map((todo) => (
              <TodoRow key={todo.title} todo={todo} />
            ))}
          </Trace>
        </TraceCollapsibleContent>
      </TraceCollapsible>
    </Trace>
  );
}

Streaming

The demo streams writeTodos tool calls through a chat transport. Each tick replaces the todo list with a new snapshot where one more item moves to completed and the next becomes in_progress. The header counts and icons update without a full re-render of the chat.

Accessibility

  • Use TraceTitle as the accessible name. Write it as the todo content, not a status word.
  • Status is conveyed by icon glyph and color. Do not rely on color alone.
  • Each collapsible trigger is keyboard-focusable and toggles with Enter or Space.
  • prefers-reduced-motion disables shimmer and collapse animation.

Best Practices

  • Group by status, not by index. Pending and completed read as two lists, not one list with gaps.
  • Keep todo titles short. One sentence, imperative mood — "Add a toggle", not "Toggle should be added".
  • Let the counts speak. The header shows how many are left. Do not repeat that in the intro.
  • Collapse the completed group by default for long runs. Users scan the pending rows first.