Web UI Types

Type definitions for the Web UI package

Core TypeScript types for the @mariozechner/pi-web-ui package.

Import

import type {
  Attachment,
  MessageRenderer,
  ToolRenderer,
  SandboxRuntimeProvider,
  ConsoleLog,
  ArtifactMessage,
} from "@mariozechner/pi-web-ui";

Message Types

ArtifactMessage

Custom message type for artifact content (HTML, SVG, etc.).

interface ArtifactMessage {
  role: "artifact";
  type: "html" | "svg" | "markdown" | "text" | "image";
  title: string;
  content: string;
  timestamp: number;
}

Extend CustomAgentMessages to use in agent:

declare module "@mariozechner/pi-agent-core" {
  interface CustomAgentMessages {
    artifact: ArtifactMessage;
  }
}

UserMessageWithAttachments

User message with file attachments.

interface UserMessageWithAttachments {
  role: "user";
  content: string | Content[];
  attachments?: Attachment[];
  timestamp: number;
}

Attachment Types

Attachment

File attachment data.

interface Attachment {
  name: string;
  type: string;  // MIME type
  data: string;  // base64 encoded
  size?: number; // bytes
}

Example

const attachment: Attachment = {
  name: "screenshot.png",
  type: "image/png",
  data: "iVBORw0KGgoAAAANSUhEUgAA...",
  size: 12345,
};

Renderer Types

MessageRenderer

Custom message renderer function.

type MessageRenderer<T = any> = (props: {
  message: T;
  isStreaming?: boolean;
}) => React.ReactElement | null;

Example

import { registerMessageRenderer } from "@mariozechner/pi-web-ui";

const artifactRenderer: MessageRenderer<ArtifactMessage> = ({ message }) => {
  return (
    <div className="artifact">
      <h3>{message.title}</h3>
      <div dangerouslySetInnerHTML={{ __html: message.content }} />
    </div>
  );
};

registerMessageRenderer("artifact", artifactRenderer);

ToolRenderer

Custom tool result renderer.

interface ToolRenderResult {
  content: React.ReactElement;
  summary?: string;
}

type ToolRenderer = (props: {
  toolName: string;
  content: Content[];
  details: any;
  isStreaming?: boolean;
}) => ToolRenderResult;

Example

import { registerToolRenderer } from "@mariozechner/pi-web-ui";

const searchRenderer: ToolRenderer = ({ details }) => {
  return {
    content: (
      <div>
        <h4>Search Results</h4>
        <p>Found {details.count} results</p>
      </div>
    ),
    summary: `Found ${details.count} results`,
  };
};

registerToolRenderer("search", searchRenderer);

Sandbox Types

SandboxRuntimeProvider

Runtime provider for sandboxed code execution.

interface SandboxRuntimeProvider {
  name: string;
  description: string;
  provideRuntime: (iframe: HTMLIFrameElement) => void;
}

ConsoleLog

Console log entry.

interface ConsoleLog {
  type: "log" | "error" | "warn" | "info";
  message: string;
  timestamp?: number;
}

DownloadableFile

File available for download from sandbox.

interface DownloadableFile {
  name: string;
  content: string | Blob;
  mimeType: string;
}

Storage Types

SessionData

Session data stored in IndexedDB.

interface SessionData {
  id: string;
  name?: string;
  messages: AgentMessage[];
  model: Model;
  thinkingLevel: ThinkingLevel;
  timestamp: number;
  lastModified: number;
}

SessionMetadata

Session metadata for list display.

interface SessionMetadata {
  id: string;
  name?: string;
  timestamp: number;
  lastModified: number;
  messageCount: number;
}

Settings Types

CustomProvider

Custom API provider configuration.

interface CustomProvider {
  id: string;
  name: string;
  type: CustomProviderType;
  baseUrl: string;
  apiKey?: string;
  models?: string[];
}

CustomProviderType

type CustomProviderType = "openai" | "anthropic" | "openai-compatible" | "auto-discovery";

Component Props Types

ChatPanelProps

interface ChatPanelProps {
  agent: Agent;
  onSendMessage: (text: string, attachments?: Attachment[]) => void;
  theme?: "light" | "dark";
  className?: string;
}

AgentInterfaceProps

interface AgentInterfaceProps {
  agent: Agent;
  onSendMessage: (text: string, attachments?: Attachment[]) => void;
  showSidebar?: boolean;
  enableAttachments?: boolean;
  onOpenSettings?: () => void;
  onOpenModelSelector?: () => void;
}

MessageListProps

interface MessageListProps {
  messages: AgentMessage[];
  streamMessage?: AgentMessage | null;
  className?: string;
}

InputProps

interface InputProps {
  onSubmit: (text: string, attachments?: Attachment[]) => void;
  placeholder?: string;
  enableAttachments?: boolean;
  disabled?: boolean;
  className?: string;
}

ModelSelectorProps

interface ModelSelectorProps {
  open: boolean;
  onClose: () => void;
  currentModel: Model;
  onSelectModel: (model: Model, thinkingLevel: ThinkingLevel) => void;
}

SettingsDialogProps

interface SettingsDialogProps {
  open: boolean;
  onClose: () => void;
  tabs?: string[];
}

Example: Type-Safe Usage

import type {
  Attachment,
  MessageRenderer,
  ToolRenderer,
  ArtifactMessage,
  SessionData,
} from "@mariozechner/pi-web-ui";
import { Agent } from "@mariozechner/pi-agent-core";
import { getModel } from "@mariozechner/pi-ai";

// Custom message type
declare module "@mariozechner/pi-agent-core" {
  interface CustomAgentMessages {
    artifact: ArtifactMessage;
  }
}

// Type-safe attachment
const attachment: Attachment = {
  name: "file.txt",
  type: "text/plain",
  data: btoa("Hello, world!"),
};

// Type-safe message renderer
const artifactRenderer: MessageRenderer<ArtifactMessage> = ({ message }) => {
  return <div>{message.content}</div>;
};

// Type-safe tool renderer
const searchRenderer: ToolRenderer = ({ details }) => {
  return {
    content: <div>Found {details.count} results</div>,
    summary: `${details.count} results`,
  };
};

// Type-safe session data
const session: SessionData = {
  id: "session-123",
  name: "My Chat",
  messages: [],
  model: getModel("anthropic", "claude-4.5-sonnet-20250514"),
  thinkingLevel: "medium",
  timestamp: Date.now(),
  lastModified: Date.now(),
};

Storage Backend Types

StorageBackend

Generic storage interface.

interface StorageBackend {
  get<T>(key: string): Promise<T | undefined>;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
  list(): Promise<string[]>;
}

IndexedDBConfig

IndexedDB configuration.

interface IndexedDBConfig {
  databaseName: string;
  version: number;
  stores: StoreConfig[];
}

StoreConfig

IndexedDB store configuration.

interface StoreConfig {
  name: string;
  keyPath: string;
  indexes?: IndexConfig[];
}

IndexConfig

IndexedDB index configuration.

interface IndexConfig {
  name: string;
  keyPath: string | string[];
  unique?: boolean;
}