diff --git a/CLAUDE.md b/CLAUDE.md index b0d709c..c233fa5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,6 +12,7 @@ This is a dual-architecture project with **two separate parts**: ## Development Commands ### Core Commands + ```bash npm start # Start React website development server npm run build # Build both library AND website @@ -21,6 +22,7 @@ npm run lint # ESLint with TypeScript strict rules ``` ### Development Workflows + - **Library development**: Use `npm run build:lib:watch` while editing `src/` - **Website development**: Use `npm start` while editing `pages/` - **Testing library**: Inject `dist/lib/page-agent.umd.js` via script tag @@ -28,11 +30,13 @@ npm run lint # ESLint with TypeScript strict rules ## Architecture & Critical Patterns ### Dual Build System + - **Website build**: `vite.config.ts` → React SPA with hash routing → `dist/` - **Library build**: `vite.lib.config.ts` → UMD/ES modules → `dist/lib/` - **Entry points**: `src/entry.ts` (library), `pages/main.tsx` (website) ### Module Boundaries (Critical) + - **Core library** (`src/`): NEVER import from `pages/` - must remain pure JavaScript - **Website** (`pages/`): CAN import from `src/` via `@/` alias for demos - **Import aliases**: `@/` → `src/`, `@pages/` → `pages/` @@ -45,7 +49,9 @@ npm run lint # ESLint with TypeScript strict rules 4. **Indexed Operations**: Map LLM responses back to specific DOM elements ### Event Bus Communication + Use `src/utils/bus.ts` for decoupled PageAgent ↔ UI communication: + ```typescript // Emit from PageAgent getEventBus().emit('panel:show', undefined) @@ -56,21 +62,27 @@ getEventBus().on('panel:show', () => panel.show()) ``` ### Hash Routing Requirement + Uses wouter with `useHashLocation` for static hosting: + ```tsx // Always hash-based routes ``` ### CDN Auto-Injection Pattern + Library auto-initializes when injected via script tag: + ```html ``` + Query params configure `PageAgentConfig` automatically in `src/entry.ts`. ## File Organization ### Core Library (`src/`) + - `entry.ts` - CDN/UMD entry point with auto-initialization - `PageAgent.ts` - **Main AI agent class** orchestrating DOM operations - `tools/` - Agent tool implementations for web actions @@ -82,6 +94,7 @@ Query params configure `PageAgentConfig` automatically in `src/entry.ts`. - `config/` - Configuration constants and settings ### Website (`pages/`) + - `main.tsx` - Site entry with hash routing setup - `router.tsx` - **Manual route definitions** (requires explicit registration) - `components/DocsLayout.tsx` - Navigation structure (hardcoded nav items) @@ -91,16 +104,19 @@ Query params configure `PageAgentConfig` automatically in `src/entry.ts`. ## Adding New Features ### New Documentation Page + 1. Create `pages/docs/
//page.tsx` 2. Add route to `pages/router.tsx` with `
+ ` wrapper 3. Add navigation item to `DocsLayout.tsx` ### New Agent Tool + 1. Implement under `src/tools/` 2. Export via `src/tools/index.ts` 3. Wire into `PageAgent.ts` if needed ### New UI Component + 1. Create in `src/ui/` with colocated CSS modules 2. Use event bus for PageAgent communication 3. Test via `pages/test-pages/` @@ -108,17 +124,20 @@ Query params configure `PageAgentConfig` automatically in `src/entry.ts`. ## Code Standards ### TypeScript + - Strict mode enabled with `noUnusedLocals`/`noUnusedParameters` - Explicit typing for exported/public APIs - ESLint relaxes some unsafe rules for rapid iteration ### CSS & Styling + - **Prefer Tailwind CSS over custom CSS** - Custom CSS variables for theme gradients in `src/index.css` - Dark mode support via `dark:` classes - CSS modules for component-specific styles ### Import Organization + - External libraries first - Internal modules (`@/`, `@pages/`) - Relative imports last @@ -137,6 +156,7 @@ Query params configure `PageAgentConfig` automatically in `src/entry.ts`. ## Environment Variables Add new environment variables to `vite.config.ts` under `define`: + ```typescript define: { 'import.meta.env.YOUR_VAR': JSON.stringify(process.env.YOUR_VAR), @@ -146,13 +166,15 @@ define: { ## Debugging Common Issues ### Blank Documentation Pages + 1. Verify route exists in `pages/router.tsx` 2. Check component import path 3. Verify CSS isn't hiding content (check dark mode classes) 4. Test with minimal component first ### Library Integration Issues + 1. Check `dist/lib/page-agent.umd.js` builds correctly 2. Test CDN injection with query params 3. Verify event bus communications are properly typed -4. Use `pages/test-pages/` for isolated testing \ No newline at end of file +4. Use `pages/test-pages/` for isolated testing