Skip to content

ARTIFACT-SYSTEM.md

Latest commit

 

History

History
253 lines (186 loc) · 8.79 KB

ARTIFACT-SYSTEM.md

File metadata and controls

253 lines (186 loc) · 8.79 KB

Artifact System

Overview

This document details the artifact system in the AI Chatbot, which allows the AI to generate and share specialized content such as documents, images, and data tables.

Artifacts are special types of content that can be generated by the AI and displayed in a dedicated panel in the UI. They provide a richer experience beyond simple text messages, allowing for interactive documents, images, and structured data.

Artifact Types

Text Artifacts

  • Description: Formatted text documents with Markdown support
  • File Extension: .md
  • Used For: Essays, documentation, code snippets
  • Implementation: artifacts/text/client.tsx

Image Artifacts

  • Description: Visual content generated by the AI
  • File Formats: PNG, JPG
  • Used For: Diagrams, charts, illustrations
  • Implementation: artifacts/image/client.tsx

Sheet Artifacts

  • Description: Tabular data in spreadsheet format
  • File Format: CSV
  • Used For: Data tables, structured information
  • Implementation: artifacts/sheet/client.tsx

Architecture

Core Components

Artifact Component (components/artifact.tsx)

  • Description: Main container for the artifact panel
  • Responsibilities:
    • Controls visibility and state
    • Integrates different artifact viewers
    • Manages version history and document storage
    • Implements dual-storage approach (API and localStorage)
    • Provides debounced content saving
    • Shows saving status indicators
    • Handles responsive layout for mobile and desktop

DataStreamHandler (components/data-stream-handler.tsx)

  • Description: Manages streaming data for artifacts
  • Responsibilities:
    • Processes artifact deltas as they arrive
    • Updates the artifact state in real-time
    • Manages streaming status indicators

ArtifactMessages (components/artifact-messages.tsx)

  • Description: Specialized message display for artifacts
  • Responsibilities:
    • Shows interactions related to the current artifact
    • Provides context for artifact creation and modifications
    • Handles input specifically for the artifact context

VersionFooter (components/version-footer.tsx)

  • Description: Manages version history interface
  • Responsibilities:
    • Allows navigation between document versions
    • Provides version restoration functionality
    • Displays timestamp information
    • Shows version count and navigation controls

Hooks and State Management

useArtifact Hook (hooks/use-artifact.ts)

  • Description: Central hook for artifact state management
  • Features:
    • Provides global artifact state
    • Includes selector pattern for optimized rerenders
    • Manages artifact metadata
    • Uses SWR for state persistence
    • Maintains initial state configuration

Artifact Context Flow

  • Artifact state is managed globally through SWR
  • Components access state via useArtifact hook
  • State updates are propagated efficiently to minimize rerenders
  • Metadata is stored separately from core artifact data

Attachment Structure

Interface

  • type (string): 'image', 'text', 'sheet', or with '-delta' suffix
  • name (string, optional): Optional name for the attachment
  • content (string, optional): The actual content (base64 for images, text for others)
  • url (string): URL reference, often with 'artifact:' scheme
  • title (string, optional): Title displayed in the artifact header

Data Flow

Artifact Creation

  1. User sends a message that triggers artifact generation
  2. AI responds with an initial message
  3. AI streams artifact data as attachments with '-delta' type suffix
  4. DataStreamHandler processes these deltas and updates the UI
  5. Artifact panel becomes visible showing the generated content

Artifact Interaction

  1. User interacts with the artifact (edits text, views image, etc.)
  2. Interactions are processed by the specific artifact viewer
  3. Changes can be sent back to the AI as messages
  4. AI can respond to changes or provide further content
  5. Content changes are debounced to prevent excessive version creation

Document Storage

API-Based Document Storage

  • Description: For production environments, documents are stored via API
  • Features:
    • Documents are fetched from /api/document?id=${documentId}
    • Updates are posted to the same endpoint
    • Versions are managed on the server side
    • Authentication and access control handled by the API
    • Uses SWR for data fetching, caching, and optimistic updates

Local Document Storage

  • Description: For development or special document types
  • Features:
    • Documents with local: prefix use local storage
    • Special URIs (http://, text:, sheet:) automatically use local storage
    • Document history is stored in browser localStorage
    • Each edit creates a new version with timestamp
    • Versions can be navigated, compared, and restored
    • Key format: local-document-${documentId}
    • Same UI and interaction patterns as API storage

Storage Detection

  • Local Storage Triggers:
    • Document IDs with local: prefix
    • URLs starting with http:// or https://
    • Content identifiers like text: or sheet:
    • Placeholder image URLs
  • API Storage:
    • All other document IDs use API-based storage
    • Integration with authentication system

Version Control

Version Creation

  • Each edit automatically creates a new version
  • Versions include timestamps and content changes
  • Debounced saving prevents excessive version creation
  • Visual indicator shows saving status

Version Navigation

  • Users can move between versions using toolbar controls
  • Navigation includes previous, next, and latest version options
  • Current version status is clearly indicated
  • Version comparison is available via diff mode

Version Comparison

  • 'diff' mode allows comparing changes between versions
  • Toggled via toolbar button or version navigation
  • Special UI state shows comparison view
  • Consistent interface across both storage backends

Version Restoration

  • Users can restore previous versions
  • Restoration works for both API and local storage documents
  • After restoration, the system returns to edit mode with the restored content
  • The restored version becomes the latest version in the history

User Interface

Split Panel Layout

  • Desktop:
    • Left panel (400px): Shows messages related to the artifact
    • Right panel (remaining width): Displays the artifact content
    • Both panels scroll independently
    • Smooth animations for transitions
  • Mobile:
    • The interface adapts to show only the artifact content for better usability
    • Full-screen layout optimized for smaller screens
    • Specialized controls for touch interaction

Animations

The artifact interface includes smooth animations for:

  • Opening and closing the artifact panel
  • Transitioning between versions
  • Showing/hiding the version footer
  • Indicating saving status
  • Smooth modal animations using Framer Motion

Responsive Design

  • Desktop: Split panel with messages and content
  • Mobile: Full-screen artifact view with optimized controls
  • Adaptive sizing based on window dimensions
  • Custom hook (useMobile) assists with responsive behavior

Testing

Commands

  • test image artifact: Generates a sample image
  • test text artifact: Creates a text document
  • test sheet artifact: Produces a spreadsheet
  • artifact testing: Reference docs/ARTIFACT-TESTING.md for detailed test procedures

Backend Integration

Steps

  1. Replace sample content generation with actual AI-generated content
  2. Implement proper artifact storage (S3, database, etc.)
  3. Leverage the existing version control system
  4. Implement authentication for artifact access
  5. Add collaboration features for shared artifacts

Recent Improvements

  • Unified Storage Handling: Consistent approach for both API and local storage
  • Improved Version History: Better UI for navigating versions
  • Performance Optimizations: Debounced content saving and memoized components
  • Visual Feedback: Clear indicators for saving status and version information
  • Mobile Responsiveness: Optimized experience across device sizes
  • Enhanced Hooks: New useArtifact hook for better state management
  • SWR Integration: More efficient data fetching and caching
  • Advanced URI Detection: Automatic detection of special document types

Future Enhancements

  • Collaborative Editing: Allow multiple users to work on artifacts simultaneously
  • Enhanced Diff Visualization: Better visualization of changes between versions
  • Advanced Export Options: Additional export formats for artifacts
  • Integration with External Tools: Connect to third-party services
  • Offline Support: Improved capabilities when working without network connection
  • Real-time Collaboration: WebSocket integration for live editing