feat: init

.cursor/rules/infra-build.mdc

@@ -0,0 +1,27 @@
+---
+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`.
+

.cursor/rules/project-structure.mdc

@@ -0,0 +1,67 @@
+---
+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.
+