| # CLAUDE.md | |
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | |
| ## Project Overview | |
| This is a Svelte 5 + TypeScript + Vite single-page application for a discovery-based creature collection game called "Pictuary". It uses the latest Svelte 5 with runes syntax (`$state()`, `$derived()`, etc.). | |
| ### Main Features | |
| - **Monster Discovery**: Upload images → AI identifies objects and generates/retrieves canonical "Piclets" | |
| - **Canonical System**: Each real-world object has ONE canonical Piclet, with variations tracked | |
| - **Collection Management**: Track discovered Piclets with metadata (discoverer, rarity, variations) | |
| - **Activity Feed**: Leaderboard showing top discoverers and recent finds | |
| - **Server Integration**: Connects to `../piclets-server/` for canonical Piclet database | |
| ## Essential Commands | |
| ```bash | |
| # Install dependencies | |
| npm install | |
| # Development server with HMR | |
| npm run dev | |
| # Type checking | |
| npm run check | |
| # Production build (outputs to dist/) | |
| npm run build | |
| # Preview production build | |
| npm run preview | |
| # Run tests | |
| npm test | |
| # Run tests with UI | |
| npm run test:ui | |
| ``` | |
| ## Architecture | |
| ### Component Structure | |
| - Components use `.svelte` files with TypeScript support via `lang="ts"` in script tags | |
| - Main entry: `src/main.ts` → mounts `src/App.svelte` | |
| - Reusable components go in `src/lib/` | |
| - Uses Svelte 5 runes syntax (not Svelte 4 syntax) | |
| ### Key Components | |
| - **Pages**: `Scanner.svelte` (discovery), `Pictuary.svelte` (collection), `Activity.svelte` (leaderboard/feed) | |
| - **Monster Discovery**: `PicletGenerator.svelte`, `PicletResult.svelte` with canonical/variation detection | |
| - **Server Integration**: Services for canonical Piclet lookup and creation | |
| - **Piclet Management**: `PicletCard.svelte`, `PicletDetail.svelte` with discovery metadata | |
| - **Database**: IndexedDB with `schema.ts` for local caching + server sync for canonical data | |
| ### Key Patterns | |
| 1. **State Management**: Use `$state()` rune for reactive state | |
| 2. **TypeScript**: All components should use `<script lang="ts">` | |
| 3. **Imports**: Use ES module imports, components are default exports | |
| 4. **Styling**: Component styles are scoped by default, global styles in `src/app.css` | |
| 5. **Database**: Hybrid approach - IndexedDB for local state, server API for canonical Piclets | |
| 6. **Discovery Flow**: Caption → Extract object → Server lookup → Return canonical/variation/new | |
| ### Build Configuration | |
| - Vite handles bundling with `vite.config.ts` | |
| - TypeScript config uses project references (tsconfig.json + tsconfig.app.json) | |
| - Production builds go to `dist/` directory | |
| ## External Dependencies | |
| ### Gradio Client Integration | |
| This project uses Gradio Client for connecting to Hugging Face Spaces. **Important**: Use the CDN-based approach, not npm packages. | |
| **Setup in App.svelte:** | |
| ```javascript | |
| // CDN imports are loaded dynamically | |
| import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js"; | |
| window.gradioClient = { Client }; | |
| ``` | |
| **Usage in other files:** | |
| ```typescript | |
| // Access via window.gradioClient (types are declared in vite-env.d.ts) | |
| const client = await window.gradioClient.Client.connect("space-name"); | |
| ``` | |
| **Current Gradio Connections:** | |
| - **Flux Image Generation**: `Fraser/flux` | |
| - **Joy Caption**: `fancyfeast/joy-caption-alpha-two` (configured for object identification) | |
| - **Qwen Text Generation**: For generating Piclet concepts from object captions | |
| ### Server Integration | |
| - **Endpoint**: `../piclets-server/` (local development) | |
| - **Canonical Lookup**: POST `/api/piclets/search` with object keywords | |
| - **Create Canonical**: POST `/api/piclets/canonical` for new discoveries | |
| - **Create Variation**: POST `/api/piclets/variation` with canonicalId | |
| - **Activity Feed**: GET `/api/activity/recent` for global discoveries | |
| **Build Notes:** | |
| - DO NOT install Gradio Client via npm (`npm install @gradio/client`) - it causes build failures | |
| - The CDN approach ensures compatibility with Vite bundling | |
| - All Gradio connections should use the established pattern from App.svelte | |
| ### Discovery Architecture | |
| #### Object Identification Flow | |
| 1. **Image Caption**: Joy Caption extracts object type and visual attributes | |
| 2. **Object Extraction**: Parse caption for primary object ("pillow", "pyramid", etc.) | |
| 3. **Server Lookup**: Search for exact match or close variations | |
| 4. **Response Types**: | |
| - **Exact Match**: Return existing canonical Piclet + increment scan count | |
| - **Close Match**: Create variation of canonical + link to parent | |
| - **No Match**: Create new canonical Piclet + register discoverer | |
| #### Rarity Calculation | |
| - Track `scanCount` per canonical Piclet | |
| - Rarity score = 1 / scanCount (lower scan count = higher rarity) | |
| - Display rarity tiers: Common, Uncommon, Rare, Epic, Legendary | |
| ## Troubleshooting | |
| ### Common Build Issues | |
| - **Gradio Client build failures**: Ensure you're NOT using `npm install @gradio/client`. Use CDN imports only. | |
| - **Type errors**: Run `npm run check` to identify TypeScript issues before building | |
| - **Missing dependencies**: Run `npm install` if packages are missing | |
| ### Discovery System Issues | |
| - **Object extraction**: Ensure Joy Caption is set to "Descriptive" mode with focus on object type | |
| - **Server connection**: Verify `../piclets-server/` is running on expected port | |
| - **Variation detection**: Check keyword matching algorithm for false positives | |
| - **Rarity calculation**: Ensure scanCount is properly incremented on each discovery | |
| ### Performance | |
| - **Large image files**: Consider image compression before upload | |
| - **Server latency**: Cache canonical Piclets locally after first fetch | |
| - **Search optimization**: Use keyword indexing for O(1) lookups | |
| - **Activity feed**: Paginate results, cache recent discoveries | |
| ## Implementation Strategy | |
| ### Caption Processing | |
| ```typescript | |
| // Example caption processing for object extraction | |
| const caption = "A velvet blue pillow with golden tassels on a couch"; | |
| const primaryObject = extractObject(caption); // "pillow" | |
| const attributes = extractAttributes(caption); // ["velvet", "blue"] | |
| ``` | |
| ### Server Communication | |
| ```typescript | |
| // Canonical lookup | |
| const result = await fetch('/api/piclets/search', { | |
| method: 'POST', | |
| body: JSON.stringify({ | |
| object: 'pillow', | |
| attributes: ['velvet', 'blue'] | |
| }) | |
| }); | |
| // Response types | |
| interface CanonicalMatch { | |
| type: 'exact' | 'variation' | 'new'; | |
| piclet: PicletInstance; | |
| canonicalId?: string; | |
| discoveredBy?: string; | |
| scanCount: number; | |
| } | |
| ``` | |
| ### Database Schema Updates | |
| - Remove: level, xp, hp, attack, defense, speed, moves, battleStats | |
| - Add: canonicalId, isCanonical, discoveredBy, discoveredAt, scanCount, variations[] | |
| - Keep: typeId, primaryType, tier, imageUrl, description, concept | |
| ## Important Notes | |
| - This is NOT SvelteKit - no routing, SSR, or API routes | |
| - HMR preserves component state (can be toggled in vite.config.ts) | |
| - All paths in imports should be relative or use `$lib` alias for src/lib | |
| - Hybrid storage: IndexedDB for local cache, server for canonical truth | |
| - Object abstraction level is critical - "pillow" not "decorative cushion" | |
| - Variations limited to 2-3 meaningful attributes (material, style, color) |