PRD-38.1: Widget-Ready Chatbot Workspace

Version: 1.0 Status: 🟡 Ready for Implementation Priority: HIGH Author: Automatos AI Platform Team Last Updated: 2026-01-27 Dependencies: PRD-31 (Chatbot UX), PRD-38.0 (Master Plan) Timeline: Weeks 1-3

---

Executive Summary

Transform the current chatbot interface from a modal-based artifact viewer into a canvas-based workspace where widgets (artifacts) persist, can be arranged, and remain accessible throughout the conversation. This phase establishes the widget architecture foundation that enables all future phases.

Before & After

CURRENT STATE                          TARGET STATE
─────────────────────────────────      ─────────────────────────────────
┌─────────┐ ┌──────────────────┐      ┌────────┐ ┌────────────────────┐
│ Sidebar │ │                  │      │        │ │                    │
│         │ │   Chat Area      │      │  Chat  │ │      Canvas        │
│ History │ │                  │      │  Panel │ │                    │
│         │ │   [Message]      │      │        │ │ ┌────┐ ┌────┐      │
│         │ │   [Message]      │      │ [Msgs] │ │ │Code│ │Data│      │
│         │ │   [Artifact      │      │        │ │ └────┘ └────┘      │
│         │ │    MODAL]        │      │        │ │ ┌─────────────┐    │
│         │ │                  │      │        │ │ │  Document   │    │
│         │ │   [Input]        │      │[Input] │ │ └─────────────┘    │
└─────────┘ └──────────────────┘      └────────┘ └────────────────────┘
                                      └─────────Widget Tray────────────┘

• Single artifact at a time          • Multiple widgets visible
• Modal overlay                      • Persistent canvas
• Lost on close                      • Saved in workspace
• No arrangement                     • Drag, resize, arrange

---

1) Goals & Success Metrics

Goals

ID	Goal	Description
G1	Widget Foundation	Create reusable widget architecture for all future phases
G2	Canvas Workspace	Replace modal artifact viewer with persistent canvas
G3	Multi-Widget	Support viewing multiple widgets simultaneously
G4	Tool Integration	Tool results automatically create widgets in canvas
G5	Zero Regression	Existing chat functionality must not break

Success Metrics

Metric	Target	Measurement
Widget render time	< 200ms	Performance profiling
Canvas with 10 widgets	60fps	Chrome DevTools FPS
Tool → Widget latency	< 500ms	Time from tool-end to widget visible
Existing tests passing	100%	CI pipeline
User can view 4+ widgets	Working	Manual QA

---

2) Current State Analysis

Existing Files to Modify

File	Lines	Current Purpose	Changes Needed
components/chatbot/chat.tsx	668	Main chat container	Add canvas, split layout
components/chatbot/message.tsx	602	Message rendering	Emit widgets to canvas instead of inline
components/chatbot/artifact-viewer.tsx	175	Modal artifact display	Transform to widget wrapper
components/chatbot/code-artifact.tsx	51	Code display	Move to widgets/CodeWidget
components/chatbot/text-artifact.tsx	278	Document display	Move to widgets/DocumentWidget
components/chatbot/sheet-artifact.tsx	302	Table display	Move to widgets/DataWidget
lib/chat/hooks.ts	~300	Chat state	Add widget event handling

Existing Files to Reuse As-Is

File	Purpose	Reuse Strategy
components/ui/*	Shadcn components	Use in widgets
components/chatbot/multimodal-input.tsx	Input handling	Keep unchanged
components/chatbot/model-selector.tsx	Model selection	Keep unchanged
components/chatbot/agent-selector.tsx	Agent selection	Keep unchanged
components/chatbot/sidebar.tsx	Chat history	Keep unchanged

Existing Patterns to Follow

// Current artifact structure (from types/chat.ts)
interface Artifact {
  id: string
  kind: 'code' | 'text' | 'image' | 'sheet'
  title: string
  content: string
  language?: string
  metadata?: Record<string, any>
  createdAt?: string
}

// We will EXTEND this, not replace
interface Widget extends Artifact {
  kind: WidgetType  // Extended types
  position?: WidgetPosition
  size?: WidgetSize
  state: 'loading' | 'ready' | 'error' | 'stale'
  actions: WidgetAction[]
}

---

3) Technical Architecture

3.1 Component Hierarchy

ChatPage
├── AppSidebar (unchanged)
│
└── WorkspaceContainer (NEW)
    ├── ChatPanel
    │   ├── MessageList
    │   │   └── Message[] (modified - no inline artifacts)
    │   └── MultimodalInput (unchanged)
    │
    ├── Canvas (NEW)
    │   ├── CanvasGrid / CanvasFreeform
    │   │   └── WidgetWrapper[]
    │   │       └── Widget (CodeWidget, DataWidget, etc.)
    │   │
    │   └── CanvasControls
    │       ├── LayoutToggle
    │       ├── ZoomControls
    │       └── AddWidgetButton
    │
    ├── WidgetTray (NEW)
    │   └── WidgetThumbnail[]
    │
    └── ContextPanel (NEW, optional)
        └── WidgetDetails

3.2 State Flow

User asks question
        │
        ▼
Tool executes (RAG, NL2SQL, etc.)
        │
        ▼
Backend streams tool-data event
        │
        ▼
useChat hook receives event
        │
        ▼
Widget Router determines widget type
        │
        ▼
workspaceStore.addWidget() called
        │
        ▼
Canvas re-renders with new widget
        │
        ▼
Widget fetches additional data if needed

3.3 Zustand Store Design

// frontend/stores/workspace-store.ts
import { create } from 'zustand'
import { persist } from 'zustand/middleware'

interface WorkspaceState {
  // Widgets
  widgets: Record<string, Widget>
  widgetIds: string[]  // Ordered list for rendering
  activeWidgetId: string | null

  // Layout
  layoutMode: 'grid' | 'freeform' | 'split' | 'focus'
  gridConfig: GridConfig
  positions: Record<string, WidgetPosition>
  sizes: Record<string, WidgetSize>

  // Chat integration
  chatPanelWidth: number
  isChatCollapsed: boolean
  widgetsInContext: string[]

  // UI state
  isWidgetTrayOpen: boolean
  selectedWidgetForContext: string | null
}

interface WorkspaceActions {
  // Widget CRUD
  addWidget: (widget: Omit<Widget, 'id'>) => string
  updateWidget: (id: string, updates: Partial<Widget>) => void
  removeWidget: (id: string) => void
  clearWidgets: () => void

  // Selection
  setActiveWidget: (id: string | null) => void
  bringToFront: (id: string) => void
  sendToBack: (id: string) => void

  // Layout
  setLayoutMode: (mode: LayoutMode) => void
  updatePosition: (id: string, position: WidgetPosition) => void
  updateSize: (id: string, size: WidgetSize) => void
  resetLayout: () => void

  // Chat panel
  setChatPanelWidth: (width: number) => void
  toggleChatCollapsed: () => void

  // Context (for chat references)
  addToContext: (widgetId: string) => void
  removeFromContext: (widgetId: string) => void
  clearContext: () => void

  // Tray
  toggleWidgetTray: () => void

  // From tool results
  handleToolResult: (
    toolName: string,
    toolCallId: string,
    result: any,
    conversationId: string
  ) => void
}

export const useWorkspaceStore = create<WorkspaceState & WorkspaceActions>()(
  persist(
    (set, get) => ({
      // Initial state
      widgets: {},
      widgetIds: [],
      activeWidgetId: null,
      layoutMode: 'grid',
      gridConfig: { columns: 12, rowHeight: 100 },
      positions: {},
      sizes: {},
      chatPanelWidth: 400,
      isChatCollapsed: false,
      widgetsInContext: [],
      isWidgetTrayOpen: true,
      selectedWidgetForContext: null,

      // Actions implementation...
      addWidget: (widgetData) => {
        // Use crypto.randomUUID() for collision-resistant IDs
        // Falls back to nanoid pattern if crypto.randomUUID unavailable
        const id = typeof crypto !== 'undefined' && crypto.randomUUID
          ? `widget-${crypto.randomUUID()}`
          : `widget-${Date.now().toString(36)}-${Array.from(
              crypto.getRandomValues(new Uint8Array(8)),
              b => b.toString(16).padStart(2, '0')
            ).join('')}`

        const widget: Widget = {
          ...widgetData,
          id,
          state: 'ready',
          createdAt: new Date().toISOString(),
        }

        set((state) => ({
          widgets: { ...state.widgets, [id]: widget },
          widgetIds: [...state.widgetIds, id],
          activeWidgetId: id,
        }))

        return id
      },

      handleToolResult: (toolName, toolCallId, result, conversationId) => {
        const widgetType = routeToolToWidget(toolName, result)
        const widgetData = transformToolResultToWidget(
          widgetType,
          toolName,
          result,
          conversationId,
          toolCallId
        )

        if (widgetData) {
          get().addWidget(widgetData)
        }
      },

      // ... other actions
    }),
    {
      name: 'automatos-workspace',
      partialize: (state) => ({
        layoutMode: state.layoutMode,
        chatPanelWidth: state.chatPanelWidth,
        isChatCollapsed: state.isChatCollapsed,
        isWidgetTrayOpen: state.isWidgetTrayOpen,
      }),
    }
  )
)

---

4) Implementation Plan

Week 1: Foundation

Task 1.1: Create Widget Types & Registry

Files to Create:

frontend/components/widgets/
├── types.ts           # All widget type definitions
├── registry.ts        # Widget registration system
└── router.ts          # Tool → Widget routing

types.ts:

// frontend/components/widgets/types.ts

export type WidgetType =
  | 'code'
  | 'data'
  | 'document'
  | 'image'

export interface WidgetPosition {
  x: number
  y: number
}

export interface WidgetSize {
  width: number
  height: number
}

export interface Widget {
  id: string
  type: WidgetType
  title: string
  data: unknown
  metadata: WidgetMetadata
  state: 'loading' | 'ready' | 'error' | 'stale'
  position?: WidgetPosition
  size?: WidgetSize
  createdAt: string
  updatedAt?: string
}

export interface WidgetMetadata {
  source: {
    type: 'tool' | 'user' | 'system'
    name: string
    provider?: string
  }
  conversationId?: string
  toolCallId?: string
  workspaceId?: string
}

export interface WidgetBaseProps<T = unknown> {
  id: string
  title: string
  data: T
  metadata: WidgetMetadata
  isActive?: boolean
  isLoading?: boolean
  error?: Error | null
  onClose?: () => void
  onMaximize?: () => void
  onRefresh?: () => void
}

// Widget-specific data types
export interface CodeWidgetData {
  code: string
  language: string
  filePath?: string
  lineNumber?: number
  explanation?: string
  symbolName?: string
}

export interface DataWidgetData {
  columns: string[]
  rows: Record<string, unknown>[]
  sql?: string
  database?: string
  rowCount: number
  executionTime?: number
  charts?: ChartData[]
  pandasAiSummary?: string
}

export interface DocumentWidgetData {
  content: string
  format: 'markdown' | 'text' | 'html'
  filename?: string
  filePath?: string
  similarity?: number
  chunkCount?: number
  chunks?: DocumentChunk[]
  downloadUrl?: string
}

export interface ImageWidgetData {
  src: string
  alt?: string
  width?: number
  height?: number
  mimeType?: string
  prompt?: string  // For generated images
  model?: string
}

registry.ts:

// frontend/components/widgets/registry.ts

import { WidgetType, WidgetBaseProps } from './types'
import { ComponentType } from 'react'

export interface WidgetDefinition {
  type: WidgetType
  displayName: string
  icon: string
  component: ComponentType<WidgetBaseProps<any>>
  defaultSize: { width: number; height: number }
  minSize?: { width: number; height: number }
  capabilities: string[]
}

const registry = new Map<WidgetType, WidgetDefinition>()

export function registerWidget(definition: WidgetDefinition) {
  registry.set(definition.type, definition)
}

export function getWidget(type: WidgetType): WidgetDefinition | undefined {
  return registry.get(type)
}

export function getAllWidgets(): WidgetDefinition[] {
  return Array.from(registry.values())
}

// Register default widgets
import { CodeWidget, CodeWidgetDef } from './CodeWidget'
import { DataWidget, DataWidgetDef } from './DataWidget'
import { DocumentWidget, DocumentWidgetDef } from './DocumentWidget'
import { ImageWidget, ImageWidgetDef } from './ImageWidget'

registerWidget(CodeWidgetDef)
registerWidget(DataWidgetDef)
registerWidget(DocumentWidgetDef)
registerWidget(ImageWidgetDef)

router.ts:

// frontend/components/widgets/router.ts

import { WidgetType } from './types'

const TOOL_WIDGET_MAP: Record<string, WidgetType> = {
  // RAG Tools
  'search_knowledge': 'document',
  'semantic_search': 'document',
  'search_documents': 'document',
  'search_multimodal': 'document',

  // Database Tools
  'smart_query_database': 'data',
  'query_database': 'data',
  'execute_sql': 'data',

  // Code Tools
  'search_codebase': 'code',
  'get_code_context': 'code',
  'analyze_code': 'code',

  // Image Tools
  'generate_image': 'image',
  'edit_image': 'image',
  'analyze_image': 'image',
  'search_images': 'image',
}

export function routeToolToWidget(
  toolName: string,
  result: any
): WidgetType | null {
  // Direct mapping
  if (TOOL_WIDGET_MAP[toolName]) {
    return TOOL_WIDGET_MAP[toolName]
  }

  // Infer from result structure
  if (result.database_results?.length > 0) return 'data'
  if (result.documents?.length > 0) return 'document'
  if (result.code_snippets?.length > 0) return 'code'
  if (result.images?.length > 0) return 'image'

  // Check for specific data patterns
  if (result.sql || result.columns) return 'data'
  if (result.code || result.language) return 'code'
  if (result.content && (result.chunks || result.similarity)) return 'document'

  return null
}

export function transformToolResultToWidget(
  type: WidgetType,
  toolName: string,
  result: any,
  conversationId: string,
  toolCallId: string
): Omit<Widget, 'id'> | null {
  const baseWidget = {
    type,
    metadata: {
      source: {
        type: 'tool' as const,
        name: toolName,
      },
      conversationId,
      toolCallId,
    },
    state: 'ready' as const,
  }

  switch (type) {
    case 'data':
      return {
        ...baseWidget,
        title: result.database || 'Query Result',
        data: {
          columns: result.columns || [],
          rows: result.data || result.rows || [],
          sql: result.sql,
          database: result.database,
          rowCount: result.row_count || result.data?.length || 0,
          executionTime: result.execution_time_ms,
          charts: result.pandas_ai?.charts,
          pandasAiSummary: result.pandas_ai?.summary,
        },
      }

    case 'document':
      return {
        ...baseWidget,
        title: result.title || result.filename || 'Document',
        data: {
          content: result.full_content || result.content || result.preview,
          format: 'markdown',
          filename: result.filename,
          filePath: result.file_path,
          similarity: result.relevance || result.similarity,
          chunkCount: result.chunk_count,
          chunks: result.chunks,
          downloadUrl: result.download_url,
        },
      }

    case 'code':
      return {
        ...baseWidget,
        title: result.symbol_name || result.file_path || 'Code',
        data: {
          code: result.code || result.content,
          language: result.language || 'python',
          filePath: result.file_path,
          lineNumber: result.line_number,
          explanation: result.explanation,
          symbolName: result.symbol_name,
        },
      }

    case 'image':
      return {
        ...baseWidget,
        title: result.filename || 'Image',
        data: {
          src: result.base64
            ? `data:${result.mime_type || 'image/png'};base64,${result.base64}`
            : result.url || result.src,
          alt: result.alt || result.prompt,
          mimeType: result.mime_type,
          prompt: result.prompt,
          model: result.model,
        },
      }

    default:
      return null
  }
}

Task 1.2: Create Zustand Store

File to Create:

frontend/stores/workspace-store.ts

Full implementation as shown in section 3.3 above.

Install Zustand:

cd frontend
npm install zustand

Task 1.3: Create WidgetBase Component

Files to Create:

frontend/components/widgets/
├── WidgetBase.tsx
└── WidgetWrapper.tsx

WidgetBase.tsx:

// frontend/components/widgets/WidgetBase.tsx

import { ReactNode } from 'react'
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
import { Button } from '@/components/ui/button'
import {
  X,
  Maximize2,
  Minimize2,
  RefreshCw,
  Copy,
  Download,
  MoreVertical,
} from 'lucide-react'
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu'
import { cn } from '@/lib/utils'
import { WidgetMetadata } from './types'

interface WidgetBaseProps {
  title: string
  icon?: ReactNode
  metadata?: WidgetMetadata
  isActive?: boolean
  isLoading?: boolean
  error?: Error | null
  children: ReactNode

  // Actions
  onClose?: () => void
  onMaximize?: () => void
  onMinimize?: () => void
  onRefresh?: () => void
  onCopy?: () => void
  onDownload?: () => void

  // Capabilities
  canCopy?: boolean
  canDownload?: boolean
  canRefresh?: boolean

  // Custom actions
  customActions?: Array<{
    label: string
    icon?: ReactNode
    onClick: () => void
  }>

  className?: string
}

export function WidgetBase({
  title,
  icon,
  metadata,
  isActive,
  isLoading,
  error,
  children,
  onClose,
  onMaximize,
  onMinimize,
  onRefresh,
  onCopy,
  onDownload,
  canCopy,
  canDownload,
  canRefresh,
  customActions,
  className,
}: WidgetBaseProps) {
  return (
    <Card
      className={cn(
        'flex flex-col h-full overflow-hidden transition-all',
        'border-border/50 bg-card/95 backdrop-blur-sm',
        isActive && 'ring-2 ring-primary/50',
        className
      )}
    >
      {/* Header */}
      <CardHeader className="flex-shrink-0 flex flex-row items-center justify-between p-3 pb-2 border-b border-border/30">
        <div className="flex items-center gap-2 min-w-0">
          {icon && <span className="text-muted-foreground">{icon}</span>}
          <CardTitle className="text-sm font-medium truncate">
            {title}
          </CardTitle>
          {metadata?.source && (
            <span className="text-xs text-muted-foreground bg-muted/50 px-1.5 py-0.5 rounded">
              {metadata.source.name}
            </span>
          )}
        </div>

        <div className="flex items-center gap-1">
          {canRefresh && onRefresh && (
            <Button
              variant="ghost"
              size="icon"
              className="h-7 w-7"
              onClick={onRefresh}
              disabled={isLoading}
            >
              <RefreshCw className={cn('h-4 w-4', isLoading && 'animate-spin')} />
            </Button>
          )}

          {canCopy && onCopy && (
            <Button
              variant="ghost"
              size="icon"
              className="h-7 w-7"
              onClick={onCopy}
            >
              <Copy className="h-4 w-4" />
            </Button>
          )}

          {canDownload && onDownload && (
            <Button
              variant="ghost"
              size="icon"
              className="h-7 w-7"
              onClick={onDownload}
            >
              <Download className="h-4 w-4" />
            </Button>
          )}

          {customActions && customActions.length > 0 && (
            <DropdownMenu>
              <DropdownMenuTrigger asChild>
                <Button variant="ghost" size="icon" className="h-7 w-7">
                  <MoreVertical className="h-4 w-4" />
                </Button>
              </DropdownMenuTrigger>
              <DropdownMenuContent align="end">
                {customActions.map((action, i) => (
                  <DropdownMenuItem key={i} onClick={action.onClick}>
                    {action.icon}
                    {action.label}
                  </DropdownMenuItem>
                ))}
              </DropdownMenuContent>
            </DropdownMenu>
          )}

          {onMaximize && (
            <Button
              variant="ghost"
              size="icon"
              className="h-7 w-7"
              onClick={onMaximize}
            >
              <Maximize2 className="h-4 w-4" />
            </Button>
          )}

          {onClose && (
            <Button
              variant="ghost"
              size="icon"
              className="h-7 w-7"
              onClick={onClose}
            >
              <X className="h-4 w-4" />
            </Button>
          )}
        </div>
      </CardHeader>

      {/* Content */}
      <CardContent className="flex-1 overflow-auto p-0">
        {error ? (
          <div className="flex items-center justify-center h-full p-4">
            <div className="text-center text-destructive">
              <p className="font-medium">Error loading widget</p>
              <p className="text-sm text-muted-foreground mt-1">
                {error.message}
              </p>
            </div>
          </div>
        ) : isLoading ? (
          <div className="flex items-center justify-center h-full">
            <RefreshCw className="h-6 w-6 animate-spin text-muted-foreground" />
          </div>
        ) : (
          children
        )}
      </CardContent>
    </Card>
  )
}

WidgetWrapper.tsx:

// frontend/components/widgets/WidgetWrapper.tsx

import { useCallback } from 'react'
import { Widget, getWidget } from './registry'
import { WidgetBase } from './WidgetBase'
import { useWorkspaceStore } from '@/stores/workspace-store'

interface WidgetWrapperProps {
  widget: Widget
  isActive?: boolean
}

export function WidgetWrapper({ widget, isActive }: WidgetWrapperProps) {
  const removeWidget = useWorkspaceStore((s) => s.removeWidget)
  const setActiveWidget = useWorkspaceStore((s) => s.setActiveWidget)

  const definition = getWidget(widget.type)

  const handleClose = useCallback(() => {
    removeWidget(widget.id)
  }, [widget.id, removeWidget])

  const handleClick = useCallback(() => {
    setActiveWidget(widget.id)
  }, [widget.id, setActiveWidget])

  if (!definition) {
    return (
      <WidgetBase
        title="Unknown Widget"
        isActive={isActive}
        error={new Error(`Unknown widget type: ${widget.type}`)}
        onClose={handleClose}
      >
        <div />
      </WidgetBase>
    )
  }

  const WidgetComponent = definition.component

  return (
    <div onClick={handleClick} className="h-full">
      <WidgetComponent
        id={widget.id}
        title={widget.title}
        data={widget.data}
        metadata={widget.metadata}
        isActive={isActive}
        isLoading={widget.state === 'loading'}
        error={widget.state === 'error' ? new Error('Widget error') : null}
        onClose={handleClose}
      />
    </div>
  )
}

---

Week 2: Migrate Existing Artifacts

Task 2.1: Create CodeWidget (from code-artifact.tsx)

Files:

• DELETE after migration: components/chatbot/code-artifact.tsx

• CREATE: components/widgets/CodeWidget/index.tsx

// frontend/components/widgets/CodeWidget/index.tsx

import { useCallback, useState } from 'react'
import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter'
import { oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism'
import { Code2, Copy, Check, FileCode, ExternalLink } from 'lucide-react'
import { WidgetBase } from '../WidgetBase'
import { WidgetBaseProps, CodeWidgetData, WidgetDefinition } from '../types'
import { Button } from '@/components/ui/button'
import { toast } from 'sonner'

export function CodeWidget({
  id,
  title,
  data,
  metadata,
  isActive,
  isLoading,
  error,
  onClose,
}: WidgetBaseProps<CodeWidgetData>) {
  const [copied, setCopied] = useState(false)

  const handleCopy = useCallback(async () => {
    await navigator.clipboard.writeText(data.code)
    setCopied(true)
    toast.success('Code copied to clipboard')
    setTimeout(() => setCopied(false), 2000)
  }, [data.code])

  const languageMap: Record<string, string> = {
    python: 'python',
    py: 'python',
    javascript: 'javascript',
    js: 'javascript',
    typescript: 'typescript',
    ts: 'typescript',
    json: 'json',
    bash: 'bash',
    shell: 'bash',
    sql: 'sql',
    html: 'html',
    css: 'css',
    yaml: 'yaml',
    yml: 'yaml',
    markdown: 'markdown',
    md: 'markdown',
  }

  const language = languageMap[data.language?.toLowerCase() || 'text'] || 'text'

  return (
    <WidgetBase
      title={title}
      icon={<Code2 className="h-4 w-4" />}
      metadata={metadata}
      isActive={isActive}
      isLoading={isLoading}
      error={error}
      onClose={onClose}
      onCopy={handleCopy}
      canCopy
    >
      <div className="flex flex-col h-full">
        {/* File info bar */}
        {(data.filePath || data.lineNumber) && (
          <div className="flex items-center gap-2 px-3 py-2 bg-muted/30 border-b border-border/30 text-xs text-muted-foreground">
            <FileCode className="h-3 w-3" />
            {data.filePath && <span className="font-mono">{data.filePath}</span>}
            {data.lineNumber && (
              <span className="text-primary">:L{data.lineNumber}</span>
            )}
          </div>
        )}

        {/* Code block */}
        <div className="flex-1 overflow-auto">
          <SyntaxHighlighter
            language={language}
            style={oneDark}
            customStyle={{
              margin: 0,
              padding: '1rem',
              background: 'transparent',
              fontSize: '0.875rem',
              lineHeight: '1.5',
            }}
            showLineNumbers={data.code.split('\n').length > 5}
            wrapLines
          >
            {data.code}
          </SyntaxHighlighter>
        </div>

        {/* Explanation */}
        {data.explanation && (
          <div className="px-3 py-2 bg-muted/20 border-t border-border/30">
            <p className="text-sm text-muted-foreground">{data.explanation}</p>
          </div>
        )}
      </div>
    </WidgetBase>
  )
}

export const CodeWidgetDef: WidgetDefinition = {
  type: 'code',
  displayName: 'Code',
  icon: 'Code2',
  component: CodeWidget,
  defaultSize: { width: 500, height: 400 },
  minSize: { width: 300, height: 200 },
  capabilities: ['copyable', 'fullscreen'],
}

Task 2.2: Create DataWidget (from sheet-artifact.tsx)

Files:

• DELETE after migration: components/chatbot/sheet-artifact.tsx

• CREATE: components/widgets/DataWidget/index.tsx

// frontend/components/widgets/DataWidget/index.tsx

import { useState, useMemo, useCallback } from 'react'
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from '@/components/ui/table'
import { Input } from '@/components/ui/input'
import { Button } from '@/components/ui/button'
import {
  Database,
  Search,
  ChevronLeft,
  ChevronRight,
  Download,
  BarChart3,
  Code,
  ChevronDown,
  ChevronUp,
} from 'lucide-react'
import { WidgetBase } from '../WidgetBase'
import { WidgetBaseProps, DataWidgetData, WidgetDefinition } from '../types'
import { toast } from 'sonner'
import { cn } from '@/lib/utils'

const ROWS_PER_PAGE = 25

export function DataWidget({
  id,
  title,
  data,
  metadata,
  isActive,
  isLoading,
  error,
  onClose,
}: WidgetBaseProps<DataWidgetData>) {
  const [searchTerm, setSearchTerm] = useState('')
  const [currentPage, setCurrentPage] = useState(1)
  const [showSql, setShowSql] = useState(false)
  const [showCharts, setShowCharts] = useState(true)

  // Filter rows by search term
  const filteredRows = useMemo(() => {
    if (!searchTerm.trim()) return data.rows

    const term = searchTerm.toLowerCase()
    return data.rows.filter((row) =>
      Object.values(row).some((val) =>
        String(val).toLowerCase().includes(term)
      )
    )
  }, [data.rows, searchTerm])

  // Paginate
  const totalPages = Math.ceil(filteredRows.length / ROWS_PER_PAGE)
  const paginatedRows = useMemo(() => {
    const start = (currentPage - 1) * ROWS_PER_PAGE
    return filteredRows.slice(start, start + ROWS_PER_PAGE)
  }, [filteredRows, currentPage])

  // Export to CSV
  const handleExportCsv = useCallback(() => {
    const headers = data.columns.join(',')
    const rows = data.rows.map((row) =>
      data.columns.map((col) => {
        const val = row[col]
        // Escape quotes and wrap in quotes if contains comma
        const str = String(val ?? '')
        return str.includes(',') || str.includes('"')
          ? `"${str.replace(/"/g, '""')}"`
          : str
      }).join(',')
    ).join('\n')

    const csv = `${headers}\n${rows}`
    const blob = new Blob([csv], { type: 'text/csv' })
    const url = URL.createObjectURL(blob)
    const a = document.createElement('a')
    a.href = url
    a.download = `${title.replace(/\s+/g, '_')}.csv`
    a.click()
    URL.revokeObjectURL(url)
    toast.success('CSV exported')
  }, [data, title])

  return (
    <WidgetBase
      title={title}
      icon={<Database className="h-4 w-4" />}
      metadata={metadata}
      isActive={isActive}
      isLoading={isLoading}
      error={error}
      onClose={onClose}
      onDownload={handleExportCsv}
      canDownload
      customActions={[
        {
          label: showSql ? 'Hide SQL' : 'Show SQL',
          icon: <Code className="h-4 w-4 mr-2" />,
          onClick: () => setShowSql(!showSql),
        },
        {
          label: showCharts ? 'Hide Charts' : 'Show Charts',
          icon: <BarChart3 className="h-4 w-4 mr-2" />,
          onClick: () => setShowCharts(!showCharts),
        },
      ]}
    >
      <div className="flex flex-col h-full">
        {/* Stats bar */}
        <div className="flex items-center justify-between px-3 py-2 bg-muted/30 border-b border-border/30 text-xs">
          <div className="flex items-center gap-4 text-muted-foreground">
            <span>{data.rowCount.toLocaleString()} rows</span>
            <span>{data.columns.length} columns</span>
            {data.executionTime && (
              <span>{data.executionTime}ms</span>
            )}
          </div>
        </div>

        {/* SQL Preview */}
        {showSql && data.sql && (
          <div className="px-3 py-2 bg-muted/20 border-b border-border/30">
            <pre className="text-xs font-mono text-muted-foreground overflow-x-auto">
              {data.sql}
            </pre>
          </div>
        )}

        {/* PandasAI Summary */}
        {data.pandasAiSummary && (
          <div className="px-3 py-2 bg-primary/5 border-b border-border/30">
            <p className="text-sm">{data.pandasAiSummary}</p>
          </div>
        )}

        {/* Charts */}
        {showCharts && data.charts && data.charts.length > 0 && (
          <div className="flex gap-2 p-3 overflow-x-auto border-b border-border/30">
            {data.charts.map((chart, i) => (
              <img
                key={i}
                src={`data:${chart.mimeType || 'image/png'};base64,${chart.base64}`}
                alt={chart.filename || `Chart ${i + 1}`}
                className="max-h-48 rounded border border-border/30"
              />
            ))}
          </div>
        )}

        {/* Search */}
        <div className="p-2 border-b border-border/30">
          <div className="relative">
            <Search className="absolute left-2 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
            <Input
              placeholder="Search rows..."
              value={searchTerm}
              onChange={(e) => {
                setSearchTerm(e.target.value)
                setCurrentPage(1)
              }}
              className="pl-8 h-8"
            />
          </div>
        </div>

        {/* Table */}
        <div className="flex-1 overflow-auto">
          <Table>
            <TableHeader>
              <TableRow>
                {data.columns.map((col) => (
                  <TableHead
                    key={col}
                    className="bg-muted/30 sticky top-0 whitespace-nowrap"
                  >
                    {col}
                  </TableHead>
                ))}
              </TableRow>
            </TableHeader>
            <TableBody>
              {paginatedRows.map((row, i) => (
                <TableRow key={i}>
                  {data.columns.map((col) => (
                    <TableCell
                      key={col}
                      className="whitespace-nowrap max-w-[300px] truncate"
                    >
                      {String(row[col] ?? '')}
                    </TableCell>
                  ))}
                </TableRow>
              ))}
            </TableBody>
          </Table>
        </div>

        {/* Pagination */}
        {totalPages > 1 && (
          <div className="flex items-center justify-between px-3 py-2 border-t border-border/30">
            <span className="text-xs text-muted-foreground">
              Page {currentPage} of {totalPages}
            </span>
            <div className="flex gap-1">
              <Button
                variant="ghost"
                size="sm"
                onClick={() => setCurrentPage((p) => Math.max(1, p - 1))}
                disabled={currentPage === 1}
              >
                <ChevronLeft className="h-4 w-4" />
              </Button>
              <Button
                variant="ghost"
                size="sm"
                onClick={() => setCurrentPage((p) => Math.min(totalPages, p + 1))}
                disabled={currentPage === totalPages}
              >
                <ChevronRight className="h-4 w-4" />
              </Button>
            </div>
          </div>
        )}
      </div>
    </WidgetBase>
  )
}

export const DataWidgetDef: WidgetDefinition = {
  type: 'data',
  displayName: 'Data',
  icon: 'Database',
  component: DataWidget,
  defaultSize: { width: 600, height: 500 },
  minSize: { width: 400, height: 300 },
  capabilities: ['exportable', 'fullscreen', 'refreshable'],
}

Task 2.3: Create DocumentWidget (from text-artifact.tsx)

Files:

• DELETE after migration: components/chatbot/text-artifact.tsx

• CREATE: components/widgets/DocumentWidget/index.tsx

// frontend/components/widgets/DocumentWidget/index.tsx

import { useState } from 'react'
import ReactMarkdown from 'react-markdown'
import remarkGfm from 'remark-gfm'
import { FileText, Download, List, FileDown, ExternalLink } from 'lucide-react'
import { WidgetBase } from '../WidgetBase'
import { WidgetBaseProps, DocumentWidgetData, WidgetDefinition } from '../types'
import { Button } from '@/components/ui/button'
import { Badge } from '@/components/ui/badge'
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
import { cn } from '@/lib/utils'

export function DocumentWidget({
  id,
  title,
  data,
  metadata,
  isActive,
  isLoading,
  error,
  onClose,
}: WidgetBaseProps<DocumentWidgetData>) {
  const [activeTab, setActiveTab] = useState<'content' | 'chunks'>('content')

  const handleDownload = () => {
    if (data.downloadUrl) {
      window.open(data.downloadUrl, '_blank')
    }
  }

  return (
    <WidgetBase
      title={title}
      icon={<FileText className="h-4 w-4" />}
      metadata={metadata}
      isActive={isActive}
      isLoading={isLoading}
      error={error}
      onClose={onClose}
      onDownload={data.downloadUrl ? handleDownload : undefined}
      canDownload={!!data.downloadUrl}
    >
      <div className="flex flex-col h-full">
        {/* Info bar */}
        <div className="flex items-center gap-2 px-3 py-2 bg-muted/30 border-b border-border/30">
          {data.similarity !== undefined && (
            <Badge variant="secondary" className="text-xs">
              {Math.round(data.similarity)}% match
            </Badge>
          )}
          {data.chunkCount !== undefined && (
            <Badge variant="outline" className="text-xs">
              {data.chunkCount} chunks
            </Badge>
          )}
          {data.filename && (
            <span className="text-xs text-muted-foreground font-mono">
              {data.filename}
            </span>
          )}
        </div>

        {/* Tabs for content vs chunks */}
        {data.chunks && data.chunks.length > 0 ? (
          <Tabs value={activeTab} onValueChange={(v) => setActiveTab(v as any)} className="flex flex-col flex-1">
            <TabsList className="mx-3 mt-2">
              <TabsTrigger value="content" className="text-xs">
                <FileText className="h-3 w-3 mr-1" />
                Content
              </TabsTrigger>
              <TabsTrigger value="chunks" className="text-xs">
                <List className="h-3 w-3 mr-1" />
                Chunks ({data.chunks.length})
              </TabsTrigger>
            </TabsList>

            <TabsContent value="content" className="flex-1 overflow-auto px-4 py-3 m-0">
              <article className="prose prose-sm dark:prose-invert max-w-none">
                <ReactMarkdown remarkPlugins={[remarkGfm]}>
                  {data.content}
                </ReactMarkdown>
              </article>
            </TabsContent>

            <TabsContent value="chunks" className="flex-1 overflow-auto m-0">
              <div className="divide-y divide-border/30">
                {data.chunks.map((chunk, i) => (
                  <div key={i} className="p-3 hover:bg-muted/30">
                    <div className="flex items-center gap-2 mb-1">
                      <Badge variant="outline" className="text-xs">
                        Chunk {i + 1}
                      </Badge>
                      {chunk.similarity !== undefined && (
                        <span className="text-xs text-muted-foreground">
                          {Math.round(chunk.similarity * 100)}% relevant
                        </span>
                      )}
                    </div>
                    <p className="text-sm text-foreground/80">{chunk.content}</p>
                  </div>
                ))}
              </div>
            </TabsContent>
          </Tabs>
        ) : (
          <div className="flex-1 overflow-auto px-4 py-3">
            <article className="prose prose-sm dark:prose-invert max-w-none">
              <ReactMarkdown remarkPlugins={[remarkGfm]}>
                {data.content}
              </ReactMarkdown>
            </article>
          </div>
        )}
      </div>
    </WidgetBase>
  )
}

export const DocumentWidgetDef: WidgetDefinition = {
  type: 'document',
  displayName: 'Document',
  icon: 'FileText',
  component: DocumentWidget,
  defaultSize: { width: 500, height: 500 },
  minSize: { width: 300, height: 200 },
  capabilities: ['downloadable', 'fullscreen', 'copyable'],
}

Task 2.4: Create ImageWidget

File: components/widgets/ImageWidget/index.tsx

// frontend/components/widgets/ImageWidget/index.tsx

import { useState, useCallback } from 'react'
import { Image as ImageIcon, Download, ZoomIn, ZoomOut, RotateCw, Maximize2 } from 'lucide-react'
import { WidgetBase } from '../WidgetBase'
import { WidgetBaseProps, ImageWidgetData, WidgetDefinition } from '../types'
import { Button } from '@/components/ui/button'
import { cn } from '@/lib/utils'
import { toast } from 'sonner'

export function ImageWidget({
  id,
  title,
  data,
  metadata,
  isActive,
  isLoading,
  error,
  onClose,
}: WidgetBaseProps<ImageWidgetData>) {
  const [zoom, setZoom] = useState(1)
  const [rotation, setRotation] = useState(0)

  const handleDownload = useCallback(async () => {
    try {
      const response = await fetch(data.src)
      const blob = await response.blob()
      const url = URL.createObjectURL(blob)
      const a = document.createElement('a')
      a.href = url
      a.download = title.replace(/\s+/g, '_') + '.png'
      a.click()
      URL.revokeObjectURL(url)
      toast.success('Image downloaded')
    } catch (err) {
      toast.error('Failed to download image')
    }
  }, [data.src, title])

  const handleZoomIn = () => setZoom((z) => Math.min(z + 0.25, 3))
  const handleZoomOut = () => setZoom((z) => Math.max(z - 0.25, 0.25))
  const handleRotate = () => setRotation((r) => (r + 90) % 360)
  const handleReset = () => {
    setZoom(1)
    setRotation(0)
  }

  return (
    <WidgetBase
      title={title}
      icon={<ImageIcon className="h-4 w-4" />}
      metadata={metadata}
      isActive={isActive}
      isLoading={isLoading}
      error={error}
      onClose={onClose}
      onDownload={handleDownload}
      canDownload
      customActions={[
        {
          label: 'Zoom In',
          icon: <ZoomIn className="h-4 w-4 mr-2" />,
          onClick: handleZoomIn,
        },
        {
          label: 'Zoom Out',
          icon: <ZoomOut className="h-4 w-4 mr-2" />,
          onClick: handleZoomOut,
        },
        {
          label: 'Rotate',
          icon: <RotateCw className="h-4 w-4 mr-2" />,
          onClick: handleRotate,
        },
      ]}
    >
      <div className="flex flex-col h-full">
        {/* Prompt info for generated images */}
        {data.prompt && (
          <div className="px-3 py-2 bg-muted/30 border-b border-border/30">
            <p className="text-xs text-muted-foreground">
              <span className="font-medium">Prompt:</span> {data.prompt}
            </p>
            {data.model && (
              <p className="text-xs text-muted-foreground mt-1">
                <span className="font-medium">Model:</span> {data.model}
              </p>
            )}
          </div>
        )}

        {/* Image viewport */}
        <div
          className="flex-1 overflow-auto flex items-center justify-center bg-muted/10 p-4"
          onDoubleClick={handleReset}
        >
          <img
            src={data.src}
            alt={data.alt || title}
            style={{
              transform: `scale(${zoom}) rotate(${rotation}deg)`,
              transition: 'transform 0.2s ease',
              maxWidth: '100%',
              maxHeight: '100%',
              objectFit: 'contain',
            }}
            className="rounded shadow-lg"
          />
        </div>

        {/* Zoom controls */}
        <div className="flex items-center justify-center gap-2 px-3 py-2 border-t border-border/30">
          <Button variant="ghost" size="sm" onClick={handleZoomOut}>
            <ZoomOut className="h-4 w-4" />
          </Button>
          <span className="text-xs text-muted-foreground w-16 text-center">
            {Math.round(zoom * 100)}%
          </span>
          <Button variant="ghost" size="sm" onClick={handleZoomIn}>
            <ZoomIn className="h-4 w-4" />
          </Button>
          <Button variant="ghost" size="sm" onClick={handleRotate}>
            <RotateCw className="h-4 w-4" />
          </Button>
        </div>
      </div>
    </WidgetBase>
  )
}

export const ImageWidgetDef: WidgetDefinition = {
  type: 'image',
  displayName: 'Image',
  icon: 'Image',
  component: ImageWidget,
  defaultSize: { width: 500, height: 400 },
  minSize: { width: 200, height: 200 },
  capabilities: ['downloadable', 'fullscreen'],
}

---

Week 3: Canvas & Integration

Task 3.1: Create Canvas Component

Install dependencies:

cd frontend
npm install react-grid-layout @types/react-grid-layout

File: components/workspace/Canvas.tsx

// frontend/components/workspace/Canvas.tsx

import { useCallback, useMemo } from 'react'
import GridLayout, { Layout, WidthProvider } from 'react-grid-layout'
import { useWorkspaceStore } from '@/stores/workspace-store'
import { WidgetWrapper } from '../widgets/WidgetWrapper'
import { cn } from '@/lib/utils'
import 'react-grid-layout/css/styles.css'
import 'react-resizable/css/styles.css'

const ResponsiveGridLayout = WidthProvider(GridLayout)

interface CanvasProps {
  className?: string
}

export function Canvas({ className }: CanvasProps) {
  const widgets = useWorkspaceStore((s) => s.widgets)
  const widgetIds = useWorkspaceStore((s) => s.widgetIds)
  const activeWidgetId = useWorkspaceStore((s) => s.activeWidgetId)
  const positions = useWorkspaceStore((s) => s.positions)
  const sizes = useWorkspaceStore((s) => s.sizes)
  const updatePosition = useWorkspaceStore((s) => s.updatePosition)
  const updateSize = useWorkspaceStore((s) => s.updateSize)

  // Convert our state to react-grid-layout format
  const layout: Layout[] = useMemo(() => {
    return widgetIds.map((id, index) => {
      const pos = positions[id] || { x: (index % 2) * 6, y: Math.floor(index / 2) * 4 }
      const size = sizes[id] || { width: 6, height: 4 }

      return {
        i: id,
        x: pos.x,
        y: pos.y,
        w: size.width,
        h: size.height,
        minW: 3,
        minH: 2,
      }
    })
  }, [widgetIds, positions, sizes])

  const handleLayoutChange = useCallback((newLayout: Layout[]) => {
    newLayout.forEach((item) => {
      const currentPos = positions[item.i]
      const currentSize = sizes[item.i]

      if (!currentPos || currentPos.x !== item.x || currentPos.y !== item.y) {
        updatePosition(item.i, { x: item.x, y: item.y })
      }

      if (!currentSize || currentSize.width !== item.w || currentSize.height !== item.h) {
        updateSize(item.i, { width: item.w, height: item.h })
      }
    })
  }, [positions, sizes, updatePosition, updateSize])

  if (widgetIds.length === 0) {
    return (
      <div className={cn('flex items-center justify-center h-full', className)}>
        <div className="text-center text-muted-foreground">
          <p className="text-lg font-medium">No widgets yet</p>
          <p className="text-sm mt-1">
            Ask a question and results will appear here
          </p>
        </div>
      </div>
    )
  }

  return (
    <div className={cn('h-full overflow-auto', className)}>
      <ResponsiveGridLayout
        className="layout"
        layout={layout}
        cols={12}
        rowHeight={100}
        onLayoutChange={handleLayoutChange}
        draggableHandle=".widget-drag-handle"
        resizeHandles={['se', 'sw', 'ne', 'nw']}
        compactType="vertical"
        preventCollision={false}
        isResizable
        isDraggable
        margin={[12, 12]}
        containerPadding={[12, 12]}
      >
        {widgetIds.map((id) => {
          const widget = widgets[id]
          if (!widget) return null

          return (
            <div
              key={id}
              className={cn(
                'rounded-lg overflow-hidden',
                activeWidgetId === id && 'ring-2 ring-primary'
              )}
            >
              <WidgetWrapper
                widget={widget}
                isActive={activeWidgetId === id}
              />
            </div>
          )
        })}
      </ResponsiveGridLayout>
    </div>
  )
}

Task 3.2: Create WidgetTray Component

File: components/workspace/WidgetTray.tsx

// frontend/components/workspace/WidgetTray.tsx

import { useWorkspaceStore } from '@/stores/workspace-store'
import { getWidget } from '../widgets/registry'
import { Button } from '@/components/ui/button'
import { ScrollArea, ScrollBar } from '@/components/ui/scroll-area'
import { ChevronUp, ChevronDown, X } from 'lucide-react'
import { cn } from '@/lib/utils'

export function WidgetTray() {
  const widgets = useWorkspaceStore((s) => s.widgets)
  const widgetIds = useWorkspaceStore((s) => s.widgetIds)
  const activeWidgetId = useWorkspaceStore((s) => s.activeWidgetId)
  const isWidgetTrayOpen = useWorkspaceStore((s) => s.isWidgetTrayOpen)
  const toggleWidgetTray = useWorkspaceStore((s) => s.toggleWidgetTray)
  const setActiveWidget = useWorkspaceStore((s) => s.setActiveWidget)
  const removeWidget = useWorkspaceStore((s) => s.removeWidget)

  if (widgetIds.length === 0) return null

  return (
    <div className="border-t border-border/50 bg-background/95 backdrop-blur">
      {/* Toggle button */}
      <div className="flex items-center justify-between px-3 py-1.5 border-b border-border/30">
        <span className="text-xs font-medium text-muted-foreground">
          Widgets ({widgetIds.length})
        </span>
        <Button
          variant="ghost"
          size="sm"
          className="h-6 w-6 p-0"
          onClick={toggleWidgetTray}
        >
          {isWidgetTrayOpen ? (
            <ChevronDown className="h-4 w-4" />
          ) : (
            <ChevronUp className="h-4 w-4" />
          )}
        </Button>
      </div>

      {/* Widget list */}
      {isWidgetTrayOpen && (
        <ScrollArea className="h-20">
          <div className="flex gap-2 p-2">
            {widgetIds.map((id) => {
              const widget = widgets[id]
              if (!widget) return null

              const definition = getWidget(widget.type)
              const isActive = activeWidgetId === id

              return (
                <div
                  key={id}
                  className={cn(
                    'group relative flex items-center gap-2 px-3 py-2 rounded-md',
                    'bg-muted/50 hover:bg-muted cursor-pointer transition-colors',
                    'min-w-[150px] max-w-[200px]',
                    isActive && 'ring-2 ring-primary bg-muted'
                  )}
                  onClick={() => setActiveWidget(id)}
                >
                  <span className="text-muted-foreground">
                    {definition?.icon || '📄'}
                  </span>
                  <span className="text-sm truncate flex-1">
                    {widget.title}
                  </span>
                  <Button
                    variant="ghost"
                    size="sm"
                    className="h-5 w-5 p-0 opacity-0 group-hover:opacity-100"
                    onClick={(e) => {
                      e.stopPropagation()
                      removeWidget(id)
                    }}
                  >
                    <X className="h-3 w-3" />
                  </Button>
                </div>
              )
            })}
          </div>
          <ScrollBar orientation="horizontal" />
        </ScrollArea>
      )}
    </div>
  )
}

Task 3.3: Modify Chat Component

File to Modify: components/chatbot/chat.tsx

Key changes:

1. Import workspace store

2. Replace artifact viewer modal with canvas

3. Add workspace container layout

// CHANGES TO frontend/components/chatbot/chat.tsx

// Add imports
import { useWorkspaceStore } from '@/stores/workspace-store'
import { Canvas } from '../workspace/Canvas'
import { WidgetTray } from '../workspace/WidgetTray'

// In the component, replace the artifact modal with canvas layout
export function Chat({ chatId, initialMessages }: ChatProps) {
  // Existing state...
  const chatPanelWidth = useWorkspaceStore((s) => s.chatPanelWidth)
  const isChatCollapsed = useWorkspaceStore((s) => s.isChatCollapsed)
  const widgetIds = useWorkspaceStore((s) => s.widgetIds)

  // Remove selectedArtifact state and ArtifactViewer modal

  return (
    <div className="flex h-full">
      {/* Chat Panel */}
      <div
        className="flex flex-col border-r border-border/50"
        style={{ width: isChatCollapsed ? 48 : chatPanelWidth }}
      >
        {/* Existing chat content... */}
        <div className="flex-1 overflow-y-auto">
          {/* Messages */}
        </div>
        <MultimodalInput {...inputProps} />
      </div>

      {/* Canvas Panel */}
      <div className="flex-1 flex flex-col">
        <Canvas className="flex-1" />
        <WidgetTray />
      </div>
    </div>
  )
}

Task 3.4: Modify Message Component

File to Modify: components/chatbot/message.tsx

Key changes:

1. Instead of inline artifacts, emit to workspace store

2. Show small "widget created" indicators

// CHANGES TO frontend/components/chatbot/message.tsx

import { useWorkspaceStore } from '@/stores/workspace-store'
import { routeToolToWidget, transformToolResultToWidget } from '../widgets/router'

// In the component
const handleToolResult = useWorkspaceStore((s) => s.handleToolResult)

// When tool results come in, emit to workspace instead of inline render
useEffect(() => {
  if (message.database_results) {
    message.database_results.forEach((result) => {
      handleToolResult(
        'smart_query_database',
        result.toolCallId || 'unknown',
        result,
        message.conversationId || ''
      )
    })
  }

  if (message.documents) {
    message.documents.forEach((doc) => {
      handleToolResult(
        'search_knowledge',
        doc.toolCallId || 'unknown',
        doc,
        message.conversationId || ''
      )
    })
  }

  // Similar for code snippets, images, etc.
}, [message])

// Replace inline artifact rendering with widget indicators
// Instead of rendering full database results, show:
{message.database_results && (
  <div className="flex gap-2 mt-2">
    {message.database_results.map((result, i) => (
      <div
        key={i}
        className="flex items-center gap-2 px-2 py-1 rounded bg-muted/50 text-xs cursor-pointer"
        onClick={() => setActiveWidget(result.widgetId)}
      >
        <Database className="h-3 w-3" />
        <span>Query Result</span>
      </div>
    ))}
  </div>
)}

Task 3.5: Update useChat Hook

File to Modify: lib/chat/hooks.ts

Add widget event handling for tool-data events:

// CHANGES TO frontend/lib/chat/hooks.ts

import { useWorkspaceStore } from '@/stores/workspace-store'

// In the hook
const handleToolResult = useWorkspaceStore.getState().handleToolResult

// When processing tool-data events
if (event.type === 'tool-data') {
  // Existing message update logic...

  // Also emit to workspace
  if (event.data.database_results) {
    event.data.database_results.forEach((result: any) => {
      handleToolResult(
        'smart_query_database',
        event.data.toolCallId,
        result,
        chatId
      )
    })
  }

  // Similar for other result types
}

---

5) Files Summary

Files to CREATE

File	Purpose
frontend/components/widgets/types.ts	Type definitions
frontend/components/widgets/registry.ts	Widget registration
frontend/components/widgets/router.ts	Tool → Widget routing
frontend/components/widgets/WidgetBase.tsx	Base component
frontend/components/widgets/WidgetWrapper.tsx	Widget container
frontend/components/widgets/CodeWidget/index.tsx	Code display
frontend/components/widgets/DataWidget/index.tsx	Data tables/charts
frontend/components/widgets/DocumentWidget/index.tsx	Documents/RAG
frontend/components/widgets/ImageWidget/index.tsx	Images
frontend/components/workspace/Canvas.tsx	Canvas layout
frontend/components/workspace/WidgetTray.tsx	Widget tray
frontend/stores/workspace-store.ts	Zustand store

Files to MODIFY

File	Changes
frontend/components/chatbot/chat.tsx	Add canvas layout, remove artifact modal
frontend/components/chatbot/message.tsx	Emit to workspace, show widget indicators
frontend/lib/chat/hooks.ts	Add widget event handling

Files to DELETE (after migration)

File	Reason
frontend/components/chatbot/code-artifact.tsx	Moved to CodeWidget
frontend/components/chatbot/text-artifact.tsx	Moved to DocumentWidget
frontend/components/chatbot/sheet-artifact.tsx	Moved to DataWidget
frontend/components/chatbot/artifact-viewer.tsx	Replaced by Canvas

---

6) Dependencies to Install

cd frontend

# State management
npm install zustand

# Grid layout
npm install react-grid-layout @types/react-grid-layout

# Optional: Enhanced tables (can add in Phase 2)
# npm install @tanstack/react-table

---

7) Testing Checklist

Unit Tests

• Widget registry correctly registers/retrieves widgets

• Tool router maps tools to correct widget types

• Widget data transformers handle all tool result formats

• Workspace store actions work correctly

Integration Tests

• Tool results create widgets in canvas

• Widgets can be dragged and resized

• Widget tray shows all active widgets

• Active widget selection works

• Widget removal works

E2E Tests

• Ask database question → DataWidget appears in canvas

• Ask document question → DocumentWidget appears in canvas

• Ask code question → CodeWidget appears in canvas

• Generate image → ImageWidget appears in canvas

• Multiple widgets can be viewed simultaneously

• Layout persists across page refresh

Performance Tests

• 10+ widgets render at 60fps

• Widget creation < 200ms

• Canvas scroll is smooth

• Memory usage stable with many widgets

---

8) Rollout Plan

Week 1: Foundation (Dev Environment)

• Create all widget types and registry

• Create workspace store

• Create widget base components

Week 2: Migration (Dev Environment)

• Create all 4 widget components

• Test each widget independently

• Ensure feature parity with existing artifacts

Week 3: Integration (Staging)

• Create Canvas and WidgetTray

• Modify chat.tsx and message.tsx

• Integration testing

• Performance testing

Week 4: Rollout (Production)

• Feature flag for gradual rollout

• Monitor performance and errors

• Collect user feedback

• Delete deprecated files

---

9) Open Questions (Resolved)

The following architectural decisions are required before Phase 2 can start:

9.1 Widget Persistence in Zustand Store

Decision: YES - widgets persist across browser sessions via useWorkspaceStore.

Implementation:

• The Zustand store already uses persist() middleware (see Section 3.3)

• Widget data stored in localStorage under key automatos-workspace

• Partialize strategy: persist widgets, widgetIds, positions, sizes, layoutMode

• Session-specific state (like isLoading) is NOT persisted

// Already in useWorkspaceStore definition
persist(
  (set, get) => ({ /* ... */ }),
  {
    name: 'automatos-workspace',
    partialize: (state) => ({
      widgets: state.widgets,
      widgetIds: state.widgetIds,
      positions: state.positions,
      sizes: state.sizes,
      layoutMode: state.layoutMode,
      chatPanelWidth: state.chatPanelWidth,
    }),
  }
)

9.2 Widget Reference Syntax

Decision: Use @widget-<short-id> pattern with the following rules:

Syntax Rules:

@widget-<short-id>    # Reference by short ID (first 8 chars of UUID)
@widget:title         # Reference by title (fuzzy match)
@widget-latest        # Reference most recently created widget
@widget-active        # Reference currently active widget

Parsing Implementation:

// lib/widgets/reference-parser.ts

const WIDGET_REF_PATTERN = /@widget-([a-f0-9]{8}|latest|active)|@widget:([^\s]+)/gi

interface WidgetReference {
  type: 'id' | 'title' | 'special'
  value: string
  originalText: string
}

function parseWidgetReferences(text: string): WidgetReference[] {
  const matches = [...text.matchAll(WIDGET_REF_PATTERN)]
  return matches.map(match => ({
    type: match[1] ? (match[1] === 'latest' || match[1] === 'active' ? 'special' : 'id') : 'title',
    value: match[1] || match[2],
    originalText: match[0]
  }))
}

function resolveWidgetReference(ref: WidgetReference, store: WorkspaceState): Widget | null {
  switch (ref.type) {
    case 'id':
      return Object.values(store.widgets).find(w => w.id.startsWith(`widget-${ref.value}`)) || null
    case 'title':
      return Object.values(store.widgets).find(w =>
        w.title.toLowerCase().includes(ref.value.toLowerCase())
      ) || null
    case 'special':
      if (ref.value === 'latest') {
        return store.widgetIds.length > 0
          ? store.widgets[store.widgetIds[store.widgetIds.length - 1]]
          : null
      }
      if (ref.value === 'active') {
        return store.activeWidgetId ? store.widgets[store.activeWidgetId] : null
      }
      return null
  }
}

Scope: References are resolved within the current workspace/conversation context.

9.3 Mobile Layout Strategy

Decision: Use responsive breakpoints with simplified layout on mobile.

Strategy:

• Desktop (≥1024px): Full React Grid Layout with drag-drop

• Tablet (768-1023px): Simplified 2-column grid, drag-drop disabled

• Mobile (<768px): Single-column stack with swipeable widget cards

Implementation:

// components/workspace/Canvas.tsx

import { useMediaQuery } from '@/hooks/useMediaQuery'

function Canvas() {
  const isMobile = useMediaQuery('(max-width: 767px)')
  const isTablet = useMediaQuery('(min-width: 768px) and (max-width: 1023px)')

  if (isMobile) {
    return <MobileWidgetStack widgets={widgets} />  // Swipeable cards
  }

  if (isTablet) {
    return (
      <ResponsiveGridLayout
        cols={2}
        isDraggable={false}
        isResizable={false}
        // ... simplified layout
      />
    )
  }

  // Desktop: full functionality
  return (
    <ResponsiveGridLayout
      cols={12}
      isDraggable={true}
      isResizable={true}
      // ... full layout
    />
  )
}

// Mobile-specific component
function MobileWidgetStack({ widgets }: { widgets: Widget[] }) {
  const [activeIndex, setActiveIndex] = useState(0)

  return (
    <div className="mobile-widget-stack">
      <div className="widget-indicators">
        {widgets.map((_, i) => (
          <button
            key={i}
            className={cn('indicator', i === activeIndex && 'active')}
            onClick={() => setActiveIndex(i)}
          />
        ))}
      </div>
      <SwipeableViews index={activeIndex} onChangeIndex={setActiveIndex}>
        {widgets.map(widget => (
          <WidgetWrapper key={widget.id} widget={widget} isMobile />
        ))}
      </SwipeableViews>
    </div>
  )
}

Rationale: React Grid Layout is not mobile-friendly due to drag-drop interaction patterns. A swipeable card stack provides better UX on touch devices.

Alternative Considered: Using a modal/drawer pattern on mobile. Rejected because it breaks the multi-widget visibility goal.

---

9.4) Phase 1.5: Architecture Decisions Checklist

Before Phase 2 can start, the following must be verified:

Decision	Status	Verified By	Date
Widget persistence works in Zustand store	☐ Pending	QA Test	-
Widget reference syntax parser implemented	☐ Pending	Code Review	-
Mobile layout renders correctly on iOS/Android	☐ Pending	Device Test	-
No data loss on page refresh with 10+ widgets	☐ Pending	QA Test	-
Widget references resolve in chat input	☐ Pending	Integration Test	-

Acceptance Criteria:

• useWorkspaceStore persists and restores widgets correctly

• @widget-* syntax is parsed and resolved in chat messages

• Canvas renders appropriately on mobile, tablet, and desktop

• All Phase 1 success metrics are met (see Section 1)

---

10) References

• React Grid Layout Documentation

• Zustand Documentation

• PRD-31: Chatbot UX Upgrade

• PRD-38.0: Widget Architecture Master Plan

• Existing artifact components in components/chatbot/

---

Document Version: 1.0 Created: 2026-01-27 Estimated Implementation: 3 weeks