feat!: local iife testing

BREAKING CHANGES: remove umd build from npm package and cdn

CONTRIBUTING.md

@@ -14,7 +14,7 @@ Thank you for your interest in contributing to Page-Agent! We welcome contributi
 2. **Setup**
 
    ```bash
-   npm install
+   npm ci
    npm start          # Start demo and documentation site
    ```
 
@@ -29,7 +29,7 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference
 
 - When developing. Use alias so that we don't have to pre-build.
 - When bundling. Use external and disable ts `paths` alias to leave deps out.
-- When bundling `UMD` and `Website`. Bundle everything including local packages.
+- When bundling `IIFE` and `Website`. Bundle everything including local packages.
 
 ## 🤝 How to Contribute
 
@@ -61,10 +61,9 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference
    - Update documentation as needed
 
 4. **Test Your Changes**
-
+   - Test in our demo website
-   ```bash
+   - Test it on other websites if applicable
-   # TODO
+   - `@TODO: test suite`
-   ```
 
 5. **Commit and Push**
 
@@ -94,41 +93,52 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference
 - It's **recommended** to heavily rely on AI (aka "vibe coding") when maintaining **demo pages and tests**.
 - BUT **NOT the core lib!!!** Be very careful if AI ever touched the core lib!!!
 - Review anything AI wrote before make a commit. You are the author of anything you commit. NOT AI.
-- Update the AI instructions when structure changed.
+- Update the [AI instructions](AGENTS.md) when structure changed.
-   - Cursor and Cline: `./.cursor/rules`
-   - Github Copilot: `./.github/copilot-instructions.md`
-   - Claude Code: `./CLAUDE.md`
 
 ## 🔧 Development Workflows
 
+### Test With Your Own LLM API
+
+- Create a `.env` file in the repo root with your LLM API config
+
+  ```env
+  LLM_MODEL_NAME=gpt-5.2
+  LLM_API_KEY=your-api-key
+  LLM_BASE_URL=https://api.your-llm-provider.com/v1
+  ```
+
+- Restart the dev server to load new env vars
+- If not provided, the demo will the free testing proxy by default
+
 ### Website Development
 
 ```bash
-npm start                # React development server
+npm start
 ```
 
-### Core Lib Development and Testing
+### Testing on Other Websites
 
-> @TODO this part is outdated. Update this.
+- Start and serve a local `iife` script
 
-- Config your LLM API
+  ```bash
-- Start and serve a local umd script
+  npm run dev:iife # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.js
+  ```
 
-   ```bash
+- Add a new bookmark
-   npm run dev:umd # Serving UMD with auto rebuild at http://localhost:5173/page-agent.umd.cjs
-   ```
 
-- Add a new bookmark enable it on other website
+  ```javascript
+  javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
+  ```
 
-   ```
+- Click the bookmark on any page to load Page-Agent
-   javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5173/page-agent.umd.cjs?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
+
-   ```
+> Warning: AK in your local `.env` will be inlined in the iife script.
 
 ### Adding Documentation
 
-1. Create `website/src/docs/section/page-name/page.tsx`
+Ask an AI to help you add documentation to the `website/` package. Follow the existing style.
-2. Add route to `website/src/router.tsx`
+
-3. Add navigation link to `website/src/components/DocsLayout.tsx`
+> Our AGENTS.md file and guardrails are designed for this purpose. But please be careful and review anything AI generated.
 
 ## 🎯 Contribution Areas
 
@@ -143,7 +153,7 @@ We especially welcome contributions in:
 
 ## 🚫 What We Don't Accept
 
-- Changes that break existing API compatibility
+- Changes that break existing API compatibility (Discuss first)
 - Heavy dependencies to core library
 - Contributions without proper testing
 - Code that doesn't follow project conventions

LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2025 Alibaba
+Copyright (c) 2026 Alibaba
+Copyright (c) 2026 Simon
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package.json

@@ -29,7 +29,7 @@
 		"build:website": "npm run build:website --workspace=@page-agent/website",
 		"build:libs": "npm run build --workspaces --if-present",
 		"build": "npm run build:libs && npm run build:website",
-		"dev:umd": "npm run dev:umd --workspace=page-agent",
+		"dev:iife": "npm run dev:iife --workspace=page-agent",
 		"version": "node scripts/sync-version.js",
 		"lint": "eslint .",
 		"prepare": "husky"

packages/page-agent/package.json

@@ -37,9 +37,8 @@
 	},
 	"homepage": "https://alibaba.github.io/page-agent/",
 	"scripts": {
-		"build": "vite build && vite build --config vite.umd.config.js",
+		"build": "vite build",
-		"serve": "npx serve dist/umd -p 5173",
+		"dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
-		"dev:umd": "concurrently \"vite build --config vite.umd.config.js --watch\" \"npm run serve\"",
 		"prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
 		"postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
 	},

packages/page-agent/src/iife.ts

@@ -36,9 +36,13 @@ setTimeout(() => {
 	} else {
 		console.log('🚀 page-agent.js no current script detected, using default demo config')
 		const config: PageAgentConfig = {
-			model: DEMO_MODEL,
+			// model: DEMO_MODEL,
-			baseURL: DEMO_BASE_URL,
+			// baseURL: DEMO_BASE_URL,
-			apiKey: DEMO_API_KEY,
+			// apiKey: DEMO_API_KEY,
+
+			model: import.meta.env.LLM_MODEL_NAME ? import.meta.env.LLM_MODEL_NAME : DEMO_MODEL,
+			baseURL: import.meta.env.LLM_BASE_URL ? import.meta.env.LLM_BASE_URL : DEMO_BASE_URL,
+			apiKey: import.meta.env.LLM_API_KEY ? import.meta.env.LLM_API_KEY : DEMO_API_KEY,
 		}
 		window.pageAgent = new PageAgent(config)
 	}

packages/page-agent/vite.iife.config.js

@@ -1,4 +1,5 @@
 // @ts-check
+import { config as dotenvConfig } from 'dotenv'
 import { dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { defineConfig } from 'vite'
@@ -6,11 +7,14 @@ import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
+// Load .env from repo root
+dotenvConfig({ path: resolve(__dirname, '../../.env') })
+
 // UMD Bundle for CDN
 // - alias all local packages so that they can be build in
 // - no external
 // - no d.ts. dts does not work with monorepo aliasing
-export default defineConfig({
+export default defineConfig(({ mode }) => ({
 	plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
 	publicDir: false,
 	esbuild: {
@@ -25,13 +29,14 @@ export default defineConfig({
 	},
 	build: {
 		lib: {
-			entry: resolve(__dirname, 'src/umd.ts'),
+			entry: resolve(__dirname, 'src/iife.ts'),
 			name: 'PageAgent',
 			fileName: 'page-agent',
-			formats: ['umd'],
+			formats: ['iife'],
 		},
-		outDir: resolve(__dirname, 'dist', 'umd'),
+		outDir: resolve(__dirname, 'dist', 'iife'),
 		cssCodeSplit: true,
+		minify: false,
 		rollupOptions: {
 			output: {
 				// force use .js as extension
@@ -44,6 +49,8 @@ export default defineConfig({
 		},
 	},
 	define: {
-		'process.env.NODE_ENV': '"production"',
+		'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME),
+		'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY),
+		'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL),
 	},
-})
+}))

packages/website/vite.config.js

@@ -16,7 +16,7 @@ const pageAgentPkg = JSON.parse(
 dotenvConfig({ path: resolve(__dirname, '../../.env') })
 
 // Website Config (React Documentation Site)
-export default defineConfig({
+export default defineConfig(({ mode }) => ({
 	base: './',
 	clearScreen: false,
 	plugins: [react(), tailwindcss()],
@@ -43,9 +43,11 @@ export default defineConfig({
 		},
 	},
 	define: {
-		'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME),
+		...(mode === 'development' && {
-		'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY),
+			'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME),
-		'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL),
+			'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY),
+			'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL),
+		}),
 		'import.meta.env.VERSION': JSON.stringify(pageAgentPkg.version),
 	},
-})
+}))