chore: agents.md
This commit is contained in:
Simon
@@ -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,
|
||||
"cSpell.words": ["retryable"],
|
||||
"cSpell.words": ["opensource", "retryable"],
|
||||
"markdownlint.config": {
|
||||
// "comment": "Relaxed rules",
|
||||
"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
|
||||
|
||||
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
|
||||
@AGENTS.md
|
||||
|
||||
@@ -69,7 +69,7 @@ members of the project's leadership.
|
||||
|
||||
## 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
|
||||
|
||||
----
|
||||
|
||||
22
env.d.ts
vendored
22
env.d.ts
vendored
@@ -1,15 +1,6 @@
|
||||
/// <reference types="vite/client" />
|
||||
import type { PageAgent } from './src/PageAgent'
|
||||
|
||||
declare global {
|
||||
interface Window {
|
||||
pageAgent?: PageAgent
|
||||
PageAgent: typeof PageAgent
|
||||
|
||||
__PAGE_AGENT_IDS__: string[]
|
||||
}
|
||||
}
|
||||
|
||||
declare module '*.module.css' {
|
||||
const classes: Record<string, string>
|
||||
export default classes
|
||||
@@ -19,3 +10,16 @@ declare module '*.md?raw' {
|
||||
const content: string
|
||||
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