Relevant source files

The following files were used as context for generating this wiki page: - [app/lib/common/prompts/optimized.ts](https://github.com/ivanm696/codinit-dev-1.2.4/blob/main/app/lib/common/prompts/optimized.ts) - [app/lib/stores/workbench.ts](https://github.com/ivanm696/codinit-dev-1.2.4/blob/main/app/lib/stores/workbench.ts) - [app/lib/runtime/message-parser.spec.ts](https://github.com/ivanm696/codinit-dev-1.2.4/blob/main/app/lib/runtime/message-parser.spec.ts) - [app/components/chat/Markdown.tsx](https://github.com/ivanm696/codinit-dev-1.2.4/blob/main/app/components/chat/Markdown.tsx) - [app/components/chat/TestArtifact.tsx](https://github.com/ivanm696/codinit-dev-1.2.4/blob/main/app/components/chat/TestArtifact.tsx) - [app/lib/common/prompts/fine-tuned.ts](https://github.com/ivanm696/codinit-dev-1.2.4/blob/main/app/lib/common/prompts/fine-tuned.ts)

# Artifacts System The Artifacts System is a core architectural component designed to manage structured output from the AI assistant. It provides a containerized way to execute shell commands, create or update files, and visualize complex processes such as thinking steps or test results within the workbench environment. By wrapping technical operations in `` tags, the system separates conversational text from actionable code and configuration. The system is responsible for parsing streaming LLM responses, identifying artifact boundaries, and delegating specific actions (such as `file`, `shell`, or `start`) to the appropriate execution runners. This ensures that the user interface remains clean while the underlying WebContainer environment handles the technical heavy lifting of project initialization and maintenance. ## System Architecture The Artifacts System operates through a pipeline of parsing, state management, and execution. When the AI generates a response, the `StreamingMessageParser` identifies artifact tags and triggers callbacks that update the `WorkbenchStore`. ### Data Flow Overview ```mermaid flowchart TD LLM[LLM Stream] --> Parser[StreamingMessageParser] Parser -->|onArtifactOpen| WB_Store[WorkbenchStore] Parser -->|onActionOpen| Runner[ActionRunner] WB_Store -->|Updates State| UI[React UI Components] Runner -->|Executes| WC[WebContainer/Shell] UI -->|Render| ArtComp[Artifact/TestArtifact Components] ``` The diagram above illustrates how raw text from the LLM is transformed into executable actions and interactive UI elements. Sources: [app/lib/stores/workbench.ts](), [app/lib/runtime/message-parser.spec.ts]() ### Component Responsibilities | Component | Responsibility | Source | | :--- | :--- | :--- | | `StreamingMessageParser` | Scans text for `` and `` tags during streaming. | [app/lib/runtime/message-parser.spec.ts]() | | `WorkbenchStore` | Maintains the global state of active, thinking, and test artifacts. | [app/lib/stores/workbench.ts:68-80]() | | `ActionRunner` | Handles the lifecycle of individual actions (pending, running, complete). | [app/lib/stores/workbench.ts:400-450]() | | `Markdown` Component | Renders the text while detecting artifact classes to inject UI components. | [app/components/chat/Markdown.tsx:28-60]() | ## Artifact Types The system supports several specialized artifact types to handle different categories of AI output. ### 1. Code and Shell Artifacts These are the primary vehicles for project modification. They contain actions that interact directly with the file system and shell. * **`file`**: Writes or updates the content of a file at a specific `filePath`. The system requires full file content rather than diffs. * **`shell`**: Executes terminal commands sequentially (e.g., `npm install`). * **`start`**: A specialized command for long-running processes like development servers. * **`supabase`**: Handles database migrations and direct SQL queries. Sources: [app/lib/common/prompts/optimized.ts:250-265](), [app/lib/common/prompts/fine-tuned.ts:230-250]() ### 2. Thinking Artifacts Used to display the AI's internal reasoning process before generating code. * **Tag**: `` * **State**: Tracked in `thinkingArtifacts` within the store. * **UI**: Rendered via the `ThinkingProcess` component. Sources: [app/lib/common/prompts/optimized.ts:312-330](), [app/lib/stores/workbench.ts:72-73]() ### 3. Test Artifacts Specifically designed to visualize the results of test suite executions (e.g., Vitest). * **Summary Data**: Tracks total, passed, failed, and skipped tests. * **Coverage**: Visualizes line, statement, function, and branch coverage. * **Interactivity**: Allows users to re-run tests or click on failed files to open them in the editor. Sources: [app/lib/stores/workbench.ts:82-110](), [app/components/chat/TestArtifact.tsx:30-80]() ## Execution Logic and Safety The system implements a global execution queue to ensure that actions are performed in a logical and non-conflicting order. ```mermaid sequenceDiagram participant LLM as AI Assistant participant Store as WorkbenchStore participant Runner as ActionRunner participant WC as WebContainer LLM->>Store: Send Action (file/shell) Store->>Store: Add to #globalExecutionQueue Store->>Runner: _runAction() alt Action is 'file' Runner->>WC: fs.writeFile() Store->>Store: updateFile in Editor else Action is 'shell' Runner->>WC: shell.run() end Runner-->>Store: Action Complete ``` This sequence ensures that file system changes are reflected in the editor before shell commands that might depend on them are executed. Sources: [app/lib/stores/workbench.ts:133-145](), [app/lib/stores/workbench.ts:488-530]() ### Critical Safety Constraints 1. **Data Preservation**: Destructive operations like `DROP` or transaction controls (`COMMIT/ROLLBACK`) are strictly forbidden in database artifacts. Sources: [app/lib/common/prompts/optimized.ts:45-60]() 2. **No Diffs**: The system requires the entire file content for every update to ensure consistency in the WebContainer environment. Sources: [app/lib/common/prompts/optimized.ts:265]() 3. **Queue Limits**: The `WorkbenchStore` limits pending actions to 50 to prevent memory overflow. Sources: [app/lib/stores/workbench.ts:117-118]() ## UI Rendering and Integration Artifacts are integrated into the chat interface using specialized CSS classes that the `Markdown` component detects during rendering. ```typescript // app/components/chat/Markdown.tsx:32-48 if (className?.includes('__codinitArtifact__')) { const messageId = node?.properties.dataMessageId as string; return ; } if (className?.includes('__testArtifact__')) { const messageId = node?.properties.dataMessageId as string; return ; } ``` The `stripCodeFenceFromArtifact` utility ensures that the UI remains clean by removing the markdown code fences (e.g., ` ```xml `) that the LLM often wraps around artifact tags. Sources: [app/components/chat/Markdown.tsx:90-115]() ## Summary The Artifacts System acts as the bridge between AI reasoning and browser-based project execution. By utilizing a structured tag system, it allows the `WorkbenchStore` to manage complex file operations and shell commands while providing users with specialized views for thinking processes and test summaries. This modularity ensures that code generation is safe, orderly, and highly visible to the developer.