chore: agents.md
This commit is contained in:
@@ -1,27 +0,0 @@
|
|||||||
---
|
|
||||||
globs: *.ts,*.tsx,*.js,*.cjs,*.mjs
|
|
||||||
description: Build, lint, and env guidance for this repo
|
|
||||||
---
|
|
||||||
### Build and env
|
|
||||||
|
|
||||||
- **Dev**: `npm run dev` starts Vite with base `./` and React SWC, Tailwind v4 plugin. Hash routing is required; use `useHashLocation`.
|
|
||||||
- **App build**: `npm run build` runs TypeScript build then Vite static build to `dist/` (site) and then `npm run build:lib`.
|
|
||||||
- **Library build**: `vite.lib.config.ts` builds UMD and ES to `dist/lib/` with entry `src/entry.ts`, file name `page-agent`.
|
|
||||||
- **Env injection**: `vite.config.ts` defines `import.meta.env.OPEN_ROUTER_*` from real env. When adding new env vars, add them under `define` in `vite.config.ts` and reference via `import.meta.env.*`.
|
|
||||||
- **Base path**: keep `base: './'` in both dev and build to make hash routing work under static hosting. If you change it, review `pages/main.tsx` URL logic.
|
|
||||||
|
|
||||||
### ESLint & TypeScript
|
|
||||||
|
|
||||||
- **Lint**: Config in `eslint.config.js` uses TypeScript ESLint with type‑aware rules, React plugins, and relaxed unsafe checks for rapid iteration. Run `npm run lint` or rely on lint‑staged.
|
|
||||||
- **TypeScript**: `tsconfig.app.json` is strict with `noEmit` and bundler resolution. Use `@/*` alias per config. Prefer explicit types on exported functions and public classes.
|
|
||||||
|
|
||||||
### Output hygiene
|
|
||||||
|
|
||||||
- Never commit changes under `dist/` manually. If you need to test CDN/UMD output locally, run library build and open `dist/index.html` or consume `dist/lib/page-agent.umd.cjs`.
|
|
||||||
- Do not import from `dist/` in source files. Always import from `src/`.
|
|
||||||
|
|
||||||
### Routing & deploy gotchas
|
|
||||||
|
|
||||||
- This site is SPA with hash routing. Ensure hosting serves `index.html` and does not rewrite hash routes.
|
|
||||||
- When embedding via CDN bookmarklet, the script is `dist/lib/page-agent.umd.cjs`. Query param `?model=` is parsed in `src/entry.ts`.
|
|
||||||
|
|
||||||
@@ -1,67 +0,0 @@
|
|||||||
---
|
|
||||||
alwaysApply: true
|
|
||||||
---
|
|
||||||
### Project structure and navigation map
|
|
||||||
|
|
||||||
- **Library entry (CDN/UMD)**: Public script entry is `src/entry.ts`. It attaches `PageAgent` to `window` and auto-initializes if injected via a `<script>` tag. Library build outputs to `dist/lib/` with file name `page-agent.*`.
|
|
||||||
|
|
||||||
- **Main Page entry**: `pages/main.tsx` mounts a `wouter` `Router` with `useHashLocation`. Routes delegate to:
|
|
||||||
- `pages/router.tsx` for docs/marketing pages
|
|
||||||
- `pages/test-pages/router.tsx` for internal test pages under `#/test-pages`
|
|
||||||
|
|
||||||
- **Docs layout**: Use `pages/components/DocsLayout.tsx` for all docs pages. When adding a new doc page, add it to:
|
|
||||||
- the navigation in `DocsLayout.tsx`, and
|
|
||||||
- the switch in `pages/router.tsx` with `<Header /> + <DocsLayout>...` wrapper
|
|
||||||
|
|
||||||
- **Hash routing**: Always use hash routes (e.g. `#/docs/...`). The `Router` is created as:
|
|
||||||
- `createRoot(...).render(<Router hook={useHashLocation}> ...)`
|
|
||||||
- Base URL in dev is `/`; otherwise computed relative to `index.html`. Do not change `vite.config.ts` base from `./` without updating `pages/main.tsx`.
|
|
||||||
|
|
||||||
- **Aliases**: Use `@/` as alias for `src/` and `@pages/` as alias for `pages/` (set in both Vite configs). Prefer absolute alias imports over deep relative chains.
|
|
||||||
|
|
||||||
- **Styling**: Tailwind v4 is enabled via `@tailwindcss/vite`. Use semantic utility classes; avoid ad‑hoc inline styles.
|
|
||||||
|
|
||||||
- **Do not edit generated files**: Never edit anything under `dist/`. Add sources under `src/` and let builds emit artifacts.
|
|
||||||
|
|
||||||
- **Event bus**: Type-safe event system for decoupling components, primarily used for PageAgent-UI communication.
|
|
||||||
|
|
||||||
### Conventions
|
|
||||||
|
|
||||||
- **Routing (wouter)**:
|
|
||||||
- Prefer `<Route path="/segment" component={Page} />` for simple pages; use children form when wrapping with layout.
|
|
||||||
- Keep 404 as the final catch‑all `Route` in `pages/router.tsx`.
|
|
||||||
- For test pages, mount under `#/test-pages` only.
|
|
||||||
|
|
||||||
- **Docs pages**: Place in `pages/docs/**/page.tsx`. Export a default React component. Pages are rendered inside `DocsLayout` and must be linked in the sidebar.
|
|
||||||
|
|
||||||
- **Typescript**:
|
|
||||||
- TS strict is enabled; however, ESLint relaxes many unsafe rules for DX. Keep exported/public APIs typed explicitly.
|
|
||||||
- JSX runtime is `react-jsx` (React 19).
|
|
||||||
|
|
||||||
- **Global objects**: The library exposes `window.PageAgent` and `window.pageAgent`. Guard re‑injection by disposing `window.pageAgent` before re‑creating, as done in `src/entry.ts`.
|
|
||||||
|
|
||||||
### Core modules (src/)
|
|
||||||
|
|
||||||
- **PageAgent.ts**: Core agent implementation and public API
|
|
||||||
- **entry.ts**: Library entry point for CDN/UMD usage
|
|
||||||
- **config/**: Configuration constants and settings management
|
|
||||||
- **tools/**: Agent tool implementations for web actions and page manipulation
|
|
||||||
- **ui/**: User interface components (Panel, SimulatorMask, etc.) for agent visualization
|
|
||||||
- **llms/**: LLM integration and communication layer
|
|
||||||
- **dom/**: HTML serialization, page analysis utilities, and DOM manipulation helpers
|
|
||||||
- **utils/**: Shared utilities including the type-safe event bus system
|
|
||||||
- **patches/**: Framework-specific optimizations and compatibility fixes (React, Antd, etc.)
|
|
||||||
- **prompts/**: System prompts and LLM instruction templates
|
|
||||||
- **i18n/**: Internationalization and language support
|
|
||||||
|
|
||||||
### Site structure (pages/)
|
|
||||||
|
|
||||||
- **pages/**: Documentation site and marketing pages
|
|
||||||
- **pages/test-pages/**: Demo pages for testing agent capabilities
|
|
||||||
|
|
||||||
### When adding features
|
|
||||||
|
|
||||||
- New docs page: create `pages/docs/<section>/<slug>/page.tsx`, add route and sidebar link.
|
|
||||||
- New tool: implement under `src/tools/`, export via `src/tools/index.ts`, wire into `PageAgent` if needed.
|
|
||||||
- Visual tweaks: edit under `src/ui/` and keep styles in colocated CSS modules.
|
|
||||||
|
|
||||||
214
.github/copilot-instructions.md
vendored
214
.github/copilot-instructions.md
vendored
@@ -1,214 +0,0 @@
|
|||||||
# page-agent AI Coding Instructions
|
|
||||||
|
|
||||||
## Project Overview
|
|
||||||
|
|
||||||
This project has **TWO SEPARATE PARTS**:
|
|
||||||
|
|
||||||
1. **Core Library** (`src/`) - Pure JavaScript AI agent library that can be injected into any webpage
|
|
||||||
2. **Marketing Website** (`pages/`) - React web app for landing page and documentation
|
|
||||||
|
|
||||||
## Architecture & Tech Stack
|
|
||||||
|
|
||||||
### Core Library (`src/`) - Pure JavaScript AI Agent
|
|
||||||
|
|
||||||
- **Technology**: Vanilla JavaScript/TypeScript (no React dependency)
|
|
||||||
- **Purpose**: AI agent with DOM automation capabilities
|
|
||||||
- **Output**: UMD/ES modules via `vite.lib.config.ts`
|
|
||||||
- **Key Features**: DOM processing, LLM integration, type-safe event bus
|
|
||||||
|
|
||||||
### Marketing Website (`pages/`) - React Web App
|
|
||||||
|
|
||||||
- **Technology**: React 19 + TypeScript + Wouter routing + Tailwind CSS v4
|
|
||||||
- **Purpose**: Landing page and documentation site
|
|
||||||
- **Output**: Static website via `vite.config.ts`
|
|
||||||
- **Usage**: Hosted documentation and demos
|
|
||||||
|
|
||||||
## Critical Development Workflows
|
|
||||||
|
|
||||||
### Dual Build System - Two Separate Projects
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm start # React website (pages/) development
|
|
||||||
npm run build # Build BOTH library AND website
|
|
||||||
npm run build:lib # Pure JS library only (src/ → dist/lib/)
|
|
||||||
npm run build:lib:watch # Library development with auto-rebuild
|
|
||||||
```
|
|
||||||
|
|
||||||
### Library Development (Pure JavaScript)
|
|
||||||
|
|
||||||
**Working on the core AI agent (`src/`):**
|
|
||||||
|
|
||||||
1. Edit pure JavaScript/TypeScript files in `src/`
|
|
||||||
2. Use `npm run build:lib:watch` for development
|
|
||||||
3. Test via CDN injection: `<script src="dist/lib/page-agent.umd.js"></script>`
|
|
||||||
4. No React dependencies allowed in `src/`
|
|
||||||
|
|
||||||
### Website Development (React)
|
|
||||||
|
|
||||||
**Working on marketing/docs (`pages/`):**
|
|
||||||
|
|
||||||
1. Use `npm start` for React development server
|
|
||||||
2. Can import from `src/` via `@/` alias to demo library features
|
|
||||||
3. Create test pages in `pages/test-pages/` to validate library integration
|
|
||||||
|
|
||||||
### DOM Pipeline
|
|
||||||
|
|
||||||
1. **DOM Extraction**: `src/dom/` converts live DOM to `FlatDomTree`
|
|
||||||
2. **Dehydration**: DOM tree → simplified text representation for LLM
|
|
||||||
3. **LLM Processing**: Send text to AI model for action planning
|
|
||||||
4. **Indexed Operations**: Map LLM responses back to specific DOM elements via indices
|
|
||||||
|
|
||||||
### Event Bus Communication
|
|
||||||
|
|
||||||
Use `src/utils/bus.ts` instead of prop drilling for PageAgent ↔ UI communication:
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// Emit events from PageAgent
|
|
||||||
getEventBus().emit('panel:show', undefined)
|
|
||||||
getEventBus().emit('panel:update', { status: 'thinking', message: 'Processing...' })
|
|
||||||
|
|
||||||
// Listen in UI components
|
|
||||||
getEventBus().on('panel:show', () => panel.show())
|
|
||||||
```
|
|
||||||
|
|
||||||
## Key Patterns & Conventions
|
|
||||||
|
|
||||||
### Strict Module Boundaries
|
|
||||||
|
|
||||||
- **Core library** (`src/`): Never import from `pages/` - must remain pure JavaScript
|
|
||||||
- **React website** (`pages/`): Can import from `src/` via `@/` alias to demo features
|
|
||||||
- **Entry points**: `src/entry.ts` (CDN/UMD), `pages/main.tsx` (React website)
|
|
||||||
|
|
||||||
### Manual Route Registration Pattern
|
|
||||||
|
|
||||||
Routes in `pages/router.tsx` require explicit definition:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
<Route path="/docs/features/dom-operations">
|
|
||||||
<div className="min-h-screen bg-white dark:bg-gray-900">
|
|
||||||
<Header />
|
|
||||||
<DocsLayout>
|
|
||||||
<DomOperations />
|
|
||||||
</DocsLayout>
|
|
||||||
</div>
|
|
||||||
</Route>
|
|
||||||
```
|
|
||||||
|
|
||||||
**Adding new docs pages**: 1) Add route to `router.tsx`, 2) Add nav item to `DocsLayout.tsx`
|
|
||||||
|
|
||||||
### Hash Routing Requirement
|
|
||||||
|
|
||||||
Uses wouter with `useHashLocation` for static hosting compatibility:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
<Router hook={useHashLocation}> // Always hash-based routes
|
|
||||||
```
|
|
||||||
|
|
||||||
### CDN Auto-Injection Pattern
|
|
||||||
|
|
||||||
Library auto-initializes when injected via script tag:
|
|
||||||
|
|
||||||
```html
|
|
||||||
<script src="page-agent.js?model=gpt-4"></script>
|
|
||||||
```
|
|
||||||
|
|
||||||
Query params configure `PageAgentConfig` automatically.
|
|
||||||
|
|
||||||
### CSS & Design System
|
|
||||||
|
|
||||||
- **Prefer Tailwind CSS over custom CSS** - Use utility classes for styling
|
|
||||||
- Custom CSS variables in `src/index.css` define theme gradients:
|
|
||||||
```css
|
|
||||||
--theme-color-1: rgb(88, 192, 252);
|
|
||||||
--theme-color-2: rgb(189, 69, 251);
|
|
||||||
```
|
|
||||||
- Design follows modern SaaS aesthetic with blue/purple gradients
|
|
||||||
- **Accessibility**: Ensure proper contrast ratios, semantic HTML, ARIA labels
|
|
||||||
- Dark mode support throughout via Tailwind `dark:` classes
|
|
||||||
- Responsive grid layouts for features and content sections
|
|
||||||
|
|
||||||
## File Organization
|
|
||||||
|
|
||||||
### Core Library (`src/`)
|
|
||||||
|
|
||||||
- **PageAgent.ts**: Core agent implementation and public API
|
|
||||||
- **entry.ts**: Library entry point for CDN/UMD usage
|
|
||||||
- **config/**: Configuration constants and settings management
|
|
||||||
- **tools/**: Agent tool implementations for web actions and page manipulation
|
|
||||||
- **ui/**: User interface components (Panel, SimulatorMask, etc.) for agent visualization
|
|
||||||
- **llms/**: LLM integration and communication layer
|
|
||||||
- **dom/**: HTML serialization, page analysis utilities, and DOM manipulation helpers
|
|
||||||
- **utils/**: Shared utilities including the type-safe event bus system
|
|
||||||
- **patches/**: Framework-specific optimizations and compatibility fixes (React, Antd, etc.)
|
|
||||||
- **prompts/**: System prompts and LLM instruction templates
|
|
||||||
- **i18n/**: Internationalization and language support
|
|
||||||
|
|
||||||
### Documentation Site (`pages/`)
|
|
||||||
|
|
||||||
- `main.tsx` - Site entry point with hash routing setup
|
|
||||||
- `router.tsx` - Manual route definitions (requires explicit registration)
|
|
||||||
- `components/DocsLayout.tsx` - Navigation structure (hardcoded nav items)
|
|
||||||
- `docs/[section]/[topic]/page.tsx` - Documentation pages
|
|
||||||
- `test-pages/` - Library integration test pages
|
|
||||||
|
|
||||||
## Development Workflow
|
|
||||||
|
|
||||||
### Commands
|
|
||||||
|
|
||||||
- `npm start` - Development server (Vite)
|
|
||||||
- `npm run build` - Production build (TypeScript check + Vite build)
|
|
||||||
- `npm run lint` - ESLint with strict TypeScript rules
|
|
||||||
|
|
||||||
### Debugging Routing Issues
|
|
||||||
|
|
||||||
**Common problem**: Blank pages in docs sections. Debug steps:
|
|
||||||
|
|
||||||
1. Verify route exists in `pages/router.tsx`
|
|
||||||
2. Check component import path
|
|
||||||
3. Test with minimal component first
|
|
||||||
4. Verify CSS isn't hiding content (check dark mode classes)
|
|
||||||
|
|
||||||
### TypeScript Configuration
|
|
||||||
|
|
||||||
- Strict mode enabled with `noUnusedLocals` and `noUnusedParameters`
|
|
||||||
- Path alias `@/*` maps to `src/*`
|
|
||||||
- ESLint uses strict TypeScript rules but disables some for pragmatism:
|
|
||||||
```js
|
|
||||||
'@typescript-eslint/no-non-null-assertion': 'off'
|
|
||||||
'@typescript-eslint/no-unsafe-assignment': 'off'
|
|
||||||
```
|
|
||||||
|
|
||||||
## Content & Messaging
|
|
||||||
|
|
||||||
- **Tone**: Technical but approachable, targeting web developers
|
|
||||||
- **Core value prop**: "一行 CDN 引入,为任何网站添加智能 UI Agent"
|
|
||||||
- **Differentiator**: Page-embedded vs external automation (vs browser-use)
|
|
||||||
- Feature categories: DOM operations, security, data masking, knowledge injection, model integration
|
|
||||||
|
|
||||||
## Code Quality Standards
|
|
||||||
|
|
||||||
- Use TypeScript strict mode
|
|
||||||
- Prefer functional components with hooks
|
|
||||||
- **Prefer Tailwind CSS over custom CSS** - Use utility classes for styling
|
|
||||||
- Consistent file naming: kebab-case for multi-word files
|
|
||||||
- Import organization: React imports first, then components, then styles
|
|
||||||
|
|
||||||
## Critical Files to Understand
|
|
||||||
|
|
||||||
- `pages/router.tsx` - Central routing definition
|
|
||||||
- `pages/components/DocsLayout.tsx` - Navigation structure
|
|
||||||
- `pages/page.tsx` - Homepage showcasing product features
|
|
||||||
- `src/PageAgent.ts` - **Core library**: AI agent class with DOM manipulation
|
|
||||||
- `src/dom/dom_tree/index.js` - **DOM extraction engine** (ported from Python)
|
|
||||||
- `src/utils/bus.ts` - **Type-safe event bus** for decoupled communication
|
|
||||||
- `src/entry.ts` - CDN/UMD entry point with auto-initialization
|
|
||||||
- `vite.config.ts` and `vite.lib.config.ts` - Dual build configuration
|
|
||||||
- `tsconfig.app.json` - TypeScript strictness settings
|
|
||||||
|
|
||||||
## Core Library Architecture
|
|
||||||
|
|
||||||
The core library (`src/`) is a standalone AI agent with these key components:
|
|
||||||
|
|
||||||
- **PageAgent.ts**: Main agent class managing DOM tree updates, element highlighting, and LLM communication
|
|
||||||
- **DOM processing pipeline**: Converts complex web pages into LLM-friendly text while preserving interactive element mappings for precise actions
|
|
||||||
- **Event bus system**: Type-safe communication between PageAgent and UI components
|
|
||||||
2
.vscode/settings.json
vendored
2
.vscode/settings.json
vendored
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"editor.fontLigatures": true,
|
"editor.fontLigatures": true,
|
||||||
"cSpell.words": ["retryable"],
|
"cSpell.words": ["opensource", "retryable"],
|
||||||
"markdownlint.config": {
|
"markdownlint.config": {
|
||||||
// "comment": "Relaxed rules",
|
// "comment": "Relaxed rules",
|
||||||
"default": true,
|
"default": true,
|
||||||
|
|||||||
161
AGENTS.md
Normal file
161
AGENTS.md
Normal file
@@ -0,0 +1,161 @@
|
|||||||
|
# Instructions for coding assistants
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
This is a dual-architecture project with **two separate parts**:
|
||||||
|
|
||||||
|
1. **Core Library** (`src/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation
|
||||||
|
2. **Demo&docs Website** (`pages/`) - React documentation and landing page
|
||||||
|
|
||||||
|
## Development Commands
|
||||||
|
|
||||||
|
### Core Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm start # Start React website development server
|
||||||
|
npm run build # Build both library AND website
|
||||||
|
npm run build:lib # Build pure JS library only (src/ → dist/lib/)
|
||||||
|
npm run build:lib:watch # Library development with auto-rebuild
|
||||||
|
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/`
|
||||||
|
|
||||||
|
### DOM Pipeline
|
||||||
|
|
||||||
|
1. **DOM Extraction**: Convert live DOM to `FlatDomTree` via `src/dom/dom_tree/`
|
||||||
|
2. **Dehydration**: DOM tree → simplified text for LLM processing
|
||||||
|
3. **LLM Processing**: AI model returns action plans
|
||||||
|
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')
|
||||||
|
getEventBus().emit('panel:update', { status: 'thinking' })
|
||||||
|
|
||||||
|
// Listen in UI components
|
||||||
|
getEventBus().on('panel:show', () => panel.show())
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hash Routing Requirement
|
||||||
|
|
||||||
|
Uses wouter with `useHashLocation` for static hosting:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Router hook={useHashLocation}> // Always hash-based routes
|
||||||
|
```
|
||||||
|
|
||||||
|
### CDN Auto-Injection Pattern
|
||||||
|
|
||||||
|
Library auto-initializes when injected via script tag:
|
||||||
|
|
||||||
|
```html
|
||||||
|
<script src="page-agent.js?model=gpt-4"></script>
|
||||||
|
```
|
||||||
|
|
||||||
|
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
|
||||||
|
- `ui/` - UI components (Panel, SimulatorMask) with CSS modules
|
||||||
|
- `utils/bus.ts` - **Type-safe event bus** for decoupled communication
|
||||||
|
- `patches/` - Framework-specific optimizations (React, Antd compatibility)
|
||||||
|
- `llms/` - LLM integration and communication layer
|
||||||
|
- `dom/` - HTML serialization and page analysis utilities
|
||||||
|
- `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)
|
||||||
|
- `docs/[section]/[topic]/page.tsx` - Documentation pages
|
||||||
|
- `test-pages/` - Library integration test pages
|
||||||
|
|
||||||
|
## Adding New Features
|
||||||
|
|
||||||
|
### New Documentation Page
|
||||||
|
|
||||||
|
1. Create `pages/docs/<section>/<slug>/page.tsx`
|
||||||
|
2. Add route to `pages/router.tsx` with `<Header /> + <DocsLayout>` 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/`
|
||||||
|
|
||||||
|
## Code Standards
|
||||||
|
|
||||||
|
### TypeScript
|
||||||
|
|
||||||
|
- 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
|
||||||
|
- Blank lines between groups
|
||||||
|
|
||||||
|
## Critical Files to Understand
|
||||||
|
|
||||||
|
- `pages/router.tsx` - Central routing definition (manual registration required)
|
||||||
|
- `pages/components/DocsLayout.tsx` - Navigation structure
|
||||||
|
- `src/PageAgent.ts` - Core AI agent class with DOM manipulation
|
||||||
|
- `src/dom/dom_tree/index.js` - DOM extraction engine
|
||||||
|
- `src/utils/bus.ts` - Type-safe event bus system
|
||||||
|
- `src/entry.ts` - Library entry point for CDN usage
|
||||||
|
- `vite.config.ts` / `vite.lib.config.ts` - Dual build configuration
|
||||||
|
|
||||||
|
## 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
|
||||||
181
CLAUDE.md
181
CLAUDE.md
@@ -1,180 +1 @@
|
|||||||
# CLAUDE.md
|
@AGENTS.md
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
||||||
|
|
||||||
## Project Overview
|
|
||||||
|
|
||||||
This is a dual-architecture project with **two separate parts**:
|
|
||||||
|
|
||||||
1. **Core Library** (`src/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation
|
|
||||||
2. **Marketing Website** (`pages/`) - React documentation and landing page
|
|
||||||
|
|
||||||
## Development Commands
|
|
||||||
|
|
||||||
### Core Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm start # Start React website development server
|
|
||||||
npm run build # Build both library AND website
|
|
||||||
npm run build:lib # Build pure JS library only (src/ → dist/lib/)
|
|
||||||
npm run build:lib:watch # Library development with auto-rebuild
|
|
||||||
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
|
|
||||||
|
|
||||||
## 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/`
|
|
||||||
|
|
||||||
### DOM Pipeline
|
|
||||||
|
|
||||||
1. **DOM Extraction**: Convert live DOM to `FlatDomTree` via `src/dom/dom_tree/`
|
|
||||||
2. **Dehydration**: DOM tree → simplified text for LLM processing
|
|
||||||
3. **LLM Processing**: AI model returns action plans
|
|
||||||
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)
|
|
||||||
getEventBus().emit('panel:update', { status: 'thinking' })
|
|
||||||
|
|
||||||
// Listen in UI components
|
|
||||||
getEventBus().on('panel:show', () => panel.show())
|
|
||||||
```
|
|
||||||
|
|
||||||
### Hash Routing Requirement
|
|
||||||
|
|
||||||
Uses wouter with `useHashLocation` for static hosting:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
<Router hook={useHashLocation}> // Always hash-based routes
|
|
||||||
```
|
|
||||||
|
|
||||||
### CDN Auto-Injection Pattern
|
|
||||||
|
|
||||||
Library auto-initializes when injected via script tag:
|
|
||||||
|
|
||||||
```html
|
|
||||||
<script src="page-agent.js?model=gpt-4"></script>
|
|
||||||
```
|
|
||||||
|
|
||||||
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
|
|
||||||
- `ui/` - UI components (Panel, SimulatorMask) with CSS modules
|
|
||||||
- `utils/bus.ts` - **Type-safe event bus** for decoupled communication
|
|
||||||
- `patches/` - Framework-specific optimizations (React, Antd compatibility)
|
|
||||||
- `llms/` - LLM integration and communication layer
|
|
||||||
- `dom/` - HTML serialization and page analysis utilities
|
|
||||||
- `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)
|
|
||||||
- `docs/[section]/[topic]/page.tsx` - Documentation pages
|
|
||||||
- `test-pages/` - Library integration test pages
|
|
||||||
|
|
||||||
## Adding New Features
|
|
||||||
|
|
||||||
### New Documentation Page
|
|
||||||
|
|
||||||
1. Create `pages/docs/<section>/<slug>/page.tsx`
|
|
||||||
2. Add route to `pages/router.tsx` with `<Header /> + <DocsLayout>` 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/`
|
|
||||||
|
|
||||||
## 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
|
|
||||||
- Blank lines between groups
|
|
||||||
|
|
||||||
## Critical Files to Understand
|
|
||||||
|
|
||||||
- `pages/router.tsx` - Central routing definition (manual registration required)
|
|
||||||
- `pages/components/DocsLayout.tsx` - Navigation structure
|
|
||||||
- `src/PageAgent.ts` - Core AI agent class with DOM manipulation
|
|
||||||
- `src/dom/dom_tree/index.js` - DOM extraction engine
|
|
||||||
- `src/utils/bus.ts` - Type-safe event bus system
|
|
||||||
- `src/entry.ts` - Library entry point for CDN usage
|
|
||||||
- `vite.config.ts` / `vite.lib.config.ts` - Dual build configuration
|
|
||||||
|
|
||||||
## 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),
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|||||||
@@ -69,7 +69,7 @@ members of the project's leadership.
|
|||||||
|
|
||||||
## Attribution
|
## Attribution
|
||||||
|
|
||||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
|
This Code of Conduct is adapted from the [Contributor Covenant][https://www.contributor-covenant.org], version 1.4,
|
||||||
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
|
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
|
||||||
|
|
||||||
----
|
----
|
||||||
|
|||||||
22
env.d.ts
vendored
22
env.d.ts
vendored
@@ -1,15 +1,6 @@
|
|||||||
/// <reference types="vite/client" />
|
/// <reference types="vite/client" />
|
||||||
import type { PageAgent } from './src/PageAgent'
|
import type { PageAgent } from './src/PageAgent'
|
||||||
|
|
||||||
declare global {
|
|
||||||
interface Window {
|
|
||||||
pageAgent?: PageAgent
|
|
||||||
PageAgent: typeof PageAgent
|
|
||||||
|
|
||||||
__PAGE_AGENT_IDS__: string[]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
declare module '*.module.css' {
|
declare module '*.module.css' {
|
||||||
const classes: Record<string, string>
|
const classes: Record<string, string>
|
||||||
export default classes
|
export default classes
|
||||||
@@ -19,3 +10,16 @@ declare module '*.md?raw' {
|
|||||||
const content: string
|
const content: string
|
||||||
export default content
|
export default content
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* for local dev and umd demo
|
||||||
|
*/
|
||||||
|
|
||||||
|
declare global {
|
||||||
|
interface Window {
|
||||||
|
pageAgent?: PageAgent
|
||||||
|
PageAgent: typeof PageAgent
|
||||||
|
|
||||||
|
__PAGE_AGENT_IDS__: string[]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user