68 lines
3.6 KiB
Plaintext
68 lines
3.6 KiB
Plaintext
---
|
||
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.
|
||
|