@tangle-network/ui 11.30.2 → 11.31.0

package/src/markdown/markdown-table.tsx

@@ -0,0 +1,191 @@
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentProps,
+} from "react";
+import type { ExtraProps } from "react-markdown";
+import { Check, Copy } from "lucide-react";
+import { focusRing, focusRingInset } from "../lib/focus";
+import { cn } from "../lib/utils";
+
+type Element = NonNullable<ExtraProps["node"]>;
+type ElementContent = Element["children"][number];
+
+/** A figure: optional sign or currency, digits with separators, an optional unit. */
+const NUMERIC_CELL = /^[(]?[-+−]?\s?[$€£¥₹]?\s?\d[\d,_ ]*(?:\.\d+)?\s?(?:%|[kKmMbB]|x|ms|s|h|pp)?[)]?$/;
+
+/** The text of a hast subtree, as a reader sees it. */
+function textOf(node: ElementContent | Element): string {
+  if (node.type === "text") return node.value;
+  if (node.type !== "element") return "";
+  return node.children.map(textOf).join("");
+}
+
+function rowsOf(table: Element): { header: string[][]; body: string[][] } {
+  const header: string[][] = [];
+  const body: string[][] = [];
+  const visit = (element: Element, inHead: boolean) => {
+    for (const child of element.children) {
+      if (child.type !== "element") continue;
+      if (child.tagName === "tr") {
+        const cells = child.children
+          .filter((cell): cell is Element => cell.type === "element" && (cell.tagName === "th" || cell.tagName === "td"))
+          .map((cell) => textOf(cell).replace(/\s+/g, " ").trim());
+        (inHead ? header : body).push(cells);
+      } else {
+        visit(child, inHead || child.tagName === "thead");
+      }
+    }
+  };
+  visit(table, false);
+  return { header, body };
+}
+
+/** A column is numeric when every non-empty body cell is a figure. */
+export function numericColumns(body: string[][]): boolean[] {
+  const width = Math.max(0, ...body.map((row) => row.length));
+  return Array.from({ length: width }, (_, column) => {
+    const cells = body.map((row) => row[column] ?? "").filter(Boolean);
+    return cells.length > 0 && cells.every((cell) => NUMERIC_CELL.test(cell));
+  });
+}
+
+function csvCell(value: string): string {
+  // A spreadsheet runs a leading = + - @ as a formula unless the cell is a figure.
+  const safe = /^[=+\-@\t\r]/.test(value) && !NUMERIC_CELL.test(value) ? `'${value}` : value;
+  return /[",\n\r]/.test(safe) || safe !== safe.trim() ? `"${safe.replace(/"/g, '""')}"` : safe;
+}
+
+/** RFC 4180 CSV of a rendered Markdown table, header first. */
+export function tableCsv(rows: string[][]): string {
+  return rows.map((row) => row.map(csvCell).join(",")).join("\n");
+}
+
+const TableColumns = createContext<boolean[]>([]);
+const CellColumn = createContext(-1);
+
+function CopyCsvButton({ csv }: { csv: string }) {
+  const [state, setState] = useState<"idle" | "copied" | "failed">("idle");
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => { if (timer.current) clearTimeout(timer.current); }, []);
+  const copy = useCallback(async () => {
+    if (timer.current) clearTimeout(timer.current);
+    try {
+      await navigator.clipboard.writeText(csv);
+      setState("copied");
+    } catch {
+      setState("failed");
+    }
+    timer.current = setTimeout(() => setState("idle"), 2000);
+  }, [csv]);
+  return (
+    <>
+      <button
+        type="button"
+        onClick={copy}
+        className={cn(
+          "inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-sm font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground",
+          focusRing,
+        )}
+      >
+        {state === "copied"
+          ? <Check aria-hidden className="size-4 text-[var(--surface-success-text)]" />
+          : <Copy aria-hidden className="size-4" />}
+        {state === "copied" ? "Copied" : "Copy CSV"}
+      </button>
+      <span className="sr-only" role="status" aria-live="polite">
+        {state === "copied" ? "Table copied as CSV" : state === "failed" ? "Copy failed" : ""}
+      </span>
+    </>
+  );
+}
+
+/**
+ * A Markdown table as a card: a header row, subtle row lines, figures
+ * right-aligned in tabular numerals, a copy-as-CSV control, and horizontal
+ * scrolling inside the card when the columns outgrow a phone.
+ */
+export function MarkdownTable({ node, className, children, ...props }: ComponentProps<"table"> & ExtraProps) {
+  const { csv, numeric, rowCount } = useMemo(() => {
+    const { header, body } = node ? rowsOf(node) : { header: [], body: [] };
+    return { csv: tableCsv([...header, ...body]), numeric: numericColumns(body), rowCount: body.length };
+  }, [node]);
+  return (
+    <div className="not-prose my-4 overflow-hidden rounded-lg border border-border bg-card">
+      <div className="flex items-center justify-between gap-2 border-b border-border px-3 py-1">
+        <span className="text-sm text-muted-foreground">{rowCount === 1 ? "1 row" : `${rowCount} rows`}</span>
+        <CopyCsvButton csv={csv} />
+      </div>
+      {/* A keyboard reaches a sideways-scrolling table only when it can take focus. */}
+      <div tabIndex={0} role="region" aria-label="Table" className={cn("overflow-x-auto", focusRingInset)}>
+        <TableColumns.Provider value={numeric}>
+          <table {...props} className={cn("w-full border-collapse text-sm text-foreground", className)}>
+            {children}
+          </table>
+        </TableColumns.Provider>
+      </div>
+    </div>
+  );
+}
+
+export function MarkdownTableHead({ node: _node, className, ...props }: ComponentProps<"thead"> & ExtraProps) {
+  return <thead {...props} className={cn("bg-muted/50", className)} />;
+}
+
+export function MarkdownTableBody({ node: _node, className, ...props }: ComponentProps<"tbody"> & ExtraProps) {
+  return <tbody {...props} className={cn("[&>tr:last-child>td]:border-b-0", className)} />;
+}
+
+export function MarkdownTableRow({ node: _node, children, ...props }: ComponentProps<"tr"> & ExtraProps) {
+  let column = 0;
+  return (
+    <tr {...props}>
+      {Children.map(children, (child) =>
+        isValidElement(child)
+          ? <CellColumn.Provider value={column++}>{child}</CellColumn.Provider>
+          : child,
+      )}
+    </tr>
+  );
+}
+
+function useNumericCell(): boolean {
+  const numeric = useContext(TableColumns);
+  const column = useContext(CellColumn);
+  return column >= 0 && numeric[column] === true;
+}
+
+export function MarkdownTableHeaderCell({ node: _node, className, ...props }: ComponentProps<"th"> & ExtraProps) {
+  const numeric = useNumericCell();
+  return (
+    <th
+      {...props}
+      className={cn(
+        "whitespace-nowrap border-b border-border px-3 py-2 text-left font-semibold text-foreground",
+        numeric && "text-right",
+        className,
+      )}
+    />
+  );
+}
+
+export function MarkdownTableCell({ node: _node, className, ...props }: ComponentProps<"td"> & ExtraProps) {
+  const numeric = useNumericCell();
+  return (
+    <td
+      {...props}
+      className={cn(
+        "border-b border-border/60 px-3 py-2 align-top",
+        numeric ? "whitespace-nowrap text-right tabular-nums" : "min-w-[8rem]",
+        className,
+      )}
+    />
+  );
+}

package/src/markdown/markdown.test.tsx

@@ -136,4 +136,31 @@ describe("Markdown", () => {
     );
     expect(screen.queryByRole("link")).toBeNull();
   });
+
+  it("renders a fenced block's file name and highlights it as that file's language", () => {
+    render(<Markdown>{'```ts title="src/lib/ctr.ts"\nexport const x = 1;\n```'}</Markdown>);
+    expect(screen.getByText("src/lib/ctr.ts")).toBeInTheDocument();
+    expect(screen.getByText("TypeScript")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Copy to clipboard" })).toBeInTheDocument();
+  });
+
+  it("renders a single-line fence without a language as a block, not inline code", () => {
+    const { container } = render(<Markdown>{"```\nnpm run build\n```\n\nRun `npm test` too."}</Markdown>);
+    expect(container.querySelectorAll("pre")).toHaveLength(1);
+    expect(container.querySelector("pre")?.textContent).toBe("npm run build");
+    expect(container.querySelector("p code")?.textContent).toBe("npm test");
+  });
+
+  it("renders links the host classifies as chips that keep their href", () => {
+    render(
+      <Markdown linkChip={(href) => href.startsWith("/vault/") ? { kind: "file", label: "REVIEW.md", title: "campaigns/REVIEW.md" } : null}>
+        {"See [the review](/vault/REVIEW.md) and [docs](https://example.com)."}
+      </Markdown>,
+    );
+    const chip = screen.getByRole("link", { name: "REVIEW.md" });
+    expect(chip.getAttribute("href")).toBe("/vault/REVIEW.md");
+    expect(chip.getAttribute("data-link-chip")).toBe("file");
+    expect(chip.getAttribute("title")).toBe("campaigns/REVIEW.md");
+    expect(screen.getByRole("link", { name: "docs" }).hasAttribute("data-link-chip")).toBe(false);
+  });
 });

package/src/markdown/markdown.tsx

@@ -9,11 +9,21 @@ import {
 } from "react";
 import ReactMarkdown, { defaultUrlTransform, type ExtraProps, type UrlTransform } from "react-markdown";
 import remarkGfm from "remark-gfm";
-import rehypeSanitize from "rehype-sanitize";
+import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
 import rehypeSlug from "rehype-slug";
 import GithubSlugger from "github-slugger";
-import { ImageOff } from "lucide-react";
+import { FileImage, FileText, Folder, ImageOff, Package, type LucideIcon } from "lucide-react";
 import { CodeBlock, CopyButton } from "./code-block";
+import { fenceInfo, remarkCodeMeta } from "./code-meta";
+import {
+  MarkdownTable,
+  MarkdownTableBody,
+  MarkdownTableCell,
+  MarkdownTableHead,
+  MarkdownTableHeaderCell,
+  MarkdownTableRow,
+} from "./markdown-table";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 const SANITIZED_HEADING_ID_PREFIX = "user-content-";
@@ -50,17 +60,101 @@ function transformMarkdownUrl(
   return safeUrl(transformed);
 }
 
+/** How a link to a known object renders: a chip with that object's icon. */
+export interface MarkdownLinkChip {
+  kind: "file" | "image" | "asset" | "folder";
+  /** Chip text; the link's own text when omitted. */
+  label?: string;
+  /** Tooltip, such as the full path. */
+  title?: string;
+}
+
+/** Classifies a link by its transformed href; null keeps an ordinary link. */
+export type MarkdownLinkChipResolver = (href: string) => MarkdownLinkChip | null | undefined;
+
+const LINK_CHIP_ICONS: Record<MarkdownLinkChip["kind"], LucideIcon> = {
+  file: FileText,
+  image: FileImage,
+  asset: Package,
+  folder: Folder,
+};
+
+const LinkChipContext = createContext<MarkdownLinkChipResolver | undefined>(undefined);
+
 // An image already wrapped in a Markdown link keeps that link: anchors cannot nest.
 const MarkdownLinkContext = createContext(false);
 
-function MarkdownLink({ node: _node, ...props }: ComponentProps<"a"> & ExtraProps) {
+function MarkdownLink({ node: _node, children, className, ...props }: ComponentProps<"a"> & ExtraProps) {
+  const resolveChip = useContext(LinkChipContext);
+  const chip = typeof props.href === "string" && props.href ? resolveChip?.(props.href) : null;
+  if (!chip) {
+    return (
+      <MarkdownLinkContext.Provider value>
+        <a {...props} className={className}>{children}</a>
+      </MarkdownLinkContext.Provider>
+    );
+  }
+  const Icon = LINK_CHIP_ICONS[chip.kind];
   return (
     <MarkdownLinkContext.Provider value>
-      <a {...props} />
+      <a
+        {...props}
+        title={chip.title ?? props.title}
+        data-link-chip={chip.kind}
+        className={cn(
+          "not-prose inline-flex max-w-full items-center gap-1.5 rounded-md border border-border bg-muted/60 px-2 py-0.5 align-middle text-[0.9375em] font-medium leading-6 text-foreground no-underline transition-colors hover:border-[var(--border-strong)] hover:bg-muted",
+          focusRing,
+          className,
+        )}
+      >
+        <Icon aria-hidden className="size-4 shrink-0 text-muted-foreground" />
+        <span className="min-w-0 truncate">{chip.label ?? children}</span>
+      </a>
     </MarkdownLinkContext.Provider>
   );
 }
 
+// Fenced code arrives as <pre><code>; inline code is a bare <code>.
+const PreContext = createContext(false);
+
+function MarkdownPre({ children }: ComponentProps<"pre"> & ExtraProps) {
+  return <PreContext.Provider value>{children}</PreContext.Provider>;
+}
+
+function MarkdownCode({ node, className: codeClass, children: codeChildren, ...rest }: ComponentProps<"code"> & ExtraProps) {
+  const fenced = useContext(PreContext);
+  const code = String(codeChildren).replace(/\n$/, "");
+  if (!fenced) {
+    const { "data-meta": _meta, ...attributes } = rest as typeof rest & { "data-meta"?: unknown };
+    return (
+      <code
+        className={cn(
+          "px-1.5 py-0.5 rounded border border-border bg-muted text-foreground text-[0.85em] font-mono",
+          codeClass,
+        )}
+        {...attributes}
+      >
+        {codeChildren}
+      </code>
+    );
+  }
+  const { language, filename } = fenceInfo(codeClass, node?.properties?.dataMeta);
+  return (
+    <CodeBlock code={code} language={language} filename={filename} className="my-4">
+      <CopyButton text={code} />
+    </CodeBlock>
+  );
+}
+
+// The default schema plus a fence's info string on <code>, which names its file.
+const sanitizeSchema = {
+  ...defaultSchema,
+  attributes: {
+    ...defaultSchema.attributes,
+    code: [...(defaultSchema.attributes?.code ?? []), "dataMeta"],
+  },
+};
+
 /**
  * Renders a Markdown image that opens full size in a new tab, or a labelled
  * placeholder when its URL is unsafe or fails to load, instead of the
@@ -131,58 +225,42 @@ export interface MarkdownProps {
   className?: string;
   /** Transform parsed link and image URLs while retaining protocol safety checks. */
   urlTransform?: UrlTransform;
+  /** Render links to known objects (a file, an asset) as chips that keep their href. */
+  linkChip?: MarkdownLinkChipResolver;
 }
 
 /**
- * Renders Markdown content with GFM support, XSS sanitisation, custom code
- * block rendering via our CodeBlock component, and images that open full size
- * or show a labelled placeholder when unavailable.
+ * Renders Markdown content with GFM support and XSS sanitisation: Shiki code
+ * blocks that name their file, tables as cards with right-aligned figures and
+ * a CSV copy, images that open full size or show a labelled placeholder, and
+ * optional chips for links to known objects.
  */
-export const Markdown = memo(({ children, className, urlTransform }: MarkdownProps) => {
+export const Markdown = memo(({ children, className, urlTransform, linkChip }: MarkdownProps) => {
   return (
     <div
       className={cn("tangle-prose max-w-none text-sm", className)}
     >
-      <ReactMarkdown
-        remarkPlugins={[remarkGfm]}
-        rehypePlugins={[rehypeSlug, rehypeSanitize]}
-        urlTransform={(url, key, node) => transformMarkdownUrl(url, key, node, urlTransform)}
-        components={{
-          a: MarkdownLink,
-          img: MarkdownImage,
-          pre({ children: preChildren }) {
-            return <>{preChildren}</>;
-          },
-          code({ className: codeClass, children: codeChildren, ...rest }) {
-            const match = /language-(\w+)/.exec(codeClass || "");
-            const language = match?.[1];
-            const code = String(codeChildren).replace(/\n$/, "");
-
-            // Inline code (no language fence)
-            if (!language && !code.includes("\n")) {
-              return (
-                <code
-                  className={cn(
-                    "px-1.5 py-0.5 rounded border border-border bg-muted text-foreground text-[0.85em] font-mono",
-                    codeClass,
-                  )}
-                  {...rest}
-                >
-                  {codeChildren}
-                </code>
-              );
-            }
-
-            return (
-              <CodeBlock code={code} language={language}>
-                <CopyButton text={code} />
-              </CodeBlock>
-            );
-          },
-        }}
-      >
-        {children}
-      </ReactMarkdown>
+      <LinkChipContext.Provider value={linkChip}>
+        <ReactMarkdown
+          remarkPlugins={[remarkGfm, remarkCodeMeta]}
+          rehypePlugins={[rehypeSlug, [rehypeSanitize, sanitizeSchema]]}
+          urlTransform={(url, key, node) => transformMarkdownUrl(url, key, node, urlTransform)}
+          components={{
+            a: MarkdownLink,
+            img: MarkdownImage,
+            pre: MarkdownPre,
+            code: MarkdownCode,
+            table: MarkdownTable,
+            thead: MarkdownTableHead,
+            tbody: MarkdownTableBody,
+            tr: MarkdownTableRow,
+            th: MarkdownTableHeaderCell,
+            td: MarkdownTableCell,
+          }}
+        >
+          {children}
+        </ReactMarkdown>
+      </LinkChipContext.Provider>
     </div>
   );
 });

package/src/run/approval-card.test.tsx

@@ -0,0 +1,41 @@
+import { cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { ApprovalCard } from "./approval-card";
+
+afterEach(cleanup);
+
+describe("ApprovalCard", () => {
+  it("shows the plain-language action, its step, the plan, the diff and the raw input behind Details", () => {
+    render(
+      <ApprovalCard
+        title="Create a commit for src/routes/_index.tsx in tangle-network/gtm-agent"
+        context="GitHub · tangle-network/gtm-agent"
+        step={{ index: 1, total: 4 }}
+        plan={[
+          { label: "Write the change", state: "current" },
+          { label: "Commit it", state: "upcoming" },
+        ]}
+        diff={[{ path: "src/routes/_index.tsx", change: "modified", additions: 3, deletions: 1 }]}
+        details={<pre>{'{"tree":[]}'}</pre>}
+        actions={<button type="button">Approve all 4 steps</button>}
+      />,
+    );
+    const card = screen.getByRole("group", { name: "Approval request" });
+    expect(within(card).getByRole("heading").textContent).toContain("Create a commit for src/routes/_index.tsx");
+    expect(within(card).getByText("Step 1 of 4")).toBeInTheDocument();
+    expect(within(card).getByRole("list", { name: "Plan" }).querySelector('[aria-current="step"]')?.textContent).toBe("Write the change");
+    expect(within(card).getByText("1 file")).toBeInTheDocument();
+    expect(within(card).getAllByText("+3")).toHaveLength(2);
+    const details = within(card).getByText("Details").closest("details")!;
+    expect(details.open).toBe(false);
+    fireEvent.click(within(card).getByText("Details"));
+    expect(details.open).toBe(true);
+    expect(within(card).getByRole("button", { name: "Approve all 4 steps" })).toBeInTheDocument();
+  });
+
+  it("marks unknown line counts instead of guessing zero", () => {
+    render(<ApprovalCard title="Write" diff={[{ path: "a.ts", additions: 2 }]} diffNote="Counting lines…" />);
+    expect(screen.getByText("Counting lines…")).toBeInTheDocument();
+    expect(screen.getByText("−–")).toBeInTheDocument();
+  });
+});

package/src/run/approval-card.tsx

@@ -0,0 +1,146 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import { Check, ChevronRight, Circle, FileMinus, FilePen, FilePlus } from "lucide-react";
+import { cn } from "../lib/utils";
+
+export interface ApprovalDiffFile {
+  path: string;
+  change?: "added" | "modified" | "deleted";
+  /** Unknown counts render as a dash rather than a guessed zero. */
+  additions?: number;
+  deletions?: number;
+}
+
+export interface ApprovalPlanStep {
+  label: ReactNode;
+  state: "done" | "current" | "upcoming";
+}
+
+export interface ApprovalCardProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  /** What the action does, in plain words. */
+  title: ReactNode;
+  /** Where it acts, such as "GitHub · owner/repo". */
+  context?: ReactNode;
+  /** This action's place in a declared plan. */
+  step?: { index: number; total: number };
+  /** The plan's steps, when the action belongs to one. */
+  plan?: readonly ApprovalPlanStep[];
+  /** Files the action writes, with line counts when known. */
+  diff?: readonly ApprovalDiffFile[];
+  /** Shown while line counts are being read. */
+  diffNote?: ReactNode;
+  /** The raw request, behind a Details toggle. */
+  details?: ReactNode;
+  status?: ReactNode;
+  actions?: ReactNode;
+}
+
+const CHANGE_ICON = { added: FilePlus, modified: FilePen, deleted: FileMinus } as const;
+
+function count(value: number | undefined, sign: "+" | "−"): string {
+  return value === undefined ? `${sign}–` : `${sign}${value}`;
+}
+
+/** Files and +/− line counts for a write, with totals when every count is known. */
+export function ApprovalDiffSummary({ files, note }: { files: readonly ApprovalDiffFile[]; note?: ReactNode }) {
+  const known = files.every((file) => file.additions !== undefined && file.deletions !== undefined);
+  const additions = files.reduce((sum, file) => sum + (file.additions ?? 0), 0);
+  const deletions = files.reduce((sum, file) => sum + (file.deletions ?? 0), 0);
+  return (
+    <div className="rounded-lg border border-border">
+      <div className="flex flex-wrap items-center justify-between gap-2 border-b border-border px-3 py-2 text-sm">
+        <span className="font-medium text-foreground">{files.length === 1 ? "1 file" : `${files.length} files`}</span>
+        {known
+          ? (
+              <span className="tabular-nums">
+                <span className="text-[var(--surface-success-text)]">+{additions}</span>{" "}
+                <span className="text-[var(--surface-danger-text)]">−{deletions}</span>
+              </span>
+            )
+          : note && <span className="text-muted-foreground">{note}</span>}
+      </div>
+      <ul className="divide-y divide-border/70">
+        {files.map((file) => {
+          const Icon = CHANGE_ICON[file.change ?? "modified"];
+          return (
+            <li key={file.path} className="flex items-center justify-between gap-3 px-3 py-2 text-sm">
+              <span className="flex min-w-0 items-center gap-2">
+                <Icon aria-hidden className="size-4 shrink-0 text-muted-foreground" />
+                <span className="min-w-0 truncate font-mono text-foreground" title={file.path}>{file.path}</span>
+              </span>
+              <span className="shrink-0 tabular-nums">
+                <span className="text-[var(--surface-success-text)]">{count(file.additions, "+")}</span>{" "}
+                <span className="text-[var(--surface-danger-text)]">{count(file.deletions, "−")}</span>
+              </span>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+
+function PlanMarker({ state }: { state: ApprovalPlanStep["state"] }) {
+  if (state === "done") return <Check aria-hidden className="size-4 shrink-0 text-[var(--surface-success-text)]" />;
+  if (state === "current") return <ChevronRight aria-hidden className="size-4 shrink-0 text-foreground" />;
+  return <Circle aria-hidden className="size-3.5 shrink-0 text-muted-foreground" />;
+}
+
+/**
+ * A request for a person to approve one action: what it does in plain words,
+ * where, its step in a plan, the files it writes, and the raw request behind
+ * a Details toggle. The caller owns the decision and supplies the actions.
+ */
+export function ApprovalCard({
+  title, context, step, plan, diff, diffNote, details, status, actions, className, ...props
+}: ApprovalCardProps) {
+  return (
+    <section
+      role="group"
+      aria-label="Approval request"
+      {...props}
+      className={cn("space-y-3 rounded-xl border border-border bg-card p-4 shadow-sm", className)}
+    >
+      <div className="space-y-1">
+        {(step || context) && (
+          <p className="flex flex-wrap items-center gap-2 text-sm text-muted-foreground">
+            {step && (
+              <span className="rounded-md bg-muted px-2 py-0.5 font-medium text-foreground">
+                Step {step.index} of {step.total}
+              </span>
+            )}
+            {context && <span className="min-w-0 truncate">{context}</span>}
+          </p>
+        )}
+        <h3 className="text-base font-semibold leading-6 text-foreground">{title}</h3>
+      </div>
+      {plan && plan.length > 0 && (
+        <ol className="space-y-1.5" aria-label="Plan">
+          {plan.map((item, index) => (
+            <li
+              key={index}
+              aria-current={item.state === "current" ? "step" : undefined}
+              className={cn(
+                "flex items-start gap-2 text-sm leading-6",
+                item.state === "current" ? "font-medium text-foreground" : "text-muted-foreground",
+              )}
+            >
+              <span className="mt-1"><PlanMarker state={item.state} /></span>
+              <span className="min-w-0">{item.label}</span>
+            </li>
+          ))}
+        </ol>
+      )}
+      {diff && diff.length > 0 && <ApprovalDiffSummary files={diff} note={diffNote} />}
+      {details !== undefined && (
+        <details className="group text-sm">
+          <summary className="cursor-pointer select-none font-medium text-muted-foreground hover:text-foreground">
+            Details
+          </summary>
+          <div className="mt-2">{details}</div>
+        </details>
+      )}
+      {status}
+      {actions && <div className="flex flex-wrap gap-2">{actions}</div>}
+    </section>
+  );
+}

package/src/run/index.ts

@@ -20,3 +20,20 @@ export { LiveDuration } from "./run-item-primitives";
 // because ToolCallData references it.
 export { type ToolCallType, type ToolCallStatus } from "./tool-call-step";
 export { ToolCallFeed, parseToolEvent, type ToolCallFeedProps, type ToolCallData, type FeedSegment } from "./tool-call-feed";
+export {
+  TaskList,
+  taskProgress,
+  taskStatus,
+  showsTaskPriority,
+  type TaskListItem,
+  type TaskListProps,
+  type TaskStatus,
+} from "./task-list";
+export {
+  ApprovalCard,
+  ApprovalDiffSummary,
+  type ApprovalCardProps,
+  type ApprovalDiffFile,
+  type ApprovalPlanStep,
+} from "./approval-card";
+export { RunPhaseList, type RunPhase } from "./run-phase-list";

package/src/run/run-phase-list.test.tsx

@@ -0,0 +1,25 @@
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { RunPhaseList } from "./run-phase-list";
+
+afterEach(cleanup);
+
+describe("RunPhaseList", () => {
+  it("collapses each phase to one summarizing line and expands its steps", () => {
+    render(
+      <RunPhaseList
+        phases={[
+          { id: "a", title: "Find the hero source", summary: "Read 12 files · searched 3 times", content: <p>step detail</p> },
+          { id: "b", title: "Open a draft PR", summary: "4 GitHub calls", status: "error", content: <p>pr detail</p> },
+        ]}
+      />,
+    );
+    const first = screen.getByRole("button", { name: /Find the hero source/ });
+    expect(first.textContent).toContain("Read 12 files · searched 3 times");
+    expect(first.getAttribute("aria-expanded")).toBe("false");
+    expect(screen.queryByText("step detail")).toBeNull();
+    fireEvent.click(first);
+    expect(screen.getByText("step detail")).toBeInTheDocument();
+    expect(screen.getByLabelText("Had an error")).toBeInTheDocument();
+  });
+});