Artifacts Browser & Code Viewer
Relevant source files
The following files were used as context for generating this wiki page:
- apps/macos/Happy/Views/ArtifactBrowser.swift
- apps/web/vue/src/components/app/ArtifactViewer.vue
- apps/macos/Happy/Views/Components/ArtifactDetailView.swift
- apps/mobile/ios/Happy/Views/ArtifactDetailView.swift
- apps/mobile/ios/Happy/Models/Artifact.swift
- packages/schema/protocol/coverage/src/updates/artifact.ts.html
- apps/web/vue/src/composables/useArtifactDownload.test.ts
The Artifacts Browser & Code Viewer is a multi-platform system designed to display, manage, and interact with files generated during Claude Code and Codex sessions. It provides a structured interface for navigating file trees, viewing syntax-highlighted source code, previewing images, and downloading generated assets.
Sources: apps/macos/Happy/Views/ArtifactBrowser.swift:15-25, apps/web/vue/src/components/app/ArtifactViewer.vue:4-15
Architecture and Components
The system follows a consistent structural pattern across web (Vue), macOS (SwiftUI), and mobile (SwiftUI) platforms, typically consisting of a sidebar for file navigation and a main detail area for content rendering.
Component Structure
The primary interface is split into two functional zones:
- Sidebar/Navigation: Displays a file tree or list of artifacts.
- Detail Area: Renders the specific content based on the artifact's file type (code, image, or document).
The diagram shows the high-level component hierarchy shared across the different application implementations.
Sources: apps/macos/Happy/Views/ArtifactBrowser.swift:38-50, apps/web/vue/src/components/app/ArtifactViewer.vue:155-165
Core Data Structures
Artifacts are defined by a set of shared properties including identifiers, session associations, and content metadata.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier for the artifact. |
sessionId | String | Association with a specific Claude session. |
filePath | String | Path within the project structure (optional). |
fileType | Enum | Classification: code, image, document, data, or unknown. |
language | String | Programming language for syntax highlighting (e.g., swift, typescript). |
body / content | String | The actual data (source code or base64 image). |
Sources: apps/mobile/ios/Happy/Models/Artifact.swift:15-30, packages/schema/protocol/coverage/src/updates/artifact.ts.html:34-45
Navigation and File Trees
The system implements advanced navigation logic to handle varying sizes of artifact collections.
Performance Optimizations (HAP-873)
Both macOS and Vue implementations utilize a "threshold" pattern to switch between standard and optimized rendering. When the number of nodes exceeds 100, the system transitions to virtualized or flattened rendering to maintain performance for collections containing 1000+ artifacts.
- macOS: Switches from
OutlineGroupto aLazyVStack-based flat tree. - Vue: Switches from a recursive component to a
VirtualFileTree.
Sources: apps/macos/Happy/Views/ArtifactBrowser.swift:11-13, apps/web/vue/src/components/app/ArtifactViewer.vue:32-36
File Type Inference
The system automatically determines how to display an artifact based on its file extension or MIME type.
| Extension | Inferred Language | Icon Category |
|---|---|---|
.swift | Swift | Code |
.py, .pyw | Python | Code |
.js, .jsx | JavaScript | Code |
.ts, .tsx | TypeScript | Code |
.md, .markdown | Markdown | Document |
.png, .jpg | N/A | Image |
Sources: apps/mobile/ios/Happy/Models/Artifact.swift:105-150, apps/macos/Happy/Views/ArtifactBrowser.swift:285-305
Content Rendering
Artifacts are rendered using specialized viewers optimized for their specific type.
Code Viewer
The code viewer provides syntax highlighting using native AttributedString logic on macOS/iOS and components like CodeBlock on the web. Features include:
- Line Numbers: Toggable display for better readability.
- Copy to Clipboard: Quick access to copy the entire file or specific blocks.
- Search: In-content search with navigation between matches (iOS).
Sources: apps/mobile/ios/Happy/Views/ArtifactDetailView.swift:125-150, apps/macos/Happy/Views/Components/ArtifactDetailView.swift:135-145
Image Previewer
For image artifacts, the system renders the raw data (often base64 encoded) with features such as:
- Pinch-to-zoom: Supported on mobile and macOS.
- Checkerboard Background: Used on macOS to visualize transparency in images.
Sources: apps/macos/Happy/Views/Components/ArtifactDetailView.swift:230-245, apps/web/vue/src/components/app/ArtifactViewer.vue:220-225
Interaction and Persistence
The browser provides several ways to interact with and export artifact data.
Download Logic
The useArtifactDownload logic enables users to export files either individually or as a combined bundle.
The sequence describes the process of bundling multiple session artifacts into a single archive for export.
Sources: apps/web/vue/src/components/app/ArtifactViewer.vue:105-120, apps/web/vue/src/composables/useArtifactDownload.test.ts:145-165
OS Integration
Native applications include deep integration with operating system features:
- QuickLook (macOS): Integration for instant file previews.
- Drag and Drop (macOS): Ability to drag artifact nodes directly to Finder.
- Share Sheet (iOS): Integration with the native iOS sharing menu for images and text.
Sources: apps/macos/Happy/Views/Components/ArtifactDetailView.swift:15-25, apps/mobile/ios/Happy/Views/ArtifactDetailView.swift:230-245
Conclusion
The Artifacts Browser & Code Viewer provides a cohesive experience for reviewing session outputs. By implementing platform-specific optimizations like virtualization for large trees and native OS integrations for file handling, it ensures that users can efficiently navigate and utilize the assets generated by the Magic Agent ecosystem.