> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifacts

> Zeus Structured Tool Return Format

## Overview

Artifacts is a structured tool return format used to render rich content (HTML, code, diff, charts, etc.) in the Trajectory area instead of displaying raw text. Rendering adopts a **VSCode light style** with Prism.js syntax highlighting and line numbers.

## Background

Current tool return results have the following issues:

1. **Inconsistent formats**: Different tools return different formats
2. **Difficult frontend parsing**: Relies on regex to detect content types
3. **Limited rendering**: Cannot distinguish renderable content from plain text
4. **Poor extensibility**: Every new type requires modifying frontend detection logic

## Data Structure Design

### ToolResultContent

Structured representation of tool return content with the following fields:

| Field      | Type              | Description                                                 |
| ---------- | ----------------- | ----------------------------------------------------------- |
| `type`     | string            | Content type (see table below)                              |
| `data`     | string            | Content data                                                |
| `language` | string (optional) | Programming language identifier                             |
| `title`    | string (optional) | Title (also used for language detection via file extension) |
| `meta`     | object (optional) | Additional metadata (e.g. `old_content` for diff)           |

### ToolResult

Standard tool return format:

| Field       | Type                         | Description                                   |
| ----------- | ---------------------------- | --------------------------------------------- |
| `success`   | boolean                      | Whether successful                            |
| `message`   | string                       | Result message (concise, for LLM consumption) |
| `content`   | ToolResultContent (optional) | Structured content (for user display)         |
| `file_path` | string (optional)            | Associated file path                          |
| `files`     | SandboxFile\[] (optional)    | List of generated files                       |

### SandboxFile

File metadata returned by sandbox operations:

| Field          | Type              | Description                                      |
| -------------- | ----------------- | ------------------------------------------------ |
| `name`         | string            | File name                                        |
| `type`         | string            | File type (`document`, `code`, `image`, `other`) |
| `sandbox_path` | string            | File path inside the sandbox                     |
| `url`          | string (optional) | Cloud storage URL (e.g. Supabase Storage)        |
| `content`      | string (optional) | File content or base64                           |
| `size`         | number (optional) | File size in bytes                               |

## Content Types

| type       | Description   | Rendering Method                                        |
| ---------- | ------------- | ------------------------------------------------------- |
| `text`     | Plain text    | `<pre>` or Markdown renderer (auto-detected)            |
| `html`     | HTML content  | `<iframe>` sandbox rendering                            |
| `markdown` | Markdown      | Markdown renderer                                       |
| `code`     | Code          | Prism.js syntax-highlighted CodeBlock with line numbers |
| `json`     | JSON data     | Prism.js highlighted JSON viewer with line numbers      |
| `image`    | Image         | `<img>`                                                 |
| `error`    | Error message | Red error styling                                       |

## Diff Rendering

For `edit` and `write` tool results, when `meta.old_content` is present, the frontend renders a **DiffPreview** component instead of the standard artifact renderer. This provides a Cursor-like split/unified diff view.

### How It Works

1. **Backend**: The `write` tool reads the file's previous content before overwriting, and the `edit` tool captures the original file content before applying changes. Both store the old content in `content.meta.old_content`.
2. **Frontend**: The `WorkspaceArea` component detects `edit`/`write` results containing `meta.old_content` and renders a `DiffPreview` using `react-diff-viewer-continued`, with Prism.js syntax highlighting based on the file extension.
3. **Fallback**: For `edit` calls where `meta.old_content` is unavailable, the frontend falls back to diffing `parameters.old_string` vs `parameters.new_string` (snippet-level diff).

### Diff Stats on ToolCallCard

When a tool call completes, the `ToolCallCard` header displays inline diff statistics (`+N` / `-N`) computed from the old and new content. This gives users an at-a-glance view of how much code was added or removed.

## Frontend Rendering

The frontend selects the corresponding rendering component based on the `content.type` field:

* **HTML**: Sandbox iframe preview with device-width presets (desktop/tablet/mobile) and deploy capability
* **Markdown**: Full Markdown renderer
* **Code**: VSCode-inspired light-themed table layout with line numbers, Prism.js syntax highlighting, and collapsible long files (>20 lines)
* **JSON**: Same table-based layout as code, with JSON-specific highlighting
* **Image**: Direct `<img>` display
* **Error**: Red error styling
* **Diff** (edit/write): Unified diff view with added/removed line highlighting

### Raw Mode

The workspace area supports toggling between **Preview** and **Raw** mode. Raw mode displays parameters and results as Prism.js-highlighted JSON with a copy button on section headers, replacing the previous Monaco Editor-based approach for lighter weight and faster rendering.

## Backward Compatibility

* The frontend supports both new and old formats
* Old format (plain text) is wrapped as content with `type: "text"`
* Progressive migration without affecting existing functionality