@tangle-network/sandbox-ui 0.2.2 → 0.3.3

package/README.md

@@ -1,6 +1,4 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/tangle-network/sandbox-ui/main/.github/banner.svg" alt="Tangle Sandbox UI" width="100%" />
-</p>
+![Tangle Network Banner](https://raw.githubusercontent.com/tangle-network/tangle/refs/heads/main/assets/Tangle%20%20Banner.png)
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@tangle-network/sandbox-ui"><img src="https://img.shields.io/npm/v/@tangle-network/sandbox-ui?color=8E59FF&label=npm" alt="npm" /></a>
@@ -10,7 +8,7 @@
 
 # @tangle-network/sandbox-ui
 
-React component library for [Tangle Sandbox](https://sandbox.tangle.tools) — 100+ components for building AI agent interfaces with chat, terminal, file browser, tool call feeds, and dashboard views.
+React component library for [Tangle Sandbox](https://sandbox.tangle.tools) — a shadcn-style primitive layer plus higher-order sandbox surfaces for agent chat, files, runtime state, artifacts, and dashboard views.
 
 ## Install
 
@@ -23,9 +21,12 @@ npm install @tangle-network/sandbox-ui
 ## Usage
 
 ```tsx
-import { Button, Badge, Card } from "@tangle-network/sandbox-ui/primitives";
-import { ChatContainer } from "@tangle-network/sandbox-ui/chat";
-import { WorkspaceLayout } from "@tangle-network/sandbox-ui/workspace";
+import {
+  SandboxWorkbench,
+  type FileNode,
+  type SessionMessage,
+  type SessionPart,
+} from "@tangle-network/sandbox-ui";
 ```
 
 Import styles in your app root:
@@ -34,15 +35,203 @@ Import styles in your app root:
 import "@tangle-network/sandbox-ui/styles";
 ```
 
+If you are building on the sandbox SDK directly, use `useSdkSession` to turn raw SDK/session-gateway events into the `messages + partMap` model that `ChatContainer` and `SandboxWorkbench` expect:
+
+```tsx
+import {
+  SandboxWorkbench,
+} from "@tangle-network/sandbox-ui";
+import { useSdkSession } from "@tangle-network/sandbox-ui/sdk-hooks";
+
+function App() {
+  const {
+    messages,
+    partMap,
+    isStreaming,
+    appendUserMessage,
+    beginAssistantMessage,
+    applySdkEvent,
+    completeAssistantMessage,
+    failAssistantMessage,
+  } = useSdkSession();
+
+  async function runTurn(text: string) {
+    appendUserMessage({ content: text });
+    const assistantMessageId = beginAssistantMessage();
+
+    try {
+      for await (const event of sdk.streamPrompt(text)) {
+        applySdkEvent(event, { messageId: assistantMessageId });
+      }
+      completeAssistantMessage({ messageId: assistantMessageId });
+    } catch (error) {
+      failAssistantMessage(
+        error instanceof Error ? error.message : "Agent run failed",
+        { messageId: assistantMessageId },
+      );
+    }
+  }
+
+  return (
+    <SandboxWorkbench
+      session={{
+        messages,
+        partMap,
+        isStreaming,
+        onSend: runTurn,
+      }}
+    />
+  );
+}
+```
+
+Compose sandbox applications around `SandboxWorkbench` when you want the library’s default operating model:
+
+```tsx
+const root: FileNode = {
+  name: "agent",
+  path: "/home/agent",
+  type: "directory",
+  children: [],
+};
+
+const messages: SessionMessage[] = [];
+const partMap: Record<string, SessionPart[]> = {};
+
+<SandboxWorkbench
+  title="Tax filing workspace"
+  directory={{
+    root,
+    visibility: {
+      hiddenPathPrefixes: ["/home/agent/tax_toolkit"],
+    },
+  }}
+  session={{
+    messages,
+    partMap,
+    isStreaming: false,
+    presentation: "timeline",
+    onSend: console.log,
+  }}
+  runtime={{
+    title: "Runtime",
+  }}
+/>;
+```
+
+`FileTreeVisibilityOptions` is a UI-layer policy only. Sensitive paths still need to be hidden and denied by the app/backend layer.
+
+## Theming And Retheming
+
+There is a built-in Tangle default theme, but consumers can restyle the library in three layers:
+
+1. Pick a built-in surface theme
+2. Override semantic tokens
+3. Wrap higher-level components when you want a different product composition
+
+### 1. Pick a Built-in Theme
+
+`WorkspaceLayout` and `SandboxWorkbench` support:
+
+- `theme="operator"`
+- `theme="builder"`
+- `theme="consumer"`
+
+They also support `density="comfortable"` and `density="compact"`.
+
+```tsx
+<SandboxWorkbench
+  layout={{
+    theme: "consumer",
+    density: "comfortable",
+  }}
+  session={{ ... }}
+/>
+```
+
+If you are not using `SandboxWorkbench`, you can set the same attributes yourself:
+
+```tsx
+<div data-sandbox-ui data-sandbox-theme="consumer" data-density="compact">
+  <YourSandboxApp />
+</div>
+```
+
+### 2. Override Semantic Tokens
+
+The shared visual contract lives in [src/styles/tokens.css](./src/styles/tokens.css). The important tokens are:
+
+- surfaces: `--bg-root`, `--bg-card`, `--bg-elevated`, `--bg-section`, `--bg-input`
+- text: `--text-primary`, `--text-secondary`, `--text-muted`
+- brand: `--brand-cool`, `--brand-glow`, `--brand-purple`
+- accent surfaces: `--accent-gradient-strong`, `--accent-surface-soft`, `--accent-surface-strong`, `--accent-text`
+- borders: `--border-subtle`, `--border-default`, `--border-accent`
+- radii/shadows: `--radius-*`, `--shadow-card`, `--shadow-dropdown`, `--shadow-accent`
+
+App-level overrides can be scoped to a wrapper:
+
+```css
+.tax-theme {
+  --brand-cool: hsl(187 75% 54%);
+  --brand-glow: hsl(164 74% 56%);
+  --bg-root: hsl(222 18% 9%);
+  --bg-card: hsl(223 20% 12%);
+  --border-accent: hsl(187 75% 48% / 0.35);
+  --font-sans: "Satoshi", ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+```tsx
+<div className="tax-theme">
+  <SandboxWorkbench ... />
+</div>
+```
+
+### 3. Know When To Wrap Instead Of Override
+
+Token overrides are the right tool when you want:
+
+- a different brand color system
+- different typography
+- tighter or roomier density
+- a more consumer-facing or operator-facing tone
+
+Wrap or compose on lower-level exports when you want:
+
+- a different page shell
+- different header chrome
+- a different artifact tab model
+- app-specific empty states and actions
+
+The higher-order dashboard/billing surfaces are now accent-token driven rather than hardcoded to the default Tangle look. The main seams are:
+
+- `DashboardLayout.className`, `sidebarClassName`, `contentClassName`
+- `BillingDashboard.className`, `cardClassName`
+- `PricingCards.className`, `cardClassName`
+- `UsageChart.className`
+- `StandalonePricingPage.className`
+
+For that, compose directly from:
+
+- `/workspace`
+- `/chat`
+- `/run`
+- `/files`
+
+### Current Reality
+
+Retheming is absolutely supported, but the documentation was thinner than it should be. The token layer is strong; the higher-level surfaces are themeable, but more opinionated. For a radically different product look, prefer keeping the token contract and wrapping the higher-level workbench/chat surfaces rather than fighting every internal class.
+
 ## Subpath Exports
 
 | Subpath | Description |
 |---------|-------------|
 | `/primitives` | Button, Card, Dialog, Badge, Input, Select, Table, Tabs, Toast, etc. |
-| `/chat` | ChatContainer, ChatInput, ChatMessage, MessageList |
+| `/chat` | ChatContainer, ChatInput, ChatMessage, AgentTimeline, ThinkingIndicator |
 | `/run` | ToolCallFeed, RunGroup, InlineToolItem, ExpandedToolDetail |
-| `/workspace` | WorkspaceLayout, StatusBar, StatusBanner, TerminalPanel |
-| `/files` | FileTree, FilePreview, FileTabs |
+| `/workspace` | SandboxWorkbench, WorkspaceLayout, DirectoryPane, RuntimePane, StatusBar |
+| `/openui` | OpenUIArtifactRenderer and schema types for structured artifact rendering |
+| `/files` | FileTree, FilePreview, FileTabs, FileArtifactPane |
 | `/dashboard` | DashboardLayout, BillingDashboard, UsageChart, ProfileSelector |
 | `/editor` | TipTap collaborative editor (requires optional peers) |
 | `/terminal` | xterm.js terminal view (requires optional peers) |
@@ -50,6 +239,7 @@ import "@tangle-network/sandbox-ui/styles";
 | `/auth` | AuthHeader, GitHubLoginButton, UserMenu |
 | `/pages` | Pre-built billing, pricing, profiles pages |
 | `/hooks` | useSSEStream, useAuth, usePtySession, useRunGroups, etc. |
+| `/sdk-hooks` | Lightweight session/stream hooks without the React Query CRUD hook bundle |
 | `/stores` | Session and chat nanostores |
 | `/types` | TypeScript types for messages, parts, runs, sessions |
 | `/utils` | cn, formatDuration, timeAgo, tool display helpers |
@@ -61,6 +251,7 @@ import "@tangle-network/sandbox-ui/styles";
 - [Tailwind CSS](https://tailwindcss.com/) v4
 - [Lucide](https://lucide.dev/) icons
 - [CVA](https://cva.style/) for variant management
+- Shared semantic tokens for `operator`, `builder`, and `consumer` sandbox themes
 - ESM-only, tree-shakeable, fully typed
 
 ## License

package/dist/auth.js

@@ -2,10 +2,10 @@ import {
   AuthHeader,
   GitHubLoginButton,
   UserMenu
-} from "./chunk-OU4TRNQZ.js";
+} from "./chunk-COCSO7FG.js";
 import "./chunk-B26TQ7SA.js";
 import "./chunk-MCGKDCOR.js";
-import "./chunk-E6FS7R4X.js";
+import "./chunk-HWLX5NME.js";
 import "./chunk-RQHJBTEU.js";
 export {
   AuthHeader,

package/dist/chat-container-C8eHLw8z.d.ts

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { S as SessionMessage, a as SessionPart } from './parts-CyGkM6Fp.js';
+import { A as AgentBranding } from './branding-DCi5VEik.js';
+import { C as CustomToolRenderer } from './tool-display-Ct9nFAzJ.js';
+
+/**
+ * ChatInput — message input bar with file attach, send/cancel, model selector.
+ *
+ * - Auto-resizing textarea (up to max height)
+ * - Enter to send, Shift+Enter for newline
+ * - File attachment button with pending file chips
+ * - Cancel button when streaming
+ * - Optional model selector pill
+ */
+interface PendingFile {
+    id: string;
+    name: string;
+    size: number;
+    status: "pending" | "uploading" | "ready" | "error";
+}
+interface ChatInputProps {
+    onSend: (message: string, files?: File[]) => void;
+    onCancel?: () => void;
+    isStreaming?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    /** Currently selected model label */
+    modelLabel?: string;
+    onModelClick?: () => void;
+    /** Pending uploaded files */
+    pendingFiles?: PendingFile[];
+    onRemoveFile?: (id: string) => void;
+    onAttach?: (files: FileList) => void;
+    className?: string;
+}
+declare function ChatInput({ onSend, onCancel, isStreaming, disabled, placeholder, modelLabel, onModelClick, pendingFiles, onRemoveFile, onAttach, className, }: ChatInputProps): react_jsx_runtime.JSX.Element;
+
+interface ChatContainerProps {
+    messages: SessionMessage[];
+    partMap: Record<string, SessionPart[]>;
+    isStreaming: boolean;
+    onSend?: (text: string) => void;
+    onCancel?: () => void;
+    branding?: AgentBranding;
+    placeholder?: string;
+    className?: string;
+    /** Hide the input area (useful for read-only views). */
+    hideInput?: boolean;
+    /** Custom renderer for tool details. Return ReactNode to override, null to use default. */
+    renderToolDetail?: CustomToolRenderer;
+    /** Presentation mode for the session view. */
+    presentation?: "runs" | "timeline";
+    modelLabel?: string;
+    onModelClick?: () => void;
+    pendingFiles?: PendingFile[];
+    onRemoveFile?: (id: string) => void;
+    onAttach?: (files: FileList) => void;
+    disabled?: boolean;
+}
+/**
+ * Full chat container: message list + auto-scroll + input area.
+ * Orchestrates useRunGroups, useRunCollapseState, and useAutoScroll.
+ */
+declare const ChatContainer: React.MemoExoticComponent<({ messages, partMap, isStreaming, onSend, onCancel, branding, placeholder, className, hideInput, renderToolDetail, presentation, modelLabel, onModelClick, pendingFiles, onRemoveFile, onAttach, disabled, }: ChatContainerProps) => react_jsx_runtime.JSX.Element>;
+
+export { ChatContainer as C, type PendingFile as P, ChatInput as a, type ChatInputProps as b, type ChatContainerProps as c };

package/dist/chat.d.ts

@@ -1,10 +1,12 @@
+export { C as ChatContainer, c as ChatContainerProps, a as ChatInput, b as ChatInputProps, P as PendingFile } from './chat-container-C8eHLw8z.js';
 import * as React from 'react';
 import { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { S as SessionMessage, a as SessionPart } from './parts-CyGkM6Fp.js';
-import { A as AgentBranding } from './branding-DCi5VEik.js';
-import { C as CustomToolRenderer } from './tool-display-BvsVW_Ur.js';
 import { G as GroupedMessage } from './run-CtFZ6s-D.js';
+import { a as SessionPart, S as SessionMessage } from './parts-CyGkM6Fp.js';
+import { A as AgentBranding } from './branding-DCi5VEik.js';
+import { C as CustomToolRenderer } from './tool-display-Ct9nFAzJ.js';
+import { T as ToolCallData } from './tool-call-feed-D5Ume-Pt.js';
 
 type MessageRole = "user" | "assistant" | "system";
 interface ChatMessageProps {
@@ -20,80 +22,6 @@ interface ChatMessageProps {
 }
 declare function ChatMessage({ role, content, toolCalls, isStreaming, timestamp, className, }: ChatMessageProps): react_jsx_runtime.JSX.Element;
 
-interface Message {
-    id: string;
-    role: MessageRole;
-    content: string;
-    toolCalls?: ReactNode;
-    isStreaming?: boolean;
-    timestamp?: Date;
-}
-interface ChatMessageListProps {
-    messages: Message[];
-    /** Render additional content after a message (e.g., tool call feed) */
-    renderAfter?: (message: Message, index: number) => ReactNode;
-    /** Content shown when no messages */
-    emptyState?: ReactNode;
-    /** Show thinking indicator at bottom */
-    isThinking?: boolean;
-    className?: string;
-}
-declare function ChatMessageList({ messages, renderAfter, emptyState, isThinking, className, }: ChatMessageListProps): react_jsx_runtime.JSX.Element;
-declare function ThinkingIndicator({ className }: {
-    className?: string;
-}): react_jsx_runtime.JSX.Element;
-
-/**
- * ChatInput — message input bar with file attach, send/cancel, model selector.
- *
- * - Auto-resizing textarea (up to max height)
- * - Enter to send, Shift+Enter for newline
- * - File attachment button with pending file chips
- * - Cancel button when streaming
- * - Optional model selector pill
- */
-interface PendingFile {
-    id: string;
-    name: string;
-    size: number;
-    status: "pending" | "uploading" | "ready" | "error";
-}
-interface ChatInputProps {
-    onSend: (message: string, files?: File[]) => void;
-    onCancel?: () => void;
-    isStreaming?: boolean;
-    disabled?: boolean;
-    placeholder?: string;
-    /** Currently selected model label */
-    modelLabel?: string;
-    onModelClick?: () => void;
-    /** Pending uploaded files */
-    pendingFiles?: PendingFile[];
-    onRemoveFile?: (id: string) => void;
-    onAttach?: (files: FileList) => void;
-    className?: string;
-}
-declare function ChatInput({ onSend, onCancel, isStreaming, disabled, placeholder, modelLabel, onModelClick, pendingFiles, onRemoveFile, onAttach, className, }: ChatInputProps): react_jsx_runtime.JSX.Element;
-
-interface ChatContainerProps {
-    messages: SessionMessage[];
-    partMap: Record<string, SessionPart[]>;
-    isStreaming: boolean;
-    onSend?: (text: string) => void;
-    branding?: AgentBranding;
-    placeholder?: string;
-    className?: string;
-    /** Hide the input area (useful for read-only views). */
-    hideInput?: boolean;
-    /** Custom renderer for tool details. Return ReactNode to override, null to use default. */
-    renderToolDetail?: CustomToolRenderer;
-}
-/**
- * Full chat container: message list + auto-scroll + input area.
- * Orchestrates useRunGroups, useRunCollapseState, and useAutoScroll.
- */
-declare const ChatContainer: React.MemoExoticComponent<({ messages, partMap, isStreaming, onSend, branding, placeholder, className, hideInput, renderToolDetail, }: ChatContainerProps) => react_jsx_runtime.JSX.Element>;
-
 interface MessageListProps {
     groups: GroupedMessage[];
     partMap: Record<string, SessionPart[]>;
@@ -118,4 +46,68 @@ interface UserMessageProps {
  */
 declare const UserMessage: React.MemoExoticComponent<({ message, parts }: UserMessageProps) => react_jsx_runtime.JSX.Element | null>;
 
-export { ChatContainer, type ChatContainerProps, ChatInput, type ChatInputProps, ChatMessage, ChatMessageList, type ChatMessageListProps, type ChatMessageProps, type Message, MessageList, type MessageListProps, type MessageRole, type PendingFile, ThinkingIndicator, UserMessage, type UserMessageProps };
+interface ThinkingIndicatorProps {
+    className?: string;
+}
+declare function ThinkingIndicator({ className }: ThinkingIndicatorProps): react_jsx_runtime.JSX.Element;
+
+type AgentTimelineTone = "default" | "info" | "success" | "warning" | "error";
+interface AgentTimelineMessageItem {
+    id: string;
+    kind: "message";
+    role: MessageRole;
+    content: string;
+    toolCalls?: ReactNode;
+    isStreaming?: boolean;
+    timestamp?: Date;
+    after?: ReactNode;
+}
+interface AgentTimelineToolItem {
+    id: string;
+    kind: "tool";
+    call: ToolCallData;
+}
+interface AgentTimelineToolGroupItem {
+    id: string;
+    kind: "tool_group";
+    title?: string;
+    calls: ToolCallData[];
+}
+interface AgentTimelineStatusItem {
+    id: string;
+    kind: "status";
+    label: string;
+    detail?: string;
+    tone?: AgentTimelineTone;
+}
+interface AgentTimelineArtifactItem {
+    id: string;
+    kind: "artifact";
+    title: string;
+    description?: string;
+    meta?: ReactNode;
+    icon?: ReactNode;
+    tone?: AgentTimelineTone;
+    action?: ReactNode;
+    onClick?: () => void;
+}
+interface AgentTimelineCustomItem {
+    id: string;
+    kind: "custom";
+    content: ReactNode;
+}
+type AgentTimelineItem = AgentTimelineMessageItem | AgentTimelineToolItem | AgentTimelineToolGroupItem | AgentTimelineStatusItem | AgentTimelineArtifactItem | AgentTimelineCustomItem;
+interface AgentTimelineProps {
+    items: AgentTimelineItem[];
+    isThinking?: boolean;
+    emptyState?: ReactNode;
+    className?: string;
+}
+/**
+ * AgentTimeline — unified mixed-content timeline for agent-backed sandbox
+ * sessions. Renders messages, tool steps, status cards, and artifact handoffs in
+ * a single execution narrative.
+ */
+declare function AgentTimeline({ items, isThinking, emptyState, className, }: AgentTimelineProps): react_jsx_runtime.JSX.Element | null;
+
+export { AgentTimeline, type AgentTimelineArtifactItem, type AgentTimelineCustomItem, type AgentTimelineItem, type AgentTimelineMessageItem, type AgentTimelineProps, type AgentTimelineStatusItem, type AgentTimelineTone, type AgentTimelineToolGroupItem, type AgentTimelineToolItem, ChatMessage, type ChatMessageProps, MessageList, type MessageListProps, type MessageRole, ThinkingIndicator, type ThinkingIndicatorProps, UserMessage, type UserMessageProps };

package/dist/chat.js

@@ -1,24 +1,24 @@
 import {
+  AgentTimeline,
   ChatContainer,
   ChatInput,
   ChatMessage,
-  ChatMessageList,
   MessageList,
   ThinkingIndicator,
   UserMessage
-} from "./chunk-U62G5TS7.js";
-import "./chunk-KMXV7DDX.js";
-import "./chunk-6MQIDUPA.js";
-import "./chunk-LTFK464G.js";
-import "./chunk-M34OA6PQ.js";
+} from "./chunk-4F2GJRGU.js";
+import "./chunk-CNWVHQFY.js";
+import "./chunk-WUR652Y3.js";
 import "./chunk-HRMUF35V.js";
-import "./chunk-QSQBDR3N.js";
+import "./chunk-CJ2RYVZH.js";
+import "./chunk-BX6AQMUS.js";
+import "./chunk-LTFK464G.js";
 import "./chunk-RQHJBTEU.js";
 export {
+  AgentTimeline,
   ChatContainer,
   ChatInput,
   ChatMessage,
-  ChatMessageList,
   MessageList,
   ThinkingIndicator,
   UserMessage