@tangle-network/ui 1.0.0

package/src/tool-previews/glob-results-preview.tsx

@@ -0,0 +1,98 @@
+import { memo, useMemo } from "react";
+import { FileText, FolderOpen } from "lucide-react";
+import type { ToolPart } from "../types/parts";
+import { PreviewCard, PreviewEmpty, PreviewError, PreviewLoading } from "./preview-primitives";
+
+function coerceString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function extractPattern(input: unknown): string | undefined {
+  if (!input || typeof input !== "object") {
+    return undefined;
+  }
+
+  const record = input as Record<string, unknown>;
+  return coerceString(record.pattern) ?? coerceString(record.path);
+}
+
+function extractFiles(output: unknown): string[] {
+  if (Array.isArray(output)) {
+    return output.map((item) => String(item)).filter(Boolean);
+  }
+
+  if (output && typeof output === "object") {
+    const record = output as Record<string, unknown>;
+    const candidate = record.files ?? record.matches ?? record.paths ?? record.results;
+
+    if (Array.isArray(candidate)) {
+      return candidate
+        .map((item) =>
+          typeof item === "string"
+            ? item
+            : item && typeof item === "object"
+              ? String(
+                  (item as Record<string, unknown>).path ??
+                    (item as Record<string, unknown>).file ??
+                    "",
+                )
+              : "",
+        )
+        .filter(Boolean);
+    }
+  }
+
+  if (typeof output === "string") {
+    return output
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+  }
+
+  return [];
+}
+
+export interface GlobResultsPreviewProps {
+  part: ToolPart;
+}
+
+export const GlobResultsPreview = memo(({ part }: GlobResultsPreviewProps) => {
+  const pattern = extractPattern(part.state.input);
+  const files = useMemo(() => extractFiles(part.state.output), [part.state.output]);
+
+  return (
+    <PreviewCard
+      icon={<FolderOpen className="h-4 w-4" />}
+      title={pattern ? `Files for ${pattern}` : "File results"}
+      description={files.length > 0 ? `${files.length} path${files.length === 1 ? "" : "s"}` : undefined}
+    >
+      {part.state.status === "running" ? <PreviewLoading label="Collecting files…" /> : null}
+      {part.state.error ? <PreviewError error={part.state.error} /> : null}
+      {part.state.status === "completed" && files.length === 0 ? (
+        <PreviewEmpty label="No matching files were returned." />
+      ) : null}
+      {files.length > 0 ? (
+        <div className="grid gap-2 sm:grid-cols-2">
+          {files.map((file) => {
+            const isDirectory = file.endsWith("/");
+            const Icon = isDirectory ? FolderOpen : FileText;
+
+            return (
+              <div
+                key={file}
+                className="flex items-center gap-2 rounded-[var(--radius-md)] border border-border bg-muted/55 px-3 py-2"
+              >
+                <Icon className="h-4 w-4 shrink-0 text-primary" />
+                <span className="min-w-0 truncate text-xs font-mono text-foreground">
+                  {file}
+                </span>
+              </div>
+            );
+          })}
+        </div>
+      ) : null}
+    </PreviewCard>
+  );
+});
+
+GlobResultsPreview.displayName = "GlobResultsPreview";

package/src/tool-previews/grep-results-preview.tsx

@@ -0,0 +1,157 @@
+import { memo, useMemo } from "react";
+import { Search } from "lucide-react";
+import type { ToolPart } from "../types/parts";
+import { PreviewCard, PreviewEmpty, PreviewError, PreviewLoading } from "./preview-primitives";
+
+interface GrepMatch {
+  path: string;
+  line?: number;
+  text: string;
+}
+
+function coerceString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function parseMatch(value: unknown): GrepMatch | null {
+  if (typeof value === "string") {
+    const [path, maybeLine, ...rest] = value.split(":");
+    const line = Number(maybeLine);
+
+    if (rest.length > 0 && Number.isFinite(line)) {
+      return {
+        path,
+        line,
+        text: rest.join(":").trim(),
+      };
+    }
+
+    return {
+      path: "match",
+      text: value,
+    };
+  }
+
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const record = value as Record<string, unknown>;
+  const path =
+    coerceString(record.path) ??
+    coerceString(record.file) ??
+    coerceString(record.filePath) ??
+    "match";
+  const lineValue = record.line ?? record.lineNumber ?? record.line_number;
+  const line = typeof lineValue === "number" ? lineValue : Number(lineValue);
+  const text =
+    coerceString(record.text) ??
+    coerceString(record.content) ??
+    coerceString(record.lineText) ??
+    coerceString(record.preview);
+
+  if (!text) {
+    return null;
+  }
+
+  return {
+    path,
+    line: Number.isFinite(line) ? line : undefined,
+    text,
+  };
+}
+
+function extractPattern(input: unknown): string | undefined {
+  if (!input || typeof input !== "object") {
+    return undefined;
+  }
+
+  const record = input as Record<string, unknown>;
+  return coerceString(record.pattern) ?? coerceString(record.query);
+}
+
+function extractMatches(output: unknown): GrepMatch[] {
+  if (Array.isArray(output)) {
+    return output.map(parseMatch).filter((value): value is GrepMatch => value !== null);
+  }
+
+  if (output && typeof output === "object") {
+    const record = output as Record<string, unknown>;
+    const candidates = [record.matches, record.results, record.output];
+
+    for (const candidate of candidates) {
+      if (Array.isArray(candidate)) {
+        return candidate.map(parseMatch).filter((value): value is GrepMatch => value !== null);
+      }
+    }
+  }
+
+  if (typeof output === "string") {
+    return output
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map(parseMatch)
+      .filter((value): value is GrepMatch => value !== null);
+  }
+
+  return [];
+}
+
+export interface GrepResultsPreviewProps {
+  part: ToolPart;
+}
+
+export const GrepResultsPreview = memo(({ part }: GrepResultsPreviewProps) => {
+  const pattern = extractPattern(part.state.input);
+  const matches = useMemo(() => extractMatches(part.state.output), [part.state.output]);
+  const groupedMatches = useMemo(() => {
+    const groups = new Map<string, GrepMatch[]>();
+
+    for (const match of matches) {
+      const list = groups.get(match.path) ?? [];
+      list.push(match);
+      groups.set(match.path, list);
+    }
+
+    return [...groups.entries()];
+  }, [matches]);
+
+  return (
+    <PreviewCard
+      icon={<Search className="h-4 w-4" />}
+      title={pattern ? `Search results for "${pattern}"` : "Search results"}
+      description={matches.length > 0 ? `${matches.length} match${matches.length === 1 ? "" : "es"}` : undefined}
+    >
+      {part.state.status === "running" ? <PreviewLoading label="Searching files…" /> : null}
+      {part.state.error ? <PreviewError error={part.state.error} /> : null}
+      {part.state.status === "completed" && matches.length === 0 ? (
+        <PreviewEmpty label="No matching files or lines were returned." />
+      ) : null}
+      {groupedMatches.map(([path, pathMatches]) => (
+        <div
+          key={path}
+          className="rounded-[var(--radius-md)] border border-border bg-muted/55"
+        >
+          <div className="border-b border-border px-3 py-2 text-xs font-medium text-foreground">
+            {path}
+          </div>
+          <div className="divide-y divide-border">
+            {pathMatches.map((match, index) => (
+              <div key={`${path}-${match.line ?? index}-${index}`} className="grid grid-cols-[auto_minmax(0,1fr)] gap-3 px-3 py-2">
+                <div className="pt-0.5 text-xs font-mono text-muted-foreground">
+                  {match.line ?? "·"}
+                </div>
+                <pre className="overflow-x-auto whitespace-pre-wrap break-words text-xs font-mono text-foreground">
+                  {match.text}
+                </pre>
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </PreviewCard>
+  );
+});
+
+GrepResultsPreview.displayName = "GrepResultsPreview";

package/src/tool-previews/index.ts

@@ -0,0 +1,22 @@
+export { CommandPreview, type CommandPreviewProps } from "./command-preview";
+export {
+  WriteFilePreview,
+  type WriteFilePreviewProps,
+} from "./write-file-preview";
+export {
+  GrepResultsPreview,
+  type GrepResultsPreviewProps,
+} from "./grep-results-preview";
+export {
+  GlobResultsPreview,
+  type GlobResultsPreviewProps,
+} from "./glob-results-preview";
+export {
+  WebSearchPreview,
+  type WebSearchPreviewProps,
+} from "./web-search-preview";
+export {
+  QuestionPreview,
+  type QuestionPreviewProps,
+} from "./question-preview";
+export { DiffPreview, type DiffPreviewProps } from "./diff-preview";

package/src/tool-previews/preview-primitives.tsx

@@ -0,0 +1,84 @@
+import type { ReactNode } from "react";
+import { Loader2 } from "lucide-react";
+import { cn } from "../lib/utils";
+
+export interface PreviewCardProps {
+  icon: ReactNode;
+  title: string;
+  description?: string;
+  meta?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+}
+
+export function PreviewCard({
+  icon,
+  title,
+  description,
+  meta,
+  children,
+  className,
+}: PreviewCardProps) {
+  return (
+    <div
+      className={cn(
+        "overflow-hidden rounded-[var(--radius-lg)] border border-border bg-card shadow-[var(--shadow-card)]",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2.5 border-b border-border bg-card px-[var(--tool-card-px)] py-[var(--tool-card-py)]">
+        <div className="flex h-[var(--tool-icon-size)] w-[var(--tool-icon-size)] shrink-0 items-center justify-center rounded-[var(--radius-sm)] border border-[var(--border-accent)] bg-muted text-primary">
+          {icon}
+        </div>
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2">
+            <span className="text-xs font-semibold text-foreground">{title}</span>
+            {description ? (
+              <span className="truncate text-xs font-mono text-muted-foreground">{description}</span>
+            ) : null}
+          </div>
+        </div>
+        {meta ? (
+          <div className="shrink-0 text-xs text-muted-foreground">{meta}</div>
+        ) : null}
+      </div>
+      {children ? <div className="space-y-2 px-[var(--tool-card-px)] py-[var(--tool-card-py)]">{children}</div> : null}
+    </div>
+  );
+}
+
+export function PreviewEmpty({
+  label,
+  className,
+}: {
+  label: string;
+  className?: string;
+}) {
+  return (
+    <div
+      className={cn(
+        "rounded-[var(--radius-md)] border border-dashed border-border bg-muted px-3 py-2.5 text-xs text-muted-foreground",
+        className,
+      )}
+    >
+      {label}
+    </div>
+  );
+}
+
+export function PreviewError({ error }: { error: string }) {
+  return (
+    <div className="rounded-[var(--radius-md)] border border-[var(--surface-danger-border)] bg-[var(--surface-danger-bg)] px-3 py-3 text-sm text-[var(--surface-danger-text)]">
+      {error}
+    </div>
+  );
+}
+
+export function PreviewLoading({ label = "Running…" }: { label?: string }) {
+  return (
+    <div className="flex items-center gap-2 rounded-[var(--radius-md)] border border-border bg-muted px-3 py-2 text-xs text-muted-foreground">
+      <Loader2 className="h-4 w-4 animate-spin text-primary" />
+      <span>{label}</span>
+    </div>
+  );
+}

package/src/tool-previews/question-preview.tsx

@@ -0,0 +1,101 @@
+import { memo, useMemo } from "react";
+import { MessageSquareQuote } from "lucide-react";
+import type { ToolPart } from "../types/parts";
+import { PreviewCard, PreviewEmpty, PreviewError, PreviewLoading } from "./preview-primitives";
+
+function toQuestionList(input: unknown): string[] {
+  if (!input) {
+    return [];
+  }
+
+  if (typeof input === "string") {
+    return [input];
+  }
+
+  if (Array.isArray(input)) {
+    return input.map((item) => String(item)).filter(Boolean);
+  }
+
+  if (typeof input === "object") {
+    const record = input as Record<string, unknown>;
+    const value = record.questions ?? record.question ?? record.prompt;
+
+    if (Array.isArray(value)) {
+      return value.map((item) => String(item)).filter(Boolean);
+    }
+
+    if (typeof value === "string") {
+      return [value];
+    }
+  }
+
+  return [];
+}
+
+function toAnswerList(output: unknown): string[] {
+  if (!output) {
+    return [];
+  }
+
+  if (typeof output === "string") {
+    return [output];
+  }
+
+  if (Array.isArray(output)) {
+    return output.map((item) => String(item)).filter(Boolean);
+  }
+
+  if (typeof output === "object") {
+    const record = output as Record<string, unknown>;
+    const value = record.answers ?? record.answer ?? record.response;
+
+    if (Array.isArray(value)) {
+      return value.map((item) => String(item)).filter(Boolean);
+    }
+
+    if (typeof value === "string") {
+      return [value];
+    }
+  }
+
+  return [];
+}
+
+export interface QuestionPreviewProps {
+  part: ToolPart;
+}
+
+export const QuestionPreview = memo(({ part }: QuestionPreviewProps) => {
+  const questions = useMemo(() => toQuestionList(part.state.input), [part.state.input]);
+  const answers = useMemo(() => toAnswerList(part.state.output), [part.state.output]);
+
+  return (
+    <PreviewCard
+      icon={<MessageSquareQuote className="h-4 w-4" />}
+      title="Agent question"
+      description={questions.length > 1 ? `${questions.length} questions require attention` : undefined}
+    >
+      {part.state.status === "running" ? <PreviewLoading label="Waiting for an answer…" /> : null}
+      {part.state.error ? <PreviewError error={part.state.error} /> : null}
+      {questions.length === 0 ? <PreviewEmpty label="No question text was provided." /> : null}
+      {questions.map((question, index) => (
+        <div
+          key={`${question}-${index}`}
+          className="rounded-[var(--radius-md)] border border-border bg-muted px-3 py-3"
+        >
+          <div className="text-xs font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+            Question {index + 1}
+          </div>
+          <div className="mt-2 text-sm leading-relaxed text-foreground">
+            {question}
+          </div>
+          <div className="mt-3 rounded-[var(--radius-sm)] border border-border bg-card px-3 py-2 text-sm text-foreground">
+            {answers[index] ?? (part.state.status === "completed" ? "No answer recorded." : "Awaiting answer")}
+          </div>
+        </div>
+      ))}
+    </PreviewCard>
+  );
+});
+
+QuestionPreview.displayName = "QuestionPreview";

package/src/tool-previews/web-search-preview.tsx

@@ -0,0 +1,117 @@
+import { memo, useMemo } from "react";
+import { Globe } from "lucide-react";
+import type { ToolPart } from "../types/parts";
+import { PreviewCard, PreviewEmpty, PreviewError, PreviewLoading } from "./preview-primitives";
+
+interface SearchResult {
+  title: string;
+  url: string;
+  snippet?: string;
+}
+
+function coerceString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function extractQuery(input: unknown, output: unknown): string | undefined {
+  if (input && typeof input === "object") {
+    const record = input as Record<string, unknown>;
+    const query = coerceString(record.query) ?? coerceString(record.url);
+    if (query) return query;
+  }
+
+  if (output && typeof output === "object") {
+    const record = output as Record<string, unknown>;
+    return coerceString(record.query);
+  }
+
+  return undefined;
+}
+
+function parseResult(value: unknown): SearchResult | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const record = value as Record<string, unknown>;
+  const title = coerceString(record.title) ?? coerceString(record.name) ?? "Untitled result";
+  const url = coerceString(record.url) ?? coerceString(record.link);
+
+  if (!url) {
+    return null;
+  }
+
+  return {
+    title,
+    url,
+    snippet:
+      coerceString(record.snippet) ??
+      coerceString(record.description) ??
+      coerceString(record.text),
+  };
+}
+
+function extractResults(output: unknown): SearchResult[] {
+  if (output && typeof output === "object") {
+    const record = output as Record<string, unknown>;
+    const candidate = record.results ?? record.items ?? record.output;
+
+    if (Array.isArray(candidate)) {
+      return candidate.map(parseResult).filter((value): value is SearchResult => value !== null);
+    }
+  }
+
+  if (Array.isArray(output)) {
+    return output.map(parseResult).filter((value): value is SearchResult => value !== null);
+  }
+
+  return [];
+}
+
+export interface WebSearchPreviewProps {
+  part: ToolPart;
+}
+
+export const WebSearchPreview = memo(({ part }: WebSearchPreviewProps) => {
+  const query = extractQuery(part.state.input, part.state.output);
+  const results = useMemo(() => extractResults(part.state.output), [part.state.output]);
+
+  return (
+    <PreviewCard
+      icon={<Globe className="h-4 w-4" />}
+      title={query ? `Web results for ${query}` : "Web results"}
+      description={results.length > 0 ? `${results.length} result${results.length === 1 ? "" : "s"}` : undefined}
+    >
+      {part.state.status === "running" ? <PreviewLoading label="Searching the web…" /> : null}
+      {part.state.error ? <PreviewError error={part.state.error} /> : null}
+      {part.state.status === "completed" && results.length === 0 ? (
+        <PreviewEmpty label="No web results were returned." />
+      ) : null}
+      <div className="space-y-2">
+        {results.map((result) => (
+          <a
+            key={result.url}
+            href={result.url}
+            target="_blank"
+            rel="noreferrer"
+            className="block rounded-[var(--radius-md)] border border-border bg-muted/55 px-3 py-3 transition-colors hover:border-[var(--border-accent-hover)] hover:bg-accent/50"
+          >
+            <div className="text-sm font-medium text-foreground">
+              {result.title}
+            </div>
+            <div className="mt-1 truncate text-xs text-primary">
+              {result.url}
+            </div>
+            {result.snippet ? (
+              <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
+                {result.snippet}
+              </p>
+            ) : null}
+          </a>
+        ))}
+      </div>
+    </PreviewCard>
+  );
+});
+
+WebSearchPreview.displayName = "WebSearchPreview";

package/src/tool-previews/write-file-preview.tsx

@@ -0,0 +1,80 @@
+import { memo } from "react";
+import { FileEdit } from "lucide-react";
+import type { ToolPart } from "../types/parts";
+import { CodeBlock, CopyButton } from "../markdown/code-block";
+import { PreviewCard, PreviewError, PreviewLoading } from "./preview-primitives";
+
+export interface WriteFilePreviewProps {
+  part: ToolPart;
+}
+
+function extractWriteContent(
+  input: unknown,
+): { path: string; content: string } | null {
+  if (!input || typeof input !== "object") return null;
+  const obj = input as Record<string, unknown>;
+  const path = String(obj.file_path ?? obj.path ?? obj.filePath ?? "unknown");
+  const content = String(obj.content ?? obj.contents ?? obj.data ?? "");
+  return { path, content };
+}
+
+function getLanguageFromPath(path: string): string | undefined {
+  const ext = path.split(".").pop()?.toLowerCase();
+  const map: Record<string, string> = {
+    ts: "typescript",
+    tsx: "tsx",
+    js: "javascript",
+    jsx: "jsx",
+    rs: "rust",
+    py: "python",
+    go: "go",
+    rb: "ruby",
+    json: "json",
+    yaml: "yaml",
+    yml: "yaml",
+    toml: "toml",
+    md: "markdown",
+    css: "css",
+    scss: "scss",
+    html: "html",
+    sh: "bash",
+    bash: "bash",
+    zsh: "bash",
+    sql: "sql",
+    sol: "solidity",
+    proto: "protobuf",
+  };
+  return ext ? map[ext] : undefined;
+}
+
+/**
+ * Preview for file write/create operations.
+ * Shows file path, line count, and the written content.
+ */
+export const WriteFilePreview = memo(({ part }: WriteFilePreviewProps) => {
+  const write = extractWriteContent(part.state.input);
+  if (!write) return null;
+
+  const lineCount = write.content.split("\n").length;
+  const language = getLanguageFromPath(write.path);
+
+  return (
+    <PreviewCard
+      icon={<FileEdit className="h-4 w-4" />}
+      title="Write file"
+      description={write.path}
+      meta={
+        <span className="text-xs text-muted-foreground">
+          +{lineCount} line{lineCount !== 1 ? "s" : ""}
+        </span>
+      }
+    >
+      {part.state.status === "running" ? <PreviewLoading label="Writing file…" /> : null}
+      {part.state.error ? <PreviewError error={part.state.error} /> : null}
+      <CodeBlock code={write.content} language={language} className="rounded-[var(--radius-md)]">
+        <CopyButton text={write.content} />
+      </CodeBlock>
+    </PreviewCard>
+  );
+});
+WriteFilePreview.displayName = "WriteFilePreview";

package/src/types/branding.ts

@@ -0,0 +1,11 @@
+/** Visual branding for a run group header — injected by consuming app. */
+export interface AgentBranding {
+  label: string;
+  accentClass: string;
+  bgClass: string;
+  containerBgClass: string;
+  borderClass: string;
+  /** CSS class for the agent icon (legacy). Ignored when using lucide-react icons. */
+  iconClass: string;
+  textClass: string;
+}

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export * from "./branding";
+export * from "./message";
+export * from "./parts";
+export * from "./run";
+export * from "./tool-display";

package/src/types/message.ts

@@ -0,0 +1,13 @@
+/** A single message in a chat session. */
+export interface SessionMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  sessionID?: string;
+  time?: {
+    created?: number;
+    updated?: number;
+    completed?: number;
+  };
+  /** Monotonically increasing insertion index for stable ordering. */
+  _insertionIndex?: number;
+}