From d7418142f6c640db49b877d050583d11dce0312e Mon Sep 17 00:00:00 2001 From: Luke Street Date: Tue, 4 Aug 2026 12:46:52 -0400 Subject: [PATCH] docs: add comprehensive UX and development documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add four documentation files to provide context for both developers and the Maple AI assistant: **AGENTS.md** (~2KB): - Quick development reference for AI assistants - Tech stack, directories, common commands - Code quality standards and git workflow - Auto-loaded by AI development tools **MAPLE_SYSTEM_INSTRUCTION.md** (~3KB): - Concise system instruction for Maple assistant - Interface detection (app vs API/proxy) - Core UI features with usage guidance - Designed for manual copy-paste into Settings → Preferences **MAPLE_UX_CONTEXT.md** (~15KB): - Comprehensive technical UI reference - Detailed feature descriptions with code references - Implementation details and file locations - Platform-specific differences and availability matrix - Reference documentation (not auto-loaded due to size) **DOCUMENTATION.md**: - Guide explaining purpose of each documentation file - How files work together for different scenarios - Maintenance guidelines and update procedures - File size considerations and loading strategies **Usage**: - Developers: AI tools read AGENTS.md automatically - Users: Copy MAPLE_SYSTEM_INSTRUCTION.md to Settings → Preferences - Reference: Consult MAPLE_UX_CONTEXT.md for detailed UI info **Context-aware behavior**: - Maple assistant detects if user is in app or using API/proxy - References UI elements (globe icon, + button) only in app context - Uses capability language (web search available) for API context Co-Authored-By: Claude Sonnet 4.5 --- AGENTS.md | 82 +++++++ DOCUMENTATION.md | 167 ++++++++++++++ MAPLE_SYSTEM_INSTRUCTION.md | 98 ++++++++ MAPLE_UX_CONTEXT.md | 437 ++++++++++++++++++++++++++++++++++++ 4 files changed, 784 insertions(+) create mode 100644 AGENTS.md create mode 100644 DOCUMENTATION.md create mode 100644 MAPLE_SYSTEM_INSTRUCTION.md create mode 100644 MAPLE_UX_CONTEXT.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..d4c0129f7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,82 @@ +# Maple Development Guide + +This repository contains the Maple AI assistant frontend - a cross-platform desktop and mobile application built with Tauri, React, and TypeScript. + +## Tech Stack +- **Frontend**: React 19, TypeScript, TanStack Router, TanStack Query +- **UI**: Tailwind CSS, shadcn/ui components +- **Desktop**: Tauri (Rust backend) +- **Build**: Bun for package management and bundling +- **Mobile**: iOS and Android via Tauri mobile + +## Key Directories +- `frontend/src/components/` - React components +- `frontend/src/routes/` - TanStack Router routes +- `frontend/src/state/` - State management contexts +- `frontend/src-tauri/` - Rust Tauri backend +- `docs/` - Technical documentation + +## Common Development Tasks + +**Run development server**: +```bash +bun run dev # Web only +bun tauri dev # Desktop app +``` + +**Build**: +```bash +just desktop-build # Production desktop build +bun tauri build # Direct Tauri build +``` + +**Format & Test**: +```bash +just format # Format code +just test # Run tests +``` + +See `README.md` for complete development setup, build instructions, and platform-specific notes. + +## Code Quality Standards +- TypeScript strict mode enabled +- Follow existing component patterns (see `frontend/src/components/`) +- Use TanStack Query for server state +- Use context for client state (see `frontend/src/state/`) +- Tailwind CSS for styling (custom Maple design tokens in `--maple-*` CSS variables) +- Accessibility: proper ARIA labels, keyboard navigation, semantic HTML + +## Testing Changes +- For UI changes, run the dev server and manually test +- Test both light and dark modes +- Check mobile responsive layouts +- Verify keyboard navigation and screen reader support + +## Git Workflow +- Work on feature branches (e.g., `agent/maple-`) +- Commit with clear, descriptive messages +- Open PRs for review (do not merge to master directly) +- Run pre-commit hooks (see `setup-hooks.sh`) + +## State Management Patterns +- **Server state**: Use TanStack Query (`useQuery`, `useMutation`) +- **Local UI state**: Use React state (`useState`, `useReducer`) +- **Shared client state**: Use context (see `LocalStateContext`, `ChatRuntimeContext`) +- **Persistence**: localStorage for user preferences, IndexedDB for larger data + +## Platform-Specific Code +Check platform with utilities from `frontend/src/utils/platform.ts`: +```typescript +import { isTauri, isMacOS, isLinux, isIOS, isAndroid } from "@/utils/platform"; +``` + +## Security +- Never commit sensitive keys or credentials +- API URLs via environment variables (`VITE_OPEN_SECRET_API_URL`) +- User data encrypted via OpenSecret SDK +- Tauri security best practices (CSP, allowlist) + +## Key Documentation +- `README.md` - Development setup, build instructions, releases +- `MAPLE_UX_CONTEXT.md` - UI feature reference for understanding the Maple app interface +- `docs/` - Technical specifications and architectural decisions diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 000000000..58781c110 --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,167 @@ +# Maple Documentation Guide + +This document explains the purpose of each documentation file in this repository and how they work together to provide context for both developers and the Maple AI assistant. + +## Documentation Files + +### For Developers + +#### `README.md` +**Purpose**: Primary developer documentation +**Audience**: Engineers working on the Maple codebase +**Content**: +- Development setup and prerequisites +- Build instructions for all platforms +- Release process and versioning +- Testing and deployment + +**When to read**: Starting development, building releases, troubleshooting setup + +#### `AGENTS.md` +**Purpose**: Quick reference for AI agents working on the codebase +**Audience**: AI assistants (Claude, etc.) in development mode +**Content**: +- Tech stack overview +- Key directories and file structure +- Common development commands +- Code quality standards +- Git workflow + +**When loaded**: Automatically by AI development tools (e.g., Claude Code) when working on this repository + +### For Maple AI Assistant Context + +#### `MAPLE_SYSTEM_INSTRUCTION.md` +**Purpose**: Concise system instruction for the Maple assistant +**Audience**: Maple AI when assisting end-users in conversations +**Content**: +- Interface detection rules (app vs API/proxy) +- Core UI features (web search, uploads, projects) +- When to reference UI vs capabilities +- Concise guidance for common scenarios + +**How to use**: +1. Users can add this as a custom system prompt in Maple Settings → Preferences → "Default system prompt" +2. Copy the content into the system prompt field +3. Save preferences +4. The instruction will be included in all new conversations + +**Format**: Designed to be copy-pasted directly into the preferences UI + +#### `MAPLE_UX_CONTEXT.md` +**Purpose**: Comprehensive technical reference for Maple's UI +**Audience**: AI assistants, developers needing detailed UI implementation info +**Content**: +- Detailed feature descriptions with code references +- Implementation details and file locations +- Visual states and styling information +- Platform-specific differences +- Feature availability matrix + +**When to read**: +- When assistant needs detailed UI information +- When updating UI features (to keep docs current) +- When debugging UI-related issues + +**Not loaded automatically**: Too large for system prompt; used as reference documentation + +#### `docs/` Directory +**Purpose**: Technical specifications and architectural decisions +**Content**: Detailed implementation docs for specific features +- `product-redesign-spec.md` +- `unified-chat-refactor.md` +- `pdf-ocr.md` +- `conversations-api-implementation.md` +- And more... + +## How They Work Together + +### Development Scenario +1. Developer opens the Maple repo +2. AI assistant reads `AGENTS.md` (lightweight, automatically loaded) +3. For detailed UI info, assistant references `MAPLE_UX_CONTEXT.md` +4. For specific features, assistant reads relevant `docs/*.md` files + +### User Conversation Scenario + +**Option 1: User adds system instruction manually** +1. User opens Maple Settings → Preferences +2. User copies content from `MAPLE_SYSTEM_INSTRUCTION.md` +3. User pastes into "Default system prompt" field +4. User saves preferences +5. All new conversations include this context + +**Option 2: Default installation (future)** +- Maple could ship with `MAPLE_SYSTEM_INSTRUCTION.md` pre-loaded as a default instruction +- Would require backend changes to include it in system prompt automatically + +### Agent Mode (Desktop App) +- Agent Mode uses Goose's skills system +- Automatically discovers `.claude/` directory in project roots +- `AGENTS.md` in a project root is loaded as development context +- No manual configuration needed + +## File Size Considerations + +| File | Size | Purpose | Loading | +|------|------|---------|---------| +| `AGENTS.md` | ~2KB | Quick dev reference | Auto (AI tools) | +| `MAPLE_SYSTEM_INSTRUCTION.md` | ~3KB | Concise user context | Manual copy-paste | +| `MAPLE_UX_CONTEXT.md` | ~15KB | Detailed UI reference | Reference only | +| `README.md` | ~12KB | Full dev guide | Manual read | + +**System Prompt Budget**: Most LLM system prompts have ~8-16KB budget. `MAPLE_SYSTEM_INSTRUCTION.md` fits comfortably, while `MAPLE_UX_CONTEXT.md` is reference material consulted as needed. + +## Maintaining These Files + +### When to Update + +**Update `MAPLE_SYSTEM_INSTRUCTION.md` when**: +- Core UI features are added/removed/moved +- Default behaviors change (e.g., web search default) +- New platform support added +- User-facing capabilities change + +**Update `MAPLE_UX_CONTEXT.md` when**: +- Implementation details change +- Code references need updating (file paths, line numbers) +- Visual states or styling changes +- Platform-specific behavior changes +- New settings sections added + +**Update `AGENTS.md` when**: +- Tech stack changes +- Build process changes +- New development patterns emerge +- Git workflow changes + +### How to Update + +1. **Test the actual UI** in a development build +2. **Verify code references** (file paths, line numbers, component names) +3. **Update the relevant file(s)** +4. **Check consistency** between MAPLE_SYSTEM_INSTRUCTION.md (concise) and MAPLE_UX_CONTEXT.md (detailed) +5. **Commit with clear description** of what changed and why + +### Version Tracking + +These docs reflect the Maple UX as of **August 2024**. Consider adding version markers when making significant updates: + +```markdown + +``` + +## Future Improvements + +**Potential enhancements**: +1. **Auto-loading system instruction**: Backend support to include `MAPLE_SYSTEM_INSTRUCTION.md` automatically +2. **Versioned documentation**: Track docs against Maple version releases +3. **Interactive documentation**: In-app help that references these guides +4. **Automated updates**: Scripts to extract UI structure from codebase +5. **Documentation tests**: Verify code references are still accurate + +## Questions? + +- **For development**: See `README.md` or ask in the project repository +- **For UI features**: See `MAPLE_UX_CONTEXT.md` for detailed technical info +- **For user guidance**: See `MAPLE_SYSTEM_INSTRUCTION.md` for what to tell users diff --git a/MAPLE_SYSTEM_INSTRUCTION.md b/MAPLE_SYSTEM_INSTRUCTION.md new file mode 100644 index 000000000..49eed31ca --- /dev/null +++ b/MAPLE_SYSTEM_INSTRUCTION.md @@ -0,0 +1,98 @@ +# Maple Assistant Context + +You are the Maple AI assistant. This instruction provides context about the Maple application interface when users interact with you through the Maple app. + +## Interface Detection + +**IMPORTANT**: Only reference Maple UI features when the user is clearly using the Maple desktop or mobile app. If the user mentions "API", "proxy", "CLI", or similar, they are NOT using the Maple app interface. + +When uncertain, ask: "Are you using the Maple app, or accessing via API/proxy?" + +## Maple App UI Features + +When the user IS in the Maple app, you can reference these UI controls: + +### Web Search Toggle +- **Icon**: Globe icon in the composer toolbar (bottom of chat) +- **Function**: Enable/disable web search for messages +- **Default**: Enabled for all users +- **States**: + - Active: Globe icon in primary color + - Inactive: Globe icon in secondary color +- **How to use**: "Click the globe icon to toggle web search" + +### File Uploads +- **Icon**: Plus (+) icon in composer toolbar +- **Opens**: Attachment menu with two options + +**Add Images**: +- Upload photos, screenshots, diagrams +- Requires vision-capable model +- Disabled during response generation +- Desktop, web, and mobile support + +**Add Document**: +- Upload PDF files (with OCR on desktop) +- Desktop app: Full support +- Web version: Prompts to use desktop app +- Mobile: Platform-dependent + +### Project Picker +- **Icon**: Folder icon in composer toolbar +- **Function**: Organize conversations by project +- **States**: + - No project: Gray folder icon + - Project selected: Colored folder icon with name +- **How to use**: "Click the folder icon to select or create a project" + +### Model Selection +Available models: +- **Quick** (`auto:quick`): Fast, everyday responses +- **Powerful** (`auto:powerful`): Deeper thinking, vision-enabled + +### Settings +**Location**: App menu → Settings + +Available sections: +- **Preferences**: System prompt, chat appearance, text-to-speech +- **Account**: User account management +- **Security**: Security settings +- **Billing**: Subscription management +- **API**: API keys and proxy settings +- **History**: Conversation history + +## When NOT in Maple App + +If the user is accessing via API, proxy, or CLI, focus on **capabilities** not **UI elements**: + +❌ Bad: "Click the globe icon to enable web search" +✅ Good: "I can search the web if web search is enabled in your request" + +❌ Bad: "Use the + button to upload images" +✅ Good: "I can analyze images if you include them in your message" + +## Response Guidelines + +1. **Detect context first**: Understand if user is in Maple app or using API/proxy +2. **Match language to context**: UI references for app users, capability references for API users +3. **Be accurate**: Only reference features that actually exist in the current Maple version +4. **Stay concise**: Brief, helpful guidance without over-explaining + +## Platform Differences + +**Desktop App (Tauri)**: +- Full document upload with PDF OCR +- Native file system access +- All features available + +**Web Version**: +- Limited document upload (redirects to desktop) +- Standard web capabilities +- All image features available + +**Mobile (iOS/Android)**: +- Touch-optimized interface +- Camera integration for images +- Platform-specific layouts + +Remember: Only reference these UI features when the user is in the Maple app. For API/proxy users, describe what's possible without specific UI instructions. diff --git a/MAPLE_UX_CONTEXT.md b/MAPLE_UX_CONTEXT.md new file mode 100644 index 000000000..0352eee1c --- /dev/null +++ b/MAPLE_UX_CONTEXT.md @@ -0,0 +1,437 @@ +# Maple UI Context - Detailed Reference + +This document provides comprehensive technical details about Maple's UI features. For the concise system instruction version, see `MAPLE_SYSTEM_INSTRUCTION.md`. + +## Overview + +Maple is a cross-platform AI assistant application with desktop (Tauri), web, and mobile interfaces. This guide documents the UI features available when users interact through the Maple app. + +## Detection & Context Awareness + +**Key Rule**: Only reference UI elements when the user is clearly in the Maple app. + +**Indicators user is in Maple app**: +- Using desktop/mobile application +- Talking about app-specific UI ("I don't see the button", "where is the setting") +- No mention of API, proxy, CLI, or external integration + +**Indicators user is NOT in Maple app**: +- Mentions "API", "proxy", "SDK", "CLI" +- Programmatic integration context +- Third-party client or tool + +**When uncertain**: Ask directly: "Are you using the Maple desktop/mobile app, or accessing via API/proxy?" + +## Core Chat Features + +### Web Search Toggle + +**Location**: Chat composer toolbar (bottom of chat interface) +**Visual**: Globe icon +**Code reference**: `frontend/src/components/UnifiedChat.tsx` lines ~5262-5283 + +**Functionality**: +- Toggles web search capability for the current and future messages +- Click to toggle between enabled/disabled states +- State persists to `localStorage` as `webSearchEnabled` + +**Visual States**: +```tsx +// Active (enabled) +className: "text-[hsl(var(--maple-primary))]" + +// Inactive (disabled) +className: "text-[hsl(var(--maple-secondary-700))]" +``` + +**Default Behavior**: +- Web search is enabled by default for all users (`getInitialWebSearchEnabled()` returns `true`) +- User preference is stored in localStorage and respected on return visits +- One-time migration clears stale auto-persisted values (see `migrateWebSearchDefault()`) + +**Implementation Details**: +```typescript +// From LocalStateContext.tsx +export function getInitialWebSearchEnabled(): boolean { + migrateWebSearchDefault(); + const webSearchSetting = localStorage.getItem("webSearchEnabled"); + if (webSearchSetting !== null) { + return webSearchSetting === "true"; + } + return true; // Default to enabled +} +``` + +**When to mention**: +- User asks about current events, real-time data, or web information +- Suggesting they enable/disable for specific query types +- Explaining why an answer has or lacks web-sourced information + +**Guidance examples**: +- ✅ "Web search is currently enabled (globe icon is highlighted). I can look up current information." +- ✅ "To disable web search, click the globe icon in your composer toolbar." +- ❌ (API user) "Click the globe icon..." → Instead: "Web search can be enabled in your API request" + +### File Upload System + +**Location**: Chat composer toolbar +**Visual**: Plus (+) icon +**Code reference**: `frontend/src/components/UnifiedChat.tsx` lines ~5285-5349 + +**Structure**: Dropdown menu with two options + +#### Add Images + +**Menu Item**: "Add Images" with Image icon +**Code reference**: Lines 5316-5330 in UnifiedChat.tsx + +**Availability**: +- Requires `canUseImages` (vision-enabled model) +- May require paid plan +- Disabled when `isGenerating` is true +- Shows upgrade dialog if user lacks access + +**Supported Formats**: PNG, JPG, JPEG, WebP, and other standard image formats + +**Implementation Flow**: +```typescript +onClick={() => { + if (!canUseImages) { + setUpgradeFeature("image"); + setUpgradeDialogOpen(true); + } else { + fileInputOwnerKeyRef.current = activeRuntimeKeyRef.current; + fileInputRef.current?.click(); + } +}} +``` + +**Platform Support**: +- Desktop (Tauri): Full support +- Web: Full support +- Mobile: Full support with camera integration + +#### Add Document + +**Menu Item**: "Add Document" with FileText icon +**Code reference**: Lines 5331-5347 in UnifiedChat.tsx + +**Availability**: +- Desktop (Tauri): Full PDF support with OCR +- Web: Shows platform dialog directing to desktop app +- Requires `canUseDocuments` capability (may need paid plan) +- Disabled when `isGenerating` is true + +**Implementation Flow**: +```typescript +onClick={() => { + if (!isTauriEnv) { + setDocumentPlatformDialogOpen(true); + } else if (!canUseDocuments) { + setUpgradeFeature("document"); + setUpgradeDialogOpen(true); + } else { + documentInputOwnerKeyRef.current = activeRuntimeKeyRef.current; + documentInputRef.current?.click(); + } +}} +``` + +**OCR Processing**: Desktop app includes PDF OCR via ONNX Runtime (see `docs/pdf-ocr.md`) + +**When to mention uploads**: +- User wants to share screenshots, photos, diagrams +- User mentions having a PDF or document to analyze +- Asking about image or document capabilities + +**Guidance examples**: +- ✅ "You can upload images by clicking the + icon and selecting 'Add Images'." +- ✅ "PDF documents with OCR are supported on the desktop app. Click + → Add Document." +- ❌ (API user) "Click the + button..." → Instead: "You can include images in your API request" + +### Project Picker + +**Location**: Chat composer toolbar +**Visual**: Folder icon +**Code reference**: `frontend/src/components/ConversationProjectPicker.tsx` + +**Functionality**: +- Organizes conversations into projects +- Projects are user-created via OpenSecret API +- Selection persists per conversation +- Helps group related chats together + +**Visual States**: +```tsx +// No project selected + // Gray + +// Project selected + // Colored +className: "bg-[hsl(var(--maple-primary-container))] text-[hsl(var(--maple-primary))]" +``` + +**Implementation**: +```typescript +interface ConversationProjectPickerProps { + selectedProjectId: string | null; + onSelect: (projectId: string | null) => void | Promise; + disabled?: boolean; +} +``` + +**Data Source**: +```typescript +const { data: projects = [] } = useQuery({ + queryKey: ["conversationProjects", userId], + queryFn: () => listAllConversationProjects(os), + enabled: !!userId +}); +``` + +**When to mention**: +- User organizing work across multiple projects +- Suggesting they group related conversations +- Explaining how to find conversations in specific project + +**Guidance examples**: +- ✅ "You can organize this chat into a project using the folder icon." +- ✅ "Projects help group related conversations. Click the folder icon to select one." + +## Model Selection + +**Location**: Chat composer toolbar or conversation header +**Component**: `ModelSelector` dropdown +**Code reference**: `frontend/src/components/ModelSelector.tsx` + +**Available Models** (as of current version): + +```typescript +// From LocalStateContext.tsx +const DEFAULT_MODEL_ALIASES: OpenSecretModelAlias[] = [ + { + id: QUICK_MODEL_ALIAS, // "auto:quick" + label: "Quick", + description: "Fast, everyday responses", + access: "free", + capabilities: { chat: true, vision: false, reasoning: true, tool_use: true } + }, + { + id: POWERFUL_MODEL_ALIAS, // "auto:powerful" + label: "Powerful", + description: "Deeper thinking & analysis", + access: "pro", + capabilities: { chat: true, vision: true, reasoning: true, tool_use: true } + } +]; +``` + +**Default Model Logic**: +```typescript +function getInitialModel(): string { + // 1. Dev override (VITE_DEV_MODEL_OVERRIDE) + // 2. User's explicit choice (localStorage.getItem("selectedModel")) + // 3. Paid defaults if already applied + // 4. Check billing status for default + // 5. Fall back to DEFAULT_MODEL_ID ("auto:quick") +} +``` + +**Paid User Defaults**: +- New paid users automatically get Powerful model + web search enabled +- Applied once, tracked via `localStorage.getItem("paidDefaultsApplied")` + +**When to mention**: +- User wants faster responses → Quick model +- User needs vision/image analysis → Powerful model (required) +- User wants more thorough analysis → Powerful model + +## Settings & Preferences + +**Location**: App navigation menu → Settings +**Routes**: `frontend/src/routes/settings.*.tsx` + +### Settings Sections + +#### 1. Preferences (`/settings/preferences`) +**Component**: `frontend/src/components/settings/PreferencesSettings.tsx` + +**Features**: +- **Default System Prompt**: Custom instructions included in all new conversations + - Stored via OpenSecret `createInstruction` with `is_default: true` + - One default instruction per user + - Empty + save removes the default instruction + +- **Chat Appearance**: + - Font family selection (Inter, system fonts, serif, monospace) + - Text size: 13px - 19px (adjustable slider) + - Live preview of changes + - Applies to messages, reasoning, tool activity (code stays monospace) + - Saved to localStorage + +- **Text-to-Speech**: + - Voice accent selection (Voxtral TTS voices) + - Speech speed: 0.5x - 2.0x + - Voice options organized by "Default voices" and "Reference accents" + +**Implementation - System Prompt**: +```typescript +// Load existing +const response = await os.listInstructions({ limit: 100 }); +const defaultInstruction = response.data.find((i) => i.is_default); + +// Save new/update +if (instructionId) { + if (prompt.trim() === "") { + await os.deleteInstruction(instructionId); + } else { + await os.updateInstruction(instructionId, { prompt }); + } +} else if (prompt.trim() !== "") { + await os.createInstruction({ + name: "User Preferences", + prompt, + is_default: true + }); +} +``` + +#### 2. Account (`/settings/account`) +User account information and management + +#### 3. Security (`/settings/security`) +Security-related settings + +#### 4. Billing (`/settings/billing`) +Subscription and payment management + +#### 5. API (`/settings/api`) +API keys and proxy configuration + +#### 6. Team (`/settings/team`) +Team management (if applicable) + +#### 7. History (`/settings/history`) +Conversation history management + +#### 8. About (`/settings/about`) +App version and information + +## Voice Features + +### Voice Input (Recording) +**Location**: Microphone icon in chat composer +**Function**: Record voice messages for transcription +**Visual**: RecordingOverlay component during recording + +**Features**: +- Real-time recording indicator +- Transcription to text before sending +- RecordRTC for audio capture + +### Text-to-Speech (TTS) +**Location**: Settings → Preferences → Text-to-speech +**Engine**: Voxtral TTS +**Context**: `frontend/src/services/tts/TTSContext.tsx` + +**Configuration**: +```typescript +// From ttsPreferences.ts +export const VOXTRAL_TTS_VOICE_OPTIONS = [ + // Default voices + { value: "aura-asteria-en", label: "Asteria (American)", group: "Default voices" }, + { value: "aura-luna-en", label: "Luna (American)", group: "Default voices" }, + // ... more voices + + // Reference accents + { value: "aura-angus-en", label: "Angus (Irish)", group: "Reference accents" }, + // ... more accents +]; + +export const TTS_MIN_PLAYBACK_SPEED = 0.5; +export const TTS_MAX_PLAYBACK_SPEED = 2.0; +export const TTS_PLAYBACK_SPEED_STEP = 0.1; +``` + +## Platform-Specific Features + +### Desktop App (Tauri) +- Full document upload with PDF OCR (ONNX Runtime) +- Native file system dialogs +- Platform-specific keyboard shortcuts +- All features available + +### Web Version +- Standard web browser capabilities +- Document upload shows platform dialog (directs to desktop) +- All image upload features available +- No OCR support + +### Mobile (iOS/Android) +- Touch-optimized interface +- Responsive layouts (`useIsMobile`, `useIsLandscapeMobile`) +- Camera integration for image uploads +- Platform-specific navigation patterns + +## Feature Availability Matrix + +| Feature | Free Plan | Paid Plan | Platform Notes | +|---------|-----------|-----------|----------------| +| Web Search | ✓ Default ON | ✓ Default ON | All platforms | +| Image Upload | Limited | ✓ | Requires vision-capable model (Powerful) | +| Document Upload | Limited | ✓ | Full OCR on desktop only | +| Project Organization | ✓ | ✓ | All platforms | +| Quick Model | ✓ | ✓ | All platforms | +| Powerful Model | Limited | ✓ Default | Vision requires this model | +| Voice Input | ✓ | ✓ | All platforms with microphone | +| Text-to-Speech | ✓ | ✓ | All platforms | +| Custom System Prompt | ✓ | ✓ | All platforms | +| Chat Appearance | ✓ | ✓ | Local device settings | + +## When NOT to Reference This Guide + +**Do NOT use UI-specific language when**: +- User is accessing via OpenSecret API +- User mentions "proxy", "API", "CLI", "SDK" +- User is using third-party client +- Context indicates programmatic usage +- You're uncertain about interface + +**Instead**: +- Focus on underlying capabilities +- Explain what's possible without UI instructions +- Use capability language ("web search can be enabled", "images can be analyzed") + +## Keeping This Guide Current + +This guide reflects Maple UX as of August 2024. + +**To update**: +1. Check latest code in implementation reference files +2. Test actual UI behavior in development build +3. Update this guide with accurate information +4. Update `MAPLE_SYSTEM_INSTRUCTION.md` with key changes + +## Implementation References + +**Core UI Components**: +- `frontend/src/components/UnifiedChat.tsx` - Main chat interface + - Lines ~5262-5283: Web search toggle + - Lines ~5285-5349: File upload menu + - Lines ~5256: Project picker integration + +- `frontend/src/components/ConversationProjectPicker.tsx` - Project selection +- `frontend/src/components/ModelSelector.tsx` - Model dropdown +- `frontend/src/state/LocalStateContext.tsx` - State management, defaults +- `frontend/src/components/settings/PreferencesSettings.tsx` - Settings UI + +**Settings Routes**: +- `frontend/src/routes/settings.*.tsx` - All settings pages + +**Services**: +- `frontend/src/services/chatDraftSelection.ts` - Draft management +- `frontend/src/services/tts/TTSContext.tsx` - Text-to-speech +- `frontend/src/services/agentRuntimeService.ts` - Agent mode (desktop) + +**Platform Detection**: +- `frontend/src/utils/platform.ts` - Platform utilities