@widgetic/chat 0.1.4

package/README.md

@@ -0,0 +1,440 @@
+# @widgetic/chat
+
+A modern, reusable chat module built with Svelte 5, TypeScript, and the Widgetic Design System. Designed for canvas-based platforms with frame content integration and LLM communication.
+
+## Features
+
+- 🎨 **Modern UI** - Built with Svelte 5 runes and Tailwind CSS
+- 🔌 **Platform Agnostic** - Adapter pattern for different contexts (frames, documents, etc.)
+- 📱 **Responsive Design** - Mobile-friendly with collapsible interface
+- 📁 **File Attachments** - Support for images, videos, documents with preview
+- 🔄 **Real-time Updates** - WebSocket integration ready
+- 🤖 **AI Integration** - LLM communication with context awareness
+- 📦 **TypeScript** - Fully typed for better development experience
+- ♿ **Accessible** - WCAG compliant with keyboard navigation
+
+## Installation
+
+```bash
+npm install @widgetic/chat
+```
+
+### Peer Dependencies
+
+```bash
+npm install @widgetic/design-system @widgetic/api-sdk svelte @sveltejs/kit
+```
+
+## Quick Start
+
+```svelte
+<script>
+  import { Chat, createChatService, createWidgeticAdapter } from '@widgetic/chat';
+  
+  // Create a context for your frame/component
+  const context = {
+    id: 'canvas_123:component_456',
+    type: 'frame',
+    parentId: 'canvas_123',
+    title: 'My Component',
+    metadata: {
+      frameTitle: 'Interactive Button',
+      canvasId: 'canvas_123'
+    }
+  };
+</script>
+
+<Chat {context} />
+```
+
+## Core Concepts
+
+### Context
+
+A context represents what the user is chatting about - typically a frame, document, or other object:
+
+```typescript
+interface ChatContext {
+  id: string;           // Unique identifier (e.g., "canvas_123:component_456")
+  type: ContextType;    // 'frame' | 'text' | 'image' | 'document' | 'canvas'
+  parentId: string;     // Parent container ID
+  title?: string;       // Display name
+  thumbnail?: string;   // Preview image URL
+  metadata?: Record<string, any>; // Additional context data
+}
+```
+
+### Platform Adapters
+
+Adapters handle platform-specific functionality:
+
+```typescript
+import { createWidgeticAdapter } from '@widgetic/chat';
+
+const adapter = createWidgeticAdapter();
+
+// Register event handlers
+adapter.onFrameSelection((frameId) => {
+  console.log('Frame selected:', frameId);
+});
+
+// Capture screenshots
+const screenshot = await adapter.captureFrameScreenshot('frame_123'); 
+```
+
+### Chat Service
+
+Handles API communication and data management:
+
+```typescript
+import { createChatService } from '@widgetic/chat';
+
+const chatService = createChatService({
+  // API configuration
+});
+
+// Send messages
+const message = await chatService.sendMessage(conversationId, {
+  messageContent: 'Hello, AI!',
+  attachments: [file]
+});
+```
+
+## Components
+
+### Main Chat Component
+
+```svelte
+<Chat 
+  {context}
+  config={{
+    ui: {
+      position: 'right',
+      showTimestamps: true
+    },
+    features: {
+      fileUpload: true,
+      voiceTranscription: false,
+      screenshot: true,
+      aiSuggestions: true,
+      screenRecording: false,
+      restoreCheckpoint: true
+    }
+  }}
+  class="custom-chat-styles"
+/>
+```
+
+### Context Preview
+
+For collapsed chat states:
+
+```svelte
+<ContextPreview 
+  {context}
+  onclick={() => expandChat()}
+/>
+```
+
+### Individual Components
+
+You can also use individual components:
+
+```svelte
+<script>
+  import { ChatMessages, ChatInput } from '@widgetic/chat';
+</script>
+
+<ChatMessages 
+  {messages}
+  {isLoading}
+  {context}
+/>
+
+<ChatInput
+  value={inputText}
+  {attachments}
+  onSend={handleSend}
+  onInputChange={handleInputChange}
+/>
+```
+
+## State Management
+
+The chat module uses Svelte 5 runes for reactive state management:
+
+```typescript
+import { chatStore } from '@widgetic/chat';
+
+// Access reactive state
+let chatState = $state(chatStore);
+
+// Dispatch actions
+chatStore.dispatch({
+  type: 'SET_ACTIVE_CONTEXT',
+  payload: { contextId: 'frame_123', isExpanded: true }
+});
+
+// Helper methods
+chatStore.actions.setActiveContext('frame_123', true);
+chatStore.actions.addMessage(conversationId, message);
+```
+
+## Configuration
+
+### Chat Config
+
+```typescript
+interface ChatConfig {
+  api: {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+  };
+  ui: {
+    position: 'right' | 'bottom' | 'left' | 'floating';
+    width?: number;
+    height?: number;
+    showTimestamps?: boolean;
+    maxFileSize?: number;
+  };
+  features: {
+    fileUpload: boolean;
+    voiceTranscription: boolean;
+    screenshot: boolean;
+    aiSuggestions: boolean;
+    screenRecording: boolean;
+    restoreCheckpoint: boolean;
+  };
+}
+```
+
+### Default Configuration
+
+```typescript
+import { DEFAULT_CHAT_CONFIG } from '@widgetic/chat';
+
+const customConfig = {
+  ...DEFAULT_CHAT_CONFIG,
+  ui: {
+    ...DEFAULT_CHAT_CONFIG.ui,
+    position: 'bottom'
+  }
+};
+```
+
+## File Handling
+
+### Supported File Types
+
+- **Images**: JPEG, PNG, SVG (max 10MB)
+- **Videos**: MP4 (max 100MB) 
+- **Documents**: PDF, TXT, MD, .mermaid (max 25MB)
+
+### File Utilities
+
+```typescript
+import { 
+  validateFile, 
+  createFilePreview, 
+  compressImage 
+} from '@widgetic/chat';
+
+// Validate before upload
+const validation = validateFile(file);
+if (!validation.valid) {
+  console.error(validation.error);
+}
+
+// Create preview
+const preview = await createFilePreview(file);
+
+// Compress images
+const compressed = await compressImage(file, {
+  maxWidth: 1920,
+  maxHeight: 1080,
+  quality: 0.8
+});
+```
+
+## API Integration
+
+### Widgetic API SDK
+
+The chat service integrates with the Widgetic API SDK:
+
+```typescript
+import { ConversationsApi, MessagesApi } from '@widgetic/api-sdk';
+
+// The service handles API calls automatically
+const conversations = await chatService.getConversations(contextId);
+const messages = await chatService.getMessages(conversationId);
+```
+
+### Custom API Integration
+
+You can implement custom chat services:
+
+```typescript
+import type { ChatService } from '@widgetic/chat';
+
+class CustomChatService implements ChatService {
+  async getConversations(contextId: string) {
+    // Your implementation
+  }
+  
+  async sendMessage(conversationId: string, data: any) {
+    // Your implementation
+  }
+}
+```
+
+## Styling
+
+### CSS Classes
+
+The chat module uses Tailwind CSS with design system components:
+
+```css
+.chat-container {
+  /* Custom chat container styles */
+}
+
+.chat-expanded {
+  /* Expanded chat styles */
+}
+
+.message-bubble {
+  /* Message bubble styles */
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  ChatContext,
+  ChatMessage,
+  ChatConversation,
+  ChatConfig,
+  ChatState,
+  PlatformAdapter
+} from '@widgetic/chat';
+```
+
+## Examples
+
+### Frame-based Chat
+
+```svelte
+<script>
+  import { Chat } from '@widgetic/chat';
+  
+  const frameContext = {
+    id: 'canvas_123:button_component',
+    type: 'frame',
+    parentId: 'canvas_123',
+    title: 'Interactive Button',
+    metadata: {
+      isPublished: true,
+      dimensions: { width: 200, height: 50 }
+    }
+  };
+</script>
+
+<Chat 
+  context={frameContext}
+  config={{
+    ui: { position: 'right' },
+    features: { 
+      fileUpload: true,
+      screenshot: true,
+      screenRecording: false,
+      restoreCheckpoint: true
+    }
+  }}
+/>
+```
+
+### Document Chat
+
+```svelte
+<script>
+  const documentContext = {
+    id: 'doc_456',
+    type: 'text',
+    parentId: 'editor_123',
+    title: 'My Document.md',
+    metadata: {
+      contentType: 'markdown',
+      wordCount: 1250
+    }
+  };
+</script>
+
+<Chat context={documentContext} />
+```
+
+### Programmatic Control
+
+```svelte
+<script>
+  import { chatStore, createChatService } from '@widgetic/chat';
+  
+  let chatService = createChatService();
+  
+  async function sendProgrammaticMessage() {
+    const conversation = await chatService.createConversation(
+      context.id, 
+      { title: 'Auto Chat' }
+    );
+    
+    await chatService.sendMessage(conversation.id, {
+      messageContent: 'This is an automated message',
+      messageType: 'user'
+    });
+    
+    chatStore.actions.setActiveContext(context.id, true);
+  }
+</script>
+```
+
+## Development
+
+### Building
+
+```bash
+npm run build
+npm run package
+```
+
+### Testing
+
+```bash
+npm run check
+npm run lint
+```
+
+### Watching
+
+```bash
+npm run package:watch
+```
+
+## License
+
+MIT
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+---
+
+For more detailed documentation, see the [API Reference](./docs/api.md) and [Examples](./docs/examples.md).

package/dist/adapters/index.d.ts

@@ -0,0 +1,2 @@
+export { WidgeticCanvasAdapter, createWidgeticAdapter } from './widgeticAdapter.js';
+export type { PlatformAdapter, WidgeticAdapter, AdapterFactory, AdapterConfig } from '../types/index.js';

package/dist/adapters/index.js

@@ -0,0 +1,2 @@
+// Platform Adapters
+export { WidgeticCanvasAdapter, createWidgeticAdapter } from './widgeticAdapter.js';

package/dist/adapters/widgeticAdapter.d.ts

@@ -0,0 +1,185 @@
+import type { WidgeticAdapter, ChatContext, FrameContext, ContextCapabilities } from '../types/index.js';
+/**
+ * Widgetic Canvas Platform Adapter
+ * Handles frame-based contexts for the Widgetic canvas system
+ */
+export declare class WidgeticCanvasAdapter implements WidgeticAdapter {
+    name: "widgetic";
+    version: string;
+    private frameSelectionCallbacks;
+    private frameDeselectionCallbacks;
+    private contextChangeCallbacks;
+    private contextUpdateCallbacks;
+    /**
+     * Extract frame ID from context object
+     */
+    getContextId(contextObject: any): string;
+    /**
+     * Get human-readable title for the frame
+     */
+    getContextTitle(contextObject: any): string;
+    /**
+     * Get context type
+     */
+    getContextType(): string;
+    /**
+     * Create a standardized chat context from a frame object
+     */
+    createContext(contextObject: any): FrameContext;
+    /**
+     * Returns the capabilities supported by the Widgetic platform adapter.
+     *
+     * Capabilities explained:
+     * - supportsScreenshot: Can capture static images of frame content
+     * - supportsRecording: Can record video of user interactions within frames
+     * - supportsFileUpload: Can handle file uploads via drag-and-drop or file picker
+     * - supportsTextInput: Can handle text-based chat messages
+     * - supportsMediaCapture: Can handle general media input (camera access, microphone,
+     *   file uploads, reference images) beyond just screenshots and recordings
+     */
+    getCapabilities(): ContextCapabilities;
+    /**
+     * Get AI suggestions based on frame context
+     */
+    getSuggestions(context: ChatContext): Promise<string[]>;
+    /**
+     * Get available actions for this frame
+     */
+    getActions(context: ChatContext): Promise<any[]>;
+    /**
+     * Capture screenshot of a specific frame
+     */
+    captureFrameScreenshot(frameId: string): Promise<Blob>;
+    /**
+     * Start recording a frame
+     */
+    startFrameRecording(frameId: string): Promise<void>;
+    /**
+     * Capture screenshot of any frame context
+     */
+    captureScreenshot(contextId: string): Promise<Blob>;
+    /**
+     * Start recording for any context
+     */
+    startRecording(contextId: string): Promise<void>;
+    /**
+     * Stop recording (placeholder)
+     */
+    stopRecording(): Promise<Blob>;
+    /**
+     * Get frame content and metadata with optional element-specific inspection.
+     *
+     * This method retrieves detailed information about a frame's structure, components,
+     * and optionally focuses on a specific element within the frame. It's used by the
+     * AI to understand the frame's composition and provide targeted suggestions.
+     *
+     * @param frameId - The unique identifier of the frame to inspect
+     * @param elementId - Optional. The specific element within the frame to focus on
+     * @returns Promise containing frame content, structure, and metadata
+     *
+     * Use cases:
+     * - General frame analysis: getFrameContent('frame-123')
+     * - Specific element targeting: getFrameContent('frame-123', 'button-456')
+     * - AI code generation based on existing components
+     * - Providing context for design suggestions
+     */
+    getFrameContent(frameId: string, elementId?: string): Promise<any>;
+    /**
+     * Get detailed information about a specific element within a frame.
+     *
+     * This method provides comprehensive data about a selected element, including
+     * its properties, styling, position, and relationships to other elements.
+     * Used when the user wants to make changes to a specific component.
+     *
+     * @param frameId - The frame containing the element
+     * @param elementId - The unique identifier of the element to inspect
+     * @returns Element details including properties, styling, and context
+     */
+    getElementDetails(frameId: string, elementId: string): Promise<any>;
+    /**
+     * Get the hierarchical structure of all components within a frame.
+     *
+     * This method provides a tree-like representation of the frame's content,
+     * showing how components are nested and organized. Useful for understanding
+     * the overall layout and suggesting structural improvements.
+     *
+     * @param frameId - The frame to analyze
+     * @returns Hierarchical structure of frame components
+     */
+    getFrameStructure(frameId: string): Promise<any>;
+    /**
+     * Get a list of all components within a frame with their basic properties.
+     *
+     * This method provides a flat list of all components for quick reference
+     * and bulk operations. Useful for inventory, search, and batch modifications.
+     *
+     * @param frameId - The frame to analyze
+     * @returns Array of component summaries
+     */
+    getFrameComponents(frameId: string): Promise<any[]>;
+    /**
+     * Enable element selection mode for a frame.
+     *
+     * This method puts the frame into a special selection mode where users can
+     * click on individual elements to select them for targeted AI assistance.
+     * When an element is selected, it becomes the focus for subsequent AI interactions.
+     *
+     * @param frameId - The frame to enable selection mode for
+     * @returns Promise that resolves when selection mode is active
+     *
+     * Behavior:
+     * - Highlights hoverable elements
+     * - Shows selection cursor
+     * - Captures element clicks
+     * - Provides visual feedback for selection
+     * - Automatically focuses chat on selected element
+     */
+    enableElementSelection(frameId: string): Promise<void>;
+    /**
+     * Select a specific element within a frame for targeted AI assistance.
+     *
+     * This method is called when a user clicks on an element during selection mode.
+     * It highlights the selected element and prepares it for AI interaction.
+     *
+     * @param frameId - The frame containing the element
+     * @param elementId - The element that was selected
+     * @returns Promise that resolves when element is selected
+     */
+    selectElement(frameId: string, elementId: string): Promise<void>;
+    /**
+     * Register callback for frame selection events
+     */
+    onFrameSelection(callback: (frameId: string) => void): () => void;
+    /**
+     * Register callback for frame deselection events
+     */
+    onFrameDeselection(callback: (frameId: string) => void): () => void;
+    /**
+     * Register callback for context changes
+     */
+    onContextChange(callback: (context: ChatContext | null) => void): () => void;
+    /**
+     * Register callback for context updates
+     */
+    onContextUpdate(callback: (context: ChatContext) => void): () => void;
+    /**
+     * Trigger frame selection event
+     */
+    triggerFrameSelection(frameId: string): void;
+    /**
+     * Trigger frame deselection event
+     */
+    triggerFrameDeselection(frameId: string): void;
+    /**
+     * Trigger context change event
+     */
+    triggerContextChange(context: ChatContext | null): void;
+    /**
+     * Trigger context update event
+     */
+    triggerContextUpdate(context: ChatContext): void;
+}
+/**
+ * Create a new Widgetic adapter instance
+ */
+export declare function createWidgeticAdapter(): WidgeticCanvasAdapter;