[ { "path": ".gitattributes", "content": "*.onnx filter=lfs diff=lfs merge=lfs -text\n" }, { "path": ".github/workflows/build-release.yml", "content": "# name: Build and Release Chrome Extension\n\n# on:\n# push:\n# branches: [ master, develop ]\n# paths:\n# - 'app/chrome-extension/**'\n# pull_request:\n# branches: [ master ]\n# paths:\n# - 'app/chrome-extension/**'\n# workflow_dispatch:\n\n# jobs:\n# build-extension:\n# runs-on: ubuntu-latest\n \n# steps:\n# - name: Checkout code\n# uses: actions/checkout@v4\n \n# - name: Setup Node.js\n# uses: actions/setup-node@v4\n# with:\n# node-version: '18'\n# cache: 'npm'\n# cache-dependency-path: 'app/chrome-extension/package-lock.json'\n \n# - name: Install dependencies\n# run: |\n# cd app/chrome-extension\n# npm ci\n \n# - name: Build extension\n# run: |\n# cd app/chrome-extension\n# npm run build\n \n# - name: Create zip package\n# run: |\n# cd app/chrome-extension\n# npm run zip\n \n# - name: Prepare release directory\n# run: |\n# mkdir -p releases/chrome-extension/latest\n# mkdir -p releases/chrome-extension/$(date +%Y%m%d-%H%M%S)\n \n# - name: Copy release files\n# run: |\n# # Copy to latest\n# cp app/chrome-extension/.output/chrome-mv3-prod.zip releases/chrome-extension/latest/chrome-mcp-server-latest.zip\n \n# # Copy to timestamped version\n# TIMESTAMP=$(date +%Y%m%d-%H%M%S)\n# cp app/chrome-extension/.output/chrome-mv3-prod.zip releases/chrome-extension/$TIMESTAMP/chrome-mcp-server-$TIMESTAMP.zip\n \n# - name: Upload build artifacts\n# uses: actions/upload-artifact@v4\n# with:\n# name: chrome-extension-build\n# path: releases/chrome-extension/\n# retention-days: 30\n \n# - name: Commit and push releases (if on main branch)\n# if: github.ref == 'refs/heads/main'\n# run: |\n# git config --local user.email \"action@github.com\"\n# git config --local user.name \"GitHub Action\"\n# git add releases/\n# git diff --staged --quiet || git commit -m \"Auto-build: Update Chrome extension release [skip ci]\"\n# git push\n" }, { "path": ".gitignore", "content": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\npnpm-debug.log*\nlerna-debug.log*\n\nnode_modules\n.output\nstats.html\nstats-*.json\n.wxt\nweb-ext.config.ts\ndist\n\n# Editor directories and files\n.vscode/*\n!.vscode/extensions.json\n.idea\n.DS_Store\n*.suo\n*.ntvs*\n*.njsproj\n*.sln\n*.sw?\n*.onnx\n\n# Environment variables\n.env\n.env.local\n.env.*.local\n\n# Prevent npm metadata pollution\nfalse/\nmetadata-v1.3/\nregistry.npmmirror.com/\nregistry.npmjs.com/\n\nother/\ntools_optimize.md\nAgents.md\nCLAUDE.md\n\n**/*/coverage/*\n\n.docs/\n.claude/" }, { "path": ".husky/commit-msg", "content": "npx --no -- commitlint --edit \"$1\"" }, { "path": ".husky/pre-commit", "content": "npx lint-staged" }, { "path": ".prettierignore", "content": "# 构建输出目录\ndist\n.output\n.wxt\n\n# 依赖\nnode_modules\n\n# 日志\nlogs\n*.log\n\n# 缓存\n.cache\n.temp\n\n# 编辑器配置\n.vscode\n!.vscode/extensions.json\n.idea\n\n# 系统文件\n.DS_Store\nThumbs.db\n\n# 打包文件\n*.zip\n*.tar.gz\n\n# 统计文件\nstats.html\nstats-*.json\n\n# 锁文件\npnpm-lock.yaml" }, { "path": ".prettierrc.json", "content": "{\n \"semi\": true,\n \"singleQuote\": true,\n \"tabWidth\": 2,\n \"printWidth\": 100,\n \"endOfLine\": \"auto\",\n \"proseWrap\": \"preserve\",\n \"htmlWhitespaceSensitivity\": \"strict\"\n}\n" }, { "path": ".vscode/extensions.json", "content": "{\n \"recommendations\": [\"Vue.volar\"]\n}\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2024 hangye\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "# Chrome MCP Server 🚀\n\n[![Stars](https://img.shields.io/github/stars/hangwin/mcp-chrome)](https://img.shields.io/github/stars/hangwin/mcp-chrome)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-blue.svg)](https://www.typescriptlang.org/)\n[![Chrome Extension](https://img.shields.io/badge/Chrome-Extension-green.svg)](https://developer.chrome.com/docs/extensions/)\n[![Release](https://img.shields.io/github/v/release/hangwin/mcp-chrome.svg)](https://img.shields.io/github/v/release/hangwin/mcp-chrome.svg)\n\n> 🌟 **Turn your Chrome browser into your intelligent assistant** - Let AI take control of your browser, transforming it into a powerful AI-controlled automation tool.\n\n**📖 Documentation**: [English](README.md) | [中文](README_zh.md)\n\n> The project is still in its early stages and is under intensive development. More features, stability improvements, and other enhancements will follow.\n\n---\n\n## 🎯 What is Chrome MCP Server?\n\nChrome MCP Server is a Chrome extension-based **Model Context Protocol (MCP) server** that exposes your Chrome browser functionality to AI assistants like Claude, enabling complex browser automation, content analysis, and semantic search. Unlike traditional browser automation tools (like Playwright), **Chrome MCP Server** directly uses your daily Chrome browser, leveraging existing user habits, configurations, and login states, allowing various large models or chatbots to take control of your browser and truly become your everyday assistant.\n\n## ✨ New Features(2025/12/30)\n\n- **A New Visual Editor for Claude Code & Codex**, for more detail here: [VisualEditor](docs/VisualEditor.md)\n\n## ✨ Core Features\n\n- 😁 **Chatbot/Model Agnostic**: Let any LLM or chatbot client or agent you prefer automate your browser\n- ⭐️ **Use Your Original Browser**: Seamlessly integrate with your existing browser environment (your configurations, login states, etc.)\n- 💻 **Fully Local**: Pure local MCP server ensuring user privacy\n- 🚄 **Streamable HTTP**: Streamable HTTP connection method\n- 🏎 **Cross-Tab**: Cross-tab context\n- 🧠 **Semantic Search**: Built-in vector database for intelligent browser tab content discovery\n- 🔍 **Smart Content Analysis**: AI-powered text extraction and similarity matching\n- 🌐 **20+ Tools**: Support for screenshots, network monitoring, interactive operations, bookmark management, browsing history, and 20+ other tools\n- 🚀 **SIMD-Accelerated AI**: Custom WebAssembly SIMD optimization for 4-8x faster vector operations\n\n## 🆚 Comparison with Similar Projects\n\n| Comparison Dimension | Playwright-based MCP Server | Chrome Extension-based MCP Server |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |\n| **Resource Usage** | ❌ Requires launching independent browser process, installing Playwright dependencies, downloading browser binaries, etc. | ✅ No need to launch independent browser process, directly utilizes user's already open Chrome browser |\n| **User Session Reuse** | ❌ Requires re-login | ✅ Automatically uses existing login state |\n| **Browser Environment** | ❌ Clean environment lacks user settings | ✅ Fully preserves user environment |\n| **API Access** | ⚠️ Limited to Playwright API | ✅ Full access to Chrome native APIs |\n| **Startup Speed** | ❌ Requires launching browser process | ✅ Only needs to activate extension |\n| **Response Speed** | 50-200ms inter-process communication | ✅ Faster |\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js >= 20.0.0 and pnpm/npm\n- Chrome/Chromium browser\n\n### Installation Steps\n\n1. **Download the latest Chrome extension from GitHub**\n\nDownload link: https://github.com/hangwin/mcp-chrome/releases\n\n2. **Install mcp-chrome-bridge globally**\n\nnpm\n\n```bash\nnpm install -g mcp-chrome-bridge\n```\n\npnpm\n\n```bash\n# Method 1: Enable scripts globally (recommended)\npnpm config set enable-pre-post-scripts true\npnpm install -g mcp-chrome-bridge\n\n# Method 2: Manual registration (if postinstall doesn't run)\npnpm install -g mcp-chrome-bridge\nmcp-chrome-bridge register\n```\n\n> Note: pnpm v7+ disables postinstall scripts by default for security. The `enable-pre-post-scripts` setting controls whether pre/post install scripts run. If automatic registration fails, use the manual registration command above.\n\n3. **Load Chrome Extension**\n - Open Chrome and go to `chrome://extensions/`\n - Enable \"Developer mode\"\n - Click \"Load unpacked\" and select `your/dowloaded/extension/folder`\n - Click the extension icon to open the plugin, then click connect to see the MCP configuration\n \"Screenshot\n\n### Usage with MCP Protocol Clients\n\n#### Using Streamable HTTP Connection (👍🏻 Recommended)\n\nAdd the following configuration to your MCP client configuration (using CherryStudio as an example):\n\n> Streamable HTTP connection method is recommended\n\n```json\n{\n \"mcpServers\": {\n \"chrome-mcp-server\": {\n \"type\": \"streamableHttp\",\n \"url\": \"http://127.0.0.1:12306/mcp\"\n }\n }\n}\n```\n\n#### Using STDIO Connection (Alternative)\n\nIf your client only supports stdio connection method, please use the following approach:\n\n1. First, check the installation location of the npm package you just installed\n\n```sh\n# npm check method\nnpm list -g mcp-chrome-bridge\n# pnpm check method\npnpm list -g mcp-chrome-bridge\n```\n\nAssuming the command above outputs the path: /Users/xxx/Library/pnpm/global/5\nThen your final path would be: /Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js\n\n2. Replace the configuration below with the final path you just obtained\n\n```json\n{\n \"mcpServers\": {\n \"chrome-mcp-stdio\": {\n \"command\": \"npx\",\n \"args\": [\n \"node\",\n \"/Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js\"\n ]\n }\n }\n}\n```\n\neg：config in augment:\n\n\"截屏2025-06-22\n\n## 🛠️ Available Tools\n\nComplete tool list: [Complete Tool List](docs/TOOLS.md)\n\n
\n📊 Browser Management (6 tools)\n\n- `get_windows_and_tabs` - List all browser windows and tabs\n- `chrome_navigate` - Navigate to URLs and control viewport\n- `chrome_switch_tab` - Switch the current active tab\n- `chrome_close_tabs` - Close specific tabs or windows\n- `chrome_go_back_or_forward` - Browser navigation control\n- `chrome_inject_script` - Inject content scripts into web pages\n- `chrome_send_command_to_inject_script` - Send commands to injected content scripts\n
\n\n
\n📸 Screenshots & Visual (1 tool)\n\n- `chrome_screenshot` - Advanced screenshot capture with element targeting, full-page support, and custom dimensions\n
\n\n
\n🌐 Network Monitoring (4 tools)\n\n- `chrome_network_capture_start/stop` - webRequest API network capture\n- `chrome_network_debugger_start/stop` - Debugger API with response bodies\n- `chrome_network_request` - Send custom HTTP requests\n
\n\n
\n🔍 Content Analysis (4 tools)\n\n- `search_tabs_content` - AI-powered semantic search across browser tabs\n- `chrome_get_web_content` - Extract HTML/text content from pages\n- `chrome_get_interactive_elements` - Find clickable elements\n- `chrome_console` - Capture and retrieve console output from browser tabs\n
\n\n
\n🎯 Interaction (3 tools)\n\n- `chrome_click_element` - Click elements using CSS selectors\n- `chrome_fill_or_select` - Fill forms and select options\n- `chrome_keyboard` - Simulate keyboard input and shortcuts\n
\n\n
\n📚 Data Management (5 tools)\n\n- `chrome_history` - Search browser history with time filters\n- `chrome_bookmark_search` - Find bookmarks by keywords\n- `chrome_bookmark_add` - Add new bookmarks with folder support\n- `chrome_bookmark_delete` - Delete bookmarks\n
\n\n## 🧪 Usage Examples\n\n### AI helps you summarize webpage content and automatically control Excalidraw for drawing\n\nprompt: [excalidraw-prompt](prompt/excalidraw-prompt.md)\nInstruction: Help me summarize the current page content, then draw a diagram to aid my understanding.\nhttps://www.youtube.com/watch?v=3fBPdUBWVz0\n\nhttps://github.com/user-attachments/assets/fd17209b-303d-48db-9e5e-3717141df183\n\n### After analyzing the content of the image, the LLM automatically controls Excalidraw to replicate the image\n\nprompt: [excalidraw-prompt](prompt/excalidraw-prompt.md)|[content-analize](prompt/content-analize.md)\nInstruction: First, analyze the content of the image, and then replicate the image by combining the analysis with the content of the image.\nhttps://www.youtube.com/watch?v=tEPdHZBzbZk\n\nhttps://github.com/user-attachments/assets/60d12b1a-9b74-40f4-994c-95e8fa1fc8d3\n\n### AI automatically injects scripts and modifies webpage styles\n\nprompt: [modify-web-prompt](prompt/modify-web.md)\nInstruction: Help me modify the current page's style and remove advertisements.\nhttps://youtu.be/twI6apRKHsk\n\nhttps://github.com/user-attachments/assets/69cb561c-2e1e-4665-9411-4a3185f9643e\n\n### AI automatically captures network requests for you\n\nquery: I want to know what the search API for Xiaohongshu is and what the response structure looks like\n\nhttps://youtu.be/1hHKr7XKqnQ\n\nhttps://github.com/user-attachments/assets/dc7e5cab-b9af-4b9a-97ce-18e4837318d9\n\n### AI helps analyze your browsing history\n\nquery: Analyze my browsing history from the past month\n\nhttps://youtu.be/jf2UZfrR2Vk\n\nhttps://github.com/user-attachments/assets/31b2e064-88c6-4adb-96d7-50748b826eae\n\n### Web page conversation\n\nquery: Translate and summarize the current web page\nhttps://youtu.be/FlJKS9UQyC8\n\nhttps://github.com/user-attachments/assets/aa8ef2a1-2310-47e6-897a-769d85489396\n\n### AI automatically takes screenshots for you (web page screenshots)\n\nquery: Take a screenshot of Hugging Face's homepage\nhttps://youtu.be/7ycK6iksWi4\n\nhttps://github.com/user-attachments/assets/65c6eee2-6366-493d-a3bd-2b27529ff5b3\n\n### AI automatically takes screenshots for you (element screenshots)\n\nquery: Capture the icon from Hugging Face's homepage\nhttps://youtu.be/ev8VivANIrk\n\nhttps://github.com/user-attachments/assets/d0cf9785-c2fe-4729-a3c5-7f2b8b96fe0c\n\n### AI helps manage bookmarks\n\nquery: Add the current page to bookmarks and put it in an appropriate folder\n\nhttps://youtu.be/R_83arKmFTo\n\nhttps://github.com/user-attachments/assets/15a7d04c-0196-4b40-84c2-bafb5c26dfe0\n\n### Automatically close web pages\n\nquery: Close all shadcn-related web pages\n\nhttps://youtu.be/2wzUT6eNVg4\n\nhttps://github.com/user-attachments/assets/83de4008-bb7e-494d-9b0f-98325cfea592\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed guidelines.\n\n## 🚧 Future Roadmap\n\nWe have exciting plans for the future development of Chrome MCP Server:\n\n- [ ] Authentication\n- [ ] Recording and Playback\n- [ ] Workflow Automation\n- [ ] Enhanced Browser Support (Firefox Extension)\n\n---\n\n**Want to contribute to any of these features?** Check out our [Contributing Guide](docs/CONTRIBUTING.md) and join our development community!\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 📚 More Documentation\n\n- [Architecture Design](docs/ARCHITECTURE.md) - Detailed technical architecture documentation\n- [TOOLS API](docs/TOOLS.md) - Complete tool API documentation\n- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issue solutions\n" }, { "path": "README_zh.md", "content": "# Chrome MCP Server 🚀\n\n[![许可证: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-blue.svg)](https://www.typescriptlang.org/)\n[![Chrome 扩展](https://img.shields.io/badge/Chrome-Extension-green.svg)](https://developer.chrome.com/docs/extensions/)\n\n> 🌟 **让chrome浏览器变成你的智能助手** - 让AI接管你的浏览器，将您的浏览器转变为强大的 AI 控制自动化工具。\n\n**📖 文档**: [English](README.md) | [中文](README_zh.md)\n\n> 项目仍处于早期阶段，正在紧锣密鼓开发中，后续将有更多新功能，以及稳定性等的提升，如遇bug，请轻喷\n\n---\n\n## 🎯 什么是 Chrome MCP Server？\n\nChrome MCP Server 是一个基于chrome插件的 **模型上下文协议 (MCP) 服务器**，它将您的 Chrome 浏览器功能暴露给 Claude 等 AI 助手，实现复杂的浏览器自动化、内容分析和语义搜索等。与传统的浏览器自动化工具（如playwright）不同，**Chrome MCP server**直接使用您日常使用的chrome浏览器，基于现有的用户习惯和配置、登录态，让各种大模型或者各种chatbot都可以接管你的浏览器，真正成为你的日常助手\n\n## ✨ 船新的功能(2025/12/30)\n\n- **让Claude Code/Codex也能使用的可视化编辑器**, 更多详情请看: [VisualEditor](docs/VisualEditor_zh.md)\n\n## ✨ 核心特性\n\n- 😁 **chatbot/模型无关**：让任意你喜欢的llm或chatbot客户端或agent来自动化操作你的浏览器\n- ⭐️ **使用你原本的浏览器**：无缝集成用户本身的浏览器环境（你的配置、登录态等）\n- 💻 **完全本地运行**：纯本地运行的mcp server，保证用户隐私\n- 🚄 **Streamable http**：Streamable http的连接方式\n- 🏎 **跨标签页** 跨标签页的上下文\n- 🧠 **语义搜索**：内置向量数据库和本地小模型，智能发现浏览器标签页内容\n- 🔍 **智能内容分析**：AI 驱动的文本提取和相似度匹配\n- 🌐 **20+ 工具**：支持截图、网络监控、交互操作、书签管理、浏览历史等20多种工具\n- 🚀 **SIMD 加速 AI**：自定义 WebAssembly SIMD 优化，向量运算速度提升 4-8 倍\n\n## 🆚 与同类项目对比\n\n| 对比维度 | 基于Playwright的MCP Server | 基于Chrome插件的MCP Server |\n| ------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------- |\n| **资源占用** | ❌ 需启动独立浏览器进程，需要安装Playwright依赖，下载浏览器二进制等 | ✅ 无需启动独立的浏览器进程，直接利用用户已打开的Chrome浏览器 |\n| **用户会话复用** | ❌ 需重新登录 | ✅ 自动使用已登录状态 |\n| **浏览器环境保持** | ❌ 干净环境缺少用户设置 | ✅ 完整保留用户环境 |\n| **API访问权限** | ⚠️ 受限于Playwright API | ✅ Chrome原生API全访问 |\n| **启动速度** | ❌ 需启动浏览器进程 | ✅ 只需激活插件 |\n| **响应速度** | 50-200ms进程间通信 | ✅ 更快 |\n\n## 🚀 快速开始\n\n### 环境要求\n\n- Node.js >= 20.0.0 和 （npm 或 pnpm）\n- Chrome/Chromium 浏览器\n\n### 安装步骤\n\n1. **从github上下载最新的chrome扩展**\n\n下载地址：https://github.com/hangwin/mcp-chrome/releases\n\n2. **全局安装mcp-chrome-bridge**\n\nnpm\n\n```bash\nnpm install -g mcp-chrome-bridge\n```\n\npnpm\n\n```bash\n# 方法1：全局启用脚本（推荐）\npnpm config set enable-pre-post-scripts true\npnpm install -g mcp-chrome-bridge\n\n# 方法2：如果 postinstall 没有运行，手动注册\npnpm install -g mcp-chrome-bridge\nmcp-chrome-bridge register\n```\n\n> 注意：pnpm v7+ 默认禁用 postinstall 脚本以提高安全性。`enable-pre-post-scripts` 设置控制是否运行 pre/post 安装脚本。如果自动注册失败，请使用上述手动注册命令。\n\n3. **加载 Chrome 扩展**\n - 打开 Chrome 并访问 `chrome://extensions/`\n - 启用\"开发者模式\"\n - 点击\"加载已解压的扩展程序\"，选择 `your/dowloaded/extension/folder`\n - 点击插件图标打开插件，点击连接即可看到mcp的配置\n \"截屏2025-06-09\n\n### 在支持MCP协议的客户端中使用\n\n#### 使用streamable http的方式连接（👍🏻推荐）\n\n将以下配置添加到客户端的 MCP 配置中以cherryStudio为例：\n\n> 推荐用streamable http的连接方式\n\n```json\n{\n \"mcpServers\": {\n \"chrome-mcp-server\": {\n \"type\": \"streamableHttp\",\n \"url\": \"http://127.0.0.1:12306/mcp\"\n }\n }\n}\n```\n\n#### 使用stdio的方式连接（备选）\n\n假设你的客户端仅支持stdio的连接方式，那么请使用下面的方法：\n\n1. 先查看你刚刚安装的npm包的安装位置\n\n```sh\n# npm 查看方式\nnpm list -g mcp-chrome-bridge\n# pnpm 查看方式\npnpm list -g mcp-chrome-bridge\n```\n\n假设上面的命令输出的路径是：/Users/xxx/Library/pnpm/global/5\n那么你的最终路径就是：/Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js\n\n2. 把下面的配置替换成你刚刚得到的最终路径\n\n```json\n{\n \"mcpServers\": {\n \"chrome-mcp-stdio\": {\n \"command\": \"npx\",\n \"args\": [\n \"node\",\n \"/Users/xxx/Library/pnpm/global/5/node_modules/mcp-chrome-bridge/dist/mcp/mcp-server-stdio.js\"\n ]\n }\n }\n}\n```\n\n比如：在augment中的配置如下：\n\n\"截屏2025-06-22\n\n## 🛠️ 可用工具\n\n完整工具列表：[完整工具列表](docs/TOOLS_zh.md)\n\n
\n📊 浏览器管理 (6个工具)\n\n- `get_windows_and_tabs` - 列出所有浏览器窗口和标签页\n- `chrome_navigate` - 导航到 URL 并控制视口\n- `chrome_switch_tab` - 切换当前显示的标签页\n- `chrome_close_tabs` - 关闭特定标签页或窗口\n- `chrome_go_back_or_forward` - 浏览器导航控制\n- `chrome_inject_script` - 向网页注入内容脚本\n- `chrome_send_command_to_inject_script` - 向已注入的内容脚本发送指令\n
\n\n
\n📸 截图和视觉 (1个工具)\n\n- `chrome_screenshot` - 高级截图捕获，支持元素定位、全页面和自定义尺寸\n
\n\n
\n🌐 网络监控 (4个工具)\n\n- `chrome_network_capture_start/stop` - webRequest API 网络捕获\n- `chrome_network_debugger_start/stop` - Debugger API 包含响应体\n- `chrome_network_request` - 发送自定义 HTTP 请求\n
\n\n
\n🔍 内容分析 (4个工具)\n\n- `search_tabs_content` - AI 驱动的浏览器标签页语义搜索\n- `chrome_get_web_content` - 从页面提取 HTML/文本内容\n- `chrome_get_interactive_elements` - 查找可点击元素\n- `chrome_console` - 捕获和获取浏览器标签页的控制台输出\n
\n\n
\n🎯 交互操作 (3个工具)\n\n- `chrome_click_element` - 使用 CSS 选择器点击元素\n- `chrome_fill_or_select` - 填充表单和选择选项\n- `chrome_keyboard` - 模拟键盘输入和快捷键\n
\n\n
\n📚 数据管理 (5个工具)\n\n- `chrome_history` - 搜索浏览器历史记录，支持时间过滤\n- `chrome_bookmark_search` - 按关键词查找书签\n- `chrome_bookmark_add` - 添加新书签，支持文件夹\n- `chrome_bookmark_delete` - 删除书签\n
\n\n## 🧪 使用示例\n\n### ai帮你总结网页内容然后自动控制excalidraw画图\n\nprompt: [excalidraw-prompt](prompt/excalidraw-prompt.md)\n指令：帮我总结当前页面内容，然后画个图帮我理解\nhttps://www.youtube.com/watch?v=3fBPdUBWVz0\n\nhttps://github.com/user-attachments/assets/f14f79a6-9390-4821-8296-06d020bcfc07\n\n### ai先分析图片的内容元素，然后再自动控制excalidraw把图片模仿出来\n\nprompt: [excalidraw-prompt](prompt/excalidraw-prompt.md)|[content-analize](prompt/content-analize.md)\n指令：先看下图片是否能用excalidraw画出来，如果则列出所需的步骤和元素，然后画出来\nhttps://www.youtube.com/watch?v=tEPdHZBzbZk\n\nhttps://github.com/user-attachments/assets/4f0600c1-bb1e-4b57-85ab-36c8bdf71c68\n\n### ai自动帮你注入脚本并修改网页的样式\n\nprompt: [modify-web-prompt](prompt/modify-web.md)\n指令：帮我修改当前页面的样式，去掉广告\nhttps://youtu.be/twI6apRKHsk\n\nhttps://github.com/user-attachments/assets/aedbe98d-e90c-4a58-a4a5-d888f7293d8e\n\n### ai自动帮你捕获网络请求\n\n指令：我想知道小红书的搜索接口是哪个，响应体结构是什么样的\nhttps://youtu.be/1hHKr7XKqnQ\n\nhttps://github.com/user-attachments/assets/dc7e5cab-b9af-4b9a-97ce-18e4837318d9\n\n### ai帮你分析你的浏览记录\n\n指令：分析一下我近一个月的浏览记录\nhttps://youtu.be/jf2UZfrR2Vk\n\nhttps://github.com/user-attachments/assets/31b2e064-88c6-4adb-96d7-50748b826eae\n\n### 网页对话\n\n指令：翻译并总结当前网页\nhttps://youtu.be/FlJKS9UQyC8\n\nhttps://github.com/user-attachments/assets/aa8ef2a1-2310-47e6-897a-769d85489396\n\n### ai帮你自动截图（网页截图）\n\n指令：把huggingface的首页截个图\nhttps://youtu.be/7ycK6iksWi4\n\nhttps://github.com/user-attachments/assets/65c6eee2-6366-493d-a3bd-2b27529ff5b3\n\n### ai帮你自动截图（元素截图）\n\n指令：把huggingface首页的图标截取下来\nhttps://youtu.be/ev8VivANIrk\n\nhttps://github.com/user-attachments/assets/d0cf9785-c2fe-4729-a3c5-7f2b8b96fe0c\n\n### ai帮你管理书签\n\n指令：将当前页面添加到书签中，放到合适的文件夹\nhttps://youtu.be/R_83arKmFTo\n\nhttps://github.com/user-attachments/assets/15a7d04c-0196-4b40-84c2-bafb5c26dfe0\n\n### 自动关闭网页\n\n指令：关闭所有shadcn相关的网页\nhttps://youtu.be/2wzUT6eNVg4\n\nhttps://github.com/user-attachments/assets/83de4008-bb7e-494d-9b0f-98325cfea592\n\n## 🤝 贡献指南\n\n我们欢迎贡献！请查看 [CONTRIBUTING_zh.md](docs/CONTRIBUTING_zh.md) 了解详细指南。\n\n## 🚧 未来发展路线图\n\n我们对 Chrome MCP Server 的未来发展有着激动人心的计划：\n\n- [ ] 身份认证\n\n- [ ] 录制与回放\n\n- [ ] 工作流自动化\n\n- [ ] 增强浏览器支持（Firefox 扩展）\n\n---\n\n**想要为这些功能中的任何一个做贡献？** 查看我们的[贡献指南](docs/CONTRIBUTING_zh.md)并加入我们的开发社区！\n\n## 📄 许可证\n\n本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。\n\n## 📚 更多文档\n\n- [架构设计](docs/ARCHITECTURE_zh.md) - 详细的技术架构说明\n- [工具列表](docs/TOOLS_zh.md) - 完整的工具 API 文档\n- [故障排除](docs/TROUBLESHOOTING_zh.md) - 常见问题解决方案\n\n## 微信交流群\n\n拉群的目的是让踩过坑的大佬们互相帮忙解答问题，因本人平时要忙着搬砖，不一定能及时解答\n\n![IMG_6296](https://github.com/user-attachments/assets/ecd2e084-24d2-4038-b75f-3ab020b55594)\n" }, { "path": "app/chrome-extension/LICENSE", "content": "MIT License\n\nCopyright (c) 2025 hangwin\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "app/chrome-extension/README.md", "content": "# WXT + Vue 3\n\nThis template should help get you started developing with Vue 3 in WXT.\n\n## Recommended IDE Setup\n\n- [VS Code](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar).\n" }, { "path": "app/chrome-extension/_locales/de/messages.json", "content": "{\n \"extensionName\": {\n \"message\": \"chrome-mcp-server\",\n \"description\": \"Erweiterungsname\"\n },\n \"extensionDescription\": {\n \"message\": \"Stellt Browser-Funktionen mit Ihrem eigenen Chrome zur Verfügung\",\n \"description\": \"Erweiterungsbeschreibung\"\n },\n \"nativeServerConfigLabel\": {\n \"message\": \"Native Server-Konfiguration\",\n \"description\": \"Hauptabschnittstitel für Native Server-Einstellungen\"\n },\n \"semanticEngineLabel\": {\n \"message\": \"Semantische Engine\",\n \"description\": \"Hauptabschnittstitel für semantische Engine\"\n },\n \"embeddingModelLabel\": {\n \"message\": \"Embedding-Modell\",\n \"description\": \"Hauptabschnittstitel für Modellauswahl\"\n },\n \"indexDataManagementLabel\": {\n \"message\": \"Index-Datenverwaltung\",\n \"description\": \"Hauptabschnittstitel für Datenverwaltung\"\n },\n \"modelCacheManagementLabel\": {\n \"message\": \"Modell-Cache-Verwaltung\",\n \"description\": \"Hauptabschnittstitel für Cache-Verwaltung\"\n },\n \"statusLabel\": {\n \"message\": \"Status\",\n \"description\": \"Allgemeines Statuslabel\"\n },\n \"runningStatusLabel\": {\n \"message\": \"Betriebsstatus\",\n \"description\": \"Server-Betriebsstatuslabel\"\n },\n \"connectionStatusLabel\": {\n \"message\": \"Verbindungsstatus\",\n \"description\": \"Verbindungsstatuslabel\"\n },\n \"lastUpdatedLabel\": {\n \"message\": \"Zuletzt aktualisiert:\",\n \"description\": \"Zeitstempel der letzten Aktualisierung\"\n },\n \"connectButton\": {\n \"message\": \"Verbinden\",\n \"description\": \"Verbinden-Schaltflächentext\"\n },\n \"disconnectButton\": {\n \"message\": \"Trennen\",\n \"description\": \"Trennen-Schaltflächentext\"\n },\n \"connectingStatus\": {\n \"message\": \"Verbindung wird hergestellt...\",\n \"description\": \"Verbindungsstatusmeldung\"\n },\n \"connectedStatus\": {\n \"message\": \"Verbunden\",\n \"description\": \"Verbunden-Statusmeldung\"\n },\n \"disconnectedStatus\": {\n \"message\": \"Getrennt\",\n \"description\": \"Getrennt-Statusmeldung\"\n },\n \"detectingStatus\": {\n \"message\": \"Erkennung läuft...\",\n \"description\": \"Erkennungsstatusmeldung\"\n },\n \"serviceRunningStatus\": {\n \"message\": \"Service läuft (Port: $PORT$)\",\n \"description\": \"Service läuft mit Portnummer\",\n \"placeholders\": {\n \"port\": {\n \"content\": \"$1\",\n \"example\": \"12306\"\n }\n }\n },\n \"serviceNotConnectedStatus\": {\n \"message\": \"Service nicht verbunden\",\n \"description\": \"Service nicht verbunden Status\"\n },\n \"connectedServiceNotStartedStatus\": {\n \"message\": \"Verbunden, Service nicht gestartet\",\n \"description\": \"Verbunden aber Service nicht gestartet Status\"\n },\n \"mcpServerConfigLabel\": {\n \"message\": \"MCP Server-Konfiguration\",\n \"description\": \"MCP Server-Konfigurationsabschnittslabel\"\n },\n \"connectionPortLabel\": {\n \"message\": \"Verbindungsport\",\n \"description\": \"Verbindungsport-Eingabelabel\"\n },\n \"refreshStatusButton\": {\n \"message\": \"Status aktualisieren\",\n \"description\": \"Status aktualisieren Schaltflächen-Tooltip\"\n },\n \"copyConfigButton\": {\n \"message\": \"Konfiguration kopieren\",\n \"description\": \"Konfiguration kopieren Schaltflächentext\"\n },\n \"retryButton\": {\n \"message\": \"Wiederholen\",\n \"description\": \"Wiederholen-Schaltflächentext\"\n },\n \"cancelButton\": {\n \"message\": \"Abbrechen\",\n \"description\": \"Abbrechen-Schaltflächentext\"\n },\n \"confirmButton\": {\n \"message\": \"Bestätigen\",\n \"description\": \"Bestätigen-Schaltflächentext\"\n },\n \"saveButton\": {\n \"message\": \"Speichern\",\n \"description\": \"Speichern-Schaltflächentext\"\n },\n \"closeButton\": {\n \"message\": \"Schließen\",\n \"description\": \"Schließen-Schaltflächentext\"\n },\n \"resetButton\": {\n \"message\": \"Zurücksetzen\",\n \"description\": \"Zurücksetzen-Schaltflächentext\"\n },\n \"initializingStatus\": {\n \"message\": \"Initialisierung...\",\n \"description\": \"Initialisierung-Fortschrittsmeldung\"\n },\n \"processingStatus\": {\n \"message\": \"Verarbeitung...\",\n \"description\": \"Verarbeitung-Fortschrittsmeldung\"\n },\n \"loadingStatus\": {\n \"message\": \"Wird geladen...\",\n \"description\": \"Ladefortschrittsmeldung\"\n },\n \"clearingStatus\": {\n \"message\": \"Wird geleert...\",\n \"description\": \"Leerungsfortschrittsmeldung\"\n },\n \"cleaningStatus\": {\n \"message\": \"Wird bereinigt...\",\n \"description\": \"Bereinigungsfortschrittsmeldung\"\n },\n \"downloadingStatus\": {\n \"message\": \"Wird heruntergeladen...\",\n \"description\": \"Download-Fortschrittsmeldung\"\n },\n \"semanticEngineReadyStatus\": {\n \"message\": \"Semantische Engine bereit\",\n \"description\": \"Semantische Engine bereit Status\"\n },\n \"semanticEngineInitializingStatus\": {\n \"message\": \"Semantische Engine wird initialisiert...\",\n \"description\": \"Semantische Engine Initialisierungsstatus\"\n },\n \"semanticEngineInitFailedStatus\": {\n \"message\": \"Initialisierung der semantischen Engine fehlgeschlagen\",\n \"description\": \"Semantische Engine Initialisierung fehlgeschlagen Status\"\n },\n \"semanticEngineNotInitStatus\": {\n \"message\": \"Semantische Engine nicht initialisiert\",\n \"description\": \"Semantische Engine nicht initialisiert Status\"\n },\n \"initSemanticEngineButton\": {\n \"message\": \"Semantische Engine initialisieren\",\n \"description\": \"Semantische Engine initialisieren Schaltflächentext\"\n },\n \"reinitializeButton\": {\n \"message\": \"Neu initialisieren\",\n \"description\": \"Neu initialisieren Schaltflächentext\"\n },\n \"downloadingModelStatus\": {\n \"message\": \"Modell wird heruntergeladen... $PROGRESS$%\",\n \"description\": \"Modell-Download-Fortschritt mit Prozentsatz\",\n \"placeholders\": {\n \"progress\": {\n \"content\": \"$1\",\n \"example\": \"50\"\n }\n }\n },\n \"switchingModelStatus\": {\n \"message\": \"Modell wird gewechselt...\",\n \"description\": \"Modellwechsel-Fortschrittsmeldung\"\n },\n \"modelLoadedStatus\": {\n \"message\": \"Modell geladen\",\n \"description\": \"Modell erfolgreich geladen Status\"\n },\n \"modelFailedStatus\": {\n \"message\": \"Modell konnte nicht geladen werden\",\n \"description\": \"Modell-Ladefehler Status\"\n },\n \"lightweightModelDescription\": {\n \"message\": \"Leichtgewichtiges mehrsprachiges Modell\",\n \"description\": \"Beschreibung für leichtgewichtige Modelloption\"\n },\n \"betterThanSmallDescription\": {\n \"message\": \"Etwas größer als e5-small, aber bessere Leistung\",\n \"description\": \"Beschreibung für mittlere Modelloption\"\n },\n \"multilingualModelDescription\": {\n \"message\": \"Mehrsprachiges semantisches Modell\",\n \"description\": \"Beschreibung für mehrsprachige Modelloption\"\n },\n \"fastPerformance\": {\n \"message\": \"Schnell\",\n \"description\": \"Schnelle Leistungsanzeige\"\n },\n \"balancedPerformance\": {\n \"message\": \"Ausgewogen\",\n \"description\": \"Ausgewogene Leistungsanzeige\"\n },\n \"accuratePerformance\": {\n \"message\": \"Genau\",\n \"description\": \"Genaue Leistungsanzeige\"\n },\n \"networkErrorMessage\": {\n \"message\": \"Netzwerkverbindungsfehler, bitte Netzwerk prüfen und erneut versuchen\",\n \"description\": \"Netzwerkverbindungsfehlermeldung\"\n },\n \"modelCorruptedErrorMessage\": {\n \"message\": \"Modelldatei beschädigt oder unvollständig, bitte Download wiederholen\",\n \"description\": \"Modell-Beschädigungsfehlermeldung\"\n },\n \"unknownErrorMessage\": {\n \"message\": \"Unbekannter Fehler, bitte prüfen Sie, ob Ihr Netzwerk auf HuggingFace zugreifen kann\",\n \"description\": \"Unbekannte Fehler-Rückfallmeldung\"\n },\n \"permissionDeniedErrorMessage\": {\n \"message\": \"Zugriff verweigert\",\n \"description\": \"Zugriff verweigert Fehlermeldung\"\n },\n \"timeoutErrorMessage\": {\n \"message\": \"Zeitüberschreitung\",\n \"description\": \"Zeitüberschreitungsfehlermeldung\"\n },\n \"indexedPagesLabel\": {\n \"message\": \"Indizierte Seiten\",\n \"description\": \"Anzahl indizierter Seiten Label\"\n },\n \"indexSizeLabel\": {\n \"message\": \"Indexgröße\",\n \"description\": \"Indexgröße Label\"\n },\n \"activeTabsLabel\": {\n \"message\": \"Aktive Tabs\",\n \"description\": \"Anzahl aktiver Tabs Label\"\n },\n \"vectorDocumentsLabel\": {\n \"message\": \"Vektordokumente\",\n \"description\": \"Anzahl Vektordokumente Label\"\n },\n \"cacheSizeLabel\": {\n \"message\": \"Cache-Größe\",\n \"description\": \"Cache-Größe Label\"\n },\n \"cacheEntriesLabel\": {\n \"message\": \"Cache-Einträge\",\n \"description\": \"Anzahl Cache-Einträge Label\"\n },\n \"clearAllDataButton\": {\n \"message\": \"Alle Daten löschen\",\n \"description\": \"Alle Daten löschen Schaltflächentext\"\n },\n \"clearAllCacheButton\": {\n \"message\": \"Gesamten Cache löschen\",\n \"description\": \"Gesamten Cache löschen Schaltflächentext\"\n },\n \"cleanExpiredCacheButton\": {\n \"message\": \"Abgelaufenen Cache bereinigen\",\n \"description\": \"Abgelaufenen Cache bereinigen Schaltflächentext\"\n },\n \"exportDataButton\": {\n \"message\": \"Daten exportieren\",\n \"description\": \"Daten exportieren Schaltflächentext\"\n },\n \"importDataButton\": {\n \"message\": \"Daten importieren\",\n \"description\": \"Daten importieren Schaltflächentext\"\n },\n \"confirmClearDataTitle\": {\n \"message\": \"Datenlöschung bestätigen\",\n \"description\": \"Datenlöschung bestätigen Dialogtitel\"\n },\n \"settingsTitle\": {\n \"message\": \"Einstellungen\",\n \"description\": \"Einstellungen Dialogtitel\"\n },\n \"aboutTitle\": {\n \"message\": \"Über\",\n \"description\": \"Über Dialogtitel\"\n },\n \"helpTitle\": {\n \"message\": \"Hilfe\",\n \"description\": \"Hilfe Dialogtitel\"\n },\n \"clearDataWarningMessage\": {\n \"message\": \"Diese Aktion löscht alle indizierten Webseiteninhalte und Vektordaten, einschließlich:\",\n \"description\": \"Datenlöschung Warnmeldung\"\n },\n \"clearDataList1\": {\n \"message\": \"Alle Webseitentextinhaltsindizes\",\n \"description\": \"Erster Punkt in Datenlöschungsliste\"\n },\n \"clearDataList2\": {\n \"message\": \"Vektor-Embedding-Daten\",\n \"description\": \"Zweiter Punkt in Datenlöschungsliste\"\n },\n \"clearDataList3\": {\n \"message\": \"Suchverlauf und Cache\",\n \"description\": \"Dritter Punkt in Datenlöschungsliste\"\n },\n \"clearDataIrreversibleWarning\": {\n \"message\": \"Diese Aktion ist unwiderruflich! Nach dem Löschen müssen Sie Webseiten erneut durchsuchen, um den Index neu aufzubauen.\",\n \"description\": \"Unwiderrufliche Aktion Warnung\"\n },\n \"confirmClearButton\": {\n \"message\": \"Löschung bestätigen\",\n \"description\": \"Löschung bestätigen Aktionsschaltfläche\"\n },\n \"cacheDetailsLabel\": {\n \"message\": \"Cache-Details\",\n \"description\": \"Cache-Details Abschnittslabel\"\n },\n \"noCacheDataMessage\": {\n \"message\": \"Keine Cache-Daten vorhanden\",\n \"description\": \"Keine Cache-Daten verfügbar Meldung\"\n },\n \"loadingCacheInfoStatus\": {\n \"message\": \"Cache-Informationen werden geladen...\",\n \"description\": \"Cache-Informationen laden Status\"\n },\n \"processingCacheStatus\": {\n \"message\": \"Cache wird verarbeitet...\",\n \"description\": \"Cache verarbeiten Status\"\n },\n \"expiredLabel\": {\n \"message\": \"Abgelaufen\",\n \"description\": \"Abgelaufenes Element Label\"\n },\n \"bookmarksBarLabel\": {\n \"message\": \"Lesezeichenleiste\",\n \"description\": \"Lesezeichenleiste Ordnername\"\n },\n \"newTabLabel\": {\n \"message\": \"Neuer Tab\",\n \"description\": \"Neuer Tab Label\"\n },\n \"currentPageLabel\": {\n \"message\": \"Aktuelle Seite\",\n \"description\": \"Aktuelle Seite Label\"\n },\n \"menuLabel\": {\n \"message\": \"Menü\",\n \"description\": \"Menü Barrierefreiheitslabel\"\n },\n \"navigationLabel\": {\n \"message\": \"Navigation\",\n \"description\": \"Navigation Barrierefreiheitslabel\"\n },\n \"mainContentLabel\": {\n \"message\": \"Hauptinhalt\",\n \"description\": \"Hauptinhalt Barrierefreiheitslabel\"\n },\n \"languageSelectorLabel\": {\n \"message\": \"Sprache\",\n \"description\": \"Sprachauswahl Label\"\n },\n \"themeLabel\": {\n \"message\": \"Design\",\n \"description\": \"Design-Auswahl Label\"\n },\n \"lightTheme\": {\n \"message\": \"Hell\",\n \"description\": \"Helles Design Option\"\n },\n \"darkTheme\": {\n \"message\": \"Dunkel\",\n \"description\": \"Dunkles Design Option\"\n },\n \"autoTheme\": {\n \"message\": \"Automatisch\",\n \"description\": \"Automatisches Design Option\"\n },\n \"advancedSettingsLabel\": {\n \"message\": \"Erweiterte Einstellungen\",\n \"description\": \"Erweiterte Einstellungen Abschnittslabel\"\n },\n \"debugModeLabel\": {\n \"message\": \"Debug-Modus\",\n \"description\": \"Debug-Modus Umschalter Label\"\n },\n \"verboseLoggingLabel\": {\n \"message\": \"Ausführliche Protokollierung\",\n \"description\": \"Ausführliche Protokollierung Umschalter Label\"\n },\n \"successNotification\": {\n \"message\": \"Vorgang erfolgreich abgeschlossen\",\n \"description\": \"Allgemeine Erfolgsmeldung\"\n },\n \"warningNotification\": {\n \"message\": \"Warnung: Bitte prüfen Sie vor dem Fortfahren\",\n \"description\": \"Allgemeine Warnmeldung\"\n },\n \"infoNotification\": {\n \"message\": \"Information\",\n \"description\": \"Allgemeine Informationsmeldung\"\n },\n \"configCopiedNotification\": {\n \"message\": \"Konfiguration in Zwischenablage kopiert\",\n \"description\": \"Konfiguration kopiert Erfolgsmeldung\"\n },\n \"dataClearedNotification\": {\n \"message\": \"Daten erfolgreich gelöscht\",\n \"description\": \"Daten gelöscht Erfolgsmeldung\"\n },\n \"bytesUnit\": {\n \"message\": \"Bytes\",\n \"description\": \"Bytes Einheit\"\n },\n \"kilobytesUnit\": {\n \"message\": \"KB\",\n \"description\": \"Kilobytes Einheit\"\n },\n \"megabytesUnit\": {\n \"message\": \"MB\",\n \"description\": \"Megabytes Einheit\"\n },\n \"gigabytesUnit\": {\n \"message\": \"GB\",\n \"description\": \"Gigabytes Einheit\"\n },\n \"itemsUnit\": {\n \"message\": \"Elemente\",\n \"description\": \"Elemente Zähleinheit\"\n },\n \"pagesUnit\": {\n \"message\": \"Seiten\",\n \"description\": \"Seiten Zähleinheit\"\n }\n}" }, { "path": "app/chrome-extension/_locales/en/messages.json", "content": "{\n \"extensionName\": {\n \"message\": \"chrome-mcp-server\",\n \"description\": \"Extension name\"\n },\n \"extensionDescription\": {\n \"message\": \"Exposes browser capabilities with your own chrome\",\n \"description\": \"Extension description\"\n },\n \"nativeServerConfigLabel\": {\n \"message\": \"Native Server Configuration\",\n \"description\": \"Main section header for native server settings\"\n },\n \"semanticEngineLabel\": {\n \"message\": \"Semantic Engine\",\n \"description\": \"Main section header for semantic engine\"\n },\n \"embeddingModelLabel\": {\n \"message\": \"Embedding Model\",\n \"description\": \"Main section header for model selection\"\n },\n \"indexDataManagementLabel\": {\n \"message\": \"Index Data Management\",\n \"description\": \"Main section header for data management\"\n },\n \"modelCacheManagementLabel\": {\n \"message\": \"Model Cache Management\",\n \"description\": \"Main section header for cache management\"\n },\n \"statusLabel\": {\n \"message\": \"Status\",\n \"description\": \"Generic status label\"\n },\n \"runningStatusLabel\": {\n \"message\": \"Running Status\",\n \"description\": \"Server running status label\"\n },\n \"connectionStatusLabel\": {\n \"message\": \"Connection Status\",\n \"description\": \"Connection status label\"\n },\n \"lastUpdatedLabel\": {\n \"message\": \"Last Updated:\",\n \"description\": \"Last updated timestamp label\"\n },\n \"connectButton\": {\n \"message\": \"Connect\",\n \"description\": \"Connect button text\"\n },\n \"disconnectButton\": {\n \"message\": \"Disconnect\",\n \"description\": \"Disconnect button text\"\n },\n \"connectingStatus\": {\n \"message\": \"Connecting...\",\n \"description\": \"Connecting status message\"\n },\n \"connectedStatus\": {\n \"message\": \"Connected\",\n \"description\": \"Connected status message\"\n },\n \"disconnectedStatus\": {\n \"message\": \"Disconnected\",\n \"description\": \"Disconnected status message\"\n },\n \"detectingStatus\": {\n \"message\": \"Detecting...\",\n \"description\": \"Detecting status message\"\n },\n \"serviceRunningStatus\": {\n \"message\": \"Service Running (Port: $PORT$)\",\n \"description\": \"Service running with port number\",\n \"placeholders\": {\n \"port\": {\n \"content\": \"$1\",\n \"example\": \"12306\"\n }\n }\n },\n \"serviceNotConnectedStatus\": {\n \"message\": \"Service Not Connected\",\n \"description\": \"Service not connected status\"\n },\n \"connectedServiceNotStartedStatus\": {\n \"message\": \"Connected, Service Not Started\",\n \"description\": \"Connected but service not started status\"\n },\n \"mcpServerConfigLabel\": {\n \"message\": \"MCP Server Configuration\",\n \"description\": \"MCP server configuration section label\"\n },\n \"connectionPortLabel\": {\n \"message\": \"Connection Port\",\n \"description\": \"Connection port input label\"\n },\n \"refreshStatusButton\": {\n \"message\": \"Refresh Status\",\n \"description\": \"Refresh status button tooltip\"\n },\n \"copyConfigButton\": {\n \"message\": \"Copy Configuration\",\n \"description\": \"Copy configuration button text\"\n },\n \"retryButton\": {\n \"message\": \"Retry\",\n \"description\": \"Retry button text\"\n },\n \"cancelButton\": {\n \"message\": \"Cancel\",\n \"description\": \"Cancel button text\"\n },\n \"confirmButton\": {\n \"message\": \"Confirm\",\n \"description\": \"Confirm button text\"\n },\n \"saveButton\": {\n \"message\": \"Save\",\n \"description\": \"Save button text\"\n },\n \"closeButton\": {\n \"message\": \"Close\",\n \"description\": \"Close button text\"\n },\n \"resetButton\": {\n \"message\": \"Reset\",\n \"description\": \"Reset button text\"\n },\n \"initializingStatus\": {\n \"message\": \"Initializing...\",\n \"description\": \"Initializing progress message\"\n },\n \"processingStatus\": {\n \"message\": \"Processing...\",\n \"description\": \"Processing progress message\"\n },\n \"loadingStatus\": {\n \"message\": \"Loading...\",\n \"description\": \"Loading progress message\"\n },\n \"clearingStatus\": {\n \"message\": \"Clearing...\",\n \"description\": \"Clearing progress message\"\n },\n \"cleaningStatus\": {\n \"message\": \"Cleaning...\",\n \"description\": \"Cleaning progress message\"\n },\n \"downloadingStatus\": {\n \"message\": \"Downloading...\",\n \"description\": \"Downloading progress message\"\n },\n \"semanticEngineReadyStatus\": {\n \"message\": \"Semantic Engine Ready\",\n \"description\": \"Semantic engine ready status\"\n },\n \"semanticEngineInitializingStatus\": {\n \"message\": \"Semantic Engine Initializing...\",\n \"description\": \"Semantic engine initializing status\"\n },\n \"semanticEngineInitFailedStatus\": {\n \"message\": \"Semantic Engine Initialization Failed\",\n \"description\": \"Semantic engine initialization failed status\"\n },\n \"semanticEngineNotInitStatus\": {\n \"message\": \"Semantic Engine Not Initialized\",\n \"description\": \"Semantic engine not initialized status\"\n },\n \"initSemanticEngineButton\": {\n \"message\": \"Initialize Semantic Engine\",\n \"description\": \"Initialize semantic engine button text\"\n },\n \"reinitializeButton\": {\n \"message\": \"Reinitialize\",\n \"description\": \"Reinitialize button text\"\n },\n \"downloadingModelStatus\": {\n \"message\": \"Downloading Model... $PROGRESS$%\",\n \"description\": \"Model download progress with percentage\",\n \"placeholders\": {\n \"progress\": {\n \"content\": \"$1\",\n \"example\": \"50\"\n }\n }\n },\n \"switchingModelStatus\": {\n \"message\": \"Switching Model...\",\n \"description\": \"Model switching progress message\"\n },\n \"modelLoadedStatus\": {\n \"message\": \"Model Loaded\",\n \"description\": \"Model successfully loaded status\"\n },\n \"modelFailedStatus\": {\n \"message\": \"Model Failed to Load\",\n \"description\": \"Model failed to load status\"\n },\n \"lightweightModelDescription\": {\n \"message\": \"Lightweight Multilingual Model\",\n \"description\": \"Description for lightweight model option\"\n },\n \"betterThanSmallDescription\": {\n \"message\": \"Slightly larger than e5-small, but better performance\",\n \"description\": \"Description for medium model option\"\n },\n \"multilingualModelDescription\": {\n \"message\": \"Multilingual Semantic Model\",\n \"description\": \"Description for multilingual model option\"\n },\n \"fastPerformance\": {\n \"message\": \"Fast\",\n \"description\": \"Fast performance indicator\"\n },\n \"balancedPerformance\": {\n \"message\": \"Balanced\",\n \"description\": \"Balanced performance indicator\"\n },\n \"accuratePerformance\": {\n \"message\": \"Accurate\",\n \"description\": \"Accurate performance indicator\"\n },\n \"networkErrorMessage\": {\n \"message\": \"Network connection error, please check network and retry\",\n \"description\": \"Network connection error message\"\n },\n \"modelCorruptedErrorMessage\": {\n \"message\": \"Model file corrupted or incomplete, please retry download\",\n \"description\": \"Model corruption error message\"\n },\n \"unknownErrorMessage\": {\n \"message\": \"Unknown error, please check if your network can access HuggingFace\",\n \"description\": \"Unknown error fallback message\"\n },\n \"permissionDeniedErrorMessage\": {\n \"message\": \"Permission denied\",\n \"description\": \"Permission denied error message\"\n },\n \"timeoutErrorMessage\": {\n \"message\": \"Operation timed out\",\n \"description\": \"Timeout error message\"\n },\n \"indexedPagesLabel\": {\n \"message\": \"Indexed Pages\",\n \"description\": \"Number of indexed pages label\"\n },\n \"indexSizeLabel\": {\n \"message\": \"Index Size\",\n \"description\": \"Index size label\"\n },\n \"activeTabsLabel\": {\n \"message\": \"Active Tabs\",\n \"description\": \"Number of active tabs label\"\n },\n \"vectorDocumentsLabel\": {\n \"message\": \"Vector Documents\",\n \"description\": \"Number of vector documents label\"\n },\n \"cacheSizeLabel\": {\n \"message\": \"Cache Size\",\n \"description\": \"Cache size label\"\n },\n \"cacheEntriesLabel\": {\n \"message\": \"Cache Entries\",\n \"description\": \"Number of cache entries label\"\n },\n \"clearAllDataButton\": {\n \"message\": \"Clear All Data\",\n \"description\": \"Clear all data button text\"\n },\n \"clearAllCacheButton\": {\n \"message\": \"Clear All Cache\",\n \"description\": \"Clear all cache button text\"\n },\n \"cleanExpiredCacheButton\": {\n \"message\": \"Clean Expired Cache\",\n \"description\": \"Clean expired cache button text\"\n },\n \"exportDataButton\": {\n \"message\": \"Export Data\",\n \"description\": \"Export data button text\"\n },\n \"importDataButton\": {\n \"message\": \"Import Data\",\n \"description\": \"Import data button text\"\n },\n \"confirmClearDataTitle\": {\n \"message\": \"Confirm Clear Data\",\n \"description\": \"Clear data confirmation dialog title\"\n },\n \"settingsTitle\": {\n \"message\": \"Settings\",\n \"description\": \"Settings dialog title\"\n },\n \"aboutTitle\": {\n \"message\": \"About\",\n \"description\": \"About dialog title\"\n },\n \"helpTitle\": {\n \"message\": \"Help\",\n \"description\": \"Help dialog title\"\n },\n \"clearDataWarningMessage\": {\n \"message\": \"This operation will clear all indexed webpage content and vector data, including:\",\n \"description\": \"Clear data warning message\"\n },\n \"clearDataList1\": {\n \"message\": \"All webpage text content index\",\n \"description\": \"First item in clear data list\"\n },\n \"clearDataList2\": {\n \"message\": \"Vector embedding data\",\n \"description\": \"Second item in clear data list\"\n },\n \"clearDataList3\": {\n \"message\": \"Search history and cache\",\n \"description\": \"Third item in clear data list\"\n },\n \"clearDataIrreversibleWarning\": {\n \"message\": \"This operation is irreversible! After clearing, you need to browse webpages again to rebuild the index.\",\n \"description\": \"Irreversible operation warning\"\n },\n \"confirmClearButton\": {\n \"message\": \"Confirm Clear\",\n \"description\": \"Confirm clear action button\"\n },\n \"cacheDetailsLabel\": {\n \"message\": \"Cache Details\",\n \"description\": \"Cache details section label\"\n },\n \"noCacheDataMessage\": {\n \"message\": \"No cache data\",\n \"description\": \"No cache data available message\"\n },\n \"loadingCacheInfoStatus\": {\n \"message\": \"Loading cache information...\",\n \"description\": \"Loading cache information status\"\n },\n \"processingCacheStatus\": {\n \"message\": \"Processing cache...\",\n \"description\": \"Processing cache status\"\n },\n \"expiredLabel\": {\n \"message\": \"Expired\",\n \"description\": \"Expired item label\"\n },\n \"bookmarksBarLabel\": {\n \"message\": \"Bookmarks Bar\",\n \"description\": \"Bookmarks bar folder name\"\n },\n \"newTabLabel\": {\n \"message\": \"New Tab\",\n \"description\": \"New tab label\"\n },\n \"currentPageLabel\": {\n \"message\": \"Current Page\",\n \"description\": \"Current page label\"\n },\n \"menuLabel\": {\n \"message\": \"Menu\",\n \"description\": \"Menu accessibility label\"\n },\n \"navigationLabel\": {\n \"message\": \"Navigation\",\n \"description\": \"Navigation accessibility label\"\n },\n \"mainContentLabel\": {\n \"message\": \"Main Content\",\n \"description\": \"Main content accessibility label\"\n },\n \"languageSelectorLabel\": {\n \"message\": \"Language\",\n \"description\": \"Language selector label\"\n },\n \"themeLabel\": {\n \"message\": \"Theme\",\n \"description\": \"Theme selector label\"\n },\n \"lightTheme\": {\n \"message\": \"Light\",\n \"description\": \"Light theme option\"\n },\n \"darkTheme\": {\n \"message\": \"Dark\",\n \"description\": \"Dark theme option\"\n },\n \"autoTheme\": {\n \"message\": \"Auto\",\n \"description\": \"Auto theme option\"\n },\n \"advancedSettingsLabel\": {\n \"message\": \"Advanced Settings\",\n \"description\": \"Advanced settings section label\"\n },\n \"debugModeLabel\": {\n \"message\": \"Debug Mode\",\n \"description\": \"Debug mode toggle label\"\n },\n \"verboseLoggingLabel\": {\n \"message\": \"Verbose Logging\",\n \"description\": \"Verbose logging toggle label\"\n },\n \"successNotification\": {\n \"message\": \"Operation completed successfully\",\n \"description\": \"Generic success notification\"\n },\n \"warningNotification\": {\n \"message\": \"Warning: Please review before proceeding\",\n \"description\": \"Generic warning notification\"\n },\n \"infoNotification\": {\n \"message\": \"Information\",\n \"description\": \"Generic info notification\"\n },\n \"configCopiedNotification\": {\n \"message\": \"Configuration copied to clipboard\",\n \"description\": \"Configuration copied success message\"\n },\n \"dataClearedNotification\": {\n \"message\": \"Data cleared successfully\",\n \"description\": \"Data cleared success message\"\n },\n \"bytesUnit\": {\n \"message\": \"bytes\",\n \"description\": \"Bytes unit\"\n },\n \"kilobytesUnit\": {\n \"message\": \"KB\",\n \"description\": \"Kilobytes unit\"\n },\n \"megabytesUnit\": {\n \"message\": \"MB\",\n \"description\": \"Megabytes unit\"\n },\n \"gigabytesUnit\": {\n \"message\": \"GB\",\n \"description\": \"Gigabytes unit\"\n },\n \"itemsUnit\": {\n \"message\": \"items\",\n \"description\": \"Items count unit\"\n },\n \"pagesUnit\": {\n \"message\": \"pages\",\n \"description\": \"Pages count unit\"\n },\n \"userscriptsManagerTitle\": {\n \"message\": \"Userscripts Manager\",\n \"description\": \"Options page title\"\n },\n \"emergencySwitchLabel\": { \"message\": \"Emergency Switch\", \"description\": \"Global disable switch\" },\n \"createRunSectionTitle\": {\n \"message\": \"Create / Run\",\n \"description\": \"Create & run section title\"\n },\n \"nameLabel\": { \"message\": \"Name\", \"description\": \"Name input label\" },\n \"runAtLabel\": { \"message\": \"Run At\", \"description\": \"runAt select label\" },\n \"runAtAuto\": { \"message\": \"auto\", \"description\": \"runAt auto\" },\n \"runAtDocumentStart\": { \"message\": \"document_start\", \"description\": \"runAt document_start\" },\n \"runAtDocumentEnd\": { \"message\": \"document_end\", \"description\": \"runAt document_end\" },\n \"runAtDocumentIdle\": { \"message\": \"document_idle\", \"description\": \"runAt document_idle\" },\n \"worldLabel\": { \"message\": \"World\", \"description\": \"world select label\" },\n \"worldAuto\": { \"message\": \"auto\", \"description\": \"world auto\" },\n \"worldIsolated\": { \"message\": \"ISOLATED\", \"description\": \"ISOLATED world\" },\n \"worldMain\": { \"message\": \"MAIN\", \"description\": \"MAIN world\" },\n \"modeLabel\": { \"message\": \"Mode\", \"description\": \"mode select label\" },\n \"modeAuto\": { \"message\": \"auto\", \"description\": \"mode auto\" },\n \"modePersistent\": { \"message\": \"persistent\", \"description\": \"mode persistent\" },\n \"modeCss\": { \"message\": \"css\", \"description\": \"mode css\" },\n \"modeOnce\": { \"message\": \"once\", \"description\": \"mode once\" },\n \"allFramesLabel\": { \"message\": \"All Frames\", \"description\": \"allFrames checkbox\" },\n \"persistLabel\": { \"message\": \"Persist\", \"description\": \"persist checkbox\" },\n \"dnrFallbackLabel\": { \"message\": \"DNR Fallback\", \"description\": \"dnr fallback checkbox\" },\n \"matchesInputLabel\": { \"message\": \"Matches (comma-separated)\", \"description\": \"matches input\" },\n \"excludesInputLabel\": {\n \"message\": \"Excludes (comma-separated)\",\n \"description\": \"excludes input\"\n },\n \"tagsInputLabel\": { \"message\": \"Tags (comma-separated)\", \"description\": \"tags input\" },\n \"scriptLabel\": { \"message\": \"Script\", \"description\": \"script textarea label\" },\n \"applyButton\": { \"message\": \"Apply\", \"description\": \"apply button\" },\n \"runOnceButton\": { \"message\": \"Run Once (CDP)\", \"description\": \"run once button\" },\n \"listSectionTitle\": { \"message\": \"List\", \"description\": \"list section title\" },\n \"queryLabel\": { \"message\": \"Query\", \"description\": \"query input label\" },\n \"statusAll\": { \"message\": \"all\", \"description\": \"status all\" },\n \"statusEnabled\": { \"message\": \"enabled\", \"description\": \"status enabled\" },\n \"statusDisabled\": { \"message\": \"disabled\", \"description\": \"status disabled\" },\n \"domainLabel\": { \"message\": \"Domain\", \"description\": \"domain filter label\" },\n \"exportAllButton\": { \"message\": \"Export All\", \"description\": \"export button\" },\n \"tableHeaderName\": { \"message\": \"Name\", \"description\": \"table header name\" },\n \"tableHeaderWorld\": { \"message\": \"World\", \"description\": \"table header world\" },\n \"tableHeaderRunAt\": { \"message\": \"Run At\", \"description\": \"table header runAt\" },\n \"tableHeaderUpdated\": { \"message\": \"Updated\", \"description\": \"table header updated\" },\n \"deleteButton\": { \"message\": \"Delete\", \"description\": \"delete button\" },\n \"placeholderOptional\": { \"message\": \"optional\", \"description\": \"generic optional placeholder\" },\n \"placeholderMatchesExample\": {\n \"message\": \"e.g. https://*.example.com/*\",\n \"description\": \"matches example placeholder\"\n },\n \"placeholderScriptHint\": {\n \"message\": \"Paste JS/CSS/TM here\",\n \"description\": \"script textarea placeholder\"\n },\n \"placeholderDomainHint\": { \"message\": \"example.com\", \"description\": \"domain filter placeholder\" }\n}\n" }, { "path": "app/chrome-extension/_locales/ja/messages.json", "content": "{\n \"extensionName\": {\n \"message\": \"Chrome MCPサーバー\"\n },\n \"extensionDescription\": {\n \"message\": \"自身のChromeブラウザの機能を外部に公開します\"\n },\n \"nativeServerConfigLabel\": {\n \"message\": \"ネイティブサーバー設定\"\n },\n \"semanticEngineLabel\": {\n \"message\": \"セマンティックエンジン\"\n },\n \"embeddingModelLabel\": {\n \"message\": \"埋め込みモデル\"\n },\n \"indexDataManagementLabel\": {\n \"message\": \"インデックスデータ管理\"\n },\n \"modelCacheManagementLabel\": {\n \"message\": \"モデルキャッシュ管理\"\n },\n \"statusLabel\": {\n \"message\": \"ステータス\"\n },\n \"runningStatusLabel\": {\n \"message\": \"実行ステータス\"\n },\n \"connectionStatusLabel\": {\n \"message\": \"接続ステータス\"\n },\n \"lastUpdatedLabel\": {\n \"message\": \"最終更新:\"\n },\n \"connectButton\": {\n \"message\": \"接続\"\n },\n \"disconnectButton\": {\n \"message\": \"切断\"\n },\n \"connectingStatus\": {\n \"message\": \"接続中...\"\n },\n \"connectedStatus\": {\n \"message\": \"接続済み\"\n },\n \"disconnectedStatus\": {\n \"message\": \"未接続\"\n },\n \"detectingStatus\": {\n \"message\": \"検出中...\"\n },\n \"serviceRunningStatus\": {\n \"message\": \"サービス実行中 (ポート: $1)\",\n \"placeholders\": {\n \"port\": {\n \"content\": \"$1\",\n \"example\": \"12306\"\n }\n }\n },\n \"serviceNotConnectedStatus\": {\n \"message\": \"サービス未接続\"\n },\n \"connectedServiceNotStartedStatus\": {\n \"message\": \"接続済み、サービス未起動\"\n },\n \"mcpServerConfigLabel\": {\n \"message\": \"MCPサーバー設定\"\n },\n \"connectionPortLabel\": {\n \"message\": \"接続ポート\"\n },\n \"refreshStatusButton\": {\n \"message\": \"ステータス更新\"\n },\n \"copyConfigButton\": {\n \"message\": \"設定をコピー\"\n },\n \"retryButton\": {\n \"message\": \"再試行\"\n },\n \"cancelButton\": {\n \"message\": \"キャンセル\"\n },\n \"confirmButton\": {\n \"message\": \"確認\"\n },\n \"saveButton\": {\n \"message\": \"保存\"\n },\n \"closeButton\": {\n \"message\": \"閉じる\"\n },\n \"resetButton\": {\n \"message\": \"リセット\"\n },\n \"initializingStatus\": {\n \"message\": \"初期化中...\"\n },\n \"processingStatus\": {\n \"message\": \"処理中...\"\n },\n \"loadingStatus\": {\n \"message\": \"読み込み中...\"\n },\n \"clearingStatus\": {\n \"message\": \"クリア中...\"\n },\n \"cleaningStatus\": {\n \"message\": \"クリーンアップ中...\"\n },\n \"downloadingStatus\": {\n \"message\": \"ダウンロード中...\"\n },\n \"semanticEngineReadyStatus\": {\n \"message\": \"セマンティックエンジン準備完了\"\n },\n \"semanticEngineInitializingStatus\": {\n \"message\": \"セマンティックエンジン初期化中...\"\n },\n \"semanticEngineInitFailedStatus\": {\n \"message\": \"セマンティックエンジンの初期化に失敗しました\"\n },\n \"semanticEngineNotInitStatus\": {\n \"message\": \"セマンティックエンジン未初期化\"\n },\n \"initSemanticEngineButton\": {\n \"message\": \"セマンティックエンジンを初期化\"\n },\n \"reinitializeButton\": {\n \"message\": \"再初期化\"\n },\n \"downloadingModelStatus\": {\n \"message\": \"モデルをダウンロード中... $1%\",\n \"placeholders\": {\n \"progress\": {\n \"content\": \"$1\",\n \"example\": \"50\"\n }\n }\n },\n \"switchingModelStatus\": {\n \"message\": \"モデルを切り替え中...\"\n },\n \"modelLoadedStatus\": {\n \"message\": \"モデル読み込み完了\"\n },\n \"modelFailedStatus\": {\n \"message\": \"モデルの読み込みに失敗しました\"\n },\n \"lightweightModelDescription\": {\n \"message\": \"軽量多言語モデル\"\n },\n \"betterThanSmallDescription\": {\n \"message\": \"e5-smallよりわずかに大きいが、性能は向上\"\n },\n \"multilingualModelDescription\": {\n \"message\": \"多言語対応セマンティックモデル\"\n },\n \"fastPerformance\": {\n \"message\": \"高速\"\n },\n \"balancedPerformance\": {\n \"message\": \"バランス\"\n },\n \"accuratePerformance\": {\n \"message\": \"高精度\"\n },\n \"networkErrorMessage\": {\n \"message\": \"ネットワーク接続エラーです。ネットワークを確認して再試行してください\"\n },\n \"modelCorruptedErrorMessage\": {\n \"message\": \"モデルファイルが破損しているか不完全です。再ダウンロードしてください\"\n },\n \"unknownErrorMessage\": {\n \"message\": \"不明なエラーです。ネットワークがHuggingFaceにアクセスできるか確認してください\"\n },\n \"permissionDeniedErrorMessage\": {\n \"message\": \"権限が拒否されました\"\n },\n \"timeoutErrorMessage\": {\n \"message\": \"操作がタイムアウトしました\"\n },\n \"indexedPagesLabel\": {\n \"message\": \"インデックス化されたページ\"\n },\n \"indexSizeLabel\": {\n \"message\": \"インデックスサイズ\"\n },\n \"activeTabsLabel\": {\n \"message\": \"アクティブなタブ\"\n },\n \"vectorDocumentsLabel\": {\n \"message\": \"ベクトルドキュメント\"\n },\n \"cacheSizeLabel\": {\n \"message\": \"キャッシュサイズ\"\n },\n \"cacheEntriesLabel\": {\n \"message\": \"キャッシュエントリ\"\n },\n \"clearAllDataButton\": {\n \"message\": \"全データをクリア\"\n },\n \"clearAllCacheButton\": {\n \"message\": \"全キャッシュをクリア\"\n },\n \"cleanExpiredCacheButton\": {\n \"message\": \"期限切れキャッシュをクリーンアップ\"\n },\n \"exportDataButton\": {\n \"message\": \"データのエクスポート\"\n },\n \"importDataButton\": {\n \"message\": \"データのインポート\"\n },\n \"confirmClearDataTitle\": {\n \"message\": \"データクリアの確認\"\n },\n \"settingsTitle\": {\n \"message\": \"設定\"\n },\n \"aboutTitle\": {\n \"message\": \"情報\"\n },\n \"helpTitle\": {\n \"message\": \"ヘルプ\"\n },\n \"clearDataWarningMessage\": {\n \"message\": \"この操作は、インデックス化されたすべてのウェブページコンテンツとベクトルデータをクリアします。これには以下が含まれます：\"\n },\n \"clearDataList1\": {\n \"message\": \"すべてのウェブページテキストコンテンツインデックス\"\n },\n \"clearDataList2\": {\n \"message\": \"ベクトル埋め込みデータ\"\n },\n \"clearDataList3\": {\n \"message\": \"検索履歴とキャッシュ\"\n },\n \"clearDataIrreversibleWarning\": {\n \"message\": \"この操作は元に戻せません！クリア後、再度ウェブページを閲覧してインデックスを再構築する必要があります。\"\n },\n \"confirmClearButton\": {\n \"message\": \"クリアを確認\"\n },\n \"cacheDetailsLabel\": {\n \"message\": \"キャッシュ詳細\"\n },\n \"noCacheDataMessage\": {\n \"message\": \"キャッシュデータがありません\"\n },\n \"loadingCacheInfoStatus\": {\n \"message\": \"キャッシュ情報を読み込み中...\"\n },\n \"processingCacheStatus\": {\n \"message\": \"キャッシュを処理中...\"\n },\n \"expiredLabel\": {\n \"message\": \"期限切れ\"\n },\n \"bookmarksBarLabel\": {\n \"message\": \"ブックマークバー\"\n },\n \"newTabLabel\": {\n \"message\": \"新しいタブ\"\n },\n \"currentPageLabel\": {\n \"message\": \"現在のページ\"\n },\n \"menuLabel\": {\n \"message\": \"メニュー\"\n },\n \"navigationLabel\": {\n \"message\": \"ナビゲーション\"\n },\n \"mainContentLabel\": {\n \"message\": \"メインコンテンツ\"\n },\n \"languageSelectorLabel\": {\n \"message\": \"言語\"\n },\n \"themeLabel\": {\n \"message\": \"テーマ\"\n },\n \"lightTheme\": {\n \"message\": \"ライト\"\n },\n \"darkTheme\": {\n \"message\": \"ダーク\"\n },\n \"autoTheme\": {\n \"message\": \"自動\"\n },\n \"advancedSettingsLabel\": {\n \"message\": \"詳細設定\"\n },\n \"debugModeLabel\": {\n \"message\": \"デバッグモード\"\n },\n \"verboseLoggingLabel\": {\n \"message\": \"詳細ロギング\"\n },\n \"successNotification\": {\n \"message\": \"操作が正常に完了しました\"\n },\n \"warningNotification\": {\n \"message\": \"警告：続行する前に確認してください\"\n },\n \"infoNotification\": {\n \"message\": \"情報\"\n },\n \"configCopiedNotification\": {\n \"message\": \"設定がクリップボードにコピーされました\"\n },\n \"dataClearedNotification\": {\n \"message\": \"データが正常にクリアされました\"\n },\n \"bytesUnit\": {\n \"message\": \"バイト\"\n },\n \"kilobytesUnit\": {\n \"message\": \"KB\"\n },\n \"megabytesUnit\": {\n \"message\": \"MB\"\n },\n \"gigabytesUnit\": {\n \"message\": \"GB\"\n },\n \"itemsUnit\": {\n \"message\": \"項目\"\n },\n \"pagesUnit\": {\n \"message\": \"ページ\"\n }\n}" }, { "path": "app/chrome-extension/_locales/ko/messages.json", "content": "{\n \"extensionName\": {\n \"message\": \"chrome-mcp-server\",\n \"description\": \"확장 프로그램 이름\"\n },\n \"extensionDescription\": {\n \"message\": \"크롬 브라우저와 연동하여 브라우저 기능을 제어하는 MCP 서버입니다.\",\n \"description\": \"확장 프로그램 설명\"\n },\n \"nativeServerConfigLabel\": {\n \"message\": \"네이티브 서버 설정\",\n \"description\": \"네이티브 서버 설정의 주 섹션 제목\"\n },\n \"semanticEngineLabel\": {\n \"message\": \"시맨틱 엔진\",\n \"description\": \"시맨틱 엔진의 주 섹션 제목\"\n },\n \"embeddingModelLabel\": {\n \"message\": \"임베딩 모델\",\n \"description\": \"모델 선택의 주 섹션 제목\"\n },\n \"indexDataManagementLabel\": {\n \"message\": \"인덱스 데이터 관리\",\n \"description\": \"데이터 관리의 주 섹션 제목\"\n },\n \"modelCacheManagementLabel\": {\n \"message\": \"모델 캐시 관리\",\n \"description\": \"캐시 관리의 주 섹션 제목\"\n },\n \"statusLabel\": {\n \"message\": \"상태\",\n \"description\": \"일반 상태 레이블\"\n },\n \"runningStatusLabel\": {\n \"message\": \"실행 상태\",\n \"description\": \"서버 실행 상태 레이블\"\n },\n \"connectionStatusLabel\": {\n \"message\": \"연결 상태\",\n \"description\": \"연결 상태 레이블\"\n },\n \"lastUpdatedLabel\": {\n \"message\": \"마지막 업데이트:\",\n \"description\": \"마지막 업데이트 타임스탬프 레이블\"\n },\n \"connectButton\": {\n \"message\": \"연결\",\n \"description\": \"연결 버튼 텍스트\"\n },\n \"disconnectButton\": {\n \"message\": \"연결 끊기\",\n \"description\": \"연결 끊기 버튼 텍스트\"\n },\n \"connectingStatus\": {\n \"message\": \"연결 중...\",\n \"description\": \"연결 상태 메시지\"\n },\n \"connectedStatus\": {\n \"message\": \"연결됨\",\n \"description\": \"연결된 상태 메시지\"\n },\n \"disconnectedStatus\": {\n \"message\": \"연결 끊김\",\n \"description\": \"연결이 끊긴 상태 메시지\"\n },\n \"detectingStatus\": {\n \"message\": \"감지 중...\",\n \"description\": \"감지 상태 메시지\"\n },\n \"serviceRunningStatus\": {\n \"message\": \"서비스 실행 중 (포트: $PORT$)\",\n \"description\": \"포트 번호와 함께 서비스 실행 중 상태\",\n \"placeholders\": {\n \"port\": {\n \"content\": \"$1\",\n \"example\": \"12306\"\n }\n }\n },\n \"serviceNotConnectedStatus\": {\n \"message\": \"서비스에 연결되지 않음\",\n \"description\": \"서비스가 연결되지 않은 상태\"\n },\n \"connectedServiceNotStartedStatus\": {\n \"message\": \"연결됨, 서비스 시작되지 않음\",\n \"description\": \"연결되었지만 서비스가 시작되지 않은 상태\"\n },\n \"mcpServerConfigLabel\": {\n \"message\": \"MCP 서버 설정\",\n \"description\": \"MCP 서버 설정 섹션 레이블\"\n },\n \"connectionPortLabel\": {\n \"message\": \"연결 포트\",\n \"description\": \"연결 포트 입력 레이블\"\n },\n \"refreshStatusButton\": {\n \"message\": \"상태 새로고침\",\n \"description\": \"상태 새로고침 버튼 툴팁\"\n },\n \"copyConfigButton\": {\n \"message\": \"설정 복사\",\n \"description\": \"설정 복사 버튼 텍스트\"\n },\n \"retryButton\": {\n \"message\": \"재시도\",\n \"description\": \"재시도 버튼 텍스트\"\n },\n \"cancelButton\": {\n \"message\": \"취소\",\n \"description\": \"취소 버튼 텍스트\"\n },\n \"confirmButton\": {\n \"message\": \"확인\",\n \"description\": \"확인 버튼 텍스트\"\n },\n \"saveButton\": {\n \"message\": \"저장\",\n \"description\": \"저장 버튼 텍스트\"\n },\n \"closeButton\": {\n \"message\": \"닫기\",\n \"description\": \"닫기 버튼 텍스트\"\n },\n \"resetButton\": {\n \"message\": \"초기화\",\n \"description\": \"초기화 버튼 텍스트\"\n },\n \"initializingStatus\": {\n \"message\": \"초기화 중...\",\n \"description\": \"초기화 진행 메시지\"\n },\n \"processingStatus\": {\n \"message\": \"처리 중...\",\n \"description\": \"처리 진행 메시지\"\n },\n \"loadingStatus\": {\n \"message\": \"로드 중...\",\n \"description\": \"로드 진행 메시지\"\n },\n \"clearingStatus\": {\n \"message\": \"삭제 중...\",\n \"description\": \"삭제 진행 메시지\"\n },\n \"cleaningStatus\": {\n \"message\": \"정리 중...\",\n \"description\": \"정리 진행 메시지\"\n },\n \"downloadingStatus\": {\n \"message\": \"다운로드 중...\",\n \"description\": \"다운로드 진행 메시지\"\n },\n \"semanticEngineReadyStatus\": {\n \"message\": \"시맨틱 엔진 준비 완료\",\n \"description\": \"시맨틱 엔진 준비 완료 상태\"\n },\n \"semanticEngineInitializingStatus\": {\n \"message\": \"시맨틱 엔진 초기화 중...\",\n \"description\": \"시맨틱 엔진 초기화 상태\"\n },\n \"semanticEngineInitFailedStatus\": {\n \"message\": \"시맨틱 엔진 초기화 실패\",\n \"description\": \"시맨틱 엔진 초기화 실패 상태\"\n },\n \"semanticEngineNotInitStatus\": {\n \"message\": \"시맨틱 엔진이 초기화되지 않음\",\n \"description\": \"시맨틱 엔진이 초기화되지 않은 상태\"\n },\n \"initSemanticEngineButton\": {\n \"message\": \"시맨틱 엔진 초기화\",\n \"description\": \"시맨틱 엔진 초기화 버튼 텍스트\"\n },\n \"reinitializeButton\": {\n \"message\": \"재초기화\",\n \"description\": \"재초기화 버튼 텍스트\"\n },\n \"downloadingModelStatus\": {\n \"message\": \"모델 다운로드 중... $PROGRESS$%\",\n \"description\": \"백분율이 포함된 모델 다운로드 진행 상태\",\n \"placeholders\": {\n \"progress\": {\n \"content\": \"$1\",\n \"example\": \"50\"\n }\n }\n },\n \"switchingModelStatus\": {\n \"message\": \"모델 전환 중...\",\n \"description\": \"모델 전환 진행 메시지\"\n },\n \"modelLoadedStatus\": {\n \"message\": \"모델 로드 완료\",\n \"description\": \"모델 로드 성공 상태\"\n },\n \"modelFailedStatus\": {\n \"message\": \"모델 로드 실패\",\n \"description\": \"모델 로드 실패 상태\"\n },\n \"lightweightModelDescription\": {\n \"message\": \"경량 다국어 모델\",\n \"description\": \"경량 모델 옵션 설명\"\n },\n \"betterThanSmallDescription\": {\n \"message\": \"e5-small보다 약간 크지만 성능이 더 좋습니다\",\n \"description\": \"중간 모델 옵션 설명\"\n },\n \"multilingualModelDescription\": {\n \"message\": \"다국어 시맨틱 모델\",\n \"description\": \"다국어 모델 옵션 설명\"\n },\n \"fastPerformance\": {\n \"message\": \"빠름\",\n \"description\": \"빠른 성능 표시\"\n },\n \"balancedPerformance\": {\n \"message\": \"균형\",\n \"description\": \"균형 잡힌 성능 표시\"\n },\n \"accuratePerformance\": {\n \"message\": \"정확\",\n \"description\": \"정확한 성능 표시\"\n },\n \"networkErrorMessage\": {\n \"message\": \"네트워크 연결 오류, 네트워크를 확인하고 다시 시도하세요\",\n \"description\": \"네트워크 연결 오류 메시지\"\n },\n \"modelCorruptedErrorMessage\": {\n \"message\": \"모델 파일이 손상되었거나 불완전합니다. 다운로드를 다시 시도하세요\",\n \"description\": \"모델 손상 오류 메시지\"\n },\n \"unknownErrorMessage\": {\n \"message\": \"알 수 없는 오류, 네트워크에서 HuggingFace에 접속할 수 있는지 확인하세요\",\n \"description\": \"알 수 없는 오류 대체 메시지\"\n },\n \"permissionDeniedErrorMessage\": {\n \"message\": \"권한이 거부되었습니다\",\n \"description\": \"권한 거부 오류 메시지\"\n },\n \"timeoutErrorMessage\": {\n \"message\": \"작업 시간 초과\",\n \"description\": \"시간 초과 오류 메시지\"\n },\n \"indexedPagesLabel\": {\n \"message\": \"인덱싱된 페이지\",\n \"description\": \"인덱싱된 페이지 수 레이블\"\n },\n \"indexSizeLabel\": {\n \"message\": \"인덱스 크기\",\n \"description\": \"인덱스 크기 레이블\"\n },\n \"activeTabsLabel\": {\n \"message\": \"활성 탭\",\n \"description\": \"활성 탭 수 레이블\"\n },\n \"vectorDocumentsLabel\": {\n \"message\": \"벡터 문서\",\n \"description\": \"벡터 문서 수 레이블\"\n },\n \"cacheSizeLabel\": {\n \"message\": \"캐시 크기\",\n \"description\": \"캐시 크기 레이블\"\n },\n \"cacheEntriesLabel\": {\n \"message\": \"캐시 항목\",\n \"description\": \"캐시 항목 수 레이블\"\n },\n \"clearAllDataButton\": {\n \"message\": \"모든 데이터 지우기\",\n \"description\": \"모든 데이터 지우기 버튼 텍스트\"\n },\n \"clearAllCacheButton\": {\n \"message\": \"모든 캐시 지우기\",\n \"description\": \"모든 캐시 지우기 버튼 텍스트\"\n },\n \"cleanExpiredCacheButton\": {\n \"message\": \"만료된 캐시 정리\",\n \"description\": \"만료된 캐시 정리 버튼 텍스트\"\n },\n \"exportDataButton\": {\n \"message\": \"데이터 내보내기\",\n \"description\": \"데이터 내보내기 버튼 텍스트\"\n },\n \"importDataButton\": {\n \"message\": \"데이터 가져오기\",\n \"description\": \"데이터 가져오기 버튼 텍스트\"\n },\n \"confirmClearDataTitle\": {\n \"message\": \"데이터 지우기 확인\",\n \"description\": \"데이터 지우기 확인 대화상자 제목\"\n },\n \"settingsTitle\": {\n \"message\": \"설정\",\n \"description\": \"설정 대화상자 제목\"\n },\n \"aboutTitle\": {\n \"message\": \"정보\",\n \"description\": \"정보 대화상자 제목\"\n },\n \"helpTitle\": {\n \"message\": \"도움말\",\n \"description\": \"도움말 대화상자 제목\"\n },\n \"clearDataWarningMessage\": {\n \"message\": \"이 작업은 다음을 포함한 모든 인덱싱된 웹페이지 콘텐츠와 벡터 데이터를 지웁니다:\",\n \"description\": \"데이터 지우기 경고 메시지\"\n },\n \"clearDataList1\": {\n \"message\": \"모든 웹페이지 텍스트 콘텐츠 인덱스\",\n \"description\": \"데이터 지우기 목록 첫 번째 항목\"\n },\n \"clearDataList2\": {\n \"message\": \"벡터 임베딩 데이터\",\n \"description\": \"데이터 지우기 목록 두 번째 항목\"\n },\n \"clearDataList3\": {\n \"message\": \"검색 기록 및 캐시\",\n \"description\": \"데이터 지우기 목록 세 번째 항목\"\n },\n \"clearDataIrreversibleWarning\": {\n \"message\": \"이 작업은 되돌릴 수 없습니다! 삭제 후에는 인덱스를 다시 생성하기 위해 웹페이지를 다시 방문해야 합니다.\",\n \"description\": \"되돌릴 수 없는 작업 경고\"\n },\n \"confirmClearButton\": {\n \"message\": \"삭제 확인\",\n \"description\": \"삭제 작업 확인 버튼\"\n },\n \"cacheDetailsLabel\": {\n \"message\": \"캐시 정보\",\n \"description\": \"캐시 정보 섹션 레이블\"\n },\n \"noCacheDataMessage\": {\n \"message\": \"캐시 데이터 없음\",\n \"description\": \"사용 가능한 캐시 데이터 없음 메시지\"\n },\n \"loadingCacheInfoStatus\": {\n \"message\": \"캐시 정보를 불러오는 중...\",\n \"description\": \"캐시 정보 로드 상태\"\n },\n \"processingCacheStatus\": {\n \"message\": \"캐시 처리 중...\",\n \"description\": \"캐시 처리 상태\"\n },\n \"expiredLabel\": {\n \"message\": \"만료됨\",\n \"description\": \"만료된 항목 레이블\"\n },\n \"bookmarksBarLabel\": {\n \"message\": \"북마크바\",\n \"description\": \"북마크바 폴더 이름\"\n },\n \"newTabLabel\": {\n \"message\": \"새 탭\",\n \"description\": \"새 탭 레이블\"\n },\n \"currentPageLabel\": {\n \"message\": \"현재 페이지\",\n \"description\": \"현재 페이지 레이블\"\n },\n \"menuLabel\": {\n \"message\": \"메뉴\",\n \"description\": \"메뉴 접근성 레이블\"\n },\n \"navigationLabel\": {\n \"message\": \"탐색\",\n \"description\": \"탐색 접근성 레이블\"\n },\n \"mainContentLabel\": {\n \"message\": \"주요 콘텐츠\",\n \"description\": \"주요 콘텐츠 접근성 레이블\"\n },\n \"languageSelectorLabel\": {\n \"message\": \"언어\",\n \"description\": \"언어 선택기 레이블\"\n },\n \"themeLabel\": {\n \"message\": \"테마\",\n \"description\": \"테마 선택기 레이블\"\n },\n \"lightTheme\": {\n \"message\": \"라이트\",\n \"description\": \"라이트 테마 옵션\"\n },\n \"darkTheme\": {\n \"message\": \"다크\",\n \"description\": \"다크 테마 옵션\"\n },\n \"autoTheme\": {\n \"message\": \"자동\",\n \"description\": \"자동 테마 옵션\"\n },\n \"advancedSettingsLabel\": {\n \"message\": \"고급 설정\",\n \"description\": \"고급 설정 섹션 레이블\"\n },\n \"debugModeLabel\": {\n \"message\": \"디버그 모드\",\n \"description\": \"디버그 모드 토글 레이블\"\n },\n \"verboseLoggingLabel\": {\n \"message\": \"상세 로깅\",\n \"description\": \"상세 로깅 토글 레이블\"\n },\n \"successNotification\": {\n \"message\": \"작업이 성공적으로 완료되었습니다\",\n \"description\": \"일반 성공 알림\"\n },\n \"warningNotification\": {\n \"message\": \"경고: 계속하기 전에 검토하세요\",\n \"description\": \"일반 경고 알림\"\n },\n \"infoNotification\": {\n \"message\": \"정보\",\n \"description\": \"일반 정보 알림\"\n },\n \"configCopiedNotification\": {\n \"message\": \"설정이 클립보드에 복사되었습니다\",\n \"description\": \"설정 복사 성공 메시지\"\n },\n \"dataClearedNotification\": {\n \"message\": \"데이터가 성공적으로 삭제되었습니다\",\n \"description\": \"데이터 삭제 성공 메시지\"\n },\n \"bytesUnit\": {\n \"message\": \"바이트\",\n \"description\": \"바이트 단위\"\n },\n \"kilobytesUnit\": {\n \"message\": \"KB\",\n \"description\": \"킬로바이트 단위\"\n },\n \"megabytesUnit\": {\n \"message\": \"MB\",\n \"description\": \"메가바이트 단위\"\n },\n \"gigabytesUnit\": {\n \"message\": \"GB\",\n \"description\": \"기가바이트 단위\"\n },\n \"itemsUnit\": {\n \"message\": \"개\",\n \"description\": \"항목 개수 단위\"\n },\n \"pagesUnit\": {\n \"message\": \"페이지\",\n \"description\": \"페이지 수 단위\"\n }\n}\n" }, { "path": "app/chrome-extension/_locales/zh_CN/messages.json", "content": "{\n \"extensionName\": {\n \"message\": \"chrome-mcp-server\",\n \"description\": \"扩展名称\"\n },\n \"extensionDescription\": {\n \"message\": \"使用你自己的 Chrome 浏览器暴露浏览器功能\",\n \"description\": \"扩展描述\"\n },\n \"nativeServerConfigLabel\": {\n \"message\": \"Native Server 配置\",\n \"description\": \"本地服务器设置的主要节标题\"\n },\n \"semanticEngineLabel\": {\n \"message\": \"语义引擎\",\n \"description\": \"语义引擎的主要节标题\"\n },\n \"embeddingModelLabel\": {\n \"message\": \"Embedding模型\",\n \"description\": \"模型选择的主要节标题\"\n },\n \"indexDataManagementLabel\": {\n \"message\": \"索引数据管理\",\n \"description\": \"数据管理的主要节标题\"\n },\n \"modelCacheManagementLabel\": {\n \"message\": \"模型缓存管理\",\n \"description\": \"缓存管理的主要节标题\"\n },\n \"statusLabel\": {\n \"message\": \"状态\",\n \"description\": \"通用状态标签\"\n },\n \"runningStatusLabel\": {\n \"message\": \"运行状态\",\n \"description\": \"服务器运行状态标签\"\n },\n \"connectionStatusLabel\": {\n \"message\": \"连接状态\",\n \"description\": \"连接状态标签\"\n },\n \"lastUpdatedLabel\": {\n \"message\": \"最后更新:\",\n \"description\": \"最后更新时间戳标签\"\n },\n \"connectButton\": {\n \"message\": \"连接\",\n \"description\": \"连接按钮文本\"\n },\n \"disconnectButton\": {\n \"message\": \"断开\",\n \"description\": \"断开连接按钮文本\"\n },\n \"connectingStatus\": {\n \"message\": \"连接中...\",\n \"description\": \"连接状态消息\"\n },\n \"connectedStatus\": {\n \"message\": \"已连接\",\n \"description\": \"已连接状态消息\"\n },\n \"disconnectedStatus\": {\n \"message\": \"已断开\",\n \"description\": \"已断开状态消息\"\n },\n \"detectingStatus\": {\n \"message\": \"检测中...\",\n \"description\": \"检测状态消息\"\n },\n \"serviceRunningStatus\": {\n \"message\": \"服务运行中 (端口: $PORT$)\",\n \"description\": \"带端口号的服务运行状态\",\n \"placeholders\": {\n \"port\": {\n \"content\": \"$1\",\n \"example\": \"12306\"\n }\n }\n },\n \"serviceNotConnectedStatus\": {\n \"message\": \"服务未连接\",\n \"description\": \"服务未连接状态\"\n },\n \"connectedServiceNotStartedStatus\": {\n \"message\": \"已连接，服务未启动\",\n \"description\": \"已连接但服务未启动状态\"\n },\n \"mcpServerConfigLabel\": {\n \"message\": \"MCP 服务器配置\",\n \"description\": \"MCP 服务器配置节标签\"\n },\n \"connectionPortLabel\": {\n \"message\": \"连接端口\",\n \"description\": \"连接端口输入标签\"\n },\n \"refreshStatusButton\": {\n \"message\": \"刷新状态\",\n \"description\": \"刷新状态按钮提示\"\n },\n \"copyConfigButton\": {\n \"message\": \"复制配置\",\n \"description\": \"复制配置按钮文本\"\n },\n \"retryButton\": {\n \"message\": \"重试\",\n \"description\": \"重试按钮文本\"\n },\n \"cancelButton\": {\n \"message\": \"取消\",\n \"description\": \"取消按钮文本\"\n },\n \"confirmButton\": {\n \"message\": \"确认\",\n \"description\": \"确认按钮文本\"\n },\n \"saveButton\": {\n \"message\": \"保存\",\n \"description\": \"保存按钮文本\"\n },\n \"closeButton\": {\n \"message\": \"关闭\",\n \"description\": \"关闭按钮文本\"\n },\n \"resetButton\": {\n \"message\": \"重置\",\n \"description\": \"重置按钮文本\"\n },\n \"initializingStatus\": {\n \"message\": \"初始化中...\",\n \"description\": \"初始化进度消息\"\n },\n \"processingStatus\": {\n \"message\": \"处理中...\",\n \"description\": \"处理进度消息\"\n },\n \"loadingStatus\": {\n \"message\": \"加载中...\",\n \"description\": \"加载进度消息\"\n },\n \"clearingStatus\": {\n \"message\": \"清空中...\",\n \"description\": \"清空进度消息\"\n },\n \"cleaningStatus\": {\n \"message\": \"清理中...\",\n \"description\": \"清理进度消息\"\n },\n \"downloadingStatus\": {\n \"message\": \"下载中...\",\n \"description\": \"下载进度消息\"\n },\n \"semanticEngineReadyStatus\": {\n \"message\": \"语义引擎已就绪\",\n \"description\": \"语义引擎就绪状态\"\n },\n \"semanticEngineInitializingStatus\": {\n \"message\": \"语义引擎初始化中...\",\n \"description\": \"语义引擎初始化状态\"\n },\n \"semanticEngineInitFailedStatus\": {\n \"message\": \"语义引擎初始化失败\",\n \"description\": \"语义引擎初始化失败状态\"\n },\n \"semanticEngineNotInitStatus\": {\n \"message\": \"语义引擎未初始化\",\n \"description\": \"语义引擎未初始化状态\"\n },\n \"initSemanticEngineButton\": {\n \"message\": \"初始化语义引擎\",\n \"description\": \"初始化语义引擎按钮文本\"\n },\n \"reinitializeButton\": {\n \"message\": \"重新初始化\",\n \"description\": \"重新初始化按钮文本\"\n },\n \"downloadingModelStatus\": {\n \"message\": \"下载模型中... $PROGRESS$%\",\n \"description\": \"带百分比的模型下载进度\",\n \"placeholders\": {\n \"progress\": {\n \"content\": \"$1\",\n \"example\": \"50\"\n }\n }\n },\n \"switchingModelStatus\": {\n \"message\": \"切换模型中...\",\n \"description\": \"模型切换进度消息\"\n },\n \"modelLoadedStatus\": {\n \"message\": \"模型已加载\",\n \"description\": \"模型成功加载状态\"\n },\n \"modelFailedStatus\": {\n \"message\": \"模型加载失败\",\n \"description\": \"模型加载失败状态\"\n },\n \"lightweightModelDescription\": {\n \"message\": \"轻量级多语言模型\",\n \"description\": \"轻量级模型选项的描述\"\n },\n \"betterThanSmallDescription\": {\n \"message\": \"比e5-small稍大，但效果更好\",\n \"description\": \"中等模型选项的描述\"\n },\n \"multilingualModelDescription\": {\n \"message\": \"多语言语义模型\",\n \"description\": \"多语言模型选项的描述\"\n },\n \"fastPerformance\": {\n \"message\": \"快速\",\n \"description\": \"快速性能指示器\"\n },\n \"balancedPerformance\": {\n \"message\": \"平衡\",\n \"description\": \"平衡性能指示器\"\n },\n \"accuratePerformance\": {\n \"message\": \"精确\",\n \"description\": \"精确性能指示器\"\n },\n \"networkErrorMessage\": {\n \"message\": \"网络连接错误，请检查网络连接后重试\",\n \"description\": \"网络连接错误消息\"\n },\n \"modelCorruptedErrorMessage\": {\n \"message\": \"模型文件损坏或不完整，请重试下载\",\n \"description\": \"模型损坏错误消息\"\n },\n \"unknownErrorMessage\": {\n \"message\": \"未知错误，请检查你的网络是否可以访问HuggingFace\",\n \"description\": \"未知错误回退消息\"\n },\n \"permissionDeniedErrorMessage\": {\n \"message\": \"权限被拒绝\",\n \"description\": \"权限被拒绝错误消息\"\n },\n \"timeoutErrorMessage\": {\n \"message\": \"操作超时\",\n \"description\": \"超时错误消息\"\n },\n \"indexedPagesLabel\": {\n \"message\": \"已索引页面\",\n \"description\": \"已索引页面数量标签\"\n },\n \"indexSizeLabel\": {\n \"message\": \"索引大小\",\n \"description\": \"索引大小标签\"\n },\n \"activeTabsLabel\": {\n \"message\": \"活跃标签页\",\n \"description\": \"活跃标签页数量标签\"\n },\n \"vectorDocumentsLabel\": {\n \"message\": \"向量文档\",\n \"description\": \"向量文档数量标签\"\n },\n \"cacheSizeLabel\": {\n \"message\": \"缓存大小\",\n \"description\": \"缓存大小标签\"\n },\n \"cacheEntriesLabel\": {\n \"message\": \"缓存条目\",\n \"description\": \"缓存条目数量标签\"\n },\n \"clearAllDataButton\": {\n \"message\": \"清空所有数据\",\n \"description\": \"清空所有数据按钮文本\"\n },\n \"clearAllCacheButton\": {\n \"message\": \"清空所有缓存\",\n \"description\": \"清空所有缓存按钮文本\"\n },\n \"cleanExpiredCacheButton\": {\n \"message\": \"清理过期缓存\",\n \"description\": \"清理过期缓存按钮文本\"\n },\n \"exportDataButton\": {\n \"message\": \"导出数据\",\n \"description\": \"导出数据按钮文本\"\n },\n \"importDataButton\": {\n \"message\": \"导入数据\",\n \"description\": \"导入数据按钮文本\"\n },\n \"confirmClearDataTitle\": {\n \"message\": \"确认清空数据\",\n \"description\": \"清空数据确认对话框标题\"\n },\n \"settingsTitle\": {\n \"message\": \"设置\",\n \"description\": \"设置对话框标题\"\n },\n \"aboutTitle\": {\n \"message\": \"关于\",\n \"description\": \"关于对话框标题\"\n },\n \"helpTitle\": {\n \"message\": \"帮助\",\n \"description\": \"帮助对话框标题\"\n },\n \"clearDataWarningMessage\": {\n \"message\": \"此操作将清空所有已索引的网页内容和向量数据，包括：\",\n \"description\": \"清空数据警告消息\"\n },\n \"clearDataList1\": {\n \"message\": \"所有网页的文本内容索引\",\n \"description\": \"清空数据列表第一项\"\n },\n \"clearDataList2\": {\n \"message\": \"向量嵌入数据\",\n \"description\": \"清空数据列表第二项\"\n },\n \"clearDataList3\": {\n \"message\": \"搜索历史和缓存\",\n \"description\": \"清空数据列表第三项\"\n },\n \"clearDataIrreversibleWarning\": {\n \"message\": \"此操作不可撤销！清空后需要重新浏览网页来重建索引。\",\n \"description\": \"不可逆操作警告\"\n },\n \"confirmClearButton\": {\n \"message\": \"确认清空\",\n \"description\": \"确认清空操作按钮\"\n },\n \"cacheDetailsLabel\": {\n \"message\": \"缓存详情\",\n \"description\": \"缓存详情节标签\"\n },\n \"noCacheDataMessage\": {\n \"message\": \"暂无缓存数据\",\n \"description\": \"无缓存数据可用消息\"\n },\n \"loadingCacheInfoStatus\": {\n \"message\": \"正在加载缓存信息...\",\n \"description\": \"加载缓存信息状态\"\n },\n \"processingCacheStatus\": {\n \"message\": \"处理缓存中...\",\n \"description\": \"处理缓存状态\"\n },\n \"expiredLabel\": {\n \"message\": \"已过期\",\n \"description\": \"过期项标签\"\n },\n \"bookmarksBarLabel\": {\n \"message\": \"书签栏\",\n \"description\": \"书签栏文件夹名称\"\n },\n \"newTabLabel\": {\n \"message\": \"新标签页\",\n \"description\": \"新标签页标签\"\n },\n \"currentPageLabel\": {\n \"message\": \"当前页面\",\n \"description\": \"当前页面标签\"\n },\n \"menuLabel\": {\n \"message\": \"菜单\",\n \"description\": \"菜单辅助功能标签\"\n },\n \"navigationLabel\": {\n \"message\": \"导航\",\n \"description\": \"导航辅助功能标签\"\n },\n \"mainContentLabel\": {\n \"message\": \"主要内容\",\n \"description\": \"主要内容辅助功能标签\"\n },\n \"languageSelectorLabel\": {\n \"message\": \"语言\",\n \"description\": \"语言选择器标签\"\n },\n \"themeLabel\": {\n \"message\": \"主题\",\n \"description\": \"主题选择器标签\"\n },\n \"lightTheme\": {\n \"message\": \"浅色\",\n \"description\": \"浅色主题选项\"\n },\n \"darkTheme\": {\n \"message\": \"深色\",\n \"description\": \"深色主题选项\"\n },\n \"autoTheme\": {\n \"message\": \"自动\",\n \"description\": \"自动主题选项\"\n },\n \"advancedSettingsLabel\": {\n \"message\": \"高级设置\",\n \"description\": \"高级设置节标签\"\n },\n \"debugModeLabel\": {\n \"message\": \"调试模式\",\n \"description\": \"调试模式切换标签\"\n },\n \"verboseLoggingLabel\": {\n \"message\": \"详细日志\",\n \"description\": \"详细日志切换标签\"\n },\n \"successNotification\": {\n \"message\": \"操作成功完成\",\n \"description\": \"通用成功通知\"\n },\n \"warningNotification\": {\n \"message\": \"警告：请在继续之前检查\",\n \"description\": \"通用警告通知\"\n },\n \"infoNotification\": {\n \"message\": \"信息\",\n \"description\": \"通用信息通知\"\n },\n \"configCopiedNotification\": {\n \"message\": \"配置已复制到剪贴板\",\n \"description\": \"配置复制成功消息\"\n },\n \"dataClearedNotification\": {\n \"message\": \"数据清空成功\",\n \"description\": \"数据清空成功消息\"\n },\n \"bytesUnit\": {\n \"message\": \"字节\",\n \"description\": \"字节单位\"\n },\n \"kilobytesUnit\": {\n \"message\": \"KB\",\n \"description\": \"千字节单位\"\n },\n \"megabytesUnit\": {\n \"message\": \"MB\",\n \"description\": \"兆字节单位\"\n },\n \"gigabytesUnit\": {\n \"message\": \"GB\",\n \"description\": \"吉字节单位\"\n },\n \"itemsUnit\": {\n \"message\": \"项\",\n \"description\": \"项目计数单位\"\n },\n \"pagesUnit\": {\n \"message\": \"页\",\n \"description\": \"页面计数单位\"\n },\n \"userscriptsManagerTitle\": { \"message\": \"脚本管理器\", \"description\": \"Options 页标题\" },\n \"emergencySwitchLabel\": { \"message\": \"紧急开关\", \"description\": \"紧急关闭开关\" },\n \"createRunSectionTitle\": { \"message\": \"创建 / 运行\", \"description\": \"创建与运行分区标题\" },\n \"nameLabel\": { \"message\": \"名称\", \"description\": \"名称输入标签\" },\n \"runAtLabel\": { \"message\": \"运行时机\", \"description\": \"runAt 选择标签\" },\n \"runAtAuto\": { \"message\": \"自动\", \"description\": \"runAt auto\" },\n \"runAtDocumentStart\": { \"message\": \"document_start\", \"description\": \"runAt document_start\" },\n \"runAtDocumentEnd\": { \"message\": \"document_end\", \"description\": \"runAt document_end\" },\n \"runAtDocumentIdle\": { \"message\": \"document_idle\", \"description\": \"runAt document_idle\" },\n \"worldLabel\": { \"message\": \"执行上下文\", \"description\": \"world 选择标签\" },\n \"worldAuto\": { \"message\": \"自动\", \"description\": \"world auto\" },\n \"worldIsolated\": { \"message\": \"隔离 (ISOLATED)\", \"description\": \"ISOLATED world\" },\n \"worldMain\": { \"message\": \"页面 (MAIN)\", \"description\": \"MAIN world\" },\n \"modeLabel\": { \"message\": \"模式\", \"description\": \"模式选择标签\" },\n \"modeAuto\": { \"message\": \"自动\", \"description\": \"mode auto\" },\n \"modePersistent\": { \"message\": \"持久\", \"description\": \"mode persistent\" },\n \"modeCss\": { \"message\": \"仅样式 (CSS)\", \"description\": \"mode css\" },\n \"modeOnce\": { \"message\": \"一次运行 (CDP)\", \"description\": \"mode once\" },\n \"allFramesLabel\": { \"message\": \"全部 frame\", \"description\": \"allFrames 复选框\" },\n \"persistLabel\": { \"message\": \"持久化\", \"description\": \"persist 复选框\" },\n \"dnrFallbackLabel\": { \"message\": \"DNR 回退\", \"description\": \"DNR fallback 复选框\" },\n \"matchesInputLabel\": { \"message\": \"匹配（逗号分隔）\", \"description\": \"matches 输入\" },\n \"excludesInputLabel\": { \"message\": \"排除（逗号分隔）\", \"description\": \"excludes 输入\" },\n \"tagsInputLabel\": { \"message\": \"标签（逗号分隔）\", \"description\": \"tags 输入\" },\n \"scriptLabel\": { \"message\": \"脚本\", \"description\": \"脚本文本标签\" },\n \"applyButton\": { \"message\": \"应用\", \"description\": \"应用按钮\" },\n \"runOnceButton\": { \"message\": \"一次运行（CDP）\", \"description\": \"一次运行按钮\" },\n \"listSectionTitle\": { \"message\": \"脚本列表\", \"description\": \"列表分区标题\" },\n \"queryLabel\": { \"message\": \"搜索\", \"description\": \"查询输入标签\" },\n \"statusAll\": { \"message\": \"全部\", \"description\": \"状态-全部\" },\n \"statusEnabled\": { \"message\": \"启用\", \"description\": \"状态-启用\" },\n \"statusDisabled\": { \"message\": \"禁用\", \"description\": \"状态-禁用\" },\n \"domainLabel\": { \"message\": \"域名\", \"description\": \"域名过滤标签\" },\n \"exportAllButton\": { \"message\": \"导出全部\", \"description\": \"导出按钮\" },\n \"tableHeaderName\": { \"message\": \"名称\", \"description\": \"表头-名称\" },\n \"tableHeaderWorld\": { \"message\": \"执行上下文\", \"description\": \"表头-World\" },\n \"tableHeaderRunAt\": { \"message\": \"运行时机\", \"description\": \"表头-RunAt\" },\n \"tableHeaderUpdated\": { \"message\": \"更新时间\", \"description\": \"表头-更新时间\" },\n \"deleteButton\": { \"message\": \"删除\", \"description\": \"删除按钮\" },\n \"placeholderOptional\": { \"message\": \"可选\", \"description\": \"通用可选占位符\" },\n \"placeholderMatchesExample\": {\n \"message\": \"例如：https://*.example.com/*\",\n \"description\": \"匹配示例占位符\"\n },\n \"placeholderScriptHint\": { \"message\": \"在此粘贴 JS/CSS/TM\", \"description\": \"脚本文本域占位符\" },\n \"placeholderDomainHint\": { \"message\": \"example.com\", \"description\": \"域名筛选占位符\" }\n}\n" }, { "path": "app/chrome-extension/_locales/zh_TW/messages.json", "content": "{\n \"extensionName\": {\n \"message\": \"chrome-mcp-server\",\n \"description\": \"擴充功能名稱\"\n },\n \"extensionDescription\": {\n \"message\": \"使用您自己的 Chrome 瀏覽器暴露瀏覽器功能\",\n \"description\": \"擴充功能描述\"\n },\n \"nativeServerConfigLabel\": {\n \"message\": \"原生伺服器設定\",\n \"description\": \"本機伺服器設定的主要區段標題\"\n },\n \"semanticEngineLabel\": {\n \"message\": \"語意引擎\",\n \"description\": \"語意引擎的主要區段標題\"\n },\n \"embeddingModelLabel\": {\n \"message\": \"Embedding 模型\",\n \"description\": \"模型選擇的主要區段標題\"\n },\n \"indexDataManagementLabel\": {\n \"message\": \"索引資料管理\",\n \"description\": \"資料管理主要區段標題\"\n },\n \"modelCacheManagementLabel\": {\n \"message\": \"模型快取管理\",\n \"description\": \"快取管理主要區段標題\"\n },\n \"statusLabel\": {\n \"message\": \"狀態\",\n \"description\": \"通用狀態標籤\"\n },\n \"runningStatusLabel\": {\n \"message\": \"執行狀態\",\n \"description\": \"伺服器執行狀態標籤\"\n },\n \"connectionStatusLabel\": {\n \"message\": \"連線狀態\",\n \"description\": \"連線狀態標籤\"\n },\n \"lastUpdatedLabel\": {\n \"message\": \"最後更新：\",\n \"description\": \"最後更新時間戳標籤\"\n },\n \"connectButton\": {\n \"message\": \"連線\",\n \"description\": \"連線按鈕文字\"\n },\n \"disconnectButton\": {\n \"message\": \"中斷連線\",\n \"description\": \"中斷連線按鈕文字\"\n },\n \"connectingStatus\": {\n \"message\": \"連線中...\",\n \"description\": \"連線狀態訊息\"\n },\n \"connectedStatus\": {\n \"message\": \"已連線\",\n \"description\": \"已連線狀態訊息\"\n },\n \"disconnectedStatus\": {\n \"message\": \"已中斷\",\n \"description\": \"已中斷狀態訊息\"\n },\n \"detectingStatus\": {\n \"message\": \"偵測中...\",\n \"description\": \"偵測狀態訊息\"\n },\n \"serviceRunningStatus\": {\n \"message\": \"服務執行中 (連結埠: $PORT$)\",\n \"description\": \"含連結埠號的服務執行狀態\",\n \"placeholders\": {\n \"port\": {\n \"content\": \"$1\",\n \"example\": \"12306\"\n }\n }\n },\n \"serviceNotConnectedStatus\": {\n \"message\": \"服務未連線\",\n \"description\": \"服務未連線狀態\"\n },\n \"connectedServiceNotStartedStatus\": {\n \"message\": \"已連線，服務未啟動\",\n \"description\": \"已連線但服務未啟動狀態\"\n },\n \"mcpServerConfigLabel\": {\n \"message\": \"MCP 伺服器設定\",\n \"description\": \"MCP 伺服器設定區段標籤\"\n },\n \"connectionPortLabel\": {\n \"message\": \"連結埠\",\n \"description\": \"連結埠輸入標籤\"\n },\n \"refreshStatusButton\": {\n \"message\": \"重新整理狀態\",\n \"description\": \"重新整理狀態按鈕提示\"\n },\n \"copyConfigButton\": {\n \"message\": \"複製設定\",\n \"description\": \"複製設定按鈕文字\"\n },\n \"retryButton\": {\n \"message\": \"重試\",\n \"description\": \"重試按鈕文字\"\n },\n \"cancelButton\": {\n \"message\": \"取消\",\n \"description\": \"取消按鈕文字\"\n },\n \"confirmButton\": {\n \"message\": \"確認\",\n \"description\": \"確認按鈕文字\"\n },\n \"saveButton\": {\n \"message\": \"儲存\",\n \"description\": \"儲存按鈕文字\"\n },\n \"closeButton\": {\n \"message\": \"關閉\",\n \"description\": \"關閉按鈕文字\"\n },\n \"resetButton\": {\n \"message\": \"重設\",\n \"description\": \"重設按鈕文字\"\n },\n \"initializingStatus\": {\n \"message\": \"初始化中...\",\n \"description\": \"初始化進度訊息\"\n },\n \"processingStatus\": {\n \"message\": \"處理中...\",\n \"description\": \"處理進度訊息\"\n },\n \"loadingStatus\": {\n \"message\": \"載入中...\",\n \"description\": \"載入進度訊息\"\n },\n \"clearingStatus\": {\n \"message\": \"清除中...\",\n \"description\": \"清除進度訊息\"\n },\n \"cleaningStatus\": {\n \"message\": \"清理中...\",\n \"description\": \"清理進度訊息\"\n },\n \"downloadingStatus\": {\n \"message\": \"下載中...\",\n \"description\": \"下載進度訊息\"\n },\n \"semanticEngineReadyStatus\": {\n \"message\": \"語意引擎已就緒\",\n \"description\": \"語意引擎就緒狀態\"\n },\n \"semanticEngineInitializingStatus\": {\n \"message\": \"語意引擎初始化中...\",\n \"description\": \"語意引擎初始化狀態\"\n },\n \"semanticEngineInitFailedStatus\": {\n \"message\": \"語意引擎初始化失敗\",\n \"description\": \"語意引擎初始化失敗狀態\"\n },\n \"semanticEngineNotInitStatus\": {\n \"message\": \"語意引擎未初始化\",\n \"description\": \"語意引擎未初始化狀態\"\n },\n \"initSemanticEngineButton\": {\n \"message\": \"初始化語意引擎\",\n \"description\": \"初始化語意引擎按鈕文字\"\n },\n \"reinitializeButton\": {\n \"message\": \"重新初始化\",\n \"description\": \"重新初始化按鈕文字\"\n },\n \"downloadingModelStatus\": {\n \"message\": \"正在下載模型... $PROGRESS$%\",\n \"description\": \"含百分比的模型下載進度\",\n \"placeholders\": {\n \"progress\": {\n \"content\": \"$1\",\n \"example\": \"50\"\n }\n }\n },\n \"switchingModelStatus\": {\n \"message\": \"正在切換模型...\",\n \"description\": \"模型切換進度訊息\"\n },\n \"modelLoadedStatus\": {\n \"message\": \"模型已載入\",\n \"description\": \"模型成功載入狀態\"\n },\n \"modelFailedStatus\": {\n \"message\": \"模型載入失敗\",\n \"description\": \"模型載入失敗狀態\"\n },\n \"lightweightModelDescription\": {\n \"message\": \"輕量級多語言模型\",\n \"description\": \"輕量級模型選項描述\"\n },\n \"betterThanSmallDescription\": {\n \"message\": \"比 e5-small 稍大，但效果更佳\",\n \"description\": \"中等模型選項描述\"\n },\n \"multilingualModelDescription\": {\n \"message\": \"多語言語意模型\",\n \"description\": \"多語言模型選項描述\"\n },\n \"fastPerformance\": {\n \"message\": \"快速\",\n \"description\": \"快速效能指標\"\n },\n \"balancedPerformance\": {\n \"message\": \"平衡\",\n \"description\": \"平衡效能指標\"\n },\n \"accuratePerformance\": {\n \"message\": \"精確\",\n \"description\": \"精確效能指標\"\n },\n \"networkErrorMessage\": {\n \"message\": \"網路連線錯誤，請檢查網路後再試一次\",\n \"description\": \"網路連線錯誤訊息\"\n },\n \"modelCorruptedErrorMessage\": {\n \"message\": \"模型檔案毀損或不完整，請重新下載\",\n \"description\": \"模型毀損錯誤訊息\"\n },\n \"unknownErrorMessage\": {\n \"message\": \"未知錯誤，請檢查您的網路是否可存取 HuggingFace\",\n \"description\": \"未知錯誤回退訊息\"\n },\n \"permissionDeniedErrorMessage\": {\n \"message\": \"權限被拒絕\",\n \"description\": \"權限被拒絕錯誤訊息\"\n },\n \"timeoutErrorMessage\": {\n \"message\": \"操作逾時\",\n \"description\": \"逾時錯誤訊息\"\n },\n \"indexedPagesLabel\": {\n \"message\": \"已索引頁面\",\n \"description\": \"已索引頁面數量標籤\"\n },\n \"indexSizeLabel\": {\n \"message\": \"索引大小\",\n \"description\": \"索引大小標籤\"\n },\n \"activeTabsLabel\": {\n \"message\": \"作用中分頁\",\n \"description\": \"作用中分頁數量標籤\"\n },\n \"vectorDocumentsLabel\": {\n \"message\": \"向量文件\",\n \"description\": \"向量文件數量標籤\"\n },\n \"cacheSizeLabel\": {\n \"message\": \"快取大小\",\n \"description\": \"快取大小標籤\"\n },\n \"cacheEntriesLabel\": {\n \"message\": \"快取項目\",\n \"description\": \"快取項目數量標籤\"\n },\n \"clearAllDataButton\": {\n \"message\": \"清除所有資料\",\n \"description\": \"清除所有資料按鈕文字\"\n },\n \"clearAllCacheButton\": {\n \"message\": \"清除所有快取\",\n \"description\": \"清除所有快取按鈕文字\"\n },\n \"cleanExpiredCacheButton\": {\n \"message\": \"清理過期快取\",\n \"description\": \"清理過期快取按鈕文字\"\n },\n \"exportDataButton\": {\n \"message\": \"匯出資料\",\n \"description\": \"匯出資料按鈕文字\"\n },\n \"importDataButton\": {\n \"message\": \"匯入資料\",\n \"description\": \"匯入資料按鈕文字\"\n },\n \"confirmClearDataTitle\": {\n \"message\": \"確認清除資料\",\n \"description\": \"清除資料確認對話框標題\"\n },\n \"settingsTitle\": {\n \"message\": \"設定\",\n \"description\": \"設定對話框標題\"\n },\n \"aboutTitle\": {\n \"message\": \"關於\",\n \"description\": \"關於對話框標題\"\n },\n \"helpTitle\": {\n \"message\": \"說明\",\n \"description\": \"說明對話框標題\"\n },\n \"clearDataWarningMessage\": {\n \"message\": \"此操作將清除所有已索引的網頁內容與向量資料，包括：\",\n \"description\": \"清除資料警告訊息\"\n },\n \"clearDataList1\": {\n \"message\": \"所有網頁的文字內容索引\",\n \"description\": \"清除資料列表第一項\"\n },\n \"clearDataList2\": {\n \"message\": \"向量嵌入資料\",\n \"description\": \"清除資料列表第二項\"\n },\n \"clearDataList3\": {\n \"message\": \"搜尋歷史與快取\",\n \"description\": \"清除資料列表第三項\"\n },\n \"clearDataIrreversibleWarning\": {\n \"message\": \"此操作無法復原！清除後需重新瀏覽網頁以重建索引。\",\n \"description\": \"不可逆操作警告\"\n },\n \"confirmClearButton\": {\n \"message\": \"確認清除\",\n \"description\": \"確認清除操作按鈕\"\n },\n \"cacheDetailsLabel\": {\n \"message\": \"快取詳細資訊\",\n \"description\": \"快取詳細資訊區段標籤\"\n },\n \"noCacheDataMessage\": {\n \"message\": \"尚無快取資料\",\n \"description\": \"無可用快取資料訊息\"\n },\n \"loadingCacheInfoStatus\": {\n \"message\": \"正在載入快取資訊...\",\n \"description\": \"載入快取資訊狀態\"\n },\n \"processingCacheStatus\": {\n \"message\": \"正在處理快取...\",\n \"description\": \"處理快取狀態\"\n },\n \"expiredLabel\": {\n \"message\": \"已過期\",\n \"description\": \"過期項目標籤\"\n },\n \"bookmarksBarLabel\": {\n \"message\": \"書籤列\",\n \"description\": \"書籤列資料夾名稱\"\n },\n \"newTabLabel\": {\n \"message\": \"新分頁\",\n \"description\": \"新分頁標籤\"\n },\n \"currentPageLabel\": {\n \"message\": \"目前頁面\",\n \"description\": \"目前頁面標籤\"\n },\n \"menuLabel\": {\n \"message\": \"功能表\",\n \"description\": \"功能表無障礙標籤\"\n },\n \"navigationLabel\": {\n \"message\": \"導覽\",\n \"description\": \"導覽無障礙標籤\"\n },\n \"mainContentLabel\": {\n \"message\": \"主要內容\",\n \"description\": \"主要內容無障礙標籤\"\n },\n \"languageSelectorLabel\": {\n \"message\": \"語言\",\n \"description\": \"語言選擇器標籤\"\n },\n \"themeLabel\": {\n \"message\": \"主題\",\n \"description\": \"主題選擇器標籤\"\n },\n \"lightTheme\": {\n \"message\": \"淺色\",\n \"description\": \"淺色主題選項\"\n },\n \"darkTheme\": {\n \"message\": \"深色\",\n \"description\": \"深色主題選項\"\n },\n \"autoTheme\": {\n \"message\": \"自動\",\n \"description\": \"自動主題選項\"\n },\n \"advancedSettingsLabel\": {\n \"message\": \"進階設定\",\n \"description\": \"進階設定區段標籤\"\n },\n \"debugModeLabel\": {\n \"message\": \"偵錯模式\",\n \"description\": \"偵錯模式切換標籤\"\n },\n \"verboseLoggingLabel\": {\n \"message\": \"詳細日誌\",\n \"description\": \"詳細日誌切換標籤\"\n },\n \"successNotification\": {\n \"message\": \"操作已成功完成\",\n \"description\": \"通用成功通知\"\n },\n \"warningNotification\": {\n \"message\": \"警告：請在繼續前檢查\",\n \"description\": \"通用警告通知\"\n },\n \"infoNotification\": {\n \"message\": \"資訊\",\n \"description\": \"通用資訊通知\"\n },\n \"configCopiedNotification\": {\n \"message\": \"設定已複製到剪貼簿\",\n \"description\": \"設定複製成功訊息\"\n },\n \"dataClearedNotification\": {\n \"message\": \"資料清除成功\",\n \"description\": \"資料清除成功訊息\"\n },\n \"bytesUnit\": {\n \"message\": \"bytes\",\n \"description\": \"位元組單位\"\n },\n \"kilobytesUnit\": {\n \"message\": \"KB\",\n \"description\": \"千位元組單位\"\n },\n \"megabytesUnit\": {\n \"message\": \"MB\",\n \"description\": \"百萬位元組單位\"\n },\n \"gigabytesUnit\": {\n \"message\": \"GB\",\n \"description\": \"十億位元組單位\"\n },\n \"itemsUnit\": {\n \"message\": \"項目\",\n \"description\": \"項目計數單位\"\n },\n \"pagesUnit\": {\n \"message\": \"頁面\",\n \"description\": \"頁面計數單位\"\n }\n}\n" }, { "path": "app/chrome-extension/common/agent-models.ts", "content": "/**\n * Agent CLI Model Definitions.\n *\n * Static model definitions for each CLI type.\n * Based on the pattern from Claudable (other/cweb).\n */\n\nimport type { CodexReasoningEffort } from 'chrome-mcp-shared';\n\n// ============================================================\n// Types\n// ============================================================\n\nexport interface ModelDefinition {\n id: string;\n name: string;\n description?: string;\n supportsImages?: boolean;\n /** Supported reasoning effort levels for Codex models */\n supportedReasoningEfforts?: readonly CodexReasoningEffort[];\n}\n\nexport type AgentCliType = 'claude' | 'codex' | 'cursor' | 'qwen' | 'glm';\n\n// ============================================================\n// Claude Models\n// ============================================================\n\nexport const CLAUDE_MODELS: ModelDefinition[] = [\n {\n id: 'claude-sonnet-4-5-20250929',\n name: 'Claude Sonnet 4.5',\n description: 'Balanced model with large context window',\n supportsImages: true,\n },\n {\n id: 'claude-opus-4-5-20251101',\n name: 'Claude Opus 4.5',\n description: 'Strongest reasoning model',\n supportsImages: true,\n },\n {\n id: 'claude-haiku-4-5-20251001',\n name: 'Claude Haiku 4.5',\n description: 'Fast and cost-efficient',\n supportsImages: true,\n },\n];\n\nexport const CLAUDE_DEFAULT_MODEL = 'claude-sonnet-4-5-20250929';\n\n// ============================================================\n// Codex Models\n// ============================================================\n\n/** Standard reasoning efforts supported by all models */\nconst CODEX_STANDARD_EFFORTS: readonly CodexReasoningEffort[] = ['low', 'medium', 'high'];\n/** Extended reasoning efforts (includes xhigh) - only for gpt-5.2 and gpt-5.1-codex-max */\nconst CODEX_EXTENDED_EFFORTS: readonly CodexReasoningEffort[] = ['low', 'medium', 'high', 'xhigh'];\n\nexport const CODEX_MODELS: ModelDefinition[] = [\n {\n id: 'gpt-5.1',\n name: 'GPT-5.1',\n description: 'OpenAI high-quality reasoning model',\n supportedReasoningEfforts: CODEX_STANDARD_EFFORTS,\n },\n {\n id: 'gpt-5.2',\n name: 'GPT-5.2',\n description: 'OpenAI flagship reasoning model with extended effort support',\n supportedReasoningEfforts: CODEX_EXTENDED_EFFORTS,\n },\n {\n id: 'gpt-5.1-codex',\n name: 'GPT-5.1 Codex',\n description: 'Coding-optimized model for agent workflows',\n supportedReasoningEfforts: CODEX_STANDARD_EFFORTS,\n },\n {\n id: 'gpt-5.1-codex-max',\n name: 'GPT-5.1 Codex Max',\n description: 'Highest quality coding model with extended effort support',\n supportedReasoningEfforts: CODEX_EXTENDED_EFFORTS,\n },\n {\n id: 'gpt-5.1-codex-mini',\n name: 'GPT-5.1 Codex Mini',\n description: 'Fast, cost-efficient coding model',\n supportedReasoningEfforts: CODEX_STANDARD_EFFORTS,\n },\n];\n\nexport const CODEX_DEFAULT_MODEL = 'gpt-5.1';\n\n// Codex model alias normalization\nconst CODEX_ALIAS_MAP: Record = {\n gpt5: 'gpt-5.1',\n gpt_5: 'gpt-5.1',\n 'gpt-5': 'gpt-5.1',\n 'gpt-5.0': 'gpt-5.1',\n};\n\nconst CODEX_KNOWN_IDS = new Set(CODEX_MODELS.map((model) => model.id));\n\n/**\n * Normalize a Codex model ID, handling aliases and falling back to default.\n */\nexport function normalizeCodexModelId(model?: string | null): string {\n if (!model || typeof model !== 'string') {\n return CODEX_DEFAULT_MODEL;\n }\n\n const trimmed = model.trim();\n if (!trimmed) {\n return CODEX_DEFAULT_MODEL;\n }\n\n const lower = trimmed.toLowerCase();\n if (CODEX_ALIAS_MAP[lower]) {\n return CODEX_ALIAS_MAP[lower];\n }\n\n if (CODEX_KNOWN_IDS.has(lower)) {\n return lower;\n }\n\n // If the exact casing exists, allow it\n if (CODEX_KNOWN_IDS.has(trimmed)) {\n return trimmed;\n }\n\n return CODEX_DEFAULT_MODEL;\n}\n\n/**\n * Get supported reasoning efforts for a Codex model.\n * Returns standard efforts (low/medium/high) for unknown models.\n */\nexport function getCodexReasoningEfforts(modelId?: string | null): readonly CodexReasoningEffort[] {\n const normalized = normalizeCodexModelId(modelId);\n const model = CODEX_MODELS.find((m) => m.id === normalized);\n return model?.supportedReasoningEfforts ?? CODEX_STANDARD_EFFORTS;\n}\n\n/**\n * Check if a model supports xhigh reasoning effort.\n */\nexport function supportsXhighEffort(modelId?: string | null): boolean {\n const efforts = getCodexReasoningEfforts(modelId);\n return efforts.includes('xhigh');\n}\n\n// ============================================================\n// Cursor Models\n// ============================================================\n\nexport const CURSOR_MODELS: ModelDefinition[] = [\n {\n id: 'auto',\n name: 'Auto',\n description: 'Cursor auto-selects the best model',\n },\n {\n id: 'claude-sonnet-4-5-20250929',\n name: 'Claude Sonnet 4.5',\n description: 'Anthropic Claude via Cursor',\n supportsImages: true,\n },\n {\n id: 'gpt-4.1',\n name: 'GPT-4.1',\n description: 'OpenAI model via Cursor',\n },\n];\n\nexport const CURSOR_DEFAULT_MODEL = 'auto';\n\n// ============================================================\n// Qwen Models\n// ============================================================\n\nexport const QWEN_MODELS: ModelDefinition[] = [\n {\n id: 'qwen3-coder-plus',\n name: 'Qwen3 Coder Plus',\n description: 'Balanced 32k context model for coding',\n },\n {\n id: 'qwen3-coder-pro',\n name: 'Qwen3 Coder Pro',\n description: 'Larger 128k context with stronger reasoning',\n },\n {\n id: 'qwen3-coder',\n name: 'Qwen3 Coder',\n description: 'Fast iteration model',\n },\n];\n\nexport const QWEN_DEFAULT_MODEL = 'qwen3-coder-plus';\n\n// ============================================================\n// GLM Models\n// ============================================================\n\nexport const GLM_MODELS: ModelDefinition[] = [\n {\n id: 'glm-4.6',\n name: 'GLM 4.6',\n description: 'Zhipu GLM 4.6 agent runtime',\n },\n];\n\nexport const GLM_DEFAULT_MODEL = 'glm-4.6';\n\n// ============================================================\n// Aggregated Definitions\n// ============================================================\n\nexport const CLI_MODEL_DEFINITIONS: Record = {\n claude: CLAUDE_MODELS,\n codex: CODEX_MODELS,\n cursor: CURSOR_MODELS,\n qwen: QWEN_MODELS,\n glm: GLM_MODELS,\n};\n\nexport const CLI_DEFAULT_MODELS: Record = {\n claude: CLAUDE_DEFAULT_MODEL,\n codex: CODEX_DEFAULT_MODEL,\n cursor: CURSOR_DEFAULT_MODEL,\n qwen: QWEN_DEFAULT_MODEL,\n glm: GLM_DEFAULT_MODEL,\n};\n\n// ============================================================\n// Helper Functions\n// ============================================================\n\n/**\n * Get model definitions for a specific CLI type.\n */\nexport function getModelsForCli(cli: string | null | undefined): ModelDefinition[] {\n if (!cli) return [];\n const key = cli.toLowerCase() as AgentCliType;\n return CLI_MODEL_DEFINITIONS[key] || [];\n}\n\n/**\n * Get the default model for a CLI type.\n */\nexport function getDefaultModelForCli(cli: string | null | undefined): string {\n if (!cli) return '';\n const key = cli.toLowerCase() as AgentCliType;\n return CLI_DEFAULT_MODELS[key] || '';\n}\n\n/**\n * Get display name for a model ID.\n */\nexport function getModelDisplayName(\n cli: string | null | undefined,\n modelId: string | null | undefined,\n): string {\n if (!cli || !modelId) return modelId || '';\n const models = getModelsForCli(cli);\n const model = models.find((m) => m.id === modelId);\n return model?.name || modelId;\n}\n" }, { "path": "app/chrome-extension/common/constants.ts", "content": "/**\n * Chrome Extension Constants\n * Centralized configuration values and magic constants\n */\n\n// Native Host Configuration\nexport const NATIVE_HOST = {\n NAME: 'com.chromemcp.nativehost',\n DEFAULT_PORT: 12306,\n} as const;\n\n// Chrome Extension Icons\nexport const ICONS = {\n NOTIFICATION: 'icon/48.png',\n} as const;\n\n// Timeouts and Delays (in milliseconds)\nexport const TIMEOUTS = {\n DEFAULT_WAIT: 1000,\n NETWORK_CAPTURE_MAX: 30000,\n NETWORK_CAPTURE_IDLE: 3000,\n SCREENSHOT_DELAY: 100,\n KEYBOARD_DELAY: 50,\n CLICK_DELAY: 100,\n} as const;\n\n// Limits and Thresholds\nexport const LIMITS = {\n MAX_NETWORK_REQUESTS: 100,\n MAX_SEARCH_RESULTS: 50,\n MAX_BOOKMARK_RESULTS: 100,\n MAX_HISTORY_RESULTS: 100,\n SIMILARITY_THRESHOLD: 0.1,\n VECTOR_DIMENSIONS: 384,\n} as const;\n\n// Error Messages\nexport const ERROR_MESSAGES = {\n NATIVE_CONNECTION_FAILED: 'Failed to connect to native host',\n NATIVE_DISCONNECTED: 'Native connection disconnected',\n SERVER_STATUS_LOAD_FAILED: 'Failed to load server status',\n SERVER_STATUS_SAVE_FAILED: 'Failed to save server status',\n TOOL_EXECUTION_FAILED: 'Tool execution failed',\n INVALID_PARAMETERS: 'Invalid parameters provided',\n PERMISSION_DENIED: 'Permission denied',\n TAB_NOT_FOUND: 'Tab not found',\n ELEMENT_NOT_FOUND: 'Element not found',\n NETWORK_ERROR: 'Network error occurred',\n} as const;\n\n// Success Messages\nexport const SUCCESS_MESSAGES = {\n TOOL_EXECUTED: 'Tool executed successfully',\n CONNECTION_ESTABLISHED: 'Connection established',\n SERVER_STARTED: 'Server started successfully',\n SERVER_STOPPED: 'Server stopped successfully',\n} as const;\n\n// External Links\nexport const LINKS = {\n TROUBLESHOOTING: 'https://github.com/hangwin/mcp-chrome/blob/master/docs/TROUBLESHOOTING.md',\n} as const;\n\n// File Extensions and MIME Types\nexport const FILE_TYPES = {\n STATIC_EXTENSIONS: [\n '.css',\n '.js',\n '.png',\n '.jpg',\n '.jpeg',\n '.gif',\n '.svg',\n '.ico',\n '.woff',\n '.woff2',\n '.ttf',\n ],\n FILTERED_MIME_TYPES: ['text/html', 'text/css', 'text/javascript', 'application/javascript'],\n IMAGE_FORMATS: ['png', 'jpeg', 'webp'] as const,\n} as const;\n\n// Network Filtering\nexport const NETWORK_FILTERS = {\n // Substring match against full URL (not just hostname) to support patterns like 'facebook.com/tr'\n EXCLUDED_DOMAINS: [\n // Google\n 'google-analytics.com',\n 'googletagmanager.com',\n 'analytics.google.com',\n 'doubleclick.net',\n 'googlesyndication.com',\n 'googleads.g.doubleclick.net',\n 'stats.g.doubleclick.net',\n 'adservice.google.com',\n 'pagead2.googlesyndication.com',\n // Amazon\n 'amazon-adsystem.com',\n // Microsoft\n 'bat.bing.com',\n 'clarity.ms',\n // Facebook\n 'connect.facebook.net',\n 'facebook.com/tr',\n // Twitter\n 'analytics.twitter.com',\n 'ads-twitter.com',\n // Other ad networks\n 'ads.yahoo.com',\n 'adroll.com',\n 'adnxs.com',\n 'criteo.com',\n 'quantserve.com',\n 'scorecardresearch.com',\n // Analytics & session recording\n 'segment.io',\n 'amplitude.com',\n 'mixpanel.com',\n 'optimizely.com',\n 'static.hotjar.com',\n 'script.hotjar.com',\n 'crazyegg.com',\n 'clicktale.net',\n 'mouseflow.com',\n 'fullstory.com',\n // LinkedIn (tracking pixels)\n 'linkedin.com/px',\n ],\n // Static resource extensions (used when includeStatic=false)\n STATIC_RESOURCE_EXTENSIONS: [\n '.jpg',\n '.jpeg',\n '.png',\n '.gif',\n '.svg',\n '.webp',\n '.ico',\n '.bmp',\n '.cur',\n '.css',\n '.scss',\n '.less',\n '.js',\n '.jsx',\n '.ts',\n '.tsx',\n '.map',\n '.woff',\n '.woff2',\n '.ttf',\n '.eot',\n '.otf',\n '.mp3',\n '.mp4',\n '.avi',\n '.mov',\n '.wmv',\n '.flv',\n '.webm',\n '.ogg',\n '.wav',\n '.pdf',\n '.zip',\n '.rar',\n '.7z',\n '.iso',\n '.dmg',\n '.doc',\n '.docx',\n '.xls',\n '.xlsx',\n '.ppt',\n '.pptx',\n ],\n // MIME types treated as static/binary (filtered when includeStatic=false)\n STATIC_MIME_TYPES_TO_FILTER: [\n 'image/',\n 'font/',\n 'audio/',\n 'video/',\n 'text/css',\n 'text/javascript',\n 'application/javascript',\n 'application/x-javascript',\n 'application/pdf',\n 'application/zip',\n 'application/octet-stream',\n ],\n // API-like MIME types (never filtered by MIME)\n API_MIME_TYPES: [\n 'application/json',\n 'application/xml',\n 'text/xml',\n 'text/plain',\n 'text/event-stream',\n 'application/x-www-form-urlencoded',\n 'application/graphql',\n 'application/grpc',\n 'application/protobuf',\n 'application/x-protobuf',\n 'application/x-json',\n 'application/ld+json',\n 'application/problem+json',\n 'application/problem+xml',\n 'application/soap+xml',\n 'application/vnd.api+json',\n ],\n STATIC_RESOURCE_TYPES: ['stylesheet', 'image', 'font', 'media', 'other'],\n} as const;\n\n// Semantic Similarity Configuration\nexport const SEMANTIC_CONFIG = {\n DEFAULT_MODEL: 'sentence-transformers/all-MiniLM-L6-v2',\n CHUNK_SIZE: 512,\n CHUNK_OVERLAP: 50,\n BATCH_SIZE: 32,\n CACHE_SIZE: 1000,\n} as const;\n\n// Storage Keys\nexport const STORAGE_KEYS = {\n SERVER_STATUS: 'serverStatus',\n NATIVE_SERVER_PORT: 'nativeServerPort',\n NATIVE_AUTO_CONNECT_ENABLED: 'nativeAutoConnectEnabled',\n SEMANTIC_MODEL: 'selectedModel',\n USER_PREFERENCES: 'userPreferences',\n VECTOR_INDEX: 'vectorIndex',\n USERSCRIPTS: 'userscripts',\n USERSCRIPTS_DISABLED: 'userscripts_disabled',\n // Record & Replay storage keys\n RR_FLOWS: 'rr_flows',\n RR_RUNS: 'rr_runs',\n RR_PUBLISHED: 'rr_published_flows',\n RR_SCHEDULES: 'rr_schedules',\n RR_TRIGGERS: 'rr_triggers',\n // Persistent recording state (guards resume across navigations/service worker restarts)\n RR_RECORDING_STATE: 'rr_recording_state',\n} as const;\n\n// Notification Configuration\nexport const NOTIFICATIONS = {\n PRIORITY: 2,\n TYPE: 'basic' as const,\n} as const;\n\nexport enum ExecutionWorld {\n ISOLATED = 'ISOLATED',\n MAIN = 'MAIN',\n}\n" }, { "path": "app/chrome-extension/common/element-marker-types.ts", "content": "// Element marker types shared across background, content scripts, and popup\n\nexport type UrlMatchType = 'exact' | 'prefix' | 'host';\n\nexport interface ElementMarker {\n id: string;\n // Original URL where the marker was created\n url: string;\n // Normalized pieces to support matching\n origin: string; // scheme + host + port\n host: string; // hostname\n path: string; // pathname part only\n matchType: UrlMatchType; // default: 'prefix'\n\n name: string; // Human-friendly name, e.g., \"Login Button\"\n selector: string; // Selector string\n selectorType?: 'css' | 'xpath'; // Default: css\n listMode?: boolean; // Whether this marker was created in list mode (allows multiple matches)\n action?: 'click' | 'fill' | 'custom'; // Intended action hint (optional)\n\n createdAt: number;\n updatedAt: number;\n}\n\nexport interface UpsertMarkerRequest {\n id?: string;\n url: string;\n name: string;\n selector: string;\n selectorType?: 'css' | 'xpath';\n listMode?: boolean;\n matchType?: UrlMatchType;\n action?: 'click' | 'fill' | 'custom';\n}\n\n// Validation actions for MCP-integrated verification\nexport enum MarkerValidationAction {\n Hover = 'hover',\n LeftClick = 'left_click',\n RightClick = 'right_click',\n DoubleClick = 'double_click',\n TypeText = 'type_text',\n PressKeys = 'press_keys',\n Scroll = 'scroll',\n}\n\nexport interface MarkerValidationRequest {\n selector: string;\n selectorType?: 'css' | 'xpath';\n action: MarkerValidationAction;\n // Optional payload for certain actions\n text?: string; // for type_text\n keys?: string; // for press_keys\n // Event options for click-like actions\n button?: 'left' | 'right' | 'middle';\n bubbles?: boolean;\n cancelable?: boolean;\n modifiers?: { altKey?: boolean; ctrlKey?: boolean; metaKey?: boolean; shiftKey?: boolean };\n // Targeting options\n coordinates?: { x: number; y: number }; // absolute viewport coords\n offsetX?: number; // relative to element center if relativeTo = 'element'\n offsetY?: number;\n relativeTo?: 'element' | 'viewport';\n // Navigation options for click-like actions\n waitForNavigation?: boolean;\n timeoutMs?: number;\n // Scroll options\n scrollDirection?: 'up' | 'down' | 'left' | 'right';\n scrollAmount?: number; // pixels per tick\n}\n\nexport interface MarkerValidationResponse {\n success: boolean;\n resolved?: boolean;\n ref?: string;\n center?: { x: number; y: number };\n tool?: { name: string; ok: boolean; error?: string };\n error?: string;\n}\n\nexport interface MarkerQuery {\n url?: string; // If present, query by URL match; otherwise list all\n}\n" }, { "path": "app/chrome-extension/common/message-types.ts", "content": "/**\n * Consolidated message type constants for Chrome extension communication\n * Note: Native message types are imported from the shared package\n */\n\nimport type { RealtimeEvent } from 'chrome-mcp-shared';\n\n// Message targets for routing\nexport enum MessageTarget {\n Offscreen = 'offscreen',\n ContentScript = 'content_script',\n Background = 'background',\n}\n\n// Background script message types\nexport const BACKGROUND_MESSAGE_TYPES = {\n SWITCH_SEMANTIC_MODEL: 'switch_semantic_model',\n GET_MODEL_STATUS: 'get_model_status',\n UPDATE_MODEL_STATUS: 'update_model_status',\n GET_STORAGE_STATS: 'get_storage_stats',\n CLEAR_ALL_DATA: 'clear_all_data',\n GET_SERVER_STATUS: 'get_server_status',\n REFRESH_SERVER_STATUS: 'refresh_server_status',\n SERVER_STATUS_CHANGED: 'server_status_changed',\n INITIALIZE_SEMANTIC_ENGINE: 'initialize_semantic_engine',\n // Record & Replay background control and queries\n RR_START_RECORDING: 'rr_start_recording',\n RR_STOP_RECORDING: 'rr_stop_recording',\n RR_PAUSE_RECORDING: 'rr_pause_recording',\n RR_RESUME_RECORDING: 'rr_resume_recording',\n RR_GET_RECORDING_STATUS: 'rr_get_recording_status',\n RR_LIST_FLOWS: 'rr_list_flows',\n RR_FLOWS_CHANGED: 'rr_flows_changed',\n RR_GET_FLOW: 'rr_get_flow',\n RR_DELETE_FLOW: 'rr_delete_flow',\n RR_PUBLISH_FLOW: 'rr_publish_flow',\n RR_UNPUBLISH_FLOW: 'rr_unpublish_flow',\n RR_RUN_FLOW: 'rr_run_flow',\n RR_SAVE_FLOW: 'rr_save_flow',\n RR_EXPORT_FLOW: 'rr_export_flow',\n RR_EXPORT_ALL: 'rr_export_all',\n RR_IMPORT_FLOW: 'rr_import_flow',\n RR_LIST_RUNS: 'rr_list_runs',\n // Triggers\n RR_LIST_TRIGGERS: 'rr_list_triggers',\n RR_SAVE_TRIGGER: 'rr_save_trigger',\n RR_DELETE_TRIGGER: 'rr_delete_trigger',\n RR_REFRESH_TRIGGERS: 'rr_refresh_triggers',\n // Scheduling\n RR_SCHEDULE_FLOW: 'rr_schedule_flow',\n RR_UNSCHEDULE_FLOW: 'rr_unschedule_flow',\n RR_LIST_SCHEDULES: 'rr_list_schedules',\n // Element marker management\n ELEMENT_MARKER_LIST_ALL: 'element_marker_list_all',\n ELEMENT_MARKER_LIST_FOR_URL: 'element_marker_list_for_url',\n ELEMENT_MARKER_SAVE: 'element_marker_save',\n ELEMENT_MARKER_UPDATE: 'element_marker_update',\n ELEMENT_MARKER_DELETE: 'element_marker_delete',\n ELEMENT_MARKER_VALIDATE: 'element_marker_validate',\n ELEMENT_MARKER_START: 'element_marker_start_from_popup',\n // Element picker (human-in-the-loop element selection)\n ELEMENT_PICKER_UI_EVENT: 'element_picker_ui_event',\n ELEMENT_PICKER_FRAME_EVENT: 'element_picker_frame_event',\n // Web editor (in-page visual editing)\n WEB_EDITOR_TOGGLE: 'web_editor_toggle',\n WEB_EDITOR_APPLY: 'web_editor_apply',\n WEB_EDITOR_STATUS_QUERY: 'web_editor_status_query',\n // Web editor <-> AgentChat integration (Phase 1.1)\n WEB_EDITOR_APPLY_BATCH: 'web_editor_apply_batch',\n WEB_EDITOR_TX_CHANGED: 'web_editor_tx_changed',\n WEB_EDITOR_HIGHLIGHT_ELEMENT: 'web_editor_highlight_element',\n // Web editor <-> AgentChat integration (Phase 2 - Revert)\n WEB_EDITOR_REVERT_ELEMENT: 'web_editor_revert_element',\n // Web editor <-> AgentChat integration - Selection sync\n WEB_EDITOR_SELECTION_CHANGED: 'web_editor_selection_changed',\n // Web editor <-> AgentChat integration - Clear selection (sidepanel -> web-editor)\n WEB_EDITOR_CLEAR_SELECTION: 'web_editor_clear_selection',\n // Web editor <-> AgentChat integration - Cancel execution\n WEB_EDITOR_CANCEL_EXECUTION: 'web_editor_cancel_execution',\n // Web editor props (Phase 7.1.6 early injection)\n WEB_EDITOR_PROPS_REGISTER_EARLY_INJECTION: 'web_editor_props_register_early_injection',\n // Web editor props - open source file in VSCode\n WEB_EDITOR_OPEN_SOURCE: 'web_editor_open_source',\n // Quick Panel <-> AgentChat integration\n QUICK_PANEL_SEND_TO_AI: 'quick_panel_send_to_ai',\n QUICK_PANEL_CANCEL_AI: 'quick_panel_cancel_ai',\n // Quick Panel Search - Tabs bridge\n QUICK_PANEL_TABS_QUERY: 'quick_panel_tabs_query',\n QUICK_PANEL_TAB_ACTIVATE: 'quick_panel_tab_activate',\n QUICK_PANEL_TAB_CLOSE: 'quick_panel_tab_close',\n} as const;\n\n// Offscreen message types\nexport const OFFSCREEN_MESSAGE_TYPES = {\n SIMILARITY_ENGINE_INIT: 'similarityEngineInit',\n SIMILARITY_ENGINE_COMPUTE: 'similarityEngineCompute',\n SIMILARITY_ENGINE_BATCH_COMPUTE: 'similarityEngineBatchCompute',\n SIMILARITY_ENGINE_STATUS: 'similarityEngineStatus',\n // GIF encoding\n GIF_ADD_FRAME: 'gifAddFrame',\n GIF_FINISH: 'gifFinish',\n GIF_RESET: 'gifReset',\n} as const;\n\n// Content script message types\nexport const CONTENT_MESSAGE_TYPES = {\n WEB_FETCHER_GET_TEXT_CONTENT: 'webFetcherGetTextContent',\n WEB_FETCHER_GET_HTML_CONTENT: 'getHtmlContent',\n NETWORK_CAPTURE_PING: 'network_capture_ping',\n CLICK_HELPER_PING: 'click_helper_ping',\n FILL_HELPER_PING: 'fill_helper_ping',\n KEYBOARD_HELPER_PING: 'keyboard_helper_ping',\n SCREENSHOT_HELPER_PING: 'screenshot_helper_ping',\n INTERACTIVE_ELEMENTS_HELPER_PING: 'interactive_elements_helper_ping',\n ACCESSIBILITY_TREE_HELPER_PING: 'chrome_read_page_ping',\n WAIT_HELPER_PING: 'wait_helper_ping',\n DOM_OBSERVER_PING: 'dom_observer_ping',\n} as const;\n\n// Tool action message types (for chrome.runtime.sendMessage)\nexport const TOOL_MESSAGE_TYPES = {\n // Screenshot related\n SCREENSHOT_PREPARE_PAGE_FOR_CAPTURE: 'preparePageForCapture',\n SCREENSHOT_GET_PAGE_DETAILS: 'getPageDetails',\n SCREENSHOT_GET_ELEMENT_DETAILS: 'getElementDetails',\n SCREENSHOT_SCROLL_PAGE: 'scrollPage',\n SCREENSHOT_RESET_PAGE_AFTER_CAPTURE: 'resetPageAfterCapture',\n\n // Web content fetching\n WEB_FETCHER_GET_HTML_CONTENT: 'getHtmlContent',\n WEB_FETCHER_GET_TEXT_CONTENT: 'getTextContent',\n\n // User interactions\n CLICK_ELEMENT: 'clickElement',\n FILL_ELEMENT: 'fillElement',\n SIMULATE_KEYBOARD: 'simulateKeyboard',\n\n // Interactive elements\n GET_INTERACTIVE_ELEMENTS: 'getInteractiveElements',\n\n // Accessibility tree\n GENERATE_ACCESSIBILITY_TREE: 'generateAccessibilityTree',\n RESOLVE_REF: 'resolveRef',\n ENSURE_REF_FOR_SELECTOR: 'ensureRefForSelector',\n VERIFY_FINGERPRINT: 'verifyFingerprint',\n DISPATCH_HOVER_FOR_REF: 'dispatchHoverForRef',\n\n // Network requests\n NETWORK_SEND_REQUEST: 'sendPureNetworkRequest',\n\n // Wait helper\n WAIT_FOR_TEXT: 'waitForText',\n\n // Semantic similarity engine\n SIMILARITY_ENGINE_INIT: 'similarityEngineInit',\n SIMILARITY_ENGINE_COMPUTE_BATCH: 'similarityEngineComputeBatch',\n // Record & Replay content script bridge\n RR_RECORDER_CONTROL: 'rr_recorder_control',\n RR_RECORDER_EVENT: 'rr_recorder_event',\n // Record & Replay timeline feed (background -> content overlay)\n RR_TIMELINE_UPDATE: 'rr_timeline_update',\n // Quick Panel AI streaming events (background -> content script)\n QUICK_PANEL_AI_EVENT: 'quick_panel_ai_event',\n // DOM observer trigger bridge\n SET_DOM_TRIGGERS: 'set_dom_triggers',\n DOM_TRIGGER_FIRED: 'dom_trigger_fired',\n // Record & Replay overlay: variable collection\n COLLECT_VARIABLES: 'collectVariables',\n // Element marker overlay control (content-side)\n ELEMENT_MARKER_START: 'element_marker_start',\n // Element picker (tool-driven, background <-> content scripts)\n ELEMENT_PICKER_START: 'elementPickerStart',\n ELEMENT_PICKER_STOP: 'elementPickerStop',\n ELEMENT_PICKER_SET_ACTIVE_REQUEST: 'elementPickerSetActiveRequest',\n ELEMENT_PICKER_UI_PING: 'elementPickerUiPing',\n ELEMENT_PICKER_UI_SHOW: 'elementPickerUiShow',\n ELEMENT_PICKER_UI_UPDATE: 'elementPickerUiUpdate',\n ELEMENT_PICKER_UI_HIDE: 'elementPickerUiHide',\n} as const;\n\n// Type unions for type safety\nexport type BackgroundMessageType =\n (typeof BACKGROUND_MESSAGE_TYPES)[keyof typeof BACKGROUND_MESSAGE_TYPES];\nexport type OffscreenMessageType =\n (typeof OFFSCREEN_MESSAGE_TYPES)[keyof typeof OFFSCREEN_MESSAGE_TYPES];\nexport type ContentMessageType = (typeof CONTENT_MESSAGE_TYPES)[keyof typeof CONTENT_MESSAGE_TYPES];\nexport type ToolMessageType = (typeof TOOL_MESSAGE_TYPES)[keyof typeof TOOL_MESSAGE_TYPES];\n\n// Legacy enum for backward compatibility (will be deprecated)\nexport enum SendMessageType {\n // Screenshot related message types\n ScreenshotPreparePageForCapture = 'preparePageForCapture',\n ScreenshotGetPageDetails = 'getPageDetails',\n ScreenshotGetElementDetails = 'getElementDetails',\n ScreenshotScrollPage = 'scrollPage',\n ScreenshotResetPageAfterCapture = 'resetPageAfterCapture',\n\n // Web content fetching related message types\n WebFetcherGetHtmlContent = 'getHtmlContent',\n WebFetcherGetTextContent = 'getTextContent',\n\n // Click related message types\n ClickElement = 'clickElement',\n\n // Input filling related message types\n FillElement = 'fillElement',\n\n // Interactive elements related message types\n GetInteractiveElements = 'getInteractiveElements',\n\n // Network request capture related message types\n NetworkSendRequest = 'sendPureNetworkRequest',\n\n // Keyboard event related message types\n SimulateKeyboard = 'simulateKeyboard',\n\n // Semantic similarity engine related message types\n SimilarityEngineInit = 'similarityEngineInit',\n SimilarityEngineComputeBatch = 'similarityEngineComputeBatch',\n}\n\n// ============================================================\n// Quick Panel <-> AgentChat Message Contracts\n// ============================================================\n\n/**\n * Context information that can be attached to a Quick Panel AI request.\n * Allows passing page-specific data to enhance the AI's understanding.\n */\nexport interface QuickPanelAIContext {\n /** Current page URL */\n pageUrl?: string;\n /** User's text selection on the page */\n selectedText?: string;\n /**\n * Optional element metadata from the page.\n * Kept as unknown to avoid tight coupling with specific element types.\n */\n elementInfo?: unknown;\n}\n\n/**\n * Payload for sending a message to AI via Quick Panel.\n */\nexport interface QuickPanelSendToAIPayload {\n /** The user's instruction/question for the AI */\n instruction: string;\n /** Optional contextual information from the page */\n context?: QuickPanelAIContext;\n}\n\n/**\n * Response from QUICK_PANEL_SEND_TO_AI message handler.\n */\nexport type QuickPanelSendToAIResponse =\n | { success: true; requestId: string; sessionId: string }\n | { success: false; error: string };\n\n/**\n * Message structure for sending to AI.\n */\nexport interface QuickPanelSendToAIMessage {\n type: typeof BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_SEND_TO_AI;\n payload: QuickPanelSendToAIPayload;\n}\n\n/**\n * Payload for cancelling an active AI request.\n */\nexport interface QuickPanelCancelAIPayload {\n /** The request ID to cancel */\n requestId: string;\n /**\n * Optional session ID for fallback when background state is missing.\n * This can happen after MV3 Service Worker restarts.\n */\n sessionId?: string;\n}\n\n/**\n * Response from QUICK_PANEL_CANCEL_AI message handler.\n */\nexport type QuickPanelCancelAIResponse = { success: true } | { success: false; error: string };\n\n/**\n * Message structure for cancelling AI request.\n */\nexport interface QuickPanelCancelAIMessage {\n type: typeof BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_CANCEL_AI;\n payload: QuickPanelCancelAIPayload;\n}\n\n/**\n * Message pushed from background to content script with AI streaming events.\n * Uses the same RealtimeEvent type as AgentChat for consistency.\n */\nexport interface QuickPanelAIEventMessage {\n action: typeof TOOL_MESSAGE_TYPES.QUICK_PANEL_AI_EVENT;\n requestId: string;\n sessionId: string;\n event: RealtimeEvent;\n}\n\n// ============================================================\n// Quick Panel Search - Tabs Bridge Contracts\n// ============================================================\n\n/**\n * Payload for querying open tabs.\n */\nexport interface QuickPanelTabsQueryPayload {\n /**\n * When true (default), query tabs across all windows.\n * When false, restrict results to the sender's window.\n */\n includeAllWindows?: boolean;\n}\n\n/**\n * Summary of a single tab returned from the background.\n */\nexport interface QuickPanelTabSummary {\n tabId: number;\n windowId: number;\n title: string;\n url: string;\n favIconUrl?: string;\n active: boolean;\n pinned: boolean;\n audible: boolean;\n muted: boolean;\n index: number;\n lastAccessed?: number;\n}\n\n/**\n * Response from QUICK_PANEL_TABS_QUERY message handler.\n */\nexport type QuickPanelTabsQueryResponse =\n | {\n success: true;\n tabs: QuickPanelTabSummary[];\n currentTabId: number | null;\n currentWindowId: number | null;\n }\n | { success: false; error: string };\n\n/**\n * Message structure for querying tabs.\n */\nexport interface QuickPanelTabsQueryMessage {\n type: typeof BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_TABS_QUERY;\n payload?: QuickPanelTabsQueryPayload;\n}\n\n/**\n * Payload for activating a tab.\n */\nexport interface QuickPanelActivateTabPayload {\n tabId: number;\n windowId?: number;\n}\n\n/**\n * Response from QUICK_PANEL_TAB_ACTIVATE message handler.\n */\nexport type QuickPanelActivateTabResponse = { success: true } | { success: false; error: string };\n\n/**\n * Message structure for activating a tab.\n */\nexport interface QuickPanelActivateTabMessage {\n type: typeof BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_TAB_ACTIVATE;\n payload: QuickPanelActivateTabPayload;\n}\n\n/**\n * Payload for closing a tab.\n */\nexport interface QuickPanelCloseTabPayload {\n tabId: number;\n}\n\n/**\n * Response from QUICK_PANEL_TAB_CLOSE message handler.\n */\nexport type QuickPanelCloseTabResponse = { success: true } | { success: false; error: string };\n\n/**\n * Message structure for closing a tab.\n */\nexport interface QuickPanelCloseTabMessage {\n type: typeof BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_TAB_CLOSE;\n payload: QuickPanelCloseTabPayload;\n}\n" }, { "path": "app/chrome-extension/common/node-types.ts", "content": "// node-types.ts — centralized node type constants for Builder/UI layer\n// Combines all executable Step types with UI-only nodes (e.g., trigger, delay)\n\nimport { STEP_TYPES } from './step-types';\n\nexport const NODE_TYPES = {\n // Executable step types (spread from STEP_TYPES)\n ...STEP_TYPES,\n // UI-only nodes\n TRIGGER: 'trigger',\n DELAY: 'delay',\n} as const;\n\nexport type NodeTypeConst = (typeof NODE_TYPES)[keyof typeof NODE_TYPES];\n" }, { "path": "app/chrome-extension/common/rr-v3-keepalive-protocol.ts", "content": "/**\n * @fileoverview RR V3 Keepalive Protocol Constants\n * @description Shared protocol constants for Background-Offscreen keepalive communication\n */\n\n/** Keepalive Port 名称 */\nexport const RR_V3_KEEPALIVE_PORT_NAME = 'rr_v3_keepalive' as const;\n\n/** Keepalive 消息类型 */\nexport type KeepaliveMessageType =\n | 'keepalive.ping'\n | 'keepalive.pong'\n | 'keepalive.start'\n | 'keepalive.stop';\n\n/** Keepalive 消息 */\nexport interface KeepaliveMessage {\n type: KeepaliveMessageType;\n timestamp: number;\n}\n\n/** 默认心跳间隔（毫秒） - Offscreen 每隔这个间隔发送 ping */\nexport const DEFAULT_KEEPALIVE_PING_INTERVAL_MS = 20_000;\n\n/** 最大心跳间隔（毫秒）- Chrome MV3 SW 约 30s 空闲后终止 */\nexport const MAX_KEEPALIVE_PING_INTERVAL_MS = 25_000;\n" }, { "path": "app/chrome-extension/common/step-types.ts", "content": "// step-types.ts — re-export shared constants to keep single source of truth\nexport { STEP_TYPES } from 'chrome-mcp-shared';\nexport type StepTypeConst =\n (typeof import('chrome-mcp-shared'))['STEP_TYPES'][keyof (typeof import('chrome-mcp-shared'))['STEP_TYPES']];\n" }, { "path": "app/chrome-extension/common/tool-handler.ts", "content": "import type { CallToolResult, TextContent, ImageContent } from '@modelcontextprotocol/sdk/types.js';\n\nexport interface ToolResult extends CallToolResult {\n content: (TextContent | ImageContent)[];\n isError: boolean;\n}\n\nexport interface ToolExecutor {\n execute(args: any): Promise;\n}\n\nexport const createErrorResponse = (\n message: string = 'Unknown error, please try again',\n): ToolResult => {\n return {\n content: [\n {\n type: 'text',\n text: message,\n },\n ],\n isError: true,\n };\n};\n" }, { "path": "app/chrome-extension/common/web-editor-types.ts", "content": "/**\n * Web Editor V2 - Shared Type Definitions\n *\n * This module defines types shared between:\n * - Background script (injection control)\n * - Inject script (web-editor-v2.ts)\n * - Future: UI panels\n */\n\n// =============================================================================\n// Editor State\n// =============================================================================\n\n/** Current state of the web editor */\nexport interface WebEditorState {\n /** Whether the editor is currently active */\n active: boolean;\n /** Editor version for compatibility checks */\n version: 2;\n}\n\n// =============================================================================\n// Message Protocol (Background <-> Inject Script)\n// =============================================================================\n\n/**\n * Action types for web editor V2 messages\n *\n * IMPORTANT: V2 uses versioned action names (suffix _v2) to avoid\n * conflicts with V1 when both scripts might be injected in the same tab.\n * This prevents double-response race conditions.\n *\n * V1 uses: web_editor_ping, web_editor_toggle, etc.\n * V2 uses: web_editor_ping_v2, web_editor_toggle_v2, etc.\n */\nexport const WEB_EDITOR_V2_ACTIONS = {\n /** Check if V2 editor is injected and get status */\n PING: 'web_editor_ping_v2',\n /** Toggle V2 editor on/off */\n TOGGLE: 'web_editor_toggle_v2',\n /** Start V2 editor */\n START: 'web_editor_start_v2',\n /** Stop V2 editor */\n STOP: 'web_editor_stop_v2',\n /** Highlight an element (from sidepanel hover) */\n HIGHLIGHT_ELEMENT: 'web_editor_highlight_element_v2',\n /** Revert an element to its original state (Phase 2 - Selective Undo) */\n REVERT_ELEMENT: 'web_editor_revert_element_v2',\n /** Clear selection (from sidepanel after send) */\n CLEAR_SELECTION: 'web_editor_clear_selection_v2',\n} as const;\n\n/**\n * Legacy V1 action types (for reference and background compatibility)\n * These are used when USE_WEB_EDITOR_V2 is false\n */\nexport const WEB_EDITOR_V1_ACTIONS = {\n PING: 'web_editor_ping',\n TOGGLE: 'web_editor_toggle',\n START: 'web_editor_start',\n STOP: 'web_editor_stop',\n APPLY: 'web_editor_apply',\n} as const;\n\nexport type WebEditorV2Action = (typeof WEB_EDITOR_V2_ACTIONS)[keyof typeof WEB_EDITOR_V2_ACTIONS];\nexport type WebEditorV1Action = (typeof WEB_EDITOR_V1_ACTIONS)[keyof typeof WEB_EDITOR_V1_ACTIONS];\n\n/** Editor version literal type */\nexport type WebEditorVersion = 1 | 2;\n\n/** Ping request (V2) */\nexport interface WebEditorV2PingRequest {\n action: typeof WEB_EDITOR_V2_ACTIONS.PING;\n}\n\n/** Ping response (V2) */\nexport interface WebEditorV2PingResponse {\n status: 'pong';\n active: boolean;\n version: 2;\n}\n\n/** Toggle request (V2) */\nexport interface WebEditorV2ToggleRequest {\n action: typeof WEB_EDITOR_V2_ACTIONS.TOGGLE;\n}\n\n/** Toggle response (V2) */\nexport interface WebEditorV2ToggleResponse {\n active: boolean;\n}\n\n/** Start request (V2) */\nexport interface WebEditorV2StartRequest {\n action: typeof WEB_EDITOR_V2_ACTIONS.START;\n}\n\n/** Start response (V2) */\nexport interface WebEditorV2StartResponse {\n active: boolean;\n}\n\n/** Stop request (V2) */\nexport interface WebEditorV2StopRequest {\n action: typeof WEB_EDITOR_V2_ACTIONS.STOP;\n}\n\n/** Stop response (V2) */\nexport interface WebEditorV2StopResponse {\n active: boolean;\n}\n\n/** Union types for V2 type-safe message handling */\nexport type WebEditorV2Request =\n | WebEditorV2PingRequest\n | WebEditorV2ToggleRequest\n | WebEditorV2StartRequest\n | WebEditorV2StopRequest;\n\nexport type WebEditorV2Response =\n | WebEditorV2PingResponse\n | WebEditorV2ToggleResponse\n | WebEditorV2StartResponse\n | WebEditorV2StopResponse;\n\n// =============================================================================\n// Element Locator (Phase 1 - Basic Structure)\n// =============================================================================\n\n/**\n * Framework debug source information\n * Extracted from React Fiber or Vue component instance\n */\nexport interface DebugSource {\n /** Source file path */\n file: string;\n /** Line number (1-based) */\n line?: number;\n /** Column number (1-based) */\n column?: number;\n /** Component name (if available) */\n componentName?: string;\n}\n\n/**\n * Element Locator - Primary key for element identification\n *\n * Uses multiple strategies to locate elements, supporting:\n * - HMR/DOM changes recovery\n * - Cross-session persistence\n * - Framework-agnostic identification\n */\nexport interface ElementLocator {\n /** CSS selector candidates (ordered by specificity) */\n selectors: string[];\n /** Structural fingerprint for similarity matching */\n fingerprint: string;\n /** Framework debug information (React/Vue) */\n debugSource?: DebugSource;\n /** DOM tree path (child indices from root) */\n path: number[];\n /** iframe selector chain (from top to target frame) - Phase 4 */\n frameChain?: string[];\n /** Shadow DOM host selector chain - Phase 2 */\n shadowHostChain?: string[];\n}\n\n// =============================================================================\n// Transaction System (Phase 1 - Basic Structure, Low Priority)\n// =============================================================================\n\n/** Transaction operation types */\nexport type TransactionType = 'style' | 'text' | 'class' | 'move' | 'structure';\n\n/**\n * Transaction snapshot for undo/redo\n * Captures element state before/after changes\n */\nexport interface TransactionSnapshot {\n /** Element locator for re-identification */\n locator: ElementLocator;\n /** innerHTML snapshot (for structure changes) */\n html?: string;\n /** Changed style properties */\n styles?: Record;\n /** Class list tokens (from `class` attribute) */\n classes?: string[];\n /** Text content */\n text?: string;\n}\n\n/**\n * Move position data\n * Captures a concrete insertion point under a parent element\n */\nexport interface MoveOperationData {\n /** Target parent element locator */\n parentLocator: ElementLocator;\n /** Insert position index (among element children) */\n insertIndex: number;\n /** Anchor sibling element locator (for stable positioning) */\n anchorLocator?: ElementLocator;\n /** Position relative to anchor */\n anchorPosition: 'before' | 'after';\n}\n\n/**\n * Move transaction data\n * Captures both source and destination for undo/redo\n */\nexport interface MoveTransactionData {\n /** Original location before move */\n from: MoveOperationData;\n /** Target location after move */\n to: MoveOperationData;\n}\n\n/**\n * Structure operation data\n * For wrap/unwrap/delete/duplicate operations (Phase 5.5)\n */\nexport interface StructureOperationData {\n /** Structure action type */\n action: 'wrap' | 'unwrap' | 'delete' | 'duplicate';\n /** Wrapper tag for wrap/unwrap actions */\n wrapperTag?: string;\n /** Wrapper inline styles for wrap/unwrap actions */\n wrapperStyles?: Record;\n /**\n * Deterministic insertion position for undo/redo.\n * Required for delete (restore) and duplicate (re-create).\n */\n position?: MoveOperationData;\n /**\n * Serialized element HTML for undo/redo.\n * Must be a single-root element outerHTML string.\n * Used by delete (restore original) and duplicate (re-create clone).\n */\n html?: string;\n}\n\n/**\n * Transaction record for undo/redo system\n */\nexport interface Transaction {\n /** Unique transaction ID */\n id: string;\n /** Operation type */\n type: TransactionType;\n /** Target element locator */\n targetLocator: ElementLocator;\n /**\n * Stable element identifier for cross-transaction grouping.\n * Used by AgentChat integration for element chips aggregation.\n * Optional for backward compatibility with existing transactions.\n */\n elementKey?: string;\n /** State before change */\n before: TransactionSnapshot;\n /** State after change */\n after: TransactionSnapshot;\n /** Move-specific data */\n moveData?: MoveTransactionData;\n /** Structure-specific data */\n structureData?: StructureOperationData;\n /** Timestamp */\n timestamp: number;\n /** Whether merged with previous transaction */\n merged: boolean;\n}\n\n// =============================================================================\n// AgentChat Integration Types (Phase 1.1)\n// =============================================================================\n\n/** Stable element identifier for aggregating transactions across UI contexts */\nexport type WebEditorElementKey = string;\n\n/**\n * Net effect payload for a single element aggregated from the undo stack.\n * Designed to be directly consumable by prompt builders.\n */\nexport interface NetEffectPayload {\n /** Stable element key */\n elementKey: WebEditorElementKey;\n /** Locator snapshot for element re-identification */\n locator: ElementLocator;\n /**\n * Aggregated style changes (first before -> last after).\n * Contains ONLY the affected properties, not a full style snapshot.\n * Empty string value means the property was removed/unset.\n */\n styleChanges?: {\n before: Record;\n after: Record;\n };\n /** Aggregated text change (first before -> last after) */\n textChange?: {\n before: string;\n after: string;\n };\n /** Aggregated class changes (first before -> last after) */\n classChanges?: {\n before: string[];\n after: string[];\n };\n}\n\n/** High-level change category for UI display */\nexport type ElementChangeType = 'style' | 'text' | 'class' | 'mixed';\n\n/**\n * Element change summary for Chips rendering in AgentChat.\n * Aggregates multiple transactions for the same element.\n */\nexport interface ElementChangeSummary {\n /** Stable element identifier */\n elementKey: WebEditorElementKey;\n /** Short label for Chips display (e.g., \"button#submit\") */\n label: string;\n /** Full label for tooltips with more context */\n fullLabel: string;\n /** Locator snapshot for highlighting and element recovery */\n locator: ElementLocator;\n /** High-level change category */\n type: ElementChangeType;\n /** Detailed change statistics for UI tooltips */\n changes: {\n style?: {\n /** Number of new style properties added */\n added: number;\n /** Number of style properties removed */\n removed: number;\n /** Number of style properties modified */\n modified: number;\n /** List of affected style property names */\n details: string[];\n };\n text?: {\n /** Truncated preview of original text */\n beforePreview: string;\n /** Truncated preview of new text */\n afterPreview: string;\n };\n class?: {\n /** Classes added */\n added: string[];\n /** Classes removed */\n removed: string[];\n };\n };\n /** Contributing transaction IDs in chronological order */\n transactionIds: string[];\n /** Net effect payload for batch Apply */\n netEffect: NetEffectPayload;\n /** Timestamp of the most recent transaction */\n updatedAt: number;\n /** Debug source information if available */\n debugSource?: DebugSource;\n}\n\n/** Action types for TX change events */\nexport type WebEditorTxChangeAction = 'push' | 'merge' | 'undo' | 'redo' | 'clear' | 'rollback';\n\n/**\n * TX change broadcast payload sent to Sidepanel/AgentChat.\n * Emitted when the undo stack changes (push, undo, redo, clear).\n */\nexport interface WebEditorTxChangedPayload {\n /** Source tab ID for multi-tab isolation */\n tabId: number;\n /** Action that triggered this change (for UI animations/incremental updates) */\n action: WebEditorTxChangeAction;\n /** Aggregated element-level summaries from the current undo stack */\n elements: ElementChangeSummary[];\n /** Current undo stack size */\n undoCount: number;\n /** Current redo stack size */\n redoCount: number;\n /** Whether there are applicable changes (style/text/class) */\n hasApplicableChanges: boolean;\n /** Page URL for context */\n pageUrl?: string;\n}\n\n/**\n * Batch Apply payload sent from web-editor to background.\n */\nexport interface WebEditorApplyBatchPayload {\n /** Source tab ID */\n tabId: number;\n /** Element changes to apply */\n elements: ElementChangeSummary[];\n /** Element keys excluded by user */\n excludedKeys: WebEditorElementKey[];\n /** Page URL for context */\n pageUrl?: string;\n}\n\n/**\n * Highlight element request sent from AgentChat to the active tab.\n */\nexport interface WebEditorHighlightElementPayload {\n /** Target tab ID */\n tabId: number;\n /** Element key to highlight */\n elementKey: WebEditorElementKey;\n /** Locator for element identification */\n locator: ElementLocator;\n /** Highlight mode: 'hover' to show, 'clear' to hide */\n mode: 'hover' | 'clear';\n}\n\n/**\n * Revert element request sent from AgentChat to the active tab.\n * Used for Phase 2 - Selective Undo (reverting individual element changes).\n */\nexport interface WebEditorRevertElementPayload {\n /** Target tab ID */\n tabId: number;\n /** Element key to revert */\n elementKey: WebEditorElementKey;\n}\n\n/**\n * Revert element response from content script.\n */\nexport interface WebEditorRevertElementResponse {\n /** Whether the revert was successful */\n success: boolean;\n /** What was reverted (for UI feedback) */\n reverted?: {\n style?: boolean;\n text?: boolean;\n class?: boolean;\n };\n /** Error message if revert failed */\n error?: string;\n}\n\n// =============================================================================\n// Selection Sync Types\n// =============================================================================\n\n/**\n * Summary of currently selected element.\n * Lightweight payload for selection sync (no transaction data).\n */\nexport interface SelectedElementSummary {\n /** Stable element identifier */\n elementKey: WebEditorElementKey;\n /** Locator for element identification and highlighting */\n locator: ElementLocator;\n /** Short display label (e.g., \"div#app\") */\n label: string;\n /** Full label with context (e.g., \"body > div#app\") */\n fullLabel: string;\n /** Tag name of the element */\n tagName: string;\n /** Timestamp for deduplication */\n updatedAt: number;\n}\n\n/**\n * Selection change broadcast payload.\n * Sent immediately when user selects/deselects elements (no debounce).\n */\nexport interface WebEditorSelectionChangedPayload {\n /** Source tab ID (filled by background from sender.tab.id) */\n tabId: number;\n /** Currently selected element, or null if deselected */\n selected: SelectedElementSummary | null;\n /** Page URL for context */\n pageUrl?: string;\n}\n\n// =============================================================================\n// Execution Cancel Types\n// =============================================================================\n\n/**\n * Payload for canceling an ongoing Apply execution.\n * Sent from web-editor toolbar or sidepanel to background.\n */\nexport interface WebEditorCancelExecutionPayload {\n /** Session ID of the execution to cancel */\n sessionId: string;\n /** Request ID of the execution to cancel */\n requestId: string;\n}\n\n/**\n * Response from cancel execution request.\n */\nexport interface WebEditorCancelExecutionResponse {\n /** Whether the cancel request was successful */\n success: boolean;\n /** Error message if cancellation failed */\n error?: string;\n}\n\n// =============================================================================\n// Public API Interface\n// =============================================================================\n\n/**\n * Web Editor V2 Public API\n * Exposed on window.__MCP_WEB_EDITOR_V2__\n */\nexport interface WebEditorV2Api {\n /** Start the editor */\n start: () => void;\n /** Stop the editor */\n stop: () => void;\n /** Toggle editor on/off, returns new state */\n toggle: () => boolean;\n /** Get current state */\n getState: () => WebEditorState;\n /**\n * Revert a specific element to its original state (Phase 2 - Selective Undo).\n * Creates a compensating transaction that can be undone.\n */\n revertElement: (elementKey: WebEditorElementKey) => Promise;\n /**\n * Clear current selection (called from sidepanel after send).\n * Triggers deselect and broadcasts null selection.\n */\n clearSelection: () => void;\n}\n\n// =============================================================================\n// Global Declaration\n// =============================================================================\n\ndeclare global {\n interface Window {\n __MCP_WEB_EDITOR_V2__?: WebEditorV2Api;\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/element-marker/element-marker-storage.ts", "content": "// IndexedDB storage for element markers (URL -> marked selectors)\n// Uses the shared IndexedDbClient for robust transaction handling.\n\nimport { IndexedDbClient } from '@/utils/indexeddb-client';\nimport type { ElementMarker, UpsertMarkerRequest } from '@/common/element-marker-types';\n\nconst DB_NAME = 'element_marker_storage';\nconst DB_VERSION = 1;\nconst STORE = 'markers';\n\nconst idb = new IndexedDbClient(DB_NAME, DB_VERSION, (db, oldVersion) => {\n switch (oldVersion) {\n case 0: {\n const store = db.createObjectStore(STORE, { keyPath: 'id' });\n // Useful indexes for lookups\n store.createIndex('by_host', 'host', { unique: false });\n store.createIndex('by_origin', 'origin', { unique: false });\n store.createIndex('by_path', 'path', { unique: false });\n }\n }\n});\n\nfunction normalizeUrl(raw: string): { url: string; origin: string; host: string; path: string } {\n try {\n const u = new URL(raw);\n return { url: raw, origin: u.origin, host: u.hostname, path: u.pathname };\n } catch {\n return { url: raw, origin: '', host: '', path: '' };\n }\n}\n\nfunction now(): number {\n return Date.now();\n}\n\nexport async function listAllMarkers(): Promise {\n return idb.getAll(STORE);\n}\n\nexport async function listMarkersForUrl(url: string): Promise {\n const { origin, path, host } = normalizeUrl(url);\n const all = await idb.getAll(STORE);\n // Simple matching policy:\n // - exact: origin + path must match exactly\n // - prefix: origin matches and marker.path is a prefix of current path\n // - host: host matches regardless of path\n return all.filter((m) => {\n if (!m) return false;\n if (m.matchType === 'exact') return m.origin === origin && m.path === path;\n if (m.matchType === 'host') return !!m.host && m.host === host;\n // default 'prefix'\n return m.origin === origin && (m.path ? path.startsWith(m.path) : true);\n });\n}\n\nexport async function saveMarker(req: UpsertMarkerRequest): Promise {\n const { url: rawUrl, selector } = req;\n if (!rawUrl || !selector) throw new Error('url and selector are required');\n const { url, origin, host, path } = normalizeUrl(rawUrl);\n const ts = now();\n const marker: ElementMarker = {\n id: req.id || (globalThis.crypto?.randomUUID?.() ?? `${ts}_${Math.random()}`),\n url,\n origin,\n host,\n path,\n matchType: req.matchType || 'prefix',\n name: req.name || selector,\n selector,\n selectorType: req.selectorType || 'css',\n listMode: req.listMode || false,\n action: req.action || 'custom',\n createdAt: ts,\n updatedAt: ts,\n };\n await idb.put(STORE, marker);\n return marker;\n}\n\nexport async function updateMarker(marker: ElementMarker): Promise {\n const existing = await idb.get(STORE, marker.id);\n if (!existing) throw new Error('marker not found');\n\n // Preserve createdAt from existing record, only update updatedAt\n const updated: ElementMarker = {\n ...marker,\n createdAt: existing.createdAt, // Never overwrite createdAt\n updatedAt: now(),\n };\n await idb.put(STORE, updated);\n}\n\nexport async function deleteMarker(id: string): Promise {\n await idb.delete(STORE, id);\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/element-marker/index.ts", "content": "import { BACKGROUND_MESSAGE_TYPES } from '@/common/message-types';\nimport type {\n UpsertMarkerRequest,\n ElementMarker,\n MarkerValidationRequest,\n MarkerValidationAction,\n} from '@/common/element-marker-types';\nimport {\n deleteMarker,\n listAllMarkers,\n listMarkersForUrl,\n saveMarker,\n updateMarker,\n} from './element-marker-storage';\nimport { computerTool } from '@/entrypoints/background/tools/browser/computer';\nimport { clickTool } from '@/entrypoints/background/tools/browser/interaction';\nimport { keyboardTool } from '@/entrypoints/background/tools/browser/keyboard';\n\nconst CONTEXT_MENU_ID = 'element_marker_mark';\n\n/**\n * Extract error message from MCP tool result\n */\nfunction extractToolError(result: any): string | undefined {\n if (!result) return undefined;\n\n // Check for error in result content array\n if (Array.isArray(result.content)) {\n for (const item of result.content) {\n if (item?.text) {\n try {\n const parsed = JSON.parse(item.text);\n if (parsed?.error) return parsed.error;\n if (parsed?.message) return parsed.message;\n } catch {\n // Not JSON, use as-is\n return item.text;\n }\n }\n }\n }\n\n // Fallback to direct error field\n return result.error || (result.isError ? 'unknown tool error' : undefined);\n}\n\nasync function ensureContextMenu() {\n try {\n // Guard: contextMenus permission may be missing\n if (!(chrome as any).contextMenus?.create) return;\n // Remove and re-create our single menu to avoid duplication\n try {\n await chrome.contextMenus.remove(CONTEXT_MENU_ID);\n } catch {}\n await chrome.contextMenus.create({\n id: CONTEXT_MENU_ID,\n title: '标注元素',\n contexts: ['all'],\n });\n } catch (e) {\n console.warn('ElementMarker: ensureContextMenu failed:', e);\n }\n}\n\n/**\n * Check if element-marker.js is already injected in the tab\n * Uses a short timeout to avoid hanging on unresponsive tabs\n */\nasync function isMarkerInjected(tabId: number): Promise {\n try {\n const response = await Promise.race([\n chrome.tabs.sendMessage(tabId, { action: 'element_marker_ping' }),\n new Promise((resolve) => setTimeout(() => resolve(null), 300)),\n ]);\n return response?.status === 'pong';\n } catch {\n return false;\n }\n}\n\n/**\n * Inject element-marker.js into the tab if not already injected\n */\nasync function injectMarkerHelper(tabId: number) {\n // Check if already injected via ping\n const alreadyInjected = await isMarkerInjected(tabId);\n\n if (!alreadyInjected) {\n try {\n await chrome.scripting.executeScript({\n target: { tabId, allFrames: true },\n files: ['inject-scripts/element-marker.js'],\n world: 'ISOLATED',\n } as any);\n } catch (e) {\n // Script injection may fail on some pages (e.g., chrome:// URLs)\n console.warn('ElementMarker: script injection failed:', e);\n }\n }\n\n try {\n await chrome.tabs.sendMessage(tabId, { action: 'element_marker_start' } as any);\n } catch (e) {\n console.warn('ElementMarker: start overlay failed:', e);\n }\n}\n\nexport function initElementMarkerListeners() {\n // Ensure context menu on startup\n ensureContextMenu().catch(() => {});\n\n // Respond to RR triggers refresh by re-ensuring our menu a bit later\n chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {\n try {\n switch (message?.type) {\n // Handle element marker start from popup\n case BACKGROUND_MESSAGE_TYPES.ELEMENT_MARKER_START: {\n const tabId = message.tabId;\n if (typeof tabId !== 'number') {\n sendResponse({ success: false, error: 'invalid tabId' });\n return true;\n }\n injectMarkerHelper(tabId)\n .then(() => sendResponse({ success: true }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.ELEMENT_MARKER_LIST_ALL: {\n listAllMarkers()\n .then((markers) => sendResponse({ success: true, markers }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.ELEMENT_MARKER_LIST_FOR_URL: {\n const url = String(message.url || '');\n listMarkersForUrl(url)\n .then((markers) => sendResponse({ success: true, markers }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.ELEMENT_MARKER_SAVE: {\n const req = message.marker as UpsertMarkerRequest;\n saveMarker(req)\n .then((marker) => sendResponse({ success: true, marker }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.ELEMENT_MARKER_UPDATE: {\n const marker = message.marker as ElementMarker;\n updateMarker(marker)\n .then(() => sendResponse({ success: true }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.ELEMENT_MARKER_DELETE: {\n const id = String(message.id || '');\n if (!id) {\n sendResponse({ success: false, error: 'invalid id' });\n return true;\n }\n deleteMarker(id)\n .then(() => sendResponse({ success: true }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.ELEMENT_MARKER_VALIDATE: {\n // Validate via MCP tool chain\n (async () => {\n const req = message as {\n selector: string;\n selectorType?: 'css' | 'xpath';\n action: MarkerValidationAction;\n listMode?: boolean;\n text?: string;\n keys?: string;\n button?: 'left' | 'right' | 'middle';\n bubbles?: boolean;\n cancelable?: boolean;\n modifiers?: any;\n coordinates?: { x: number; y: number };\n offsetX?: number;\n offsetY?: number;\n relativeTo?: 'element' | 'viewport';\n };\n // enrich typing with optional nav + scroll params\n (req as any).waitForNavigation = (message as any).waitForNavigation;\n (req as any).timeoutMs = (message as any).timeoutMs;\n (req as any).scrollDirection = (message as any).scrollDirection;\n (req as any).scrollAmount = (message as any).scrollAmount;\n const selector = String(req.selector || '').trim();\n const selectorType = (req.selectorType || 'css') as 'css' | 'xpath';\n const action = req.action as MarkerValidationAction;\n if (!selector) return sendResponse({ success: false, error: 'selector is required' });\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tab = tabs[0];\n if (!tab?.id) return sendResponse({ success: false, error: 'active tab not found' });\n\n // 1) Ensure helper\n try {\n await chrome.scripting.executeScript({\n target: { tabId: tab.id, allFrames: true },\n files: ['inject-scripts/accessibility-tree-helper.js'],\n world: 'ISOLATED',\n } as any);\n } catch {}\n\n // 2) Resolve selector -> ref/center via helper (same as tools)\n let ensured: any;\n try {\n ensured = await chrome.tabs.sendMessage(tab.id, {\n action: 'ensureRefForSelector',\n selector,\n isXPath: selectorType === 'xpath',\n allowMultiple: !!req.listMode,\n } as any);\n } catch (e) {\n return sendResponse({\n success: false,\n error: String(e instanceof Error ? e.message : e),\n });\n }\n if (!ensured || !ensured.success || !ensured.ref) {\n return sendResponse({\n success: false,\n error: ensured?.error || 'failed to resolve selector',\n });\n }\n\n const base = {\n success: true,\n resolved: true,\n ref: ensured.ref,\n center: ensured.center,\n } as any;\n\n // Compute optional coordinates from offsets\n let coords: { x: number; y: number } | undefined = undefined;\n if (\n req.coordinates &&\n typeof req.coordinates.x === 'number' &&\n typeof req.coordinates.y === 'number'\n ) {\n coords = { x: Math.round(req.coordinates.x), y: Math.round(req.coordinates.y) };\n } else if (\n req.relativeTo === 'element' &&\n ensured.center &&\n (typeof req.offsetX === 'number' || typeof req.offsetY === 'number')\n ) {\n const dx = Number.isFinite(req.offsetX as any) ? (req.offsetX as number) : 0;\n const dy = Number.isFinite(req.offsetY as any) ? (req.offsetY as number) : 0;\n coords = { x: ensured.center.x + dx, y: ensured.center.y + dy };\n }\n\n // 3) Dispatch to appropriate tool for end-to-end validation\n try {\n switch (action) {\n case 'hover': {\n const r = await computerTool.execute(\n coords\n ? { action: 'hover', coordinates: coords }\n : ({ action: 'hover', ref: ensured.ref } as any),\n );\n const error = r.isError ? extractToolError(r) : undefined;\n base.tool = { name: 'computer.hover', ok: !r.isError, error };\n break;\n }\n case 'left_click': {\n const r = await clickTool.execute({\n ...(coords ? { coordinates: coords } : { ref: ensured.ref }),\n waitForNavigation: !!req.waitForNavigation,\n timeout: Number.isFinite(req.timeoutMs as any)\n ? (req.timeoutMs as number)\n : 3000,\n button: (req.button || 'left') as any,\n modifiers: req.modifiers || {},\n } as any);\n const error = r.isError ? extractToolError(r) : undefined;\n base.tool = { name: 'interaction.click', ok: !r.isError, error };\n break;\n }\n case 'double_click': {\n const r = await clickTool.execute({\n ...(coords ? { coordinates: coords } : { ref: ensured.ref }),\n double: true,\n waitForNavigation: !!req.waitForNavigation,\n timeout: Number.isFinite(req.timeoutMs as any)\n ? (req.timeoutMs as number)\n : 3000,\n button: (req.button || 'left') as any,\n modifiers: req.modifiers || {},\n } as any);\n const error = r.isError ? extractToolError(r) : undefined;\n base.tool = { name: 'interaction.click(double)', ok: !r.isError, error };\n break;\n }\n case 'right_click': {\n const r = await clickTool.execute({\n ...(coords ? { coordinates: coords } : { ref: ensured.ref }),\n waitForNavigation: !!req.waitForNavigation,\n timeout: Number.isFinite(req.timeoutMs as any)\n ? (req.timeoutMs as number)\n : 3000,\n button: 'right',\n modifiers: req.modifiers || {},\n } as any);\n const error = r.isError ? extractToolError(r) : undefined;\n base.tool = { name: 'interaction.click(right)', ok: !r.isError, error };\n break;\n }\n case 'scroll': {\n const direction = (req as any).scrollDirection || 'down';\n const amount = Number.isFinite((req as any).scrollAmount)\n ? Number((req as any).scrollAmount)\n : 300;\n const payload = coords\n ? {\n action: 'scroll',\n scrollDirection: direction,\n scrollAmount: amount,\n coordinates: coords,\n }\n : ({\n action: 'scroll',\n scrollDirection: direction,\n scrollAmount: amount,\n ref: ensured.ref,\n } as any);\n const r = await computerTool.execute(payload as any);\n const error = r.isError ? extractToolError(r) : undefined;\n base.tool = { name: 'computer.scroll', ok: !r.isError, error };\n break;\n }\n case 'type_text': {\n const text = String(req.text || '');\n const r = await computerTool.execute({ action: 'type', ref: ensured.ref, text });\n const error = r.isError ? extractToolError(r) : undefined;\n base.tool = { name: 'computer.type', ok: !r.isError, error };\n break;\n }\n case 'press_keys': {\n const keys = String(req.keys || '');\n // Focus first by ref to ensure key target\n try {\n await clickTool.execute({\n ref: ensured.ref,\n waitForNavigation: false,\n timeout: 2000,\n });\n } catch {}\n const r = await keyboardTool.execute({ keys, delay: 0 } as any);\n const error = r.isError ? extractToolError(r) : undefined;\n base.tool = { name: 'keyboard.simulate', ok: !r.isError, error };\n break;\n }\n default: {\n base.tool = { name: 'noop', ok: true };\n }\n }\n } catch (e) {\n console.warn('[ElementMarker] Validation failed before tool execution', e);\n base.tool = {\n name: 'unknown',\n ok: false,\n error: String(e instanceof Error ? e.message : e),\n };\n }\n\n // Log tool failures for debugging\n if (base.tool && base.tool.ok === false) {\n console.warn('[ElementMarker] Tool validation failure', {\n action,\n toolName: base.tool.name,\n error: base.tool.error,\n selector,\n selectorType,\n });\n }\n\n return sendResponse(base);\n })();\n return true;\n }\n // When RR refresh (or similar) happens, re-add our menu\n case BACKGROUND_MESSAGE_TYPES.RR_REFRESH_TRIGGERS:\n case BACKGROUND_MESSAGE_TYPES.RR_SAVE_TRIGGER:\n case BACKGROUND_MESSAGE_TYPES.RR_DELETE_TRIGGER: {\n setTimeout(() => ensureContextMenu().catch(() => {}), 300);\n break;\n }\n }\n } catch (e) {\n sendResponse({ success: false, error: (e as any)?.message || String(e) });\n }\n return false;\n });\n\n // Context menu click routing\n if ((chrome as any).contextMenus?.onClicked?.addListener) {\n chrome.contextMenus.onClicked.addListener(async (info, tab) => {\n try {\n if (info.menuItemId === CONTEXT_MENU_ID && tab?.id) {\n await injectMarkerHelper(tab.id);\n }\n } catch (e) {\n console.warn('ElementMarker: context menu click failed:', e);\n }\n });\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/index.ts", "content": "import { initNativeHostListener } from './native-host';\nimport {\n initSemanticSimilarityListener,\n initializeSemanticEngineIfCached,\n} from './semantic-similarity';\nimport { initStorageManagerListener } from './storage-manager';\nimport { cleanupModelCache } from '@/utils/semantic-similarity-engine';\nimport { initRecordReplayListeners } from './record-replay';\nimport { initElementMarkerListeners } from './element-marker';\nimport { initWebEditorListeners } from './web-editor';\nimport { initQuickPanelAgentHandler } from './quick-panel/agent-handler';\nimport { initQuickPanelCommands } from './quick-panel/commands';\nimport { initQuickPanelTabsHandler } from './quick-panel/tabs-handler';\n\n// Record-Replay V3 (feature flag)\nimport { bootstrapV3 } from './record-replay-v3/bootstrap';\n\n/**\n * Feature flag for RR-V3\n * Set to true to enable the new Record-Replay V3 engine\n */\nconst ENABLE_RR_V3 = true;\n\n/**\n * Background script entry point\n * Initializes all background services and listeners\n */\nexport default defineBackground(() => {\n // Open welcome page on first install\n chrome.runtime.onInstalled.addListener((details) => {\n if (details.reason === 'install') {\n // Open the welcome/onboarding page for new installations\n chrome.tabs.create({\n url: chrome.runtime.getURL('/welcome.html'),\n });\n }\n });\n\n // Initialize core services\n initNativeHostListener();\n initSemanticSimilarityListener();\n initStorageManagerListener();\n // Record & Replay V1/V2 listeners\n initRecordReplayListeners();\n\n // Record & Replay V3 (new engine)\n if (ENABLE_RR_V3) {\n bootstrapV3()\n .then((runtime) => {\n console.log(`[RR-V3] Bootstrap complete, ownerId: ${runtime.ownerId}`);\n })\n .catch((error) => {\n console.error('[RR-V3] Bootstrap failed:', error);\n });\n }\n\n // Element marker: context menu + CRUD listeners\n initElementMarkerListeners();\n // Web editor: toggle edit-mode overlay\n initWebEditorListeners();\n // Quick Panel: send messages to AgentChat via background-stream bridge\n initQuickPanelAgentHandler();\n // Quick Panel: tabs search bridge for content script UI\n initQuickPanelTabsHandler();\n // Quick Panel: keyboard shortcut handler\n initQuickPanelCommands();\n\n // Conditionally initialize semantic similarity engine if model cache exists\n initializeSemanticEngineIfCached()\n .then((initialized) => {\n if (initialized) {\n console.log('Background: Semantic similarity engine initialized from cache');\n } else {\n console.log(\n 'Background: Semantic similarity engine initialization skipped (no cache found)',\n );\n }\n })\n .catch((error) => {\n console.warn('Background: Failed to conditionally initialize semantic engine:', error);\n });\n\n // Initial cleanup on startup\n cleanupModelCache().catch((error) => {\n console.warn('Background: Initial cache cleanup failed:', error);\n });\n});\n" }, { "path": "app/chrome-extension/entrypoints/background/keepalive-manager.ts", "content": "/**\n * @fileoverview Keepalive Manager\n * @description Global singleton service for managing Service Worker keepalive.\n *\n * This module provides a unified interface for acquiring and releasing keepalive\n * references. Multiple modules can acquire keepalive independently using tags,\n * and the underlying keepalive mechanism will remain active as long as at least\n * one reference is held.\n */\n\nimport {\n createOffscreenKeepaliveController,\n type KeepaliveController,\n} from './record-replay-v3/engine/keepalive/offscreen-keepalive';\n\nconst LOG_PREFIX = '[KeepaliveManager]';\n\n/**\n * Singleton keepalive controller instance.\n * Created lazily to avoid initialization issues during module loading.\n */\nlet controller: KeepaliveController | null = null;\n\n/**\n * Get or create the singleton keepalive controller.\n */\nfunction getController(): KeepaliveController {\n if (!controller) {\n controller = createOffscreenKeepaliveController({ logger: console });\n console.debug(`${LOG_PREFIX} Controller initialized`);\n }\n return controller;\n}\n\n/**\n * Acquire a keepalive reference with a tag.\n *\n * @param tag - Identifier for the reference (e.g., 'native-host', 'rr-engine')\n * @returns A release function to call when keepalive is no longer needed\n *\n * @example\n * ```typescript\n * const release = acquireKeepalive('native-host');\n * // ... do work that needs SW to stay alive ...\n * release(); // Release when done\n * ```\n */\nexport function acquireKeepalive(tag: string): () => void {\n try {\n const release = getController().acquire(tag);\n console.debug(`${LOG_PREFIX} Acquired keepalive for tag: ${tag}`);\n return () => {\n try {\n release();\n console.debug(`${LOG_PREFIX} Released keepalive for tag: ${tag}`);\n } catch (error) {\n console.warn(`${LOG_PREFIX} Failed to release keepalive for ${tag}:`, error);\n }\n };\n } catch (error) {\n console.warn(`${LOG_PREFIX} Failed to acquire keepalive for ${tag}:`, error);\n return () => {};\n }\n}\n\n/**\n * Check if keepalive is currently active (any references held).\n */\nexport function isKeepaliveActive(): boolean {\n try {\n return getController().isActive();\n } catch {\n return false;\n }\n}\n\n/**\n * Get the current keepalive reference count.\n * Useful for debugging.\n */\nexport function getKeepaliveRefCount(): number {\n try {\n return getController().getRefCount();\n } catch {\n return 0;\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/native-host.ts", "content": "import { NativeMessageType } from 'chrome-mcp-shared';\nimport { BACKGROUND_MESSAGE_TYPES } from '@/common/message-types';\nimport { NATIVE_HOST, STORAGE_KEYS, ERROR_MESSAGES, SUCCESS_MESSAGES } from '@/common/constants';\nimport { handleCallTool } from './tools';\nimport { listPublished, getFlow } from './record-replay/flow-store';\nimport { acquireKeepalive } from './keepalive-manager';\n\nconst LOG_PREFIX = '[NativeHost]';\n\nlet nativePort: chrome.runtime.Port | null = null;\nexport const HOST_NAME = NATIVE_HOST.NAME;\n\n// ==================== Reconnect Configuration ====================\n\nconst RECONNECT_BASE_DELAY_MS = 500;\nconst RECONNECT_MAX_DELAY_MS = 60_000;\nconst RECONNECT_MAX_FAST_ATTEMPTS = 8;\nconst RECONNECT_COOLDOWN_DELAY_MS = 5 * 60_000;\n\n// ==================== Auto-connect State ====================\n\nlet keepaliveRelease: (() => void) | null = null;\nlet autoConnectEnabled = true;\nlet autoConnectLoaded = false;\nlet ensurePromise: Promise | null = null;\nlet reconnectTimer: ReturnType | null = null;\nlet reconnectAttempts = 0;\nlet manualDisconnect = false;\n\n/**\n * Server status management interface\n */\ninterface ServerStatus {\n isRunning: boolean;\n port?: number;\n lastUpdated: number;\n}\n\nlet currentServerStatus: ServerStatus = {\n isRunning: false,\n lastUpdated: Date.now(),\n};\n\n/**\n * Save server status to chrome.storage\n */\nasync function saveServerStatus(status: ServerStatus): Promise {\n try {\n await chrome.storage.local.set({ [STORAGE_KEYS.SERVER_STATUS]: status });\n } catch (error) {\n console.error(ERROR_MESSAGES.SERVER_STATUS_SAVE_FAILED, error);\n }\n}\n\n/**\n * Load server status from chrome.storage\n */\nasync function loadServerStatus(): Promise {\n try {\n const result = await chrome.storage.local.get([STORAGE_KEYS.SERVER_STATUS]);\n if (result[STORAGE_KEYS.SERVER_STATUS]) {\n return result[STORAGE_KEYS.SERVER_STATUS];\n }\n } catch (error) {\n console.error(ERROR_MESSAGES.SERVER_STATUS_LOAD_FAILED, error);\n }\n return {\n isRunning: false,\n lastUpdated: Date.now(),\n };\n}\n\n/**\n * Broadcast server status change to all listeners\n */\nfunction broadcastServerStatusChange(status: ServerStatus): void {\n chrome.runtime\n .sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.SERVER_STATUS_CHANGED,\n payload: status,\n })\n .catch(() => {\n // Ignore errors if no listeners are present\n });\n}\n\n// ==================== Port Normalization ====================\n\n/**\n * Normalize a port value to a valid port number or null.\n */\nfunction normalizePort(value: unknown): number | null {\n const n =\n typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : Number.NaN;\n if (!Number.isFinite(n)) return null;\n const port = Math.floor(n);\n if (port <= 0 || port > 65535) return null;\n return port;\n}\n\n// ==================== Reconnect Utilities ====================\n\n/**\n * Add jitter to a delay value to avoid thundering herd.\n */\nfunction withJitter(ms: number): number {\n const ratio = 0.7 + Math.random() * 0.6;\n return Math.max(0, Math.round(ms * ratio));\n}\n\n/**\n * Calculate reconnect delay based on attempt number.\n * Uses exponential backoff with jitter, then switches to cooldown interval.\n */\nfunction getReconnectDelayMs(attempt: number): number {\n if (attempt >= RECONNECT_MAX_FAST_ATTEMPTS) {\n return withJitter(RECONNECT_COOLDOWN_DELAY_MS);\n }\n const delay = Math.min(RECONNECT_BASE_DELAY_MS * Math.pow(2, attempt), RECONNECT_MAX_DELAY_MS);\n return withJitter(delay);\n}\n\n/**\n * Clear the reconnect timer if active.\n */\nfunction clearReconnectTimer(): void {\n if (!reconnectTimer) return;\n clearTimeout(reconnectTimer);\n reconnectTimer = null;\n}\n\n/**\n * Reset reconnect state after successful connection.\n */\nfunction resetReconnectState(): void {\n reconnectAttempts = 0;\n clearReconnectTimer();\n}\n\n// ==================== Keepalive Management ====================\n\n/**\n * Sync keepalive hold based on autoConnectEnabled state.\n * When auto-connect is enabled, we hold a keepalive reference to keep SW alive.\n */\nfunction syncKeepaliveHold(): void {\n if (autoConnectEnabled) {\n if (!keepaliveRelease) {\n keepaliveRelease = acquireKeepalive('native-host');\n console.debug(`${LOG_PREFIX} Acquired keepalive`);\n }\n return;\n }\n if (keepaliveRelease) {\n try {\n keepaliveRelease();\n console.debug(`${LOG_PREFIX} Released keepalive`);\n } catch {\n // Ignore\n }\n keepaliveRelease = null;\n }\n}\n\n// ==================== Auto-connect Settings ====================\n\n/**\n * Load the nativeAutoConnectEnabled setting from storage.\n */\nasync function loadNativeAutoConnectEnabled(): Promise {\n try {\n const result = await chrome.storage.local.get([STORAGE_KEYS.NATIVE_AUTO_CONNECT_ENABLED]);\n const raw = result[STORAGE_KEYS.NATIVE_AUTO_CONNECT_ENABLED];\n if (typeof raw === 'boolean') return raw;\n } catch (error) {\n console.warn(`${LOG_PREFIX} Failed to load nativeAutoConnectEnabled`, error);\n }\n return true; // Default to enabled\n}\n\n/**\n * Set the nativeAutoConnectEnabled setting and persist to storage.\n */\nasync function setNativeAutoConnectEnabled(enabled: boolean): Promise {\n autoConnectEnabled = enabled;\n autoConnectLoaded = true;\n try {\n await chrome.storage.local.set({ [STORAGE_KEYS.NATIVE_AUTO_CONNECT_ENABLED]: enabled });\n console.debug(`${LOG_PREFIX} Set nativeAutoConnectEnabled=${enabled}`);\n } catch (error) {\n console.warn(`${LOG_PREFIX} Failed to persist nativeAutoConnectEnabled`, error);\n }\n syncKeepaliveHold();\n}\n\n// ==================== Port Preference ====================\n\n/**\n * Get the preferred port for connecting to native server.\n * Priority: explicit override > user preference > last known port > default\n */\nasync function getPreferredPort(override?: unknown): Promise {\n const explicit = normalizePort(override);\n if (explicit) return explicit;\n\n try {\n const result = await chrome.storage.local.get([\n STORAGE_KEYS.NATIVE_SERVER_PORT,\n STORAGE_KEYS.SERVER_STATUS,\n ]);\n\n const userPort = normalizePort(result[STORAGE_KEYS.NATIVE_SERVER_PORT]);\n if (userPort) return userPort;\n\n const status = result[STORAGE_KEYS.SERVER_STATUS] as Partial | undefined;\n const statusPort = normalizePort(status?.port);\n if (statusPort) return statusPort;\n } catch (error) {\n console.warn(`${LOG_PREFIX} Failed to read preferred port`, error);\n }\n\n const inMemoryPort = normalizePort(currentServerStatus.port);\n if (inMemoryPort) return inMemoryPort;\n\n return NATIVE_HOST.DEFAULT_PORT;\n}\n\n// ==================== Reconnect Scheduling ====================\n\n/**\n * Schedule a reconnect attempt with exponential backoff.\n */\nfunction scheduleReconnect(reason: string): void {\n if (nativePort) return;\n if (manualDisconnect) return;\n if (!autoConnectEnabled) return;\n if (reconnectTimer) return;\n\n const delay = getReconnectDelayMs(reconnectAttempts);\n console.debug(\n `${LOG_PREFIX} Reconnect scheduled in ${delay}ms (attempt=${reconnectAttempts}, reason=${reason})`,\n );\n\n reconnectTimer = setTimeout(() => {\n reconnectTimer = null;\n if (nativePort) return;\n if (manualDisconnect || !autoConnectEnabled) return;\n\n reconnectAttempts += 1;\n void ensureNativeConnected(`reconnect:${reason}`).catch(() => {});\n }, delay);\n}\n\n// ==================== Server Status Update ====================\n\n/**\n * Mark server as stopped and broadcast the change.\n */\nasync function markServerStopped(reason: string): Promise {\n currentServerStatus = {\n isRunning: false,\n port: currentServerStatus.port,\n lastUpdated: Date.now(),\n };\n try {\n await saveServerStatus(currentServerStatus);\n } catch {\n // Ignore\n }\n broadcastServerStatusChange(currentServerStatus);\n console.debug(`${LOG_PREFIX} Server marked stopped (${reason})`);\n}\n\n// ==================== Core Ensure Function ====================\n\n/**\n * Ensure native connection is established.\n * This is the main entry point for auto-connect logic.\n *\n * @param trigger - Description of what triggered this call (for logging)\n * @param portOverride - Optional explicit port to use\n * @returns Whether the connection is now established\n */\nasync function ensureNativeConnected(trigger: string, portOverride?: unknown): Promise {\n // Concurrency protection: only one ensure flow at a time\n if (ensurePromise) return ensurePromise;\n\n ensurePromise = (async () => {\n // Load auto-connect setting if not yet loaded\n if (!autoConnectLoaded) {\n autoConnectEnabled = await loadNativeAutoConnectEnabled();\n autoConnectLoaded = true;\n syncKeepaliveHold();\n }\n\n // If auto-connect is disabled, do nothing\n if (!autoConnectEnabled) {\n console.debug(`${LOG_PREFIX} Auto-connect disabled, skipping ensure (trigger=${trigger})`);\n return false;\n }\n\n // Sync keepalive hold\n syncKeepaliveHold();\n\n // Already connected\n if (nativePort) {\n console.debug(`${LOG_PREFIX} Already connected (trigger=${trigger})`);\n return true;\n }\n\n // Get the port to use\n const port = await getPreferredPort(portOverride);\n console.debug(`${LOG_PREFIX} Attempting connection on port ${port} (trigger=${trigger})`);\n\n // Attempt connection\n const ok = connectNativeHost(port);\n if (!ok) {\n console.warn(`${LOG_PREFIX} Connection failed (trigger=${trigger})`);\n scheduleReconnect(`connect_failed:${trigger}`);\n return false;\n }\n\n console.debug(`${LOG_PREFIX} Connection initiated successfully (trigger=${trigger})`);\n // Note: Don't reset reconnect state here. Wait for SERVER_STARTED confirmation.\n // Chrome may return a Port but disconnect immediately if native host is missing.\n return true;\n })().finally(() => {\n ensurePromise = null;\n });\n\n return ensurePromise;\n}\n\n/**\n * Connect to the native messaging host\n * @returns Whether the connection was initiated successfully\n */\nexport function connectNativeHost(port: number = NATIVE_HOST.DEFAULT_PORT): boolean {\n if (nativePort) {\n return true;\n }\n\n try {\n nativePort = chrome.runtime.connectNative(HOST_NAME);\n\n nativePort.onMessage.addListener(async (message) => {\n if (message.type === NativeMessageType.PROCESS_DATA && message.requestId) {\n const requestId = message.requestId;\n const requestPayload = message.payload;\n\n nativePort?.postMessage({\n responseToRequestId: requestId,\n payload: {\n status: 'success',\n message: SUCCESS_MESSAGES.TOOL_EXECUTED,\n data: requestPayload,\n },\n });\n } else if (message.type === NativeMessageType.CALL_TOOL && message.requestId) {\n const requestId = message.requestId;\n try {\n const result = await handleCallTool(message.payload);\n nativePort?.postMessage({\n responseToRequestId: requestId,\n payload: {\n status: 'success',\n message: SUCCESS_MESSAGES.TOOL_EXECUTED,\n data: result,\n },\n });\n } catch (error) {\n nativePort?.postMessage({\n responseToRequestId: requestId,\n payload: {\n status: 'error',\n message: ERROR_MESSAGES.TOOL_EXECUTION_FAILED,\n error: error instanceof Error ? error.message : String(error),\n },\n });\n }\n } else if (message.type === 'rr_list_published_flows' && message.requestId) {\n const requestId = message.requestId;\n try {\n const published = await listPublished();\n const items = [] as any[];\n for (const p of published) {\n const flow = await getFlow(p.id);\n if (!flow) continue;\n items.push({\n id: p.id,\n slug: p.slug,\n version: p.version,\n name: p.name,\n description: p.description || flow.description || '',\n variables: flow.variables || [],\n meta: flow.meta || {},\n });\n }\n nativePort?.postMessage({\n responseToRequestId: requestId,\n payload: { status: 'success', items },\n });\n } catch (error: any) {\n nativePort?.postMessage({\n responseToRequestId: requestId,\n payload: { status: 'error', error: error?.message || String(error) },\n });\n }\n } else if (message.type === NativeMessageType.SERVER_STARTED) {\n const port = message.payload?.port;\n currentServerStatus = {\n isRunning: true,\n port: port,\n lastUpdated: Date.now(),\n };\n await saveServerStatus(currentServerStatus);\n broadcastServerStatusChange(currentServerStatus);\n // Server is confirmed running - now we can reset reconnect state\n resetReconnectState();\n console.log(`${SUCCESS_MESSAGES.SERVER_STARTED} on port ${port}`);\n } else if (message.type === NativeMessageType.SERVER_STOPPED) {\n currentServerStatus = {\n isRunning: false,\n port: currentServerStatus.port, // Keep last known port for reconnection\n lastUpdated: Date.now(),\n };\n await saveServerStatus(currentServerStatus);\n broadcastServerStatusChange(currentServerStatus);\n console.log(SUCCESS_MESSAGES.SERVER_STOPPED);\n } else if (message.type === NativeMessageType.ERROR_FROM_NATIVE_HOST) {\n console.error('Error from native host:', message.payload?.message || 'Unknown error');\n } else if (message.type === 'file_operation_response') {\n // Forward file operation response back to the requesting tool\n chrome.runtime.sendMessage(message).catch(() => {\n // Ignore if no listeners\n });\n }\n });\n\n nativePort.onDisconnect.addListener(() => {\n console.warn(ERROR_MESSAGES.NATIVE_DISCONNECTED, chrome.runtime.lastError);\n nativePort = null;\n\n // Mark server as stopped since native host disconnection means server is down\n void markServerStopped('native_port_disconnected');\n\n // Handle reconnection based on disconnect reason\n if (manualDisconnect) {\n manualDisconnect = false;\n return;\n }\n if (!autoConnectEnabled) return;\n scheduleReconnect('native_port_disconnected');\n });\n\n nativePort.postMessage({ type: NativeMessageType.START, payload: { port } });\n // Note: Don't reset reconnect state here. Wait for SERVER_STARTED confirmation.\n // Chrome may return a Port but disconnect immediately if native host is missing.\n return true;\n } catch (error) {\n console.warn(ERROR_MESSAGES.NATIVE_CONNECTION_FAILED, error);\n nativePort = null;\n return false;\n }\n}\n\n/**\n * Initialize native host listeners and load initial state\n */\nexport const initNativeHostListener = () => {\n // Initialize server status from storage\n loadServerStatus()\n .then((status) => {\n currentServerStatus = status;\n })\n .catch((error) => {\n console.error(ERROR_MESSAGES.SERVER_STATUS_LOAD_FAILED, error);\n });\n\n // Auto-connect on SW activation (covers SW restart after idle termination)\n void ensureNativeConnected('sw_startup').catch(() => {});\n\n // Auto-connect on Chrome browser startup\n chrome.runtime.onStartup.addListener(() => {\n void ensureNativeConnected('onStartup').catch(() => {});\n });\n\n // Auto-connect on extension install/update\n chrome.runtime.onInstalled.addListener(() => {\n void ensureNativeConnected('onInstalled').catch(() => {});\n });\n\n chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {\n // Allow UI to call tools directly\n if (message && message.type === 'call_tool' && message.name) {\n handleCallTool({ name: message.name, args: message.args })\n .then((res) => sendResponse({ success: true, result: res }))\n .catch((err) =>\n sendResponse({ success: false, error: err instanceof Error ? err.message : String(err) }),\n );\n return true;\n }\n\n const msgType = typeof message === 'string' ? message : message?.type;\n\n // ENSURE_NATIVE: Trigger ensure without changing autoConnectEnabled\n if (msgType === NativeMessageType.ENSURE_NATIVE) {\n const portOverride = typeof message === 'object' ? message.port : undefined;\n ensureNativeConnected('ui_ensure', portOverride)\n .then((connected) => {\n sendResponse({ success: true, connected, autoConnectEnabled });\n })\n .catch((e) => {\n sendResponse({ success: false, connected: nativePort !== null, error: String(e) });\n });\n return true;\n }\n\n // CONNECT_NATIVE: Explicit user connect, re-enables auto-connect\n if (msgType === NativeMessageType.CONNECT_NATIVE) {\n const portOverride = typeof message === 'object' ? message.port : undefined;\n const normalized = normalizePort(portOverride);\n\n (async () => {\n // Explicit user connect: re-enable auto-connect\n await setNativeAutoConnectEnabled(true);\n\n if (normalized) {\n // Best-effort: persist preferred port\n try {\n await chrome.storage.local.set({ [STORAGE_KEYS.NATIVE_SERVER_PORT]: normalized });\n } catch {\n // Ignore\n }\n }\n\n return ensureNativeConnected('ui_connect', normalized ?? undefined);\n })()\n .then((connected) => {\n sendResponse({ success: true, connected });\n })\n .catch((e) => {\n sendResponse({ success: false, connected: nativePort !== null, error: String(e) });\n });\n return true;\n }\n\n if (msgType === NativeMessageType.PING_NATIVE) {\n const connected = nativePort !== null;\n sendResponse({ connected, autoConnectEnabled });\n return true;\n }\n\n // DISCONNECT_NATIVE: Explicit user disconnect, disables auto-connect\n if (msgType === NativeMessageType.DISCONNECT_NATIVE) {\n (async () => {\n // Explicit user disconnect: disable auto-connect and stop reconnect loop\n await setNativeAutoConnectEnabled(false);\n clearReconnectTimer();\n reconnectAttempts = 0;\n syncKeepaliveHold();\n\n if (nativePort) {\n // Only set manualDisconnect if we actually have a port to disconnect.\n // This prevents the flag from persisting when there's no active connection.\n manualDisconnect = true;\n try {\n nativePort.disconnect();\n } catch {\n // Ignore\n }\n nativePort = null;\n }\n await markServerStopped('manual_disconnect');\n })()\n .then(() => {\n sendResponse({ success: true });\n })\n .catch((e) => {\n sendResponse({ success: false, error: String(e) });\n });\n return true;\n }\n\n if (message.type === BACKGROUND_MESSAGE_TYPES.GET_SERVER_STATUS) {\n sendResponse({\n success: true,\n serverStatus: currentServerStatus,\n connected: nativePort !== null,\n });\n return true;\n }\n\n if (message.type === BACKGROUND_MESSAGE_TYPES.REFRESH_SERVER_STATUS) {\n loadServerStatus()\n .then((storedStatus) => {\n currentServerStatus = storedStatus;\n sendResponse({\n success: true,\n serverStatus: currentServerStatus,\n connected: nativePort !== null,\n });\n })\n .catch((error) => {\n console.error(ERROR_MESSAGES.SERVER_STATUS_LOAD_FAILED, error);\n sendResponse({\n success: false,\n error: ERROR_MESSAGES.SERVER_STATUS_LOAD_FAILED,\n serverStatus: currentServerStatus,\n connected: nativePort !== null,\n });\n });\n return true;\n }\n\n // Forward file operation messages to native host\n if (message.type === 'forward_to_native' && message.message) {\n if (nativePort) {\n nativePort.postMessage(message.message);\n sendResponse({ success: true });\n } else {\n sendResponse({ success: false, error: 'Native host not connected' });\n }\n return true;\n }\n });\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/quick-panel/agent-handler.ts", "content": "/**\n * Quick Panel Agent Handler\n *\n * Background service that bridges Quick Panel (content script) with the native-server Agent.\n * Handles message routing, SSE streaming, and lifecycle management for AI chat requests.\n *\n * Architecture:\n * - Quick Panel sends QUICK_PANEL_SEND_TO_AI via chrome.runtime.sendMessage\n * - This handler subscribes to SSE first, then fires POST /act\n * - Incoming RealtimeEvents are filtered by requestId and forwarded to the originating tab\n * - Keepalive is explicitly managed to prevent MV3 Service Worker suspension during streaming\n *\n * @see https://developer.chrome.com/docs/extensions/mv3/service_workers/\n */\n\nimport type { AgentActRequest, RealtimeEvent } from 'chrome-mcp-shared';\nimport { NativeMessageType } from 'chrome-mcp-shared';\n\nimport { NATIVE_HOST, STORAGE_KEYS } from '@/common/constants';\nimport {\n BACKGROUND_MESSAGE_TYPES,\n TOOL_MESSAGE_TYPES,\n type QuickPanelAIEventMessage,\n type QuickPanelCancelAIMessage,\n type QuickPanelCancelAIResponse,\n type QuickPanelSendToAIMessage,\n type QuickPanelSendToAIResponse,\n} from '@/common/message-types';\nimport { acquireKeepalive } from '../keepalive-manager';\nimport { openAgentChatSidepanel } from '../utils/sidepanel';\n\n// ============================================================\n// Constants\n// ============================================================\n\nconst LOG_PREFIX = '[QuickPanelAgent]';\nconst KEEPALIVE_TAG = 'quick-panel-ai';\n\n/** Storage key for AgentChat selected session ID (owned by sidepanel composables) */\nconst STORAGE_KEY_SELECTED_SESSION = 'agent-selected-session-id';\n\n/** Timeout for initial SSE connection establishment */\nconst SSE_CONNECT_TIMEOUT_MS = 3000;\n\n/** Safety timeout for entire request lifecycle (15 minutes) */\nconst REQUEST_TIMEOUT_MS = 15 * 60 * 1000;\n\n/** Flag indicating SSE connection was successful */\nconst SSE_CONNECTED = Symbol('SSE_CONNECTED');\n\n/** Flag indicating SSE connection timed out but we should continue */\nconst SSE_TIMEOUT = Symbol('SSE_TIMEOUT');\n\n// ============================================================\n// Types\n// ============================================================\n\n/**\n * Represents an active streaming request from Quick Panel.\n *\n * Background maintains this state to:\n * 1. Route SSE events to the correct tab\n * 2. Manage keepalive lifecycle\n * 3. Handle cancellation and cleanup\n */\ninterface ActiveRequest {\n readonly requestId: string;\n readonly sessionId: string;\n readonly instruction: string;\n readonly tabId: number;\n readonly windowId?: number;\n readonly frameId?: number;\n readonly port: number;\n readonly createdAt: number;\n readonly abortController: AbortController;\n readonly releaseKeepalive: () => void;\n readonly timeoutId: ReturnType;\n}\n\n// ============================================================\n// State\n// ============================================================\n\n/** Active streaming requests indexed by requestId */\nconst activeRequests = new Map();\n\n/** Initialization flag to prevent duplicate listeners */\nlet initialized = false;\n\n// ============================================================\n// Utility Functions\n// ============================================================\n\nfunction normalizeString(value: unknown): string {\n return typeof value === 'string' ? value : '';\n}\n\nfunction normalizePort(value: unknown): number | null {\n const num =\n typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : Number.NaN;\n\n if (!Number.isFinite(num)) return null;\n\n const port = Math.floor(num);\n if (port <= 0 || port > 65535) return null;\n\n return port;\n}\n\nfunction createRequestId(): string {\n // Prefer crypto.randomUUID for proper UUID format\n try {\n const id = crypto?.randomUUID?.();\n if (id) return id;\n } catch {\n // Fallback for environments without crypto.randomUUID\n }\n return `req_${Date.now()}_${Math.random().toString(16).slice(2)}`;\n}\n\nfunction sleep(ms: number): Promise {\n return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nfunction isTerminalStatus(status: string): boolean {\n return status === 'completed' || status === 'error' || status === 'cancelled';\n}\n\n// ============================================================\n// Event Factories\n// ============================================================\n\nfunction createErrorEvent(sessionId: string, requestId: string, error: string): RealtimeEvent {\n return {\n type: 'error',\n error: error || 'Unknown error',\n data: { sessionId, requestId },\n };\n}\n\nfunction createCancelledStatusEvent(\n sessionId: string,\n requestId: string,\n message?: string,\n): RealtimeEvent {\n return {\n type: 'status',\n data: {\n sessionId,\n status: 'cancelled',\n requestId,\n message: message || 'Cancelled by user',\n },\n };\n}\n\n// ============================================================\n// Event Forwarding\n// ============================================================\n\n/**\n * Forward a RealtimeEvent to the Quick Panel in the originating tab.\n * Handles receiver unavailability gracefully by cleaning up the request.\n */\nfunction forwardEventToQuickPanel(request: ActiveRequest, event: RealtimeEvent): void {\n const message: QuickPanelAIEventMessage = {\n action: TOOL_MESSAGE_TYPES.QUICK_PANEL_AI_EVENT,\n requestId: request.requestId,\n sessionId: request.sessionId,\n event,\n };\n\n const sendOptions =\n typeof request.frameId === 'number' ? { frameId: request.frameId } : undefined;\n\n const sendPromise = sendOptions\n ? chrome.tabs.sendMessage(request.tabId, message, sendOptions)\n : chrome.tabs.sendMessage(request.tabId, message);\n\n sendPromise.catch((err) => {\n const msg = err instanceof Error ? err.message : String(err);\n\n // Detect receiver unavailability (tab closed, navigated, Quick Panel closed)\n const receiverGone =\n msg.includes('Receiving end does not exist') ||\n msg.includes('No tab with id') ||\n msg.includes('The message port closed');\n\n if (receiverGone) {\n cleanupRequest(request.requestId, 'receiver_unavailable');\n }\n });\n}\n\n// ============================================================\n// Request Lifecycle Management\n// ============================================================\n\n/**\n * Clean up an active request and release all associated resources.\n * Idempotent - safe to call multiple times.\n */\nfunction cleanupRequest(requestId: string, reason: string): void {\n const request = activeRequests.get(requestId);\n if (!request) return;\n\n activeRequests.delete(requestId);\n\n // Clear timeout\n try {\n clearTimeout(request.timeoutId);\n } catch {\n // Ignore\n }\n\n // Abort SSE connection\n try {\n request.abortController.abort();\n } catch {\n // Ignore\n }\n\n // Release keepalive\n try {\n request.releaseKeepalive();\n } catch {\n // Ignore\n }\n\n console.debug(`${LOG_PREFIX} Cleaned up request ${requestId} (${reason})`);\n}\n\n// ============================================================\n// Session Validation\n// ============================================================\n\n/**\n * Validate that the selected session exists on the native server.\n * Returns false if the session is invalid or server is unreachable.\n */\nasync function validateSession(port: number, sessionId: string): Promise {\n const url = `http://127.0.0.1:${port}/agent/sessions/${encodeURIComponent(sessionId)}`;\n try {\n const response = await fetch(url);\n return response.ok;\n } catch {\n return false;\n }\n}\n\n// ============================================================\n// SSE Event Filtering\n// ============================================================\n\n/**\n * Determine if a RealtimeEvent should be forwarded for a specific requestId.\n *\n * Events without requestId (connected, heartbeat) are session-level signals\n * and are not forwarded to avoid confusion with request-specific events.\n */\nfunction shouldForwardEvent(event: RealtimeEvent, requestId: string): boolean {\n switch (event.type) {\n case 'message':\n return event.data?.requestId === requestId;\n case 'status':\n return event.data?.requestId === requestId;\n case 'usage':\n return event.data?.requestId === requestId;\n case 'error':\n return event.data?.requestId === requestId;\n case 'connected':\n case 'heartbeat':\n // Session-level signals, not request-scoped\n return false;\n default:\n return false;\n }\n}\n\n// ============================================================\n// SSE Subscription\n// ============================================================\n\ninterface SseSubscription {\n /**\n * Resolves with true when SSE connection is established.\n * Resolves with false if connection failed (request was cleaned up).\n */\n ready: Promise;\n /** Resolves when SSE stream ends (normally or due to error/abort) */\n done: Promise;\n}\n\n/**\n * Create an SSE subscription for the request's session.\n *\n * The subscription:\n * 1. Connects to the session's /stream endpoint\n * 2. Filters events by requestId\n * 3. Forwards matching events to Quick Panel\n * 4. Triggers cleanup on terminal status\n *\n * @returns SseSubscription with ready promise that resolves to:\n * - true: SSE connected successfully\n * - false: SSE failed (request was cleaned up, don't send /act)\n */\nfunction createSseSubscription(request: ActiveRequest): SseSubscription {\n // Track whether ready has been resolved\n let readySettled = false;\n let readyResolve: (connected: boolean) => void;\n\n const ready = new Promise((resolve) => {\n readyResolve = resolve;\n });\n\n // Helper to resolve ready exactly once\n const settleReady = (connected: boolean): void => {\n if (readySettled) return;\n readySettled = true;\n readyResolve(connected);\n };\n\n const done = (async () => {\n const sseUrl = `http://127.0.0.1:${request.port}/agent/chat/${encodeURIComponent(request.sessionId)}/stream`;\n\n try {\n const response = await fetch(sseUrl, {\n method: 'GET',\n headers: { Accept: 'text/event-stream' },\n signal: request.abortController.signal,\n });\n\n if (!response.ok || !response.body) {\n throw new Error(`SSE stream unavailable (HTTP ${response.status})`);\n }\n\n // Signal that SSE is connected successfully\n settleReady(true);\n\n const reader = response.body.getReader();\n const decoder = new TextDecoder();\n let buffer = '';\n\n // Read and parse SSE stream\n while (true) {\n const { done, value } = await reader.read();\n if (done) break;\n\n buffer += decoder.decode(value, { stream: true });\n const lines = buffer.split('\\n');\n buffer = lines.pop() ?? '';\n\n for (const line of lines) {\n if (!line.startsWith('data:')) continue;\n const raw = line.slice(5).trim();\n if (!raw) continue;\n\n try {\n const event = JSON.parse(raw) as RealtimeEvent;\n\n // Filter by requestId to prevent cross-request leakage\n if (!shouldForwardEvent(event, request.requestId)) {\n continue;\n }\n\n forwardEventToQuickPanel(request, event);\n\n // Cleanup on terminal status\n if (event.type === 'status' && event.data?.requestId === request.requestId) {\n if (isTerminalStatus(event.data.status)) {\n cleanupRequest(request.requestId, `terminal_status:${event.data.status}`);\n return;\n }\n }\n } catch {\n // Ignore parse errors (best-effort stream processing)\n }\n }\n }\n } catch (err) {\n // AbortError is intentional (cancellation or cleanup)\n if (err instanceof Error && err.name === 'AbortError') {\n // Signal not connected if aborted before connecting\n settleReady(false);\n return;\n }\n\n // Surface error to UI and cleanup if request is still active\n if (activeRequests.has(request.requestId)) {\n const msg = err instanceof Error ? err.message : String(err);\n forwardEventToQuickPanel(\n request,\n createErrorEvent(request.sessionId, request.requestId, msg),\n );\n cleanupRequest(request.requestId, 'sse_error');\n }\n\n // Signal failed connection\n settleReady(false);\n }\n })();\n\n return { ready, done };\n}\n\n// ============================================================\n// Agent API\n// ============================================================\n\n/**\n * Send the act request to native-server.\n * The server will emit events via SSE which are already being subscribed.\n *\n * @param request - Active request context\n * @throws Error if request was cancelled/aborted or HTTP request fails\n */\nasync function postActRequest(request: ActiveRequest): Promise {\n // Check if request was cancelled before sending\n if (request.abortController.signal.aborted) {\n throw new Error('Request was cancelled');\n }\n\n const url = `http://127.0.0.1:${request.port}/agent/chat/${encodeURIComponent(request.sessionId)}/act`;\n\n const payload: AgentActRequest = {\n instruction: request.instruction,\n // Ensures session-level config is loaded (engine, model, options, project binding)\n dbSessionId: request.sessionId,\n // Enables SSE-first flow and requestId filtering on session-scoped streams\n requestId: request.requestId,\n };\n\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(payload),\n signal: request.abortController.signal,\n });\n\n if (!response.ok) {\n const text = await response.text().catch(() => '');\n throw new Error(text || `HTTP ${response.status}`);\n }\n}\n\n/**\n * Cancel an active request on the native-server.\n */\nasync function cancelRequestOnServer(\n port: number,\n sessionId: string,\n requestId: string,\n): Promise {\n const url = `http://127.0.0.1:${port}/agent/chat/${encodeURIComponent(sessionId)}/cancel/${encodeURIComponent(requestId)}`;\n try {\n await fetch(url, { method: 'DELETE' });\n } catch {\n // Best-effort: cancellation might still succeed if request already ended\n }\n}\n\n// ============================================================\n// Request Orchestration\n// ============================================================\n\n/**\n * Check if the request is still active and not cancelled.\n * Used as a guard before each async operation to handle race conditions.\n */\nfunction isRequestStillActive(request: ActiveRequest): boolean {\n return activeRequests.has(request.requestId) && !request.abortController.signal.aborted;\n}\n\n/**\n * Main orchestration function for starting a Quick Panel AI request.\n *\n * Flow:\n * 1. Ensure native server is running\n * 2. Validate session exists\n * 3. Open sidepanel (best-effort)\n * 4. Start SSE subscription (wait for connection)\n * 5. Fire act request\n * 6. Let SSE handle event forwarding and cleanup\n *\n * @remarks\n * Guards are placed after each async operation to handle cancellation races.\n */\nasync function startRequest(request: ActiveRequest): Promise {\n try {\n // Best-effort: ensure native server is running\n await chrome.runtime.sendMessage({ type: NativeMessageType.ENSURE_NATIVE }).catch(() => null);\n\n // Guard: check if cancelled during ENSURE_NATIVE\n if (!isRequestStillActive(request)) return;\n\n // Validate session still exists\n const sessionValid = await validateSession(request.port, request.sessionId);\n\n // Guard: check if cancelled during validation\n if (!isRequestStillActive(request)) return;\n\n if (!sessionValid) {\n forwardEventToQuickPanel(\n request,\n createErrorEvent(\n request.sessionId,\n request.requestId,\n 'Selected Agent session is not available. Please open AgentChat and select a valid session.',\n ),\n );\n // Open sidepanel without deep-linking to invalid session\n openAgentChatSidepanel(request.tabId, request.windowId).catch(() => {});\n cleanupRequest(request.requestId, 'session_invalid');\n return;\n }\n\n // Best-effort: open sidepanel deep-linked to current session\n openAgentChatSidepanel(request.tabId, request.windowId, request.sessionId).catch(() => {});\n\n // Start SSE subscription BEFORE sending act request to avoid missing early events\n const sse = createSseSubscription(request);\n\n // Wait for SSE connection with timeout\n // The race returns either:\n // - boolean from sse.ready (true=connected, false=failed)\n // - undefined from timeout (treat as \"proceed with caution\")\n const sseResult = await Promise.race([\n sse.ready,\n sleep(SSE_CONNECT_TIMEOUT_MS).then(() => SSE_TIMEOUT),\n ]);\n\n // Guard: check if cancelled during SSE connection\n if (!isRequestStillActive(request)) return;\n\n // If SSE explicitly failed (returned false), don't send /act\n // The SSE subscription already cleaned up and sent error to UI\n if (sseResult === false) {\n console.debug(`${LOG_PREFIX} SSE failed for ${request.requestId}, not sending /act`);\n return;\n }\n\n // If SSE timed out, log warning but continue (degraded experience)\n if (sseResult === SSE_TIMEOUT) {\n console.warn(\n `${LOG_PREFIX} SSE connection timed out for ${request.requestId}, proceeding anyway`,\n );\n }\n\n // Fire the act request\n await postActRequest(request);\n\n // SSE subscription continues running and will handle cleanup on terminal status\n void sse.done;\n } catch (err) {\n // Abort errors are expected during cancellation\n if (err instanceof Error && err.name === 'AbortError') {\n return;\n }\n\n // Request may have been cleaned up already\n if (!activeRequests.has(request.requestId)) return;\n\n const msg = err instanceof Error ? err.message : String(err);\n forwardEventToQuickPanel(request, createErrorEvent(request.sessionId, request.requestId, msg));\n cleanupRequest(request.requestId, 'start_failed');\n }\n}\n\n// ============================================================\n// Message Handlers\n// ============================================================\n\n/**\n * Handle QUICK_PANEL_SEND_TO_AI message.\n * Creates a new streaming request and starts the orchestration flow.\n */\nasync function handleSendToAI(\n message: QuickPanelSendToAIMessage,\n sender: chrome.runtime.MessageSender,\n): Promise {\n const tabId = sender?.tab?.id;\n const windowId = sender?.tab?.windowId;\n const frameId = typeof sender?.frameId === 'number' ? sender.frameId : undefined;\n\n if (typeof tabId !== 'number') {\n return { success: false, error: 'Quick Panel request must originate from a tab.' };\n }\n\n const instruction = normalizeString(message?.payload?.instruction).trim();\n if (!instruction) {\n return { success: false, error: 'instruction is required' };\n }\n\n // Read server port and selected session from storage\n const stored = await chrome.storage.local.get([\n STORAGE_KEYS.NATIVE_SERVER_PORT,\n STORAGE_KEY_SELECTED_SESSION,\n ]);\n\n const port = normalizePort(stored?.[STORAGE_KEYS.NATIVE_SERVER_PORT]) ?? NATIVE_HOST.DEFAULT_PORT;\n const sessionId = normalizeString(stored?.[STORAGE_KEY_SELECTED_SESSION]).trim();\n\n if (!sessionId) {\n // No session selected: open sidepanel for user to select/create one\n openAgentChatSidepanel(tabId, windowId).catch(() => {});\n return {\n success: false,\n error:\n 'No Agent session selected. Please open AgentChat, select or create a session, then try again.',\n };\n }\n\n // Create request state\n const requestId = createRequestId();\n const releaseKeepalive = acquireKeepalive(KEEPALIVE_TAG);\n const abortController = new AbortController();\n\n // Safety timeout to prevent infinite streaming\n const timeoutId = setTimeout(() => {\n const activeRequest = activeRequests.get(requestId);\n if (!activeRequest) return;\n\n forwardEventToQuickPanel(\n activeRequest,\n createErrorEvent(\n activeRequest.sessionId,\n activeRequest.requestId,\n 'Quick Panel stream timed out. Please continue in AgentChat sidepanel.',\n ),\n );\n cleanupRequest(requestId, 'timeout');\n }, REQUEST_TIMEOUT_MS);\n\n const request: ActiveRequest = {\n requestId,\n sessionId,\n instruction,\n tabId,\n windowId: typeof windowId === 'number' ? windowId : undefined,\n frameId,\n port,\n createdAt: Date.now(),\n abortController,\n releaseKeepalive,\n timeoutId,\n };\n\n activeRequests.set(requestId, request);\n\n // Start the request asynchronously (don't await)\n void startRequest(request);\n\n return { success: true, requestId, sessionId };\n}\n\n/**\n * Handle QUICK_PANEL_CANCEL_AI message.\n * Cancels an active request both locally and on the server.\n */\nasync function handleCancelAI(\n message: QuickPanelCancelAIMessage,\n sender: chrome.runtime.MessageSender,\n): Promise {\n const tabId = sender?.tab?.id;\n const frameId = typeof sender?.frameId === 'number' ? sender.frameId : undefined;\n\n if (typeof tabId !== 'number') {\n return { success: false, error: 'Cancel request must originate from a tab.' };\n }\n\n const requestId = normalizeString(message?.payload?.requestId).trim();\n const fallbackSessionId = normalizeString(message?.payload?.sessionId).trim();\n\n if (!requestId) {\n return { success: false, error: 'requestId is required' };\n }\n\n const activeRequest = activeRequests.get(requestId);\n const sessionId = activeRequest?.sessionId || fallbackSessionId;\n\n if (!sessionId) {\n return {\n success: false,\n error: 'Unknown sessionId for this request. Please cancel from AgentChat sidepanel.',\n };\n }\n\n // Abort SSE immediately for responsive UX\n if (activeRequest) {\n try {\n activeRequest.abortController.abort();\n } catch {\n // Ignore\n }\n }\n\n // Determine port\n let port = activeRequest?.port;\n if (!port) {\n const stored = await chrome.storage.local.get([STORAGE_KEYS.NATIVE_SERVER_PORT]);\n port = normalizePort(stored?.[STORAGE_KEYS.NATIVE_SERVER_PORT]) ?? NATIVE_HOST.DEFAULT_PORT;\n }\n\n // Cancel on server (async, don't await)\n void cancelRequestOnServer(port, sessionId, requestId);\n\n // Send synthetic cancelled status to UI\n const cancelledEvent = createCancelledStatusEvent(sessionId, requestId);\n const eventMessage: QuickPanelAIEventMessage = {\n action: TOOL_MESSAGE_TYPES.QUICK_PANEL_AI_EVENT,\n requestId,\n sessionId,\n event: cancelledEvent,\n };\n\n const sendOptions = typeof frameId === 'number' ? { frameId } : undefined;\n const sendPromise = sendOptions\n ? chrome.tabs.sendMessage(tabId, eventMessage, sendOptions)\n : chrome.tabs.sendMessage(tabId, eventMessage);\n\n sendPromise\n .catch(() => {})\n .finally(() => {\n cleanupRequest(requestId, 'cancelled_by_user');\n });\n\n return { success: true };\n}\n\n// ============================================================\n// Initialization\n// ============================================================\n\n/**\n * Initialize the Quick Panel Agent Handler.\n * Sets up message listeners and tab cleanup handlers.\n */\nexport function initQuickPanelAgentHandler(): void {\n if (initialized) return;\n initialized = true;\n\n // Message listener for Quick Panel messages\n chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {\n // Handle QUICK_PANEL_SEND_TO_AI\n if (message?.type === BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_SEND_TO_AI) {\n handleSendToAI(message as QuickPanelSendToAIMessage, sender)\n .then(sendResponse)\n .catch((err) => {\n const msg = err instanceof Error ? err.message : String(err);\n sendResponse({ success: false, error: msg || 'Unknown error' });\n });\n return true; // Async response\n }\n\n // Handle QUICK_PANEL_CANCEL_AI\n if (message?.type === BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_CANCEL_AI) {\n handleCancelAI(message as QuickPanelCancelAIMessage, sender)\n .then(sendResponse)\n .catch((err) => {\n const msg = err instanceof Error ? err.message : String(err);\n sendResponse({ success: false, error: msg || 'Unknown error' });\n });\n return true; // Async response\n }\n\n return false;\n });\n\n // Clean up requests when their tab is closed\n chrome.tabs.onRemoved.addListener((tabId) => {\n for (const [requestId, request] of activeRequests) {\n if (request.tabId === tabId) {\n cleanupRequest(requestId, 'tab_removed');\n }\n }\n });\n\n console.debug(`${LOG_PREFIX} Initialized`);\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/quick-panel/commands.ts", "content": "/**\n * Quick Panel Commands Handler\n *\n * Handles keyboard shortcuts for Quick Panel functionality.\n * Listens for the 'toggle_quick_panel' command and sends toggle message\n * to the content script in the active tab.\n */\n\n// ============================================================\n// Constants\n// ============================================================\n\nconst COMMAND_KEY = 'toggle_quick_panel';\nconst LOG_PREFIX = '[QuickPanelCommands]';\n\n// ============================================================\n// Helpers\n// ============================================================\n\n/**\n * Get the ID of the currently active tab\n */\nasync function getActiveTabId(): Promise {\n try {\n const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });\n return tab?.id ?? null;\n } catch (err) {\n console.warn(`${LOG_PREFIX} Failed to get active tab:`, err);\n return null;\n }\n}\n\n/**\n * Check if a tab can receive content scripts\n */\nfunction isValidTabUrl(url?: string): boolean {\n if (!url) return false;\n\n // Cannot inject into browser internal pages\n const invalidPrefixes = [\n 'chrome://',\n 'chrome-extension://',\n 'edge://',\n 'about:',\n 'moz-extension://',\n 'devtools://',\n 'view-source:',\n 'data:',\n // 'file://',\n ];\n\n return !invalidPrefixes.some((prefix) => url.startsWith(prefix));\n}\n\n// ============================================================\n// Main Handler\n// ============================================================\n\n/**\n * Toggle Quick Panel in the active tab\n */\nasync function toggleQuickPanelInActiveTab(): Promise {\n const tabId = await getActiveTabId();\n if (tabId === null) {\n console.warn(`${LOG_PREFIX} No active tab found`);\n return;\n }\n\n // Get tab info to check URL validity\n try {\n const tab = await chrome.tabs.get(tabId);\n if (!isValidTabUrl(tab.url)) {\n console.warn(`${LOG_PREFIX} Cannot inject into tab URL: ${tab.url}`);\n return;\n }\n } catch (err) {\n console.warn(`${LOG_PREFIX} Failed to get tab info:`, err);\n return;\n }\n\n // Send toggle message to content script\n try {\n const response = await chrome.tabs.sendMessage(tabId, { action: 'toggle_quick_panel' });\n if (response?.success) {\n console.log(`${LOG_PREFIX} Quick Panel toggled, visible: ${response.visible}`);\n } else {\n console.warn(`${LOG_PREFIX} Toggle failed:`, response?.error);\n }\n } catch (err) {\n // Content script may not be loaded yet; this is expected on some pages\n console.warn(\n `${LOG_PREFIX} Failed to send toggle message (content script may not be loaded):`,\n err,\n );\n }\n}\n\n// ============================================================\n// Initialization\n// ============================================================\n\n/**\n * Initialize Quick Panel keyboard command listener\n */\nexport function initQuickPanelCommands(): void {\n console.log(`${LOG_PREFIX} initQuickPanelCommands called`);\n chrome.commands.onCommand.addListener(async (command) => {\n console.log(`${LOG_PREFIX} onCommand received:`, command);\n if (command !== COMMAND_KEY) {\n console.log(`${LOG_PREFIX} Command not matched, expected:`, COMMAND_KEY);\n return;\n }\n console.log(`${LOG_PREFIX} Command matched, calling toggleQuickPanelInActiveTab...`);\n\n try {\n await toggleQuickPanelInActiveTab();\n console.log(`${LOG_PREFIX} toggleQuickPanelInActiveTab completed`);\n } catch (err) {\n console.error(`${LOG_PREFIX} Command handler error:`, err);\n }\n });\n\n console.log(`${LOG_PREFIX} Command listener registered for: ${COMMAND_KEY}`);\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/quick-panel/tabs-handler.ts", "content": "/**\n * Quick Panel Tabs Handler\n *\n * Background service worker bridge for Quick Panel (content script) to:\n * - Enumerate tabs for search suggestions\n * - Activate a selected tab\n * - Close a tab\n *\n * Note: Content scripts cannot access chrome.tabs.* directly.\n */\n\nimport {\n BACKGROUND_MESSAGE_TYPES,\n type QuickPanelActivateTabMessage,\n type QuickPanelActivateTabResponse,\n type QuickPanelCloseTabMessage,\n type QuickPanelCloseTabResponse,\n type QuickPanelTabSummary,\n type QuickPanelTabsQueryMessage,\n type QuickPanelTabsQueryResponse,\n} from '@/common/message-types';\n\n// ============================================================\n// Constants\n// ============================================================\n\nconst LOG_PREFIX = '[QuickPanelTabs]';\n\n// ============================================================\n// Helpers\n// ============================================================\n\nfunction isValidTabId(value: unknown): value is number {\n return typeof value === 'number' && Number.isFinite(value) && value > 0;\n}\n\nfunction isValidWindowId(value: unknown): value is number {\n return typeof value === 'number' && Number.isFinite(value) && value > 0;\n}\n\nfunction normalizeBoolean(value: unknown): boolean {\n return value === true;\n}\n\nfunction getLastAccessed(tab: chrome.tabs.Tab): number | undefined {\n const anyTab = tab as unknown as { lastAccessed?: unknown };\n const value = anyTab.lastAccessed;\n return typeof value === 'number' && Number.isFinite(value) ? value : undefined;\n}\n\nfunction safeErrorMessage(err: unknown): string {\n if (err instanceof Error) {\n return err.message || String(err);\n }\n return String(err);\n}\n\n/**\n * Convert a chrome.tabs.Tab to our summary format.\n * Returns null if tab is invalid.\n */\nfunction toTabSummary(tab: chrome.tabs.Tab): QuickPanelTabSummary | null {\n if (!isValidTabId(tab.id)) return null;\n\n const windowId = isValidWindowId(tab.windowId) ? tab.windowId : null;\n if (windowId === null) return null;\n\n return {\n tabId: tab.id,\n windowId,\n title: tab.title ?? '',\n url: tab.url ?? '',\n favIconUrl: tab.favIconUrl ?? undefined,\n active: normalizeBoolean(tab.active),\n pinned: normalizeBoolean(tab.pinned),\n audible: normalizeBoolean(tab.audible),\n muted: normalizeBoolean(tab.mutedInfo?.muted),\n index: typeof tab.index === 'number' && Number.isFinite(tab.index) ? tab.index : 0,\n lastAccessed: getLastAccessed(tab),\n };\n}\n\n// ============================================================\n// Message Handlers\n// ============================================================\n\nasync function handleTabsQuery(\n message: QuickPanelTabsQueryMessage,\n sender: chrome.runtime.MessageSender,\n): Promise {\n try {\n const includeAllWindows = message.payload?.includeAllWindows ?? true;\n\n // Extract current context from sender\n const currentWindowId = isValidWindowId(sender.tab?.windowId) ? sender.tab!.windowId : null;\n const currentTabId = isValidTabId(sender.tab?.id) ? sender.tab!.id : null;\n\n // Quick Panel should only be called from content scripts (which have sender.tab)\n // Reject requests without valid sender tab context for security\n if (!includeAllWindows && currentWindowId === null) {\n return {\n success: false,\n error: 'Invalid request: sender tab context required for window-scoped queries',\n };\n }\n\n // Build query info based on scope\n const queryInfo: chrome.tabs.QueryInfo = includeAllWindows\n ? {}\n : { windowId: currentWindowId! };\n\n const tabs = await chrome.tabs.query(queryInfo);\n\n // Convert to summaries, filtering out invalid tabs\n const summaries: QuickPanelTabSummary[] = [];\n for (const tab of tabs) {\n const summary = toTabSummary(tab);\n if (summary) {\n summaries.push(summary);\n }\n }\n\n return {\n success: true,\n tabs: summaries,\n currentTabId,\n currentWindowId,\n };\n } catch (err) {\n console.warn(`${LOG_PREFIX} Error querying tabs:`, err);\n return {\n success: false,\n error: safeErrorMessage(err) || 'Failed to query tabs',\n };\n }\n}\n\nasync function handleActivateTab(\n message: QuickPanelActivateTabMessage,\n): Promise {\n try {\n const tabId = message.payload?.tabId;\n const windowId = message.payload?.windowId;\n\n if (!isValidTabId(tabId)) {\n return { success: false, error: 'Invalid tabId' };\n }\n\n // Focus the window first if provided\n if (isValidWindowId(windowId)) {\n try {\n await chrome.windows.update(windowId, { focused: true });\n } catch {\n // Best-effort: tab activation may still succeed without focusing window.\n }\n }\n\n // Activate the tab\n await chrome.tabs.update(tabId, { active: true });\n\n return { success: true };\n } catch (err) {\n console.warn(`${LOG_PREFIX} Error activating tab:`, err);\n return {\n success: false,\n error: safeErrorMessage(err) || 'Failed to activate tab',\n };\n }\n}\n\nasync function handleCloseTab(\n message: QuickPanelCloseTabMessage,\n): Promise {\n try {\n const tabId = message.payload?.tabId;\n\n if (!isValidTabId(tabId)) {\n return { success: false, error: 'Invalid tabId' };\n }\n\n await chrome.tabs.remove(tabId);\n\n return { success: true };\n } catch (err) {\n console.warn(`${LOG_PREFIX} Error closing tab:`, err);\n return {\n success: false,\n error: safeErrorMessage(err) || 'Failed to close tab',\n };\n }\n}\n\n// ============================================================\n// Initialization\n// ============================================================\n\nlet initialized = false;\n\n/**\n * Initialize the Quick Panel Tabs handler.\n * Safe to call multiple times - subsequent calls are no-ops.\n */\nexport function initQuickPanelTabsHandler(): void {\n if (initialized) return;\n initialized = true;\n\n chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {\n // Tabs query\n if (message?.type === BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_TABS_QUERY) {\n handleTabsQuery(message as QuickPanelTabsQueryMessage, sender).then(sendResponse);\n return true; // Will respond asynchronously\n }\n\n // Tab activate\n if (message?.type === BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_TAB_ACTIVATE) {\n handleActivateTab(message as QuickPanelActivateTabMessage).then(sendResponse);\n return true;\n }\n\n // Tab close\n if (message?.type === BACKGROUND_MESSAGE_TYPES.QUICK_PANEL_TAB_CLOSE) {\n handleCloseTab(message as QuickPanelCloseTabMessage).then(sendResponse);\n return true;\n }\n\n return false; // Not handled by this listener\n });\n\n console.debug(`${LOG_PREFIX} Initialized`);\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/adapter.ts", "content": "/**\n * Adapter Layer: Step ↔ Action\n *\n * Provides conversion utilities between the legacy Step system and the new Action system.\n * This adapter enables gradual migration while maintaining backward compatibility.\n *\n * Architecture:\n * - `stepToAction`: Converts a Step to an ExecutableAction\n * - `execCtxToActionCtx`: Converts ExecCtx to ActionExecutionContext\n * - `actionResultToExecResult`: Converts ActionExecutionResult to ExecResult\n * - `createStepExecutor`: Factory for a Step executor backed by ActionRegistry\n */\n\nimport type { ExecCtx, ExecResult } from '../nodes/types';\nimport type { Step } from '../types';\nimport type { ActionRegistry } from './registry';\nimport type {\n ActionExecutionContext,\n ActionExecutionResult,\n ActionPolicy,\n ExecutableAction,\n ExecutableActionType,\n ExecutionFlags,\n VariableStore,\n} from './types';\n\n// ================================\n// Type Mapping\n// ================================\n\n/**\n * Map legacy step types to new action types\n * Most types map 1:1, but some require special handling\n */\nconst STEP_TYPE_TO_ACTION_TYPE: Record = {\n // Interaction\n click: 'click',\n dblclick: 'dblclick',\n fill: 'fill',\n key: 'key',\n scroll: 'scroll',\n drag: 'drag',\n\n // Timing\n wait: 'wait',\n delay: 'delay',\n\n // Validation\n assert: 'assert',\n\n // Data\n extract: 'extract',\n script: 'script',\n http: 'http',\n screenshot: 'screenshot',\n\n // Navigation / Tabs\n navigate: 'navigate',\n openTab: 'openTab',\n switchTab: 'switchTab',\n closeTab: 'closeTab',\n handleDownload: 'handleDownload',\n\n // Control Flow\n if: 'if',\n foreach: 'foreach',\n while: 'while',\n switchFrame: 'switchFrame',\n\n // TODO: Add when handlers are implemented\n // triggerEvent: 'triggerEvent',\n // setAttribute: 'setAttribute',\n // loopElements: 'loopElements',\n // executeFlow: 'executeFlow',\n};\n\n// ================================\n// Context Conversion\n// ================================\n\n/**\n * Convert legacy ExecCtx to ActionExecutionContext\n */\nexport function execCtxToActionCtx(\n ctx: ExecCtx,\n tabId: number,\n options?: {\n stepId?: string;\n runId?: string;\n pushLog?: (entry: unknown) => void;\n /** Execution flags to pass to action handlers */\n execution?: ExecutionFlags;\n },\n): ActionExecutionContext {\n // Use provided stepId for proper log attribution, fallback to 'action' only if not provided\n const logStepId = options?.stepId || 'action';\n return {\n vars: ctx.vars as VariableStore,\n tabId,\n frameId: ctx.frameId,\n runId: options?.runId,\n log: (message: string, level?: 'info' | 'warn' | 'error') => {\n ctx.logger({\n stepId: logStepId,\n status: level === 'error' ? 'failed' : level === 'warn' ? 'warning' : 'success',\n message,\n });\n },\n pushLog: options?.pushLog,\n execution: options?.execution,\n };\n}\n\n// ================================\n// Step → Action Conversion\n// ================================\n\n/**\n * Convert a legacy Step to an ExecutableAction\n *\n * The conversion maps step properties to action params and policy.\n * Unknown step types are passed through as-is for forward compatibility.\n */\nexport function stepToAction(step: Step): ExecutableAction | null {\n const actionType = STEP_TYPE_TO_ACTION_TYPE[step.type];\n\n if (!actionType) {\n // Unsupported step type\n return null;\n }\n\n // Build policy if step has timeout or retry config\n let policy: ActionPolicy | undefined;\n if (step.timeoutMs || step.retry) {\n policy = {};\n\n if (step.timeoutMs) {\n policy.timeout = { ms: step.timeoutMs };\n }\n\n if (step.retry) {\n policy.retry = {\n retries: step.retry.count ?? 0,\n intervalMs: step.retry.intervalMs ?? 0,\n // Step backoff only supports 'none' | 'exp', map to Action backoff type\n backoff: step.retry.backoff === 'exp' ? 'exp' : 'none',\n };\n }\n }\n\n // Build base action - use type assertion for generic action\n // Note: Step doesn't have name/disabled at base level, they are on NodeBase\n const action = {\n id: step.id,\n type: actionType,\n params: extractParams(step),\n policy,\n } as ExecutableAction;\n\n return action;\n}\n\n/**\n * Legacy SelectorCandidate format: { type, value, weight? }\n * Action SelectorCandidate format: { type, selector/xpath/text/etc, weight? }\n */\ninterface LegacySelectorCandidate {\n type: string;\n value: string;\n weight?: number;\n}\n\ninterface LegacyTargetLocator {\n ref?: string;\n candidates: LegacySelectorCandidate[];\n // Additional fields from recorder\n selector?: string;\n tag?: string;\n}\n\n/**\n * Parse legacy ARIA value format\n * Formats:\n * - \"role[name=...]\" (e.g., \"button[name=\\\"Submit\\\"]\")\n * - \"aria-label=...\" (role-less, just name)\n */\nfunction parseAriaValue(value: string): { role?: string; name: string } {\n // Try \"role[name=...]\" format\n const roleMatch = value.match(/^([a-zA-Z]+)\\[name=[\"']?(.+?)[\"']?\\]$/);\n if (roleMatch) {\n return { role: roleMatch[1], name: roleMatch[2] };\n }\n\n // Try \"aria-label=...\" format\n const labelMatch = value.match(/^aria-label=[\"']?(.+?)[\"']?$/);\n if (labelMatch) {\n return { name: labelMatch[1] };\n }\n\n // Fallback: treat entire value as name\n return { name: value };\n}\n\n/**\n * Convert legacy SelectorCandidate to Action SelectorCandidate\n */\nfunction convertSelectorCandidate(legacy: LegacySelectorCandidate): Record {\n const base: Record = { type: legacy.type };\n if (typeof legacy.weight === 'number') {\n base.weight = legacy.weight;\n }\n\n switch (legacy.type) {\n case 'css':\n case 'attr':\n // CSS and attr use 'selector' field\n base.selector = legacy.value;\n break;\n case 'xpath':\n // XPath uses 'xpath' field\n base.xpath = legacy.value;\n break;\n case 'text':\n // Text uses 'text' field\n base.text = legacy.value;\n break;\n case 'aria': {\n // ARIA: parse \"role[name=...]\" or \"aria-label=...\" format\n const parsed = parseAriaValue(legacy.value);\n if (parsed.role) {\n base.role = parsed.role;\n }\n base.name = parsed.name;\n break;\n }\n default:\n // Unknown type, pass through as-is\n base.value = legacy.value;\n }\n\n return base;\n}\n\n/**\n * Convert legacy TargetLocator to Action ElementTarget\n * Preserves additional fields like selector and tag for locator optimization\n */\nfunction convertTargetLocator(target: LegacyTargetLocator): Record {\n const result: Record = {};\n\n if (target.ref) {\n result.ref = target.ref;\n }\n\n // Preserve selector field for fast-path (e.g., #id selectors)\n if (typeof target.selector === 'string' && target.selector.trim()) {\n result.selector = target.selector;\n }\n\n // Preserve tag hint for text/aria matching\n if (typeof target.tag === 'string' && target.tag.trim()) {\n result.hint = { tagName: target.tag };\n }\n\n if (Array.isArray(target.candidates) && target.candidates.length > 0) {\n result.candidates = target.candidates.map(convertSelectorCandidate);\n }\n\n return result;\n}\n\n/**\n * Check if a value looks like a legacy TargetLocator that needs conversion\n *\n * Detection criteria:\n * 1. Must be an object with candidates array\n * 2. Candidates must use legacy format (has 'value' field, not 'selector'/'xpath'/'text')\n *\n * This prevents double-conversion of already-converted Action format targets.\n */\nfunction isLegacyTargetLocator(value: unknown): value is LegacyTargetLocator {\n if (!value || typeof value !== 'object') return false;\n const obj = value as Record;\n\n // Must have candidates array\n if (!Array.isArray(obj.candidates)) {\n // If only has ref without candidates, check if it's legacy format\n return typeof obj.ref === 'string' && !obj.hint;\n }\n\n // Check first candidate to determine format\n const firstCandidate = obj.candidates[0];\n if (!firstCandidate || typeof firstCandidate !== 'object') {\n return false;\n }\n\n const candidate = firstCandidate as Record;\n // Legacy format uses 'value' field\n // Action format uses 'selector', 'xpath', 'text', etc. (NOT 'value')\n const hasValueField = typeof candidate.value === 'string';\n const hasActionFields =\n typeof candidate.selector === 'string' ||\n typeof candidate.xpath === 'string' ||\n typeof candidate.text === 'string' ||\n typeof candidate.name === 'string';\n\n // It's legacy if it has 'value' field and doesn't have action-specific fields\n return hasValueField && !hasActionFields;\n}\n\n/**\n * Extract action params from step\n * Each step type has its own param structure\n *\n * This function also converts legacy data structures to Action-compatible formats:\n * - TargetLocator.candidates: { type, value } -> { type, selector/xpath/text }\n */\nfunction extractParams(step: Step): Record {\n // The step already contains params inline, so we extract them\n // excluding common fields that go into the action base\n // Use unknown first to satisfy TypeScript's type narrowing\n const stepObj = step as unknown as Record;\n const { id, type, timeoutMs, retry, screenshotOnFail, ...params } = stepObj;\n\n // Convert TargetLocator fields if present\n const converted: Record = {};\n for (const [key, value] of Object.entries(params)) {\n if (key === 'target' && isLegacyTargetLocator(value)) {\n converted[key] = convertTargetLocator(value);\n } else if (key === 'start' && isLegacyTargetLocator(value)) {\n // For drag step\n converted[key] = convertTargetLocator(value);\n } else if (key === 'end' && isLegacyTargetLocator(value)) {\n // For drag step\n converted[key] = convertTargetLocator(value);\n } else {\n converted[key] = value;\n }\n }\n\n return converted;\n}\n\n// ================================\n// Result Conversion\n// ================================\n\n/**\n * Convert ActionExecutionResult to legacy ExecResult\n */\nexport function actionResultToExecResult(result: ActionExecutionResult): ExecResult {\n const execResult: ExecResult = {};\n\n // Map nextLabel for control flow\n if (result.nextLabel) {\n execResult.nextLabel = result.nextLabel;\n }\n\n // Map control directives\n if (result.control) {\n execResult.control = result.control;\n }\n\n // If action already handled logging, mark it\n if (result.status === 'success') {\n execResult.alreadyLogged = false; // Let StepRunner handle logging\n }\n\n return execResult;\n}\n\n// ================================\n// Executor Factory\n// ================================\n\n/**\n * Result from attempting to execute a step via actions\n */\nexport type StepExecutionAttempt =\n | { supported: true; result: ExecResult }\n | { supported: false; reason: string };\n\n/**\n * Options for step executor\n */\nexport interface StepExecutorOptions {\n runId?: string;\n pushLog?: (entry: unknown) => void;\n /**\n * If true, throws on unsupported step types instead of returning { supported: false }\n * Use this in strict mode where all steps must go through ActionRegistry\n */\n strict?: boolean;\n /**\n * Skip ActionRegistry retry policy.\n * When true, the action's retry policy is removed before execution.\n * Use this when StepRunner already handles retry via withRetry().\n */\n skipRetry?: boolean;\n /**\n * Skip navigation waiting inside action handlers.\n * When true, handlers like click/navigate skip their internal nav-wait logic.\n * Use this when StepRunner already handles navigation waiting.\n */\n skipNavWait?: boolean;\n}\n\n/**\n * Create a step executor that uses ActionRegistry\n *\n * This is the main integration point - it creates a function that can\n * replace the legacy `executeStep` call in StepRunner.\n *\n * The executor returns a discriminated union indicating whether the step\n * was supported by ActionRegistry. This allows hybrid mode to fall back\n * to legacy execution gracefully.\n */\nexport function createStepExecutor(registry: ActionRegistry) {\n return async function executeStepViaActions(\n ctx: ExecCtx,\n step: Step,\n tabId: number,\n options?: StepExecutorOptions,\n ): Promise {\n // Convert step to action\n let action = stepToAction(step);\n\n if (!action) {\n const reason = `Unsupported step type for ActionRegistry: ${step.type}`;\n if (options?.strict) {\n throw new Error(reason);\n }\n return { supported: false, reason };\n }\n\n // Skip retry policy if StepRunner handles it\n // This avoids double retry: StepRunner.withRetry() + ActionRegistry.retry\n if (options?.skipRetry === true && action.policy?.retry) {\n action = { ...action, policy: { ...action.policy, retry: undefined } };\n }\n\n // Check if handler exists\n const handler = registry.get(action.type);\n if (!handler) {\n const reason = `No handler registered for action type: ${action.type}`;\n if (options?.strict) {\n throw new Error(reason);\n }\n return { supported: false, reason };\n }\n\n // Build execution flags for handlers\n const execution: ExecutionFlags | undefined =\n options?.skipNavWait === true ? { skipNavWait: true } : undefined;\n\n // Convert context with proper stepId for log attribution\n const actionCtx = execCtxToActionCtx(ctx, tabId, {\n stepId: step.id,\n runId: options?.runId,\n pushLog: options?.pushLog,\n execution,\n });\n\n // Execute via registry (includes retry, timeout, hooks)\n const result = await registry.execute(actionCtx, action);\n\n // Handle failure - still return as supported, but throw the error\n if (result.status === 'failed') {\n const error = result.error;\n throw new Error(\n error?.message || `Action ${action.type} failed: ${error?.code || 'UNKNOWN'}`,\n );\n }\n\n // Sync vars back (in case action modified them)\n Object.assign(ctx.vars, actionCtx.vars);\n\n // Sync frameId back (in case switchFrame modified it)\n if (actionCtx.frameId !== undefined) {\n ctx.frameId = actionCtx.frameId;\n }\n\n // Sync tabId back (in case openTab/switchTab changed it)\n // Chrome tabId is always a positive safe integer\n if (result.status === 'success') {\n const nextTabId = result.newTabId;\n if (typeof nextTabId === 'number' && Number.isSafeInteger(nextTabId) && nextTabId > 0) {\n ctx.tabId = nextTabId;\n }\n }\n\n // Convert result\n return { supported: true, result: actionResultToExecResult(result) };\n };\n}\n\n// ================================\n// Type Guards\n// ================================\n\n/**\n * Check if a step type is supported by ActionRegistry\n */\nexport function isActionSupported(stepType: string): boolean {\n return stepType in STEP_TYPE_TO_ACTION_TYPE;\n}\n\n/**\n * Get the action type for a step type\n */\nexport function getActionType(stepType: string): ExecutableActionType | undefined {\n return STEP_TYPE_TO_ACTION_TYPE[stepType];\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/assert.ts", "content": "/**\n * Assert Action Handler\n *\n * Validates page state against specified conditions:\n * - exists: Selector can be resolved to an element\n * - visible: Element exists and has non-zero dimensions\n * - textPresent: Text appears in the page content\n * - attribute: Element attribute equals/matches/exists\n */\n\nimport { failed, invalid, ok, tryResolveString } from '../registry';\nimport type { ActionHandler, Assertion, VariableStore } from '../types';\n\n/** Default timeout for polling assertions (ms) */\nconst DEFAULT_ASSERT_TIMEOUT_MS = 5000;\n\n/** Polling interval for retry assertions (ms) */\nconst POLL_INTERVAL_MS = 200;\n\n/** Maximum attribute name length */\nconst MAX_ATTR_NAME_LENGTH = 256;\n\n/**\n * Validates assertion configuration at build time\n */\nfunction validateAssertion(assert: Assertion): { ok: true } | { ok: false; error: string } {\n switch (assert.kind) {\n case 'exists':\n case 'visible':\n if (assert.selector === undefined) {\n return { ok: false, error: `Assertion \"${assert.kind}\" requires a selector` };\n }\n break;\n\n case 'textPresent':\n if (assert.text === undefined) {\n return { ok: false, error: 'Assertion \"textPresent\" requires a text value' };\n }\n break;\n\n case 'attribute':\n if (assert.selector === undefined) {\n return { ok: false, error: 'Assertion \"attribute\" requires a selector' };\n }\n if (assert.name === undefined) {\n return { ok: false, error: 'Assertion \"attribute\" requires an attribute name' };\n }\n // Must have at least equals or matches (or neither for existence check)\n break;\n\n default: {\n const exhaustive: never = assert;\n return { ok: false, error: `Unknown assertion kind: ${(exhaustive as Assertion).kind}` };\n }\n }\n\n return { ok: true };\n}\n\n/**\n * Resolve assertion parameters at runtime\n */\nfunction resolveAssertionParams(\n assert: Assertion,\n vars: VariableStore,\n): { ok: true; resolved: ResolvedAssertion } | { ok: false; error: string } {\n switch (assert.kind) {\n case 'exists':\n case 'visible': {\n const selectorResult = tryResolveString(assert.selector, vars);\n if (!selectorResult.ok) return selectorResult;\n const selector = selectorResult.value.trim();\n if (!selector) return { ok: false, error: `Empty selector for \"${assert.kind}\" assertion` };\n return {\n ok: true,\n resolved: { kind: assert.kind, selector },\n };\n }\n\n case 'textPresent': {\n const textResult = tryResolveString(assert.text, vars);\n if (!textResult.ok) return textResult;\n const text = textResult.value;\n if (!text) return { ok: false, error: 'Empty text for \"textPresent\" assertion' };\n return {\n ok: true,\n resolved: { kind: 'textPresent', text },\n };\n }\n\n case 'attribute': {\n const selectorResult = tryResolveString(assert.selector, vars);\n if (!selectorResult.ok) return selectorResult;\n const selector = selectorResult.value.trim();\n if (!selector) return { ok: false, error: 'Empty selector for \"attribute\" assertion' };\n\n const nameResult = tryResolveString(assert.name, vars);\n if (!nameResult.ok) return nameResult;\n const attrName = nameResult.value.trim();\n if (!attrName) return { ok: false, error: 'Empty attribute name' };\n if (attrName.length > MAX_ATTR_NAME_LENGTH) {\n return { ok: false, error: `Attribute name exceeds ${MAX_ATTR_NAME_LENGTH} characters` };\n }\n\n let equals: string | undefined;\n let matches: string | undefined;\n\n if (assert.equals !== undefined) {\n const equalsResult = tryResolveString(assert.equals, vars);\n if (!equalsResult.ok) return equalsResult;\n equals = equalsResult.value;\n }\n\n if (assert.matches !== undefined) {\n const matchesResult = tryResolveString(assert.matches, vars);\n if (!matchesResult.ok) return matchesResult;\n matches = matchesResult.value;\n // Validate regex\n try {\n new RegExp(matches);\n } catch {\n return { ok: false, error: `Invalid regex pattern: ${matches}` };\n }\n }\n\n return {\n ok: true,\n resolved: { kind: 'attribute', selector, attrName, equals, matches },\n };\n }\n }\n}\n\n/**\n * Resolved assertion with all variables interpolated\n */\ntype ResolvedAssertion =\n | { kind: 'exists'; selector: string }\n | { kind: 'visible'; selector: string }\n | { kind: 'textPresent'; text: string }\n | { kind: 'attribute'; selector: string; attrName: string; equals?: string; matches?: string };\n\n/**\n * Execute assertion check in page context\n */\nasync function checkAssertionInPage(\n tabId: number,\n frameId: number | undefined,\n resolved: ResolvedAssertion,\n): Promise<{ passed: boolean; message?: string }> {\n const frameIds = typeof frameId === 'number' ? [frameId] : undefined;\n\n try {\n const injected = await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n world: 'MAIN',\n func: (assertion: ResolvedAssertion) => {\n try {\n switch (assertion.kind) {\n case 'exists': {\n const el = document.querySelector(assertion.selector);\n return el ? { passed: true } : { passed: false, message: 'Element not found' };\n }\n\n case 'visible': {\n const el = document.querySelector(assertion.selector);\n if (!el) return { passed: false, message: 'Element not found' };\n const rect = el.getBoundingClientRect();\n const hasSize = rect.width > 0 && rect.height > 0;\n if (!hasSize) return { passed: false, message: 'Element has zero dimensions' };\n\n // Check if element is visible in viewport\n const style = window.getComputedStyle(el);\n if (\n style.display === 'none' ||\n style.visibility === 'hidden' ||\n style.opacity === '0'\n ) {\n return { passed: false, message: 'Element is hidden via CSS' };\n }\n return { passed: true };\n }\n\n case 'textPresent': {\n const text = assertion.text;\n const bodyText = document.body?.textContent || '';\n if (bodyText.includes(text)) return { passed: true };\n return { passed: false, message: `Text \"${text}\" not found in page` };\n }\n\n case 'attribute': {\n const el = document.querySelector(assertion.selector);\n if (!el) return { passed: false, message: 'Element not found' };\n\n const attrValue = el.getAttribute(assertion.attrName);\n\n // Check existence only\n if (assertion.equals === undefined && assertion.matches === undefined) {\n return attrValue !== null\n ? { passed: true }\n : { passed: false, message: `Attribute \"${assertion.attrName}\" not found` };\n }\n\n // Check equals\n if (assertion.equals !== undefined) {\n if (attrValue === assertion.equals) return { passed: true };\n return {\n passed: false,\n message: `Attribute \"${assertion.attrName}\" is \"${attrValue}\", expected \"${assertion.equals}\"`,\n };\n }\n\n // Check matches (regex)\n if (assertion.matches !== undefined) {\n if (attrValue === null) {\n return { passed: false, message: `Attribute \"${assertion.attrName}\" not found` };\n }\n const regex = new RegExp(assertion.matches);\n if (regex.test(attrValue)) return { passed: true };\n return {\n passed: false,\n message: `Attribute \"${assertion.attrName}\" value \"${attrValue}\" does not match pattern \"${assertion.matches}\"`,\n };\n }\n\n return { passed: true };\n }\n }\n } catch (e) {\n return { passed: false, message: e instanceof Error ? e.message : String(e) };\n }\n },\n args: [resolved],\n });\n\n const result = Array.isArray(injected) ? injected[0]?.result : undefined;\n if (!result || typeof result !== 'object') {\n return { passed: false, message: 'Assertion script returned invalid result' };\n }\n\n return result as { passed: boolean; message?: string };\n } catch (e) {\n return {\n passed: false,\n message: `Script execution failed: ${e instanceof Error ? e.message : String(e)}`,\n };\n }\n}\n\n/**\n * Poll assertion until it passes or timeout\n */\nasync function pollAssertion(\n tabId: number,\n frameId: number | undefined,\n resolved: ResolvedAssertion,\n timeoutMs: number,\n): Promise<{ passed: boolean; message?: string }> {\n const startTime = Date.now();\n let lastResult: { passed: boolean; message?: string } = {\n passed: false,\n message: 'Timeout before first check',\n };\n\n while (Date.now() - startTime < timeoutMs) {\n lastResult = await checkAssertionInPage(tabId, frameId, resolved);\n if (lastResult.passed) return lastResult;\n\n // Wait before next poll\n const remaining = timeoutMs - (Date.now() - startTime);\n if (remaining > 0) {\n await new Promise((resolve) => setTimeout(resolve, Math.min(POLL_INTERVAL_MS, remaining)));\n }\n }\n\n return {\n passed: false,\n message: `${lastResult.message || 'Assertion failed'} (timeout: ${timeoutMs}ms)`,\n };\n}\n\nexport const assertHandler: ActionHandler<'assert'> = {\n type: 'assert',\n\n validate: (action) => {\n const validation = validateAssertion(action.params.assert);\n if (!validation.ok) {\n return invalid(validation.error);\n }\n return ok();\n },\n\n describe: (action) => {\n const assert = action.params.assert;\n switch (assert.kind) {\n case 'exists':\n return `Assert exists: ${truncate(String(assert.selector), 30)}`;\n case 'visible':\n return `Assert visible: ${truncate(String(assert.selector), 30)}`;\n case 'textPresent':\n return `Assert text: \"${truncate(String(assert.text), 25)}\"`;\n case 'attribute':\n return `Assert attr: ${truncate(String(assert.name), 15)}`;\n default:\n return 'Assert';\n }\n },\n\n run: async (ctx, action) => {\n const tabId = ctx.tabId;\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found for assert action');\n }\n\n // Resolve assertion parameters\n const resolved = resolveAssertionParams(action.params.assert, ctx.vars);\n if (!resolved.ok) {\n return failed('VALIDATION_ERROR', resolved.error);\n }\n\n // Determine timeout from policy or default\n const timeoutMs = action.policy?.timeout?.ms ?? DEFAULT_ASSERT_TIMEOUT_MS;\n const failStrategy = action.params.failStrategy ?? 'stop';\n\n // Execute assertion with polling\n const result = await pollAssertion(tabId, ctx.frameId, resolved.resolved, timeoutMs);\n\n if (result.passed) {\n return { status: 'success' };\n }\n\n // Handle failure based on strategy\n const errorMessage = result.message || 'Assertion failed';\n\n switch (failStrategy) {\n case 'warn':\n ctx.log(`Assertion warning: ${errorMessage}`, 'warn');\n return { status: 'success' };\n\n case 'retry':\n // Return failed with retryable error code\n // The scheduler should handle retry based on policy\n return failed('ASSERTION_FAILED', errorMessage);\n\n case 'stop':\n default:\n return failed('ASSERTION_FAILED', errorMessage);\n }\n },\n};\n\n/** Truncate string for display */\nfunction truncate(str: string, maxLen: number): string {\n if (typeof str !== 'string') return '(dynamic)';\n return str.length > maxLen ? str.slice(0, maxLen) + '...' : str;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/click.ts", "content": "/**\n * Click and Double-Click Action Handlers\n *\n * Handles click interactions:\n * - Single click\n * - Double click\n * - Post-click navigation/network wait\n * - Selector fallback with logging\n */\n\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { ENGINE_CONSTANTS } from '../../engine/constants';\nimport {\n maybeQuickWaitForNav,\n waitForNavigationDone,\n waitForNetworkIdle,\n} from '../../engine/policies/wait';\nimport { failed, invalid, ok } from '../registry';\nimport type {\n Action,\n ActionExecutionContext,\n ActionExecutionResult,\n ActionHandler,\n} from '../types';\nimport {\n clampInt,\n ensureElementVisible,\n logSelectorFallback,\n readTabUrl,\n selectorLocator,\n toSelectorTarget,\n} from './common';\n\n/**\n * Shared click execution logic for both click and dblclick\n */\nasync function executeClick(\n ctx: ActionExecutionContext,\n action: Action,\n): Promise> {\n const vars = ctx.vars;\n const tabId = ctx.tabId;\n // Check if StepRunner owns nav-wait (skip internal nav-wait logic)\n const skipNavWait = ctx.execution?.skipNavWait === true;\n\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found');\n }\n\n // Ensure page is read before locating element\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n\n // Only read beforeUrl if we need to do nav-wait\n const beforeUrl = skipNavWait ? '' : await readTabUrl(tabId);\n const { selectorTarget, firstCandidateType, firstCssOrAttr } = toSelectorTarget(\n action.params.target,\n vars,\n );\n\n // Locate element using shared selector locator\n const located = await selectorLocator.locate(tabId, selectorTarget, {\n frameId: ctx.frameId,\n preferRef: false,\n });\n\n const frameId = located?.frameId ?? ctx.frameId;\n const refToUse = located?.ref ?? selectorTarget.ref;\n const selectorToUse = !located?.ref ? firstCssOrAttr : undefined;\n\n if (!refToUse && !selectorToUse) {\n return failed('TARGET_NOT_FOUND', 'Could not locate target element');\n }\n\n // Verify element visibility if we have a ref\n if (located?.ref) {\n const isVisible = await ensureElementVisible(tabId, located.ref, frameId);\n if (!isVisible) {\n return failed('ELEMENT_NOT_VISIBLE', 'Target element is not visible');\n }\n }\n\n // Execute click with tool timeout\n const toolTimeout = clampInt(action.policy?.timeout?.ms ?? 10000, 1000, 30000);\n\n const clickResult = await handleCallTool({\n name: TOOL_NAMES.BROWSER.CLICK,\n args: {\n ref: refToUse,\n selector: selectorToUse,\n waitForNavigation: false,\n timeout: toolTimeout,\n frameId,\n tabId,\n double: action.type === 'dblclick',\n },\n });\n\n if ((clickResult as { isError?: boolean })?.isError) {\n const errorContent = (clickResult as { content?: Array<{ text?: string }> })?.content;\n const errorMsg = errorContent?.[0]?.text || `${action.type} action failed`;\n return failed('UNKNOWN', errorMsg);\n }\n\n // Log selector fallback if used\n const resolvedBy = located?.resolvedBy || (located?.ref ? 'ref' : '');\n const fallbackUsed =\n resolvedBy && firstCandidateType && resolvedBy !== 'ref' && resolvedBy !== firstCandidateType;\n\n if (fallbackUsed) {\n logSelectorFallback(ctx, action.id, String(firstCandidateType), String(resolvedBy));\n }\n\n // Skip post-click wait if StepRunner handles it\n if (skipNavWait) {\n return { status: 'success' };\n }\n\n // Post-click wait handling (only when handler owns nav-wait)\n const waitMs = clampInt(\n action.policy?.timeout?.ms ?? ENGINE_CONSTANTS.DEFAULT_WAIT_MS,\n 0,\n ENGINE_CONSTANTS.MAX_WAIT_MS,\n );\n const after = action.params.after ?? {};\n\n if (after.waitForNavigation) {\n await waitForNavigationDone(beforeUrl, waitMs);\n } else if (after.waitForNetworkIdle) {\n const totalMs = clampInt(waitMs, 1000, ENGINE_CONSTANTS.MAX_WAIT_MS);\n const idleMs = Math.min(1500, Math.max(500, Math.floor(totalMs / 3)));\n await waitForNetworkIdle(totalMs, idleMs);\n } else {\n // Quick sniff for navigation that might have been triggered\n await maybeQuickWaitForNav(beforeUrl, waitMs);\n }\n\n return { status: 'success' };\n}\n\n/**\n * Validate click target configuration\n */\nfunction validateClickTarget(target: {\n ref?: string;\n candidates?: unknown[];\n}): { ok: true } | { ok: false; errors: [string, ...string[]] } {\n const hasRef = typeof target?.ref === 'string' && target.ref.trim().length > 0;\n const hasCandidates = Array.isArray(target?.candidates) && target.candidates.length > 0;\n\n if (hasRef || hasCandidates) {\n return ok();\n }\n return invalid('Missing target selector or ref');\n}\n\nexport const clickHandler: ActionHandler<'click'> = {\n type: 'click',\n\n validate: (action) =>\n validateClickTarget(action.params.target as { ref?: string; candidates?: unknown[] }),\n\n describe: (action) => {\n const target = action.params.target;\n if (typeof (target as { ref?: string }).ref === 'string') {\n return `Click element ${(target as { ref: string }).ref}`;\n }\n return 'Click element';\n },\n\n run: async (ctx, action) => {\n return await executeClick(ctx, action);\n },\n};\n\nexport const dblclickHandler: ActionHandler<'dblclick'> = {\n type: 'dblclick',\n\n validate: (action) =>\n validateClickTarget(action.params.target as { ref?: string; candidates?: unknown[] }),\n\n describe: (action) => {\n const target = action.params.target;\n if (typeof (target as { ref?: string }).ref === 'string') {\n return `Double-click element ${(target as { ref: string }).ref}`;\n }\n return 'Double-click element';\n },\n\n run: async (ctx, action) => {\n return await executeClick(ctx, action);\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/common.ts", "content": "/**\n * Common utilities for Action handlers\n *\n * Shared helpers for:\n * - Variable resolution and template interpolation\n * - Selector target conversion\n * - Element visibility verification\n * - Logging utilities\n */\n\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport {\n createChromeSelectorLocator,\n type SelectorCandidate as SharedSelectorCandidate,\n type SelectorCandidateSource,\n type SelectorStability,\n type SelectorTarget,\n} from '@/shared/selector';\nimport { tryResolveString } from '../registry';\nimport type { ActionExecutionContext, ElementTarget, Resolvable, VariableStore } from '../types';\n\n// ================================\n// Selector Locator Instance\n// ================================\n\nexport const selectorLocator = createChromeSelectorLocator();\n\n// ================================\n// String Resolution Utilities\n// ================================\n\n/**\n * Interpolate {varName} placeholders in a string using variable store\n */\nexport function interpolateBraces(template: string, vars: VariableStore): string {\n return String(template || '').replace(/\\{([^}]+)\\}/g, (_match, key) => {\n const value = (vars as Record)[key];\n return value == null ? '' : String(value);\n });\n}\n\n/**\n * Resolve a Resolvable value with template interpolation\n */\nexport function resolveString(\n value: Resolvable,\n vars: VariableStore,\n): { ok: true; value: string } | { ok: false; error: string } {\n const resolved = tryResolveString(value, vars);\n if (!resolved.ok) return resolved;\n return { ok: true, value: interpolateBraces(resolved.value, vars) };\n}\n\n/**\n * Resolve an optional Resolvable value\n */\nexport function resolveOptionalString(\n value: Resolvable | undefined,\n vars: VariableStore,\n): string | undefined {\n if (value === undefined) return undefined;\n const resolved = resolveString(value, vars);\n if (!resolved.ok) return undefined;\n const out = resolved.value.trim();\n return out.length > 0 ? out : undefined;\n}\n\n// ================================\n// Number Utilities\n// ================================\n\n/**\n * Clamp a number to a range with integer conversion\n */\nexport function clampInt(value: number, min: number, max: number): number {\n const n = Number(value);\n if (!Number.isFinite(n)) return min;\n return Math.min(max, Math.max(min, Math.floor(n)));\n}\n\n// ================================\n// Selector Target Conversion\n// ================================\n\nexport interface ConvertedSelectorTarget {\n selectorTarget: SelectorTarget;\n /** Type of the first candidate (for fallback logging) */\n firstCandidateType?: string;\n /** First CSS or attr selector value (for tool fallback) */\n firstCssOrAttr?: string;\n}\n\n/**\n * Convert Action ElementTarget to shared SelectorTarget\n *\n * Handles:\n * - Resolvable candidate values\n * - Template interpolation\n * - Weight assignment for locator priority\n */\nexport function toSelectorTarget(\n target: ElementTarget,\n vars: VariableStore,\n): ConvertedSelectorTarget {\n const srcCandidates = Array.isArray(target.candidates) ? target.candidates : [];\n const firstCandidateType =\n srcCandidates.length > 0\n ? String((srcCandidates[0] as { type?: string })?.type || '') || undefined\n : undefined;\n\n // Find first CSS/attr selector for tool fallback\n let firstCssOrAttr: string | undefined;\n for (const c of srcCandidates) {\n if (c.type !== 'css' && c.type !== 'attr') continue;\n const resolved = resolveString(c.selector, vars);\n if (resolved.ok && resolved.value.trim()) {\n firstCssOrAttr = resolved.value;\n break;\n }\n }\n\n // Extract selector from target if present\n const primaryRaw =\n typeof (target as { selector?: string }).selector === 'string'\n ? String((target as { selector?: string }).selector).trim()\n : '';\n const selectorInterpolated = primaryRaw ? interpolateBraces(primaryRaw, vars).trim() : '';\n const selector = selectorInterpolated || undefined;\n\n // Extract tagName hint\n const tagName =\n typeof (target as { tag?: string }).tag === 'string'\n ? String((target as { tag?: string }).tag)\n : typeof (target as { hint?: { tagName?: string } }).hint?.tagName === 'string'\n ? String((target as { hint?: { tagName?: string } }).hint!.tagName)\n : undefined;\n\n // Convert candidates with weight assignment\n // Preserve user-defined weights while keeping text candidates as last resort\n let nonTextIndex = 0;\n let textIndex = 0;\n const candidates: SharedSelectorCandidate[] = [];\n\n for (const c of srcCandidates) {\n const idx = c.type === 'text' ? textIndex++ : nonTextIndex++;\n // Respect user-defined weight if present, otherwise use position-based weight\n const userWeight =\n typeof (c as { weight?: number }).weight === 'number' &&\n Number.isFinite((c as { weight?: number }).weight)\n ? (c as { weight: number }).weight\n : 0;\n // Non-text candidates get higher base weight\n const weightBase = c.type === 'text' ? 0 : 1000;\n const weight = weightBase + userWeight - idx;\n\n // Preserve source and stability metadata from original candidate\n // Type-safely extract optional source and stability fields\n const rawSource = (c as { source?: SelectorCandidateSource }).source;\n const rawStability = (c as { stability?: SelectorStability }).stability;\n const meta: Pick = {\n weight,\n ...(rawSource && { source: rawSource }),\n ...(rawStability && { stability: rawStability }),\n };\n\n switch (c.type) {\n case 'css': {\n const resolved = resolveString(c.selector, vars);\n if (!resolved.ok) continue;\n candidates.push({ type: 'css', value: resolved.value, ...meta });\n break;\n }\n case 'attr': {\n const resolved = resolveString(c.selector, vars);\n if (!resolved.ok) continue;\n candidates.push({ type: 'attr', value: resolved.value, ...meta });\n break;\n }\n case 'xpath': {\n const resolved = resolveString(c.xpath, vars);\n if (!resolved.ok) continue;\n candidates.push({ type: 'xpath', value: resolved.value, ...meta });\n break;\n }\n case 'text': {\n const resolved = resolveString(c.text, vars);\n if (!resolved.ok) continue;\n candidates.push({\n type: 'text',\n value: resolved.value,\n ...meta,\n match: c.match,\n tagNameHint: c.tagNameHint ?? tagName,\n });\n break;\n }\n case 'aria': {\n const role = resolveOptionalString(c.role, vars);\n const name = resolveOptionalString(c.name, vars);\n // Skip aria candidate if no name provided (would produce useless selector)\n if (!name) break;\n // Avoid injecting fake role; use aria-label format when role is not specified\n const value = role\n ? `${role}[name=${JSON.stringify(name)}]`\n : `aria-label=${JSON.stringify(name)}`;\n candidates.push({ type: 'aria', value, ...meta, role, name });\n break;\n }\n }\n }\n\n // Ensure at least one candidate\n const ensuredCandidates: [SharedSelectorCandidate, ...SharedSelectorCandidate[]] =\n candidates.length > 0\n ? (candidates as [SharedSelectorCandidate, ...SharedSelectorCandidate[]])\n : [{ type: 'css', value: '' }];\n\n return {\n selectorTarget: {\n selector,\n candidates: ensuredCandidates,\n tagName,\n ref:\n typeof (target as { ref?: string }).ref === 'string'\n ? String((target as { ref?: string }).ref)\n : undefined,\n },\n firstCandidateType,\n firstCssOrAttr,\n };\n}\n\n// ================================\n// Chrome Message Utilities\n// ================================\n\n/**\n * Result type for sendMessageToTab\n */\nexport type SendMessageResult = { ok: true; value: T } | { ok: false; error: string };\n\n/**\n * Send message to tab with optional frameId\n * Returns structured result to avoid silent failures\n */\nexport async function sendMessageToTab(\n tabId: number,\n message: unknown,\n frameId?: number,\n): Promise> {\n try {\n let response: T;\n if (typeof frameId === 'number') {\n response = await chrome.tabs.sendMessage(tabId, message, { frameId });\n } else {\n response = await chrome.tabs.sendMessage(tabId, message);\n }\n return { ok: true, value: response };\n } catch (e) {\n return { ok: false, error: e instanceof Error ? e.message : String(e) };\n }\n}\n\n// ================================\n// Element Verification\n// ================================\n\n/**\n * Verify element is visible by checking its bounding rect\n */\nexport async function ensureElementVisible(\n tabId: number,\n ref: string,\n frameId: number | undefined,\n): Promise {\n const result = await sendMessageToTab<{ rect?: { width: number; height: number } }>(\n tabId,\n { action: TOOL_MESSAGE_TYPES.RESOLVE_REF, ref },\n frameId,\n );\n if (!result.ok) return false;\n const rect = result.value?.rect;\n return !!rect && rect.width > 0 && rect.height > 0;\n}\n\n/**\n * Get current tab URL\n */\nexport async function readTabUrl(tabId: number): Promise {\n try {\n const tab = await chrome.tabs.get(tabId);\n return tab?.url || '';\n } catch {\n return '';\n }\n}\n\n// ================================\n// Logging Utilities\n// ================================\n\nexport interface FallbackLogEntry {\n stepId: string;\n status: 'success';\n message: string;\n fallbackUsed: boolean;\n fallbackFrom: string;\n fallbackTo: string;\n}\n\n/**\n * Log selector fallback usage for debugging\n */\nexport function logSelectorFallback(\n ctx: Pick,\n actionId: string,\n from: string,\n to: string,\n): void {\n try {\n ctx.pushLog?.({\n stepId: actionId,\n status: 'success',\n message: `Selector fallback used (${from} -> ${to})`,\n fallbackUsed: true,\n fallbackFrom: from,\n fallbackTo: to,\n });\n } catch {\n // Ignore logging errors\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/control-flow.ts", "content": "/**\n * Control Flow Action Handlers\n *\n * Handles flow control operations:\n * - if: Conditional branching\n * - foreach: Loop over array\n * - while: Loop with condition\n * - switchFrame: Switch to a different frame\n *\n * Note: The actual loop iteration is handled by the Scheduler.\n * These handlers return control directives that tell the Scheduler how to proceed.\n */\n\nimport {\n failed,\n invalid,\n ok,\n tryResolveNumber,\n tryResolveString,\n tryResolveValue,\n} from '../registry';\nimport type {\n ActionHandler,\n Condition,\n ControlDirective,\n EdgeLabel,\n VariableStore,\n} from '../types';\n\n/** Default max iterations for while loops */\nconst DEFAULT_MAX_ITERATIONS = 1000;\n\n// ================================\n// Condition Evaluation\n// ================================\n\n/**\n * Evaluate a condition against variables\n */\nfunction evaluateCondition(condition: Condition, vars: VariableStore): boolean {\n switch (condition.kind) {\n case 'expr': {\n // Expression evaluation not supported in default resolver\n // Return false for safety\n return false;\n }\n\n case 'compare': {\n const leftResult = tryResolveValue(condition.left, vars);\n const rightResult = tryResolveValue(condition.right, vars);\n\n if (!leftResult.ok || !rightResult.ok) return false;\n\n const left = leftResult.value;\n const right = rightResult.value;\n\n switch (condition.op) {\n case 'eq':\n return left === right;\n case 'eqi':\n return String(left).toLowerCase() === String(right).toLowerCase();\n case 'neq':\n return left !== right;\n case 'gt':\n return Number(left) > Number(right);\n case 'gte':\n return Number(left) >= Number(right);\n case 'lt':\n return Number(left) < Number(right);\n case 'lte':\n return Number(left) <= Number(right);\n case 'contains':\n return String(left).includes(String(right));\n case 'containsI':\n return String(left).toLowerCase().includes(String(right).toLowerCase());\n case 'notContains':\n return !String(left).includes(String(right));\n case 'notContainsI':\n return !String(left).toLowerCase().includes(String(right).toLowerCase());\n case 'startsWith':\n return String(left).startsWith(String(right));\n case 'endsWith':\n return String(left).endsWith(String(right));\n case 'regex': {\n try {\n const regex = new RegExp(String(right));\n return regex.test(String(left));\n } catch {\n return false;\n }\n }\n default:\n return false;\n }\n }\n\n case 'truthy': {\n const result = tryResolveValue(condition.value, vars);\n if (!result.ok) return false;\n return Boolean(result.value);\n }\n\n case 'falsy': {\n const result = tryResolveValue(condition.value, vars);\n if (!result.ok) return true;\n return !result.value;\n }\n\n case 'not':\n return !evaluateCondition(condition.condition, vars);\n\n case 'and':\n return condition.conditions.every((c) => evaluateCondition(c, vars));\n\n case 'or':\n return condition.conditions.some((c) => evaluateCondition(c, vars));\n\n default:\n return false;\n }\n}\n\n// ================================\n// if Handler\n// ================================\n\nexport const ifHandler: ActionHandler<'if'> = {\n type: 'if',\n\n validate: (action) => {\n const params = action.params;\n\n if (params.mode === 'binary') {\n if (!params.condition) {\n return invalid('Binary if requires a condition');\n }\n } else if (params.mode === 'branches') {\n if (!params.branches || params.branches.length === 0) {\n return invalid('Branches if requires at least one branch');\n }\n } else {\n return invalid(`Unknown if mode: ${String((params as { mode: string }).mode)}`);\n }\n\n return ok();\n },\n\n describe: (action) => {\n if (action.params.mode === 'binary') {\n return 'If condition';\n }\n const branchCount = action.params.mode === 'branches' ? action.params.branches.length : 0;\n return `If (${branchCount} branches)`;\n },\n\n run: async (ctx, action) => {\n const params = action.params;\n\n if (params.mode === 'binary') {\n const result = evaluateCondition(params.condition, ctx.vars);\n const label: EdgeLabel = result\n ? (params.trueLabel ?? 'true')\n : (params.falseLabel ?? 'false');\n return { status: 'success', nextLabel: label };\n }\n\n // Branches mode\n if (params.mode === 'branches') {\n for (const branch of params.branches) {\n if (evaluateCondition(branch.condition, ctx.vars)) {\n return { status: 'success', nextLabel: branch.label };\n }\n }\n // No branch matched, use else label\n const elseLabel = params.elseLabel ?? 'default';\n return { status: 'success', nextLabel: elseLabel };\n }\n\n return failed('VALIDATION_ERROR', 'Invalid if mode');\n },\n};\n\n// ================================\n// foreach Handler\n// ================================\n\nexport const foreachHandler: ActionHandler<'foreach'> = {\n type: 'foreach',\n\n validate: (action) => {\n const params = action.params;\n\n if (!params.listVar) {\n return invalid('foreach requires a listVar');\n }\n\n if (!params.subflowId) {\n return invalid('foreach requires a subflowId');\n }\n\n return ok();\n },\n\n describe: (action) => {\n return `For each in ${action.params.listVar}`;\n },\n\n run: async (ctx, action) => {\n const params = action.params;\n\n // Check if listVar exists and is an array\n const list = ctx.vars[params.listVar];\n if (!Array.isArray(list)) {\n return failed('VALIDATION_ERROR', `Variable \"${params.listVar}\" is not an array`);\n }\n\n if (list.length === 0) {\n // Empty list, nothing to iterate\n return { status: 'success' };\n }\n\n // Return control directive for scheduler to handle\n const directive: ControlDirective = {\n kind: 'foreach',\n listVar: params.listVar,\n itemVar: params.itemVar || 'item',\n subflowId: params.subflowId,\n concurrency: params.concurrency,\n };\n\n return { status: 'success', control: directive };\n },\n};\n\n// ================================\n// while Handler\n// ================================\n\nexport const whileHandler: ActionHandler<'while'> = {\n type: 'while',\n\n validate: (action) => {\n const params = action.params;\n\n if (!params.condition) {\n return invalid('while requires a condition');\n }\n\n if (!params.subflowId) {\n return invalid('while requires a subflowId');\n }\n\n return ok();\n },\n\n describe: () => {\n return 'While loop';\n },\n\n run: async (ctx, action) => {\n const params = action.params;\n\n // Check if condition is currently true\n const conditionResult = evaluateCondition(params.condition, ctx.vars);\n\n if (!conditionResult) {\n // Condition is false, don't enter loop\n return { status: 'success' };\n }\n\n // Return control directive for scheduler to handle\n const directive: ControlDirective = {\n kind: 'while',\n condition: params.condition,\n subflowId: params.subflowId,\n maxIterations: params.maxIterations ?? DEFAULT_MAX_ITERATIONS,\n };\n\n return { status: 'success', control: directive };\n },\n};\n\n// ================================\n// switchFrame Handler\n// ================================\n\nexport const switchFrameHandler: ActionHandler<'switchFrame'> = {\n type: 'switchFrame',\n\n validate: (action) => {\n const target = action.params.target;\n\n if (!target) {\n return invalid('switchFrame requires a target');\n }\n\n if (target.kind !== 'top' && target.kind !== 'index' && target.kind !== 'urlContains') {\n return invalid(`Unknown frame target kind: ${String((target as { kind: string }).kind)}`);\n }\n\n return ok();\n },\n\n describe: (action) => {\n const target = action.params.target;\n if (target.kind === 'top') return 'Switch to top frame';\n if (target.kind === 'index') return `Switch to frame #${target.index}`;\n if (target.kind === 'urlContains') return 'Switch frame (by URL)';\n return 'Switch frame';\n },\n\n run: async (ctx, action) => {\n const target = action.params.target;\n const tabId = ctx.tabId;\n\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found');\n }\n\n try {\n if (target.kind === 'top') {\n // Reset to main frame (frameId = 0)\n ctx.frameId = 0;\n return { status: 'success' };\n }\n\n // Get all frames in the tab\n const frames = await chrome.webNavigation.getAllFrames({ tabId });\n if (!frames || frames.length === 0) {\n return failed('FRAME_NOT_FOUND', 'No frames found in tab');\n }\n\n let targetFrame: chrome.webNavigation.GetAllFrameResultDetails | undefined;\n\n if (target.kind === 'index') {\n const indexResult = tryResolveNumber(target.index, ctx.vars);\n if (!indexResult.ok) {\n return failed('VALIDATION_ERROR', `Failed to resolve frame index: ${indexResult.error}`);\n }\n const index = Math.floor(indexResult.value);\n\n // Find frame by index (excluding main frame which is 0)\n const childFrames = frames.filter((f) => f.frameId !== 0);\n if (index < 0 || index >= childFrames.length) {\n return failed(\n 'FRAME_NOT_FOUND',\n `Frame index ${index} out of bounds (${childFrames.length} frames)`,\n );\n }\n targetFrame = childFrames[index];\n } else if (target.kind === 'urlContains') {\n const urlResult = tryResolveString(target.value, ctx.vars);\n if (!urlResult.ok) {\n return failed('VALIDATION_ERROR', `Failed to resolve URL pattern: ${urlResult.error}`);\n }\n const urlPattern = urlResult.value.trim().toLowerCase();\n\n // Empty pattern is invalid\n if (!urlPattern) {\n return failed('VALIDATION_ERROR', 'URL pattern cannot be empty');\n }\n\n targetFrame = frames.find((f) => f.url && f.url.toLowerCase().includes(urlPattern));\n }\n\n if (!targetFrame) {\n return failed('FRAME_NOT_FOUND', 'No matching frame found');\n }\n\n // The frameId will be used by subsequent actions\n // Store it in context (this is typically handled by scheduler)\n ctx.frameId = targetFrame.frameId;\n\n return { status: 'success' };\n } catch (e) {\n return failed(\n 'FRAME_NOT_FOUND',\n `Failed to switch frame: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/delay.ts", "content": "/**\n * Delay Action Handler\n *\n * Provides a simple pause in execution flow.\n * Supports variable resolution for dynamic delay times.\n */\n\nimport { failed, invalid, ok, tryResolveNumber } from '../registry';\nimport type { ActionHandler } from '../types';\n\n/** Maximum delay time to prevent integer overflow in setTimeout */\nconst MAX_DELAY_MS = 2_147_483_647;\n\nexport const delayHandler: ActionHandler<'delay'> = {\n type: 'delay',\n\n validate: (action) => {\n if (action.params.sleep === undefined) {\n return invalid('Missing sleep parameter');\n }\n return ok();\n },\n\n describe: (action) => {\n const ms = typeof action.params.sleep === 'number' ? action.params.sleep : '(dynamic)';\n return `Delay ${ms}ms`;\n },\n\n run: async (ctx, action) => {\n const resolved = tryResolveNumber(action.params.sleep, ctx.vars);\n if (!resolved.ok) {\n return failed('VALIDATION_ERROR', resolved.error);\n }\n\n const ms = Math.max(0, Math.min(MAX_DELAY_MS, Math.floor(resolved.value)));\n\n if (ms > 0) {\n await new Promise((resolve) => setTimeout(resolve, ms));\n }\n\n return { status: 'success' };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/dom.ts", "content": "/**\n * DOM Tools Action Handlers\n *\n * Handles DOM manipulation actions:\n * - triggerEvent: Dispatch a custom DOM Event on an element\n * - setAttribute: Set or remove an attribute on an element\n *\n * Design notes:\n * - Both handlers follow the same pattern as click.ts\n * - Element location uses selectorLocator from shared code\n * - CSS selector resolution supports ref fallback\n */\n\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { failed, invalid, ok, tryResolveJson } from '../registry';\nimport type {\n ActionExecutionResult,\n ActionHandler,\n ElementTarget,\n JsonValue,\n VariableStore,\n} from '../types';\nimport {\n interpolateBraces,\n logSelectorFallback,\n resolveString,\n selectorLocator,\n sendMessageToTab,\n toSelectorTarget,\n} from './common';\n\n// ================================\n// Type Definitions\n// ================================\n\ninterface ResolveRefResponse {\n success?: boolean;\n selector?: string;\n error?: string;\n}\n\ninterface DomScriptResult {\n success: boolean;\n error?: string;\n}\n\ninterface ResolvedTarget {\n selector: string;\n frameId: number | undefined;\n firstCandidateType?: string;\n resolvedBy?: string;\n}\n\n// ================================\n// Shared Utilities\n// ================================\n\n/**\n * Check if target has valid ref or candidates\n * Accepts unknown to safely handle malformed input in validate()\n */\nfunction hasValidTarget(target: unknown): boolean {\n if (typeof target !== 'object' || target === null) return false;\n const t = target as { ref?: unknown; candidates?: unknown };\n const hasRef = typeof t.ref === 'string' && t.ref.trim().length > 0;\n const hasCandidates = Array.isArray(t.candidates) && t.candidates.length > 0;\n return hasRef || hasCandidates;\n}\n\n/**\n * Strip frame prefix from composite selector (e.g., \"frame|>selector\" -> \"selector\")\n */\nfunction stripCompositePrefix(selector: string): string {\n const raw = String(selector || '').trim();\n if (!raw.includes('|>')) return raw;\n\n const parts = raw\n .split('|>')\n .map((p) => p.trim())\n .filter(Boolean);\n return parts.length > 0 ? parts[parts.length - 1] : raw;\n}\n\n/**\n * Resolve ElementTarget to a CSS selector string\n *\n * Resolution order:\n * 1. Try to locate element using selectorLocator\n * 2. If ref found, resolve it to CSS selector via content script\n * 3. Fall back to first CSS/attr candidate if no ref\n */\nasync function resolveTargetSelector(\n tabId: number,\n target: ElementTarget,\n vars: VariableStore,\n contextFrameId: number | undefined,\n): Promise<{ ok: true; value: ResolvedTarget } | { ok: false; error: string }> {\n const { selectorTarget, firstCandidateType, firstCssOrAttr } = toSelectorTarget(target, vars);\n\n // Locate element using shared selector locator\n const located = await selectorLocator.locate(tabId, selectorTarget, {\n frameId: contextFrameId,\n preferRef: false,\n });\n\n const frameId = located?.frameId ?? contextFrameId;\n const refToUse = located?.ref ?? selectorTarget.ref;\n\n // Must have either ref or CSS/attr candidate\n if (!refToUse && !firstCssOrAttr) {\n return { ok: false, error: 'Could not locate target element' };\n }\n\n let selector: string | undefined;\n\n // Try to resolve ref to CSS selector\n if (refToUse) {\n const resolved = await sendMessageToTab(\n tabId,\n { action: TOOL_MESSAGE_TYPES.RESOLVE_REF, ref: refToUse },\n frameId,\n );\n\n if (resolved.ok && resolved.value?.success !== false && resolved.value?.selector) {\n const sel = resolved.value.selector.trim();\n if (sel) selector = sel;\n }\n }\n\n // Fall back to CSS/attr candidate\n if (!selector && firstCssOrAttr) {\n const stripped = stripCompositePrefix(firstCssOrAttr);\n if (stripped) selector = stripped;\n }\n\n if (!selector) {\n return { ok: false, error: 'Could not resolve a CSS selector for the target element' };\n }\n\n return {\n ok: true,\n value: {\n selector,\n frameId,\n firstCandidateType,\n // Only mark as 'ref' if locator actually resolved via ref\n resolvedBy: located?.resolvedBy || (located?.ref ? 'ref' : undefined),\n },\n };\n}\n\n/**\n * Log selector fallback if a different selector type was used\n */\nfunction maybeLogFallback(\n ctx: Parameters[0],\n actionId: string,\n resolved: ResolvedTarget,\n): void {\n const { resolvedBy, firstCandidateType } = resolved;\n\n const fallbackUsed =\n resolvedBy && firstCandidateType && resolvedBy !== 'ref' && resolvedBy !== firstCandidateType;\n\n if (fallbackUsed) {\n logSelectorFallback(ctx, actionId, String(firstCandidateType), String(resolvedBy));\n }\n}\n\n// ================================\n// triggerEvent Handler\n// ================================\n\nexport const triggerEventHandler: ActionHandler<'triggerEvent'> = {\n type: 'triggerEvent',\n\n validate: (action) => {\n if (!hasValidTarget(action.params.target)) {\n return invalid('triggerEvent requires a target ref or selector candidates');\n }\n\n const event = action.params.event;\n if (event === undefined || event === null) {\n return invalid('Missing event parameter');\n }\n if (typeof event === 'string' && event.trim().length === 0) {\n return invalid('event must be a non-empty string');\n }\n\n return ok();\n },\n\n describe: (action) => {\n const ev = typeof action.params.event === 'string' ? action.params.event : '(dynamic)';\n const display = ev.length > 30 ? ev.slice(0, 30) + '...' : ev;\n return `Trigger event \"${display}\"`;\n },\n\n run: async (ctx, action): Promise> => {\n const { tabId, vars, frameId } = ctx;\n\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found for triggerEvent action');\n }\n\n // Resolve event type\n const eventResolved = resolveString(action.params.event, vars);\n if (!eventResolved.ok) {\n return failed('VALIDATION_ERROR', eventResolved.error);\n }\n\n const eventType = eventResolved.value.trim();\n if (!eventType) {\n return failed('VALIDATION_ERROR', 'Event type is empty');\n }\n\n // Event options\n const bubbles = action.params.bubbles !== false;\n const cancelable = action.params.cancelable === true;\n\n // Ensure page is read for element location\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: { tabId } });\n\n // Resolve target selector\n const targetResolved = await resolveTargetSelector(tabId, action.params.target, vars, frameId);\n if (!targetResolved.ok) {\n return failed('TARGET_NOT_FOUND', targetResolved.error);\n }\n\n const { selector, frameId: resolvedFrameId } = targetResolved.value;\n const frameIds = typeof resolvedFrameId === 'number' ? [resolvedFrameId] : undefined;\n\n // Execute event dispatch in page context\n try {\n const injected = await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n world: 'MAIN',\n func: (\n sel: string,\n type: string,\n bubbles: boolean,\n cancelable: boolean,\n ): DomScriptResult => {\n try {\n const el = document.querySelector(sel);\n if (!el) {\n // Use special error code to distinguish from script execution errors\n return { success: false, error: `[TARGET_NOT_FOUND] Element not found: ${sel}` };\n }\n\n const event = new Event(type, { bubbles, cancelable });\n el.dispatchEvent(event);\n return { success: true };\n } catch (e) {\n return { success: false, error: e instanceof Error ? e.message : String(e) };\n }\n },\n args: [selector, eventType, bubbles, cancelable],\n });\n\n const result = Array.isArray(injected) ? injected[0]?.result : undefined;\n if (!result || typeof result !== 'object') {\n return failed('SCRIPT_FAILED', 'triggerEvent script returned invalid result');\n }\n\n const typed = result as DomScriptResult;\n if (!typed.success) {\n // Parse error code from message if present (e.g., \"[TARGET_NOT_FOUND] ...\")\n const errorMsg = typed.error || `Failed to dispatch \"${eventType}\"`;\n const code = errorMsg.startsWith('[TARGET_NOT_FOUND]')\n ? 'TARGET_NOT_FOUND'\n : 'SCRIPT_FAILED';\n return failed(code, errorMsg.replace(/^\\[TARGET_NOT_FOUND\\]\\s*/, ''));\n }\n } catch (e) {\n return failed(\n 'SCRIPT_FAILED',\n `Failed to trigger event \"${eventType}\": ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n\n maybeLogFallback(ctx, action.id, targetResolved.value);\n\n return { status: 'success' };\n },\n};\n\n// ================================\n// setAttribute Handler\n// ================================\n\nexport const setAttributeHandler: ActionHandler<'setAttribute'> = {\n type: 'setAttribute',\n\n validate: (action) => {\n if (!hasValidTarget(action.params.target)) {\n return invalid('setAttribute requires a target ref or selector candidates');\n }\n\n const name = action.params.name;\n if (name === undefined || name === null) {\n return invalid('Missing name parameter');\n }\n if (typeof name === 'string' && name.trim().length === 0) {\n return invalid('name must be a non-empty string');\n }\n\n return ok();\n },\n\n describe: (action) => {\n const name = typeof action.params.name === 'string' ? action.params.name : '(dynamic)';\n const display = name.length > 30 ? name.slice(0, 30) + '...' : name;\n return action.params.remove ? `Remove attribute \"${display}\"` : `Set attribute \"${display}\"`;\n },\n\n run: async (ctx, action): Promise> => {\n const { tabId, vars, frameId } = ctx;\n\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found for setAttribute action');\n }\n\n // Resolve attribute name\n const nameResolved = resolveString(action.params.name, vars);\n if (!nameResolved.ok) {\n return failed('VALIDATION_ERROR', nameResolved.error);\n }\n\n const attrName = nameResolved.value.trim();\n if (!attrName) {\n return failed('VALIDATION_ERROR', 'Attribute name is empty');\n }\n\n const remove = action.params.remove === true;\n\n // Resolve attribute value (only if not removing)\n let attrValue: JsonValue = null;\n if (!remove && action.params.value !== undefined) {\n const valueResolved = tryResolveJson(action.params.value, vars);\n if (!valueResolved.ok) {\n return failed('VALIDATION_ERROR', valueResolved.error);\n }\n\n // Apply template interpolation for string values\n attrValue =\n typeof valueResolved.value === 'string'\n ? interpolateBraces(valueResolved.value, vars)\n : valueResolved.value;\n }\n\n // Ensure page is read for element location\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: { tabId } });\n\n // Resolve target selector\n const targetResolved = await resolveTargetSelector(tabId, action.params.target, vars, frameId);\n if (!targetResolved.ok) {\n return failed('TARGET_NOT_FOUND', targetResolved.error);\n }\n\n const { selector, frameId: resolvedFrameId } = targetResolved.value;\n const frameIds = typeof resolvedFrameId === 'number' ? [resolvedFrameId] : undefined;\n\n // Execute attribute modification in page context\n try {\n const injected = await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n world: 'MAIN',\n func: (sel: string, name: string, value: JsonValue, remove: boolean): DomScriptResult => {\n try {\n const el = document.querySelector(sel);\n if (!el) {\n // Use special error code to distinguish from script execution errors\n return { success: false, error: `[TARGET_NOT_FOUND] Element not found: ${sel}` };\n }\n\n if (remove) {\n el.removeAttribute(name);\n } else {\n // Convert value to string for setAttribute\n const strValue =\n value === null || value === undefined\n ? ''\n : typeof value === 'string'\n ? value\n : String(value);\n el.setAttribute(name, strValue);\n }\n\n return { success: true };\n } catch (e) {\n return { success: false, error: e instanceof Error ? e.message : String(e) };\n }\n },\n args: [selector, attrName, attrValue, remove],\n });\n\n const result = Array.isArray(injected) ? injected[0]?.result : undefined;\n if (!result || typeof result !== 'object') {\n return failed('SCRIPT_FAILED', 'setAttribute script returned invalid result');\n }\n\n const typed = result as DomScriptResult;\n if (!typed.success) {\n const actionDesc = remove ? 'remove' : 'set';\n // Parse error code from message if present (e.g., \"[TARGET_NOT_FOUND] ...\")\n const errorMsg = typed.error || `Failed to ${actionDesc} attribute \"${attrName}\"`;\n const code = errorMsg.startsWith('[TARGET_NOT_FOUND]')\n ? 'TARGET_NOT_FOUND'\n : 'SCRIPT_FAILED';\n return failed(code, errorMsg.replace(/^\\[TARGET_NOT_FOUND\\]\\s*/, ''));\n }\n } catch (e) {\n const actionDesc = remove ? 'remove' : 'set';\n return failed(\n 'SCRIPT_FAILED',\n `Failed to ${actionDesc} attribute \"${attrName}\": ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n\n maybeLogFallback(ctx, action.id, targetResolved.value);\n\n return { status: 'success' };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/drag.ts", "content": "/**\n * Drag Action Handler\n *\n * Performs a left-click drag from a start target to an end target.\n *\n * Features:\n * - Locates start/end via shared SelectorLocator (ref + candidates)\n * - Executes via chrome_computer with action=\"left_click_drag\" (CDP-based)\n * - Uses optional `path` endpoints as a fallback for coordinates\n * - Validates element visibility before drag\n */\n\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { failed, invalid, ok } from '../registry';\nimport type { ActionHandler, ElementTarget, Point, VariableStore } from '../types';\nimport {\n ensureElementVisible,\n logSelectorFallback,\n selectorLocator,\n toSelectorTarget,\n} from './common';\n\ninterface Coordinates {\n x: number;\n y: number;\n}\n\n/** Check if target has valid selector specification */\nfunction hasTargetSpec(target: unknown): boolean {\n if (!target || typeof target !== 'object') return false;\n const t = target as { ref?: unknown; candidates?: unknown };\n const hasRef = typeof t.ref === 'string' && t.ref.trim().length > 0;\n const hasCandidates = Array.isArray(t.candidates) && t.candidates.length > 0;\n return hasRef || hasCandidates;\n}\n\n/** Check if value is a finite number */\nfunction isFiniteNumber(v: unknown): v is number {\n return typeof v === 'number' && Number.isFinite(v);\n}\n\n/** Extract start/end coordinates from path array */\nfunction getPathEndpoints(\n path: ReadonlyArray | undefined,\n): { startCoordinates: Coordinates; endCoordinates: Coordinates } | null {\n if (!Array.isArray(path) || path.length < 2) return null;\n\n const first = path[0];\n const last = path[path.length - 1];\n\n if (!first || !last) return null;\n if (!isFiniteNumber(first.x) || !isFiniteNumber(first.y)) return null;\n if (!isFiniteNumber(last.x) || !isFiniteNumber(last.y)) return null;\n\n return {\n startCoordinates: { x: first.x, y: first.y },\n endCoordinates: { x: last.x, y: last.y },\n };\n}\n\n/** Extract error text from tool result */\nfunction extractToolError(result: unknown, fallback: string): string {\n const content = (result as { content?: Array<{ text?: string }> })?.content;\n return content?.find((c) => typeof c?.text === 'string')?.text || fallback;\n}\n\n/** Locate target and verify visibility */\nasync function locateTarget(\n tabId: number,\n frameId: number | undefined,\n target: ElementTarget | undefined,\n vars: VariableStore,\n role: 'start' | 'end',\n): Promise<\n | { ok: true; ref?: string; firstCandidateType?: string; resolvedBy?: string }\n | { ok: false; error: string; code: 'TARGET_NOT_FOUND' | 'ELEMENT_NOT_VISIBLE' }\n> {\n if (!target || !hasTargetSpec(target)) {\n return { ok: true };\n }\n\n const { selectorTarget, firstCandidateType } = toSelectorTarget(target, vars);\n\n const located = await selectorLocator.locate(tabId, selectorTarget, {\n frameId,\n preferRef: false,\n });\n\n const locatedFrameId = located?.frameId ?? frameId;\n const ref = located?.ref ?? selectorTarget.ref;\n const resolvedBy = located?.resolvedBy || (located?.ref ? 'ref' : '');\n\n // Verify visibility for freshly located refs\n if (located?.ref) {\n const visible = await ensureElementVisible(tabId, located.ref, locatedFrameId);\n if (!visible) {\n return {\n ok: false,\n error: `Drag ${role} element is not visible`,\n code: 'ELEMENT_NOT_VISIBLE',\n };\n }\n }\n\n return { ok: true, ref, firstCandidateType, resolvedBy };\n}\n\nexport const dragHandler: ActionHandler<'drag'> = {\n type: 'drag',\n\n validate: (action) => {\n const pathEndpoints = getPathEndpoints(action.params.path);\n\n // If path is present, it must be well-formed\n if (action.params.path !== undefined && action.params.path.length > 0 && !pathEndpoints) {\n return invalid('path must contain at least two points with finite x/y coordinates');\n }\n\n const hasStart = hasTargetSpec(action.params.start);\n const hasEnd = hasTargetSpec(action.params.end);\n const hasPath = !!pathEndpoints;\n\n // Must have either target spec or path coordinates\n if (!hasStart && !hasPath) {\n return invalid('Drag start must include a non-empty ref or selector candidates');\n }\n if (!hasEnd && !hasPath) {\n return invalid('Drag end must include a non-empty ref or selector candidates');\n }\n\n return ok();\n },\n\n describe: (action) => {\n const startRef = (action.params.start as { ref?: unknown })?.ref;\n const endRef = (action.params.end as { ref?: unknown })?.ref;\n\n const s = typeof startRef === 'string' && startRef.trim() ? startRef.trim() : '';\n const e = typeof endRef === 'string' && endRef.trim() ? endRef.trim() : '';\n\n if (s && e) {\n const truncS = s.length > 15 ? s.slice(0, 15) + '...' : s;\n const truncE = e.length > 15 ? e.slice(0, 15) + '...' : e;\n return `Drag ${truncS} → ${truncE}`;\n }\n if (s) return `Drag from ${s.length > 20 ? s.slice(0, 20) + '...' : s}`;\n if (e) return `Drag to ${e.length > 20 ? e.slice(0, 20) + '...' : e}`;\n\n const pathEndpoints = getPathEndpoints(action.params.path);\n if (pathEndpoints) {\n const { startCoordinates, endCoordinates } = pathEndpoints;\n return `Drag (${startCoordinates.x},${startCoordinates.y}) → (${endCoordinates.x},${endCoordinates.y})`;\n }\n\n return 'Drag';\n },\n\n run: async (ctx, action) => {\n const tabId = ctx.tabId;\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found for drag action');\n }\n\n // Ensure element refs are fresh before locating\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: { tabId } });\n\n // Get path coordinates as fallback\n const pathEndpoints = getPathEndpoints(action.params.path);\n const startCoordinates = pathEndpoints?.startCoordinates;\n const endCoordinates = pathEndpoints?.endCoordinates;\n\n // Locate start target\n const startResult = await locateTarget(\n tabId,\n ctx.frameId,\n action.params.start,\n ctx.vars,\n 'start',\n );\n if (!startResult.ok) {\n return failed(startResult.code, startResult.error);\n }\n\n // Locate end target\n const endResult = await locateTarget(tabId, ctx.frameId, action.params.end, ctx.vars, 'end');\n if (!endResult.ok) {\n return failed(endResult.code, endResult.error);\n }\n\n // Validate we have at least one way to identify start and end\n if (!startResult.ref && !startCoordinates) {\n return failed('TARGET_NOT_FOUND', 'Could not resolve drag start (ref or path coordinates)');\n }\n if (!endResult.ref && !endCoordinates) {\n return failed('TARGET_NOT_FOUND', 'Could not resolve drag end (ref or path coordinates)');\n }\n\n // Execute drag via chrome_computer tool\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.COMPUTER,\n args: {\n action: 'left_click_drag',\n tabId,\n startRef: startResult.ref,\n ref: endResult.ref,\n startCoordinates,\n coordinates: endCoordinates,\n },\n });\n\n if ((res as { isError?: boolean })?.isError) {\n return failed('UNKNOWN', extractToolError(res, 'Drag action failed'));\n }\n\n // Log selector fallback after successful execution\n const startFallbackUsed =\n startResult.resolvedBy &&\n startResult.firstCandidateType &&\n startResult.resolvedBy !== 'ref' &&\n startResult.resolvedBy !== startResult.firstCandidateType;\n\n if (startFallbackUsed) {\n logSelectorFallback(\n ctx,\n action.id,\n `start:${String(startResult.firstCandidateType)}`,\n `start:${String(startResult.resolvedBy)}`,\n );\n }\n\n const endFallbackUsed =\n endResult.resolvedBy &&\n endResult.firstCandidateType &&\n endResult.resolvedBy !== 'ref' &&\n endResult.resolvedBy !== endResult.firstCandidateType;\n\n if (endFallbackUsed) {\n logSelectorFallback(\n ctx,\n action.id,\n `end:${String(endResult.firstCandidateType)}`,\n `end:${String(endResult.resolvedBy)}`,\n );\n }\n\n return { status: 'success' };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/extract.ts", "content": "/**\n * Extract Action Handler\n *\n * Extracts data from the page and stores in variables:\n * - selector mode: Extract text/attribute from elements\n * - js mode: Execute JavaScript and capture return value\n */\n\nimport { failed, invalid, ok, tryResolveString } from '../registry';\nimport type { ActionHandler, BrowserWorld, JsonValue, VariableStore } from '../types';\n\n/** Default attribute to extract */\nconst DEFAULT_EXTRACT_ATTR = 'textContent';\n\n/**\n * Execute extraction script in page context\n */\nasync function executeExtraction(\n tabId: number,\n frameId: number | undefined,\n mode: 'selector' | 'js',\n params: {\n selector?: string;\n attr?: string;\n code?: string;\n world?: BrowserWorld;\n },\n): Promise<{ ok: true; value: JsonValue } | { ok: false; error: string }> {\n const frameIds = typeof frameId === 'number' ? [frameId] : undefined;\n const world = params.world === 'ISOLATED' ? 'ISOLATED' : 'MAIN';\n\n try {\n if (mode === 'selector') {\n const injected = await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n world,\n func: (selector: string, attr: string) => {\n const el = document.querySelector(selector);\n if (!el) {\n return { success: false, error: `Element not found: ${selector}` };\n }\n\n let value: JsonValue;\n\n // Handle special attribute names\n if (attr === 'text' || attr === 'textContent') {\n value = el.textContent?.trim() ?? '';\n } else if (attr === 'innerText') {\n value = (el as HTMLElement).innerText?.trim() ?? '';\n } else if (attr === 'innerHTML') {\n value = el.innerHTML;\n } else if (attr === 'outerHTML') {\n value = el.outerHTML;\n } else if (attr === 'value') {\n // For form elements\n value = (el as HTMLInputElement).value ?? '';\n } else if (attr === 'checked') {\n value = (el as HTMLInputElement).checked ?? false;\n } else if (attr === 'href') {\n value = (el as HTMLAnchorElement).href ?? el.getAttribute('href') ?? '';\n } else if (attr === 'src') {\n value = (el as HTMLImageElement).src ?? el.getAttribute('src') ?? '';\n } else {\n // Generic attribute\n const attrValue = el.getAttribute(attr);\n value = attrValue ?? '';\n }\n\n return { success: true, value };\n },\n args: [params.selector!, params.attr!],\n });\n\n const result = Array.isArray(injected) ? injected[0]?.result : undefined;\n if (!result || typeof result !== 'object') {\n return { ok: false, error: 'Extraction script returned invalid result' };\n }\n\n if (!result.success) {\n return { ok: false, error: result.error || 'Extraction failed' };\n }\n\n return { ok: true, value: result.value as JsonValue };\n }\n\n // JS mode\n const injected = await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n world,\n func: (code: string) => {\n try {\n // Create function and execute\n const fn = new Function(code);\n const result = fn();\n\n // Handle promises\n if (result instanceof Promise) {\n return result.then(\n (value: unknown) => ({ success: true, value }),\n (error: Error) => ({ success: false, error: error?.message || String(error) }),\n );\n }\n\n return { success: true, value: result };\n } catch (e) {\n return { success: false, error: e instanceof Error ? e.message : String(e) };\n }\n },\n args: [params.code!],\n });\n\n const result = Array.isArray(injected) ? injected[0]?.result : undefined;\n\n // Handle async result\n if (result instanceof Promise) {\n const asyncResult = await result;\n if (!asyncResult || typeof asyncResult !== 'object') {\n return { ok: false, error: 'Async extraction returned invalid result' };\n }\n if (!asyncResult.success) {\n return { ok: false, error: asyncResult.error || 'Extraction failed' };\n }\n return { ok: true, value: asyncResult.value as JsonValue };\n }\n\n if (!result || typeof result !== 'object') {\n return { ok: false, error: 'Extraction script returned invalid result' };\n }\n\n const typedResult = result as { success: boolean; value?: unknown; error?: string };\n if (!typedResult.success) {\n return { ok: false, error: typedResult.error || 'Extraction failed' };\n }\n\n return { ok: true, value: typedResult.value as JsonValue };\n } catch (e) {\n return {\n ok: false,\n error: `Script execution failed: ${e instanceof Error ? e.message : String(e)}`,\n };\n }\n}\n\n/**\n * Resolve extraction parameters\n */\nfunction resolveExtractParams(\n params: unknown,\n vars: VariableStore,\n): { ok: true; mode: 'selector' | 'js'; resolved: ResolvedParams } | { ok: false; error: string } {\n const p = params as {\n mode: 'selector' | 'js';\n selector?: unknown;\n attr?: unknown;\n code?: string;\n world?: BrowserWorld;\n saveAs: string;\n };\n\n if (p.mode === 'selector') {\n const selectorResult = tryResolveString(p.selector as string, vars);\n if (!selectorResult.ok) return selectorResult;\n const selector = selectorResult.value.trim();\n if (!selector) return { ok: false, error: 'Empty selector' };\n\n let attr = DEFAULT_EXTRACT_ATTR;\n if (p.attr !== undefined && p.attr !== null) {\n const attrResult = tryResolveString(p.attr as string, vars);\n if (!attrResult.ok) return attrResult;\n attr = attrResult.value.trim() || DEFAULT_EXTRACT_ATTR;\n }\n\n return {\n ok: true,\n mode: 'selector',\n resolved: { selector, attr, saveAs: p.saveAs },\n };\n }\n\n if (p.mode === 'js') {\n if (!p.code || typeof p.code !== 'string') {\n return { ok: false, error: 'JS mode requires code string' };\n }\n return {\n ok: true,\n mode: 'js',\n resolved: { code: p.code, world: p.world, saveAs: p.saveAs },\n };\n }\n\n return { ok: false, error: `Unknown extract mode: ${String(p.mode)}` };\n}\n\ntype ResolvedParams =\n | { selector: string; attr: string; saveAs: string }\n | { code: string; world?: BrowserWorld; saveAs: string };\n\nexport const extractHandler: ActionHandler<'extract'> = {\n type: 'extract',\n\n validate: (action) => {\n const params = action.params as {\n mode: string;\n selector?: unknown;\n code?: string;\n saveAs?: string;\n };\n\n if (params.mode !== 'selector' && params.mode !== 'js') {\n return invalid(`Invalid extract mode: ${String(params.mode)}`);\n }\n\n if (!params.saveAs || typeof params.saveAs !== 'string' || params.saveAs.trim().length === 0) {\n return invalid('Extract action requires a non-empty saveAs variable name');\n }\n\n if (params.mode === 'selector' && params.selector === undefined) {\n return invalid('Selector mode requires a selector');\n }\n\n if (params.mode === 'js' && (!params.code || typeof params.code !== 'string')) {\n return invalid('JS mode requires a code string');\n }\n\n return ok();\n },\n\n describe: (action) => {\n const params = action.params as { mode: string; saveAs?: string };\n const varName = params.saveAs || '?';\n return params.mode === 'js' ? `Extract JS → ${varName}` : `Extract → ${varName}`;\n },\n\n run: async (ctx, action) => {\n const tabId = ctx.tabId;\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found for extract action');\n }\n\n const resolved = resolveExtractParams(action.params, ctx.vars);\n if (!resolved.ok) {\n return failed('VALIDATION_ERROR', resolved.error);\n }\n\n const extractParams =\n resolved.mode === 'selector'\n ? {\n selector: (resolved.resolved as { selector: string }).selector,\n attr: (resolved.resolved as { attr: string }).attr,\n }\n : {\n code: (resolved.resolved as { code: string }).code,\n world: (resolved.resolved as { world?: BrowserWorld }).world,\n };\n\n const result = await executeExtraction(tabId, ctx.frameId, resolved.mode, extractParams);\n\n if (!result.ok) {\n return failed('SCRIPT_FAILED', result.error);\n }\n\n // Store in variables\n const saveAs = (resolved.resolved as { saveAs: string }).saveAs;\n ctx.vars[saveAs] = result.value;\n\n return {\n status: 'success',\n output: { value: result.value },\n };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/fill.ts", "content": "/**\n * Fill Action Handler\n *\n * Handles form input actions:\n * - Text input\n * - File upload\n * - Auto-scroll and focus\n * - Selector fallback with logging\n */\n\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { failed, invalid, ok } from '../registry';\nimport type { ActionHandler } from '../types';\nimport {\n ensureElementVisible,\n logSelectorFallback,\n resolveString,\n selectorLocator,\n sendMessageToTab,\n toSelectorTarget,\n} from './common';\n\nexport const fillHandler: ActionHandler<'fill'> = {\n type: 'fill',\n\n validate: (action) => {\n const target = action.params.target as { ref?: string; candidates?: unknown[] };\n const hasRef = typeof target?.ref === 'string' && target.ref.trim().length > 0;\n const hasCandidates = Array.isArray(target?.candidates) && target.candidates.length > 0;\n const hasValue = action.params.value !== undefined;\n\n if (!hasValue) {\n return invalid('Missing value parameter');\n }\n if (!hasRef && !hasCandidates) {\n return invalid('Missing target selector or ref');\n }\n return ok();\n },\n\n describe: (action) => {\n const value = typeof action.params.value === 'string' ? action.params.value : '(dynamic)';\n const displayValue = value.length > 20 ? value.slice(0, 20) + '...' : value;\n return `Fill \"${displayValue}\"`;\n },\n\n run: async (ctx, action) => {\n const vars = ctx.vars;\n const tabId = ctx.tabId;\n\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found');\n }\n\n // Ensure page is read before locating element\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n\n // Resolve fill value\n const valueResolved = resolveString(action.params.value, vars);\n if (!valueResolved.ok) {\n return failed('VALIDATION_ERROR', valueResolved.error);\n }\n const value = valueResolved.value;\n\n // Locate target element\n const { selectorTarget, firstCandidateType, firstCssOrAttr } = toSelectorTarget(\n action.params.target,\n vars,\n );\n\n const located = await selectorLocator.locate(tabId, selectorTarget, {\n frameId: ctx.frameId,\n preferRef: false,\n });\n\n const frameId = located?.frameId ?? ctx.frameId;\n const refToUse = located?.ref ?? selectorTarget.ref;\n const cssSelector = !located?.ref ? firstCssOrAttr : undefined;\n\n if (!refToUse && !cssSelector) {\n return failed('TARGET_NOT_FOUND', 'Could not locate target element');\n }\n\n // Verify element visibility if we have a ref\n if (located?.ref) {\n const isVisible = await ensureElementVisible(tabId, located.ref, frameId);\n if (!isVisible) {\n return failed('ELEMENT_NOT_VISIBLE', 'Target element is not visible');\n }\n }\n\n // Check for file input and handle file upload\n // Use firstCssOrAttr to check input type even when ref is available\n const selectorForTypeCheck = firstCssOrAttr || cssSelector;\n if (selectorForTypeCheck) {\n const attrResult = await sendMessageToTab<{ value?: string }>(\n tabId,\n { action: 'getAttributeForSelector', selector: selectorForTypeCheck, name: 'type' },\n frameId,\n );\n const inputType = (attrResult.ok ? (attrResult.value?.value ?? '') : '').toLowerCase();\n\n if (inputType === 'file') {\n const uploadResult = await handleCallTool({\n name: TOOL_NAMES.BROWSER.FILE_UPLOAD,\n args: { selector: selectorForTypeCheck, filePath: value, tabId },\n });\n\n if ((uploadResult as { isError?: boolean })?.isError) {\n const errorContent = (uploadResult as { content?: Array<{ text?: string }> })?.content;\n const errorMsg = errorContent?.[0]?.text || 'File upload failed';\n return failed('UNKNOWN', errorMsg);\n }\n\n // Log fallback if used\n const resolvedBy = located?.resolvedBy || (located?.ref ? 'ref' : '');\n const fallbackUsed =\n resolvedBy &&\n firstCandidateType &&\n resolvedBy !== 'ref' &&\n resolvedBy !== firstCandidateType;\n if (fallbackUsed) {\n logSelectorFallback(ctx, action.id, String(firstCandidateType), String(resolvedBy));\n }\n\n return { status: 'success' };\n }\n }\n\n // Scroll element into view (best-effort)\n if (cssSelector) {\n try {\n await handleCallTool({\n name: TOOL_NAMES.BROWSER.INJECT_SCRIPT,\n args: {\n type: 'MAIN',\n jsScript: `try{var el=document.querySelector(${JSON.stringify(cssSelector)});if(el){el.scrollIntoView({behavior:'instant',block:'center',inline:'nearest'});}}catch(e){}`,\n tabId,\n },\n });\n } catch {\n // Ignore scroll errors\n }\n }\n\n // Focus element (best-effort, ignore errors)\n if (located?.ref) {\n await sendMessageToTab(tabId, { action: 'focusByRef', ref: located.ref }, frameId);\n } else if (cssSelector) {\n await handleCallTool({\n name: TOOL_NAMES.BROWSER.INJECT_SCRIPT,\n args: {\n type: 'MAIN',\n jsScript: `try{var el=document.querySelector(${JSON.stringify(cssSelector)});if(el&&el.focus){el.focus();}}catch(e){}`,\n tabId,\n },\n });\n }\n\n // Execute fill\n const fillResult = await handleCallTool({\n name: TOOL_NAMES.BROWSER.FILL,\n args: {\n ref: refToUse,\n selector: cssSelector,\n value,\n frameId,\n tabId,\n },\n });\n\n if ((fillResult as { isError?: boolean })?.isError) {\n const errorContent = (fillResult as { content?: Array<{ text?: string }> })?.content;\n const errorMsg = errorContent?.[0]?.text || 'Fill action failed';\n return failed('UNKNOWN', errorMsg);\n }\n\n // Log fallback if used\n const resolvedBy = located?.resolvedBy || (located?.ref ? 'ref' : '');\n const fallbackUsed =\n resolvedBy && firstCandidateType && resolvedBy !== 'ref' && resolvedBy !== firstCandidateType;\n\n if (fallbackUsed) {\n logSelectorFallback(ctx, action.id, String(firstCandidateType), String(resolvedBy));\n }\n\n return { status: 'success' };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/http.ts", "content": "/**\n * HTTP Action Handler\n *\n * Makes HTTP requests from the extension context.\n * Supports:\n * - All common HTTP methods (GET, POST, PUT, PATCH, DELETE)\n * - JSON and text body types\n * - Form data\n * - Custom headers\n * - Response validation\n * - Result capture to variables\n */\n\nimport { failed, invalid, ok, tryResolveString, tryResolveValue } from '../registry';\nimport type {\n ActionHandler,\n Assignments,\n HttpBody,\n HttpHeaders,\n HttpFormData,\n HttpMethod,\n HttpOkStatus,\n HttpResponse,\n JsonValue,\n Resolvable,\n VariableStore,\n} from '../types';\n\n/** Default timeout for HTTP requests */\nconst DEFAULT_HTTP_TIMEOUT_MS = 30000;\n\n/** Maximum URL length */\nconst MAX_URL_LENGTH = 8192;\n\n/**\n * Resolve HTTP headers\n */\nasync function resolveHeaders(\n headers: HttpHeaders | undefined,\n vars: VariableStore,\n): Promise<{ ok: true; resolved: Record } | { ok: false; error: string }> {\n if (!headers) return { ok: true, resolved: {} };\n\n const resolved: Record = {};\n for (const [key, resolvable] of Object.entries(headers)) {\n const result = tryResolveString(resolvable, vars);\n if (!result.ok) {\n return { ok: false, error: `Failed to resolve header \"${key}\": ${result.error}` };\n }\n resolved[key] = result.value;\n }\n\n return { ok: true, resolved };\n}\n\n/**\n * Resolve form data\n */\nasync function resolveFormData(\n formData: HttpFormData | undefined,\n vars: VariableStore,\n): Promise<{ ok: true; resolved: Record } | { ok: false; error: string }> {\n if (!formData) return { ok: true, resolved: {} };\n\n const resolved: Record = {};\n for (const [key, resolvable] of Object.entries(formData)) {\n const result = tryResolveString(resolvable, vars);\n if (!result.ok) {\n return { ok: false, error: `Failed to resolve form field \"${key}\": ${result.error}` };\n }\n resolved[key] = result.value;\n }\n\n return { ok: true, resolved };\n}\n\n/**\n * Resolve HTTP body\n */\nasync function resolveBody(\n body: HttpBody | undefined,\n vars: VariableStore,\n): Promise<\n | { ok: true; contentType: string | undefined; data: string | undefined }\n | { ok: false; error: string }\n> {\n if (!body || body.kind === 'none') {\n return { ok: true, contentType: undefined, data: undefined };\n }\n\n if (body.kind === 'text') {\n const textResult = tryResolveString(body.text, vars);\n if (!textResult.ok) {\n return { ok: false, error: `Failed to resolve body text: ${textResult.error}` };\n }\n\n let contentType = 'text/plain';\n if (body.contentType) {\n const ctResult = tryResolveString(body.contentType, vars);\n if (!ctResult.ok) {\n return { ok: false, error: `Failed to resolve content type: ${ctResult.error}` };\n }\n contentType = ctResult.value;\n }\n\n return { ok: true, contentType, data: textResult.value };\n }\n\n if (body.kind === 'json') {\n const jsonResult = tryResolveValue(body.json, vars);\n if (!jsonResult.ok) {\n return { ok: false, error: `Failed to resolve JSON body: ${jsonResult.error}` };\n }\n\n return {\n ok: true,\n contentType: 'application/json',\n data: JSON.stringify(jsonResult.value),\n };\n }\n\n return { ok: false, error: `Unknown body kind: ${(body as { kind: string }).kind}` };\n}\n\n/**\n * Check if status code is considered successful\n */\nfunction isStatusOk(status: number, okStatus: HttpOkStatus | undefined): boolean {\n if (!okStatus) {\n // Default: 2xx is OK\n return status >= 200 && status < 300;\n }\n\n if (okStatus.kind === 'range') {\n return status >= okStatus.min && status <= okStatus.max;\n }\n\n if (okStatus.kind === 'list') {\n return okStatus.statuses.includes(status);\n }\n\n return false;\n}\n\n/**\n * Get value from result using dot/bracket path notation\n */\nfunction getValueByPath(obj: unknown, path: string): JsonValue | undefined {\n if (!path || typeof obj !== 'object' || obj === null) {\n return obj as JsonValue;\n }\n\n const segments: Array = [];\n const pathRegex = /([^.[\\]]+)|\\[(\\d+)\\]/g;\n let match: RegExpExecArray | null;\n\n while ((match = pathRegex.exec(path)) !== null) {\n if (match[1]) {\n segments.push(match[1]);\n } else if (match[2]) {\n segments.push(parseInt(match[2], 10));\n }\n }\n\n let current: unknown = obj;\n for (const segment of segments) {\n if (current === null || current === undefined) return undefined;\n if (typeof current !== 'object') return undefined;\n current = (current as Record)[segment];\n }\n\n return current as JsonValue;\n}\n\n/**\n * Apply assignments from response to variables\n */\nfunction applyAssignments(\n response: HttpResponse,\n assignments: Assignments,\n vars: VariableStore,\n): void {\n for (const [varName, path] of Object.entries(assignments)) {\n const value = getValueByPath(response, path);\n if (value !== undefined) {\n vars[varName] = value;\n }\n }\n}\n\nexport const httpHandler: ActionHandler<'http'> = {\n type: 'http',\n\n validate: (action) => {\n const params = action.params;\n\n if (params.url === undefined) {\n return invalid('HTTP action requires a URL');\n }\n\n if (params.method !== undefined) {\n const validMethods: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];\n if (!validMethods.includes(params.method)) {\n return invalid(`Invalid HTTP method: ${String(params.method)}`);\n }\n }\n\n return ok();\n },\n\n describe: (action) => {\n const method = action.params.method || 'GET';\n const url = typeof action.params.url === 'string' ? action.params.url : '(dynamic)';\n const displayUrl = url.length > 40 ? url.slice(0, 40) + '...' : url;\n return `${method} ${displayUrl}`;\n },\n\n run: async (ctx, action) => {\n const params = action.params;\n const method: HttpMethod = params.method || 'GET';\n\n // Resolve URL\n const urlResult = tryResolveString(params.url, ctx.vars);\n if (!urlResult.ok) {\n return failed('VALIDATION_ERROR', `Failed to resolve URL: ${urlResult.error}`);\n }\n\n const url = urlResult.value.trim();\n if (!url) {\n return failed('VALIDATION_ERROR', 'URL is empty');\n }\n\n if (url.length > MAX_URL_LENGTH) {\n return failed('VALIDATION_ERROR', `URL exceeds maximum length of ${MAX_URL_LENGTH}`);\n }\n\n // Validate URL format\n try {\n new URL(url);\n } catch {\n return failed('VALIDATION_ERROR', `Invalid URL format: ${url}`);\n }\n\n // Resolve headers\n const headersResult = await resolveHeaders(params.headers, ctx.vars);\n if (!headersResult.ok) {\n return failed('VALIDATION_ERROR', headersResult.error);\n }\n\n // Resolve body\n const bodyResult = await resolveBody(params.body, ctx.vars);\n if (!bodyResult.ok) {\n return failed('VALIDATION_ERROR', bodyResult.error);\n }\n\n // Resolve form data (alternative to body)\n const formDataResult = await resolveFormData(params.formData, ctx.vars);\n if (!formDataResult.ok) {\n return failed('VALIDATION_ERROR', formDataResult.error);\n }\n\n // Build request\n const headers: Record = { ...headersResult.resolved };\n let requestBody: string | FormData | undefined;\n\n if (Object.keys(formDataResult.resolved).length > 0) {\n // Use form data\n const formData = new FormData();\n for (const [key, value] of Object.entries(formDataResult.resolved)) {\n formData.append(key, value);\n }\n requestBody = formData as unknown as string; // FormData handled by fetch\n } else if (bodyResult.data !== undefined) {\n // Use body\n requestBody = bodyResult.data;\n if (bodyResult.contentType && !headers['Content-Type']) {\n headers['Content-Type'] = bodyResult.contentType;\n }\n }\n\n // Execute request\n const timeoutMs = action.policy?.timeout?.ms ?? DEFAULT_HTTP_TIMEOUT_MS;\n const controller = new AbortController();\n const timeoutId = setTimeout(() => controller.abort(), timeoutMs);\n\n try {\n const fetchOptions: RequestInit = {\n method,\n headers,\n signal: controller.signal,\n };\n\n if (requestBody !== undefined && method !== 'GET' && method !== 'DELETE') {\n fetchOptions.body = requestBody;\n }\n\n const response = await fetch(url, fetchOptions);\n clearTimeout(timeoutId);\n\n // Parse response\n const responseHeaders: Record = {};\n response.headers.forEach((value, key) => {\n responseHeaders[key] = value;\n });\n\n let responseBody: JsonValue | string | null = null;\n const contentType = response.headers.get('content-type') || '';\n\n try {\n if (contentType.includes('application/json')) {\n responseBody = (await response.json()) as JsonValue;\n } else {\n responseBody = await response.text();\n }\n } catch {\n responseBody = null;\n }\n\n const httpResponse: HttpResponse = {\n url: response.url,\n status: response.status,\n headers: responseHeaders,\n body: responseBody,\n };\n\n // Check status\n if (!isStatusOk(response.status, params.okStatus)) {\n return failed(\n 'NETWORK_REQUEST_FAILED',\n `HTTP ${response.status}: ${response.statusText || 'Request failed'}`,\n );\n }\n\n // Store response if saveAs specified\n if (params.saveAs) {\n ctx.vars[params.saveAs] = httpResponse as unknown as JsonValue;\n }\n\n // Apply assignments\n if (params.assign) {\n applyAssignments(httpResponse, params.assign, ctx.vars);\n }\n\n return {\n status: 'success',\n output: { response: httpResponse },\n };\n } catch (e) {\n clearTimeout(timeoutId);\n\n if (e instanceof Error && e.name === 'AbortError') {\n return failed('TIMEOUT', `HTTP request timed out after ${timeoutMs}ms`);\n }\n\n return failed(\n 'NETWORK_REQUEST_FAILED',\n `HTTP request failed: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/index.ts", "content": "/**\n * Action Handlers Registry\n *\n * Central registration point for all action handlers.\n * Provides factory function to create a fully-configured ActionRegistry\n * with all replay handlers registered.\n */\n\nimport { ActionRegistry, createActionRegistry } from '../registry';\nimport { assertHandler } from './assert';\nimport { clickHandler, dblclickHandler } from './click';\nimport { foreachHandler, ifHandler, switchFrameHandler, whileHandler } from './control-flow';\nimport { delayHandler } from './delay';\nimport { setAttributeHandler, triggerEventHandler } from './dom';\nimport { dragHandler } from './drag';\nimport { extractHandler } from './extract';\nimport { fillHandler } from './fill';\nimport { httpHandler } from './http';\nimport { keyHandler } from './key';\nimport { navigateHandler } from './navigate';\nimport { screenshotHandler } from './screenshot';\nimport { scriptHandler } from './script';\nimport { scrollHandler } from './scroll';\nimport { closeTabHandler, handleDownloadHandler, openTabHandler, switchTabHandler } from './tabs';\nimport { waitHandler } from './wait';\n\n// Re-export individual handlers for direct access\nexport { assertHandler } from './assert';\nexport { clickHandler, dblclickHandler } from './click';\nexport { foreachHandler, ifHandler, switchFrameHandler, whileHandler } from './control-flow';\nexport { delayHandler } from './delay';\nexport { setAttributeHandler, triggerEventHandler } from './dom';\nexport { dragHandler } from './drag';\nexport { extractHandler } from './extract';\nexport { fillHandler } from './fill';\nexport { httpHandler } from './http';\nexport { keyHandler } from './key';\nexport { navigateHandler } from './navigate';\nexport { screenshotHandler } from './screenshot';\nexport { scriptHandler } from './script';\nexport { scrollHandler } from './scroll';\nexport { closeTabHandler, handleDownloadHandler, openTabHandler, switchTabHandler } from './tabs';\nexport { waitHandler } from './wait';\n\n// Re-export common utilities\nexport * from './common';\n\n/**\n * All available action handlers for replay\n *\n * Organized by category:\n * - Navigation: navigate\n * - Interaction: click, dblclick, fill, key, scroll, drag\n * - Timing: wait, delay\n * - Validation: assert\n * - Data: extract, script, http, screenshot\n * - DOM Tools: triggerEvent, setAttribute\n * - Tabs: openTab, switchTab, closeTab, handleDownload\n * - Control Flow: if, foreach, while, switchFrame\n *\n * TODO: Add remaining handlers:\n * - loopElements, executeFlow (advanced control flow)\n */\nconst ALL_HANDLERS = [\n // Navigation\n navigateHandler,\n // Interaction\n clickHandler,\n dblclickHandler,\n fillHandler,\n keyHandler,\n scrollHandler,\n dragHandler,\n // Timing\n waitHandler,\n delayHandler,\n // Validation\n assertHandler,\n // Data\n extractHandler,\n scriptHandler,\n httpHandler,\n screenshotHandler,\n // DOM Tools\n triggerEventHandler,\n setAttributeHandler,\n // Tabs\n openTabHandler,\n switchTabHandler,\n closeTabHandler,\n handleDownloadHandler,\n // Control Flow\n ifHandler,\n foreachHandler,\n whileHandler,\n switchFrameHandler,\n] as const;\n\n/**\n * Register all replay handlers to an ActionRegistry instance\n */\nexport function registerReplayHandlers(registry: ActionRegistry): void {\n // Register each handler individually to satisfy TypeScript's type checker\n registry.register(navigateHandler, { override: true });\n registry.register(clickHandler, { override: true });\n registry.register(dblclickHandler, { override: true });\n registry.register(fillHandler, { override: true });\n registry.register(keyHandler, { override: true });\n registry.register(scrollHandler, { override: true });\n registry.register(dragHandler, { override: true });\n registry.register(waitHandler, { override: true });\n registry.register(delayHandler, { override: true });\n registry.register(assertHandler, { override: true });\n registry.register(extractHandler, { override: true });\n registry.register(scriptHandler, { override: true });\n registry.register(httpHandler, { override: true });\n registry.register(screenshotHandler, { override: true });\n registry.register(triggerEventHandler, { override: true });\n registry.register(setAttributeHandler, { override: true });\n registry.register(openTabHandler, { override: true });\n registry.register(switchTabHandler, { override: true });\n registry.register(closeTabHandler, { override: true });\n registry.register(handleDownloadHandler, { override: true });\n registry.register(ifHandler, { override: true });\n registry.register(foreachHandler, { override: true });\n registry.register(whileHandler, { override: true });\n registry.register(switchFrameHandler, { override: true });\n}\n\n/**\n * Create a new ActionRegistry with all replay handlers registered\n *\n * This is the primary entry point for creating an action execution context.\n *\n * @example\n * ```ts\n * const registry = createReplayActionRegistry();\n *\n * const result = await registry.execute(ctx, {\n * id: 'action-1',\n * type: 'click',\n * params: { target: { candidates: [...] } },\n * });\n * ```\n */\nexport function createReplayActionRegistry(): ActionRegistry {\n const registry = createActionRegistry();\n registerReplayHandlers(registry);\n return registry;\n}\n\n/**\n * Get list of supported action types\n */\nexport function getSupportedActionTypes(): ReadonlyArray {\n return ALL_HANDLERS.map((h) => h.type);\n}\n\n/**\n * Check if an action type is supported\n */\nexport function isActionTypeSupported(type: string): boolean {\n return ALL_HANDLERS.some((h) => h.type === type);\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/key.ts", "content": "/**\n * Key Action Handler\n *\n * Handles keyboard input:\n * - Resolves key sequences via variables/templates\n * - Optionally focuses a target element before sending keys\n * - Dispatches keyboard events via the keyboard tool\n */\n\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { failed, invalid, ok } from '../registry';\nimport type { ActionHandler, ElementTarget } from '../types';\nimport {\n ensureElementVisible,\n logSelectorFallback,\n resolveString,\n selectorLocator,\n sendMessageToTab,\n toSelectorTarget,\n} from './common';\n\n/** Extract error text from tool result */\nfunction extractToolError(result: unknown, fallback: string): string {\n const content = (result as { content?: Array<{ text?: string }> })?.content;\n return content?.find((c) => typeof c?.text === 'string')?.text || fallback;\n}\n\n/** Check if target has valid selector specification */\nfunction hasTargetSpec(target: unknown): boolean {\n if (!target || typeof target !== 'object') return false;\n const t = target as { ref?: unknown; candidates?: unknown };\n const hasRef = typeof t.ref === 'string' && t.ref.trim().length > 0;\n const hasCandidates = Array.isArray(t.candidates) && t.candidates.length > 0;\n return hasRef || hasCandidates;\n}\n\n/** Strip frame prefix from composite selector */\nfunction stripCompositeSelector(selector: string): string {\n const raw = String(selector || '').trim();\n if (!raw || !raw.includes('|>')) return raw;\n const parts = raw\n .split('|>')\n .map((p) => p.trim())\n .filter(Boolean);\n return parts.length > 0 ? parts[parts.length - 1] : raw;\n}\n\nexport const keyHandler: ActionHandler<'key'> = {\n type: 'key',\n\n validate: (action) => {\n if (action.params.keys === undefined) {\n return invalid('Missing keys parameter');\n }\n\n if (action.params.target !== undefined && !hasTargetSpec(action.params.target)) {\n return invalid('Target must include a non-empty ref or selector candidates');\n }\n\n return ok();\n },\n\n describe: (action) => {\n const keys = typeof action.params.keys === 'string' ? action.params.keys : '(dynamic)';\n const display = keys.length > 30 ? keys.slice(0, 30) + '...' : keys;\n return `Keys \"${display}\"`;\n },\n\n run: async (ctx, action) => {\n const vars = ctx.vars;\n const tabId = ctx.tabId;\n\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found for key action');\n }\n\n // Resolve keys string\n const keysResolved = resolveString(action.params.keys, vars);\n if (!keysResolved.ok) {\n return failed('VALIDATION_ERROR', keysResolved.error);\n }\n\n const keys = keysResolved.value.trim();\n if (!keys) {\n return failed('VALIDATION_ERROR', 'Keys string is empty');\n }\n\n let frameId = ctx.frameId;\n let selectorForTool: string | undefined;\n let firstCandidateType: string | undefined;\n let resolvedBy: string | undefined;\n\n // Handle optional target focusing\n const target = action.params.target as ElementTarget | undefined;\n if (target) {\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: { tabId } });\n\n const {\n selectorTarget,\n firstCandidateType: firstType,\n firstCssOrAttr,\n } = toSelectorTarget(target, vars);\n firstCandidateType = firstType;\n\n const located = await selectorLocator.locate(tabId, selectorTarget, {\n frameId: ctx.frameId,\n preferRef: false,\n });\n\n frameId = located?.frameId ?? ctx.frameId;\n const refToUse = located?.ref ?? selectorTarget.ref;\n\n if (!refToUse && !firstCssOrAttr) {\n return failed('TARGET_NOT_FOUND', 'Could not locate target element for key action');\n }\n\n resolvedBy = located?.resolvedBy || (located?.ref ? 'ref' : '');\n\n // Only verify visibility for freshly located refs (not stale refs from payload)\n if (located?.ref) {\n const visible = await ensureElementVisible(tabId, located.ref, frameId);\n if (!visible) {\n return failed('ELEMENT_NOT_VISIBLE', 'Target element is not visible');\n }\n\n const focusResult = await sendMessageToTab<{ success?: boolean; error?: string }>(\n tabId,\n { action: 'focusByRef', ref: located.ref },\n frameId,\n );\n\n if (!focusResult.ok || focusResult.value?.success !== true) {\n const focusErr = focusResult.ok ? focusResult.value?.error : focusResult.error;\n\n if (!firstCssOrAttr) {\n return failed(\n 'TARGET_NOT_FOUND',\n `Failed to focus target element: ${focusErr || 'ref may be stale'}`,\n );\n }\n\n ctx.log(`focusByRef failed; falling back to selector: ${focusErr}`, 'warn');\n }\n\n // Try to resolve ref to CSS selector for tool\n const resolved = await sendMessageToTab<{\n success?: boolean;\n selector?: string;\n error?: string;\n }>(tabId, { action: TOOL_MESSAGE_TYPES.RESOLVE_REF, ref: located.ref }, frameId);\n\n if (\n resolved.ok &&\n resolved.value?.success !== false &&\n typeof resolved.value?.selector === 'string'\n ) {\n const sel = resolved.value.selector.trim();\n if (sel) selectorForTool = sel;\n }\n }\n\n // Fallback to CSS/attr selector\n if (!selectorForTool && firstCssOrAttr) {\n const stripped = stripCompositeSelector(firstCssOrAttr);\n if (stripped) selectorForTool = stripped;\n }\n }\n\n // Execute keyboard input\n const keyboardResult = await handleCallTool({\n name: TOOL_NAMES.BROWSER.KEYBOARD,\n args: {\n keys,\n selector: selectorForTool,\n selectorType: selectorForTool ? 'css' : undefined,\n tabId,\n frameId,\n },\n });\n\n if ((keyboardResult as { isError?: boolean })?.isError) {\n return failed('UNKNOWN', extractToolError(keyboardResult, 'Keyboard input failed'));\n }\n\n // Log fallback after successful execution\n const fallbackUsed =\n resolvedBy && firstCandidateType && resolvedBy !== 'ref' && resolvedBy !== firstCandidateType;\n if (fallbackUsed) {\n logSelectorFallback(ctx, action.id, String(firstCandidateType), String(resolvedBy));\n }\n\n return { status: 'success' };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/navigate.ts", "content": "/**\n * Navigate Action Handler\n *\n * Handles page navigation actions:\n * - Navigate to URL\n * - Page refresh\n * - Wait for navigation completion\n */\n\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { ENGINE_CONSTANTS } from '../../engine/constants';\nimport { ensureReadPageIfWeb, waitForNavigationDone } from '../../engine/policies/wait';\nimport { failed, invalid, ok } from '../registry';\nimport type { ActionHandler } from '../types';\nimport { clampInt, readTabUrl, resolveString } from './common';\n\nexport const navigateHandler: ActionHandler<'navigate'> = {\n type: 'navigate',\n\n validate: (action) => {\n const hasRefresh = action.params.refresh === true;\n const hasUrl = action.params.url !== undefined;\n return hasRefresh || hasUrl ? ok() : invalid('Missing url or refresh parameter');\n },\n\n describe: (action) => {\n if (action.params.refresh) return 'Refresh page';\n const url = typeof action.params.url === 'string' ? action.params.url : '(dynamic)';\n return `Navigate to ${url}`;\n },\n\n run: async (ctx, action) => {\n const vars = ctx.vars;\n const tabId = ctx.tabId;\n // Check if StepRunner owns nav-wait (skip internal nav-wait logic)\n const skipNavWait = ctx.execution?.skipNavWait === true;\n\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found');\n }\n\n // Only read beforeUrl and calculate waitMs if we need to do nav-wait\n const beforeUrl = skipNavWait ? '' : await readTabUrl(tabId);\n const waitMs = skipNavWait\n ? 0\n : clampInt(\n action.policy?.timeout?.ms ?? ENGINE_CONSTANTS.DEFAULT_WAIT_MS,\n 0,\n ENGINE_CONSTANTS.MAX_WAIT_MS,\n );\n\n // Handle page refresh\n if (action.params.refresh) {\n const result = await handleCallTool({\n name: TOOL_NAMES.BROWSER.NAVIGATE,\n args: { refresh: true, tabId },\n });\n\n if ((result as { isError?: boolean })?.isError) {\n const errorContent = (result as { content?: Array<{ text?: string }> })?.content;\n const errorMsg = errorContent?.[0]?.text || 'Page refresh failed';\n return failed('NAVIGATION_FAILED', errorMsg);\n }\n\n // Skip nav-wait if StepRunner handles it\n if (!skipNavWait) {\n await waitForNavigationDone(beforeUrl, waitMs);\n await ensureReadPageIfWeb();\n }\n return { status: 'success' };\n }\n\n // Handle URL navigation\n const urlResolved = resolveString(action.params.url, vars);\n if (!urlResolved.ok) {\n return failed('VALIDATION_ERROR', urlResolved.error);\n }\n\n const url = urlResolved.value.trim();\n if (!url) {\n return failed('VALIDATION_ERROR', 'URL is empty');\n }\n\n const result = await handleCallTool({\n name: TOOL_NAMES.BROWSER.NAVIGATE,\n args: { url, tabId },\n });\n\n if ((result as { isError?: boolean })?.isError) {\n const errorContent = (result as { content?: Array<{ text?: string }> })?.content;\n const errorMsg = errorContent?.[0]?.text || `Navigation to ${url} failed`;\n return failed('NAVIGATION_FAILED', errorMsg);\n }\n\n // Skip nav-wait if StepRunner handles it\n if (!skipNavWait) {\n await waitForNavigationDone(beforeUrl, waitMs);\n await ensureReadPageIfWeb();\n }\n\n return { status: 'success' };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/screenshot.ts", "content": "/**\n * Screenshot Action Handler\n *\n * Captures screenshots and optionally stores base64 data in variables.\n * Supports full page, selector-based, and viewport screenshots.\n */\n\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { failed, invalid, ok } from '../registry';\nimport type { ActionHandler } from '../types';\nimport { resolveString } from './common';\n\n/** Extract text content from tool result */\nfunction extractToolText(result: unknown): string | undefined {\n const content = (result as { content?: Array<{ type?: string; text?: string }> })?.content;\n const text = content?.find((c) => c?.type === 'text' && typeof c.text === 'string')?.text;\n return typeof text === 'string' && text.trim() ? text : undefined;\n}\n\nexport const screenshotHandler: ActionHandler<'screenshot'> = {\n type: 'screenshot',\n\n validate: (action) => {\n const saveAs = action.params.saveAs;\n if (saveAs !== undefined && (!saveAs || String(saveAs).trim().length === 0)) {\n return invalid('saveAs must be a non-empty variable name when provided');\n }\n return ok();\n },\n\n describe: (action) => {\n if (action.params.fullPage) return 'Screenshot (full page)';\n if (typeof action.params.selector === 'string') {\n const sel =\n action.params.selector.length > 30\n ? action.params.selector.slice(0, 30) + '...'\n : action.params.selector;\n return `Screenshot: ${sel}`;\n }\n if (action.params.selector) return 'Screenshot (dynamic selector)';\n return 'Screenshot';\n },\n\n run: async (ctx, action) => {\n const tabId = ctx.tabId;\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found for screenshot action');\n }\n\n // Resolve optional selector\n let selector: string | undefined;\n if (action.params.selector !== undefined) {\n const resolved = resolveString(action.params.selector, ctx.vars);\n if (!resolved.ok) return failed('VALIDATION_ERROR', resolved.error);\n const s = resolved.value.trim();\n if (s) selector = s;\n }\n\n // Call screenshot tool\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.SCREENSHOT,\n args: {\n name: 'workflow',\n storeBase64: true,\n fullPage: action.params.fullPage === true,\n selector,\n tabId,\n },\n });\n\n if ((res as { isError?: boolean })?.isError) {\n return failed('UNKNOWN', extractToolText(res) || 'Screenshot failed');\n }\n\n // Parse response\n const text = extractToolText(res);\n if (!text) {\n return failed('UNKNOWN', 'Screenshot tool returned an empty response');\n }\n\n let payload: unknown;\n try {\n payload = JSON.parse(text);\n } catch {\n return failed('UNKNOWN', 'Screenshot tool returned invalid JSON');\n }\n\n const base64Data = (payload as { base64Data?: unknown })?.base64Data;\n if (typeof base64Data !== 'string' || base64Data.length === 0) {\n return failed('UNKNOWN', 'Screenshot tool returned empty base64Data');\n }\n\n // Store in variables if saveAs specified\n if (action.params.saveAs) {\n ctx.vars[action.params.saveAs] = base64Data;\n }\n\n return { status: 'success', output: { base64Data } };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/script.ts", "content": "/**\n * Script Action Handler\n *\n * Executes custom JavaScript in the page context.\n * Supports:\n * - MAIN or ISOLATED world execution\n * - Argument passing with variable resolution\n * - Result capture to variables\n * - Assignment mapping from result paths\n */\n\nimport { failed, invalid, ok, tryResolveValue } from '../registry';\nimport type {\n ActionHandler,\n Assignments,\n BrowserWorld,\n JsonValue,\n Resolvable,\n VariableStore,\n} from '../types';\n\n/** Maximum code length to prevent abuse */\nconst MAX_CODE_LENGTH = 100000;\n\n/**\n * Resolve script arguments\n */\nfunction resolveArgs(\n args: Record> | undefined,\n vars: VariableStore,\n): { ok: true; resolved: Record } | { ok: false; error: string } {\n if (!args) return { ok: true, resolved: {} };\n\n const resolved: Record = {};\n for (const [key, resolvable] of Object.entries(args)) {\n const result = tryResolveValue(resolvable, vars);\n if (!result.ok) {\n return { ok: false, error: `Failed to resolve arg \"${key}\": ${result.error}` };\n }\n resolved[key] = result.value;\n }\n\n return { ok: true, resolved };\n}\n\n/**\n * Get value from result using dot/bracket path notation\n */\nfunction getValueByPath(obj: unknown, path: string): JsonValue | undefined {\n if (!path || typeof obj !== 'object' || obj === null) {\n return obj as JsonValue;\n }\n\n // Parse path: supports \"data.items[0].name\" style\n const segments: Array = [];\n const pathRegex = /([^.[\\]]+)|\\[(\\d+)\\]/g;\n let match: RegExpExecArray | null;\n\n while ((match = pathRegex.exec(path)) !== null) {\n if (match[1]) {\n segments.push(match[1]);\n } else if (match[2]) {\n segments.push(parseInt(match[2], 10));\n }\n }\n\n let current: unknown = obj;\n for (const segment of segments) {\n if (current === null || current === undefined) return undefined;\n if (typeof current !== 'object') return undefined;\n current = (current as Record)[segment];\n }\n\n return current as JsonValue;\n}\n\n/**\n * Apply assignments from result to variables\n */\nfunction applyAssignments(result: JsonValue, assignments: Assignments, vars: VariableStore): void {\n for (const [varName, path] of Object.entries(assignments)) {\n const value = getValueByPath(result, path);\n if (value !== undefined) {\n vars[varName] = value;\n }\n }\n}\n\n/**\n * Execute script in page context\n */\nasync function executeScript(\n tabId: number,\n frameId: number | undefined,\n code: string,\n args: Record,\n world: BrowserWorld,\n): Promise<{ ok: true; result: JsonValue } | { ok: false; error: string }> {\n const frameIds = typeof frameId === 'number' ? [frameId] : undefined;\n\n try {\n const injected = await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n world: world === 'ISOLATED' ? 'ISOLATED' : 'MAIN',\n func: (scriptCode: string, scriptArgs: Record) => {\n try {\n // Create function with args available\n const argNames = Object.keys(scriptArgs);\n const argValues = Object.values(scriptArgs);\n\n // Wrap code to return result\n const wrappedCode = `\n return (function(${argNames.join(', ')}) {\n ${scriptCode}\n })(${argNames.map((_, i) => `arguments[${i}]`).join(', ')});\n `;\n\n const fn = new Function(...argNames, wrappedCode);\n const result = fn(...argValues);\n\n // Handle promises\n if (result instanceof Promise) {\n return result.then(\n (value: unknown) => ({ success: true, result: value }),\n (error: Error) => ({ success: false, error: error?.message || String(error) }),\n );\n }\n\n return { success: true, result };\n } catch (e) {\n return { success: false, error: e instanceof Error ? e.message : String(e) };\n }\n },\n args: [code, args],\n });\n\n const scriptResult = Array.isArray(injected) ? injected[0]?.result : undefined;\n\n // Handle async result\n if (scriptResult instanceof Promise) {\n const asyncResult = await scriptResult;\n if (!asyncResult || typeof asyncResult !== 'object') {\n return { ok: false, error: 'Async script returned invalid result' };\n }\n if (!asyncResult.success) {\n return { ok: false, error: asyncResult.error || 'Script failed' };\n }\n return { ok: true, result: asyncResult.result as JsonValue };\n }\n\n if (!scriptResult || typeof scriptResult !== 'object') {\n return { ok: false, error: 'Script returned invalid result' };\n }\n\n const typedResult = scriptResult as { success: boolean; result?: unknown; error?: string };\n if (!typedResult.success) {\n return { ok: false, error: typedResult.error || 'Script failed' };\n }\n\n return { ok: true, result: typedResult.result as JsonValue };\n } catch (e) {\n return {\n ok: false,\n error: `Script execution failed: ${e instanceof Error ? e.message : String(e)}`,\n };\n }\n}\n\nexport const scriptHandler: ActionHandler<'script'> = {\n type: 'script',\n\n validate: (action) => {\n const params = action.params;\n\n if (!params.code || typeof params.code !== 'string') {\n return invalid('Script action requires a code string');\n }\n\n if (params.code.length > MAX_CODE_LENGTH) {\n return invalid(`Script code exceeds maximum length of ${MAX_CODE_LENGTH} characters`);\n }\n\n if (params.world !== undefined && params.world !== 'MAIN' && params.world !== 'ISOLATED') {\n return invalid(`Invalid world: ${String(params.world)}`);\n }\n\n if (params.when !== undefined && params.when !== 'before' && params.when !== 'after') {\n return invalid(`Invalid timing: ${String(params.when)}`);\n }\n\n return ok();\n },\n\n describe: (action) => {\n const world = action.params.world === 'ISOLATED' ? '[isolated]' : '';\n const timing = action.params.when ? `(${action.params.when})` : '';\n return `Script ${world}${timing}`.trim();\n },\n\n run: async (ctx, action) => {\n const tabId = ctx.tabId;\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found for script action');\n }\n\n const params = action.params;\n const world: BrowserWorld = params.world || 'MAIN';\n\n // Resolve arguments\n const argsResult = resolveArgs(params.args, ctx.vars);\n if (!argsResult.ok) {\n return failed('VALIDATION_ERROR', argsResult.error);\n }\n\n // Execute script\n const result = await executeScript(tabId, ctx.frameId, params.code, argsResult.resolved, world);\n\n if (!result.ok) {\n return failed('SCRIPT_FAILED', result.error);\n }\n\n // Store result if saveAs specified\n if (params.saveAs) {\n ctx.vars[params.saveAs] = result.result;\n }\n\n // Apply assignments if specified\n if (params.assign) {\n applyAssignments(result.result, params.assign, ctx.vars);\n }\n\n return {\n status: 'success',\n output: { result: result.result },\n };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/scroll.ts", "content": "/**\n * Scroll Action Handler\n *\n * Supports three scroll modes:\n * - offset: Scroll the window to absolute coordinates\n * - element: Scroll an element into view\n * - container: Scroll within a container element\n */\n\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { failed, invalid, ok, tryResolveNumber } from '../registry';\nimport type { ActionHandler, ElementTarget } from '../types';\nimport { logSelectorFallback, selectorLocator, sendMessageToTab, toSelectorTarget } from './common';\n\n/** Check if target has valid selector specification */\nfunction hasTargetSpec(target: unknown): boolean {\n if (!target || typeof target !== 'object') return false;\n const t = target as { ref?: unknown; candidates?: unknown };\n const hasRef = typeof t.ref === 'string' && t.ref.trim().length > 0;\n const hasCandidates = Array.isArray(t.candidates) && t.candidates.length > 0;\n return hasRef || hasCandidates;\n}\n\n/** Strip frame prefix from composite selector */\nfunction stripCompositeSelector(selector: string): string {\n const raw = String(selector || '').trim();\n if (!raw || !raw.includes('|>')) return raw;\n const parts = raw\n .split('|>')\n .map((p) => p.trim())\n .filter(Boolean);\n return parts.length > 0 ? parts[parts.length - 1] : raw;\n}\n\n/** Format offset value for description */\nfunction describeOffset(v: unknown): string {\n return typeof v === 'number' && Number.isFinite(v) ? String(v) : '(dynamic)';\n}\n\nexport const scrollHandler: ActionHandler<'scroll'> = {\n type: 'scroll',\n\n validate: (action) => {\n const mode = action.params.mode;\n if (mode !== 'offset' && mode !== 'element' && mode !== 'container') {\n return invalid(`Unsupported scroll mode: ${String(mode)}`);\n }\n\n if ((mode === 'element' || mode === 'container') && !hasTargetSpec(action.params.target)) {\n return invalid(`Scroll mode \"${mode}\" requires a target ref or selector candidates`);\n }\n\n return ok();\n },\n\n describe: (action) => {\n const mode = action.params.mode;\n if (mode === 'offset') {\n const x = describeOffset(action.params.offset?.x);\n const y = describeOffset(action.params.offset?.y);\n return `Scroll window to x=${x}, y=${y}`;\n }\n if (mode === 'container') return 'Scroll container';\n return 'Scroll to element';\n },\n\n run: async (ctx, action) => {\n const vars = ctx.vars;\n const tabId = ctx.tabId;\n\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found for scroll action');\n }\n\n const mode = action.params.mode;\n\n // ----------------------------\n // Offset mode: window scroll\n // ----------------------------\n if (mode === 'offset') {\n let top: number | undefined;\n let left: number | undefined;\n\n if (action.params.offset?.y !== undefined) {\n const yResolved = tryResolveNumber(action.params.offset.y, vars);\n if (!yResolved.ok) return failed('VALIDATION_ERROR', yResolved.error);\n top = yResolved.value;\n }\n\n if (action.params.offset?.x !== undefined) {\n const xResolved = tryResolveNumber(action.params.offset.x, vars);\n if (!xResolved.ok) return failed('VALIDATION_ERROR', xResolved.error);\n left = xResolved.value;\n }\n\n const frameIds = typeof ctx.frameId === 'number' ? [ctx.frameId] : undefined;\n\n try {\n const injected = await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n world: 'MAIN',\n func: (t: number | null, l: number | null) => {\n try {\n const hasTop = typeof t === 'number' && Number.isFinite(t);\n const hasLeft = typeof l === 'number' && Number.isFinite(l);\n if (!hasTop && !hasLeft) return true;\n\n window.scrollTo({\n top: hasTop ? t : window.scrollY,\n left: hasLeft ? l : window.scrollX,\n behavior: 'auto',\n });\n return true;\n } catch {\n return false;\n }\n },\n args: [top ?? null, left ?? null],\n });\n\n const result = Array.isArray(injected) ? injected[0]?.result : undefined;\n if (result !== true) {\n return failed('SCRIPT_FAILED', 'Window scroll script returned failure');\n }\n } catch (e) {\n return failed(\n 'SCRIPT_FAILED',\n `Failed to scroll window: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n\n return { status: 'success' };\n }\n\n // ----------------------------\n // Element/Container mode\n // ----------------------------\n const target = action.params.target as ElementTarget | undefined;\n if (!target) {\n return failed('VALIDATION_ERROR', `Scroll mode \"${mode}\" requires a target`);\n }\n\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: { tabId } });\n\n const { selectorTarget, firstCandidateType, firstCssOrAttr } = toSelectorTarget(target, vars);\n const located = await selectorLocator.locate(tabId, selectorTarget, {\n frameId: ctx.frameId,\n preferRef: false,\n });\n\n const frameId = located?.frameId ?? ctx.frameId;\n const refToUse = located?.ref ?? selectorTarget.ref;\n\n // Resolve selector from ref or fallback\n let selector: string | undefined;\n if (refToUse) {\n const resolved = await sendMessageToTab<{ success?: boolean; selector?: string }>(\n tabId,\n { action: TOOL_MESSAGE_TYPES.RESOLVE_REF, ref: refToUse },\n frameId,\n );\n if (\n resolved.ok &&\n resolved.value?.success !== false &&\n typeof resolved.value?.selector === 'string'\n ) {\n const sel = resolved.value.selector.trim();\n if (sel) selector = sel;\n }\n }\n\n if (!selector && firstCssOrAttr) {\n const stripped = stripCompositeSelector(firstCssOrAttr);\n if (stripped) selector = stripped;\n }\n\n if (!selector) {\n return failed('TARGET_NOT_FOUND', 'Could not resolve a CSS selector for the scroll target');\n }\n\n // Resolve offset for container mode\n let scrollTop: number | undefined;\n let scrollLeft: number | undefined;\n if (mode === 'container') {\n if (action.params.offset?.y !== undefined) {\n const yResolved = tryResolveNumber(action.params.offset.y, vars);\n if (!yResolved.ok) return failed('VALIDATION_ERROR', yResolved.error);\n scrollTop = yResolved.value;\n }\n\n if (action.params.offset?.x !== undefined) {\n const xResolved = tryResolveNumber(action.params.offset.x, vars);\n if (!xResolved.ok) return failed('VALIDATION_ERROR', xResolved.error);\n scrollLeft = xResolved.value;\n }\n }\n\n // Execute scroll script\n try {\n const frameIds = typeof frameId === 'number' ? [frameId] : undefined;\n const injected = await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n world: 'MAIN',\n func: (\n sel: string,\n scrollMode: 'element' | 'container',\n top: number | null,\n left: number | null,\n ) => {\n const el = document.querySelector(sel) as HTMLElement | null;\n if (!el) return false;\n\n if (scrollMode === 'element') {\n el.scrollIntoView({ behavior: 'instant', block: 'center', inline: 'nearest' });\n return true;\n }\n\n // Container scroll\n const hasTop = typeof top === 'number' && Number.isFinite(top);\n const hasLeft = typeof left === 'number' && Number.isFinite(left);\n\n if (typeof el.scrollTo === 'function') {\n el.scrollTo({\n top: hasTop ? top : el.scrollTop,\n left: hasLeft ? left : el.scrollLeft,\n behavior: 'instant',\n });\n } else {\n if (hasTop) el.scrollTop = top;\n if (hasLeft) el.scrollLeft = left;\n }\n return true;\n },\n args: [selector, mode, scrollTop ?? null, scrollLeft ?? null],\n });\n\n const result = Array.isArray(injected) ? injected[0]?.result : undefined;\n if (result !== true) {\n return failed('TARGET_NOT_FOUND', `Scroll target not found: ${selector}`);\n }\n } catch (e) {\n return failed(\n 'SCRIPT_FAILED',\n `Failed to execute scroll: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n\n // Log fallback if used\n const resolvedBy = located?.resolvedBy || (located?.ref ? 'ref' : '');\n const fallbackUsed =\n resolvedBy && firstCandidateType && resolvedBy !== 'ref' && resolvedBy !== firstCandidateType;\n if (fallbackUsed) {\n logSelectorFallback(ctx, action.id, String(firstCandidateType), String(resolvedBy));\n }\n\n return { status: 'success' };\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/tabs.ts", "content": "/**\n * Tab Management Action Handlers\n *\n * Handles browser tab operations:\n * - openTab: Open a new tab or window\n * - switchTab: Switch to a different tab\n * - closeTab: Close tab(s)\n * - handleDownload: Monitor and capture download information\n */\n\nimport { failed, invalid, ok, tryResolveString } from '../registry';\nimport type { ActionHandler, DownloadInfo, DownloadState, VariableStore } from '../types';\n\n/** Default timeout for tab operations */\nconst DEFAULT_TAB_TIMEOUT_MS = 10000;\n\n/** Default timeout for download operations */\nconst DEFAULT_DOWNLOAD_TIMEOUT_MS = 60000;\n\n// ================================\n// openTab Handler\n// ================================\n\nexport const openTabHandler: ActionHandler<'openTab'> = {\n type: 'openTab',\n\n validate: () => ok(),\n\n describe: (action) => {\n const url = typeof action.params.url === 'string' ? action.params.url : undefined;\n const displayUrl = url ? (url.length > 30 ? url.slice(0, 30) + '...' : url) : 'blank';\n return action.params.newWindow ? `Open window: ${displayUrl}` : `Open tab: ${displayUrl}`;\n },\n\n run: async (ctx, action) => {\n const params = action.params;\n\n // Resolve URL if provided\n let url: string | undefined;\n if (params.url !== undefined) {\n const urlResult = tryResolveString(params.url, ctx.vars);\n if (!urlResult.ok) {\n return failed('VALIDATION_ERROR', `Failed to resolve URL: ${urlResult.error}`);\n }\n url = urlResult.value.trim() || undefined;\n }\n\n try {\n let tabId: number;\n\n if (params.newWindow) {\n // Create new window\n const window = await chrome.windows.create({\n url: url || 'about:blank',\n focused: true,\n });\n\n const tab = window?.tabs?.[0];\n if (!tab?.id) {\n return failed('TAB_NOT_FOUND', 'Failed to create new window');\n }\n tabId = tab.id;\n } else {\n // Create new tab in current window\n const tab = await chrome.tabs.create({\n url: url || 'about:blank',\n active: true,\n });\n\n if (!tab.id) {\n return failed('TAB_NOT_FOUND', 'Failed to create new tab');\n }\n tabId = tab.id;\n }\n\n // Wait for tab to be ready if URL was specified\n if (url) {\n await waitForTabComplete(tabId, DEFAULT_TAB_TIMEOUT_MS);\n }\n\n // Return newTabId for ctx.tabId sync\n return { status: 'success', newTabId: tabId };\n } catch (e) {\n return failed('UNKNOWN', `Failed to open tab: ${e instanceof Error ? e.message : String(e)}`);\n }\n },\n};\n\n// ================================\n// switchTab Handler\n// ================================\n\nexport const switchTabHandler: ActionHandler<'switchTab'> = {\n type: 'switchTab',\n\n validate: (action) => {\n const params = action.params;\n const hasTabId = params.tabId !== undefined;\n const hasUrlContains = params.urlContains !== undefined;\n const hasTitleContains = params.titleContains !== undefined;\n\n if (!hasTabId && !hasUrlContains && !hasTitleContains) {\n return invalid('switchTab requires tabId, urlContains, or titleContains');\n }\n\n return ok();\n },\n\n describe: (action) => {\n if (action.params.tabId !== undefined) {\n return `Switch to tab #${action.params.tabId}`;\n }\n if (action.params.urlContains !== undefined) {\n return `Switch tab (URL contains)`;\n }\n if (action.params.titleContains !== undefined) {\n return `Switch tab (title contains)`;\n }\n return 'Switch tab';\n },\n\n run: async (ctx, action) => {\n const params = action.params;\n\n try {\n let targetTabId: number | undefined;\n\n if (params.tabId !== undefined) {\n targetTabId = params.tabId;\n } else {\n // Find tab by URL or title\n const tabs = await chrome.tabs.query({});\n\n if (params.urlContains !== undefined) {\n const urlResult = tryResolveString(params.urlContains, ctx.vars);\n if (!urlResult.ok) {\n return failed('VALIDATION_ERROR', `Failed to resolve urlContains: ${urlResult.error}`);\n }\n const urlPattern = urlResult.value.trim().toLowerCase();\n\n // Empty pattern is invalid\n if (!urlPattern) {\n return failed('VALIDATION_ERROR', 'urlContains pattern cannot be empty');\n }\n\n const matchingTab = tabs.find(\n (tab) => tab.url && tab.url.toLowerCase().includes(urlPattern),\n );\n targetTabId = matchingTab?.id;\n } else if (params.titleContains !== undefined) {\n const titleResult = tryResolveString(params.titleContains, ctx.vars);\n if (!titleResult.ok) {\n return failed(\n 'VALIDATION_ERROR',\n `Failed to resolve titleContains: ${titleResult.error}`,\n );\n }\n const titlePattern = titleResult.value.trim().toLowerCase();\n\n // Empty pattern is invalid\n if (!titlePattern) {\n return failed('VALIDATION_ERROR', 'titleContains pattern cannot be empty');\n }\n\n const matchingTab = tabs.find(\n (tab) => tab.title && tab.title.toLowerCase().includes(titlePattern),\n );\n targetTabId = matchingTab?.id;\n }\n }\n\n if (targetTabId === undefined) {\n return failed('TAB_NOT_FOUND', 'No matching tab found');\n }\n\n // Activate the tab\n await chrome.tabs.update(targetTabId, { active: true });\n\n // Focus the window containing the tab\n const tab = await chrome.tabs.get(targetTabId);\n if (tab.windowId) {\n await chrome.windows.update(tab.windowId, { focused: true });\n }\n\n // Return newTabId for ctx.tabId sync\n return { status: 'success', newTabId: targetTabId };\n } catch (e) {\n return failed(\n 'UNKNOWN',\n `Failed to switch tab: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n },\n};\n\n// ================================\n// closeTab Handler\n// ================================\n\nexport const closeTabHandler: ActionHandler<'closeTab'> = {\n type: 'closeTab',\n\n validate: () => ok(),\n\n describe: (action) => {\n if (action.params.tabIds && action.params.tabIds.length > 0) {\n return `Close ${action.params.tabIds.length} tab(s)`;\n }\n if (action.params.url !== undefined) {\n return 'Close tab (by URL)';\n }\n return 'Close current tab';\n },\n\n run: async (ctx, action) => {\n const params = action.params;\n\n try {\n let tabIds: number[] = [];\n\n if (params.tabIds && params.tabIds.length > 0) {\n // Close specific tabs\n tabIds = [...params.tabIds];\n } else if (params.url !== undefined) {\n // Find and close tabs by URL\n const urlResult = tryResolveString(params.url, ctx.vars);\n if (!urlResult.ok) {\n return failed('VALIDATION_ERROR', `Failed to resolve URL: ${urlResult.error}`);\n }\n const urlPattern = urlResult.value.trim().toLowerCase();\n\n // Empty pattern is invalid\n if (!urlPattern) {\n return failed('VALIDATION_ERROR', 'URL pattern cannot be empty');\n }\n\n const tabs = await chrome.tabs.query({});\n tabIds = tabs\n .filter((tab) => tab.url && tab.url.toLowerCase().includes(urlPattern) && tab.id)\n .map((tab) => tab.id!);\n } else {\n // Close current tab\n if (typeof ctx.tabId === 'number') {\n tabIds = [ctx.tabId];\n }\n }\n\n if (tabIds.length === 0) {\n return failed('TAB_NOT_FOUND', 'No tabs to close');\n }\n\n await chrome.tabs.remove(tabIds);\n return { status: 'success' };\n } catch (e) {\n return failed(\n 'UNKNOWN',\n `Failed to close tab: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n },\n};\n\n// ================================\n// handleDownload Handler\n// ================================\n\nexport const handleDownloadHandler: ActionHandler<'handleDownload'> = {\n type: 'handleDownload',\n\n validate: () => ok(),\n\n describe: (action) => {\n if (action.params.filenameContains !== undefined) {\n return 'Handle download (by filename)';\n }\n return 'Handle download';\n },\n\n run: async (ctx, action) => {\n const params = action.params;\n const timeoutMs = action.policy?.timeout?.ms ?? DEFAULT_DOWNLOAD_TIMEOUT_MS;\n const waitForComplete = params.waitForComplete !== false;\n\n // Resolve filename pattern if provided\n let filenamePattern: string | undefined;\n if (params.filenameContains !== undefined) {\n const result = tryResolveString(params.filenameContains, ctx.vars);\n if (!result.ok) {\n return failed('VALIDATION_ERROR', `Failed to resolve filenameContains: ${result.error}`);\n }\n filenamePattern = result.value.toLowerCase();\n }\n\n return new Promise((resolve) => {\n const startTime = Date.now();\n let downloadId: number | undefined;\n let downloadInfo: DownloadInfo | undefined;\n let resolved = false;\n\n const cleanup = () => {\n chrome.downloads.onCreated.removeListener(onCreated);\n chrome.downloads.onChanged.removeListener(onChanged);\n };\n\n const finish = (result: Awaited['run']>>) => {\n if (!resolved) {\n resolved = true;\n cleanup();\n resolve(result);\n }\n };\n\n const onCreated = (item: chrome.downloads.DownloadItem) => {\n // Check if this download matches our criteria\n if (filenamePattern) {\n const filename = item.filename.toLowerCase();\n if (!filename.includes(filenamePattern)) return;\n }\n\n downloadId = item.id;\n downloadInfo = {\n id: String(item.id),\n filename: item.filename,\n url: item.url,\n state: item.state as DownloadState,\n size: item.totalBytes > 0 ? item.totalBytes : undefined,\n };\n\n if (!waitForComplete || item.state === 'complete') {\n storeAndFinish();\n }\n };\n\n const onChanged = (delta: chrome.downloads.DownloadDelta) => {\n if (delta.id !== downloadId) return;\n\n if (delta.state) {\n if (downloadInfo) {\n downloadInfo.state = delta.state.current as DownloadState;\n }\n\n if (delta.state.current === 'complete') {\n storeAndFinish();\n } else if (delta.state.current === 'interrupted') {\n finish(failed('DOWNLOAD_FAILED', 'Download was interrupted'));\n }\n }\n\n if (delta.filename && downloadInfo) {\n downloadInfo.filename = delta.filename.current || downloadInfo.filename;\n }\n\n if (delta.totalBytes && downloadInfo && delta.totalBytes.current) {\n downloadInfo.size = delta.totalBytes.current;\n }\n };\n\n const storeAndFinish = () => {\n if (params.saveAs && downloadInfo) {\n ctx.vars[params.saveAs] = downloadInfo as unknown as VariableStore[string];\n }\n finish({\n status: 'success',\n output: downloadInfo ? { download: downloadInfo } : undefined,\n });\n };\n\n // Set up listeners\n chrome.downloads.onCreated.addListener(onCreated);\n chrome.downloads.onChanged.addListener(onChanged);\n\n // Set up timeout\n const checkTimeout = () => {\n if (resolved) return;\n if (Date.now() - startTime > timeoutMs) {\n finish(failed('TIMEOUT', `Download timeout after ${timeoutMs}ms`));\n } else {\n setTimeout(checkTimeout, 500);\n }\n };\n setTimeout(checkTimeout, 500);\n });\n },\n};\n\n// ================================\n// Helper Functions\n// ================================\n\n/**\n * Wait for a tab to complete loading\n */\nasync function waitForTabComplete(tabId: number, timeoutMs: number): Promise {\n const startTime = Date.now();\n\n return new Promise((resolve, reject) => {\n const checkStatus = async () => {\n try {\n const tab = await chrome.tabs.get(tabId);\n\n if (tab.status === 'complete') {\n resolve();\n return;\n }\n\n if (Date.now() - startTime > timeoutMs) {\n reject(new Error(`Tab load timeout after ${timeoutMs}ms`));\n return;\n }\n\n setTimeout(checkStatus, 100);\n } catch (e) {\n reject(e);\n }\n };\n\n checkStatus();\n });\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/handlers/wait.ts", "content": "/**\n * Wait Action Handler\n *\n * Handles various wait conditions:\n * - Sleep (fixed delay)\n * - Network idle\n * - Navigation complete\n * - Text appears/disappears\n * - Selector visible/hidden\n */\n\nimport { ENGINE_CONSTANTS } from '../../engine/constants';\nimport { waitForNavigation, waitForNetworkIdle } from '../../rr-utils';\nimport { failed, invalid, ok, tryResolveNumber } from '../registry';\nimport type { ActionHandler } from '../types';\nimport { clampInt, resolveString, sendMessageToTab } from './common';\n\nexport const waitHandler: ActionHandler<'wait'> = {\n type: 'wait',\n\n validate: (action) => {\n const condition = action.params.condition;\n if (!condition || typeof condition !== 'object') {\n return invalid('Missing condition parameter');\n }\n if (!('kind' in condition)) {\n return invalid('Condition must have a kind property');\n }\n return ok();\n },\n\n describe: (action) => {\n const condition = action.params.condition;\n if (!condition) return 'Wait';\n\n switch (condition.kind) {\n case 'sleep': {\n const ms = typeof condition.sleep === 'number' ? condition.sleep : '(dynamic)';\n return `Wait ${ms}ms`;\n }\n case 'networkIdle':\n return 'Wait for network idle';\n case 'navigation':\n return 'Wait for navigation';\n case 'text': {\n const appear = condition.appear !== false;\n const text = typeof condition.text === 'string' ? condition.text : '(dynamic)';\n const displayText = text.length > 20 ? text.slice(0, 20) + '...' : text;\n return `Wait for text \"${displayText}\" to ${appear ? 'appear' : 'disappear'}`;\n }\n case 'selector': {\n const visible = condition.visible !== false;\n return `Wait for selector to be ${visible ? 'visible' : 'hidden'}`;\n }\n default:\n return 'Wait';\n }\n },\n\n run: async (ctx, action) => {\n const vars = ctx.vars;\n const tabId = ctx.tabId;\n\n if (typeof tabId !== 'number') {\n return failed('TAB_NOT_FOUND', 'No active tab found');\n }\n\n const timeoutMs = action.policy?.timeout?.ms;\n const frameIds = typeof ctx.frameId === 'number' ? [ctx.frameId] : undefined;\n const condition = action.params.condition;\n\n // Handle sleep condition\n if (condition.kind === 'sleep') {\n const msResolved = tryResolveNumber(condition.sleep, vars);\n if (!msResolved.ok) {\n return failed('VALIDATION_ERROR', msResolved.error);\n }\n const ms = Math.max(0, Number(msResolved.value ?? 0));\n await new Promise((resolve) => setTimeout(resolve, ms));\n return { status: 'success' };\n }\n\n // Handle network idle condition\n if (condition.kind === 'networkIdle') {\n const totalMs = clampInt(timeoutMs ?? 5000, 1000, ENGINE_CONSTANTS.MAX_WAIT_MS);\n let idleMs: number;\n\n if (condition.idleMs !== undefined) {\n const idleResolved = tryResolveNumber(condition.idleMs, vars);\n idleMs = idleResolved.ok\n ? clampInt(idleResolved.value, 200, 5000)\n : Math.min(1500, Math.max(500, Math.floor(totalMs / 3)));\n } else {\n idleMs = Math.min(1500, Math.max(500, Math.floor(totalMs / 3)));\n }\n\n await waitForNetworkIdle(totalMs, idleMs);\n return { status: 'success' };\n }\n\n // Handle navigation condition\n if (condition.kind === 'navigation') {\n const timeout = timeoutMs === undefined ? undefined : Math.max(0, Number(timeoutMs));\n await waitForNavigation(timeout);\n return { status: 'success' };\n }\n\n // Handle text condition\n if (condition.kind === 'text') {\n const textResolved = resolveString(condition.text, vars);\n if (!textResolved.ok) {\n return failed('VALIDATION_ERROR', textResolved.error);\n }\n\n const appear = condition.appear !== false;\n const timeout = clampInt(timeoutMs ?? 10000, 0, ENGINE_CONSTANTS.MAX_WAIT_MS);\n\n // Inject wait helper script\n try {\n await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n files: ['inject-scripts/wait-helper.js'],\n world: 'ISOLATED',\n });\n } catch (e) {\n return failed('SCRIPT_FAILED', `Failed to inject wait helper: ${(e as Error).message}`);\n }\n\n // Execute wait for text\n const response = await sendMessageToTab<{ success?: boolean }>(\n tabId,\n { action: 'waitForText', text: textResolved.value, appear, timeout },\n ctx.frameId,\n );\n\n if (!response.ok) {\n return failed('TIMEOUT', `Wait for text failed: ${response.error}`);\n }\n if (response.value?.success !== true) {\n return failed(\n 'TIMEOUT',\n `Text \"${textResolved.value}\" did not ${appear ? 'appear' : 'disappear'} within timeout`,\n );\n }\n\n return { status: 'success' };\n }\n\n // Handle selector condition\n if (condition.kind === 'selector') {\n const selectorResolved = resolveString(condition.selector, vars);\n if (!selectorResolved.ok) {\n return failed('VALIDATION_ERROR', selectorResolved.error);\n }\n\n const visible = condition.visible !== false;\n const timeout = clampInt(timeoutMs ?? 10000, 0, ENGINE_CONSTANTS.MAX_WAIT_MS);\n\n // Inject wait helper script\n try {\n await chrome.scripting.executeScript({\n target: { tabId, frameIds } as chrome.scripting.InjectionTarget,\n files: ['inject-scripts/wait-helper.js'],\n world: 'ISOLATED',\n });\n } catch (e) {\n return failed('SCRIPT_FAILED', `Failed to inject wait helper: ${(e as Error).message}`);\n }\n\n // Execute wait for selector\n const response = await sendMessageToTab<{ success?: boolean }>(\n tabId,\n { action: 'waitForSelector', selector: selectorResolved.value, visible, timeout },\n ctx.frameId,\n );\n\n if (!response.ok) {\n return failed('TIMEOUT', `Wait for selector failed: ${response.error}`);\n }\n if (response.value?.success !== true) {\n return failed(\n 'TIMEOUT',\n `Selector \"${selectorResolved.value}\" did not become ${visible ? 'visible' : 'hidden'} within timeout`,\n );\n }\n\n return { status: 'success' };\n }\n\n return failed(\n 'VALIDATION_ERROR',\n `Unsupported wait condition kind: ${(condition as { kind: string }).kind}`,\n );\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/index.ts", "content": "/**\n * Action System - 导出模块\n */\n\n// 类型导出\nexport * from './types';\n\n// 注册表导出\nexport {\n ActionRegistry,\n createActionRegistry,\n ok,\n invalid,\n failed,\n tryResolveString,\n tryResolveNumber,\n tryResolveJson,\n tryResolveValue,\n type BeforeExecuteArgs,\n type BeforeExecuteHook,\n type AfterExecuteArgs,\n type AfterExecuteHook,\n type ActionRegistryHooks,\n} from './registry';\n\n// 适配器导出\nexport {\n execCtxToActionCtx,\n stepToAction,\n actionResultToExecResult,\n createStepExecutor,\n isActionSupported,\n getActionType,\n type StepExecutionAttempt,\n} from './adapter';\n\n// Handler 工厂导出\nexport {\n createReplayActionRegistry,\n registerReplayHandlers,\n getSupportedActionTypes,\n isActionTypeSupported,\n} from './handlers';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/registry.ts", "content": "/**\n * Action Registry - Action 执行器注册表和执行管道\n *\n * 特性：\n * - 动态注册/注销 handler\n * - 中间件/钩子机制 (beforeExecute, afterExecute)\n * - 重试和超时策略\n * - 类型安全\n */\n\nimport type {\n Action,\n ActionError,\n ActionErrorCode,\n ActionExecutionContext,\n ActionExecutionResult,\n ActionHandler,\n EdgeLabel,\n ElementTarget,\n ExecutableAction,\n ExecutableActionType,\n FrameTarget,\n JsonValue,\n NonEmptyArray,\n Resolvable,\n RetryPolicy,\n SelectorCandidate,\n TimeoutPolicy,\n ValidationResult,\n VariablePathSegment,\n VariablePointer,\n VariableStore,\n} from './types';\n\n// ================================\n// 类型定义\n// ================================\n\ntype AnyExecutableAction = {\n [T in ExecutableActionType]: ExecutableAction;\n}[ExecutableActionType];\ntype AnyExecutableHandler = { [T in ExecutableActionType]: ActionHandler }[ExecutableActionType];\n\nexport interface BeforeExecuteArgs {\n ctx: ActionExecutionContext;\n action: ExecutableAction;\n handler: ActionHandler;\n attempt: number;\n}\n\nexport type BeforeExecuteHook = (\n args: BeforeExecuteArgs,\n) => void | ActionExecutionResult | Promise>;\n\nexport interface AfterExecuteArgs {\n ctx: ActionExecutionContext;\n action: ExecutableAction;\n handler: ActionHandler;\n result: ActionExecutionResult;\n attempt: number;\n}\n\nexport type AfterExecuteHook = (\n args: AfterExecuteArgs,\n) => void | ActionExecutionResult | Promise>;\n\nexport interface ActionRegistryHooks {\n beforeExecute?: BeforeExecuteHook;\n afterExecute?: AfterExecuteHook;\n}\n\n// ================================\n// 工具函数\n// ================================\n\nfunction isRecord(value: unknown): value is Record {\n return typeof value === 'object' && value !== null;\n}\n\nfunction toNonEmptyArray(value: string[], fallback: string): NonEmptyArray {\n return (value.length > 0 ? value : [fallback]) as NonEmptyArray;\n}\n\nconst ACTION_ERROR_CODES: ReadonlyArray = [\n 'VALIDATION_ERROR',\n 'TIMEOUT',\n 'TAB_NOT_FOUND',\n 'FRAME_NOT_FOUND',\n 'TARGET_NOT_FOUND',\n 'ELEMENT_NOT_VISIBLE',\n 'NAVIGATION_FAILED',\n 'NETWORK_REQUEST_FAILED',\n 'DOWNLOAD_FAILED',\n 'ASSERTION_FAILED',\n 'SCRIPT_FAILED',\n 'UNKNOWN',\n] as const;\n\nfunction isActionErrorCode(value: unknown): value is ActionErrorCode {\n return typeof value === 'string' && (ACTION_ERROR_CODES as ReadonlyArray).includes(value);\n}\n\nfunction toErrorMessage(e: unknown): string {\n if (e instanceof Error) return e.message;\n if (typeof e === 'string') return e;\n if (isRecord(e) && typeof e.message === 'string') return e.message;\n return 'Unknown error';\n}\n\nfunction toActionError(e: unknown, fallbackCode: ActionErrorCode = 'UNKNOWN'): ActionError {\n if (isRecord(e) && isActionErrorCode(e.code) && typeof e.message === 'string') {\n return { code: e.code, message: e.message, data: undefined };\n }\n return { code: fallbackCode, message: toErrorMessage(e) };\n}\n\nexport function ok(): ValidationResult {\n return { ok: true };\n}\n\nexport function invalid(...errors: string[]): ValidationResult {\n return { ok: false, errors: toNonEmptyArray(errors.filter(Boolean), 'Validation failed') };\n}\n\nexport function failed(\n code: ActionErrorCode,\n message: string,\n): ActionExecutionResult {\n return { status: 'failed', error: { code, message } };\n}\n\nfunction sleep(ms: number): Promise {\n const safe = Math.max(0, Math.floor(ms));\n return new Promise((resolve) => setTimeout(resolve, safe));\n}\n\n// ================================\n// Resolvable 解析器\n// ================================\n\nfunction isVariablePointer(value: unknown): value is VariablePointer {\n if (!isRecord(value)) return false;\n if (typeof value.name !== 'string' || value.name.length === 0) return false;\n if (value.path === undefined) return true;\n if (!Array.isArray(value.path)) return false;\n return value.path.every((s) => typeof s === 'string' || typeof s === 'number');\n}\n\nfunction isVarValue(\n value: unknown,\n): value is { kind: 'var'; ref: VariablePointer; default?: unknown } {\n if (!isRecord(value)) return false;\n if (value.kind !== 'var') return false;\n return isVariablePointer(value.ref);\n}\n\nfunction isExprValue(value: unknown): value is { kind: 'expr'; default?: unknown } {\n if (!isRecord(value)) return false;\n if (value.kind !== 'expr') return false;\n return 'expr' in value;\n}\n\nfunction isStringTemplate(value: unknown): value is { kind: 'template'; parts: unknown[] } {\n if (!isRecord(value)) return false;\n if (value.kind !== 'template') return false;\n return Array.isArray(value.parts) && value.parts.length > 0;\n}\n\nfunction readByPath(\n value: JsonValue,\n path?: ReadonlyArray,\n): JsonValue | undefined {\n if (!path || path.length === 0) return value;\n let cur: JsonValue | undefined = value;\n for (const seg of path) {\n if (cur === undefined || cur === null) return undefined;\n if (typeof seg === 'number') {\n if (!Array.isArray(cur)) return undefined;\n cur = cur[seg] as JsonValue | undefined;\n continue;\n }\n if (typeof seg === 'string') {\n if (!isRecord(cur)) return undefined;\n cur = (cur as Record)[seg] as JsonValue | undefined;\n continue;\n }\n return undefined;\n }\n return cur;\n}\n\nexport function tryResolveJson(\n value: Resolvable,\n vars: VariableStore,\n): { ok: true; value: JsonValue } | { ok: false; error: string } {\n if (isVarValue(value)) {\n const ref = value.ref;\n const root = vars[ref.name];\n const resolved = root === undefined ? undefined : readByPath(root, ref.path);\n if (resolved !== undefined) return { ok: true, value: resolved };\n if ('default' in value) return { ok: true, value: (value.default ?? null) as JsonValue };\n return { ok: true, value: null };\n }\n if (isExprValue(value)) {\n if ('default' in value) return { ok: true, value: (value.default ?? null) as JsonValue };\n return { ok: false, error: 'Expression value is not supported by the default resolver' };\n }\n return { ok: true, value };\n}\n\nfunction formatInserted(value: JsonValue, format?: 'text' | 'json' | 'urlEncoded'): string {\n if (format === 'json') return JSON.stringify(value);\n const text = value === null ? '' : typeof value === 'string' ? value : String(value);\n if (format === 'urlEncoded') return encodeURIComponent(text);\n return text;\n}\n\nexport function tryResolveString(\n value: Resolvable,\n vars: VariableStore,\n): { ok: true; value: string } | { ok: false; error: string } {\n if (typeof value === 'string') return { ok: true, value };\n if (isVarValue(value)) {\n const ref = value.ref;\n const root = vars[ref.name];\n const resolved = root === undefined ? undefined : readByPath(root, ref.path);\n if (resolved !== undefined && resolved !== null) return { ok: true, value: String(resolved) };\n if ('default' in value && typeof value.default === 'string')\n return { ok: true, value: value.default };\n return { ok: true, value: '' };\n }\n if (isStringTemplate(value)) {\n const parts = value.parts;\n let out = '';\n for (const p of parts) {\n if (!isRecord(p) || typeof p.kind !== 'string')\n return { ok: false, error: 'Invalid template part' };\n if (p.kind === 'text') {\n if (typeof p.value !== 'string') return { ok: false, error: 'Invalid template text part' };\n out += p.value;\n continue;\n }\n if (p.kind === 'insert') {\n const resolved = tryResolveJson(p.value as Resolvable, vars);\n if (!resolved.ok) return { ok: false, error: resolved.error };\n out += formatInserted(\n resolved.value,\n (p.format as 'text' | 'json' | 'urlEncoded' | undefined) ?? 'text',\n );\n continue;\n }\n return {\n ok: false,\n error: `Unknown template part kind: ${String((p as { kind: string }).kind)}`,\n };\n }\n return { ok: true, value: out };\n }\n if (isExprValue(value)) {\n if ('default' in value && typeof value.default === 'string')\n return { ok: true, value: value.default };\n return { ok: false, error: 'Expression value is not supported by the default resolver' };\n }\n return { ok: false, error: 'Unsupported resolvable string value' };\n}\n\nexport function tryResolveNumber(\n value: Resolvable,\n vars: VariableStore,\n): { ok: true; value: number } | { ok: false; error: string } {\n if (typeof value === 'number' && Number.isFinite(value)) return { ok: true, value };\n if (isVarValue(value)) {\n const ref = value.ref;\n const root = vars[ref.name];\n const resolved = root === undefined ? undefined : readByPath(root, ref.path);\n if (typeof resolved === 'number' && Number.isFinite(resolved))\n return { ok: true, value: resolved };\n if (typeof resolved === 'string' && resolved.trim() !== '') {\n const n = Number(resolved);\n if (Number.isFinite(n)) return { ok: true, value: n };\n }\n if ('default' in value && typeof value.default === 'number' && Number.isFinite(value.default))\n return { ok: true, value: value.default };\n return { ok: false, error: `Variable \"${ref.name}\" is not a finite number` };\n }\n if (isExprValue(value)) {\n if ('default' in value && typeof value.default === 'number' && Number.isFinite(value.default))\n return { ok: true, value: value.default };\n return { ok: false, error: 'Expression value is not supported by the default resolver' };\n }\n return { ok: false, error: 'Unsupported resolvable number value' };\n}\n\n/**\n * Resolve a generic JSON value (alias for tryResolveJson)\n * Useful for script/http handlers that work with arbitrary JSON\n */\nexport const tryResolveValue = tryResolveJson;\n\n// ================================\n// 重试和超时逻辑\n// ================================\n\nfunction shouldRetry(policy: RetryPolicy | undefined, error: ActionError | undefined): boolean {\n if (!policy) return false;\n if (policy.retries <= 0) return false;\n if (!error) return false;\n if (error.code === 'VALIDATION_ERROR') return false;\n if (policy.retryOn && policy.retryOn.length > 0) return policy.retryOn.includes(error.code);\n return true;\n}\n\nfunction computeRetryDelayMs(policy: RetryPolicy, retryIndex: number): number {\n const base = Math.max(0, Math.floor(policy.intervalMs));\n const backoff = policy.backoff ?? 'none';\n\n let delay = base;\n if (backoff === 'linear') delay = base * (retryIndex + 1);\n if (backoff === 'exp') delay = base * Math.pow(2, retryIndex);\n\n const capped =\n policy.maxIntervalMs !== undefined ? Math.min(delay, Math.max(0, policy.maxIntervalMs)) : delay;\n if ((policy.jitter ?? 'none') === 'full') return Math.floor(Math.random() * capped);\n return capped;\n}\n\nasync function runWithTimeout(\n run: () => Promise,\n timeoutMs: number | undefined,\n): Promise<{ ok: true; value: T } | { ok: false; error: ActionError }> {\n if (timeoutMs === undefined) {\n try {\n return { ok: true, value: await run() };\n } catch (e) {\n return { ok: false, error: toActionError(e) };\n }\n }\n\n const ms = Math.max(0, Math.floor(timeoutMs));\n if (ms === 0) return { ok: false, error: { code: 'TIMEOUT', message: 'Timeout reached' } };\n\n return await new Promise((resolve) => {\n const timer: ReturnType = setTimeout(() => {\n resolve({ ok: false, error: { code: 'TIMEOUT', message: 'Timeout reached' } });\n }, ms);\n\n run()\n .then((value) => {\n clearTimeout(timer);\n resolve({ ok: true, value });\n })\n .catch((e) => {\n clearTimeout(timer);\n resolve({ ok: false, error: toActionError(e) });\n });\n });\n}\n\n// ================================\n// ActionRegistry 类\n// ================================\n\nexport class ActionRegistry {\n private readonly handlers: { [T in ExecutableActionType]?: ActionHandler } = {};\n private readonly beforeHooks: BeforeExecuteHook[] = [];\n private readonly afterHooks: AfterExecuteHook[] = [];\n\n /**\n * 注册 action handler\n */\n register(\n handler: ActionHandler,\n options?: { override?: boolean },\n ): void {\n const override = options?.override !== false;\n const existing = this.handlers[handler.type];\n if (existing && !override) {\n throw new Error(`Handler already registered for type: ${handler.type}`);\n }\n // Type assertion needed due to TypeScript mapped type limitation\n\n (this.handlers as Record>)[handler.type] = handler;\n }\n\n /**\n * 注销 action handler\n */\n unregister(type: T): boolean {\n const exists = this.handlers[type] !== undefined;\n delete this.handlers[type];\n return exists;\n }\n\n /**\n * 获取 handler\n */\n get(type: T): ActionHandler | undefined {\n return this.handlers[type];\n }\n\n /**\n * 检查是否存在 handler\n */\n has(type: ExecutableActionType): boolean {\n return this.handlers[type] !== undefined;\n }\n\n /**\n * 列出所有已注册的 handler\n */\n list(): ReadonlyArray {\n const arr = Object.values(this.handlers).filter(\n (h): h is AnyExecutableHandler => h !== undefined,\n );\n return arr;\n }\n\n /**\n * 注册 beforeExecute 钩子\n */\n onBeforeExecute(hook: BeforeExecuteHook): () => void {\n this.beforeHooks.push(hook);\n return () => {\n const idx = this.beforeHooks.indexOf(hook);\n if (idx >= 0) this.beforeHooks.splice(idx, 1);\n };\n }\n\n /**\n * 注册 afterExecute 钩子\n */\n onAfterExecute(hook: AfterExecuteHook): () => void {\n this.afterHooks.push(hook);\n return () => {\n const idx = this.afterHooks.indexOf(hook);\n if (idx >= 0) this.afterHooks.splice(idx, 1);\n };\n }\n\n /**\n * 批量注册钩子\n */\n use(hooks: ActionRegistryHooks): () => void {\n const disposers: Array<() => void> = [];\n if (hooks.beforeExecute) disposers.push(this.onBeforeExecute(hooks.beforeExecute));\n if (hooks.afterExecute) disposers.push(this.onAfterExecute(hooks.afterExecute));\n return () => {\n for (const d of disposers) d();\n };\n }\n\n /**\n * 验证 action 配置\n */\n validate(action: ExecutableAction): ValidationResult {\n const handler = this.get(action.type);\n if (!handler) return invalid(`Unsupported action type: ${String(action.type)}`);\n if (!handler.validate) return ok();\n return handler.validate(action);\n }\n\n /**\n * 执行 action\n */\n async execute(\n ctx: ActionExecutionContext,\n action: ExecutableAction,\n ): Promise> {\n const startedAt = Date.now();\n\n // 跳过禁用的 action\n if (action.disabled) {\n return { status: 'skipped', durationMs: Date.now() - startedAt };\n }\n\n // 获取 handler\n const handler = this.get(action.type);\n if (!handler) {\n return {\n status: 'failed',\n error: {\n code: 'VALIDATION_ERROR',\n message: `Unsupported action type: ${String(action.type)}`,\n },\n durationMs: Date.now() - startedAt,\n };\n }\n\n // 验证\n const v = this.validate(action);\n if (!v.ok) {\n let result: ActionExecutionResult = {\n status: 'failed',\n error: { code: 'VALIDATION_ERROR', message: v.errors.join(', ') },\n };\n\n // 调用 afterExecute 钩子\n for (const hook of this.afterHooks) {\n try {\n const maybe = await hook({ ctx, action, handler, result, attempt: 0 });\n if (maybe) result = maybe;\n } catch (e) {\n try {\n ctx.log(`afterExecute hook failed: ${toErrorMessage(e)}`, 'warn');\n } catch {\n // ignore\n }\n }\n }\n\n result.durationMs = Date.now() - startedAt;\n return result;\n }\n\n // 计算重试和超时参数\n const retryPolicy = action.policy?.retry;\n const timeoutPolicy = action.policy?.timeout;\n const maxAttempts = 1 + Math.max(0, Math.floor(retryPolicy?.retries ?? 0));\n\n const actionDeadline =\n timeoutPolicy && timeoutPolicy.ms > 0 && (timeoutPolicy.scope ?? 'attempt') === 'action'\n ? startedAt + timeoutPolicy.ms\n : undefined;\n\n const remainingActionMs = () =>\n actionDeadline === undefined ? undefined : Math.max(0, actionDeadline - Date.now());\n\n let last: ActionExecutionResult | undefined;\n\n // 执行循环（支持重试）\n for (let attempt = 0; attempt < maxAttempts; attempt++) {\n const attemptTimeoutMs: number | undefined = (() => {\n if (!timeoutPolicy || timeoutPolicy.ms <= 0) return undefined;\n const scope = timeoutPolicy.scope ?? 'attempt';\n if (scope === 'attempt') return timeoutPolicy.ms;\n return remainingActionMs();\n })();\n\n if (attemptTimeoutMs !== undefined && attemptTimeoutMs <= 0) {\n last = failed('TIMEOUT', 'Timeout reached');\n break;\n }\n\n // beforeExecute 钩子（可以短路）\n let shortCircuited: ActionExecutionResult | undefined;\n for (const hook of this.beforeHooks) {\n try {\n const maybe = await hook({ ctx, action, handler, attempt });\n if (maybe) {\n shortCircuited = maybe;\n break;\n }\n } catch (e) {\n try {\n ctx.log(`beforeExecute hook failed: ${toErrorMessage(e)}`, 'warn');\n } catch {\n // ignore\n }\n }\n }\n\n // 执行 handler\n const runOutcome =\n shortCircuited ??\n (await (async () => {\n const out = await runWithTimeout(() => handler.run(ctx, action), attemptTimeoutMs);\n if (!out.ok) return failed(out.error.code, out.error.message);\n\n const result = out.value ?? ({} as ActionExecutionResult);\n if (result.status === 'failed' && !result.error) {\n return { ...result, error: { code: 'UNKNOWN' as const, message: 'Action failed' } };\n }\n return result;\n })());\n\n let result: ActionExecutionResult = runOutcome;\n\n // afterExecute 钩子（可以替换结果）\n for (const hook of this.afterHooks) {\n try {\n const maybe = await hook({ ctx, action, handler, result, attempt });\n if (maybe) result = maybe;\n } catch (e) {\n try {\n ctx.log(`afterExecute hook failed: ${toErrorMessage(e)}`, 'warn');\n } catch {\n // ignore\n }\n }\n }\n\n last = result;\n\n // 成功则退出\n if (result.status !== 'failed') break;\n\n // 判断是否重试\n const canRetry = attempt < maxAttempts - 1 && shouldRetry(retryPolicy, result.error);\n if (!canRetry) break;\n\n const delay = computeRetryDelayMs(retryPolicy!, attempt);\n if (\n actionDeadline !== undefined &&\n remainingActionMs() !== undefined &&\n (remainingActionMs() as number) < delay\n ) {\n break;\n }\n\n try {\n ctx.log(`Retrying action \"${action.type}\" (attempt ${attempt + 1}/${maxAttempts})`, 'warn');\n } catch {\n // ignore\n }\n\n if (delay > 0) await sleep(delay);\n }\n\n const finalResult: ActionExecutionResult =\n last ??\n ({\n status: 'failed',\n error: { code: 'UNKNOWN', message: 'Action execution produced no result' },\n } as ActionExecutionResult);\n\n finalResult.durationMs = Date.now() - startedAt;\n return finalResult;\n }\n}\n\n// ================================\n// 导出工厂函数\n// ================================\n\n/**\n * 创建默认的 ActionRegistry 实例\n */\nexport function createActionRegistry(): ActionRegistry {\n return new ActionRegistry();\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/actions/types.ts", "content": "/**\n * Action Type System for Record & Replay\n * 商业级录制回放的核心类型定义\n *\n * 设计原则：\n * - 类型安全，无 any\n * - 支持所有操作类型\n * - 支持重试、超时、错误处理策略\n * - 支持选择器候选列表和稳定性评分\n * - 支持变量系统\n * - 符合 SOLID 原则（接口可通过声明合并扩展）\n */\n\n// ================================\n// 基础类型\n// ================================\n\nexport type Milliseconds = number;\nexport type ISODateTimeString = string;\nexport type NonEmptyArray = [T, ...T[]];\n\n// JSON 类型\nexport type JsonPrimitive = string | number | boolean | null;\nexport type JsonValue = JsonPrimitive | JsonObject | JsonArray;\nexport interface JsonObject {\n [key: string]: JsonValue;\n}\nexport type JsonArray = JsonValue[];\n\n// ID 类型\nexport type FlowId = string;\nexport type ActionId = string;\nexport type SubflowId = string;\nexport type EdgeId = string;\nexport type VariableName = string;\n\n// ================================\n// Edge Labels\n// ================================\n\nexport const EDGE_LABELS = {\n DEFAULT: 'default',\n TRUE: 'true',\n FALSE: 'false',\n ON_ERROR: 'onError',\n} as const;\n\nexport type BuiltinEdgeLabel = (typeof EDGE_LABELS)[keyof typeof EDGE_LABELS];\nexport type EdgeLabel = string;\n\n// ================================\n// 错误处理\n// ================================\n\nexport type ActionErrorCode =\n | 'VALIDATION_ERROR'\n | 'TIMEOUT'\n | 'TAB_NOT_FOUND'\n | 'FRAME_NOT_FOUND'\n | 'TARGET_NOT_FOUND'\n | 'ELEMENT_NOT_VISIBLE'\n | 'NAVIGATION_FAILED'\n | 'NETWORK_REQUEST_FAILED'\n | 'DOWNLOAD_FAILED'\n | 'ASSERTION_FAILED'\n | 'SCRIPT_FAILED'\n | 'UNKNOWN';\n\nexport interface ActionError {\n code: ActionErrorCode;\n message: string;\n data?: JsonValue;\n}\n\n// ================================\n// 执行策略\n// ================================\n\nexport interface TimeoutPolicy {\n ms: Milliseconds;\n /** 'attempt' = 每次尝试独立计时, 'action' = 整个 action 总计时 */\n scope?: 'attempt' | 'action';\n}\n\nexport type BackoffKind = 'none' | 'exp' | 'linear';\n\nexport interface RetryPolicy {\n /** 重试次数（不含首次尝试） */\n retries: number;\n /** 重试间隔 */\n intervalMs: Milliseconds;\n /** 退避策略 */\n backoff?: BackoffKind;\n /** 最大间隔（用于 exp/linear） */\n maxIntervalMs?: Milliseconds;\n /** 抖动策略 */\n jitter?: 'none' | 'full';\n /** 仅在这些错误码时重试 */\n retryOn?: ReadonlyArray;\n}\n\nexport type ErrorHandlingStrategy =\n | { kind: 'stop' }\n | { kind: 'continue'; level?: 'warning' | 'error' }\n | { kind: 'goto'; label: EdgeLabel };\n\nexport interface ArtifactCapturePolicy {\n screenshot?: 'never' | 'onFailure' | 'always';\n saveScreenshotAs?: VariableName;\n includeConsole?: boolean;\n includeNetwork?: boolean;\n}\n\nexport interface ActionPolicy {\n timeout?: TimeoutPolicy;\n retry?: RetryPolicy;\n onError?: ErrorHandlingStrategy;\n artifacts?: ArtifactCapturePolicy;\n}\n\n// ================================\n// 变量系统\n// ================================\n\nexport interface VariableDefinitionBase {\n name: VariableName;\n label?: string;\n description?: string;\n sensitive?: boolean;\n required?: boolean;\n}\n\nexport interface VariableStringRules {\n pattern?: string;\n minLength?: number;\n maxLength?: number;\n}\n\nexport interface VariableNumberRules {\n min?: number;\n max?: number;\n integer?: boolean;\n}\n\nexport type VariableDefinition =\n | (VariableDefinitionBase & {\n kind: 'string';\n default?: string;\n rules?: VariableStringRules;\n })\n | (VariableDefinitionBase & {\n kind: 'number';\n default?: number;\n rules?: VariableNumberRules;\n })\n | (VariableDefinitionBase & {\n kind: 'boolean';\n default?: boolean;\n })\n | (VariableDefinitionBase & {\n kind: 'enum';\n options: NonEmptyArray;\n default?: string;\n })\n | (VariableDefinitionBase & {\n kind: 'array';\n item: 'string' | 'number' | 'boolean' | 'json';\n default?: JsonValue[];\n })\n | (VariableDefinitionBase & {\n kind: 'json';\n default?: JsonValue;\n });\n\nexport type VariableStore = Record;\n\nexport type VariableScope = 'flow' | 'run' | 'env' | 'secret';\nexport type VariablePathSegment = string | number;\n\nexport interface VariablePointer {\n scope?: VariableScope;\n name: VariableName;\n path?: ReadonlyArray;\n}\n\n// ================================\n// 表达式和模板\n// ================================\n\nexport type ExpressionLanguage = 'js' | 'rr';\n\nexport interface Expression<_T = JsonValue> {\n language: ExpressionLanguage;\n code: string;\n}\n\nexport interface VariableValue {\n kind: 'var';\n ref: VariablePointer;\n default?: T;\n}\n\nexport interface ExpressionValue {\n kind: 'expr';\n expr: Expression;\n default?: T;\n}\n\nexport type TemplateFormat = 'text' | 'json' | 'urlEncoded';\n\nexport type TemplatePart =\n | { kind: 'text'; value: string }\n | { kind: 'insert'; value: Resolvable; format?: TemplateFormat };\n\nexport interface StringTemplate {\n kind: 'template';\n parts: NonEmptyArray;\n}\n\nexport type Resolvable =\n | T\n | VariableValue\n | ExpressionValue\n | ([T] extends [string] ? StringTemplate : never);\n\nexport type DataPath = string; // dot/bracket path: e.g. \"data.items[0].id\"\nexport type Assignments = Record;\n\n// ================================\n// 条件表达式\n// ================================\n\nexport type CompareOp =\n | 'eq'\n | 'eqi'\n | 'neq'\n | 'gt'\n | 'gte'\n | 'lt'\n | 'lte'\n | 'contains'\n | 'containsI'\n | 'notContains'\n | 'notContainsI'\n | 'startsWith'\n | 'endsWith'\n | 'regex';\n\nexport type Condition =\n | { kind: 'expr'; expr: Expression }\n | {\n kind: 'compare';\n left: Resolvable;\n op: CompareOp;\n right: Resolvable;\n }\n | { kind: 'truthy'; value: Resolvable }\n | { kind: 'falsy'; value: Resolvable }\n | { kind: 'not'; condition: Condition }\n | { kind: 'and'; conditions: NonEmptyArray }\n | { kind: 'or'; conditions: NonEmptyArray };\n\n// ================================\n// 选择器系统\n// ================================\n\nexport type SelectorCandidateSource = 'recorded' | 'user' | 'generated';\n\nexport interface SelectorStability {\n /** 稳定性评分 0-1 */\n score: number;\n signals?: {\n usesId?: boolean;\n usesAria?: boolean;\n usesText?: boolean;\n usesNthOfType?: boolean;\n usesAttributes?: boolean;\n usesClass?: boolean;\n };\n note?: string;\n}\n\nexport interface SelectorCandidateBase {\n weight?: number;\n stability?: SelectorStability;\n source?: SelectorCandidateSource;\n}\n\nexport type SelectorCandidate =\n | (SelectorCandidateBase & { type: 'css'; selector: Resolvable })\n | (SelectorCandidateBase & { type: 'xpath'; xpath: Resolvable })\n | (SelectorCandidateBase & { type: 'attr'; selector: Resolvable })\n | (SelectorCandidateBase & {\n type: 'aria';\n role?: Resolvable;\n name?: Resolvable;\n })\n | (SelectorCandidateBase & {\n type: 'text';\n text: Resolvable;\n tagNameHint?: string;\n match?: 'exact' | 'contains';\n });\n\nexport type FrameTarget =\n | { kind: 'top' }\n | { kind: 'index'; index: Resolvable }\n | { kind: 'urlContains'; value: Resolvable };\n\nexport interface TargetHint {\n tagName?: string;\n role?: string;\n name?: string;\n text?: string;\n}\n\nexport interface ElementTargetBase {\n frame?: FrameTarget;\n hint?: TargetHint;\n}\n\nexport type ElementTarget =\n | (ElementTargetBase & {\n /** 临时引用（快速路径） */\n ref: string;\n candidates?: ReadonlyArray;\n })\n | (ElementTargetBase & {\n ref?: string;\n candidates: NonEmptyArray;\n });\n\n// ================================\n// Action 参数定义\n// ================================\n\nexport type BrowserWorld = 'MAIN' | 'ISOLATED';\n\n// --- 页面交互 ---\n\nexport interface ClickParams {\n target: ElementTarget;\n button?: 'left' | 'middle' | 'right';\n before?: { scrollIntoView?: boolean; waitForSelector?: boolean };\n after?: { waitForNavigation?: boolean; waitForNetworkIdle?: boolean };\n}\n\nexport interface FillParams {\n target: ElementTarget;\n value: Resolvable;\n clearFirst?: boolean;\n mode?: 'replace' | 'append';\n}\n\nexport interface KeyParams {\n keys: Resolvable; // e.g. \"Backspace Enter\" or \"cmd+a\"\n target?: ElementTarget;\n}\n\nexport type ScrollMode = 'element' | 'offset' | 'container';\n\nexport interface ScrollOffset {\n x?: Resolvable;\n y?: Resolvable;\n}\n\nexport interface ScrollParams {\n mode: ScrollMode;\n target?: ElementTarget;\n offset?: ScrollOffset;\n}\n\nexport interface Point {\n x: number;\n y: number;\n}\n\nexport interface DragParams {\n start: ElementTarget;\n end: ElementTarget;\n path?: ReadonlyArray;\n}\n\n// --- 导航 ---\n\nexport interface NavigateParams {\n url: Resolvable;\n refresh?: boolean;\n}\n\n// --- 等待和断言 ---\n\nexport type WaitCondition =\n | { kind: 'sleep'; sleep: Resolvable }\n | { kind: 'navigation' }\n | { kind: 'networkIdle'; idleMs?: Resolvable }\n | { kind: 'text'; text: Resolvable; appear?: boolean }\n | { kind: 'selector'; selector: Resolvable; visible?: boolean };\n\nexport interface WaitParams {\n condition: WaitCondition;\n}\n\nexport type Assertion =\n | { kind: 'exists'; selector: Resolvable }\n | { kind: 'visible'; selector: Resolvable }\n | { kind: 'textPresent'; text: Resolvable }\n | {\n kind: 'attribute';\n selector: Resolvable;\n name: Resolvable;\n equals?: Resolvable;\n matches?: Resolvable;\n };\n\nexport type AssertFailStrategy = 'stop' | 'warn' | 'retry';\n\nexport interface AssertParams {\n assert: Assertion;\n failStrategy?: AssertFailStrategy;\n}\n\n// --- 数据和脚本 ---\n\nexport type ExtractParams =\n | {\n mode: 'selector';\n selector: Resolvable;\n attr?: Resolvable; // \"text\" | \"textContent\" | attribute name\n saveAs: VariableName;\n }\n | {\n mode: 'js';\n code: string;\n world?: BrowserWorld;\n saveAs: VariableName;\n };\n\nexport type ScriptTiming = 'before' | 'after';\n\nexport interface ScriptParams {\n world?: BrowserWorld;\n code: string;\n when?: ScriptTiming;\n args?: Record>;\n saveAs?: VariableName;\n assign?: Assignments;\n}\n\nexport interface ScreenshotParams {\n selector?: Resolvable;\n fullPage?: boolean;\n saveAs?: VariableName;\n}\n\n// --- HTTP ---\n\nexport type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\nexport type HttpHeaders = Record>;\nexport type HttpFormData = Record>;\n\nexport type HttpBody =\n | { kind: 'none' }\n | { kind: 'text'; text: Resolvable; contentType?: Resolvable }\n | { kind: 'json'; json: Resolvable };\n\nexport type HttpOkStatus =\n | { kind: 'range'; min: number; max: number }\n | { kind: 'list'; statuses: NonEmptyArray };\n\nexport interface HttpParams {\n method?: HttpMethod;\n url: Resolvable;\n headers?: HttpHeaders;\n body?: HttpBody;\n formData?: HttpFormData;\n okStatus?: HttpOkStatus;\n saveAs?: VariableName;\n assign?: Assignments;\n}\n\n// --- DOM 工具 ---\n\nexport interface TriggerEventParams {\n target: ElementTarget;\n event: Resolvable;\n bubbles?: boolean;\n cancelable?: boolean;\n}\n\nexport interface SetAttributeParams {\n target: ElementTarget;\n name: Resolvable;\n value?: Resolvable;\n remove?: boolean;\n}\n\nexport interface SwitchFrameParams {\n target: FrameTarget;\n}\n\nexport interface LoopElementsParams {\n selector: Resolvable;\n saveAs?: VariableName;\n itemVar?: VariableName;\n subflowId: SubflowId;\n}\n\n// --- 标签页管理 ---\n\nexport interface OpenTabParams {\n url?: Resolvable;\n newWindow?: boolean;\n}\n\nexport interface SwitchTabParams {\n tabId?: number;\n urlContains?: Resolvable;\n titleContains?: Resolvable;\n}\n\nexport interface CloseTabParams {\n tabIds?: ReadonlyArray;\n url?: Resolvable;\n}\n\nexport interface HandleDownloadParams {\n filenameContains?: Resolvable;\n waitForComplete?: boolean;\n saveAs?: VariableName;\n}\n\n// --- 控制流 ---\n\nexport interface ExecuteFlowParams {\n flowId: FlowId;\n inline?: boolean;\n args?: Record>;\n}\n\nexport interface ForeachParams {\n listVar: VariableName;\n itemVar?: VariableName;\n subflowId: SubflowId;\n concurrency?: number;\n}\n\nexport interface WhileParams {\n condition: Condition;\n subflowId: SubflowId;\n maxIterations?: number;\n}\n\nexport interface IfBranch {\n id: string;\n label: EdgeLabel;\n condition: Condition;\n}\n\nexport type IfParams =\n | {\n mode: 'binary';\n condition: Condition;\n trueLabel?: EdgeLabel;\n falseLabel?: EdgeLabel;\n }\n | {\n mode: 'branches';\n branches: NonEmptyArray;\n elseLabel?: EdgeLabel;\n };\n\nexport interface DelayParams {\n sleep: Resolvable;\n}\n\n// --- 触发器 ---\n\nexport type TriggerUrlRuleKind = 'url' | 'domain' | 'path';\n\nexport interface TriggerUrlRule {\n kind: TriggerUrlRuleKind;\n value: Resolvable;\n}\n\nexport interface TriggerUrlConfig {\n rules?: ReadonlyArray;\n}\n\nexport interface TriggerModeConfig {\n manual?: boolean;\n url?: boolean;\n contextMenu?: boolean;\n command?: boolean;\n dom?: boolean;\n schedule?: boolean;\n}\n\nexport interface TriggerContextMenuConfig {\n title?: Resolvable;\n enabled?: boolean;\n}\n\nexport interface TriggerCommandConfig {\n commandKey?: Resolvable;\n enabled?: boolean;\n}\n\nexport interface TriggerDomConfig {\n selector?: Resolvable;\n appear?: boolean;\n once?: boolean;\n debounceMs?: Milliseconds;\n enabled?: boolean;\n}\n\nexport type TriggerScheduleType = 'once' | 'interval' | 'daily';\n\nexport interface TriggerSchedule {\n id: string;\n type: TriggerScheduleType;\n when: Resolvable; // ISO/cron-like string\n enabled?: boolean;\n}\n\nexport interface TriggerParams {\n enabled?: boolean;\n description?: Resolvable;\n modes?: TriggerModeConfig;\n url?: TriggerUrlConfig;\n contextMenu?: TriggerContextMenuConfig;\n command?: TriggerCommandConfig;\n dom?: TriggerDomConfig;\n schedules?: ReadonlyArray;\n}\n\n// ================================\n// Action 核心定义\n// ================================\n\n/**\n * ActionParamsByType 使用 interface 声明\n * 允许外部模块通过声明合并扩展 Action 类型（符合 OCP 原则）\n */\nexport interface ActionParamsByType {\n // UI/构建时\n trigger: TriggerParams;\n delay: DelayParams;\n\n // 页面交互\n click: ClickParams;\n dblclick: ClickParams;\n fill: FillParams;\n key: KeyParams;\n scroll: ScrollParams;\n drag: DragParams;\n\n // 同步和验证\n wait: WaitParams;\n assert: AssertParams;\n\n // 数据和脚本\n extract: ExtractParams;\n script: ScriptParams;\n http: HttpParams;\n screenshot: ScreenshotParams;\n\n // DOM 工具\n triggerEvent: TriggerEventParams;\n setAttribute: SetAttributeParams;\n\n // 帧和循环\n switchFrame: SwitchFrameParams;\n loopElements: LoopElementsParams;\n\n // 控制流\n if: IfParams;\n foreach: ForeachParams;\n while: WhileParams;\n executeFlow: ExecuteFlowParams;\n\n // 标签页\n navigate: NavigateParams;\n openTab: OpenTabParams;\n switchTab: SwitchTabParams;\n closeTab: CloseTabParams;\n handleDownload: HandleDownloadParams;\n}\n\nexport type ActionType = keyof ActionParamsByType;\n\nexport interface ActionBase {\n id: ActionId;\n type: T;\n name?: string;\n disabled?: boolean;\n tags?: ReadonlyArray;\n policy?: ActionPolicy;\n ui?: { x: number; y: number };\n}\n\nexport type Action = ActionBase & {\n params: ActionParamsByType[T];\n};\n\nexport type AnyAction = { [T in ActionType]: Action }[ActionType];\n\nexport type ExecutableActionType = Exclude;\nexport type ExecutableAction = Action;\n\n// ================================\n// Action 输出\n// ================================\n\nexport interface HttpResponse {\n url: string;\n status: number;\n headers?: Record;\n body?: JsonValue | string | null;\n}\n\nexport type DownloadState = 'in_progress' | 'complete' | 'interrupted' | 'canceled';\n\nexport interface DownloadInfo {\n id: string;\n filename: string;\n url?: string;\n state?: DownloadState;\n size?: number;\n}\n\n/**\n * Action 输出类型映射（可通过声明合并扩展）\n */\nexport interface ActionOutputsByType {\n screenshot: { base64Data: string };\n extract: { value: JsonValue };\n script: { result: JsonValue };\n http: { response: HttpResponse };\n handleDownload: { download: DownloadInfo };\n loopElements: { elements: string[] };\n}\n\nexport type ActionOutput = T extends keyof ActionOutputsByType\n ? ActionOutputsByType[T]\n : undefined;\n\n// ================================\n// 执行接口\n// ================================\n\nexport type ValidationResult = { ok: true } | { ok: false; errors: NonEmptyArray };\n\n/**\n * Execution flags for coordinating with orchestrator policies.\n * Used to avoid duplicate retry/nav-wait when StepRunner owns these policies.\n */\nexport interface ExecutionFlags {\n /**\n * When true, navigation waiting should be handled by StepRunner.\n * Action handlers (click, navigate) should skip their internal nav-wait logic.\n */\n skipNavWait?: boolean;\n}\n\nexport interface ActionExecutionContext {\n vars: VariableStore;\n tabId: number;\n frameId?: number;\n runId?: string;\n /** 日志记录函数 */\n log: (message: string, level?: 'info' | 'warn' | 'error') => void;\n /** 截图函数 */\n captureScreenshot?: () => Promise;\n /**\n * Optional structured log sink for replay UIs (legacy RunLogger integration).\n * Action handlers may emit richer entries (e.g. selector fallback) via this hook.\n */\n pushLog?: (entry: unknown) => void;\n /**\n * Execution flags provided by the orchestrator.\n * Handlers should respect these flags to avoid duplicating StepRunner policies.\n */\n execution?: ExecutionFlags;\n}\n\nexport type ControlDirective =\n | {\n kind: 'foreach';\n listVar: VariableName;\n itemVar: VariableName;\n subflowId: SubflowId;\n concurrency?: number;\n }\n | {\n kind: 'while';\n condition: Condition;\n subflowId: SubflowId;\n maxIterations: number;\n };\n\nexport interface ActionExecutionResult {\n status: 'success' | 'failed' | 'skipped' | 'paused';\n output?: ActionOutput;\n error?: ActionError;\n /** 下一个边的 label（用于条件分支） */\n nextLabel?: EdgeLabel;\n /** 控制流指令（foreach/while） */\n control?: ControlDirective;\n /** 执行耗时 */\n durationMs?: Milliseconds;\n /**\n * New tab ID after tab operations (openTab/switchTab).\n * Used to update execution context for subsequent steps.\n */\n newTabId?: number;\n}\n\n/**\n * Action 执行器接口\n */\nexport interface ActionHandler {\n type: T;\n /** 验证 action 配置 */\n validate?: (action: Action) => ValidationResult;\n /** 执行 action */\n run: (ctx: ActionExecutionContext, action: Action) => Promise>;\n /** 生成 action 描述（用于 UI 显示） */\n describe?: (action: Action) => string;\n}\n\n// ================================\n// Flow 图结构\n// ================================\n\nexport interface ActionEdge {\n id: EdgeId;\n from: ActionId;\n to: ActionId;\n label?: EdgeLabel;\n}\n\nexport interface FlowBinding {\n type: 'domain' | 'path' | 'url';\n value: string;\n}\n\nexport interface FlowMeta {\n createdAt: ISODateTimeString;\n updatedAt: ISODateTimeString;\n domain?: string;\n tags?: ReadonlyArray;\n bindings?: ReadonlyArray;\n tool?: { category?: string; description?: string };\n exposedOutputs?: ReadonlyArray<{ nodeId: ActionId; as: VariableName }>;\n}\n\nexport interface Flow {\n id: FlowId;\n name: string;\n description?: string;\n version: number;\n meta: FlowMeta;\n variables?: ReadonlyArray;\n\n /** DAG 节点 */\n nodes: ReadonlyArray;\n /** DAG 边 */\n edges: ReadonlyArray;\n /** 子流程（用于 foreach/while/loopElements） */\n subflows?: Record<\n SubflowId,\n { nodes: ReadonlyArray; edges: ReadonlyArray }\n >;\n}\n\n// ================================\n// Action 规格（用于 UI）\n// ================================\n\nexport type ActionCategory = 'Flow' | 'Actions' | 'Logic' | 'Tools' | 'Tabs' | 'Page';\n\nexport interface ActionSpecDisplay {\n label: string;\n description?: string;\n category: ActionCategory;\n icon?: string;\n docUrl?: string;\n}\n\nexport interface ActionSpecPorts {\n inputs: number | 'any';\n outputs: Array<{ label?: EdgeLabel }> | 'any';\n maxConnection?: number;\n allowedInputs?: boolean;\n}\n\nexport interface ActionSpec {\n type: T;\n version: number;\n display: ActionSpecDisplay;\n ports: ActionSpecPorts;\n defaults?: Partial;\n /** 需要进行模板替换的字段路径 */\n refDataKeys?: ReadonlyArray;\n}\n\n// ================================\n// 常量导出\n// ================================\n\nexport const ACTION_TYPES: ReadonlyArray = [\n 'trigger',\n 'delay',\n 'click',\n 'dblclick',\n 'fill',\n 'key',\n 'scroll',\n 'drag',\n 'wait',\n 'assert',\n 'extract',\n 'script',\n 'http',\n 'screenshot',\n 'triggerEvent',\n 'setAttribute',\n 'switchFrame',\n 'loopElements',\n 'if',\n 'foreach',\n 'while',\n 'executeFlow',\n 'navigate',\n 'openTab',\n 'switchTab',\n 'closeTab',\n 'handleDownload',\n] as const;\n\nexport const EXECUTABLE_ACTION_TYPES: ReadonlyArray = ACTION_TYPES.filter(\n (t): t is ExecutableActionType => t !== 'trigger',\n);\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/constants.ts", "content": "// constants.ts — centralized engine constants and labels\nimport { EDGE_LABELS } from 'chrome-mcp-shared';\n\nexport const ENGINE_CONSTANTS = {\n DEFAULT_WAIT_MS: 5000,\n MAX_WAIT_MS: 120000,\n NETWORK_IDLE_SAMPLE_MS: 1200,\n MAX_ITERATIONS: 1000,\n MAX_FOREACH_CONCURRENCY: 16,\n EDGE_LABELS: EDGE_LABELS,\n} as const;\n\nexport type EdgeLabel =\n (typeof ENGINE_CONSTANTS.EDGE_LABELS)[keyof typeof ENGINE_CONSTANTS.EDGE_LABELS];\n\n// Centralized stepId values used in run logs for non-step events\nexport const LOG_STEP_IDS = {\n GLOBAL_TIMEOUT: 'global-timeout',\n PLUGIN_RUN_START: 'plugin-runStart',\n VARIABLE_COLLECT: 'variable-collect',\n BINDING_CHECK: 'binding-check',\n NETWORK_CAPTURE: 'network-capture',\n DAG_REQUIRED: 'dag-required',\n DAG_CYCLE: 'dag-cycle',\n LOOP_GUARD: 'loop-guard',\n PLUGIN_RUN_END: 'plugin-runEnd',\n RUNSTATE_UPDATE: 'runState-update',\n RUNSTATE_DELETE: 'runState-delete',\n} as const;\n\nexport type LogStepId = (typeof LOG_STEP_IDS)[keyof typeof LOG_STEP_IDS];\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/execution-mode.ts", "content": "/**\n * Execution Mode Configuration\n *\n * Controls whether step execution uses the legacy node system or the new ActionRegistry.\n * Provides a migration path from legacy to actions with hybrid mode for gradual rollout.\n *\n * Modes:\n * - 'legacy': Use the existing executeStep from nodes/index.ts (default, safest)\n * - 'actions': Use ActionRegistry exclusively (strict mode, throws on unsupported)\n * - 'hybrid': Try ActionRegistry first, fall back to legacy for unsupported types\n */\n\nimport type { Step } from '../types';\n\n/**\n * Execution mode determines how steps are executed\n */\nexport type ExecutionMode = 'legacy' | 'actions' | 'hybrid';\n\n/**\n * Configuration for execution mode\n */\nexport interface ExecutionModeConfig {\n /**\n * The execution mode to use\n * @default 'legacy'\n */\n mode: ExecutionMode;\n\n /**\n * Step types that should always use legacy execution (denylist for actions)\n * Only applies in hybrid mode\n */\n legacyOnlyTypes?: Set;\n\n /**\n * Step types that should use actions execution (allowlist)\n * Only applies in hybrid mode.\n * - If undefined: uses MINIMAL_HYBRID_ACTION_TYPES (safest default)\n * - If empty Set (size=0): falls back to MIGRATED_ACTION_TYPES policy\n * - If non-empty Set: only these types use actions\n */\n actionsAllowlist?: Set;\n\n /**\n * Whether to log when falling back from actions to legacy in hybrid mode\n * @default true\n */\n logFallbacks?: boolean;\n\n /**\n * Skip ActionRegistry's built-in retry policy.\n * When true, action.policy.retry is removed before execution.\n * @default true - StepRunner already handles retry via withRetry()\n *\n * Note: ActionRegistry timeout is NOT disabled (provides per-action timeout safety).\n */\n skipActionsRetry?: boolean;\n\n /**\n * Skip ActionRegistry's navigation waiting when StepRunner handles it\n * @default true - StepRunner already handles navigation waiting\n */\n skipActionsNavWait?: boolean;\n}\n\n/**\n * Default execution mode configuration\n * Starts with legacy mode for maximum safety during migration\n */\nexport const DEFAULT_EXECUTION_MODE_CONFIG: ExecutionModeConfig = {\n mode: 'legacy',\n logFallbacks: true,\n skipActionsRetry: true,\n skipActionsNavWait: true,\n};\n\n/**\n * Minimal allowlist for initial hybrid rollout.\n *\n * This keeps high-risk step types (navigation/click/tab management) on legacy\n * until policy (retry/timeout/nav-wait) and tab cursor semantics are unified.\n *\n * These types are chosen for their low risk:\n * - No navigation side effects\n * - No tab management\n * - No complex timing requirements\n * - Simple input/output semantics\n */\nexport const MINIMAL_HYBRID_ACTION_TYPES = new Set([\n 'fill', // Form input - no navigation\n 'key', // Keyboard input - no navigation\n 'scroll', // Viewport manipulation - no navigation\n 'drag', // Drag and drop - local operation\n 'wait', // Condition waiting - no side effects\n 'delay', // Simple delay - no side effects\n 'screenshot', // Capture only - no side effects\n 'assert', // Validation only - no side effects\n]);\n\n/**\n * Step types that are fully migrated and tested with ActionRegistry\n * These are safe to run in actions mode\n *\n * NOTE: Start conservative and expand gradually as testing confirms equivalence.\n * Types NOT included here will fall back to legacy in hybrid mode.\n *\n * Criteria for inclusion:\n * 1. Handler implementation matches legacy behavior exactly\n * 2. Step data structure is compatible (no complex transformation needed)\n * 3. No timing-sensitive dependencies (like script when:'after' defer)\n */\nexport const MIGRATED_ACTION_TYPES = new Set([\n // Navigation - well tested, simple mapping\n 'navigate',\n // Interaction - well tested, core functionality\n 'click',\n 'dblclick',\n 'fill',\n 'key',\n 'scroll',\n 'drag',\n // Timing - simple logic, no complex state\n 'wait',\n 'delay',\n // Screenshot - simple, no side effects\n 'screenshot',\n // Assert - validation only, no state changes\n 'assert',\n]);\n\n/**\n * Step types that need more validation before migration\n * These are supported by ActionRegistry but may have behavior differences\n */\nexport const NEEDS_VALIDATION_TYPES = new Set([\n // Data extraction - need to verify selector/js mode equivalence\n 'extract',\n // HTTP - body type handling may differ\n 'http',\n // Script - when:'after' defer semantics differ from legacy\n 'script',\n // Tabs - tabId tracking needs careful integration\n 'openTab',\n 'switchTab',\n 'closeTab',\n 'handleDownload',\n // Control flow - condition evaluation may differ\n 'if',\n 'foreach',\n 'while',\n 'switchFrame',\n]);\n\n/**\n * Step types that must use legacy execution\n * These have complex integration requirements not yet supported by ActionRegistry\n */\nexport const LEGACY_ONLY_TYPES = new Set([\n // Complex legacy types not yet migrated\n 'triggerEvent',\n 'setAttribute',\n 'loopElements',\n 'executeFlow',\n]);\n\n/**\n * Determine whether a step should use actions execution based on config\n */\nexport function shouldUseActions(step: Step, config: ExecutionModeConfig): boolean {\n if (config.mode === 'legacy') {\n return false;\n }\n\n if (config.mode === 'actions') {\n return true;\n }\n\n // Hybrid mode: check allowlist/denylist\n const stepType = step.type;\n\n // Denylist takes precedence\n if (config.legacyOnlyTypes?.has(stepType)) {\n return false;\n }\n\n // If allowlist is specified and non-empty, step must be in it\n if (config.actionsAllowlist && config.actionsAllowlist.size > 0) {\n return config.actionsAllowlist.has(stepType);\n }\n\n // Default to using actions for supported types\n return MIGRATED_ACTION_TYPES.has(stepType);\n}\n\n/**\n * Create a hybrid execution mode config for gradual migration.\n *\n * By default uses MINIMAL_HYBRID_ACTION_TYPES as allowlist, which excludes\n * high-risk types (navigate/click/tab management) from actions execution.\n *\n * @param overrides - Optional overrides for the config\n * @param overrides.actionsAllowlist - Set of step types to execute via actions.\n * If provided with size > 0, only these types use actions.\n * If empty Set, falls back to MIGRATED_ACTION_TYPES.\n * If undefined, uses MINIMAL_HYBRID_ACTION_TYPES (safest default).\n */\nexport function createHybridConfig(overrides?: Partial): ExecutionModeConfig {\n return {\n ...DEFAULT_EXECUTION_MODE_CONFIG,\n mode: 'hybrid',\n legacyOnlyTypes: new Set(LEGACY_ONLY_TYPES),\n actionsAllowlist: new Set(MINIMAL_HYBRID_ACTION_TYPES),\n ...overrides,\n };\n}\n\n/**\n * Create a strict actions mode config for testing.\n * All steps must be handled by ActionRegistry or throw.\n *\n * Note: Even in actions mode, StepRunner remains the policy authority for\n * retry/nav-wait. This ensures consistent behavior across all execution modes\n * and avoids double-strategy issues.\n */\nexport function createActionsOnlyConfig(\n overrides?: Partial,\n): ExecutionModeConfig {\n return {\n ...DEFAULT_EXECUTION_MODE_CONFIG,\n mode: 'actions',\n // Keep StepRunner as policy authority - skip ActionRegistry's internal policies\n skipActionsRetry: true,\n skipActionsNavWait: true,\n ...overrides,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/logging/run-logger.ts", "content": "// engine/logging/run-logger.ts — run logs, overlay and persistence\nimport type { RunLogEntry, RunRecord, Flow } from '../../types';\nimport { appendRun } from '../../flow-store';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\n\nexport class RunLogger {\n private logs: RunLogEntry[] = [];\n constructor(private runId: string) {}\n\n push(e: RunLogEntry) {\n this.logs.push(e);\n }\n\n getLogs() {\n return this.logs;\n }\n\n async overlayInit() {\n try {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n if (tabs[0]?.id)\n await chrome.tabs.sendMessage(tabs[0].id, { action: 'rr_overlay', cmd: 'init' } as any);\n } catch {}\n }\n\n async overlayAppend(text: string) {\n try {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n if (tabs[0]?.id)\n await chrome.tabs.sendMessage(tabs[0].id, {\n action: 'rr_overlay',\n cmd: 'append',\n text,\n } as any);\n } catch {}\n }\n\n async overlayDone() {\n try {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n if (tabs[0]?.id)\n await chrome.tabs.sendMessage(tabs[0].id, { action: 'rr_overlay', cmd: 'done' } as any);\n } catch {}\n }\n\n async screenshotOnFailure() {\n try {\n const shot = await handleCallTool({\n name: TOOL_NAMES.BROWSER.COMPUTER,\n args: { action: 'screenshot' },\n });\n const img = (shot?.content?.find((c: any) => c.type === 'image') as any)?.data as string;\n if (img) this.logs[this.logs.length - 1].screenshotBase64 = img;\n } catch {}\n }\n\n async persist(flow: Flow, startedAt: number, success: boolean) {\n const record: RunRecord = {\n id: this.runId,\n flowId: flow.id,\n startedAt: new Date(startedAt).toISOString(),\n finishedAt: new Date().toISOString(),\n success,\n entries: this.logs,\n };\n await appendRun(record);\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/plugins/breakpoint.ts", "content": "import type { RunPlugin, StepContext } from './types';\nimport { runState } from '../state-manager';\n\nexport function breakpointPlugin(): RunPlugin {\n return {\n name: 'breakpoint',\n async onBeforeStep(ctx: StepContext) {\n try {\n const step: any = ctx.step as any;\n const hasBreakpoint = step?.$breakpoint === true || step?.breakpoint === true;\n if (!hasBreakpoint) return;\n // mark run paused for external UI to resume\n await runState.update(ctx.runId, { status: 'stopped', updatedAt: Date.now() } as any);\n return { pause: true };\n } catch {}\n return;\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/plugins/manager.ts", "content": "import type {\n RunPlugin,\n HookControl,\n RunContext,\n StepContext,\n StepAfterContext,\n StepErrorContext,\n StepRetryContext,\n RunEndContext,\n SubflowContext,\n} from './types';\n\nexport class PluginManager {\n constructor(private plugins: RunPlugin[]) {}\n\n async runStart(ctx: RunContext) {\n for (const p of this.plugins) await safeCall(p, 'onRunStart', ctx);\n }\n\n async beforeStep(ctx: StepContext): Promise {\n for (const p of this.plugins) {\n const out = await safeCall(p, 'onBeforeStep', ctx);\n if (out && (out.pause || out.nextLabel)) return out;\n }\n return undefined;\n }\n\n async afterStep(ctx: StepAfterContext) {\n for (const p of this.plugins) await safeCall(p, 'onAfterStep', ctx);\n }\n\n async onError(ctx: StepErrorContext): Promise {\n for (const p of this.plugins) {\n const out = await safeCall(p, 'onStepError', ctx);\n if (out && (out.pause || out.nextLabel)) return out;\n }\n return undefined;\n }\n\n async onRetry(ctx: StepRetryContext) {\n for (const p of this.plugins) await safeCall(p, 'onRetry', ctx);\n }\n\n async onChooseNextLabel(ctx: StepContext & { suggested?: string }): Promise {\n for (const p of this.plugins) {\n const out = await safeCall(p, 'onChooseNextLabel', ctx);\n if (out && out.nextLabel) return String(out.nextLabel);\n }\n return undefined;\n }\n\n async subflowStart(ctx: SubflowContext) {\n for (const p of this.plugins) await safeCall(p, 'onSubflowStart', ctx);\n }\n\n async subflowEnd(ctx: SubflowContext) {\n for (const p of this.plugins) await safeCall(p, 'onSubflowEnd', ctx);\n }\n\n async runEnd(ctx: RunEndContext) {\n for (const p of this.plugins) await safeCall(p, 'onRunEnd', ctx);\n }\n}\n\nasync function safeCall(plugin: RunPlugin, key: T, arg: any) {\n try {\n const fn = plugin[key] as any;\n if (typeof fn === 'function') return await fn.call(plugin, arg);\n } catch (e) {\n // swallow plugin errors to keep core stable\n // console.warn(`[plugin:${plugin.name}] ${String(key)} error:`, e);\n }\n return undefined;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/plugins/types.ts", "content": "// Plugin system for record-replay engine\n// Inspired by webpack-like lifecycle hooks, to avoid touching core for extensibility\n\nimport type { Flow, Step } from '../../types';\nimport type { ExecResult } from '../../nodes';\n\nexport interface RunContext {\n runId: string;\n flow: Flow;\n vars: Record;\n}\n\nexport interface StepContext extends RunContext {\n step: Step;\n}\n\nexport interface StepErrorContext extends StepContext {\n error: any;\n}\n\nexport interface StepRetryContext extends StepErrorContext {\n attempt: number;\n}\n\nexport interface StepAfterContext extends StepContext {\n result?: ExecResult;\n}\n\nexport interface SubflowContext extends RunContext {\n subflowId: string;\n}\n\nexport interface RunEndContext extends RunContext {\n success: boolean;\n failed: number;\n}\n\nexport interface HookControl {\n pause?: boolean; // request scheduler to pause run (e.g., breakpoint)\n nextLabel?: string; // override next edge label\n}\n\nexport interface RunPlugin {\n name: string;\n onRunStart?(ctx: RunContext): Promise | void;\n onBeforeStep?(ctx: StepContext): Promise | HookControl | void;\n onAfterStep?(ctx: StepAfterContext): Promise | void;\n onStepError?(ctx: StepErrorContext): Promise | HookControl | void;\n onRetry?(ctx: StepRetryContext): Promise | void;\n onChooseNextLabel?(\n ctx: StepContext & { suggested?: string },\n ): Promise | HookControl | void;\n onSubflowStart?(ctx: SubflowContext): Promise | void;\n onSubflowEnd?(ctx: SubflowContext): Promise | void;\n onRunEnd?(ctx: RunEndContext): Promise | void;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/policies/retry.ts", "content": "// engine/policies/retry.ts — unified retry/backoff policy\n\nexport type BackoffKind = 'none' | 'exp';\n\nexport interface RetryOptions {\n count?: number; // max attempts beyond the first run\n intervalMs?: number;\n backoff?: BackoffKind;\n}\n\nexport async function withRetry(\n run: () => Promise,\n onRetry?: (attempt: number, err: any) => Promise | void,\n opts?: RetryOptions,\n): Promise {\n const max = Math.max(0, Number(opts?.count ?? 0));\n const base = Math.max(0, Number(opts?.intervalMs ?? 0));\n const backoff = (opts?.backoff || 'none') as BackoffKind;\n let attempt = 0;\n while (true) {\n try {\n return await run();\n } catch (e) {\n if (attempt >= max) throw e;\n if (onRetry) await onRetry(attempt, e);\n const delay = base > 0 ? (backoff === 'exp' ? base * Math.pow(2, attempt) : base) : 0;\n if (delay > 0) await new Promise((r) => setTimeout(r, delay));\n attempt += 1;\n }\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts", "content": "// engine/policies/wait.ts — wrappers around rr-utils navigation/network waits\n// Keep logic centralized to avoid duplication in schedulers and nodes\n\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { waitForNavigation as rrWaitForNavigation, waitForNetworkIdle } from '../../rr-utils';\n\nexport async function waitForNavigationDone(prevUrl: string, timeoutMs?: number) {\n await rrWaitForNavigation(timeoutMs, prevUrl);\n}\n\nexport async function ensureReadPageIfWeb() {\n try {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const url = tabs?.[0]?.url || '';\n if (/^(https?:|file:)/i.test(url)) {\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n }\n } catch {}\n}\n\nexport async function maybeQuickWaitForNav(prevUrl: string, timeoutMs?: number) {\n try {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') return;\n const sniffMs = 350;\n const startedAt = Date.now();\n let seen = false;\n await new Promise((resolve) => {\n let timer: any = null;\n const cleanup = () => {\n try {\n chrome.webNavigation.onCommitted.removeListener(onCommitted);\n } catch {}\n try {\n chrome.webNavigation.onCompleted.removeListener(onCompleted);\n } catch {}\n try {\n (chrome.webNavigation as any).onHistoryStateUpdated?.removeListener?.(\n onHistoryStateUpdated,\n );\n } catch {}\n try {\n chrome.tabs.onUpdated.removeListener(onUpdated);\n } catch {}\n if (timer) {\n try {\n clearTimeout(timer);\n } catch {}\n }\n };\n const finish = async () => {\n cleanup();\n if (seen) {\n try {\n await rrWaitForNavigation(\n prevUrl ? Math.min(timeoutMs || 15000, 30000) : undefined,\n prevUrl,\n );\n } catch {}\n }\n resolve();\n };\n const mark = () => {\n seen = true;\n };\n const onCommitted = (d: any) => {\n if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();\n };\n const onCompleted = (d: any) => {\n if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();\n };\n const onHistoryStateUpdated = (d: any) => {\n if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();\n };\n const onUpdated = (updatedId: number, change: chrome.tabs.TabChangeInfo) => {\n if (updatedId !== tabId) return;\n if (change.status === 'loading') mark();\n if (typeof change.url === 'string' && (!prevUrl || change.url !== prevUrl)) mark();\n };\n\n chrome.webNavigation.onCommitted.addListener(onCommitted);\n chrome.webNavigation.onCompleted.addListener(onCompleted);\n try {\n (chrome.webNavigation as any).onHistoryStateUpdated?.addListener?.(onHistoryStateUpdated);\n } catch {}\n chrome.tabs.onUpdated.addListener(onUpdated);\n timer = setTimeout(finish, sniffMs);\n });\n } catch {}\n}\n\nexport { waitForNetworkIdle };\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/runners/after-script-queue.ts", "content": "// after-script-queue.ts — queue + executor for deferred after-scripts\n// Notes:\n// - Executes user-provided code in the specified world (ISOLATED by default)\n// - Clears queue before execution to avoid leaks; re-queues remainder on failure\n// - Logs warnings instead of throwing to keep the main engine resilient\n\nimport type { StepScript } from '../../types';\nimport type { ExecCtx } from '../../nodes';\nimport { RunLogger } from '../logging/run-logger';\nimport { applyAssign } from '../../rr-utils';\n\nexport class AfterScriptQueue {\n private queue: StepScript[] = [];\n\n constructor(private logger: RunLogger) {}\n\n enqueue(script: StepScript) {\n this.queue.push(script);\n }\n\n size() {\n return this.queue.length;\n }\n\n async flush(ctx: ExecCtx, vars: Record) {\n if (this.queue.length === 0) return;\n const scriptsToFlush = this.queue.splice(0, this.queue.length);\n for (let i = 0; i < scriptsToFlush.length; i++) {\n const s = scriptsToFlush[i]!;\n const tScript = Date.now();\n const world = (s as any).world || 'ISOLATED';\n const code = String((s as any).code || '');\n if (!code.trim()) {\n this.logger.push({ stepId: s.id, status: 'success', tookMs: Date.now() - tScript });\n continue;\n }\n try {\n // Warn on obviously dangerous constructs; not a sandbox, just visibility.\n const dangerous =\n /[;{}]|\\b(function|=>|while|for|class|globalThis|window|self|this|constructor|__proto__|prototype|eval|Function|import|require|XMLHttpRequest|fetch|chrome)\\b/;\n if (dangerous.test(code)) {\n this.logger.push({\n stepId: s.id,\n status: 'warning',\n message: 'Script contains potentially unsafe tokens; executed in isolated world',\n });\n }\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n const [{ result }] = await chrome.scripting.executeScript({\n target: { tabId },\n func: (userCode: string) => {\n try {\n return (0, eval)(userCode);\n } catch (e) {\n return { __error: true, message: String(e) } as any;\n }\n },\n args: [code],\n world: world as any,\n } as any);\n if ((result as any)?.__error) {\n this.logger.push({\n stepId: s.id,\n status: 'warning',\n message: `After-script error: ${(result as any).message || 'unknown'}`,\n });\n }\n const value = (result as any)?.__error ? null : result;\n if ((s as any).saveAs) (vars as any)[(s as any).saveAs] = value;\n if ((s as any).assign && typeof (s as any).assign === 'object')\n applyAssign(vars, value, (s as any).assign);\n } catch (e: any) {\n // Re-queue remaining and stop flush cycle for now\n const remaining = scriptsToFlush.slice(i + 1);\n if (remaining.length) this.queue.unshift(...remaining);\n this.logger.push({\n stepId: s.id,\n status: 'warning',\n message: `After-script execution failed: ${e?.message || String(e)}`,\n });\n break;\n }\n this.logger.push({ stepId: s.id, status: 'success', tookMs: Date.now() - tScript });\n }\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/runners/control-flow-runner.ts", "content": "// control-flow-runner.ts — foreach / while orchestration\n\nimport type { ExecCtx } from '../../nodes';\nimport { RunLogger } from '../logging/run-logger';\n\nexport interface ControlFlowEnv {\n vars: Record;\n logger: RunLogger;\n evalCondition: (cond: any) => boolean;\n runSubflowById: (subflowId: string, ctx: ExecCtx) => Promise;\n isPaused: () => boolean;\n}\n\nexport class ControlFlowRunner {\n constructor(private env: ControlFlowEnv) {}\n\n async run(control: any, ctx: ExecCtx): Promise<'ok' | 'paused'> {\n if (control?.kind === 'foreach') {\n const list = Array.isArray(this.env.vars[control.listVar])\n ? (this.env.vars[control.listVar] as any[])\n : [];\n const concurrency = Math.max(1, Math.min(16, Number(control.concurrency ?? 1)));\n if (concurrency <= 1) {\n for (const it of list) {\n this.env.vars[control.itemVar] = it;\n await this.env.runSubflowById(control.subflowId, ctx);\n if (this.env.isPaused()) return 'paused';\n }\n return this.env.isPaused() ? 'paused' : 'ok';\n }\n // Parallel with shallow-cloned vars per task (no automatic merge)\n let idx = 0;\n const runOne = async () => {\n while (idx < list.length) {\n const cur = idx++;\n const it = list[cur];\n const childCtx: ExecCtx = { ...ctx, vars: { ...this.env.vars } };\n childCtx.vars[control.itemVar] = it;\n await this.env.runSubflowById(control.subflowId, childCtx);\n if (this.env.isPaused()) return;\n }\n };\n const workers = Array.from({ length: Math.min(concurrency, list.length) }, () => runOne());\n await Promise.all(workers);\n return this.env.isPaused() ? 'paused' : 'ok';\n }\n if (control?.kind === 'while') {\n let i = 0;\n while (i < control.maxIterations && this.env.evalCondition(control.condition)) {\n await this.env.runSubflowById(control.subflowId, ctx);\n if (this.env.isPaused()) return 'paused';\n i++;\n }\n return this.env.isPaused() ? 'paused' : 'ok';\n }\n // Unknown control type → no-op\n return 'ok';\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/runners/step-executor.ts", "content": "/**\n * Step Executor Interface\n *\n * Provides a unified interface for step execution that supports multiple execution modes.\n * This abstraction allows seamless switching between legacy and actions execution.\n *\n * Architecture:\n * - StepExecutorInterface: Base interface for all executors\n * - LegacyStepExecutor: Uses the existing executeStep from nodes/\n * - ActionsStepExecutor: Uses ActionRegistry from actions/\n * - HybridStepExecutor: Tries actions first, falls back to legacy\n */\n\nimport type { Step } from '../../types';\nimport type { ExecCtx, ExecResult } from '../../nodes/types';\nimport { executeStep as legacyExecuteStep } from '../../nodes';\nimport type { ActionRegistry } from '../../actions/registry';\nimport {\n createStepExecutor,\n isActionSupported,\n type StepExecutionAttempt,\n} from '../../actions/adapter';\nimport type { ExecutionModeConfig } from '../execution-mode';\nimport { shouldUseActions } from '../execution-mode';\n\n/**\n * Step execution result with additional metadata\n */\nexport interface StepExecutionResult {\n /** The execution result from the step */\n result: ExecResult;\n /** Which executor was used */\n executor: 'legacy' | 'actions';\n /** Whether fallback was used (only in hybrid mode) */\n fallback?: boolean;\n /** Reason for fallback (only when fallback=true) */\n fallbackReason?: string;\n}\n\n/**\n * Options for step execution\n */\nexport interface StepExecutionOptions {\n /** Current tab ID */\n tabId: number;\n /** Run ID for logging/tracing */\n runId?: string;\n /** Logger for recording fallback information */\n pushLog?: (entry: unknown) => void;\n /** Remaining time budget from global deadline */\n remainingBudgetMs?: number;\n}\n\n/**\n * Base interface for step executors\n */\nexport interface StepExecutorInterface {\n /**\n * Execute a single step\n */\n execute(ctx: ExecCtx, step: Step, options: StepExecutionOptions): Promise;\n\n /**\n * Check if executor supports a step type\n */\n supports(stepType: string): boolean;\n}\n\n/**\n * Legacy step executor using nodes/executeStep\n *\n * This executor delegates to the existing node execution system.\n * The options parameter is accepted but not used - retry/timeout/navigation\n * waiting are handled by StepRunner to maintain existing behavior.\n */\nexport class LegacyStepExecutor implements StepExecutorInterface {\n async execute(\n ctx: ExecCtx,\n step: Step,\n _options: StepExecutionOptions,\n ): Promise {\n // Note: tabId from options is not used here because legacy executeStep\n // queries the active tab internally. In hybrid/actions mode, tabId is\n // passed through to ActionRegistry handlers.\n const result = await legacyExecuteStep(ctx, step);\n return {\n result: result || {},\n executor: 'legacy',\n };\n }\n\n supports(_stepType: string): boolean {\n // Legacy executor supports all step types via its own registry\n return true;\n }\n}\n\n/**\n * Actions step executor using ActionRegistry\n *\n * In strict mode, any unsupported step type throws an error.\n * This executor does NOT fall back to legacy - use HybridStepExecutor for fallback behavior.\n *\n * Respects ExecutionModeConfig for:\n * - skipActionsRetry: Disables ActionRegistry retry (StepRunner owns retry)\n * - skipActionsNavWait: Disables handler nav-wait (StepRunner owns nav-wait)\n */\nexport class ActionsStepExecutor implements StepExecutorInterface {\n private executor: ReturnType;\n\n constructor(\n private registry: ActionRegistry,\n private config: ExecutionModeConfig,\n ) {\n this.executor = createStepExecutor(registry);\n }\n\n async execute(\n ctx: ExecCtx,\n step: Step,\n options: StepExecutionOptions,\n ): Promise {\n // Use strict=true: throws on unsupported types instead of returning { supported: false }\n // This ensures all steps must be handled by ActionRegistry in actions-only mode\n const attempt = (await this.executor(ctx, step, options.tabId, {\n runId: options.runId,\n pushLog: options.pushLog,\n strict: true,\n // Pass policy skip flags from config (default to true = skip)\n skipRetry: this.config.skipActionsRetry !== false,\n skipNavWait: this.config.skipActionsNavWait !== false,\n })) as StepExecutionAttempt;\n\n // With strict=true, we should never get { supported: false } - it would throw instead\n // This check exists for type safety and defensive programming\n if (!attempt.supported) {\n throw new Error(attempt.reason);\n }\n\n return {\n result: attempt.result,\n executor: 'actions',\n };\n }\n\n supports(stepType: string): boolean {\n // Use adapter's type guard to check if step type is supported\n return isActionSupported(stepType);\n }\n}\n\n/**\n * Hybrid step executor that tries actions first, falls back to legacy\n *\n * Respects ExecutionModeConfig for:\n * - actionsAllowlist/legacyOnlyTypes: Controls which steps use actions vs legacy\n * - skipActionsRetry: Disables ActionRegistry retry (StepRunner owns retry)\n * - skipActionsNavWait: Disables handler nav-wait (StepRunner owns nav-wait)\n * - logFallbacks: Whether to log when falling back to legacy\n */\nexport class HybridStepExecutor implements StepExecutorInterface {\n private actionsExecutor: ReturnType;\n\n constructor(\n private registry: ActionRegistry,\n private config: ExecutionModeConfig,\n ) {\n this.actionsExecutor = createStepExecutor(registry);\n }\n\n async execute(\n ctx: ExecCtx,\n step: Step,\n options: StepExecutionOptions,\n ): Promise {\n // Check if step should use actions based on config\n if (!shouldUseActions(step, this.config)) {\n // Use legacy directly\n const result = await legacyExecuteStep(ctx, step);\n return {\n result: result || {},\n executor: 'legacy',\n };\n }\n\n // Try actions first\n const attempt = (await this.actionsExecutor(ctx, step, options.tabId, {\n runId: options.runId,\n pushLog: options.pushLog,\n strict: false, // Don't throw on unsupported, return { supported: false }\n // Pass policy skip flags from config (default to true = skip)\n skipRetry: this.config.skipActionsRetry !== false,\n skipNavWait: this.config.skipActionsNavWait !== false,\n })) as StepExecutionAttempt;\n\n if (attempt.supported) {\n return {\n result: attempt.result,\n executor: 'actions',\n };\n }\n\n // Fall back to legacy\n if (this.config.logFallbacks) {\n options.pushLog?.({\n stepId: step.id,\n status: 'warning',\n message: `Falling back to legacy execution: ${attempt.reason}`,\n });\n }\n\n const legacyResult = await legacyExecuteStep(ctx, step);\n return {\n result: legacyResult || {},\n executor: 'legacy',\n fallback: true,\n fallbackReason: attempt.reason,\n };\n }\n\n supports(stepType: string): boolean {\n // Hybrid executor supports all types (via fallback)\n return true;\n }\n}\n\n/**\n * Factory function to create the appropriate executor based on config\n */\nexport function createExecutor(\n config: ExecutionModeConfig,\n registry?: ActionRegistry,\n): StepExecutorInterface {\n switch (config.mode) {\n case 'legacy':\n return new LegacyStepExecutor();\n\n case 'actions':\n if (!registry) {\n throw new Error('ActionRegistry required for actions execution mode');\n }\n return new ActionsStepExecutor(registry, config);\n\n case 'hybrid':\n if (!registry) {\n throw new Error('ActionRegistry required for hybrid execution mode');\n }\n return new HybridStepExecutor(registry, config);\n\n default: {\n // TypeScript exhaustiveness check\n const _exhaustive: never = config.mode;\n throw new Error(`Unknown execution mode: ${_exhaustive}`);\n }\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/runners/step-runner.ts", "content": "/**\n * step-runner.ts\n *\n * Encapsulates execution of a single step with policies (retry, navigation wait) and plugins.\n * Uses dependency-injected StepExecutorInterface for actual step execution, enabling\n * seamless switching between legacy and ActionRegistry execution modes.\n */\n\nimport type { Flow, Step, StepClick } from '../../types';\nimport { STEP_TYPES } from 'chrome-mcp-shared';\nimport type { ExecCtx, ExecResult } from '../../nodes';\nimport { RunLogger } from '../logging/run-logger';\nimport { withRetry } from '../policies/retry';\nimport {\n waitForNavigationDone,\n maybeQuickWaitForNav,\n ensureReadPageIfWeb,\n waitForNetworkIdle,\n} from '../policies/wait';\nimport { ENGINE_CONSTANTS } from '../constants';\nimport { AfterScriptQueue } from './after-script-queue';\nimport { PluginManager } from '../plugins/manager';\nimport type { HookControl } from '../plugins/types';\nimport type { StepExecutorInterface } from './step-executor';\n\n// Narrow error-like value used for overlay reporting\ninterface ErrorLike {\n message?: string;\n}\n\nfunction errorMessage(e: unknown): string {\n if (e instanceof Error) return e.message;\n if (e && typeof e === 'object' && 'message' in e) return String((e as any).message);\n return String(e);\n}\n\n/**\n * Environment dependencies for StepRunner.\n * Injected by Scheduler to allow flexible configuration and testing.\n */\nexport interface StepRunEnv {\n /** Unique identifier for this run */\n runId: string;\n /** The flow being executed */\n flow: Flow;\n /** Runtime variables */\n vars: Record;\n /** Run logger for recording execution events */\n logger: RunLogger;\n /** Plugin manager for hooks (beforeStep, afterStep, onRetry, onError) */\n pluginManager: PluginManager;\n /** Queue for deferred after-scripts */\n afterScripts: AfterScriptQueue;\n /** Returns remaining time budget from global deadline (ms), Infinity if no deadline */\n getRemainingBudgetMs: () => number;\n /**\n * Step executor for actual step execution.\n * Defaults to LegacyStepExecutor if not provided (for backwards compatibility).\n * In future, Scheduler will inject ActionsStepExecutor or HybridStepExecutor.\n */\n stepExecutor: StepExecutorInterface;\n}\n\nexport class StepRunner {\n constructor(private env: StepRunEnv) {}\n\n private async getActiveTabInfo(): Promise<{ url: string; status: string | '' }> {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tab = tabs[0];\n return { url: tab?.url || '', status: (tab?.status as string) || '' };\n }\n\n async run(\n ctx: ExecCtx,\n step: Step,\n appendOverlayOk: (s: Step) => Promise | void,\n appendOverlayFail: (s: Step, e: ErrorLike) => Promise | void,\n ): Promise<{\n status: 'success' | 'failed' | 'paused';\n nextLabel?: string;\n control?: ExecResult['control'];\n }> {\n const t0 = Date.now();\n let stepNextLabel: string | undefined;\n let controlOut: ExecResult['control'] | undefined = undefined;\n let ctrlStart: HookControl | undefined;\n try {\n ctrlStart = await this.env.pluginManager.beforeStep({\n runId: this.env.runId,\n flow: this.env.flow,\n vars: this.env.vars,\n step,\n });\n } catch (e: unknown) {\n this.env.logger.push({\n stepId: step.id,\n status: 'warning',\n message: `plugin.beforeStep error: ${errorMessage(e)}`,\n });\n }\n if (ctrlStart?.pause) return { status: 'paused' };\n\n const beforeInfo = await this.getActiveTabInfo();\n try {\n await withRetry(\n async () => {\n // Execute step via injected executor (legacy, actions, or hybrid)\n // tabId is expected to be set by Scheduler in ctx; fallback to active tab if missing\n let tabId = ctx.tabId;\n if (typeof tabId !== 'number') {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n tabId = tabs?.[0]?.id;\n }\n if (typeof tabId !== 'number') {\n throw new Error('No active tab found for step execution');\n }\n\n const execResult = await this.env.stepExecutor.execute(ctx, step, {\n tabId,\n runId: this.env.runId,\n pushLog: (entry) => this.env.logger.push(entry as any),\n remainingBudgetMs: this.env.getRemainingBudgetMs(),\n });\n const result = execResult.result;\n const remainingBudget = this.env.getRemainingBudgetMs();\n if (step.type === STEP_TYPES.CLICK || step.type === STEP_TYPES.DBLCLICK) {\n const after = step.after ?? ({} as NonNullable);\n if (after.waitForNavigation)\n await waitForNavigationDone(\n beforeInfo.url,\n Math.min(step.timeoutMs ?? ENGINE_CONSTANTS.DEFAULT_WAIT_MS, remainingBudget),\n );\n else if (after.waitForNetworkIdle) {\n const totalMs = Math.min(\n step.timeoutMs ?? ENGINE_CONSTANTS.DEFAULT_WAIT_MS,\n remainingBudget,\n );\n const idleMs = Math.min(1500, Math.max(500, Math.floor(totalMs / 3)));\n await waitForNetworkIdle(totalMs, idleMs);\n } else\n await maybeQuickWaitForNav(\n beforeInfo.url,\n Math.min(step.timeoutMs ?? ENGINE_CONSTANTS.DEFAULT_WAIT_MS, remainingBudget),\n );\n }\n if (step.type === STEP_TYPES.NAVIGATE || step.type === STEP_TYPES.OPEN_TAB) {\n await waitForNavigationDone(\n beforeInfo.url,\n Math.min(\n step.timeoutMs ?? ENGINE_CONSTANTS.DEFAULT_WAIT_MS,\n this.env.getRemainingBudgetMs(),\n ),\n );\n await ensureReadPageIfWeb();\n } else if (step.type === STEP_TYPES.SWITCH_TAB) {\n await ensureReadPageIfWeb();\n }\n if (!result?.alreadyLogged)\n this.env.logger.push({ stepId: step.id, status: 'success', tookMs: Date.now() - t0 });\n try {\n await this.env.pluginManager.afterStep({\n runId: this.env.runId,\n flow: this.env.flow,\n vars: this.env.vars,\n step,\n result,\n });\n } catch (e: unknown) {\n this.env.logger.push({\n stepId: step.id,\n status: 'warning',\n message: `plugin.afterStep error: ${errorMessage(e)}`,\n });\n }\n await appendOverlayOk(step);\n if (result?.nextLabel) stepNextLabel = String(result.nextLabel);\n if (result?.control) controlOut = result.control;\n if (result?.deferAfterScript) this.env.afterScripts.enqueue(result.deferAfterScript);\n await this.env.afterScripts.flush(ctx, this.env.vars);\n },\n async (attempt, e) => {\n this.env.logger.push({\n stepId: step.id,\n status: 'retrying',\n message: errorMessage(e),\n });\n try {\n await this.env.pluginManager.onRetry({\n runId: this.env.runId,\n flow: this.env.flow,\n vars: this.env.vars,\n step,\n error: e,\n attempt,\n });\n } catch (pe: unknown) {\n this.env.logger.push({\n stepId: step.id,\n status: 'warning',\n message: `plugin.onRetry error: ${errorMessage(pe)}`,\n });\n }\n },\n {\n count: Math.max(0, step.retry?.count ?? 0),\n intervalMs: Math.max(0, step.retry?.intervalMs ?? 0),\n backoff: step.retry?.backoff || 'none',\n },\n );\n } catch (e: unknown) {\n this.env.logger.push({\n stepId: step.id,\n status: 'failed',\n message: errorMessage(e),\n tookMs: Date.now() - t0,\n });\n await appendOverlayFail(step, e as ErrorLike);\n try {\n const hook = await this.env.pluginManager.onError({\n runId: this.env.runId,\n flow: this.env.flow,\n vars: this.env.vars,\n step,\n error: e,\n });\n if (hook?.pause) return { status: 'paused' };\n } catch (pe: unknown) {\n this.env.logger.push({\n stepId: step.id,\n status: 'warning',\n message: `plugin.onError error: ${errorMessage(pe)}`,\n });\n }\n return { status: 'failed' };\n }\n return { status: 'success', nextLabel: stepNextLabel, control: controlOut };\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/runners/subflow-runner.ts", "content": "// subflow-runner.ts — execute a subflow (nodes/edges) using DAG traversal with branch support\n\nimport { STEP_TYPES } from 'chrome-mcp-shared';\nimport type { ExecCtx } from '../../nodes';\nimport { RunLogger } from '../logging/run-logger';\nimport { PluginManager } from '../plugins/manager';\nimport { mapDagNodeToStep } from '../../rr-utils';\nimport type { Edge, NodeBase, Step } from '../../types';\nimport { StepRunner } from './step-runner';\nimport { ENGINE_CONSTANTS } from '../constants';\n\nexport interface SubflowEnv {\n runId: string;\n flow: any;\n vars: Record;\n logger: RunLogger;\n pluginManager: PluginManager;\n stepRunner: StepRunner;\n}\n\nexport class SubflowRunner {\n constructor(private env: SubflowEnv) {}\n\n async runSubflowById(subflowId: string, ctx: ExecCtx, pausedRef: () => boolean): Promise {\n const sub = (this.env.flow.subflows || {})[subflowId];\n if (!sub || !Array.isArray(sub.nodes) || sub.nodes.length === 0) return;\n\n try {\n await this.env.pluginManager.subflowStart({\n runId: this.env.runId,\n flow: this.env.flow,\n vars: this.env.vars,\n subflowId,\n });\n } catch (e: any) {\n this.env.logger.push({\n stepId: `subflow:${subflowId}`,\n status: 'warning',\n message: `plugin.subflowStart error: ${e?.message || String(e)}`,\n });\n }\n\n const sNodes: NodeBase[] = sub.nodes;\n const sEdges: Edge[] = sub.edges || [];\n\n // Build lookup maps\n const id2node = new Map(sNodes.map((n) => [n.id, n] as const));\n const outEdges = new Map();\n for (const e of sEdges) {\n if (!outEdges.has(e.from)) outEdges.set(e.from, []);\n outEdges.get(e.from)!.push(e);\n }\n\n // Calculate in-degrees to find root nodes\n const indeg = new Map(sNodes.map((n) => [n.id, 0] as const));\n for (const e of sEdges) {\n indeg.set(e.to, (indeg.get(e.to) || 0) + 1);\n }\n\n // Find start node: prefer non-trigger nodes with indeg=0\n const findFirstExecutableRoot = (): string | undefined => {\n const executableRoot = sNodes.find(\n (n) => (indeg.get(n.id) || 0) === 0 && n.type !== STEP_TYPES.TRIGGER,\n );\n if (executableRoot) return executableRoot.id;\n\n // If all roots are triggers, follow default edge to first executable\n const triggerRoot = sNodes.find((n) => (indeg.get(n.id) || 0) === 0);\n if (triggerRoot) {\n const defaultEdge = (outEdges.get(triggerRoot.id) || []).find(\n (e) => !e.label || e.label === ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT,\n );\n if (defaultEdge) return defaultEdge.to;\n }\n\n return sNodes[0]?.id;\n };\n\n let currentId: string | undefined = findFirstExecutableRoot();\n let guard = 0;\n const maxIterations = ENGINE_CONSTANTS.MAX_ITERATIONS;\n\n const ok = (s: Step) => this.env.logger.overlayAppend(`✔ ${s.type} (${s.id})`);\n const fail = (s: Step, e: any) =>\n this.env.logger.overlayAppend(`✘ ${s.type} (${s.id}) -> ${e?.message || String(e)}`);\n\n while (currentId) {\n if (pausedRef()) break;\n if (guard++ >= maxIterations) {\n this.env.logger.push({\n stepId: `subflow:${subflowId}`,\n status: 'warning',\n message: `Subflow exceeded ${maxIterations} iterations - possible cycle`,\n });\n break;\n }\n\n const node = id2node.get(currentId);\n if (!node) break;\n\n // Skip trigger nodes\n if (node.type === STEP_TYPES.TRIGGER) {\n const defaultEdge = (outEdges.get(currentId) || []).find(\n (e) => !e.label || e.label === ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT,\n );\n if (defaultEdge) {\n currentId = defaultEdge.to;\n continue;\n }\n break;\n }\n\n const step: Step = mapDagNodeToStep(node);\n const r = await this.env.stepRunner.run(ctx, step, ok, fail);\n\n if (r.status === 'paused' || pausedRef()) break;\n\n if (r.status === 'failed') {\n // Try to find on_error edge\n const errEdge = (outEdges.get(currentId) || []).find(\n (e) => e.label === ENGINE_CONSTANTS.EDGE_LABELS.ON_ERROR,\n );\n if (errEdge) {\n currentId = errEdge.to;\n continue;\n }\n break;\n }\n\n // Determine next edge by label\n const suggestedLabel = r.nextLabel\n ? String(r.nextLabel)\n : ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT;\n const oes = outEdges.get(currentId) || [];\n const nextEdge =\n oes.find((e) => (e.label || ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT) === suggestedLabel) ||\n oes.find((e) => !e.label || e.label === ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT);\n\n if (!nextEdge) {\n // Log warning if we expected a labeled edge but couldn't find it\n if (r.nextLabel && oes.length > 0) {\n const availableLabels = oes.map((e) => e.label || ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT);\n this.env.logger.push({\n stepId: step.id,\n status: 'warning',\n message: `No edge for label '${suggestedLabel}'. Available: [${availableLabels.join(', ')}]`,\n });\n }\n break;\n }\n currentId = nextEdge.to;\n }\n\n try {\n await this.env.pluginManager.subflowEnd({\n runId: this.env.runId,\n flow: this.env.flow,\n vars: this.env.vars,\n subflowId,\n });\n } catch (e: any) {\n this.env.logger.push({\n stepId: `subflow:${subflowId}`,\n status: 'warning',\n message: `plugin.subflowEnd error: ${e?.message || String(e)}`,\n });\n }\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/scheduler.ts", "content": "import { STEP_TYPES, TOOL_NAMES } from 'chrome-mcp-shared';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { Edge, Flow, NodeBase, RunLogEntry, RunResult, Step } from '../types';\nimport {\n mapDagNodeToStep,\n topoOrder,\n ensureTab,\n expandTemplatesDeep,\n defaultEdgesOnly,\n} from '../rr-utils';\nimport type { ExecCtx } from '../nodes';\nimport { RunLogger } from './logging/run-logger';\nimport { PluginManager } from './plugins/manager';\nimport type { RunPlugin } from './plugins/types';\nimport { breakpointPlugin } from './plugins/breakpoint';\nimport { evalExpression } from './utils/expression';\nimport { runState } from './state-manager';\nimport { AfterScriptQueue } from './runners/after-script-queue';\nimport { StepRunner } from './runners/step-runner';\nimport { ControlFlowRunner } from './runners/control-flow-runner';\nimport { SubflowRunner } from './runners/subflow-runner';\nimport { ENGINE_CONSTANTS, LOG_STEP_IDS } from './constants';\nimport {\n DEFAULT_EXECUTION_MODE_CONFIG,\n createActionsOnlyConfig,\n createHybridConfig,\n type ExecutionMode,\n type ExecutionModeConfig,\n} from './execution-mode';\nimport { createExecutor, type StepExecutorInterface } from './runners/step-executor';\nimport { createReplayActionRegistry } from '../actions/handlers';\n\nexport interface RunOptions {\n tabTarget?: 'current' | 'new';\n refresh?: boolean;\n captureNetwork?: boolean;\n returnLogs?: boolean;\n timeoutMs?: number;\n startUrl?: string;\n args?: Record;\n startNodeId?: string;\n plugins?: RunPlugin[];\n\n /**\n * Step execution mode switch.\n * - 'legacy': Use existing nodes/executeStep (default, safest)\n * - 'hybrid': Try ActionRegistry first, fall back to legacy\n * - 'actions': Use ActionRegistry exclusively (strict mode)\n */\n executionMode?: ExecutionMode;\n\n /**\n * Hybrid mode only: allowlist of step types executed via ActionRegistry.\n * - undefined: use MINIMAL_HYBRID_ACTION_TYPES (safest default)\n * - []: disable allowlist, fall back to MIGRATED_ACTION_TYPES policy\n * - ['fill', 'key', ...]: only these types use actions\n */\n actionsAllowlist?: string[];\n\n /**\n * Hybrid mode only: denylist of step types forced to legacy.\n * When omitted, createHybridConfig defaults to LEGACY_ONLY_TYPES.\n */\n legacyOnlyTypes?: string[];\n}\n\n/**\n * Type guard for ExecutionMode\n */\nfunction isExecutionMode(value: unknown): value is ExecutionMode {\n return value === 'legacy' || value === 'hybrid' || value === 'actions';\n}\n\n/**\n * Convert array to Set, filtering invalid values\n */\nfunction toStringSet(value: unknown): Set {\n const result = new Set();\n if (!Array.isArray(value)) return result;\n for (const item of value) {\n if (typeof item === 'string') {\n const trimmed = item.trim();\n if (trimmed) result.add(trimmed);\n }\n }\n return result;\n}\n\n/**\n * Build ExecutionModeConfig from RunOptions.\n * Defaults to legacy mode if executionMode is not specified.\n *\n * Note: Only array inputs for actionsAllowlist/legacyOnlyTypes are accepted.\n * Non-array values are ignored to prevent accidental misconfiguration\n * (e.g., passing a string instead of array would unexpectedly widen the allowlist).\n */\nfunction buildExecutionModeConfig(options: RunOptions): ExecutionModeConfig {\n const mode: ExecutionMode = isExecutionMode(options.executionMode)\n ? options.executionMode\n : DEFAULT_EXECUTION_MODE_CONFIG.mode;\n\n if (mode === 'hybrid') {\n const overrides: Partial = {};\n // Only apply override if it's a valid array\n // This prevents misconfiguration from widening the actions scope\n if (Array.isArray(options.actionsAllowlist)) {\n overrides.actionsAllowlist = toStringSet(options.actionsAllowlist);\n }\n if (Array.isArray(options.legacyOnlyTypes)) {\n overrides.legacyOnlyTypes = toStringSet(options.legacyOnlyTypes);\n }\n return createHybridConfig(overrides);\n }\n\n if (mode === 'actions') {\n return createActionsOnlyConfig();\n }\n\n // Default: legacy mode\n return { ...DEFAULT_EXECUTION_MODE_CONFIG };\n}\n\n/**\n * ExecutionOrchestrator manages the lifecycle of a flow execution.\n *\n * Architecture:\n * - Creates StepExecutor based on ExecutionModeConfig (legacy by default)\n * - Injects StepExecutor into StepRunner for step execution\n * - Manages tabId and passes it through ExecCtx\n * - Handles DAG traversal, control flow, and cleanup\n */\nclass ExecutionOrchestrator {\n private readonly runId = `run_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n private readonly startAt = Date.now();\n private readonly logger = new RunLogger(this.runId);\n private readonly pluginManager: PluginManager;\n private readonly afterScripts = new AfterScriptQueue(this.logger);\n\n // Execution mode configuration (defaults to legacy for safety)\n private readonly executionModeConfig: ExecutionModeConfig;\n private readonly stepExecutor: StepExecutorInterface;\n\n // Runtime state\n private vars: Record = Object.create(null);\n private tabId: number | null = null;\n private deadline = 0;\n private networkCaptureStarted = false;\n private paused = false;\n private failed = 0;\n private executed = 0;\n private steps: Step[] = [];\n private prepareError: RunResult | null = null;\n\n // Runners\n private stepRunner: StepRunner;\n private controlFlowRunner!: ControlFlowRunner;\n private subflowRunner!: SubflowRunner;\n\n constructor(\n private flow: Flow,\n private options: RunOptions = {},\n ) {\n // Initialize variables from flow defaults and args\n for (const v of flow.variables || []) {\n if (v.default !== undefined) this.vars[v.key] = v.default;\n }\n if (options.args) Object.assign(this.vars, options.args);\n\n // Set up global deadline\n const globalTimeout = Math.max(0, Number(options.timeoutMs || 0));\n this.deadline = globalTimeout > 0 ? this.startAt + globalTimeout : 0;\n\n // Initialize plugin manager\n this.pluginManager = new PluginManager(\n options.plugins && options.plugins.length ? options.plugins : [breakpointPlugin()],\n );\n\n // Create step executor based on execution mode configuration\n // Default to legacy mode for maximum safety during migration\n this.executionModeConfig = buildExecutionModeConfig(options);\n\n // Only create ActionRegistry when needed (hybrid or actions mode)\n // This avoids unnecessary initialization overhead in legacy mode\n const registry =\n this.executionModeConfig.mode === 'legacy' ? undefined : createReplayActionRegistry();\n this.stepExecutor = createExecutor(this.executionModeConfig, registry);\n\n // Initialize step runner with injected executor\n this.stepRunner = new StepRunner({\n runId: this.runId,\n flow: this.flow,\n vars: this.vars,\n logger: this.logger,\n pluginManager: this.pluginManager,\n afterScripts: this.afterScripts,\n getRemainingBudgetMs: () =>\n this.deadline > 0 ? Math.max(0, this.deadline - Date.now()) : Number.POSITIVE_INFINITY,\n stepExecutor: this.stepExecutor,\n });\n }\n\n private ensureWithinDeadline() {\n if (this.deadline > 0 && Date.now() > this.deadline) {\n const err = new Error('Global timeout reached');\n this.logger.push({\n stepId: LOG_STEP_IDS.GLOBAL_TIMEOUT,\n status: 'failed',\n message: 'Global timeout reached',\n });\n throw err;\n }\n }\n\n async run(): Promise {\n try {\n await this.prepareExecution();\n if (this.prepareError) return this.prepareError;\n return await this.traverseDag();\n } finally {\n await this.cleanup();\n }\n }\n\n private async prepareExecution() {\n // Derive default startUrl\n let derivedStartUrl: string | undefined;\n try {\n const hasDag0 = Array.isArray(this.flow.nodes) && (this.flow.nodes?.length || 0) > 0;\n const nodes0: NodeBase[] = hasDag0 ? this.flow.nodes || [] : [];\n const edges0: Edge[] = hasDag0 ? this.flow.edges || [] : [];\n const defaultEdges0 = hasDag0 ? defaultEdgesOnly(edges0) : [];\n const order0 = hasDag0 ? topoOrder(nodes0, defaultEdges0) : [];\n const steps0: Step[] = hasDag0 ? order0.map((n) => mapDagNodeToStep(n)) : [];\n const nav = steps0.find((s) => s.type === STEP_TYPES.NAVIGATE);\n if (nav && nav.type === STEP_TYPES.NAVIGATE)\n derivedStartUrl = expandTemplatesDeep(nav.url, this.vars);\n } catch {\n // ignore: best-effort derive startUrl\n }\n\n const ensured = await ensureTab({\n tabTarget: this.options.tabTarget,\n startUrl: this.options.startUrl || derivedStartUrl,\n refresh: this.options.refresh,\n });\n // Capture tabId for use in ExecCtx\n this.tabId = ensured?.tabId ?? null;\n\n // register run state\n await runState.restore();\n await runState.add(this.runId, {\n id: this.runId,\n flowId: this.flow.id,\n name: this.flow.name,\n status: 'running',\n startedAt: this.startAt,\n updatedAt: this.startAt,\n });\n\n try {\n await this.pluginManager.runStart({ runId: this.runId, flow: this.flow, vars: this.vars });\n } catch (e: any) {\n this.logger.push({\n stepId: LOG_STEP_IDS.PLUGIN_RUN_START,\n status: 'warning',\n message: e?.message || String(e),\n });\n }\n\n // pre-load read_page when on web\n try {\n const u = ensured?.url || '';\n if (/^(https?:|file:)/i.test(u))\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n } catch {\n // ignore: preloading read_page is best-effort\n }\n\n // overlay variable collection\n try {\n const needed = (this.flow.variables || []).filter(\n (v) =>\n (this.options.args?.[v.key] == null || this.options.args?.[v.key] === '') &&\n (v.rules?.required || (v.default ?? '') === ''),\n );\n if (needed.length) {\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.SEND_COMMAND_TO_INJECT_SCRIPT,\n args: {\n eventName: TOOL_MESSAGE_TYPES.COLLECT_VARIABLES,\n payload: JSON.stringify({ variables: needed, useOverlay: true }),\n },\n });\n let values: Record | null = null;\n try {\n const t = (res?.content || []).find((c: any) => c.type === 'text')?.text;\n const j = t ? JSON.parse(t) : null;\n if (j && j.success && j.values) values = j.values;\n } catch {\n // ignore: parse result from tool response\n }\n if (!values) {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId === 'number') {\n const res2 = await chrome.tabs.sendMessage(tabId, {\n action: TOOL_MESSAGE_TYPES.COLLECT_VARIABLES,\n variables: needed,\n useOverlay: true,\n });\n if (res2 && res2.success && res2.values) values = res2.values;\n }\n }\n if (values) Object.assign(this.vars, values);\n else\n this.logger.push({\n stepId: LOG_STEP_IDS.VARIABLE_COLLECT,\n status: 'warning',\n message: 'Variable collection failed; using provided args/defaults',\n });\n }\n } catch {\n // ignore: variable collection is optional\n }\n\n await this.logger.overlayInit();\n\n // binding enforcement\n try {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const currentUrl = tabs?.[0]?.url || '';\n const bindings = this.flow.meta?.bindings || [];\n if (!this.options.startUrl && bindings.length > 0) {\n const ok = bindings.some((b) => {\n try {\n if (b.type === 'domain') return new URL(currentUrl).hostname.includes(b.value);\n if (b.type === 'path') return new URL(currentUrl).pathname.startsWith(b.value);\n if (b.type === 'url') return currentUrl.startsWith(b.value);\n } catch {\n // ignore: URL parsing for binding check\n }\n return false;\n });\n if (!ok) {\n this.prepareError = {\n runId: this.runId,\n success: false,\n summary: { total: 0, success: 0, failed: 0, tookMs: 0 },\n url: currentUrl,\n outputs: null,\n logs: [\n {\n stepId: LOG_STEP_IDS.BINDING_CHECK,\n status: 'failed',\n message:\n 'Flow binding mismatch. Provide startUrl or open a page matching flow.meta.bindings.',\n },\n ],\n screenshots: { onFailure: null },\n paused: false,\n };\n return;\n }\n }\n } catch {\n // ignore: binding enforcement failures fall back to default behavior\n }\n\n // network capture start\n if (this.options.captureNetwork) {\n try {\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.NETWORK_DEBUGGER_START,\n args: { includeStatic: false, maxCaptureTime: 3 * 60_000, inactivityTimeout: 0 },\n });\n let started = false;\n try {\n const t = res?.content?.find?.((c: any) => c.type === 'text')?.text;\n if (t) {\n const j = JSON.parse(t);\n started = !!j?.success;\n }\n } catch {\n // ignore: parse network debugger start response\n }\n this.networkCaptureStarted = started;\n if (!started) {\n this.logger.push({\n stepId: LOG_STEP_IDS.NETWORK_CAPTURE,\n status: 'warning',\n message: 'Failed to confirm network capture start',\n });\n }\n } catch (e: any) {\n this.logger.push({\n stepId: LOG_STEP_IDS.NETWORK_CAPTURE,\n status: 'warning',\n message: e?.message || 'Network capture start errored',\n });\n }\n }\n\n // build DAG steps\n const hasDag = Array.isArray(this.flow.nodes) && (this.flow.nodes?.length || 0) > 0;\n if (!hasDag) {\n this.prepareError = {\n runId: this.runId,\n success: false,\n summary: { total: 0, success: 0, failed: 0, tookMs: 0 },\n url: null,\n outputs: null,\n logs: [\n {\n stepId: LOG_STEP_IDS.DAG_REQUIRED,\n status: 'failed',\n message:\n 'Flow has no DAG nodes. Linear steps are no longer supported. Please migrate this flow to nodes/edges.',\n },\n ],\n screenshots: { onFailure: null },\n paused: false,\n };\n return;\n }\n const nodes: NodeBase[] = (this.flow.nodes || []) as NodeBase[];\n const edges: Edge[] = (this.flow.edges || []) as Edge[];\n // Validate DAG for potential cycles on full edge set\n try {\n if (this.hasCycle(nodes, edges)) {\n this.prepareError = {\n runId: this.runId,\n success: false,\n summary: { total: 0, success: 0, failed: 0, tookMs: 0 },\n url: null,\n outputs: null,\n logs: [\n {\n stepId: LOG_STEP_IDS.DAG_CYCLE,\n status: 'failed',\n message:\n 'Flow DAG contains a cycle. Please break the cycle or add explicit labels/branches to avoid infinite loops.',\n },\n ],\n screenshots: { onFailure: null },\n paused: false,\n };\n return;\n }\n } catch {\n // ignore: cycle detection guard\n }\n const defaultEdges = defaultEdgesOnly(edges);\n const order = topoOrder(nodes, defaultEdges);\n // Filter out trigger nodes - they are configuration nodes, not executable steps\n this.steps = order.filter((n) => n.type !== STEP_TYPES.TRIGGER).map((n) => mapDagNodeToStep(n));\n // initialize runners\n this.subflowRunner = new SubflowRunner({\n runId: this.runId,\n flow: this.flow,\n vars: this.vars,\n logger: this.logger,\n pluginManager: this.pluginManager,\n stepRunner: this.stepRunner,\n });\n this.controlFlowRunner = new ControlFlowRunner({\n vars: this.vars,\n logger: this.logger,\n evalCondition: (c) => this.evalCondition(c),\n runSubflowById: (id, ctx) => this.subflowRunner.runSubflowById(id, ctx, () => this.paused),\n isPaused: () => this.paused,\n });\n }\n\n // Basic cycle detection using DFS coloring on the full edge set\n private hasCycle(\n nodes: Array<{ id: string }>,\n edges: Array<{ from: string; to: string }>,\n ): boolean {\n const adj = new Map();\n for (const n of nodes) adj.set(n.id, []);\n for (const e of edges) {\n if (!adj.has(e.from)) adj.set(e.from, []);\n adj.get(e.from)!.push(e.to);\n }\n const color = new Map(); // 0=unvisited,1=visiting,2=done\n const visit = (u: string): boolean => {\n const c = color.get(u) || 0;\n if (c === 1) return true; // back-edge\n if (c === 2) return false;\n color.set(u, 1);\n for (const v of adj.get(u) || []) if (visit(v)) return true;\n color.set(u, 2);\n return false;\n };\n for (const n of nodes) if ((color.get(n.id) || 0) === 0 && visit(n.id)) return true;\n return false;\n }\n\n private async traverseDag(): Promise {\n if (!this.steps.length) {\n await this.logger.overlayDone();\n const tookMs0 = Date.now() - this.startAt;\n return (\n this.prepareError || {\n runId: this.runId,\n success: false,\n summary: { total: 0, success: 0, failed: 0, tookMs: tookMs0 },\n url: null,\n outputs: null,\n logs: this.options.returnLogs ? this.logger.getLogs() : undefined,\n screenshots: { onFailure: null },\n paused: false,\n }\n );\n }\n const nodes: NodeBase[] = this.flow.nodes || [];\n const edges: Edge[] = this.flow.edges || [];\n const id2node = new Map(nodes.map((n) => [n.id, n] as const));\n const outEdges = new Map>();\n for (const e of edges) {\n if (!outEdges.has(e.from)) outEdges.set(e.from, []);\n outEdges.get(e.from)!.push(e);\n }\n const indeg = new Map(nodes.map((n) => [n.id, 0] as const));\n for (const e of edges) indeg.set(e.to, (indeg.get(e.to) || 0) + 1);\n // Find start node: prefer non-trigger nodes with indeg=0\n // Trigger nodes are configuration nodes and should be skipped\n const findFirstExecutableRoot = (): string | undefined => {\n // First try to find a non-trigger root node\n const executableRoot = nodes.find(\n (n) => (indeg.get(n.id) || 0) === 0 && n.type !== STEP_TYPES.TRIGGER,\n );\n if (executableRoot) return executableRoot.id;\n\n // If all roots are triggers, find one and follow default edge to first executable\n const triggerRoot = nodes.find((n) => (indeg.get(n.id) || 0) === 0);\n if (triggerRoot) {\n const defaultEdge = (outEdges.get(triggerRoot.id) || []).find(\n (e) => !e.label || e.label === ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT,\n );\n if (defaultEdge) return defaultEdge.to;\n }\n\n // Fallback to first node\n return nodes[0]?.id;\n };\n\n let currentId: string | undefined =\n this.options.startNodeId && id2node.has(this.options.startNodeId)\n ? this.options.startNodeId\n : findFirstExecutableRoot();\n let guard = 0;\n\n // Create execution context with tabId from ensureTab\n // tabId is managed by Scheduler and may be updated by openTab/switchTab actions\n const ctx: ExecCtx = {\n vars: this.vars,\n tabId: this.tabId ?? undefined,\n logger: (e: RunLogEntry) => this.logger.push(e),\n };\n if (currentId) {\n try {\n await this.logger.overlayAppend(\n `▶ start at ${id2node.get(currentId)?.type || ''} (${currentId})`,\n );\n } catch {\n // ignore: eval condition failure treated as false\n }\n }\n while (currentId) {\n this.ensureWithinDeadline();\n if (guard++ >= ENGINE_CONSTANTS.MAX_ITERATIONS) {\n this.logger.push({\n stepId: LOG_STEP_IDS.LOOP_GUARD,\n status: 'failed',\n message: `Exceeded ${ENGINE_CONSTANTS.MAX_ITERATIONS} iterations - possible cycle in DAG`,\n });\n this.failed++;\n break;\n }\n const node = id2node.get(currentId);\n if (!node) break;\n\n // Skip trigger nodes - they are configuration nodes, not executable steps\n // Follow default edge to the next executable node\n if (node.type === STEP_TYPES.TRIGGER) {\n try {\n await this.logger.overlayAppend(`⏭ skip trigger (${node.id})`);\n } catch {}\n const defaultEdge = (outEdges.get(currentId) || []).find(\n (e) => !e.label || e.label === ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT,\n );\n if (defaultEdge) {\n currentId = defaultEdge.to;\n continue;\n }\n // No successor after trigger - end execution\n this.logger.push({\n stepId: node.id,\n status: 'warning',\n message: 'Trigger node has no successor - nothing to execute',\n });\n break;\n }\n\n const step: Step = mapDagNodeToStep(node);\n // lightweight trace to aid debugging edge traversal\n try {\n await this.logger.overlayAppend(`→ ${step.type} (${step.id})`);\n } catch {\n // ignore: stopping network capture is best-effort\n }\n // Count this step as executed (regardless of success/failure)\n this.executed++;\n\n const r = await this.stepRunner.run(\n ctx,\n step,\n (s) => this.logger.overlayAppend(`✔ ${s.type} (${s.id})`),\n (s, e) => this.logger.overlayAppend(`✘ ${s.type} (${s.id}) -> ${e?.message || String(e)}`),\n );\n if (r.status === 'paused') {\n this.paused = true;\n break;\n }\n if (r.status === 'failed') {\n this.failed++;\n const oes = (outEdges.get(currentId) || []) as Edge[];\n const errEdge = oes.find((edg) => edg.label === ENGINE_CONSTANTS.EDGE_LABELS.ON_ERROR);\n if (errEdge) {\n currentId = errEdge.to;\n continue;\n } else {\n break;\n }\n }\n if (r.control) {\n const control = r.control;\n const st = await this.controlFlowRunner.run(control, ctx);\n if (st === 'paused') {\n this.paused = true;\n break;\n }\n const suggested = r.nextLabel ? String(r.nextLabel) : ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT;\n const next = await this.advanceToNext(currentId, step, suggested, id2node, outEdges);\n if (!next) break;\n currentId = next;\n continue;\n }\n // choose next by label\n {\n const suggested = r.nextLabel ? String(r.nextLabel) : ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT;\n const next = await this.advanceToNext(currentId, step, suggested, id2node, outEdges);\n if (!next) break;\n currentId = next;\n }\n }\n const tookMs = Date.now() - this.startAt;\n const sensitiveKeys = new Set(\n (this.flow.variables || []).filter((v) => v.sensitive).map((v) => v.key),\n );\n const outputs: Record = {};\n for (const [k, v] of Object.entries(this.vars)) if (!sensitiveKeys.has(k)) outputs[k] = v;\n return {\n runId: this.runId,\n success: !this.paused && this.failed === 0,\n summary: {\n total: this.executed,\n success: this.executed - this.failed,\n failed: this.failed,\n tookMs,\n },\n url: null,\n outputs,\n logs: this.options.returnLogs ? this.logger.getLogs() : undefined,\n screenshots: {\n onFailure: this.logger.getLogs().find((l) => l.status === 'failed')?.screenshotBase64,\n },\n paused: this.paused,\n };\n }\n\n // Advance to next node by suggested label, with overlay/logging and fallback to default edge.\n private async advanceToNext(\n currentId: string,\n step: Step,\n suggested: string,\n id2node: Map,\n outEdges: Map>,\n ): Promise {\n const nextLabel = await this.chooseNextLabel(step, suggested);\n const nextId = this.findNextNodeId(currentId, outEdges, nextLabel);\n if (nextId) {\n try {\n await this.logger.overlayAppend(\n `↪ next(${nextLabel}) → ${id2node.get(nextId)?.type || ''} (${nextId})`,\n );\n } catch {}\n return nextId;\n }\n const labels = (outEdges.get(currentId) || []).map((e) =>\n String(e.label || ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT),\n );\n this.logger.push({\n stepId: step.id,\n status: 'warning',\n message: `No next edge for label '${nextLabel}'. Outgoing labels: [${labels.join(', ')}]`,\n });\n return undefined;\n }\n\n // Decide next label, allowing plugins to override; logs plugin errors as warnings\n private async chooseNextLabel(step: Step, suggested: string): Promise {\n try {\n const override = await this.pluginManager.onChooseNextLabel({\n runId: this.runId,\n flow: this.flow,\n vars: this.vars,\n step,\n suggested,\n });\n return override ? String(override) : suggested;\n } catch (e: any) {\n this.logger.push({\n stepId: step.id,\n status: 'warning',\n message: `plugin.onChooseNextLabel error: ${e?.message || String(e)}`,\n });\n return suggested;\n }\n }\n\n // From current node and label, pick next nodeId using outEdges; prefers labeled edge then default\n private findNextNodeId(\n currentId: string,\n outEdges: Map>,\n nextLabel: string,\n ): string | undefined {\n const oes = (outEdges.get(currentId) || []) as Edge[];\n const edge =\n oes.find((e) => String(e.label || ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT) === nextLabel) ||\n oes.find((e) => !e.label || e.label === ENGINE_CONSTANTS.EDGE_LABELS.DEFAULT);\n return edge ? edge.to : undefined;\n }\n\n private evalCondition(cond: any): boolean {\n try {\n if (cond && typeof cond.expression === 'string' && cond.expression.trim()) {\n return !!evalExpression(String(cond.expression), { vars: this.vars });\n }\n if (cond && typeof cond.var === 'string') {\n const v = this.vars[cond.var];\n if ('equals' in cond) return String(v) === String(cond.equals);\n return !!v;\n }\n } catch {\n // ignore: cleanup guard\n }\n return false;\n }\n\n private async cleanup() {\n if (this.networkCaptureStarted) {\n try {\n const stopRes = await handleCallTool({\n name: TOOL_NAMES.BROWSER.NETWORK_DEBUGGER_STOP,\n args: {},\n });\n const text = (stopRes?.content || []).find((c: any) => c.type === 'text')?.text;\n if (text) {\n try {\n const data = JSON.parse(text);\n const requests: any[] = Array.isArray(data?.requests) ? data.requests : [];\n const snippets = requests\n .filter((r) => ['XHR', 'Fetch'].includes(String(r.type)))\n .slice(0, 10)\n .map((r) => ({\n method: String(r.method || 'GET'),\n url: String(r.url || ''),\n status: r.statusCode || r.status,\n ms: Math.max(0, (r.responseTime || 0) - (r.requestTime || 0)),\n }));\n this.logger.push({\n stepId: LOG_STEP_IDS.NETWORK_CAPTURE,\n status: 'success',\n message: `Captured ${Number(data?.requestCount || 0)} requests`,\n networkSnippets: snippets,\n });\n } catch (e: any) {\n this.logger.push({\n stepId: LOG_STEP_IDS.NETWORK_CAPTURE,\n status: 'warning',\n message: `Failed parsing network capture result: ${e?.message || String(e)}`,\n });\n }\n }\n } catch {}\n }\n await this.logger.overlayDone();\n try {\n try {\n await this.pluginManager.runEnd({\n runId: this.runId,\n flow: this.flow,\n vars: this.vars,\n success: this.failed === 0 && !this.paused,\n failed: this.failed,\n });\n } catch (e: any) {\n this.logger.push({\n stepId: LOG_STEP_IDS.PLUGIN_RUN_END,\n status: 'warning',\n message: e?.message || String(e),\n });\n }\n if (!this.paused) await this.logger.persist(this.flow, this.startAt, this.failed === 0);\n try {\n await runState.update(this.runId, {\n status: this.paused ? 'stopped' : this.failed === 0 ? 'completed' : 'failed',\n updatedAt: Date.now(),\n });\n } catch (e: any) {\n this.logger.push({\n stepId: LOG_STEP_IDS.RUNSTATE_UPDATE,\n status: 'warning',\n message: e?.message || String(e),\n });\n }\n try {\n if (!this.paused) await runState.delete(this.runId);\n } catch (e: any) {\n this.logger.push({\n stepId: LOG_STEP_IDS.RUNSTATE_DELETE,\n status: 'warning',\n message: e?.message || String(e),\n });\n }\n } catch {}\n }\n}\n\nexport async function runFlow(flow: Flow, options: RunOptions = {}): Promise {\n const orchestrator = new ExecutionOrchestrator(flow, options);\n return await orchestrator.run();\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/state-manager.ts", "content": "// engine/state-manager.ts — lightweight run state store with events and persistence\n\ntype Listener = (payload: T) => void;\n\nexport interface RunState {\n id: string;\n flowId: string;\n name?: string;\n status: 'running' | 'completed' | 'failed' | 'stopped';\n startedAt: number;\n updatedAt: number;\n}\n\nexport class StateManager {\n private key: string;\n private states = new Map();\n private listeners: Record[]> = Object.create(null);\n\n constructor(storageKey: string) {\n this.key = storageKey;\n }\n\n on(name: string, listener: Listener) {\n (this.listeners[name] = this.listeners[name] || []).push(listener);\n }\n\n off(name: string, listener: Listener) {\n const arr = this.listeners[name];\n if (!arr) return;\n const i = arr.indexOf(listener as any);\n if (i >= 0) arr.splice(i, 1);\n }\n\n private emit(name: string, payload: E) {\n const arr = this.listeners[name] || [];\n for (const fn of arr)\n try {\n fn(payload);\n } catch {}\n }\n\n getAll(): Map {\n return this.states;\n }\n\n get(id: string): T | undefined {\n return this.states.get(id);\n }\n\n async add(id: string, data: T): Promise {\n this.states.set(id, data);\n this.emit('add', { id, data });\n await this.persist();\n }\n\n async update(id: string, patch: Partial): Promise {\n const cur = this.states.get(id);\n if (!cur) return;\n const next = Object.assign({}, cur, patch);\n this.states.set(id, next);\n this.emit('update', { id, data: next });\n await this.persist();\n }\n\n async delete(id: string): Promise {\n this.states.delete(id);\n this.emit('delete', { id });\n await this.persist();\n }\n\n private async persist(): Promise {\n try {\n const obj = Object.fromEntries(this.states.entries());\n await chrome.storage.local.set({ [this.key]: obj });\n } catch {}\n }\n\n async restore(): Promise {\n try {\n const res = await chrome.storage.local.get(this.key);\n const obj = (res && res[this.key]) || {};\n this.states = new Map(Object.entries(obj) as any);\n } catch {}\n }\n}\n\nexport const runState = new StateManager('rr_run_states');\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/engine/utils/expression.ts", "content": "// expression.ts — minimal safe boolean expression evaluator (no access to global scope)\n// Supported:\n// - Literals: numbers (123, 1.23), strings ('x' or \"x\"), booleans (true/false)\n// - Variables: vars.x, vars.a.b (only reads from provided vars object)\n// - Operators: !, &&, ||, ==, !=, >, >=, <, <=, +, -, *, /\n// - Parentheses: ( ... )\n\ntype Token = { type: string; value?: any };\n\nfunction tokenize(input: string): Token[] {\n const s = input.trim();\n const out: Token[] = [];\n let i = 0;\n const isAlpha = (c: string) => /[a-zA-Z_]/.test(c);\n const isNum = (c: string) => /[0-9]/.test(c);\n const isIdChar = (c: string) => /[a-zA-Z0-9_]/.test(c);\n while (i < s.length) {\n const c = s[i];\n if (c === ' ' || c === '\\t' || c === '\\n' || c === '\\r') {\n i++;\n continue;\n }\n // operators\n if (\n s.startsWith('&&', i) ||\n s.startsWith('||', i) ||\n s.startsWith('==', i) ||\n s.startsWith('!=', i) ||\n s.startsWith('>=', i) ||\n s.startsWith('<=', i)\n ) {\n out.push({ type: 'op', value: s.slice(i, i + 2) });\n i += 2;\n continue;\n }\n if ('!+-*/()<>'.includes(c)) {\n out.push({ type: 'op', value: c });\n i++;\n continue;\n }\n // number\n if (isNum(c) || (c === '.' && isNum(s[i + 1] || ''))) {\n let j = i + 1;\n while (j < s.length && (isNum(s[j]) || s[j] === '.')) j++;\n out.push({ type: 'num', value: parseFloat(s.slice(i, j)) });\n i = j;\n continue;\n }\n // string\n if (c === '\"' || c === \"'\") {\n const quote = c;\n let j = i + 1;\n let str = '';\n while (j < s.length) {\n if (s[j] === '\\\\' && j + 1 < s.length) {\n str += s[j + 1];\n j += 2;\n } else if (s[j] === quote) {\n j++;\n break;\n } else {\n str += s[j++];\n }\n }\n out.push({ type: 'str', value: str });\n i = j;\n continue;\n }\n // identifier (vars or true/false)\n if (isAlpha(c)) {\n let j = i + 1;\n while (j < s.length && isIdChar(s[j])) j++;\n let id = s.slice(i, j);\n // dotted path\n while (s[j] === '.' && isAlpha(s[j + 1] || '')) {\n let k = j + 1;\n while (k < s.length && isIdChar(s[k])) k++;\n id += s.slice(j, k);\n j = k;\n }\n out.push({ type: 'id', value: id });\n i = j;\n continue;\n }\n // unknown token, skip to avoid crash\n i++;\n }\n return out;\n}\n\n// Recursive descent parser\nexport function evalExpression(expr: string, scope: { vars: Record }): any {\n const tokens = tokenize(expr);\n let i = 0;\n const peek = () => tokens[i];\n const consume = () => tokens[i++];\n\n function parsePrimary(): any {\n const t = peek();\n if (!t) return undefined;\n if (t.type === 'num') {\n consume();\n return t.value;\n }\n if (t.type === 'str') {\n consume();\n return t.value;\n }\n if (t.type === 'id') {\n consume();\n const id = String(t.value);\n if (id === 'true') return true;\n if (id === 'false') return false;\n // Only allow vars.* lookups\n if (!id.startsWith('vars')) return undefined;\n try {\n const parts = id.split('.').slice(1);\n let cur: any = scope.vars;\n for (const p of parts) {\n if (cur == null) return undefined;\n cur = cur[p];\n }\n return cur;\n } catch {\n return undefined;\n }\n }\n if (t.type === 'op' && t.value === '(') {\n consume();\n const v = parseOr();\n if (peek()?.type === 'op' && peek()?.value === ')') consume();\n return v;\n }\n return undefined;\n }\n\n function parseUnary(): any {\n const t = peek();\n if (t && t.type === 'op' && (t.value === '!' || t.value === '-')) {\n consume();\n const v = parseUnary();\n return t.value === '!' ? !truthy(v) : -Number(v || 0);\n }\n return parsePrimary();\n }\n\n function parseMulDiv(): any {\n let v = parseUnary();\n while (peek() && peek().type === 'op' && (peek().value === '*' || peek().value === '/')) {\n const op = consume().value;\n const r = parseUnary();\n v = op === '*' ? Number(v || 0) * Number(r || 0) : Number(v || 0) / Number(r || 0);\n }\n return v;\n }\n\n function parseAddSub(): any {\n let v = parseMulDiv();\n while (peek() && peek().type === 'op' && (peek().value === '+' || peek().value === '-')) {\n const op = consume().value;\n const r = parseMulDiv();\n v = op === '+' ? Number(v || 0) + Number(r || 0) : Number(v || 0) - Number(r || 0);\n }\n return v;\n }\n\n function parseRel(): any {\n let v = parseAddSub();\n while (peek() && peek().type === 'op' && ['>', '>=', '<', '<='].includes(peek().value)) {\n const op = consume().value as string;\n const r = parseAddSub();\n const a = toComparable(v);\n const b = toComparable(r);\n if (op === '>') v = (a as any) > (b as any);\n else if (op === '>=') v = (a as any) >= (b as any);\n else if (op === '<') v = (a as any) < (b as any);\n else v = (a as any) <= (b as any);\n }\n return v;\n }\n\n function parseEq(): any {\n let v = parseRel();\n while (peek() && peek().type === 'op' && (peek().value === '==' || peek().value === '!=')) {\n const op = consume().value as string;\n const r = parseRel();\n const a = toComparable(v);\n const b = toComparable(r);\n v = op === '==' ? a === b : a !== b;\n }\n return v;\n }\n\n function parseAnd(): any {\n let v = parseEq();\n while (peek() && peek().type === 'op' && peek().value === '&&') {\n consume();\n const r = parseEq();\n v = truthy(v) && truthy(r);\n }\n return v;\n }\n\n function parseOr(): any {\n let v = parseAnd();\n while (peek() && peek().type === 'op' && peek().value === '||') {\n consume();\n const r = parseAnd();\n v = truthy(v) || truthy(r);\n }\n return v;\n }\n\n function truthy(v: any) {\n return !!v;\n }\n function toComparable(v: any) {\n return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' ? v : String(v);\n }\n\n try {\n const res = parseOr();\n return res;\n } catch {\n return false;\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/flow-runner.ts", "content": "// thin re-export for backward compatibility\nexport { runFlow } from './engine/scheduler';\nexport type { RunOptions } from './engine/scheduler';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/flow-store.ts", "content": "import type { Flow, RunRecord, NodeBase, Edge } from './types';\nimport { stepsToDAG, type RRNode, type RREdge } from 'chrome-mcp-shared';\nimport { NODE_TYPES } from '@/common/node-types';\nimport { BACKGROUND_MESSAGE_TYPES } from '@/common/message-types';\nimport { IndexedDbStorage, ensureMigratedFromLocal } from './storage/indexeddb-manager';\n\n// Design note: IndexedDB-backed store for flows and run records.\n// Includes lazy migration from chrome.storage.local for backwards compatibility.\n\n// Validate if a type string is a valid NodeType\nconst VALID_NODE_TYPES = new Set(Object.values(NODE_TYPES));\nfunction isValidNodeType(type: string): boolean {\n return VALID_NODE_TYPES.has(type);\n}\n\n// Convert RRNode to NodeBase (ui coordinates are optional, not added here)\nfunction toNodeBase(node: RRNode): NodeBase {\n return {\n id: node.id,\n type: isValidNodeType(node.type) ? (node.type as NodeBase['type']) : NODE_TYPES.SCRIPT,\n config: node.config,\n };\n}\n\n// Convert RREdge to Edge\nfunction toEdge(edge: RREdge): Edge {\n return {\n id: edge.id,\n from: edge.from,\n to: edge.to,\n label: edge.label,\n };\n}\n\n/**\n * Filter edges to only keep those whose from/to both exist in nodeIds.\n * Prevents topoOrder crash when edges reference non-existent nodes.\n */\nfunction filterValidEdges(edges: Edge[], nodeIds: Set): Edge[] {\n return edges.filter((e) => nodeIds.has(e.from) && nodeIds.has(e.to));\n}\n\n// =============================================================================\n// UI Notification\n// =============================================================================\n\n/**\n * Timer handle for coalescing flow change notifications.\n * Prevents multiple rapid changes (e.g., during import) from flooding UI.\n */\nlet flowsChangedTimer: ReturnType | undefined;\n\n/**\n * Notify UI that flows have changed.\n * Uses a short debounce (50ms) to coalesce rapid changes.\n */\nfunction notifyFlowsChanged(): void {\n // If timer is already scheduled, skip (will be handled by pending timer)\n if (flowsChangedTimer !== undefined) return;\n\n flowsChangedTimer = setTimeout(() => {\n flowsChangedTimer = undefined;\n try {\n // Send message to all extension contexts (popup, sidepanel, etc.)\n // Use void cast to avoid unhandled promise rejection\n void chrome.runtime\n .sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.RR_FLOWS_CHANGED,\n })\n .catch(() => {\n // Ignore errors - no listeners is expected when UI is closed\n });\n } catch {\n // Ignore errors (e.g., if chrome.runtime is not available)\n }\n }, 50);\n}\n\n/**\n * Strip deprecated steps field before persisting to IndexedDB.\n * This ensures new saves only contain the DAG model (nodes/edges).\n *\n * @param flow - Flow with or without steps\n * @returns Flow without steps field (omit entirely, not set to empty array)\n */\nfunction stripStepsForSave(flow: Flow): Flow {\n if (!('steps' in flow)) {\n return flow;\n }\n\n const { steps: _steps, ...rest } = flow;\n return rest as Flow;\n}\n\n/**\n * Normalize flow before saving: ensure nodes/edges exist for scheduler compatibility.\n * Only generates DAG from steps if nodes are missing or empty.\n * Preserves existing nodes/edges to avoid overwriting user edits.\n *\n * Also validates edges: removes edges referencing non-existent nodes to prevent\n * runtime errors in scheduler's topoOrder calculation.\n */\nfunction normalizeFlowForSave(flow: Flow): Flow {\n const hasNodes = Array.isArray(flow.nodes) && flow.nodes.length > 0;\n if (hasNodes) {\n // Validate edges even when nodes exist (e.g., imported flows may have invalid edges)\n const nodeIds = new Set(flow.nodes!.map((n) => n.id));\n if (Array.isArray(flow.edges) && flow.edges.length > 0) {\n const validEdges = filterValidEdges(flow.edges, nodeIds);\n if (validEdges.length !== flow.edges.length) {\n // Some edges were invalid, return cleaned flow\n return { ...flow, edges: validEdges };\n }\n }\n return flow;\n }\n\n // No nodes - generate from steps\n if (!Array.isArray(flow.steps) || flow.steps.length === 0) {\n return flow;\n }\n\n const dag = stepsToDAG(flow.steps);\n if (dag.nodes.length === 0) {\n return flow;\n }\n\n const nodes: NodeBase[] = dag.nodes.map(toNodeBase);\n const nodeIds = new Set(nodes.map((n) => n.id));\n\n // Validate existing edges: only keep if from/to both exist in new nodes\n // Otherwise fall back to generated chain edges\n let edges: Edge[];\n if (Array.isArray(flow.edges) && flow.edges.length > 0) {\n const validEdges = filterValidEdges(flow.edges, nodeIds);\n edges = validEdges.length > 0 ? validEdges : dag.edges.map(toEdge);\n } else {\n edges = dag.edges.map(toEdge);\n }\n\n return {\n ...flow,\n nodes,\n edges,\n };\n}\n\nexport interface PublishedFlowInfo {\n id: string;\n slug: string; // for tool name `flow.`\n version: number;\n name: string;\n description?: string;\n}\n\n/**\n * Check if a flow needs normalization (missing nodes when steps exist).\n */\nfunction needsNormalization(flow: Flow): boolean {\n const hasSteps = Array.isArray(flow.steps) && flow.steps.length > 0;\n const hasNodes = Array.isArray(flow.nodes) && flow.nodes.length > 0;\n return hasSteps && !hasNodes;\n}\n\n/**\n * Lazy normalize a flow if needed, and persist the normalized version.\n * This handles legacy flows that only have steps but no nodes.\n * After normalization, steps field is stripped before persist AND return.\n */\nasync function lazyNormalize(flow: Flow): Promise {\n if (!needsNormalization(flow)) {\n return stripStepsForSave(flow);\n }\n // Normalize and save back to storage (strip steps before persist)\n const normalized = normalizeFlowForSave(flow);\n const cleanFlow = stripStepsForSave(normalized);\n try {\n await IndexedDbStorage.flows.save(cleanFlow);\n } catch (e) {\n console.warn('lazyNormalize: failed to save normalized flow', e);\n }\n // Return DAG-only flow (do not leak deprecated steps to callers)\n return cleanFlow;\n}\n\nexport async function listFlows(): Promise {\n await ensureMigratedFromLocal();\n const flows = await IndexedDbStorage.flows.list();\n // Check if any flows need normalization\n const needsNorm = flows.some(needsNormalization);\n if (!needsNorm) {\n // Strip steps from all flows before returning\n return flows.map(stripStepsForSave);\n }\n // Normalize flows that need it (in parallel)\n // lazyNormalize already returns DAG-only flow\n const normalized = await Promise.all(\n flows.map(async (flow) => {\n if (needsNormalization(flow)) {\n return lazyNormalize(flow);\n }\n return stripStepsForSave(flow);\n }),\n );\n return normalized;\n}\n\nexport async function getFlow(flowId: string): Promise {\n await ensureMigratedFromLocal();\n const flow = await IndexedDbStorage.flows.get(flowId);\n if (!flow) return undefined;\n // Lazy normalize if needed (lazyNormalize returns DAG-only)\n if (needsNormalization(flow)) {\n return lazyNormalize(flow);\n }\n // Strip steps before returning\n return stripStepsForSave(flow);\n}\n\nexport async function saveFlow(flow: Flow, options?: { notify?: boolean }): Promise {\n await ensureMigratedFromLocal();\n // 1. Normalize: generate nodes/edges from steps if missing\n // 2. Strip: remove deprecated steps field before persist\n const normalizedFlow = normalizeFlowForSave(flow);\n const cleanFlow = stripStepsForSave(normalizedFlow);\n await IndexedDbStorage.flows.save(cleanFlow);\n // Notify UI by default, can be disabled for batch operations\n if (options?.notify !== false) {\n notifyFlowsChanged();\n }\n}\n\nexport async function deleteFlow(flowId: string): Promise {\n await ensureMigratedFromLocal();\n await IndexedDbStorage.flows.delete(flowId);\n notifyFlowsChanged();\n}\n\nexport async function listRuns(): Promise {\n await ensureMigratedFromLocal();\n return await IndexedDbStorage.runs.list();\n}\n\nexport async function appendRun(record: RunRecord): Promise {\n await ensureMigratedFromLocal();\n const runs = await IndexedDbStorage.runs.list();\n runs.push(record);\n // Trim to keep last 10 runs per flowId to avoid unbounded growth\n try {\n const byFlow = new Map();\n for (const r of runs) {\n const list = byFlow.get(r.flowId) || [];\n list.push(r);\n byFlow.set(r.flowId, list);\n }\n const merged: RunRecord[] = [];\n for (const [, arr] of byFlow.entries()) {\n arr.sort((a, b) => new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime());\n const last = arr.slice(Math.max(0, arr.length - 10));\n merged.push(...last);\n }\n await IndexedDbStorage.runs.replaceAll(merged);\n } catch (e) {\n console.warn('appendRun: trim failed, saving all', e);\n await IndexedDbStorage.runs.replaceAll(runs);\n }\n}\n\nexport async function listPublished(): Promise {\n await ensureMigratedFromLocal();\n return await IndexedDbStorage.published.list();\n}\n\nexport async function publishFlow(flow: Flow, slug?: string): Promise {\n await ensureMigratedFromLocal();\n const info: PublishedFlowInfo = {\n id: flow.id,\n slug: slug || toSlug(flow.name) || flow.id,\n version: flow.version,\n name: flow.name,\n description: flow.description,\n };\n await IndexedDbStorage.published.save(info);\n return info;\n}\n\nexport async function unpublishFlow(flowId: string): Promise {\n await ensureMigratedFromLocal();\n await IndexedDbStorage.published.delete(flowId);\n}\n\nexport function toSlug(name: string): string {\n return (name || '')\n .toLowerCase()\n .replace(/[^a-z0-9]+/g, '-')\n .replace(/(^-|-$)+/g, '')\n .slice(0, 64);\n}\n\nexport async function exportFlow(flowId: string): Promise {\n const flow = await getFlow(flowId);\n if (!flow) throw new Error('flow not found');\n return JSON.stringify(flow, null, 2);\n}\n\nexport async function exportAllFlows(): Promise {\n const flows = await listFlows();\n return JSON.stringify({ flows }, null, 2);\n}\n\n/**\n * Import flows from JSON string.\n *\n * Supported formats:\n * 1. Array of flows: [...flows]\n * 2. Object with flows array: { flows: [...] }\n * 3. Single flow with steps: { id, steps: [...] }\n * 4. Single flow with nodes (new format): { id, nodes: [...], edges?: [...] }\n *\n * Flows are normalized on save (steps → nodes if needed).\n */\nexport async function importFlowFromJson(json: string): Promise {\n await ensureMigratedFromLocal();\n const parsed = JSON.parse(json);\n\n // Detect candidates from various formats\n const candidates: unknown[] = Array.isArray(parsed)\n ? parsed\n : Array.isArray(parsed?.flows)\n ? parsed.flows\n : parsed?.id && (Array.isArray(parsed?.steps) || Array.isArray(parsed?.nodes))\n ? [parsed]\n : [];\n\n if (!candidates.length) {\n throw new Error('invalid flow json: no flows found');\n }\n\n const nowIso = new Date().toISOString();\n const flowsToImport: Flow[] = [];\n\n for (const raw of candidates) {\n if (!raw || typeof raw !== 'object') {\n throw new Error('invalid flow json: flow must be an object');\n }\n\n const f = raw as Record;\n const id = String(f.id || '').trim();\n if (!id) {\n throw new Error('invalid flow json: missing id');\n }\n\n // Normalize fields with sensible defaults\n const name = typeof f.name === 'string' && f.name.trim() ? f.name : id;\n const version = Number.isFinite(Number(f.version)) ? Number(f.version) : 1;\n\n // Handle meta with proper timestamps\n const existingMeta =\n f.meta && typeof f.meta === 'object' ? (f.meta as Record) : {};\n const createdAt = typeof existingMeta.createdAt === 'string' ? existingMeta.createdAt : nowIso;\n\n // Build flow object - preserve steps only if present (for normalize)\n // saveFlow() will normalize (steps→nodes) then strip steps before persist\n const flow: Flow = {\n ...(f as object),\n id,\n name,\n version,\n meta: {\n ...existingMeta,\n createdAt,\n updatedAt: nowIso,\n },\n } as Flow;\n\n // Preserve steps for normalization if present in import data\n if (Array.isArray(f.steps) && f.steps.length > 0) {\n flow.steps = f.steps as Flow['steps'];\n }\n\n flowsToImport.push(flow);\n }\n\n // Save all flows (normalize on save)\n // Disable individual notifications to avoid flooding UI during batch import\n for (const f of flowsToImport) {\n await saveFlow(f, { notify: false });\n }\n\n // Send single notification after all flows are imported\n notifyFlowsChanged();\n\n return flowsToImport;\n}\n\n// Scheduling support\nexport type ScheduleType = 'once' | 'interval' | 'daily';\nexport interface FlowSchedule {\n id: string; // schedule id\n flowId: string;\n type: ScheduleType;\n enabled: boolean;\n // when: ISO string for 'once'; HH:mm for 'daily'; minutes for 'interval'\n when: string;\n // optional variables to pass when running\n args?: Record;\n}\n\nexport async function listSchedules(): Promise {\n await ensureMigratedFromLocal();\n return await IndexedDbStorage.schedules.list();\n}\n\nexport async function saveSchedule(s: FlowSchedule): Promise {\n await ensureMigratedFromLocal();\n await IndexedDbStorage.schedules.save(s);\n}\n\nexport async function removeSchedule(scheduleId: string): Promise {\n await ensureMigratedFromLocal();\n await IndexedDbStorage.schedules.delete(scheduleId);\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/index.ts", "content": "import { BACKGROUND_MESSAGE_TYPES, CONTENT_MESSAGE_TYPES } from '@/common/message-types';\nimport { Flow } from './types';\nimport {\n listFlows,\n saveFlow,\n getFlow,\n deleteFlow,\n publishFlow,\n unpublishFlow,\n exportFlow,\n exportAllFlows,\n importFlowFromJson,\n listSchedules,\n saveSchedule,\n removeSchedule,\n type FlowSchedule,\n} from './flow-store';\nimport { listRuns } from './flow-store';\nimport { STORAGE_KEYS } from '@/common/constants';\nimport { listTriggers, saveTrigger, deleteTrigger, type FlowTrigger } from './trigger-store';\nimport { runFlow } from './flow-runner';\nimport { RecorderManager } from './recording/recorder-manager';\nimport { recordingSession } from './recording/session-manager';\n// Browser/content listeners are initialized via RecorderManager.init\n\n// design note: background listener for record & replay; delegates recording to dedicated modules\n\n// Alarm helpers for schedules\nasync function rescheduleAlarms() {\n const schedules = await listSchedules();\n // Clear existing rr_schedule_* alarms\n const alarms = await chrome.alarms.getAll();\n await Promise.all(\n alarms\n .filter((a) => a.name && a.name.startsWith('rr_schedule_'))\n .map((a) => chrome.alarms.clear(a.name)),\n );\n for (const s of schedules) {\n if (!s.enabled) continue;\n const name = `rr_schedule_${s.id}`;\n if (s.type === 'interval') {\n const minutes = Math.max(1, Math.floor(Number(s.when) || 0));\n await chrome.alarms.create(name, { periodInMinutes: minutes });\n } else if (s.type === 'once') {\n const whenMs = Date.parse(s.when);\n if (Number.isFinite(whenMs)) await chrome.alarms.create(name, { when: whenMs });\n } else if (s.type === 'daily') {\n // daily HH:mm local time\n const [hh, mm] = String(s.when || '00:00')\n .split(':')\n .map((x) => Number(x));\n const now = new Date();\n const next = new Date();\n next.setHours(hh || 0, mm || 0, 0, 0);\n if (next.getTime() <= now.getTime()) next.setDate(next.getDate() + 1);\n await chrome.alarms.create(name, { when: next.getTime(), periodInMinutes: 24 * 60 });\n }\n }\n}\n\n// legacy injection helpers removed — use recording/content-injection when needed\n\nasync function startRecording(meta?: Partial): Promise<{ success: boolean; error?: string }> {\n return await RecorderManager.start(meta);\n}\n\nasync function stopRecording(): Promise<{ success: boolean; flow?: Flow; error?: string }> {\n return await RecorderManager.stop();\n}\n\nexport function initRecordReplayListeners() {\n // Storage state sync is handled within session manager and recorder manager\n // On startup, re-schedule alarms\n rescheduleAlarms().catch(() => {});\n // Initialize trigger engine (contextMenus/commands/url/dom)\n initTriggerEngine().catch(() => {});\n // Initialize recorder manager (wires browser and content listeners)\n RecorderManager.init().catch(() => {});\n\n chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {\n try {\n // rr_recorder_event 交由 ContentMessageHandler 处理\n switch (message?.type) {\n case BACKGROUND_MESSAGE_TYPES.RR_START_RECORDING: {\n startRecording(message.meta)\n .then(sendResponse)\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_STOP_RECORDING: {\n stopRecording()\n .then(sendResponse)\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_PAUSE_RECORDING: {\n RecorderManager.pause()\n .then(sendResponse)\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_RESUME_RECORDING: {\n RecorderManager.resume()\n .then(sendResponse)\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_GET_RECORDING_STATUS: {\n const status = recordingSession.getStatus();\n const session = recordingSession.getSession();\n sendResponse({\n success: true,\n status,\n sessionId: session.sessionId,\n originTabId: session.originTabId,\n });\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_LIST_FLOWS: {\n listFlows()\n .then((flows) => sendResponse({ success: true, flows }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_GET_FLOW: {\n getFlow(message.flowId)\n .then((flow) => sendResponse({ success: !!flow, flow }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_DELETE_FLOW: {\n deleteFlow(message.flowId)\n .then(() => sendResponse({ success: true }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_PUBLISH_FLOW: {\n getFlow(message.flowId)\n .then(async (flow) => {\n if (!flow) return sendResponse({ success: false, error: 'flow not found' });\n await publishFlow(flow, message.slug);\n sendResponse({ success: true });\n })\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_UNPUBLISH_FLOW: {\n unpublishFlow(message.flowId)\n .then(() => sendResponse({ success: true }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_RUN_FLOW: {\n getFlow(message.flowId)\n .then(async (flow) => {\n if (!flow) return sendResponse({ success: false, error: 'flow not found' });\n const result = await runFlow(flow, message.options || {});\n sendResponse({ success: true, result });\n })\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_SAVE_FLOW: {\n const flow = message.flow as Flow;\n if (!flow || !flow.id) {\n sendResponse({ success: false, error: 'invalid flow' });\n return true;\n }\n saveFlow(flow)\n .then(() => sendResponse({ success: true }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_EXPORT_FLOW: {\n exportFlow(message.flowId)\n .then((json) => sendResponse({ success: true, json }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_EXPORT_ALL: {\n exportAllFlows()\n .then((json) => sendResponse({ success: true, json }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_IMPORT_FLOW: {\n importFlowFromJson(message.json)\n .then((flows) => sendResponse({ success: true, imported: flows.length, flows }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_LIST_RUNS: {\n listRuns()\n .then((runs) => sendResponse({ success: true, runs }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_LIST_TRIGGERS: {\n listTriggers()\n .then((triggers) => sendResponse({ success: true, triggers }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_SAVE_TRIGGER: {\n const t = message.trigger as FlowTrigger;\n if (!t || !t.id || !t.type || !t.flowId) {\n sendResponse({ success: false, error: 'invalid trigger' });\n return true;\n }\n saveTrigger(t)\n .then(async () => {\n await refreshTriggers();\n sendResponse({ success: true });\n })\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_DELETE_TRIGGER: {\n const id = String(message.id || '');\n if (!id) {\n sendResponse({ success: false, error: 'invalid id' });\n return true;\n }\n deleteTrigger(id)\n .then(async () => {\n await refreshTriggers();\n sendResponse({ success: true });\n })\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_REFRESH_TRIGGERS: {\n refreshTriggers()\n .then(() => sendResponse({ success: true }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_LIST_SCHEDULES: {\n listSchedules()\n .then((s) => sendResponse({ success: true, schedules: s }))\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_SCHEDULE_FLOW: {\n const s = message.schedule as FlowSchedule;\n if (!s || !s.id || !s.flowId) {\n sendResponse({ success: false, error: 'invalid schedule' });\n return true;\n }\n saveSchedule(s)\n .then(async () => {\n await rescheduleAlarms();\n sendResponse({ success: true });\n })\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n case BACKGROUND_MESSAGE_TYPES.RR_UNSCHEDULE_FLOW: {\n const scheduleId = String(message.scheduleId || '');\n if (!scheduleId) {\n sendResponse({ success: false, error: 'invalid scheduleId' });\n return true;\n }\n removeSchedule(scheduleId)\n .then(async () => {\n await rescheduleAlarms();\n sendResponse({ success: true });\n })\n .catch((e) => sendResponse({ success: false, error: e?.message || String(e) }));\n return true;\n }\n }\n } catch (err) {\n sendResponse({ success: false, error: (err as any)?.message || String(err) });\n }\n return false;\n });\n\n // Trigger engine: contextMenus/commands/url/dom\n if ((chrome as any).contextMenus?.onClicked?.addListener) {\n chrome.contextMenus.onClicked.addListener(async (info) => {\n try {\n const triggers = await listTriggers();\n const t = triggers.find(\n (x) => x.type === 'contextMenu' && (x as any).menuId === info.menuItemId,\n );\n if (!t || t.enabled === false) return;\n const flow = await getFlow(t.flowId);\n if (!flow) return;\n await runFlow(flow, { args: t.args || {}, returnLogs: false });\n } catch {}\n });\n }\n chrome.commands.onCommand.addListener(async (command) => {\n try {\n const triggers = await listTriggers();\n const t = triggers.find((x) => x.type === 'command' && (x as any).commandKey === command);\n if (!t || t.enabled === false) return;\n const flow = await getFlow(t.flowId);\n if (!flow) return;\n await runFlow(flow, { args: t.args || {}, returnLogs: false });\n } catch {}\n });\n chrome.webNavigation.onCommitted.addListener(async (details) => {\n try {\n if (details.frameId !== 0) return;\n const url = details.url || '';\n // Ensure core content scripts are injected for this tab (pre-heat for replay)\n await ensureCoreInjected(details.tabId);\n // Ensure DOM observer is active on this tab (if triggers exist)\n try {\n const { [STORAGE_KEYS.RR_TRIGGERS]: stored } =\n (await chrome.storage.local.get(STORAGE_KEYS.RR_TRIGGERS)) || {};\n const triggers: any[] = Array.isArray(stored) ? stored : [];\n const domTriggers = triggers\n .filter((x) => x.type === 'dom' && x.enabled !== false)\n .map((x: any) => ({\n id: x.id,\n selector: x.selector,\n appear: x.appear !== false,\n once: x.once !== false,\n debounceMs: x.debounceMs ?? 800,\n }));\n if (typeof details.tabId === 'number') {\n try {\n await chrome.scripting.executeScript({\n target: { tabId: details.tabId, allFrames: true },\n files: ['inject-scripts/dom-observer.js'],\n world: 'ISOLATED',\n } as any);\n await chrome.tabs.sendMessage(details.tabId, {\n action: 'set_dom_triggers',\n triggers: domTriggers,\n } as any);\n } catch {}\n }\n } catch {}\n const triggers = await listTriggers();\n const list = triggers.filter((x) => x.type === 'url' && x.enabled !== false) as any[];\n for (const t of list) {\n if (matchUrl(url, (t as any).match || [])) {\n const flow = await getFlow(t.flowId);\n if (!flow) continue;\n await runFlow(flow, { args: t.args || {}, returnLogs: false });\n }\n }\n } catch {}\n });\n chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {\n try {\n if (message && message.action === 'dom_trigger_fired') {\n const id = message.triggerId;\n listTriggers().then(async (arr) => {\n const t = arr.find((x) => x.id === id && x.type === 'dom');\n if (!t || t.enabled === false) return;\n const flow = await getFlow(t.flowId);\n if (!flow) return;\n await runFlow(flow, { args: t.args || {}, returnLogs: false });\n });\n sendResponse({ ok: true });\n return true;\n }\n } catch {}\n return false;\n });\n}\n\nfunction matchUrl(\n u: string,\n rules: Array<{ kind: 'url' | 'domain' | 'path'; value: string }>,\n): boolean {\n try {\n const url = new URL(u);\n for (const r of rules || []) {\n const v = String(r.value || '');\n if (r.kind === 'url' && u.startsWith(v)) return true;\n if (r.kind === 'domain' && url.hostname.includes(v)) return true;\n if (r.kind === 'path' && url.pathname.startsWith(v)) return true;\n }\n } catch {}\n return false;\n}\n\n// Track context menu IDs created by record-replay to avoid removing other menus\nconst rrContextMenuIds = new Set();\n\nasync function refreshContextMenus(triggers: FlowTrigger[]) {\n if (!(chrome as any).contextMenus?.create) return;\n\n // Remove only our own menu items\n await removeRecordReplayMenus();\n\n // Create menus for enabled context menu triggers\n for (const t of triggers) {\n if (t.type !== 'contextMenu' || t.enabled === false) continue;\n const id = `rr_menu_${t.id}`;\n (t as any).menuId = id;\n\n try {\n await chrome.contextMenus.create({\n id,\n title: (t as any).title || '运行工作流',\n contexts: (t as any).contexts || ['all'],\n });\n rrContextMenuIds.add(id);\n } catch (err) {\n console.warn('[RecordReplay] Failed to create context menu:', err);\n }\n }\n}\n\nasync function removeRecordReplayMenus() {\n if (!(chrome as any).contextMenus?.remove) {\n rrContextMenuIds.clear();\n return;\n }\n\n const pending = Array.from(rrContextMenuIds.values()).map((id) =>\n chrome.contextMenus.remove(id).catch(() => {}),\n );\n\n if (pending.length) await Promise.all(pending);\n rrContextMenuIds.clear();\n}\n\nasync function refreshTriggers() {\n try {\n const triggers = await listTriggers();\n await refreshContextMenus(triggers);\n await chrome.storage.local.set({ [STORAGE_KEYS.RR_TRIGGERS]: triggers });\n const domTriggers = triggers\n .filter((x) => x.type === 'dom' && x.enabled !== false)\n .map((x: any) => ({\n id: x.id,\n selector: x.selector,\n appear: x.appear !== false,\n once: x.once !== false,\n debounceMs: x.debounceMs ?? 800,\n }));\n const tabs = await chrome.tabs.query({});\n for (const t of tabs) {\n if (!t.id) continue;\n try {\n await chrome.scripting.executeScript({\n target: { tabId: t.id, allFrames: true },\n files: ['inject-scripts/dom-observer.js'],\n world: 'ISOLATED',\n } as any);\n await chrome.tabs.sendMessage(t.id, {\n action: 'set_dom_triggers',\n triggers: domTriggers,\n } as any);\n } catch {}\n }\n } catch {}\n}\n\n// Backward-compatible init function; initialize all trigger-related hooks/state\nasync function initTriggerEngine() {\n await refreshTriggers();\n}\n\n// Ensure core content scripts are present for a tab after navigation\nasync function ensureCoreInjected(tabId?: number) {\n try {\n if (typeof tabId !== 'number') return;\n // Ping accessibility helper\n const ok = await pingTab(tabId, CONTENT_MESSAGE_TYPES.ACCESSIBILITY_TREE_HELPER_PING);\n if (!ok) {\n await chrome.scripting.executeScript({\n target: { tabId, allFrames: true },\n files: ['inject-scripts/inject-bridge.js', 'inject-scripts/accessibility-tree-helper.js'],\n world: 'ISOLATED',\n } as any);\n }\n } catch {}\n}\n\nasync function pingTab(tabId: number, action: string): Promise {\n try {\n const resp: any = await chrome.tabs.sendMessage(tabId, { action } as any);\n if (!resp) return false;\n // Helpers generally respond { status: 'pong' } or { ok: true }\n return resp.status === 'pong' || resp.ok === true;\n } catch {\n return false;\n }\n}\n\n// Alarm listener executes scheduled flows\nchrome.alarms.onAlarm.addListener(async (alarm) => {\n try {\n if (!alarm?.name || !alarm.name.startsWith('rr_schedule_')) return;\n const id = alarm.name.slice('rr_schedule_'.length);\n const schedules = await listSchedules();\n const s = schedules.find((x) => x.id === id && x.enabled);\n if (!s) return;\n const flow = await getFlow(s.flowId);\n if (!flow) return;\n await runFlow(flow, { args: s.args || {}, returnLogs: false });\n } catch (e) {\n // swallow to not spam logs\n }\n});\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/legacy-types.ts", "content": "/**\n * Legacy Step Types for Record & Replay\n *\n * This file contains the legacy Step type system that is being phased out\n * in favor of the DAG-based execution model (nodes/edges).\n *\n * These types are kept for:\n * 1. Backward compatibility with existing flows that use steps array\n * 2. Recording pipeline that still produces Step[] output\n * 3. Legacy node handlers in nodes/ directory\n *\n * New code should use the Action type system from ./actions/types.ts instead.\n *\n * Migration status: P4 phase 1 - types extracted, re-exported from types.ts\n */\n\nimport { STEP_TYPES } from '@/common/step-types';\n\n// =============================================================================\n// Legacy Selector Types\n// =============================================================================\n\nexport type SelectorType = 'css' | 'xpath' | 'attr' | 'aria' | 'text';\n\nexport interface SelectorCandidate {\n type: SelectorType;\n value: string; // literal selector or text/aria expression\n weight?: number; // user-adjustable priority; higher first\n}\n\nexport interface TargetLocator {\n ref?: string; // ephemeral ref from read_page\n candidates: SelectorCandidate[]; // ordered by priority\n}\n\n// =============================================================================\n// Legacy Step Types\n// =============================================================================\n\nexport type StepType = (typeof STEP_TYPES)[keyof typeof STEP_TYPES];\n\nexport interface StepBase {\n id: string;\n type: StepType;\n timeoutMs?: number; // default 10000\n retry?: { count: number; intervalMs: number; backoff?: 'none' | 'exp' };\n screenshotOnFail?: boolean; // default true\n}\n\nexport interface StepClick extends StepBase {\n type: 'click' | 'dblclick';\n target: TargetLocator;\n before?: { scrollIntoView?: boolean; waitForSelector?: boolean };\n after?: { waitForNavigation?: boolean; waitForNetworkIdle?: boolean };\n}\n\nexport interface StepFill extends StepBase {\n type: 'fill';\n target: TargetLocator;\n value: string; // may contain {var}\n}\n\nexport interface StepTriggerEvent extends StepBase {\n type: 'triggerEvent';\n target: TargetLocator;\n event: string; // e.g. 'input', 'change', 'mouseover'\n bubbles?: boolean;\n cancelable?: boolean;\n}\n\nexport interface StepSetAttribute extends StepBase {\n type: 'setAttribute';\n target: TargetLocator;\n name: string;\n value?: string; // when omitted and remove=true, remove attribute\n remove?: boolean;\n}\n\nexport interface StepScreenshot extends StepBase {\n type: 'screenshot';\n selector?: string;\n fullPage?: boolean;\n saveAs?: string; // variable name to store base64\n}\n\nexport interface StepSwitchFrame extends StepBase {\n type: 'switchFrame';\n frame?: { index?: number; urlContains?: string };\n}\n\nexport interface StepLoopElements extends StepBase {\n type: 'loopElements';\n selector: string;\n saveAs?: string; // list var name\n itemVar?: string; // default 'item'\n subflowId: string;\n}\n\nexport interface StepKey extends StepBase {\n type: 'key';\n keys: string; // e.g. \"Backspace Enter\" or \"cmd+a\"\n target?: TargetLocator; // optional focus target\n}\n\nexport interface StepScroll extends StepBase {\n type: 'scroll';\n mode: 'element' | 'offset' | 'container';\n target?: TargetLocator; // when mode = element / container\n offset?: { x?: number; y?: number };\n}\n\nexport interface StepDrag extends StepBase {\n type: 'drag';\n start: TargetLocator;\n end: TargetLocator;\n path?: Array<{ x: number; y: number }>; // sampled trajectory\n}\n\nexport interface StepWait extends StepBase {\n type: 'wait';\n condition:\n | { selector: string; visible?: boolean }\n | { text: string; appear?: boolean }\n | { navigation: true }\n | { networkIdle: true }\n | { sleep: number };\n}\n\nexport interface StepAssert extends StepBase {\n type: 'assert';\n assert:\n | { exists: string }\n | { visible: string }\n | { textPresent: string }\n | { attribute: { selector: string; name: string; equals?: string; matches?: string } };\n // 失败策略：stop=失败即停（默认）、warn=仅告警并继续、retry=触发重试机制\n failStrategy?: 'stop' | 'warn' | 'retry';\n}\n\nexport interface StepScript extends StepBase {\n type: 'script';\n world?: 'MAIN' | 'ISOLATED';\n code: string; // user script string\n when?: 'before' | 'after';\n}\n\nexport interface StepIf extends StepBase {\n type: 'if';\n // condition supports: { var: string; equals?: any } | { expression: string }\n condition: any;\n}\n\nexport interface StepForeach extends StepBase {\n type: 'foreach';\n listVar: string;\n itemVar?: string;\n subflowId: string;\n}\n\nexport interface StepWhile extends StepBase {\n type: 'while';\n condition: any;\n subflowId: string;\n maxIterations?: number;\n}\n\nexport interface StepHttp extends StepBase {\n type: 'http';\n method?: string;\n url: string;\n headers?: Record;\n body?: any;\n formData?: any;\n saveAs?: string;\n assign?: Record;\n}\n\nexport interface StepExtract extends StepBase {\n type: 'extract';\n selector?: string;\n attr?: string; // 'text'|'textContent' to read text\n js?: string; // custom JS that returns value\n saveAs: string;\n}\n\nexport interface StepOpenTab extends StepBase {\n type: 'openTab';\n url?: string;\n newWindow?: boolean;\n}\n\nexport interface StepSwitchTab extends StepBase {\n type: 'switchTab';\n tabId?: number;\n urlContains?: string;\n titleContains?: string;\n}\n\nexport interface StepCloseTab extends StepBase {\n type: 'closeTab';\n tabIds?: number[];\n url?: string;\n}\n\nexport interface StepNavigate extends StepBase {\n type: 'navigate';\n url: string;\n}\n\nexport interface StepHandleDownload extends StepBase {\n type: 'handleDownload';\n filenameContains?: string;\n saveAs?: string;\n waitForComplete?: boolean;\n}\n\nexport interface StepExecuteFlow extends StepBase {\n type: 'executeFlow';\n flowId: string;\n inline?: boolean;\n args?: Record;\n}\n\n// =============================================================================\n// Step Union Type\n// =============================================================================\n\nexport type Step =\n | StepClick\n | StepFill\n | StepTriggerEvent\n | StepSetAttribute\n | StepScreenshot\n | StepSwitchFrame\n | StepLoopElements\n | StepKey\n | StepScroll\n | StepDrag\n | StepWait\n | StepAssert\n | StepScript\n | StepIf\n | StepForeach\n | StepWhile\n | StepNavigate\n | StepHttp\n | StepExtract\n | StepOpenTab\n | StepSwitchTab\n | StepCloseTab\n | StepHandleDownload\n | StepExecuteFlow;\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/assert.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { StepAssert } from '../types';\nimport { expandTemplatesDeep } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const assertNode: NodeRuntime = {\n validate: (step) => {\n const s = step as any;\n const ok = !!s.assert;\n if (ok && s.assert && 'attribute' in s.assert) {\n const a = s.assert.attribute || {};\n if (!a.selector || !a.name)\n return { ok: false, errors: ['assert.attribute: 需提供 selector 与 name'] };\n }\n return ok ? { ok } : { ok, errors: ['缺少断言条件'] };\n },\n run: async (ctx: ExecCtx, step: StepAssert) => {\n const s = expandTemplatesDeep(step as StepAssert, ctx.vars) as any;\n const failStrategy = (s as any).failStrategy || 'stop';\n const fail = (msg: string) => {\n if (failStrategy === 'warn') {\n ctx.logger({ stepId: (step as any).id, status: 'warning', message: msg });\n return { alreadyLogged: true } as any;\n }\n throw new Error(msg);\n };\n if ('textPresent' in s.assert) {\n const text = (s.assert as any).textPresent;\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.COMPUTER,\n args: { action: 'wait', text, appear: true, timeout: (step as any).timeoutMs || 5000 },\n });\n if ((res as any).isError) return fail('assert text failed');\n } else if ('exists' in s.assert || 'visible' in s.assert) {\n const selector = (s.assert as any).exists || (s.assert as any).visible;\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const firstTab = tabs && tabs[0];\n const tabId = firstTab && typeof firstTab.id === 'number' ? firstTab.id : undefined;\n if (!tabId) return fail('Active tab not found');\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n const ensured: any = (await chrome.tabs.sendMessage(\n tabId,\n {\n action: 'ensureRefForSelector',\n selector,\n } as any,\n { frameId: ctx.frameId } as any,\n )) as any;\n if (!ensured || !ensured.success) return fail('assert selector not found');\n if ('visible' in s.assert) {\n const rect = ensured && ensured.center ? ensured.center : null;\n if (!rect) return fail('assert visible failed');\n }\n } else if ('attribute' in s.assert) {\n const { selector, name, equals, matches } = (s.assert as any).attribute || {};\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const firstTab = tabs && tabs[0];\n const tabId = firstTab && typeof firstTab.id === 'number' ? firstTab.id : undefined;\n if (!tabId) return fail('Active tab not found');\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n const resp: any = (await chrome.tabs.sendMessage(\n tabId,\n { action: 'getAttributeForSelector', selector, name } as any,\n { frameId: ctx.frameId } as any,\n )) as any;\n if (!resp || !resp.success) return fail('assert attribute: element not found');\n const actual: string | null = resp.value ?? null;\n if (equals !== undefined && equals !== null) {\n const expected = String(equals);\n if (String(actual) !== String(expected))\n return fail(\n `assert attribute equals failed: ${name} actual=${String(actual)} expected=${String(expected)}`,\n );\n } else if (matches !== undefined && matches !== null) {\n try {\n const re = new RegExp(String(matches));\n if (!re.test(String(actual)))\n return fail(\n `assert attribute matches failed: ${name} actual=${String(actual)} regex=${String(matches)}`,\n );\n } catch {\n return fail(`invalid regex for attribute matches: ${String(matches)}`);\n }\n } else {\n if (actual == null) return fail(`assert attribute failed: ${name} missing`);\n }\n }\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/click.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { Step } from '../types';\nimport { locateElement } from '../selector-engine';\nimport { expandTemplatesDeep } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const clickNode: NodeRuntime = {\n validate: (step) => {\n const ok = !!(step as any).target?.candidates?.length;\n return ok ? { ok } : { ok, errors: ['缺少目标选择器候选'] };\n },\n run: async (ctx: ExecCtx, step: Step) => {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const firstTab = tabs && tabs[0];\n const tabId = firstTab && typeof firstTab.id === 'number' ? firstTab.id : undefined;\n if (!tabId) throw new Error('Active tab not found');\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const located = await locateElement(tabId, s.target, ctx.frameId);\n const frameId = (located as any)?.frameId ?? ctx.frameId;\n const first = s.target?.candidates?.[0]?.type;\n const resolvedBy = (located as any)?.resolvedBy || ((located as any)?.ref ? 'ref' : '');\n const fallbackUsed = resolvedBy && first && resolvedBy !== 'ref' && resolvedBy !== first;\n if ((located as any)?.ref) {\n const resolved: any = (await chrome.tabs.sendMessage(\n tabId,\n { action: 'resolveRef', ref: (located as any).ref } as any,\n { frameId } as any,\n )) as any;\n const rect = resolved?.rect;\n if (!rect || rect.width <= 0 || rect.height <= 0) throw new Error('element not visible');\n }\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.CLICK,\n args: {\n ref: (located as any)?.ref || (step as any).target?.ref,\n selector: !(located as any)?.ref\n ? s.target?.candidates?.find((c: any) => c.type === 'css' || c.type === 'attr')?.value\n : undefined,\n waitForNavigation: false,\n timeout: Math.max(1000, Math.min(s.timeoutMs || 10000, 30000)),\n frameId,\n },\n });\n if ((res as any).isError) throw new Error('click failed');\n if (fallbackUsed)\n ctx.logger({\n stepId: step.id,\n status: 'success',\n message: `Selector fallback used (${String(first)} -> ${String(resolvedBy)})`,\n fallbackUsed: true,\n fallbackFrom: String(first),\n fallbackTo: String(resolvedBy),\n } as any);\n return {} as ExecResult;\n },\n};\n\nexport const dblclickNode: NodeRuntime = {\n validate: clickNode.validate,\n run: async (ctx: ExecCtx, step: Step) => {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const firstTab = tabs && tabs[0];\n const tabId = firstTab && typeof firstTab.id === 'number' ? firstTab.id : undefined;\n if (!tabId) throw new Error('Active tab not found');\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const located = await locateElement(tabId, s.target, ctx.frameId);\n const frameId = (located as any)?.frameId ?? ctx.frameId;\n const first = s.target?.candidates?.[0]?.type;\n const resolvedBy = (located as any)?.resolvedBy || ((located as any)?.ref ? 'ref' : '');\n const fallbackUsed = resolvedBy && first && resolvedBy !== 'ref' && resolvedBy !== first;\n if ((located as any)?.ref) {\n const resolved: any = (await chrome.tabs.sendMessage(\n tabId,\n { action: 'resolveRef', ref: (located as any).ref } as any,\n { frameId } as any,\n )) as any;\n const rect = resolved?.rect;\n if (!rect || rect.width <= 0 || rect.height <= 0) throw new Error('element not visible');\n }\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.CLICK,\n args: {\n ref: (located as any)?.ref || (step as any).target?.ref,\n selector: !(located as any)?.ref\n ? s.target?.candidates?.find((c: any) => c.type === 'css' || c.type === 'attr')?.value\n : undefined,\n waitForNavigation: false,\n timeout: Math.max(1000, Math.min(s.timeoutMs || 10000, 30000)),\n frameId,\n double: true,\n },\n });\n if ((res as any).isError) throw new Error('dblclick failed');\n if (fallbackUsed)\n ctx.logger({\n stepId: step.id,\n status: 'success',\n message: `Selector fallback used (${String(first)} -> ${String(resolvedBy)})`,\n fallbackUsed: true,\n fallbackFrom: String(first),\n fallbackTo: String(resolvedBy),\n } as any);\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/conditional.ts", "content": "import type { Step } from '../types';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const ifNode: NodeRuntime = {\n validate: (step) => {\n const s = step as any;\n const hasBranches = Array.isArray(s.branches) && s.branches.length > 0;\n const ok = hasBranches || !!s.condition;\n return ok ? { ok } : { ok, errors: ['缺少条件或分支'] };\n },\n run: async (ctx: ExecCtx, step: Step) => {\n const s: any = step;\n if (Array.isArray(s.branches) && s.branches.length > 0) {\n const evalExpr = (expr: string): boolean => {\n const code = String(expr || '').trim();\n if (!code) return false;\n try {\n const fn = new Function(\n 'vars',\n 'workflow',\n `try { return !!(${code}); } catch (e) { return false; }`,\n );\n return !!fn(ctx.vars, ctx.vars);\n } catch {\n return false;\n }\n };\n for (const br of s.branches) {\n if (br?.expr && evalExpr(String(br.expr)))\n return { nextLabel: String(br.label || `case:${br.id || 'match'}`) } as ExecResult;\n }\n if ('else' in s) return { nextLabel: String(s.else || 'default') } as ExecResult;\n return { nextLabel: 'default' } as ExecResult;\n }\n // legacy condition: { var/equals | expression }\n try {\n let result = false;\n const cond = s.condition;\n if (cond && typeof cond.expression === 'string' && cond.expression.trim()) {\n const fn = new Function(\n 'vars',\n `try { return !!(${cond.expression}); } catch (e) { return false; }`,\n );\n result = !!fn(ctx.vars);\n } else if (cond && typeof cond.var === 'string') {\n const v = ctx.vars[cond.var];\n if ('equals' in cond) result = String(v) === String(cond.equals);\n else result = !!v;\n }\n return { nextLabel: result ? 'true' : 'false' } as ExecResult;\n } catch {\n return { nextLabel: 'false' } as ExecResult;\n }\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/download-screenshot-attr-event-frame-loop.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\nimport { expandTemplatesDeep } from '../rr-utils';\nimport type { Step } from '../types';\nimport { locateElement } from '../selector-engine';\n\nexport const handleDownloadNode: NodeRuntime = {\n run: async (ctx, step) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const args: any = {\n filenameContains: s.filenameContains || undefined,\n timeoutMs: Math.max(1000, Math.min(Number(s.timeoutMs ?? 60000), 300000)),\n waitForComplete: s.waitForComplete !== false,\n };\n const res = await handleCallTool({ name: TOOL_NAMES.BROWSER.HANDLE_DOWNLOAD, args });\n const text = (res as any)?.content?.find((c: any) => c.type === 'text')?.text;\n try {\n const payload = text ? JSON.parse(text) : null;\n if (s.saveAs && payload && payload.download) ctx.vars[s.saveAs] = payload.download;\n } catch {}\n return {} as ExecResult;\n },\n};\n\nexport const screenshotNode: NodeRuntime = {\n run: async (ctx, step) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const args: any = { name: 'workflow', storeBase64: true };\n if (s.fullPage) args.fullPage = true;\n if (s.selector && typeof s.selector === 'string' && s.selector.trim())\n args.selector = s.selector;\n const res = await handleCallTool({ name: TOOL_NAMES.BROWSER.SCREENSHOT, args });\n const text = (res as any)?.content?.find((c: any) => c.type === 'text')?.text;\n try {\n const payload = text ? JSON.parse(text) : null;\n if (s.saveAs && payload && payload.base64Data) ctx.vars[s.saveAs] = payload.base64Data;\n } catch {}\n return {} as ExecResult;\n },\n};\n\nexport const triggerEventNode: NodeRuntime = {\n validate: (step) => {\n const s: any = step;\n const ok = !!s?.target?.candidates?.length && typeof s?.event === 'string' && s.event;\n return ok ? { ok } : { ok, errors: ['缺少目标选择器或事件类型'] };\n },\n run: async (ctx, step) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n const located = await locateElement(tabId, s.target, ctx.frameId);\n const cssSelector = !(located as any)?.ref\n ? s.target.candidates?.find((c: any) => c.type === 'css' || c.type === 'attr')?.value\n : undefined;\n let sel = cssSelector as string | undefined;\n if (!sel && (located as any)?.ref) {\n try {\n const resolved: any = (await chrome.tabs.sendMessage(\n tabId,\n { action: 'resolveRef', ref: (located as any).ref } as any,\n { frameId: ctx.frameId } as any,\n )) as any;\n sel = resolved?.selector;\n } catch {}\n }\n if (!sel) throw new Error('triggerEvent: selector not resolved');\n const world: any = 'MAIN';\n const ev = String(s.event || '').trim();\n const bubbles = s.bubbles !== false;\n const cancelable = s.cancelable === true;\n await chrome.scripting.executeScript({\n target: {\n tabId,\n frameIds: typeof ctx.frameId === 'number' ? [ctx.frameId] : undefined,\n } as any,\n world,\n func: (selector: string, type: string, bubbles: boolean, cancelable: boolean) => {\n try {\n const el = document.querySelector(selector);\n if (!el) return false;\n const e = new Event(type, { bubbles, cancelable });\n (el as any).dispatchEvent(e);\n return true;\n } catch (e) {\n return false;\n }\n },\n args: [sel, ev, !!bubbles, !!cancelable],\n } as any);\n return {} as ExecResult;\n },\n};\n\nexport const setAttributeNode: NodeRuntime = {\n validate: (step) => {\n const s: any = step;\n const ok = !!s?.target?.candidates?.length && typeof s?.name === 'string' && s.name;\n return ok ? { ok } : { ok, errors: ['需提供目标选择器与属性名'] };\n },\n run: async (ctx, step) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n const located = await locateElement(tabId, s.target, ctx.frameId);\n const frameId = (located as any)?.frameId ?? ctx.frameId;\n const cssSelector = !(located as any)?.ref\n ? s.target.candidates?.find((c: any) => c.type === 'css' || c.type === 'attr')?.value\n : undefined;\n let sel = cssSelector as string | undefined;\n if (!sel && (located as any)?.ref) {\n try {\n const resolved: any = (await chrome.tabs.sendMessage(\n tabId,\n { action: 'resolveRef', ref: (located as any).ref } as any,\n { frameId } as any,\n )) as any;\n sel = resolved?.selector;\n } catch {}\n }\n if (!sel) throw new Error('setAttribute: selector not resolved');\n const world: any = 'MAIN';\n const name = String(s.name || '');\n const value = s.value;\n const remove = s.remove === true;\n await chrome.scripting.executeScript({\n target: { tabId, frameIds: typeof frameId === 'number' ? [frameId] : undefined } as any,\n world,\n func: (selector: string, name: string, value: any, remove: boolean) => {\n try {\n const el = document.querySelector(selector) as any;\n if (!el) return false;\n if (remove) el.removeAttribute(name);\n else el.setAttribute(name, String(value ?? ''));\n return true;\n } catch {\n return false;\n }\n },\n args: [sel, name, value, remove],\n } as any);\n return {} as ExecResult;\n },\n};\n\nexport const switchFrameNode: NodeRuntime = {\n run: async (ctx, step) => {\n const s: any = step;\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n const frames = await chrome.webNavigation.getAllFrames({ tabId });\n if (!Array.isArray(frames) || frames.length === 0) {\n ctx.frameId = undefined;\n return {} as ExecResult;\n }\n let target: any | undefined;\n const idx = Number(s?.frame?.index ?? NaN);\n if (Number.isFinite(idx)) {\n const list = frames.filter((f) => f.frameId !== 0);\n target = list[Math.max(0, Math.min(list.length - 1, idx))];\n }\n const urlContains = String(s?.frame?.urlContains || '').trim();\n if (!target && urlContains)\n target = frames.find((f) => typeof f.url === 'string' && f.url.includes(urlContains));\n if (!target) ctx.frameId = undefined;\n else ctx.frameId = target.frameId;\n try {\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n } catch {}\n ctx.logger({\n stepId: (step as any).id,\n status: 'success',\n message: `frameId=${String(ctx.frameId ?? 'top')}`,\n } as any);\n return {} as ExecResult;\n },\n};\n\nexport const loopElementsNode: NodeRuntime = {\n validate: (step) => {\n const s: any = step;\n const ok =\n typeof s?.selector === 'string' &&\n s.selector &&\n typeof s?.subflowId === 'string' &&\n s.subflowId;\n return ok ? { ok } : { ok, errors: ['需提供 selector 与 subflowId'] };\n },\n run: async (ctx, step) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n const world: any = 'MAIN';\n const selector = String(s.selector || '');\n const res = await chrome.scripting.executeScript({\n target: {\n tabId,\n frameIds: typeof ctx.frameId === 'number' ? [ctx.frameId] : undefined,\n } as any,\n world,\n func: (sel: string) => {\n try {\n const list = Array.from(document.querySelectorAll(sel));\n const toCss = (node: Element) => {\n try {\n if ((node as HTMLElement).id) {\n const idSel = `#${CSS.escape((node as HTMLElement).id)}`;\n if (document.querySelectorAll(idSel).length === 1) return idSel;\n }\n } catch {}\n let path = '';\n let current: Element | null = node;\n while (current && current.tagName !== 'BODY') {\n let part = current.tagName.toLowerCase();\n const parentEl: Element | null = current.parentElement;\n if (parentEl) {\n const siblings = Array.from(parentEl.children).filter(\n (c) => (c as any).tagName === current!.tagName,\n );\n if (siblings.length > 1) {\n const idx = siblings.indexOf(current) + 1;\n part += `:nth-of-type(${idx})`;\n }\n }\n path = path ? `${part} > ${path}` : part;\n current = parentEl;\n }\n return path ? `body > ${path}` : 'body';\n };\n return list.map(toCss);\n } catch (e) {\n return [];\n }\n },\n args: [selector],\n } as any);\n const arr: string[] = (res && Array.isArray(res[0]?.result) ? res[0].result : []) as any;\n const listVar = String(s.saveAs || 'elements');\n const itemVar = String(s.itemVar || 'item');\n ctx.vars[listVar] = arr;\n return {\n control: { kind: 'foreach', listVar, itemVar, subflowId: String(s.subflowId) },\n } as any;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/drag.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { StepDrag } from '../types';\nimport { locateElement } from '../selector-engine';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const dragNode: NodeRuntime = {\n run: async (_ctx, step: StepDrag) => {\n const s = step as StepDrag;\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n let startRef: string | undefined;\n let endRef: string | undefined;\n try {\n if (typeof tabId === 'number') {\n const locatedStart = await locateElement(tabId, (s as any).start);\n const locatedEnd = await locateElement(tabId, (s as any).end);\n startRef = (locatedStart as any)?.ref || (s as any).start.ref;\n endRef = (locatedEnd as any)?.ref || (s as any).end.ref;\n }\n } catch {}\n let startCoordinates: { x: number; y: number } | undefined;\n let endCoordinates: { x: number; y: number } | undefined;\n if ((!startRef || !endRef) && Array.isArray((s as any).path) && (s as any).path.length >= 2) {\n startCoordinates = { x: Number((s as any).path[0].x), y: Number((s as any).path[0].y) };\n const last = (s as any).path[(s as any).path.length - 1];\n endCoordinates = { x: Number(last.x), y: Number(last.y) };\n }\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.COMPUTER,\n args: {\n action: 'left_click_drag',\n startRef,\n ref: endRef,\n startCoordinates,\n coordinates: endCoordinates,\n },\n });\n if ((res as any).isError) throw new Error('drag failed');\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/execute-flow.ts", "content": "import type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const executeFlowNode: NodeRuntime = {\n validate: (step) => {\n const s: any = step;\n const ok = typeof s.flowId === 'string' && !!s.flowId;\n return ok ? { ok } : { ok, errors: ['需提供 flowId'] };\n },\n run: async (ctx: ExecCtx, step) => {\n const s: any = step;\n const { getFlow } = await import('../flow-store');\n const flow = await getFlow(String(s.flowId));\n if (!flow) throw new Error('referenced flow not found');\n const inline = s.inline !== false; // default inline\n if (!inline) {\n const { runFlow } = await import('../flow-runner');\n await runFlow(flow, { args: s.args || {}, returnLogs: false });\n return {} as ExecResult;\n }\n const { defaultEdgesOnly, topoOrder, mapDagNodeToStep, waitForNetworkIdle, waitForNavigation } =\n await import('../rr-utils');\n const vars = ctx.vars;\n if (s.args && typeof s.args === 'object') Object.assign(vars, s.args);\n\n // DAG is required - flow-store guarantees nodes/edges via normalization\n const nodes = ((flow as any).nodes || []) as any[];\n const edges = ((flow as any).edges || []) as any[];\n if (nodes.length === 0) {\n throw new Error(\n 'Flow has no DAG nodes. Linear steps are no longer supported. Please migrate this flow to nodes/edges.',\n );\n }\n const defaultEdges = defaultEdgesOnly(edges as any);\n const order = topoOrder(nodes as any, defaultEdges as any);\n const stepsToRun: any[] = order.map((n) => mapDagNodeToStep(n as any));\n for (const st of stepsToRun) {\n const t0 = Date.now();\n const maxRetries = Math.max(0, (st as any).retry?.count ?? 0);\n const baseInterval = Math.max(0, (st as any).retry?.intervalMs ?? 0);\n let attempt = 0;\n const doDelay = async (i: number) => {\n const delay =\n baseInterval > 0\n ? (st as any).retry?.backoff === 'exp'\n ? baseInterval * Math.pow(2, i)\n : baseInterval\n : 0;\n if (delay > 0) await new Promise((r) => setTimeout(r, delay));\n };\n while (true) {\n try {\n const beforeInfo = await (async () => {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tab = tabs[0];\n return { url: tab?.url || '', status: (tab as any)?.status || '' };\n })();\n const { executeStep } = await import('../nodes');\n const result = await executeStep(ctx as any, st as any);\n if ((st.type === 'click' || st.type === 'dblclick') && (st as any).after) {\n const after = (st as any).after as any;\n if (after.waitForNavigation)\n await waitForNavigation((st as any).timeoutMs, beforeInfo.url);\n else if (after.waitForNetworkIdle)\n await waitForNetworkIdle(Math.min((st as any).timeoutMs || 5000, 120000), 1200);\n }\n if (!result?.alreadyLogged)\n ctx.logger({ stepId: st.id, status: 'success', tookMs: Date.now() - t0 } as any);\n break;\n } catch (e: any) {\n if (attempt < maxRetries) {\n ctx.logger({\n stepId: st.id,\n status: 'retrying',\n message: e?.message || String(e),\n } as any);\n await doDelay(attempt);\n attempt += 1;\n continue;\n }\n ctx.logger({\n stepId: st.id,\n status: 'failed',\n message: e?.message || String(e),\n tookMs: Date.now() - t0,\n } as any);\n throw e;\n }\n }\n }\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/extract.ts", "content": "import type { StepExtract } from '../types';\nimport { expandTemplatesDeep } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const extractNode: NodeRuntime = {\n run: async (ctx: ExecCtx, step: StepExtract) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n let value: any = null;\n if (s.js && String(s.js).trim()) {\n const [{ result }] = await chrome.scripting.executeScript({\n target: { tabId },\n func: (code: string) => {\n try {\n return (0, eval)(code);\n } catch (e) {\n return null;\n }\n },\n args: [String(s.js)],\n } as any);\n value = result;\n } else if (s.selector) {\n const attr = String(s.attr || 'text');\n const sel = String(s.selector);\n const [{ result }] = await chrome.scripting.executeScript({\n target: { tabId },\n func: (selector: string, attr: string) => {\n try {\n const el = document.querySelector(selector) as any;\n if (!el) return null;\n if (attr === 'text' || attr === 'textContent') return (el.textContent || '').trim();\n return el.getAttribute ? el.getAttribute(attr) : null;\n } catch {\n return null;\n }\n },\n args: [sel, attr],\n } as any);\n value = result;\n }\n if (s.saveAs) ctx.vars[s.saveAs] = value;\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/fill.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { StepFill } from '../types';\nimport { locateElement } from '../selector-engine';\nimport { expandTemplatesDeep } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const fillNode: NodeRuntime = {\n validate: (step) => {\n const ok = !!(step as any).target?.candidates?.length && 'value' in (step as any);\n return ok ? { ok } : { ok, errors: ['缺少目标选择器候选或输入值'] };\n },\n run: async (ctx: ExecCtx, step: StepFill) => {\n const s: any = step;\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const firstTab = tabs && tabs[0];\n const tabId = firstTab && typeof firstTab.id === 'number' ? firstTab.id : undefined;\n if (!tabId) throw new Error('Active tab not found');\n await handleCallTool({ name: TOOL_NAMES.BROWSER.READ_PAGE, args: {} });\n const located = await locateElement(tabId, s.target, ctx.frameId);\n const frameId = (located as any)?.frameId ?? ctx.frameId;\n const first = s.target?.candidates?.[0]?.type;\n const resolvedBy = (located as any)?.resolvedBy || ((located as any)?.ref ? 'ref' : '');\n const fallbackUsed = resolvedBy && first && resolvedBy !== 'ref' && resolvedBy !== first;\n const interpolate = (v: any) =>\n typeof v === 'string'\n ? v.replace(/\\{([^}]+)\\}/g, (_m, k) => (ctx.vars[k] ?? '').toString())\n : v;\n const value = interpolate(s.value);\n if ((located as any)?.ref) {\n const resolved: any = (await chrome.tabs.sendMessage(\n tabId,\n { action: 'resolveRef', ref: (located as any).ref } as any,\n { frameId } as any,\n )) as any;\n const rect = resolved?.rect;\n if (!rect || rect.width <= 0 || rect.height <= 0) throw new Error('element not visible');\n }\n const cssSelector = !(located as any)?.ref\n ? s.target.candidates?.find((c: any) => c.type === 'css' || c.type === 'attr')?.value\n : undefined;\n if (cssSelector) {\n try {\n const attr: any = (await chrome.tabs.sendMessage(\n tabId,\n { action: 'getAttributeForSelector', selector: cssSelector, name: 'type' } as any,\n { frameId } as any,\n )) as any;\n const typeName = (attr && attr.value ? String(attr.value) : '').toLowerCase();\n if (typeName === 'file') {\n const uploadRes = await handleCallTool({\n name: TOOL_NAMES.BROWSER.FILE_UPLOAD,\n args: { selector: cssSelector, filePath: String(value ?? '') },\n });\n if ((uploadRes as any).isError) throw new Error('file upload failed');\n if (fallbackUsed)\n ctx.logger({\n stepId: (step as any).id,\n status: 'success',\n message: `Selector fallback used (${String(first)} -> ${String(resolvedBy)})`,\n fallbackUsed: true,\n fallbackFrom: String(first),\n fallbackTo: String(resolvedBy),\n } as any);\n return {} as ExecResult;\n }\n } catch {}\n }\n try {\n if (cssSelector)\n await handleCallTool({\n name: TOOL_NAMES.BROWSER.INJECT_SCRIPT,\n args: {\n type: 'MAIN',\n jsScript: `try{var el=document.querySelector(${JSON.stringify(cssSelector)});if(el){el.scrollIntoView({behavior:'instant',block:'center',inline:'nearest'});} }catch(e){}`,\n },\n });\n } catch {}\n try {\n if ((located as any)?.ref)\n await chrome.tabs.sendMessage(\n tabId,\n { action: 'focusByRef', ref: (located as any).ref } as any,\n { frameId } as any,\n );\n else if (cssSelector)\n await handleCallTool({\n name: TOOL_NAMES.BROWSER.INJECT_SCRIPT,\n args: {\n type: 'MAIN',\n jsScript: `try{var el=document.querySelector(${JSON.stringify(cssSelector)});if(el&&el.focus){el.focus();}}catch(e){}`,\n },\n });\n } catch {}\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.FILL,\n args: {\n ref: (located as any)?.ref || (s as any).target?.ref,\n selector: cssSelector,\n value,\n frameId,\n },\n });\n if ((res as any).isError) throw new Error('fill failed');\n if (fallbackUsed)\n ctx.logger({\n stepId: (step as any).id,\n status: 'success',\n message: `Selector fallback used (${String(first)} -> ${String(resolvedBy)})`,\n fallbackUsed: true,\n fallbackFrom: String(first),\n fallbackTo: String(resolvedBy),\n } as any);\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/http.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { StepHttp } from '../types';\nimport { applyAssign, expandTemplatesDeep } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const httpNode: NodeRuntime = {\n run: async (ctx: ExecCtx, step: StepHttp) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.NETWORK_REQUEST,\n args: {\n url: s.url,\n method: s.method || 'GET',\n headers: s.headers || {},\n body: s.body,\n formData: s.formData,\n },\n });\n const text = (res as any)?.content?.find((c: any) => c.type === 'text')?.text;\n try {\n const payload = text ? JSON.parse(text) : null;\n if (s.saveAs && payload !== undefined) ctx.vars[s.saveAs] = payload;\n if (s.assign && payload !== undefined) applyAssign(ctx.vars, payload, s.assign);\n } catch {}\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/index.ts", "content": "import type { Step } from '../types';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\nimport { clickNode, dblclickNode } from './click';\nimport { fillNode } from './fill';\nimport { httpNode } from './http';\nimport { extractNode } from './extract';\nimport { scriptNode } from './script';\nimport { openTabNode, switchTabNode, closeTabNode } from './tabs';\nimport { scrollNode } from './scroll';\nimport { dragNode } from './drag';\nimport { keyNode } from './key';\nimport { waitNode } from './wait';\nimport { assertNode } from './assert';\nimport { navigateNode } from './navigate';\nimport { ifNode } from './conditional';\nimport { STEP_TYPES } from 'chrome-mcp-shared';\nimport { foreachNode, whileNode } from './loops';\nimport { executeFlowNode } from './execute-flow';\nimport {\n handleDownloadNode,\n screenshotNode,\n triggerEventNode,\n setAttributeNode,\n switchFrameNode,\n loopElementsNode,\n} from './download-screenshot-attr-event-frame-loop';\n\nconst registry = new Map>([\n [STEP_TYPES.CLICK, clickNode],\n [STEP_TYPES.DBLCLICK, dblclickNode],\n [STEP_TYPES.FILL, fillNode],\n [STEP_TYPES.HTTP, httpNode],\n [STEP_TYPES.EXTRACT, extractNode],\n [STEP_TYPES.SCRIPT, scriptNode],\n [STEP_TYPES.OPEN_TAB, openTabNode],\n [STEP_TYPES.SWITCH_TAB, switchTabNode],\n [STEP_TYPES.CLOSE_TAB, closeTabNode],\n [STEP_TYPES.SCROLL, scrollNode],\n [STEP_TYPES.DRAG, dragNode],\n [STEP_TYPES.KEY, keyNode],\n [STEP_TYPES.WAIT, waitNode],\n [STEP_TYPES.ASSERT, assertNode],\n [STEP_TYPES.NAVIGATE, navigateNode],\n [STEP_TYPES.IF, ifNode],\n [STEP_TYPES.FOREACH, foreachNode],\n [STEP_TYPES.WHILE, whileNode],\n [STEP_TYPES.EXECUTE_FLOW, executeFlowNode],\n [STEP_TYPES.HANDLE_DOWNLOAD, handleDownloadNode],\n [STEP_TYPES.SCREENSHOT, screenshotNode],\n [STEP_TYPES.TRIGGER_EVENT, triggerEventNode],\n [STEP_TYPES.SET_ATTRIBUTE, setAttributeNode],\n [STEP_TYPES.SWITCH_FRAME, switchFrameNode],\n [STEP_TYPES.LOOP_ELEMENTS, loopElementsNode],\n]);\n\nexport async function executeStep(ctx: ExecCtx, step: Step): Promise {\n const rt = registry.get(step.type);\n if (!rt) throw new Error(`unsupported step type: ${String(step.type)}`);\n const v = rt.validate ? rt.validate(step) : { ok: true };\n if (!v.ok) throw new Error((v.errors || []).join(', ') || 'validation failed');\n const out = await rt.run(ctx, step);\n return out || {};\n}\n\nexport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/key.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { StepKey } from '../types';\nimport { expandTemplatesDeep } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const keyNode: NodeRuntime = {\n run: async (ctx, step: StepKey) => {\n const s = expandTemplatesDeep(step as StepKey, ctx.vars) as StepKey;\n const args: { keys: string; frameId?: number; selector?: string } = { keys: s.keys };\n\n // Support target selector for focusing before key input\n if (s.target && s.target.candidates?.length) {\n const selector = s.target.candidates[0]?.value;\n if (selector) {\n args.selector = selector;\n }\n }\n\n if (typeof ctx.frameId === 'number') {\n args.frameId = ctx.frameId;\n }\n\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.KEYBOARD,\n args,\n });\n if ((res as any).isError) throw new Error('key failed');\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/loops.ts", "content": "import type { ExecCtx, ExecResult, NodeRuntime } from './types';\nimport { ENGINE_CONSTANTS } from '../engine/constants';\n\nexport const foreachNode: NodeRuntime = {\n validate: (step) => {\n const s = step as any;\n const ok =\n typeof s.listVar === 'string' && s.listVar && typeof s.subflowId === 'string' && s.subflowId;\n return ok ? { ok } : { ok, errors: ['foreach: 需提供 listVar 与 subflowId'] };\n },\n run: async (_ctx: ExecCtx, step) => {\n const s: any = step;\n const itemVar = typeof s.itemVar === 'string' && s.itemVar ? s.itemVar : 'item';\n return {\n control: {\n kind: 'foreach',\n listVar: String(s.listVar),\n itemVar,\n subflowId: String(s.subflowId),\n concurrency: Math.max(\n 1,\n Math.min(ENGINE_CONSTANTS.MAX_FOREACH_CONCURRENCY, Number(s.concurrency ?? 1)),\n ),\n },\n } as ExecResult;\n },\n};\n\nexport const whileNode: NodeRuntime = {\n validate: (step) => {\n const s = step as any;\n const ok = !!s.condition && typeof s.subflowId === 'string' && s.subflowId;\n return ok ? { ok } : { ok, errors: ['while: 需提供 condition 与 subflowId'] };\n },\n run: async (_ctx: ExecCtx, step) => {\n const s: any = step;\n const max = Math.max(1, Math.min(10000, Number(s.maxIterations ?? 100)));\n return {\n control: {\n kind: 'while',\n condition: s.condition,\n subflowId: String(s.subflowId),\n maxIterations: max,\n },\n } as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/navigate.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { Step } from '../types';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const navigateNode: NodeRuntime = {\n validate: (step) => {\n const ok = !!(step as any).url;\n return ok ? { ok } : { ok, errors: ['缺少 URL'] };\n },\n run: async (_ctx: ExecCtx, step: Step) => {\n const url = (step as any).url;\n const res = await handleCallTool({ name: TOOL_NAMES.BROWSER.NAVIGATE, args: { url } });\n if ((res as any).isError) throw new Error('navigate failed');\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/script.ts", "content": "import type { StepScript } from '../types';\nimport { expandTemplatesDeep, applyAssign } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const scriptNode: NodeRuntime = {\n run: async (ctx: ExecCtx, step: StepScript) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n if (s.when === 'after') return { deferAfterScript: s } as ExecResult;\n const world = s.world || 'ISOLATED';\n const code = String(s.code || '');\n if (!code.trim()) return {} as ExecResult;\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n const frameIds = typeof ctx.frameId === 'number' ? [ctx.frameId] : undefined;\n const [{ result }] = await chrome.scripting.executeScript({\n target: { tabId, frameIds } as any,\n func: (userCode: string) => {\n try {\n return (0, eval)(userCode);\n } catch {\n return null;\n }\n },\n args: [code],\n world: world as any,\n } as any);\n if (s.saveAs) ctx.vars[s.saveAs] = result;\n if (s.assign && typeof s.assign === 'object') applyAssign(ctx.vars, result, s.assign);\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/scroll.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { StepScroll } from '../types';\nimport { expandTemplatesDeep } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const scrollNode: NodeRuntime = {\n run: async (ctx, step: StepScroll) => {\n const s = expandTemplatesDeep(step as StepScroll, ctx.vars);\n const top = s.offset?.y ?? undefined;\n const left = s.offset?.x ?? undefined;\n const selectorFromTarget = (s as any).target?.candidates?.find(\n (c: any) => c.type === 'css' || c.type === 'attr',\n )?.value;\n let code = '';\n if (s.mode === 'offset' && !(s as any).target) {\n const t = top != null ? Number(top) : 'undefined';\n const l = left != null ? Number(left) : 'undefined';\n code = `try { window.scrollTo({ top: ${t}, left: ${l}, behavior: 'instant' }); } catch (e) {}`;\n } else if (s.mode === 'element' && selectorFromTarget) {\n code = `(() => { try { const el = document.querySelector(${JSON.stringify(selectorFromTarget)}); if (el) el.scrollIntoView({ behavior: 'instant', block: 'center', inline: 'nearest' }); } catch (e) {} })();`;\n } else if (s.mode === 'container' && selectorFromTarget) {\n const t = top != null ? Number(top) : 'undefined';\n const l = left != null ? Number(left) : 'undefined';\n code = `(() => { try { const el = document.querySelector(${JSON.stringify(selectorFromTarget)}); if (el && typeof el.scrollTo === 'function') el.scrollTo({ top: ${t}, left: ${l}, behavior: 'instant' }); } catch (e) {} })();`;\n } else {\n const direction = top != null && Number(top) < 0 ? 'up' : 'down';\n const amount = 3;\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.COMPUTER,\n args: { action: 'scroll', scrollDirection: direction, scrollAmount: amount },\n });\n if ((res as any).isError) throw new Error('scroll failed');\n return {} as ExecResult;\n }\n if (code) {\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.INJECT_SCRIPT,\n args: { type: 'MAIN', jsScript: code },\n });\n if ((res as any).isError) throw new Error('scroll failed');\n }\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/tabs.ts", "content": "import { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { handleCallTool } from '@/entrypoints/background/tools';\nimport type { StepOpenTab, StepSwitchTab, StepCloseTab } from '../types';\nimport { expandTemplatesDeep } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const openTabNode: NodeRuntime = {\n run: async (ctx, step) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n if (s.newWindow) await chrome.windows.create({ url: s.url || undefined, focused: true });\n else await chrome.tabs.create({ url: s.url || undefined, active: true });\n return {} as ExecResult;\n },\n};\n\nexport const switchTabNode: NodeRuntime = {\n run: async (ctx, step) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n let targetTabId: number | undefined = s.tabId;\n if (!targetTabId) {\n const tabs = await chrome.tabs.query({});\n const hit = tabs.find(\n (t) =>\n (s.urlContains && (t.url || '').includes(String(s.urlContains))) ||\n (s.titleContains && (t.title || '').includes(String(s.titleContains))),\n );\n targetTabId = (hit && hit.id) as number | undefined;\n }\n if (!targetTabId) throw new Error('switchTab: no matching tab');\n const res = await handleCallTool({\n name: TOOL_NAMES.BROWSER.SWITCH_TAB,\n args: { tabId: targetTabId },\n });\n if ((res as any).isError) throw new Error('switchTab failed');\n return {} as ExecResult;\n },\n};\n\nexport const closeTabNode: NodeRuntime = {\n run: async (ctx, step) => {\n const s: any = expandTemplatesDeep(step as any, ctx.vars);\n const args: any = {};\n if (Array.isArray(s.tabIds) && s.tabIds.length) args.tabIds = s.tabIds;\n if (s.url) args.url = s.url;\n const res = await handleCallTool({ name: TOOL_NAMES.BROWSER.CLOSE_TABS, args });\n if ((res as any).isError) throw new Error('closeTab failed');\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/types.ts", "content": "import type { RunLogEntry, Step, StepScript } from '../types';\n\n/**\n * Execution context for step execution.\n * Contains runtime state that may change during flow execution.\n */\nexport interface ExecCtx {\n /** Runtime variables accessible to steps */\n vars: Record;\n /** Logger function for recording execution events */\n logger: (e: RunLogEntry) => void;\n /**\n * Current tab ID for this execution context.\n * Managed by Scheduler, may change after openTab/switchTab actions.\n */\n tabId?: number;\n /**\n * Current frame ID within the tab.\n * Used for iframe targeting, 0 for main frame.\n */\n frameId?: number;\n}\n\nexport interface ExecResult {\n alreadyLogged?: boolean;\n deferAfterScript?: StepScript | null;\n nextLabel?: string;\n control?:\n | { kind: 'foreach'; listVar: string; itemVar: string; subflowId: string; concurrency?: number }\n | { kind: 'while'; condition: any; subflowId: string; maxIterations: number };\n}\n\nexport interface NodeRuntime {\n validate?: (step: S) => { ok: boolean; errors?: string[] };\n run: (ctx: ExecCtx, step: S) => Promise;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/nodes/wait.ts", "content": "import type { StepWait } from '../types';\nimport { waitForNetworkIdle, waitForNavigation } from '../rr-utils';\nimport { expandTemplatesDeep } from '../rr-utils';\nimport type { ExecCtx, ExecResult, NodeRuntime } from './types';\n\nexport const waitNode: NodeRuntime = {\n validate: (step) => {\n const ok = !!(step as any).condition;\n return ok ? { ok } : { ok, errors: ['缺少等待条件'] };\n },\n run: async (ctx: ExecCtx, step: StepWait) => {\n const s = expandTemplatesDeep(step as StepWait, ctx.vars);\n const cond = (s as StepWait).condition as\n | { selector: string; visible?: boolean }\n | { text: string; appear?: boolean }\n | { navigation: true }\n | { networkIdle: true }\n | { sleep: number };\n if ('text' in cond) {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n const frameIds = typeof ctx.frameId === 'number' ? [ctx.frameId] : undefined;\n await chrome.scripting.executeScript({\n target: { tabId, frameIds },\n files: ['inject-scripts/wait-helper.js'],\n world: 'ISOLATED',\n } as any);\n const resp: any = (await chrome.tabs.sendMessage(\n tabId,\n {\n action: 'waitForText',\n text: cond.text,\n appear: (cond as any).appear !== false,\n timeout: Math.max(0, Math.min((s as any).timeoutMs || 10000, 120000)),\n } as any,\n { frameId: ctx.frameId } as any,\n )) as any;\n if (!resp || resp.success !== true) throw new Error('wait text failed');\n } else if ('networkIdle' in cond) {\n const total = Math.min(Math.max(1000, (s as any).timeoutMs || 5000), 120000);\n const idle = Math.min(1500, Math.max(500, Math.floor(total / 3)));\n await waitForNetworkIdle(total, idle);\n } else if ('navigation' in cond) {\n await waitForNavigation((s as any).timeoutMs);\n } else if ('sleep' in cond) {\n const ms = Math.max(0, Number(cond.sleep ?? 0));\n await new Promise((r) => setTimeout(r, ms));\n } else if ('selector' in cond) {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n const frameIds = typeof ctx.frameId === 'number' ? [ctx.frameId] : undefined;\n await chrome.scripting.executeScript({\n target: { tabId, frameIds },\n files: ['inject-scripts/wait-helper.js'],\n world: 'ISOLATED',\n } as any);\n const resp: any = (await chrome.tabs.sendMessage(\n tabId,\n {\n action: 'waitForSelector',\n selector: (cond as any).selector,\n visible: (cond as any).visible !== false,\n timeout: Math.max(0, Math.min((s as any).timeoutMs || 10000, 120000)),\n } as any,\n { frameId: ctx.frameId } as any,\n )) as any;\n if (!resp || resp.success !== true) throw new Error('wait selector failed');\n }\n return {} as ExecResult;\n },\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/recording/browser-event-listener.ts", "content": "import { addNavigationStep } from './flow-builder';\nimport { STEP_TYPES } from '@/common/step-types';\nimport { ensureRecorderInjected, broadcastControlToTab, REC_CMD } from './content-injection';\nimport type { RecordingSessionManager } from './session-manager';\nimport type { Step } from '../types';\n\nexport function initBrowserEventListeners(session: RecordingSessionManager): void {\n chrome.tabs.onActivated.addListener(async (activeInfo) => {\n try {\n if (session.getStatus() !== 'recording') return;\n const tabId = activeInfo.tabId;\n await ensureRecorderInjected(tabId);\n await broadcastControlToTab(tabId, REC_CMD.START);\n // Track active tab for targeted STOP later\n session.addActiveTab(tabId);\n\n const flow = session.getFlow();\n if (!flow) return;\n const tab = await chrome.tabs.get(tabId);\n const url = tab.url;\n const step: Step = {\n id: '',\n type: STEP_TYPES.SWITCH_TAB,\n ...(url ? { urlContains: url } : {}),\n };\n session.appendSteps([step]);\n } catch (e) {\n console.warn('onActivated handler failed', e);\n }\n });\n\n chrome.webNavigation.onCommitted.addListener(async (details) => {\n try {\n if (session.getStatus() !== 'recording') return;\n if (details.frameId !== 0) return;\n const tabId = details.tabId;\n const t = details.transitionType;\n const link = t === 'link';\n if (!link) {\n const shouldRecord =\n t === 'reload' ||\n t === 'typed' ||\n t === 'generated' ||\n t === 'auto_bookmark' ||\n t === 'keyword' ||\n // include form_submit to better capture Enter-to-search navigations\n t === 'form_submit';\n if (shouldRecord) {\n const tab = await chrome.tabs.get(tabId);\n const url = tab.url || details.url;\n const flow = session.getFlow();\n if (flow && url) addNavigationStep(flow, url);\n }\n }\n await ensureRecorderInjected(tabId);\n await broadcastControlToTab(tabId, REC_CMD.START);\n // Track active tab for targeted STOP later\n session.addActiveTab(tabId);\n if (session.getFlow()) {\n session.broadcastTimelineUpdate();\n }\n } catch (e) {\n console.warn('onCommitted handler failed', e);\n }\n });\n\n // Remove closed tabs from the active set to avoid stale broadcasts\n chrome.tabs.onRemoved.addListener((tabId) => {\n try {\n // Even if not recording, removing is harmless; keep guard for clarity\n if (session.getStatus() !== 'recording') return;\n session.removeActiveTab(tabId);\n } catch (e) {\n console.warn('onRemoved handler failed', e);\n }\n });\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/recording/content-injection.ts", "content": "import { TOOL_MESSAGE_TYPES } from '@/common/message-types';\n\n// Avoid magic strings for recorder control commands\nexport type RecorderCmd = 'start' | 'stop' | 'pause' | 'resume';\nexport const REC_CMD = {\n START: 'start',\n STOP: 'stop',\n PAUSE: 'pause',\n RESUME: 'resume',\n} as const satisfies Record;\n\nconst RECORDER_JS_SCRIPT = 'inject-scripts/recorder.js';\n\nexport async function ensureRecorderInjected(tabId: number): Promise {\n // Discover frames (top + subframes)\n let frames: Array<{ frameId: number } & Record> = [];\n try {\n const res = (await chrome.webNavigation.getAllFrames({ tabId })) as\n | Array<{ frameId: number } & Record>\n | null\n | undefined;\n frames = Array.isArray(res) ? res : [];\n } catch {\n // ignore and fallback to top frame only\n }\n if (frames.length === 0) frames = [{ frameId: 0 }];\n\n const needRecorder: number[] = [];\n await Promise.all(\n frames.map(async (f) => {\n const frameId = f.frameId ?? 0;\n try {\n const res = await chrome.tabs.sendMessage(\n tabId,\n { action: 'rr_recorder_ping' },\n { frameId },\n );\n const pong = res?.status === 'pong';\n if (!pong) needRecorder.push(frameId);\n } catch {\n needRecorder.push(frameId);\n }\n }),\n );\n\n if (needRecorder.length > 0) {\n try {\n await chrome.scripting.executeScript({\n target: { tabId, frameIds: needRecorder },\n files: [RECORDER_JS_SCRIPT],\n world: 'ISOLATED',\n });\n } catch {\n // Fallback: try allFrames to cover dynamic/subframe changes; safe due to idempotent guard in recorder.js\n try {\n await chrome.scripting.executeScript({\n target: { tabId, allFrames: true },\n files: [RECORDER_JS_SCRIPT],\n world: 'ISOLATED',\n });\n } catch {\n // ignore injection failures per-tab\n }\n }\n }\n}\n\nexport async function broadcastControlToTab(\n tabId: number,\n cmd: RecorderCmd,\n meta?: unknown,\n): Promise {\n try {\n const res = (await chrome.webNavigation.getAllFrames({ tabId })) as\n | Array<{ frameId: number } & Record>\n | null\n | undefined;\n const targets = Array.isArray(res) && res.length ? res : [{ frameId: 0 }];\n await Promise.all(\n targets.map(async (f) => {\n try {\n await chrome.tabs.sendMessage(\n tabId,\n { action: TOOL_MESSAGE_TYPES.RR_RECORDER_CONTROL, cmd, meta },\n { frameId: f.frameId },\n );\n } catch {\n // ignore per-frame send failure\n }\n }),\n );\n } catch {\n // ignore\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/recording/content-message-handler.ts", "content": "import type { RecordingSessionManager } from './session-manager';\nimport type { Step, VariableDef } from '../types';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\n\n/**\n * Initialize the content message handler for receiving steps and variables from content scripts.\n *\n * Supports the following payload kinds:\n * - 'steps' | 'step': Append steps to the current flow\n * - 'variables': Append variables to the current flow (for sensitive input handling)\n * - 'finalize': Content script has finished flushing (used during stop barrier)\n */\nexport function initContentMessageHandler(session: RecordingSessionManager): void {\n chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {\n try {\n if (!message || message.type !== TOOL_MESSAGE_TYPES.RR_RECORDER_EVENT) return false;\n\n // Accept messages during 'recording' or 'stopping' states\n // 'stopping' allows final steps to arrive during the drain phase\n if (!session.canAcceptSteps()) {\n sendResponse({ ok: true, ignored: true });\n return true;\n }\n\n const flow = session.getFlow();\n if (!flow) {\n sendResponse({ ok: true, ignored: true });\n return true;\n }\n\n const payload = message?.payload || {};\n\n // Handle steps\n if (payload.kind === 'steps' || payload.kind === 'step') {\n const steps: Step[] = Array.isArray(payload.steps)\n ? (payload.steps as Step[])\n : payload.step\n ? [payload.step as Step]\n : [];\n if (steps.length > 0) {\n session.appendSteps(steps);\n }\n }\n\n // Handle variables (for sensitive input handling)\n if (payload.kind === 'variables') {\n const variables: VariableDef[] = Array.isArray(payload.variables)\n ? (payload.variables as VariableDef[])\n : [];\n if (variables.length > 0) {\n session.appendVariables(variables);\n }\n }\n\n // Handle combined payload (steps + variables in one message)\n if (payload.kind === 'batch') {\n const steps: Step[] = Array.isArray(payload.steps) ? (payload.steps as Step[]) : [];\n const variables: VariableDef[] = Array.isArray(payload.variables)\n ? (payload.variables as VariableDef[])\n : [];\n if (steps.length > 0) {\n session.appendSteps(steps);\n }\n if (variables.length > 0) {\n session.appendVariables(variables);\n }\n }\n\n // payload.kind === 'start'|'stop'|'finalize' are no-ops here (lifecycle handled elsewhere)\n sendResponse({ ok: true });\n return true;\n } catch (e) {\n console.warn('ContentMessageHandler: processing message failed', e);\n sendResponse({ ok: false, error: String((e as Error)?.message || e) });\n return true;\n }\n });\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/recording/flow-builder.ts", "content": "import type { Edge, Flow, NodeBase, Step } from '../types';\nimport { STEP_TYPES } from '@/common/step-types';\nimport { recordingSession } from './session-manager';\nimport { mapStepToNodeConfig, EDGE_LABELS } from 'chrome-mcp-shared';\n\nconst WORKFLOW_VERSION = 1;\n\n/**\n * Creates an initial flow structure for recording.\n * Initializes with nodes/edges (DAG) instead of steps.\n */\nexport function createInitialFlow(meta?: Partial): Flow {\n const timeStamp = new Date().toISOString();\n const flow: Flow = {\n id: meta?.id || `flow_${Date.now()}`,\n name: meta?.name || 'new_workflow',\n version: WORKFLOW_VERSION,\n nodes: [],\n edges: [],\n variables: [],\n meta: {\n createdAt: timeStamp,\n updatedAt: timeStamp,\n ...meta?.meta,\n },\n };\n return flow;\n}\n\nexport function generateStepId(): string {\n return `step_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;\n}\n\n/**\n * Appends a navigation step to the flow.\n * Prefers centralized session append when recording is active.\n * Falls back to direct DAG mutation (does NOT write flow.steps).\n */\nexport function addNavigationStep(flow: Flow, url: string): void {\n const step: Step = { id: generateStepId(), type: STEP_TYPES.NAVIGATE, url } as Step;\n\n // Prefer centralized session append (single broadcast path) when active and matching flow\n const sessFlow = recordingSession.getFlow?.();\n if (recordingSession.getStatus?.() === 'recording' && sessFlow === flow) {\n recordingSession.appendSteps([step]);\n return;\n }\n\n // Fallback: mutate DAG directly (do not write flow.steps)\n appendNodeToFlow(flow, step);\n}\n\n/**\n * Appends a step as a node to the flow's DAG structure.\n * Creates node and edge from the previous node if exists.\n *\n * Internal helper - rarely invoked in practice. During active recording,\n * addNavigationStep() routes to session.appendSteps() which handles DAG\n * maintenance, caching, and timeline broadcast. This fallback only runs\n * when session is not active or flow reference doesn't match.\n */\nfunction appendNodeToFlow(flow: Flow, step: Step): void {\n // Ensure DAG arrays exist\n if (!Array.isArray(flow.nodes)) flow.nodes = [];\n if (!Array.isArray(flow.edges)) flow.edges = [];\n\n const prevNodeId = flow.nodes.length > 0 ? flow.nodes[flow.nodes.length - 1]?.id : undefined;\n\n // Create new node\n const newNode: NodeBase = {\n id: step.id,\n type: step.type as NodeBase['type'],\n config: mapStepToNodeConfig(step),\n };\n flow.nodes.push(newNode);\n\n // Create edge from previous node if exists\n if (prevNodeId) {\n const edgeId = `e_${flow.edges.length}_${prevNodeId}_${step.id}`;\n const edge: Edge = {\n id: edgeId,\n from: prevNodeId,\n to: step.id,\n label: EDGE_LABELS.DEFAULT,\n };\n flow.edges.push(edge);\n }\n\n // Update meta timestamp (with error tolerance like session-manager)\n try {\n const timeStamp = new Date().toISOString();\n if (!flow.meta) {\n flow.meta = { createdAt: timeStamp, updatedAt: timeStamp };\n } else {\n flow.meta.updatedAt = timeStamp;\n }\n } catch {\n // ignore meta update errors to not block recording\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/recording/recorder-manager.ts", "content": "import type { Flow } from '../types';\nimport { saveFlow } from '../flow-store';\nimport { broadcastControlToTab, ensureRecorderInjected, REC_CMD } from './content-injection';\nimport { recordingSession as session } from './session-manager';\nimport { createInitialFlow, addNavigationStep } from './flow-builder';\nimport { initBrowserEventListeners } from './browser-event-listener';\nimport { initContentMessageHandler } from './content-message-handler';\n\n/** Timeout for waiting for the top-frame content script to acknowledge stop. */\nconst STOP_BARRIER_TOP_TIMEOUT_MS = 5000;\n\n/** Best-effort stop timeout for subframes (keeps top-frame still listening). */\nconst STOP_BARRIER_SUBFRAME_TIMEOUT_MS = 1500;\n\n/** Small grace period for in-flight messages after all ACKs. */\nconst STOP_BARRIER_GRACE_MS = 150;\n\n/** Types for stop barrier results */\ninterface StopAckStats {\n ack: boolean;\n steps: number;\n variables: number;\n}\n\ninterface StopFrameAck {\n frameId: number;\n ack: boolean;\n timedOut: boolean;\n error?: string;\n stats?: StopAckStats;\n}\n\ninterface StopTabBarrierResult {\n tabId: number;\n ok: boolean;\n skipped?: boolean;\n reason?: string;\n top?: StopFrameAck;\n subframes: StopFrameAck[];\n}\n\n/**\n * List frameIds for a tab. Always includes 0 (main frame).\n */\nasync function listFrameIds(tabId: number): Promise {\n try {\n const res = await chrome.webNavigation.getAllFrames({ tabId });\n const ids = Array.isArray(res)\n ? res.map((f) => f.frameId).filter((n) => typeof n === 'number')\n : [];\n if (!ids.includes(0)) ids.unshift(0);\n return Array.from(new Set(ids)).sort((a, b) => a - b);\n } catch {\n return [0];\n }\n}\n\n/**\n * Send stop command to a specific frame and wait for acknowledgment.\n */\nasync function sendStopToFrameWithAck(\n tabId: number,\n sessionId: string,\n frameId: number,\n timeoutMs: number,\n): Promise {\n return new Promise((resolve) => {\n const t = setTimeout(() => {\n resolve({ frameId, ack: false, timedOut: true });\n }, timeoutMs);\n\n chrome.tabs\n .sendMessage(\n tabId,\n {\n action: REC_CMD.STOP,\n sessionId,\n requireAck: true,\n },\n { frameId },\n )\n .then((response) => {\n clearTimeout(t);\n const ack = !!(response && response.ack);\n const stats = response && response.stats ? (response.stats as StopAckStats) : undefined;\n resolve({ frameId, ack, timedOut: false, stats });\n })\n .catch((err) => {\n clearTimeout(t);\n resolve({ frameId, ack: false, timedOut: false, error: String(err) });\n });\n });\n}\n\n/**\n * Stop a tab with full barrier support.\n * 1. Stop subframes first (so they can finalize and postMessage to top while top is still listening)\n * 2. Stop the main frame (top) and wait for ACK\n */\nasync function stopTabWithBarrier(tabId: number, sessionId: string): Promise {\n // If the tab is already gone, don't block stop.\n try {\n await chrome.tabs.get(tabId);\n } catch {\n return { tabId, ok: true, skipped: true, reason: 'tab not found', subframes: [] };\n }\n\n // Ensure recorder is available in frames (best-effort).\n try {\n await ensureRecorderInjected(tabId);\n } catch {}\n\n const frameIds = await listFrameIds(tabId);\n const subframeIds = frameIds.filter((id) => id !== 0);\n\n // Stop subframes first so they can finalize and postMessage to top while top is still listening.\n const subframes = await Promise.all(\n subframeIds.map((fid) =>\n sendStopToFrameWithAck(tabId, sessionId, fid, STOP_BARRIER_SUBFRAME_TIMEOUT_MS),\n ),\n );\n\n // Stop the main frame (top) with longer timeout\n const top = await sendStopToFrameWithAck(tabId, sessionId, 0, STOP_BARRIER_TOP_TIMEOUT_MS);\n\n return { tabId, ok: top.ack, top, subframes };\n}\n\nclass RecorderManagerImpl {\n private initialized = false;\n\n async init(): Promise {\n if (this.initialized) return;\n initBrowserEventListeners(session);\n initContentMessageHandler(session);\n this.initialized = true;\n }\n\n async start(meta?: Partial): Promise<{ success: boolean; error?: string }> {\n if (session.getStatus() !== 'idle')\n return { success: false, error: 'Recording already active' };\n // Resolve active tab\n const [active] = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!active?.id) return { success: false, error: 'Active tab not found' };\n\n // Initialize flow & session\n const flow: Flow = createInitialFlow(meta);\n await session.startSession(flow, active.id);\n\n // Ensure recorder available and start listening\n await ensureRecorderInjected(active.id);\n await broadcastControlToTab(active.id, REC_CMD.START, {\n id: flow.id,\n name: flow.name,\n description: flow.description,\n sessionId: session.getSession().sessionId,\n });\n // Track active tab for targeted STOP broadcasts\n session.addActiveTab(active.id);\n\n // Record first step\n const url = active.url;\n if (url) {\n addNavigationStep(flow, url);\n try {\n await saveFlow(flow);\n } catch (e) {\n console.warn('RecorderManager: initial saveFlow failed', e);\n }\n }\n\n return { success: true };\n }\n\n /**\n * Stop recording with reliable step collection using barrier protocol.\n *\n * Flow:\n * 1. Transition to 'stopping' state (still accepts final steps)\n * 2. For each tab: stop subframes first (best-effort), then stop main frame\n * 3. Wait for main frame ACK (required) with timeout\n * 4. Grace period for any final messages in flight\n * 5. Finalize session and save flow with barrier metadata\n *\n * The barrier ensures:\n * - All tabs have flushed their data before save\n * - Subframes finalize to top before top stops\n * - Barrier status is recorded in flow.meta for debugging\n */\n async stop(): Promise<{ success: boolean; error?: string; flow?: Flow }> {\n const currentStatus = session.getStatus();\n if (currentStatus === 'idle' || !session.getFlow()) {\n return { success: false, error: 'No active recording' };\n }\n\n // Already stopping - don't double-stop\n if (currentStatus === 'stopping') {\n return { success: false, error: 'Stop already in progress' };\n }\n\n // Step 1: Transition to stopping state\n const sessionId = session.beginStopping();\n const tabs = session.getActiveTabs();\n\n // Step 2: Send stop commands to all tabs with full barrier support\n // Each tab: stop subframes first, then stop main frame and wait for ACK\n let results: StopTabBarrierResult[] = [];\n try {\n results = await Promise.all(tabs.map((tabId) => stopTabWithBarrier(tabId, sessionId)));\n } catch (e) {\n console.warn('RecorderManager: Error during stop broadcast:', e);\n }\n\n // Step 3: Allow a small grace period for any final messages in flight\n await new Promise((resolve) => setTimeout(resolve, STOP_BARRIER_GRACE_MS));\n\n // Step 4: Finalize - clear session state and save with barrier metadata\n const flow = await session.stopSession();\n const barrierOk = results.length === tabs.length && results.every((r) => r.ok || r.skipped);\n const stoppedAt = new Date().toISOString();\n\n if (flow) {\n // Add barrier metadata to flow\n try {\n if (!flow.meta) flow.meta = { createdAt: stoppedAt, updatedAt: stoppedAt };\n const failed = results\n .filter((r) => !r.ok || r.skipped || r.subframes.some((sf) => !sf.ack))\n .map((r) => ({\n tabId: r.tabId,\n skipped: r.skipped || undefined,\n reason: r.reason || undefined,\n topTimedOut: r.top?.timedOut || undefined,\n topError: r.top?.error || undefined,\n subframesFailed: r.subframes.filter((sf) => !sf.ack).length || undefined,\n }))\n .slice(0, 20); // Limit to first 20 to avoid bloating metadata\n\n flow.meta.stopBarrier = {\n ok: barrierOk,\n sessionId,\n stoppedAt,\n failed: failed.length ? failed : undefined,\n };\n } catch {}\n\n await saveFlow(flow);\n }\n\n // Return with barrier status\n if (!barrierOk) {\n const failedTabs = results.filter((r) => !r.ok && !r.skipped).map((r) => r.tabId);\n return {\n success: true, // Flow is still saved, but with incomplete barrier\n flow: flow || undefined,\n error: failedTabs.length\n ? `Stop barrier incomplete; missing ACK from tabs: ${failedTabs.join(', ')}`\n : 'Stop barrier incomplete; missing ACK(s)',\n };\n }\n\n return flow ? { success: true, flow } : { success: true };\n }\n\n /**\n * Pause recording. Steps are not collected while paused.\n */\n async pause(): Promise<{ success: boolean; error?: string }> {\n if (session.getStatus() !== 'recording') {\n return { success: false, error: 'Not currently recording' };\n }\n\n session.pause();\n\n // Broadcast pause to all active tabs\n const tabs = session.getActiveTabs();\n try {\n await Promise.all(tabs.map((id) => broadcastControlToTab(id, REC_CMD.PAUSE)));\n } catch (e) {\n console.warn('RecorderManager: Error during pause broadcast:', e);\n }\n\n return { success: true };\n }\n\n /**\n * Resume recording after pause.\n */\n async resume(): Promise<{ success: boolean; error?: string }> {\n if (session.getStatus() !== 'paused') {\n return { success: false, error: 'Not currently paused' };\n }\n\n session.resume();\n\n // Broadcast resume to all active tabs\n const tabs = session.getActiveTabs();\n try {\n await Promise.all(tabs.map((id) => broadcastControlToTab(id, REC_CMD.RESUME)));\n } catch (e) {\n console.warn('RecorderManager: Error during resume broadcast:', e);\n }\n\n return { success: true };\n }\n}\n\nexport const RecorderManager = new RecorderManagerImpl();\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/recording/session-manager.ts", "content": "import type { Edge, Flow, NodeBase, Step, VariableDef } from '../types';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { NODE_TYPES } from '@/common/node-types';\nimport { mapStepToNodeConfig, stepsToDAG, EDGE_LABELS } from 'chrome-mcp-shared';\n\n/**\n * Recording status state machine:\n * - idle: No active recording\n * - recording: Actively capturing user interactions\n * - paused: Temporarily paused (UI can resume)\n * - stopping: Draining final steps from content scripts before save\n */\nexport type RecordingStatus = 'idle' | 'recording' | 'paused' | 'stopping';\n\nexport interface RecordingSessionState {\n sessionId: string;\n status: RecordingStatus;\n originTabId: number | null;\n flow: Flow | null;\n // Track tabs that have participated in this recording session\n activeTabs: Set;\n // Track which tabs have acknowledged stop command\n stoppedTabs: Set;\n}\n\n// Valid node types for type checking\nconst VALID_NODE_TYPES = new Set(Object.values(NODE_TYPES));\n\nexport class RecordingSessionManager {\n private state: RecordingSessionState = {\n sessionId: '',\n status: 'idle',\n originTabId: null,\n flow: null,\n activeTabs: new Set(),\n stoppedTabs: new Set(),\n };\n\n // Session-level cache for incremental DAG sync (cleared on session start/stop)\n // Note: stepIndexMap removed - we no longer write to flow.steps\n private nodeIndexMap: Map = new Map();\n // Monotonic counter for edge id generation (avoids collision on delete/reorder)\n private edgeSeq: number = 0;\n\n getStatus(): RecordingStatus {\n return this.state.status;\n }\n\n getSession(): Readonly {\n return this.state;\n }\n\n getFlow(): Flow | null {\n return this.state.flow;\n }\n\n getOriginTabId(): number | null {\n return this.state.originTabId;\n }\n\n addActiveTab(tabId: number): void {\n if (typeof tabId === 'number') this.state.activeTabs.add(tabId);\n }\n\n removeActiveTab(tabId: number): void {\n this.state.activeTabs.delete(tabId);\n }\n\n getActiveTabs(): number[] {\n return Array.from(this.state.activeTabs);\n }\n\n async startSession(flow: Flow, originTabId: number): Promise {\n // Clear cache for fresh session\n this.nodeIndexMap.clear();\n this.edgeSeq = 0;\n\n this.state = {\n sessionId: `sess_${Date.now()}`,\n status: 'recording',\n originTabId,\n flow,\n activeTabs: new Set([originTabId]),\n stoppedTabs: new Set(),\n };\n\n // Initialize caches from existing flow data (supports resume scenarios)\n this.rebuildCaches();\n }\n\n /**\n * Transition to stopping state. Content scripts can still send final steps.\n * Returns the sessionId for barrier verification.\n */\n beginStopping(): string {\n if (this.state.status === 'idle') return '';\n this.state.status = 'stopping';\n this.state.stoppedTabs.clear();\n return this.state.sessionId;\n }\n\n /**\n * Mark a tab as having acknowledged the stop command.\n * Returns true if all active tabs have stopped.\n */\n markTabStopped(tabId: number): boolean {\n this.state.stoppedTabs.add(tabId);\n // Check if all active tabs have acknowledged\n for (const activeTabId of this.state.activeTabs) {\n if (!this.state.stoppedTabs.has(activeTabId)) {\n return false;\n }\n }\n return true;\n }\n\n /**\n * Check if we're in stopping state (still accepting final steps).\n */\n isStopping(): boolean {\n return this.state.status === 'stopping';\n }\n\n /**\n * Check if we can accept steps (recording or stopping).\n */\n canAcceptSteps(): boolean {\n return this.state.status === 'recording' || this.state.status === 'stopping';\n }\n\n /**\n * Transition to paused state.\n */\n pause(): void {\n if (this.state.status === 'recording') {\n this.state.status = 'paused';\n }\n }\n\n /**\n * Resume from paused state.\n */\n resume(): void {\n if (this.state.status === 'paused') {\n this.state.status = 'recording';\n }\n }\n\n /**\n * Finalize stop and clear session state.\n */\n async stopSession(): Promise {\n const flow = this.state.flow;\n this.state.status = 'idle';\n this.state.flow = null;\n this.state.originTabId = null;\n this.state.activeTabs.clear();\n this.state.stoppedTabs.clear();\n // Clear cache\n this.nodeIndexMap.clear();\n this.edgeSeq = 0;\n return flow;\n }\n\n updateFlow(mutator: (f: Flow) => void): void {\n const f = this.state.flow;\n if (!f) return;\n mutator(f);\n try {\n (f.meta as any).updatedAt = new Date().toISOString();\n } catch (e) {\n // ignore meta update errors\n }\n }\n\n /**\n * Append or upsert steps to the flow with incremental DAG sync.\n * Uses upsert semantics: if a step with the same id exists, update it in place.\n * This ensures fill steps get their final value even after initial flush.\n *\n * DAG sync: maintains flow.nodes/edges during recording.\n * - New step → create node + edge from previous node\n * - Upsert step → update node.config and node.type\n * - Invariant violation → fallback to linear DAG rebuild\n *\n * Note: flow.steps is no longer written. Nodes are the source of truth.\n */\n appendSteps(steps: Step[]): void {\n const f = this.state.flow;\n if (!f || !Array.isArray(steps) || steps.length === 0) return;\n\n // Initialize arrays if missing\n if (!Array.isArray(f.nodes)) f.nodes = [];\n if (!Array.isArray(f.edges)) f.edges = [];\n\n // Legacy compatibility: if flow only has steps, initialize DAG from them once\n if (f.nodes.length === 0 && Array.isArray(f.steps) && f.steps.length > 0) {\n this.rebuildDagFromSteps();\n }\n\n const nodes = f.nodes;\n const edges = f.edges;\n\n // Check invariants: edges must match linear chain\n // If violated (e.g., imported flow, manual edit), rebuild linear chain\n if (!this.checkDagInvariant(nodes, edges)) {\n this.rechainEdges();\n }\n\n // Process each incoming step with upsert semantics + incremental DAG sync\n let needsRebuild = false;\n for (const step of steps) {\n // Ensure step has an id\n if (!step.id) {\n step.id = `step_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;\n }\n\n const nodeIdx = this.nodeIndexMap.get(step.id);\n if (nodeIdx !== undefined) {\n // Upsert: update existing node in place\n if (!nodes[nodeIdx]) {\n needsRebuild = true;\n continue;\n }\n nodes[nodeIdx] = {\n ...nodes[nodeIdx],\n type: this.toNodeType(step.type),\n config: mapStepToNodeConfig(step),\n };\n } else {\n // Append: new node\n const prevNodeId = nodes.length > 0 ? nodes[nodes.length - 1]?.id : undefined;\n\n // Create corresponding node\n const newNode: NodeBase = {\n id: step.id,\n type: this.toNodeType(step.type),\n config: mapStepToNodeConfig(step),\n };\n nodes.push(newNode);\n this.nodeIndexMap.set(step.id, nodes.length - 1);\n\n // Create edge from previous node (if exists)\n if (prevNodeId) {\n if (!this.nodeIndexMap.has(prevNodeId)) {\n needsRebuild = true;\n continue;\n }\n const edgeId = `e_${this.edgeSeq++}_${prevNodeId}_${step.id}`;\n edges.push({\n id: edgeId,\n from: prevNodeId,\n to: step.id,\n label: EDGE_LABELS.DEFAULT,\n });\n }\n }\n }\n\n // Final invariant check: if any inconsistency detected, rebuild edges\n if (needsRebuild || !this.checkDagInvariant(nodes, edges)) {\n this.rechainEdges();\n }\n\n // Update meta timestamp\n try {\n if (f.meta) {\n f.meta.updatedAt = new Date().toISOString();\n }\n } catch {\n // ignore meta update errors\n }\n\n this.broadcastTimelineUpdate();\n }\n\n /**\n * Convert step type to valid NodeType with fallback to SCRIPT.\n * Logs a warning for unknown types to help detect upstream type drift.\n */\n private toNodeType(stepType: string): NodeBase['type'] {\n if (VALID_NODE_TYPES.has(stepType)) {\n return stepType as NodeBase['type'];\n }\n console.warn(`[RecordingSession] Unknown step type \"${stepType}\", falling back to \"script\"`);\n return NODE_TYPES.SCRIPT;\n }\n\n /**\n * Check DAG invariant for linear recording:\n * - edges.length === max(0, nodes.length - 1)\n * - Last edge (if exists) points to the last node\n */\n private checkDagInvariant(nodes: NodeBase[], edges: Edge[]): boolean {\n const nodeCount = nodes.length;\n const expectedEdgeCount = Math.max(0, nodeCount - 1);\n\n // Check edge count matches expected linear chain\n if (edges.length !== expectedEdgeCount) {\n return false;\n }\n\n // Check last edge points to last node (if edges exist)\n if (edges.length > 0 && nodes.length > 0) {\n const lastEdge = edges[edges.length - 1];\n const lastNodeId = nodes[nodes.length - 1]?.id;\n if (lastEdge.to !== lastNodeId) {\n return false;\n }\n }\n\n return true;\n }\n\n /**\n * Rebuild caches from current flow state.\n * Called on session start and after DAG rebuild.\n */\n private rebuildCaches(): void {\n const f = this.state.flow;\n if (!f) return;\n\n this.nodeIndexMap.clear();\n\n if (Array.isArray(f.nodes)) {\n for (let i = 0; i < f.nodes.length; i++) {\n const id = f.nodes[i]?.id;\n if (id) this.nodeIndexMap.set(id, i);\n }\n }\n\n // Sync edgeSeq to continue from current edge count (avoids id collision)\n this.edgeSeq = Array.isArray(f.edges) ? f.edges.length : 0;\n }\n\n /**\n * Full DAG rebuild from legacy steps.\n * Used when flow only has steps[] but no nodes[].\n */\n private rebuildDagFromSteps(): void {\n const f = this.state.flow;\n if (!f || !Array.isArray(f.steps) || f.steps.length === 0) return;\n\n const dag = stepsToDAG(f.steps);\n\n // Clear and repopulate nodes\n if (!Array.isArray(f.nodes)) f.nodes = [];\n f.nodes.length = 0;\n for (const n of dag.nodes) {\n f.nodes.push({\n id: n.id,\n type: this.toNodeType(n.type),\n config: n.config,\n });\n }\n\n // Clear and repopulate edges\n if (!Array.isArray(f.edges)) f.edges = [];\n f.edges.length = 0;\n for (const e of dag.edges) {\n f.edges.push({\n id: e.id,\n from: e.from,\n to: e.to,\n label: e.label,\n });\n }\n\n // Rebuild caches\n this.rebuildCaches();\n }\n\n /**\n * Re-chain edges linearly according to current nodes order.\n * Used when edge invariant is violated but nodes exist.\n */\n private rechainEdges(): void {\n const f = this.state.flow;\n if (!f) return;\n\n if (!Array.isArray(f.nodes)) f.nodes = [];\n if (!Array.isArray(f.edges)) f.edges = [];\n\n // Clear and re-chain edges\n f.edges.length = 0;\n for (let i = 0; i < f.nodes.length - 1; i++) {\n const from = f.nodes[i].id;\n const to = f.nodes[i + 1].id;\n f.edges.push({\n id: `e_${i}_${from}_${to}`,\n from,\n to,\n label: EDGE_LABELS.DEFAULT,\n });\n }\n\n // Rebuild caches\n this.rebuildCaches();\n }\n\n /**\n * Append variables to the flow. Deduplicates by key.\n */\n appendVariables(variables: VariableDef[]): void {\n const f = this.state.flow;\n if (!f || !Array.isArray(variables) || variables.length === 0) return;\n\n if (!f.variables) {\n f.variables = [];\n }\n\n // Deduplicate by key - newer definitions override older ones\n const existingKeys = new Set(f.variables.map((v) => v.key));\n for (const v of variables) {\n if (!v.key) continue;\n if (existingKeys.has(v.key)) {\n // Update existing variable\n const idx = f.variables.findIndex((fv) => fv.key === v.key);\n if (idx >= 0) {\n f.variables[idx] = v;\n }\n } else {\n f.variables.push(v);\n existingKeys.add(v.key);\n }\n }\n\n // Update meta timestamp\n try {\n if (f.meta) {\n f.meta.updatedAt = new Date().toISOString();\n }\n } catch {\n // ignore meta update errors\n }\n }\n\n /**\n * Derive timeline steps from nodes for UI broadcast.\n * This keeps protocol compatibility with recorder.js without storing steps.\n */\n private getTimelineSteps(): Step[] {\n const f = this.state.flow;\n if (!f) return [];\n\n // Primary: derive from nodes\n if (Array.isArray(f.nodes) && f.nodes.length > 0) {\n return f.nodes.map((n) => {\n const cfg =\n n && typeof n.config === 'object' && n.config != null\n ? (n.config as Record)\n : {};\n // Important: id and type must override any values in config\n // (config may contain 'type' for trigger nodes, etc.)\n return { ...cfg, id: n.id, type: n.type } as Step;\n });\n }\n\n // Legacy fallback: use steps if no nodes (shouldn't happen in normal recording)\n if (Array.isArray(f.steps) && f.steps.length > 0) {\n return f.steps;\n }\n\n return [];\n }\n\n // Broadcast timeline updates to relevant tabs (top-frame only)\n broadcastTimelineUpdate(): void {\n try {\n // Derive steps from nodes for UI consumption (protocol unchanged)\n const fullSteps = this.getTimelineSteps();\n if (fullSteps.length === 0) return;\n\n // Prefer broadcasting to all tabs that participated in this session, so timeline\n // stays consistent when user switches across tabs/windows during a single session.\n const targets = this.getActiveTabs();\n const list =\n targets && targets.length\n ? targets\n : this.state.originTabId != null\n ? [this.state.originTabId]\n : [];\n for (const tabId of list) {\n chrome.tabs.sendMessage(\n tabId,\n { action: TOOL_MESSAGE_TYPES.RR_TIMELINE_UPDATE, steps: fullSteps },\n { frameId: 0 },\n );\n }\n } catch {}\n }\n}\n\n// Singleton for wiring convenience\nexport const recordingSession = new RecordingSessionManager();\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/rr-utils.ts", "content": "// rr-utils.ts — shared helpers for record-replay runner\n// Note: comments in English\n\nimport {\n TOOL_NAMES,\n topoOrder as sharedTopoOrder,\n mapNodeToStep as sharedMapNodeToStep,\n} from 'chrome-mcp-shared';\nimport type { Edge as DagEdge, NodeBase as DagNode, Step } from './types';\nimport { handleCallTool } from '../tools';\nimport { EDGE_LABELS } from 'chrome-mcp-shared';\n\nexport function applyAssign(\n target: Record,\n source: any,\n assign: Record,\n) {\n const getByPath = (obj: any, path: string) => {\n try {\n const parts = path\n .replace(/\\[(\\d+)\\]/g, '.$1')\n .split('.')\n .filter(Boolean);\n let cur = obj;\n for (const p of parts) {\n if (cur == null) return undefined;\n cur = (cur as any)[p as any];\n }\n return cur;\n } catch {\n return undefined;\n }\n };\n for (const [k, v] of Object.entries(assign || {})) {\n target[k] = getByPath(source, String(v));\n }\n}\n\nexport function expandTemplatesDeep(value: T, scope: Record): T {\n const replaceOne = (s: string) =>\n s.replace(/\\{([^}]+)\\}/g, (_m, k) => (scope[k] ?? '').toString());\n const walk = (v: any): any => {\n if (v == null) return v;\n if (typeof v === 'string') return replaceOne(v);\n if (Array.isArray(v)) return v.map((x) => walk(x));\n if (typeof v === 'object') {\n const out: any = {};\n for (const [k, val] of Object.entries(v)) out[k] = walk(val);\n return out;\n }\n return v;\n };\n return walk(value);\n}\n\nexport async function ensureTab(options: {\n tabTarget?: 'current' | 'new';\n startUrl?: string;\n refresh?: boolean;\n}): Promise<{ tabId: number; url?: string }> {\n const target = options.tabTarget || 'current';\n const startUrl = options.startUrl;\n const isWebUrl = (u?: string | null) => !!u && /^(https?:|file:)/i.test(u);\n\n const tabs = await chrome.tabs.query({ currentWindow: true });\n const [active] = tabs.filter((t) => t.active);\n\n if (target === 'new') {\n let urlToOpen = startUrl;\n if (!urlToOpen) urlToOpen = isWebUrl(active?.url) ? active!.url! : 'about:blank';\n const created = await chrome.tabs.create({ url: urlToOpen, active: true });\n await new Promise((r) => setTimeout(r, 300));\n return { tabId: created.id!, url: created.url };\n }\n\n // current tab target\n if (startUrl) {\n await handleCallTool({ name: TOOL_NAMES.BROWSER.NAVIGATE, args: { url: startUrl } });\n } else if (options.refresh) {\n // only refresh if current tab is a web page\n if (isWebUrl(active?.url))\n await handleCallTool({ name: TOOL_NAMES.BROWSER.NAVIGATE, args: { refresh: true } });\n }\n\n // Re-evaluate active after potential navigation\n const cur = (await chrome.tabs.query({ active: true, currentWindow: true }))[0];\n let tabId = cur?.id;\n let url = cur?.url;\n\n // If still on extension/internal page and no startUrl, try switch to an existing web tab\n if (!isWebUrl(url) && !startUrl) {\n const candidate = tabs.find((t) => isWebUrl(t.url));\n if (candidate?.id) {\n await chrome.tabs.update(candidate.id, { active: true });\n tabId = candidate.id;\n url = candidate.url;\n }\n }\n return { tabId: tabId!, url };\n}\n\nexport async function waitForNetworkIdle(totalTimeoutMs: number, idleThresholdMs: number) {\n const deadline = Date.now() + Math.max(500, totalTimeoutMs);\n const threshold = Math.max(200, idleThresholdMs);\n while (Date.now() < deadline) {\n await handleCallTool({\n name: TOOL_NAMES.BROWSER.NETWORK_CAPTURE_START,\n args: {\n includeStatic: false,\n // Ensure capture remains active until we explicitly stop it\n maxCaptureTime: Math.min(60_000, Math.max(threshold + 500, 2_000)),\n inactivityTimeout: 0,\n },\n });\n await new Promise((r) => setTimeout(r, threshold + 200));\n const stopRes = await handleCallTool({\n name: TOOL_NAMES.BROWSER.NETWORK_CAPTURE_STOP,\n args: {},\n });\n const text = (stopRes as any)?.content?.find((c: any) => c.type === 'text')?.text;\n try {\n const json = text ? JSON.parse(text) : null;\n const captureEnd = Number(json?.captureEndTime) || Date.now();\n const reqs: any[] = Array.isArray(json?.requests) ? json.requests : [];\n const lastActivity = reqs.reduce(\n (acc, r) => {\n const t = Number(r.responseTime || r.requestTime || 0);\n return t > acc ? t : acc;\n },\n Number(json?.captureStartTime || 0),\n );\n if (captureEnd - lastActivity >= threshold) return; // idle reached\n } catch {\n // ignore parse errors\n }\n await new Promise((r) => setTimeout(r, Math.min(500, threshold)));\n }\n throw new Error('wait for network idle timed out');\n}\n\n// Event-driven navigation wait helper\n// Waits for top-frame navigation completion or SPA history updates on active tab.\n// Falls back to short network idle on timeout.\nexport async function waitForNavigation(timeoutMs?: number, prevUrl?: string): Promise {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n if (typeof tabId !== 'number') throw new Error('Active tab not found');\n const timeout = Math.max(1000, Math.min(timeoutMs || 15000, 30000));\n const startedAt = Date.now();\n\n await new Promise((resolve, reject) => {\n let done = false;\n let timer: any = null;\n const cleanup = () => {\n try {\n chrome.webNavigation.onCommitted.removeListener(onCommitted);\n } catch {}\n try {\n chrome.webNavigation.onCompleted.removeListener(onCompleted);\n } catch {}\n try {\n (chrome.webNavigation as any).onHistoryStateUpdated?.removeListener?.(\n onHistoryStateUpdated,\n );\n } catch {}\n try {\n chrome.tabs.onUpdated.removeListener(onTabUpdated);\n } catch {}\n if (timer) {\n try {\n clearTimeout(timer);\n } catch {}\n }\n };\n const finish = () => {\n if (done) return;\n done = true;\n cleanup();\n resolve();\n };\n const onCommitted = (details: any) => {\n if (\n details &&\n details.tabId === tabId &&\n details.frameId === 0 &&\n details.timeStamp >= startedAt\n ) {\n // committed observed; we'll wait for completion or SPA fallback\n }\n };\n const onCompleted = (details: any) => {\n if (\n details &&\n details.tabId === tabId &&\n details.frameId === 0 &&\n details.timeStamp >= startedAt\n )\n finish();\n };\n const onHistoryStateUpdated = (details: any) => {\n if (\n details &&\n details.tabId === tabId &&\n details.frameId === 0 &&\n details.timeStamp >= startedAt\n )\n finish();\n };\n const onTabUpdated = (updatedTabId: number, changeInfo: chrome.tabs.TabChangeInfo) => {\n if (updatedTabId !== tabId) return;\n if (changeInfo.status === 'complete') finish();\n if (typeof changeInfo.url === 'string' && (!prevUrl || changeInfo.url !== prevUrl)) finish();\n };\n const onTimeout = async () => {\n cleanup();\n try {\n await waitForNetworkIdle(2000, 800);\n resolve();\n } catch {\n reject(new Error('navigation timeout'));\n }\n };\n\n chrome.webNavigation.onCommitted.addListener(onCommitted);\n chrome.webNavigation.onCompleted.addListener(onCompleted);\n try {\n (chrome.webNavigation as any).onHistoryStateUpdated?.addListener?.(onHistoryStateUpdated);\n } catch {}\n chrome.tabs.onUpdated.addListener(onTabUpdated);\n timer = setTimeout(onTimeout, timeout);\n });\n}\n\nexport function topoOrder(nodes: DagNode[], edges: DagEdge[]): DagNode[] {\n return sharedTopoOrder(nodes, edges as any);\n}\n\n// Helper: filter only default edges (no label or label === 'default')\nexport function defaultEdgesOnly(edges: DagEdge[] = []): DagEdge[] {\n return (edges || []).filter((e) => !e.label || e.label === EDGE_LABELS.DEFAULT);\n}\n\nexport function mapDagNodeToStep(n: DagNode): Step {\n const s: any = sharedMapNodeToStep(n as any);\n if ((n as any)?.type === 'if') {\n // forward extended conditional config for DAG mode\n const cfg: any = (n as any).config || {};\n if (Array.isArray(cfg.branches)) s.branches = cfg.branches;\n if ('else' in cfg) s.else = cfg.else;\n if (cfg.condition && !s.condition) s.condition = cfg.condition; // backward-compat\n }\n return s as Step;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/selector-engine.ts", "content": "import { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { TargetLocator, SelectorCandidate } from './types';\n\n// design note: minimal selector engine that tries ref then candidates\n\nexport interface LocatedElement {\n ref?: string;\n center?: { x: number; y: number };\n resolvedBy?: 'ref' | SelectorCandidate['type'];\n frameId?: number;\n}\n\n// Helper: decide whether selector is a composite cross-frame selector\nfunction isCompositeSelector(sel: string): boolean {\n return typeof sel === 'string' && sel.includes('|>');\n}\n\n// Helper: typed wrapper for chrome.tabs.sendMessage with optional frameId\nasync function sendToTab(tabId: number, message: any, frameId?: number): Promise {\n if (typeof frameId === 'number') {\n return await chrome.tabs.sendMessage(tabId, message, { frameId });\n }\n return await chrome.tabs.sendMessage(tabId, message);\n}\n\n// Helper: ensure ref for a selector, handling composite selectors and mapping frameId\nasync function ensureRefForSelector(\n tabId: number,\n selector: string,\n frameId?: number,\n): Promise<{ ref: string; center: { x: number; y: number }; frameId?: number } | null> {\n try {\n let ensured: any = null;\n if (isCompositeSelector(selector)) {\n // Always query top for composite; helper will bridge to child and return href\n ensured = await sendToTab(tabId, {\n action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR,\n selector,\n });\n } else {\n ensured = await sendToTab(\n tabId,\n { action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR, selector },\n frameId,\n );\n }\n if (!ensured || !ensured.success || !ensured.ref || !ensured.center) return null;\n // Map frameId when composite via returned href\n let locFrameId: number | undefined = undefined;\n if (isCompositeSelector(selector) && ensured.href) {\n try {\n const frames = (await chrome.webNavigation.getAllFrames({ tabId })) as any[];\n const match = frames?.find((f) => typeof f.url === 'string' && f.url === ensured.href);\n if (match) locFrameId = match.frameId;\n } catch {}\n }\n return { ref: ensured.ref, center: ensured.center, frameId: locFrameId };\n } catch {\n return null;\n }\n}\n\n/**\n * Try to resolve an element using ref or candidates via content scripts\n */\nexport async function locateElement(\n tabId: number,\n target: TargetLocator,\n frameId?: number,\n): Promise {\n // 0) Fast path: try primary selector if provided\n const primarySel = (target as any)?.selector ? String((target as any).selector).trim() : '';\n if (primarySel) {\n const ensured = await ensureRefForSelector(tabId, primarySel, frameId);\n if (ensured) return { ...ensured, resolvedBy: 'css' };\n }\n\n // 1) Non-text candidates first for stability (css/attr/aria/xpath)\n const nonText = (target.candidates || []).filter((c) => c.type !== 'text');\n for (const c of nonText) {\n try {\n if (c.type === 'css' || c.type === 'attr') {\n const ensured = await ensureRefForSelector(tabId, String(c.value || ''), frameId);\n if (ensured) return { ...ensured, resolvedBy: c.type };\n } else if (c.type === 'aria') {\n // Minimal ARIA role+name parser like: \"button[name=提交]\" or \"textbox[name=用户名]\"\n const v = String(c.value || '').trim();\n const m = v.match(/^(\\w+)\\s*\\[\\s*name\\s*=\\s*([^\\]]+)\\]$/);\n const role = m ? m[1] : '';\n const name = m ? m[2] : '';\n const cleanName = name.replace(/^['\"]|['\"]$/g, '');\n const ariaSelectors: string[] = [];\n if (role === 'textbox') {\n ariaSelectors.push(\n `[role=\"textbox\"][aria-label=${JSON.stringify(cleanName)}]`,\n `input[aria-label=${JSON.stringify(cleanName)}]`,\n `textarea[aria-label=${JSON.stringify(cleanName)}]`,\n );\n } else if (role === 'button') {\n ariaSelectors.push(\n `[role=\"button\"][aria-label=${JSON.stringify(cleanName)}]`,\n `button[aria-label=${JSON.stringify(cleanName)}]`,\n );\n } else if (role === 'link') {\n ariaSelectors.push(\n `[role=\"link\"][aria-label=${JSON.stringify(cleanName)}]`,\n `a[aria-label=${JSON.stringify(cleanName)}]`,\n );\n }\n if (!ariaSelectors.length && role) {\n ariaSelectors.push(\n `[role=${JSON.stringify(role)}][aria-label=${JSON.stringify(cleanName)}]`,\n );\n }\n for (const sel of ariaSelectors) {\n const ensured = await sendToTab(\n tabId,\n { action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR, selector: sel } as any,\n frameId,\n );\n if (ensured && ensured.success && ensured.ref && ensured.center) {\n return { ref: ensured.ref, center: ensured.center, resolvedBy: c.type, frameId };\n }\n }\n } else if (c.type === 'xpath') {\n // Minimal xpath support via document.evaluate through injected helper\n const ensured = await sendToTab(\n tabId,\n {\n action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR,\n selector: c.value,\n isXPath: true,\n } as any,\n frameId,\n );\n if (ensured && ensured.success && ensured.ref && ensured.center) {\n return { ref: ensured.ref, center: ensured.center, resolvedBy: c.type, frameId };\n }\n }\n } catch (e) {\n // continue to next candidate\n }\n }\n // 2) Human-intent fallback: text-based search as last resort\n const textCands = (target.candidates || []).filter((c) => c.type === 'text');\n const tagName = ((target as any)?.tag || '').toString();\n for (const c of textCands) {\n try {\n const ensured = await sendToTab(\n tabId,\n {\n action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR,\n useText: true,\n text: c.value,\n tagName,\n } as any,\n frameId,\n );\n if (ensured && ensured.success && ensured.ref && ensured.center) {\n return { ref: ensured.ref, center: ensured.center, resolvedBy: c.type };\n }\n } catch {}\n }\n // Fallback: try ref (works when ref was produced in the same page lifecycle)\n if (target.ref) {\n try {\n const res = await sendToTab(\n tabId,\n { action: TOOL_MESSAGE_TYPES.RESOLVE_REF, ref: target.ref } as any,\n frameId,\n );\n if (res && res.success && res.center) {\n return { ref: target.ref, center: res.center, resolvedBy: 'ref' };\n }\n } catch (e) {\n // ignore\n }\n }\n return null;\n}\n\n/**\n * Ensure screenshot context hostname is still valid for coordinate-based actions\n */\n// Note: screenshot hostname validation is handled elsewhere; removed legacy stub.\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/storage/indexeddb-manager.ts", "content": "// indexeddb-manager.ts\n// IndexedDB storage manager for Record & Replay data.\n// Stores: flows, runs, published, schedules, triggers.\n\nimport type { Flow, RunRecord } from '../types';\nimport type { FlowSchedule } from '../flow-store';\nimport type { PublishedFlowInfo } from '../flow-store';\nimport type { FlowTrigger } from '../trigger-store';\nimport { IndexedDbClient } from '@/utils/indexeddb-client';\n\ntype StoreName = 'flows' | 'runs' | 'published' | 'schedules' | 'triggers';\n\nconst DB_NAME = 'rr_storage';\n// Version history:\n// v1: Initial schema with flows, runs, published, schedules, triggers stores\n// v2: (Previous iteration - no schema change, version was bumped during development)\n// v3: Current - ensure all stores exist, support upgrade from any previous version\nconst DB_VERSION = 3;\n\nconst REQUIRED_STORES = ['flows', 'runs', 'published', 'schedules', 'triggers'] as const;\n\nconst idb = new IndexedDbClient(DB_NAME, DB_VERSION, (db, oldVersion) => {\n // Idempotent upgrade: ensure all required stores exist regardless of oldVersion\n // This handles both fresh installs (oldVersion=0) and upgrades from any version\n for (const storeName of REQUIRED_STORES) {\n if (!db.objectStoreNames.contains(storeName)) {\n db.createObjectStore(storeName, { keyPath: 'id' });\n }\n }\n});\n\nconst tx = (\n store: StoreName,\n mode: IDBTransactionMode,\n op: (s: IDBObjectStore, t: IDBTransaction) => T | Promise,\n) => idb.tx(store, mode, op);\n\nasync function getAll(store: StoreName): Promise {\n return idb.getAll(store);\n}\n\nasync function getOne(store: StoreName, key: string): Promise {\n return idb.get(store, key);\n}\n\nasync function putOne(store: StoreName, value: T): Promise {\n return idb.put(store, value);\n}\n\nasync function deleteOne(store: StoreName, key: string): Promise {\n return idb.delete(store, key);\n}\n\nasync function clearStore(store: StoreName): Promise {\n return idb.clear(store);\n}\n\nasync function putMany(storeName: StoreName, values: T[]): Promise {\n return idb.putMany(storeName, values);\n}\n\nexport const IndexedDbStorage = {\n flows: {\n async list(): Promise {\n return getAll('flows');\n },\n async get(id: string): Promise {\n return getOne('flows', id);\n },\n async save(flow: Flow): Promise {\n return putOne('flows', flow);\n },\n async delete(id: string): Promise {\n return deleteOne('flows', id);\n },\n },\n runs: {\n async list(): Promise {\n return getAll('runs');\n },\n async save(record: RunRecord): Promise {\n return putOne('runs', record);\n },\n async replaceAll(records: RunRecord[]): Promise {\n return tx('runs', 'readwrite', async (st) => {\n st.clear();\n for (const r of records) st.put(r);\n return;\n });\n },\n },\n published: {\n async list(): Promise {\n return getAll('published');\n },\n async save(info: PublishedFlowInfo): Promise {\n return putOne('published', info);\n },\n async delete(id: string): Promise {\n return deleteOne('published', id);\n },\n },\n schedules: {\n async list(): Promise {\n return getAll('schedules');\n },\n async save(s: FlowSchedule): Promise {\n return putOne('schedules', s);\n },\n async delete(id: string): Promise {\n return deleteOne('schedules', id);\n },\n },\n triggers: {\n async list(): Promise {\n return getAll('triggers');\n },\n async save(t: FlowTrigger): Promise {\n return putOne('triggers', t);\n },\n async delete(id: string): Promise {\n return deleteOne('triggers', id);\n },\n },\n};\n\n// One-time migration from chrome.storage.local to IndexedDB\nlet migrationPromise: Promise | null = null;\nlet migrationFailed = false;\n\nexport async function ensureMigratedFromLocal(): Promise {\n // If previous migration failed, allow retry\n if (migrationFailed) {\n migrationPromise = null;\n migrationFailed = false;\n }\n if (migrationPromise) return migrationPromise;\n\n migrationPromise = (async () => {\n try {\n const flag = await chrome.storage.local.get(['rr_idb_migrated']);\n if (flag && flag['rr_idb_migrated']) return;\n\n // Read existing data from chrome.storage.local\n const res = await chrome.storage.local.get([\n 'rr_flows',\n 'rr_runs',\n 'rr_published_flows',\n 'rr_schedules',\n 'rr_triggers',\n ]);\n const flows = (res['rr_flows'] as Flow[]) || [];\n const runs = (res['rr_runs'] as RunRecord[]) || [];\n const published = (res['rr_published_flows'] as PublishedFlowInfo[]) || [];\n const schedules = (res['rr_schedules'] as FlowSchedule[]) || [];\n const triggers = (res['rr_triggers'] as FlowTrigger[]) || [];\n\n // Write into IDB\n if (flows.length) await putMany('flows', flows);\n if (runs.length) await putMany('runs', runs);\n if (published.length) await putMany('published', published);\n if (schedules.length) await putMany('schedules', schedules);\n if (triggers.length) await putMany('triggers', triggers);\n\n await chrome.storage.local.set({ rr_idb_migrated: true });\n } catch (e) {\n migrationFailed = true;\n console.error('IndexedDbStorage migration failed:', e);\n // Re-throw to let callers know migration failed\n throw e;\n }\n })();\n return migrationPromise;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/trigger-store.ts", "content": "import { IndexedDbStorage, ensureMigratedFromLocal } from './storage/indexeddb-manager';\n\nexport type TriggerType = 'url' | 'contextMenu' | 'command' | 'dom';\n\nexport interface BaseTrigger {\n id: string;\n type: TriggerType;\n enabled: boolean;\n flowId: string;\n args?: Record;\n}\n\nexport interface UrlTrigger extends BaseTrigger {\n type: 'url';\n match: Array<{ kind: 'url' | 'domain' | 'path'; value: string }>;\n}\n\nexport interface ContextMenuTrigger extends BaseTrigger {\n type: 'contextMenu';\n title: string;\n contexts?: chrome.contextMenus.ContextType[];\n}\n\nexport interface CommandTrigger extends BaseTrigger {\n type: 'command';\n commandKey: string; // e.g., run_quick_trigger_1\n}\n\nexport interface DomTrigger extends BaseTrigger {\n type: 'dom';\n selector: string;\n appear?: boolean; // default true\n once?: boolean; // default true\n debounceMs?: number; // default 800\n}\n\nexport type FlowTrigger = UrlTrigger | ContextMenuTrigger | CommandTrigger | DomTrigger;\n\nexport async function listTriggers(): Promise {\n await ensureMigratedFromLocal();\n return await IndexedDbStorage.triggers.list();\n}\n\nexport async function saveTrigger(t: FlowTrigger): Promise {\n await ensureMigratedFromLocal();\n await IndexedDbStorage.triggers.save(t);\n}\n\nexport async function deleteTrigger(id: string): Promise {\n await ensureMigratedFromLocal();\n await IndexedDbStorage.triggers.delete(id);\n}\n\nexport function toId(prefix = 'trg') {\n return `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay/types.ts", "content": "/**\n * Record & Replay Core Types\n *\n * This file contains the core type definitions for the record-replay system.\n * Legacy Step types have been moved to ./legacy-types.ts and are re-exported\n * here for backward compatibility.\n *\n * Type system architecture:\n * - Legacy types (./legacy-types.ts): Step-based execution model (being phased out)\n * - Action types (./actions/types.ts): DAG-based execution model (new standard)\n * - Core types (this file): Flow, Node, Edge, Run records (shared by both)\n */\n\nimport { NODE_TYPES } from '@/common/node-types';\n\n// =============================================================================\n// Re-export Legacy Types for Backward Compatibility\n// =============================================================================\n\nexport type {\n // Selector types\n SelectorType,\n SelectorCandidate,\n TargetLocator,\n // Step types\n StepType,\n StepBase,\n StepClick,\n StepFill,\n StepTriggerEvent,\n StepSetAttribute,\n StepScreenshot,\n StepSwitchFrame,\n StepLoopElements,\n StepKey,\n StepScroll,\n StepDrag,\n StepWait,\n StepAssert,\n StepScript,\n StepIf,\n StepForeach,\n StepWhile,\n StepHttp,\n StepExtract,\n StepOpenTab,\n StepSwitchTab,\n StepCloseTab,\n StepNavigate,\n StepHandleDownload,\n StepExecuteFlow,\n Step,\n} from './legacy-types';\n\n// Import Step type for use in Flow interface\nimport type { Step } from './legacy-types';\n\n// =============================================================================\n// Variable Definitions\n// =============================================================================\n\nexport type VariableType = 'string' | 'number' | 'boolean' | 'enum' | 'array';\n\nexport interface VariableDef {\n key: string;\n label?: string;\n sensitive?: boolean;\n // default value can be string/number/boolean/array depending on type\n default?: any; // keep broad for backward compatibility\n type?: VariableType; // default to 'string' when omitted\n rules?: { required?: boolean; pattern?: string; enum?: string[] };\n}\n\n// =============================================================================\n// DAG Node and Edge Types (Flow V2)\n// =============================================================================\n\nexport type NodeType = (typeof NODE_TYPES)[keyof typeof NODE_TYPES];\n\nexport interface NodeBase {\n id: string;\n type: NodeType;\n name?: string;\n disabled?: boolean;\n config?: any;\n ui?: { x: number; y: number };\n}\n\nexport interface Edge {\n id: string;\n from: string;\n to: string;\n // label identifies the logical branch. Keep 'default' for linear/main path.\n // For conditionals, use arbitrary strings like 'case:' or 'else'.\n label?: string;\n}\n\n// =============================================================================\n// Flow Definition\n// =============================================================================\n\nexport interface Flow {\n id: string;\n name: string;\n description?: string;\n version: number;\n meta?: {\n createdAt: string;\n updatedAt: string;\n domain?: string;\n tags?: string[];\n bindings?: Array<{ type: 'domain' | 'path' | 'url'; value: string }>;\n tool?: { category?: string; description?: string };\n exposedOutputs?: Array<{ nodeId: string; as: string }>;\n /** Recording stop barrier status (used during recording stop) */\n stopBarrier?: {\n ok: boolean;\n sessionId?: string;\n stoppedAt?: string;\n failed?: Array<{\n tabId: number;\n skipped?: boolean;\n reason?: string;\n topTimedOut?: boolean;\n topError?: string;\n subframesFailed?: number;\n }>;\n };\n };\n variables?: VariableDef[];\n /**\n * @deprecated Use nodes/edges instead. This field is no longer written to storage.\n * Kept as optional for backward compatibility with existing flows and imports.\n */\n steps?: Step[];\n // Flow V2: DAG-based execution model\n nodes?: NodeBase[];\n edges?: Edge[];\n subflows?: Record;\n}\n\n// =============================================================================\n// Run Records and Results\n// =============================================================================\n\nexport interface RunLogEntry {\n stepId: string;\n status: 'success' | 'failed' | 'retrying' | 'warning';\n message?: string;\n tookMs?: number;\n screenshotBase64?: string; // small thumbnail (optional)\n consoleSnippets?: string[]; // critical lines\n networkSnippets?: Array<{ method: string; url: string; status?: number; ms?: number }>;\n // selector fallback info\n fallbackUsed?: boolean;\n fallbackFrom?: string;\n fallbackTo?: string;\n}\n\nexport interface RunRecord {\n id: string;\n flowId: string;\n startedAt: string;\n finishedAt?: string;\n success?: boolean;\n entries: RunLogEntry[];\n}\n\nexport interface RunResult {\n runId: string;\n success: boolean;\n summary: { total: number; success: number; failed: number; tookMs: number };\n url?: string | null;\n outputs?: Record | null;\n logs?: RunLogEntry[];\n screenshots?: { onFailure?: string | null };\n paused?: boolean; // when true, the run was intentionally paused (e.g., breakpoint)\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/bootstrap.ts", "content": "/**\n * @fileoverview Record-Replay V3 composition root (bootstrap)\n * @description\n * Wires storage, events, scheduler, triggers and RPC for the MV3 background service worker.\n *\n * 设计说明：\n * - 必须先执行 recoverFromCrash() 再启动 scheduler.start()\n * - 使用全局单例 keepalive-manager 避免多个控制器冲突\n * - RunExecutor 使用 RunRunner 执行实际的 Flow\n */\n\nimport type { UnixMillis } from './domain/json';\nimport type { RunId } from './domain/ids';\nimport { RR_ERROR_CODES, createRRError, type RRError } from './domain/errors';\n\nimport type { StoragePort } from './engine/storage/storage-port';\nimport { StorageBackedEventsBus, type EventsBus } from './engine/transport/events-bus';\n\nimport { DEFAULT_QUEUE_CONFIG, type RunQueueItem } from './engine/queue/queue';\nimport { createLeaseManager, generateOwnerId, type LeaseManager } from './engine/queue/leasing';\nimport { createRunScheduler, type RunExecutor, type RunScheduler } from './engine/queue/scheduler';\nimport { recoverFromCrash } from './engine/recovery/recovery-coordinator';\n\nimport { RpcServer } from './engine/transport/rpc-server';\n\nimport { createTriggerManager, type TriggerManager } from './engine/triggers/trigger-manager';\nimport { createUrlTriggerHandlerFactory } from './engine/triggers/url-trigger';\nimport { createCommandTriggerHandlerFactory } from './engine/triggers/command-trigger';\nimport { createContextMenuTriggerHandlerFactory } from './engine/triggers/context-menu-trigger';\nimport { createDomTriggerHandlerFactory } from './engine/triggers/dom-trigger';\nimport { createCronTriggerHandlerFactory } from './engine/triggers/cron-trigger';\nimport { createIntervalTriggerHandlerFactory } from './engine/triggers/interval-trigger';\nimport { createOnceTriggerHandlerFactory } from './engine/triggers/once-trigger';\nimport { createManualTriggerHandlerFactory } from './engine/triggers/manual-trigger';\n\nimport { createChromeArtifactService } from './engine/kernel/artifacts';\nimport { createRunRunnerFactory, type RunRunnerFactory } from './engine/kernel/runner';\nimport {\n createDebugController,\n createRunnerRegistry,\n type DebugController,\n type RunnerRegistry,\n} from './engine/kernel/debug-controller';\n\nimport { PluginRegistry } from './engine/plugins/registry';\nimport {\n registerV2ReplayNodesAsV3Nodes,\n DEFAULT_V2_EXCLUDE_LIST,\n} from './engine/plugins/register-v2-replay-nodes';\n\nimport { acquireKeepalive } from '../keepalive-manager';\nimport { createStoragePort } from './index';\n\n// ==================== Types ====================\n\ntype Logger = Pick;\n\n/**\n * V3 运行时句柄\n */\nexport interface V3Runtime {\n ownerId: string;\n storage: StoragePort;\n events: EventsBus;\n leaseManager: LeaseManager;\n scheduler: RunScheduler;\n runners: RunnerRegistry;\n debugController: DebugController;\n triggers: TriggerManager;\n rpcServer: RpcServer;\n stop(): Promise;\n}\n\n// ==================== Singleton State ====================\n\nlet runtime: V3Runtime | null = null;\nlet bootstrapPromise: Promise | null = null;\n\n// ==================== Utilities ====================\n\nfunction errorMessage(err: unknown): string {\n if (err instanceof Error) return err.message;\n if (err && typeof err === 'object' && 'message' in err)\n return String((err as { message: unknown }).message);\n return String(err);\n}\n\nfunction isFiniteNumber(v: unknown): v is number {\n return typeof v === 'number' && Number.isFinite(v);\n}\n\nasync function tabExists(tabId: number): Promise {\n try {\n await chrome.tabs.get(tabId);\n return true;\n } catch {\n return false;\n }\n}\n\nasync function createEphemeralTab(logger: Logger): Promise {\n const tab = await chrome.tabs.create({ url: 'about:blank', active: false });\n if (tab.id === undefined) {\n throw new Error('chrome.tabs.create returned a tab without id');\n }\n logger.debug(`[RR-V3] Allocated ephemeral tab ${tab.id}`);\n return tab.id;\n}\n\nasync function safeRemoveTab(tabId: number, logger: Logger): Promise {\n try {\n await chrome.tabs.remove(tabId);\n } catch (e) {\n logger.debug(`[RR-V3] Failed to close tab ${tabId}:`, e);\n }\n}\n\n/**\n * 解析运行 Run 所需的 Tab ID\n * 优先级: run.tabId > queue.tabId > trigger.sourceTabId > 创建新 Tab\n */\nasync function resolveRunTab(input: {\n runTabId?: number;\n queueTabId?: number;\n triggerTabId?: number;\n logger: Logger;\n}): Promise<{ tabId: number; shouldClose: boolean }> {\n const candidates = [input.runTabId, input.queueTabId, input.triggerTabId].filter(\n (x): x is number => isFiniteNumber(x),\n );\n\n for (const tabId of candidates) {\n if (await tabExists(tabId)) {\n return { tabId, shouldClose: false };\n }\n }\n\n const tabId = await createEphemeralTab(input.logger);\n return { tabId, shouldClose: true };\n}\n\n/**\n * 将 Run 标记为失败\n * 注意：会重新读取最新的 RunRecord 以获取正确的 startedAt\n */\nasync function failRun(\n deps: { storage: StoragePort; events: EventsBus; now: () => UnixMillis; logger: Logger },\n runId: RunId,\n error: RRError,\n): Promise {\n const finishedAt = deps.now();\n\n // 重新获取最新的 run 记录以获取正确的 startedAt\n let startedAt = finishedAt;\n try {\n const latestRun = await deps.storage.runs.get(runId);\n if (latestRun?.startedAt !== undefined) {\n startedAt = latestRun.startedAt;\n }\n } catch {\n // ignore - use finishedAt as startedAt\n }\n\n const tookMs = Math.max(0, finishedAt - startedAt);\n\n try {\n await deps.storage.runs.patch(runId, {\n status: 'failed',\n finishedAt,\n tookMs,\n error,\n });\n } catch (e) {\n deps.logger.error(`[RR-V3] Failed to patch run \"${runId}\" as failed:`, e);\n return;\n }\n\n try {\n await deps.events.append({ runId, type: 'run.failed', error });\n } catch (e) {\n deps.logger.warn(`[RR-V3] Failed to append run.failed for \"${runId}\":`, e);\n }\n}\n\n// ==================== Run Executor ====================\n\n/**\n * 创建默认的 RunExecutor\n * 使用 RunRunner 执行 Flow\n */\nfunction createDefaultRunExecutor(deps: {\n storage: StoragePort;\n events: EventsBus;\n runnerFactory: RunRunnerFactory;\n runners: RunnerRegistry;\n now: () => UnixMillis;\n logger: Logger;\n}): RunExecutor {\n return async (item: RunQueueItem): Promise => {\n const runId = item.id;\n\n // 1. 获取 RunRecord\n const run = await deps.storage.runs.get(runId);\n if (!run) {\n deps.logger.warn(`[RR-V3] RunRecord not found for queue item \"${runId}\", skipping execution`);\n return;\n }\n\n // 2. 获取 Flow\n const flow = await deps.storage.flows.get(item.flowId);\n if (!flow) {\n await failRun(\n deps,\n runId,\n createRRError(RR_ERROR_CODES.VALIDATION_ERROR, `Flow \"${item.flowId}\" not found`),\n );\n return;\n }\n\n // 3. 解析 Tab ID\n const { tabId, shouldClose } = await resolveRunTab({\n runTabId: run.tabId,\n queueTabId: item.tabId,\n triggerTabId: item.trigger?.sourceTabId,\n logger: deps.logger,\n });\n\n // 4. 同步 attempt 到 RunRecord\n try {\n await deps.storage.runs.patch(runId, {\n attempt: item.attempt,\n maxAttempts: item.maxAttempts,\n tabId,\n });\n } catch (e) {\n deps.logger.debug(`[RR-V3] Failed to patch run \"${runId}\" attempt/tabId:`, e);\n }\n\n // 5. 执行 Run\n let runner;\n try {\n runner = deps.runnerFactory.create(runId, {\n flow,\n tabId,\n args: item.args,\n startNodeId: run.startNodeId,\n debug: item.debug,\n });\n\n // 注册到 RunnerRegistry，供 DebugController 和 RPC 使用\n deps.runners.register(runId, runner);\n\n await runner.start();\n } catch (e) {\n await failRun(\n deps,\n runId,\n createRRError(RR_ERROR_CODES.INTERNAL, `Executor crashed: ${errorMessage(e)}`),\n );\n } finally {\n // 6. 注销 Runner\n if (runner) {\n deps.runners.unregister(runId);\n }\n\n // 7. 清理临时 Tab\n if (shouldClose) {\n await safeRemoveTab(tabId, deps.logger);\n }\n }\n };\n}\n\n// ==================== Bootstrap ====================\n\n/**\n * 启动 RR-V3 运行时\n * @returns 运行时句柄\n */\nexport async function bootstrapV3(): Promise {\n if (runtime) return runtime;\n if (bootstrapPromise) return bootstrapPromise;\n\n bootstrapPromise = (async () => {\n const logger: Logger = console;\n const now = (): UnixMillis => Date.now();\n\n logger.info('[RR-V3] Bootstrapping...');\n\n // 1) Storage\n const storage = createStoragePort();\n\n // 2) EventsBus\n const events: EventsBus = new StorageBackedEventsBus(storage.events);\n\n // 3) Lease owner identity (per SW instance)\n const ownerId = generateOwnerId();\n logger.debug(`[RR-V3] Owner ID: ${ownerId}`);\n\n // 4) LeaseManager\n const leaseManager = createLeaseManager(storage.queue, DEFAULT_QUEUE_CONFIG);\n\n // 5) RunnerRegistry + DebugController\n const runners = createRunnerRegistry();\n const debugController = createDebugController({ storage, events, runners });\n\n // 6) Keepalive (reuse global singleton to avoid multiple controllers fighting)\n const keepalive = {\n acquire: (tag: string) => acquireKeepalive(`rr_v3:${tag}`),\n };\n\n // 7) PluginRegistry - register V2 action handlers as V3 nodes\n const plugins = new PluginRegistry();\n const registeredNodes = registerV2ReplayNodesAsV3Nodes(plugins, {\n // Exclude control directives that V3 runner doesn't support\n exclude: [...DEFAULT_V2_EXCLUDE_LIST],\n });\n logger.debug(`[RR-V3] Registered ${registeredNodes.length} V2 action handlers as V3 nodes`);\n\n // 8) RunExecutor via RunRunnerFactory\n const runnerFactory = createRunRunnerFactory({\n storage,\n events,\n plugins,\n artifactService: createChromeArtifactService(),\n now,\n });\n\n const execute = createDefaultRunExecutor({\n storage,\n events,\n runnerFactory,\n runners,\n now,\n logger,\n });\n\n // 7) Scheduler\n const scheduler = createRunScheduler({\n queue: storage.queue,\n leaseManager,\n keepalive,\n config: DEFAULT_QUEUE_CONFIG,\n ownerId,\n execute,\n now,\n logger,\n });\n\n // 8) TriggerManager\n const triggers = createTriggerManager({\n storage,\n events,\n scheduler,\n handlerFactories: {\n url: createUrlTriggerHandlerFactory({ logger }),\n command: createCommandTriggerHandlerFactory({ logger }),\n contextMenu: createContextMenuTriggerHandlerFactory({ logger }),\n dom: createDomTriggerHandlerFactory({ logger }),\n cron: createCronTriggerHandlerFactory({ logger, now }),\n interval: createIntervalTriggerHandlerFactory({ logger }),\n once: createOnceTriggerHandlerFactory({ logger }),\n manual: createManualTriggerHandlerFactory({ logger }),\n },\n now,\n logger,\n });\n\n // 10) RpcServer (created but started after recovery)\n const rpcServer = new RpcServer({\n storage,\n events,\n scheduler,\n debugController,\n runners,\n triggerManager: triggers,\n now,\n });\n\n // Cleanup helper for error recovery\n const cleanup = async (): Promise => {\n try {\n rpcServer.stop();\n } catch {\n /* ignore */\n }\n try {\n await triggers.stop();\n } catch {\n /* ignore */\n }\n try {\n scheduler.stop();\n } catch {\n /* ignore */\n }\n try {\n leaseManager.dispose();\n } catch {\n /* ignore */\n }\n try {\n debugController.stop();\n } catch {\n /* ignore */\n }\n };\n\n try {\n // 10) Recovery - MUST run before scheduler.start()\n logger.info('[RR-V3] Running crash recovery...');\n await recoverFromCrash({ storage, events, ownerId, now, logger });\n\n // 11) Start components\n scheduler.start();\n await triggers.start();\n rpcServer.start();\n\n logger.info('[RR-V3] Bootstrap complete');\n } catch (e) {\n await cleanup();\n throw e;\n }\n\n // Build runtime handle\n runtime = {\n ownerId,\n storage,\n events,\n leaseManager,\n scheduler,\n runners,\n debugController,\n triggers,\n rpcServer,\n stop: async () => {\n logger.info('[RR-V3] Stopping...');\n // Stop order: RPC first (block new requests) -> triggers -> scheduler -> lease -> debug\n rpcServer.stop();\n await triggers.stop().catch(() => {});\n scheduler.stop();\n leaseManager.dispose();\n debugController.stop();\n runtime = null;\n logger.info('[RR-V3] Stopped');\n },\n };\n\n return runtime;\n })().finally(() => {\n bootstrapPromise = null;\n });\n\n return bootstrapPromise;\n}\n\n/**\n * 获取当前运行时（如果已启动）\n */\nexport function getV3Runtime(): V3Runtime | null {\n return runtime;\n}\n\n/**\n * 检查 V3 是否已启动\n */\nexport function isV3Running(): boolean {\n return runtime !== null;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/debug.ts", "content": "/**\n * @fileoverview 调试器类型定义\n * @description 定义 Record-Replay V3 中的调试器状态和协议\n */\n\nimport type { JsonValue } from './json';\nimport type { NodeId, RunId } from './ids';\nimport type { PauseReason } from './events';\n\n/**\n * 断点定义\n */\nexport interface Breakpoint {\n /** 断点所在节点 ID */\n nodeId: NodeId;\n /** 是否启用 */\n enabled: boolean;\n}\n\n/**\n * 调试器状态\n * @description 描述调试器当前的连接和执行状态\n */\nexport interface DebuggerState {\n /** 关联的 Run ID */\n runId: RunId;\n /** 调试器连接状态 */\n status: 'attached' | 'detached';\n /** 执行状态 */\n execution: 'running' | 'paused';\n /** 暂停原因（仅当 execution='paused' 时有效） */\n pauseReason?: PauseReason;\n /** 当前节点 ID */\n currentNodeId?: NodeId;\n /** 断点列表 */\n breakpoints: Breakpoint[];\n /** 单步模式 */\n stepMode?: 'none' | 'stepOver';\n}\n\n/**\n * 调试器命令\n * @description 客户端发送给调试器的命令\n */\nexport type DebuggerCommand =\n // ===== 连接控制 =====\n | { type: 'debug.attach'; runId: RunId }\n | { type: 'debug.detach'; runId: RunId }\n\n // ===== 执行控制 =====\n | { type: 'debug.pause'; runId: RunId }\n | { type: 'debug.resume'; runId: RunId }\n | { type: 'debug.stepOver'; runId: RunId }\n\n // ===== 断点管理 =====\n | { type: 'debug.setBreakpoints'; runId: RunId; nodeIds: NodeId[] }\n | { type: 'debug.addBreakpoint'; runId: RunId; nodeId: NodeId }\n | { type: 'debug.removeBreakpoint'; runId: RunId; nodeId: NodeId }\n\n // ===== 状态查询 =====\n | { type: 'debug.getState'; runId: RunId }\n\n // ===== 变量操作 =====\n | { type: 'debug.getVar'; runId: RunId; name: string }\n | { type: 'debug.setVar'; runId: RunId; name: string; value: JsonValue };\n\n/** 调试器命令类型（从联合类型提取） */\nexport type DebuggerCommandType = DebuggerCommand['type'];\n\n/**\n * 调试器命令响应\n */\nexport type DebuggerResponse =\n | { ok: true; state?: DebuggerState; value?: JsonValue }\n | { ok: false; error: string };\n\n/**\n * 创建初始调试器状态\n */\nexport function createInitialDebuggerState(runId: RunId): DebuggerState {\n return {\n runId,\n status: 'detached',\n execution: 'running',\n breakpoints: [],\n stepMode: 'none',\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/errors.ts", "content": "/**\n * @fileoverview 错误类型定义\n * @description 定义 Record-Replay V3 中使用的错误码和错误类型\n */\n\nimport type { JsonValue } from './json';\n\n/** 错误码常量 */\nexport const RR_ERROR_CODES = {\n // ===== 验证错误 =====\n /** 通用验证错误 */\n VALIDATION_ERROR: 'VALIDATION_ERROR',\n /** 不支持的节点类型 */\n UNSUPPORTED_NODE: 'UNSUPPORTED_NODE',\n /** DAG 结构无效 */\n DAG_INVALID: 'DAG_INVALID',\n /** DAG 存在循环 */\n DAG_CYCLE: 'DAG_CYCLE',\n\n // ===== 运行时错误 =====\n /** 操作超时 */\n TIMEOUT: 'TIMEOUT',\n /** Tab 未找到 */\n TAB_NOT_FOUND: 'TAB_NOT_FOUND',\n /** Frame 未找到 */\n FRAME_NOT_FOUND: 'FRAME_NOT_FOUND',\n /** 目标元素未找到 */\n TARGET_NOT_FOUND: 'TARGET_NOT_FOUND',\n /** 元素不可见 */\n ELEMENT_NOT_VISIBLE: 'ELEMENT_NOT_VISIBLE',\n /** 导航失败 */\n NAVIGATION_FAILED: 'NAVIGATION_FAILED',\n /** 网络请求失败 */\n NETWORK_REQUEST_FAILED: 'NETWORK_REQUEST_FAILED',\n\n // ===== 脚本/工具错误 =====\n /** 脚本执行失败 */\n SCRIPT_FAILED: 'SCRIPT_FAILED',\n /** 权限被拒绝 */\n PERMISSION_DENIED: 'PERMISSION_DENIED',\n /** 工具执行错误 */\n TOOL_ERROR: 'TOOL_ERROR',\n\n // ===== 控制错误 =====\n /** Run 被取消 */\n RUN_CANCELED: 'RUN_CANCELED',\n /** Run 被暂停 */\n RUN_PAUSED: 'RUN_PAUSED',\n\n // ===== 内部错误 =====\n /** 内部错误 */\n INTERNAL: 'INTERNAL',\n /** 不变量违规 */\n INVARIANT_VIOLATION: 'INVARIANT_VIOLATION',\n} as const;\n\n/** 错误码类型 */\nexport type RRErrorCode = (typeof RR_ERROR_CODES)[keyof typeof RR_ERROR_CODES];\n\n/**\n * Record-Replay 错误接口\n * @description 统一的错误表示，支持错误链和可重试标记\n */\nexport interface RRError {\n /** 错误码 */\n code: RRErrorCode;\n /** 错误消息 */\n message: string;\n /** 附加数据 */\n data?: JsonValue;\n /** 是否可重试 */\n retryable?: boolean;\n /** 原因错误（错误链） */\n cause?: RRError;\n}\n\n/**\n * 创建 RRError 的工厂函数\n */\nexport function createRRError(\n code: RRErrorCode,\n message: string,\n options?: { data?: JsonValue; retryable?: boolean; cause?: RRError },\n): RRError {\n return {\n code,\n message,\n ...(options?.data !== undefined && { data: options.data }),\n ...(options?.retryable !== undefined && { retryable: options.retryable }),\n ...(options?.cause !== undefined && { cause: options.cause }),\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/events.ts", "content": "/**\n * @fileoverview 事件类型定义\n * @description 定义 Record-Replay V3 中的运行事件和状态\n */\n\nimport type { JsonObject, JsonValue, UnixMillis } from './json';\nimport type { EdgeLabel, FlowId, NodeId, RunId } from './ids';\nimport type { RRError } from './errors';\nimport type { TriggerFireContext } from './triggers';\n\n/** 取消订阅函数类型 */\nexport type Unsubscribe = () => void;\n\n/** Run 状态 */\nexport type RunStatus = 'queued' | 'running' | 'paused' | 'succeeded' | 'failed' | 'canceled';\n\n/**\n * 事件基础接口\n * @description 所有事件的公共字段\n */\nexport interface EventBase {\n /** 所属 Run ID */\n runId: RunId;\n /** 事件时间戳 */\n ts: UnixMillis;\n /** 单调递增序列号 */\n seq: number;\n}\n\n/**\n * 暂停原因\n * @description 描述 Run 暂停的原因\n */\nexport type PauseReason =\n | { kind: 'breakpoint'; nodeId: NodeId }\n | { kind: 'step'; nodeId: NodeId }\n | { kind: 'command' }\n | { kind: 'policy'; nodeId: NodeId; reason: string };\n\n/** 恢复原因 */\nexport type RecoveryReason = 'sw_restart' | 'lease_expired';\n\n/**\n * Run 事件联合类型\n * @description 所有可能的运行时事件\n */\nexport type RunEvent =\n // ===== Run 生命周期事件 =====\n | (EventBase & { type: 'run.queued'; flowId: FlowId })\n | (EventBase & { type: 'run.started'; flowId: FlowId; tabId: number })\n | (EventBase & { type: 'run.paused'; reason: PauseReason; nodeId?: NodeId })\n | (EventBase & { type: 'run.resumed' })\n | (EventBase & {\n type: 'run.recovered';\n /** 恢复原因 */\n reason: RecoveryReason;\n /** 恢复前状态 */\n fromStatus: 'running' | 'paused';\n /** 恢复后状态 */\n toStatus: 'queued';\n /** 原 ownerId（用于审计） */\n prevOwnerId?: string;\n })\n | (EventBase & { type: 'run.canceled'; reason?: string })\n | (EventBase & { type: 'run.succeeded'; tookMs: number; outputs?: JsonObject })\n | (EventBase & { type: 'run.failed'; error: RRError; nodeId?: NodeId })\n\n // ===== Node 执行事件 =====\n | (EventBase & { type: 'node.queued'; nodeId: NodeId })\n | (EventBase & { type: 'node.started'; nodeId: NodeId; attempt: number })\n | (EventBase & {\n type: 'node.succeeded';\n nodeId: NodeId;\n tookMs: number;\n next?: { kind: 'edgeLabel'; label: EdgeLabel } | { kind: 'end' };\n })\n | (EventBase & {\n type: 'node.failed';\n nodeId: NodeId;\n attempt: number;\n error: RRError;\n decision: 'retry' | 'continue' | 'stop' | 'goto';\n })\n | (EventBase & { type: 'node.skipped'; nodeId: NodeId; reason: 'disabled' | 'unreachable' })\n\n // ===== 变量和日志事件 =====\n | (EventBase & {\n type: 'vars.patch';\n patch: Array<{ op: 'set' | 'delete'; name: string; value?: JsonValue }>;\n })\n | (EventBase & { type: 'artifact.screenshot'; nodeId: NodeId; data: string; savedAs?: string })\n | (EventBase & {\n type: 'log';\n level: 'debug' | 'info' | 'warn' | 'error';\n message: string;\n data?: JsonValue;\n });\n\n/** Run 事件类型（从联合类型提取） */\nexport type RunEventType = RunEvent['type'];\n\n/**\n * 分布式 Omit（保留联合类型）\n */\ntype DistributiveOmit = T extends unknown ? Omit : never;\n\n/**\n * Run 事件输入类型\n * @description seq 必须由 storage 层原子分配（通过 RunRecordV3.nextSeq）\n * ts 可选，默认为 Date.now()\n */\nexport type RunEventInput = DistributiveOmit & {\n ts?: UnixMillis;\n};\n\n/** Run Schema 版本 */\nexport const RUN_SCHEMA_VERSION = 3 as const;\n\n/**\n * Run 记录 V3\n * @description 存储在 IndexedDB 中的 Run 摘要记录\n */\nexport interface RunRecordV3 {\n /** Schema 版本 */\n schemaVersion: typeof RUN_SCHEMA_VERSION;\n /** Run 唯一标识符 */\n id: RunId;\n /** 关联的 Flow ID */\n flowId: FlowId;\n\n /** 当前状态 */\n status: RunStatus;\n /** 创建时间 */\n createdAt: UnixMillis;\n /** 最后更新时间 */\n updatedAt: UnixMillis;\n\n /** 开始执行时间 */\n startedAt?: UnixMillis;\n /** 结束时间 */\n finishedAt?: UnixMillis;\n /** 总耗时（毫秒） */\n tookMs?: number;\n\n /** 绑定的 Tab ID（每 Run 独占） */\n tabId?: number;\n /** 起始节点 ID（如果不是默认入口） */\n startNodeId?: NodeId;\n /** 当前执行节点 ID */\n currentNodeId?: NodeId;\n\n /** 当前尝试次数 */\n attempt: number;\n /** 最大尝试次数 */\n maxAttempts: number;\n\n /** 运行参数 */\n args?: JsonObject;\n /** 触发器上下文 */\n trigger?: TriggerFireContext;\n /** 调试配置 */\n debug?: { breakpoints?: NodeId[]; pauseOnStart?: boolean };\n\n /** 错误信息（如果失败） */\n error?: RRError;\n /** 输出结果 */\n outputs?: JsonObject;\n\n /** 下一个事件序列号（缓存字段） */\n nextSeq: number;\n}\n\n/**\n * 判断 Run 是否已终止\n */\nexport function isTerminalStatus(status: RunStatus): boolean {\n return status === 'succeeded' || status === 'failed' || status === 'canceled';\n}\n\n/**\n * 判断 Run 是否正在执行\n */\nexport function isActiveStatus(status: RunStatus): boolean {\n return status === 'running' || status === 'paused';\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/flow.ts", "content": "/**\n * @fileoverview Flow 类型定义\n * @description 定义 Record-Replay V3 中的 Flow IR（中间表示）\n */\n\nimport type { ISODateTimeString, JsonObject } from './json';\nimport type { EdgeId, EdgeLabel, FlowId, NodeId } from './ids';\nimport type { FlowPolicy, NodePolicy } from './policy';\nimport type { VariableDefinition } from './variables';\n\n/** Flow Schema 版本 */\nexport const FLOW_SCHEMA_VERSION = 3 as const;\n\n/**\n * Edge V3\n * @description DAG 中的边，连接两个节点\n */\nexport interface EdgeV3 {\n /** Edge 唯一标识符 */\n id: EdgeId;\n /** 源节点 ID */\n from: NodeId;\n /** 目标节点 ID */\n to: NodeId;\n /** 边标签（用于条件分支和错误处理） */\n label?: EdgeLabel;\n}\n\n/** 节点类型（可扩展） */\nexport type NodeKind = string;\n\n/**\n * Node V3\n * @description DAG 中的节点，代表一个可执行的操作\n */\nexport interface NodeV3 {\n /** Node 唯一标识符 */\n id: NodeId;\n /** 节点类型 */\n kind: NodeKind;\n /** 节点名称（用于显示） */\n name?: string;\n /** 是否禁用 */\n disabled?: boolean;\n /** 节点级策略 */\n policy?: NodePolicy;\n /** 节点配置（类型由 kind 决定） */\n config: JsonObject;\n /** UI 布局信息 */\n ui?: { x: number; y: number };\n}\n\n/**\n * Flow 元数据绑定\n * @description 定义 Flow 与特定域名/路径/URL 的关联\n */\nexport interface FlowBinding {\n kind: 'domain' | 'path' | 'url';\n value: string;\n}\n\n/**\n * Flow V3\n * @description 完整的 Flow 定义，包含节点、边和配置\n */\nexport interface FlowV3 {\n /** Schema 版本 */\n schemaVersion: typeof FLOW_SCHEMA_VERSION;\n /** Flow 唯一标识符 */\n id: FlowId;\n /** Flow 名称 */\n name: string;\n /** Flow 描述 */\n description?: string;\n /** 创建时间 */\n createdAt: ISODateTimeString;\n /** 更新时间 */\n updatedAt: ISODateTimeString;\n\n /** 入口节点 ID（显式指定，不依赖入度推断） */\n entryNodeId: NodeId;\n /** 节点列表 */\n nodes: NodeV3[];\n /** 边列表 */\n edges: EdgeV3[];\n\n /** 变量定义 */\n variables?: VariableDefinition[];\n /** Flow 级策略 */\n policy?: FlowPolicy;\n /** 元数据 */\n meta?: {\n /** 标签 */\n tags?: string[];\n /** 绑定规则 */\n bindings?: FlowBinding[];\n };\n}\n\n/**\n * 根据 ID 查找节点\n */\nexport function findNodeById(flow: FlowV3, nodeId: NodeId): NodeV3 | undefined {\n return flow.nodes.find((n) => n.id === nodeId);\n}\n\n/**\n * 查找从指定节点出发的所有边\n */\nexport function findEdgesFrom(flow: FlowV3, nodeId: NodeId): EdgeV3[] {\n return flow.edges.filter((e) => e.from === nodeId);\n}\n\n/**\n * 查找指向指定节点的所有边\n */\nexport function findEdgesTo(flow: FlowV3, nodeId: NodeId): EdgeV3[] {\n return flow.edges.filter((e) => e.to === nodeId);\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/ids.ts", "content": "/**\n * @fileoverview ID 类型定义\n * @description 定义 Record-Replay V3 中使用的各种 ID 类型\n */\n\n/** Flow 唯一标识符 */\nexport type FlowId = string;\n\n/** Node 唯一标识符 */\nexport type NodeId = string;\n\n/** Edge 唯一标识符 */\nexport type EdgeId = string;\n\n/** Run 唯一标识符 */\nexport type RunId = string;\n\n/** Trigger 唯一标识符 */\nexport type TriggerId = string;\n\n/** Edge 标签类型 */\nexport type EdgeLabel = string;\n\n/** 预定义的 Edge 标签常量 */\nexport const EDGE_LABELS = {\n /** 默认边 */\n DEFAULT: 'default',\n /** 错误处理边 */\n ON_ERROR: 'onError',\n /** 条件为真时的边 */\n TRUE: 'true',\n /** 条件为假时的边 */\n FALSE: 'false',\n} as const;\n\n/** Edge 标签类型（从常量推导） */\nexport type EdgeLabelValue = (typeof EDGE_LABELS)[keyof typeof EDGE_LABELS];\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/index.ts", "content": "/**\n * @fileoverview Domain 层导出入口\n * @description 导出所有 Domain 类型定义\n */\n\n// JSON 基础类型\nexport * from './json';\n\n// ID 类型\nexport * from './ids';\n\n// 错误类型\nexport * from './errors';\n\n// 策略类型\nexport * from './policy';\n\n// 变量类型\nexport * from './variables';\n\n// Flow 类型\nexport * from './flow';\n\n// 事件类型\nexport * from './events';\n\n// 调试器类型\nexport * from './debug';\n\n// 触发器类型\nexport * from './triggers';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/json.ts", "content": "/**\n * @fileoverview JSON 基础类型定义\n * @description 定义 Record-Replay V3 中使用的 JSON 相关类型\n */\n\n/** JSON 原始类型 */\nexport type JsonPrimitive = string | number | boolean | null;\n\n/** JSON 对象类型 */\nexport interface JsonObject {\n [key: string]: JsonValue;\n}\n\n/** JSON 数组类型 */\nexport type JsonArray = JsonValue[];\n\n/** 任意 JSON 值类型 */\nexport type JsonValue = JsonPrimitive | JsonObject | JsonArray;\n\n/** ISO 8601 日期时间字符串 */\nexport type ISODateTimeString = string;\n\n/** Unix 毫秒时间戳 */\nexport type UnixMillis = number;\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/policy.ts", "content": "/**\n * @fileoverview 策略类型定义\n * @description 定义 Record-Replay V3 中使用的超时、重试、错误处理和工件策略\n */\n\nimport type { EdgeLabel, NodeId } from './ids';\nimport type { RRErrorCode } from './errors';\nimport type { UnixMillis } from './json';\n\n/**\n * 超时策略\n * @description 定义操作的超时时间和作用范围\n */\nexport interface TimeoutPolicy {\n /** 超时时间（毫秒） */\n ms: UnixMillis;\n /** 超时范围：attempt=每次尝试, node=整个节点执行 */\n scope?: 'attempt' | 'node';\n}\n\n/**\n * 重试策略\n * @description 定义失败后的重试行为\n */\nexport interface RetryPolicy {\n /** 最大重试次数 */\n retries: number;\n /** 重试间隔（毫秒） */\n intervalMs: UnixMillis;\n /** 退避策略：none=固定间隔, exp=指数退避, linear=线性增长 */\n backoff?: 'none' | 'exp' | 'linear';\n /** 最大重试间隔（毫秒） */\n maxIntervalMs?: UnixMillis;\n /** 抖动策略：none=无抖动, full=完全随机 */\n jitter?: 'none' | 'full';\n /** 仅在这些错误码时重试 */\n retryOn?: ReadonlyArray;\n}\n\n/**\n * 错误处理策略\n * @description 定义节点执行失败后的处理方式\n */\nexport type OnErrorPolicy =\n | { kind: 'stop' }\n | { kind: 'continue'; as?: 'warning' | 'error' }\n | {\n kind: 'goto';\n target: { kind: 'edgeLabel'; label: EdgeLabel } | { kind: 'node'; nodeId: NodeId };\n }\n | { kind: 'retry'; override?: Partial };\n\n/**\n * 工件策略\n * @description 定义截图和日志收集的行为\n */\nexport interface ArtifactPolicy {\n /** 截图策略：never=从不, onFailure=失败时, always=总是 */\n screenshot?: 'never' | 'onFailure' | 'always';\n /** 截图保存路径模板 */\n saveScreenshotAs?: string;\n /** 是否包含控制台日志 */\n includeConsole?: boolean;\n /** 是否包含网络请求 */\n includeNetwork?: boolean;\n}\n\n/**\n * 节点级策略\n * @description 单个节点的执行策略配置\n */\nexport interface NodePolicy {\n /** 超时策略 */\n timeout?: TimeoutPolicy;\n /** 重试策略 */\n retry?: RetryPolicy;\n /** 错误处理策略 */\n onError?: OnErrorPolicy;\n /** 工件策略 */\n artifacts?: ArtifactPolicy;\n}\n\n/**\n * Flow 级策略\n * @description 整个 Flow 的执行策略配置\n */\nexport interface FlowPolicy {\n /** 默认节点策略 */\n defaultNodePolicy?: NodePolicy;\n /** 不支持节点的处理策略 */\n unsupportedNodePolicy?: OnErrorPolicy;\n /** Run 总超时时间（毫秒） */\n runTimeoutMs?: UnixMillis;\n}\n\n/**\n * 合并节点策略\n * @description 将 Flow 级默认策略与节点级策略合并\n */\nexport function mergeNodePolicy(\n flowDefault: NodePolicy | undefined,\n nodePolicy: NodePolicy | undefined,\n): NodePolicy {\n if (!flowDefault) return nodePolicy ?? {};\n if (!nodePolicy) return flowDefault;\n\n return {\n timeout: nodePolicy.timeout ?? flowDefault.timeout,\n retry: nodePolicy.retry ?? flowDefault.retry,\n onError: nodePolicy.onError ?? flowDefault.onError,\n artifacts: nodePolicy.artifacts\n ? { ...flowDefault.artifacts, ...nodePolicy.artifacts }\n : flowDefault.artifacts,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/triggers.ts", "content": "/**\n * @fileoverview 触发器类型定义\n * @description 定义 Record-Replay V3 中的触发器规范\n */\n\nimport type { JsonObject, UnixMillis } from './json';\nimport type { FlowId, TriggerId } from './ids';\n\n/** 触发器类型 */\nexport type TriggerKind =\n | 'manual'\n | 'url'\n | 'cron'\n | 'interval'\n | 'once'\n | 'command'\n | 'contextMenu'\n | 'dom';\n\n/**\n * 触发器基础接口\n */\nexport interface TriggerSpecBase {\n /** 触发器 ID */\n id: TriggerId;\n /** 触发器类型 */\n kind: TriggerKind;\n /** 是否启用 */\n enabled: boolean;\n /** 关联的 Flow ID */\n flowId: FlowId;\n /** 传递给 Flow 的参数 */\n args?: JsonObject;\n}\n\n/**\n * URL 匹配规则\n */\nexport interface UrlMatchRule {\n kind: 'url' | 'domain' | 'path';\n value: string;\n}\n\n/**\n * 触发器规范联合类型\n */\nexport type TriggerSpec =\n // 手动触发\n | (TriggerSpecBase & { kind: 'manual' })\n\n // URL 触发\n | (TriggerSpecBase & {\n kind: 'url';\n match: UrlMatchRule[];\n })\n\n // Cron 定时触发\n | (TriggerSpecBase & {\n kind: 'cron';\n cron: string;\n timezone?: string;\n })\n\n // Interval 定时触发（固定间隔重复）\n | (TriggerSpecBase & {\n kind: 'interval';\n /** 间隔分钟数，最小为 1 */\n periodMinutes: number;\n })\n\n // Once 定时触发（指定时间触发一次后自动禁用）\n | (TriggerSpecBase & {\n kind: 'once';\n /** 触发时间戳 (Unix milliseconds) */\n whenMs: UnixMillis;\n })\n\n // 快捷键触发\n | (TriggerSpecBase & {\n kind: 'command';\n commandKey: string;\n })\n\n // 右键菜单触发\n | (TriggerSpecBase & {\n kind: 'contextMenu';\n title: string;\n contexts?: ReadonlyArray;\n })\n\n // DOM 元素出现触发\n | (TriggerSpecBase & {\n kind: 'dom';\n selector: string;\n appear?: boolean;\n once?: boolean;\n debounceMs?: UnixMillis;\n });\n\n/**\n * 触发器触发上下文\n * @description 描述触发器被触发时的上下文信息\n */\nexport interface TriggerFireContext {\n /** 触发器 ID */\n triggerId: TriggerId;\n /** 触发器类型 */\n kind: TriggerKind;\n /** 触发时间 */\n firedAt: UnixMillis;\n /** 来源 Tab ID */\n sourceTabId?: number;\n /** 来源 URL */\n sourceUrl?: string;\n}\n\n/**\n * 根据触发器类型获取类型化的触发器规范\n */\nexport type TriggerSpecByKind = Extract;\n\n/**\n * 判断触发器是否启用\n */\nexport function isTriggerEnabled(trigger: TriggerSpec): boolean {\n return trigger.enabled;\n}\n\n/**\n * 创建触发器触发上下文\n */\nexport function createTriggerFireContext(\n trigger: TriggerSpec,\n options?: { sourceTabId?: number; sourceUrl?: string },\n): TriggerFireContext {\n return {\n triggerId: trigger.id,\n kind: trigger.kind,\n firedAt: Date.now(),\n sourceTabId: options?.sourceTabId,\n sourceUrl: options?.sourceUrl,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/domain/variables.ts", "content": "/**\n * @fileoverview 变量类型定义\n * @description 定义 Record-Replay V3 中使用的变量指针和持久化变量\n */\n\nimport type { JsonValue, UnixMillis } from './json';\n\n/** 变量名称 */\nexport type VariableName = string;\n\n/** 持久化变量名称（以 $ 开头） */\nexport type PersistentVariableName = `$${string}`;\n\n/** 变量作用域 */\nexport type VariableScope = 'run' | 'flow' | 'persistent';\n\n/**\n * 变量指针\n * @description 指向变量的引用，支持 JSON path 访问\n */\nexport interface VariablePointer {\n /** 变量作用域 */\n scope: VariableScope;\n /** 变量名称 */\n name: VariableName;\n /** JSON path（用于访问嵌套属性） */\n path?: ReadonlyArray;\n}\n\n/**\n * 变量定义\n * @description Flow 中声明的变量\n */\nexport interface VariableDefinition {\n /** 变量名称 */\n name: VariableName;\n /** 显示标签 */\n label?: string;\n /** 描述 */\n description?: string;\n /** 是否敏感（不显示/导出） */\n sensitive?: boolean;\n /** 是否必需 */\n required?: boolean;\n /** 默认值 */\n default?: JsonValue;\n /** 作用域（不含 persistent，persistent 通过 $ 前缀判断） */\n scope?: Exclude;\n}\n\n/**\n * 持久化变量记录\n * @description 存储在 IndexedDB 中的持久化变量\n */\nexport interface PersistentVarRecord {\n /** 变量键（以 $ 开头） */\n key: PersistentVariableName;\n /** 变量值 */\n value: JsonValue;\n /** 最后更新时间 */\n updatedAt: UnixMillis;\n /** 版本号（单调递增，用于 LWW 和调试） */\n version: number;\n}\n\n/**\n * 判断变量名是否为持久化变量\n */\nexport function isPersistentVariable(name: string): name is PersistentVariableName {\n return name.startsWith('$');\n}\n\n/**\n * 解析变量指针字符串\n * @example \"$user.name\" -> { scope: 'persistent', name: '$user', path: ['name'] }\n */\nexport function parseVariablePointer(ref: string): VariablePointer | null {\n if (!ref) return null;\n\n const parts = ref.split('.');\n const name = parts[0];\n const path = parts.slice(1);\n\n if (isPersistentVariable(name)) {\n return {\n scope: 'persistent',\n name,\n path: path.length > 0 ? path : undefined,\n };\n }\n\n // 默认为 run 作用域\n return {\n scope: 'run',\n name,\n path: path.length > 0 ? path : undefined,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/index.ts", "content": "/**\n * @fileoverview Engine 层导出入口\n */\n\n// Kernel\nexport * from './kernel';\n\n// Queue\nexport * from './queue';\n\n// Plugins\nexport * from './plugins';\n\n// Transport\nexport * from './transport';\n\n// Keepalive\nexport * from './keepalive';\n\n// Recovery\nexport * from './recovery';\n\n// Triggers\nexport * from './triggers';\n\n// Storage Port\nexport * from './storage';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/keepalive/index.ts", "content": "/**\n * @fileoverview Keepalive 模块导出入口\n */\n\nexport * from './offscreen-keepalive';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/keepalive/offscreen-keepalive.ts", "content": "/**\n * @fileoverview Offscreen Keepalive Controller\n * @description Keeps the MV3 service worker alive using an Offscreen Document + Port heartbeat.\n *\n * Architecture:\n * - Background (this module) listens for an Offscreen Port connection.\n * - Offscreen connects and sends heartbeat pings.\n * - Background replies with pong and controls the heartbeat via `start`/`stop`.\n *\n * Contract:\n * - When at least one keepalive reference is held, keepalive must be running.\n * - When the reference count drops to zero, keepalive must fully stop (no ping loop, no Port, no reconnect).\n */\n\nimport { offscreenManager } from '@/utils/offscreen-manager';\nimport {\n RR_V3_KEEPALIVE_PORT_NAME,\n type KeepaliveMessage,\n} from '@/common/rr-v3-keepalive-protocol';\n\n// ==================== Runtime Control Protocol ====================\n\nconst KEEPALIVE_CONTROL_MESSAGE_TYPE = 'rr_v3_keepalive.control' as const;\n\ntype KeepaliveControlCommand = 'start' | 'stop';\n\ninterface KeepaliveControlMessage {\n type: typeof KEEPALIVE_CONTROL_MESSAGE_TYPE;\n command: KeepaliveControlCommand;\n}\n\n// ==================== Types ====================\n\n/**\n * Keepalive controller interface.\n * @description Manages Service Worker keepalive state.\n */\nexport interface KeepaliveController {\n /**\n * Acquire (increment reference count).\n * @param tag Tag used for debugging.\n * @returns Release function.\n */\n acquire(tag: string): () => void;\n\n /** Whether any keepalive reference is currently held. */\n isActive(): boolean;\n\n /** Current reference count. */\n getRefCount(): number;\n\n /** Release all references (primarily for testing). */\n releaseAll(): void;\n}\n\n/**\n * Offscreen keepalive options.\n */\nexport interface OffscreenKeepaliveOptions {\n /** Logger. */\n logger?: Pick;\n}\n\n// ==================== Factory ====================\n\n/**\n * Create an Offscreen keepalive controller.\n * @description Reuses the global OffscreenManager to avoid creating multiple Offscreen Documents concurrently.\n */\nexport function createOffscreenKeepaliveController(\n options: OffscreenKeepaliveOptions = {},\n): KeepaliveController {\n return new OffscreenKeepaliveControllerImpl(options);\n}\n\n/**\n * Create a NotImplemented KeepaliveController.\n * @description Placeholder implementation.\n */\nexport function createNotImplementedKeepaliveController(): KeepaliveController {\n return {\n acquire: () => {\n console.warn('[KeepaliveController] Not implemented, returning no-op release');\n return () => {};\n },\n isActive: () => false,\n getRefCount: () => 0,\n releaseAll: () => {},\n };\n}\n\n// ==================== Implementation ====================\n\n/**\n * Offscreen keepalive controller implementation.\n */\nclass OffscreenKeepaliveControllerImpl implements KeepaliveController {\n private readonly refs = new Map();\n private totalRefs = 0;\n\n private offscreenPort: chrome.runtime.Port | null = null;\n private connectionListenerRegistered = false;\n\n // Used to serialize async operations to avoid races.\n private syncPromise: Promise = Promise.resolve();\n\n private readonly logger: Pick;\n\n constructor(options: OffscreenKeepaliveOptions) {\n this.logger = options.logger ?? console;\n // Register listener eagerly to avoid missing Offscreen connect events.\n // This prevents race conditions where Offscreen connects before we start listening.\n this.ensureConnectionListener();\n }\n\n acquire(tag: string): () => void {\n this.totalRefs += 1;\n\n const count = this.refs.get(tag) ?? 0;\n this.refs.set(tag, count + 1);\n\n this.logger.debug(`[OffscreenKeepalive] acquire(${tag}), totalRefs=${this.totalRefs}`);\n\n // Start keepalive when the first reference is acquired.\n if (this.totalRefs === 1) {\n this.scheduleSync();\n }\n\n let released = false;\n return () => {\n if (released) return;\n released = true;\n\n if (this.totalRefs > 0) {\n this.totalRefs -= 1;\n }\n\n const currentCount = this.refs.get(tag) ?? 0;\n if (currentCount <= 1) {\n this.refs.delete(tag);\n } else {\n this.refs.set(tag, currentCount - 1);\n }\n\n this.logger.debug(`[OffscreenKeepalive] release(${tag}), totalRefs=${this.totalRefs}`);\n\n // Stop keepalive when the reference count drops to zero.\n if (this.totalRefs === 0) {\n this.scheduleSync();\n }\n };\n }\n\n isActive(): boolean {\n return this.totalRefs > 0;\n }\n\n getRefCount(): number {\n return this.totalRefs;\n }\n\n releaseAll(): void {\n if (this.totalRefs === 0) return;\n\n this.logger.debug('[OffscreenKeepalive] releaseAll()');\n this.refs.clear();\n this.totalRefs = 0;\n this.scheduleSync();\n }\n\n /**\n * Get the current reference counts grouped by tag.\n * @description Useful for debugging.\n */\n getRefsByTag(): Record {\n return Object.fromEntries(this.refs);\n }\n\n // ==================== Private Methods ====================\n\n /**\n * Schedule a sync operation.\n * @description Serializes async operations to avoid races.\n */\n private scheduleSync(): void {\n this.syncPromise = this.syncPromise\n .catch(() => {\n // Ignore previous operation errors.\n })\n .then(() => this.syncOnce())\n .catch((e) => {\n this.logger.warn('[OffscreenKeepalive] sync failed:', e);\n });\n }\n\n /**\n * Perform a single sync step based on the current ref count.\n */\n private async syncOnce(): Promise {\n if (this.totalRefs > 0) {\n // Ensure listener exists before Offscreen connects (race prevention).\n this.ensureConnectionListener();\n\n // Ensure the Offscreen document exists.\n await offscreenManager.ensureOffscreenDocument();\n\n // Re-check after await: state may have changed while we were creating the document.\n if (this.totalRefs === 0) {\n await this.teardown();\n return;\n }\n\n // Send start command via runtime message (works even if Port is not connected).\n await this.sendRuntimeControl('start');\n // Also send via Port if connected.\n this.sendStartCommand();\n } else {\n // Send stop via Port first (if connected).\n this.sendStopCommand();\n // Then send via runtime message to ensure Offscreen stops.\n await this.sendRuntimeControl('stop');\n await this.teardown();\n }\n }\n\n /**\n * Clean up resources.\n */\n private async teardown(): Promise {\n this.disconnectPort();\n // Note: We do not close the Offscreen Document here because it may be used by other modules.\n // If Offscreen Document lifecycle needs ref-counting, it should be implemented in OffscreenManager.\n }\n\n /**\n * Ensure the Port connection listener is registered.\n */\n private ensureConnectionListener(): void {\n if (this.connectionListenerRegistered) return;\n\n if (typeof chrome === 'undefined' || !chrome.runtime?.onConnect) {\n this.logger.warn('[OffscreenKeepalive] chrome.runtime.onConnect not available');\n return;\n }\n\n chrome.runtime.onConnect.addListener(this.handleConnect);\n this.connectionListenerRegistered = true;\n\n this.logger.debug('[OffscreenKeepalive] Connection listener registered');\n }\n\n /**\n * Handle Port connections from Offscreen.\n */\n private handleConnect = (port: chrome.runtime.Port): void => {\n if (port.name !== RR_V3_KEEPALIVE_PORT_NAME) return;\n\n this.logger.debug('[OffscreenKeepalive] Offscreen connected');\n\n // Store Port reference.\n this.offscreenPort = port;\n\n // Listen to messages.\n port.onMessage.addListener(this.handlePortMessage);\n\n // Listen to disconnect.\n port.onDisconnect.addListener(() => {\n this.logger.debug('[OffscreenKeepalive] Offscreen disconnected');\n if (this.offscreenPort === port) {\n this.offscreenPort = null;\n }\n });\n\n // If active, send the start command.\n if (this.totalRefs > 0) {\n this.sendStartCommand();\n }\n };\n\n /**\n * Handle messages from Offscreen.\n */\n private handlePortMessage = (msg: unknown): void => {\n const m = msg as Partial | null;\n if (!m || typeof m !== 'object') return;\n\n if (m.type === 'keepalive.ping') {\n this.logger.debug('[OffscreenKeepalive] Received ping, sending pong');\n this.sendPong();\n }\n };\n\n /**\n * Disconnect the Port.\n */\n private disconnectPort(): void {\n if (!this.offscreenPort) return;\n\n const port = this.offscreenPort;\n this.offscreenPort = null;\n\n try {\n port.disconnect();\n } catch {\n // Port may already be disconnected.\n }\n\n this.logger.debug('[OffscreenKeepalive] Port disconnected');\n }\n\n /**\n * Send the start command to Offscreen (Port channel).\n */\n private sendStartCommand(): void {\n if (!this.offscreenPort) return;\n\n const msg: KeepaliveMessage = {\n type: 'keepalive.start',\n timestamp: Date.now(),\n };\n\n try {\n this.offscreenPort.postMessage(msg);\n this.logger.debug('[OffscreenKeepalive] Sent start command via Port');\n } catch (e) {\n this.logger.warn('[OffscreenKeepalive] Failed to send start command:', e);\n }\n }\n\n /**\n * Send the stop command to Offscreen (Port channel).\n */\n private sendStopCommand(): void {\n if (!this.offscreenPort) return;\n\n const msg: KeepaliveMessage = {\n type: 'keepalive.stop',\n timestamp: Date.now(),\n };\n\n try {\n this.offscreenPort.postMessage(msg);\n this.logger.debug('[OffscreenKeepalive] Sent stop command via Port');\n } catch (e) {\n this.logger.warn('[OffscreenKeepalive] Failed to send stop command:', e);\n }\n }\n\n /**\n * Send a pong response.\n */\n private sendPong(): void {\n if (!this.offscreenPort) return;\n\n const msg: KeepaliveMessage = {\n type: 'keepalive.pong',\n timestamp: Date.now(),\n };\n\n try {\n this.offscreenPort.postMessage(msg);\n } catch (e) {\n this.logger.warn('[OffscreenKeepalive] Failed to send pong:', e);\n }\n }\n\n /**\n * Send a runtime control command to Offscreen.\n * This is the control plane used to start/stop keepalive even when the Port is not connected.\n */\n private async sendRuntimeControl(command: KeepaliveControlCommand): Promise {\n if (typeof chrome === 'undefined' || !chrome.runtime?.sendMessage) {\n this.logger.warn('[OffscreenKeepalive] chrome.runtime.sendMessage not available');\n return;\n }\n\n const msg: KeepaliveControlMessage = {\n type: KEEPALIVE_CONTROL_MESSAGE_TYPE,\n command,\n };\n\n // Retry with delays for start command (Offscreen document may not be ready yet).\n const delaysMs = command === 'start' ? [0, 50, 200] : [0];\n for (const delayMs of delaysMs) {\n if (delayMs > 0) {\n await new Promise((resolve) => setTimeout(resolve, delayMs));\n }\n try {\n await chrome.runtime.sendMessage(msg);\n this.logger.debug(`[OffscreenKeepalive] Sent runtime ${command} command`);\n return;\n } catch {\n // Best-effort: Offscreen document may not be ready yet.\n }\n }\n\n this.logger.warn(`[OffscreenKeepalive] Failed to send runtime ${command} command`);\n }\n}\n\n// ==================== Test Utilities ====================\n\n/**\n * In-memory keepalive controller.\n * @description For tests only: tracks reference counts without using Offscreen.\n */\nexport class InMemoryKeepaliveController implements KeepaliveController {\n private refs = new Map();\n\n acquire(tag: string): () => void {\n const count = this.refs.get(tag) ?? 0;\n this.refs.set(tag, count + 1);\n\n let released = false;\n return () => {\n if (released) return;\n released = true;\n\n const currentCount = this.refs.get(tag) ?? 0;\n if (currentCount <= 1) {\n this.refs.delete(tag);\n } else {\n this.refs.set(tag, currentCount - 1);\n }\n };\n }\n\n isActive(): boolean {\n return this.refs.size > 0;\n }\n\n getRefCount(): number {\n let total = 0;\n for (const count of this.refs.values()) {\n total += count;\n }\n return total;\n }\n\n releaseAll(): void {\n this.refs.clear();\n }\n\n /**\n * Get the current reference counts grouped by tag.\n * @description Useful for debugging.\n */\n getRefsByTag(): Record {\n return Object.fromEntries(this.refs);\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/kernel/artifacts.ts", "content": "/**\n * @fileoverview 工件（Artifacts）接口\n * @description 定义截图等工件的获取和存储接口\n */\n\nimport type { NodeId, RunId } from '../../domain/ids';\nimport type { RRError } from '../../domain/errors';\nimport { RR_ERROR_CODES, createRRError } from '../../domain/errors';\n\n/**\n * 截图结果\n */\nexport type ScreenshotResult = { ok: true; base64: string } | { ok: false; error: RRError };\n\n/**\n * 工件服务接口\n * @description 提供工件获取和存储功能\n */\nexport interface ArtifactService {\n /**\n * 截取页面截图\n * @param tabId Tab ID\n * @param options 截图选项\n */\n screenshot(\n tabId: number,\n options?: {\n format?: 'png' | 'jpeg';\n quality?: number;\n },\n ): Promise;\n\n /**\n * 保存截图\n * @param runId Run ID\n * @param nodeId Node ID\n * @param base64 截图数据\n * @param filename 文件名（可选）\n */\n saveScreenshot(\n runId: RunId,\n nodeId: NodeId,\n base64: string,\n filename?: string,\n ): Promise<{ savedAs: string } | { error: RRError }>;\n}\n\n/**\n * 创建 NotImplemented 的 ArtifactService\n * @description Phase 0-1 占位实现\n */\nexport function createNotImplementedArtifactService(): ArtifactService {\n return {\n screenshot: async () => ({\n ok: false,\n error: createRRError(RR_ERROR_CODES.INTERNAL, 'ArtifactService.screenshot not implemented'),\n }),\n saveScreenshot: async () => ({\n error: createRRError(\n RR_ERROR_CODES.INTERNAL,\n 'ArtifactService.saveScreenshot not implemented',\n ),\n }),\n };\n}\n\n/**\n * 创建基于 chrome.tabs.captureVisibleTab 的 ArtifactService\n * @description 使用 Chrome API 截取可见标签页\n */\nexport function createChromeArtifactService(): ArtifactService {\n // In-memory storage for screenshots (could be replaced with IndexedDB)\n const screenshotStore = new Map();\n\n return {\n screenshot: async (tabId, options) => {\n try {\n // Get the window ID for the tab\n const tab = await chrome.tabs.get(tabId);\n if (!tab.windowId) {\n return {\n ok: false,\n error: createRRError(RR_ERROR_CODES.INTERNAL, `Tab ${tabId} has no window`),\n };\n }\n\n // Capture the visible tab\n const format = options?.format ?? 'png';\n const quality = options?.quality ?? 100;\n\n const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, {\n format,\n quality: format === 'jpeg' ? quality : undefined,\n });\n\n // Extract base64 from data URL\n const base64Match = dataUrl.match(/^data:image\\/\\w+;base64,(.+)$/);\n if (!base64Match) {\n return {\n ok: false,\n error: createRRError(RR_ERROR_CODES.INTERNAL, 'Invalid screenshot data URL'),\n };\n }\n\n return { ok: true, base64: base64Match[1] };\n } catch (e) {\n const message = e instanceof Error ? e.message : String(e);\n return {\n ok: false,\n error: createRRError(RR_ERROR_CODES.INTERNAL, `Screenshot failed: ${message}`),\n };\n }\n },\n\n saveScreenshot: async (runId, nodeId, base64, filename) => {\n try {\n // Generate filename if not provided\n const savedAs = filename ?? `${runId}_${nodeId}_${Date.now()}.png`;\n const key = `${runId}/${savedAs}`;\n\n // Store in memory (in production, this would go to IndexedDB or cloud storage)\n screenshotStore.set(key, base64);\n\n return { savedAs };\n } catch (e) {\n const message = e instanceof Error ? e.message : String(e);\n return {\n error: createRRError(RR_ERROR_CODES.INTERNAL, `Save screenshot failed: ${message}`),\n };\n }\n },\n };\n}\n\n/**\n * 工件策略执行器\n * @description 根据策略配置决定是否获取工件\n */\nexport interface ArtifactPolicyExecutor {\n /**\n * 执行截图策略\n * @param policy 截图策略\n * @param context 上下文\n */\n executeScreenshotPolicy(\n policy: 'never' | 'onFailure' | 'always',\n context: {\n tabId: number;\n runId: RunId;\n nodeId: NodeId;\n failed: boolean;\n saveAs?: string;\n },\n ): Promise<{ captured: boolean; savedAs?: string; error?: RRError }>;\n}\n\n/**\n * 创建默认的工件策略执行器\n */\nexport function createArtifactPolicyExecutor(service: ArtifactService): ArtifactPolicyExecutor {\n return {\n executeScreenshotPolicy: async (policy, context) => {\n // 根据策略决定是否截图\n const shouldCapture = policy === 'always' || (policy === 'onFailure' && context.failed);\n\n if (!shouldCapture) {\n return { captured: false };\n }\n\n // 截图\n const result = await service.screenshot(context.tabId);\n if (!result.ok) {\n return { captured: false, error: result.error };\n }\n\n // 保存（如果指定了文件名）\n if (context.saveAs) {\n const saveResult = await service.saveScreenshot(\n context.runId,\n context.nodeId,\n result.base64,\n context.saveAs,\n );\n if ('error' in saveResult) {\n return { captured: true, error: saveResult.error };\n }\n return { captured: true, savedAs: saveResult.savedAs };\n }\n\n return { captured: true };\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/kernel/breakpoints.ts", "content": "/**\n * @fileoverview 断点管理器\n * @description 管理调试断点的添加、删除和命中检测\n */\n\nimport type { NodeId, RunId } from '../../domain/ids';\nimport type { Breakpoint, DebuggerState } from '../../domain/debug';\n\n/**\n * 断点管理器\n * @description 管理单个 Run 的断点\n */\nexport class BreakpointManager {\n private breakpoints = new Map();\n private stepMode: 'none' | 'stepOver' = 'none';\n\n constructor(initialBreakpoints?: NodeId[]) {\n if (initialBreakpoints) {\n for (const nodeId of initialBreakpoints) {\n this.add(nodeId);\n }\n }\n }\n\n /**\n * 添加断点\n */\n add(nodeId: NodeId): void {\n this.breakpoints.set(nodeId, { nodeId, enabled: true });\n }\n\n /**\n * 删除断点\n */\n remove(nodeId: NodeId): void {\n this.breakpoints.delete(nodeId);\n }\n\n /**\n * 设置断点列表（替换所有现有断点）\n */\n setAll(nodeIds: NodeId[]): void {\n this.breakpoints.clear();\n for (const nodeId of nodeIds) {\n this.add(nodeId);\n }\n }\n\n /**\n * 启用断点\n */\n enable(nodeId: NodeId): void {\n const bp = this.breakpoints.get(nodeId);\n if (bp) {\n bp.enabled = true;\n }\n }\n\n /**\n * 禁用断点\n */\n disable(nodeId: NodeId): void {\n const bp = this.breakpoints.get(nodeId);\n if (bp) {\n bp.enabled = false;\n }\n }\n\n /**\n * 检查节点是否有启用的断点\n */\n hasBreakpoint(nodeId: NodeId): boolean {\n const bp = this.breakpoints.get(nodeId);\n return bp?.enabled ?? false;\n }\n\n /**\n * 检查是否应该在节点处暂停\n * @description 考虑断点和单步模式\n */\n shouldPauseAt(nodeId: NodeId): boolean {\n // 如果在单步模式，总是暂停\n if (this.stepMode === 'stepOver') {\n return true;\n }\n // 否则检查断点\n return this.hasBreakpoint(nodeId);\n }\n\n /**\n * 获取所有断点\n */\n getAll(): Breakpoint[] {\n return Array.from(this.breakpoints.values());\n }\n\n /**\n * 获取启用的断点\n */\n getEnabled(): Breakpoint[] {\n return this.getAll().filter((bp) => bp.enabled);\n }\n\n /**\n * 设置单步模式\n */\n setStepMode(mode: 'none' | 'stepOver'): void {\n this.stepMode = mode;\n }\n\n /**\n * 获取单步模式\n */\n getStepMode(): 'none' | 'stepOver' {\n return this.stepMode;\n }\n\n /**\n * 清除所有断点\n */\n clear(): void {\n this.breakpoints.clear();\n this.stepMode = 'none';\n }\n}\n\n/**\n * 断点管理器注册表\n * @description 管理多个 Run 的断点管理器\n */\nexport class BreakpointRegistry {\n private managers = new Map();\n\n /**\n * 获取或创建断点管理器\n */\n getOrCreate(runId: RunId, initialBreakpoints?: NodeId[]): BreakpointManager {\n let manager = this.managers.get(runId);\n if (!manager) {\n manager = new BreakpointManager(initialBreakpoints);\n this.managers.set(runId, manager);\n }\n return manager;\n }\n\n /**\n * 获取断点管理器\n */\n get(runId: RunId): BreakpointManager | undefined {\n return this.managers.get(runId);\n }\n\n /**\n * 删除断点管理器\n */\n remove(runId: RunId): void {\n this.managers.delete(runId);\n }\n\n /**\n * 清空所有\n */\n clear(): void {\n this.managers.clear();\n }\n}\n\n/** 全局断点注册表 */\nlet globalBreakpointRegistry: BreakpointRegistry | null = null;\n\n/**\n * 获取全局断点注册表\n */\nexport function getBreakpointRegistry(): BreakpointRegistry {\n if (!globalBreakpointRegistry) {\n globalBreakpointRegistry = new BreakpointRegistry();\n }\n return globalBreakpointRegistry;\n}\n\n/**\n * 重置全局断点注册表\n * @description 主要用于测试\n */\nexport function resetBreakpointRegistry(): void {\n globalBreakpointRegistry = null;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/kernel/debug-controller.ts", "content": "/**\n * @fileoverview Debug Controller\n * @description Central control plane for debugging - command routing, state aggregation, and UI push\n */\n\nimport type { NodeId, RunId } from '../../domain/ids';\nimport type { JsonValue } from '../../domain/json';\nimport type { PauseReason, RunEvent, Unsubscribe } from '../../domain/events';\nimport type {\n DebuggerCommand,\n DebuggerResponse,\n DebuggerState,\n Breakpoint,\n} from '../../domain/debug';\nimport { createInitialDebuggerState } from '../../domain/debug';\n\nimport type { StoragePort } from '../storage/storage-port';\nimport type { EventsBus } from '../transport/events-bus';\nimport type { RunRunner } from './runner';\nimport { BreakpointManager, getBreakpointRegistry } from './breakpoints';\n\n/**\n * Runner registry for managing active runners\n */\nexport interface RunnerRegistry {\n get(runId: RunId): RunRunner | undefined;\n register(runId: RunId, runner: RunRunner): void;\n unregister(runId: RunId): void;\n list(): RunId[];\n}\n\n/**\n * Create a simple runner registry\n */\nexport function createRunnerRegistry(): RunnerRegistry {\n const runners = new Map();\n return {\n get: (runId) => runners.get(runId),\n register: (runId, runner) => runners.set(runId, runner),\n unregister: (runId) => runners.delete(runId),\n list: () => Array.from(runners.keys()),\n };\n}\n\n/**\n * Debug session state (per-run)\n */\ninterface DebugSession {\n runId: RunId;\n attached: boolean;\n lastPauseReason?: PauseReason;\n lastKnownNodeId?: NodeId;\n lastKnownExecution: 'running' | 'paused';\n}\n\n/**\n * Debug state listener\n */\ntype DebugStateListener = (state: DebuggerState) => void;\n\n/**\n * Debug Controller Configuration\n */\nexport interface DebugControllerConfig {\n storage: StoragePort;\n events: EventsBus;\n runners: RunnerRegistry;\n}\n\n/**\n * Debug Controller\n * @description Single entry point for all debug operations\n */\nexport class DebugController {\n private readonly storage: StoragePort;\n private readonly events: EventsBus;\n private readonly runners: RunnerRegistry;\n\n private readonly sessions = new Map();\n private readonly listeners = new Map>();\n private eventUnsubscribe: Unsubscribe | null = null;\n\n constructor(config: DebugControllerConfig) {\n this.storage = config.storage;\n this.events = config.events;\n this.runners = config.runners;\n }\n\n /**\n * Start the debug controller\n */\n start(): void {\n // Subscribe to all events to track pause/resume state\n this.eventUnsubscribe = this.events.subscribe((event) => {\n this.handleEvent(event);\n });\n }\n\n /**\n * Stop the debug controller\n */\n stop(): void {\n if (this.eventUnsubscribe) {\n this.eventUnsubscribe();\n this.eventUnsubscribe = null;\n }\n this.sessions.clear();\n this.listeners.clear();\n }\n\n /**\n * Handle a debug command\n */\n async handle(cmd: DebuggerCommand): Promise {\n try {\n switch (cmd.type) {\n case 'debug.attach':\n return this.handleAttach(cmd.runId);\n\n case 'debug.detach':\n return this.handleDetach(cmd.runId);\n\n case 'debug.pause':\n return this.handlePause(cmd.runId);\n\n case 'debug.resume':\n return this.handleResume(cmd.runId);\n\n case 'debug.stepOver':\n return this.handleStepOver(cmd.runId);\n\n case 'debug.setBreakpoints':\n return this.handleSetBreakpoints(cmd.runId, cmd.nodeIds);\n\n case 'debug.addBreakpoint':\n return this.handleAddBreakpoint(cmd.runId, cmd.nodeId);\n\n case 'debug.removeBreakpoint':\n return this.handleRemoveBreakpoint(cmd.runId, cmd.nodeId);\n\n case 'debug.getState':\n return this.handleGetState(cmd.runId);\n\n case 'debug.getVar':\n return this.handleGetVar(cmd.runId, cmd.name);\n\n case 'debug.setVar':\n return this.handleSetVar(cmd.runId, cmd.name, cmd.value);\n\n default:\n return { ok: false, error: `Unknown debug command: ${(cmd as { type: string }).type}` };\n }\n } catch (e) {\n const message = e instanceof Error ? e.message : String(e);\n return { ok: false, error: message };\n }\n }\n\n /**\n * Subscribe to debug state changes\n */\n subscribe(listener: DebugStateListener, filter?: { runId?: RunId }): Unsubscribe {\n const key = filter?.runId ?? null;\n let set = this.listeners.get(key);\n if (!set) {\n set = new Set();\n this.listeners.set(key, set);\n }\n set.add(listener);\n\n return () => {\n set?.delete(listener);\n if (set?.size === 0) {\n this.listeners.delete(key);\n }\n };\n }\n\n /**\n * Get current debug state for a run\n */\n async getState(runId: RunId): Promise {\n const session = this.sessions.get(runId);\n const run = await this.storage.runs.get(runId);\n const bpManager = getBreakpointRegistry().get(runId);\n\n const state: DebuggerState = {\n runId,\n status: session?.attached ? 'attached' : 'detached',\n execution: session?.lastKnownExecution ?? (run?.status === 'paused' ? 'paused' : 'running'),\n pauseReason: session?.lastPauseReason,\n currentNodeId: session?.lastKnownNodeId ?? run?.currentNodeId,\n breakpoints: bpManager?.getAll() ?? [],\n stepMode: bpManager?.getStepMode() ?? 'none',\n };\n\n return state;\n }\n\n // ==================== Command Handlers ====================\n\n private async handleAttach(runId: RunId): Promise {\n const run = await this.storage.runs.get(runId);\n if (!run) {\n return { ok: false, error: `Run \"${runId}\" not found` };\n }\n\n // Create or update session\n let session = this.sessions.get(runId);\n if (!session) {\n session = {\n runId,\n attached: true,\n lastKnownExecution: run.status === 'paused' ? 'paused' : 'running',\n lastKnownNodeId: run.currentNodeId,\n };\n this.sessions.set(runId, session);\n } else {\n session.attached = true;\n }\n\n // Get or create breakpoint manager\n getBreakpointRegistry().getOrCreate(runId, run.debug?.breakpoints);\n\n const state = await this.getState(runId);\n this.notifyStateChange(runId, state);\n return { ok: true, state };\n }\n\n private async handleDetach(runId: RunId): Promise {\n const session = this.sessions.get(runId);\n if (session) {\n session.attached = false;\n }\n\n const state = await this.getState(runId);\n this.notifyStateChange(runId, state);\n return { ok: true, state };\n }\n\n private async handlePause(runId: RunId): Promise {\n const runner = this.runners.get(runId);\n if (!runner) {\n return { ok: false, error: `Runner for \"${runId}\" not found` };\n }\n\n runner.pause();\n const state = await this.getState(runId);\n return { ok: true, state };\n }\n\n private async handleResume(runId: RunId): Promise {\n const runner = this.runners.get(runId);\n if (!runner) {\n return { ok: false, error: `Runner for \"${runId}\" not found` };\n }\n\n runner.resume();\n const state = await this.getState(runId);\n return { ok: true, state };\n }\n\n private async handleStepOver(runId: RunId): Promise {\n const runner = this.runners.get(runId);\n if (!runner) {\n return { ok: false, error: `Runner for \"${runId}\" not found` };\n }\n\n // Set step mode to stepOver (will pause at next node)\n const bpManager = getBreakpointRegistry().getOrCreate(runId);\n bpManager.setStepMode('stepOver');\n\n // Resume execution - runner will pause at next node due to stepOver mode\n runner.resume();\n\n const state = await this.getState(runId);\n return { ok: true, state };\n }\n\n private async handleSetBreakpoints(runId: RunId, nodeIds: NodeId[]): Promise {\n const bpManager = getBreakpointRegistry().getOrCreate(runId);\n bpManager.setAll(nodeIds);\n\n // Persist breakpoints to run record\n await this.persistBreakpoints(runId, bpManager);\n\n const state = await this.getState(runId);\n this.notifyStateChange(runId, state);\n return { ok: true, state };\n }\n\n private async handleAddBreakpoint(runId: RunId, nodeId: NodeId): Promise {\n const bpManager = getBreakpointRegistry().getOrCreate(runId);\n bpManager.add(nodeId);\n\n await this.persistBreakpoints(runId, bpManager);\n\n const state = await this.getState(runId);\n this.notifyStateChange(runId, state);\n return { ok: true, state };\n }\n\n private async handleRemoveBreakpoint(runId: RunId, nodeId: NodeId): Promise {\n const bpManager = getBreakpointRegistry().getOrCreate(runId);\n bpManager.remove(nodeId);\n\n await this.persistBreakpoints(runId, bpManager);\n\n const state = await this.getState(runId);\n this.notifyStateChange(runId, state);\n return { ok: true, state };\n }\n\n private async handleGetState(runId: RunId): Promise {\n const state = await this.getState(runId);\n return { ok: true, state };\n }\n\n private async handleGetVar(runId: RunId, name: string): Promise {\n // Try to get from active runner first\n const runner = this.runners.get(runId);\n if (runner) {\n const value = runner.getVar(name);\n return { ok: true, value: value ?? null };\n }\n\n // Fallback: reconstruct from events\n const value = await this.reconstructVar(runId, name);\n return { ok: true, value: value ?? null };\n }\n\n private async handleSetVar(\n runId: RunId,\n name: string,\n value: JsonValue,\n ): Promise {\n const runner = this.runners.get(runId);\n if (!runner) {\n return {\n ok: false,\n error: `Runner for \"${runId}\" not found - cannot set variable on inactive run`,\n };\n }\n\n runner.setVar(name, value);\n return { ok: true };\n }\n\n // ==================== Event Handling ====================\n\n private handleEvent(event: RunEvent): void {\n const { runId } = event;\n let session = this.sessions.get(runId);\n\n // Track pause/resume state\n if (event.type === 'run.paused') {\n if (!session) {\n session = {\n runId,\n attached: false,\n lastKnownExecution: 'paused',\n };\n this.sessions.set(runId, session);\n }\n session.lastKnownExecution = 'paused';\n session.lastPauseReason = event.reason;\n session.lastKnownNodeId = event.nodeId;\n } else if (event.type === 'run.resumed') {\n if (session) {\n session.lastKnownExecution = 'running';\n session.lastPauseReason = undefined;\n }\n } else if (event.type === 'run.started') {\n if (!session) {\n session = {\n runId,\n attached: false,\n lastKnownExecution: 'running',\n };\n this.sessions.set(runId, session);\n }\n } else if (\n event.type === 'run.succeeded' ||\n event.type === 'run.failed' ||\n event.type === 'run.canceled'\n ) {\n // Run ended - keep session for querying but mark as not running\n if (session) {\n session.lastKnownExecution = 'running'; // Technically ended, but not paused\n }\n } else if (event.type === 'node.started') {\n if (session) {\n session.lastKnownNodeId = event.nodeId;\n }\n }\n\n // Notify listeners if session is attached\n if (session?.attached) {\n void this.getState(runId).then((state) => {\n this.notifyStateChange(runId, state);\n });\n }\n }\n\n // ==================== Helpers ====================\n\n private async persistBreakpoints(runId: RunId, bpManager: BreakpointManager): Promise {\n const breakpoints = bpManager.getEnabled().map((bp) => bp.nodeId);\n try {\n await this.storage.runs.patch(runId, {\n debug: { breakpoints },\n });\n } catch {\n // Run may not exist yet - ignore persistence error\n }\n }\n\n private async reconstructVar(runId: RunId, name: string): Promise {\n // Get flow and run to reconstruct initial vars\n const run = await this.storage.runs.get(runId);\n if (!run) return undefined;\n\n const flow = await this.storage.flows.get(run.flowId);\n if (!flow) return undefined;\n\n // Build initial vars\n const vars: Record = { ...(run.args ?? {}) };\n for (const def of flow.variables ?? []) {\n if (vars[def.name] === undefined && def.default !== undefined) {\n vars[def.name] = def.default;\n }\n }\n\n // Apply all vars.patch events\n const events = await this.storage.events.list(runId);\n for (const event of events) {\n if (event.type === 'vars.patch') {\n for (const op of event.patch) {\n if (op.op === 'set') {\n vars[op.name] = op.value ?? null;\n } else {\n delete vars[op.name];\n }\n }\n }\n }\n\n return vars[name];\n }\n\n private notifyStateChange(runId: RunId, state: DebuggerState): void {\n // Notify specific run listeners\n const runListeners = this.listeners.get(runId);\n if (runListeners) {\n for (const listener of runListeners) {\n try {\n listener(state);\n } catch (e) {\n console.error('[DebugController] Listener error:', e);\n }\n }\n }\n\n // Notify global listeners\n const globalListeners = this.listeners.get(null);\n if (globalListeners) {\n for (const listener of globalListeners) {\n try {\n listener(state);\n } catch (e) {\n console.error('[DebugController] Listener error:', e);\n }\n }\n }\n }\n}\n\n/**\n * Create and start a debug controller\n */\nexport function createDebugController(config: DebugControllerConfig): DebugController {\n const controller = new DebugController(config);\n controller.start();\n return controller;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/kernel/index.ts", "content": "/**\n * @fileoverview Kernel 模块导出入口\n */\n\nexport * from './kernel';\nexport * from './runner';\nexport * from './traversal';\nexport * from './breakpoints';\nexport * from './artifacts';\nexport * from './debug-controller';\nexport * from './recovery-kernel';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/kernel/kernel.ts", "content": "/**\n * @fileoverview ExecutionKernel 接口定义\n * @description 定义 Record-Replay V3 的核心执行引擎接口\n */\n\nimport type { JsonObject } from '../../domain/json';\nimport type { FlowId, NodeId, RunId } from '../../domain/ids';\nimport type { RRError } from '../../domain/errors';\nimport type { FlowV3 } from '../../domain/flow';\nimport type { DebuggerCommand, DebuggerState } from '../../domain/debug';\nimport type { RunEvent, RunStatus, Unsubscribe } from '../../domain/events';\n\n/**\n * Run 启动请求\n */\nexport interface RunStartRequest {\n /** Run ID（由调用方生成） */\n runId: RunId;\n /** Flow ID */\n flowId: FlowId;\n /** Flow 快照（执行时使用的完整 Flow 定义） */\n flowSnapshot: FlowV3;\n /** 运行参数 */\n args?: JsonObject;\n /** 起始节点 ID（默认为 Flow 的 entryNodeId） */\n startNodeId?: NodeId;\n /** Tab ID（必须由调用方分配，每 Run 独占） */\n tabId: number;\n /** 调试配置 */\n debug?: { breakpoints?: NodeId[]; pauseOnStart?: boolean };\n}\n\n/**\n * Run 执行结果\n */\nexport interface RunResult {\n /** Run ID */\n runId: RunId;\n /** 最终状态 */\n status: Extract;\n /** 总耗时（毫秒） */\n tookMs: number;\n /** 错误信息（如果失败） */\n error?: RRError;\n /** 输出结果 */\n outputs?: JsonObject;\n}\n\n/**\n * Run 状态查询结果\n */\nexport interface RunStatusInfo {\n /** 当前状态 */\n status: RunStatus;\n /** 当前节点 ID */\n currentNodeId?: NodeId;\n /** 开始时间 */\n startedAt?: number;\n /** 最后更新时间 */\n updatedAt: number;\n /** Tab ID */\n tabId?: number;\n}\n\n/**\n * ExecutionKernel 接口\n * @description Record-Replay V3 的核心执行引擎\n */\nexport interface ExecutionKernel {\n /**\n * 订阅事件流\n * @param listener 事件监听器\n * @returns 取消订阅函数\n */\n onEvent(listener: (event: RunEvent) => void): Unsubscribe;\n\n /**\n * 启动 Run\n * @description 将 Run 加入队列并开始执行\n */\n startRun(req: RunStartRequest): Promise;\n\n /**\n * 暂停 Run\n * @param runId Run ID\n * @param reason 暂停原因\n */\n pauseRun(runId: RunId, reason?: { kind: 'command' }): Promise;\n\n /**\n * 恢复 Run\n * @param runId Run ID\n */\n resumeRun(runId: RunId): Promise;\n\n /**\n * 取消 Run\n * @param runId Run ID\n * @param reason 取消原因\n */\n cancelRun(runId: RunId, reason?: string): Promise;\n\n /**\n * 执行调试命令\n * @param runId Run ID\n * @param cmd 调试命令\n */\n debug(\n runId: RunId,\n cmd: DebuggerCommand,\n ): Promise<{ ok: true; state?: DebuggerState } | { ok: false; error: string }>;\n\n /**\n * 获取 Run 状态\n * @param runId Run ID\n * @returns Run 状态信息或 null（如果不存在）\n */\n getRunStatus(runId: RunId): Promise;\n\n /**\n * 恢复执行\n * @description 在 Service Worker 重启后调用，恢复中断的 Run\n */\n recover(): Promise;\n}\n\n/**\n * 创建 NotImplemented 的 ExecutionKernel\n * @description Phase 0 占位实现\n */\nexport function createNotImplementedKernel(): ExecutionKernel {\n const notImplemented = () => {\n throw new Error('ExecutionKernel not implemented');\n };\n\n return {\n onEvent: () => {\n notImplemented();\n return () => {};\n },\n startRun: async () => notImplemented(),\n pauseRun: async () => notImplemented(),\n resumeRun: async () => notImplemented(),\n cancelRun: async () => notImplemented(),\n debug: async () => notImplemented(),\n getRunStatus: async () => notImplemented(),\n recover: async () => notImplemented(),\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/kernel/recovery-kernel.ts", "content": "/**\n * @fileoverview 支持崩溃恢复的 ExecutionKernel 实现 (P3-06)\n * @description\n * 提供 ExecutionKernel 的恢复增强实现，支持 `recover()` 方法。\n * 通过委托给 RecoveryCoordinator 实现崩溃恢复。\n *\n * 其他执行方法（startRun, pauseRun 等）暂未实现，将在后续阶段完成。\n */\n\nimport type { UnixMillis } from '../../domain/json';\nimport type { RunId } from '../../domain/ids';\nimport type { DebuggerCommand, DebuggerState } from '../../domain/debug';\n\nimport type { StoragePort } from '../storage/storage-port';\nimport type { EventsBus } from '../transport/events-bus';\nimport { recoverFromCrash } from '../recovery/recovery-coordinator';\n\nimport type { ExecutionKernel, RunStartRequest, RunStatusInfo } from './kernel';\n\n// ==================== Types ====================\n\n/**\n * 支持恢复的 Kernel 依赖\n */\nexport interface RecoveryEnabledKernelDeps {\n /** 存储层 */\n storage: StoragePort;\n /** 事件总线 */\n events: EventsBus;\n /** 当前 Service Worker 的 ownerId */\n ownerId: string;\n /** 时间源 */\n now?: () => UnixMillis;\n /** 日志器 */\n logger?: Pick;\n}\n\n// ==================== Factory ====================\n\n/**\n * 创建支持恢复的 ExecutionKernel\n * @description\n * 此实现仅支持 `recover()` 和 `getRunStatus()` 方法。\n * 其他执行方法暂未实现，将在后续阶段完成。\n */\nexport function createRecoveryEnabledKernel(deps: RecoveryEnabledKernelDeps): ExecutionKernel {\n const logger = deps.logger ?? console;\n const now = deps.now ?? (() => Date.now());\n\n if (!deps.ownerId) {\n throw new Error('ownerId is required');\n }\n\n const notImplemented = (name: string): never => {\n throw new Error(`ExecutionKernel.${name} not implemented`);\n };\n\n return {\n onEvent: (listener) => deps.events.subscribe(listener),\n\n startRun: async (_req: RunStartRequest) => notImplemented('startRun'),\n pauseRun: async (_runId: RunId) => notImplemented('pauseRun'),\n resumeRun: async (_runId: RunId) => notImplemented('resumeRun'),\n cancelRun: async (_runId: RunId) => notImplemented('cancelRun'),\n\n debug: async (\n _runId: RunId,\n _cmd: DebuggerCommand,\n ): Promise<{ ok: true; state?: DebuggerState } | { ok: false; error: string }> => {\n return { ok: false, error: 'ExecutionKernel.debug not configured' };\n },\n\n getRunStatus: async (runId: RunId): Promise => {\n const run = await deps.storage.runs.get(runId);\n if (!run) return null;\n return {\n status: run.status,\n currentNodeId: run.currentNodeId,\n startedAt: run.startedAt,\n updatedAt: run.updatedAt,\n tabId: run.tabId,\n };\n },\n\n recover: async (): Promise => {\n logger.info('[RecoveryKernel] Starting crash recovery...');\n const result = await recoverFromCrash({\n storage: deps.storage,\n events: deps.events,\n ownerId: deps.ownerId,\n now,\n logger,\n });\n logger.info('[RecoveryKernel] Recovery complete:', result);\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/kernel/runner.ts", "content": "/**\n * @fileoverview RunRunner 接口和实现\n * @description 定义和实现单个 Run 的顺序执行器\n */\n\nimport type { NodeId, RunId } from '../../domain/ids';\nimport { EDGE_LABELS } from '../../domain/ids';\nimport type { FlowV3, NodeV3 } from '../../domain/flow';\nimport { findNodeById } from '../../domain/flow';\nimport type {\n PauseReason,\n RunEvent,\n RunEventInput,\n RunRecordV3,\n Unsubscribe,\n} from '../../domain/events';\nimport { RUN_SCHEMA_VERSION } from '../../domain/events';\nimport type { JsonObject, JsonValue } from '../../domain/json';\nimport { RR_ERROR_CODES, createRRError, type RRError } from '../../domain/errors';\nimport type { NodePolicy, RetryPolicy } from '../../domain/policy';\nimport { mergeNodePolicy } from '../../domain/policy';\n\nimport type { EventsBus } from '../transport/events-bus';\nimport type { StoragePort } from '../storage/storage-port';\nimport type { PluginRegistry } from '../plugins/registry';\nimport { getPluginRegistry } from '../plugins/registry';\nimport type { NodeExecutionContext, NodeExecutionResult, VarsPatchOp } from '../plugins/types';\n\nimport type { ArtifactService } from './artifacts';\nimport { createNotImplementedArtifactService } from './artifacts';\nimport { getBreakpointRegistry, type BreakpointManager } from './breakpoints';\nimport { findEdgeByLabel, findNextNode, validateFlowDAG } from './traversal';\nimport type { RunResult } from './kernel';\n\n// ==================== Types ====================\n\n/**\n * RunRunner 运行时状态\n */\nexport interface RunnerRuntimeState {\n /** Run ID */\n runId: RunId;\n /** 当前节点 ID */\n currentNodeId: NodeId | null;\n /** 当前尝试次数 */\n attempt: number;\n /** 变量表 */\n vars: Record;\n /** 是否暂停 */\n paused: boolean;\n /** 是否取消 */\n canceled: boolean;\n}\n\n/**\n * RunRunner 配置\n */\nexport interface RunnerConfig {\n /** Flow 快照 */\n flow: FlowV3;\n /** Tab ID */\n tabId: number;\n /** 初始参数 */\n args?: JsonObject;\n /** 起始节点 ID */\n startNodeId?: NodeId;\n /** 调试配置 */\n debug?: { breakpoints?: NodeId[]; pauseOnStart?: boolean };\n}\n\n/**\n * RunRunner 接口\n */\nexport interface RunRunner {\n /** Run ID */\n readonly runId: RunId;\n /** 当前状态 */\n readonly state: RunnerRuntimeState;\n /** 订阅事件 */\n onEvent(listener: (event: RunEvent) => void): Unsubscribe;\n /** 开始执行 */\n start(): Promise;\n /** 暂停执行 */\n pause(): void;\n /** 恢复执行 */\n resume(): void;\n /** 取消执行 */\n cancel(reason?: string): void;\n /** 获取变量值 */\n getVar(name: string): JsonValue | undefined;\n /** 设置变量值 */\n setVar(name: string, value: JsonValue): void;\n}\n\n/**\n * RunRunner 工厂接口\n */\nexport interface RunRunnerFactory {\n create(runId: RunId, config: RunnerConfig): RunRunner;\n}\n\n/**\n * RunRunner 工厂依赖\n */\nexport interface RunRunnerFactoryDeps {\n storage: StoragePort;\n events: EventsBus;\n plugins?: PluginRegistry;\n artifactService?: ArtifactService;\n now?: () => number;\n}\n\n// ==================== Helpers ====================\n\ninterface Deferred {\n promise: Promise;\n resolve: (value: T) => void;\n reject: (reason?: unknown) => void;\n}\n\nfunction createDeferred(): Deferred {\n let resolve!: (value: T) => void;\n let reject!: (reason?: unknown) => void;\n const promise = new Promise((res, rej) => {\n resolve = res;\n reject = rej;\n });\n return { promise, resolve, reject };\n}\n\nfunction sleep(ms: number): Promise {\n return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nfunction errorMessage(err: unknown): string {\n if (err instanceof Error) return err.message;\n if (err && typeof err === 'object' && 'message' in err)\n return String((err as { message: unknown }).message);\n return String(err);\n}\n\nasync function withTimeout(\n p: Promise,\n ms: number | undefined,\n onTimeout: () => RRError,\n): Promise {\n if (ms === undefined || !Number.isFinite(ms) || ms <= 0) {\n return p;\n }\n\n let timer: ReturnType | undefined;\n try {\n return await Promise.race([\n p,\n new Promise((_resolve, reject) => {\n timer = setTimeout(() => reject(onTimeout()), ms);\n }),\n ]);\n } finally {\n if (timer !== undefined) {\n clearTimeout(timer);\n }\n }\n}\n\nfunction computeRetryDelayMs(policy: RetryPolicy, attempt: number): number {\n const base = Math.max(0, policy.intervalMs);\n let delay = base;\n const backoff = policy.backoff ?? 'none';\n\n if (backoff === 'linear') {\n delay = base * attempt;\n } else if (backoff === 'exp') {\n delay = base * Math.pow(2, Math.max(0, attempt - 1));\n }\n\n if (policy.maxIntervalMs !== undefined) {\n delay = Math.min(delay, Math.max(0, policy.maxIntervalMs));\n }\n\n if (policy.jitter === 'full') {\n delay = Math.floor(Math.random() * (delay + 1));\n }\n\n return Math.max(0, Math.floor(delay));\n}\n\nfunction applyVarsPatch(vars: Record, patch: VarsPatchOp[]): void {\n for (const op of patch) {\n if (op.op === 'set') {\n vars[op.name] = op.value ?? null;\n } else {\n delete vars[op.name];\n }\n }\n}\n\nfunction toRRError(err: unknown, fallback: { code: string; message: string }): RRError {\n if (err && typeof err === 'object' && 'code' in err && 'message' in err) {\n return err as RRError;\n }\n return createRRError(\n fallback.code as RRError['code'],\n `${fallback.message}: ${errorMessage(err)}`,\n );\n}\n\n/**\n * Serial queue for write operations\n * Ensures event ordering and reduces write races\n */\nclass SerialQueue {\n private tail: Promise = Promise.resolve();\n\n run(fn: () => Promise): Promise {\n const next = this.tail.then(fn, fn);\n this.tail = next.then(\n () => undefined,\n () => undefined,\n );\n return next;\n }\n}\n\n// ==================== Factory ====================\n\n/**\n * 创建 NotImplemented 的 RunRunnerFactory\n */\nexport function createNotImplementedRunnerFactory(): RunRunnerFactory {\n return {\n create: () => {\n throw new Error('RunRunnerFactory not implemented');\n },\n };\n}\n\n/**\n * 创建 RunRunner 工厂\n */\nexport function createRunRunnerFactory(deps: RunRunnerFactoryDeps): RunRunnerFactory {\n const plugins = deps.plugins ?? getPluginRegistry();\n const artifactService = deps.artifactService ?? createNotImplementedArtifactService();\n const now = deps.now ?? Date.now;\n\n return {\n create: (runId, config) =>\n new StorageBackedRunRunner(runId, config, {\n storage: deps.storage,\n events: deps.events,\n plugins,\n artifactService,\n now,\n }),\n };\n}\n\n// ==================== Implementation ====================\n\ninterface RunnerEnv {\n storage: StoragePort;\n events: EventsBus;\n plugins: PluginRegistry;\n artifactService: ArtifactService;\n now: () => number;\n}\n\ntype OnErrorDecision =\n | { kind: 'stop' }\n | { kind: 'continue' }\n | {\n kind: 'goto';\n target: { kind: 'edgeLabel'; label: string } | { kind: 'node'; nodeId: NodeId };\n }\n | { kind: 'retry'; retryPolicy: RetryPolicy | null };\n\ntype NodeRunResult =\n | { nextNodeId: NodeId | null }\n | { terminal: 'failed'; error: RRError }\n | { terminal: 'canceled' };\n\n/**\n * Storage-backed RunRunner implementation\n */\nclass StorageBackedRunRunner implements RunRunner {\n readonly runId: RunId;\n readonly state: RunnerRuntimeState;\n\n private readonly config: RunnerConfig;\n private readonly env: RunnerEnv;\n private readonly queue = new SerialQueue();\n private readonly breakpoints: BreakpointManager;\n\n private startPromise: Promise | null = null;\n private outputs: JsonObject = {};\n private cancelReason: string | undefined;\n private pauseWaiter: Deferred | null = null;\n\n constructor(runId: RunId, config: RunnerConfig, env: RunnerEnv) {\n this.runId = runId;\n this.config = config;\n this.env = env;\n\n this.state = {\n runId,\n currentNodeId: null,\n attempt: 0,\n vars: this.buildInitialVars(),\n paused: false,\n canceled: false,\n };\n\n this.breakpoints = getBreakpointRegistry().getOrCreate(runId, config.debug?.breakpoints);\n }\n\n onEvent(listener: (event: RunEvent) => void): Unsubscribe {\n return this.env.events.subscribe(listener, { runId: this.runId });\n }\n\n start(): Promise {\n if (!this.startPromise) {\n this.startPromise = this.run();\n }\n return this.startPromise;\n }\n\n pause(): void {\n this.requestPause({ kind: 'command' });\n }\n\n resume(): void {\n if (!this.state.paused) return;\n this.state.paused = false;\n this.pauseWaiter?.resolve(undefined);\n this.pauseWaiter = null;\n\n void this.queue\n .run(async () => {\n await this.env.storage.runs.patch(this.runId, { status: 'running' });\n await this.env.events.append({ runId: this.runId, type: 'run.resumed' } as RunEventInput);\n })\n .catch((e) => {\n console.error('[RunRunner] resume persistence failed:', e);\n });\n }\n\n cancel(reason?: string): void {\n if (this.state.canceled) return;\n this.state.canceled = true;\n this.cancelReason = reason;\n\n if (this.state.paused) {\n this.state.paused = false;\n this.pauseWaiter?.resolve(undefined);\n this.pauseWaiter = null;\n }\n }\n\n getVar(name: string): JsonValue | undefined {\n return this.state.vars[name];\n }\n\n setVar(name: string, value: JsonValue): void {\n this.state.vars[name] = value;\n\n // Best-effort: emit vars.patch event\n void this.queue\n .run(() =>\n this.env.events.append({\n runId: this.runId,\n type: 'vars.patch',\n patch: [{ op: 'set', name, value }],\n } as RunEventInput),\n )\n .catch(() => {});\n }\n\n // ==================== Private Methods ====================\n\n private buildInitialVars(): Record {\n const vars: Record = { ...(this.config.args ?? {}) };\n for (const def of this.config.flow.variables ?? []) {\n if (vars[def.name] === undefined && def.default !== undefined) {\n vars[def.name] = def.default;\n }\n }\n return vars;\n }\n\n private requestPause(reason: PauseReason): void {\n if (this.state.canceled) return;\n if (this.state.paused) return;\n\n this.state.paused = true;\n if (!this.pauseWaiter) {\n this.pauseWaiter = createDeferred();\n }\n\n const nodeId = this.state.currentNodeId ?? undefined;\n void this.queue\n .run(async () => {\n await this.env.storage.runs.patch(this.runId, {\n status: 'paused',\n ...(nodeId ? { currentNodeId: nodeId } : {}),\n });\n await this.env.events.append({\n runId: this.runId,\n type: 'run.paused',\n reason,\n ...(nodeId ? { nodeId } : {}),\n } as RunEventInput);\n })\n .catch((e) => {\n console.error('[RunRunner] pause persistence failed:', e);\n });\n }\n\n private async waitIfPaused(): Promise {\n while (this.state.paused && !this.state.canceled) {\n if (!this.pauseWaiter) {\n this.pauseWaiter = createDeferred();\n }\n await this.pauseWaiter.promise;\n }\n }\n\n private async ensureRunRecord(startNodeId: NodeId, startedAt: number): Promise {\n await this.queue.run(async () => {\n const existing = await this.env.storage.runs.get(this.runId);\n if (!existing) {\n const record: RunRecordV3 = {\n schemaVersion: RUN_SCHEMA_VERSION,\n id: this.runId,\n flowId: this.config.flow.id,\n status: 'running',\n createdAt: startedAt,\n updatedAt: startedAt,\n startedAt,\n tabId: this.config.tabId,\n startNodeId: this.config.startNodeId,\n currentNodeId: startNodeId,\n attempt: 0,\n maxAttempts: 1,\n args: this.config.args,\n debug: this.config.debug,\n nextSeq: 1,\n };\n await this.env.storage.runs.save(record);\n return;\n }\n\n if (!Number.isSafeInteger(existing.nextSeq) || existing.nextSeq < 0) {\n throw createRRError(\n RR_ERROR_CODES.INVARIANT_VIOLATION,\n `Invalid nextSeq for run \"${this.runId}\": ${String(existing.nextSeq)}`,\n );\n }\n\n const patch: Partial = {\n status: 'running',\n tabId: this.config.tabId,\n currentNodeId: startNodeId,\n };\n if (existing.startedAt === undefined) patch.startedAt = startedAt;\n if (this.config.startNodeId !== undefined) patch.startNodeId = this.config.startNodeId;\n if (this.config.args !== undefined) patch.args = this.config.args;\n if (this.config.debug !== undefined) patch.debug = this.config.debug;\n await this.env.storage.runs.patch(this.runId, patch);\n });\n }\n\n private async run(): Promise {\n const startedAt = this.env.now();\n const { flow } = this.config;\n\n const startNodeId = (this.config.startNodeId ?? flow.entryNodeId) as NodeId;\n\n // Ensure Run record exists FIRST (before DAG validation)\n // so that finishFailed can safely patch the record\n await this.ensureRunRecord(startNodeId, startedAt);\n\n // Validate DAG\n const validation = validateFlowDAG(flow);\n if (!validation.ok) {\n const error =\n validation.errors[0] ?? createRRError(RR_ERROR_CODES.DAG_INVALID, 'Invalid DAG');\n return this.finishFailed(startedAt, error, undefined);\n }\n\n if (this.state.canceled) {\n return this.finishCanceled(startedAt);\n }\n\n // Emit run.started\n await this.queue.run(() =>\n this.env.events.append({\n runId: this.runId,\n type: 'run.started',\n flowId: flow.id,\n tabId: this.config.tabId,\n } as RunEventInput),\n );\n\n // Handle pauseOnStart\n if (this.config.debug?.pauseOnStart) {\n this.requestPause({ kind: 'policy', nodeId: startNodeId, reason: 'pauseOnStart' });\n }\n\n // Main execution loop\n let currentNodeId: NodeId | null = startNodeId;\n while (currentNodeId) {\n this.state.currentNodeId = currentNodeId;\n\n // Only update currentNodeId, not status (to preserve paused state)\n const nodeIdToUpdate = currentNodeId; // Capture for closure\n await this.queue.run(() =>\n this.env.storage.runs.patch(this.runId, { currentNodeId: nodeIdToUpdate }),\n );\n\n if (this.state.canceled) break;\n await this.waitIfPaused();\n if (this.state.canceled) break;\n\n const node = findNodeById(flow, currentNodeId);\n if (!node) {\n const error = createRRError(\n RR_ERROR_CODES.DAG_INVALID,\n `Node \"${currentNodeId}\" not found in flow`,\n );\n return this.finishFailed(startedAt, error, currentNodeId);\n }\n\n // Skip disabled nodes\n if (node.disabled) {\n await this.queue.run(() =>\n this.env.events.append({\n runId: this.runId,\n type: 'node.skipped',\n nodeId: node.id,\n reason: 'disabled',\n } as RunEventInput),\n );\n currentNodeId = findNextNode(flow, node.id);\n continue;\n }\n\n // Check breakpoints\n if (this.breakpoints.shouldPauseAt(node.id)) {\n const reason: PauseReason =\n this.breakpoints.getStepMode() === 'stepOver'\n ? { kind: 'step', nodeId: node.id }\n : { kind: 'breakpoint', nodeId: node.id };\n\n // Clear step mode after hitting (to avoid infinite pause loop)\n if (this.breakpoints.getStepMode() === 'stepOver') {\n this.breakpoints.setStepMode('none');\n }\n\n this.requestPause(reason);\n await this.waitIfPaused();\n // After resume, proceed to execute the node (don't continue loop)\n }\n\n // Emit node.queued\n await this.queue.run(() =>\n this.env.events.append({\n runId: this.runId,\n type: 'node.queued',\n nodeId: node.id,\n } as RunEventInput),\n );\n\n // Execute node\n const nodeStartAt = this.env.now();\n const next = await this.runNode(flow, node, nodeStartAt);\n if ('terminal' in next) {\n if (next.terminal === 'canceled') break;\n if (next.terminal === 'failed') {\n return this.finishFailed(startedAt, next.error, node.id);\n }\n break;\n }\n\n currentNodeId = next.nextNodeId;\n }\n\n if (this.state.canceled) {\n return this.finishCanceled(startedAt);\n }\n\n return this.finishSucceeded(startedAt);\n }\n\n private async runNode(flow: FlowV3, node: NodeV3, nodeStartAt: number): Promise {\n let attempt = 1;\n\n for (;;) {\n if (this.state.canceled) return { terminal: 'canceled' };\n await this.waitIfPaused();\n if (this.state.canceled) return { terminal: 'canceled' };\n\n this.state.attempt = attempt;\n\n // Emit node.started\n await this.queue.run(() =>\n this.env.events.append({\n runId: this.runId,\n type: 'node.started',\n nodeId: node.id,\n attempt,\n } as RunEventInput),\n );\n\n const exec = await this.executeNodeAttempt(flow, node);\n if (exec.status === 'succeeded') {\n const tookMs = this.env.now() - nodeStartAt;\n\n // Apply vars patch\n if (exec.varsPatch && exec.varsPatch.length > 0) {\n applyVarsPatch(this.state.vars, exec.varsPatch);\n await this.queue.run(() =>\n this.env.events.append({\n runId: this.runId,\n type: 'vars.patch',\n patch: exec.varsPatch,\n } as RunEventInput),\n );\n }\n\n // Merge outputs\n if (exec.outputs) {\n this.outputs = { ...this.outputs, ...exec.outputs };\n }\n\n // Emit node.succeeded\n await this.queue.run(() =>\n this.env.events.append({\n runId: this.runId,\n type: 'node.succeeded',\n nodeId: node.id,\n tookMs,\n ...(exec.next ? { next: exec.next } : {}),\n } as RunEventInput),\n );\n\n if (exec.next?.kind === 'end') {\n return { nextNodeId: null };\n }\n\n const label = exec.next?.kind === 'edgeLabel' ? exec.next.label : undefined;\n return { nextNodeId: findNextNode(flow, node.id, label) };\n }\n\n // Handle failure\n const error = exec.error;\n const policy = this.resolveNodePolicy(flow, node);\n const decision = this.decideOnError(flow, node, policy, error);\n\n // Emit node.failed\n await this.queue.run(() =>\n this.env.events.append({\n runId: this.runId,\n type: 'node.failed',\n nodeId: node.id,\n attempt,\n error,\n decision: decision.kind,\n } as RunEventInput),\n );\n\n if (decision.kind === 'retry' && decision.retryPolicy) {\n const maxAttempts = 1 + Math.max(0, decision.retryPolicy.retries);\n const canRetry =\n attempt < maxAttempts &&\n (decision.retryPolicy.retryOn\n ? decision.retryPolicy.retryOn.includes(\n error.code as (typeof decision.retryPolicy.retryOn)[number],\n )\n : true);\n\n if (!canRetry) {\n return { terminal: 'failed', error };\n }\n\n const delay = computeRetryDelayMs(decision.retryPolicy, attempt);\n if (delay > 0) {\n await sleep(delay);\n }\n attempt++;\n continue;\n }\n\n if (decision.kind === 'continue') {\n return { nextNodeId: findNextNode(flow, node.id) };\n }\n\n if (decision.kind === 'goto') {\n if (decision.target.kind === 'node') {\n return { nextNodeId: decision.target.nodeId };\n }\n return { nextNodeId: findNextNode(flow, node.id, decision.target.label) };\n }\n\n return { terminal: 'failed', error };\n }\n }\n\n private resolveNodePolicy(flow: FlowV3, node: NodeV3): NodePolicy {\n const def = this.env.plugins.getNode(node.kind);\n const flowDefault = flow.policy?.defaultNodePolicy;\n const pluginDefault = def?.defaultPolicy;\n const merged1 = mergeNodePolicy(flowDefault, pluginDefault);\n return mergeNodePolicy(merged1, node.policy);\n }\n\n private decideOnError(\n flow: FlowV3,\n node: NodeV3,\n policy: NodePolicy,\n _error: RRError,\n ): OnErrorDecision {\n const configured = policy.onError;\n\n // Default: if there's an ON_ERROR edge, use it\n if (!configured) {\n const onErrorEdge = findEdgeByLabel(flow, node.id, EDGE_LABELS.ON_ERROR);\n if (onErrorEdge) {\n return { kind: 'goto', target: { kind: 'edgeLabel', label: EDGE_LABELS.ON_ERROR } };\n }\n return { kind: 'stop' };\n }\n\n if (configured.kind === 'stop') return { kind: 'stop' };\n if (configured.kind === 'continue') return { kind: 'continue' };\n if (configured.kind === 'goto') {\n return {\n kind: 'goto',\n target: configured.target as\n | { kind: 'edgeLabel'; label: string }\n | { kind: 'node'; nodeId: NodeId },\n };\n }\n\n // retry\n const base: RetryPolicy = policy.retry ?? { retries: 1, intervalMs: 0 };\n const retryPolicy: RetryPolicy = configured.override\n ? { ...base, ...configured.override }\n : base;\n return { kind: 'retry', retryPolicy };\n }\n\n private async executeNodeAttempt(flow: FlowV3, node: NodeV3): Promise {\n const def = this.env.plugins.getNode(node.kind);\n if (!def) {\n return {\n status: 'failed',\n error: createRRError(\n RR_ERROR_CODES.UNSUPPORTED_NODE,\n `Node kind \"${node.kind}\" is not registered`,\n ),\n };\n }\n\n let parsedConfig: unknown = node.config;\n try {\n parsedConfig = def.schema.parse(node.config);\n } catch (e) {\n return {\n status: 'failed',\n error: createRRError(\n RR_ERROR_CODES.VALIDATION_ERROR,\n `Invalid node config: ${errorMessage(e)}`,\n ),\n };\n }\n\n const ctx: NodeExecutionContext = {\n runId: this.runId,\n flow,\n nodeId: node.id,\n tabId: this.config.tabId,\n vars: this.state.vars,\n log: (level, message, data) => {\n void this.queue\n .run(() =>\n this.env.events.append({\n runId: this.runId,\n type: 'log',\n level,\n message,\n ...(data !== undefined ? { data } : {}),\n } as RunEventInput),\n )\n .catch(() => {});\n },\n chooseNext: (label) => ({ kind: 'edgeLabel', label }),\n artifacts: {\n screenshot: () => this.env.artifactService.screenshot(this.config.tabId),\n },\n persistent: {\n get: async (name) => (await this.env.storage.persistentVars.get(name))?.value,\n set: async (name, value) => {\n await this.env.storage.persistentVars.set(name, value);\n },\n delete: async (name) => {\n await this.env.storage.persistentVars.delete(name);\n },\n },\n };\n\n const policy = this.resolveNodePolicy(flow, node);\n const timeoutMs = policy.timeout?.ms;\n const scope = policy.timeout?.scope ?? 'attempt';\n const attemptTimeoutMs = scope === 'attempt' && timeoutMs !== undefined ? timeoutMs : undefined;\n\n try {\n const nodeWithConfig = { ...node, config: parsedConfig } as Parameters[1];\n const execPromise = def.execute(ctx, nodeWithConfig);\n const result = await withTimeout(execPromise, attemptTimeoutMs, () =>\n createRRError(RR_ERROR_CODES.TIMEOUT, `Node \"${node.id}\" timed out`),\n );\n return result;\n } catch (e) {\n return {\n status: 'failed',\n error: toRRError(e, { code: RR_ERROR_CODES.INTERNAL, message: 'Node execution threw' }),\n };\n }\n }\n\n private async finishSucceeded(startedAt: number): Promise {\n const tookMs = this.env.now() - startedAt;\n await this.queue.run(async () => {\n await this.env.storage.runs.patch(this.runId, {\n status: 'succeeded',\n finishedAt: this.env.now(),\n tookMs,\n outputs: this.outputs,\n });\n await this.env.events.append({\n runId: this.runId,\n type: 'run.succeeded',\n tookMs,\n outputs: this.outputs,\n } as RunEventInput);\n });\n\n return { runId: this.runId, status: 'succeeded', tookMs, outputs: this.outputs };\n }\n\n private async finishFailed(\n startedAt: number,\n error: RRError,\n nodeId?: NodeId,\n ): Promise {\n const tookMs = this.env.now() - startedAt;\n await this.queue.run(async () => {\n await this.env.storage.runs.patch(this.runId, {\n status: 'failed',\n finishedAt: this.env.now(),\n tookMs,\n error,\n ...(nodeId ? { currentNodeId: nodeId } : {}),\n });\n await this.env.events.append({\n runId: this.runId,\n type: 'run.failed',\n error,\n ...(nodeId ? { nodeId } : {}),\n } as RunEventInput);\n });\n\n return { runId: this.runId, status: 'failed', tookMs, error };\n }\n\n private async finishCanceled(startedAt: number): Promise {\n const tookMs = this.env.now() - startedAt;\n await this.queue.run(async () => {\n await this.env.storage.runs.patch(this.runId, {\n status: 'canceled',\n finishedAt: this.env.now(),\n tookMs,\n });\n await this.env.events.append({\n runId: this.runId,\n type: 'run.canceled',\n ...(this.cancelReason ? { reason: this.cancelReason } : {}),\n } as RunEventInput);\n });\n\n return { runId: this.runId, status: 'canceled', tookMs };\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/kernel/traversal.ts", "content": "/**\n * @fileoverview DAG 遍历和校验\n * @description 提供 Flow DAG 的校验、遍历和下一节点查找功能\n */\n\nimport type { NodeId, EdgeLabel } from '../../domain/ids';\nimport type { FlowV3, EdgeV3 } from '../../domain/flow';\nimport { EDGE_LABELS } from '../../domain/ids';\nimport { RR_ERROR_CODES, createRRError, type RRError } from '../../domain/errors';\n\n/**\n * DAG 校验结果\n */\nexport type ValidateFlowDAGResult = { ok: true } | { ok: false; errors: RRError[] };\n\n/**\n * 校验 Flow DAG 结构\n * @param flow Flow 定义\n * @returns 校验结果\n */\nexport function validateFlowDAG(flow: FlowV3): ValidateFlowDAGResult {\n const errors: RRError[] = [];\n const nodeIds = new Set(flow.nodes.map((n) => n.id));\n\n // 检查 entryNodeId 是否存在\n if (!nodeIds.has(flow.entryNodeId)) {\n errors.push(\n createRRError(\n RR_ERROR_CODES.DAG_INVALID,\n `Entry node \"${flow.entryNodeId}\" does not exist in flow`,\n ),\n );\n }\n\n // 检查边引用的节点是否存在\n for (const edge of flow.edges) {\n if (!nodeIds.has(edge.from)) {\n errors.push(\n createRRError(\n RR_ERROR_CODES.DAG_INVALID,\n `Edge \"${edge.id}\" references non-existent source node \"${edge.from}\"`,\n ),\n );\n }\n if (!nodeIds.has(edge.to)) {\n errors.push(\n createRRError(\n RR_ERROR_CODES.DAG_INVALID,\n `Edge \"${edge.id}\" references non-existent target node \"${edge.to}\"`,\n ),\n );\n }\n }\n\n // 检查循环\n const cycle = detectCycle(flow);\n if (cycle) {\n errors.push(\n createRRError(RR_ERROR_CODES.DAG_CYCLE, `Cycle detected in flow: ${cycle.join(' -> ')}`),\n );\n }\n\n return errors.length > 0 ? { ok: false, errors } : { ok: true };\n}\n\n/**\n * 检测 DAG 中的循环\n * @param flow Flow 定义\n * @returns 循环路径（如果存在）或 null\n */\nexport function detectCycle(flow: FlowV3): NodeId[] | null {\n const adjacency = buildAdjacencyMap(flow);\n const visited = new Set();\n const recursionStack = new Set();\n const path: NodeId[] = [];\n\n function dfs(nodeId: NodeId): boolean {\n visited.add(nodeId);\n recursionStack.add(nodeId);\n path.push(nodeId);\n\n const neighbors = adjacency.get(nodeId) || [];\n for (const neighbor of neighbors) {\n if (!visited.has(neighbor)) {\n if (dfs(neighbor)) {\n return true;\n }\n } else if (recursionStack.has(neighbor)) {\n // 找到循环\n const cycleStart = path.indexOf(neighbor);\n path.push(neighbor); // 闭合循环\n path.splice(0, cycleStart); // 移除循环前的节点\n return true;\n }\n }\n\n path.pop();\n recursionStack.delete(nodeId);\n return false;\n }\n\n for (const node of flow.nodes) {\n if (!visited.has(node.id)) {\n if (dfs(node.id)) {\n return path;\n }\n }\n }\n\n return null;\n}\n\n/**\n * 查找下一个节点\n * @param flow Flow 定义\n * @param currentNodeId 当前节点 ID\n * @param label 边标签（可选，默认使用 default）\n * @returns 下一个节点 ID 或 null（如果没有后续节点）\n */\nexport function findNextNode(\n flow: FlowV3,\n currentNodeId: NodeId,\n label?: EdgeLabel,\n): NodeId | null {\n const outEdges = flow.edges.filter((e) => e.from === currentNodeId);\n\n if (outEdges.length === 0) {\n return null;\n }\n\n // 如果指定了 label，优先匹配\n if (label) {\n const matchedEdge = outEdges.find((e) => e.label === label);\n if (matchedEdge) {\n return matchedEdge.to;\n }\n }\n\n // 否则使用 default 边\n const defaultEdge = outEdges.find(\n (e) => e.label === EDGE_LABELS.DEFAULT || e.label === undefined,\n );\n if (defaultEdge) {\n return defaultEdge.to;\n }\n\n // 如果只有一条边，使用它\n if (outEdges.length === 1) {\n return outEdges[0].to;\n }\n\n return null;\n}\n\n/**\n * 查找指定标签的边\n */\nexport function findEdgeByLabel(\n flow: FlowV3,\n fromNodeId: NodeId,\n label: EdgeLabel,\n): EdgeV3 | undefined {\n return flow.edges.find((e) => e.from === fromNodeId && e.label === label);\n}\n\n/**\n * 获取节点的所有出边\n */\nexport function getOutEdges(flow: FlowV3, nodeId: NodeId): EdgeV3[] {\n return flow.edges.filter((e) => e.from === nodeId);\n}\n\n/**\n * 获取节点的所有入边\n */\nexport function getInEdges(flow: FlowV3, nodeId: NodeId): EdgeV3[] {\n return flow.edges.filter((e) => e.to === nodeId);\n}\n\n/**\n * 构建邻接表\n */\nfunction buildAdjacencyMap(flow: FlowV3): Map {\n const map = new Map();\n\n for (const node of flow.nodes) {\n map.set(node.id, []);\n }\n\n for (const edge of flow.edges) {\n const neighbors = map.get(edge.from);\n if (neighbors) {\n neighbors.push(edge.to);\n }\n }\n\n return map;\n}\n\n/**\n * 获取从入口节点可达的所有节点\n */\nexport function getReachableNodes(flow: FlowV3): Set {\n const reachable = new Set();\n const adjacency = buildAdjacencyMap(flow);\n\n function dfs(nodeId: NodeId): void {\n if (reachable.has(nodeId)) return;\n reachable.add(nodeId);\n\n const neighbors = adjacency.get(nodeId) || [];\n for (const neighbor of neighbors) {\n dfs(neighbor);\n }\n }\n\n dfs(flow.entryNodeId);\n return reachable;\n}\n\n/**\n * 检查节点是否可达\n */\nexport function isNodeReachable(flow: FlowV3, nodeId: NodeId): boolean {\n return getReachableNodes(flow).has(nodeId);\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/plugins/index.ts", "content": "/**\n * @fileoverview 插件系统导出入口\n */\n\nexport * from './types';\nexport * from './registry';\nexport * from './v2-action-adapter';\nexport * from './register-v2-replay-nodes';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/plugins/register-v2-replay-nodes.ts", "content": "/**\n * @fileoverview Register RR-V2 replay action handlers as RR-V3 nodes\n * @description\n * Batch registration of V2 action handlers into the V3 PluginRegistry.\n * This enables V3 to execute flows that use V2 action types.\n */\n\nimport { createReplayActionRegistry } from '@/entrypoints/background/record-replay/actions/handlers';\nimport type {\n ActionHandler,\n ExecutableActionType,\n} from '@/entrypoints/background/record-replay/actions/types';\n\nimport type { PluginRegistry } from './registry';\nimport {\n adaptV2ActionHandlerToV3NodeDefinition,\n type V2ActionNodeAdapterOptions,\n} from './v2-action-adapter';\n\nexport interface RegisterV2ReplayNodesOptions extends V2ActionNodeAdapterOptions {\n /**\n * Only include these action types. If not specified, all V2 handlers are included.\n */\n include?: ReadonlyArray;\n\n /**\n * Exclude these action types. Applied after include filter.\n */\n exclude?: ReadonlyArray;\n}\n\n/**\n * Register V2 replay action handlers as V3 node definitions.\n *\n * @param registry The V3 PluginRegistry to register nodes into\n * @param options Configuration options\n * @returns Array of registered node kinds\n *\n * @example\n * ```ts\n * const plugins = new PluginRegistry();\n * const registered = registerV2ReplayNodesAsV3Nodes(plugins, {\n * // Exclude control flow handlers that V3 runner doesn't support\n * exclude: ['foreach', 'while'],\n * });\n * console.log('Registered:', registered);\n * ```\n */\nexport function registerV2ReplayNodesAsV3Nodes(\n registry: PluginRegistry,\n options: RegisterV2ReplayNodesOptions = {},\n): string[] {\n const actionRegistry = createReplayActionRegistry();\n const handlers = actionRegistry.list();\n\n const include = options.include ? new Set(options.include) : null;\n const exclude = options.exclude ? new Set(options.exclude) : null;\n\n const registered: string[] = [];\n\n for (const handler of handlers) {\n if (include && !include.has(handler.type)) continue;\n if (exclude && exclude.has(handler.type)) continue;\n\n // Cast needed because V2 handler types don't perfectly align with V3 NodeKind\n const nodeDef = adaptV2ActionHandlerToV3NodeDefinition(\n handler as ActionHandler,\n options,\n );\n registry.registerNode(nodeDef as unknown as Parameters[0]);\n registered.push(handler.type);\n }\n\n return registered;\n}\n\n/**\n * Get list of V2 action types that can be registered.\n * Useful for debugging and documentation.\n */\nexport function listV2ActionTypes(): string[] {\n const actionRegistry = createReplayActionRegistry();\n return actionRegistry.list().map((h) => h.type);\n}\n\n/**\n * Default exclude list for V3 registration.\n * These handlers rely on V2 control directives that V3 runner doesn't support.\n */\nexport const DEFAULT_V2_EXCLUDE_LIST = ['foreach', 'while'] as const;\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/plugins/registry.ts", "content": "/**\n * @fileoverview 插件注册表\n * @description 管理节点和触发器插件的注册和查询\n */\n\nimport type { NodeKind } from '../../domain/flow';\nimport type { TriggerKind } from '../../domain/triggers';\nimport { RR_ERROR_CODES, createRRError } from '../../domain/errors';\nimport type {\n NodeDefinition,\n TriggerDefinition,\n PluginRegistrationContext,\n RRPlugin,\n} from './types';\n\n/**\n * 插件注册表\n * @description 单例模式，管理所有已注册的节点和触发器\n */\nexport class PluginRegistry implements PluginRegistrationContext {\n private nodes = new Map();\n private triggers = new Map();\n\n /**\n * 注册节点定义\n * @description 如果已存在同名节点，会覆盖\n */\n registerNode(def: NodeDefinition): void {\n this.nodes.set(def.kind, def);\n }\n\n /**\n * 注册触发器定义\n * @description 如果已存在同名触发器，会覆盖\n */\n registerTrigger(def: TriggerDefinition): void {\n this.triggers.set(def.kind, def);\n }\n\n /**\n * 获取节点定义\n * @returns 节点定义或 undefined\n */\n getNode(kind: NodeKind): NodeDefinition | undefined {\n return this.nodes.get(kind);\n }\n\n /**\n * 获取节点定义（必须存在）\n * @throws RRError 如果节点未注册\n */\n getNodeOrThrow(kind: NodeKind): NodeDefinition {\n const def = this.nodes.get(kind);\n if (!def) {\n throw createRRError(RR_ERROR_CODES.UNSUPPORTED_NODE, `Node kind \"${kind}\" is not registered`);\n }\n return def;\n }\n\n /**\n * 获取触发器定义\n * @returns 触发器定义或 undefined\n */\n getTrigger(kind: TriggerKind): TriggerDefinition | undefined {\n return this.triggers.get(kind);\n }\n\n /**\n * 获取触发器定义（必须存在）\n * @throws RRError 如果触发器未注册\n */\n getTriggerOrThrow(kind: TriggerKind): TriggerDefinition {\n const def = this.triggers.get(kind);\n if (!def) {\n throw createRRError(\n RR_ERROR_CODES.UNSUPPORTED_NODE,\n `Trigger kind \"${kind}\" is not registered`,\n );\n }\n return def;\n }\n\n /**\n * 检查节点是否已注册\n */\n hasNode(kind: NodeKind): boolean {\n return this.nodes.has(kind);\n }\n\n /**\n * 检查触发器是否已注册\n */\n hasTrigger(kind: TriggerKind): boolean {\n return this.triggers.has(kind);\n }\n\n /**\n * 获取所有已注册的节点类型\n */\n listNodeKinds(): NodeKind[] {\n return Array.from(this.nodes.keys());\n }\n\n /**\n * 获取所有已注册的触发器类型\n */\n listTriggerKinds(): TriggerKind[] {\n return Array.from(this.triggers.keys());\n }\n\n /**\n * 注册插件\n * @description 调用插件的 register 方法\n */\n registerPlugin(plugin: RRPlugin): void {\n plugin.register(this);\n }\n\n /**\n * 批量注册插件\n */\n registerPlugins(plugins: RRPlugin[]): void {\n for (const plugin of plugins) {\n this.registerPlugin(plugin);\n }\n }\n\n /**\n * 清空所有注册\n * @description 主要用于测试\n */\n clear(): void {\n this.nodes.clear();\n this.triggers.clear();\n }\n}\n\n/** 全局插件注册表实例 */\nlet globalRegistry: PluginRegistry | null = null;\n\n/**\n * 获取全局插件注册表\n */\nexport function getPluginRegistry(): PluginRegistry {\n if (!globalRegistry) {\n globalRegistry = new PluginRegistry();\n }\n return globalRegistry;\n}\n\n/**\n * 重置全局插件注册表\n * @description 主要用于测试\n */\nexport function resetPluginRegistry(): void {\n globalRegistry = null;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/plugins/types.ts", "content": "/**\n * @fileoverview 插件类型定义\n * @description 定义 Record-Replay V3 中的节点和触发器插件接口\n */\n\nimport { z } from 'zod';\n\nimport type { JsonObject, JsonValue } from '../../domain/json';\nimport type { FlowId, NodeId, RunId, TriggerId } from '../../domain/ids';\nimport type { NodeKind } from '../../domain/flow';\nimport type { RRError } from '../../domain/errors';\nimport type { NodePolicy } from '../../domain/policy';\nimport type { FlowV3, NodeV3 } from '../../domain/flow';\nimport type { TriggerKind } from '../../domain/triggers';\n\n/**\n * Schema 类型\n * @description 使用 Zod 进行配置校验\n */\nexport type Schema = z.ZodType;\n\n/**\n * 节点执行上下文\n * @description 提供给节点执行器的运行时上下文\n */\nexport interface NodeExecutionContext {\n /** Run ID */\n runId: RunId;\n /** Flow 定义（快照） */\n flow: FlowV3;\n /** 当前节点 ID */\n nodeId: NodeId;\n\n /** 绑定的 Tab ID（每 Run 独占） */\n tabId: number;\n /** Frame ID（默认 0 为主框架） */\n frameId?: number;\n\n /** 当前变量表 */\n vars: Record;\n\n /**\n * 日志记录\n */\n log: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: JsonValue) => void;\n\n /**\n * 选择下一个边\n * @description 用于条件分支节点\n */\n chooseNext: (label: string) => { kind: 'edgeLabel'; label: string };\n\n /**\n * 工件操作\n */\n artifacts: {\n /** 截取当前页面截图 */\n screenshot: () => Promise<{ ok: true; base64: string } | { ok: false; error: RRError }>;\n };\n\n /**\n * 持久化变量操作\n */\n persistent: {\n /** 获取持久化变量 */\n get: (name: `$${string}`) => Promise;\n /** 设置持久化变量 */\n set: (name: `$${string}`, value: JsonValue) => Promise;\n /** 删除持久化变量 */\n delete: (name: `$${string}`) => Promise;\n };\n}\n\n/**\n * 变量补丁操作\n */\nexport interface VarsPatchOp {\n op: 'set' | 'delete';\n name: string;\n value?: JsonValue;\n}\n\n/**\n * 节点执行结果\n */\nexport type NodeExecutionResult =\n | {\n status: 'succeeded';\n /** 下一步执行方向 */\n next?: { kind: 'edgeLabel'; label: string } | { kind: 'end' };\n /** 输出结果 */\n outputs?: JsonObject;\n /** 变量修改 */\n varsPatch?: VarsPatchOp[];\n }\n | { status: 'failed'; error: RRError };\n\n/**\n * 节点定义\n * @description 定义一种节点类型的执行逻辑\n */\nexport interface NodeDefinition<\n TKind extends NodeKind = NodeKind,\n TConfig extends JsonObject = JsonObject,\n> {\n /** 节点类型标识 */\n kind: TKind;\n /** 配置校验 Schema */\n schema: Schema;\n /** 默认策略 */\n defaultPolicy?: NodePolicy;\n /**\n * 执行节点\n * @param ctx 执行上下文\n * @param node 节点定义（含配置）\n */\n execute(\n ctx: NodeExecutionContext,\n node: NodeV3 & { kind: TKind; config: TConfig },\n ): Promise;\n}\n\n/**\n * 触发器安装上下文\n */\nexport interface TriggerInstallContext<\n TKind extends TriggerKind = TriggerKind,\n TConfig extends JsonObject = JsonObject,\n> {\n /** 触发器 ID */\n triggerId: TriggerId;\n /** 触发器类型 */\n kind: TKind;\n /** 是否启用 */\n enabled: boolean;\n /** 关联的 Flow ID */\n flowId: FlowId;\n /** 触发器配置 */\n config: TConfig;\n /** 传递给 Flow 的参数 */\n args?: JsonObject;\n}\n\n/**\n * 触发器定义\n * @description 定义一种触发器类型的安装和卸载逻辑\n */\nexport interface TriggerDefinition<\n TKind extends TriggerKind = TriggerKind,\n TConfig extends JsonObject = JsonObject,\n> {\n /** 触发器类型标识 */\n kind: TKind;\n /** 配置校验 Schema */\n schema: Schema;\n /** 安装触发器 */\n install(ctx: TriggerInstallContext): Promise | void;\n /** 卸载触发器 */\n uninstall(ctx: TriggerInstallContext): Promise | void;\n}\n\n/**\n * 插件注册上下文\n */\nexport interface PluginRegistrationContext {\n /** 注册节点定义 */\n registerNode(def: NodeDefinition): void;\n /** 注册触发器定义 */\n registerTrigger(def: TriggerDefinition): void;\n}\n\n/**\n * 插件接口\n * @description Record-Replay 插件的标准接口\n */\nexport interface RRPlugin {\n /** 插件名称 */\n name: string;\n /** 注册插件内容 */\n register(ctx: PluginRegistrationContext): void;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/plugins/v2-action-adapter.ts", "content": "/**\n * @fileoverview V2 ActionHandler -> V3 NodeDefinition adapter\n * @description Bridges legacy RR-V2 action handlers into the RR-V3 PluginRegistry.\n *\n * Design notes:\n * - V3 requires variable mutations to be represented as varsPatch so they are auditable in the event log.\n * - V2 handlers mutate ctx.vars directly, so we run them against a cloned VariableStore and diff it.\n * - Cross-node state (tabId/frameId changes from switchFrame/openTab/switchTab) is persisted in internal vars.\n *\n * WARNING: This adapter accesses V2 handler internals and may need updates if V2 types change.\n */\n\nimport { z } from 'zod';\n\nimport type {\n ActionExecutionContext,\n ActionExecutionResult,\n ActionHandler,\n ActionError,\n ActionErrorCode,\n ActionPolicy,\n ExecutableActionType,\n ValidationResult,\n Action,\n} from '@/entrypoints/background/record-replay/actions/types';\n\nimport type { JsonValue, JsonObject } from '../../domain/json';\nimport { RR_ERROR_CODES, createRRError, type RRError, type RRErrorCode } from '../../domain/errors';\nimport type { NodePolicy } from '../../domain/policy';\nimport { mergeNodePolicy } from '../../domain/policy';\n\nimport type {\n NodeDefinition,\n NodeExecutionContext,\n NodeExecutionResult,\n VarsPatchOp,\n} from './types';\n\n// Internal run-scoped state keys used to emulate V2 \"mutable context\" across nodes.\nconst DEFAULT_TAB_ID_VAR = '__rr_v2__tabId';\nconst DEFAULT_FRAME_ID_VAR = '__rr_v2__frameId';\n\nexport interface V2ActionNodeAdapterOptions {\n /**\n * Whether to emit v2 ActionExecutionResult.output into V3 NodeExecutionResult.outputs.\n * Defaults to true.\n */\n includeOutput?: boolean;\n\n /**\n * Where to store cross-node \"mutable context\" state (tabId/frameId).\n * Defaults are \"__rr_v2__tabId\" and \"__rr_v2__frameId\".\n */\n stateVars?: {\n tabIdVar?: string;\n frameIdVar?: string;\n };\n\n /**\n * Execution flags forwarded into V2 ActionExecutionContext.execution.\n * Keep default undefined to preserve V2 handler behavior.\n */\n executionFlags?: ActionExecutionContext['execution'];\n}\n\n// ==================== Utilities ====================\n\nfunction toErrorMessage(e: unknown): string {\n if (e instanceof Error) return e.message;\n if (e && typeof e === 'object' && 'message' in e)\n return String((e as { message: unknown }).message);\n return String(e);\n}\n\nfunction deepClone(value: T): T {\n const sc = (globalThis as unknown as { structuredClone?: (v: U) => U }).structuredClone;\n if (typeof sc === 'function') return sc(value);\n return JSON.parse(JSON.stringify(value)) as T;\n}\n\nfunction safeJsonValue(value: unknown): JsonValue {\n if (value === undefined) return null;\n try {\n const s = JSON.stringify(value);\n if (s === undefined) return String(value);\n return JSON.parse(s) as JsonValue;\n } catch {\n return String(value);\n }\n}\n\nfunction mapLogLevel(level: 'info' | 'warn' | 'error' | undefined): 'info' | 'warn' | 'error' {\n return level ?? 'info';\n}\n\nfunction mapV2ErrorCode(code: ActionErrorCode): RRErrorCode {\n switch (code) {\n case 'VALIDATION_ERROR':\n return RR_ERROR_CODES.VALIDATION_ERROR;\n case 'TIMEOUT':\n return RR_ERROR_CODES.TIMEOUT;\n case 'TAB_NOT_FOUND':\n return RR_ERROR_CODES.TAB_NOT_FOUND;\n case 'FRAME_NOT_FOUND':\n return RR_ERROR_CODES.FRAME_NOT_FOUND;\n case 'TARGET_NOT_FOUND':\n return RR_ERROR_CODES.TARGET_NOT_FOUND;\n case 'ELEMENT_NOT_VISIBLE':\n return RR_ERROR_CODES.ELEMENT_NOT_VISIBLE;\n case 'NAVIGATION_FAILED':\n return RR_ERROR_CODES.NAVIGATION_FAILED;\n case 'NETWORK_REQUEST_FAILED':\n return RR_ERROR_CODES.NETWORK_REQUEST_FAILED;\n case 'SCRIPT_FAILED':\n return RR_ERROR_CODES.SCRIPT_FAILED;\n\n // V3 doesn't currently have dedicated codes for these.\n case 'DOWNLOAD_FAILED':\n case 'ASSERTION_FAILED':\n return RR_ERROR_CODES.TOOL_ERROR;\n\n case 'UNKNOWN':\n default:\n return RR_ERROR_CODES.INTERNAL;\n }\n}\n\nfunction toRRErrorFromV2(error: ActionError): RRError {\n const data = error.data !== undefined ? safeJsonValue(error.data) : undefined;\n return createRRError(\n mapV2ErrorCode(error.code),\n error.message,\n data !== undefined ? { data } : undefined,\n );\n}\n\nfunction isRecord(value: unknown): value is Record {\n return typeof value === 'object' && value !== null;\n}\n\nfunction jsonEquals(a: JsonValue, b: JsonValue): boolean {\n if (a === b) return true;\n\n const aIsArray = Array.isArray(a);\n const bIsArray = Array.isArray(b);\n if (aIsArray || bIsArray) {\n if (!aIsArray || !bIsArray) return false;\n if (a.length !== b.length) return false;\n for (let i = 0; i < a.length; i++) {\n if (!jsonEquals(a[i] as JsonValue, b[i] as JsonValue)) return false;\n }\n return true;\n }\n\n const aIsObj = isRecord(a);\n const bIsObj = isRecord(b);\n if (aIsObj || bIsObj) {\n if (!aIsObj || !bIsObj) return false;\n const aKeys = Object.keys(a);\n const bKeys = Object.keys(b);\n if (aKeys.length !== bKeys.length) return false;\n for (const k of aKeys) {\n if (!Object.prototype.hasOwnProperty.call(b, k)) return false;\n if (!jsonEquals(a[k] as JsonValue, (b as Record)[k] as JsonValue))\n return false;\n }\n return true;\n }\n\n return false;\n}\n\nfunction diffVars(\n before: Record,\n after: Record,\n): VarsPatchOp[] {\n const patch: VarsPatchOp[] = [];\n const keys = new Set([...Object.keys(before), ...Object.keys(after)]);\n\n for (const key of keys) {\n const beforeHas = Object.prototype.hasOwnProperty.call(before, key);\n const afterHas = Object.prototype.hasOwnProperty.call(after, key);\n\n if (!afterHas) {\n if (beforeHas) patch.push({ op: 'delete', name: key });\n continue;\n }\n\n const afterVal = after[key];\n if (!beforeHas) {\n patch.push({ op: 'set', name: key, value: afterVal });\n continue;\n }\n\n const beforeVal = before[key];\n if (!jsonEquals(beforeVal, afterVal)) {\n patch.push({ op: 'set', name: key, value: afterVal });\n }\n }\n\n return patch;\n}\n\nfunction readNumberVar(vars: Record, key: string): number | undefined {\n const v = vars[key];\n return typeof v === 'number' && Number.isFinite(v) ? v : undefined;\n}\n\nfunction toV2ActionPolicy(policy: NodePolicy | undefined): ActionPolicy | undefined {\n if (!policy) return undefined;\n\n const timeout = policy.timeout\n ? {\n ms: policy.timeout.ms,\n scope: policy.timeout.scope === 'node' ? ('action' as const) : ('attempt' as const),\n }\n : undefined;\n\n // NodePolicy/ActionPolicy are structurally similar; we only normalize timeout.scope.\n return {\n ...(timeout ? { timeout } : {}),\n ...(policy.retry ? { retry: policy.retry as unknown as ActionPolicy['retry'] } : {}),\n ...(policy.artifacts\n ? { artifacts: policy.artifacts as unknown as ActionPolicy['artifacts'] }\n : {}),\n ...(policy.onError\n ? (() => {\n // V2 only supports goto by edge label. Node-target goto can't be represented.\n if (policy.onError.kind === 'goto' && policy.onError.target.kind === 'node') {\n return { onError: { kind: 'stop' } as ActionPolicy['onError'] };\n }\n if (policy.onError.kind === 'continue') {\n return {\n onError: {\n kind: 'continue',\n level: policy.onError.as,\n } as ActionPolicy['onError'],\n };\n }\n if (policy.onError.kind === 'goto') {\n const target = policy.onError.target;\n if (target.kind === 'edgeLabel') {\n return {\n onError: {\n kind: 'goto',\n label: target.label,\n } as ActionPolicy['onError'],\n };\n }\n // Node target can't be represented in V2, fall through to stop\n return { onError: { kind: 'stop' } as ActionPolicy['onError'] };\n }\n if (policy.onError.kind === 'retry') {\n // V2 has retry policy on action.policy.retry; keep onError as stop to avoid double semantics.\n return { onError: { kind: 'stop' } as ActionPolicy['onError'] };\n }\n return { onError: policy.onError as unknown as ActionPolicy['onError'] };\n })()\n : {}),\n };\n}\n\nfunction toJsonRecord(value: unknown): Record {\n const out: Record = {};\n if (!isRecord(value)) return out;\n\n for (const [k, v] of Object.entries(value)) {\n // Treat undefined as deletion (omit).\n if (v === undefined) continue;\n out[k] = safeJsonValue(v);\n }\n\n return out;\n}\n\n// ==================== Main Adapter ====================\n\n/**\n * Adapt a single V2 ActionHandler into a V3 NodeDefinition.\n */\nexport function adaptV2ActionHandlerToV3NodeDefinition(\n handler: ActionHandler,\n options: V2ActionNodeAdapterOptions = {},\n): NodeDefinition {\n const tabIdVar = options.stateVars?.tabIdVar ?? DEFAULT_TAB_ID_VAR;\n const frameIdVar = options.stateVars?.frameIdVar ?? DEFAULT_FRAME_ID_VAR;\n\n return {\n kind: handler.type,\n schema: z.record(z.any()) as unknown as NodeDefinition['schema'],\n execute: async (ctx: NodeExecutionContext, node): Promise => {\n const beforeVars = ctx.vars;\n\n const effectiveTabId = readNumberVar(beforeVars, tabIdVar) ?? ctx.tabId;\n const effectiveFrameId = readNumberVar(beforeVars, frameIdVar);\n\n // Run against a cloned variable store to prevent bypassing vars.patch event stream.\n const v2Vars = deepClone(beforeVars) as unknown as Record;\n\n const v2Ctx: ActionExecutionContext = {\n vars: v2Vars as unknown as ActionExecutionContext['vars'],\n tabId: effectiveTabId,\n frameId: effectiveFrameId,\n runId: ctx.runId,\n log: (message, level) => ctx.log(mapLogLevel(level), message),\n pushLog: (entry) => {\n try {\n ctx.log('debug', 'v2.pushLog', safeJsonValue(entry));\n } catch {\n // ignore\n }\n },\n captureScreenshot: async () => {\n const r = await ctx.artifacts.screenshot();\n if (r.ok) return r.base64;\n throw new Error(r.error.message);\n },\n ...(options.executionFlags ? { execution: options.executionFlags } : {}),\n };\n\n const effectivePolicy = mergeNodePolicy(ctx.flow.policy?.defaultNodePolicy, node.policy);\n const v2Policy = toV2ActionPolicy(effectivePolicy);\n\n const action: Action = {\n id: node.id as Action['id'],\n type: handler.type,\n ...(node.name ? { name: node.name } : {}),\n ...(node.disabled ? { disabled: true } : {}),\n ...(v2Policy ? { policy: v2Policy } : {}),\n params: node.config as unknown as Action['params'],\n ...(node.ui ? { ui: node.ui as Action['ui'] } : {}),\n };\n\n // V2 handler-level validation\n if (handler.validate) {\n const v: ValidationResult = handler.validate(action);\n if (!v.ok) {\n return {\n status: 'failed',\n error: createRRError(RR_ERROR_CODES.VALIDATION_ERROR, v.errors.join(', ')),\n };\n }\n }\n\n let result: ActionExecutionResult;\n try {\n result = await handler.run(v2Ctx, action);\n } catch (e) {\n return {\n status: 'failed',\n error: createRRError(\n RR_ERROR_CODES.INTERNAL,\n `V2 handler \"${handler.type}\" threw: ${toErrorMessage(e)}`,\n ),\n };\n }\n\n if (result.status === 'failed') {\n const err = result.error\n ? toRRErrorFromV2(result.error)\n : createRRError(RR_ERROR_CODES.INTERNAL, `V2 handler \"${handler.type}\" failed`);\n return { status: 'failed', error: err };\n }\n\n if (result.status === 'paused') {\n return {\n status: 'failed',\n error: createRRError(\n RR_ERROR_CODES.RUN_PAUSED,\n `V2 handler \"${handler.type}\" returned paused (not supported in V3 NodeExecutionResult)`,\n ),\n };\n }\n\n // V3 does not support V2 scheduler control directives (foreach/while).\n if (result.control) {\n return {\n status: 'failed',\n error: createRRError(\n RR_ERROR_CODES.UNSUPPORTED_NODE,\n `V2 control directive \"${result.control.kind}\" is not supported by the V3 runner`,\n { data: safeJsonValue(result.control) },\n ),\n };\n }\n\n // Persist cross-node context changes via internal vars.\n if (typeof v2Ctx.frameId === 'number' && Number.isFinite(v2Ctx.frameId)) {\n v2Vars[frameIdVar] = v2Ctx.frameId;\n } else {\n delete v2Vars[frameIdVar];\n }\n\n if (typeof result.newTabId === 'number' && Number.isFinite(result.newTabId)) {\n v2Vars[tabIdVar] = result.newTabId;\n }\n\n const afterVars = toJsonRecord(v2Vars);\n const varsPatch = diffVars(beforeVars, afterVars);\n\n const outputs: Record | undefined =\n options.includeOutput === false || result.output === undefined\n ? undefined\n : { [node.id]: safeJsonValue(result.output) };\n\n return {\n status: 'succeeded',\n ...(result.nextLabel ? { next: ctx.chooseNext(result.nextLabel) } : {}),\n ...(outputs ? { outputs } : {}),\n ...(varsPatch.length > 0 ? { varsPatch } : {}),\n };\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/queue/enqueue-run.ts", "content": "/**\n * @fileoverview 共享入队服务\n * @description\n * 提供统一的 Run 入队逻辑，供 RPC Server 和 TriggerManager 共用。\n *\n * 设计理由：\n * - 将原本位于 RpcServer 的入队逻辑抽离为独立服务\n * - 避免 RPC 和 TriggerManager 之间的行为漂移\n * - 统一参数校验、Run 创建、队列入队、事件发布流程\n */\n\nimport type { JsonObject, UnixMillis } from '../../domain/json';\nimport type { FlowId, NodeId, RunId } from '../../domain/ids';\nimport type { TriggerFireContext } from '../../domain/triggers';\nimport { RUN_SCHEMA_VERSION, type RunRecordV3 } from '../../domain/events';\nimport type { StoragePort } from '../storage/storage-port';\nimport type { EventsBus } from '../transport/events-bus';\nimport type { RunScheduler } from './scheduler';\n\n// ==================== Types ====================\n\n/**\n * 入队服务依赖\n */\nexport interface EnqueueRunDeps {\n /** 存储层 (仅需 flows/runs/queue) */\n storage: Pick;\n /** 事件总线 */\n events: Pick;\n /** 调度器 (可选) */\n scheduler?: Pick;\n /** RunId 生成器 (用于测试注入) */\n generateRunId?: () => RunId;\n /** 时间源 (用于测试注入) */\n now?: () => UnixMillis;\n}\n\n/**\n * 入队请求参数\n */\nexport interface EnqueueRunInput {\n /** Flow ID (必选) */\n flowId: FlowId;\n /** 起始节点 ID (可选，默认使用 Flow 的 entryNodeId) */\n startNodeId?: NodeId;\n /** 优先级 (默认 0) */\n priority?: number;\n /** 最大尝试次数 (默认 1) */\n maxAttempts?: number;\n /** 传递给 Flow 的参数 */\n args?: JsonObject;\n /** 触发上下文 (由 TriggerManager 设置) */\n trigger?: TriggerFireContext;\n /** 调试选项 */\n debug?: {\n breakpoints?: NodeId[];\n pauseOnStart?: boolean;\n };\n}\n\n/**\n * 入队结果\n */\nexport interface EnqueueRunResult {\n /** 新创建的 Run ID */\n runId: RunId;\n /** 在队列中的位置 (1-based) */\n position: number;\n}\n\n// ==================== Utilities ====================\n\n/**\n * 默认 RunId 生成器\n */\nfunction defaultGenerateRunId(): RunId {\n return `run_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n}\n\n/**\n * 校验整数参数\n */\nfunction validateInt(\n value: unknown,\n defaultValue: number,\n fieldName: string,\n opts?: { min?: number; max?: number },\n): number {\n if (value === undefined || value === null) {\n return defaultValue;\n }\n if (typeof value !== 'number' || !Number.isFinite(value)) {\n throw new Error(`${fieldName} must be a finite number`);\n }\n const intValue = Math.floor(value);\n if (opts?.min !== undefined && intValue < opts.min) {\n throw new Error(`${fieldName} must be >= ${opts.min}`);\n }\n if (opts?.max !== undefined && intValue > opts.max) {\n throw new Error(`${fieldName} must be <= ${opts.max}`);\n }\n return intValue;\n}\n\n/**\n * 计算 Run 在队列中的位置\n * @description 按调度顺序: priority DESC + createdAt ASC\n * @returns 1-based position, or -1 if run not found in queued items\n *\n * Note: Due to race conditions (scheduler may claim the run before this is called),\n * position may be -1. Callers should handle this gracefully.\n */\nasync function computeQueuePosition(\n storage: Pick,\n runId: RunId,\n): Promise {\n const queueItems = await storage.queue.list('queued');\n queueItems.sort((a, b) => {\n if (a.priority !== b.priority) return b.priority - a.priority;\n return a.createdAt - b.createdAt;\n });\n const index = queueItems.findIndex((item) => item.id === runId);\n // Return -1 if not found (run may have been claimed already)\n return index === -1 ? -1 : index + 1;\n}\n\n// ==================== Main Function ====================\n\n/**\n * 入队执行一个 Run\n * @description\n * 执行步骤：\n * 1. 参数校验\n * 2. 验证 Flow 存在\n * 3. 创建 RunRecordV3 (status=queued)\n * 4. 入队到 RunQueue\n * 5. 发布 run.queued 事件\n * 6. 触发调度 (best-effort)\n * 7. 计算队列位置\n */\nexport async function enqueueRun(\n deps: EnqueueRunDeps,\n input: EnqueueRunInput,\n): Promise {\n const { flowId } = input;\n if (!flowId) {\n throw new Error('flowId is required');\n }\n\n const now = deps.now ?? (() => Date.now());\n const generateRunId = deps.generateRunId ?? defaultGenerateRunId;\n\n // 参数校验\n const priority = validateInt(input.priority, 0, 'priority');\n const maxAttempts = validateInt(input.maxAttempts, 1, 'maxAttempts', { min: 1 });\n\n // 验证 Flow 存在\n const flow = await deps.storage.flows.get(flowId);\n if (!flow) {\n throw new Error(`Flow \"${flowId}\" not found`);\n }\n\n // 验证 startNodeId 存在于 Flow 中\n if (input.startNodeId) {\n const nodeExists = flow.nodes.some((n) => n.id === input.startNodeId);\n if (!nodeExists) {\n throw new Error(`startNodeId \"${input.startNodeId}\" not found in flow \"${flowId}\"`);\n }\n }\n\n const ts = now();\n const runId = generateRunId();\n\n // 1. 创建 RunRecordV3\n const runRecord: RunRecordV3 = {\n schemaVersion: RUN_SCHEMA_VERSION,\n id: runId,\n flowId,\n status: 'queued',\n createdAt: ts,\n updatedAt: ts,\n attempt: 0,\n maxAttempts,\n args: input.args,\n trigger: input.trigger,\n debug: input.debug,\n startNodeId: input.startNodeId,\n nextSeq: 0,\n };\n await deps.storage.runs.save(runRecord);\n\n // 2. 入队\n await deps.storage.queue.enqueue({\n id: runId,\n flowId,\n priority,\n maxAttempts,\n args: input.args,\n trigger: input.trigger,\n debug: input.debug,\n });\n\n // 3. 发布 run.queued 事件\n await deps.events.append({\n runId,\n type: 'run.queued',\n flowId,\n });\n\n // 4. 计算队列位置 (在 kick 之前计算，减少竞态条件导致 position=-1 的概率)\n const position = await computeQueuePosition(deps.storage, runId);\n\n // 5. 触发调度 (best-effort, 不阻塞返回)\n if (deps.scheduler) {\n void deps.scheduler.kick();\n }\n\n return { runId, position };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/queue/index.ts", "content": "/**\n * @fileoverview Queue 模块导出入口\n */\n\nexport * from './queue';\nexport * from './leasing';\nexport * from './scheduler';\nexport * from './enqueue-run';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/queue/leasing.ts", "content": "/**\n * @fileoverview 租约管理\n * @description 管理 Run 的租约续约和过期回收\n */\n\nimport type { UnixMillis } from '../../domain/json';\nimport type { RunId } from '../../domain/ids';\nimport type { RunQueue, RunQueueConfig, Lease } from './queue';\n\n/**\n * 租约管理器\n * @description 管理租约续约和过期检测\n */\nexport interface LeaseManager {\n /**\n * 开始心跳\n * @param ownerId 持有者 ID\n */\n startHeartbeat(ownerId: string): void;\n\n /**\n * 停止心跳\n * @param ownerId 持有者 ID\n */\n stopHeartbeat(ownerId: string): void;\n\n /**\n * 检查并回收过期租约\n * @param now 当前时间\n * @returns 被回收的 Run ID 列表\n */\n reclaimExpiredLeases(now: UnixMillis): Promise;\n\n /**\n * 判断租约是否过期\n */\n isLeaseExpired(lease: Lease, now: UnixMillis): boolean;\n\n /**\n * 创建新租约\n */\n createLease(ownerId: string, now: UnixMillis): Lease;\n\n /**\n * 停止所有心跳\n */\n dispose(): void;\n}\n\n/**\n * 创建租约管理器\n */\nexport function createLeaseManager(queue: RunQueue, config: RunQueueConfig): LeaseManager {\n const heartbeatTimers = new Map>();\n\n return {\n startHeartbeat(ownerId: string): void {\n // 如果已有定时器，先停止\n this.stopHeartbeat(ownerId);\n\n // 创建新的心跳定时器\n const timer = setInterval(async () => {\n try {\n await queue.heartbeat(ownerId, Date.now());\n } catch (error) {\n console.error(`[LeaseManager] Heartbeat failed for ${ownerId}:`, error);\n }\n }, config.heartbeatIntervalMs);\n\n heartbeatTimers.set(ownerId, timer);\n },\n\n stopHeartbeat(ownerId: string): void {\n const timer = heartbeatTimers.get(ownerId);\n if (timer) {\n clearInterval(timer);\n heartbeatTimers.delete(ownerId);\n }\n },\n\n async reclaimExpiredLeases(now: UnixMillis): Promise {\n // Delegate to the queue implementation which uses the lease_expiresAt index\n // for efficient scanning and updates storage atomically.\n return queue.reclaimExpiredLeases(now);\n },\n\n isLeaseExpired(lease: Lease, now: UnixMillis): boolean {\n return lease.expiresAt < now;\n },\n\n createLease(ownerId: string, now: UnixMillis): Lease {\n return {\n ownerId,\n expiresAt: now + config.leaseTtlMs,\n };\n },\n\n dispose(): void {\n for (const timer of heartbeatTimers.values()) {\n clearInterval(timer);\n }\n heartbeatTimers.clear();\n },\n };\n}\n\n/**\n * 生成唯一的 owner ID\n * @description 用于标识当前 Service Worker 实例\n */\nexport function generateOwnerId(): string {\n return `sw_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/queue/queue.ts", "content": "/**\n * @fileoverview RunQueue 接口定义\n * @description 定义 Run 队列的管理接口\n */\n\nimport type { JsonObject, UnixMillis } from '../../domain/json';\nimport type { FlowId, NodeId, RunId } from '../../domain/ids';\nimport type { TriggerFireContext } from '../../domain/triggers';\n\n/**\n * RunQueue 配置\n */\nexport interface RunQueueConfig {\n /** 最大并行 Run 数量 */\n maxParallelRuns: number;\n /** 租约 TTL（毫秒） */\n leaseTtlMs: number;\n /** 心跳间隔（毫秒） */\n heartbeatIntervalMs: number;\n}\n\n/**\n * 默认队列配置\n */\nexport const DEFAULT_QUEUE_CONFIG: RunQueueConfig = {\n maxParallelRuns: 3,\n leaseTtlMs: 15_000,\n heartbeatIntervalMs: 5_000,\n};\n\n/**\n * 队列项状态\n */\nexport type QueueItemStatus = 'queued' | 'running' | 'paused';\n\n/**\n * 租约信息\n */\nexport interface Lease {\n /** 持有者 ID */\n ownerId: string;\n /** 过期时间 */\n expiresAt: UnixMillis;\n}\n\n/**\n * RunQueue 队列项\n */\nexport interface RunQueueItem {\n /** Run ID */\n id: RunId;\n /** Flow ID */\n flowId: FlowId;\n /** 状态 */\n status: QueueItemStatus;\n /** 创建时间 */\n createdAt: UnixMillis;\n /** 更新时间 */\n updatedAt: UnixMillis;\n /** 优先级（数字越大优先级越高） */\n priority: number;\n /** 当前尝试次数 */\n attempt: number;\n /** 最大尝试次数 */\n maxAttempts: number;\n /** Tab ID */\n tabId?: number;\n /** 运行参数 */\n args?: JsonObject;\n /** 触发器上下文 */\n trigger?: TriggerFireContext;\n /** 租约信息 */\n lease?: Lease;\n /** 调试配置 */\n debug?: { breakpoints?: NodeId[]; pauseOnStart?: boolean };\n}\n\n/**\n * 入队请求（不含自动生成的字段）\n * - priority 默认为 0\n * - maxAttempts 默认为 1\n */\nexport type EnqueueInput = Omit<\n RunQueueItem,\n 'status' | 'createdAt' | 'updatedAt' | 'attempt' | 'lease' | 'priority' | 'maxAttempts'\n> & {\n id: RunId;\n /** 优先级（数字越大优先级越高，默认 0） */\n priority?: number;\n /** 最大尝试次数（默认 1） */\n maxAttempts?: number;\n};\n\n/**\n * RunQueue 接口\n * @description 管理 Run 的队列和调度\n */\nexport interface RunQueue {\n /**\n * 入队\n * @param input 入队请求\n * @returns 队列项\n */\n enqueue(input: EnqueueInput): Promise;\n\n /**\n * 领取下一个可执行的 Run\n * @param ownerId 领取者 ID\n * @param now 当前时间\n * @returns 队列项或 null\n */\n claimNext(ownerId: string, now: UnixMillis): Promise;\n\n /**\n * 续约心跳\n * @param ownerId 领取者 ID\n * @param now 当前时间\n */\n heartbeat(ownerId: string, now: UnixMillis): Promise;\n\n /**\n * 回收过期租约\n * @description 将 lease.expiresAt < now 的 running/paused 项回收为 queued\n * @param now 当前时间\n * @returns 被回收的 Run ID 列表\n */\n reclaimExpiredLeases(now: UnixMillis): Promise;\n\n /**\n * 恢复孤儿租约（SW 重启后调用）\n * @description\n * - 将孤儿 running 项回收为 queued（status -> queued，租约清除）\n * - 将孤儿 paused 项接管（保持 status=paused，租约 ownerId 更新为新 ownerId）\n * @param ownerId 新的 ownerId（当前 Service Worker 实例）\n * @param now 当前时间\n * @returns 受影响的 runId 列表（含原 ownerId 用于审计）\n */\n recoverOrphanLeases(\n ownerId: string,\n now: UnixMillis,\n ): Promise<{\n requeuedRunning: Array<{ runId: RunId; prevOwnerId?: string }>;\n adoptedPaused: Array<{ runId: RunId; prevOwnerId?: string }>;\n }>;\n\n /**\n * 标记为 running\n */\n markRunning(runId: RunId, ownerId: string, now: UnixMillis): Promise;\n\n /**\n * 标记为 paused\n */\n markPaused(runId: RunId, ownerId: string, now: UnixMillis): Promise;\n\n /**\n * 标记为完成（从队列移除）\n */\n markDone(runId: RunId, now: UnixMillis): Promise;\n\n /**\n * 取消 Run\n */\n cancel(runId: RunId, now: UnixMillis, reason?: string): Promise;\n\n /**\n * 获取队列项\n */\n get(runId: RunId): Promise;\n\n /**\n * 列出队列项\n */\n list(status?: QueueItemStatus): Promise;\n}\n\n/**\n * 创建 NotImplemented 的 RunQueue\n * @description Phase 0 占位实现\n */\nexport function createNotImplementedQueue(): RunQueue {\n const notImplemented = () => {\n throw new Error('RunQueue not implemented');\n };\n\n return {\n enqueue: async () => notImplemented(),\n claimNext: async () => notImplemented(),\n heartbeat: async () => notImplemented(),\n reclaimExpiredLeases: async () => notImplemented(),\n recoverOrphanLeases: async () => notImplemented(),\n markRunning: async () => notImplemented(),\n markPaused: async () => notImplemented(),\n markDone: async () => notImplemented(),\n cancel: async () => notImplemented(),\n get: async () => notImplemented(),\n list: async () => notImplemented(),\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/queue/scheduler.ts", "content": "/**\n * @fileoverview RunQueue scheduler (maxParallelRuns)\n * @description\n * Orchestrates atomic claims from RunQueue and launches execution with an injected executor.\n *\n * Responsibilities:\n * - Enforce maxParallelRuns (per scheduler instance)\n * - Backfill available slots when runs complete\n * - Periodically reclaim expired leases (best-effort)\n * - Start/stop lease heartbeats via LeaseManager\n * - Acquire/release keepalive to prevent MV3 SW termination (P3-05)\n *\n * Non-responsibilities:\n * - Run execution details (Flow loading, tab allocation, etc.) are injected via RunExecutor\n */\n\nimport type { UnixMillis } from '../../domain/json';\nimport type { RunId } from '../../domain/ids';\nimport type { LeaseManager } from './leasing';\nimport type { RunQueue, RunQueueConfig, RunQueueItem } from './queue';\nimport type { KeepaliveController } from '../keepalive/offscreen-keepalive';\n\n// ==================== Types ====================\n\n/**\n * Run executor contract:\n * - Resolve when the run reaches a terminal state (succeeded/failed/canceled).\n * - Throw/reject only for unexpected infrastructure errors.\n */\nexport type RunExecutor = (item: RunQueueItem) => Promise;\n\n/**\n * Scheduler tuning parameters\n */\nexport interface RunSchedulerTuning {\n /**\n * Poll interval for queue consumption fallback.\n * Set to 0 to disable polling (kick-only).\n */\n pollIntervalMs?: number;\n\n /**\n * Minimum interval between lease reclaim scans.\n * Set to 0 to disable periodic reclaim (not recommended in production).\n */\n reclaimIntervalMs?: number;\n}\n\n/**\n * Scheduler dependencies (dependency injection)\n */\nexport interface RunSchedulerDeps {\n queue: Pick;\n leaseManager: Pick;\n keepalive: Pick;\n config: RunQueueConfig;\n ownerId: string;\n execute: RunExecutor;\n now?: () => UnixMillis;\n tuning?: RunSchedulerTuning;\n logger?: Pick;\n}\n\n/**\n * Scheduler state for inspection\n */\nexport interface RunSchedulerState {\n started: boolean;\n ownerId: string;\n maxParallelRuns: number;\n activeRunIds: RunId[];\n}\n\n/**\n * Scheduler interface\n */\nexport interface RunScheduler {\n /** Start the scheduler */\n start(): void;\n /** Stop the scheduler */\n stop(): void;\n /**\n * Trigger a scheduling pass.\n * Safe to call frequently; re-entrancy is coalesced.\n */\n kick(): Promise;\n /** Get current state */\n getState(): RunSchedulerState;\n /** Dispose the scheduler */\n dispose(): void;\n}\n\n// ==================== Constants ====================\n\nconst DEFAULT_POLL_INTERVAL_MS = 500;\n\n// ==================== Helpers ====================\n\nfunction clampNonNegativeInt(value: unknown, fallback: number): number {\n const n = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : fallback;\n return Math.max(0, n);\n}\n\nfunction defaultReclaimIntervalMs(leaseTtlMs: number): number {\n const ttl = clampNonNegativeInt(leaseTtlMs, 0);\n // Reclaim at most every ~TTL/2, but never less than 1s to avoid tight loops.\n return Math.max(1_000, Math.floor(ttl / 2));\n}\n\n// ==================== Factory ====================\n\n/**\n * Create a RunScheduler\n *\n * Scheduling model:\n * - Concurrency is enforced by an in-memory set of active runIds.\n * - Ordering is delegated to RunQueue.claimNext() (priority DESC, createdAt ASC).\n *\n * MV3 Service Worker may be suspended/restarted, so we use a \"kick + polling\" strategy:\n * - kick: Immediate scheduling trigger on enqueue/completion (low latency)\n * - polling: Fallback to ensure queue is consumed even if caller forgets to kick\n */\nexport function createRunScheduler(deps: RunSchedulerDeps): RunScheduler {\n const logger = deps.logger ?? console;\n\n if (!deps.ownerId) {\n throw new Error('ownerId is required');\n }\n\n const now = deps.now ?? (() => Date.now());\n const maxParallelRuns = clampNonNegativeInt(deps.config.maxParallelRuns, 0);\n const pollIntervalMs = clampNonNegativeInt(\n deps.tuning?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,\n DEFAULT_POLL_INTERVAL_MS,\n );\n const reclaimIntervalMs = clampNonNegativeInt(\n deps.tuning?.reclaimIntervalMs ?? defaultReclaimIntervalMs(deps.config.leaseTtlMs),\n defaultReclaimIntervalMs(deps.config.leaseTtlMs),\n );\n\n let started = false;\n let pollTimer: ReturnType | null = null;\n let releaseKeepalive: (() => void) | null = null;\n\n const activeRunIds = new Set();\n\n // Coalesced re-entrancy control for tick()\n let pendingKick = false;\n let pumpPromise: Promise | null = null;\n\n let lastReclaimAt: UnixMillis | null = null;\n\n /**\n * Single scheduling tick:\n * 1. Reclaim expired leases (if interval elapsed)\n * 2. Fill available slots up to maxParallelRuns\n */\n async function tick(): Promise {\n const t = now();\n\n // Best-effort lease reclaim (disabled when reclaimIntervalMs === 0)\n if (reclaimIntervalMs > 0) {\n const shouldReclaim = lastReclaimAt === null || t - lastReclaimAt >= reclaimIntervalMs;\n if (shouldReclaim) {\n lastReclaimAt = t;\n try {\n await deps.leaseManager.reclaimExpiredLeases(t);\n } catch (e) {\n logger.warn('[RunScheduler] reclaimExpiredLeases failed:', e);\n }\n }\n }\n\n // Fill available slots up to maxParallelRuns\n //\n // Note: `stop()` can be called while an async claim is in-flight. Guard the loop\n // with `started` to prevent claiming additional items after stop is requested.\n while (started && activeRunIds.size < maxParallelRuns) {\n let claimed: RunQueueItem | null = null;\n try {\n claimed = await deps.queue.claimNext(deps.ownerId, t);\n } catch (e) {\n logger.error('[RunScheduler] claimNext failed:', e);\n return;\n }\n\n if (!claimed) return;\n\n // Guard against double-launch within the same scheduler instance\n if (activeRunIds.has(claimed.id)) {\n logger.error(\n `[RunScheduler] Invariant violation: run \"${claimed.id}\" was claimed twice in the same scheduler instance`,\n );\n // Best-effort cleanup: avoid a stuck running entry\n void deps.queue\n .markDone(claimed.id, now())\n .catch((err) =>\n logger.warn('[RunScheduler] markDone after duplicate claim failed:', err),\n );\n continue;\n }\n\n activeRunIds.add(claimed.id);\n\n // Capture claimed item for the closure\n const claimedItem = claimed;\n\n const runPromise = Promise.resolve()\n .then(() => deps.execute(claimedItem))\n .catch((e) => {\n // If execution failed unexpectedly, log but still cleanup\n logger.error(`[RunScheduler] execute failed for run \"${claimedItem.id}\":`, e);\n })\n .finally(async () => {\n activeRunIds.delete(claimedItem.id);\n try {\n await deps.queue.markDone(claimedItem.id, now());\n } catch (e) {\n logger.warn(`[RunScheduler] markDone failed for run \"${claimedItem.id}\":`, e);\n }\n\n // Backfill immediately when a slot frees up\n if (started) {\n void kick();\n }\n });\n\n // Ensure no floating promise warnings\n void runPromise;\n }\n }\n\n /**\n * Pump loop: keeps running while pendingKick is set\n */\n async function pump(): Promise {\n try {\n while (started && pendingKick) {\n pendingKick = false;\n try {\n await tick();\n } catch (e) {\n logger.error('[RunScheduler] tick failed:', e);\n }\n }\n } finally {\n pumpPromise = null;\n }\n }\n\n function start(): void {\n if (started) return;\n started = true;\n\n // Acquire keepalive to prevent MV3 SW termination\n try {\n releaseKeepalive = deps.keepalive.acquire('scheduler');\n } catch (e) {\n logger.warn('[RunScheduler] keepalive.acquire failed:', e);\n releaseKeepalive = null;\n }\n\n try {\n deps.leaseManager.startHeartbeat(deps.ownerId);\n } catch (e) {\n logger.warn('[RunScheduler] startHeartbeat failed:', e);\n }\n\n if (pollIntervalMs > 0) {\n pollTimer = setInterval(() => {\n void kick();\n }, pollIntervalMs);\n }\n\n void kick();\n }\n\n function stop(): void {\n if (!started) return;\n\n if (activeRunIds.size > 0) {\n logger.warn(\n `[RunScheduler] stop() called with ${activeRunIds.size} active runs; heartbeats will stop and leases may expire/reclaim concurrently`,\n );\n }\n\n started = false;\n\n if (pollTimer) {\n clearInterval(pollTimer);\n pollTimer = null;\n }\n\n try {\n deps.leaseManager.stopHeartbeat(deps.ownerId);\n } catch (e) {\n logger.warn('[RunScheduler] stopHeartbeat failed:', e);\n }\n\n // Release keepalive\n if (releaseKeepalive) {\n try {\n releaseKeepalive();\n } catch (e) {\n logger.warn('[RunScheduler] keepalive release failed:', e);\n }\n releaseKeepalive = null;\n }\n }\n\n function kick(): Promise {\n if (!started) return Promise.resolve();\n\n pendingKick = true;\n if (!pumpPromise) {\n pumpPromise = pump();\n }\n return pumpPromise;\n }\n\n function getState(): RunSchedulerState {\n return {\n started,\n ownerId: deps.ownerId,\n maxParallelRuns,\n activeRunIds: Array.from(activeRunIds),\n };\n }\n\n function dispose(): void {\n stop();\n activeRunIds.clear();\n }\n\n return { start, stop, kick, getState, dispose };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/recovery/index.ts", "content": "/**\n * @fileoverview Recovery module exports\n * @description 崩溃恢复模块导出\n */\n\nexport * from './recovery-coordinator';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/recovery/recovery-coordinator.ts", "content": "/**\n * @fileoverview 崩溃恢复协调器 (P3-06)\n * @description\n * MV3 Service Worker 可能随时被终止。此协调器在 SW 启动时协调队列状态和 Run 记录，\n * 使中断的 Run 能够被恢复执行。\n *\n * 恢复策略：\n * - 孤儿 running 项：回收为 queued，等待重新调度（从头重跑）\n * - 孤儿 paused 项：接管 lease，保持 paused 状态\n * - 已终态 Run 的队列残留：清理\n *\n * 调用时机：\n * - 必须在 scheduler.start() 之前调用\n * - 通常在 SW 启动时调用一次\n */\n\nimport type { UnixMillis } from '../../domain/json';\nimport type { RunId } from '../../domain/ids';\nimport { isTerminalStatus, type RunStatus } from '../../domain/events';\nimport type { StoragePort } from '../storage/storage-port';\nimport type { EventsBus } from '../transport/events-bus';\n\n// ==================== Types ====================\n\n/**\n * 恢复结果\n */\nexport interface RecoveryResult {\n /** 被回收为 queued 的 running Run ID */\n requeuedRunning: RunId[];\n /** 被接管的 paused Run ID */\n adoptedPaused: RunId[];\n /** 被清理的已终态 Run ID */\n cleanedTerminal: RunId[];\n}\n\n/**\n * 恢复协调器依赖\n */\nexport interface RecoveryCoordinatorDeps {\n /** 存储层 */\n storage: StoragePort;\n /** 事件总线 */\n events: EventsBus;\n /** 当前 Service Worker 的 ownerId */\n ownerId: string;\n /** 时间源 */\n now: () => UnixMillis;\n /** 日志器 */\n logger?: Pick;\n}\n\n// ==================== Main Function ====================\n\n/**\n * 执行崩溃恢复\n * @description\n * 在 SW 启动时调用，协调队列状态和 Run 记录。\n *\n * 执行顺序：\n * 1. 预清理：检查队列中的所有项，清理已终态或无对应 RunRecord 的残留\n * 2. 恢复孤儿租约：回收 running，接管 paused\n * 3. 同步 RunRecord 状态：确保 RunRecord 与队列状态一致\n * 4. 发送恢复事件：为 requeued running 项发送 run.recovered 事件\n */\nexport async function recoverFromCrash(deps: RecoveryCoordinatorDeps): Promise {\n const logger = deps.logger ?? console;\n\n if (!deps.ownerId) {\n throw new Error('ownerId is required');\n }\n\n const now = deps.now();\n\n // 设计理由：恢复过程必须\"先清理后接管/回收\"，否则可能把已经终态的 Run 重新排队执行\n const cleanedTerminalSet = new Set();\n\n // ==================== Step 1: 预清理 ====================\n // 检查队列中的所有项，清理已终态或无对应 RunRecord 的残留\n try {\n const items = await deps.storage.queue.list();\n for (const item of items) {\n const runId = item.id;\n const run = await deps.storage.runs.get(runId);\n\n // 防御性清理：无 RunRecord 的队列项无法执行\n if (!run) {\n try {\n await deps.storage.queue.markDone(runId, now);\n cleanedTerminalSet.add(runId);\n logger.debug(`[Recovery] Cleaned orphan queue item without RunRecord: ${runId}`);\n } catch (e) {\n logger.warn('[Recovery] markDone for missing RunRecord failed:', runId, e);\n }\n continue;\n }\n\n // 清理已终态的 Run（SW 可能在 runner 完成后、scheduler markDone 前崩溃）\n if (isTerminalStatus(run.status)) {\n try {\n await deps.storage.queue.markDone(runId, now);\n cleanedTerminalSet.add(runId);\n logger.debug(`[Recovery] Cleaned terminal queue item: ${runId} (status=${run.status})`);\n } catch (e) {\n logger.warn('[Recovery] markDone for terminal run failed:', runId, e);\n }\n }\n }\n } catch (e) {\n logger.warn('[Recovery] Pre-clean failed:', e);\n }\n\n // ==================== Step 2: 恢复孤儿租约 ====================\n // Best-effort：即使失败也不应该阻止启动\n let requeuedRunning: Array<{ runId: RunId; prevOwnerId?: string }> = [];\n let adoptedPaused: Array<{ runId: RunId; prevOwnerId?: string }> = [];\n try {\n const result = await deps.storage.queue.recoverOrphanLeases(deps.ownerId, now);\n requeuedRunning = result.requeuedRunning;\n adoptedPaused = result.adoptedPaused;\n } catch (e) {\n logger.error('[Recovery] recoverOrphanLeases failed:', e);\n // 继续执行，不阻止启动\n }\n\n // ==================== Step 3: 同步 RunRecord 状态 ====================\n const requeuedRunningIds: RunId[] = [];\n for (const entry of requeuedRunning) {\n const runId = entry.runId;\n requeuedRunningIds.push(runId);\n\n // 跳过在 Step 1 中已清理的项\n if (cleanedTerminalSet.has(runId)) {\n continue;\n }\n\n try {\n const run = await deps.storage.runs.get(runId);\n if (!run) {\n // RunRecord 不存在，清理队列项（防御性）\n try {\n await deps.storage.queue.markDone(runId, now);\n cleanedTerminalSet.add(runId);\n } catch (markDoneErr) {\n logger.warn(\n '[Recovery] markDone for missing RunRecord in Step3 failed:',\n runId,\n markDoneErr,\n );\n }\n continue;\n }\n\n // 跳过已终态的 Run（可能在恢复过程中被其他逻辑更新）\n // 同时清理队列项，防止残留\n if (isTerminalStatus(run.status)) {\n try {\n await deps.storage.queue.markDone(runId, now);\n cleanedTerminalSet.add(runId);\n logger.debug(\n `[Recovery] Cleaned terminal queue item in Step3: ${runId} (status=${run.status})`,\n );\n } catch (markDoneErr) {\n logger.warn('[Recovery] markDone for terminal run in Step3 failed:', runId, markDoneErr);\n }\n continue;\n }\n\n // 更新 RunRecord 状态为 queued\n await deps.storage.runs.patch(runId, { status: 'queued', updatedAt: now });\n\n // 发送恢复事件（best-effort，失败不影响恢复流程）\n try {\n const fromStatus: 'running' | 'paused' = run.status === 'paused' ? 'paused' : 'running';\n await deps.events.append({\n runId,\n type: 'run.recovered',\n reason: 'sw_restart',\n fromStatus,\n toStatus: 'queued',\n prevOwnerId: entry.prevOwnerId,\n ts: now,\n });\n logger.info(`[Recovery] Requeued orphan running run: ${runId} (from=${fromStatus})`);\n } catch (eventErr) {\n logger.warn('[Recovery] Failed to emit run.recovered event:', runId, eventErr);\n // 继续执行，不影响恢复流程\n }\n } catch (e) {\n logger.warn('[Recovery] Reconcile requeued running failed:', runId, e);\n }\n }\n\n // ==================== Step 4: 同步 adopted paused 的 RunRecord ====================\n const adoptedPausedIds: RunId[] = [];\n for (const entry of adoptedPaused) {\n const runId = entry.runId;\n adoptedPausedIds.push(runId);\n\n // 跳过在 Step 1 中已清理的项\n if (cleanedTerminalSet.has(runId)) {\n continue;\n }\n\n try {\n const run = await deps.storage.runs.get(runId);\n if (!run) {\n // RunRecord 不存在，清理队列项（防御性）\n try {\n await deps.storage.queue.markDone(runId, now);\n cleanedTerminalSet.add(runId);\n } catch (markDoneErr) {\n logger.warn(\n '[Recovery] markDone for missing RunRecord in Step4 failed:',\n runId,\n markDoneErr,\n );\n }\n continue;\n }\n\n // 跳过已终态的 Run，同时清理队列项\n if (isTerminalStatus(run.status)) {\n try {\n await deps.storage.queue.markDone(runId, now);\n cleanedTerminalSet.add(runId);\n logger.debug(\n `[Recovery] Cleaned terminal queue item in Step4: ${runId} (status=${run.status})`,\n );\n } catch (markDoneErr) {\n logger.warn('[Recovery] markDone for terminal run in Step4 failed:', runId, markDoneErr);\n }\n continue;\n }\n\n // 如果 RunRecord 状态不是 paused，同步更新\n if (run.status !== 'paused') {\n await deps.storage.runs.patch(runId, { status: 'paused' as RunStatus, updatedAt: now });\n }\n\n logger.info(`[Recovery] Adopted orphan paused run: ${runId}`);\n } catch (e) {\n logger.warn('[Recovery] Reconcile adopted paused failed:', runId, e);\n }\n }\n\n const result: RecoveryResult = {\n requeuedRunning: requeuedRunningIds,\n adoptedPaused: adoptedPausedIds,\n cleanedTerminal: Array.from(cleanedTerminalSet),\n };\n\n logger.info('[Recovery] Complete:', {\n requeuedRunning: result.requeuedRunning.length,\n adoptedPaused: result.adoptedPaused.length,\n cleanedTerminal: result.cleanedTerminal.length,\n });\n\n return result;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/storage/index.ts", "content": "/**\n * @fileoverview Engine Storage 模块导出入口\n */\n\nexport * from './storage-port';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/storage/storage-port.ts", "content": "/**\n * @fileoverview StoragePort 接口定义\n * @description 定义 Storage 层的抽象接口，用于依赖注入\n */\n\nimport type { FlowId, RunId, TriggerId } from '../../domain/ids';\nimport type { FlowV3 } from '../../domain/flow';\nimport type { RunEvent, RunEventInput, RunRecordV3 } from '../../domain/events';\nimport type { PersistentVarRecord, PersistentVariableName } from '../../domain/variables';\nimport type { TriggerSpec } from '../../domain/triggers';\nimport type { RunQueue } from '../queue/queue';\n\n/**\n * FlowsStore 接口\n */\nexport interface FlowsStore {\n /** 列出所有 Flow */\n list(): Promise;\n /** 获取单个 Flow */\n get(id: FlowId): Promise;\n /** 保存 Flow */\n save(flow: FlowV3): Promise;\n /** 删除 Flow */\n delete(id: FlowId): Promise;\n}\n\n/**\n * RunsStore 接口\n */\nexport interface RunsStore {\n /** 列出所有 Run 记录 */\n list(): Promise;\n /** 获取单个 Run 记录 */\n get(id: RunId): Promise;\n /** 保存 Run 记录 */\n save(record: RunRecordV3): Promise;\n /** 部分更新 Run 记录 */\n patch(id: RunId, patch: Partial): Promise;\n}\n\n/**\n * EventsStore 接口\n * @description seq 分配必须由 append() 内部原子完成\n */\nexport interface EventsStore {\n /**\n * 追加事件并原子分配 seq\n * @description 在单个事务中：读取 RunRecordV3.nextSeq -> 写入事件 -> 递增 nextSeq\n * @param event 事件输入（不含 seq）\n * @returns 完整事件（含分配的 seq 和 ts）\n */\n append(event: RunEventInput): Promise;\n\n /**\n * 列出事件\n * @param runId Run ID\n * @param opts 查询选项\n */\n list(runId: RunId, opts?: { fromSeq?: number; limit?: number }): Promise;\n}\n\n/**\n * PersistentVarsStore 接口\n */\nexport interface PersistentVarsStore {\n /** 获取持久化变量 */\n get(key: PersistentVariableName): Promise;\n /** 设置持久化变量 */\n set(\n key: PersistentVariableName,\n value: PersistentVarRecord['value'],\n ): Promise;\n /** 删除持久化变量 */\n delete(key: PersistentVariableName): Promise;\n /** 列出持久化变量 */\n list(prefix?: PersistentVariableName): Promise;\n}\n\n/**\n * TriggersStore 接口\n */\nexport interface TriggersStore {\n /** 列出所有触发器 */\n list(): Promise;\n /** 获取单个触发器 */\n get(id: TriggerId): Promise;\n /** 保存触发器 */\n save(spec: TriggerSpec): Promise;\n /** 删除触发器 */\n delete(id: TriggerId): Promise;\n}\n\n/**\n * StoragePort 接口\n * @description 聚合所有存储接口，用于依赖注入\n */\nexport interface StoragePort {\n /** Flows 存储 */\n flows: FlowsStore;\n /** Runs 存储 */\n runs: RunsStore;\n /** Events 存储 */\n events: EventsStore;\n /** Queue 存储 */\n queue: RunQueue;\n /** 持久化变量存储 */\n persistentVars: PersistentVarsStore;\n /** 触发器存储 */\n triggers: TriggersStore;\n}\n\n/**\n * 创建 NotImplemented 的 Store\n * @description 避免 Proxy 生成 'then' 导致 thenable 行为\n */\nfunction createNotImplementedStore(name: string): T {\n const target = {} as T;\n return new Proxy(target, {\n get(_, prop) {\n // Avoid thenable behavior by returning undefined for 'then'\n if (prop === 'then') {\n return undefined;\n }\n return async () => {\n throw new Error(`${name}.${String(prop)} not implemented`);\n };\n },\n });\n}\n\n/**\n * 创建 NotImplemented 的 StoragePort\n * @description Phase 0 占位实现\n */\nexport function createNotImplementedStoragePort(): StoragePort {\n return {\n flows: createNotImplementedStore('FlowsStore'),\n runs: createNotImplementedStore('RunsStore'),\n events: createNotImplementedStore('EventsStore'),\n queue: createNotImplementedStore('RunQueue'),\n persistentVars: createNotImplementedStore('PersistentVarsStore'),\n triggers: createNotImplementedStore('TriggersStore'),\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/transport/events-bus.ts", "content": "/**\n * @fileoverview EventsBus Interface and Implementation\n * @description Event subscription, publishing, and persistence\n */\n\nimport type { RunId } from '../../domain/ids';\nimport type { RunEvent, RunEventInput, Unsubscribe } from '../../domain/events';\nimport type { EventsStore } from '../storage/storage-port';\n\n/**\n * Event query parameters\n */\nexport interface EventsQuery {\n /** Run ID */\n runId: RunId;\n /** Starting sequence number (inclusive) */\n fromSeq?: number;\n /** Maximum number of results */\n limit?: number;\n}\n\n/**\n * Subscription filter\n */\nexport interface EventsFilter {\n /** Only receive events for this Run */\n runId?: RunId;\n}\n\n/**\n * EventsBus Interface\n * @description Responsible for event subscription, publishing, and persistence\n */\nexport interface EventsBus {\n /**\n * Subscribe to events\n * @param listener Event listener\n * @param filter Optional filter\n * @returns Unsubscribe function\n */\n subscribe(listener: (event: RunEvent) => void, filter?: EventsFilter): Unsubscribe;\n\n /**\n * Append event\n * @description Delegates to EventsStore for atomic seq allocation, then broadcasts\n * @param event Event input (without seq)\n * @returns Complete event (with seq and ts)\n */\n append(event: RunEventInput): Promise;\n\n /**\n * Query historical events\n * @param query Query parameters\n * @returns Events sorted by seq ascending\n */\n list(query: EventsQuery): Promise;\n}\n\n/**\n * Create NotImplemented EventsBus\n * @description Phase 0 placeholder\n */\nexport function createNotImplementedEventsBus(): EventsBus {\n const notImplemented = () => {\n throw new Error('EventsBus not implemented');\n };\n\n return {\n subscribe: () => {\n notImplemented();\n return () => {};\n },\n append: async () => notImplemented(),\n list: async () => notImplemented(),\n };\n}\n\n/**\n * Listener entry for subscription management\n */\ninterface ListenerEntry {\n listener: (event: RunEvent) => void;\n filter?: EventsFilter;\n}\n\n/**\n * Storage-backed EventsBus Implementation\n * @description\n * - seq allocation is done by EventsStore.append() (atomic with RunRecordV3.nextSeq)\n * - broadcast happens only after append resolves (i.e. after commit)\n */\nexport class StorageBackedEventsBus implements EventsBus {\n private listeners = new Set();\n\n constructor(private readonly store: EventsStore) {}\n\n subscribe(listener: (event: RunEvent) => void, filter?: EventsFilter): Unsubscribe {\n const entry: ListenerEntry = { listener, filter };\n this.listeners.add(entry);\n return () => {\n this.listeners.delete(entry);\n };\n }\n\n async append(input: RunEventInput): Promise {\n // Delegate to storage for atomic seq allocation\n const event = await this.store.append(input);\n\n // Broadcast after successful commit\n this.broadcast(event);\n\n return event;\n }\n\n async list(query: EventsQuery): Promise {\n return this.store.list(query.runId, {\n fromSeq: query.fromSeq,\n limit: query.limit,\n });\n }\n\n /**\n * Broadcast event to all matching listeners\n */\n private broadcast(event: RunEvent): void {\n const { runId } = event;\n for (const { listener, filter } of this.listeners) {\n if (!filter || !filter.runId || filter.runId === runId) {\n try {\n listener(event);\n } catch (error) {\n console.error('[StorageBackedEventsBus] Listener error:', error);\n }\n }\n }\n }\n}\n\n/**\n * In-memory EventsBus for testing\n * @description Uses internal seq counter, NOT suitable for production\n * @deprecated Use StorageBackedEventsBus with mock EventsStore for testing\n */\nexport class InMemoryEventsBus implements EventsBus {\n private events = new Map();\n private seqCounters = new Map();\n private listeners = new Set();\n\n subscribe(listener: (event: RunEvent) => void, filter?: EventsFilter): Unsubscribe {\n const entry: ListenerEntry = { listener, filter };\n this.listeners.add(entry);\n return () => {\n this.listeners.delete(entry);\n };\n }\n\n async append(input: RunEventInput): Promise {\n const { runId } = input;\n\n // Allocate seq (NOT atomic, for testing only)\n const currentSeq = this.seqCounters.get(runId) ?? 0;\n const seq = currentSeq + 1;\n this.seqCounters.set(runId, seq);\n\n // Create complete event\n const event: RunEvent = {\n ...input,\n seq,\n ts: input.ts ?? Date.now(),\n } as RunEvent;\n\n // Store\n const runEvents = this.events.get(runId) ?? [];\n runEvents.push(event);\n this.events.set(runId, runEvents);\n\n // Broadcast\n for (const { listener, filter } of this.listeners) {\n if (!filter || !filter.runId || filter.runId === runId) {\n try {\n listener(event);\n } catch (error) {\n console.error('[InMemoryEventsBus] Listener error:', error);\n }\n }\n }\n\n return event;\n }\n\n async list(query: EventsQuery): Promise {\n const runEvents = this.events.get(query.runId) ?? [];\n\n let result = runEvents;\n\n if (query.fromSeq !== undefined) {\n result = result.filter((e) => e.seq >= query.fromSeq!);\n }\n\n if (query.limit !== undefined) {\n result = result.slice(0, query.limit);\n }\n\n return result;\n }\n\n /**\n * Clear all data (for testing)\n */\n clear(): void {\n this.events.clear();\n this.seqCounters.clear();\n this.listeners.clear();\n }\n\n /**\n * Get current seq for a run (for testing)\n */\n getSeq(runId: RunId): number {\n return this.seqCounters.get(runId) ?? 0;\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/transport/index.ts", "content": "/**\n * @fileoverview Transport 模块导出入口\n */\n\nexport * from './rpc';\nexport * from './rpc-server';\nexport * from './events-bus';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/transport/rpc-server.ts", "content": "/**\n * @fileoverview RPC Server Implementation\n * @description Handles RPC requests from UI via chrome.runtime.Port\n */\n\nimport type { ISODateTimeString, JsonObject, JsonValue } from '../../domain/json';\nimport type { EdgeId, FlowId, NodeId, RunId, TriggerId } from '../../domain/ids';\nimport type { DebuggerCommand } from '../../domain/debug';\nimport type { RunEvent } from '../../domain/events';\nimport type { FlowV3, NodeV3, EdgeV3 } from '../../domain/flow';\nimport { FLOW_SCHEMA_VERSION as CURRENT_FLOW_SCHEMA_VERSION } from '../../domain/flow';\nimport type { VariableDefinition } from '../../domain/variables';\nimport type { TriggerKind, TriggerSpec } from '../../domain/triggers';\nimport type { StoragePort } from '../storage/storage-port';\nimport type { EventsBus } from './events-bus';\nimport type { DebugController, RunnerRegistry } from '../kernel/debug-controller';\nimport type { RunScheduler } from '../queue/scheduler';\nimport type { QueueItemStatus } from '../queue/queue';\nimport { enqueueRun } from '../queue/enqueue-run';\nimport type { TriggerManager } from '../triggers/trigger-manager';\nimport {\n RR_V3_PORT_NAME,\n isRpcRequest,\n createRpcResponseOk,\n createRpcResponseErr,\n createRpcEventMessage,\n type RpcRequest,\n} from './rpc';\n\n/**\n * RPC Server 配置\n */\nexport interface RpcServerConfig {\n storage: StoragePort;\n events: EventsBus;\n debugController?: DebugController;\n runners?: RunnerRegistry;\n scheduler?: RunScheduler;\n triggerManager?: TriggerManager;\n /** ID 生成器（用于测试注入） */\n generateRunId?: () => RunId;\n /** 时间源（用于测试注入） */\n now?: () => number;\n}\n\n/**\n * 活跃的 Port 连接\n */\ninterface PortConnection {\n port: chrome.runtime.Port;\n subscriptions: Set; // null means subscribe to all\n}\n\n/**\n * 默认 RunId 生成器\n */\nfunction defaultGenerateRunId(): RunId {\n return `run_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n}\n\n/**\n * RPC Server\n * @description 处理来自 UI 的 RPC 请求\n */\nexport class RpcServer {\n private readonly storage: StoragePort;\n private readonly events: EventsBus;\n private readonly debugController?: DebugController;\n private readonly runners?: RunnerRegistry;\n private readonly scheduler?: RunScheduler;\n private readonly triggerManager?: TriggerManager;\n private readonly generateRunId: () => RunId;\n private readonly now: () => number;\n private readonly connections = new Map();\n private eventUnsubscribe: (() => void) | null = null;\n\n constructor(config: RpcServerConfig) {\n this.storage = config.storage;\n this.events = config.events;\n this.debugController = config.debugController;\n this.runners = config.runners;\n this.scheduler = config.scheduler;\n this.triggerManager = config.triggerManager;\n this.generateRunId = config.generateRunId ?? defaultGenerateRunId;\n this.now = config.now ?? Date.now;\n }\n\n /**\n * 启动 RPC Server\n */\n start(): void {\n chrome.runtime.onConnect.addListener(this.handleConnect);\n\n // Subscribe to all events and broadcast to connected ports\n this.eventUnsubscribe = this.events.subscribe((event) => {\n this.broadcastEvent(event);\n });\n }\n\n /**\n * 停止 RPC Server\n */\n stop(): void {\n chrome.runtime.onConnect.removeListener(this.handleConnect);\n\n if (this.eventUnsubscribe) {\n this.eventUnsubscribe();\n this.eventUnsubscribe = null;\n }\n\n // Disconnect all ports\n for (const conn of this.connections.values()) {\n conn.port.disconnect();\n }\n this.connections.clear();\n }\n\n /**\n * 处理新连接\n */\n private handleConnect = (port: chrome.runtime.Port): void => {\n if (port.name !== RR_V3_PORT_NAME) return;\n\n const connId = `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n const connection: PortConnection = {\n port,\n subscriptions: new Set(),\n };\n\n this.connections.set(connId, connection);\n\n port.onMessage.addListener((msg) => this.handleMessage(connId, msg));\n port.onDisconnect.addListener(() => this.handleDisconnect(connId));\n };\n\n /**\n * 处理消息\n */\n private handleMessage = async (connId: string, msg: unknown): Promise => {\n if (!isRpcRequest(msg)) return;\n\n const conn = this.connections.get(connId);\n if (!conn) return;\n\n try {\n const result = await this.handleRequest(msg, conn);\n conn.port.postMessage(createRpcResponseOk(msg.requestId, result));\n } catch (e) {\n const error = e instanceof Error ? e.message : String(e);\n conn.port.postMessage(createRpcResponseErr(msg.requestId, error));\n }\n };\n\n /**\n * 处理断开连接\n */\n private handleDisconnect = (connId: string): void => {\n this.connections.delete(connId);\n };\n\n /**\n * 广播事件\n */\n private broadcastEvent(event: RunEvent): void {\n const message = createRpcEventMessage(event);\n\n for (const conn of this.connections.values()) {\n // Check if this connection subscribed to this event\n const subs = conn.subscriptions;\n if (subs.size === 0) continue; // No subscriptions\n if (subs.has(null) || subs.has(event.runId)) {\n try {\n conn.port.postMessage(message);\n } catch {\n // Port may be disconnected\n }\n }\n }\n }\n\n // ===== Queue Management Handlers =====\n\n /**\n * 处理 enqueueRun 请求\n * @description 委托给共享的 enqueueRun 服务\n */\n private async handleEnqueueRun(params: JsonObject | undefined): Promise {\n const result = await enqueueRun(\n {\n storage: this.storage,\n events: this.events,\n scheduler: this.scheduler,\n generateRunId: this.generateRunId,\n now: this.now,\n },\n {\n flowId: params?.flowId as FlowId,\n startNodeId: params?.startNodeId as NodeId | undefined,\n priority: params?.priority as number | undefined,\n maxAttempts: params?.maxAttempts as number | undefined,\n args: params?.args as JsonObject | undefined,\n debug: params?.debug as { breakpoints?: string[]; pauseOnStart?: boolean } | undefined,\n },\n );\n\n return result as unknown as JsonValue;\n }\n\n /**\n * 处理 listQueue 请求\n * @description 列出队列项，按 priority DESC + createdAt ASC 排序\n */\n private async handleListQueue(params: JsonObject | undefined): Promise {\n const rawStatus = params?.status;\n\n // 校验 status 白名单\n let status: QueueItemStatus | undefined;\n if (rawStatus !== undefined) {\n if (rawStatus !== 'queued' && rawStatus !== 'running' && rawStatus !== 'paused') {\n throw new Error('status must be one of: queued, running, paused');\n }\n status = rawStatus;\n }\n\n const items = await this.storage.queue.list(status);\n\n // 按 priority DESC + createdAt ASC 排序\n items.sort((a, b) => {\n if (a.priority !== b.priority) {\n return b.priority - a.priority; // DESC\n }\n return a.createdAt - b.createdAt; // ASC (FIFO)\n });\n\n return items as unknown as JsonValue;\n }\n\n /**\n * 处理 cancelQueueItem 请求\n * @description 取消排队中的队列项，更新 Run 状态，发布 run.canceled 事件\n * @note 仅允许取消 status=queued 的项；running/paused 需使用 rr_v3.cancelRun\n */\n private async handleCancelQueueItem(params: JsonObject | undefined): Promise {\n const runId = params?.runId as RunId | undefined;\n if (!runId) throw new Error('runId is required');\n\n const reason = params?.reason as string | undefined;\n const now = this.now();\n\n // 1. 检查队列项存在\n const queueItem = await this.storage.queue.get(runId);\n if (!queueItem) {\n throw new Error(`Queue item \"${runId}\" not found`);\n }\n\n // 2. 仅允许取消 queued 状态（running/paused 需使用 rr_v3.cancelRun）\n if (queueItem.status !== 'queued') {\n throw new Error(\n `Cannot cancel queue item \"${runId}\" with status \"${queueItem.status}\"; use rr_v3.cancelRun for running/paused runs`,\n );\n }\n\n // 3. 从队列移除\n await this.storage.queue.cancel(runId, now, reason);\n\n // 4. 更新 Run 记录状态\n await this.storage.runs.patch(runId, {\n status: 'canceled',\n updatedAt: now,\n finishedAt: now,\n });\n\n // 5. 发布 run.canceled 事件（通过 EventsBus 以确保广播）\n await this.events.append({\n runId,\n type: 'run.canceled',\n reason,\n });\n\n return { ok: true, runId };\n }\n\n /**\n * 处理 RPC 请求\n */\n private async handleRequest(request: RpcRequest, conn: PortConnection): Promise {\n const { method, params } = request;\n\n switch (method) {\n case 'rr_v3.listRuns': {\n const runs = await this.storage.runs.list();\n return runs as unknown as JsonValue;\n }\n\n case 'rr_v3.getRun': {\n const runId = params?.runId as RunId | undefined;\n if (!runId) throw new Error('runId is required');\n const run = await this.storage.runs.get(runId);\n return run as unknown as JsonValue;\n }\n\n case 'rr_v3.getEvents': {\n const runId = params?.runId as RunId | undefined;\n if (!runId) throw new Error('runId is required');\n const fromSeq = params?.fromSeq as number | undefined;\n const limit = params?.limit as number | undefined;\n const events = await this.storage.events.list(runId, { fromSeq, limit });\n return events as unknown as JsonValue;\n }\n\n case 'rr_v3.getFlow': {\n const flowId = params?.flowId as FlowId | undefined;\n if (!flowId) throw new Error('flowId is required');\n const flow = await this.storage.flows.get(flowId);\n return flow as unknown as JsonValue;\n }\n\n case 'rr_v3.listFlows': {\n const flows = await this.storage.flows.list();\n return flows as unknown as JsonValue;\n }\n\n case 'rr_v3.saveFlow': {\n return this.handleSaveFlow(params);\n }\n\n case 'rr_v3.deleteFlow': {\n return this.handleDeleteFlow(params);\n }\n\n // ===== Trigger APIs =====\n\n case 'rr_v3.createTrigger':\n return this.handleCreateTrigger(params);\n\n case 'rr_v3.updateTrigger':\n return this.handleUpdateTrigger(params);\n\n case 'rr_v3.deleteTrigger':\n return this.handleDeleteTrigger(params);\n\n case 'rr_v3.getTrigger':\n return this.handleGetTrigger(params);\n\n case 'rr_v3.listTriggers':\n return this.handleListTriggers(params);\n\n case 'rr_v3.enableTrigger':\n return this.handleEnableTrigger(params);\n\n case 'rr_v3.disableTrigger':\n return this.handleDisableTrigger(params);\n\n case 'rr_v3.fireTrigger':\n return this.handleFireTrigger(params);\n\n // ===== Queue Management APIs =====\n\n case 'rr_v3.enqueueRun': {\n return this.handleEnqueueRun(params);\n }\n\n case 'rr_v3.listQueue': {\n return this.handleListQueue(params);\n }\n\n case 'rr_v3.cancelQueueItem': {\n return this.handleCancelQueueItem(params);\n }\n\n case 'rr_v3.subscribe': {\n const runId = (params?.runId as RunId | undefined) ?? null;\n conn.subscriptions.add(runId);\n return { subscribed: true, runId };\n }\n\n case 'rr_v3.unsubscribe': {\n const runId = (params?.runId as RunId | undefined) ?? null;\n conn.subscriptions.delete(runId);\n return { unsubscribed: true, runId };\n }\n\n // Debug method - route to DebugController\n case 'rr_v3.debug': {\n if (!this.debugController) {\n throw new Error('DebugController not configured');\n }\n const cmd = params as unknown as DebuggerCommand;\n if (!cmd || !cmd.type) {\n throw new Error('Invalid debug command');\n }\n const response = await this.debugController.handle(cmd);\n return response as unknown as JsonValue;\n }\n\n // Control methods\n case 'rr_v3.startRun':\n // startRun is essentially enqueueRun - the run starts when claimed by scheduler\n return this.handleEnqueueRun(params);\n\n case 'rr_v3.pauseRun':\n return this.handlePauseRun(params);\n\n case 'rr_v3.resumeRun':\n return this.handleResumeRun(params);\n\n case 'rr_v3.cancelRun':\n return this.handleCancelRun(params);\n\n default:\n throw new Error(`Unknown method: ${method}`);\n }\n }\n\n // ===== Flow Management Handlers =====\n\n /**\n * 处理 saveFlow 请求\n * @description 保存或更新 Flow，执行完整的结构验证\n */\n private async handleSaveFlow(params: JsonObject | undefined): Promise {\n const rawFlow = params?.flow;\n if (!rawFlow || typeof rawFlow !== 'object' || Array.isArray(rawFlow)) {\n throw new Error('flow is required');\n }\n\n // 检查是否为更新现有 flow（使用 trim 后的 ID 查询）\n const rawId = (rawFlow as JsonObject).id;\n let existingFlow: FlowV3 | null = null;\n if (typeof rawId === 'string' && rawId.trim()) {\n existingFlow = await this.storage.flows.get(rawId.trim() as FlowId);\n }\n\n // 规范化 flow，传入 existingFlow 以继承 createdAt\n const flow = this.normalizeFlowSpec(rawFlow, existingFlow);\n\n // 保存到存储（存储层会执行二次验证）\n await this.storage.flows.save(flow);\n\n return flow as unknown as JsonValue;\n }\n\n /**\n * 处理 deleteFlow 请求\n * @description 删除 Flow，先检查是否有关联的 Trigger 和 queued runs\n */\n private async handleDeleteFlow(params: JsonObject | undefined): Promise {\n const flowId = params?.flowId as FlowId | undefined;\n if (!flowId) throw new Error('flowId is required');\n\n // 检查 Flow 是否存在\n const existing = await this.storage.flows.get(flowId);\n if (!existing) {\n throw new Error(`Flow \"${flowId}\" not found`);\n }\n\n // 检查是否有关联的 Trigger\n const triggers = await this.storage.triggers.list();\n const linkedTriggers = triggers.filter((t) => t.flowId === flowId);\n if (linkedTriggers.length > 0) {\n const triggerIds = linkedTriggers.map((t) => t.id).join(', ');\n throw new Error(\n `Cannot delete flow \"${flowId}\": it has ${linkedTriggers.length} linked trigger(s): ${triggerIds}. ` +\n `Delete the trigger(s) first.`,\n );\n }\n\n // 检查是否有 queued runs（未执行的 runs 删除后会失败）\n const queuedItems = await this.storage.queue.list('queued');\n const linkedQueuedRuns = queuedItems.filter((item) => item.flowId === flowId);\n if (linkedQueuedRuns.length > 0) {\n const runIds = linkedQueuedRuns.map((r) => r.id).join(', ');\n throw new Error(\n `Cannot delete flow \"${flowId}\": it has ${linkedQueuedRuns.length} queued run(s): ${runIds}. ` +\n `Cancel the run(s) first or wait for them to complete.`,\n );\n }\n\n // 删除 Flow\n await this.storage.flows.delete(flowId);\n\n return { ok: true, flowId };\n }\n\n /**\n * 规范化 FlowV3 输入\n * @description 验证并转换输入为完整的 FlowV3 结构\n * @param value 原始输入\n * @param existingFlow 已存在的 flow（用于继承 createdAt）\n */\n private normalizeFlowSpec(value: unknown, existingFlow: FlowV3 | null = null): FlowV3 {\n if (!value || typeof value !== 'object' || Array.isArray(value)) {\n throw new Error('flow is required');\n }\n const raw = value as JsonObject;\n\n // id 校验与生成\n let id: FlowId;\n if (raw.id === undefined || raw.id === null) {\n id = `flow_${Date.now()}_${Math.random().toString(36).slice(2, 8)}` as FlowId;\n } else {\n if (typeof raw.id !== 'string' || !raw.id.trim()) {\n throw new Error('flow.id must be a non-empty string');\n }\n id = raw.id.trim() as FlowId;\n }\n\n // name 校验\n if (!raw.name || typeof raw.name !== 'string' || !raw.name.trim()) {\n throw new Error('flow.name is required');\n }\n const name = raw.name.trim();\n\n // description 校验\n let description: string | undefined;\n if (raw.description !== undefined && raw.description !== null) {\n if (typeof raw.description !== 'string') {\n throw new Error('flow.description must be a string');\n }\n description = raw.description;\n }\n\n // entryNodeId 校验\n if (!raw.entryNodeId || typeof raw.entryNodeId !== 'string' || !raw.entryNodeId.trim()) {\n throw new Error('flow.entryNodeId is required');\n }\n const entryNodeId = raw.entryNodeId.trim() as NodeId;\n\n // nodes 校验\n if (!Array.isArray(raw.nodes)) {\n throw new Error('flow.nodes must be an array');\n }\n const nodes = raw.nodes.map((n, i) => this.normalizeNode(n, i));\n\n // 验证 node ID 唯一性\n const nodeIdSet = new Set();\n for (const node of nodes) {\n if (nodeIdSet.has(node.id)) {\n throw new Error(`Duplicate node ID: \"${node.id}\"`);\n }\n nodeIdSet.add(node.id);\n }\n\n // edges 校验\n let edges: EdgeV3[] = [];\n if (raw.edges !== undefined && raw.edges !== null) {\n if (!Array.isArray(raw.edges)) {\n throw new Error('flow.edges must be an array');\n }\n edges = raw.edges.map((e, i) => this.normalizeEdge(e, i));\n }\n\n // 验证 edge ID 唯一性\n const edgeIdSet = new Set();\n for (const edge of edges) {\n if (edgeIdSet.has(edge.id)) {\n throw new Error(`Duplicate edge ID: \"${edge.id}\"`);\n }\n edgeIdSet.add(edge.id);\n }\n\n // 验证 entryNodeId 存在\n if (!nodeIdSet.has(entryNodeId)) {\n throw new Error(`Entry node \"${entryNodeId}\" does not exist in flow`);\n }\n\n // 验证边引用\n for (const edge of edges) {\n if (!nodeIdSet.has(edge.from)) {\n throw new Error(`Edge \"${edge.id}\" references non-existent source node \"${edge.from}\"`);\n }\n if (!nodeIdSet.has(edge.to)) {\n throw new Error(`Edge \"${edge.id}\" references non-existent target node \"${edge.to}\"`);\n }\n }\n\n // 时间戳：更新时继承 existingFlow.createdAt，新建时用当前时间\n const now = new Date(this.now()).toISOString() as ISODateTimeString;\n const createdAt = existingFlow?.createdAt ?? now;\n const updatedAt = now;\n\n // 构建完整的 FlowV3\n const flow: FlowV3 = {\n schemaVersion: CURRENT_FLOW_SCHEMA_VERSION,\n id,\n name,\n createdAt,\n updatedAt,\n entryNodeId,\n nodes,\n edges,\n };\n\n // 可选字段\n if (description !== undefined) {\n flow.description = description;\n }\n\n // variables 验证：每项必须是 object 且有 name 字段\n if (raw.variables !== undefined && raw.variables !== null) {\n if (!Array.isArray(raw.variables)) {\n throw new Error('flow.variables must be an array');\n }\n const variables: VariableDefinition[] = [];\n const varNameSet = new Set();\n for (let i = 0; i < raw.variables.length; i++) {\n const v = raw.variables[i];\n if (!v || typeof v !== 'object' || Array.isArray(v)) {\n throw new Error(`flow.variables[${i}] must be an object`);\n }\n const varObj = v as JsonObject;\n if (!varObj.name || typeof varObj.name !== 'string' || !varObj.name.trim()) {\n throw new Error(`flow.variables[${i}].name is required`);\n }\n const varName = varObj.name.trim();\n if (varNameSet.has(varName)) {\n throw new Error(`Duplicate variable name: \"${varName}\"`);\n }\n varNameSet.add(varName);\n // 使用 trim 后的 name\n variables.push({ ...varObj, name: varName } as unknown as VariableDefinition);\n }\n if (variables.length > 0) {\n flow.variables = variables;\n }\n }\n\n if (raw.policy !== undefined && raw.policy !== null) {\n if (typeof raw.policy !== 'object' || Array.isArray(raw.policy)) {\n throw new Error('flow.policy must be an object');\n }\n flow.policy = raw.policy as FlowV3['policy'];\n }\n if (raw.meta !== undefined && raw.meta !== null) {\n if (typeof raw.meta !== 'object' || Array.isArray(raw.meta)) {\n throw new Error('flow.meta must be an object');\n }\n flow.meta = raw.meta as FlowV3['meta'];\n }\n\n return flow;\n }\n\n /**\n * 规范化 Node 输入\n */\n private normalizeNode(value: unknown, index: number): NodeV3 {\n if (!value || typeof value !== 'object' || Array.isArray(value)) {\n throw new Error(`flow.nodes[${index}] must be an object`);\n }\n const raw = value as JsonObject;\n\n // id 校验（非空 + trim）\n if (!raw.id || typeof raw.id !== 'string' || !raw.id.trim()) {\n throw new Error(`flow.nodes[${index}].id is required`);\n }\n const nodeId = raw.id.trim() as NodeId;\n\n // kind 校验（非空 + trim）\n if (!raw.kind || typeof raw.kind !== 'string' || !raw.kind.trim()) {\n throw new Error(`flow.nodes[${index}].kind is required`);\n }\n const kind = raw.kind.trim();\n\n // config 校验\n if (raw.config !== undefined && raw.config !== null) {\n if (typeof raw.config !== 'object' || Array.isArray(raw.config)) {\n throw new Error(`flow.nodes[${index}].config must be an object`);\n }\n }\n\n const node: NodeV3 = {\n id: nodeId,\n kind,\n config: (raw.config as JsonObject) ?? {},\n };\n\n // 可选字段\n if (raw.name !== undefined && raw.name !== null) {\n if (typeof raw.name !== 'string') {\n throw new Error(`flow.nodes[${index}].name must be a string`);\n }\n node.name = raw.name;\n }\n if (raw.disabled !== undefined && raw.disabled !== null) {\n if (typeof raw.disabled !== 'boolean') {\n throw new Error(`flow.nodes[${index}].disabled must be a boolean`);\n }\n node.disabled = raw.disabled;\n }\n if (raw.policy !== undefined && raw.policy !== null) {\n if (typeof raw.policy !== 'object' || Array.isArray(raw.policy)) {\n throw new Error(`flow.nodes[${index}].policy must be an object`);\n }\n node.policy = raw.policy as NodeV3['policy'];\n }\n if (raw.ui !== undefined && raw.ui !== null) {\n if (typeof raw.ui !== 'object' || Array.isArray(raw.ui)) {\n throw new Error(`flow.nodes[${index}].ui must be an object`);\n }\n node.ui = raw.ui as NodeV3['ui'];\n }\n\n return node;\n }\n\n /**\n * 规范化 Edge 输入\n */\n private normalizeEdge(value: unknown, index: number): EdgeV3 {\n if (!value || typeof value !== 'object' || Array.isArray(value)) {\n throw new Error(`flow.edges[${index}] must be an object`);\n }\n const raw = value as JsonObject;\n\n // id 校验或生成（非空 + trim）\n let id: EdgeId;\n if (raw.id === undefined || raw.id === null) {\n id = `edge_${index}_${Math.random().toString(36).slice(2, 8)}` as EdgeId;\n } else {\n if (typeof raw.id !== 'string' || !raw.id.trim()) {\n throw new Error(`flow.edges[${index}].id must be a non-empty string`);\n }\n id = raw.id.trim() as EdgeId;\n }\n\n // from 校验（非空 + trim）\n if (!raw.from || typeof raw.from !== 'string' || !raw.from.trim()) {\n throw new Error(`flow.edges[${index}].from is required`);\n }\n const from = raw.from.trim() as NodeId;\n\n // to 校验（非空 + trim）\n if (!raw.to || typeof raw.to !== 'string' || !raw.to.trim()) {\n throw new Error(`flow.edges[${index}].to is required`);\n }\n const to = raw.to.trim() as NodeId;\n\n const edge: EdgeV3 = {\n id,\n from,\n to,\n };\n\n // label 可选\n if (raw.label !== undefined && raw.label !== null) {\n if (typeof raw.label !== 'string') {\n throw new Error(`flow.edges[${index}].label must be a string`);\n }\n edge.label = raw.label as EdgeV3['label'];\n }\n\n return edge;\n }\n\n // ===== Trigger Management Handlers =====\n\n private requireTriggerManager(): TriggerManager {\n if (!this.triggerManager) {\n throw new Error('TriggerManager not configured');\n }\n return this.triggerManager;\n }\n\n private async handleCreateTrigger(params: JsonObject | undefined): Promise {\n const trigger = this.normalizeTriggerSpec(params?.trigger, { requireId: false });\n\n const existing = await this.storage.triggers.get(trigger.id);\n if (existing) {\n throw new Error(`Trigger \"${trigger.id}\" already exists`);\n }\n\n const flow = await this.storage.flows.get(trigger.flowId);\n if (!flow) {\n throw new Error(`Flow \"${trigger.flowId}\" not found`);\n }\n\n await this.storage.triggers.save(trigger);\n await this.requireTriggerManager().refresh();\n return trigger as unknown as JsonValue;\n }\n\n private async handleUpdateTrigger(params: JsonObject | undefined): Promise {\n const trigger = this.normalizeTriggerSpec(params?.trigger, { requireId: true });\n\n const existing = await this.storage.triggers.get(trigger.id);\n if (!existing) {\n throw new Error(`Trigger \"${trigger.id}\" not found`);\n }\n\n const flow = await this.storage.flows.get(trigger.flowId);\n if (!flow) {\n throw new Error(`Flow \"${trigger.flowId}\" not found`);\n }\n\n await this.storage.triggers.save(trigger);\n await this.requireTriggerManager().refresh();\n return trigger as unknown as JsonValue;\n }\n\n private async handleDeleteTrigger(params: JsonObject | undefined): Promise {\n const triggerId = params?.triggerId as TriggerId | undefined;\n if (!triggerId) throw new Error('triggerId is required');\n\n await this.storage.triggers.delete(triggerId);\n await this.requireTriggerManager().refresh();\n return { ok: true, triggerId };\n }\n\n private async handleGetTrigger(params: JsonObject | undefined): Promise {\n const triggerId = params?.triggerId as TriggerId | undefined;\n if (!triggerId) throw new Error('triggerId is required');\n const trigger = await this.storage.triggers.get(triggerId);\n return trigger as unknown as JsonValue;\n }\n\n private async handleListTriggers(params: JsonObject | undefined): Promise {\n const flowIdValue = params?.flowId;\n let flowId: FlowId | undefined;\n if (flowIdValue !== undefined && flowIdValue !== null) {\n if (typeof flowIdValue !== 'string') {\n throw new Error('flowId must be a string');\n }\n flowId = flowIdValue as FlowId;\n }\n\n const triggers = await this.storage.triggers.list();\n const filtered = flowId ? triggers.filter((t) => t.flowId === flowId) : triggers;\n return filtered as unknown as JsonValue;\n }\n\n private async handleEnableTrigger(params: JsonObject | undefined): Promise {\n const triggerId = params?.triggerId as TriggerId | undefined;\n if (!triggerId) throw new Error('triggerId is required');\n\n const trigger = await this.storage.triggers.get(triggerId);\n if (!trigger) {\n throw new Error(`Trigger \"${triggerId}\" not found`);\n }\n\n const updated: TriggerSpec = { ...trigger, enabled: true };\n await this.storage.triggers.save(updated);\n await this.requireTriggerManager().refresh();\n return updated as unknown as JsonValue;\n }\n\n private async handleDisableTrigger(params: JsonObject | undefined): Promise {\n const triggerId = params?.triggerId as TriggerId | undefined;\n if (!triggerId) throw new Error('triggerId is required');\n\n const trigger = await this.storage.triggers.get(triggerId);\n if (!trigger) {\n throw new Error(`Trigger \"${triggerId}\" not found`);\n }\n\n const updated: TriggerSpec = { ...trigger, enabled: false };\n await this.storage.triggers.save(updated);\n await this.requireTriggerManager().refresh();\n return updated as unknown as JsonValue;\n }\n\n private async handleFireTrigger(params: JsonObject | undefined): Promise {\n const triggerId = params?.triggerId as TriggerId | undefined;\n if (!triggerId) throw new Error('triggerId is required');\n\n const trigger = await this.storage.triggers.get(triggerId);\n if (!trigger) {\n throw new Error(`Trigger \"${triggerId}\" not found`);\n }\n if (trigger.kind !== 'manual') {\n throw new Error(`fireTrigger only supports manual triggers (got kind=\"${trigger.kind}\")`);\n }\n if (!trigger.enabled) {\n throw new Error(`Trigger \"${triggerId}\" is disabled`);\n }\n\n let sourceTabId: number | undefined;\n if (params?.sourceTabId !== undefined && params?.sourceTabId !== null) {\n if (typeof params.sourceTabId !== 'number' || !Number.isFinite(params.sourceTabId)) {\n throw new Error('sourceTabId must be a finite number');\n }\n sourceTabId = Math.floor(params.sourceTabId);\n }\n\n let sourceUrl: string | undefined;\n if (params?.sourceUrl !== undefined && params?.sourceUrl !== null) {\n if (typeof params.sourceUrl !== 'string') {\n throw new Error('sourceUrl must be a string');\n }\n sourceUrl = params.sourceUrl;\n }\n\n const result = await this.requireTriggerManager().fire(triggerId, {\n sourceTabId,\n sourceUrl,\n });\n return result as unknown as JsonValue;\n }\n\n /**\n * 规范化 TriggerSpec 输入\n */\n private normalizeTriggerSpec(value: unknown, opts: { requireId: boolean }): TriggerSpec {\n if (!value || typeof value !== 'object' || Array.isArray(value)) {\n throw new Error('trigger is required');\n }\n const raw = value as JsonObject;\n\n // kind 校验\n const kind = raw.kind;\n if (!kind || typeof kind !== 'string') {\n throw new Error('trigger.kind is required');\n }\n\n // flowId 校验\n const flowId = raw.flowId;\n if (!flowId || typeof flowId !== 'string') {\n throw new Error('trigger.flowId is required');\n }\n\n // id 校验\n let id: TriggerId;\n if (raw.id === undefined || raw.id === null) {\n if (opts.requireId) {\n throw new Error('trigger.id is required');\n }\n id = `trg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}` as TriggerId;\n } else {\n if (typeof raw.id !== 'string' || !raw.id.trim()) {\n throw new Error('trigger.id must be a non-empty string');\n }\n id = raw.id as TriggerId;\n }\n\n // enabled 校验\n let enabled = true;\n if (raw.enabled !== undefined && raw.enabled !== null) {\n if (typeof raw.enabled !== 'boolean') {\n throw new Error('trigger.enabled must be a boolean');\n }\n enabled = raw.enabled;\n }\n\n // args 校验\n let args: JsonObject | undefined;\n if (raw.args !== undefined && raw.args !== null) {\n if (typeof raw.args !== 'object' || Array.isArray(raw.args)) {\n throw new Error('trigger.args must be an object');\n }\n args = raw.args as JsonObject;\n }\n\n // 基础字段\n const base = { id, kind: kind as TriggerKind, enabled, flowId: flowId as FlowId, args };\n\n // 根据 kind 添加特定字段\n switch (kind) {\n case 'manual':\n return base as TriggerSpec;\n\n case 'url': {\n let match: unknown[] = [];\n if (raw.match !== undefined && raw.match !== null) {\n if (!Array.isArray(raw.match)) {\n throw new Error('trigger.match must be an array');\n }\n match = raw.match;\n }\n return { ...base, match } as TriggerSpec;\n }\n\n case 'cron': {\n if (!raw.cron || typeof raw.cron !== 'string') {\n throw new Error('trigger.cron is required for cron triggers');\n }\n let timezone: string | undefined;\n if (raw.timezone !== undefined && raw.timezone !== null) {\n if (typeof raw.timezone !== 'string') {\n throw new Error('trigger.timezone must be a string');\n }\n timezone = raw.timezone.trim() || undefined;\n }\n return { ...base, cron: raw.cron, timezone } as TriggerSpec;\n }\n\n case 'interval': {\n if (raw.periodMinutes === undefined || raw.periodMinutes === null) {\n throw new Error('trigger.periodMinutes is required for interval triggers');\n }\n if (typeof raw.periodMinutes !== 'number' || !Number.isFinite(raw.periodMinutes)) {\n throw new Error('trigger.periodMinutes must be a finite number');\n }\n if (raw.periodMinutes < 1) {\n throw new Error('trigger.periodMinutes must be >= 1');\n }\n return { ...base, periodMinutes: raw.periodMinutes } as TriggerSpec;\n }\n\n case 'once': {\n if (raw.whenMs === undefined || raw.whenMs === null) {\n throw new Error('trigger.whenMs is required for once triggers');\n }\n if (typeof raw.whenMs !== 'number' || !Number.isFinite(raw.whenMs)) {\n throw new Error('trigger.whenMs must be a finite number');\n }\n return { ...base, whenMs: Math.floor(raw.whenMs) } as TriggerSpec;\n }\n\n case 'command': {\n if (!raw.commandKey || typeof raw.commandKey !== 'string') {\n throw new Error('trigger.commandKey is required for command triggers');\n }\n return { ...base, commandKey: raw.commandKey } as TriggerSpec;\n }\n\n case 'contextMenu': {\n if (!raw.title || typeof raw.title !== 'string') {\n throw new Error('trigger.title is required for contextMenu triggers');\n }\n let contexts: string[] | undefined;\n if (raw.contexts !== undefined && raw.contexts !== null) {\n if (!Array.isArray(raw.contexts) || !raw.contexts.every((c) => typeof c === 'string')) {\n throw new Error('trigger.contexts must be an array of strings');\n }\n contexts = raw.contexts as string[];\n }\n return { ...base, title: raw.title, contexts } as TriggerSpec;\n }\n\n case 'dom': {\n if (!raw.selector || typeof raw.selector !== 'string') {\n throw new Error('trigger.selector is required for dom triggers');\n }\n let appear: boolean | undefined;\n if (raw.appear !== undefined && raw.appear !== null) {\n if (typeof raw.appear !== 'boolean') {\n throw new Error('trigger.appear must be a boolean');\n }\n appear = raw.appear;\n }\n let once: boolean | undefined;\n if (raw.once !== undefined && raw.once !== null) {\n if (typeof raw.once !== 'boolean') {\n throw new Error('trigger.once must be a boolean');\n }\n once = raw.once;\n }\n let debounceMs: number | undefined;\n if (raw.debounceMs !== undefined && raw.debounceMs !== null) {\n if (typeof raw.debounceMs !== 'number' || !Number.isFinite(raw.debounceMs)) {\n throw new Error('trigger.debounceMs must be a finite number');\n }\n debounceMs = raw.debounceMs;\n }\n return { ...base, selector: raw.selector, appear, once, debounceMs } as TriggerSpec;\n }\n\n default:\n throw new Error(\n `trigger.kind must be one of: manual, url, cron, interval, once, command, contextMenu, dom`,\n );\n }\n }\n\n // ===== Run Control Handlers =====\n\n private async handlePauseRun(params: JsonObject | undefined): Promise {\n const runId = params?.runId as RunId | undefined;\n if (!runId) throw new Error('runId is required');\n\n if (!this.runners) {\n throw new Error('RunnerRegistry not configured');\n }\n\n const runner = this.runners.get(runId);\n if (!runner) {\n throw new Error(`Runner for \"${runId}\" not found (run may not be executing)`);\n }\n\n const queueItem = await this.storage.queue.get(runId);\n if (!queueItem) {\n throw new Error(`Queue item \"${runId}\" not found`);\n }\n if (queueItem.status === 'queued') {\n throw new Error(`Cannot pause run \"${runId}\" while status=queued`);\n }\n\n const ownerId = queueItem.lease?.ownerId;\n if (!ownerId) {\n throw new Error(`Queue item \"${runId}\" has no lease ownerId`);\n }\n\n const now = this.now();\n await this.storage.queue.markPaused(runId, ownerId, now);\n runner.pause();\n\n return { ok: true, runId };\n }\n\n private async handleResumeRun(params: JsonObject | undefined): Promise {\n const runId = params?.runId as RunId | undefined;\n if (!runId) throw new Error('runId is required');\n\n if (!this.runners) {\n throw new Error('RunnerRegistry not configured');\n }\n\n const runner = this.runners.get(runId);\n if (!runner) {\n throw new Error(`Runner for \"${runId}\" not found (run may not be executing)`);\n }\n\n const queueItem = await this.storage.queue.get(runId);\n if (!queueItem) {\n throw new Error(`Queue item \"${runId}\" not found`);\n }\n if (queueItem.status !== 'paused') {\n throw new Error(`Cannot resume run \"${runId}\" with status=${queueItem.status}`);\n }\n\n const ownerId = queueItem.lease?.ownerId;\n if (!ownerId) {\n throw new Error(`Queue item \"${runId}\" has no lease ownerId`);\n }\n\n const now = this.now();\n await this.storage.queue.markRunning(runId, ownerId, now);\n runner.resume();\n\n return { ok: true, runId };\n }\n\n private async handleCancelRun(params: JsonObject | undefined): Promise {\n const runId = params?.runId as RunId | undefined;\n if (!runId) throw new Error('runId is required');\n\n const reason = (params?.reason as string) ?? 'Canceled by user';\n const queueItem = await this.storage.queue.get(runId);\n\n // If still queued (not yet claimed), cancel via queue\n if (queueItem?.status === 'queued') {\n return this.handleCancelQueueItem({ runId, reason } as unknown as JsonObject);\n }\n\n // If running/paused, cancel via runner\n if (!this.runners) {\n throw new Error('RunnerRegistry not configured');\n }\n\n const runner = this.runners.get(runId);\n if (!runner) {\n // Run may have already finished\n throw new Error(`Runner for \"${runId}\" not found (run may have already finished)`);\n }\n\n runner.cancel(reason);\n return { ok: true, runId };\n }\n}\n\n/**\n * 创建并启动 RPC Server\n */\nexport function createRpcServer(config: RpcServerConfig): RpcServer {\n const server = new RpcServer(config);\n server.start();\n return server;\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/transport/rpc.ts", "content": "/**\n * @fileoverview Port RPC 协议定义\n * @description 定义通过 chrome.runtime.Port 进行通信的协议类型\n */\n\nimport type { JsonObject, JsonValue } from '../../domain/json';\nimport type { RunId } from '../../domain/ids';\nimport type { RunEvent } from '../../domain/events';\n\n/** Port 名称 */\nexport const RR_V3_PORT_NAME = 'rr_v3' as const;\n\n/**\n * RPC 方法名称\n */\nexport type RpcMethod =\n // 查询方法\n | 'rr_v3.listRuns'\n | 'rr_v3.getRun'\n | 'rr_v3.getEvents'\n // Flow 管理方法\n | 'rr_v3.getFlow'\n | 'rr_v3.listFlows'\n | 'rr_v3.saveFlow'\n | 'rr_v3.deleteFlow'\n // 触发器管理方法\n | 'rr_v3.createTrigger'\n | 'rr_v3.updateTrigger'\n | 'rr_v3.deleteTrigger'\n | 'rr_v3.getTrigger'\n | 'rr_v3.listTriggers'\n | 'rr_v3.enableTrigger'\n | 'rr_v3.disableTrigger'\n | 'rr_v3.fireTrigger'\n // 队列管理方法\n | 'rr_v3.enqueueRun'\n | 'rr_v3.listQueue'\n | 'rr_v3.cancelQueueItem'\n // 控制方法\n | 'rr_v3.startRun'\n | 'rr_v3.cancelRun'\n | 'rr_v3.pauseRun'\n | 'rr_v3.resumeRun'\n // 调试方法\n | 'rr_v3.debug'\n // 订阅方法\n | 'rr_v3.subscribe'\n | 'rr_v3.unsubscribe';\n\n/**\n * RPC 请求消息\n */\nexport interface RpcRequest {\n type: 'rr_v3.request';\n /** 请求 ID（用于匹配响应） */\n requestId: string;\n /** 方法名 */\n method: RpcMethod;\n /** 参数 */\n params?: JsonObject;\n}\n\n/**\n * RPC 成功响应\n */\nexport interface RpcResponseOk {\n type: 'rr_v3.response';\n /** 对应的请求 ID */\n requestId: string;\n ok: true;\n /** 返回结果 */\n result: JsonValue;\n}\n\n/**\n * RPC 错误响应\n */\nexport interface RpcResponseErr {\n type: 'rr_v3.response';\n /** 对应的请求 ID */\n requestId: string;\n ok: false;\n /** 错误信息 */\n error: string;\n}\n\n/**\n * RPC 响应\n */\nexport type RpcResponse = RpcResponseOk | RpcResponseErr;\n\n/**\n * RPC 事件推送\n */\nexport interface RpcEventMessage {\n type: 'rr_v3.event';\n /** 事件数据 */\n event: RunEvent;\n}\n\n/**\n * RPC 订阅确认\n */\nexport interface RpcSubscribeAck {\n type: 'rr_v3.subscribeAck';\n /** 订阅的 Run ID（可选，null 表示订阅所有） */\n runId: RunId | null;\n}\n\n/**\n * 所有 RPC 消息类型\n */\nexport type RpcMessage =\n | RpcRequest\n | RpcResponseOk\n | RpcResponseErr\n | RpcEventMessage\n | RpcSubscribeAck;\n\n/**\n * 生成唯一的请求 ID\n */\nexport function generateRequestId(): string {\n return `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n}\n\n/**\n * 判断消息是否为 RPC 请求\n */\nexport function isRpcRequest(msg: unknown): msg is RpcRequest {\n return typeof msg === 'object' && msg !== null && (msg as RpcRequest).type === 'rr_v3.request';\n}\n\n/**\n * 判断消息是否为 RPC 响应\n */\nexport function isRpcResponse(msg: unknown): msg is RpcResponse {\n return typeof msg === 'object' && msg !== null && (msg as RpcResponse).type === 'rr_v3.response';\n}\n\n/**\n * 判断消息是否为 RPC 事件\n */\nexport function isRpcEvent(msg: unknown): msg is RpcEventMessage {\n return typeof msg === 'object' && msg !== null && (msg as RpcEventMessage).type === 'rr_v3.event';\n}\n\n/**\n * 创建 RPC 请求\n */\nexport function createRpcRequest(method: RpcMethod, params?: JsonObject): RpcRequest {\n return {\n type: 'rr_v3.request',\n requestId: generateRequestId(),\n method,\n params,\n };\n}\n\n/**\n * 创建成功响应\n */\nexport function createRpcResponseOk(requestId: string, result: JsonValue): RpcResponseOk {\n return {\n type: 'rr_v3.response',\n requestId,\n ok: true,\n result,\n };\n}\n\n/**\n * 创建错误响应\n */\nexport function createRpcResponseErr(requestId: string, error: string): RpcResponseErr {\n return {\n type: 'rr_v3.response',\n requestId,\n ok: false,\n error,\n };\n}\n\n/**\n * 创建事件消息\n */\nexport function createRpcEventMessage(event: RunEvent): RpcEventMessage {\n return {\n type: 'rr_v3.event',\n event,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/command-trigger.ts", "content": "/**\n * @fileoverview Command Trigger Handler (P4-04)\n * @description\n * Listens to `chrome.commands.onCommand` and fires installed command triggers.\n *\n * Command triggers allow users to execute flows via keyboard shortcuts\n * defined in the extension's manifest.\n *\n * Design notes:\n * - Commands must be registered in manifest.json under the \"commands\" key\n * - Each command is identified by its commandKey (e.g., \"run-flow-1\")\n * - Active tab info is captured when available\n */\n\nimport type { TriggerId } from '../../domain/ids';\nimport type { TriggerSpecByKind } from '../../domain/triggers';\nimport type { TriggerFireCallback, TriggerHandler, TriggerHandlerFactory } from './trigger-handler';\n\n// ==================== Types ====================\n\nexport interface CommandTriggerHandlerDeps {\n logger?: Pick;\n}\n\ntype CommandTriggerSpec = TriggerSpecByKind<'command'>;\n\ninterface InstalledCommandTrigger {\n spec: CommandTriggerSpec;\n}\n\n// ==================== Handler Implementation ====================\n\n/**\n * Create command trigger handler factory\n */\nexport function createCommandTriggerHandlerFactory(\n deps?: CommandTriggerHandlerDeps,\n): TriggerHandlerFactory<'command'> {\n return (fireCallback) => createCommandTriggerHandler(fireCallback, deps);\n}\n\n/**\n * Create command trigger handler\n */\nexport function createCommandTriggerHandler(\n fireCallback: TriggerFireCallback,\n deps?: CommandTriggerHandlerDeps,\n): TriggerHandler<'command'> {\n const logger = deps?.logger ?? console;\n\n // Map commandKey -> triggerId for fast lookup\n const commandKeyToTriggerId = new Map();\n const installed = new Map();\n let listening = false;\n\n /**\n * Handle chrome.commands.onCommand event\n */\n const onCommand = (command: string, tab?: chrome.tabs.Tab): void => {\n const triggerId = commandKeyToTriggerId.get(command);\n if (!triggerId) return;\n\n const trigger = installed.get(triggerId);\n if (!trigger) return;\n\n // Fire and forget: chrome event listeners should not block\n Promise.resolve(\n fireCallback.onFire(triggerId, {\n sourceTabId: tab?.id,\n sourceUrl: tab?.url,\n }),\n ).catch((e) => {\n logger.error(`[CommandTriggerHandler] onFire failed for trigger \"${triggerId}\":`, e);\n });\n };\n\n /**\n * Ensure listener is registered\n */\n function ensureListening(): void {\n if (listening) return;\n if (!chrome.commands?.onCommand?.addListener) {\n logger.warn('[CommandTriggerHandler] chrome.commands.onCommand is unavailable');\n return;\n }\n chrome.commands.onCommand.addListener(onCommand);\n listening = true;\n }\n\n /**\n * Stop listening\n */\n function stopListening(): void {\n if (!listening) return;\n try {\n chrome.commands.onCommand.removeListener(onCommand);\n } catch (e) {\n logger.debug('[CommandTriggerHandler] removeListener failed:', e);\n } finally {\n listening = false;\n }\n }\n\n return {\n kind: 'command',\n\n async install(trigger: CommandTriggerSpec): Promise {\n const { id, commandKey } = trigger;\n\n // Warn if commandKey already used by another trigger\n const existingTriggerId = commandKeyToTriggerId.get(commandKey);\n if (existingTriggerId && existingTriggerId !== id) {\n logger.warn(\n `[CommandTriggerHandler] Command \"${commandKey}\" already used by trigger \"${existingTriggerId}\", overwriting with \"${id}\"`,\n );\n // Remove old mapping\n installed.delete(existingTriggerId);\n }\n\n installed.set(id, { spec: trigger });\n commandKeyToTriggerId.set(commandKey, id);\n ensureListening();\n },\n\n async uninstall(triggerId: string): Promise {\n const trigger = installed.get(triggerId as TriggerId);\n if (trigger) {\n commandKeyToTriggerId.delete(trigger.spec.commandKey);\n installed.delete(triggerId as TriggerId);\n }\n\n if (installed.size === 0) {\n stopListening();\n }\n },\n\n async uninstallAll(): Promise {\n installed.clear();\n commandKeyToTriggerId.clear();\n stopListening();\n },\n\n getInstalledIds(): string[] {\n return Array.from(installed.keys());\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/context-menu-trigger.ts", "content": "/**\n * @fileoverview ContextMenu Trigger Handler (P4-05)\n * @description\n * Uses `chrome.contextMenus` API to create right-click menu items that fire triggers.\n *\n * Design notes:\n * - Each trigger creates a separate menu item with unique ID\n * - Menu item ID is prefixed with 'rr_v3_' to avoid conflicts\n * - Context types: 'page', 'selection', 'link', 'image', 'video', 'audio', etc.\n * - Captures click info and tab info for trigger context\n */\n\nimport type { TriggerId } from '../../domain/ids';\nimport type { TriggerSpecByKind } from '../../domain/triggers';\nimport type { TriggerFireCallback, TriggerHandler, TriggerHandlerFactory } from './trigger-handler';\n\n// ==================== Types ====================\n\nexport interface ContextMenuTriggerHandlerDeps {\n logger?: Pick;\n}\n\ntype ContextMenuTriggerSpec = TriggerSpecByKind<'contextMenu'>;\n\ninterface InstalledContextMenuTrigger {\n spec: ContextMenuTriggerSpec;\n menuItemId: string;\n}\n\n// ==================== Constants ====================\n\nconst MENU_ITEM_PREFIX = 'rr_v3_';\n\n// Default context types if not specified\nconst DEFAULT_CONTEXTS: chrome.contextMenus.ContextType[] = ['page'];\n\n// ==================== Handler Implementation ====================\n\n/**\n * Create context menu trigger handler factory\n */\nexport function createContextMenuTriggerHandlerFactory(\n deps?: ContextMenuTriggerHandlerDeps,\n): TriggerHandlerFactory<'contextMenu'> {\n return (fireCallback) => createContextMenuTriggerHandler(fireCallback, deps);\n}\n\n/**\n * Create context menu trigger handler\n */\nexport function createContextMenuTriggerHandler(\n fireCallback: TriggerFireCallback,\n deps?: ContextMenuTriggerHandlerDeps,\n): TriggerHandler<'contextMenu'> {\n const logger = deps?.logger ?? console;\n\n // Map menuItemId -> triggerId for fast lookup\n const menuItemIdToTriggerId = new Map();\n const installed = new Map();\n let listening = false;\n\n /**\n * Generate unique menu item ID for a trigger\n */\n function generateMenuItemId(triggerId: TriggerId): string {\n return `${MENU_ITEM_PREFIX}${triggerId}`;\n }\n\n /**\n * Handle chrome.contextMenus.onClicked event\n */\n const onClicked = (info: chrome.contextMenus.OnClickData, tab?: chrome.tabs.Tab): void => {\n const menuItemId = String(info.menuItemId);\n const triggerId = menuItemIdToTriggerId.get(menuItemId);\n if (!triggerId) return;\n\n const trigger = installed.get(triggerId);\n if (!trigger) return;\n\n // Fire and forget: chrome event listeners should not block\n Promise.resolve(\n fireCallback.onFire(triggerId, {\n sourceTabId: tab?.id,\n sourceUrl: info.pageUrl ?? tab?.url,\n }),\n ).catch((e) => {\n logger.error(`[ContextMenuTriggerHandler] onFire failed for trigger \"${triggerId}\":`, e);\n });\n };\n\n /**\n * Ensure listener is registered\n */\n function ensureListening(): void {\n if (listening) return;\n if (!chrome.contextMenus?.onClicked?.addListener) {\n logger.warn('[ContextMenuTriggerHandler] chrome.contextMenus.onClicked is unavailable');\n return;\n }\n chrome.contextMenus.onClicked.addListener(onClicked);\n listening = true;\n }\n\n /**\n * Stop listening\n */\n function stopListening(): void {\n if (!listening) return;\n try {\n chrome.contextMenus.onClicked.removeListener(onClicked);\n } catch (e) {\n logger.debug('[ContextMenuTriggerHandler] removeListener failed:', e);\n } finally {\n listening = false;\n }\n }\n\n /**\n * Convert context types from spec to chrome API format\n */\n function normalizeContexts(\n contexts: ReadonlyArray | undefined,\n ): chrome.contextMenus.ContextType[] {\n if (!contexts || contexts.length === 0) {\n return DEFAULT_CONTEXTS;\n }\n return contexts as chrome.contextMenus.ContextType[];\n }\n\n return {\n kind: 'contextMenu',\n\n async install(trigger: ContextMenuTriggerSpec): Promise {\n const { id, title, contexts } = trigger;\n const menuItemId = generateMenuItemId(id);\n\n // Check if chrome.contextMenus.create is available\n if (!chrome.contextMenus?.create) {\n logger.warn('[ContextMenuTriggerHandler] chrome.contextMenus.create is unavailable');\n return;\n }\n\n // Create menu item\n await new Promise((resolve, reject) => {\n chrome.contextMenus.create(\n {\n id: menuItemId,\n title: title,\n contexts: normalizeContexts(contexts),\n },\n () => {\n if (chrome.runtime.lastError) {\n reject(new Error(chrome.runtime.lastError.message));\n } else {\n resolve();\n }\n },\n );\n });\n\n installed.set(id, { spec: trigger, menuItemId });\n menuItemIdToTriggerId.set(menuItemId, id);\n ensureListening();\n },\n\n async uninstall(triggerId: string): Promise {\n const trigger = installed.get(triggerId as TriggerId);\n if (!trigger) return;\n\n // Remove menu item\n if (chrome.contextMenus?.remove) {\n await new Promise((resolve) => {\n chrome.contextMenus.remove(trigger.menuItemId, () => {\n // Ignore errors (item may not exist)\n if (chrome.runtime.lastError) {\n logger.debug(\n `[ContextMenuTriggerHandler] Failed to remove menu item: ${chrome.runtime.lastError.message}`,\n );\n }\n resolve();\n });\n });\n }\n\n menuItemIdToTriggerId.delete(trigger.menuItemId);\n installed.delete(triggerId as TriggerId);\n\n if (installed.size === 0) {\n stopListening();\n }\n },\n\n async uninstallAll(): Promise {\n // Remove all menu items created by this handler\n if (chrome.contextMenus?.remove) {\n const removePromises = Array.from(installed.values()).map(\n (trigger) =>\n new Promise((resolve) => {\n chrome.contextMenus.remove(trigger.menuItemId, () => {\n // Ignore errors\n resolve();\n });\n }),\n );\n await Promise.all(removePromises);\n }\n\n installed.clear();\n menuItemIdToTriggerId.clear();\n stopListening();\n },\n\n getInstalledIds(): string[] {\n return Array.from(installed.keys());\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/cron-trigger.ts", "content": "/**\n * @fileoverview Cron Trigger Handler (P4-07)\n * @description\n * Schedules cron triggers via `chrome.alarms` (MV3).\n *\n * Strategy:\n * - One alarm per trigger (one-shot `when` alarm).\n * - When fired: call `fireCallback.onFire(triggerId)` then compute and schedule next.\n *\n * Timezone:\n * - Accepts IANA timezones (e.g. \"UTC\", \"Asia/Shanghai\").\n * - Validated via `Intl.DateTimeFormat(..., { timeZone })`.\n *\n * Cron parsing:\n * - Delegated to an external library (recommended: `cron-parser`) to avoid DST edge cases.\n * - Falls back to a minimal built-in parser if library not available.\n */\n\nimport type { UnixMillis } from '../../domain/json';\nimport type { TriggerId } from '../../domain/ids';\nimport type { TriggerSpecByKind } from '../../domain/triggers';\nimport type { TriggerFireCallback, TriggerHandler, TriggerHandlerFactory } from './trigger-handler';\n\n// ==================== Types ====================\n\ntype CronTriggerSpec = TriggerSpecByKind<'cron'>;\n\n/**\n * Function to compute next fire time from cron expression\n */\nexport type ComputeNextFireAtMs = (input: {\n cron: string;\n timezone?: string;\n fromMs: UnixMillis;\n}) => UnixMillis | Promise;\n\nexport interface CronTriggerHandlerDeps {\n logger?: Pick;\n now?: () => UnixMillis;\n computeNextFireAtMs?: ComputeNextFireAtMs;\n}\n\ninterface InstalledCronTrigger {\n spec: CronTriggerSpec;\n timezone?: string;\n version: number;\n}\n\n// ==================== Constants ====================\n\nconst ALARM_PREFIX = 'rr_v3_cron_';\n\n// ==================== Utilities ====================\n\n/**\n * Normalize cron expression\n */\nfunction normalizeCronExpression(value: unknown): string {\n const raw = typeof value === 'string' ? value : String(value ?? '');\n const normalized = raw.trim().replace(/\\s+/g, ' ');\n if (!normalized) {\n throw new Error('cron must be a non-empty string');\n }\n return normalized;\n}\n\n/**\n * Validate and normalize timezone\n */\nfunction normalizeTimezone(value: unknown): string | undefined {\n if (value === undefined || value === null) return undefined;\n if (typeof value !== 'string') {\n throw new Error('timezone must be a string');\n }\n const trimmed = value.trim();\n if (!trimmed) return undefined;\n\n try {\n // Throws RangeError for invalid IANA timezones\n new Intl.DateTimeFormat('en-US', { timeZone: trimmed }).format(new Date(0));\n } catch {\n throw new Error(`Invalid timezone: \"${trimmed}\"`);\n }\n\n return trimmed;\n}\n\n/**\n * Generate alarm name for trigger\n */\nfunction alarmNameForTrigger(triggerId: TriggerId): string {\n return `${ALARM_PREFIX}${triggerId}`;\n}\n\n/**\n * Parse trigger ID from alarm name\n */\nfunction parseTriggerIdFromAlarmName(name: string): TriggerId | null {\n if (!name.startsWith(ALARM_PREFIX)) return null;\n const id = name.slice(ALARM_PREFIX.length);\n return id ? (id as TriggerId) : null;\n}\n\n/**\n * Simple cron expression parser (minimal subset)\n * Supports: minute hour day-of-month month day-of-week\n * Values: numbers, * (any), intervals (e.g., * /5)\n *\n * For production use with complex cron expressions, install 'cron-parser'.\n */\nfunction parseSimpleCron(cron: string): {\n minute: number[];\n hour: number[];\n dayOfMonth: number[];\n month: number[];\n dayOfWeek: number[];\n} {\n const parts = cron.split(' ');\n if (parts.length !== 5) {\n throw new Error(`Invalid cron expression: expected 5 fields, got ${parts.length}`);\n }\n\n function parseField(field: string, min: number, max: number): number[] {\n const values: number[] = [];\n\n for (const part of field.split(',')) {\n if (part === '*') {\n for (let i = min; i <= max; i++) values.push(i);\n } else if (part.includes('/')) {\n const [range, stepStr] = part.split('/');\n const step = parseInt(stepStr, 10);\n // Guard against infinite loop: step must be positive\n if (!Number.isFinite(step) || step < 1) {\n throw new Error(`Invalid step in cron field: \"${part}\" (step must be >= 1)`);\n }\n const start = range === '*' ? min : parseInt(range, 10);\n if (!Number.isFinite(start) || start < min || start > max) {\n throw new Error(`Invalid range start in cron field: \"${part}\"`);\n }\n for (let i = start; i <= max; i += step) values.push(i);\n } else if (part.includes('-')) {\n const [startStr, endStr] = part.split('-');\n const start = parseInt(startStr, 10);\n const end = parseInt(endStr, 10);\n if (!Number.isFinite(start) || !Number.isFinite(end) || start > end) {\n throw new Error(`Invalid range in cron field: \"${part}\"`);\n }\n for (let i = start; i <= end; i++) values.push(i);\n } else {\n const num = parseInt(part, 10);\n if (!Number.isFinite(num)) {\n throw new Error(`Invalid number in cron field: \"${part}\"`);\n }\n values.push(num);\n }\n }\n\n // Validate all values are within bounds\n for (const v of values) {\n if (v < min || v > max) {\n throw new Error(`Cron field value ${v} out of range [${min}, ${max}]`);\n }\n }\n\n return [...new Set(values)].sort((a, b) => a - b);\n }\n\n return {\n minute: parseField(parts[0], 0, 59),\n hour: parseField(parts[1], 0, 23),\n dayOfMonth: parseField(parts[2], 1, 31),\n month: parseField(parts[3], 1, 12),\n dayOfWeek: parseField(parts[4], 0, 6),\n };\n}\n\n// ==================== Timezone Utilities ====================\n\ninterface ZonedTimeParts {\n year: number;\n month: number;\n day: number;\n hour: number;\n minute: number;\n dayOfWeek: number;\n}\n\n// Cache DateTimeFormat instances per timezone for performance\nconst dtfCache = new Map();\n\n/**\n * Get or create cached DateTimeFormat for a timezone\n */\nfunction getDateTimeFormat(timezone: string): Intl.DateTimeFormat {\n let dtf = dtfCache.get(timezone);\n if (!dtf) {\n dtf = new Intl.DateTimeFormat('en-US', {\n timeZone: timezone,\n hourCycle: 'h23',\n year: 'numeric',\n month: '2-digit',\n day: '2-digit',\n hour: '2-digit',\n minute: '2-digit',\n weekday: 'short',\n });\n dtfCache.set(timezone, dtf);\n }\n return dtf;\n}\n\n// Map weekday string to number (0=Sunday)\nconst WEEKDAY_MAP: Record = {\n Sun: 0,\n Mon: 1,\n Tue: 2,\n Wed: 3,\n Thu: 4,\n Fri: 5,\n Sat: 6,\n};\n\n/**\n * Get time parts in a specific timezone using Intl.DateTimeFormat\n */\nfunction getZonedTimeParts(utcMs: UnixMillis, timezone: string): ZonedTimeParts {\n const dtf = getDateTimeFormat(timezone);\n const parts = dtf.formatToParts(new Date(utcMs));\n const map: Record = Object.create(null);\n for (const p of parts) {\n if (p.type !== 'literal') map[p.type] = p.value;\n }\n\n // Handle edge case: some environments emit \"24\" for midnight\n const rawHour = Number(map.hour);\n\n return {\n year: Number(map.year),\n month: Number(map.month),\n day: Number(map.day),\n hour: rawHour === 24 ? 0 : rawHour,\n minute: Number(map.minute),\n dayOfWeek: WEEKDAY_MAP[map.weekday] ?? 0,\n };\n}\n\n/**\n * Calculate timezone offset in milliseconds at a given UTC timestamp\n * Positive offset means timezone is ahead of UTC (e.g., Asia/Shanghai = +8h = +28800000ms)\n */\nfunction getTimezoneOffsetMs(utcMs: UnixMillis, timezone: string): number {\n const z = getZonedTimeParts(utcMs, timezone);\n const asUtc = Date.UTC(z.year, z.month - 1, z.day, z.hour, z.minute, 0);\n return asUtc - utcMs;\n}\n\n/**\n * Convert zoned datetime to UTC milliseconds\n * Uses iterative refinement to handle DST transitions\n */\nfunction zonedToUtcMs(\n zoned: { year: number; month: number; day: number; hour: number; minute: number },\n timezone: string,\n): UnixMillis {\n // Start with the zoned time interpreted as UTC\n const baseUtc = Date.UTC(zoned.year, zoned.month - 1, zoned.day, zoned.hour, zoned.minute, 0);\n\n // Iteratively solve: utcMs = baseUtc - offset(utcMs)\n let utcMs = baseUtc;\n for (let i = 0; i < 3; i++) {\n const offsetMs = getTimezoneOffsetMs(utcMs, timezone);\n const next = baseUtc - offsetMs;\n if (next === utcMs) break;\n utcMs = next;\n }\n return utcMs;\n}\n\n// ==================== Cron Computation ====================\n\n/**\n * Compute next fire time using built-in simple parser (local timezone)\n */\nfunction computeNextFireAtMsLocal(\n parsed: ReturnType,\n fromMs: UnixMillis,\n): UnixMillis {\n const baseDate = new Date(fromMs + 1000); // Add 1 second to ensure next occurrence\n\n for (let dayOffset = 0; dayOffset < 366; dayOffset++) {\n for (const hour of parsed.hour) {\n for (const minute of parsed.minute) {\n const candidate = new Date(baseDate);\n candidate.setDate(candidate.getDate() + dayOffset);\n candidate.setHours(hour, minute, 0, 0);\n\n if (candidate.getTime() <= fromMs) continue;\n\n const month = candidate.getMonth() + 1;\n const dayOfMonth = candidate.getDate();\n const dayOfWeek = candidate.getDay();\n\n if (!parsed.month.includes(month)) continue;\n if (!parsed.dayOfMonth.includes(dayOfMonth) && !parsed.dayOfWeek.includes(dayOfWeek))\n continue;\n\n return candidate.getTime();\n }\n }\n }\n\n throw new Error('Failed to compute next cron fire time within 1 year');\n}\n\n/**\n * Compute next fire time in a specific timezone\n */\nfunction computeNextFireAtMsZoned(\n parsed: ReturnType,\n fromMs: UnixMillis,\n timezone: string,\n): UnixMillis {\n const baseZoned = getZonedTimeParts(fromMs + 1000, timezone);\n const dayCursor = new Date(Date.UTC(baseZoned.year, baseZoned.month - 1, baseZoned.day));\n\n for (let dayOffset = 0; dayOffset < 366; dayOffset++) {\n if (dayOffset > 0) dayCursor.setUTCDate(dayCursor.getUTCDate() + 1);\n\n const year = dayCursor.getUTCFullYear();\n const month = dayCursor.getUTCMonth() + 1;\n const dayOfMonth = dayCursor.getUTCDate();\n const dayOfWeek = dayCursor.getUTCDay();\n\n if (!parsed.month.includes(month)) continue;\n if (!parsed.dayOfMonth.includes(dayOfMonth) && !parsed.dayOfWeek.includes(dayOfWeek)) continue;\n\n for (const hour of parsed.hour) {\n for (const minute of parsed.minute) {\n const candidateUtcMs = zonedToUtcMs(\n { year, month, day: dayOfMonth, hour, minute },\n timezone,\n );\n\n if (candidateUtcMs <= fromMs) continue;\n\n // Validate conversion didn't drift (DST gaps/ambiguity can cause skipped times)\n const candidateZoned = getZonedTimeParts(candidateUtcMs, timezone);\n if (\n candidateZoned.year !== year ||\n candidateZoned.month !== month ||\n candidateZoned.day !== dayOfMonth ||\n candidateZoned.hour !== hour ||\n candidateZoned.minute !== minute\n ) {\n continue; // Skip DST gap times\n }\n\n return candidateUtcMs;\n }\n }\n }\n\n throw new Error('Failed to compute next cron fire time within 1 year');\n}\n\n/**\n * Compute next fire time using built-in simple parser\n */\nfunction computeNextFireAtMsSimple(input: {\n cron: string;\n timezone?: string;\n fromMs: UnixMillis;\n}): UnixMillis {\n const parsed = parseSimpleCron(input.cron);\n\n if (input.timezone) {\n return computeNextFireAtMsZoned(parsed, input.fromMs, input.timezone);\n }\n\n return computeNextFireAtMsLocal(parsed, input.fromMs);\n}\n\n/**\n * Default compute next fire time function\n * Uses simple built-in parser\n */\nfunction defaultComputeNextFireAtMs(input: {\n cron: string;\n timezone?: string;\n fromMs: UnixMillis;\n}): UnixMillis {\n return computeNextFireAtMsSimple(input);\n}\n\n// ==================== Handler Implementation ====================\n\n/**\n * Create cron trigger handler factory\n */\nexport function createCronTriggerHandlerFactory(\n deps?: CronTriggerHandlerDeps,\n): TriggerHandlerFactory<'cron'> {\n return (fireCallback) => createCronTriggerHandler(fireCallback, deps);\n}\n\n/**\n * Create cron trigger handler\n */\nexport function createCronTriggerHandler(\n fireCallback: TriggerFireCallback,\n deps?: CronTriggerHandlerDeps,\n): TriggerHandler<'cron'> {\n const logger = deps?.logger ?? console;\n const now = deps?.now ?? (() => Date.now());\n const computeNextFireAtMs: ComputeNextFireAtMs =\n deps?.computeNextFireAtMs ?? defaultComputeNextFireAtMs;\n\n const installed = new Map();\n const versions = new Map();\n let listening = false;\n\n /**\n * Bump version to invalidate pending operations\n */\n function bumpVersion(triggerId: TriggerId): number {\n const next = (versions.get(triggerId) ?? 0) + 1;\n versions.set(triggerId, next);\n return next;\n }\n\n /**\n * Clear alarm by name\n */\n async function clearAlarmByName(name: string): Promise {\n if (!chrome.alarms?.clear) return;\n try {\n await Promise.resolve(chrome.alarms.clear(name));\n } catch (e) {\n logger.debug('[CronTriggerHandler] alarms.clear failed:', e);\n }\n }\n\n /**\n * Clear all cron alarms\n */\n async function clearAllCronAlarms(): Promise {\n if (!chrome.alarms?.getAll || !chrome.alarms?.clear) return;\n try {\n const alarms = await Promise.resolve(chrome.alarms.getAll());\n const list = Array.isArray(alarms) ? alarms : [];\n await Promise.all(\n list\n .filter((a) => a?.name && a.name.startsWith(ALARM_PREFIX))\n .map((a) => clearAlarmByName(a.name)),\n );\n } catch (e) {\n logger.debug('[CronTriggerHandler] alarms.getAll failed:', e);\n }\n }\n\n /**\n * Schedule next alarm for trigger\n */\n async function scheduleNext(triggerId: TriggerId, expectedVersion: number): Promise {\n if (!chrome.alarms?.create) {\n logger.warn('[CronTriggerHandler] chrome.alarms.create is unavailable');\n return;\n }\n\n const entry = installed.get(triggerId);\n if (!entry || entry.version !== expectedVersion) return;\n\n const fromMs = now();\n const nextMs = await Promise.resolve(\n computeNextFireAtMs({\n cron: entry.spec.cron,\n timezone: entry.timezone,\n fromMs,\n }),\n );\n\n // Check version again after async\n if (installed.get(triggerId)?.version !== expectedVersion) return;\n\n const name = alarmNameForTrigger(triggerId);\n await Promise.resolve(chrome.alarms.create(name, { when: nextMs }));\n }\n\n /**\n * Handle alarm event\n */\n const onAlarm = (alarm: chrome.alarms.Alarm): void => {\n const triggerId = parseTriggerIdFromAlarmName(alarm?.name ?? '');\n if (!triggerId) return;\n\n const entry = installed.get(triggerId);\n if (!entry) return;\n\n const expectedVersion = entry.version;\n\n void (async () => {\n try {\n await fireCallback.onFire(triggerId, {\n sourceTabId: undefined,\n sourceUrl: undefined,\n });\n } catch (e) {\n logger.error(`[CronTriggerHandler] onFire failed for trigger \"${triggerId}\":`, e);\n } finally {\n // Reschedule if still valid\n // eslint-disable-next-line no-unsafe-finally\n if (installed.get(triggerId)?.version !== expectedVersion) return;\n try {\n await scheduleNext(triggerId, expectedVersion);\n } catch (e) {\n logger.error(`[CronTriggerHandler] Failed to reschedule trigger \"${triggerId}\":`, e);\n }\n }\n })();\n };\n\n function ensureListening(): void {\n if (listening) return;\n if (!chrome.alarms?.onAlarm?.addListener) {\n logger.warn('[CronTriggerHandler] chrome.alarms.onAlarm is unavailable');\n return;\n }\n chrome.alarms.onAlarm.addListener(onAlarm);\n listening = true;\n }\n\n function stopListening(): void {\n if (!listening) return;\n try {\n chrome.alarms.onAlarm.removeListener(onAlarm);\n } catch (e) {\n logger.debug('[CronTriggerHandler] alarms.onAlarm.removeListener failed:', e);\n } finally {\n listening = false;\n }\n }\n\n return {\n kind: 'cron',\n\n async install(trigger: CronTriggerSpec): Promise {\n const cron = normalizeCronExpression(trigger.cron);\n const timezone = normalizeTimezone(trigger.timezone);\n\n const version = bumpVersion(trigger.id);\n installed.set(trigger.id, {\n spec: { ...trigger, cron },\n timezone,\n version,\n });\n\n ensureListening();\n await scheduleNext(trigger.id, version);\n },\n\n async uninstall(triggerId: string): Promise {\n const id = triggerId as TriggerId;\n bumpVersion(id);\n installed.delete(id);\n await clearAlarmByName(alarmNameForTrigger(id));\n\n if (installed.size === 0) {\n stopListening();\n }\n },\n\n async uninstallAll(): Promise {\n for (const id of installed.keys()) bumpVersion(id);\n installed.clear();\n await clearAllCronAlarms();\n stopListening();\n },\n\n getInstalledIds(): string[] {\n return Array.from(installed.keys());\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/dom-trigger.ts", "content": "/**\n * @fileoverview DOM Trigger Handler (P4-06)\n * @description\n * Bridges DOM triggers to a content-script MutationObserver (`inject-scripts/dom-observer.js`).\n *\n * Contract:\n * - Background -> content: { action: 'set_dom_triggers', triggers: [...] }\n * - Content -> background: { action: 'dom_trigger_fired', triggerId, url }\n * - Ping: { action: 'dom_observer_ping' } -> { status:'pong' }\n *\n * Design notes:\n * - Reuses existing V2 dom observer script for consistency and auditability.\n * - Single handler instance manages multiple triggers.\n * - Sync is coalesced to avoid storms during TriggerManager.refresh().\n * - Top-frame only (no frameId in TriggerFireContext).\n */\n\nimport type { TriggerId } from '../../domain/ids';\nimport type { TriggerSpecByKind } from '../../domain/triggers';\nimport { CONTENT_MESSAGE_TYPES, TOOL_MESSAGE_TYPES } from '../../../../../common/message-types';\nimport type { TriggerFireCallback, TriggerHandler, TriggerHandlerFactory } from './trigger-handler';\n\n// ==================== Types ====================\n\nexport interface DomTriggerHandlerDeps {\n logger?: Pick;\n}\n\ntype DomTriggerSpec = TriggerSpecByKind<'dom'>;\n\n/**\n * Payload sent to dom-observer content script\n */\ninterface DomObserverTriggerPayload {\n id: string;\n selector: string;\n appear: boolean;\n once: boolean;\n debounceMs: number;\n}\n\n/**\n * Message received when DOM trigger fires\n */\ninterface DomTriggerFiredMessage {\n action: string;\n triggerId: string;\n url?: string;\n}\n\n// ==================== Constants ====================\n\nconst DOM_OBSERVER_SCRIPT_FILE = 'inject-scripts/dom-observer.js';\nconst DEFAULT_DEBOUNCE_MS = 800;\n\n// ==================== Utilities ====================\n\nfunction normalizeDebounceMs(value: unknown): number {\n if (value === undefined || value === null) return DEFAULT_DEBOUNCE_MS;\n if (typeof value !== 'number' || !Number.isFinite(value)) return DEFAULT_DEBOUNCE_MS;\n return Math.max(0, Math.floor(value));\n}\n\n/**\n * Build payload for dom-observer content script\n */\nfunction buildDomObserverPayload(\n installed: Map,\n): DomObserverTriggerPayload[] {\n const out: DomObserverTriggerPayload[] = [];\n\n for (const t of installed.values()) {\n const selector = String(t.selector ?? '').trim();\n if (!selector) continue;\n\n out.push({\n id: t.id,\n selector,\n appear: t.appear !== false, // default true\n once: t.once !== false, // default true\n debounceMs: normalizeDebounceMs(t.debounceMs),\n });\n }\n\n // Deterministic ordering for tests and debugging\n out.sort((a, b) => a.id.localeCompare(b.id));\n return out;\n}\n\n/**\n * Check if URL is injectable (http/https/file)\n */\nfunction isInjectableUrl(url: string): boolean {\n return /^(https?:|file:)/i.test(url);\n}\n\n/**\n * Type guard for DOM trigger fired message\n */\nfunction isDomTriggerFiredMessage(msg: unknown): msg is DomTriggerFiredMessage {\n if (!msg || typeof msg !== 'object') return false;\n const anyMsg = msg as Record;\n return (\n anyMsg.action === TOOL_MESSAGE_TYPES.DOM_TRIGGER_FIRED && typeof anyMsg.triggerId === 'string'\n );\n}\n\n// ==================== Handler Implementation ====================\n\n/**\n * Create DOM trigger handler factory\n */\nexport function createDomTriggerHandlerFactory(\n deps?: DomTriggerHandlerDeps,\n): TriggerHandlerFactory<'dom'> {\n return (fireCallback) => createDomTriggerHandler(fireCallback, deps);\n}\n\n/**\n * Create DOM trigger handler\n */\nexport function createDomTriggerHandler(\n fireCallback: TriggerFireCallback,\n deps?: DomTriggerHandlerDeps,\n): TriggerHandler<'dom'> {\n const logger = deps?.logger ?? console;\n\n const installed = new Map();\n\n // Payload cache for efficiency\n let payloadDirty = true;\n let payloadCache: DomObserverTriggerPayload[] = [];\n\n // Listener states\n let messageListening = false;\n let navigationListening = false;\n\n // Coalesce sync to avoid storms (e.g. TriggerManager.refresh)\n let syncPromise: Promise | null = null;\n let pendingSync = false;\n\n function markPayloadDirty(): void {\n payloadDirty = true;\n }\n\n function getPayload(): DomObserverTriggerPayload[] {\n if (!payloadDirty) return payloadCache;\n payloadCache = buildDomObserverPayload(installed);\n payloadDirty = false;\n return payloadCache;\n }\n\n /**\n * Ping dom-observer to check if injected\n */\n async function pingDomObserver(tabId: number): Promise {\n try {\n const resp = await chrome.tabs.sendMessage(tabId, {\n action: CONTENT_MESSAGE_TYPES.DOM_OBSERVER_PING,\n });\n return (resp as { status?: string } | undefined)?.status === 'pong';\n } catch {\n return false;\n }\n }\n\n /**\n * Inject dom-observer script if not present\n */\n async function ensureDomObserverInjected(tabId: number): Promise {\n const ok = await pingDomObserver(tabId);\n if (ok) return;\n\n if (!chrome.scripting?.executeScript) {\n logger.warn('[DomTriggerHandler] chrome.scripting.executeScript is unavailable');\n return;\n }\n\n try {\n await chrome.scripting.executeScript({\n target: { tabId },\n files: [DOM_OBSERVER_SCRIPT_FILE],\n world: 'ISOLATED',\n });\n } catch (e) {\n // Best-effort: injection can fail on restricted pages (chrome://, etc.)\n logger.debug('[DomTriggerHandler] executeScript failed:', e);\n }\n }\n\n /**\n * Send triggers to dom-observer\n */\n async function setDomTriggers(\n tabId: number,\n triggers: DomObserverTriggerPayload[],\n ): Promise {\n try {\n await chrome.tabs.sendMessage(tabId, {\n action: TOOL_MESSAGE_TYPES.SET_DOM_TRIGGERS,\n triggers,\n });\n } catch (e) {\n // No receiver / restricted pages are expected; keep best-effort.\n logger.debug('[DomTriggerHandler] set_dom_triggers sendMessage failed:', e);\n }\n }\n\n /**\n * Sync triggers to a single tab\n */\n async function syncTab(tabId: number, url: string | undefined): Promise {\n if (typeof url === 'string' && url && !isInjectableUrl(url)) return;\n\n const payload = getPayload();\n if (payload.length > 0) {\n await ensureDomObserverInjected(tabId);\n }\n await setDomTriggers(tabId, payload);\n }\n\n /**\n * Sync triggers to all tabs\n */\n async function doSyncAllTabs(): Promise {\n if (!chrome.tabs?.query) {\n logger.warn('[DomTriggerHandler] chrome.tabs.query is unavailable');\n return;\n }\n\n let tabs: chrome.tabs.Tab[] = [];\n try {\n tabs = await chrome.tabs.query({});\n } catch (e) {\n logger.debug('[DomTriggerHandler] tabs.query failed:', e);\n return;\n }\n\n await Promise.all(\n tabs\n .filter((t) => typeof t.id === 'number')\n .filter((t) => (typeof t.url === 'string' ? isInjectableUrl(t.url) : true))\n .map((t) => syncTab(t.id as number, t.url)),\n );\n }\n\n /**\n * Request sync (coalesced)\n */\n async function requestSyncAllTabs(): Promise {\n pendingSync = true;\n if (!syncPromise) {\n syncPromise = (async () => {\n while (pendingSync) {\n pendingSync = false;\n await doSyncAllTabs();\n }\n })().finally(() => {\n syncPromise = null;\n });\n }\n return syncPromise;\n }\n\n /**\n * Handle runtime message (dom_trigger_fired)\n */\n const onRuntimeMessage = (\n message: unknown,\n sender: chrome.runtime.MessageSender,\n sendResponse: (response?: unknown) => void,\n ): boolean => {\n if (!isDomTriggerFiredMessage(message)) return false;\n\n const triggerId = message.triggerId as TriggerId;\n if (!installed.has(triggerId)) {\n try {\n sendResponse({ ok: false });\n } catch {\n // ignore\n }\n return false;\n }\n\n const sourceTabId = sender.tab?.id;\n const sourceUrl = message.url ?? sender.tab?.url;\n\n // Fire-and-forget: do not block chrome messaging thread\n Promise.resolve(fireCallback.onFire(triggerId, { sourceTabId, sourceUrl })).catch((e) => {\n logger.error(`[DomTriggerHandler] onFire failed for trigger \"${triggerId}\":`, e);\n });\n\n try {\n sendResponse({ ok: true });\n } catch {\n // ignore\n }\n return false;\n };\n\n /**\n * Handle navigation completed (re-sync triggers to tab)\n */\n const onNavigationCompleted = (\n details: chrome.webNavigation.WebNavigationFramedCallbackDetails,\n ): void => {\n if (details.frameId !== 0) return; // Top frame only\n if (installed.size === 0) return;\n if (typeof details.url === 'string' && details.url && !isInjectableUrl(details.url)) return;\n\n void syncTab(details.tabId, details.url).catch((e) => {\n logger.debug('[DomTriggerHandler] syncTab on navigation failed:', e);\n });\n };\n\n function ensureMessageListening(): void {\n if (messageListening) return;\n if (!chrome.runtime?.onMessage?.addListener) {\n logger.warn('[DomTriggerHandler] chrome.runtime.onMessage is unavailable');\n return;\n }\n chrome.runtime.onMessage.addListener(onRuntimeMessage);\n messageListening = true;\n }\n\n function stopMessageListening(): void {\n if (!messageListening) return;\n try {\n chrome.runtime.onMessage.removeListener(onRuntimeMessage);\n } catch (e) {\n logger.debug('[DomTriggerHandler] runtime.onMessage.removeListener failed:', e);\n } finally {\n messageListening = false;\n }\n }\n\n function ensureNavigationListening(): void {\n if (navigationListening) return;\n if (!chrome.webNavigation?.onCompleted?.addListener) {\n logger.warn('[DomTriggerHandler] chrome.webNavigation.onCompleted is unavailable');\n return;\n }\n chrome.webNavigation.onCompleted.addListener(onNavigationCompleted);\n navigationListening = true;\n }\n\n function stopNavigationListening(): void {\n if (!navigationListening) return;\n try {\n chrome.webNavigation.onCompleted.removeListener(onNavigationCompleted);\n } catch (e) {\n logger.debug('[DomTriggerHandler] webNavigation.onCompleted.removeListener failed:', e);\n } finally {\n navigationListening = false;\n }\n }\n\n return {\n kind: 'dom',\n\n async install(trigger: DomTriggerSpec): Promise {\n installed.set(trigger.id, trigger);\n markPayloadDirty();\n\n // Ensure listeners are ready before pushing triggers\n ensureMessageListening();\n ensureNavigationListening();\n\n await requestSyncAllTabs();\n },\n\n async uninstall(triggerId: string): Promise {\n installed.delete(triggerId as TriggerId);\n markPayloadDirty();\n\n await requestSyncAllTabs();\n\n if (installed.size === 0) {\n stopNavigationListening();\n stopMessageListening();\n }\n },\n\n async uninstallAll(): Promise {\n installed.clear();\n markPayloadDirty();\n\n await requestSyncAllTabs();\n\n stopNavigationListening();\n stopMessageListening();\n },\n\n getInstalledIds(): string[] {\n return Array.from(installed.keys());\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/index.ts", "content": "/**\n * @fileoverview Triggers 模块导出入口\n */\n\nexport * from './trigger-handler';\nexport * from './trigger-manager';\nexport * from './url-trigger';\nexport * from './command-trigger';\nexport * from './context-menu-trigger';\nexport * from './dom-trigger';\nexport * from './cron-trigger';\nexport * from './manual-trigger';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/interval-trigger.ts", "content": "/**\n * @fileoverview Interval Trigger Handler (M3.1)\n * @description\n * 使用 chrome.alarms 的 periodInMinutes 实现固定间隔触发。\n *\n * 策略：\n * - 每个触发器对应一个重复 alarm\n * - 使用 delayInMinutes 使首次触发在配置的间隔后\n */\n\nimport type { TriggerId } from '../../domain/ids';\nimport type { TriggerSpecByKind } from '../../domain/triggers';\nimport type { TriggerFireCallback, TriggerHandler, TriggerHandlerFactory } from './trigger-handler';\n\n// ==================== Types ====================\n\ntype IntervalTriggerSpec = TriggerSpecByKind<'interval'>;\n\nexport interface IntervalTriggerHandlerDeps {\n logger?: Pick;\n}\n\ninterface InstalledIntervalTrigger {\n spec: IntervalTriggerSpec;\n periodMinutes: number;\n version: number;\n}\n\n// ==================== Constants ====================\n\nconst ALARM_PREFIX = 'rr_v3_interval_';\n\n// ==================== Utilities ====================\n\n/**\n * 校验并规范化 periodMinutes\n */\nfunction normalizePeriodMinutes(value: unknown): number {\n if (typeof value !== 'number' || !Number.isFinite(value)) {\n throw new Error('periodMinutes must be a finite number');\n }\n if (value < 1) {\n throw new Error('periodMinutes must be >= 1');\n }\n return value;\n}\n\n/**\n * 生成 alarm 名称\n */\nfunction alarmNameForTrigger(triggerId: TriggerId): string {\n return `${ALARM_PREFIX}${triggerId}`;\n}\n\n/**\n * 从 alarm 名称解析 triggerId\n */\nfunction parseTriggerIdFromAlarmName(name: string): TriggerId | null {\n if (!name.startsWith(ALARM_PREFIX)) return null;\n const id = name.slice(ALARM_PREFIX.length);\n return id ? (id as TriggerId) : null;\n}\n\n// ==================== Handler Implementation ====================\n\n/**\n * 创建 interval 触发器处理器工厂\n */\nexport function createIntervalTriggerHandlerFactory(\n deps?: IntervalTriggerHandlerDeps,\n): TriggerHandlerFactory<'interval'> {\n return (fireCallback) => createIntervalTriggerHandler(fireCallback, deps);\n}\n\n/**\n * 创建 interval 触发器处理器\n */\nexport function createIntervalTriggerHandler(\n fireCallback: TriggerFireCallback,\n deps?: IntervalTriggerHandlerDeps,\n): TriggerHandler<'interval'> {\n const logger = deps?.logger ?? console;\n\n const installed = new Map();\n const versions = new Map();\n let listening = false;\n\n /**\n * 递增版本号以使挂起的操作失效\n */\n function bumpVersion(triggerId: TriggerId): number {\n const next = (versions.get(triggerId) ?? 0) + 1;\n versions.set(triggerId, next);\n return next;\n }\n\n /**\n * 清除指定 alarm\n */\n async function clearAlarmByName(name: string): Promise {\n if (!chrome.alarms?.clear) return;\n try {\n await Promise.resolve(chrome.alarms.clear(name));\n } catch (e) {\n logger.debug('[IntervalTriggerHandler] alarms.clear failed:', e);\n }\n }\n\n /**\n * 清除所有 interval alarms\n */\n async function clearAllIntervalAlarms(): Promise {\n if (!chrome.alarms?.getAll || !chrome.alarms?.clear) return;\n try {\n const alarms = await Promise.resolve(chrome.alarms.getAll());\n const list = Array.isArray(alarms) ? alarms : [];\n await Promise.all(\n list.filter((a) => a?.name?.startsWith(ALARM_PREFIX)).map((a) => clearAlarmByName(a.name)),\n );\n } catch (e) {\n logger.debug('[IntervalTriggerHandler] alarms.getAll failed:', e);\n }\n }\n\n /**\n * 调度 alarm\n */\n async function schedule(triggerId: TriggerId, expectedVersion: number): Promise {\n if (!chrome.alarms?.create) {\n logger.warn('[IntervalTriggerHandler] chrome.alarms.create is unavailable');\n return;\n }\n\n const entry = installed.get(triggerId);\n if (!entry || entry.version !== expectedVersion) return;\n\n const name = alarmNameForTrigger(triggerId);\n const periodInMinutes = entry.periodMinutes;\n\n try {\n // 使用 delayInMinutes 和 periodInMinutes 创建重复 alarm\n // 首次触发在 periodInMinutes 后，之后每隔 periodInMinutes 触发\n await Promise.resolve(\n chrome.alarms.create(name, {\n delayInMinutes: periodInMinutes,\n periodInMinutes,\n }),\n );\n } catch (e) {\n logger.error(`[IntervalTriggerHandler] alarms.create failed for trigger \"${triggerId}\":`, e);\n }\n }\n\n /**\n * Alarm 事件处理\n */\n const onAlarm = (alarm: chrome.alarms.Alarm): void => {\n const triggerId = parseTriggerIdFromAlarmName(alarm?.name ?? '');\n if (!triggerId) return;\n\n const entry = installed.get(triggerId);\n if (!entry) return;\n\n // 触发回调\n Promise.resolve(\n fireCallback.onFire(triggerId, {\n sourceTabId: undefined,\n sourceUrl: undefined,\n }),\n ).catch((e) => {\n logger.error(`[IntervalTriggerHandler] onFire failed for trigger \"${triggerId}\":`, e);\n });\n };\n\n /**\n * 确保正在监听 alarm 事件\n */\n function ensureListening(): void {\n if (listening) return;\n if (!chrome.alarms?.onAlarm?.addListener) {\n logger.warn('[IntervalTriggerHandler] chrome.alarms.onAlarm is unavailable');\n return;\n }\n chrome.alarms.onAlarm.addListener(onAlarm);\n listening = true;\n }\n\n /**\n * 停止监听 alarm 事件\n */\n function stopListening(): void {\n if (!listening) return;\n try {\n chrome.alarms.onAlarm.removeListener(onAlarm);\n } catch (e) {\n logger.debug('[IntervalTriggerHandler] removeListener failed:', e);\n } finally {\n listening = false;\n }\n }\n\n return {\n kind: 'interval',\n\n async install(trigger: IntervalTriggerSpec): Promise {\n const periodMinutes = normalizePeriodMinutes(trigger.periodMinutes);\n\n const version = bumpVersion(trigger.id);\n installed.set(trigger.id, {\n spec: { ...trigger, periodMinutes },\n periodMinutes,\n version,\n });\n\n ensureListening();\n await schedule(trigger.id, version);\n },\n\n async uninstall(triggerId: string): Promise {\n const id = triggerId as TriggerId;\n bumpVersion(id);\n installed.delete(id);\n await clearAlarmByName(alarmNameForTrigger(id));\n\n if (installed.size === 0) {\n stopListening();\n }\n },\n\n async uninstallAll(): Promise {\n for (const id of installed.keys()) {\n bumpVersion(id);\n }\n installed.clear();\n await clearAllIntervalAlarms();\n stopListening();\n },\n\n getInstalledIds(): string[] {\n return Array.from(installed.keys());\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/manual-trigger.ts", "content": "/**\n * @fileoverview Manual Trigger Handler (P4-08)\n * @description\n * Manual triggers are the simplest trigger type - they don't auto-fire.\n * They're only triggered programmatically via RPC or UI.\n *\n * This handler just tracks installed triggers but doesn't set up any listeners.\n * Manual triggers are fired by calling TriggerManager's fire method directly.\n */\n\nimport type { TriggerId } from '../../domain/ids';\nimport type { TriggerSpecByKind } from '../../domain/triggers';\nimport type { TriggerFireCallback, TriggerHandler, TriggerHandlerFactory } from './trigger-handler';\n\n// ==================== Types ====================\n\nexport interface ManualTriggerHandlerDeps {\n logger?: Pick;\n}\n\ntype ManualTriggerSpec = TriggerSpecByKind<'manual'>;\n\n// ==================== Handler Implementation ====================\n\n/**\n * Create manual trigger handler factory\n */\nexport function createManualTriggerHandlerFactory(\n deps?: ManualTriggerHandlerDeps,\n): TriggerHandlerFactory<'manual'> {\n return (fireCallback) => createManualTriggerHandler(fireCallback, deps);\n}\n\n/**\n * Create manual trigger handler\n *\n * Manual triggers don't auto-fire - they're only triggered via RPC.\n * This handler just tracks which manual triggers are installed.\n */\nexport function createManualTriggerHandler(\n _fireCallback: TriggerFireCallback,\n _deps?: ManualTriggerHandlerDeps,\n): TriggerHandler<'manual'> {\n const installed = new Map();\n\n return {\n kind: 'manual',\n\n async install(trigger: ManualTriggerSpec): Promise {\n installed.set(trigger.id, trigger);\n },\n\n async uninstall(triggerId: string): Promise {\n installed.delete(triggerId as TriggerId);\n },\n\n async uninstallAll(): Promise {\n installed.clear();\n },\n\n getInstalledIds(): string[] {\n return Array.from(installed.keys());\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/once-trigger.ts", "content": "/**\n * @fileoverview Once Trigger Handler (M3.1)\n * @description\n * 使用 chrome.alarms 的 when 参数实现一次性定时触发。\n *\n * 行为：\n * - 每个触发器对应一个一次性 alarm\n * - 触发后自动将触发器禁用 (enabled=false) 并卸载\n */\n\nimport type { UnixMillis } from '../../domain/json';\nimport type { TriggerId } from '../../domain/ids';\nimport type { TriggerSpecByKind } from '../../domain/triggers';\nimport { createTriggersStore } from '../../storage/triggers';\nimport type { TriggerFireCallback, TriggerHandler, TriggerHandlerFactory } from './trigger-handler';\n\n// ==================== Types ====================\n\ntype OnceTriggerSpec = TriggerSpecByKind<'once'>;\n\nexport interface OnceTriggerHandlerDeps {\n logger?: Pick;\n /**\n * 可选：自定义禁用触发器的方法\n * 如果未提供，将直接更新 TriggerStore\n */\n disableTrigger?: (triggerId: TriggerId) => Promise;\n}\n\ninterface InstalledOnceTrigger {\n spec: OnceTriggerSpec;\n whenMs: UnixMillis;\n version: number;\n}\n\n// ==================== Constants ====================\n\nconst ALARM_PREFIX = 'rr_v3_once_';\n\n// ==================== Utilities ====================\n\n/**\n * 校验并规范化 whenMs\n */\nfunction normalizeWhenMs(value: unknown): UnixMillis {\n if (typeof value !== 'number' || !Number.isFinite(value)) {\n throw new Error('whenMs must be a finite number');\n }\n return Math.floor(value) as UnixMillis;\n}\n\n/**\n * 生成 alarm 名称\n */\nfunction alarmNameForTrigger(triggerId: TriggerId): string {\n return `${ALARM_PREFIX}${triggerId}`;\n}\n\n/**\n * 从 alarm 名称解析 triggerId\n */\nfunction parseTriggerIdFromAlarmName(name: string): TriggerId | null {\n if (!name.startsWith(ALARM_PREFIX)) return null;\n const id = name.slice(ALARM_PREFIX.length);\n return id ? (id as TriggerId) : null;\n}\n\n// ==================== Handler Implementation ====================\n\n/**\n * 创建 once 触发器处理器工厂\n */\nexport function createOnceTriggerHandlerFactory(\n deps?: OnceTriggerHandlerDeps,\n): TriggerHandlerFactory<'once'> {\n return (fireCallback) => createOnceTriggerHandler(fireCallback, deps);\n}\n\n/**\n * 创建 once 触发器处理器\n */\nexport function createOnceTriggerHandler(\n fireCallback: TriggerFireCallback,\n deps?: OnceTriggerHandlerDeps,\n): TriggerHandler<'once'> {\n const logger = deps?.logger ?? console;\n\n // 延迟创建 store，避免在测试环境中出问题\n let triggersStore: ReturnType | null = null;\n const getTriggersStore = () => {\n if (!triggersStore) {\n triggersStore = createTriggersStore();\n }\n return triggersStore;\n };\n\n const disableTrigger =\n deps?.disableTrigger ??\n (async (triggerId: TriggerId) => {\n const store = getTriggersStore();\n const existing = await store.get(triggerId);\n if (!existing) return;\n if (!existing.enabled) return;\n await store.save({ ...existing, enabled: false });\n });\n\n const installed = new Map();\n const versions = new Map();\n let listening = false;\n\n /**\n * 递增版本号以使挂起的操作失效\n */\n function bumpVersion(triggerId: TriggerId): number {\n const next = (versions.get(triggerId) ?? 0) + 1;\n versions.set(triggerId, next);\n return next;\n }\n\n /**\n * 清除指定 alarm\n */\n async function clearAlarmByName(name: string): Promise {\n if (!chrome.alarms?.clear) return;\n try {\n await Promise.resolve(chrome.alarms.clear(name));\n } catch (e) {\n logger.debug('[OnceTriggerHandler] alarms.clear failed:', e);\n }\n }\n\n /**\n * 清除所有 once alarms\n */\n async function clearAllOnceAlarms(): Promise {\n if (!chrome.alarms?.getAll || !chrome.alarms?.clear) return;\n try {\n const alarms = await Promise.resolve(chrome.alarms.getAll());\n const list = Array.isArray(alarms) ? alarms : [];\n await Promise.all(\n list.filter((a) => a?.name?.startsWith(ALARM_PREFIX)).map((a) => clearAlarmByName(a.name)),\n );\n } catch (e) {\n logger.debug('[OnceTriggerHandler] alarms.getAll failed:', e);\n }\n }\n\n /**\n * 调度 alarm\n */\n async function schedule(triggerId: TriggerId, expectedVersion: number): Promise {\n if (!chrome.alarms?.create) {\n logger.warn('[OnceTriggerHandler] chrome.alarms.create is unavailable');\n return;\n }\n\n const entry = installed.get(triggerId);\n if (!entry || entry.version !== expectedVersion) return;\n\n const name = alarmNameForTrigger(triggerId);\n\n try {\n await Promise.resolve(chrome.alarms.create(name, { when: entry.whenMs }));\n } catch (e) {\n logger.error(`[OnceTriggerHandler] alarms.create failed for trigger \"${triggerId}\":`, e);\n }\n }\n\n /**\n * 内部卸载逻辑（不触发外部 uninstall）\n */\n async function uninstallInternal(triggerId: TriggerId): Promise {\n bumpVersion(triggerId);\n installed.delete(triggerId);\n await clearAlarmByName(alarmNameForTrigger(triggerId));\n\n if (installed.size === 0) {\n stopListening();\n }\n }\n\n /**\n * Alarm 事件处理\n */\n const onAlarm = (alarm: chrome.alarms.Alarm): void => {\n const triggerId = parseTriggerIdFromAlarmName(alarm?.name ?? '');\n if (!triggerId) return;\n\n const entry = installed.get(triggerId);\n if (!entry) return;\n\n const expectedVersion = entry.version;\n\n void (async () => {\n try {\n await fireCallback.onFire(triggerId, {\n sourceTabId: undefined,\n sourceUrl: undefined,\n });\n } catch (e) {\n logger.error(`[OnceTriggerHandler] onFire failed for trigger \"${triggerId}\":`, e);\n } finally {\n // 检查版本是否仍然有效\n if (installed.get(triggerId)?.version === expectedVersion) {\n // 禁用触发器\n try {\n await disableTrigger(triggerId);\n } catch (e) {\n logger.error(\n `[OnceTriggerHandler] Failed to disable trigger \"${triggerId}\" after fire:`,\n e,\n );\n }\n\n // 卸载触发器\n try {\n await uninstallInternal(triggerId);\n } catch (e) {\n logger.error(\n `[OnceTriggerHandler] Failed to uninstall trigger \"${triggerId}\" after fire:`,\n e,\n );\n }\n }\n }\n })();\n };\n\n /**\n * 确保正在监听 alarm 事件\n */\n function ensureListening(): void {\n if (listening) return;\n if (!chrome.alarms?.onAlarm?.addListener) {\n logger.warn('[OnceTriggerHandler] chrome.alarms.onAlarm is unavailable');\n return;\n }\n chrome.alarms.onAlarm.addListener(onAlarm);\n listening = true;\n }\n\n /**\n * 停止监听 alarm 事件\n */\n function stopListening(): void {\n if (!listening) return;\n try {\n chrome.alarms.onAlarm.removeListener(onAlarm);\n } catch (e) {\n logger.debug('[OnceTriggerHandler] removeListener failed:', e);\n } finally {\n listening = false;\n }\n }\n\n return {\n kind: 'once',\n\n async install(trigger: OnceTriggerSpec): Promise {\n const whenMs = normalizeWhenMs(trigger.whenMs);\n\n const version = bumpVersion(trigger.id);\n installed.set(trigger.id, {\n spec: { ...trigger, whenMs },\n whenMs,\n version,\n });\n\n ensureListening();\n await schedule(trigger.id, version);\n },\n\n async uninstall(triggerId: string): Promise {\n await uninstallInternal(triggerId as TriggerId);\n },\n\n async uninstallAll(): Promise {\n for (const id of installed.keys()) {\n bumpVersion(id);\n }\n installed.clear();\n await clearAllOnceAlarms();\n stopListening();\n },\n\n getInstalledIds(): string[] {\n return Array.from(installed.keys());\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/trigger-handler.ts", "content": "/**\n * @fileoverview 触发器处理器接口定义\n * @description 定义各类触发器的统一接口\n */\n\nimport type { TriggerSpec, TriggerKind } from '../../domain/triggers';\n\n/**\n * 触发器处理器接口\n * @description 每种触发器类型需要实现此接口\n */\nexport interface TriggerHandler {\n /** 触发器类型 */\n readonly kind: K;\n\n /**\n * 安装触发器\n * @description 注册 chrome API 监听器等\n * @param trigger 触发器规范\n */\n install(trigger: Extract): Promise;\n\n /**\n * 卸载触发器\n * @description 移除 chrome API 监听器等\n * @param triggerId 触发器 ID\n */\n uninstall(triggerId: string): Promise;\n\n /**\n * 卸载所有触发器\n * @description 清理所有此类型的触发器\n */\n uninstallAll(): Promise;\n\n /**\n * 获取已安装的触发器 ID 列表\n */\n getInstalledIds(): string[];\n}\n\n/**\n * 触发器触发回调\n * @description TriggerManager 注入给各 Handler 的回调\n */\nexport interface TriggerFireCallback {\n /**\n * 触发器被触发时调用\n * @param triggerId 触发器 ID\n * @param context 触发上下文\n */\n onFire(\n triggerId: string,\n context: {\n sourceTabId?: number;\n sourceUrl?: string;\n },\n ): Promise;\n}\n\n/**\n * 触发器处理器工厂\n */\nexport type TriggerHandlerFactory = (\n fireCallback: TriggerFireCallback,\n) => TriggerHandler;\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/trigger-manager.ts", "content": "/**\n * @fileoverview 触发器管理器\n * @description\n * TriggerManager 负责管理所有触发器 Handler 的生命周期：\n * - 从 TriggerStore 加载触发器并安装\n * - 处理触发器触发事件，调用 enqueueRun\n * - 提供防风暴机制 (cooldown + maxQueued)\n *\n * 设计理由：\n * - Orchestrator 模式：TriggerManager 不直接实现各类触发器逻辑，而是委托给 per-kind Handler\n * - Handler 工厂模式：TriggerManager 在构造时创建 Handler 实例，注入 fireCallback\n * - 防风暴：cooldown (per-trigger) + maxQueued (global best-effort)\n */\n\nimport type { UnixMillis } from '../../domain/json';\nimport type { RunId, TriggerId } from '../../domain/ids';\nimport type { TriggerFireContext, TriggerKind, TriggerSpec } from '../../domain/triggers';\nimport type { StoragePort } from '../storage/storage-port';\nimport type { EventsBus } from '../transport/events-bus';\nimport type { RunScheduler } from '../queue/scheduler';\nimport { enqueueRun, type EnqueueRunResult } from '../queue/enqueue-run';\nimport type { TriggerFireCallback, TriggerHandler, TriggerHandlerFactory } from './trigger-handler';\n\n// ==================== Types ====================\n\n/**\n * Handler 工厂映射\n */\nexport type TriggerHandlerFactories = Partial<{\n [K in TriggerKind]: TriggerHandlerFactory;\n}>;\n\n/**\n * 防风暴配置\n */\nexport interface TriggerManagerStormControl {\n /**\n * 同一触发器两次触发之间的最小间隔 (ms)\n * - 0 或 undefined 表示禁用冷却\n */\n cooldownMs?: number;\n\n /**\n * 全局最大排队 Run 数量\n * - 达到上限时拒绝新的触发\n * - undefined 表示禁用上限检查\n * - 注意：这是 best-effort 检查，非原子性\n */\n maxQueued?: number;\n}\n\n/**\n * TriggerManager 依赖\n */\nexport interface TriggerManagerDeps {\n /** 存储层 */\n storage: Pick;\n /** 事件总线 */\n events: Pick;\n /** 调度器 (可选) */\n scheduler?: Pick;\n /** Handler 工厂映射 */\n handlerFactories: TriggerHandlerFactories;\n /** 防风暴配置 */\n storm?: TriggerManagerStormControl;\n /** RunId 生成器 (用于测试注入) */\n generateRunId?: () => RunId;\n /** 时间源 (用于测试注入) */\n now?: () => UnixMillis;\n /** 日志器 */\n logger?: Pick;\n}\n\n/**\n * TriggerManager 状态\n */\nexport interface TriggerManagerState {\n /** 是否已启动 */\n started: boolean;\n /** 已安装的触发器 ID 列表 */\n installedTriggerIds: TriggerId[];\n}\n\n/**\n * TriggerManager 接口\n */\nexport interface TriggerManager {\n /** 启动管理器，加载并安装所有启用的触发器 */\n start(): Promise;\n /** 停止管理器，卸载所有触发器 */\n stop(): Promise;\n /** 刷新触发器，重新从存储加载并安装 */\n refresh(): Promise;\n /**\n * 手动触发一个触发器\n * @description 仅供 RPC/UI 调用，用于 manual 触发器\n */\n fire(\n triggerId: TriggerId,\n context?: { sourceTabId?: number; sourceUrl?: string },\n ): Promise;\n /** 销毁管理器 */\n dispose(): Promise;\n /** 获取当前状态 */\n getState(): TriggerManagerState;\n}\n\n// ==================== Utilities ====================\n\n/**\n * 校验非负整数\n */\nfunction normalizeNonNegativeInt(value: unknown, fallback: number, fieldName: string): number {\n if (value === undefined || value === null) return fallback;\n if (typeof value !== 'number' || !Number.isFinite(value)) {\n throw new Error(`${fieldName} must be a finite number`);\n }\n return Math.max(0, Math.floor(value));\n}\n\n/**\n * 校验正整数\n */\nfunction normalizePositiveInt(value: unknown, fieldName: string): number {\n if (typeof value !== 'number' || !Number.isFinite(value)) {\n throw new Error(`${fieldName} must be a finite number`);\n }\n const intValue = Math.floor(value);\n if (intValue < 1) {\n throw new Error(`${fieldName} must be >= 1`);\n }\n return intValue;\n}\n\n// ==================== Implementation ====================\n\n/**\n * 创建 TriggerManager\n */\nexport function createTriggerManager(deps: TriggerManagerDeps): TriggerManager {\n const logger = deps.logger ?? console;\n const now = deps.now ?? (() => Date.now());\n\n // 防风暴参数\n const cooldownMs = normalizeNonNegativeInt(deps.storm?.cooldownMs, 0, 'storm.cooldownMs');\n const maxQueued =\n deps.storm?.maxQueued === undefined || deps.storm?.maxQueued === null\n ? undefined\n : normalizePositiveInt(deps.storm.maxQueued, 'storm.maxQueued');\n\n // 状态\n const installed = new Map();\n const lastFireAt = new Map();\n let started = false;\n let inFlightEnqueues = 0;\n\n // 防止 refresh 重入\n let refreshPromise: Promise | null = null;\n let pendingRefresh = false;\n\n // Handler 实例\n const handlers = new Map>();\n\n // 触发回调\n const fireCallback: TriggerFireCallback = {\n onFire: async (triggerId, context) => {\n // 捕获所有异常，避免抛入 chrome API 监听器\n try {\n await handleFire(triggerId as TriggerId, context);\n } catch (e) {\n logger.error('[TriggerManager] onFire failed:', e);\n }\n },\n };\n\n // 初始化 Handler 实例\n for (const [kind, factory] of Object.entries(deps.handlerFactories) as Array<\n [TriggerKind, TriggerHandlerFactory | undefined]\n >) {\n if (!factory) continue; // Skip undefined factory values\n\n const handler = factory(fireCallback) as TriggerHandler;\n if (handler.kind !== kind) {\n throw new Error(\n `[TriggerManager] Handler kind mismatch: factory key is \"${kind}\", but handler.kind is \"${handler.kind}\"`,\n );\n }\n handlers.set(kind, handler);\n }\n\n /**\n * 处理触发器触发（内部方法）\n * @param throwOnDrop 如果为 true，则在 cooldown/maxQueued 等情况下抛出错误\n * @returns EnqueueRunResult 或 null（静默丢弃）\n */\n async function handleFire(\n triggerId: TriggerId,\n context: { sourceTabId?: number; sourceUrl?: string },\n options?: { throwOnDrop?: boolean },\n ): Promise {\n if (!started) {\n if (options?.throwOnDrop) {\n throw new Error('TriggerManager is not started');\n }\n return null;\n }\n\n const trigger = installed.get(triggerId);\n if (!trigger) {\n if (options?.throwOnDrop) {\n throw new Error(`Trigger \"${triggerId}\" is not installed`);\n }\n return null;\n }\n\n const t = now();\n\n // Per-trigger cooldown 检查\n const prevLastFireAt = lastFireAt.get(triggerId);\n if (cooldownMs > 0 && prevLastFireAt !== undefined && t - prevLastFireAt < cooldownMs) {\n logger.debug(`[TriggerManager] Dropping trigger \"${triggerId}\" (cooldown ${cooldownMs}ms)`);\n if (options?.throwOnDrop) {\n throw new Error(`Trigger \"${triggerId}\" dropped (cooldown ${cooldownMs}ms)`);\n }\n return null;\n }\n\n // Global maxQueued 检查 (best-effort)\n // 注意：在 cooldown 设置前检查，避免因 maxQueued drop 而误设 cooldown\n if (maxQueued !== undefined) {\n const queued = await deps.storage.queue.list('queued');\n if (queued.length + inFlightEnqueues >= maxQueued) {\n logger.warn(\n `[TriggerManager] Dropping trigger \"${triggerId}\" (queued=${queued.length}, inFlight=${inFlightEnqueues}, maxQueued=${maxQueued})`,\n );\n if (options?.throwOnDrop) {\n throw new Error(`Trigger \"${triggerId}\" dropped (maxQueued=${maxQueued})`);\n }\n return null;\n }\n }\n\n // 设置 lastFireAt 以抑制并发触发（在 maxQueued 检查通过后）\n if (cooldownMs > 0) {\n lastFireAt.set(triggerId, t);\n }\n\n // 构建触发上下文\n const triggerContext: TriggerFireContext = {\n triggerId: trigger.id,\n kind: trigger.kind,\n firedAt: t,\n sourceTabId: context.sourceTabId,\n sourceUrl: context.sourceUrl,\n };\n\n inFlightEnqueues += 1;\n try {\n const result = await enqueueRun(\n {\n storage: deps.storage,\n events: deps.events,\n scheduler: deps.scheduler,\n generateRunId: deps.generateRunId,\n now,\n },\n {\n flowId: trigger.flowId,\n args: trigger.args,\n trigger: triggerContext,\n },\n );\n return result;\n } catch (e) {\n // 入队失败时回滚 cooldown 标记\n if (cooldownMs > 0) {\n if (prevLastFireAt === undefined) {\n lastFireAt.delete(triggerId);\n } else {\n lastFireAt.set(triggerId, prevLastFireAt);\n }\n }\n const msg = e instanceof Error ? e.message : String(e);\n logger.error(`[TriggerManager] enqueueRun failed for trigger \"${triggerId}\":`, e);\n if (options?.throwOnDrop) {\n throw new Error(`enqueueRun failed for trigger \"${triggerId}\": ${msg}`);\n }\n return null;\n } finally {\n inFlightEnqueues -= 1;\n }\n }\n\n /**\n * 手动触发一个触发器（对外暴露）\n * @description 用于 RPC/UI 调用，会抛出错误而不是静默丢弃\n */\n async function fire(\n triggerId: TriggerId,\n context: { sourceTabId?: number; sourceUrl?: string } = {},\n ): Promise {\n const result = await handleFire(triggerId, context, { throwOnDrop: true });\n if (!result) {\n throw new Error(`Trigger \"${triggerId}\" did not enqueue a run`);\n }\n return result;\n }\n\n /**\n * 执行刷新\n */\n async function doRefresh(): Promise {\n const triggers = await deps.storage.triggers.list();\n if (!started) return;\n\n // 先卸载所有，再重新安装 (简单策略，保证一致性)\n // Best-effort: 单个 handler 卸载失败不影响其他\n for (const handler of handlers.values()) {\n try {\n await handler.uninstallAll();\n } catch (e) {\n logger.warn(`[TriggerManager] Error during uninstallAll for kind \"${handler.kind}\":`, e);\n }\n }\n installed.clear();\n\n // 安装启用的触发器\n for (const trigger of triggers) {\n if (!started) return;\n if (!trigger.enabled) continue;\n\n const handler = handlers.get(trigger.kind);\n if (!handler) {\n logger.warn(`[TriggerManager] No handler registered for kind \"${trigger.kind}\"`);\n continue;\n }\n\n try {\n await handler.install(trigger as Parameters[0]);\n installed.set(trigger.id, trigger);\n } catch (e) {\n logger.error(`[TriggerManager] Failed to install trigger \"${trigger.id}\":`, e);\n }\n }\n }\n\n /**\n * 刷新触发器 (合并并发调用)\n */\n async function refresh(): Promise {\n if (!started) {\n throw new Error('TriggerManager is not started');\n }\n\n pendingRefresh = true;\n if (!refreshPromise) {\n refreshPromise = (async () => {\n while (started && pendingRefresh) {\n pendingRefresh = false;\n await doRefresh();\n }\n })().finally(() => {\n refreshPromise = null;\n });\n }\n\n return refreshPromise;\n }\n\n /**\n * 启动管理器\n */\n async function start(): Promise {\n if (started) return;\n started = true;\n await refresh();\n }\n\n /**\n * 停止管理器\n */\n async function stop(): Promise {\n if (!started) return;\n\n started = false;\n pendingRefresh = false;\n\n // 等待进行中的 refresh 完成\n if (refreshPromise) {\n try {\n await refreshPromise;\n } catch {\n // 忽略 refresh 错误\n }\n }\n\n // 卸载所有触发器\n for (const handler of handlers.values()) {\n try {\n await handler.uninstallAll();\n } catch (e) {\n logger.warn('[TriggerManager] Error uninstalling handler:', e);\n }\n }\n installed.clear();\n lastFireAt.clear();\n }\n\n /**\n * 销毁管理器\n */\n async function dispose(): Promise {\n await stop();\n }\n\n /**\n * 获取状态\n */\n function getState(): TriggerManagerState {\n return {\n started,\n installedTriggerIds: Array.from(installed.keys()),\n };\n }\n\n return { start, stop, refresh, fire, dispose, getState };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/engine/triggers/url-trigger.ts", "content": "/**\n * @fileoverview URL Trigger Handler (P4-03)\n * @description\n * Listens to `chrome.webNavigation.onCompleted` and fires installed URL triggers.\n *\n * URL matching semantics:\n * - kind:'url' - Full URL prefix match (allows query/hash variations)\n * - kind:'domain' - Safe subdomain match (hostname === domain OR hostname.endsWith('.' + domain))\n * - kind:'path' - Pathname prefix match\n *\n * Design rationale:\n * - No regex/wildcards for performance and auditability\n * - Domain matching uses safe subdomain logic to avoid false positives (e.g. 'notexample.com')\n * - Single listener instance manages multiple triggers efficiently\n */\n\nimport type { TriggerId } from '../../domain/ids';\nimport type { TriggerSpecByKind, UrlMatchRule } from '../../domain/triggers';\nimport type { TriggerFireCallback, TriggerHandler, TriggerHandlerFactory } from './trigger-handler';\n\n// ==================== Types ====================\n\nexport interface UrlTriggerHandlerDeps {\n logger?: Pick;\n}\n\ntype UrlTriggerSpec = TriggerSpecByKind<'url'>;\n\n/**\n * Compiled URL match rules for efficient matching\n */\ninterface CompiledUrlRules {\n /** Full URL prefixes */\n urlPrefixes: string[];\n /** Normalized domains (lowercase, no leading/trailing dots) */\n domains: string[];\n /** Normalized path prefixes (always starts with '/') */\n pathPrefixes: string[];\n}\n\ninterface InstalledUrlTrigger {\n spec: UrlTriggerSpec;\n rules: CompiledUrlRules;\n}\n\n// ==================== Normalization Utilities ====================\n\n/**\n * Normalize domain value\n * - Trim whitespace\n * - Convert to lowercase\n * - Remove leading/trailing dots\n */\nfunction normalizeDomain(value: string): string | null {\n const normalized = value.trim().toLowerCase().replace(/^\\.+/, '').replace(/\\.+$/, '');\n return normalized || null;\n}\n\n/**\n * Normalize path prefix\n * - Trim whitespace\n * - Ensure starts with '/'\n */\nfunction normalizePathPrefix(value: string): string | null {\n const trimmed = value.trim();\n if (!trimmed) return null;\n return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;\n}\n\n/**\n * Normalize URL prefix\n * - Trim whitespace only\n */\nfunction normalizeUrlPrefix(value: string): string | null {\n const trimmed = value.trim();\n return trimmed || null;\n}\n\n/**\n * Compile URL match rules from spec\n */\nfunction compileUrlMatchRules(match: UrlMatchRule[] | undefined): CompiledUrlRules {\n const urlPrefixes: string[] = [];\n const domains: string[] = [];\n const pathPrefixes: string[] = [];\n\n for (const rule of match ?? []) {\n const { kind } = rule;\n const raw = typeof rule.value === 'string' ? rule.value : String(rule.value ?? '');\n\n switch (kind) {\n case 'url': {\n const normalized = normalizeUrlPrefix(raw);\n if (normalized) urlPrefixes.push(normalized);\n break;\n }\n case 'domain': {\n const normalized = normalizeDomain(raw);\n if (normalized) domains.push(normalized);\n break;\n }\n case 'path': {\n const normalized = normalizePathPrefix(raw);\n if (normalized) pathPrefixes.push(normalized);\n break;\n }\n }\n }\n\n return { urlPrefixes, domains, pathPrefixes };\n}\n\n// ==================== Matching Logic ====================\n\n/**\n * Check if hostname matches domain (exact or subdomain)\n */\nfunction hostnameMatchesDomain(hostname: string, domain: string): boolean {\n if (hostname === domain) return true;\n return hostname.endsWith(`.${domain}`);\n}\n\n/**\n * Check if URL matches any of the compiled rules\n */\nfunction matchesRules(compiled: CompiledUrlRules, urlString: string, parsed: URL): boolean {\n // URL prefix match\n for (const prefix of compiled.urlPrefixes) {\n if (urlString.startsWith(prefix)) return true;\n }\n\n // Domain match\n const hostname = parsed.hostname.toLowerCase();\n for (const domain of compiled.domains) {\n if (hostnameMatchesDomain(hostname, domain)) return true;\n }\n\n // Path prefix match\n const pathname = parsed.pathname || '/';\n for (const prefix of compiled.pathPrefixes) {\n if (pathname.startsWith(prefix)) return true;\n }\n\n return false;\n}\n\n// ==================== Handler Implementation ====================\n\n/**\n * Create URL trigger handler factory\n */\nexport function createUrlTriggerHandlerFactory(\n deps?: UrlTriggerHandlerDeps,\n): TriggerHandlerFactory<'url'> {\n return (fireCallback) => createUrlTriggerHandler(fireCallback, deps);\n}\n\n/**\n * Create URL trigger handler\n */\nexport function createUrlTriggerHandler(\n fireCallback: TriggerFireCallback,\n deps?: UrlTriggerHandlerDeps,\n): TriggerHandler<'url'> {\n const logger = deps?.logger ?? console;\n\n const installed = new Map();\n let listening = false;\n\n /**\n * Handle webNavigation.onCompleted event\n */\n const onCompleted = (details: chrome.webNavigation.WebNavigationFramedCallbackDetails): void => {\n // Only handle main frame navigations\n if (details.frameId !== 0) return;\n\n const urlString = details.url;\n\n // Parse URL\n let parsed: URL;\n try {\n parsed = new URL(urlString);\n } catch {\n return; // Invalid URL, skip\n }\n\n if (installed.size === 0) return;\n\n // Snapshot to avoid iteration hazards during concurrent install/uninstall\n const snapshot = Array.from(installed.entries());\n\n for (const [triggerId, trigger] of snapshot) {\n if (!matchesRules(trigger.rules, urlString, parsed)) continue;\n\n // Fire and forget: chrome event listeners should not block navigation\n Promise.resolve(\n fireCallback.onFire(triggerId, {\n sourceTabId: details.tabId,\n sourceUrl: urlString,\n }),\n ).catch((e) => {\n logger.error(`[UrlTriggerHandler] onFire failed for trigger \"${triggerId}\":`, e);\n });\n }\n };\n\n /**\n * Ensure listener is registered\n */\n function ensureListening(): void {\n if (listening) return;\n if (!chrome.webNavigation?.onCompleted?.addListener) {\n logger.warn('[UrlTriggerHandler] chrome.webNavigation.onCompleted is unavailable');\n return;\n }\n chrome.webNavigation.onCompleted.addListener(onCompleted);\n listening = true;\n }\n\n /**\n * Stop listening\n */\n function stopListening(): void {\n if (!listening) return;\n try {\n chrome.webNavigation.onCompleted.removeListener(onCompleted);\n } catch (e) {\n logger.debug('[UrlTriggerHandler] removeListener failed:', e);\n } finally {\n listening = false;\n }\n }\n\n return {\n kind: 'url',\n\n async install(trigger: UrlTriggerSpec): Promise {\n installed.set(trigger.id, {\n spec: trigger,\n rules: compileUrlMatchRules(trigger.match),\n });\n ensureListening();\n },\n\n async uninstall(triggerId: string): Promise {\n installed.delete(triggerId as TriggerId);\n if (installed.size === 0) {\n stopListening();\n }\n },\n\n async uninstallAll(): Promise {\n installed.clear();\n stopListening();\n },\n\n getInstalledIds(): string[] {\n return Array.from(installed.keys());\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/index.ts", "content": "/**\n * @fileoverview Record-Replay V3 公共 API 入口\n * @description 导出所有公共类型和接口\n */\n\n// ==================== Domain ====================\nexport * from './domain';\n\n// ==================== Engine ====================\nexport * from './engine';\n\n// ==================== Storage ====================\nexport * from './storage';\n\n// ==================== Factory Functions ====================\n\nimport type { StoragePort } from './engine/storage/storage-port';\nimport { createFlowsStore } from './storage/flows';\nimport { createRunsStore } from './storage/runs';\nimport { createEventsStore } from './storage/events';\nimport { createQueueStore } from './storage/queue';\nimport { createPersistentVarsStore } from './storage/persistent-vars';\nimport { createTriggersStore } from './storage/triggers';\n\n/**\n * 创建完整的 StoragePort 实现\n */\nexport function createStoragePort(): StoragePort {\n return {\n flows: createFlowsStore(),\n runs: createRunsStore(),\n events: createEventsStore(),\n queue: createQueueStore(),\n persistentVars: createPersistentVarsStore(),\n triggers: createTriggersStore(),\n };\n}\n\n// ==================== Version ====================\n\n/** V3 API 版本 */\nexport const RR_V3_VERSION = '3.0.0' as const;\n\n/** 是否为 V3 API */\nexport const IS_RR_V3 = true as const;\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/db.ts", "content": "/**\n * @fileoverview V3 IndexedDB 数据库定义\n * @description 定义 rr_v3 数据库的 schema 和初始化逻辑\n */\n\n/** 数据库名称 */\nexport const RR_V3_DB_NAME = 'rr_v3';\n\n/** 数据库版本 */\nexport const RR_V3_DB_VERSION = 1;\n\n/**\n * Store 名称常量\n */\nexport const RR_V3_STORES = {\n FLOWS: 'flows',\n RUNS: 'runs',\n EVENTS: 'events',\n QUEUE: 'queue',\n PERSISTENT_VARS: 'persistent_vars',\n TRIGGERS: 'triggers',\n} as const;\n\n/**\n * Store 配置\n */\nexport interface StoreConfig {\n keyPath: string | string[];\n autoIncrement?: boolean;\n indexes?: Array<{\n name: string;\n keyPath: string | string[];\n options?: IDBIndexParameters;\n }>;\n}\n\n/**\n * V3 Store Schema 定义\n * @description 包含 Phase 1-3 所需的所有索引，避免后续升级\n */\nexport const RR_V3_STORE_SCHEMAS: Record = {\n [RR_V3_STORES.FLOWS]: {\n keyPath: 'id',\n indexes: [\n { name: 'name', keyPath: 'name' },\n { name: 'updatedAt', keyPath: 'updatedAt' },\n ],\n },\n [RR_V3_STORES.RUNS]: {\n keyPath: 'id',\n indexes: [\n { name: 'status', keyPath: 'status' },\n { name: 'flowId', keyPath: 'flowId' },\n { name: 'createdAt', keyPath: 'createdAt' },\n { name: 'updatedAt', keyPath: 'updatedAt' },\n // Compound index for listing runs by flow and status\n { name: 'flowId_status', keyPath: ['flowId', 'status'] },\n ],\n },\n [RR_V3_STORES.EVENTS]: {\n keyPath: ['runId', 'seq'],\n indexes: [\n { name: 'runId', keyPath: 'runId' },\n { name: 'type', keyPath: 'type' },\n // Compound index for filtering events by run and type\n { name: 'runId_type', keyPath: ['runId', 'type'] },\n ],\n },\n [RR_V3_STORES.QUEUE]: {\n keyPath: 'id',\n indexes: [\n { name: 'status', keyPath: 'status' },\n { name: 'priority', keyPath: 'priority' },\n { name: 'createdAt', keyPath: 'createdAt' },\n { name: 'flowId', keyPath: 'flowId' },\n // Phase 3: Used by claimNext(); cursor direction + key ranges implement priority DESC + createdAt ASC.\n { name: 'status_priority_createdAt', keyPath: ['status', 'priority', 'createdAt'] },\n // Phase 3: Lease expiration tracking\n { name: 'lease_expiresAt', keyPath: 'lease.expiresAt' },\n ],\n },\n [RR_V3_STORES.PERSISTENT_VARS]: {\n keyPath: 'key',\n indexes: [{ name: 'updatedAt', keyPath: 'updatedAt' }],\n },\n [RR_V3_STORES.TRIGGERS]: {\n keyPath: 'id',\n indexes: [\n { name: 'kind', keyPath: 'kind' },\n { name: 'flowId', keyPath: 'flowId' },\n { name: 'enabled', keyPath: 'enabled' },\n // Compound index for listing enabled triggers by kind\n { name: 'kind_enabled', keyPath: ['kind', 'enabled'] },\n ],\n },\n};\n\n/**\n * 数据库升级处理器\n */\nexport function handleUpgrade(db: IDBDatabase, oldVersion: number, _newVersion: number): void {\n // Version 0 -> 1: 创建所有 stores\n if (oldVersion < 1) {\n for (const [storeName, config] of Object.entries(RR_V3_STORE_SCHEMAS)) {\n const store = db.createObjectStore(storeName, {\n keyPath: config.keyPath,\n autoIncrement: config.autoIncrement,\n });\n\n // 创建索引\n if (config.indexes) {\n for (const index of config.indexes) {\n store.createIndex(index.name, index.keyPath, index.options);\n }\n }\n }\n }\n}\n\n/** 全局数据库实例 */\nlet dbInstance: IDBDatabase | null = null;\nlet dbPromise: Promise | null = null;\n\n/**\n * 打开 V3 数据库\n * @description 单例模式，确保只有一个数据库连接\n */\nexport async function openRrV3Db(): Promise {\n if (dbInstance) {\n return dbInstance;\n }\n\n if (dbPromise) {\n return dbPromise;\n }\n\n dbPromise = new Promise((resolve, reject) => {\n const request = indexedDB.open(RR_V3_DB_NAME, RR_V3_DB_VERSION);\n\n request.onerror = () => {\n dbPromise = null;\n reject(new Error(`Failed to open database: ${request.error?.message}`));\n };\n\n request.onsuccess = () => {\n dbInstance = request.result;\n\n // 处理版本变更（其他 tab 升级了数据库）\n dbInstance.onversionchange = () => {\n dbInstance?.close();\n dbInstance = null;\n dbPromise = null;\n };\n\n resolve(dbInstance);\n };\n\n request.onupgradeneeded = (event) => {\n const db = request.result;\n const oldVersion = event.oldVersion;\n const newVersion = event.newVersion ?? RR_V3_DB_VERSION;\n handleUpgrade(db, oldVersion, newVersion);\n };\n });\n\n return dbPromise;\n}\n\n/**\n * 关闭数据库连接\n * @description 主要用于测试\n */\nexport function closeRrV3Db(): void {\n if (dbInstance) {\n dbInstance.close();\n dbInstance = null;\n dbPromise = null;\n }\n}\n\n/**\n * 删除数据库\n * @description 主要用于测试\n */\nexport async function deleteRrV3Db(): Promise {\n closeRrV3Db();\n\n return new Promise((resolve, reject) => {\n const request = indexedDB.deleteDatabase(RR_V3_DB_NAME);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n}\n\n/**\n * 执行事务\n * @param storeNames Store 名称（单个或多个）\n * @param mode 事务模式\n * @param callback 事务回调\n */\nexport async function withTransaction(\n storeNames: string | string[],\n mode: IDBTransactionMode,\n callback: (stores: Record) => Promise | T,\n): Promise {\n const db = await openRrV3Db();\n const names = Array.isArray(storeNames) ? storeNames : [storeNames];\n const tx = db.transaction(names, mode);\n\n const stores: Record = {};\n for (const name of names) {\n stores[name] = tx.objectStore(name);\n }\n\n return new Promise((resolve, reject) => {\n let result: T;\n\n tx.oncomplete = () => resolve(result);\n tx.onerror = () => reject(tx.error);\n tx.onabort = () => reject(tx.error || new Error('Transaction aborted'));\n\n Promise.resolve(callback(stores))\n .then((r) => {\n result = r;\n })\n .catch((err) => {\n tx.abort();\n reject(err);\n });\n });\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/events.ts", "content": "/**\n * @fileoverview RunEvent 持久化\n * @description 实现事件的原子 seq 分配和存储\n */\n\nimport type { RunId } from '../domain/ids';\nimport type { RunEvent, RunEventInput, RunRecordV3 } from '../domain/events';\nimport { RR_ERROR_CODES, createRRError } from '../domain/errors';\nimport type { EventsStore } from '../engine/storage/storage-port';\nimport { RR_V3_STORES, withTransaction } from './db';\n\n/**\n * IDB request helper - promisify IDBRequest with RRError wrapping\n */\nfunction idbRequest(request: IDBRequest, context: string): Promise {\n return new Promise((resolve, reject) => {\n request.onsuccess = () => resolve(request.result);\n request.onerror = () => {\n const error = request.error;\n reject(\n createRRError(\n RR_ERROR_CODES.INTERNAL,\n `IDB error in ${context}: ${error?.message ?? 'unknown'}`,\n ),\n );\n };\n });\n}\n\n/**\n * 创建 EventsStore 实现\n * @description\n * - append() 在单个事务中原子分配 seq\n * - seq 由 RunRecordV3.nextSeq 作为单一事实来源\n */\nexport function createEventsStore(): EventsStore {\n return {\n /**\n * 追加事件并原子分配 seq\n * @description 在单个事务中：读取 RunRecordV3.nextSeq -> 写入事件 -> 递增 nextSeq\n */\n async append(input: RunEventInput): Promise {\n return withTransaction(\n [RR_V3_STORES.RUNS, RR_V3_STORES.EVENTS],\n 'readwrite',\n async (stores) => {\n const runsStore = stores[RR_V3_STORES.RUNS];\n const eventsStore = stores[RR_V3_STORES.EVENTS];\n\n // Step 1: Read nextSeq from RunRecordV3 (single source of truth)\n const run = await idbRequest(\n runsStore.get(input.runId),\n `append.getRun(${input.runId})`,\n );\n\n if (!run) {\n throw createRRError(\n RR_ERROR_CODES.INTERNAL,\n `Run \"${input.runId}\" not found when appending event`,\n );\n }\n\n const seq = run.nextSeq;\n\n // Validate seq integrity\n if (!Number.isSafeInteger(seq) || seq < 0) {\n throw createRRError(\n RR_ERROR_CODES.INVARIANT_VIOLATION,\n `Invalid nextSeq for run \"${input.runId}\": ${String(seq)}`,\n );\n }\n\n // Step 2: Create complete event with allocated seq\n const event: RunEvent = {\n ...input,\n seq,\n ts: input.ts ?? Date.now(),\n } as RunEvent;\n\n // Step 3: Write event to events store\n await idbRequest(eventsStore.add(event), `append.addEvent(${input.runId}, seq=${seq})`);\n\n // Step 4: Increment nextSeq in runs store (same transaction)\n const updatedRun: RunRecordV3 = {\n ...run,\n nextSeq: seq + 1,\n updatedAt: Date.now(),\n };\n\n await idbRequest(\n runsStore.put(updatedRun),\n `append.updateNextSeq(${input.runId}, nextSeq=${seq + 1})`,\n );\n\n return event;\n },\n );\n },\n\n /**\n * 列出事件\n * @description 利用复合主键 [runId, seq] 实现高效范围查询\n */\n async list(runId: RunId, opts?: { fromSeq?: number; limit?: number }): Promise {\n return withTransaction(RR_V3_STORES.EVENTS, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.EVENTS];\n const fromSeq = opts?.fromSeq ?? 0;\n const limit = opts?.limit;\n\n // Early return for zero limit\n if (limit === 0) {\n return [];\n }\n\n return new Promise((resolve, reject) => {\n const results: RunEvent[] = [];\n\n // Use compound primary key [runId, seq] for efficient range query\n // This yields events in seq-ascending order naturally\n const range = IDBKeyRange.bound([runId, fromSeq], [runId, Number.MAX_SAFE_INTEGER]);\n\n const request = store.openCursor(range);\n\n request.onsuccess = () => {\n const cursor = request.result;\n\n if (!cursor) {\n resolve(results);\n return;\n }\n\n const event = cursor.value as RunEvent;\n results.push(event);\n\n // Check limit\n if (limit !== undefined && results.length >= limit) {\n resolve(results);\n return;\n }\n\n cursor.continue();\n };\n\n request.onerror = () => reject(request.error);\n });\n });\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/flows.ts", "content": "/**\n * @fileoverview FlowV3 持久化\n * @description 实现 Flow 的 CRUD 操作\n */\n\nimport type { FlowId } from '../domain/ids';\nimport type { FlowV3 } from '../domain/flow';\nimport { FLOW_SCHEMA_VERSION } from '../domain/flow';\nimport { RR_ERROR_CODES, createRRError } from '../domain/errors';\nimport type { FlowsStore } from '../engine/storage/storage-port';\nimport { RR_V3_STORES, withTransaction } from './db';\n\n/**\n * 校验 Flow 结构\n */\nfunction validateFlow(flow: FlowV3): void {\n // 校验 schema 版本\n if (flow.schemaVersion !== FLOW_SCHEMA_VERSION) {\n throw createRRError(\n RR_ERROR_CODES.VALIDATION_ERROR,\n `Invalid schema version: expected ${FLOW_SCHEMA_VERSION}, got ${flow.schemaVersion}`,\n );\n }\n\n // 校验必填字段\n if (!flow.id) {\n throw createRRError(RR_ERROR_CODES.VALIDATION_ERROR, 'Flow id is required');\n }\n if (!flow.name) {\n throw createRRError(RR_ERROR_CODES.VALIDATION_ERROR, 'Flow name is required');\n }\n if (!flow.entryNodeId) {\n throw createRRError(RR_ERROR_CODES.VALIDATION_ERROR, 'Flow entryNodeId is required');\n }\n\n // 校验 entryNodeId 存在\n const nodeIds = new Set(flow.nodes.map((n) => n.id));\n if (!nodeIds.has(flow.entryNodeId)) {\n throw createRRError(\n RR_ERROR_CODES.VALIDATION_ERROR,\n `Entry node \"${flow.entryNodeId}\" does not exist in flow`,\n );\n }\n\n // 校验边引用\n for (const edge of flow.edges) {\n if (!nodeIds.has(edge.from)) {\n throw createRRError(\n RR_ERROR_CODES.VALIDATION_ERROR,\n `Edge \"${edge.id}\" references non-existent source node \"${edge.from}\"`,\n );\n }\n if (!nodeIds.has(edge.to)) {\n throw createRRError(\n RR_ERROR_CODES.VALIDATION_ERROR,\n `Edge \"${edge.id}\" references non-existent target node \"${edge.to}\"`,\n );\n }\n }\n}\n\n/**\n * 创建 FlowsStore 实现\n */\nexport function createFlowsStore(): FlowsStore {\n return {\n async list(): Promise {\n return withTransaction(RR_V3_STORES.FLOWS, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.FLOWS];\n return new Promise((resolve, reject) => {\n const request = store.getAll();\n request.onsuccess = () => resolve(request.result as FlowV3[]);\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async get(id: FlowId): Promise {\n return withTransaction(RR_V3_STORES.FLOWS, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.FLOWS];\n return new Promise((resolve, reject) => {\n const request = store.get(id);\n request.onsuccess = () => resolve((request.result as FlowV3) ?? null);\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async save(flow: FlowV3): Promise {\n // 校验\n validateFlow(flow);\n\n return withTransaction(RR_V3_STORES.FLOWS, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.FLOWS];\n return new Promise((resolve, reject) => {\n const request = store.put(flow);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async delete(id: FlowId): Promise {\n return withTransaction(RR_V3_STORES.FLOWS, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.FLOWS];\n return new Promise((resolve, reject) => {\n const request = store.delete(id);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/import/index.ts", "content": "/**\n * @fileoverview Import 模块导出入口\n */\n\nexport * from './v2-reader';\nexport * from './v2-to-v3';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/import/v2-reader.ts", "content": "/**\n * @fileoverview V2 数据读取器\n * @description 读取 V2 格式的数据（占位实现）\n */\n\n/**\n * V2 数据读取器接口\n * @description Phase 5+ 实现\n */\nexport interface V2Reader {\n /** 读取 V2 Flows */\n readFlows(): Promise;\n /** 读取 V2 Runs */\n readRuns(): Promise;\n /** 读取 V2 Triggers */\n readTriggers(): Promise;\n /** 读取 V2 Schedules */\n readSchedules(): Promise;\n}\n\n/**\n * 创建 NotImplemented 的 V2Reader\n */\nexport function createNotImplementedV2Reader(): V2Reader {\n const notImplemented = async () => {\n throw new Error('V2Reader not implemented');\n };\n\n return {\n readFlows: notImplemented,\n readRuns: notImplemented,\n readTriggers: notImplemented,\n readSchedules: notImplemented,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/import/v2-to-v3.ts", "content": "/**\n * @fileoverview V2 到 V3 数据转换器\n * @description 将 V2 格式数据转换为 V3 格式，支持双向转换\n */\n\nimport type { FlowV3, NodeV3, EdgeV3, FlowBinding } from '../../domain/flow';\nimport type { TriggerSpec } from '../../domain/triggers';\nimport type { VariableDefinition } from '../../domain/variables';\nimport type { NodeId, FlowId, EdgeId } from '../../domain/ids';\nimport type { ISODateTimeString } from '../../domain/json';\nimport { FLOW_SCHEMA_VERSION } from '../../domain/flow';\n\n// ==================== V2 Types (imported from record-replay) ====================\n\n/** V2 Node type definition */\ninterface V2Node {\n id: string;\n type: string;\n name?: string;\n disabled?: boolean;\n config?: Record;\n ui?: { x: number; y: number };\n}\n\n/** V2 Edge type definition */\ninterface V2Edge {\n id: string;\n from: string;\n to: string;\n label?: string;\n}\n\n/** V2 Variable definition */\ninterface V2VariableDef {\n key: string;\n label?: string;\n sensitive?: boolean;\n default?: unknown;\n type?: string;\n rules?: { required?: boolean; pattern?: string; enum?: string[] };\n}\n\n/** V2 Flow binding */\ninterface V2Binding {\n type: 'domain' | 'path' | 'url';\n value: string;\n}\n\n/** V2 Flow definition */\ninterface V2Flow {\n id: string;\n name: string;\n description?: string;\n version: number;\n meta?: {\n createdAt?: string;\n updatedAt?: string;\n domain?: string;\n tags?: string[];\n bindings?: V2Binding[];\n tool?: { category?: string; description?: string };\n exposedOutputs?: Array<{ nodeId: string; as: string }>;\n };\n variables?: V2VariableDef[];\n nodes?: V2Node[];\n edges?: V2Edge[];\n subflows?: Record;\n}\n\n// ==================== Conversion Result Types ====================\n\nexport interface ConversionResult {\n success: boolean;\n data?: T;\n errors: string[];\n warnings: string[];\n}\n\n// ==================== V2 -> V3 Conversion ====================\n\n/**\n * 将 V2 Flow 转换为 V3 Flow\n * @param v2Flow V2 格式的 Flow\n * @returns 转换结果，包含成功/失败状态、数据和错误/警告信息\n */\nexport function convertFlowV2ToV3(v2Flow: V2Flow): ConversionResult {\n const errors: string[] = [];\n const warnings: string[] = [];\n\n // 1. 基础字段验证\n if (!v2Flow.id) {\n errors.push('V2 Flow missing required field: id');\n }\n if (!v2Flow.name) {\n errors.push('V2 Flow missing required field: name');\n }\n if (!v2Flow.nodes || v2Flow.nodes.length === 0) {\n errors.push('V2 Flow has no nodes');\n }\n\n // 2. 检查不支持的特性\n if (v2Flow.subflows && Object.keys(v2Flow.subflows).length > 0) {\n errors.push(\n 'V3 does not support subflows yet. Flow contains subflows: ' +\n Object.keys(v2Flow.subflows).join(', '),\n );\n }\n\n // 检查 foreach/while 节点\n const unsupportedNodes = (v2Flow.nodes || []).filter(\n (n) => n.type === 'foreach' || n.type === 'while',\n );\n if (unsupportedNodes.length > 0) {\n errors.push(\n 'V3 does not support foreach/while nodes yet. Found: ' +\n unsupportedNodes.map((n) => `${n.id} (${n.type})`).join(', '),\n );\n }\n\n // 如果有致命错误，直接返回\n if (errors.length > 0) {\n return { success: false, errors, warnings };\n }\n\n // 3. 转换节点\n const nodes: NodeV3[] = [];\n for (const v2Node of v2Flow.nodes || []) {\n const node = convertNodeV2ToV3(v2Node);\n if (node) {\n nodes.push(node);\n } else {\n warnings.push(`Skipped invalid node: ${v2Node.id}`);\n }\n }\n\n // 4. 转换边\n const edges: EdgeV3[] = [];\n for (const v2Edge of v2Flow.edges || []) {\n const edge = convertEdgeV2ToV3(v2Edge);\n if (edge) {\n edges.push(edge);\n } else {\n warnings.push(`Skipped invalid edge: ${v2Edge.id}`);\n }\n }\n\n // 5. 计算 entryNodeId\n const entryResult = findEntryNodeId(nodes, edges);\n warnings.push(...entryResult.warnings);\n if (!entryResult.nodeId) {\n errors.push('Could not determine entry node. No valid root node found.');\n return { success: false, errors, warnings };\n }\n const entryNodeId = entryResult.nodeId;\n\n // 6. 转换变量\n const variables = convertVariablesV2ToV3(v2Flow.variables || []);\n\n // 7. 转换元数据\n const meta = convertMetaV2ToV3(v2Flow.meta);\n\n // 8. 构建 V3 Flow\n const now = new Date().toISOString() as ISODateTimeString;\n const v3Flow: FlowV3 = {\n schemaVersion: FLOW_SCHEMA_VERSION,\n id: v2Flow.id as FlowId,\n name: v2Flow.name,\n createdAt: (v2Flow.meta?.createdAt as ISODateTimeString) || now,\n updatedAt: (v2Flow.meta?.updatedAt as ISODateTimeString) || now,\n entryNodeId,\n nodes,\n edges,\n };\n\n // 可选字段\n if (v2Flow.description) {\n v3Flow.description = v2Flow.description;\n }\n if (variables.length > 0) {\n v3Flow.variables = variables;\n }\n if (meta) {\n v3Flow.meta = meta;\n }\n\n return { success: true, data: v3Flow, errors, warnings };\n}\n\n/**\n * 转换单个 V2 Node 为 V3 Node\n */\nfunction convertNodeV2ToV3(v2Node: V2Node): NodeV3 | null {\n if (!v2Node.id || !v2Node.type) {\n return null;\n }\n\n const node: NodeV3 = {\n id: v2Node.id as NodeId,\n kind: v2Node.type, // V2 type -> V3 kind\n config: (v2Node.config as Record) || {},\n };\n\n // 可选字段\n if (v2Node.name) {\n node.name = v2Node.name;\n }\n if (v2Node.disabled) {\n node.disabled = v2Node.disabled;\n }\n if (v2Node.ui) {\n node.ui = v2Node.ui;\n }\n\n return node;\n}\n\n/**\n * 转换单个 V2 Edge 为 V3 Edge\n */\nfunction convertEdgeV2ToV3(v2Edge: V2Edge): EdgeV3 | null {\n if (!v2Edge.id || !v2Edge.from || !v2Edge.to) {\n return null;\n }\n\n const edge: EdgeV3 = {\n id: v2Edge.id as EdgeId,\n from: v2Edge.from as NodeId,\n to: v2Edge.to as NodeId,\n };\n\n // label 直接传递\n if (v2Edge.label) {\n edge.label = v2Edge.label as EdgeV3['label'];\n }\n\n return edge;\n}\n\n/** entryNodeId 计算结果 */\ninterface EntryNodeResult {\n nodeId: NodeId | null;\n warnings: string[];\n}\n\n/**\n * 找到入口节点 ID\n *\n * 规则：\n * 1. 排除 trigger 类型节点（这些是 UI 节点，不参与执行）\n * 2. 只统计「可执行节点 -> 可执行节点」的边来计算入度（忽略 trigger 指出的边）\n * 3. 找到入度为 0 的节点作为候选\n * 4. 如果有多个候选，使用稳定选择规则：\n * - 优先选择 UI 坐标最靠左上的节点（按 x 升序，x 相同按 y 升序）\n * - 如果无 UI 坐标，按 ID 字典序取第一个\n */\nfunction findEntryNodeId(nodes: NodeV3[], edges: EdgeV3[]): EntryNodeResult {\n const warnings: string[] = [];\n\n // 1. 排除 trigger 节点，获取可执行节点\n const executableNodes = nodes.filter((n) => n.kind !== 'trigger');\n if (executableNodes.length === 0) {\n warnings.push('No executable nodes found; cannot determine entry node');\n return { nodeId: null, warnings };\n }\n\n const executableNodeIds = new Set(executableNodes.map((n) => n.id));\n\n // 2. 计算入度（只统计可执行节点之间的边）\n const inDegree = new Map();\n for (const node of executableNodes) {\n inDegree.set(node.id, 0);\n }\n for (const edge of edges) {\n // 忽略从非可执行节点（如 trigger）指出的边\n if (!executableNodeIds.has(edge.from)) {\n continue;\n }\n // 忽略指向非可执行节点的边\n if (!executableNodeIds.has(edge.to)) {\n continue;\n }\n inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);\n }\n\n // 3. 找入度为 0 的节点\n const rootNodes = executableNodes.filter((n) => inDegree.get(n.id) === 0);\n\n if (rootNodes.length === 0) {\n // 没有入度为 0 的节点，说明图中存在环，使用稳定选择器选择 fallback\n const fallbackResult = selectStableRootNode(executableNodes);\n warnings.push(\n `No inDegree=0 executable node found (graph may contain cycles); ` +\n `falling back to \"${fallbackResult.node.id}\" by ${fallbackResult.rule}`,\n );\n return { nodeId: fallbackResult.node.id, warnings };\n }\n\n // 4. 单个根节点，直接返回\n if (rootNodes.length === 1) {\n return { nodeId: rootNodes[0].id, warnings };\n }\n\n // 5. 多个根节点，使用稳定选择规则\n const selectedResult = selectStableRootNode(rootNodes);\n const candidateIds = rootNodes\n .map((n) => n.id)\n .sort((a, b) => a.localeCompare(b))\n .join(', ');\n warnings.push(\n `Multiple inDegree=0 executable nodes (${candidateIds}); ` +\n `selected \"${selectedResult.node.id}\" by ${selectedResult.rule}`,\n );\n\n return { nodeId: selectedResult.node.id, warnings };\n}\n\n/** 稳定选择结果 */\ninterface StableSelectionResult {\n node: NodeV3;\n rule: string;\n}\n\n/**\n * 从多个根节点中选择一个稳定的入口节点\n * 优先按 UI 坐标（左上角优先），其次按 ID 字典序\n */\nfunction selectStableRootNode(nodes: NodeV3[]): StableSelectionResult {\n // 检查节点是否有有效的 UI 坐标\n const hasValidUi = (n: NodeV3): n is NodeV3 & { ui: { x: number; y: number } } =>\n !!n.ui && Number.isFinite(n.ui.x) && Number.isFinite(n.ui.y);\n\n const nodesWithUi = nodes.filter(hasValidUi);\n\n if (nodesWithUi.length > 0) {\n // 按 UI 坐标排序：x 升序 -> y 升序 -> id 字典序（作为 tie-breaker）\n nodesWithUi.sort((a, b) => {\n if (a.ui.x !== b.ui.x) return a.ui.x - b.ui.x;\n if (a.ui.y !== b.ui.y) return a.ui.y - b.ui.y;\n return a.id.localeCompare(b.id);\n });\n const selected = nodesWithUi[0];\n return {\n node: selected,\n rule: `ui(x=${selected.ui.x}, y=${selected.ui.y})`,\n };\n }\n\n // 无 UI 坐标，按 ID 字典序\n const sortedById = [...nodes].sort((a, b) => a.id.localeCompare(b.id));\n return { node: sortedById[0], rule: 'id' };\n}\n\n/**\n * 转换变量定义\n */\nfunction convertVariablesV2ToV3(v2Variables: V2VariableDef[]): VariableDefinition[] {\n return v2Variables\n .filter((v) => v.key)\n .map((v) => {\n const variable: VariableDefinition = {\n name: v.key,\n };\n\n if (v.label) {\n variable.label = v.label;\n }\n if (v.sensitive) {\n variable.sensitive = v.sensitive;\n }\n if (v.default !== undefined) {\n variable.default = v.default;\n }\n if (v.rules?.required) {\n variable.required = v.rules.required;\n }\n\n return variable;\n });\n}\n\n/**\n * 转换元数据\n */\nfunction convertMetaV2ToV3(v2Meta: V2Flow['meta']): FlowV3['meta'] | undefined {\n if (!v2Meta) return undefined;\n\n const meta: FlowV3['meta'] = {};\n\n if (v2Meta.tags && v2Meta.tags.length > 0) {\n meta.tags = v2Meta.tags;\n }\n\n if (v2Meta.bindings && v2Meta.bindings.length > 0) {\n meta.bindings = v2Meta.bindings.map((b) => ({\n kind: b.type, // V2 type -> V3 kind\n value: b.value,\n }));\n }\n\n // 如果 meta 为空对象，返回 undefined\n if (Object.keys(meta).length === 0) {\n return undefined;\n }\n\n return meta;\n}\n\n// ==================== V3 -> V2 Conversion ====================\n\n/**\n * 将 V3 Flow 转换为 V2 Flow（用于在 V2 Builder 中编辑）\n * @param v3Flow V3 格式的 Flow\n * @returns 转换结果\n */\nexport function convertFlowV3ToV2(v3Flow: FlowV3): ConversionResult {\n const errors: string[] = [];\n const warnings: string[] = [];\n\n // 1. 转换节点\n const nodes: V2Node[] = v3Flow.nodes.map((n) => ({\n id: n.id,\n type: n.kind, // V3 kind -> V2 type\n name: n.name,\n disabled: n.disabled,\n config: n.config as Record,\n ui: n.ui,\n }));\n\n // 2. 转换边\n const edges: V2Edge[] = v3Flow.edges.map((e) => ({\n id: e.id,\n from: e.from,\n to: e.to,\n label: e.label,\n }));\n\n // 3. 转换变量\n const variables: V2VariableDef[] = (v3Flow.variables || []).map((v) => ({\n key: v.name,\n label: v.label,\n sensitive: v.sensitive,\n default: v.default,\n rules: v.required ? { required: v.required } : undefined,\n }));\n\n // 4. 转换元数据\n const meta: V2Flow['meta'] = {\n createdAt: v3Flow.createdAt,\n updatedAt: v3Flow.updatedAt,\n };\n\n if (v3Flow.meta?.tags) {\n meta.tags = v3Flow.meta.tags;\n }\n\n if (v3Flow.meta?.bindings) {\n meta.bindings = v3Flow.meta.bindings.map((b) => ({\n type: b.kind, // V3 kind -> V2 type\n value: b.value,\n }));\n }\n\n // 5. 构建 V2 Flow\n const v2Flow: V2Flow = {\n id: v3Flow.id,\n name: v3Flow.name,\n description: v3Flow.description,\n version: 2, // V2 版本\n meta,\n variables: variables.length > 0 ? variables : undefined,\n nodes,\n edges,\n };\n\n return { success: true, data: v2Flow, errors, warnings };\n}\n\n// ==================== Trigger Conversion ====================\n\n/** V2 Trigger 定义 */\ninterface V2Trigger {\n id: string;\n type: 'url' | 'command' | 'manual' | 'schedule' | 'element';\n flowId: string;\n enabled?: boolean;\n match?: Array<{ kind: string; value: string }>;\n title?: string;\n commandKey?: string;\n selector?: string;\n appear?: boolean;\n once?: boolean;\n debounceMs?: number;\n schedule?: {\n type: 'interval' | 'daily' | 'weekly';\n intervalMs?: number;\n time?: string;\n days?: number[];\n };\n}\n\n/**\n * 将 V2 Trigger 转换为 V3 TriggerSpec\n * @param v2Trigger V2 格式的 Trigger\n * @returns 转换结果\n */\nexport function convertTriggerV2ToV3(v2Trigger: V2Trigger): ConversionResult {\n const errors: string[] = [];\n const warnings: string[] = [];\n\n if (!v2Trigger.id) {\n errors.push('V2 Trigger missing required field: id');\n }\n if (!v2Trigger.flowId) {\n errors.push('V2 Trigger missing required field: flowId');\n }\n if (!v2Trigger.type) {\n errors.push('V2 Trigger missing required field: type');\n }\n\n if (errors.length > 0) {\n return { success: false, errors, warnings };\n }\n\n // 根据 type 构建不同的 TriggerSpec\n let trigger: TriggerSpec;\n\n switch (v2Trigger.type) {\n case 'manual':\n trigger = {\n id: v2Trigger.id,\n kind: 'manual',\n flowId: v2Trigger.flowId as FlowId,\n enabled: v2Trigger.enabled ?? true,\n };\n break;\n\n case 'command':\n trigger = {\n id: v2Trigger.id,\n kind: 'command',\n flowId: v2Trigger.flowId as FlowId,\n enabled: v2Trigger.enabled ?? true,\n command: v2Trigger.commandKey || 'run_workflow',\n };\n break;\n\n case 'url':\n trigger = {\n id: v2Trigger.id,\n kind: 'url',\n flowId: v2Trigger.flowId as FlowId,\n enabled: v2Trigger.enabled ?? true,\n patterns: (v2Trigger.match || []).map((m) => m.value),\n };\n break;\n\n case 'schedule': { // 将 V2 schedule 转换为 cron 表达式\n const cron = convertScheduleToCron(v2Trigger.schedule);\n if (!cron) {\n errors.push('Could not convert V2 schedule to cron expression');\n return { success: false, errors, warnings };\n }\n trigger = {\n id: v2Trigger.id,\n kind: 'cron',\n flowId: v2Trigger.flowId as FlowId,\n enabled: v2Trigger.enabled ?? true,\n cron,\n };\n break;\n }\n\n case 'element':\n warnings.push('Element trigger is not fully supported in V3, converting to manual');\n trigger = {\n id: v2Trigger.id,\n kind: 'manual',\n flowId: v2Trigger.flowId as FlowId,\n enabled: v2Trigger.enabled ?? true,\n };\n break;\n\n default:\n errors.push(`Unknown V2 trigger type: ${v2Trigger.type}`);\n return { success: false, errors, warnings };\n }\n\n return { success: true, data: trigger, errors, warnings };\n}\n\n/**\n * 将 V2 schedule 配置转换为 cron 表达式\n */\nfunction convertScheduleToCron(schedule: V2Trigger['schedule']): string | null {\n if (!schedule) return null;\n\n switch (schedule.type) {\n case 'interval': { // 将间隔转换为近似 cron（每 N 分钟）\n const intervalMinutes = Math.max(1, Math.round((schedule.intervalMs || 60000) / 60000));\n if (intervalMinutes < 60) {\n return `*/${intervalMinutes} * * * *`;\n } else {\n const hours = Math.round(intervalMinutes / 60);\n return `0 */${hours} * * *`;\n }\n }\n\n case 'daily':\n // 每天指定时间\n if (schedule.time) {\n const [hour, minute] = schedule.time.split(':').map(Number);\n return `${minute || 0} ${hour || 0} * * *`;\n }\n return '0 0 * * *'; // 默认每天 0:00\n\n case 'weekly': { // 每周指定天数和时间\n const days = (schedule.days || [0]).join(',');\n if (schedule.time) {\n const [hour, minute] = schedule.time.split(':').map(Number);\n return `${minute || 0} ${hour || 0} * * ${days}`;\n }\n return `0 0 * * ${days}`;\n }\n\n default:\n return null;\n }\n}\n\n// ==================== Converter Interface ====================\n\n/**\n * V2 到 V3 转换器接口\n */\nexport interface V2ToV3Converter {\n /** 转换 Flow */\n convertFlow(v2Flow: unknown): FlowV3;\n /** 转换 Trigger */\n convertTrigger(v2Trigger: unknown): TriggerSpec;\n}\n\n/**\n * 创建 V2ToV3Converter 实例\n */\nexport function createV2ToV3Converter(): V2ToV3Converter {\n return {\n convertFlow(v2Flow: unknown): FlowV3 {\n const result = convertFlowV2ToV3(v2Flow as V2Flow);\n if (!result.success || !result.data) {\n throw new Error(`Flow conversion failed: ${result.errors.join('; ')}`);\n }\n return result.data;\n },\n\n convertTrigger(v2Trigger: unknown): TriggerSpec {\n const result = convertTriggerV2ToV3(v2Trigger as V2Trigger);\n if (!result.success || !result.data) {\n throw new Error(`Trigger conversion failed: ${result.errors.join('; ')}`);\n }\n return result.data;\n },\n };\n}\n\n/**\n * 创建 NotImplemented 的 V2ToV3Converter（向后兼容）\n * @deprecated 使用 createV2ToV3Converter() 替代\n */\nexport function createNotImplementedV2ToV3Converter(): V2ToV3Converter {\n return createV2ToV3Converter();\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/index.ts", "content": "/**\n * @fileoverview Storage 层导出入口\n */\n\nexport * from './db';\nexport * from './flows';\nexport * from './runs';\nexport * from './events';\nexport * from './queue';\nexport * from './persistent-vars';\nexport * from './triggers';\nexport * from './import';\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/persistent-vars.ts", "content": "/**\n * @fileoverview 持久化变量存储\n * @description 实现 $ 前缀变量的持久化，使用 LWW（Last-Write-Wins）策略\n */\n\nimport type { PersistentVarRecord, PersistentVariableName } from '../domain/variables';\nimport type { JsonValue } from '../domain/json';\nimport type { PersistentVarsStore } from '../engine/storage/storage-port';\nimport { RR_V3_STORES, withTransaction } from './db';\n\n/**\n * 创建 PersistentVarsStore 实现\n */\nexport function createPersistentVarsStore(): PersistentVarsStore {\n return {\n async get(key: PersistentVariableName): Promise {\n return withTransaction(RR_V3_STORES.PERSISTENT_VARS, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.PERSISTENT_VARS];\n return new Promise((resolve, reject) => {\n const request = store.get(key);\n request.onsuccess = () => resolve(request.result as PersistentVarRecord | undefined);\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async set(key: PersistentVariableName, value: JsonValue): Promise {\n return withTransaction(RR_V3_STORES.PERSISTENT_VARS, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.PERSISTENT_VARS];\n\n // 先读取现有记录（用于 version 递增）\n const existing = await new Promise((resolve, reject) => {\n const request = store.get(key);\n request.onsuccess = () => resolve(request.result as PersistentVarRecord | undefined);\n request.onerror = () => reject(request.error);\n });\n\n const now = Date.now();\n const record: PersistentVarRecord = {\n key,\n value,\n updatedAt: now,\n version: (existing?.version ?? 0) + 1,\n };\n\n await new Promise((resolve, reject) => {\n const request = store.put(record);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n\n return record;\n });\n },\n\n async delete(key: PersistentVariableName): Promise {\n return withTransaction(RR_V3_STORES.PERSISTENT_VARS, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.PERSISTENT_VARS];\n return new Promise((resolve, reject) => {\n const request = store.delete(key);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async list(prefix?: PersistentVariableName): Promise {\n return withTransaction(RR_V3_STORES.PERSISTENT_VARS, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.PERSISTENT_VARS];\n\n return new Promise((resolve, reject) => {\n const request = store.getAll();\n request.onsuccess = () => {\n let results = request.result as PersistentVarRecord[];\n\n // 如果指定了前缀，过滤结果\n if (prefix) {\n results = results.filter((r) => r.key.startsWith(prefix));\n }\n\n resolve(results);\n };\n request.onerror = () => reject(request.error);\n });\n });\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/queue.ts", "content": "/**\n * @fileoverview RunQueue 持久化\n * @description 实现队列的 CRUD 操作和原子 claim\n */\n\nimport type { RunId } from '../domain/ids';\nimport {\n DEFAULT_QUEUE_CONFIG,\n type EnqueueInput,\n type QueueItemStatus,\n type RunQueue,\n type RunQueueItem,\n} from '../engine/queue/queue';\nimport { RR_V3_STORES, withTransaction } from './db';\n\n/** Default lease TTL in milliseconds (from shared config to avoid drift) */\nconst DEFAULT_LEASE_TTL_MS = DEFAULT_QUEUE_CONFIG.leaseTtlMs;\n\n/**\n * IDB key range bounds for numeric fields.\n * Use MAX_VALUE to cover the full range of finite numbers (not just safe integers).\n */\nconst IDB_NUMBER_MIN = -Number.MAX_VALUE;\nconst IDB_NUMBER_MAX = Number.MAX_VALUE;\n\n/**\n * 创建 RunQueue 持久化实现\n * @description 实现队列持久化，包括 Phase 3 原子 claim\n */\nexport function createQueueStore(): RunQueue {\n return {\n async enqueue(input: EnqueueInput): Promise {\n const now = Date.now();\n const item: RunQueueItem = {\n ...input,\n priority: input.priority ?? 0,\n maxAttempts: input.maxAttempts ?? 1,\n status: 'queued',\n createdAt: now,\n updatedAt: now,\n attempt: 0,\n };\n\n await withTransaction(RR_V3_STORES.QUEUE, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n return new Promise((resolve, reject) => {\n const request = store.add(item);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n\n return item;\n },\n\n async claimNext(ownerId: string, now: number): Promise {\n // Validate inputs\n if (!ownerId) {\n throw new Error('ownerId is required');\n }\n if (!Number.isFinite(now)) {\n throw new Error(`Invalid now: ${String(now)}`);\n }\n\n return withTransaction(RR_V3_STORES.QUEUE, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n const index = store.index('status_priority_createdAt');\n\n /**\n * Atomic claim implementation using two-step cursor approach:\n *\n * Desired ordering: priority DESC, createdAt ASC (FIFO within same priority)\n *\n * IndexedDB compound indexes only support single sort direction for the entire tuple.\n * The index ['status', 'priority', 'createdAt'] is stored ASC.\n *\n * Strategy:\n * 1. Use 'prev' cursor to find the highest priority (overall DESC)\n * 2. Use 'next' cursor within that priority to find earliest createdAt (FIFO)\n *\n * Both operations are within the same readwrite transaction, ensuring atomicity\n * since IndexedDB serializes readwrite transactions on the same store.\n */\n\n // Step 1: Find the highest priority among queued items\n const queuedRange = IDBKeyRange.bound(\n ['queued', IDB_NUMBER_MIN, IDB_NUMBER_MIN],\n ['queued', IDB_NUMBER_MAX, IDB_NUMBER_MAX],\n );\n\n const highestPriority = await new Promise((resolve, reject) => {\n const request = index.openCursor(queuedRange, 'prev');\n request.onerror = () => reject(request.error);\n request.onsuccess = () => {\n const cursor = request.result;\n if (!cursor) {\n resolve(null);\n return;\n }\n const item = cursor.value as RunQueueItem;\n resolve(item.priority);\n };\n });\n\n // No queued items available\n if (highestPriority === null) {\n return null;\n }\n\n // Step 2: Find the earliest createdAt within the highest priority (FIFO)\n const fifoRange = IDBKeyRange.bound(\n ['queued', highestPriority, IDB_NUMBER_MIN],\n ['queued', highestPriority, IDB_NUMBER_MAX],\n );\n\n return new Promise((resolve, reject) => {\n const request = index.openCursor(fifoRange, 'next');\n request.onerror = () => reject(request.error);\n request.onsuccess = () => {\n const cursor = request.result;\n if (!cursor) {\n // No items found (should not happen given step 1 succeeded)\n resolve(null);\n return;\n }\n\n const existing = cursor.value as RunQueueItem;\n\n // Defensive check: ensure status is still queued\n if (existing.status !== 'queued') {\n resolve(null);\n return;\n }\n\n // Atomically update to running with lease\n const updated: RunQueueItem = {\n ...existing,\n status: 'running',\n updatedAt: now,\n attempt: existing.attempt + 1,\n lease: {\n ownerId,\n expiresAt: now + DEFAULT_LEASE_TTL_MS,\n },\n };\n\n const updateRequest = cursor.update(updated);\n updateRequest.onerror = () => reject(updateRequest.error);\n updateRequest.onsuccess = () => resolve(updated);\n };\n });\n });\n },\n\n async heartbeat(ownerId: string, now: number): Promise {\n // Validate inputs\n if (!ownerId) {\n throw new Error('ownerId is required');\n }\n if (!Number.isFinite(now)) {\n throw new Error(`Invalid now: ${String(now)}`);\n }\n\n await withTransaction(RR_V3_STORES.QUEUE, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n const statusIndex = store.index('status');\n\n /**\n * Renew leases for all items owned by ownerId in the given status.\n * Uses cursor iteration to update each item atomically.\n */\n const renewForStatus = async (status: QueueItemStatus): Promise => {\n await new Promise((resolve, reject) => {\n const request = statusIndex.openCursor(IDBKeyRange.only(status));\n request.onerror = () => reject(request.error);\n request.onsuccess = () => {\n const cursor = request.result;\n if (!cursor) {\n resolve();\n return;\n }\n\n const item = cursor.value as RunQueueItem;\n const lease = item.lease;\n\n // Skip items not owned by this ownerId\n if (!lease || lease.ownerId !== ownerId) {\n cursor.continue();\n return;\n }\n\n // Renew the lease\n const updated: RunQueueItem = {\n ...item,\n updatedAt: now,\n lease: {\n ...lease,\n expiresAt: now + DEFAULT_LEASE_TTL_MS,\n },\n };\n\n const updateRequest = cursor.update(updated);\n updateRequest.onerror = () => reject(updateRequest.error);\n updateRequest.onsuccess = () => cursor.continue();\n };\n });\n };\n\n // Renew both running and paused items for the owner.\n // Paused items also need renewal to prevent TTL expiration during debug/manual pause.\n await renewForStatus('running');\n await renewForStatus('paused');\n });\n },\n\n async reclaimExpiredLeases(now: number): Promise {\n if (!Number.isFinite(now)) {\n throw new Error(`Invalid now: ${String(now)}`);\n }\n\n return withTransaction(RR_V3_STORES.QUEUE, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n const leaseIndex = store.index('lease_expiresAt');\n\n // Scan all items where lease.expiresAt < now (strictly less than)\n const expiredRange = IDBKeyRange.upperBound(now, true);\n\n return new Promise((resolve, reject) => {\n const reclaimed: RunId[] = [];\n const request = leaseIndex.openCursor(expiredRange);\n\n request.onerror = () => reject(request.error);\n request.onsuccess = () => {\n const cursor = request.result;\n if (!cursor) {\n resolve(reclaimed);\n return;\n }\n\n const item = cursor.value as RunQueueItem;\n const expiresAtKey = cursor.key;\n\n // Defensive: index key should be a finite number (Unix millis)\n if (typeof expiresAtKey !== 'number' || !Number.isFinite(expiresAtKey)) {\n cursor.continue();\n return;\n }\n\n // The key range already guarantees expiresAtKey < now, but keep a guard\n // to be resilient to non-standard IndexedDB implementations.\n if (expiresAtKey >= now) {\n cursor.continue();\n return;\n }\n\n const isReclaimable = item.status === 'running' || item.status === 'paused';\n\n // Reclaim policy:\n // - running/paused + expired lease => move back to queued, drop lease\n // - any other status + expired lease => drop lease defensively (shouldn't happen)\n // Note: attempt is NOT reset on reclaim - preserves retry history.\n const { lease: _droppedLease, ...itemWithoutLease } = item;\n const updated: RunQueueItem = isReclaimable\n ? { ...itemWithoutLease, status: 'queued', updatedAt: now }\n : { ...itemWithoutLease, updatedAt: now };\n\n const updateRequest = cursor.update(updated);\n updateRequest.onerror = () => reject(updateRequest.error);\n updateRequest.onsuccess = () => {\n if (isReclaimable) {\n reclaimed.push(item.id);\n }\n cursor.continue();\n };\n };\n });\n });\n },\n\n async recoverOrphanLeases(\n ownerId: string,\n now: number,\n ): Promise<{\n requeuedRunning: Array<{ runId: RunId; prevOwnerId?: string }>;\n adoptedPaused: Array<{ runId: RunId; prevOwnerId?: string }>;\n }> {\n // Validate inputs\n if (!ownerId) {\n throw new Error('ownerId is required');\n }\n if (!Number.isFinite(now)) {\n throw new Error(`Invalid now: ${String(now)}`);\n }\n\n return withTransaction(RR_V3_STORES.QUEUE, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n const statusIndex = store.index('status');\n\n const requeuedRunning: Array<{ runId: RunId; prevOwnerId?: string }> = [];\n const adoptedPaused: Array<{ runId: RunId; prevOwnerId?: string }> = [];\n\n /**\n * 扫描并回收孤儿 running 项\n * @description\n * - 孤儿定义：无租约或 lease.ownerId !== currentOwnerId\n * - 回收策略：status -> queued，清除 lease，保留 attempt\n */\n const recoverRunningItems = (): Promise =>\n new Promise((resolve, reject) => {\n const request = statusIndex.openCursor(IDBKeyRange.only('running'));\n request.onerror = () => reject(request.error);\n request.onsuccess = () => {\n const cursor = request.result;\n if (!cursor) {\n resolve();\n return;\n }\n\n const item = cursor.value as RunQueueItem;\n const prevOwnerId = item.lease?.ownerId;\n\n // 非孤儿：lease 存在且属于当前 ownerId\n const isOrphan = !item.lease || item.lease.ownerId !== ownerId;\n if (!isOrphan) {\n cursor.continue();\n return;\n }\n\n // 回收：移除 lease，状态改为 queued\n const { lease: _droppedLease, ...itemWithoutLease } = item;\n const updated: RunQueueItem = {\n ...itemWithoutLease,\n status: 'queued',\n updatedAt: now,\n };\n\n const updateRequest = cursor.update(updated);\n updateRequest.onerror = () => reject(updateRequest.error);\n updateRequest.onsuccess = () => {\n requeuedRunning.push({\n runId: item.id,\n ...(prevOwnerId ? { prevOwnerId } : {}),\n });\n cursor.continue();\n };\n };\n });\n\n /**\n * 扫描并接管孤儿 paused 项\n * @description\n * - 孤儿定义：无租约或 lease.ownerId !== currentOwnerId\n * - 接管策略：保持 status=paused，更新 lease.ownerId 为新 ownerId，续约 TTL\n */\n const recoverPausedItems = (): Promise =>\n new Promise((resolve, reject) => {\n const request = statusIndex.openCursor(IDBKeyRange.only('paused'));\n request.onerror = () => reject(request.error);\n request.onsuccess = () => {\n const cursor = request.result;\n if (!cursor) {\n resolve();\n return;\n }\n\n const item = cursor.value as RunQueueItem;\n const prevOwnerId = item.lease?.ownerId;\n\n // 非孤儿：lease 存在且属于当前 ownerId\n const isOrphan = !item.lease || item.lease.ownerId !== ownerId;\n if (!isOrphan) {\n cursor.continue();\n return;\n }\n\n // 接管：更新 lease 为新 ownerId，续约 TTL\n const updated: RunQueueItem = {\n ...item,\n updatedAt: now,\n lease: {\n ownerId,\n expiresAt: now + DEFAULT_LEASE_TTL_MS,\n },\n };\n\n const updateRequest = cursor.update(updated);\n updateRequest.onerror = () => reject(updateRequest.error);\n updateRequest.onsuccess = () => {\n adoptedPaused.push({\n runId: item.id,\n ...(prevOwnerId ? { prevOwnerId } : {}),\n });\n cursor.continue();\n };\n };\n });\n\n // 顺序执行：先处理 running，再处理 paused\n await recoverRunningItems();\n await recoverPausedItems();\n\n return { requeuedRunning, adoptedPaused };\n });\n },\n\n async markRunning(runId: RunId, ownerId: string, now: number): Promise {\n await withTransaction(RR_V3_STORES.QUEUE, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n\n const existing = await new Promise((resolve, reject) => {\n const request = store.get(runId);\n request.onsuccess = () => resolve((request.result as RunQueueItem) ?? null);\n request.onerror = () => reject(request.error);\n });\n\n if (!existing) {\n throw new Error(`Queue item \"${runId}\" not found`);\n }\n\n // Attempt semantics:\n // - queued -> running: attempt + 1 (a new scheduling attempt)\n // - paused/running -> running: attempt unchanged (resume/idempotent)\n const nextAttempt = existing.status === 'queued' ? existing.attempt + 1 : existing.attempt;\n\n const updated: RunQueueItem = {\n ...existing,\n status: 'running',\n updatedAt: now,\n attempt: nextAttempt,\n lease: {\n ownerId,\n expiresAt: now + DEFAULT_LEASE_TTL_MS,\n },\n };\n\n return new Promise((resolve, reject) => {\n const request = store.put(updated);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async markPaused(runId: RunId, ownerId: string, now: number): Promise {\n await withTransaction(RR_V3_STORES.QUEUE, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n\n const existing = await new Promise((resolve, reject) => {\n const request = store.get(runId);\n request.onsuccess = () => resolve((request.result as RunQueueItem) ?? null);\n request.onerror = () => reject(request.error);\n });\n\n if (!existing) {\n throw new Error(`Queue item \"${runId}\" not found`);\n }\n\n const updated: RunQueueItem = {\n ...existing,\n status: 'paused',\n updatedAt: now,\n lease: {\n ownerId,\n expiresAt: now + DEFAULT_LEASE_TTL_MS,\n },\n };\n\n return new Promise((resolve, reject) => {\n const request = store.put(updated);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async markDone(runId: RunId, now: number): Promise {\n await withTransaction(RR_V3_STORES.QUEUE, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n return new Promise((resolve, reject) => {\n const request = store.delete(runId);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async cancel(runId: RunId, _now: number, _reason?: string): Promise {\n // 从队列中删除\n await this.markDone(runId, _now);\n },\n\n async get(runId: RunId): Promise {\n return withTransaction(RR_V3_STORES.QUEUE, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n return new Promise((resolve, reject) => {\n const request = store.get(runId);\n request.onsuccess = () => resolve((request.result as RunQueueItem) ?? null);\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async list(status?: QueueItemStatus): Promise {\n return withTransaction(RR_V3_STORES.QUEUE, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.QUEUE];\n\n if (status) {\n // 使用索引查询\n const index = store.index('status');\n return new Promise((resolve, reject) => {\n const request = index.getAll(IDBKeyRange.only(status));\n request.onsuccess = () => resolve(request.result as RunQueueItem[]);\n request.onerror = () => reject(request.error);\n });\n }\n\n // 获取所有\n return new Promise((resolve, reject) => {\n const request = store.getAll();\n request.onsuccess = () => resolve(request.result as RunQueueItem[]);\n request.onerror = () => reject(request.error);\n });\n });\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/runs.ts", "content": "/**\n * @fileoverview RunRecordV3 持久化\n * @description 实现 Run 记录的 CRUD 操作\n */\n\nimport type { RunId } from '../domain/ids';\nimport type { RunRecordV3 } from '../domain/events';\nimport { RUN_SCHEMA_VERSION } from '../domain/events';\nimport { RR_ERROR_CODES, createRRError } from '../domain/errors';\nimport type { RunsStore } from '../engine/storage/storage-port';\nimport { RR_V3_STORES, withTransaction } from './db';\n\n/**\n * 校验 Run 记录结构\n */\nfunction validateRunRecord(record: RunRecordV3): void {\n // 校验 schema 版本\n if (record.schemaVersion !== RUN_SCHEMA_VERSION) {\n throw createRRError(\n RR_ERROR_CODES.VALIDATION_ERROR,\n `Invalid schema version: expected ${RUN_SCHEMA_VERSION}, got ${record.schemaVersion}`,\n );\n }\n\n // 校验必填字段\n if (!record.id) {\n throw createRRError(RR_ERROR_CODES.VALIDATION_ERROR, 'Run id is required');\n }\n if (!record.flowId) {\n throw createRRError(RR_ERROR_CODES.VALIDATION_ERROR, 'Run flowId is required');\n }\n if (!record.status) {\n throw createRRError(RR_ERROR_CODES.VALIDATION_ERROR, 'Run status is required');\n }\n}\n\n/**\n * 创建 RunsStore 实现\n */\nexport function createRunsStore(): RunsStore {\n return {\n async list(): Promise {\n return withTransaction(RR_V3_STORES.RUNS, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.RUNS];\n return new Promise((resolve, reject) => {\n const request = store.getAll();\n request.onsuccess = () => resolve(request.result as RunRecordV3[]);\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async get(id: RunId): Promise {\n return withTransaction(RR_V3_STORES.RUNS, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.RUNS];\n return new Promise((resolve, reject) => {\n const request = store.get(id);\n request.onsuccess = () => resolve((request.result as RunRecordV3) ?? null);\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async save(record: RunRecordV3): Promise {\n // 校验\n validateRunRecord(record);\n\n return withTransaction(RR_V3_STORES.RUNS, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.RUNS];\n return new Promise((resolve, reject) => {\n const request = store.put(record);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async patch(id: RunId, patch: Partial): Promise {\n return withTransaction(RR_V3_STORES.RUNS, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.RUNS];\n\n // 先读取现有记录\n const existing = await new Promise((resolve, reject) => {\n const request = store.get(id);\n request.onsuccess = () => resolve((request.result as RunRecordV3) ?? null);\n request.onerror = () => reject(request.error);\n });\n\n if (!existing) {\n throw createRRError(RR_ERROR_CODES.INTERNAL, `Run \"${id}\" not found`);\n }\n\n // 合并并更新\n const updated: RunRecordV3 = {\n ...existing,\n ...patch,\n id: existing.id, // 确保 id 不变\n schemaVersion: existing.schemaVersion, // 确保版本不变\n updatedAt: Date.now(),\n };\n\n return new Promise((resolve, reject) => {\n const request = store.put(updated);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/record-replay-v3/storage/triggers.ts", "content": "/**\n * @fileoverview 触发器存储\n * @description 实现触发器的 CRUD 操作（Phase 4 完整实现）\n */\n\nimport type { TriggerId } from '../domain/ids';\nimport type { TriggerSpec } from '../domain/triggers';\nimport type { TriggersStore } from '../engine/storage/storage-port';\nimport { RR_V3_STORES, withTransaction } from './db';\n\n/**\n * 创建 TriggersStore 实现\n */\nexport function createTriggersStore(): TriggersStore {\n return {\n async list(): Promise {\n return withTransaction(RR_V3_STORES.TRIGGERS, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.TRIGGERS];\n return new Promise((resolve, reject) => {\n const request = store.getAll();\n request.onsuccess = () => resolve(request.result as TriggerSpec[]);\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async get(id: TriggerId): Promise {\n return withTransaction(RR_V3_STORES.TRIGGERS, 'readonly', async (stores) => {\n const store = stores[RR_V3_STORES.TRIGGERS];\n return new Promise((resolve, reject) => {\n const request = store.get(id);\n request.onsuccess = () => resolve((request.result as TriggerSpec) ?? null);\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async save(spec: TriggerSpec): Promise {\n return withTransaction(RR_V3_STORES.TRIGGERS, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.TRIGGERS];\n return new Promise((resolve, reject) => {\n const request = store.put(spec);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n\n async delete(id: TriggerId): Promise {\n return withTransaction(RR_V3_STORES.TRIGGERS, 'readwrite', async (stores) => {\n const store = stores[RR_V3_STORES.TRIGGERS];\n return new Promise((resolve, reject) => {\n const request = store.delete(id);\n request.onsuccess = () => resolve();\n request.onerror = () => reject(request.error);\n });\n });\n },\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/semantic-similarity.ts", "content": "import type { ModelPreset } from '@/utils/semantic-similarity-engine';\nimport { OffscreenManager } from '@/utils/offscreen-manager';\nimport { BACKGROUND_MESSAGE_TYPES, OFFSCREEN_MESSAGE_TYPES } from '@/common/message-types';\nimport { STORAGE_KEYS, ERROR_MESSAGES } from '@/common/constants';\nimport { hasAnyModelCache } from '@/utils/semantic-similarity-engine';\n\n/**\n * Model configuration state management interface\n */\ninterface ModelConfig {\n modelPreset: ModelPreset;\n modelVersion: 'full' | 'quantized' | 'compressed';\n modelDimension: number;\n}\n\nlet currentBackgroundModelConfig: ModelConfig | null = null;\n\n/**\n * Initialize semantic engine only if model cache exists\n * This is called during plugin startup to avoid downloading models unnecessarily\n */\nexport async function initializeSemanticEngineIfCached(): Promise {\n try {\n console.log('Background: Checking if semantic engine should be initialized from cache...');\n\n const hasCachedModel = await hasAnyModelCache();\n if (!hasCachedModel) {\n console.log('Background: No cached models found, skipping semantic engine initialization');\n return false;\n }\n\n console.log('Background: Found cached models, initializing semantic engine...');\n await initializeDefaultSemanticEngine();\n return true;\n } catch (error) {\n console.error('Background: Error during conditional semantic engine initialization:', error);\n return false;\n }\n}\n\n/**\n * Initialize default semantic engine model\n */\nexport async function initializeDefaultSemanticEngine(): Promise {\n try {\n console.log('Background: Initializing default semantic engine...');\n\n // Update status to initializing\n await updateModelStatus('initializing', 0);\n\n const result = await chrome.storage.local.get([STORAGE_KEYS.SEMANTIC_MODEL, 'selectedVersion']);\n const defaultModel =\n (result[STORAGE_KEYS.SEMANTIC_MODEL] as ModelPreset) || 'multilingual-e5-small';\n const defaultVersion =\n (result.selectedVersion as 'full' | 'quantized' | 'compressed') || 'quantized';\n\n const { PREDEFINED_MODELS } = await import('@/utils/semantic-similarity-engine');\n const modelInfo = PREDEFINED_MODELS[defaultModel];\n\n await OffscreenManager.getInstance().ensureOffscreenDocument();\n\n const response = await chrome.runtime.sendMessage({\n target: 'offscreen',\n type: OFFSCREEN_MESSAGE_TYPES.SIMILARITY_ENGINE_INIT,\n config: {\n useLocalFiles: false,\n modelPreset: defaultModel,\n modelVersion: defaultVersion,\n modelDimension: modelInfo.dimension,\n forceOffscreen: true,\n },\n });\n\n if (response && response.success) {\n currentBackgroundModelConfig = {\n modelPreset: defaultModel,\n modelVersion: defaultVersion,\n modelDimension: modelInfo.dimension,\n };\n console.log('Semantic engine initialized successfully:', currentBackgroundModelConfig);\n\n // Update status to ready\n await updateModelStatus('ready', 100);\n\n // Also initialize ContentIndexer now that semantic engine is ready\n try {\n const { getGlobalContentIndexer } = await import('@/utils/content-indexer');\n const contentIndexer = getGlobalContentIndexer();\n contentIndexer.startSemanticEngineInitialization();\n console.log('ContentIndexer initialization triggered after semantic engine initialization');\n } catch (indexerError) {\n console.warn(\n 'Failed to initialize ContentIndexer after semantic engine initialization:',\n indexerError,\n );\n }\n } else {\n const errorMessage = response?.error || ERROR_MESSAGES.TOOL_EXECUTION_FAILED;\n await updateModelStatus('error', 0, errorMessage, 'unknown');\n throw new Error(errorMessage);\n }\n } catch (error: any) {\n console.error('Background: Failed to initialize default semantic engine:', error);\n const errorMessage = error?.message || 'Unknown error during semantic engine initialization';\n await updateModelStatus('error', 0, errorMessage, 'unknown');\n // Don't throw error, let the extension continue running\n }\n}\n\n/**\n * Check if model switch is needed\n */\nfunction needsModelSwitch(\n modelPreset: ModelPreset,\n modelVersion: 'full' | 'quantized' | 'compressed',\n modelDimension?: number,\n): boolean {\n if (!currentBackgroundModelConfig) {\n return true;\n }\n\n const keyFields = ['modelPreset', 'modelVersion', 'modelDimension'];\n for (const field of keyFields) {\n const newValue =\n field === 'modelPreset'\n ? modelPreset\n : field === 'modelVersion'\n ? modelVersion\n : modelDimension;\n if (newValue !== currentBackgroundModelConfig[field as keyof ModelConfig]) {\n return true;\n }\n }\n\n return false;\n}\n\n/**\n * Handle model switching\n */\nexport async function handleModelSwitch(\n modelPreset: ModelPreset,\n modelVersion: 'full' | 'quantized' | 'compressed' = 'quantized',\n modelDimension?: number,\n previousDimension?: number,\n): Promise<{ success: boolean; error?: string }> {\n try {\n const needsSwitch = needsModelSwitch(modelPreset, modelVersion, modelDimension);\n if (!needsSwitch) {\n await updateModelStatus('ready', 100);\n return { success: true };\n }\n\n await updateModelStatus('downloading', 0);\n\n try {\n await OffscreenManager.getInstance().ensureOffscreenDocument();\n } catch (offscreenError) {\n console.error('Background: Failed to create offscreen document:', offscreenError);\n const errorMessage = `Failed to create offscreen document: ${offscreenError}`;\n await updateModelStatus('error', 0, errorMessage, 'unknown');\n return { success: false, error: errorMessage };\n }\n\n const response = await chrome.runtime.sendMessage({\n target: 'offscreen',\n type: OFFSCREEN_MESSAGE_TYPES.SIMILARITY_ENGINE_INIT,\n config: {\n useLocalFiles: false,\n modelPreset: modelPreset,\n modelVersion: modelVersion,\n modelDimension: modelDimension,\n forceOffscreen: true,\n },\n });\n\n if (response && response.success) {\n currentBackgroundModelConfig = {\n modelPreset: modelPreset,\n modelVersion: modelVersion,\n modelDimension: modelDimension!,\n };\n\n // Only reinitialize ContentIndexer when dimension changes\n try {\n if (modelDimension && previousDimension && modelDimension !== previousDimension) {\n const { getGlobalContentIndexer } = await import('@/utils/content-indexer');\n const contentIndexer = getGlobalContentIndexer();\n await contentIndexer.reinitialize();\n }\n } catch (indexerError) {\n console.warn('Background: Failed to reinitialize ContentIndexer:', indexerError);\n }\n\n await updateModelStatus('ready', 100);\n return { success: true };\n } else {\n const errorMessage = response?.error || 'Failed to switch model';\n const errorType = analyzeErrorType(errorMessage);\n await updateModelStatus('error', 0, errorMessage, errorType);\n throw new Error(errorMessage);\n }\n } catch (error: any) {\n console.error('Model switch failed:', error);\n const errorMessage = error.message || 'Unknown error';\n const errorType = analyzeErrorType(errorMessage);\n await updateModelStatus('error', 0, errorMessage, errorType);\n return { success: false, error: errorMessage };\n }\n}\n\n/**\n * Get model status\n */\nexport async function handleGetModelStatus(): Promise<{\n success: boolean;\n status?: any;\n error?: string;\n}> {\n try {\n if (typeof chrome === 'undefined' || !chrome.storage || !chrome.storage.local) {\n console.error('Background: chrome.storage.local is not available for status query');\n return {\n success: true,\n status: {\n initializationStatus: 'idle',\n downloadProgress: 0,\n isDownloading: false,\n lastUpdated: Date.now(),\n },\n };\n }\n\n const result = await chrome.storage.local.get(['modelState']);\n const modelState = result.modelState || {\n status: 'idle',\n downloadProgress: 0,\n isDownloading: false,\n lastUpdated: Date.now(),\n };\n\n return {\n success: true,\n status: {\n initializationStatus: modelState.status,\n downloadProgress: modelState.downloadProgress,\n isDownloading: modelState.isDownloading,\n lastUpdated: modelState.lastUpdated,\n errorMessage: modelState.errorMessage,\n errorType: modelState.errorType,\n },\n };\n } catch (error: any) {\n console.error('Failed to get model status:', error);\n return { success: false, error: error.message };\n }\n}\n\n/**\n * Update model status\n */\nexport async function updateModelStatus(\n status: string,\n progress: number,\n errorMessage?: string,\n errorType?: string,\n): Promise {\n try {\n // Check if chrome.storage is available\n if (typeof chrome === 'undefined' || !chrome.storage || !chrome.storage.local) {\n console.error('Background: chrome.storage.local is not available for status update');\n return;\n }\n\n const modelState = {\n status,\n downloadProgress: progress,\n isDownloading: status === 'downloading' || status === 'initializing',\n lastUpdated: Date.now(),\n errorMessage: errorMessage || '',\n errorType: errorType || '',\n };\n await chrome.storage.local.set({ modelState });\n } catch (error) {\n console.error('Failed to update model status:', error);\n }\n}\n\n/**\n * Handle model status updates from offscreen document\n */\nexport async function handleUpdateModelStatus(\n modelState: any,\n): Promise<{ success: boolean; error?: string }> {\n try {\n // Check if chrome.storage is available\n if (typeof chrome === 'undefined' || !chrome.storage || !chrome.storage.local) {\n console.error('Background: chrome.storage.local is not available');\n return { success: false, error: 'chrome.storage.local is not available' };\n }\n\n await chrome.storage.local.set({ modelState });\n return { success: true };\n } catch (error: any) {\n console.error('Background: Failed to update model status:', error);\n return { success: false, error: error.message };\n }\n}\n\n/**\n * Analyze error type based on error message\n */\nfunction analyzeErrorType(errorMessage: string): 'network' | 'file' | 'unknown' {\n const message = errorMessage.toLowerCase();\n\n if (\n message.includes('network') ||\n message.includes('fetch') ||\n message.includes('timeout') ||\n message.includes('connection') ||\n message.includes('cors') ||\n message.includes('failed to fetch')\n ) {\n return 'network';\n }\n\n if (\n message.includes('corrupt') ||\n message.includes('invalid') ||\n message.includes('format') ||\n message.includes('parse') ||\n message.includes('decode') ||\n message.includes('onnx')\n ) {\n return 'file';\n }\n\n return 'unknown';\n}\n\n/**\n * Initialize semantic similarity module message listeners\n */\nexport const initSemanticSimilarityListener = () => {\n chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {\n if (message.type === BACKGROUND_MESSAGE_TYPES.SWITCH_SEMANTIC_MODEL) {\n handleModelSwitch(\n message.modelPreset,\n message.modelVersion,\n message.modelDimension,\n message.previousDimension,\n )\n .then((result: { success: boolean; error?: string }) => sendResponse(result))\n .catch((error: any) => sendResponse({ success: false, error: error.message }));\n return true;\n } else if (message.type === BACKGROUND_MESSAGE_TYPES.GET_MODEL_STATUS) {\n handleGetModelStatus()\n .then((result: { success: boolean; status?: any; error?: string }) => sendResponse(result))\n .catch((error: any) => sendResponse({ success: false, error: error.message }));\n return true;\n } else if (message.type === BACKGROUND_MESSAGE_TYPES.UPDATE_MODEL_STATUS) {\n handleUpdateModelStatus(message.modelState)\n .then((result: { success: boolean; error?: string }) => sendResponse(result))\n .catch((error: any) => sendResponse({ success: false, error: error.message }));\n return true;\n } else if (message.type === BACKGROUND_MESSAGE_TYPES.INITIALIZE_SEMANTIC_ENGINE) {\n initializeDefaultSemanticEngine()\n .then(() => sendResponse({ success: true }))\n .catch((error: any) => sendResponse({ success: false, error: error.message }));\n return true;\n }\n });\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/storage-manager.ts", "content": "import { BACKGROUND_MESSAGE_TYPES } from '@/common/message-types';\n\n/**\n * Get storage statistics\n */\nexport async function handleGetStorageStats(): Promise<{\n success: boolean;\n stats?: any;\n error?: string;\n}> {\n try {\n // Get ContentIndexer statistics\n const { getGlobalContentIndexer } = await import('@/utils/content-indexer');\n const contentIndexer = getGlobalContentIndexer();\n\n // Note: Semantic engine initialization is now user-controlled\n // ContentIndexer will be initialized when user manually triggers semantic engine initialization\n\n // Get statistics\n const stats = contentIndexer.getStats();\n\n return {\n success: true,\n stats: {\n indexedPages: stats.indexedPages || 0,\n totalDocuments: stats.totalDocuments || 0,\n totalTabs: stats.totalTabs || 0,\n indexSize: stats.indexSize || 0,\n isInitialized: stats.isInitialized || false,\n semanticEngineReady: stats.semanticEngineReady || false,\n semanticEngineInitializing: stats.semanticEngineInitializing || false,\n },\n };\n } catch (error: any) {\n console.error('Background: Failed to get storage stats:', error);\n return {\n success: false,\n error: error.message,\n stats: {\n indexedPages: 0,\n totalDocuments: 0,\n totalTabs: 0,\n indexSize: 0,\n isInitialized: false,\n semanticEngineReady: false,\n semanticEngineInitializing: false,\n },\n };\n }\n}\n\n/**\n * Clear all data\n */\nexport async function handleClearAllData(): Promise<{ success: boolean; error?: string }> {\n try {\n // 1. Clear all ContentIndexer indexes\n try {\n const { getGlobalContentIndexer } = await import('@/utils/content-indexer');\n const contentIndexer = getGlobalContentIndexer();\n\n await contentIndexer.clearAllIndexes();\n console.log('Storage: ContentIndexer indexes cleared successfully');\n } catch (indexerError) {\n console.warn('Background: Failed to clear ContentIndexer indexes:', indexerError);\n // Continue with other cleanup operations\n }\n\n // 2. Clear all VectorDatabase data\n try {\n const { clearAllVectorData } = await import('@/utils/vector-database');\n await clearAllVectorData();\n console.log('Storage: Vector database data cleared successfully');\n } catch (vectorError) {\n console.warn('Background: Failed to clear vector data:', vectorError);\n // Continue with other cleanup operations\n }\n\n // 3. Clear related data in chrome.storage (preserve model preferences)\n try {\n const keysToRemove = ['vectorDatabaseStats', 'lastCleanupTime', 'contentIndexerStats'];\n await chrome.storage.local.remove(keysToRemove);\n console.log('Storage: Chrome storage data cleared successfully');\n } catch (storageError) {\n console.warn('Background: Failed to clear chrome storage data:', storageError);\n }\n\n return { success: true };\n } catch (error: any) {\n console.error('Background: Failed to clear all data:', error);\n return { success: false, error: error.message };\n }\n}\n\n/**\n * Initialize storage manager module message listeners\n */\nexport const initStorageManagerListener = () => {\n chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {\n if (message.type === BACKGROUND_MESSAGE_TYPES.GET_STORAGE_STATS) {\n handleGetStorageStats()\n .then((result: { success: boolean; stats?: any; error?: string }) => sendResponse(result))\n .catch((error: any) => sendResponse({ success: false, error: error.message }));\n return true;\n } else if (message.type === BACKGROUND_MESSAGE_TYPES.CLEAR_ALL_DATA) {\n handleClearAllData()\n .then((result: { success: boolean; error?: string }) => sendResponse(result))\n .catch((error: any) => sendResponse({ success: false, error: error.message }));\n return true;\n }\n });\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/base-browser.ts", "content": "import { ToolExecutor } from '@/common/tool-handler';\nimport type { ToolResult } from '@/common/tool-handler';\nimport { TIMEOUTS, ERROR_MESSAGES } from '@/common/constants';\n\nconst PING_TIMEOUT_MS = 300;\n\n/**\n * Base class for browser tool executors\n */\nexport abstract class BaseBrowserToolExecutor implements ToolExecutor {\n abstract name: string;\n abstract execute(args: any): Promise;\n\n /**\n * Inject content script into tab\n */\n protected async injectContentScript(\n tabId: number,\n files: string[],\n injectImmediately = false,\n world: 'MAIN' | 'ISOLATED' = 'ISOLATED',\n allFrames: boolean = false,\n frameIds?: number[],\n ): Promise {\n console.log(`Injecting ${files.join(', ')} into tab ${tabId}`);\n\n // check if script is already injected\n try {\n const pingFrameId = frameIds?.[0];\n const response = await Promise.race([\n typeof pingFrameId === 'number'\n ? chrome.tabs.sendMessage(\n tabId,\n { action: `${this.name}_ping` },\n { frameId: pingFrameId },\n )\n : chrome.tabs.sendMessage(tabId, { action: `${this.name}_ping` }),\n new Promise((_, reject) =>\n setTimeout(\n () => reject(new Error(`${this.name} Ping action to tab ${tabId} timed out`)),\n PING_TIMEOUT_MS,\n ),\n ),\n ]);\n\n if (response && response.status === 'pong') {\n console.log(\n `pong received for action '${this.name}' in tab ${tabId}. Assuming script is active.`,\n );\n return;\n } else {\n console.warn(`Unexpected ping response in tab ${tabId}:`, response);\n }\n } catch (error) {\n console.error(\n `ping content script failed: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n\n try {\n const target: { tabId: number; allFrames?: boolean; frameIds?: number[] } = { tabId };\n if (frameIds && frameIds.length > 0) {\n target.frameIds = frameIds;\n } else if (allFrames) {\n target.allFrames = true;\n }\n await chrome.scripting.executeScript({\n target,\n files,\n injectImmediately,\n world,\n } as any);\n console.log(`'${files.join(', ')}' injection successful for tab ${tabId}`);\n } catch (injectionError) {\n const errorMessage =\n injectionError instanceof Error ? injectionError.message : String(injectionError);\n console.error(\n `Content script '${files.join(', ')}' injection failed for tab ${tabId}: ${errorMessage}`,\n );\n throw new Error(\n `${ERROR_MESSAGES.TOOL_EXECUTION_FAILED}: Failed to inject content script in tab ${tabId}: ${errorMessage}`,\n );\n }\n }\n\n /**\n * Send message to tab\n */\n protected async sendMessageToTab(tabId: number, message: any, frameId?: number): Promise {\n try {\n const response =\n typeof frameId === 'number'\n ? await chrome.tabs.sendMessage(tabId, message, { frameId })\n : await chrome.tabs.sendMessage(tabId, message);\n\n if (response && response.error) {\n throw new Error(String(response.error));\n }\n\n return response;\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n console.error(\n `Error sending message to tab ${tabId} for action ${message?.action || 'unknown'}: ${errorMessage}`,\n );\n\n if (error instanceof Error) {\n throw error;\n }\n throw new Error(errorMessage);\n }\n }\n\n /**\n * Try to get an existing tab by id. Returns null when not found.\n */\n protected async tryGetTab(tabId?: number): Promise {\n if (typeof tabId !== 'number') return null;\n try {\n return await chrome.tabs.get(tabId);\n } catch {\n return null;\n }\n }\n\n /**\n * Get the active tab in the current window. Throws when not found.\n */\n protected async getActiveTabOrThrow(): Promise {\n const [active] = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!active || !active.id) throw new Error('Active tab not found');\n return active;\n }\n\n /**\n * Optionally focus window and/or activate tab. Defaults preserve current behavior\n * when caller sets activate/focus flags explicitly.\n */\n protected async ensureFocus(\n tab: chrome.tabs.Tab,\n options: { activate?: boolean; focusWindow?: boolean } = {},\n ): Promise {\n const activate = options.activate === true;\n const focusWindow = options.focusWindow === true;\n if (focusWindow && typeof tab.windowId === 'number') {\n await chrome.windows.update(tab.windowId, { focused: true });\n }\n if (activate && typeof tab.id === 'number') {\n await chrome.tabs.update(tab.id, { active: true });\n }\n }\n\n /**\n * Get the active tab. When windowId provided, search within that window; otherwise currentWindow.\n */\n protected async getActiveTabInWindow(windowId?: number): Promise {\n if (typeof windowId === 'number') {\n const tabs = await chrome.tabs.query({ active: true, windowId });\n return tabs && tabs[0] ? tabs[0] : null;\n }\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n return tabs && tabs[0] ? tabs[0] : null;\n }\n\n /**\n * Same as getActiveTabInWindow, but throws if not found.\n */\n protected async getActiveTabOrThrowInWindow(windowId?: number): Promise {\n const tab = await this.getActiveTabInWindow(windowId);\n if (!tab || !tab.id) throw new Error('Active tab not found');\n return tab;\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/bookmark.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { getMessage } from '@/utils/i18n';\n\n/**\n * Bookmark search tool parameters interface\n */\ninterface BookmarkSearchToolParams {\n query?: string; // Search keywords for matching bookmark titles and URLs\n maxResults?: number; // Maximum number of results to return\n folderPath?: string; // Optional, specify which folder to search in (can be ID or path string like \"Work/Projects\")\n}\n\n/**\n * Bookmark add tool parameters interface\n */\ninterface BookmarkAddToolParams {\n url?: string; // URL to add as bookmark, if not provided use current active tab URL\n title?: string; // Bookmark title, if not provided use page title\n parentId?: string; // Parent folder ID or path string (like \"Work/Projects\"), if not provided add to \"Bookmarks Bar\" folder\n createFolder?: boolean; // Whether to automatically create parent folder if it doesn't exist\n}\n\n/**\n * Bookmark delete tool parameters interface\n */\ninterface BookmarkDeleteToolParams {\n bookmarkId?: string; // ID of bookmark to delete\n url?: string; // URL of bookmark to delete (if ID not provided, search by URL)\n title?: string; // Title of bookmark to delete (used for auxiliary matching, used together with URL)\n}\n\n// --- Helper Functions ---\n\n/**\n * Get the complete folder path of a bookmark\n * @param bookmarkNodeId ID of the bookmark or folder\n * @returns Returns folder path string (e.g., \"Bookmarks Bar > Folder A > Subfolder B\")\n */\nasync function getBookmarkFolderPath(bookmarkNodeId: string): Promise {\n const pathParts: string[] = [];\n\n try {\n // First get the node itself to check if it's a bookmark or folder\n const initialNodes = await chrome.bookmarks.get(bookmarkNodeId);\n if (initialNodes.length > 0 && initialNodes[0]) {\n const initialNode = initialNodes[0];\n\n // Build path starting from parent node (same for both bookmarks and folders)\n let pathNodeId = initialNode.parentId;\n while (pathNodeId) {\n const parentNodes = await chrome.bookmarks.get(pathNodeId);\n if (parentNodes.length === 0) break;\n\n const parentNode = parentNodes[0];\n if (parentNode.title) {\n pathParts.unshift(parentNode.title);\n }\n\n if (!parentNode.parentId) break;\n pathNodeId = parentNode.parentId;\n }\n }\n } catch (error) {\n console.error(`Error getting bookmark path for node ID ${bookmarkNodeId}:`, error);\n return pathParts.join(' > ') || 'Error getting path';\n }\n\n return pathParts.join(' > ');\n}\n\n/**\n * Find bookmark folder by ID or path string\n * If it's an ID, validate it\n * If it's a path string, try to parse it\n * @param pathOrId Path string (e.g., \"Work/Projects\") or folder ID\n * @returns Returns folder node, or null if not found\n */\nasync function findFolderByPathOrId(\n pathOrId: string,\n): Promise {\n try {\n const nodes = await chrome.bookmarks.get(pathOrId);\n if (nodes && nodes.length > 0 && !nodes[0].url) {\n return nodes[0];\n }\n } catch (e) {\n // do nothing, try to parse as path string\n }\n\n const pathParts = pathOrId\n .split('/')\n .map((p) => p.trim())\n .filter((p) => p.length > 0);\n if (pathParts.length === 0) return null;\n\n const rootChildren = await chrome.bookmarks.getChildren('0');\n\n let currentNodes = rootChildren;\n let foundFolder: chrome.bookmarks.BookmarkTreeNode | null = null;\n\n for (let i = 0; i < pathParts.length; i++) {\n const part = pathParts[i];\n foundFolder = null;\n let matchedNodeThisLevel: chrome.bookmarks.BookmarkTreeNode | null = null;\n\n for (const node of currentNodes) {\n if (!node.url && node.title.toLowerCase() === part.toLowerCase()) {\n matchedNodeThisLevel = node;\n break;\n }\n }\n\n if (matchedNodeThisLevel) {\n if (i === pathParts.length - 1) {\n foundFolder = matchedNodeThisLevel;\n } else {\n currentNodes = await chrome.bookmarks.getChildren(matchedNodeThisLevel.id);\n }\n } else {\n return null;\n }\n }\n\n return foundFolder;\n}\n\n/**\n * Create folder path (if it doesn't exist)\n * @param folderPath Folder path string (e.g., \"Work/Projects/Subproject\")\n * @param parentId Optional parent folder ID, defaults to \"Bookmarks Bar\"\n * @returns Returns the created or found final folder node\n */\nasync function createFolderPath(\n folderPath: string,\n parentId?: string,\n): Promise {\n const pathParts = folderPath\n .split('/')\n .map((p) => p.trim())\n .filter((p) => p.length > 0);\n\n if (pathParts.length === 0) {\n throw new Error('Folder path cannot be empty');\n }\n\n // If no parent ID specified, use \"Bookmarks Bar\" folder\n let currentParentId: string = parentId || '';\n if (!currentParentId) {\n const rootChildren = await chrome.bookmarks.getChildren('0');\n // Find \"Bookmarks Bar\" folder (usually ID is '1', but search by title for compatibility)\n const bookmarkBarFolder = rootChildren.find(\n (node) =>\n !node.url &&\n (node.title === getMessage('bookmarksBarLabel') ||\n node.title === 'Bookmarks bar' ||\n node.title === 'Bookmarks Bar'),\n );\n currentParentId = bookmarkBarFolder?.id || '1'; // fallback to default ID\n }\n\n let currentFolder: chrome.bookmarks.BookmarkTreeNode | null = null;\n\n // Create or find folders level by level\n for (const folderName of pathParts) {\n const children: chrome.bookmarks.BookmarkTreeNode[] =\n await chrome.bookmarks.getChildren(currentParentId);\n\n // Check if folder with same name already exists\n const existingFolder: chrome.bookmarks.BookmarkTreeNode | undefined = children.find(\n (child: chrome.bookmarks.BookmarkTreeNode) =>\n !child.url && child.title.toLowerCase() === folderName.toLowerCase(),\n );\n\n if (existingFolder) {\n currentFolder = existingFolder;\n currentParentId = existingFolder.id;\n } else {\n // Create new folder\n currentFolder = await chrome.bookmarks.create({\n parentId: currentParentId,\n title: folderName,\n });\n currentParentId = currentFolder.id;\n }\n }\n\n if (!currentFolder) {\n throw new Error('Failed to create folder path');\n }\n\n return currentFolder;\n}\n\n/**\n * Flatten bookmark tree (or node array) to bookmark list (excluding folders)\n * @param nodes Bookmark tree nodes to flatten\n * @returns Returns actual bookmark node array (nodes with URLs)\n */\nfunction flattenBookmarkNodesToBookmarks(\n nodes: chrome.bookmarks.BookmarkTreeNode[],\n): chrome.bookmarks.BookmarkTreeNode[] {\n const result: chrome.bookmarks.BookmarkTreeNode[] = [];\n const stack = [...nodes]; // Use stack for iterative traversal to avoid deep recursion issues\n\n while (stack.length > 0) {\n const node = stack.pop();\n if (!node) continue;\n\n if (node.url) {\n // It's a bookmark\n result.push(node);\n }\n\n if (node.children) {\n // Add child nodes to stack for processing\n for (let i = node.children.length - 1; i >= 0; i--) {\n stack.push(node.children[i]);\n }\n }\n }\n\n return result;\n}\n\n/**\n * Find bookmarks by URL and title\n * @param url Bookmark URL\n * @param title Optional bookmark title for auxiliary matching\n * @returns Returns array of matching bookmarks\n */\nasync function findBookmarksByUrl(\n url: string,\n title?: string,\n): Promise {\n // Use Chrome API to search by URL\n const searchResults = await chrome.bookmarks.search({ url });\n\n if (!title) {\n return searchResults;\n }\n\n // If title is provided, further filter results\n const titleLower = title.toLowerCase();\n return searchResults.filter(\n (bookmark) => bookmark.title && bookmark.title.toLowerCase().includes(titleLower),\n );\n}\n\n/**\n * Bookmark search tool\n * Used to search bookmarks in Chrome browser\n */\nclass BookmarkSearchTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.BOOKMARK_SEARCH;\n\n /**\n * Execute bookmark search\n */\n async execute(args: BookmarkSearchToolParams): Promise {\n const { query = '', maxResults = 50, folderPath } = args;\n\n console.log(\n `BookmarkSearchTool: Searching bookmarks, keywords: \"${query}\", folder path: \"${folderPath}\"`,\n );\n\n try {\n let bookmarksToSearch: chrome.bookmarks.BookmarkTreeNode[] = [];\n let targetFolderNode: chrome.bookmarks.BookmarkTreeNode | null = null;\n\n // If folder path is specified, find that folder first\n if (folderPath) {\n targetFolderNode = await findFolderByPathOrId(folderPath);\n if (!targetFolderNode) {\n return createErrorResponse(`Specified folder not found: \"${folderPath}\"`);\n }\n // Get all bookmarks in that folder and its subfolders\n const subTree = await chrome.bookmarks.getSubTree(targetFolderNode.id);\n bookmarksToSearch =\n subTree.length > 0 ? flattenBookmarkNodesToBookmarks(subTree[0].children || []) : [];\n }\n\n let filteredBookmarks: chrome.bookmarks.BookmarkTreeNode[];\n\n if (query) {\n if (targetFolderNode) {\n // Has query keywords and specified folder: manually filter bookmarks from folder\n const lowerCaseQuery = query.toLowerCase();\n filteredBookmarks = bookmarksToSearch.filter(\n (bookmark) =>\n (bookmark.title && bookmark.title.toLowerCase().includes(lowerCaseQuery)) ||\n (bookmark.url && bookmark.url.toLowerCase().includes(lowerCaseQuery)),\n );\n } else {\n // Has query keywords but no specified folder: use API search\n filteredBookmarks = await chrome.bookmarks.search({ query });\n // API search may return folders (if title matches), filter them out\n filteredBookmarks = filteredBookmarks.filter((item) => !!item.url);\n }\n } else {\n // No query keywords\n if (!targetFolderNode) {\n // No folder path specified, get all bookmarks\n const tree = await chrome.bookmarks.getTree();\n bookmarksToSearch = flattenBookmarkNodesToBookmarks(tree);\n }\n filteredBookmarks = bookmarksToSearch;\n }\n\n // Limit number of results\n const limitedResults = filteredBookmarks.slice(0, maxResults);\n\n // Add folder path information for each bookmark\n const resultsWithPath = await Promise.all(\n limitedResults.map(async (bookmark) => {\n const path = await getBookmarkFolderPath(bookmark.id);\n return {\n id: bookmark.id,\n title: bookmark.title,\n url: bookmark.url,\n dateAdded: bookmark.dateAdded,\n folderPath: path,\n };\n }),\n );\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(\n {\n success: true,\n totalResults: resultsWithPath.length,\n query: query || null,\n folderSearched: targetFolderNode\n ? targetFolderNode.title || targetFolderNode.id\n : 'All bookmarks',\n bookmarks: resultsWithPath,\n },\n null,\n 2,\n ),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error searching bookmarks:', error);\n return createErrorResponse(\n `Error searching bookmarks: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\n/**\n * Bookmark add tool\n * Used to add new bookmarks to Chrome browser\n */\nclass BookmarkAddTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.BOOKMARK_ADD;\n\n /**\n * Execute add bookmark operation\n */\n async execute(args: BookmarkAddToolParams): Promise {\n const { url, title, parentId, createFolder = false } = args;\n\n console.log(`BookmarkAddTool: Adding bookmark, options:`, args);\n\n try {\n // If no URL provided, use current active tab\n let bookmarkUrl = url;\n let bookmarkTitle = title;\n\n if (!bookmarkUrl) {\n // Get current active tab\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!tabs[0] || !tabs[0].url) {\n // tab.url might be undefined (e.g., chrome:// pages)\n return createErrorResponse('No active tab with valid URL found, and no URL provided');\n }\n\n bookmarkUrl = tabs[0].url;\n if (!bookmarkTitle) {\n bookmarkTitle = tabs[0].title || bookmarkUrl; // If tab title is empty, use URL as title\n }\n }\n\n if (!bookmarkUrl) {\n // Should have been caught above, but as a safety measure\n return createErrorResponse('URL is required to create bookmark');\n }\n\n // Parse parentId (could be ID or path string)\n let actualParentId: string | undefined = undefined;\n if (parentId) {\n let folderNode = await findFolderByPathOrId(parentId);\n\n if (!folderNode && createFolder) {\n // If folder doesn't exist and creation is allowed, create folder path\n try {\n folderNode = await createFolderPath(parentId);\n } catch (createError) {\n return createErrorResponse(\n `Failed to create folder path: ${createError instanceof Error ? createError.message : String(createError)}`,\n );\n }\n }\n\n if (folderNode) {\n actualParentId = folderNode.id;\n } else {\n // Check if parentId might be a direct ID missed by findFolderByPathOrId (e.g., root folder '1')\n try {\n const nodes = await chrome.bookmarks.get(parentId);\n if (nodes && nodes.length > 0 && !nodes[0].url) {\n actualParentId = nodes[0].id;\n } else {\n return createErrorResponse(\n `Specified parent folder (ID/path: \"${parentId}\") not found or is not a folder${createFolder ? ', and creation failed' : '. You can set createFolder=true to auto-create folders'}`,\n );\n }\n } catch (e) {\n return createErrorResponse(\n `Specified parent folder (ID/path: \"${parentId}\") not found or invalid${createFolder ? ', and creation failed' : '. You can set createFolder=true to auto-create folders'}`,\n );\n }\n }\n } else {\n // If no parentId specified, default to \"Bookmarks Bar\"\n const rootChildren = await chrome.bookmarks.getChildren('0');\n const bookmarkBarFolder = rootChildren.find(\n (node) =>\n !node.url &&\n (node.title === getMessage('bookmarksBarLabel') ||\n node.title === 'Bookmarks bar' ||\n node.title === 'Bookmarks Bar'),\n );\n actualParentId = bookmarkBarFolder?.id || '1'; // fallback to default ID\n }\n // If actualParentId is still undefined, chrome.bookmarks.create will use default \"Other Bookmarks\", but we've set Bookmarks Bar\n\n // Create bookmark\n const newBookmark = await chrome.bookmarks.create({\n parentId: actualParentId, // If undefined, API uses default value\n title: bookmarkTitle || bookmarkUrl, // Ensure title is never empty\n url: bookmarkUrl,\n });\n\n // Get bookmark path\n const path = await getBookmarkFolderPath(newBookmark.id);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(\n {\n success: true,\n message: 'Bookmark added successfully',\n bookmark: {\n id: newBookmark.id,\n title: newBookmark.title,\n url: newBookmark.url,\n dateAdded: newBookmark.dateAdded,\n folderPath: path,\n },\n folderCreated: createFolder && parentId ? 'Folder created if necessary' : false,\n },\n null,\n 2,\n ),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error adding bookmark:', error);\n const errorMessage = error instanceof Error ? error.message : String(error);\n\n // Provide more specific error messages for common error cases, such as trying to bookmark chrome:// URLs\n if (errorMessage.includes(\"Can't bookmark URLs of type\")) {\n return createErrorResponse(\n `Error adding bookmark: Cannot bookmark this type of URL (e.g., chrome:// system pages). ${errorMessage}`,\n );\n }\n\n return createErrorResponse(`Error adding bookmark: ${errorMessage}`);\n }\n }\n}\n\n/**\n * Bookmark delete tool\n * Used to delete bookmarks in Chrome browser\n */\nclass BookmarkDeleteTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.BOOKMARK_DELETE;\n\n /**\n * Execute delete bookmark operation\n */\n async execute(args: BookmarkDeleteToolParams): Promise {\n const { bookmarkId, url, title } = args;\n\n console.log(`BookmarkDeleteTool: Deleting bookmark, options:`, args);\n\n if (!bookmarkId && !url) {\n return createErrorResponse('Must provide bookmark ID or URL to delete bookmark');\n }\n\n try {\n let bookmarksToDelete: chrome.bookmarks.BookmarkTreeNode[] = [];\n\n if (bookmarkId) {\n // Delete by ID\n try {\n const nodes = await chrome.bookmarks.get(bookmarkId);\n if (nodes && nodes.length > 0 && nodes[0].url) {\n bookmarksToDelete = nodes;\n } else {\n return createErrorResponse(\n `Bookmark with ID \"${bookmarkId}\" not found, or the ID does not correspond to a bookmark`,\n );\n }\n } catch (error) {\n return createErrorResponse(`Invalid bookmark ID: \"${bookmarkId}\"`);\n }\n } else if (url) {\n // Delete by URL\n bookmarksToDelete = await findBookmarksByUrl(url, title);\n if (bookmarksToDelete.length === 0) {\n return createErrorResponse(\n `No bookmark found with URL \"${url}\"${title ? ` (title contains: \"${title}\")` : ''}`,\n );\n }\n }\n\n // Delete found bookmarks\n const deletedBookmarks = [];\n const errors = [];\n\n for (const bookmark of bookmarksToDelete) {\n try {\n // Get path information before deletion\n const path = await getBookmarkFolderPath(bookmark.id);\n\n await chrome.bookmarks.remove(bookmark.id);\n\n deletedBookmarks.push({\n id: bookmark.id,\n title: bookmark.title,\n url: bookmark.url,\n folderPath: path,\n });\n } catch (error) {\n const errorMsg = error instanceof Error ? error.message : String(error);\n errors.push(\n `Failed to delete bookmark \"${bookmark.title}\" (ID: ${bookmark.id}): ${errorMsg}`,\n );\n }\n }\n\n if (deletedBookmarks.length === 0) {\n return createErrorResponse(`Failed to delete bookmarks: ${errors.join('; ')}`);\n }\n\n const result: any = {\n success: true,\n message: `Successfully deleted ${deletedBookmarks.length} bookmark(s)`,\n deletedBookmarks,\n };\n\n if (errors.length > 0) {\n result.partialSuccess = true;\n result.errors = errors;\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(result, null, 2),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error deleting bookmark:', error);\n return createErrorResponse(\n `Error deleting bookmark: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const bookmarkSearchTool = new BookmarkSearchTool();\nexport const bookmarkAddTool = new BookmarkAddTool();\nexport const bookmarkDeleteTool = new BookmarkDeleteTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/common.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { captureFrameOnAction, isAutoCaptureActive } from './gif-recorder';\n\n// Default window dimensions\nconst DEFAULT_WINDOW_WIDTH = 1280;\nconst DEFAULT_WINDOW_HEIGHT = 720;\n\ninterface NavigateToolParams {\n url?: string;\n newWindow?: boolean;\n width?: number;\n height?: number;\n refresh?: boolean;\n tabId?: number;\n windowId?: number;\n background?: boolean; // when true, do not activate tab or focus window\n}\n\n/**\n * Tool for navigating to URLs in browser tabs or windows\n */\nclass NavigateTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.NAVIGATE;\n\n /**\n * Trigger GIF auto-capture after successful navigation\n */\n private async triggerAutoCapture(tabId: number, url?: string): Promise {\n if (!isAutoCaptureActive(tabId)) {\n return;\n }\n try {\n await captureFrameOnAction(tabId, { type: 'navigate', url });\n } catch (error) {\n console.warn('[NavigateTool] Auto-capture failed:', error);\n }\n }\n\n async execute(args: NavigateToolParams): Promise {\n const {\n newWindow = false,\n width,\n height,\n url,\n refresh = false,\n tabId,\n background,\n windowId,\n } = args;\n\n console.log(\n `Attempting to ${refresh ? 'refresh current tab' : `open URL: ${url}`} with options:`,\n args,\n );\n\n try {\n // Handle refresh option first\n if (refresh) {\n console.log('Refreshing current active tab');\n const explicit = await this.tryGetTab(tabId);\n // Get target tab (explicit or active in provided window)\n const targetTab = explicit || (await this.getActiveTabOrThrowInWindow(windowId));\n if (!targetTab.id) return createErrorResponse('No target tab found to refresh');\n await chrome.tabs.reload(targetTab.id);\n\n console.log(`Refreshed tab ID: ${targetTab.id}`);\n\n // Get updated tab information\n const updatedTab = await chrome.tabs.get(targetTab.id);\n\n // Trigger auto-capture on refresh\n await this.triggerAutoCapture(updatedTab.id!, updatedTab.url);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'Successfully refreshed current tab',\n tabId: updatedTab.id,\n windowId: updatedTab.windowId,\n url: updatedTab.url,\n }),\n },\n ],\n isError: false,\n };\n }\n\n // Validate that url is provided when not refreshing\n if (!url) {\n return createErrorResponse('URL parameter is required when refresh is not true');\n }\n\n // Handle history navigation: url=\"back\" or url=\"forward\"\n if (url === 'back' || url === 'forward') {\n const explicitTab = await this.tryGetTab(tabId);\n const targetTab = explicitTab || (await this.getActiveTabOrThrowInWindow(windowId));\n if (!targetTab.id) {\n return createErrorResponse('No target tab found for history navigation');\n }\n\n // Respect background flag for focus behavior\n await this.ensureFocus(targetTab, {\n activate: background !== true,\n focusWindow: background !== true,\n });\n\n if (url === 'forward') {\n await chrome.tabs.goForward(targetTab.id);\n console.log(`Navigated forward in tab ID: ${targetTab.id}`);\n } else {\n await chrome.tabs.goBack(targetTab.id);\n console.log(`Navigated back in tab ID: ${targetTab.id}`);\n }\n\n const updatedTab = await chrome.tabs.get(targetTab.id);\n\n // Trigger auto-capture on history navigation\n await this.triggerAutoCapture(updatedTab.id!, updatedTab.url);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: `Successfully navigated ${url} in browser history`,\n tabId: updatedTab.id,\n windowId: updatedTab.windowId,\n url: updatedTab.url,\n }),\n },\n ],\n isError: false,\n };\n }\n\n // 1. Check if URL is already open\n // Prefer Chrome's URL match patterns for robust matching (host/path variations)\n console.log(`Checking if URL is already open: ${url}`);\n\n // Build robust match patterns from the provided URL.\n // This mirrors the approach in CloseTabsTool: ensure wildcard path and\n // add common variants (www/no-www, http/https) to handle real-world redirects.\n const buildUrlPatterns = (input: string): string[] => {\n const patterns = new Set();\n try {\n if (!input.includes('*')) {\n const u = new URL(input);\n // Use host-level wildcard to include all paths; we'll do precise selection later\n const pathWildcard = '/*';\n\n const hostNoWww = u.host.replace(/^www\\./, '');\n const hostWithWww = hostNoWww.startsWith('www.') ? hostNoWww : `www.${hostNoWww}`;\n\n // Keep original host\n patterns.add(`${u.protocol}//${u.host}${pathWildcard}`);\n // Add no-www variant\n patterns.add(`${u.protocol}//${hostNoWww}${pathWildcard}`);\n // Add www variant\n patterns.add(`${u.protocol}//${hostWithWww}${pathWildcard}`);\n\n // Add protocol variant to catch http↔https redirects\n const altProtocol = u.protocol === 'https:' ? 'http:' : 'https:';\n patterns.add(`${altProtocol}//${u.host}${pathWildcard}`);\n patterns.add(`${altProtocol}//${hostNoWww}${pathWildcard}`);\n patterns.add(`${altProtocol}//${hostWithWww}${pathWildcard}`);\n } else {\n patterns.add(input);\n }\n } catch {\n // Fallback: best-effort wildcard suffix\n patterns.add(input.endsWith('/') ? `${input}*` : `${input}/*`);\n }\n return Array.from(patterns);\n };\n\n const urlPatterns = buildUrlPatterns(url);\n const candidateTabs = await chrome.tabs.query({ url: urlPatterns });\n console.log(`Found ${candidateTabs.length} matching tabs with patterns:`, urlPatterns);\n\n // Prefer strict match when user specifies a concrete path/query.\n // Only fall back to host-level activation when the target is site root.\n const pickBestMatch = (target: string, tabsToPick: chrome.tabs.Tab[]) => {\n let targetUrl: URL | undefined;\n try {\n targetUrl = new URL(target);\n } catch {\n // Not a fully-qualified URL; cannot do structured comparison\n return tabsToPick[0];\n }\n\n const normalizePath = (p: string) => {\n if (!p) return '/';\n // Ensure leading slash\n const withLeading = p.startsWith('/') ? p : `/${p}`;\n // Remove trailing slash except when root\n return withLeading !== '/' && withLeading.endsWith('/')\n ? withLeading.slice(0, -1)\n : withLeading;\n };\n\n const hostBase = (h: string) => h.replace(/^www\\./, '').toLowerCase();\n const isRootTarget = normalizePath(targetUrl.pathname) === '/' && !targetUrl.search;\n const targetPath = normalizePath(targetUrl.pathname);\n const targetSearch = targetUrl.search || '';\n const targetHostBase = hostBase(targetUrl.host);\n\n let best: { tab?: chrome.tabs.Tab; score: number } = { score: -1 };\n\n for (const tab of tabsToPick) {\n const tabUrlStr = tab.url || '';\n let tabUrl: URL | undefined;\n try {\n tabUrl = new URL(tabUrlStr);\n } catch {\n continue;\n }\n\n const tabHostBase = hostBase(tabUrl.host);\n if (tabHostBase !== targetHostBase) continue;\n\n const tabPath = normalizePath(tabUrl.pathname);\n const tabSearch = tabUrl.search || '';\n\n // Scoring:\n // 3 - exact path match and (if target has query) exact query match\n // 2 - exact path match ignoring query (target without query)\n // 1 - same host, any path (only if target is root)\n let score = -1;\n const pathEqual = tabPath === targetPath;\n const searchEqual = tabSearch === targetSearch;\n\n if (pathEqual && (targetSearch ? searchEqual : true)) {\n score = 3;\n } else if (pathEqual && !targetSearch) {\n score = 2;\n }\n\n if (score > best.score) {\n best = { tab, score };\n if (score === 3) break; // Cannot do better\n }\n }\n\n return best.tab;\n };\n\n const explicitTab = await this.tryGetTab(tabId);\n const existingTab = explicitTab || pickBestMatch(url, candidateTabs);\n if (existingTab?.id !== undefined) {\n console.log(\n `URL already open in Tab ID: ${existingTab.id}, Window ID: ${existingTab.windowId}`,\n );\n // Update URL only when explicit tab specified and url differs\n if (explicitTab && typeof explicitTab.id === 'number') {\n await chrome.tabs.update(explicitTab.id, { url });\n }\n // Optionally bring to foreground based on background flag\n await this.ensureFocus(existingTab, {\n activate: background !== true,\n focusWindow: background !== true,\n });\n\n console.log(`Activated existing Tab ID: ${existingTab.id}`);\n // Get updated tab information and return it\n const updatedTab = await chrome.tabs.get(existingTab.id);\n\n // Trigger auto-capture on existing tab activation\n await this.triggerAutoCapture(updatedTab.id!, updatedTab.url);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'Activated existing tab',\n tabId: updatedTab.id,\n windowId: updatedTab.windowId,\n url: updatedTab.url,\n }),\n },\n ],\n isError: false,\n };\n }\n\n // 2. If URL is not already open, decide how to open it based on options\n const openInNewWindow = newWindow || typeof width === 'number' || typeof height === 'number';\n\n if (openInNewWindow) {\n console.log('Opening URL in a new window.');\n\n // Create new window\n const newWindow = await chrome.windows.create({\n url: url,\n width: typeof width === 'number' ? width : DEFAULT_WINDOW_WIDTH,\n height: typeof height === 'number' ? height : DEFAULT_WINDOW_HEIGHT,\n focused: background === true ? false : true,\n });\n\n if (newWindow && newWindow.id !== undefined) {\n console.log(`URL opened in new Window ID: ${newWindow.id}`);\n\n // Trigger auto-capture if the new window has a tab\n const firstTab = newWindow.tabs?.[0];\n if (firstTab?.id) {\n await this.triggerAutoCapture(firstTab.id, firstTab.url);\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'Opened URL in new window',\n windowId: newWindow.id,\n tabs: newWindow.tabs\n ? newWindow.tabs.map((tab) => ({\n tabId: tab.id,\n url: tab.url,\n }))\n : [],\n }),\n },\n ],\n isError: false,\n };\n }\n } else {\n console.log('Opening URL in the last active window.');\n // Try to open a new tab in the specified window, otherwise the most recently active window\n let targetWindow: chrome.windows.Window | null = null;\n if (typeof windowId === 'number') {\n targetWindow = await chrome.windows.get(windowId, { populate: false });\n }\n if (!targetWindow) {\n targetWindow = await chrome.windows.getLastFocused({ populate: false });\n }\n\n if (targetWindow && targetWindow.id !== undefined) {\n console.log(`Found target Window ID: ${targetWindow.id}`);\n\n const newTab = await chrome.tabs.create({\n url: url,\n windowId: targetWindow.id,\n active: background === true ? false : true,\n });\n if (background !== true) {\n await chrome.windows.update(targetWindow.id, { focused: true });\n }\n\n console.log(\n `URL opened in new Tab ID: ${newTab.id} in existing Window ID: ${targetWindow.id}`,\n );\n\n // Trigger auto-capture on new tab\n if (newTab.id) {\n await this.triggerAutoCapture(newTab.id, newTab.url);\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'Opened URL in new tab in existing window',\n tabId: newTab.id,\n windowId: targetWindow.id,\n url: newTab.url,\n }),\n },\n ],\n isError: false,\n };\n } else {\n // In rare cases, if there's no recently active window (e.g., browser just started with no windows)\n // Fall back to opening in a new window\n console.warn('No last focused window found, falling back to creating a new window.');\n\n const fallbackWindow = await chrome.windows.create({\n url: url,\n width: DEFAULT_WINDOW_WIDTH,\n height: DEFAULT_WINDOW_HEIGHT,\n focused: true,\n });\n\n if (fallbackWindow && fallbackWindow.id !== undefined) {\n console.log(`URL opened in fallback new Window ID: ${fallbackWindow.id}`);\n\n // Trigger auto-capture if fallback window has a tab\n const firstTab = fallbackWindow.tabs?.[0];\n if (firstTab?.id) {\n await this.triggerAutoCapture(firstTab.id, firstTab.url);\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'Opened URL in new window',\n windowId: fallbackWindow.id,\n tabs: fallbackWindow.tabs\n ? fallbackWindow.tabs.map((tab) => ({\n tabId: tab.id,\n url: tab.url,\n }))\n : [],\n }),\n },\n ],\n isError: false,\n };\n }\n }\n }\n\n // If all attempts fail, return a generic error\n return createErrorResponse('Failed to open URL: Unknown error occurred');\n } catch (error) {\n if (chrome.runtime.lastError) {\n console.error(`Chrome API Error: ${chrome.runtime.lastError.message}`, error);\n return createErrorResponse(`Chrome API Error: ${chrome.runtime.lastError.message}`);\n } else {\n console.error('Error in navigate:', error);\n return createErrorResponse(\n `Error navigating to URL: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n }\n}\nexport const navigateTool = new NavigateTool();\n\ninterface CloseTabsToolParams {\n tabIds?: number[];\n url?: string;\n}\n\n/**\n * Tool for closing browser tabs\n */\nclass CloseTabsTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.CLOSE_TABS;\n\n async execute(args: CloseTabsToolParams): Promise {\n const { tabIds, url } = args;\n let urlPattern = url;\n console.log(`Attempting to close tabs with options:`, args);\n\n try {\n // If URL is provided, close all tabs matching that URL\n if (urlPattern) {\n console.log(`Searching for tabs with URL: ${url}`);\n try {\n // Build a proper Chrome match pattern from a concrete URL.\n // If caller already provided a match pattern with '*', use as-is.\n if (!urlPattern.includes('*')) {\n // Ignore search/hash; match by origin + pathname prefix.\n // Use URL to normalize; fallback to simple suffixing when parsing fails.\n try {\n const u = new URL(urlPattern);\n const basePath = u.pathname || '/';\n const pathWithWildcard = basePath.endsWith('/') ? `${basePath}*` : `${basePath}/*`;\n urlPattern = `${u.protocol}//${u.host}${pathWithWildcard}`;\n } catch {\n // Not a fully-qualified URL; ensure it ends with wildcard\n urlPattern = urlPattern.endsWith('/') ? `${urlPattern}*` : `${urlPattern}/*`;\n }\n }\n } catch {\n // Best-effort: ensure we have some wildcard\n urlPattern = urlPattern.endsWith('*')\n ? urlPattern\n : urlPattern.endsWith('/')\n ? `${urlPattern}*`\n : `${urlPattern}/*`;\n }\n\n const tabs = await chrome.tabs.query({ url: urlPattern });\n\n if (!tabs || tabs.length === 0) {\n console.log(`No tabs found with URL pattern: ${urlPattern}`);\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: false,\n message: `No tabs found with URL pattern: ${urlPattern}`,\n closedCount: 0,\n }),\n },\n ],\n isError: false,\n };\n }\n\n console.log(`Found ${tabs.length} tabs with URL pattern: ${urlPattern}`);\n const tabIdsToClose = tabs\n .map((tab) => tab.id)\n .filter((id): id is number => id !== undefined);\n\n if (tabIdsToClose.length === 0) {\n return createErrorResponse('Found tabs but could not get their IDs');\n }\n\n await chrome.tabs.remove(tabIdsToClose);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: `Closed ${tabIdsToClose.length} tabs with URL: ${url}`,\n closedCount: tabIdsToClose.length,\n closedTabIds: tabIdsToClose,\n }),\n },\n ],\n isError: false,\n };\n }\n\n // If tabIds are provided, close those tabs\n if (tabIds && tabIds.length > 0) {\n console.log(`Closing tabs with IDs: ${tabIds.join(', ')}`);\n\n // Verify that all tabIds exist\n const existingTabs = await Promise.all(\n tabIds.map(async (tabId) => {\n try {\n return await chrome.tabs.get(tabId);\n } catch (error) {\n console.warn(`Tab with ID ${tabId} not found`);\n return null;\n }\n }),\n );\n\n const validTabIds = existingTabs\n .filter((tab): tab is chrome.tabs.Tab => tab !== null)\n .map((tab) => tab.id)\n .filter((id): id is number => id !== undefined);\n\n if (validTabIds.length === 0) {\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: false,\n message: 'None of the provided tab IDs exist',\n closedCount: 0,\n }),\n },\n ],\n isError: false,\n };\n }\n\n await chrome.tabs.remove(validTabIds);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: `Closed ${validTabIds.length} tabs`,\n closedCount: validTabIds.length,\n closedTabIds: validTabIds,\n invalidTabIds: tabIds.filter((id) => !validTabIds.includes(id)),\n }),\n },\n ],\n isError: false,\n };\n }\n\n // If no tabIds or URL provided, close the current active tab\n console.log('No tabIds or URL provided, closing active tab');\n const [activeTab] = await chrome.tabs.query({ active: true, currentWindow: true });\n\n if (!activeTab || !activeTab.id) {\n return createErrorResponse('No active tab found');\n }\n\n await chrome.tabs.remove(activeTab.id);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'Closed active tab',\n closedCount: 1,\n closedTabIds: [activeTab.id],\n }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in CloseTabsTool.execute:', error);\n return createErrorResponse(\n `Error closing tabs: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const closeTabsTool = new CloseTabsTool();\n\ninterface SwitchTabToolParams {\n tabId: number;\n windowId?: number;\n}\n\n/**\n * Tool for switching the active tab\n */\nclass SwitchTabTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.SWITCH_TAB;\n\n async execute(args: SwitchTabToolParams): Promise {\n const { tabId, windowId } = args;\n\n console.log(`Attempting to switch to tab ID: ${tabId} in window ID: ${windowId}`);\n\n try {\n if (windowId !== undefined) {\n await chrome.windows.update(windowId, { focused: true });\n }\n await chrome.tabs.update(tabId, { active: true });\n\n const updatedTab = await chrome.tabs.get(tabId);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: `Successfully switched to tab ID: ${tabId}`,\n tabId: updatedTab.id,\n windowId: updatedTab.windowId,\n url: updatedTab.url,\n }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n if (chrome.runtime.lastError) {\n console.error(`Chrome API Error: ${chrome.runtime.lastError.message}`, error);\n return createErrorResponse(`Chrome API Error: ${chrome.runtime.lastError.message}`);\n } else {\n console.error('Error in SwitchTabTool.execute:', error);\n return createErrorResponse(\n `Error switching tab: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n }\n}\n\nexport const switchTabTool = new SwitchTabTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/computer.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { ERROR_MESSAGES, TIMEOUTS } from '@/common/constants';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { clickTool, fillTool } from './interaction';\nimport { keyboardTool } from './keyboard';\nimport { screenshotTool } from './screenshot';\nimport { screenshotContextManager, scaleCoordinates } from '@/utils/screenshot-context';\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\nimport {\n captureFrameOnAction,\n isAutoCaptureActive,\n type ActionMetadata,\n type ActionType,\n} from './gif-recorder';\n\ntype MouseButton = 'left' | 'right' | 'middle';\n\ninterface Coordinates {\n x: number;\n y: number;\n}\n\ninterface ZoomRegion {\n x0: number;\n y0: number;\n x1: number;\n y1: number;\n}\n\ninterface Modifiers {\n altKey?: boolean;\n ctrlKey?: boolean;\n metaKey?: boolean;\n shiftKey?: boolean;\n}\n\ninterface ComputerParams {\n action:\n | 'left_click'\n | 'right_click'\n | 'double_click'\n | 'triple_click'\n | 'left_click_drag'\n | 'scroll'\n | 'type'\n | 'key'\n | 'hover'\n | 'wait'\n | 'fill'\n | 'fill_form'\n | 'resize_page'\n | 'scroll_to'\n | 'zoom'\n | 'screenshot';\n // click/scroll coordinates in screenshot space (if screenshot context exists) or viewport space\n coordinates?: Coordinates; // for click/scroll; for drag, this is endCoordinates\n startCoordinates?: Coordinates; // for drag start\n // Optional element refs (from chrome_read_page) as alternative to coordinates\n ref?: string; // click target or drag end\n startRef?: string; // drag start\n scrollDirection?: 'up' | 'down' | 'left' | 'right';\n scrollAmount?: number;\n text?: string; // for type/key\n repeat?: number; // for key action (1-100)\n modifiers?: Modifiers; // for click actions\n region?: ZoomRegion; // for zoom action\n duration?: number; // seconds for wait\n // For fill\n selector?: string;\n selectorType?: 'css' | 'xpath'; // Type of selector (default: 'css')\n value?: string;\n frameId?: number; // Target frame for selector/ref resolution\n tabId?: number; // target existing tab id\n windowId?: number;\n background?: boolean; // avoid focusing/activating\n}\n\n// Minimal CDP helper encapsulated here to avoid scattering CDP code\nclass CDPHelper {\n static async attach(tabId: number): Promise {\n await cdpSessionManager.attach(tabId, 'computer');\n }\n\n static async detach(tabId: number): Promise {\n await cdpSessionManager.detach(tabId, 'computer');\n }\n\n static async send(tabId: number, method: string, params?: object): Promise {\n return await cdpSessionManager.sendCommand(tabId, method, params);\n }\n\n static async dispatchMouseEvent(tabId: number, opts: any) {\n const params: any = {\n type: opts.type,\n x: Math.round(opts.x),\n y: Math.round(opts.y),\n modifiers: opts.modifiers || 0,\n };\n if (\n opts.type === 'mousePressed' ||\n opts.type === 'mouseReleased' ||\n opts.type === 'mouseMoved'\n ) {\n params.button = opts.button || 'none';\n if (opts.type === 'mousePressed' || opts.type === 'mouseReleased') {\n params.clickCount = opts.clickCount || 1;\n }\n // Per CDP: buttons is ignored for mouseWheel\n params.buttons = opts.buttons !== undefined ? opts.buttons : 0;\n }\n if (opts.type === 'mouseWheel') {\n params.deltaX = opts.deltaX || 0;\n params.deltaY = opts.deltaY || 0;\n }\n await this.send(tabId, 'Input.dispatchMouseEvent', params);\n }\n\n static async insertText(tabId: number, text: string) {\n await this.send(tabId, 'Input.insertText', { text });\n }\n\n static modifierMask(mods: string[]): number {\n const map: Record = {\n alt: 1,\n ctrl: 2,\n control: 2,\n meta: 4,\n cmd: 4,\n command: 4,\n win: 4,\n windows: 4,\n shift: 8,\n };\n let mask = 0;\n for (const m of mods) mask |= map[m] || 0;\n return mask;\n }\n\n // Enhanced key mapping for common non-character keys\n private static KEY_ALIASES: Record = {\n enter: { key: 'Enter', code: 'Enter' },\n return: { key: 'Enter', code: 'Enter' },\n backspace: { key: 'Backspace', code: 'Backspace' },\n delete: { key: 'Delete', code: 'Delete' },\n tab: { key: 'Tab', code: 'Tab' },\n escape: { key: 'Escape', code: 'Escape' },\n esc: { key: 'Escape', code: 'Escape' },\n space: { key: ' ', code: 'Space', text: ' ' },\n pageup: { key: 'PageUp', code: 'PageUp' },\n pagedown: { key: 'PageDown', code: 'PageDown' },\n home: { key: 'Home', code: 'Home' },\n end: { key: 'End', code: 'End' },\n arrowup: { key: 'ArrowUp', code: 'ArrowUp' },\n arrowdown: { key: 'ArrowDown', code: 'ArrowDown' },\n arrowleft: { key: 'ArrowLeft', code: 'ArrowLeft' },\n arrowright: { key: 'ArrowRight', code: 'ArrowRight' },\n };\n\n private static resolveKeyDef(token: string): { key: string; code?: string; text?: string } {\n const t = (token || '').toLowerCase();\n if (this.KEY_ALIASES[t]) return this.KEY_ALIASES[t];\n if (/^f([1-9]|1[0-2])$/.test(t)) {\n return { key: t.toUpperCase(), code: t.toUpperCase() };\n }\n if (t.length === 1) {\n const upper = t.toUpperCase();\n return { key: upper, code: `Key${upper}`, text: t };\n }\n return { key: token };\n }\n\n static async dispatchSimpleKey(tabId: number, token: string) {\n const def = this.resolveKeyDef(token);\n if (def.text && def.text.length === 1) {\n await this.insertText(tabId, def.text);\n return;\n }\n await this.send(tabId, 'Input.dispatchKeyEvent', {\n type: 'rawKeyDown',\n key: def.key,\n code: def.code,\n });\n await this.send(tabId, 'Input.dispatchKeyEvent', {\n type: 'keyUp',\n key: def.key,\n code: def.code,\n });\n }\n\n static async dispatchKeyChord(tabId: number, chord: string) {\n const parts = chord.split('+');\n const modifiers: string[] = [];\n let keyToken = '';\n for (const pRaw of parts) {\n const p = pRaw.trim().toLowerCase();\n if (\n ['ctrl', 'control', 'alt', 'shift', 'cmd', 'meta', 'command', 'win', 'windows'].includes(p)\n )\n modifiers.push(p);\n else keyToken = pRaw.trim();\n }\n const mask = this.modifierMask(modifiers);\n const def = this.resolveKeyDef(keyToken);\n await this.send(tabId, 'Input.dispatchKeyEvent', {\n type: 'rawKeyDown',\n key: def.key,\n code: def.code,\n text: def.text,\n modifiers: mask,\n });\n await this.send(tabId, 'Input.dispatchKeyEvent', {\n type: 'keyUp',\n key: def.key,\n code: def.code,\n modifiers: mask,\n });\n }\n}\n\nclass ComputerTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.COMPUTER;\n\n async execute(args: ComputerParams): Promise {\n const params = args || ({} as ComputerParams);\n if (!params.action) return createErrorResponse('Action parameter is required');\n\n try {\n const explicit = await this.tryGetTab(args.tabId);\n const tab = explicit || (await this.getActiveTabOrThrowInWindow(args.windowId));\n if (!tab.id)\n return createErrorResponse(ERROR_MESSAGES.TAB_NOT_FOUND + ': Active tab has no ID');\n\n // Execute the action and capture frame on success\n const result = await this.executeAction(params, tab);\n\n // Trigger auto-capture on successful actions (except screenshot which is read-only)\n if (!result.isError && params.action !== 'screenshot' && params.action !== 'wait') {\n const actionType = this.mapActionToCapture(params.action);\n if (actionType) {\n // Convert to viewport-space coordinates for GIF overlays\n // params.coordinates may be screenshot-space when screenshot context exists\n const ctx = screenshotContextManager.getContext(tab.id);\n const toViewport = (c?: Coordinates): { x: number; y: number } | undefined => {\n if (!c) return undefined;\n if (!ctx) return { x: c.x, y: c.y };\n const scaled = scaleCoordinates(c.x, c.y, ctx);\n return { x: scaled.x, y: scaled.y };\n };\n\n const endCoords = toViewport(params.coordinates);\n const startCoords = toViewport(params.startCoordinates);\n\n await this.triggerAutoCapture(tab.id, actionType, {\n coordinateSpace: 'viewport',\n coordinates: endCoords,\n startCoordinates: startCoords,\n endCoordinates: actionType === 'drag' ? endCoords : undefined,\n text: params.text,\n ref: params.ref,\n });\n }\n }\n\n return result;\n } catch (error) {\n console.error('Error in computer tool:', error);\n return createErrorResponse(\n `Failed to execute action: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n private mapActionToCapture(action: string): ActionType | null {\n const mapping: Record = {\n left_click: 'click',\n right_click: 'right_click',\n double_click: 'double_click',\n triple_click: 'triple_click',\n left_click_drag: 'drag',\n scroll: 'scroll',\n type: 'type',\n key: 'key',\n hover: 'hover',\n fill: 'fill',\n fill_form: 'fill',\n resize_page: 'other',\n scroll_to: 'scroll',\n zoom: 'other',\n };\n return mapping[action] || null;\n }\n\n private async executeAction(params: ComputerParams, tab: chrome.tabs.Tab): Promise {\n if (!tab.id) {\n return createErrorResponse(ERROR_MESSAGES.TAB_NOT_FOUND + ': Active tab has no ID');\n }\n\n // Helper to project coordinates using screenshot context when available\n const project = (c?: Coordinates): Coordinates | undefined => {\n if (!c) return undefined;\n const ctx = screenshotContextManager.getContext(tab.id!);\n if (!ctx) return c;\n const scaled = scaleCoordinates(c.x, c.y, ctx);\n return { x: scaled.x, y: scaled.y };\n };\n\n switch (params.action) {\n case 'resize_page': {\n const width = Number((params as any).coordinates?.x || (params as any).text);\n const height = Number((params as any).coordinates?.y || (params as any).value);\n const w = Number((params as any).width ?? width);\n const h = Number((params as any).height ?? height);\n if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0) {\n return createErrorResponse('Provide width and height for resize_page (positive numbers)');\n }\n try {\n // Prefer precise CDP emulation\n await CDPHelper.attach(tab.id);\n try {\n await CDPHelper.send(tab.id, 'Emulation.setDeviceMetricsOverride', {\n width: Math.round(w),\n height: Math.round(h),\n deviceScaleFactor: 0,\n mobile: false,\n screenWidth: Math.round(w),\n screenHeight: Math.round(h),\n });\n } finally {\n await CDPHelper.detach(tab.id);\n }\n } catch (e) {\n // Fallback: window resize\n if (tab.windowId !== undefined) {\n await chrome.windows.update(tab.windowId, {\n width: Math.round(w),\n height: Math.round(h),\n });\n } else {\n return createErrorResponse(\n `Failed to resize via CDP and cannot determine windowId: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n }\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({ success: true, action: 'resize_page', width: w, height: h }),\n },\n ],\n isError: false,\n };\n }\n case 'hover': {\n // Resolve target point from ref | selector | coordinates\n let coord: Coordinates | undefined = undefined;\n let resolvedBy: 'ref' | 'selector' | 'coordinates' | undefined;\n\n try {\n if (params.ref) {\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n // Scroll element into view first to ensure it's visible\n try {\n await this.sendMessageToTab(tab.id, { action: 'focusByRef', ref: params.ref });\n } catch {\n // Best effort - continue even if scroll fails\n }\n // Re-resolve coordinates after scroll\n const resolved = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.RESOLVE_REF,\n ref: params.ref,\n });\n if (resolved && resolved.success) {\n coord = project({ x: resolved.center.x, y: resolved.center.y });\n resolvedBy = 'ref';\n }\n } else if (params.selector) {\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n const selectorType = params.selectorType || 'css';\n const ensured = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR,\n selector: params.selector,\n isXPath: selectorType === 'xpath',\n });\n if (ensured && ensured.success) {\n // Scroll element into view first to ensure it's visible\n const resolvedRef = typeof ensured.ref === 'string' ? ensured.ref : undefined;\n if (resolvedRef) {\n try {\n await this.sendMessageToTab(tab.id, { action: 'focusByRef', ref: resolvedRef });\n } catch {\n // Best effort - continue even if scroll fails\n }\n // Re-resolve coordinates after scroll\n const reResolved = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.RESOLVE_REF,\n ref: resolvedRef,\n });\n if (reResolved && reResolved.success) {\n coord = project({ x: reResolved.center.x, y: reResolved.center.y });\n } else {\n coord = project({ x: ensured.center.x, y: ensured.center.y });\n }\n } else {\n coord = project({ x: ensured.center.x, y: ensured.center.y });\n }\n resolvedBy = 'selector';\n }\n } else if (params.coordinates) {\n coord = project(params.coordinates);\n resolvedBy = 'coordinates';\n }\n } catch (e) {\n // fall through to error handling below\n }\n\n if (!coord)\n return createErrorResponse(\n 'Provide ref or selector or coordinates for hover, or failed to resolve target',\n );\n {\n const stale = ((): any => {\n if (!params.coordinates) return null;\n const getHostname = (url: string): string => {\n try {\n return new URL(url).hostname;\n } catch {\n return '';\n }\n };\n const currentHostname = getHostname(tab.url || '');\n const ctx = screenshotContextManager.getContext(tab.id!);\n const contextHostname = (ctx as any)?.hostname as string | undefined;\n if (contextHostname && contextHostname !== currentHostname) {\n return createErrorResponse(\n `Security check failed: Domain changed since last screenshot (from ${contextHostname} to ${currentHostname}) during hover. Capture a new screenshot or use ref/selector.`,\n );\n }\n return null;\n })();\n if (stale) return stale;\n }\n\n try {\n await CDPHelper.attach(tab.id);\n try {\n // Move pointer to target. We can dispatch a single mouseMoved; browsers will generate mouseover/mouseenter as needed.\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mouseMoved',\n x: coord.x,\n y: coord.y,\n button: 'none',\n buttons: 0,\n });\n } finally {\n await CDPHelper.detach(tab.id);\n }\n\n // Optional hold to allow UI (menus/tooltips) to appear\n const holdMs = Math.max(\n 0,\n Math.min(params.duration ? params.duration * 1000 : 400, 5000),\n );\n if (holdMs > 0) await new Promise((r) => setTimeout(r, holdMs));\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: 'hover',\n coordinates: coord,\n resolvedBy,\n transport: 'cdp',\n }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.warn('[ComputerTool] CDP hover failed, attempting DOM fallback', error);\n return await this.domHoverFallback(tab.id, coord, resolvedBy, params.ref);\n }\n }\n case 'left_click':\n case 'right_click': {\n // Calculate CDP modifier mask for click events\n const modifiersMask = CDPHelper.modifierMask(\n [\n params.modifiers?.altKey ? 'alt' : undefined,\n params.modifiers?.ctrlKey ? 'ctrl' : undefined,\n params.modifiers?.metaKey ? 'meta' : undefined,\n params.modifiers?.shiftKey ? 'shift' : undefined,\n ].filter((v): v is string => typeof v === 'string'),\n );\n\n if (params.ref) {\n // Prefer DOM click via ref\n const domResult = await clickTool.execute({\n ref: params.ref,\n waitForNavigation: false,\n timeout: TIMEOUTS.DEFAULT_WAIT * 5,\n button: params.action === 'right_click' ? 'right' : 'left',\n modifiers: params.modifiers,\n });\n return domResult;\n }\n if (params.selector) {\n // Support selector-based click\n const domResult = await clickTool.execute({\n selector: params.selector,\n selectorType: params.selectorType,\n frameId: params.frameId,\n waitForNavigation: false,\n timeout: TIMEOUTS.DEFAULT_WAIT * 5,\n button: params.action === 'right_click' ? 'right' : 'left',\n modifiers: params.modifiers,\n });\n return domResult;\n }\n if (!params.coordinates)\n return createErrorResponse('Provide ref, selector, or coordinates for click action');\n {\n const stale = ((): any => {\n const getHostname = (url: string): string => {\n try {\n return new URL(url).hostname;\n } catch {\n return '';\n }\n };\n const currentHostname = getHostname(tab.url || '');\n const ctx = screenshotContextManager.getContext(tab.id!);\n const contextHostname = (ctx as any)?.hostname as string | undefined;\n if (contextHostname && contextHostname !== currentHostname) {\n return createErrorResponse(\n `Security check failed: Domain changed since last screenshot (from ${contextHostname} to ${currentHostname}) during ${params.action}. Capture a new screenshot or use ref/selector.`,\n );\n }\n return null;\n })();\n if (stale) return stale;\n }\n const coord = project(params.coordinates)!;\n // Prefer DOM path via existing click tool\n const domResult = await clickTool.execute({\n coordinates: coord,\n waitForNavigation: false,\n timeout: TIMEOUTS.DEFAULT_WAIT * 5,\n button: params.action === 'right_click' ? 'right' : 'left',\n modifiers: params.modifiers,\n });\n if (!domResult.isError) {\n return domResult; // Standardized response from click tool\n }\n // Fallback to CDP if DOM failed\n try {\n await CDPHelper.attach(tab.id);\n const button: MouseButton = params.action === 'right_click' ? 'right' : 'left';\n const clickCount = 1;\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mouseMoved',\n x: coord.x,\n y: coord.y,\n button: 'none',\n buttons: 0,\n modifiers: modifiersMask,\n });\n for (let i = 1; i <= clickCount; i++) {\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mousePressed',\n x: coord.x,\n y: coord.y,\n button,\n buttons: button === 'left' ? 1 : 2,\n clickCount: i,\n modifiers: modifiersMask,\n });\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mouseReleased',\n x: coord.x,\n y: coord.y,\n button,\n buttons: 0,\n clickCount: i,\n modifiers: modifiersMask,\n });\n }\n await CDPHelper.detach(tab.id);\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: params.action,\n coordinates: coord,\n }),\n },\n ],\n isError: false,\n };\n } catch (e) {\n await CDPHelper.detach(tab.id);\n return createErrorResponse(\n `CDP click failed: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n }\n case 'double_click':\n case 'triple_click': {\n // Calculate CDP modifier mask for click events\n const modifiersMask = CDPHelper.modifierMask(\n [\n params.modifiers?.altKey ? 'alt' : undefined,\n params.modifiers?.ctrlKey ? 'ctrl' : undefined,\n params.modifiers?.metaKey ? 'meta' : undefined,\n params.modifiers?.shiftKey ? 'shift' : undefined,\n ].filter((v): v is string => typeof v === 'string'),\n );\n\n if (!params.coordinates && !params.ref && !params.selector)\n return createErrorResponse(\n 'Provide ref, selector, or coordinates for double/triple click',\n );\n let coord = params.coordinates ? project(params.coordinates)! : (undefined as any);\n // If ref is provided, resolve center via accessibility helper\n if (params.ref) {\n try {\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n const resolved = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.RESOLVE_REF,\n ref: params.ref,\n });\n if (resolved && resolved.success) {\n coord = project({ x: resolved.center.x, y: resolved.center.y })!;\n }\n } catch (e) {\n // ignore and use provided coordinates\n }\n } else if (params.selector) {\n // Support selector-based click\n try {\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n const selectorType = params.selectorType || 'css';\n const ensured = await this.sendMessageToTab(\n tab.id,\n {\n action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR,\n selector: params.selector,\n isXPath: selectorType === 'xpath',\n },\n params.frameId,\n );\n if (ensured && ensured.success) {\n coord = project({ x: ensured.center.x, y: ensured.center.y })!;\n }\n } catch (e) {\n // ignore\n }\n }\n if (!coord) return createErrorResponse('Failed to resolve coordinates from ref/selector');\n {\n const stale = ((): any => {\n if (!params.coordinates) return null;\n const getHostname = (url: string): string => {\n try {\n return new URL(url).hostname;\n } catch {\n return '';\n }\n };\n const currentHostname = getHostname(tab.url || '');\n const ctx = screenshotContextManager.getContext(tab.id!);\n const contextHostname = (ctx as any)?.hostname as string | undefined;\n if (contextHostname && contextHostname !== currentHostname) {\n return createErrorResponse(\n `Security check failed: Domain changed since last screenshot (from ${contextHostname} to ${currentHostname}) during ${params.action}. Capture a new screenshot or use ref/selector.`,\n );\n }\n return null;\n })();\n if (stale) return stale;\n }\n try {\n await CDPHelper.attach(tab.id);\n const button: MouseButton = 'left';\n const clickCount = params.action === 'double_click' ? 2 : 3;\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mouseMoved',\n x: coord.x,\n y: coord.y,\n button: 'none',\n buttons: 0,\n modifiers: modifiersMask,\n });\n for (let i = 1; i <= clickCount; i++) {\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mousePressed',\n x: coord.x,\n y: coord.y,\n button,\n buttons: 1,\n clickCount: i,\n modifiers: modifiersMask,\n });\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mouseReleased',\n x: coord.x,\n y: coord.y,\n button,\n buttons: 0,\n clickCount: i,\n modifiers: modifiersMask,\n });\n }\n await CDPHelper.detach(tab.id);\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: params.action,\n coordinates: coord,\n }),\n },\n ],\n isError: false,\n };\n } catch (e) {\n await CDPHelper.detach(tab.id);\n return createErrorResponse(\n `CDP ${params.action} failed: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n }\n case 'left_click_drag': {\n if (!params.startCoordinates && !params.startRef)\n return createErrorResponse('Provide startRef or startCoordinates for drag');\n if (!params.coordinates && !params.ref)\n return createErrorResponse('Provide ref or end coordinates for drag');\n let start = params.startCoordinates\n ? project(params.startCoordinates)!\n : (undefined as any);\n let end = params.coordinates ? project(params.coordinates)! : (undefined as any);\n {\n const stale = ((): any => {\n if (!params.startCoordinates && !params.coordinates) return null;\n const getHostname = (url: string): string => {\n try {\n return new URL(url).hostname;\n } catch {\n return '';\n }\n };\n const currentHostname = getHostname(tab.url || '');\n const ctx = screenshotContextManager.getContext(tab.id!);\n const contextHostname = (ctx as any)?.hostname as string | undefined;\n if (contextHostname && contextHostname !== currentHostname) {\n return createErrorResponse(\n `Security check failed: Domain changed since last screenshot (from ${contextHostname} to ${currentHostname}) during left_click_drag. Capture a new screenshot or use ref/selector.`,\n );\n }\n return null;\n })();\n if (stale) return stale;\n }\n if (params.startRef || params.ref) {\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n }\n if (params.startRef) {\n try {\n const resolved = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.RESOLVE_REF,\n ref: params.startRef,\n });\n if (resolved && resolved.success)\n start = project({ x: resolved.center.x, y: resolved.center.y })!;\n } catch {\n // ignore\n }\n }\n if (params.ref) {\n try {\n const resolved = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.RESOLVE_REF,\n ref: params.ref,\n });\n if (resolved && resolved.success)\n end = project({ x: resolved.center.x, y: resolved.center.y })!;\n } catch {\n // ignore\n }\n }\n if (!start || !end) return createErrorResponse('Failed to resolve drag coordinates');\n try {\n await CDPHelper.attach(tab.id);\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mouseMoved',\n x: start.x,\n y: start.y,\n button: 'none',\n buttons: 0,\n });\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mousePressed',\n x: start.x,\n y: start.y,\n button: 'left',\n buttons: 1,\n clickCount: 1,\n });\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mouseMoved',\n x: end.x,\n y: end.y,\n button: 'left',\n buttons: 1,\n });\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mouseReleased',\n x: end.x,\n y: end.y,\n button: 'left',\n buttons: 0,\n clickCount: 1,\n });\n await CDPHelper.detach(tab.id);\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({ success: true, action: 'left_click_drag', start, end }),\n },\n ],\n isError: false,\n };\n } catch (e) {\n await CDPHelper.detach(tab.id);\n return createErrorResponse(`Drag failed: ${e instanceof Error ? e.message : String(e)}`);\n }\n }\n case 'scroll': {\n if (!params.coordinates && !params.ref)\n return createErrorResponse('Provide ref or coordinates for scroll');\n let coord = params.coordinates ? project(params.coordinates)! : (undefined as any);\n if (params.ref) {\n try {\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n const resolved = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.RESOLVE_REF,\n ref: params.ref,\n });\n if (resolved && resolved.success)\n coord = project({ x: resolved.center.x, y: resolved.center.y })!;\n } catch {\n // ignore\n }\n }\n if (!coord) return createErrorResponse('Failed to resolve scroll coordinates');\n {\n const stale = ((): any => {\n if (!params.coordinates) return null;\n const getHostname = (url: string): string => {\n try {\n return new URL(url).hostname;\n } catch {\n return '';\n }\n };\n const currentHostname = getHostname(tab.url || '');\n const ctx = screenshotContextManager.getContext(tab.id!);\n const contextHostname = (ctx as any)?.hostname as string | undefined;\n if (contextHostname && contextHostname !== currentHostname) {\n return createErrorResponse(\n `Security check failed: Domain changed since last screenshot (from ${contextHostname} to ${currentHostname}) during scroll. Capture a new screenshot or use ref/selector.`,\n );\n }\n return null;\n })();\n if (stale) return stale;\n }\n const direction = params.scrollDirection || 'down';\n const amount = Math.max(1, Math.min(params.scrollAmount || 3, 10));\n // Convert to deltas (~100px per tick)\n const unit = 100;\n let deltaX = 0,\n deltaY = 0;\n if (direction === 'up') deltaY = -amount * unit;\n if (direction === 'down') deltaY = amount * unit;\n if (direction === 'left') deltaX = -amount * unit;\n if (direction === 'right') deltaX = amount * unit;\n try {\n await CDPHelper.attach(tab.id);\n await CDPHelper.dispatchMouseEvent(tab.id, {\n type: 'mouseWheel',\n x: coord.x,\n y: coord.y,\n deltaX,\n deltaY,\n });\n await CDPHelper.detach(tab.id);\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: 'scroll',\n coordinates: coord,\n deltaX,\n deltaY,\n }),\n },\n ],\n isError: false,\n };\n } catch (e) {\n await CDPHelper.detach(tab.id);\n return createErrorResponse(\n `Scroll failed: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n }\n case 'type': {\n if (!params.text) return createErrorResponse('Text parameter is required for type action');\n try {\n // Optional focus via ref before typing\n if (params.ref) {\n await clickTool.execute({\n ref: params.ref,\n waitForNavigation: false,\n timeout: TIMEOUTS.DEFAULT_WAIT * 5,\n });\n }\n await CDPHelper.attach(tab.id);\n // Use CDP insertText to avoid complex KeyboardEvent emulation for long text\n await CDPHelper.insertText(tab.id, params.text);\n await CDPHelper.detach(tab.id);\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: 'type',\n length: params.text.length,\n }),\n },\n ],\n isError: false,\n };\n } catch (e) {\n await CDPHelper.detach(tab.id);\n // Fallback to DOM-based keyboard tool\n const res = await keyboardTool.execute({\n keys: params.text.split('').join(','),\n delay: 0,\n selector: undefined,\n });\n return res;\n }\n }\n case 'fill': {\n if (!params.ref && !params.selector) {\n return createErrorResponse('Provide ref or selector and a value for fill');\n }\n // Reuse existing fill tool to leverage robust DOM event behavior\n const res = await fillTool.execute({\n selector: params.selector as any,\n selectorType: params.selectorType as any,\n ref: params.ref as any,\n value: params.value as any,\n } as any);\n return res;\n }\n case 'fill_form': {\n const elements = (params as any).elements as Array<{\n ref: string;\n value: string | number | boolean;\n }>;\n if (!Array.isArray(elements) || elements.length === 0) {\n return createErrorResponse('elements must be a non-empty array for fill_form');\n }\n const results: Array<{ ref: string; ok: boolean; error?: string }> = [];\n for (const item of elements) {\n if (!item || !item.ref) {\n results.push({ ref: String(item?.ref || ''), ok: false, error: 'missing ref' });\n continue;\n }\n try {\n const r = await fillTool.execute({\n ref: item.ref as any,\n value: item.value as any,\n } as any);\n const ok = !r.isError;\n results.push({ ref: item.ref, ok, error: ok ? undefined : 'failed' });\n } catch (e) {\n results.push({\n ref: item.ref,\n ok: false,\n error: String(e instanceof Error ? e.message : e),\n });\n }\n }\n const successCount = results.filter((r) => r.ok).length;\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: 'fill_form',\n filled: successCount,\n total: results.length,\n results,\n }),\n },\n ],\n isError: false,\n };\n }\n case 'key': {\n if (!params.text)\n return createErrorResponse(\n 'text is required for key action (e.g., \"Backspace Backspace Enter\" or \"cmd+a\")',\n );\n const tokens = params.text.trim().split(/\\s+/).filter(Boolean);\n const repeat = params.repeat ?? 1;\n if (!Number.isInteger(repeat) || repeat < 1 || repeat > 100) {\n return createErrorResponse('repeat must be an integer between 1 and 100 for key action');\n }\n try {\n // Optional focus via ref before key events\n if (params.ref) {\n await clickTool.execute({\n ref: params.ref,\n waitForNavigation: false,\n timeout: TIMEOUTS.DEFAULT_WAIT * 5,\n });\n }\n await CDPHelper.attach(tab.id);\n for (let i = 0; i < repeat; i++) {\n for (const t of tokens) {\n if (t.includes('+')) await CDPHelper.dispatchKeyChord(tab.id, t);\n else await CDPHelper.dispatchSimpleKey(tab.id, t);\n }\n }\n await CDPHelper.detach(tab.id);\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({ success: true, action: 'key', keys: tokens, repeat }),\n },\n ],\n isError: false,\n };\n } catch (e) {\n await CDPHelper.detach(tab.id);\n // Fallback to DOM keyboard simulation (comma-separated combinations)\n const keysStr = tokens.join(',');\n const repeatedKeys =\n repeat === 1 ? keysStr : Array.from({ length: repeat }, () => keysStr).join(',');\n const res = await keyboardTool.execute({ keys: repeatedKeys });\n return res;\n }\n }\n case 'wait': {\n const hasTextCondition =\n typeof (params as any).text === 'string' && (params as any).text.trim().length > 0;\n if (hasTextCondition) {\n try {\n // Conditional wait for text appearance/disappearance using content script\n await this.injectContentScript(\n tab.id,\n ['inject-scripts/wait-helper.js'],\n false,\n 'ISOLATED',\n true,\n );\n const appear = (params as any).appear !== false; // default to true\n const timeoutMs = Math.max(\n 0,\n Math.min(((params as any).timeout as number) || 10000, 120000),\n );\n const resp = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.WAIT_FOR_TEXT,\n text: (params as any).text,\n appear,\n timeout: timeoutMs,\n });\n if (!resp || resp.success !== true) {\n return createErrorResponse(\n resp && resp.reason === 'timeout'\n ? `wait_for timed out after ${timeoutMs}ms for text: ${(params as any).text}`\n : `wait_for failed: ${resp && resp.error ? resp.error : 'unknown error'}`,\n );\n }\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: 'wait_for',\n appear,\n text: (params as any).text,\n matched: resp.matched || null,\n tookMs: resp.tookMs,\n }),\n },\n ],\n isError: false,\n };\n } catch (e) {\n return createErrorResponse(\n `wait_for failed: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n } else {\n const seconds = Math.max(0, Math.min((params as any).duration || 0, 30));\n if (!seconds)\n return createErrorResponse('Duration parameter is required and must be > 0');\n await new Promise((r) => setTimeout(r, seconds * 1000));\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({ success: true, action: 'wait', duration: seconds }),\n },\n ],\n isError: false,\n };\n }\n }\n case 'scroll_to': {\n if (!params.ref) {\n return createErrorResponse('ref is required for scroll_to action');\n }\n try {\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n const resp = await this.sendMessageToTab(tab.id, {\n action: 'focusByRef',\n ref: params.ref,\n });\n if (!resp || resp.success !== true) {\n return createErrorResponse(resp?.error || 'scroll_to failed: element not found');\n }\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: 'scroll_to',\n ref: params.ref,\n }),\n },\n ],\n isError: false,\n };\n } catch (e) {\n return createErrorResponse(\n `scroll_to failed: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n }\n case 'zoom': {\n const region = params.region;\n if (!region) {\n return createErrorResponse('region is required for zoom action');\n }\n const x0 = Number(region.x0);\n const y0 = Number(region.y0);\n const x1 = Number(region.x1);\n const y1 = Number(region.y1);\n if (![x0, y0, x1, y1].every(Number.isFinite)) {\n return createErrorResponse('region must contain finite numbers (x0, y0, x1, y1)');\n }\n if (x0 < 0 || y0 < 0 || x1 <= x0 || y1 <= y0) {\n return createErrorResponse('Invalid region: require x0>=0, y0>=0 and x1>x0, y1>y0');\n }\n\n // Project coordinates from screenshot space to viewport space\n const p0 = project({ x: x0, y: y0 })!;\n const p1 = project({ x: x1, y: y1 })!;\n const rx0 = Math.min(p0.x, p1.x);\n const ry0 = Math.min(p0.y, p1.y);\n const rx1 = Math.max(p0.x, p1.x);\n const ry1 = Math.max(p0.y, p1.y);\n const w = rx1 - rx0;\n const h = ry1 - ry0;\n if (w <= 0 || h <= 0) {\n return createErrorResponse('Invalid region after projection');\n }\n\n // Security check: verify domain hasn't changed since last screenshot\n {\n const getHostname = (url: string): string => {\n try {\n return new URL(url).hostname;\n } catch {\n return '';\n }\n };\n const ctx = screenshotContextManager.getContext(tab.id!);\n const contextHostname = (ctx as any)?.hostname as string | undefined;\n const currentHostname = getHostname(tab.url || '');\n if (contextHostname && contextHostname !== currentHostname) {\n return createErrorResponse(\n `Security check failed: Domain changed since last screenshot (from ${contextHostname} to ${currentHostname}) during zoom. Capture a new screenshot first.`,\n );\n }\n }\n\n try {\n await CDPHelper.attach(tab.id);\n const metrics: any = await CDPHelper.send(tab.id, 'Page.getLayoutMetrics', {});\n const viewport = metrics?.layoutViewport ||\n metrics?.visualViewport || {\n clientWidth: 800,\n clientHeight: 600,\n pageX: 0,\n pageY: 0,\n };\n const vw = Math.round(Number(viewport.clientWidth || 800));\n const vh = Math.round(Number(viewport.clientHeight || 600));\n if (rx1 > vw || ry1 > vh) {\n await CDPHelper.detach(tab.id);\n return createErrorResponse(\n `Region exceeds viewport boundaries (${vw}x${vh}). Choose a region within the visible viewport.`,\n );\n }\n const pageX = Number(viewport.pageX || 0);\n const pageY = Number(viewport.pageY || 0);\n\n const shot: any = await CDPHelper.send(tab.id, 'Page.captureScreenshot', {\n format: 'png',\n captureBeyondViewport: false,\n fromSurface: true,\n clip: {\n x: pageX + rx0,\n y: pageY + ry0,\n width: w,\n height: h,\n scale: 1,\n },\n });\n await CDPHelper.detach(tab.id);\n\n const base64Data = String(shot?.data || '');\n if (!base64Data) {\n return createErrorResponse('Failed to capture zoom screenshot via CDP');\n }\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: 'zoom',\n mimeType: 'image/png',\n base64Data,\n region: { x0: rx0, y0: ry0, x1: rx1, y1: ry1 },\n }),\n },\n ],\n isError: false,\n };\n } catch (e) {\n await CDPHelper.detach(tab.id);\n return createErrorResponse(`zoom failed: ${e instanceof Error ? e.message : String(e)}`);\n }\n }\n case 'screenshot': {\n // Reuse existing screenshot tool; it already supports base64 save option\n const result = await screenshotTool.execute({\n name: 'computer',\n storeBase64: true,\n fullPage: false,\n });\n return result;\n }\n default:\n return createErrorResponse(`Unsupported action: ${params.action}`);\n }\n }\n\n /**\n * DOM-based hover fallback when CDP is unavailable\n * Tries ref-based approach first (works with iframes), falls back to coordinates\n */\n private async domHoverFallback(\n tabId: number,\n coord?: Coordinates,\n resolvedBy?: 'ref' | 'selector' | 'coordinates',\n ref?: string,\n ): Promise {\n // Try ref-based approach first (handles iframes correctly)\n if (ref) {\n try {\n const resp = await this.sendMessageToTab(tabId, {\n action: TOOL_MESSAGE_TYPES.DISPATCH_HOVER_FOR_REF,\n ref,\n });\n if (resp?.success) {\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: 'hover',\n resolvedBy: 'ref',\n transport: 'dom-ref',\n target: resp.target,\n }),\n },\n ],\n isError: false,\n };\n }\n } catch (error) {\n console.warn('[ComputerTool] DOM ref hover failed, falling back to coordinates', error);\n }\n }\n\n // Fallback to coordinate-based approach\n if (!coord) {\n return createErrorResponse('Hover fallback requires coordinates or ref');\n }\n\n try {\n const [injection] = await chrome.scripting.executeScript({\n target: { tabId },\n world: 'MAIN',\n func: (point) => {\n const target = document.elementFromPoint(point.x, point.y);\n if (!target) {\n return { success: false, error: 'No element found at coordinates' };\n }\n\n // Dispatch hover-related events\n for (const type of ['mousemove', 'mouseover', 'mouseenter']) {\n target.dispatchEvent(\n new MouseEvent(type, {\n bubbles: true,\n cancelable: true,\n clientX: point.x,\n clientY: point.y,\n view: window,\n }),\n );\n }\n\n return {\n success: true,\n target: {\n tagName: target.tagName,\n id: target.id,\n className: target.className,\n text: target.textContent?.trim()?.slice(0, 100) || '',\n },\n };\n },\n args: [coord],\n });\n\n const payload = injection?.result;\n if (!payload?.success) {\n return createErrorResponse(payload?.error || 'DOM hover fallback failed');\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n action: 'hover',\n coordinates: coord,\n resolvedBy,\n transport: 'dom',\n target: payload.target,\n }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n return createErrorResponse(\n `DOM hover fallback failed: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n /**\n * Trigger GIF auto-capture after a successful action.\n * This is a no-op if auto-capture is not active.\n */\n private async triggerAutoCapture(\n tabId: number,\n actionType: ActionType,\n metadata?: Partial,\n ): Promise {\n if (!isAutoCaptureActive(tabId)) {\n return;\n }\n\n try {\n await captureFrameOnAction(tabId, {\n type: actionType,\n ...metadata,\n });\n } catch (error) {\n // Log but don't fail the main action\n console.warn('[ComputerTool] Auto-capture failed:', error);\n }\n }\n}\n\nexport const computerTool = new ComputerTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/console-buffer.ts", "content": "import { cdpSessionManager } from '@/utils/cdp-session-manager';\n\n/**\n * ConsoleBuffer - 持久化的控制台日志缓冲管理器\n *\n * 为每个 tab 维护一个滚动缓冲区，持续收集控制台事件。\n * 当 tab 导航到新域名时会自动清空缓冲，避免不同站点日志混淆。\n */\n\nconst DEFAULT_MAX_BUFFER_MESSAGES = 2000;\nconst DEFAULT_MAX_BUFFER_EXCEPTIONS = 500;\n\nexport interface BufferedConsoleMessage {\n timestamp: number;\n level: string;\n text: string;\n args?: unknown[];\n source?: string;\n url?: string;\n lineNumber?: number;\n stackTrace?: unknown;\n}\n\nexport interface BufferedConsoleException {\n timestamp: number;\n text: string;\n url?: string;\n lineNumber?: number;\n columnNumber?: number;\n stackTrace?: unknown;\n}\n\ninterface TabConsoleBufferState {\n tabId: number;\n tabUrl: string;\n tabTitle: string;\n hostname: string;\n captureStartTime: number;\n messages: BufferedConsoleMessage[];\n exceptions: BufferedConsoleException[];\n droppedMessageCount: number;\n droppedExceptionCount: number;\n}\n\nexport interface ConsoleBufferReadOptions {\n pattern?: RegExp;\n onlyErrors?: boolean;\n limit?: number;\n includeExceptions?: boolean;\n}\n\nexport interface ConsoleBufferReadResult {\n tabId: number;\n tabUrl: string;\n tabTitle: string;\n captureStartTime: number;\n captureEndTime: number;\n totalDurationMs: number;\n messages: BufferedConsoleMessage[];\n exceptions: BufferedConsoleException[];\n totalBufferedMessages: number;\n totalBufferedExceptions: number;\n messageCount: number;\n exceptionCount: number;\n messageLimitReached: boolean;\n droppedMessageCount: number;\n droppedExceptionCount: number;\n}\n\nfunction extractHostname(url?: string): string {\n if (!url) return '';\n try {\n return new URL(url).hostname;\n } catch {\n return '';\n }\n}\n\nfunction isErrorLevel(level?: string): boolean {\n const normalized = (level || '').toLowerCase();\n return normalized === 'error' || normalized === 'assert';\n}\n\nfunction matchesPattern(pattern: RegExp, text: string): boolean {\n pattern.lastIndex = 0;\n return pattern.test(text);\n}\n\nfunction formatConsoleArgs(args: unknown[]): string {\n if (!args || args.length === 0) return '';\n\n return args\n .map((arg: unknown) => {\n const a = arg as Record;\n if (a.type === 'string') return (a.value as string) || '';\n if (a.type === 'number') return String(a.value ?? '');\n if (a.type === 'boolean') return String(a.value ?? '');\n if (a.type === 'object') return (a.description as string) || '[Object]';\n if (a.type === 'undefined') return 'undefined';\n if (a.type === 'function') return (a.description as string) || '[Function]';\n return (a.description as string) || (a.value as string) || String(arg);\n })\n .join(' ');\n}\n\n/**\n * 从 CDP RemoteObject 提取安全的预览数据，丢弃 objectId 避免内存泄漏\n */\nfunction extractArgPreview(arg: unknown): unknown {\n const a = arg as Record;\n if (!a || typeof a !== 'object') return arg;\n\n // 只保留安全的字段，丢弃 objectId\n const preview: Record = {\n type: a.type,\n };\n\n if ('value' in a) preview.value = a.value;\n if ('unserializableValue' in a) preview.unserializableValue = a.unserializableValue;\n if ('description' in a) preview.description = a.description;\n if ('subtype' in a) preview.subtype = a.subtype;\n if ('className' in a) preview.className = a.className;\n\n return preview;\n}\n\nfunction safeTimestamp(value: unknown): number {\n if (typeof value === 'number' && Number.isFinite(value)) {\n return value;\n }\n return Date.now();\n}\n\nfunction safeString(value: unknown): string {\n return typeof value === 'string' ? value : '';\n}\n\nfunction safeNumber(value: unknown): number | undefined {\n return typeof value === 'number' ? value : undefined;\n}\n\nclass ConsoleBuffer {\n private buffers = new Map();\n private starting = new Map>();\n private static instance: ConsoleBuffer | null = null;\n\n constructor() {\n if (ConsoleBuffer.instance) {\n return ConsoleBuffer.instance;\n }\n ConsoleBuffer.instance = this;\n\n chrome.debugger.onEvent.addListener(this.handleDebuggerEvent.bind(this));\n chrome.debugger.onDetach.addListener(this.handleDebuggerDetach.bind(this));\n chrome.tabs.onRemoved.addListener(this.handleTabRemoved.bind(this));\n chrome.tabs.onUpdated.addListener(this.handleTabUpdated.bind(this));\n }\n\n /**\n * 检查指定 tab 是否正在进行 buffer 模式的捕获\n */\n isCapturing(tabId: number): boolean {\n return this.buffers.has(tabId);\n }\n\n /**\n * 确保指定 tab 的 buffer 捕获已启动\n */\n async ensureStarted(tabId: number): Promise {\n if (this.buffers.has(tabId)) return;\n\n const existing = this.starting.get(tabId);\n if (existing) return existing;\n\n const promise = this.startCapture(tabId).finally(() => {\n this.starting.delete(tabId);\n });\n this.starting.set(tabId, promise);\n return promise;\n }\n\n /**\n * 清空指定 tab 的缓冲区\n */\n clear(\n tabId: number,\n reason: string = 'manual',\n ): { clearedMessages: number; clearedExceptions: number } | null {\n const state = this.buffers.get(tabId);\n if (!state) return null;\n\n const clearedMessages = state.messages.length;\n const clearedExceptions = state.exceptions.length;\n\n state.messages.length = 0;\n state.exceptions.length = 0;\n state.droppedMessageCount = 0;\n state.droppedExceptionCount = 0;\n state.captureStartTime = Date.now();\n\n console.log(\n `ConsoleBuffer: Cleared buffer for tab ${tabId} (reason=${reason}). ` +\n `${clearedMessages} messages, ${clearedExceptions} exceptions.`,\n );\n\n return { clearedMessages, clearedExceptions };\n }\n\n /**\n * 读取指定 tab 的缓冲区内容\n */\n read(tabId: number, options: ConsoleBufferReadOptions = {}): ConsoleBufferReadResult | null {\n const state = this.buffers.get(tabId);\n if (!state) return null;\n\n const { pattern, onlyErrors = false, limit, includeExceptions = true } = options;\n\n const totalBufferedMessages = state.messages.length;\n const totalBufferedExceptions = state.exceptions.length;\n\n // 过滤消息\n let messages = state.messages;\n if (onlyErrors) {\n messages = messages.filter((m) => isErrorLevel(m.level));\n }\n if (pattern) {\n messages = messages.filter((m) => matchesPattern(pattern, m.text || ''));\n }\n\n // 按时间排序\n messages = [...messages].sort((a, b) => a.timestamp - b.timestamp);\n\n // 应用 limit\n let messageLimitReached = false;\n const normalizedLimit =\n typeof limit === 'number' && Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : null;\n if (normalizedLimit !== null && messages.length > normalizedLimit) {\n messageLimitReached = true;\n // 保留最新的消息\n messages = messages.slice(messages.length - normalizedLimit);\n }\n\n // 过滤异常\n let exceptions: BufferedConsoleException[] = [];\n if (includeExceptions) {\n exceptions = state.exceptions;\n if (pattern) {\n exceptions = exceptions.filter((e) => matchesPattern(pattern, e.text || ''));\n }\n exceptions = [...exceptions].sort((a, b) => a.timestamp - b.timestamp);\n }\n\n const now = Date.now();\n\n return {\n tabId,\n tabUrl: state.tabUrl,\n tabTitle: state.tabTitle,\n captureStartTime: state.captureStartTime,\n captureEndTime: now,\n totalDurationMs: now - state.captureStartTime,\n messages,\n exceptions,\n totalBufferedMessages,\n totalBufferedExceptions,\n messageCount: messages.length,\n exceptionCount: exceptions.length,\n messageLimitReached,\n droppedMessageCount: state.droppedMessageCount,\n droppedExceptionCount: state.droppedExceptionCount,\n };\n }\n\n private async startCapture(tabId: number): Promise {\n const tab = await chrome.tabs.get(tabId);\n const url = tab.url || '';\n const title = tab.title || '';\n const hostname = extractHostname(url);\n\n const state: TabConsoleBufferState = {\n tabId,\n tabUrl: url,\n tabTitle: title,\n hostname,\n captureStartTime: Date.now(),\n messages: [],\n exceptions: [],\n droppedMessageCount: 0,\n droppedExceptionCount: 0,\n };\n\n this.buffers.set(tabId, state);\n\n try {\n await cdpSessionManager.attach(tabId, 'console-buffer');\n await cdpSessionManager.sendCommand(tabId, 'Runtime.enable');\n await cdpSessionManager.sendCommand(tabId, 'Log.enable');\n } catch (error) {\n this.buffers.delete(tabId);\n await cdpSessionManager.detach(tabId, 'console-buffer').catch(() => {});\n throw error;\n }\n }\n\n private handleTabRemoved(tabId: number): void {\n if (!this.buffers.has(tabId)) return;\n void this.stopCapture(tabId, 'tab_closed');\n }\n\n private handleTabUpdated(\n tabId: number,\n changeInfo: chrome.tabs.TabChangeInfo,\n tab: chrome.tabs.Tab,\n ): void {\n const state = this.buffers.get(tabId);\n if (!state) return;\n\n const nextUrl = changeInfo.url ?? tab.url;\n const nextTitle = tab.title;\n\n if (typeof nextUrl === 'string') {\n const nextHost = extractHostname(nextUrl);\n // 域名变化时清空缓冲\n if (nextHost !== state.hostname) {\n this.clear(tabId, 'domain_changed');\n state.hostname = nextHost;\n }\n state.tabUrl = nextUrl;\n }\n\n if (typeof nextTitle === 'string') {\n state.tabTitle = nextTitle;\n }\n }\n\n private handleDebuggerDetach(source: chrome.debugger.Debuggee, reason: string): void {\n if (typeof source.tabId !== 'number') return;\n if (!this.buffers.has(source.tabId)) return;\n\n console.log(\n `ConsoleBuffer: Debugger detached from tab ${source.tabId} (reason=${reason}), cleaning up.`,\n );\n\n this.buffers.delete(source.tabId);\n this.starting.delete(source.tabId);\n cdpSessionManager.detach(source.tabId, 'console-buffer').catch(() => {});\n }\n\n private handleDebuggerEvent(\n source: chrome.debugger.Debuggee,\n method: string,\n params?: unknown,\n ): void {\n const tabId = source.tabId;\n if (typeof tabId !== 'number') return;\n\n const state = this.buffers.get(tabId);\n if (!state) return;\n\n const p = params as Record;\n\n if (method === 'Log.entryAdded' && p?.entry) {\n const entry = p.entry as Record;\n state.messages.push({\n timestamp: safeTimestamp(entry.timestamp),\n level: safeString(entry.level) || 'log',\n text: safeString(entry.text),\n source: safeString(entry.source),\n url: safeString(entry.url),\n lineNumber: safeNumber(entry.lineNumber),\n stackTrace: entry.stackTrace,\n });\n this.trimMessages(state);\n return;\n }\n\n if (method === 'Runtime.consoleAPICalled' && p) {\n const stackTrace = p.stackTrace as Record | undefined;\n const callFrame = stackTrace?.callFrames?.[0] as Record | undefined;\n const rawArgs = (p.args as unknown[]) || [];\n\n state.messages.push({\n timestamp: safeTimestamp(p.timestamp),\n level: safeString(p.type) || 'log',\n text: formatConsoleArgs(rawArgs),\n source: 'console-api',\n url: safeString(callFrame?.url),\n lineNumber: safeNumber(callFrame?.lineNumber),\n stackTrace: stackTrace,\n // 只存储安全的预览数据，避免内存泄漏\n args: rawArgs.map(extractArgPreview),\n });\n this.trimMessages(state);\n return;\n }\n\n if (method === 'Runtime.exceptionThrown' && p?.exceptionDetails) {\n const exceptionDetails = p.exceptionDetails as Record;\n const exception = exceptionDetails.exception as Record | undefined;\n state.exceptions.push({\n timestamp: Date.now(),\n text:\n safeString(exceptionDetails.text) ||\n safeString(exception?.description) ||\n 'Unknown exception',\n url: safeString(exceptionDetails.url),\n lineNumber: safeNumber(exceptionDetails.lineNumber),\n columnNumber: safeNumber(exceptionDetails.columnNumber),\n stackTrace: exceptionDetails.stackTrace,\n });\n this.trimExceptions(state);\n }\n }\n\n private trimMessages(state: TabConsoleBufferState): void {\n const overflow = state.messages.length - DEFAULT_MAX_BUFFER_MESSAGES;\n if (overflow <= 0) return;\n state.messages.splice(0, overflow);\n state.droppedMessageCount += overflow;\n }\n\n private trimExceptions(state: TabConsoleBufferState): void {\n const overflow = state.exceptions.length - DEFAULT_MAX_BUFFER_EXCEPTIONS;\n if (overflow <= 0) return;\n state.exceptions.splice(0, overflow);\n state.droppedExceptionCount += overflow;\n }\n\n private async stopCapture(tabId: number, reason: string): Promise {\n if (!this.buffers.has(tabId)) return;\n\n this.buffers.delete(tabId);\n this.starting.delete(tabId);\n\n try {\n await cdpSessionManager.sendCommand(tabId, 'Runtime.disable');\n } catch {\n // best effort\n }\n try {\n await cdpSessionManager.sendCommand(tabId, 'Log.disable');\n } catch {\n // best effort\n }\n await cdpSessionManager.detach(tabId, 'console-buffer').catch(() => {});\n console.log(`ConsoleBuffer: Stopped buffer for tab ${tabId} (reason=${reason}).`);\n }\n}\n\nexport const consoleBuffer = new ConsoleBuffer();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/console.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\nimport { consoleBuffer, BufferedConsoleMessage, BufferedConsoleException } from './console-buffer';\n\nconst DEFAULT_MAX_MESSAGES = 100;\n\ntype ConsoleMode = 'snapshot' | 'buffer';\n\ninterface ConsoleToolParams {\n url?: string;\n tabId?: number;\n background?: boolean;\n windowId?: number;\n includeExceptions?: boolean;\n maxMessages?: number;\n // 新增参数\n mode?: ConsoleMode;\n buffer?: boolean; // mode=\"buffer\" 的别名\n clear?: boolean; // 读取前清空\n clearAfterRead?: boolean; // 读取后清空（mcp-tools.js 风格）\n pattern?: string;\n onlyErrors?: boolean;\n limit?: number;\n}\n\ninterface ConsoleMessage {\n timestamp: number;\n level: string;\n text: string;\n args?: any[];\n argsSerialized?: any[];\n source?: string;\n url?: string;\n lineNumber?: number;\n stackTrace?: any;\n}\n\ninterface ConsoleException {\n timestamp: number;\n text: string;\n url?: string;\n lineNumber?: number;\n columnNumber?: number;\n stackTrace?: any;\n}\n\ninterface ConsoleResult {\n success: boolean;\n message: string;\n tabId: number;\n tabUrl: string;\n tabTitle: string;\n captureStartTime: number;\n captureEndTime: number;\n totalDurationMs: number;\n messages: ConsoleMessage[];\n exceptions: ConsoleException[];\n messageCount: number;\n exceptionCount: number;\n messageLimitReached: boolean;\n droppedMessageCount: number;\n droppedExceptionCount: number;\n}\n\n// 辅助函数\n\nfunction normalizeLimit(value: unknown, fallback: number): number {\n const n = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : fallback;\n return Math.max(0, n);\n}\n\nfunction parseRegexPattern(pattern?: string): RegExp | undefined {\n if (typeof pattern !== 'string') return undefined;\n const trimmed = pattern.trim();\n if (!trimmed) return undefined;\n // 支持 /pattern/flags 语法\n const match = trimmed.match(/^\\/(.+)\\/([gimsuy]*)$/);\n try {\n return match ? new RegExp(match[1], match[2]) : new RegExp(trimmed);\n } catch (e: unknown) {\n const msg = e instanceof Error ? e.message : String(e);\n throw new Error(`Invalid regex pattern: ${msg}`);\n }\n}\n\nfunction matchesPattern(pattern: RegExp, text: string): boolean {\n pattern.lastIndex = 0;\n return pattern.test(text);\n}\n\nfunction isErrorLevel(level?: string): boolean {\n const normalized = (level || '').toLowerCase();\n return normalized === 'error' || normalized === 'assert';\n}\n\nfunction applyResultFilters(\n result: ConsoleResult,\n options: { pattern?: RegExp; onlyErrors?: boolean; includeExceptions: boolean },\n): ConsoleResult {\n const { pattern, onlyErrors = false, includeExceptions } = options;\n\n let messages = result.messages;\n if (onlyErrors) {\n messages = messages.filter((m) => isErrorLevel(m.level));\n }\n if (pattern) {\n messages = messages.filter((m) => matchesPattern(pattern, m.text || ''));\n }\n\n let exceptions = includeExceptions ? result.exceptions : [];\n if (includeExceptions && pattern) {\n exceptions = exceptions.filter((e) => matchesPattern(pattern, e.text || ''));\n }\n\n return {\n ...result,\n messages,\n exceptions,\n messageCount: messages.length,\n exceptionCount: exceptions.length,\n };\n}\n\nfunction isDebuggerConflictError(error: unknown): boolean {\n const msg = (error instanceof Error ? error.message : String(error)).toLowerCase();\n return msg.includes('debugger is already attached') || msg.includes('another client');\n}\n\nfunction formatDebuggerConflictMessage(tabId: number, originalMessage: string): string {\n return (\n `Failed to attach Chrome Debugger to tab ${tabId}: another debugger client is already attached ` +\n `(likely DevTools or another extension). Close DevTools for this tab or disable the conflicting extension, ` +\n `then retry. Original error: ${originalMessage}`\n );\n}\n\n/**\n * Tool for capturing console output from browser tabs\n */\nclass ConsoleTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.CONSOLE;\n\n async execute(args: ConsoleToolParams): Promise {\n const {\n url,\n tabId,\n windowId,\n background = false,\n includeExceptions = true,\n maxMessages = DEFAULT_MAX_MESSAGES,\n mode = 'snapshot',\n buffer,\n clear = false,\n clearAfterRead = false,\n pattern,\n onlyErrors = false,\n limit,\n } = args;\n\n let targetTab: chrome.tabs.Tab;\n let targetTabId: number | undefined;\n\n // 解析正则表达式\n let compiledPattern: RegExp | undefined;\n try {\n compiledPattern = parseRegexPattern(pattern);\n } catch (e: unknown) {\n const msg = e instanceof Error ? e.message : String(e);\n return createErrorResponse(msg);\n }\n\n try {\n if (typeof tabId === 'number') {\n // Use explicit tab\n const t = await chrome.tabs.get(tabId);\n if (!t?.id) return createErrorResponse('Failed to identify target tab.');\n targetTab = t;\n } else if (url) {\n // Navigate to the specified URL\n targetTab = await this.navigateToUrl(url, background === true, windowId);\n } else {\n // Use current active tab\n const [activeTab] =\n typeof windowId === 'number'\n ? await chrome.tabs.query({ active: true, windowId })\n : await chrome.tabs.query({ active: true, currentWindow: true });\n if (!activeTab?.id) {\n return createErrorResponse('No active tab found and no URL provided.');\n }\n targetTab = activeTab;\n }\n\n if (!targetTab?.id) {\n return createErrorResponse('Failed to identify target tab.');\n }\n\n targetTabId = targetTab.id;\n\n // 确定模式：buffer 参数是 mode=\"buffer\" 的别名\n const resolvedMode: ConsoleMode =\n mode === 'buffer' || buffer === true ? 'buffer' : 'snapshot';\n\n // 计算有效的消息限制\n const normalizedMaxMessages = normalizeLimit(maxMessages, DEFAULT_MAX_MESSAGES);\n const effectiveLimit =\n typeof limit === 'number'\n ? normalizeLimit(limit, normalizedMaxMessages)\n : normalizedMaxMessages;\n\n // Buffer 模式\n if (resolvedMode === 'buffer') {\n try {\n await consoleBuffer.ensureStarted(targetTabId);\n } catch (error: unknown) {\n const msg = error instanceof Error ? error.message : String(error);\n if (isDebuggerConflictError(error)) {\n return createErrorResponse(formatDebuggerConflictMessage(targetTabId, msg));\n }\n throw error;\n }\n\n // 处理读取前清空请求\n let clearedBefore: { clearedMessages: number; clearedExceptions: number } | null = null;\n if (clear === true) {\n clearedBefore = consoleBuffer.clear(targetTabId, 'manual');\n }\n\n // 读取缓冲区\n const read = consoleBuffer.read(targetTabId, {\n pattern: compiledPattern,\n onlyErrors,\n limit: effectiveLimit,\n includeExceptions,\n });\n\n if (!read) {\n return createErrorResponse('Console buffer is not available for this tab.');\n }\n\n // 处理读取后清空请求（mcp-tools.js 风格，避免重复读取）\n let clearedAfter: { clearedMessages: number; clearedExceptions: number } | null = null;\n if (clearAfterRead === true) {\n clearedAfter = consoleBuffer.clear(targetTabId, 'manual');\n }\n\n // 构建清空摘要\n let clearedSummary = '';\n if (clearedBefore) {\n clearedSummary += ` Cleared ${clearedBefore.clearedMessages} messages and ${clearedBefore.clearedExceptions} exceptions before reading.`;\n }\n if (clearedAfter) {\n clearedSummary += ` Cleared ${clearedAfter.clearedMessages} messages and ${clearedAfter.clearedExceptions} exceptions after reading.`;\n }\n\n const result: ConsoleResult = {\n success: true,\n message:\n `Console buffer read for tab ${targetTabId}.` +\n clearedSummary +\n ` Returned ${read.messageCount} messages and ${read.exceptionCount} exceptions.`,\n tabId: targetTabId,\n tabUrl: read.tabUrl || '',\n tabTitle: read.tabTitle || '',\n captureStartTime: read.captureStartTime,\n captureEndTime: read.captureEndTime,\n totalDurationMs: read.totalDurationMs,\n messages: read.messages as ConsoleMessage[],\n exceptions: read.exceptions as ConsoleException[],\n messageCount: read.messageCount,\n exceptionCount: read.exceptionCount,\n messageLimitReached: read.messageLimitReached,\n droppedMessageCount: read.droppedMessageCount,\n droppedExceptionCount: read.droppedExceptionCount,\n };\n\n return {\n content: [{ type: 'text', text: JSON.stringify(result) }],\n isError: false,\n };\n }\n\n // Snapshot 模式（一次性捕获）\n const result = await this.captureConsoleMessages(targetTabId, {\n includeExceptions,\n maxMessages: effectiveLimit,\n });\n\n // 应用过滤器\n const filtered = applyResultFilters(result, {\n pattern: compiledPattern,\n onlyErrors,\n includeExceptions,\n });\n\n return {\n content: [{ type: 'text', text: JSON.stringify(filtered) }],\n isError: false,\n };\n } catch (error: unknown) {\n console.error('ConsoleTool: Critical error during execute:', error);\n const msg = error instanceof Error ? error.message : String(error);\n if (typeof targetTabId === 'number' && isDebuggerConflictError(error)) {\n return createErrorResponse(formatDebuggerConflictMessage(targetTabId, msg));\n }\n return createErrorResponse(`Error in ConsoleTool: ${msg}`);\n }\n }\n\n private async navigateToUrl(\n url: string,\n background = false,\n windowId?: number,\n ): Promise {\n // Check if URL is already open\n const existingTabs = await chrome.tabs.query({ url });\n\n if (existingTabs.length > 0 && existingTabs[0]?.id) {\n const tab = existingTabs[0];\n if (!background) {\n // Activate the existing tab\n await chrome.tabs.update(tab.id!, { active: true });\n await chrome.windows.update(tab.windowId, { focused: true });\n }\n return tab;\n } else {\n // Create new tab with the URL\n const createInfo: chrome.tabs.CreateProperties = { url, active: background ? false : true };\n if (typeof windowId === 'number') createInfo.windowId = windowId;\n const newTab = await chrome.tabs.create(createInfo);\n // Wait for tab to be ready\n await this.waitForTabReady(newTab.id!);\n return newTab;\n }\n }\n\n private async waitForTabReady(tabId: number): Promise {\n return new Promise((resolve) => {\n const checkTab = async () => {\n try {\n const tab = await chrome.tabs.get(tabId);\n if (tab.status === 'complete') {\n resolve();\n } else {\n setTimeout(checkTab, 100);\n }\n } catch (error) {\n // Tab might be closed, resolve anyway\n resolve();\n }\n };\n checkTab();\n });\n }\n\n private formatConsoleArgs(args: any[]): string {\n if (!args || args.length === 0) return '';\n\n return args\n .map((arg) => {\n if (arg.type === 'string') {\n return arg.value || '';\n } else if (arg.type === 'number') {\n return String(arg.value || '');\n } else if (arg.type === 'boolean') {\n return String(arg.value || '');\n } else if (arg.type === 'object') {\n return arg.description || '[Object]';\n } else if (arg.type === 'undefined') {\n return 'undefined';\n } else if (arg.type === 'function') {\n return arg.description || '[Function]';\n } else {\n return arg.description || arg.value || String(arg);\n }\n })\n .join(' ');\n }\n\n private async captureConsoleMessages(\n tabId: number,\n options: {\n includeExceptions: boolean;\n maxMessages: number;\n },\n ): Promise {\n const { includeExceptions, maxMessages } = options;\n const startTime = Date.now();\n const messages: ConsoleMessage[] = [];\n const exceptions: ConsoleException[] = [];\n let limitReached = false;\n\n try {\n // Get tab information\n const tab = await chrome.tabs.get(tabId);\n\n // Attach via shared manager\n await cdpSessionManager.attach(tabId, 'console');\n\n // Set up event listener to collect messages\n const collectedMessages: any[] = [];\n const collectedExceptions: any[] = [];\n\n const eventListener = (source: chrome.debugger.Debuggee, method: string, params?: any) => {\n if (source.tabId !== tabId) return;\n\n if (method === 'Log.entryAdded' && params?.entry) {\n collectedMessages.push(params.entry);\n } else if (method === 'Runtime.consoleAPICalled' && params) {\n // Convert Runtime.consoleAPICalled to Log.entryAdded format\n const logEntry = {\n timestamp: params.timestamp,\n level: params.type || 'log',\n text: this.formatConsoleArgs(params.args || []),\n source: 'console-api',\n url: params.stackTrace?.callFrames?.[0]?.url,\n lineNumber: params.stackTrace?.callFrames?.[0]?.lineNumber,\n stackTrace: params.stackTrace,\n args: params.args,\n };\n collectedMessages.push(logEntry);\n } else if (\n method === 'Runtime.exceptionThrown' &&\n includeExceptions &&\n params?.exceptionDetails\n ) {\n collectedExceptions.push(params.exceptionDetails);\n }\n };\n\n chrome.debugger.onEvent.addListener(eventListener);\n\n try {\n // Enable Runtime domain first to capture console API calls and exceptions\n await cdpSessionManager.sendCommand(tabId, 'Runtime.enable');\n\n // Also enable Log domain to capture other log entries\n await cdpSessionManager.sendCommand(tabId, 'Log.enable');\n\n // Wait for all messages to be flushed\n await new Promise((resolve) => setTimeout(resolve, 2000));\n\n // Process collected messages\n // Helper to deeply serialize console arguments when possible\n const serializeArg = async (arg: any): Promise => {\n try {\n if (!arg) return arg;\n if (Object.prototype.hasOwnProperty.call(arg, 'unserializableValue')) {\n return arg.unserializableValue;\n }\n if (Object.prototype.hasOwnProperty.call(arg, 'value')) {\n return arg.value;\n }\n if (arg.objectId) {\n const resp = await cdpSessionManager.sendCommand(tabId, 'Runtime.callFunctionOn', {\n objectId: arg.objectId,\n functionDeclaration:\n 'function(maxDepth, maxProps){\\n' +\n ' const seen=new WeakSet();\\n' +\n ' function S(v,d){\\n' +\n ' try{\\n' +\n ' if(d<0) return \"[MaxDepth]\";\\n' +\n ' if(v===null) return null;\\n' +\n ' const t=typeof v;\\n' +\n ' if(t!==\"object\"){\\n' +\n ' if(t===\"bigint\") return v.toString()+\"n\";\\n' +\n ' return v;\\n' +\n ' }\\n' +\n ' if(seen.has(v)) return \"[Circular]\";\\n' +\n ' seen.add(v);\\n' +\n ' if(Array.isArray(v)){\\n' +\n ' const out=[];\\n' +\n ' for(let i=0;i=maxProps){ out.push(\"[...truncated]\"); break; }\\n' +\n ' out.push(S(v[i], d-1));\\n' +\n ' }\\n' +\n ' return out;\\n' +\n ' }\\n' +\n ' if(v instanceof Date) return {__type:\"Date\", value:v.toISOString()};\\n' +\n ' if(v instanceof RegExp) return {__type:\"RegExp\", value:String(v)};\\n' +\n ' if(v instanceof Map){\\n' +\n ' const out={__type:\"Map\", entries:[]}; let c=0;\\n' +\n ' for(const [k,val] of v.entries()){\\n' +\n ' if(c++>=maxProps){ out.entries.push([\"[...truncated]\",\"[...truncated]\"]); break; }\\n' +\n ' out.entries.push([S(k,d-1), S(val,d-1)]);\\n' +\n ' }\\n' +\n ' return out;\\n' +\n ' }\\n' +\n ' if(v instanceof Set){\\n' +\n ' const out={__type:\"Set\", values:[]}; let c=0;\\n' +\n ' for(const val of v.values()){\\n' +\n ' if(c++>=maxProps){ out.values.push(\"[...truncated]\"); break; }\\n' +\n ' out.values.push(S(val,d-1));\\n' +\n ' }\\n' +\n ' return out;\\n' +\n ' }\\n' +\n ' const out={}; let c=0;\\n' +\n ' for(const key in v){\\n' +\n ' if(c++>=maxProps){ out.__truncated__=true; break; }\\n' +\n ' try{ out[key]=S(v[key], d-1); }catch(e){ out[key]=\"[Thrown]\"; }\\n' +\n ' }\\n' +\n ' return out;\\n' +\n ' }catch(e){ return \"[Unserializable]\" }\\n' +\n ' }\\n' +\n ' return S(this, maxDepth);\\n' +\n '}',\n arguments: [{ value: 3 }, { value: 100 }],\n silent: true,\n returnByValue: true,\n });\n return resp?.result?.value ?? '[Unavailable]';\n }\n return '[Unknown]';\n } catch (e) {\n return '[SerializeError]';\n }\n };\n\n for (const entry of collectedMessages) {\n if (messages.length >= maxMessages) {\n limitReached = true;\n break;\n }\n\n const message: ConsoleMessage = {\n timestamp: entry.timestamp,\n level: entry.level || 'log',\n text: entry.text || '',\n source: entry.source,\n url: entry.url,\n lineNumber: entry.lineNumber,\n };\n\n if (entry.stackTrace) {\n message.stackTrace = entry.stackTrace;\n }\n\n if (entry.args && Array.isArray(entry.args)) {\n message.args = entry.args;\n // Attempt deep serialization for better fidelity\n const serialized: any[] = [];\n for (const a of entry.args) {\n serialized.push(await serializeArg(a));\n }\n message.argsSerialized = serialized;\n }\n\n messages.push(message);\n }\n\n // Process collected exceptions\n for (const exceptionDetails of collectedExceptions) {\n const exception: ConsoleException = {\n timestamp: Date.now(),\n text:\n exceptionDetails.text ||\n exceptionDetails.exception?.description ||\n 'Unknown exception',\n url: exceptionDetails.url,\n lineNumber: exceptionDetails.lineNumber,\n columnNumber: exceptionDetails.columnNumber,\n };\n\n if (exceptionDetails.stackTrace) {\n exception.stackTrace = exceptionDetails.stackTrace;\n }\n\n exceptions.push(exception);\n }\n } finally {\n // Clean up\n chrome.debugger.onEvent.removeListener(eventListener);\n\n // 如果 buffer 模式正在使用这个 tab，不要关闭 Runtime/Log 域\n const keepDomainsEnabled = consoleBuffer.isCapturing(tabId);\n if (!keepDomainsEnabled) {\n try {\n await cdpSessionManager.sendCommand(tabId, 'Runtime.disable');\n } catch (e) {\n console.warn(`ConsoleTool: Error disabling Runtime for tab ${tabId}:`, e);\n }\n\n try {\n await cdpSessionManager.sendCommand(tabId, 'Log.disable');\n } catch (e) {\n console.warn(`ConsoleTool: Error disabling Log for tab ${tabId}:`, e);\n }\n }\n\n try {\n await cdpSessionManager.detach(tabId, 'console');\n } catch (e) {\n console.warn(`ConsoleTool: Error detaching debugger for tab ${tabId}:`, e);\n }\n }\n\n const endTime = Date.now();\n\n // Sort messages by timestamp\n messages.sort((a, b) => a.timestamp - b.timestamp);\n exceptions.sort((a, b) => a.timestamp - b.timestamp);\n\n return {\n success: true,\n message: `Console capture completed for tab ${tabId}. ${messages.length} messages, ${exceptions.length} exceptions captured.`,\n tabId,\n tabUrl: tab.url || '',\n tabTitle: tab.title || '',\n captureStartTime: startTime,\n captureEndTime: endTime,\n totalDurationMs: endTime - startTime,\n messages,\n exceptions,\n messageCount: messages.length,\n exceptionCount: exceptions.length,\n messageLimitReached: limitReached,\n droppedMessageCount: 0,\n droppedExceptionCount: 0,\n };\n } catch (error: any) {\n console.error(`ConsoleTool: Error capturing console messages for tab ${tabId}:`, error);\n throw error;\n }\n }\n}\n\nexport const consoleTool = new ConsoleTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/dialog.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\n\ninterface HandleDialogParams {\n action: 'accept' | 'dismiss';\n promptText?: string;\n}\n\n/**\n * Handle JavaScript dialogs (alert/confirm/prompt) via CDP Page.handleJavaScriptDialog\n */\nclass HandleDialogTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.HANDLE_DIALOG;\n\n async execute(args: HandleDialogParams): Promise {\n const { action, promptText } = args || ({} as HandleDialogParams);\n if (!action || (action !== 'accept' && action !== 'dismiss')) {\n return createErrorResponse('action must be \"accept\" or \"dismiss\"');\n }\n\n try {\n const [activeTab] = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!activeTab?.id) return createErrorResponse('No active tab found');\n const tabId = activeTab.id!;\n\n // Use shared CDP session manager for safe attach/detach with refcount\n await cdpSessionManager.withSession(tabId, 'dialog', async () => {\n await cdpSessionManager.sendCommand(tabId, 'Page.enable');\n await cdpSessionManager.sendCommand(tabId, 'Page.handleJavaScriptDialog', {\n accept: action === 'accept',\n promptText: action === 'accept' ? promptText : undefined,\n });\n });\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({ success: true, action, promptText: promptText || null }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n return createErrorResponse(\n `Failed to handle dialog: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const handleDialogTool = new HandleDialogTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/download.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\n\ninterface HandleDownloadParams {\n filenameContains?: string;\n timeoutMs?: number; // default 60000\n waitForComplete?: boolean; // default true\n}\n\n/**\n * Tool: wait for a download and return info\n */\nclass HandleDownloadTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.HANDLE_DOWNLOAD as any;\n\n async execute(args: HandleDownloadParams): Promise {\n const filenameContains = String(args?.filenameContains || '').trim();\n const waitForComplete = args?.waitForComplete !== false;\n const timeoutMs = Math.max(1000, Math.min(Number(args?.timeoutMs ?? 60000), 300000));\n\n try {\n const result = await waitForDownload({ filenameContains, waitForComplete, timeoutMs });\n return {\n content: [{ type: 'text', text: JSON.stringify({ success: true, download: result }) }],\n isError: false,\n };\n } catch (e: any) {\n return createErrorResponse(`Handle download failed: ${e?.message || String(e)}`);\n }\n }\n}\n\nasync function waitForDownload(opts: {\n filenameContains?: string;\n waitForComplete: boolean;\n timeoutMs: number;\n}) {\n const { filenameContains, waitForComplete, timeoutMs } = opts;\n return new Promise((resolve, reject) => {\n let timer: any = null;\n const onError = (err: any) => {\n cleanup();\n reject(err instanceof Error ? err : new Error(String(err)));\n };\n const cleanup = () => {\n try {\n if (timer) clearTimeout(timer);\n } catch {}\n try {\n chrome.downloads.onCreated.removeListener(onCreated);\n } catch {}\n try {\n chrome.downloads.onChanged.removeListener(onChanged);\n } catch {}\n };\n const matches = (item: chrome.downloads.DownloadItem) => {\n if (!filenameContains) return true;\n const name = (item.filename || '').split(/[/\\\\]/).pop() || '';\n return name.includes(filenameContains) || (item.url || '').includes(filenameContains);\n };\n const fulfill = async (item: chrome.downloads.DownloadItem) => {\n // try to fill more details via downloads.search\n try {\n const [found] = await chrome.downloads.search({ id: item.id });\n const out = found || item;\n cleanup();\n resolve({\n id: out.id,\n filename: out.filename,\n url: out.url,\n mime: (out as any).mime || undefined,\n fileSize: out.fileSize ?? out.totalBytes ?? undefined,\n state: out.state,\n danger: out.danger,\n startTime: out.startTime,\n endTime: (out as any).endTime || undefined,\n exists: (out as any).exists,\n });\n return;\n } catch {\n cleanup();\n resolve({ id: item.id, filename: item.filename, url: item.url, state: item.state });\n }\n };\n const onCreated = (item: chrome.downloads.DownloadItem) => {\n try {\n if (!matches(item)) return;\n if (!waitForComplete) {\n fulfill(item);\n }\n } catch {}\n };\n const onChanged = (delta: chrome.downloads.DownloadDelta) => {\n try {\n if (!delta || typeof delta.id !== 'number') return;\n // pull item and check\n chrome.downloads\n .search({ id: delta.id })\n .then((arr) => {\n const item = arr && arr[0];\n if (!item) return;\n if (!matches(item)) return;\n if (waitForComplete && item.state === 'complete') fulfill(item);\n })\n .catch(() => {});\n } catch {}\n };\n chrome.downloads.onCreated.addListener(onCreated);\n chrome.downloads.onChanged.addListener(onChanged);\n timer = setTimeout(() => onError(new Error('Download wait timed out')), timeoutMs);\n // Try to find an already-running matching download\n chrome.downloads\n .search({ state: waitForComplete ? 'in_progress' : undefined })\n .then((arr) => {\n const hit = (arr || []).find((d) => matches(d));\n if (hit && !waitForComplete) fulfill(hit);\n })\n .catch(() => {});\n });\n}\n\nexport const handleDownloadTool = new HandleDownloadTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/element-picker.ts", "content": "/**\n * Element Picker Tool\n *\n * Implements chrome_request_element_selection - a human-in-the-loop tool that allows\n * users to manually select elements on the page when AI cannot reliably locate them.\n */\n\nimport { createErrorResponse, type ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { BACKGROUND_MESSAGE_TYPES, TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { ERROR_MESSAGES } from '@/common/constants';\nimport {\n TOOL_NAMES,\n type ElementPickerRequest,\n type ElementPickerResult,\n type ElementPickerResultItem,\n type PickedElement,\n} from 'chrome-mcp-shared';\n\n// ============================================================\n// Types\n// ============================================================\n\ninterface NormalizedRequest {\n id: string;\n name: string;\n description?: string;\n}\n\ninterface ElementPickerToolParams {\n requests: ElementPickerRequest[];\n timeoutMs?: number;\n tabId?: number;\n windowId?: number;\n}\n\ninterface PickerUiEvent {\n type: string;\n sessionId: string;\n event: 'cancel' | 'confirm' | 'set_active_request' | 'clear_selection';\n requestId?: string;\n}\n\ninterface PickerFrameEvent {\n type: string;\n sessionId: string;\n event: 'selected' | 'cancel';\n requestId?: string;\n element?: Omit;\n}\n\n// ============================================================\n// Constants\n// ============================================================\n\nconst DEFAULT_TIMEOUT_MS = 3 * 60 * 1000; // 3 minutes\nconst MAX_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes\nconst MIN_TIMEOUT_MS = 10 * 1000; // 10 seconds\n\n// ============================================================\n// Utility Functions\n// ============================================================\n\nfunction toTrimmedString(value: unknown): string {\n return typeof value === 'string' ? value.trim() : '';\n}\n\nfunction normalizeTimeoutMs(value: unknown): number {\n if (value === undefined || value === null) return DEFAULT_TIMEOUT_MS;\n const n = Number(value);\n if (!Number.isFinite(n) || n <= 0) return DEFAULT_TIMEOUT_MS;\n return Math.min(Math.max(Math.floor(n), MIN_TIMEOUT_MS), MAX_TIMEOUT_MS);\n}\n\nfunction normalizeRequests(requests: ElementPickerRequest[]): NormalizedRequest[] {\n const out: NormalizedRequest[] = [];\n const seen = new Set();\n\n for (let i = 0; i < requests.length; i++) {\n const r = requests[i] || ({} as ElementPickerRequest);\n const name = toTrimmedString(r.name);\n if (!name) continue;\n\n // Generate or use provided ID, ensuring uniqueness\n const baseId = toTrimmedString(r.id) || `req_${i + 1}`;\n let id = baseId;\n let suffix = 2;\n while (seen.has(id)) {\n id = `${baseId}_${suffix++}`;\n }\n seen.add(id);\n\n const description = toTrimmedString(r.description);\n out.push({ id, name, description: description || undefined });\n }\n\n return out;\n}\n\nfunction buildResultItems(\n requests: NormalizedRequest[],\n pickedById: Map,\n): ElementPickerResultItem[] {\n return requests.map((r) => ({\n id: r.id,\n name: r.name,\n element: pickedById.get(r.id) || null,\n }));\n}\n\nfunction listMissingRequestIds(\n requests: NormalizedRequest[],\n pickedById: Map,\n): string[] {\n const missing: string[] = [];\n for (const r of requests) {\n if (!pickedById.has(r.id)) missing.push(r.id);\n }\n return missing;\n}\n\n// ============================================================\n// Element Picker Tool\n// ============================================================\n\nclass ElementPickerTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.REQUEST_ELEMENT_SELECTION;\n\n /**\n * Inject picker scripts into all frames of the tab.\n */\n private async injectPickerScripts(tabId: number): Promise {\n await chrome.scripting.executeScript({\n target: { tabId, allFrames: true },\n files: ['inject-scripts/element-picker.js'],\n world: 'ISOLATED',\n injectImmediately: false,\n } as any);\n }\n\n /**\n * Call the picker API in all frames via scripting.executeScript.\n */\n private async callPickerApi(\n tabId: number,\n method: 'startSession' | 'stopSession' | 'setActiveRequest',\n payload: Record,\n ): Promise {\n await chrome.scripting.executeScript({\n target: { tabId, allFrames: true },\n world: 'ISOLATED',\n injectImmediately: false,\n func: (methodName: string, data: Record) => {\n try {\n const api = (\n globalThis as unknown as {\n __mcpElementPicker?: Record) => void>;\n }\n ).__mcpElementPicker;\n const fn = api && api[methodName];\n if (typeof fn === 'function') {\n fn(data);\n }\n } catch {\n // Best-effort\n }\n },\n args: [method, payload],\n } as any);\n }\n\n async execute(args: ElementPickerToolParams): Promise {\n // Validate requests\n const rawRequests = Array.isArray(args?.requests) ? args.requests : [];\n if (rawRequests.length === 0) {\n return createErrorResponse(`${ERROR_MESSAGES.INVALID_PARAMETERS}: requests[] is required`);\n }\n\n const requests = normalizeRequests(rawRequests);\n if (requests.length === 0) {\n return createErrorResponse(\n `${ERROR_MESSAGES.INVALID_PARAMETERS}: requests[] must contain at least one non-empty name`,\n );\n }\n\n const timeoutMs = normalizeTimeoutMs(args?.timeoutMs);\n const sessionId = `ep_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;\n const deadlineTs = Date.now() + timeoutMs;\n\n // Resolve tab\n let tab: chrome.tabs.Tab;\n try {\n const explicit = await this.tryGetTab(args?.tabId);\n tab = explicit || (await this.getActiveTabOrThrowInWindow(args?.windowId));\n } catch (error) {\n return createErrorResponse(\n `${ERROR_MESSAGES.TAB_NOT_FOUND}: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n if (!tab.id) {\n return createErrorResponse(`${ERROR_MESSAGES.TAB_NOT_FOUND}: Active tab has no ID`);\n }\n const tabId = tab.id;\n\n // Focus the tab/window for user interaction\n try {\n await this.ensureFocus(tab, { activate: true, focusWindow: true });\n } catch {\n // Best-effort: some environments disallow focusing\n }\n\n // State tracking\n const pickedById = new Map();\n let activeRequestId: string | null = requests[0]?.id || null;\n let uiErrorMessage: string | null = null;\n let uiAvailable = true;\n\n let finished = false;\n let timer: ReturnType | null = null;\n let resolveResult: ((result: ElementPickerResult) => void) | null = null;\n\n // Send UI update to content script\n const sendUiUpdate = async (): Promise => {\n if (!uiAvailable) return;\n try {\n const selections: Record = {};\n for (const r of requests) {\n selections[r.id] = pickedById.get(r.id) || null;\n }\n await this.sendMessageToTab(\n tabId,\n {\n action: TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_UPDATE,\n sessionId,\n activeRequestId,\n selections,\n deadlineTs,\n errorMessage: uiErrorMessage,\n },\n 0, // Top frame only for UI\n );\n } catch {\n uiAvailable = false;\n }\n };\n\n // Set the active request and notify all frames + UI\n const setActiveRequest = async (requestId: string | null): Promise => {\n activeRequestId = requestId;\n await this.callPickerApi(tabId, 'setActiveRequest', {\n sessionId,\n activeRequestId: requestId,\n });\n await sendUiUpdate();\n };\n\n // Finish the tool execution\n const finish = async (final: {\n success: boolean;\n cancelled?: boolean;\n timedOut?: boolean;\n }): Promise => {\n if (finished) return;\n finished = true;\n\n if (timer !== null) {\n clearTimeout(timer);\n timer = null;\n }\n\n chrome.runtime.onMessage.removeListener(onRuntimeMessage);\n\n // Cleanup: stop picker in all frames and hide UI\n await Promise.allSettled([\n this.callPickerApi(tabId, 'stopSession', { sessionId }),\n uiAvailable\n ? this.sendMessageToTab(\n tabId,\n { action: TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_HIDE, sessionId },\n 0,\n )\n : Promise.resolve(),\n ]);\n\n const missing = listMissingRequestIds(requests, pickedById);\n const result: ElementPickerResult = {\n success: final.success,\n sessionId,\n timeoutMs,\n cancelled: final.cancelled,\n timedOut: final.timedOut,\n missingRequestIds: missing.length > 0 ? missing : undefined,\n results: buildResultItems(requests, pickedById),\n };\n\n resolveResult?.(result);\n };\n\n // Handle messages from content scripts\n const onRuntimeMessage = (\n message: unknown,\n sender: chrome.runtime.MessageSender,\n sendResponse: (response?: unknown) => void,\n ): boolean | void => {\n const senderTabId = sender?.tab?.id;\n if (senderTabId !== tabId) return;\n\n const msg = message as Partial | undefined;\n if (!msg || msg.sessionId !== sessionId) return;\n\n // Handle frame events (element selection)\n if (msg.type === BACKGROUND_MESSAGE_TYPES.ELEMENT_PICKER_FRAME_EVENT) {\n if (msg.event === 'cancel') {\n void finish({ success: false, cancelled: true });\n sendResponse?.({ success: true });\n return true;\n }\n\n if (msg.event === 'selected') {\n const requestId = toTrimmedString(msg.requestId);\n const frameId = typeof sender.frameId === 'number' ? sender.frameId : 0;\n\n // Validate request ID\n const reqExists = requestId && requests.some((r) => r.id === requestId);\n if (!reqExists) {\n sendResponse?.({ success: false, error: 'Unknown requestId' });\n return true;\n }\n\n // Validate element data\n const raw = (msg.element || {}) as Partial>;\n const ref = toTrimmedString(raw.ref);\n if (!ref) {\n sendResponse?.({ success: false, error: 'Missing element.ref' });\n return true;\n }\n\n // Build picked element with frameId\n const selector = toTrimmedString(raw.selector);\n const rect = raw.rect as PickedElement['rect'] | undefined;\n const center = raw.center as PickedElement['center'] | undefined;\n const picked: PickedElement = {\n ref,\n selector,\n selectorType: 'css',\n rect: rect && typeof rect === 'object' ? rect : { x: 0, y: 0, width: 0, height: 0 },\n center: center && typeof center === 'object' ? center : { x: 0, y: 0 },\n text: typeof raw.text === 'string' ? raw.text : undefined,\n tagName: typeof raw.tagName === 'string' ? raw.tagName : undefined,\n frameId,\n };\n\n pickedById.set(requestId, picked);\n uiErrorMessage = null;\n\n // Auto-advance to next missing request\n const missing = listMissingRequestIds(requests, pickedById);\n const next = missing.length > 0 ? missing[0] : null;\n\n void (async () => {\n try {\n if (next) {\n await setActiveRequest(next);\n } else {\n // All selected: update UI (user still needs to confirm)\n await sendUiUpdate();\n // If UI is unavailable, auto-confirm\n if (!uiAvailable) {\n await finish({ success: true });\n }\n }\n } catch {\n // Best-effort\n }\n })();\n\n sendResponse?.({ success: true });\n return true;\n }\n }\n\n // Handle UI events (cancel, confirm, etc.)\n if (msg.type === BACKGROUND_MESSAGE_TYPES.ELEMENT_PICKER_UI_EVENT) {\n if (msg.event === 'cancel') {\n void finish({ success: false, cancelled: true });\n sendResponse?.({ success: true });\n return true;\n }\n\n if (msg.event === 'confirm') {\n const missing = listMissingRequestIds(requests, pickedById);\n if (missing.length > 0) {\n uiErrorMessage = `Please select all elements: missing ${missing.join(', ')}`;\n void sendUiUpdate();\n sendResponse?.({ success: false, error: 'missing_selections', missing });\n return true;\n }\n void finish({ success: true });\n sendResponse?.({ success: true });\n return true;\n }\n\n if (msg.event === 'set_active_request') {\n const requestId = toTrimmedString(msg.requestId);\n if (!requestId || !requests.some((r) => r.id === requestId)) {\n sendResponse?.({ success: false, error: 'Unknown requestId' });\n return true;\n }\n void setActiveRequest(requestId);\n sendResponse?.({ success: true });\n return true;\n }\n\n if (msg.event === 'clear_selection') {\n const requestId = toTrimmedString(msg.requestId);\n if (!requestId || !requests.some((r) => r.id === requestId)) {\n sendResponse?.({ success: false, error: 'Unknown requestId' });\n return true;\n }\n pickedById.delete(requestId);\n uiErrorMessage = null;\n void setActiveRequest(requestId);\n sendResponse?.({ success: true });\n return true;\n }\n }\n\n return;\n };\n\n try {\n // Step 1: Ensure UI content script is ready (ping + inject fallback)\n const ensureUiReady = async (): Promise => {\n // Try to ping UI content script with retries\n const pingWithTimeout = async (timeoutMs = 500): Promise => {\n try {\n const resp = await Promise.race([\n this.sendMessageToTab(\n tabId,\n { action: TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_PING },\n 0,\n ),\n new Promise((_, reject) =>\n setTimeout(() => reject(new Error('Ping timeout')), timeoutMs),\n ),\n ]);\n return resp?.success === true;\n } catch {\n return false;\n }\n };\n\n // First ping attempt (content script may already be loaded)\n if (await pingWithTimeout()) return true;\n\n // Try to inject UI content script as fallback\n // Try multiple possible paths (production vs dev builds)\n const possiblePaths = ['content-scripts/element-picker.js', 'element-picker.js'];\n\n for (const path of possiblePaths) {\n try {\n await chrome.scripting.executeScript({\n target: { tabId, frameIds: [0] },\n files: [path],\n injectImmediately: true,\n } as any);\n // Wait a bit for script to initialize\n await new Promise((r) => setTimeout(r, 150));\n // Check if injection worked\n if (await pingWithTimeout(300)) return true;\n } catch (e) {\n // Try next path\n console.debug(`[ElementPicker] Path ${path} failed:`, e);\n }\n }\n\n // Final attempt with longer timeout (in case of slow page)\n return pingWithTimeout(1000);\n };\n\n const uiReady = await ensureUiReady();\n if (!uiReady) {\n console.error('[ElementPicker] UI not available after all attempts');\n return createErrorResponse(\n `${ERROR_MESSAGES.TOOL_EXECUTION_FAILED}: Element Picker UI is not available. This may happen if: (1) The page blocks content scripts, (2) You're using dev mode - try restarting the dev server or use production build, (3) The page needs to be refreshed.`,\n );\n }\n\n // Step 2: Show UI in top frame (must receive success:true)\n try {\n const showResp = await this.sendMessageToTab(\n tabId,\n {\n action: TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_SHOW,\n sessionId,\n requests,\n activeRequestId,\n deadlineTs,\n },\n 0,\n );\n if (showResp?.success !== true) {\n throw new Error('UI did not acknowledge show message');\n }\n } catch (e) {\n console.error('[ElementPicker] UI show failed:', e);\n return createErrorResponse(\n `${ERROR_MESSAGES.TOOL_EXECUTION_FAILED}: Failed to show Element Picker UI. Please refresh the page and try again.`,\n );\n }\n\n // Step 3: Inject picker scripts and start selection engine in all frames\n await this.injectPickerScripts(tabId);\n await this.callPickerApi(tabId, 'startSession', { sessionId, activeRequestId });\n\n // Register message listener\n chrome.runtime.onMessage.addListener(onRuntimeMessage);\n\n // Create result promise\n const resultPromise = new Promise((resolve) => {\n resolveResult = resolve;\n });\n\n // Set timeout\n timer = setTimeout(() => {\n void finish({ success: false, timedOut: true });\n }, timeoutMs);\n\n // Initial UI update\n void sendUiUpdate();\n\n // Wait for result\n const result = await resultPromise;\n return { content: [{ type: 'text', text: JSON.stringify(result) }], isError: false };\n } catch (error) {\n console.error('Error in element picker tool:', error);\n // Cleanup on error\n try {\n await Promise.allSettled([\n this.callPickerApi(tabId, 'stopSession', { sessionId }),\n this.sendMessageToTab(\n tabId,\n { action: TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_HIDE, sessionId },\n 0,\n ),\n ]);\n } catch {\n // Best-effort cleanup\n }\n return createErrorResponse(\n `${ERROR_MESSAGES.TOOL_EXECUTION_FAILED}: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const elementPickerTool = new ElementPickerTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/file-upload.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\n\ninterface FileUploadToolParams {\n selector: string; // CSS selector for the file input element\n filePath?: string; // Local file path\n fileUrl?: string; // URL to download file from\n base64Data?: string; // Base64 encoded file data\n fileName?: string; // Optional filename when using base64 or URL\n multiple?: boolean; // Whether to allow multiple files\n tabId?: number; // Target existing tab id\n windowId?: number; // When no tabId, pick active tab from this window\n}\n\n/**\n * Tool for uploading files to web forms using Chrome DevTools Protocol\n * Similar to Playwright's setInputFiles implementation\n */\nclass FileUploadTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.FILE_UPLOAD;\n constructor() {\n super();\n }\n\n /**\n * Execute file upload operation using Chrome DevTools Protocol\n */\n async execute(args: FileUploadToolParams): Promise {\n const { selector, filePath, fileUrl, base64Data, fileName, multiple = false } = args;\n\n console.log(`Starting file upload operation with options:`, args);\n\n // Validate input\n if (!selector) {\n return createErrorResponse('Selector is required for file upload');\n }\n\n if (!filePath && !fileUrl && !base64Data) {\n return createErrorResponse('One of filePath, fileUrl, or base64Data must be provided');\n }\n\n try {\n // Resolve tab\n const explicit = await this.tryGetTab(args.tabId);\n const tab = explicit || (await this.getActiveTabOrThrowInWindow(args.windowId));\n if (!tab.id) return createErrorResponse('No active tab found');\n const tabId = tab.id;\n\n // Prepare file paths\n let files: string[] = [];\n\n if (filePath) {\n // Direct file path provided\n files = [filePath];\n } else if (fileUrl || base64Data) {\n // For URL or base64, we need to use the native messaging host\n // to download or save the file temporarily\n const tempFilePath = await this.prepareFileFromRemote({\n fileUrl,\n base64Data,\n fileName: fileName || 'uploaded-file',\n });\n if (!tempFilePath) {\n return createErrorResponse('Failed to prepare file for upload');\n }\n files = [tempFilePath];\n }\n\n // Use shared CDP session manager to attach/do work/detach safely\n await cdpSessionManager.withSession(tabId, 'file-upload', async () => {\n // Enable necessary CDP domains\n await cdpSessionManager.sendCommand(tabId, 'DOM.enable', {});\n await cdpSessionManager.sendCommand(tabId, 'Runtime.enable', {});\n\n // Get the document\n const { root } = (await cdpSessionManager.sendCommand(tabId, 'DOM.getDocument', {\n depth: -1,\n pierce: true,\n })) as { root: { nodeId: number } };\n\n // Find the file input element using the selector\n const { nodeId } = (await cdpSessionManager.sendCommand(tabId, 'DOM.querySelector', {\n nodeId: root.nodeId,\n selector: selector,\n })) as { nodeId: number };\n\n if (!nodeId || nodeId === 0) {\n throw new Error(`Element with selector \"${selector}\" not found`);\n }\n\n // Verify it's actually a file input\n const { node } = (await cdpSessionManager.sendCommand(tabId, 'DOM.describeNode', {\n nodeId,\n })) as { node: { nodeName: string; attributes?: string[] } };\n\n if (node.nodeName !== 'INPUT') {\n throw new Error(`Element with selector \"${selector}\" is not an input element`);\n }\n\n // Check if it's a file input by looking for type=\"file\" in attributes\n const attributes = node.attributes || [];\n let isFileInput = false;\n for (let i = 0; i < attributes.length; i += 2) {\n if (attributes[i] === 'type' && attributes[i + 1] === 'file') {\n isFileInput = true;\n break;\n }\n }\n\n if (!isFileInput) {\n throw new Error(`Element with selector \"${selector}\" is not a file input (type=\"file\")`);\n }\n\n // Set the files on the input element\n await cdpSessionManager.sendCommand(tabId, 'DOM.setFileInputFiles', {\n nodeId,\n files,\n });\n\n // Trigger change event to ensure the page reacts to the file upload\n await cdpSessionManager.sendCommand(tabId, 'Runtime.evaluate', {\n expression: `\n (function() {\n const element = document.querySelector('${selector.replace(/'/g, \"\\\\'\")}');\n if (element) {\n const event = new Event('change', { bubbles: true });\n element.dispatchEvent(event);\n return true;\n }\n return false;\n })()\n `,\n });\n });\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'File(s) uploaded successfully',\n files: files,\n selector: selector,\n fileCount: files.length,\n }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in file upload operation:', error);\n\n // Session manager handles detach; nothing extra needed here\n\n return createErrorResponse(\n `Error uploading file: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n // All debugger attach/detach is centrally managed by cdpSessionManager\n\n /**\n * Prepare file from URL or base64 data using native messaging host\n */\n private async prepareFileFromRemote(options: {\n fileUrl?: string;\n base64Data?: string;\n fileName: string;\n }): Promise {\n const { fileUrl, base64Data, fileName } = options;\n\n return new Promise((resolve) => {\n const requestId = `file-upload-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;\n const timeout = setTimeout(() => {\n console.error('File preparation request timed out');\n resolve(null);\n }, 30000); // 30 second timeout\n\n // Create listener for the response\n const handleMessage = (message: any) => {\n if (\n message.type === 'file_operation_response' &&\n message.responseToRequestId === requestId\n ) {\n clearTimeout(timeout);\n chrome.runtime.onMessage.removeListener(handleMessage);\n\n if (message.payload?.success && message.payload?.filePath) {\n resolve(message.payload.filePath);\n } else {\n console.error(\n 'Native host failed to prepare file:',\n message.error || message.payload?.error,\n );\n resolve(null);\n }\n }\n };\n\n // Add listener\n chrome.runtime.onMessage.addListener(handleMessage);\n\n // Send message to background script to forward to native host\n chrome.runtime\n .sendMessage({\n type: 'forward_to_native',\n message: {\n type: 'file_operation',\n requestId: requestId,\n payload: {\n action: 'prepareFile',\n fileUrl,\n base64Data,\n fileName,\n },\n },\n })\n .catch((error) => {\n console.error('Error sending message to background:', error);\n clearTimeout(timeout);\n chrome.runtime.onMessage.removeListener(handleMessage);\n resolve(null);\n });\n });\n }\n}\n\nexport const fileUploadTool = new FileUploadTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/gif-auto-capture.ts", "content": "/**\n * GIF Auto-Capture Hook System\n *\n * Provides automatic frame capture for GIF recording when browser actions succeed.\n * Tools like chrome_computer and chrome_navigate can trigger frame captures\n * after successful operations, creating smooth recordings of user interactions.\n *\n * Architecture:\n * - Centralized capture manager with per-tab recording state\n * - Hooks can be registered/unregistered per tab\n * - Configurable capture delay for UI stabilization\n * - Enhanced rendering overlays (click indicators, drag paths, labels)\n */\n\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\nimport { OFFSCREEN_MESSAGE_TYPES, MessageTarget } from '@/common/message-types';\nimport { offscreenManager } from '@/utils/offscreen-manager';\nimport { createImageBitmapFromUrl } from '@/utils/image-utils';\nimport {\n pruneActionEventsInPlace,\n renderGifEnhancedOverlays,\n resolveCapturePlanForAction,\n resolveGifEnhancedRenderingConfig,\n type ActionEvent,\n type ActionMetadata,\n type ActionType,\n type GifEnhancedRenderingConfig,\n type ResolvedGifEnhancedRenderingConfig,\n} from './gif-enhanced-renderer';\n\n// Re-export types for consumers\nexport type {\n ActionMetadata,\n ActionType,\n GifEnhancedRenderingConfig,\n} from './gif-enhanced-renderer';\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst CDP_SESSION_KEY = 'gif-auto-capture';\nconst DEFAULT_CAPTURE_DELAY_MS = 150;\nconst DEFAULT_WIDTH = 800;\nconst DEFAULT_HEIGHT = 600;\nconst DEFAULT_FRAME_DELAY_CS = 20; // 20 centiseconds = 200ms per frame\nconst DEFAULT_MAX_COLORS = 256;\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport interface AutoCaptureConfig {\n width: number;\n height: number;\n maxColors: number;\n frameDelayCs: number;\n captureDelayMs: number;\n maxFrames: number;\n enhancedRendering?: GifEnhancedRenderingConfig;\n}\n\ninterface TabCaptureState {\n tabId: number;\n config: AutoCaptureConfig;\n rendering: ResolvedGifEnhancedRenderingConfig;\n frameCount: number;\n startTime: number;\n canvas: OffscreenCanvas;\n ctx: OffscreenCanvasRenderingContext2D;\n pendingCapture: Promise | null;\n actions: ActionMetadata[];\n actionEvents: ActionEvent[];\n lastViewportWidth: number;\n lastViewportHeight: number;\n}\n\n// ============================================================================\n// State Management\n// ============================================================================\n\nconst tabStates = new Map();\n\n// ============================================================================\n// Utilities\n// ============================================================================\n\nfunction sleep(ms: number): Promise {\n return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nfunction normalizeActionMetadata(action: ActionMetadata, atMs: number): ActionMetadata {\n const normalized: ActionMetadata = {\n ...action,\n timestampMs: atMs,\n coordinateSpace: action.coordinateSpace ?? 'viewport',\n };\n\n // For drag, treat `coordinates` as end position (legacy) and also populate `endCoordinates`\n if (normalized.type === 'drag') {\n const end = normalized.endCoordinates ?? normalized.coordinates;\n if (end) {\n normalized.endCoordinates = end;\n normalized.coordinates = end;\n }\n }\n\n return normalized;\n}\n\n// ============================================================================\n// Offscreen Communication\n// ============================================================================\n\nasync function sendToOffscreen(\n type: string,\n payload: Record = {},\n): Promise {\n await offscreenManager.ensureOffscreenDocument();\n\n const response = (await chrome.runtime.sendMessage({\n target: MessageTarget.Offscreen,\n type,\n ...payload,\n })) as T | undefined;\n\n if (!response) {\n throw new Error('No response from offscreen document');\n }\n if (!response.success) {\n throw new Error(response.error || 'Unknown offscreen error');\n }\n\n return response;\n}\n\n// ============================================================================\n// Frame Capture\n// ============================================================================\n\nasync function captureFrameData(tabId: number, state: TabCaptureState): Promise {\n const width = state.config.width;\n const height = state.config.height;\n const ctx = state.ctx;\n\n // Get viewport metrics\n const metrics: { layoutViewport?: { clientWidth: number; clientHeight: number } } =\n await cdpSessionManager.sendCommand(tabId, 'Page.getLayoutMetrics', {});\n\n const viewportWidth = metrics.layoutViewport?.clientWidth || width;\n const viewportHeight = metrics.layoutViewport?.clientHeight || height;\n\n // Store viewport dimensions for coordinate projection\n state.lastViewportWidth = viewportWidth;\n state.lastViewportHeight = viewportHeight;\n\n // Capture screenshot\n const screenshot: { data: string } = await cdpSessionManager.sendCommand(\n tabId,\n 'Page.captureScreenshot',\n {\n format: 'png',\n clip: {\n x: 0,\n y: 0,\n width: viewportWidth,\n height: viewportHeight,\n scale: 1,\n },\n },\n );\n\n const imageBitmap = await createImageBitmapFromUrl(`data:image/png;base64,${screenshot.data}`);\n\n // Scale to target dimensions\n ctx.clearRect(0, 0, width, height);\n ctx.drawImage(imageBitmap, 0, 0, width, height);\n imageBitmap.close();\n\n // Apply enhanced rendering overlays\n if (state.rendering.enabled) {\n const nowMs = Date.now();\n renderGifEnhancedOverlays({\n ctx,\n outputWidth: width,\n outputHeight: height,\n viewportWidth,\n viewportHeight,\n nowMs,\n events: state.actionEvents,\n config: state.rendering,\n });\n pruneActionEventsInPlace(state.actionEvents, nowMs, state.rendering);\n }\n\n return ctx.getImageData(0, 0, width, height).data;\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Start auto-capture for a tab. This initializes the GIF encoder\n * and prepares for automatic frame capture on tool actions.\n */\nexport async function startAutoCapture(\n tabId: number,\n config?: Partial,\n): Promise<{ success: boolean; error?: string }> {\n if (tabStates.has(tabId)) {\n return { success: false, error: 'Auto-capture already active for this tab' };\n }\n\n const finalConfig: AutoCaptureConfig = {\n width: config?.width ?? DEFAULT_WIDTH,\n height: config?.height ?? DEFAULT_HEIGHT,\n maxColors: config?.maxColors ?? DEFAULT_MAX_COLORS,\n frameDelayCs: config?.frameDelayCs ?? DEFAULT_FRAME_DELAY_CS,\n captureDelayMs: config?.captureDelayMs ?? DEFAULT_CAPTURE_DELAY_MS,\n maxFrames: config?.maxFrames ?? 100,\n enhancedRendering: config?.enhancedRendering,\n };\n\n try {\n // Attach CDP session\n await cdpSessionManager.attach(tabId, CDP_SESSION_KEY);\n\n // Reset offscreen encoder\n await sendToOffscreen(OFFSCREEN_MESSAGE_TYPES.GIF_RESET, {});\n\n // Create canvas\n if (typeof OffscreenCanvas === 'undefined') {\n throw new Error('OffscreenCanvas not available');\n }\n\n const canvas = new OffscreenCanvas(finalConfig.width, finalConfig.height);\n const ctx = canvas.getContext('2d');\n if (!ctx) {\n throw new Error('Failed to get canvas context');\n }\n\n const state: TabCaptureState = {\n tabId,\n config: finalConfig,\n rendering: resolveGifEnhancedRenderingConfig(finalConfig.enhancedRendering),\n frameCount: 0,\n startTime: Date.now(),\n canvas,\n ctx,\n pendingCapture: null,\n actions: [],\n actionEvents: [],\n lastViewportWidth: finalConfig.width,\n lastViewportHeight: finalConfig.height,\n };\n\n tabStates.set(tabId, state);\n\n return { success: true };\n } catch (error) {\n // Cleanup on failure\n try {\n await cdpSessionManager.detach(tabId, CDP_SESSION_KEY);\n } catch {\n // Ignore\n }\n\n return {\n success: false,\n error: error instanceof Error ? error.message : String(error),\n };\n }\n}\n\n/**\n * Stop auto-capture and finalize the GIF.\n * Returns the GIF data for saving/downloading.\n */\nexport async function stopAutoCapture(tabId: number): Promise<{\n success: boolean;\n gifData?: Uint8Array;\n frameCount?: number;\n durationMs?: number;\n actions?: ActionMetadata[];\n error?: string;\n}> {\n const state = tabStates.get(tabId);\n if (!state) {\n return { success: false, error: 'No auto-capture active for this tab' };\n }\n\n try {\n // Wait for any pending capture\n if (state.pendingCapture) {\n await state.pendingCapture;\n }\n\n const frameCount = state.frameCount;\n const durationMs = Date.now() - state.startTime;\n const actions = [...state.actions];\n\n if (frameCount === 0) {\n return {\n success: false,\n error: 'No frames captured',\n frameCount: 0,\n durationMs,\n actions,\n };\n }\n\n // Finalize GIF\n const response = await sendToOffscreen<{\n success: boolean;\n gifData?: number[];\n byteLength?: number;\n error?: string;\n }>(OFFSCREEN_MESSAGE_TYPES.GIF_FINISH, {});\n\n if (!response.gifData || response.gifData.length === 0) {\n return {\n success: false,\n error: 'Failed to encode GIF',\n frameCount,\n durationMs,\n actions,\n };\n }\n\n return {\n success: true,\n gifData: new Uint8Array(response.gifData),\n frameCount,\n durationMs,\n actions,\n };\n } catch (error) {\n return {\n success: false,\n error: error instanceof Error ? error.message : String(error),\n };\n } finally {\n // Cleanup\n tabStates.delete(tabId);\n try {\n await cdpSessionManager.detach(tabId, CDP_SESSION_KEY);\n } catch {\n // Ignore\n }\n }\n}\n\n/**\n * Check if auto-capture is active for a tab.\n */\nexport function isAutoCaptureActive(tabId: number): boolean {\n return tabStates.has(tabId);\n}\n\n/**\n * Get current auto-capture status for a tab.\n */\nexport function getAutoCaptureStatus(tabId: number): {\n active: boolean;\n frameCount?: number;\n durationMs?: number;\n actionsCount?: number;\n enhancedRenderingEnabled?: boolean;\n} {\n const state = tabStates.get(tabId);\n if (!state) {\n return { active: false };\n }\n\n return {\n active: true,\n frameCount: state.frameCount,\n durationMs: Date.now() - state.startTime,\n actionsCount: state.actions.length,\n enhancedRenderingEnabled: state.rendering.enabled,\n };\n}\n\n/**\n * Trigger a frame capture after a successful action.\n * This is the main hook that tools should call.\n *\n * @param tabId - The tab to capture\n * @param action - Optional action metadata for overlay rendering\n * @param immediate - If true, capture immediately without delay\n */\nexport async function captureFrameOnAction(\n tabId: number,\n action?: ActionMetadata,\n immediate = false,\n): Promise<{ success: boolean; frameNumber?: number; error?: string }> {\n const state = tabStates.get(tabId);\n if (!state) {\n // No auto-capture active - silently succeed (tools shouldn't fail because recording isn't active)\n return { success: true };\n }\n\n // Check frame limit\n if (state.frameCount >= state.config.maxFrames) {\n return { success: false, error: 'Max frame limit reached' };\n }\n\n // Wait for any pending capture to complete\n if (state.pendingCapture) {\n try {\n await state.pendingCapture;\n } catch {\n // Ignore errors from previous capture\n }\n }\n\n // Verify state still exists (might have been stopped while awaiting)\n const currentState = tabStates.get(tabId);\n if (!currentState) {\n return { success: true };\n }\n\n // Calculate delay for UI stabilization\n const delayMs = immediate ? 0 : currentState.config.captureDelayMs;\n\n // Normalize and record action metadata\n let normalizedAction: ActionMetadata | undefined;\n if (action) {\n const atMs = Date.now() + delayMs;\n normalizedAction = normalizeActionMetadata(action, atMs);\n currentState.actions.push(normalizedAction);\n currentState.actionEvents.push({ action: normalizedAction, atMs });\n }\n\n // Determine capture plan (may involve multiple frames for click animations)\n const plan = resolveCapturePlanForAction(\n currentState.rendering,\n normalizedAction,\n currentState.config.frameDelayCs,\n );\n\n const capturePromise = (async () => {\n if (delayMs > 0) await sleep(delayMs);\n\n for (let i = 0; i < plan.frames; i++) {\n const activeState = tabStates.get(tabId);\n if (!activeState) return;\n\n if (activeState.frameCount >= activeState.config.maxFrames) return;\n\n try {\n const frameData = await captureFrameData(tabId, activeState);\n\n // Use animation delay for intermediate frames, regular delay for final frame\n const delayCs = i < plan.frames - 1 ? plan.delayCs : activeState.config.frameDelayCs;\n\n await sendToOffscreen(OFFSCREEN_MESSAGE_TYPES.GIF_ADD_FRAME, {\n imageData: Array.from(frameData),\n width: activeState.config.width,\n height: activeState.config.height,\n delay: delayCs,\n maxColors: activeState.config.maxColors,\n });\n\n activeState.frameCount += 1;\n } catch (error) {\n console.error('[GIF Auto-Capture] Frame capture failed:', error);\n return;\n }\n\n // Wait between animation frames\n if (i < plan.frames - 1 && plan.intervalMs > 0) {\n await sleep(plan.intervalMs);\n }\n }\n })();\n\n state.pendingCapture = capturePromise;\n\n try {\n await capturePromise;\n return { success: true, frameNumber: state.frameCount };\n } catch (error) {\n return {\n success: false,\n error: error instanceof Error ? error.message : String(error),\n };\n } finally {\n // Clean up reference to avoid holding completed Promise\n const currentState = tabStates.get(tabId);\n if (currentState?.pendingCapture === capturePromise) {\n currentState.pendingCapture = null;\n }\n }\n}\n\n/**\n * Capture an initial frame immediately (useful for recording start state).\n */\nexport async function captureInitialFrame(\n tabId: number,\n): Promise<{ success: boolean; error?: string }> {\n return captureFrameOnAction(tabId, undefined, true);\n}\n\n/**\n * Clear all auto-capture state (useful for cleanup).\n */\nexport async function clearAllAutoCapture(): Promise {\n const tabIds = Array.from(tabStates.keys());\n for (const tabId of tabIds) {\n try {\n await stopAutoCapture(tabId);\n } catch {\n // Ignore errors during cleanup\n tabStates.delete(tabId);\n }\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/gif-enhanced-renderer.ts", "content": "/**\n * GIF Enhanced Renderer\n *\n * Draws visual affordances (click indicators, drag paths, labels) onto a canvas\n * before encoding frames. This keeps the offscreen document focused on encoding\n * while the background capture pipeline handles compositing.\n *\n * Coordinates are expected to be in viewport CSS pixels. If a caller provides\n * screenshot-space coordinates, it should convert them to viewport space first.\n */\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport type ActionType =\n | 'click'\n | 'double_click'\n | 'triple_click'\n | 'right_click'\n | 'drag'\n | 'scroll'\n | 'type'\n | 'key'\n | 'navigate'\n | 'hover'\n | 'fill'\n | 'annotation'\n | 'other';\n\nexport type CoordinateSpace = 'viewport' | 'screenshot';\n\nexport interface Point {\n x: number;\n y: number;\n}\n\nexport interface ActionMetadata {\n type: ActionType;\n coordinates?: Point;\n startCoordinates?: Point;\n endCoordinates?: Point;\n text?: string;\n url?: string;\n ref?: string;\n\n // Enhanced rendering hints\n label?: string;\n coordinateSpace?: CoordinateSpace;\n timestampMs?: number;\n}\n\nexport interface GifEnhancedRenderingConfig {\n enabled?: boolean;\n\n clickIndicators?: {\n enabled?: boolean;\n color?: string;\n fillColor?: string;\n radiusPx?: number;\n lineWidthPx?: number;\n durationMs?: number;\n // Capture-side animation hints (auto-capture mode only)\n animationFrames?: number;\n animationIntervalMs?: number;\n animationFrameDelayCs?: number;\n };\n\n dragPaths?: {\n enabled?: boolean;\n color?: string;\n lineWidthPx?: number;\n durationMs?: number;\n arrowSizePx?: number;\n dash?: number[];\n startDotRadiusPx?: number;\n endDotRadiusPx?: number;\n };\n\n labels?: {\n enabled?: boolean;\n mode?: 'action' | 'annotation' | 'both';\n showForClicks?: boolean;\n font?: string;\n maxLength?: number;\n durationMs?: number;\n backgroundColor?: string;\n borderColor?: string;\n textColor?: string;\n paddingX?: number;\n paddingY?: number;\n radiusPx?: number;\n offsetPx?: number;\n };\n}\n\n// ============================================================================\n// Resolved Config Types\n// ============================================================================\n\nexport interface ResolvedClickIndicatorConfig {\n enabled: boolean;\n color: string;\n fillColor: string;\n radiusPx: number;\n lineWidthPx: number;\n durationMs: number;\n animationFrames: number;\n animationIntervalMs: number;\n animationFrameDelayCs: number;\n}\n\nexport interface ResolvedDragPathConfig {\n enabled: boolean;\n color: string;\n lineWidthPx: number;\n durationMs: number;\n arrowSizePx: number;\n dash: number[];\n startDotRadiusPx: number;\n endDotRadiusPx: number;\n}\n\nexport interface ResolvedLabelsConfig {\n enabled: boolean;\n mode: 'action' | 'annotation' | 'both';\n showForClicks: boolean;\n font: string;\n maxLength: number;\n durationMs: number;\n backgroundColor: string;\n borderColor: string;\n textColor: string;\n paddingX: number;\n paddingY: number;\n radiusPx: number;\n offsetPx: number;\n}\n\nexport interface ResolvedGifEnhancedRenderingConfig {\n enabled: boolean;\n clickIndicators: ResolvedClickIndicatorConfig;\n dragPaths: ResolvedDragPathConfig;\n labels: ResolvedLabelsConfig;\n}\n\nexport interface ActionEvent {\n action: ActionMetadata;\n atMs: number;\n}\n\nexport interface CapturePlan {\n frames: number;\n intervalMs: number;\n delayCs: number;\n}\n\nexport interface RenderGifEnhancedOverlaysParams {\n ctx: OffscreenCanvasRenderingContext2D;\n outputWidth: number;\n outputHeight: number;\n viewportWidth: number;\n viewportHeight: number;\n nowMs: number;\n events: readonly ActionEvent[];\n config: ResolvedGifEnhancedRenderingConfig;\n}\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst CLICK_ACTIONS: readonly ActionType[] = [\n 'click',\n 'double_click',\n 'triple_click',\n 'right_click',\n];\n\n// ============================================================================\n// Utility Functions\n// ============================================================================\n\nfunction clamp(value: number, min: number, max: number): number {\n return Math.min(max, Math.max(min, value));\n}\n\nfunction normalizePositiveNumber(\n value: unknown,\n fallback: number,\n min: number,\n max: number,\n): number {\n if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;\n return clamp(value, min, max);\n}\n\nfunction normalizePositiveInt(value: unknown, fallback: number, min: number, max: number): number {\n if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;\n return clamp(Math.floor(value), min, max);\n}\n\nfunction normalizeDash(value: unknown, fallback: number[]): number[] {\n if (!Array.isArray(value)) return fallback;\n const nums = value.filter((n) => typeof n === 'number' && Number.isFinite(n) && n > 0);\n return nums.length >= 2 ? (nums as number[]) : fallback;\n}\n\nfunction easeOutCubic(t: number): number {\n const x = clamp(t, 0, 1);\n return 1 - Math.pow(1 - x, 3);\n}\n\nfunction projectPoint(\n point: Point,\n viewportWidth: number,\n viewportHeight: number,\n outputWidth: number,\n outputHeight: number,\n): Point | null {\n if (\n typeof point.x !== 'number' ||\n typeof point.y !== 'number' ||\n !Number.isFinite(point.x) ||\n !Number.isFinite(point.y)\n ) {\n return null;\n }\n\n const vw = viewportWidth > 0 ? viewportWidth : outputWidth;\n const vh = viewportHeight > 0 ? viewportHeight : outputHeight;\n\n return {\n x: (point.x / vw) * outputWidth,\n y: (point.y / vh) * outputHeight,\n };\n}\n\nfunction buildRoundedRectPath(\n ctx: OffscreenCanvasRenderingContext2D,\n x: number,\n y: number,\n width: number,\n height: number,\n radius: number,\n): void {\n const r = Math.max(0, Math.min(radius, Math.min(width, height) / 2));\n const x2 = x + width;\n const y2 = y + height;\n\n ctx.moveTo(x + r, y);\n ctx.arcTo(x2, y, x2, y2, r);\n ctx.arcTo(x2, y2, x, y2, r);\n ctx.arcTo(x, y2, x, y, r);\n ctx.arcTo(x, y, x2, y, r);\n}\n\nfunction truncate(text: string, maxLength: number): string {\n const trimmed = text.trim();\n if (trimmed.length <= maxLength) return trimmed;\n return `${trimmed.slice(0, Math.max(0, maxLength - 1))}…`;\n}\n\n// ============================================================================\n// Label Resolution\n// ============================================================================\n\nfunction resolveActionLabel(action: ActionMetadata, cfg: ResolvedLabelsConfig): string | null {\n const explicit = typeof action.label === 'string' ? action.label.trim() : '';\n const isExplicit = explicit.length > 0;\n\n const mode = cfg.mode;\n const canShowAction = mode === 'action' || mode === 'both';\n const canShowAnnotation = mode === 'annotation' || mode === 'both';\n\n if ((action.type === 'annotation' || isExplicit) && canShowAnnotation) {\n const labelText = explicit || (typeof action.text === 'string' ? action.text.trim() : '');\n return labelText.length > 0 ? truncate(labelText, cfg.maxLength) : null;\n }\n\n if (!canShowAction) return null;\n\n switch (action.type) {\n case 'click':\n case 'double_click':\n case 'triple_click':\n case 'right_click':\n if (!cfg.showForClicks) return null;\n return action.type.replace('_', ' ').toUpperCase();\n case 'drag':\n return 'DRAG';\n case 'scroll':\n return 'SCROLL';\n case 'hover':\n return 'HOVER';\n case 'navigate': {\n if (!action.url) return 'NAVIGATE';\n try {\n const host = new URL(action.url).hostname;\n return host ? `→ ${host}` : 'NAVIGATE';\n } catch {\n return 'NAVIGATE';\n }\n }\n case 'type': {\n const content = typeof action.text === 'string' ? action.text : '';\n return content.trim().length > 0 ? `TYPE \"${truncate(content, cfg.maxLength)}\"` : 'TYPE';\n }\n case 'key': {\n const content = typeof action.text === 'string' ? action.text : '';\n return content.trim().length > 0 ? `KEY [${truncate(content, cfg.maxLength)}]` : 'KEY';\n }\n case 'fill': {\n const content = typeof action.text === 'string' ? action.text : '';\n return content.trim().length > 0 ? `FILL \"${truncate(content, cfg.maxLength)}\"` : 'FILL';\n }\n default:\n return null;\n }\n}\n\nfunction resolveAnchorPoint(action: ActionMetadata): Point | null {\n if (action.type === 'drag') {\n return action.endCoordinates || action.coordinates || action.startCoordinates || null;\n }\n return action.coordinates || action.endCoordinates || action.startCoordinates || null;\n}\n\n// ============================================================================\n// Drawing Functions\n// ============================================================================\n\nfunction drawClickIndicator(\n ctx: OffscreenCanvasRenderingContext2D,\n x: number,\n y: number,\n progress: number,\n type: ActionType,\n cfg: ResolvedClickIndicatorConfig,\n): void {\n const t = clamp(progress, 0, 1);\n const eased = easeOutCubic(t);\n\n const base = cfg.radiusPx;\n const radius = base * (0.35 + 0.95 * eased);\n const alpha = 1 - eased;\n\n ctx.save();\n ctx.globalAlpha = alpha;\n\n ctx.lineWidth = cfg.lineWidthPx;\n ctx.strokeStyle = cfg.color;\n ctx.fillStyle = cfg.fillColor;\n\n ctx.shadowColor = 'rgba(0, 0, 0, 0.25)';\n ctx.shadowBlur = 8;\n\n ctx.beginPath();\n ctx.arc(x, y, radius, 0, Math.PI * 2);\n ctx.stroke();\n\n ctx.shadowBlur = 0;\n\n if (type === 'double_click' || type === 'triple_click') {\n ctx.globalAlpha = 1;\n ctx.fillStyle = cfg.color;\n ctx.font = `700 ${Math.max(10, Math.round(base * 0.6))}px system-ui, -apple-system, Segoe UI, Roboto, sans-serif`;\n ctx.textAlign = 'center';\n ctx.textBaseline = 'middle';\n ctx.fillText(type === 'double_click' ? '2×' : '3×', x, y);\n } else {\n ctx.beginPath();\n ctx.arc(x, y, Math.max(2, base * 0.16), 0, Math.PI * 2);\n ctx.fill();\n }\n\n ctx.restore();\n}\n\nfunction drawArrowHead(\n ctx: OffscreenCanvasRenderingContext2D,\n x1: number,\n y1: number,\n x2: number,\n y2: number,\n size: number,\n): void {\n const dx = x2 - x1;\n const dy = y2 - y1;\n const len = Math.hypot(dx, dy);\n if (!Number.isFinite(len) || len < 1) return;\n\n const ux = dx / len;\n const uy = dy / len;\n const px = -uy;\n const py = ux;\n\n const headLen = size;\n const headWidth = size * 0.65;\n\n const backX = x2 - ux * headLen;\n const backY = y2 - uy * headLen;\n\n ctx.beginPath();\n ctx.moveTo(x2, y2);\n ctx.lineTo(backX + px * headWidth, backY + py * headWidth);\n ctx.lineTo(backX - px * headWidth, backY - py * headWidth);\n ctx.closePath();\n ctx.fill();\n}\n\nfunction drawDragPath(\n ctx: OffscreenCanvasRenderingContext2D,\n start: Point,\n end: Point,\n progress: number,\n cfg: ResolvedDragPathConfig,\n): void {\n const t = clamp(progress, 0, 1);\n const alpha = 1 - easeOutCubic(t);\n\n ctx.save();\n ctx.globalAlpha = alpha;\n\n ctx.strokeStyle = cfg.color;\n ctx.fillStyle = cfg.color;\n ctx.lineWidth = cfg.lineWidthPx;\n ctx.lineCap = 'round';\n ctx.lineJoin = 'round';\n ctx.setLineDash(cfg.dash);\n\n ctx.shadowColor = 'rgba(0, 0, 0, 0.2)';\n ctx.shadowBlur = 6;\n\n ctx.beginPath();\n ctx.moveTo(start.x, start.y);\n ctx.lineTo(end.x, end.y);\n ctx.stroke();\n\n ctx.setLineDash([]);\n ctx.shadowBlur = 0;\n\n ctx.beginPath();\n ctx.arc(start.x, start.y, cfg.startDotRadiusPx, 0, Math.PI * 2);\n ctx.fill();\n\n ctx.beginPath();\n ctx.arc(end.x, end.y, cfg.endDotRadiusPx, 0, Math.PI * 2);\n ctx.fill();\n\n drawArrowHead(ctx, start.x, start.y, end.x, end.y, cfg.arrowSizePx);\n\n ctx.restore();\n}\n\nfunction drawLabelPill(\n ctx: OffscreenCanvasRenderingContext2D,\n text: string,\n anchor: Point | null,\n alpha: number,\n cfg: ResolvedLabelsConfig,\n outputWidth: number,\n outputHeight: number,\n): void {\n ctx.save();\n ctx.globalAlpha = clamp(alpha, 0, 1);\n\n ctx.font = cfg.font;\n ctx.textAlign = 'left';\n ctx.textBaseline = 'middle';\n\n const metrics = ctx.measureText(text);\n const ascent = Number.isFinite(metrics.actualBoundingBoxAscent)\n ? metrics.actualBoundingBoxAscent\n : 10;\n const descent = Number.isFinite(metrics.actualBoundingBoxDescent)\n ? metrics.actualBoundingBoxDescent\n : 4;\n const textHeight = ascent + descent;\n const pillWidth = Math.ceil(metrics.width + cfg.paddingX * 2);\n const pillHeight = Math.ceil(textHeight + cfg.paddingY * 2);\n\n const margin = 4;\n const ax = anchor?.x ?? margin;\n const ay = anchor?.y ?? margin;\n\n let x = ax + cfg.offsetPx;\n let y = ay - pillHeight / 2;\n\n if (x + pillWidth > outputWidth - margin) x = ax - cfg.offsetPx - pillWidth;\n if (y < margin) y = ay + cfg.offsetPx;\n if (y + pillHeight > outputHeight - margin) y = outputHeight - margin - pillHeight;\n\n x = clamp(x, margin, Math.max(margin, outputWidth - margin - pillWidth));\n y = clamp(y, margin, Math.max(margin, outputHeight - margin - pillHeight));\n\n ctx.fillStyle = cfg.backgroundColor;\n ctx.strokeStyle = cfg.borderColor;\n ctx.lineWidth = 1;\n\n ctx.beginPath();\n buildRoundedRectPath(ctx, x, y, pillWidth, pillHeight, cfg.radiusPx);\n ctx.fill();\n ctx.stroke();\n\n ctx.fillStyle = cfg.textColor;\n ctx.fillText(text, x + cfg.paddingX, y + pillHeight / 2);\n\n ctx.restore();\n}\n\n// ============================================================================\n// Schema Input Normalization\n// ============================================================================\n\n/**\n * External schema input type that supports both shorthand (boolean) and full config.\n * This maps to what users pass via the MCP tool schema.\n */\ninterface SchemaEnhancedRenderingInput {\n // Global toggle (Schema allows `true` to enable all defaults)\n enabled?: boolean;\n\n // Sub-configs can be boolean (enable/disable) or object (custom config)\n clickIndicators?:\n | boolean\n | {\n enabled?: boolean;\n // Schema aliases (from tools.ts)\n color?: string;\n radius?: number; // alias for radiusPx\n animationDurationMs?: number; // alias for durationMs\n animationFrames?: number;\n animationIntervalMs?: number;\n };\n\n dragPaths?:\n | boolean\n | {\n enabled?: boolean;\n color?: string;\n lineWidth?: number; // alias for lineWidthPx\n lineDash?: number[]; // alias for dash\n arrowSize?: number; // alias for arrowSizePx\n };\n\n labels?:\n | boolean\n | {\n enabled?: boolean;\n font?: string;\n textColor?: string;\n bgColor?: string; // alias for backgroundColor\n padding?: number; // alias for paddingX/paddingY\n borderRadius?: number; // alias for radiusPx\n offset?: { x?: number; y?: number } | number; // alias for offsetPx\n };\n\n durationMs?: number; // global fallback duration for all overlays\n}\n\nfunction normalizeSchemaInput(raw: unknown): GifEnhancedRenderingConfig | undefined {\n // Handle `true` shorthand - enable with all defaults\n if (raw === true) {\n return { enabled: true };\n }\n\n // Handle `false` or falsy\n if (!raw || typeof raw !== 'object') {\n return undefined;\n }\n\n const input = raw as SchemaEnhancedRenderingInput;\n const result: GifEnhancedRenderingConfig = {};\n\n // Global enabled\n result.enabled = input.enabled ?? true; // If object passed, default to enabled\n\n // Global duration fallback\n const globalDuration = typeof input.durationMs === 'number' ? input.durationMs : undefined;\n\n // Normalize clickIndicators\n if (input.clickIndicators === false) {\n result.clickIndicators = { enabled: false };\n } else if (input.clickIndicators === true) {\n result.clickIndicators = { enabled: true };\n } else if (typeof input.clickIndicators === 'object') {\n const ci = input.clickIndicators;\n result.clickIndicators = {\n enabled: ci.enabled ?? true,\n color: ci.color,\n radiusPx: ci.radius,\n durationMs: ci.animationDurationMs ?? globalDuration,\n animationFrames: ci.animationFrames,\n animationIntervalMs: ci.animationIntervalMs,\n };\n }\n\n // Normalize dragPaths\n if (input.dragPaths === false) {\n result.dragPaths = { enabled: false };\n } else if (input.dragPaths === true) {\n result.dragPaths = { enabled: true };\n } else if (typeof input.dragPaths === 'object') {\n const dp = input.dragPaths;\n result.dragPaths = {\n enabled: dp.enabled ?? true,\n color: dp.color,\n lineWidthPx: dp.lineWidth,\n dash: dp.lineDash,\n arrowSizePx: dp.arrowSize,\n durationMs: globalDuration,\n };\n }\n\n // Normalize labels\n if (input.labels === false) {\n result.labels = { enabled: false };\n } else if (input.labels === true) {\n result.labels = { enabled: true };\n } else if (typeof input.labels === 'object') {\n const lb = input.labels;\n const offset = lb.offset;\n const offsetPx =\n typeof offset === 'number' ? offset : typeof offset === 'object' ? offset.x : undefined;\n result.labels = {\n enabled: lb.enabled ?? true,\n font: lb.font,\n textColor: lb.textColor,\n backgroundColor: lb.bgColor,\n paddingX: typeof lb.padding === 'number' ? lb.padding : undefined,\n paddingY: typeof lb.padding === 'number' ? lb.padding : undefined,\n radiusPx: lb.borderRadius,\n offsetPx,\n durationMs: globalDuration,\n };\n }\n\n return result;\n}\n\n// ============================================================================\n// Config Resolution\n// ============================================================================\n\nexport function resolveGifEnhancedRenderingConfig(\n input?: GifEnhancedRenderingConfig | unknown,\n): ResolvedGifEnhancedRenderingConfig {\n // Normalize schema input (handles `true`, boolean sub-configs, field aliases)\n const normalized = normalizeSchemaInput(input) ?? (input as GifEnhancedRenderingConfig);\n const enabled = normalized?.enabled ?? false;\n\n const clickIntervalMs = normalizePositiveInt(\n normalized?.clickIndicators?.animationIntervalMs,\n 80,\n 20,\n 500,\n );\n const clickDelayCsFallback = Math.max(1, Math.round(clickIntervalMs / 10));\n\n return {\n enabled,\n clickIndicators: {\n enabled: normalized?.clickIndicators?.enabled ?? true,\n color: normalized?.clickIndicators?.color ?? '#FF6A00',\n fillColor: normalized?.clickIndicators?.fillColor ?? 'rgba(255, 106, 0, 0.18)',\n radiusPx: normalizePositiveNumber(normalized?.clickIndicators?.radiusPx, 18, 4, 96),\n lineWidthPx: normalizePositiveNumber(normalized?.clickIndicators?.lineWidthPx, 3, 1, 16),\n durationMs: normalizePositiveInt(normalized?.clickIndicators?.durationMs, 520, 120, 5000),\n animationFrames: normalizePositiveInt(normalized?.clickIndicators?.animationFrames, 3, 1, 8),\n animationIntervalMs: clickIntervalMs,\n animationFrameDelayCs: normalizePositiveInt(\n normalized?.clickIndicators?.animationFrameDelayCs,\n clickDelayCsFallback,\n 1,\n 100,\n ),\n },\n dragPaths: {\n enabled: normalized?.dragPaths?.enabled ?? true,\n color: normalized?.dragPaths?.color ?? '#FF2D55',\n lineWidthPx: normalizePositiveNumber(normalized?.dragPaths?.lineWidthPx, 4, 1, 20),\n durationMs: normalizePositiveInt(normalized?.dragPaths?.durationMs, 1000, 120, 8000),\n arrowSizePx: normalizePositiveNumber(normalized?.dragPaths?.arrowSizePx, 10, 4, 40),\n dash: normalizeDash(normalized?.dragPaths?.dash, [10, 8]),\n startDotRadiusPx: normalizePositiveNumber(normalized?.dragPaths?.startDotRadiusPx, 4, 2, 24),\n endDotRadiusPx: normalizePositiveNumber(normalized?.dragPaths?.endDotRadiusPx, 5, 2, 24),\n },\n labels: {\n enabled: normalized?.labels?.enabled ?? false,\n mode: normalized?.labels?.mode ?? 'both',\n showForClicks: normalized?.labels?.showForClicks ?? false,\n font:\n normalized?.labels?.font ??\n '600 13px system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif',\n maxLength: normalizePositiveInt(normalized?.labels?.maxLength, 48, 8, 200),\n durationMs: normalizePositiveInt(normalized?.labels?.durationMs, 1200, 120, 12000),\n backgroundColor: normalized?.labels?.backgroundColor ?? 'rgba(0, 0, 0, 0.72)',\n borderColor: normalized?.labels?.borderColor ?? 'rgba(255, 255, 255, 0.14)',\n textColor: normalized?.labels?.textColor ?? '#FFFFFF',\n paddingX: normalizePositiveNumber(normalized?.labels?.paddingX, 10, 2, 40),\n paddingY: normalizePositiveNumber(normalized?.labels?.paddingY, 6, 2, 30),\n radiusPx: normalizePositiveNumber(normalized?.labels?.radiusPx, 10, 0, 30),\n offsetPx: normalizePositiveNumber(normalized?.labels?.offsetPx, 12, 0, 80),\n },\n };\n}\n\n// ============================================================================\n// Capture Plan\n// ============================================================================\n\nexport function resolveCapturePlanForAction(\n config: ResolvedGifEnhancedRenderingConfig,\n action: ActionMetadata | undefined,\n defaultFrameDelayCs: number,\n): CapturePlan {\n const base: CapturePlan = { frames: 1, intervalMs: 0, delayCs: defaultFrameDelayCs };\n if (!config.enabled || !action) return base;\n\n if (config.clickIndicators.enabled && CLICK_ACTIONS.includes(action.type)) {\n const frames = config.clickIndicators.animationFrames;\n if (frames > 1) {\n return {\n frames,\n intervalMs: config.clickIndicators.animationIntervalMs,\n delayCs: config.clickIndicators.animationFrameDelayCs,\n };\n }\n }\n\n return base;\n}\n\n// ============================================================================\n// Main Render Function\n// ============================================================================\n\nexport function renderGifEnhancedOverlays(params: RenderGifEnhancedOverlaysParams): void {\n const { ctx, outputWidth, outputHeight, viewportWidth, viewportHeight, nowMs, events, config } =\n params;\n\n if (!config.enabled || events.length === 0) return;\n\n const clickCfg = config.clickIndicators;\n const dragCfg = config.dragPaths;\n const labelCfg = config.labels;\n\n for (const event of events) {\n const ageMs = nowMs - event.atMs;\n if (!Number.isFinite(ageMs) || ageMs < 0) continue;\n\n const action = event.action;\n\n if (clickCfg.enabled && CLICK_ACTIONS.includes(action.type)) {\n const anchor = resolveAnchorPoint(action);\n if (anchor) {\n const p = projectPoint(anchor, viewportWidth, viewportHeight, outputWidth, outputHeight);\n if (p)\n drawClickIndicator(ctx, p.x, p.y, ageMs / clickCfg.durationMs, action.type, clickCfg);\n }\n }\n\n if (dragCfg.enabled && action.type === 'drag') {\n const start = action.startCoordinates || null;\n const end = action.endCoordinates || action.coordinates || null;\n if (start && end) {\n const p1 = projectPoint(start, viewportWidth, viewportHeight, outputWidth, outputHeight);\n const p2 = projectPoint(end, viewportWidth, viewportHeight, outputWidth, outputHeight);\n if (p1 && p2) drawDragPath(ctx, p1, p2, ageMs / dragCfg.durationMs, dragCfg);\n }\n }\n\n // Render labels: always show annotation actions, respect labelCfg.enabled for other actions\n const isAnnotation = action.type === 'annotation' || typeof action.label === 'string';\n const shouldRenderLabel = labelCfg.enabled || isAnnotation;\n\n if (shouldRenderLabel) {\n const text = resolveActionLabel(action, labelCfg);\n if (text) {\n const anchor = resolveAnchorPoint(action);\n const p = anchor\n ? projectPoint(anchor, viewportWidth, viewportHeight, outputWidth, outputHeight)\n : null;\n\n const t = clamp(ageMs / labelCfg.durationMs, 0, 1);\n const alpha = 1 - clamp((t - 0.75) / 0.25, 0, 1);\n\n drawLabelPill(ctx, text, p, alpha, labelCfg, outputWidth, outputHeight);\n }\n }\n }\n}\n\n// ============================================================================\n// Event Pruning\n// ============================================================================\n\nexport function pruneActionEventsInPlace(\n events: ActionEvent[],\n nowMs: number,\n config: ResolvedGifEnhancedRenderingConfig,\n): void {\n if (events.length === 0) return;\n\n // Check if any events have annotations (which are always rendered)\n const hasAnnotations = events.some(\n (e) => e.action.type === 'annotation' || typeof e.action.label === 'string',\n );\n\n let maxLifetimeMs = 0;\n if (config.enabled) {\n if (config.clickIndicators.enabled)\n maxLifetimeMs = Math.max(maxLifetimeMs, config.clickIndicators.durationMs);\n if (config.dragPaths.enabled)\n maxLifetimeMs = Math.max(maxLifetimeMs, config.dragPaths.durationMs);\n if (config.labels.enabled) maxLifetimeMs = Math.max(maxLifetimeMs, config.labels.durationMs);\n }\n\n // Always account for label duration if there are annotations (they're always rendered)\n if (hasAnnotations) {\n maxLifetimeMs = Math.max(maxLifetimeMs, config.labels.durationMs);\n }\n\n if (maxLifetimeMs <= 0) {\n events.length = 0;\n return;\n }\n\n const cutoff = nowMs - maxLifetimeMs - 250;\n let dropCount = 0;\n while (dropCount < events.length && events[dropCount].atMs < cutoff) dropCount++;\n if (dropCount > 0) events.splice(0, dropCount);\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/gif-recorder.ts", "content": "/**\n * GIF Recorder Tool\n *\n * Records browser tab activity as an animated GIF.\n *\n * Features:\n * - Two recording modes:\n * 1. Fixed FPS mode (start): Captures frames at regular intervals\n * 2. Auto-capture mode (auto_start): Captures frames on tool actions\n * - Configurable frame rate, duration, and dimensions\n * - Quality/size optimization options\n * - CDP-based screenshot capture for background recording\n * - Offscreen document encoding via gifenc\n */\n\nimport { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport {\n MessageTarget,\n OFFSCREEN_MESSAGE_TYPES,\n OffscreenMessageType,\n} from '@/common/message-types';\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\nimport { offscreenManager } from '@/utils/offscreen-manager';\nimport { createImageBitmapFromUrl } from '@/utils/image-utils';\nimport {\n startAutoCapture,\n stopAutoCapture,\n isAutoCaptureActive,\n getAutoCaptureStatus,\n captureFrameOnAction,\n captureInitialFrame,\n type ActionMetadata,\n type GifEnhancedRenderingConfig,\n} from './gif-auto-capture';\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst DEFAULT_FPS = 5;\nconst DEFAULT_DURATION_MS = 5000;\nconst DEFAULT_MAX_FRAMES = 50;\nconst DEFAULT_WIDTH = 800;\nconst DEFAULT_HEIGHT = 600;\nconst DEFAULT_MAX_COLORS = 256;\nconst CDP_SESSION_KEY = 'gif-recorder';\n\n// ============================================================================\n// Types\n// ============================================================================\n\ntype GifRecorderAction =\n | 'start'\n | 'stop'\n | 'status'\n | 'auto_start'\n | 'capture'\n | 'clear'\n | 'export';\n\ninterface GifRecorderParams {\n action: GifRecorderAction;\n tabId?: number;\n fps?: number;\n durationMs?: number;\n maxFrames?: number;\n width?: number;\n height?: number;\n maxColors?: number;\n filename?: string;\n // Auto-capture mode specific\n captureDelayMs?: number;\n frameDelayCs?: number;\n enhancedRendering?: GifEnhancedRenderingConfig;\n // Manual annotation for action=\"capture\"\n annotation?: string;\n // Export action specific\n download?: boolean; // true to download, false to upload via drag&drop\n coordinates?: { x: number; y: number }; // target position for drag&drop upload\n ref?: string; // element ref for drag&drop upload (alternative to coordinates)\n selector?: string; // CSS selector for drag&drop upload (alternative to coordinates)\n}\n\ninterface RecordingState {\n isRecording: boolean;\n isStopping: boolean;\n tabId: number;\n width: number;\n height: number;\n fps: number;\n durationMs: number;\n frameIntervalMs: number;\n frameDelayCs: number;\n maxFrames: number;\n maxColors: number;\n frameCount: number;\n startTime: number;\n captureTimer: ReturnType | null;\n captureInProgress: Promise | null;\n canvas: OffscreenCanvas;\n ctx: OffscreenCanvasRenderingContext2D;\n filename?: string;\n}\n\ninterface GifResult {\n success: boolean;\n action: GifRecorderAction;\n tabId?: number;\n frameCount?: number;\n durationMs?: number;\n byteLength?: number;\n downloadId?: number;\n filename?: string;\n fullPath?: string;\n isRecording?: boolean;\n mode?: 'fixed_fps' | 'auto_capture';\n actionsCount?: number;\n error?: string;\n // Clear action specific\n clearedAutoCapture?: boolean;\n clearedFixedFps?: boolean;\n clearedCache?: boolean;\n // Export action specific (drag&drop upload)\n uploadTarget?: {\n x: number;\n y: number;\n tagName?: string;\n id?: string;\n };\n}\n\n// ============================================================================\n// Recording State Management\n// ============================================================================\n\nlet recordingState: RecordingState | null = null;\nlet stopPromise: Promise | null = null;\n\n// Auto-capture mode state\ninterface AutoCaptureMetadata {\n tabId: number;\n filename?: string;\n}\nlet autoCaptureMetadata: AutoCaptureMetadata | null = null;\n\n// Last recorded GIF cache for export\ninterface ExportableGif {\n gifData: Uint8Array;\n width: number;\n height: number;\n frameCount: number;\n durationMs: number;\n tabId: number;\n filename?: string;\n actionsCount?: number;\n mode: 'fixed_fps' | 'auto_capture';\n createdAt: number;\n}\nlet lastRecordedGif: ExportableGif | null = null;\n\n// Maximum cache lifetime for exportable GIF (5 minutes)\nconst EXPORT_CACHE_LIFETIME_MS = 5 * 60 * 1000;\n\n// ============================================================================\n// Offscreen Document Communication\n// ============================================================================\n\ntype OffscreenResponseBase = { success: boolean; error?: string };\n\nasync function sendToOffscreen(\n type: OffscreenMessageType,\n payload: Record = {},\n): Promise {\n await offscreenManager.ensureOffscreenDocument();\n\n let lastError: unknown;\n for (let attempt = 1; attempt <= 3; attempt++) {\n try {\n const response = (await chrome.runtime.sendMessage({\n target: MessageTarget.Offscreen,\n type,\n ...payload,\n })) as TResponse | undefined;\n\n if (!response) {\n throw new Error('No response received from offscreen document');\n }\n if (!response.success) {\n throw new Error(response.error || 'Unknown offscreen error');\n }\n\n return response;\n } catch (error) {\n lastError = error;\n if (attempt < 3) {\n await new Promise((resolve) => setTimeout(resolve, 50 * attempt));\n continue;\n }\n throw error;\n }\n }\n\n throw lastError instanceof Error ? lastError : new Error(String(lastError));\n}\n\n// ============================================================================\n// Frame Capture\n// ============================================================================\n\nasync function captureFrame(\n tabId: number,\n width: number,\n height: number,\n ctx: OffscreenCanvasRenderingContext2D,\n): Promise {\n // Get viewport metrics\n const metrics: { layoutViewport?: { clientWidth: number; clientHeight: number } } =\n await cdpSessionManager.sendCommand(tabId, 'Page.getLayoutMetrics', {});\n\n const viewportWidth = metrics.layoutViewport?.clientWidth || width;\n const viewportHeight = metrics.layoutViewport?.clientHeight || height;\n\n // Capture screenshot\n const screenshot: { data: string } = await cdpSessionManager.sendCommand(\n tabId,\n 'Page.captureScreenshot',\n {\n format: 'png',\n clip: {\n x: 0,\n y: 0,\n width: viewportWidth,\n height: viewportHeight,\n scale: 1,\n },\n },\n );\n\n const imageBitmap = await createImageBitmapFromUrl(`data:image/png;base64,${screenshot.data}`);\n\n // Scale image to target dimensions\n ctx.clearRect(0, 0, width, height);\n ctx.drawImage(imageBitmap, 0, 0, width, height);\n imageBitmap.close();\n\n const imageData = ctx.getImageData(0, 0, width, height);\n return imageData.data;\n}\n\nasync function captureAndEncodeFrame(state: RecordingState): Promise {\n const frameData = await captureFrame(state.tabId, state.width, state.height, state.ctx);\n\n await sendToOffscreen(OFFSCREEN_MESSAGE_TYPES.GIF_ADD_FRAME, {\n imageData: Array.from(frameData),\n width: state.width,\n height: state.height,\n delay: state.frameDelayCs,\n maxColors: state.maxColors,\n });\n\n if (recordingState === state && state.isRecording && !state.isStopping) {\n state.frameCount += 1;\n }\n}\n\nasync function captureTick(state: RecordingState): Promise {\n if (recordingState !== state || !state.isRecording || state.isStopping) {\n return;\n }\n\n const elapsed = Date.now() - state.startTime;\n if (elapsed >= state.durationMs || state.frameCount >= state.maxFrames) {\n await stopRecording();\n return;\n }\n\n const startedAt = Date.now();\n state.captureInProgress = captureAndEncodeFrame(state);\n\n try {\n await state.captureInProgress;\n } catch (error) {\n console.error('Frame capture error:', error);\n } finally {\n if (recordingState === state) {\n state.captureInProgress = null;\n }\n }\n\n if (recordingState !== state || !state.isRecording || state.isStopping) {\n return;\n }\n\n const elapsedAfter = Date.now() - state.startTime;\n if (elapsedAfter >= state.durationMs || state.frameCount >= state.maxFrames) {\n await stopRecording();\n return;\n }\n\n const delayMs = Math.max(0, state.frameIntervalMs - (Date.now() - startedAt));\n state.captureTimer = setTimeout(() => {\n void captureTick(state).catch((error) => {\n console.error('GIF recorder tick error:', error);\n });\n }, delayMs);\n}\n\n// ============================================================================\n// Recording Control\n// ============================================================================\n\nasync function startRecording(\n tabId: number,\n fps: number,\n durationMs: number,\n maxFrames: number,\n width: number,\n height: number,\n maxColors: number,\n filename?: string,\n): Promise {\n if (stopPromise || recordingState?.isRecording || recordingState?.isStopping) {\n return {\n success: false,\n action: 'start',\n error: 'Recording already in progress',\n };\n }\n\n try {\n await cdpSessionManager.attach(tabId, CDP_SESSION_KEY);\n } catch (error) {\n return {\n success: false,\n action: 'start',\n error: error instanceof Error ? error.message : String(error),\n };\n }\n\n try {\n await sendToOffscreen(OFFSCREEN_MESSAGE_TYPES.GIF_RESET, {});\n\n if (typeof OffscreenCanvas === 'undefined') {\n throw new Error('OffscreenCanvas not available in this context');\n }\n\n const canvas = new OffscreenCanvas(width, height);\n const ctx = canvas.getContext('2d');\n if (!ctx) {\n throw new Error('Failed to get canvas context');\n }\n\n const frameIntervalMs = Math.round(1000 / fps);\n const frameDelayCs = Math.max(1, Math.round(100 / fps));\n\n const state: RecordingState = {\n isRecording: true,\n isStopping: false,\n tabId,\n width,\n height,\n fps,\n durationMs,\n frameIntervalMs,\n frameDelayCs,\n maxFrames,\n maxColors,\n frameCount: 0,\n startTime: Date.now(),\n captureTimer: null,\n captureInProgress: null,\n canvas,\n ctx,\n filename,\n };\n\n recordingState = state;\n\n // Capture first frame eagerly so start() fails fast if capture/encoding is broken\n await captureAndEncodeFrame(state);\n\n state.captureTimer = setTimeout(() => {\n void captureTick(state).catch((error) => {\n console.error('GIF recorder tick error:', error);\n });\n }, frameIntervalMs);\n\n return {\n success: true,\n action: 'start',\n tabId,\n isRecording: true,\n };\n } catch (error) {\n recordingState = null;\n try {\n await cdpSessionManager.detach(tabId, CDP_SESSION_KEY);\n } catch {\n // ignore\n }\n return {\n success: false,\n action: 'start',\n error: error instanceof Error ? error.message : String(error),\n };\n }\n}\n\nasync function stopRecording(): Promise {\n if (stopPromise) {\n return stopPromise;\n }\n\n if (!recordingState || (!recordingState.isRecording && !recordingState.isStopping)) {\n return {\n success: false,\n action: 'stop',\n error: 'No recording in progress',\n };\n }\n\n stopPromise = (async () => {\n const state = recordingState!;\n const tabId = state.tabId;\n\n // Stop capture timer\n if (state.captureTimer) {\n clearTimeout(state.captureTimer);\n state.captureTimer = null;\n }\n\n state.isStopping = true;\n state.isRecording = false;\n\n try {\n await state.captureInProgress;\n } catch {\n // ignore\n }\n\n // Best-effort final frame capture to preserve end state\n try {\n const frameData = await captureFrame(state.tabId, state.width, state.height, state.ctx);\n await sendToOffscreen(OFFSCREEN_MESSAGE_TYPES.GIF_ADD_FRAME, {\n imageData: Array.from(frameData),\n width: state.width,\n height: state.height,\n delay: state.frameDelayCs,\n maxColors: state.maxColors,\n });\n state.frameCount += 1;\n } catch (error) {\n console.warn('GIF recorder: Final frame capture error (non-fatal):', error);\n }\n\n const frameCount = state.frameCount;\n const durationMs = Date.now() - state.startTime;\n const filename = state.filename;\n\n try {\n if (frameCount <= 0) {\n try {\n await sendToOffscreen(OFFSCREEN_MESSAGE_TYPES.GIF_RESET, {});\n } catch {\n // ignore\n }\n return {\n success: false,\n action: 'stop' as const,\n tabId,\n frameCount,\n durationMs,\n error: 'No frames captured',\n };\n }\n\n const response = await sendToOffscreen<{\n success: boolean;\n gifData?: number[];\n byteLength?: number;\n }>(OFFSCREEN_MESSAGE_TYPES.GIF_FINISH, {});\n\n if (!response.gifData || response.gifData.length === 0) {\n return {\n success: false,\n action: 'stop' as const,\n tabId,\n frameCount,\n durationMs,\n error: 'No frames captured',\n };\n }\n\n // Convert to Uint8Array and create blob\n const gifBytes = new Uint8Array(response.gifData);\n\n // Cache for later export\n lastRecordedGif = {\n gifData: gifBytes,\n width: state.width,\n height: state.height,\n frameCount,\n durationMs,\n tabId,\n filename,\n mode: 'fixed_fps',\n createdAt: Date.now(),\n };\n\n const blob = new Blob([gifBytes], { type: 'image/gif' });\n const dataUrl = await blobToDataUrl(blob);\n\n // Save GIF file\n const timestamp = new Date().toISOString().replace(/[:.]/g, '-');\n const outputFilename = filename?.replace(/[^a-z0-9_-]/gi, '_') || `recording_${timestamp}`;\n const fullFilename = outputFilename.endsWith('.gif')\n ? outputFilename\n : `${outputFilename}.gif`;\n\n const downloadId = await chrome.downloads.download({\n url: dataUrl,\n filename: fullFilename,\n saveAs: false,\n });\n\n // Wait briefly to get download info\n await new Promise((resolve) => setTimeout(resolve, 100));\n\n let fullPath: string | undefined;\n try {\n const [downloadItem] = await chrome.downloads.search({ id: downloadId });\n fullPath = downloadItem?.filename;\n } catch {\n // Ignore path lookup errors\n }\n\n return {\n success: true,\n action: 'stop' as const,\n tabId,\n frameCount,\n durationMs,\n byteLength: response.byteLength ?? gifBytes.byteLength,\n downloadId,\n filename: fullFilename,\n fullPath,\n };\n } catch (error) {\n return {\n success: false,\n action: 'stop' as const,\n error: error instanceof Error ? error.message : String(error),\n };\n } finally {\n try {\n await cdpSessionManager.detach(tabId, CDP_SESSION_KEY);\n } catch {\n // ignore\n }\n recordingState = null;\n }\n })();\n\n return await stopPromise.finally(() => {\n stopPromise = null;\n });\n}\n\nfunction getRecordingStatus(): GifResult {\n if (!recordingState) {\n return {\n success: true,\n action: 'status',\n isRecording: false,\n };\n }\n\n return {\n success: true,\n action: 'status',\n isRecording: recordingState.isRecording,\n tabId: recordingState.tabId,\n frameCount: recordingState.frameCount,\n durationMs: Date.now() - recordingState.startTime,\n };\n}\n\n// ============================================================================\n// Utilities\n// ============================================================================\n\nfunction blobToDataUrl(blob: Blob): Promise {\n return new Promise((resolve, reject) => {\n const reader = new FileReader();\n reader.onload = () => resolve(reader.result as string);\n reader.onerror = () => reject(new Error('Failed to read blob'));\n reader.readAsDataURL(blob);\n });\n}\n\nfunction normalizePositiveInt(value: unknown, fallback: number, max?: number): number {\n if (typeof value !== 'number' || !Number.isFinite(value)) {\n return fallback;\n }\n const result = Math.max(1, Math.floor(value));\n return max !== undefined ? Math.min(result, max) : result;\n}\n\n// ============================================================================\n// Tool Implementation\n// ============================================================================\n\nclass GifRecorderTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.GIF_RECORDER;\n\n async execute(args: GifRecorderParams): Promise {\n const action = args.action;\n const validActions = ['start', 'stop', 'status', 'auto_start', 'capture', 'clear', 'export'];\n\n if (!action || !validActions.includes(action)) {\n return createErrorResponse(\n `Parameter [action] is required and must be one of: ${validActions.join(', ')}`,\n );\n }\n\n try {\n switch (action) {\n case 'start': {\n // Fixed-FPS mode: captures frames at regular intervals\n const tab = await this.resolveTargetTab(args.tabId);\n if (!tab?.id) {\n return createErrorResponse(\n typeof args.tabId === 'number'\n ? `Tab not found: ${args.tabId}`\n : 'No active tab found',\n );\n }\n\n if (this.isRestrictedUrl(tab.url)) {\n return createErrorResponse(\n 'Cannot record special browser pages or web store pages due to security restrictions.',\n );\n }\n\n // Check if auto-capture is active\n if (isAutoCaptureActive(tab.id)) {\n return createErrorResponse(\n 'Auto-capture mode is active for this tab. Use action=\"stop\" to stop it first.',\n );\n }\n\n const fps = normalizePositiveInt(args.fps, DEFAULT_FPS, 30);\n const durationMs = normalizePositiveInt(args.durationMs, DEFAULT_DURATION_MS, 60000);\n const maxFrames = normalizePositiveInt(args.maxFrames, DEFAULT_MAX_FRAMES, 300);\n const width = normalizePositiveInt(args.width, DEFAULT_WIDTH, 1920);\n const height = normalizePositiveInt(args.height, DEFAULT_HEIGHT, 1080);\n const maxColors = normalizePositiveInt(args.maxColors, DEFAULT_MAX_COLORS, 256);\n\n const result = await startRecording(\n tab.id,\n fps,\n durationMs,\n maxFrames,\n width,\n height,\n maxColors,\n args.filename,\n );\n\n if (result.success) {\n result.mode = 'fixed_fps';\n }\n\n return this.buildResponse(result);\n }\n\n case 'auto_start': {\n // Auto-capture mode: captures frames when tools succeed\n const tab = await this.resolveTargetTab(args.tabId);\n if (!tab?.id) {\n return createErrorResponse(\n typeof args.tabId === 'number'\n ? `Tab not found: ${args.tabId}`\n : 'No active tab found',\n );\n }\n\n if (this.isRestrictedUrl(tab.url)) {\n return createErrorResponse(\n 'Cannot record special browser pages or web store pages due to security restrictions.',\n );\n }\n\n // Check if fixed-FPS recording is active\n if (recordingState?.isRecording && recordingState.tabId === tab.id) {\n return createErrorResponse(\n 'Fixed-FPS recording is active for this tab. Use action=\"stop\" to stop it first.',\n );\n }\n\n // Check if auto-capture is already active\n if (isAutoCaptureActive(tab.id)) {\n return createErrorResponse('Auto-capture is already active for this tab.');\n }\n\n const width = normalizePositiveInt(args.width, DEFAULT_WIDTH, 1920);\n const height = normalizePositiveInt(args.height, DEFAULT_HEIGHT, 1080);\n const maxColors = normalizePositiveInt(args.maxColors, DEFAULT_MAX_COLORS, 256);\n const maxFrames = normalizePositiveInt(args.maxFrames, 100, 300);\n const captureDelayMs = normalizePositiveInt(args.captureDelayMs, 150, 2000);\n const frameDelayCs = normalizePositiveInt(args.frameDelayCs, 20, 100);\n\n const startResult = await startAutoCapture(tab.id, {\n width,\n height,\n maxColors,\n maxFrames,\n captureDelayMs,\n frameDelayCs,\n enhancedRendering: args.enhancedRendering,\n });\n\n if (!startResult.success) {\n return this.buildResponse({\n success: false,\n action: 'auto_start',\n tabId: tab.id,\n error: startResult.error,\n });\n }\n\n // Store metadata for stop\n autoCaptureMetadata = {\n tabId: tab.id,\n filename: args.filename,\n };\n\n // Capture initial frame\n await captureInitialFrame(tab.id);\n\n return this.buildResponse({\n success: true,\n action: 'auto_start',\n tabId: tab.id,\n mode: 'auto_capture',\n isRecording: true,\n });\n }\n\n case 'capture': {\n // Manual frame capture in auto mode\n const tab = await this.resolveTargetTab(args.tabId);\n if (!tab?.id) {\n return createErrorResponse(\n typeof args.tabId === 'number'\n ? `Tab not found: ${args.tabId}`\n : 'No active tab found',\n );\n }\n\n if (!isAutoCaptureActive(tab.id)) {\n return createErrorResponse(\n 'Auto-capture is not active for this tab. Use action=\"auto_start\" first.',\n );\n }\n\n // Support optional annotation for manual captures\n const annotation =\n typeof args.annotation === 'string' && args.annotation.trim().length > 0\n ? args.annotation.trim()\n : undefined;\n\n const action: ActionMetadata | undefined = annotation\n ? { type: 'annotation', label: annotation }\n : undefined;\n\n const captureResult = await captureFrameOnAction(tab.id, action, true);\n\n return this.buildResponse({\n success: captureResult.success,\n action: 'capture',\n tabId: tab.id,\n frameCount: captureResult.frameNumber,\n error: captureResult.error,\n });\n }\n\n case 'stop': {\n // Stop either mode\n // Check auto-capture first\n const autoTab = autoCaptureMetadata?.tabId;\n if (autoTab !== undefined && isAutoCaptureActive(autoTab)) {\n const stopResult = await stopAutoCapture(autoTab);\n const filename = autoCaptureMetadata?.filename;\n autoCaptureMetadata = null;\n\n if (!stopResult.success || !stopResult.gifData) {\n return this.buildResponse({\n success: false,\n action: 'stop',\n tabId: autoTab,\n mode: 'auto_capture',\n frameCount: stopResult.frameCount,\n durationMs: stopResult.durationMs,\n actionsCount: stopResult.actions?.length,\n error: stopResult.error || 'No GIF data generated',\n });\n }\n\n // Cache for later export\n lastRecordedGif = {\n gifData: stopResult.gifData,\n width: DEFAULT_WIDTH, // auto mode uses default dimensions\n height: DEFAULT_HEIGHT,\n frameCount: stopResult.frameCount ?? 0,\n durationMs: stopResult.durationMs ?? 0,\n tabId: autoTab,\n filename,\n actionsCount: stopResult.actions?.length,\n mode: 'auto_capture',\n createdAt: Date.now(),\n };\n\n // Save GIF file\n const blob = new Blob([stopResult.gifData], { type: 'image/gif' });\n const dataUrl = await blobToDataUrl(blob);\n\n const timestamp = new Date().toISOString().replace(/[:.]/g, '-');\n const outputFilename =\n filename?.replace(/[^a-z0-9_-]/gi, '_') || `recording_${timestamp}`;\n const fullFilename = outputFilename.endsWith('.gif')\n ? outputFilename\n : `${outputFilename}.gif`;\n\n const downloadId = await chrome.downloads.download({\n url: dataUrl,\n filename: fullFilename,\n saveAs: false,\n });\n\n await new Promise((resolve) => setTimeout(resolve, 100));\n\n let fullPath: string | undefined;\n try {\n const [downloadItem] = await chrome.downloads.search({ id: downloadId });\n fullPath = downloadItem?.filename;\n } catch {\n // Ignore\n }\n\n return this.buildResponse({\n success: true,\n action: 'stop',\n tabId: autoTab,\n mode: 'auto_capture',\n frameCount: stopResult.frameCount,\n durationMs: stopResult.durationMs,\n byteLength: stopResult.gifData.byteLength,\n actionsCount: stopResult.actions?.length,\n downloadId,\n filename: fullFilename,\n fullPath,\n });\n }\n\n // Fall back to fixed-FPS stop\n const result = await stopRecording();\n if (result.success) {\n result.mode = 'fixed_fps';\n }\n return this.buildResponse(result);\n }\n\n case 'status': {\n // Check auto-capture status first\n const autoTab = autoCaptureMetadata?.tabId;\n if (autoTab !== undefined && isAutoCaptureActive(autoTab)) {\n const status = getAutoCaptureStatus(autoTab);\n return this.buildResponse({\n success: true,\n action: 'status',\n tabId: autoTab,\n isRecording: status.active,\n mode: 'auto_capture',\n frameCount: status.frameCount,\n durationMs: status.durationMs,\n actionsCount: status.actionsCount,\n });\n }\n\n // Fall back to fixed-FPS status\n const result = getRecordingStatus();\n if (result.isRecording) {\n result.mode = 'fixed_fps';\n }\n return this.buildResponse(result);\n }\n\n case 'clear': {\n // Clear all recording state and cached GIF\n let clearedAuto = false;\n let clearedFixedFps = false;\n let clearedCache = false;\n\n // Stop auto-capture if active\n const autoTab = autoCaptureMetadata?.tabId;\n if (autoTab !== undefined && isAutoCaptureActive(autoTab)) {\n await stopAutoCapture(autoTab);\n autoCaptureMetadata = null;\n clearedAuto = true;\n }\n\n // Stop fixed-FPS recording if active or stopping\n if (recordingState) {\n // Cancel timer and cleanup without waiting for finish\n if (recordingState.captureTimer) {\n clearTimeout(recordingState.captureTimer);\n recordingState.captureTimer = null;\n }\n try {\n await recordingState.captureInProgress;\n } catch {\n // ignore\n }\n try {\n await cdpSessionManager.detach(recordingState.tabId, CDP_SESSION_KEY);\n } catch {\n // ignore\n }\n const wasRecording = recordingState.isRecording || recordingState.isStopping;\n recordingState = null;\n stopPromise = null; // Clear any pending stop promise\n if (wasRecording) {\n clearedFixedFps = true;\n }\n }\n\n // Reset offscreen encoder\n try {\n await sendToOffscreen(OFFSCREEN_MESSAGE_TYPES.GIF_RESET, {});\n } catch {\n // ignore\n }\n\n // Clear cached GIF\n if (lastRecordedGif) {\n lastRecordedGif = null;\n clearedCache = true;\n }\n\n return this.buildResponse({\n success: true,\n action: 'clear',\n clearedAutoCapture: clearedAuto,\n clearedFixedFps,\n clearedCache,\n } as GifResult);\n }\n\n case 'export': {\n // Export the last recorded GIF (download or drag&drop upload)\n\n // Check if cache is valid\n if (!lastRecordedGif) {\n return createErrorResponse(\n 'No recorded GIF available for export. Use action=\"stop\" to finish a recording first.',\n );\n }\n\n // Check cache expiration\n if (Date.now() - lastRecordedGif.createdAt > EXPORT_CACHE_LIFETIME_MS) {\n lastRecordedGif = null;\n return createErrorResponse('Cached GIF has expired. Please record a new GIF.');\n }\n\n const download = args.download !== false; // Default to download\n\n if (download) {\n // Download mode\n const blob = new Blob([lastRecordedGif.gifData], { type: 'image/gif' });\n const dataUrl = await blobToDataUrl(blob);\n\n const timestamp = new Date().toISOString().replace(/[:.]/g, '-');\n const filename = args.filename ?? lastRecordedGif.filename;\n const outputFilename = filename?.replace(/[^a-z0-9_-]/gi, '_') || `export_${timestamp}`;\n const fullFilename = outputFilename.endsWith('.gif')\n ? outputFilename\n : `${outputFilename}.gif`;\n\n const downloadId = await chrome.downloads.download({\n url: dataUrl,\n filename: fullFilename,\n saveAs: false,\n });\n\n await new Promise((resolve) => setTimeout(resolve, 100));\n\n let fullPath: string | undefined;\n try {\n const [downloadItem] = await chrome.downloads.search({ id: downloadId });\n fullPath = downloadItem?.filename;\n } catch {\n // Ignore\n }\n\n return this.buildResponse({\n success: true,\n action: 'export',\n mode: lastRecordedGif.mode,\n frameCount: lastRecordedGif.frameCount,\n durationMs: lastRecordedGif.durationMs,\n byteLength: lastRecordedGif.gifData.byteLength,\n downloadId,\n filename: fullFilename,\n fullPath,\n });\n } else {\n // Drag&drop upload mode\n const { coordinates, ref, selector } = args;\n\n if (!coordinates && !ref && !selector) {\n return createErrorResponse(\n 'For drag&drop upload, provide coordinates, ref, or selector to identify the drop target.',\n );\n }\n\n // Resolve target tab\n const tab = await this.resolveTargetTab(args.tabId);\n if (!tab?.id) {\n return createErrorResponse(\n typeof args.tabId === 'number'\n ? `Tab not found: ${args.tabId}`\n : 'No active tab found',\n );\n }\n\n // Security check\n if (this.isRestrictedUrl(tab.url)) {\n return createErrorResponse(\n 'Cannot upload to special browser pages or web store pages.',\n );\n }\n\n // Prepare GIF data as base64\n const gifBase64 = btoa(\n Array.from(lastRecordedGif.gifData)\n .map((b) => String.fromCharCode(b))\n .join(''),\n );\n\n // Resolve drop target coordinates\n let targetX: number | undefined;\n let targetY: number | undefined;\n\n if (ref) {\n // Use the project's built-in ref resolution mechanism\n try {\n await this.injectContentScript(tab.id, [\n 'inject-scripts/accessibility-tree-helper.js',\n ]);\n const resolved = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.RESOLVE_REF,\n ref,\n });\n if (resolved?.success && resolved.center) {\n targetX = resolved.center.x;\n targetY = resolved.center.y;\n } else {\n return createErrorResponse(`Could not resolve ref: ${ref}`);\n }\n } catch (err) {\n return createErrorResponse(\n `Failed to resolve ref: ${err instanceof Error ? err.message : String(err)}`,\n );\n }\n } else if (selector) {\n // Use executeScript to get element center coordinates by CSS selector\n try {\n const [result] = await chrome.scripting.executeScript({\n target: { tabId: tab.id },\n func: (cssSelector: string) => {\n const el = document.querySelector(cssSelector);\n if (!el) return null;\n const rect = el.getBoundingClientRect();\n return {\n x: rect.left + rect.width / 2,\n y: rect.top + rect.height / 2,\n };\n },\n args: [selector],\n });\n\n if (result?.result) {\n targetX = result.result.x;\n targetY = result.result.y;\n } else {\n return createErrorResponse(`Could not find element: ${selector}`);\n }\n } catch (err) {\n return createErrorResponse(\n `Failed to resolve selector: ${err instanceof Error ? err.message : String(err)}`,\n );\n }\n } else if (coordinates) {\n targetX = coordinates.x;\n targetY = coordinates.y;\n }\n\n if (typeof targetX !== 'number' || typeof targetY !== 'number') {\n return createErrorResponse('Invalid drop target coordinates.');\n }\n\n // Execute drag&drop upload\n try {\n const timestamp = new Date().toISOString().replace(/[:.]/g, '-');\n const filename =\n args.filename ?? lastRecordedGif.filename ?? `recording_${timestamp}`;\n const fullFilename = filename.endsWith('.gif') ? filename : `${filename}.gif`;\n\n const [result] = await chrome.scripting.executeScript({\n target: { tabId: tab.id },\n func: (base64Data: string, x: number, y: number, fname: string) => {\n // Convert base64 to Blob\n const byteChars = atob(base64Data);\n const byteArray = new Uint8Array(byteChars.length);\n for (let i = 0; i < byteChars.length; i++) {\n byteArray[i] = byteChars.charCodeAt(i);\n }\n const blob = new Blob([byteArray], { type: 'image/gif' });\n const file = new File([blob], fname, { type: 'image/gif' });\n\n // Find drop target element\n const target = document.elementFromPoint(x, y);\n if (!target) {\n return { success: false, error: 'No element at drop coordinates' };\n }\n\n // Create DataTransfer with the file\n const dt = new DataTransfer();\n dt.items.add(file);\n\n // Dispatch drag events\n const events = ['dragenter', 'dragover', 'drop'] as const;\n for (const eventType of events) {\n const evt = new DragEvent(eventType, {\n bubbles: true,\n cancelable: true,\n dataTransfer: dt,\n clientX: x,\n clientY: y,\n });\n target.dispatchEvent(evt);\n }\n\n return {\n success: true,\n targetTagName: target.tagName,\n targetId: target.id || undefined,\n };\n },\n args: [gifBase64, targetX, targetY, fullFilename],\n });\n\n if (!result?.result?.success) {\n return createErrorResponse(result?.result?.error || 'Drag&drop upload failed');\n }\n\n return this.buildResponse({\n success: true,\n action: 'export',\n mode: lastRecordedGif.mode,\n frameCount: lastRecordedGif.frameCount,\n durationMs: lastRecordedGif.durationMs,\n byteLength: lastRecordedGif.gifData.byteLength,\n uploadTarget: {\n x: targetX,\n y: targetY,\n tagName: result.result.targetTagName,\n id: result.result.targetId,\n },\n } as GifResult);\n } catch (err) {\n return createErrorResponse(\n `Drag&drop upload failed: ${err instanceof Error ? err.message : String(err)}`,\n );\n }\n }\n }\n\n default:\n return createErrorResponse(`Unknown action: ${action}`);\n }\n } catch (error) {\n console.error('GifRecorderTool.execute error:', error);\n return createErrorResponse(\n `GIF recorder error: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n private isRestrictedUrl(url?: string): boolean {\n if (!url) return false;\n return (\n url.startsWith('chrome://') ||\n url.startsWith('edge://') ||\n url.startsWith('https://chrome.google.com/webstore') ||\n url.startsWith('https://microsoftedge.microsoft.com/')\n );\n }\n\n private async resolveTargetTab(tabId?: number): Promise {\n if (typeof tabId === 'number') {\n return this.tryGetTab(tabId);\n }\n try {\n return await this.getActiveTabOrThrow();\n } catch {\n return null;\n }\n }\n\n private buildResponse(result: GifResult): ToolResult {\n return {\n content: [{ type: 'text', text: JSON.stringify(result) }],\n isError: !result.success,\n };\n }\n}\n\nexport const gifRecorderTool = new GifRecorderTool();\n\n// Re-export auto-capture utilities for use by other tools (e.g., chrome_computer, chrome_navigate)\nexport {\n captureFrameOnAction,\n isAutoCaptureActive,\n type ActionMetadata,\n type ActionType,\n} from './gif-auto-capture';\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/history.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport {\n parseISO,\n subDays,\n subWeeks,\n subMonths,\n subYears,\n startOfToday,\n startOfYesterday,\n isValid,\n format,\n} from 'date-fns';\n\ninterface HistoryToolParams {\n text?: string;\n startTime?: string;\n endTime?: string;\n maxResults?: number;\n excludeCurrentTabs?: boolean;\n}\n\ninterface HistoryItem {\n id: string;\n url?: string;\n title?: string;\n lastVisitTime?: number; // Timestamp in milliseconds\n visitCount?: number;\n typedCount?: number;\n}\n\ninterface HistoryResult {\n items: HistoryItem[];\n totalCount: number;\n timeRange: {\n startTime: number;\n endTime: number;\n startTimeFormatted: string;\n endTimeFormatted: string;\n };\n query?: string;\n}\n\nclass HistoryTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.HISTORY;\n private static readonly ONE_DAY_MS = 24 * 60 * 60 * 1000;\n\n /**\n * Parse a date string into milliseconds since epoch.\n * Returns null if the date string is invalid.\n * Supports:\n * - ISO date strings (e.g., \"2023-10-31\", \"2023-10-31T14:30:00.000Z\")\n * - Relative times: \"1 day ago\", \"2 weeks ago\", \"3 months ago\", \"1 year ago\"\n * - Special keywords: \"now\", \"today\", \"yesterday\"\n */\n private parseDateString(dateStr: string | undefined | null): number | null {\n if (!dateStr) {\n // If an empty or null string is passed, it might mean \"no specific date\",\n // depending on how you want to treat it. Returning null is safer.\n return null;\n }\n\n const now = new Date();\n const lowerDateStr = dateStr.toLowerCase().trim();\n\n if (lowerDateStr === 'now') return now.getTime();\n if (lowerDateStr === 'today') return startOfToday().getTime();\n if (lowerDateStr === 'yesterday') return startOfYesterday().getTime();\n\n const relativeMatch = lowerDateStr.match(\n /^(\\d+)\\s+(day|days|week|weeks|month|months|year|years)\\s+ago$/,\n );\n if (relativeMatch) {\n const amount = parseInt(relativeMatch[1], 10);\n const unit = relativeMatch[2];\n let resultDate: Date;\n if (unit.startsWith('day')) resultDate = subDays(now, amount);\n else if (unit.startsWith('week')) resultDate = subWeeks(now, amount);\n else if (unit.startsWith('month')) resultDate = subMonths(now, amount);\n else if (unit.startsWith('year')) resultDate = subYears(now, amount);\n else return null; // Should not happen with the regex\n return resultDate.getTime();\n }\n\n // Try parsing as ISO or other common date string formats\n // Native Date constructor can be unreliable for non-standard formats.\n // date-fns' parseISO is good for ISO 8601.\n // For other formats, date-fns' parse function is more flexible.\n let parsedDate = parseISO(dateStr); // Handles \"2023-10-31\" or \"2023-10-31T10:00:00\"\n if (isValid(parsedDate)) {\n return parsedDate.getTime();\n }\n\n // Fallback to new Date() for other potential formats, but with caution\n parsedDate = new Date(dateStr);\n if (isValid(parsedDate) && dateStr.includes(parsedDate.getFullYear().toString())) {\n return parsedDate.getTime();\n }\n\n console.warn(`Could not parse date string: ${dateStr}`);\n return null;\n }\n\n /**\n * Format a timestamp as a human-readable date string\n */\n private formatDate(timestamp: number): string {\n // Using date-fns for consistent and potentially localized formatting\n return format(timestamp, 'yyyy-MM-dd HH:mm:ss');\n }\n\n async execute(args: HistoryToolParams): Promise {\n try {\n console.log('Executing HistoryTool with args:', args);\n\n const {\n text = '',\n maxResults = 100, // Default to 100 results\n excludeCurrentTabs = false,\n } = args;\n\n const now = Date.now();\n let startTimeMs: number;\n let endTimeMs: number;\n\n // Parse startTime\n if (args.startTime) {\n const parsedStart = this.parseDateString(args.startTime);\n if (parsedStart === null) {\n return createErrorResponse(\n `Invalid format for start time: \"${args.startTime}\". Supported formats: ISO (YYYY-MM-DD), \"today\", \"yesterday\", \"X days/weeks/months/years ago\".`,\n );\n }\n startTimeMs = parsedStart;\n } else {\n // Default to 24 hours ago if startTime is not provided\n startTimeMs = now - HistoryTool.ONE_DAY_MS;\n }\n\n // Parse endTime\n if (args.endTime) {\n const parsedEnd = this.parseDateString(args.endTime);\n if (parsedEnd === null) {\n return createErrorResponse(\n `Invalid format for end time: \"${args.endTime}\". Supported formats: ISO (YYYY-MM-DD), \"today\", \"yesterday\", \"X days/weeks/months/years ago\".`,\n );\n }\n endTimeMs = parsedEnd;\n } else {\n // Default to current time if endTime is not provided\n endTimeMs = now;\n }\n\n // Validate time range\n if (startTimeMs > endTimeMs) {\n return createErrorResponse('Start time cannot be after end time.');\n }\n\n console.log(\n `Searching history from ${this.formatDate(startTimeMs)} to ${this.formatDate(endTimeMs)} for query \"${text}\"`,\n );\n\n const historyItems = await chrome.history.search({\n text,\n startTime: startTimeMs,\n endTime: endTimeMs,\n maxResults,\n });\n\n console.log(`Found ${historyItems.length} history items before filtering current tabs.`);\n\n let filteredItems = historyItems;\n if (excludeCurrentTabs && historyItems.length > 0) {\n const currentTabs = await chrome.tabs.query({});\n const openUrls = new Set();\n\n currentTabs.forEach((tab) => {\n if (tab.url) {\n openUrls.add(tab.url);\n }\n });\n\n if (openUrls.size > 0) {\n filteredItems = historyItems.filter((item) => !(item.url && openUrls.has(item.url)));\n console.log(\n `Filtered out ${historyItems.length - filteredItems.length} items that are currently open. ${filteredItems.length} items remaining.`,\n );\n }\n }\n\n const result: HistoryResult = {\n items: filteredItems.map((item) => ({\n id: item.id,\n url: item.url,\n title: item.title,\n lastVisitTime: item.lastVisitTime,\n visitCount: item.visitCount,\n typedCount: item.typedCount,\n })),\n totalCount: filteredItems.length,\n timeRange: {\n startTime: startTimeMs,\n endTime: endTimeMs,\n startTimeFormatted: this.formatDate(startTimeMs),\n endTimeFormatted: this.formatDate(endTimeMs),\n },\n };\n\n if (text) {\n result.query = text;\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(result, null, 2),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in HistoryTool.execute:', error);\n return createErrorResponse(\n `Error retrieving browsing history: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const historyTool = new HistoryTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/index.ts", "content": "export { navigateTool, closeTabsTool, switchTabTool } from './common';\nexport { windowTool } from './window';\nexport { vectorSearchTabsContentTool as searchTabsContentTool } from './vector-search';\nexport { screenshotTool } from './screenshot';\nexport { webFetcherTool, getInteractiveElementsTool } from './web-fetcher';\nexport { clickTool, fillTool } from './interaction';\nexport { elementPickerTool } from './element-picker';\nexport { networkRequestTool } from './network-request';\nexport { networkCaptureTool } from './network-capture';\n// Legacy exports (for internal use by networkCaptureTool)\nexport { networkDebuggerStartTool, networkDebuggerStopTool } from './network-capture-debugger';\nexport { networkCaptureStartTool, networkCaptureStopTool } from './network-capture-web-request';\nexport { keyboardTool } from './keyboard';\nexport { historyTool } from './history';\nexport { bookmarkSearchTool, bookmarkAddTool, bookmarkDeleteTool } from './bookmark';\nexport { injectScriptTool, sendCommandToInjectScriptTool } from './inject-script';\nexport { javascriptTool } from './javascript';\nexport { consoleTool } from './console';\nexport { fileUploadTool } from './file-upload';\nexport { readPageTool } from './read-page';\nexport { computerTool } from './computer';\nexport { handleDialogTool } from './dialog';\nexport { handleDownloadTool } from './download';\nexport { userscriptTool } from './userscript';\nexport {\n performanceStartTraceTool,\n performanceStopTraceTool,\n performanceAnalyzeInsightTool,\n} from './performance';\nexport { gifRecorderTool } from './gif-recorder';\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/inject-script.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { ExecutionWorld } from '@/common/constants';\n\ninterface InjectScriptParam {\n url?: string;\n tabId?: number;\n windowId?: number;\n background?: boolean;\n}\ninterface ScriptConfig {\n type: ExecutionWorld;\n jsScript: string;\n}\n\ninterface SendCommandToInjectScriptToolParam {\n tabId?: number;\n eventName: string;\n payload?: string;\n}\n\nconst injectedTabs = new Map();\nclass InjectScriptTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.INJECT_SCRIPT;\n async execute(args: InjectScriptParam & ScriptConfig): Promise {\n try {\n const { url, type, jsScript, tabId, windowId, background } = args;\n let tab: chrome.tabs.Tab | undefined;\n\n if (!type || !jsScript) {\n return createErrorResponse('Param [type] and [jsScript] is required');\n }\n\n if (typeof tabId === 'number') {\n tab = await chrome.tabs.get(tabId);\n } else if (url) {\n // If URL is provided, check if it's already open\n console.log(`Checking if URL is already open: ${url}`);\n const allTabs = await chrome.tabs.query({});\n\n // Find tab with matching URL\n const matchingTabs = allTabs.filter((t) => {\n // Normalize URLs for comparison (remove trailing slashes)\n const tabUrl = t.url?.endsWith('/') ? t.url.slice(0, -1) : t.url;\n const targetUrl = url.endsWith('/') ? url.slice(0, -1) : url;\n return tabUrl === targetUrl;\n });\n\n if (matchingTabs.length > 0) {\n // Use existing tab\n tab = matchingTabs[0];\n console.log(`Found existing tab with URL: ${url}, tab ID: ${tab.id}`);\n } else {\n // Create new tab with the URL\n console.log(`No existing tab found with URL: ${url}, creating new tab`);\n tab = await chrome.tabs.create({\n url,\n active: background === true ? false : true,\n windowId,\n });\n\n // Wait for page to load\n console.log('Waiting for page to load...');\n await new Promise((resolve) => setTimeout(resolve, 3000));\n }\n } else {\n // Use active tab (prefer the specified window)\n const tabs =\n typeof windowId === 'number'\n ? await chrome.tabs.query({ active: true, windowId })\n : await chrome.tabs.query({ active: true, currentWindow: true });\n if (!tabs[0]) {\n return createErrorResponse('No active tab found');\n }\n tab = tabs[0];\n }\n\n if (!tab.id) {\n return createErrorResponse('Tab has no ID');\n }\n\n // Optionally bring tab/window to foreground based on background flag\n if (background !== true) {\n await chrome.tabs.update(tab.id, { active: true });\n await chrome.windows.update(tab.windowId, { focused: true });\n }\n\n const res = await handleInject(tab.id!, { ...args });\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(res),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in InjectScriptTool.execute:', error);\n return createErrorResponse(\n `Inject script error: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nclass SendCommandToInjectScriptTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.SEND_COMMAND_TO_INJECT_SCRIPT;\n async execute(args: SendCommandToInjectScriptToolParam): Promise {\n try {\n const { tabId, eventName, payload } = args;\n\n if (!eventName) {\n return createErrorResponse('Param [eventName] is required');\n }\n\n if (tabId) {\n const tabExists = await isTabExists(tabId);\n if (!tabExists) {\n return createErrorResponse('The tab:[tabId] is not exists');\n }\n }\n\n let finalTabId: number | undefined = tabId;\n\n if (finalTabId === undefined) {\n // Use active tab\n const tabs = await chrome.tabs.query({ active: true });\n if (!tabs[0]) {\n return createErrorResponse('No active tab found');\n }\n finalTabId = tabs[0].id;\n }\n\n if (!finalTabId) {\n return createErrorResponse('No active tab found');\n }\n\n if (!injectedTabs.has(finalTabId)) {\n throw new Error('No script injected in this tab.');\n }\n const result = await chrome.tabs.sendMessage(finalTabId, {\n action: eventName,\n payload,\n targetWorld: injectedTabs.get(finalTabId).type, // The bridge uses this to decide whether to forward to MAIN world.\n });\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(result),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in InjectScriptTool.execute:', error);\n return createErrorResponse(\n `Inject script error: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nasync function isTabExists(tabId: number) {\n try {\n await chrome.tabs.get(tabId);\n return true;\n } catch (error) {\n // An error is thrown if the tab doesn't exist.\n return false;\n }\n}\n\n/**\n * @description Handles the injection of user scripts into a specific tab.\n * @param {number} tabId - The ID of the target tab.\n * @param {object} scriptConfig - The configuration object for the script.\n */\nasync function handleInject(tabId: number, scriptConfig: ScriptConfig) {\n if (injectedTabs.has(tabId)) {\n // If already injected, run cleanup first to ensure a clean state.\n console.log(`Tab ${tabId} already has injections. Cleaning up first.`);\n await handleCleanup(tabId);\n }\n const { type, jsScript } = scriptConfig;\n const hasMain = type === ExecutionWorld.MAIN;\n\n if (hasMain) {\n // The bridge is essential for MAIN world communication and cleanup.\n await chrome.scripting.executeScript({\n target: { tabId },\n files: ['inject-scripts/inject-bridge.js'],\n world: ExecutionWorld.ISOLATED,\n });\n await chrome.scripting.executeScript({\n target: { tabId },\n func: (code) => new Function(code)(),\n args: [jsScript],\n world: ExecutionWorld.MAIN,\n });\n } else {\n await chrome.scripting.executeScript({\n target: { tabId },\n func: (code) => new Function(code)(),\n args: [jsScript],\n world: ExecutionWorld.ISOLATED,\n });\n }\n injectedTabs.set(tabId, scriptConfig);\n console.log(`Scripts successfully injected into tab ${tabId}.`);\n return { injected: true };\n}\n\n/**\n * @description Triggers the cleanup process in a specific tab.\n * @param {number} tabId - The ID of the target tab.\n */\nasync function handleCleanup(tabId: number) {\n if (!injectedTabs.has(tabId)) return;\n // Send cleanup signal. The bridge will forward it to the MAIN world.\n chrome.tabs\n .sendMessage(tabId, { type: 'chrome-mcp:cleanup' })\n .catch((err) =>\n console.warn(`Could not send cleanup message to tab ${tabId}. It might have been closed.`),\n );\n\n injectedTabs.delete(tabId);\n console.log(`Cleanup signal sent to tab ${tabId}. State cleared.`);\n}\n\nexport const injectScriptTool = new InjectScriptTool();\nexport const sendCommandToInjectScriptTool = new SendCommandToInjectScriptTool();\n\n// --- Automatic Cleanup Listeners ---\nchrome.tabs.onRemoved.addListener((tabId) => {\n if (injectedTabs.has(tabId)) {\n console.log(`Tab ${tabId} closed. Cleaning up state.`);\n injectedTabs.delete(tabId);\n }\n});\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/interaction.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { TIMEOUTS, ERROR_MESSAGES } from '@/common/constants';\n\ninterface Coordinates {\n x: number;\n y: number;\n}\n\ninterface ClickToolParams {\n selector?: string; // CSS selector or XPath for the element to click\n selectorType?: 'css' | 'xpath'; // Type of selector (default: 'css')\n ref?: string; // Element ref from accessibility tree (window.__claudeElementMap)\n coordinates?: Coordinates; // Coordinates to click at (x, y relative to viewport)\n waitForNavigation?: boolean; // Whether to wait for navigation to complete after click\n timeout?: number; // Timeout in milliseconds for waiting for the element or navigation\n frameId?: number; // Target frame for ref/selector resolution\n double?: boolean; // Perform double click when true\n button?: 'left' | 'right' | 'middle';\n bubbles?: boolean;\n cancelable?: boolean;\n modifiers?: { altKey?: boolean; ctrlKey?: boolean; metaKey?: boolean; shiftKey?: boolean };\n tabId?: number; // target existing tab id\n windowId?: number; // when no tabId, pick active tab from this window\n}\n\n/**\n * Tool for clicking elements on web pages\n */\nclass ClickTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.CLICK;\n\n /**\n * Execute click operation\n */\n async execute(args: ClickToolParams): Promise {\n const {\n selector,\n selectorType = 'css',\n coordinates,\n waitForNavigation = false,\n timeout = TIMEOUTS.DEFAULT_WAIT * 5,\n frameId,\n button,\n bubbles,\n cancelable,\n modifiers,\n } = args;\n\n console.log(`Starting click operation with options:`, args);\n\n if (!selector && !coordinates && !args.ref) {\n return createErrorResponse(\n ERROR_MESSAGES.INVALID_PARAMETERS + ': Provide ref or selector or coordinates',\n );\n }\n\n try {\n // Resolve tab\n const explicit = await this.tryGetTab(args.tabId);\n const tab = explicit || (await this.getActiveTabOrThrowInWindow(args.windowId));\n if (!tab.id) {\n return createErrorResponse(ERROR_MESSAGES.TAB_NOT_FOUND + ': Active tab has no ID');\n }\n\n let finalRef = args.ref;\n let finalSelector = selector;\n\n // If selector is XPath, convert to ref first\n if (selector && selectorType === 'xpath') {\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n try {\n const resolved = await this.sendMessageToTab(\n tab.id,\n {\n action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR,\n selector,\n isXPath: true,\n },\n frameId,\n );\n if (resolved && resolved.success && resolved.ref) {\n finalRef = resolved.ref;\n finalSelector = undefined; // Use ref instead of selector\n } else {\n return createErrorResponse(\n `Failed to resolve XPath selector: ${resolved?.error || 'unknown error'}`,\n );\n }\n } catch (error) {\n return createErrorResponse(\n `Error resolving XPath: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n await this.injectContentScript(tab.id, ['inject-scripts/click-helper.js']);\n\n // Send click message to content script\n const result = await this.sendMessageToTab(\n tab.id,\n {\n action: TOOL_MESSAGE_TYPES.CLICK_ELEMENT,\n selector: finalSelector,\n coordinates,\n ref: finalRef,\n waitForNavigation,\n timeout,\n double: args.double === true,\n button,\n bubbles,\n cancelable,\n modifiers,\n },\n frameId,\n );\n\n // Determine actual click method used\n let clickMethod: string;\n if (coordinates) {\n clickMethod = 'coordinates';\n } else if (finalRef) {\n clickMethod = 'ref';\n } else if (finalSelector) {\n clickMethod = 'selector';\n } else {\n clickMethod = 'unknown';\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: result.message || 'Click operation successful',\n elementInfo: result.elementInfo,\n navigationOccurred: result.navigationOccurred,\n clickMethod,\n }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in click operation:', error);\n return createErrorResponse(\n `Error performing click: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const clickTool = new ClickTool();\n\ninterface FillToolParams {\n selector?: string;\n selectorType?: 'css' | 'xpath'; // Type of selector (default: 'css')\n ref?: string; // Element ref from accessibility tree\n // Accept string | number | boolean for broader form input coverage\n value: string | number | boolean;\n frameId?: number;\n tabId?: number; // target existing tab id\n windowId?: number; // when no tabId, pick active tab from this window\n}\n\n/**\n * Tool for filling form elements on web pages\n */\nclass FillTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.FILL;\n\n /**\n * Execute fill operation\n */\n async execute(args: FillToolParams): Promise {\n const { selector, selectorType = 'css', ref, value, frameId } = args;\n\n console.log(`Starting fill operation with options:`, args);\n\n if (!selector && !ref) {\n return createErrorResponse(ERROR_MESSAGES.INVALID_PARAMETERS + ': Provide ref or selector');\n }\n\n if (value === undefined || value === null) {\n return createErrorResponse(ERROR_MESSAGES.INVALID_PARAMETERS + ': Value must be provided');\n }\n\n try {\n const explicit = await this.tryGetTab(args.tabId);\n const tab = explicit || (await this.getActiveTabOrThrowInWindow(args.windowId));\n if (!tab.id) {\n return createErrorResponse(ERROR_MESSAGES.TAB_NOT_FOUND + ': Active tab has no ID');\n }\n\n let finalRef = ref;\n let finalSelector = selector;\n\n // If selector is XPath, convert to ref first\n if (selector && selectorType === 'xpath') {\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n try {\n const resolved = await this.sendMessageToTab(\n tab.id,\n {\n action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR,\n selector,\n isXPath: true,\n },\n frameId,\n );\n if (resolved && resolved.success && resolved.ref) {\n finalRef = resolved.ref;\n finalSelector = undefined; // Use ref instead of selector\n } else {\n return createErrorResponse(\n `Failed to resolve XPath selector: ${resolved?.error || 'unknown error'}`,\n );\n }\n } catch (error) {\n return createErrorResponse(\n `Error resolving XPath: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n await this.injectContentScript(tab.id, ['inject-scripts/fill-helper.js']);\n\n // Send fill message to content script\n const result = await this.sendMessageToTab(\n tab.id,\n {\n action: TOOL_MESSAGE_TYPES.FILL_ELEMENT,\n selector: finalSelector,\n ref: finalRef,\n value,\n },\n frameId,\n );\n\n if (result && result.error) {\n return createErrorResponse(result.error);\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: result.message || 'Fill operation successful',\n elementInfo: result.elementInfo,\n }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in fill operation:', error);\n return createErrorResponse(\n `Error filling element: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const fillTool = new FillTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/javascript.ts", "content": "/**\n * JavaScript Tool - CDP Runtime.evaluate with fallback\n *\n * Execute JavaScript in the browser tab and return the result.\n * - Primary: CDP Runtime.evaluate (supports awaitPromise + returnByValue)\n * - Fallback: chrome.scripting.executeScript (when debugger is busy)\n *\n * Features:\n * - Async code support (top-level await via async wrapper)\n * - Output sanitization (sensitive data redaction)\n * - Output truncation (configurable max bytes)\n * - Timeout handling\n * - Detailed error classification\n */\n\nimport { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\nimport {\n DEFAULT_MAX_OUTPUT_BYTES,\n sanitizeAndLimitOutput,\n sanitizeText,\n} from '@/utils/output-sanitizer';\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst DEFAULT_TIMEOUT_MS = 15_000;\nconst CDP_SESSION_KEY = 'javascript';\n\n// ============================================================================\n// Types\n// ============================================================================\n\ntype ExecutionEngine = 'cdp' | 'scripting';\n\ntype ErrorKind =\n | 'debugger_conflict'\n | 'timeout'\n | 'syntax_error'\n | 'runtime_error'\n | 'cdp_error'\n | 'scripting_error';\n\ninterface JavaScriptToolParams {\n code: string;\n tabId?: number;\n timeoutMs?: number;\n maxOutputBytes?: number;\n}\n\ninterface ExecutionError {\n kind: ErrorKind;\n message: string;\n details?: {\n url?: string;\n lineNumber?: number;\n columnNumber?: number;\n };\n}\n\ninterface ExecutionMetrics {\n elapsedMs: number;\n}\n\ninterface JavaScriptToolResult {\n success: boolean;\n tabId: number;\n engine: ExecutionEngine;\n result?: string;\n truncated?: boolean;\n redacted?: boolean;\n warnings?: string[];\n error?: ExecutionError;\n metrics?: ExecutionMetrics;\n}\n\ninterface ExecutionOptions {\n timeoutMs: number;\n maxOutputBytes: number;\n}\n\n// Discriminated union for execution results\ntype ExecutionSuccess = {\n ok: true;\n engine: ExecutionEngine;\n output: string;\n truncated: boolean;\n redacted: boolean;\n};\n\ntype ExecutionFailure = {\n ok: false;\n engine: ExecutionEngine;\n error: ExecutionError;\n};\n\ntype ExecutionResult = ExecutionSuccess | ExecutionFailure;\n\n// ============================================================================\n// Timeout Error\n// ============================================================================\n\nclass TimeoutError extends Error {\n constructor(timeoutMs: number) {\n super(`Execution timed out after ${timeoutMs}ms`);\n this.name = 'TimeoutError';\n }\n}\n\n// ============================================================================\n// Utility Functions\n// ============================================================================\n\nfunction normalizePositiveInt(value: unknown, fallback: number): number {\n if (typeof value !== 'number' || !Number.isFinite(value)) {\n return fallback;\n }\n return Math.max(1, Math.floor(value));\n}\n\nfunction withTimeout(promise: Promise, timeoutMs: number): Promise {\n return new Promise((resolve, reject) => {\n const timer = setTimeout(() => {\n reject(new TimeoutError(timeoutMs));\n }, timeoutMs);\n\n promise\n .then(resolve)\n .catch(reject)\n .finally(() => clearTimeout(timer));\n });\n}\n\nfunction isTimeoutError(error: unknown): error is TimeoutError {\n return error instanceof Error && error.name === 'TimeoutError';\n}\n\nfunction isDebuggerConflictError(error: unknown): boolean {\n const message = error instanceof Error ? error.message : String(error);\n return /Debugger is already attached|Another debugger is already attached|Cannot attach to this target/i.test(\n message,\n );\n}\n\n/**\n * Wrap user code in an async IIFE to support top-level await and return statements.\n */\nfunction wrapUserCode(code: string): string {\n return `(async () => {\\n${code}\\n})()`;\n}\n\n// ============================================================================\n// CDP Execution\n// ============================================================================\n\ninterface CDPRemoteObject {\n type?: string;\n subtype?: string;\n value?: unknown;\n unserializableValue?: string;\n description?: string;\n}\n\ninterface CDPExceptionDetails {\n text?: string;\n url?: string;\n lineNumber?: number;\n columnNumber?: number;\n exception?: {\n className?: string;\n description?: string;\n value?: string;\n };\n}\n\ninterface CDPEvaluateResult {\n result?: CDPRemoteObject;\n exceptionDetails?: CDPExceptionDetails;\n}\n\nfunction extractReturnValue(remoteObject?: CDPRemoteObject): unknown {\n if (!remoteObject) return undefined;\n\n if ('value' in remoteObject) return remoteObject.value;\n if ('unserializableValue' in remoteObject) return remoteObject.unserializableValue;\n if (typeof remoteObject.description === 'string') return remoteObject.description;\n\n return undefined;\n}\n\nfunction parseExceptionDetails(details: CDPExceptionDetails): ExecutionError {\n const exceptionClassName = details.exception?.className ?? '';\n const exceptionDescription = details.exception?.description ?? '';\n const exceptionValue = details.exception?.value ?? '';\n const text = details.text ?? '';\n\n // Determine the raw error message\n const rawMessage =\n exceptionDescription || exceptionValue || text || 'JavaScript execution failed';\n\n // Sanitize the message\n const message = sanitizeText(rawMessage).text;\n\n // Classify the error kind\n const isSyntaxError = exceptionClassName === 'SyntaxError' || /SyntaxError/i.test(rawMessage);\n\n return {\n kind: isSyntaxError ? 'syntax_error' : 'runtime_error',\n message,\n details: {\n url: details.url,\n lineNumber: details.lineNumber,\n columnNumber: details.columnNumber,\n },\n };\n}\n\nasync function executeViaCdp(\n tabId: number,\n code: string,\n options: ExecutionOptions,\n): Promise {\n try {\n const expression = wrapUserCode(code);\n\n const response = await withTimeout(\n cdpSessionManager.withSession(tabId, CDP_SESSION_KEY, async () => {\n return (await cdpSessionManager.sendCommand(tabId, 'Runtime.evaluate', {\n expression,\n returnByValue: true,\n awaitPromise: true,\n // CDP 内置超时（毫秒），与外层 withTimeout 双重保障\n timeout: options.timeoutMs,\n })) as CDPEvaluateResult;\n }),\n // 外层超时稍长，给 CDP 一点余量处理超时响应\n options.timeoutMs + 1000,\n );\n\n // Check for exception\n if (response?.exceptionDetails) {\n return {\n ok: false,\n engine: 'cdp',\n error: parseExceptionDetails(response.exceptionDetails),\n };\n }\n\n // Extract and sanitize the result\n const value = extractReturnValue(response?.result);\n const sanitized = sanitizeAndLimitOutput(value, { maxBytes: options.maxOutputBytes });\n\n return {\n ok: true,\n engine: 'cdp',\n output: sanitized.text,\n truncated: sanitized.truncated,\n redacted: sanitized.redacted,\n };\n } catch (error) {\n if (isTimeoutError(error)) {\n return {\n ok: false,\n engine: 'cdp',\n error: { kind: 'timeout', message: error.message },\n };\n }\n\n if (isDebuggerConflictError(error)) {\n const message = sanitizeText(error instanceof Error ? error.message : String(error)).text;\n return {\n ok: false,\n engine: 'cdp',\n error: { kind: 'debugger_conflict', message },\n };\n }\n\n const message = sanitizeText(error instanceof Error ? error.message : String(error)).text;\n return {\n ok: false,\n engine: 'cdp',\n error: { kind: 'cdp_error', message },\n };\n }\n}\n\n// ============================================================================\n// chrome.scripting.executeScript Fallback\n// ============================================================================\n\ninterface ScriptingExecutionResult {\n ok: boolean;\n value?: unknown;\n error?: {\n name?: string;\n message?: string;\n stack?: string;\n };\n}\n\nasync function executeViaScripting(\n tabId: number,\n code: string,\n options: ExecutionOptions,\n): Promise {\n const innerExecute = async (): Promise => {\n const results = await chrome.scripting.executeScript({\n target: { tabId },\n world: 'ISOLATED',\n func: async (userCode: string): Promise => {\n try {\n // Use AsyncFunction constructor to support top-level await\n\n const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;\n const fn = new AsyncFunction(userCode);\n const value = await fn();\n return { ok: true, value };\n } catch (err: unknown) {\n const error = err as Error;\n return {\n ok: false,\n error: {\n name: error?.name ?? undefined,\n message: error?.message ?? String(err),\n stack: error?.stack ?? undefined,\n },\n };\n }\n },\n args: [code],\n });\n\n // Extract the first result\n const firstFrame = results?.[0];\n const result = (firstFrame as { result?: ScriptingExecutionResult })?.result;\n\n if (!result || typeof result !== 'object') {\n return {\n ok: false,\n engine: 'scripting',\n error: { kind: 'scripting_error', message: 'No result returned from executeScript' },\n };\n }\n\n if (!result.ok) {\n const rawMessage = result.error?.message ?? 'JavaScript execution failed';\n const rawStack = result.error?.stack;\n\n const message = sanitizeText(rawMessage).text;\n const sanitizedStack = rawStack ? sanitizeText(rawStack).text : undefined;\n\n const isSyntaxError = result.error?.name === 'SyntaxError' || /SyntaxError/i.test(rawMessage);\n\n return {\n ok: false,\n engine: 'scripting',\n error: {\n kind: isSyntaxError ? 'syntax_error' : 'runtime_error',\n message: sanitizedStack ? `${message}\\n${sanitizedStack}` : message,\n },\n };\n }\n\n // Sanitize the successful result\n const sanitized = sanitizeAndLimitOutput(result.value, { maxBytes: options.maxOutputBytes });\n\n return {\n ok: true,\n engine: 'scripting',\n output: sanitized.text,\n truncated: sanitized.truncated,\n redacted: sanitized.redacted,\n };\n };\n\n try {\n return await withTimeout(innerExecute(), options.timeoutMs);\n } catch (error) {\n if (isTimeoutError(error)) {\n return {\n ok: false,\n engine: 'scripting',\n error: { kind: 'timeout', message: error.message },\n };\n }\n\n const message = sanitizeText(error instanceof Error ? error.message : String(error)).text;\n return {\n ok: false,\n engine: 'scripting',\n error: { kind: 'scripting_error', message },\n };\n }\n}\n\n// ============================================================================\n// Tool Implementation\n// ============================================================================\n\nclass JavaScriptTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.JAVASCRIPT;\n\n async execute(args: JavaScriptToolParams): Promise {\n const startTime = performance.now();\n\n try {\n // Validate required parameter\n const code = typeof args?.code === 'string' ? args.code.trim() : '';\n if (!code) {\n return createErrorResponse('Parameter [code] is required');\n }\n\n // Resolve target tab\n const tab = await this.resolveTargetTab(args.tabId);\n if (!tab) {\n return createErrorResponse(\n typeof args.tabId === 'number' ? `Tab not found: ${args.tabId}` : 'No active tab found',\n );\n }\n\n if (!tab.id) {\n return createErrorResponse('Tab has no ID');\n }\n const tabId = tab.id;\n\n // Normalize options\n const options: ExecutionOptions = {\n timeoutMs: normalizePositiveInt(args.timeoutMs, DEFAULT_TIMEOUT_MS),\n maxOutputBytes: normalizePositiveInt(args.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES),\n };\n\n const warnings: string[] = [];\n\n // Try CDP execution first\n const cdpResult = await executeViaCdp(tabId, code, options);\n\n if (cdpResult.ok) {\n return this.buildSuccessResponse(tabId, cdpResult, startTime);\n }\n\n // If not a debugger conflict, return the CDP error\n if (cdpResult.error.kind !== 'debugger_conflict') {\n return this.buildErrorResponse(tabId, cdpResult, startTime);\n }\n\n // Debugger conflict - fallback to scripting API\n warnings.push(\n 'Debugger is busy (DevTools or another extension attached). Falling back to chrome.scripting.executeScript (runs in ISOLATED world, not page context).',\n );\n\n const scriptingResult = await executeViaScripting(tabId, code, options);\n\n if (scriptingResult.ok) {\n return this.buildSuccessResponse(tabId, scriptingResult, startTime, warnings);\n }\n\n return this.buildErrorResponse(tabId, scriptingResult, startTime, warnings);\n } catch (error) {\n console.error('JavaScriptTool.execute error:', error);\n return createErrorResponse(\n `JavaScript tool error: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n private async resolveTargetTab(tabId?: number): Promise {\n if (typeof tabId === 'number') {\n return this.tryGetTab(tabId);\n }\n try {\n return await this.getActiveTabOrThrow();\n } catch {\n return null;\n }\n }\n\n private buildSuccessResponse(\n tabId: number,\n result: ExecutionSuccess,\n startTime: number,\n warnings?: string[],\n ): ToolResult {\n const payload: JavaScriptToolResult = {\n success: true,\n tabId,\n engine: result.engine,\n result: result.output,\n truncated: result.truncated || undefined,\n redacted: result.redacted || undefined,\n warnings: warnings?.length ? warnings : undefined,\n metrics: { elapsedMs: Math.round(performance.now() - startTime) },\n };\n\n return {\n content: [{ type: 'text', text: JSON.stringify(payload) }],\n isError: false,\n };\n }\n\n private buildErrorResponse(\n tabId: number,\n result: ExecutionFailure,\n startTime: number,\n warnings?: string[],\n ): ToolResult {\n const payload: JavaScriptToolResult = {\n success: false,\n tabId,\n engine: result.engine,\n error: result.error,\n warnings: warnings?.length ? warnings : undefined,\n metrics: { elapsedMs: Math.round(performance.now() - startTime) },\n };\n\n return {\n content: [{ type: 'text', text: JSON.stringify(payload) }],\n isError: true,\n };\n }\n}\n\nexport const javascriptTool = new JavaScriptTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/keyboard.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { TIMEOUTS, ERROR_MESSAGES } from '@/common/constants';\n\ninterface KeyboardToolParams {\n keys: string; // Required: string representing keys or key combinations to simulate (e.g., \"Enter\", \"Ctrl+C\")\n selector?: string; // Optional: CSS selector or XPath for target element to send keyboard events to\n selectorType?: 'css' | 'xpath'; // Type of selector (default: 'css')\n delay?: number; // Optional: delay between keystrokes in milliseconds\n tabId?: number; // target existing tab id\n windowId?: number; // when no tabId, pick active tab from this window\n frameId?: number; // target frame id for iframe support\n}\n\n/**\n * Tool for simulating keyboard input on web pages\n */\nclass KeyboardTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.KEYBOARD;\n\n /**\n * Execute keyboard operation\n */\n async execute(args: KeyboardToolParams): Promise {\n const { keys, selector, selectorType = 'css', delay = TIMEOUTS.KEYBOARD_DELAY } = args;\n\n console.log(`Starting keyboard operation with options:`, args);\n\n if (!keys) {\n return createErrorResponse(\n ERROR_MESSAGES.INVALID_PARAMETERS + ': Keys parameter must be provided',\n );\n }\n\n try {\n const explicit = await this.tryGetTab(args.tabId);\n const tab = explicit || (await this.getActiveTabOrThrowInWindow(args.windowId));\n if (!tab.id) {\n return createErrorResponse(ERROR_MESSAGES.TAB_NOT_FOUND + ': Active tab has no ID');\n }\n\n let finalSelector = selector;\n let refForFocus: string | undefined = undefined;\n\n // Ensure helper is loaded for XPath or potential focus operations\n await this.injectContentScript(tab.id, ['inject-scripts/accessibility-tree-helper.js']);\n\n // If selector is XPath, convert to ref then try to get CSS selector\n if (selector && selectorType === 'xpath') {\n try {\n // First convert XPath to ref\n const ensured = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.ENSURE_REF_FOR_SELECTOR,\n selector,\n isXPath: true,\n });\n if (!ensured || !ensured.success || !ensured.ref) {\n return createErrorResponse(\n `Failed to resolve XPath selector: ${ensured?.error || 'unknown error'}`,\n );\n }\n refForFocus = ensured.ref;\n // Try to resolve ref to CSS selector\n const resolved = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.RESOLVE_REF,\n ref: ensured.ref,\n });\n if (resolved && resolved.success && resolved.selector) {\n finalSelector = resolved.selector;\n refForFocus = undefined; // Prefer CSS selector if available\n }\n // If no CSS selector available, we'll use ref to focus below\n } catch (error) {\n return createErrorResponse(\n `Error resolving XPath: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n // If we have a ref but no CSS selector, focus the element via helper\n if (refForFocus) {\n const focusResult = await this.sendMessageToTab(tab.id, {\n action: 'focusByRef',\n ref: refForFocus,\n });\n if (focusResult && !focusResult.success) {\n return createErrorResponse(\n `Failed to focus element by ref: ${focusResult.error || 'unknown error'}`,\n );\n }\n // Clear selector so keyboard events go to the focused element\n finalSelector = undefined;\n }\n\n const frameIds = typeof args.frameId === 'number' ? [args.frameId] : undefined;\n await this.injectContentScript(\n tab.id,\n ['inject-scripts/keyboard-helper.js'],\n false,\n 'ISOLATED',\n false,\n frameIds,\n );\n\n // Send keyboard simulation message to content script\n const result = await this.sendMessageToTab(\n tab.id,\n {\n action: TOOL_MESSAGE_TYPES.SIMULATE_KEYBOARD,\n keys,\n selector: finalSelector,\n delay,\n },\n args.frameId,\n );\n\n if (result.error) {\n return createErrorResponse(result.error);\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: result.message || 'Keyboard operation successful',\n targetElement: result.targetElement,\n results: result.results,\n }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in keyboard operation:', error);\n return createErrorResponse(\n `Error simulating keyboard events: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const keyboardTool = new KeyboardTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/network-capture-debugger.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\nimport { NETWORK_FILTERS } from '@/common/constants';\n\ninterface NetworkDebuggerStartToolParams {\n url?: string; // URL to navigate to or focus. If not provided, uses active tab.\n maxCaptureTime?: number;\n inactivityTimeout?: number; // Inactivity timeout (milliseconds)\n includeStatic?: boolean; // if include static resources\n}\n\n// Network request object interface\ninterface NetworkRequestInfo {\n requestId: string;\n url: string;\n method: string;\n requestHeaders?: Record; // Will be removed after common headers extraction\n responseHeaders?: Record; // Will be removed after common headers extraction\n requestTime?: number; // Timestamp of the request\n responseTime?: number; // Timestamp of the response\n type: string; // Resource type (e.g., Document, XHR, Fetch, Script, Stylesheet)\n status: string; // 'pending', 'complete', 'error'\n statusCode?: number;\n statusText?: string;\n requestBody?: string;\n responseBody?: string;\n base64Encoded?: boolean; // For responseBody\n encodedDataLength?: number; // Actual bytes received\n errorText?: string; // If loading failed\n canceled?: boolean; // If loading was canceled\n mimeType?: string;\n specificRequestHeaders?: Record; // Headers unique to this request\n specificResponseHeaders?: Record; // Headers unique to this response\n [key: string]: any; // Allow other properties from debugger events\n}\n\nconst DEBUGGER_PROTOCOL_VERSION = '1.3';\nconst MAX_RESPONSE_BODY_SIZE_BYTES = 1 * 1024 * 1024; // 1MB\nconst DEFAULT_MAX_CAPTURE_TIME_MS = 3 * 60 * 1000; // 3 minutes\nconst DEFAULT_INACTIVITY_TIMEOUT_MS = 60 * 1000; // 1 minute\n\n/**\n * Network capture start tool - uses Chrome Debugger API to start capturing network requests\n */\nclass NetworkDebuggerStartTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.NETWORK_DEBUGGER_START;\n private captureData: Map = new Map(); // tabId -> capture data\n private captureTimers: Map = new Map(); // tabId -> max capture timer\n private inactivityTimers: Map = new Map(); // tabId -> inactivity timer\n private lastActivityTime: Map = new Map(); // tabId -> timestamp of last network activity\n private pendingResponseBodies: Map> = new Map(); // requestId -> promise for getResponseBody\n private requestCounters: Map = new Map(); // tabId -> count of captured requests (after filtering)\n private static MAX_REQUESTS_PER_CAPTURE = 100; // Max requests to store to prevent memory issues\n public static instance: NetworkDebuggerStartTool | null = null;\n\n constructor() {\n super();\n if (NetworkDebuggerStartTool.instance) {\n return NetworkDebuggerStartTool.instance;\n }\n NetworkDebuggerStartTool.instance = this;\n\n chrome.debugger.onEvent.addListener(this.handleDebuggerEvent.bind(this));\n chrome.debugger.onDetach.addListener(this.handleDebuggerDetach.bind(this));\n chrome.tabs.onRemoved.addListener(this.handleTabRemoved.bind(this));\n chrome.tabs.onCreated.addListener(this.handleTabCreated.bind(this));\n }\n\n private handleTabRemoved(tabId: number) {\n if (this.captureData.has(tabId)) {\n console.log(`NetworkDebuggerStartTool: Tab ${tabId} was closed, cleaning up resources.`);\n this.cleanupCapture(tabId);\n }\n }\n\n /**\n * Handle tab creation events\n * If a new tab is opened from a tab that is currently capturing, automatically start capturing the new tab's requests\n */\n private async handleTabCreated(tab: chrome.tabs.Tab) {\n try {\n // Check if there are any tabs currently capturing\n if (this.captureData.size === 0) return;\n\n // Get the openerTabId of the new tab (ID of the tab that opened this tab)\n const openerTabId = tab.openerTabId;\n if (!openerTabId) return;\n\n // Check if the opener tab is currently capturing\n if (!this.captureData.has(openerTabId)) return;\n\n // Get the new tab's ID\n const newTabId = tab.id;\n if (!newTabId) return;\n\n console.log(\n `NetworkDebuggerStartTool: New tab ${newTabId} created from capturing tab ${openerTabId}, will extend capture to it.`,\n );\n\n // Get the opener tab's capture settings\n const openerCaptureInfo = this.captureData.get(openerTabId);\n if (!openerCaptureInfo) return;\n\n // Wait a short time to ensure the tab is ready\n await new Promise((resolve) => setTimeout(resolve, 500));\n\n // Start capturing requests for the new tab\n await this.startCaptureForTab(newTabId, {\n maxCaptureTime: openerCaptureInfo.maxCaptureTime,\n inactivityTimeout: openerCaptureInfo.inactivityTimeout,\n includeStatic: openerCaptureInfo.includeStatic,\n });\n\n console.log(`NetworkDebuggerStartTool: Successfully extended capture to new tab ${newTabId}`);\n } catch (error) {\n console.error(`NetworkDebuggerStartTool: Error extending capture to new tab:`, error);\n }\n }\n\n /**\n * Start network request capture for specified tab\n * @param tabId Tab ID\n * @param options Capture options\n */\n private async startCaptureForTab(\n tabId: number,\n options: {\n maxCaptureTime: number;\n inactivityTimeout: number;\n includeStatic: boolean;\n },\n ): Promise {\n const { maxCaptureTime, inactivityTimeout, includeStatic } = options;\n\n // If already capturing, stop first\n if (this.captureData.has(tabId)) {\n console.log(\n `NetworkDebuggerStartTool: Already capturing on tab ${tabId}. Stopping previous session.`,\n );\n await this.stopCapture(tabId);\n }\n\n try {\n // Get tab information\n const tab = await chrome.tabs.get(tabId);\n\n // Attach via shared manager (handles conflicts and refcount)\n await cdpSessionManager.attach(tabId, 'network-capture');\n\n // Enable network tracking\n try {\n await cdpSessionManager.sendCommand(tabId, 'Network.enable');\n } catch (error: any) {\n await cdpSessionManager\n .detach(tabId, 'network-capture')\n .catch((e) => console.warn('Error detaching after failed enable:', e));\n throw error;\n }\n\n // Initialize capture data\n this.captureData.set(tabId, {\n startTime: Date.now(),\n tabUrl: tab.url,\n tabTitle: tab.title,\n maxCaptureTime,\n inactivityTimeout,\n includeStatic,\n requests: {},\n limitReached: false,\n });\n\n // Initialize request counter\n this.requestCounters.set(tabId, 0);\n\n // Update last activity time\n this.updateLastActivityTime(tabId);\n\n console.log(\n `NetworkDebuggerStartTool: Started capture for tab ${tabId} (${tab.url}). Max requests: ${NetworkDebuggerStartTool.MAX_REQUESTS_PER_CAPTURE}, Max time: ${maxCaptureTime}ms, Inactivity: ${inactivityTimeout}ms.`,\n );\n\n // Set maximum capture time\n if (maxCaptureTime > 0) {\n this.captureTimers.set(\n tabId,\n setTimeout(async () => {\n console.log(\n `NetworkDebuggerStartTool: Max capture time (${maxCaptureTime}ms) reached for tab ${tabId}.`,\n );\n await this.stopCapture(tabId, true); // Auto-stop due to max time\n }, maxCaptureTime),\n );\n }\n } catch (error: any) {\n console.error(`NetworkDebuggerStartTool: Error starting capture for tab ${tabId}:`, error);\n\n // Clean up resources\n if (this.captureData.has(tabId)) {\n await cdpSessionManager\n .detach(tabId, 'network-capture')\n .catch((e) => console.warn('Cleanup detach error:', e));\n this.cleanupCapture(tabId);\n }\n\n throw error;\n }\n }\n\n private handleDebuggerEvent(source: chrome.debugger.Debuggee, method: string, params?: any) {\n if (!source.tabId) return;\n\n const tabId = source.tabId;\n const captureInfo = this.captureData.get(tabId);\n\n if (!captureInfo) return; // Not capturing for this tab\n\n // Update last activity time for any relevant network event\n this.updateLastActivityTime(tabId);\n\n switch (method) {\n case 'Network.requestWillBeSent':\n this.handleRequestWillBeSent(tabId, params);\n break;\n case 'Network.responseReceived':\n this.handleResponseReceived(tabId, params);\n break;\n case 'Network.loadingFinished':\n this.handleLoadingFinished(tabId, params);\n break;\n case 'Network.loadingFailed':\n this.handleLoadingFailed(tabId, params);\n break;\n }\n }\n\n private handleDebuggerDetach(source: chrome.debugger.Debuggee, reason: string) {\n if (source.tabId && this.captureData.has(source.tabId)) {\n console.log(\n `NetworkDebuggerStartTool: Debugger detached from tab ${source.tabId}, reason: ${reason}. Cleaning up.`,\n );\n // Potentially inform the user or log the result if the detachment was unexpected\n this.cleanupCapture(source.tabId); // Ensure cleanup happens\n }\n }\n\n private updateLastActivityTime(tabId: number) {\n this.lastActivityTime.set(tabId, Date.now());\n const captureInfo = this.captureData.get(tabId);\n\n if (captureInfo && captureInfo.inactivityTimeout > 0) {\n if (this.inactivityTimers.has(tabId)) {\n clearTimeout(this.inactivityTimers.get(tabId)!);\n }\n this.inactivityTimers.set(\n tabId,\n setTimeout(() => this.checkInactivity(tabId), captureInfo.inactivityTimeout),\n );\n }\n }\n\n private checkInactivity(tabId: number) {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) return;\n\n const lastActivity = this.lastActivityTime.get(tabId) || captureInfo.startTime; // Use startTime if no activity yet\n const now = Date.now();\n const inactiveTime = now - lastActivity;\n\n if (inactiveTime >= captureInfo.inactivityTimeout) {\n console.log(\n `NetworkDebuggerStartTool: No activity for ${inactiveTime}ms (threshold: ${captureInfo.inactivityTimeout}ms), stopping capture for tab ${tabId}`,\n );\n this.stopCaptureByInactivity(tabId);\n } else {\n // Reschedule check for the remaining time, this handles system sleep or other interruptions\n const remainingTime = Math.max(0, captureInfo.inactivityTimeout - inactiveTime);\n this.inactivityTimers.set(\n tabId,\n setTimeout(() => this.checkInactivity(tabId), remainingTime),\n );\n }\n }\n\n private async stopCaptureByInactivity(tabId: number) {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) return;\n\n console.log(`NetworkDebuggerStartTool: Stopping capture due to inactivity for tab ${tabId}.`);\n // Potentially, we might want to notify the client/user that this happened.\n // For now, just stop and make the results available if StopTool is called.\n await this.stopCapture(tabId, true); // Pass a flag indicating it's an auto-stop\n }\n\n /**\n * Check if URL should be filtered based on EXCLUDED_DOMAINS patterns.\n * Uses full URL substring match to support patterns like 'facebook.com/tr'.\n */\n private shouldFilterRequestByUrl(url: string): boolean {\n const normalizedUrl = String(url || '').toLowerCase();\n if (!normalizedUrl) return false;\n return NETWORK_FILTERS.EXCLUDED_DOMAINS.some((pattern) => normalizedUrl.includes(pattern));\n }\n\n private shouldFilterRequestByExtension(url: string, includeStatic: boolean): boolean {\n if (includeStatic) return false;\n\n try {\n const urlObj = new URL(url);\n const path = urlObj.pathname.toLowerCase();\n return NETWORK_FILTERS.STATIC_RESOURCE_EXTENSIONS.some((ext) => path.endsWith(ext));\n } catch {\n return false;\n }\n }\n\n private shouldFilterByMimeType(mimeType: string, includeStatic: boolean): boolean {\n if (!mimeType) return false;\n\n // Never filter API MIME types\n if (NETWORK_FILTERS.API_MIME_TYPES.some((apiMime) => mimeType.startsWith(apiMime))) {\n return false;\n }\n\n // Filter static MIME types when not including static resources\n if (!includeStatic) {\n return NETWORK_FILTERS.STATIC_MIME_TYPES_TO_FILTER.some((staticMime) =>\n mimeType.startsWith(staticMime),\n );\n }\n\n return false;\n }\n\n private handleRequestWillBeSent(tabId: number, params: any) {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) return;\n\n const { requestId, request, timestamp, type, loaderId, frameId } = params;\n\n // Initial filtering by URL (ads, analytics) and extension (if !includeStatic)\n if (\n this.shouldFilterRequestByUrl(request.url) ||\n this.shouldFilterRequestByExtension(request.url, captureInfo.includeStatic)\n ) {\n return;\n }\n\n const currentCount = this.requestCounters.get(tabId) || 0;\n if (currentCount >= NetworkDebuggerStartTool.MAX_REQUESTS_PER_CAPTURE) {\n // console.log(`NetworkDebuggerStartTool: Request limit (${NetworkDebuggerStartTool.MAX_REQUESTS_PER_CAPTURE}) reached for tab ${tabId}. Ignoring: ${request.url}`);\n captureInfo.limitReached = true; // Mark that limit was hit\n return;\n }\n\n // Store initial request info\n // Ensure we don't overwrite if a redirect (same requestId) occurred, though usually loaderId changes\n if (!captureInfo.requests[requestId]) {\n // Or check based on loaderId as well if needed\n captureInfo.requests[requestId] = {\n requestId,\n url: request.url,\n method: request.method,\n requestHeaders: request.headers, // Temporary, will be processed\n requestTime: timestamp * 1000, // Convert seconds to milliseconds\n type: type || 'Other',\n status: 'pending', // Initial status\n loaderId, // Useful for tracking redirects\n frameId, // Useful for context\n };\n\n if (request.postData) {\n captureInfo.requests[requestId].requestBody = request.postData;\n }\n // console.log(`NetworkDebuggerStartTool: Captured request for tab ${tabId}: ${request.method} ${request.url}`);\n } else {\n // This could be a redirect. Update URL and other relevant fields.\n // Chrome often issues a new `requestWillBeSent` for redirects with the same `requestId` but a new `loaderId`.\n // console.log(`NetworkDebuggerStartTool: Request ${requestId} updated (likely redirect) for tab ${tabId} to URL: ${request.url}`);\n const existingRequest = captureInfo.requests[requestId];\n existingRequest.url = request.url; // Update URL due to redirect\n existingRequest.requestTime = timestamp * 1000; // Update time for the redirected request\n if (request.headers) existingRequest.requestHeaders = request.headers;\n if (request.postData) existingRequest.requestBody = request.postData;\n else delete existingRequest.requestBody;\n }\n }\n\n private handleResponseReceived(tabId: number, params: any) {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) return;\n\n const { requestId, response, timestamp, type } = params; // type here is resource type\n const requestInfo: NetworkRequestInfo = captureInfo.requests[requestId];\n\n if (!requestInfo) {\n // console.warn(`NetworkDebuggerStartTool: Received response for unknown requestId ${requestId} on tab ${tabId}`);\n return;\n }\n\n // Secondary filtering based on MIME type, now that we have it\n if (this.shouldFilterByMimeType(response.mimeType, captureInfo.includeStatic)) {\n // console.log(`NetworkDebuggerStartTool: Filtering request by MIME type (${response.mimeType}): ${requestInfo.url}`);\n delete captureInfo.requests[requestId]; // Remove from captured data\n // Note: We don't decrement requestCounter here as it's meant to track how many *potential* requests were processed up to MAX_REQUESTS.\n // Or, if MAX_REQUESTS is strictly for *stored* requests, then decrement. For now, let's assume it's for stored.\n // const currentCount = this.requestCounters.get(tabId) || 0;\n // if (currentCount > 0) this.requestCounters.set(tabId, currentCount -1);\n return;\n }\n\n // If not filtered by MIME, then increment actual stored request counter\n const currentStoredCount = Object.keys(captureInfo.requests).length; // A bit inefficient but accurate\n this.requestCounters.set(tabId, currentStoredCount);\n\n requestInfo.status = response.status === 0 ? 'pending' : 'complete'; // status 0 can mean pending or blocked\n requestInfo.statusCode = response.status;\n requestInfo.statusText = response.statusText;\n requestInfo.responseHeaders = response.headers; // Temporary\n requestInfo.mimeType = response.mimeType;\n requestInfo.responseTime = timestamp * 1000; // Convert seconds to milliseconds\n if (type) requestInfo.type = type; // Update resource type if provided by this event\n\n // console.log(`NetworkDebuggerStartTool: Received response for ${requestId} on tab ${tabId}: ${response.status}`);\n }\n\n private async handleLoadingFinished(tabId: number, params: any) {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) return;\n\n const { requestId, encodedDataLength } = params;\n const requestInfo: NetworkRequestInfo = captureInfo.requests[requestId];\n\n if (!requestInfo) {\n // console.warn(`NetworkDebuggerStartTool: LoadingFinished for unknown requestId ${requestId} on tab ${tabId}`);\n return;\n }\n\n requestInfo.encodedDataLength = encodedDataLength;\n if (requestInfo.status === 'pending') requestInfo.status = 'complete'; // Mark as complete if not already\n // requestInfo.responseTime is usually set by responseReceived, but this timestamp is later.\n // timestamp here is when the resource finished loading. Could be useful for duration calculation.\n\n if (this.shouldCaptureResponseBody(requestInfo)) {\n try {\n // console.log(`NetworkDebuggerStartTool: Attempting to get response body for ${requestId} (${requestInfo.url})`);\n const responseBodyData = await this.getResponseBody(tabId, requestId);\n if (responseBodyData) {\n if (\n responseBodyData.body &&\n responseBodyData.body.length > MAX_RESPONSE_BODY_SIZE_BYTES\n ) {\n requestInfo.responseBody =\n responseBodyData.body.substring(0, MAX_RESPONSE_BODY_SIZE_BYTES) +\n `\\n\\n... [Response truncated, total size: ${responseBodyData.body.length} bytes] ...`;\n } else {\n requestInfo.responseBody = responseBodyData.body;\n }\n requestInfo.base64Encoded = responseBodyData.base64Encoded;\n // console.log(`NetworkDebuggerStartTool: Successfully got response body for ${requestId}, size: ${requestInfo.responseBody?.length || 0} bytes`);\n }\n } catch (error) {\n // console.warn(`NetworkDebuggerStartTool: Failed to get response body for ${requestId}:`, error);\n requestInfo.errorText =\n (requestInfo.errorText || '') +\n ` Failed to get body: ${error instanceof Error ? error.message : String(error)}`;\n }\n }\n }\n\n private shouldCaptureResponseBody(requestInfo: NetworkRequestInfo): boolean {\n const mimeType = requestInfo.mimeType || '';\n\n // Prioritize API MIME types for body capture\n if (NETWORK_FILTERS.API_MIME_TYPES.some((type) => mimeType.startsWith(type))) {\n return true;\n }\n\n // Heuristics for other potential API calls not perfectly matching MIME types\n const url = requestInfo.url.toLowerCase();\n if (\n /\\/(api|service|rest|graphql|query|data|rpc|v[0-9]+)\\//i.test(url) ||\n url.includes('.json') ||\n url.includes('json=') ||\n url.includes('format=json')\n ) {\n // If it looks like an API call by URL structure, try to get body,\n // unless it's a known non-API MIME type that slipped through (e.g. a script from a /api/ path)\n if (\n mimeType &&\n NETWORK_FILTERS.STATIC_MIME_TYPES_TO_FILTER.some((staticMime) =>\n mimeType.startsWith(staticMime),\n )\n ) {\n return false; // e.g. a CSS file served from an /api/ path\n }\n return true;\n }\n\n return false;\n }\n\n private handleLoadingFailed(tabId: number, params: any) {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) return;\n\n const { requestId, errorText, canceled, type } = params;\n const requestInfo: NetworkRequestInfo = captureInfo.requests[requestId];\n\n if (!requestInfo) {\n // console.warn(`NetworkDebuggerStartTool: LoadingFailed for unknown requestId ${requestId} on tab ${tabId}`);\n return;\n }\n\n requestInfo.status = 'error';\n requestInfo.errorText = errorText;\n requestInfo.canceled = canceled;\n if (type) requestInfo.type = type;\n // timestamp here is when loading failed.\n // console.log(`NetworkDebuggerStartTool: Loading failed for ${requestId} on tab ${tabId}: ${errorText}`);\n }\n\n private async getResponseBody(\n tabId: number,\n requestId: string,\n ): Promise<{ body: string; base64Encoded: boolean } | null> {\n const pendingKey = `${tabId}_${requestId}`;\n if (this.pendingResponseBodies.has(pendingKey)) {\n return this.pendingResponseBodies.get(pendingKey)!; // Return existing promise\n }\n\n const responseBodyPromise = (async () => {\n try {\n // Will attach temporarily if needed\n const result = (await cdpSessionManager.sendCommand(tabId, 'Network.getResponseBody', {\n requestId,\n })) as { body: string; base64Encoded: boolean };\n return result;\n } finally {\n this.pendingResponseBodies.delete(pendingKey); // Clean up after promise resolves or rejects\n }\n })();\n\n this.pendingResponseBodies.set(pendingKey, responseBodyPromise);\n return responseBodyPromise;\n }\n\n private cleanupCapture(tabId: number) {\n if (this.captureTimers.has(tabId)) {\n clearTimeout(this.captureTimers.get(tabId)!);\n this.captureTimers.delete(tabId);\n }\n if (this.inactivityTimers.has(tabId)) {\n clearTimeout(this.inactivityTimers.get(tabId)!);\n this.inactivityTimers.delete(tabId);\n }\n\n this.lastActivityTime.delete(tabId);\n this.captureData.delete(tabId);\n this.requestCounters.delete(tabId);\n\n // Abort pending getResponseBody calls for this tab\n // Note: Promises themselves cannot be \"aborted\" externally in a standard way once created.\n // We can delete them from the map, so new calls won't use them,\n // and the original promise will eventually resolve or reject.\n const keysToDelete: string[] = [];\n this.pendingResponseBodies.forEach((_, key) => {\n if (key.startsWith(`${tabId}_`)) {\n keysToDelete.push(key);\n }\n });\n keysToDelete.forEach((key) => this.pendingResponseBodies.delete(key));\n\n console.log(`NetworkDebuggerStartTool: Cleaned up resources for tab ${tabId}.`);\n }\n\n // isAutoStop is true if stop was triggered by timeout, false if by user/explicit call\n async stopCapture(tabId: number, isAutoStop: boolean = false): Promise {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) {\n return { success: false, message: 'No capture in progress for this tab.' };\n }\n\n console.log(\n `NetworkDebuggerStartTool: Stopping capture for tab ${tabId}. Auto-stop: ${isAutoStop}`,\n );\n\n try {\n // Attempt to disable network and detach via manager; it will no-op if others own the session\n try {\n await cdpSessionManager.sendCommand(tabId, 'Network.disable');\n } catch (e) {\n console.warn(\n `NetworkDebuggerStartTool: Error disabling network for tab ${tabId} (possibly already detached):`,\n e,\n );\n }\n try {\n await cdpSessionManager.detach(tabId, 'network-capture');\n } catch (e) {\n console.warn(\n `NetworkDebuggerStartTool: Error detaching debugger for tab ${tabId} (possibly already detached):`,\n e,\n );\n }\n } catch (error: any) {\n // Catch errors from getTargets or general logic\n console.error(\n 'NetworkDebuggerStartTool: Error during debugger interaction in stopCapture:',\n error,\n );\n // Proceed to cleanup and data formatting\n }\n\n // Process data even if detach/disable failed, as some data might have been captured.\n const allRequests = Object.values(captureInfo.requests) as NetworkRequestInfo[];\n const commonRequestHeaders = this.analyzeCommonHeaders(allRequests, 'requestHeaders');\n const commonResponseHeaders = this.analyzeCommonHeaders(allRequests, 'responseHeaders');\n\n const processedRequests = allRequests.map((req) => {\n const finalReq: Partial &\n Pick = { ...req };\n\n if (finalReq.requestHeaders) {\n finalReq.specificRequestHeaders = this.filterOutCommonHeaders(\n finalReq.requestHeaders,\n commonRequestHeaders,\n );\n delete finalReq.requestHeaders; // Remove original full headers\n } else {\n finalReq.specificRequestHeaders = {};\n }\n\n if (finalReq.responseHeaders) {\n finalReq.specificResponseHeaders = this.filterOutCommonHeaders(\n finalReq.responseHeaders,\n commonResponseHeaders,\n );\n delete finalReq.responseHeaders; // Remove original full headers\n } else {\n finalReq.specificResponseHeaders = {};\n }\n return finalReq as NetworkRequestInfo; // Cast back to full type\n });\n\n // Sort requests by requestTime\n processedRequests.sort((a, b) => (a.requestTime || 0) - (b.requestTime || 0));\n\n const resultData = {\n captureStartTime: captureInfo.startTime,\n captureEndTime: Date.now(),\n totalDurationMs: Date.now() - captureInfo.startTime,\n commonRequestHeaders,\n commonResponseHeaders,\n requests: processedRequests,\n requestCount: processedRequests.length, // Actual stored requests\n totalRequestsReceivedBeforeLimit: captureInfo.limitReached\n ? NetworkDebuggerStartTool.MAX_REQUESTS_PER_CAPTURE\n : processedRequests.length,\n requestLimitReached: !!captureInfo.limitReached,\n stoppedBy: isAutoStop\n ? this.lastActivityTime.get(tabId)\n ? 'inactivity_timeout'\n : 'max_capture_time'\n : 'user_request',\n tabUrl: captureInfo.tabUrl,\n tabTitle: captureInfo.tabTitle,\n };\n\n console.log(\n `NetworkDebuggerStartTool: Capture stopped for tab ${tabId}. ${resultData.requestCount} requests processed. Limit reached: ${resultData.requestLimitReached}. Stopped by: ${resultData.stoppedBy}`,\n );\n\n this.cleanupCapture(tabId); // Final cleanup of all internal states for this tab\n\n return {\n success: true,\n message: `Capture stopped. ${resultData.requestCount} requests.`,\n data: resultData,\n };\n }\n\n private analyzeCommonHeaders(\n requests: NetworkRequestInfo[],\n headerTypeKey: 'requestHeaders' | 'responseHeaders',\n ): Record {\n if (!requests || requests.length === 0) return {};\n\n const headerValueCounts = new Map>(); // headerName -> (headerValue -> count)\n let requestsWithHeadersCount = 0;\n\n for (const req of requests) {\n const headers = req[headerTypeKey] as Record | undefined;\n if (headers && Object.keys(headers).length > 0) {\n requestsWithHeadersCount++;\n for (const name in headers) {\n // Normalize header name to lowercase for consistent counting\n const lowerName = name.toLowerCase();\n const value = headers[name];\n if (!headerValueCounts.has(lowerName)) {\n headerValueCounts.set(lowerName, new Map());\n }\n const values = headerValueCounts.get(lowerName)!;\n values.set(value, (values.get(value) || 0) + 1);\n }\n }\n }\n\n if (requestsWithHeadersCount === 0) return {};\n\n const commonHeaders: Record = {};\n headerValueCounts.forEach((values, name) => {\n values.forEach((count, value) => {\n if (count === requestsWithHeadersCount) {\n // This (name, value) pair is present in all requests that have this type of headers.\n // We need to find the original casing for the header name.\n // This is tricky as HTTP headers are case-insensitive. Let's pick the first encountered one.\n // A more robust way would be to store original names, but lowercase comparison is standard.\n // For simplicity, we'll use the lowercase name for commonHeaders keys.\n // Or, find one original casing:\n let originalName = name;\n for (const req of requests) {\n const hdrs = req[headerTypeKey] as Record | undefined;\n if (hdrs) {\n const foundName = Object.keys(hdrs).find((k) => k.toLowerCase() === name);\n if (foundName) {\n originalName = foundName;\n break;\n }\n }\n }\n commonHeaders[originalName] = value;\n }\n });\n });\n return commonHeaders;\n }\n\n private filterOutCommonHeaders(\n headers: Record,\n commonHeaders: Record,\n ): Record {\n if (!headers || typeof headers !== 'object') return {};\n\n const specificHeaders: Record = {};\n const commonHeadersLower: Record = {};\n\n // Use Object.keys to avoid ESLint no-prototype-builtins warning\n Object.keys(commonHeaders).forEach((commonName) => {\n commonHeadersLower[commonName.toLowerCase()] = commonHeaders[commonName];\n });\n\n // Use Object.keys to avoid ESLint no-prototype-builtins warning\n Object.keys(headers).forEach((name) => {\n const lowerName = name.toLowerCase();\n // If the header (by name, case-insensitively) is not in commonHeaders OR\n // if its value is different from the common one, then it's specific.\n if (!(lowerName in commonHeadersLower) || headers[name] !== commonHeadersLower[lowerName]) {\n specificHeaders[name] = headers[name];\n }\n });\n\n return specificHeaders;\n }\n\n async execute(args: NetworkDebuggerStartToolParams): Promise {\n const {\n url: targetUrl,\n maxCaptureTime = DEFAULT_MAX_CAPTURE_TIME_MS,\n inactivityTimeout = DEFAULT_INACTIVITY_TIMEOUT_MS,\n includeStatic = false,\n } = args;\n\n console.log(\n `NetworkDebuggerStartTool: Executing with args: url=${targetUrl}, maxTime=${maxCaptureTime}, inactivityTime=${inactivityTimeout}, includeStatic=${includeStatic}`,\n );\n\n let tabToOperateOn: chrome.tabs.Tab | undefined;\n\n try {\n if (targetUrl) {\n const existingTabs = await chrome.tabs.query({\n url: targetUrl.startsWith('http') ? targetUrl : `*://*/*${targetUrl}*`,\n }); // More specific query\n if (existingTabs.length > 0 && existingTabs[0]?.id) {\n tabToOperateOn = existingTabs[0];\n // Ensure window gets focus and tab is truly activated\n await chrome.windows.update(tabToOperateOn.windowId, { focused: true });\n await chrome.tabs.update(tabToOperateOn.id!, { active: true });\n } else {\n tabToOperateOn = await chrome.tabs.create({ url: targetUrl, active: true });\n // Wait for tab to be somewhat ready. A better way is to listen to tabs.onUpdated status='complete'\n // but for debugger attachment, it just needs the tabId.\n await new Promise((resolve) => setTimeout(resolve, 500)); // Short delay\n }\n } else {\n const activeTabs = await chrome.tabs.query({ active: true, currentWindow: true });\n if (activeTabs.length > 0 && activeTabs[0]?.id) {\n tabToOperateOn = activeTabs[0];\n } else {\n return createErrorResponse('No active tab found and no URL provided.');\n }\n }\n\n if (!tabToOperateOn?.id) {\n return createErrorResponse('Failed to identify or create a target tab.');\n }\n const tabId = tabToOperateOn.id;\n\n // Use startCaptureForTab method to start capture\n try {\n await this.startCaptureForTab(tabId, {\n maxCaptureTime,\n inactivityTimeout,\n includeStatic,\n });\n } catch (error: any) {\n return createErrorResponse(\n `Failed to start capture for tab ${tabId}: ${error.message || String(error)}`,\n );\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: `Network capture started on tab ${tabId}. Waiting for stop command or timeout.`,\n tabId,\n url: tabToOperateOn.url,\n maxCaptureTime,\n inactivityTimeout,\n includeStatic,\n maxRequests: NetworkDebuggerStartTool.MAX_REQUESTS_PER_CAPTURE,\n }),\n },\n ],\n isError: false,\n };\n } catch (error: any) {\n console.error('NetworkDebuggerStartTool: Critical error during execute:', error);\n // If a tabId was involved and debugger might be attached, try to clean up.\n const tabIdToClean = tabToOperateOn?.id;\n if (tabIdToClean && this.captureData.has(tabIdToClean)) {\n await cdpSessionManager\n .detach(tabIdToClean, 'network-capture')\n .catch((e) => console.warn('Cleanup detach error:', e));\n this.cleanupCapture(tabIdToClean);\n }\n return createErrorResponse(\n `Error in NetworkDebuggerStartTool: ${error.message || String(error)}`,\n );\n }\n }\n}\n\n/**\n * Network capture stop tool - stops capture and returns results for the active tab\n */\nclass NetworkDebuggerStopTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.NETWORK_DEBUGGER_STOP;\n public static instance: NetworkDebuggerStopTool | null = null;\n\n constructor() {\n super();\n if (NetworkDebuggerStopTool.instance) {\n return NetworkDebuggerStopTool.instance;\n }\n NetworkDebuggerStopTool.instance = this;\n }\n\n async execute(): Promise {\n console.log(`NetworkDebuggerStopTool: Executing command.`);\n\n const startTool = NetworkDebuggerStartTool.instance;\n if (!startTool) {\n return createErrorResponse(\n 'NetworkDebuggerStartTool instance not available. Cannot stop capture.',\n );\n }\n\n // Get all tabs currently capturing\n const ongoingCaptures = Array.from(startTool['captureData'].keys());\n console.log(\n `NetworkDebuggerStopTool: Found ${ongoingCaptures.length} ongoing captures: ${ongoingCaptures.join(', ')}`,\n );\n\n if (ongoingCaptures.length === 0) {\n return createErrorResponse('No active network captures found in any tab.');\n }\n\n // Get current active tab\n const activeTabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const activeTabId = activeTabs[0]?.id;\n\n // Determine the primary tab to stop\n let primaryTabId: number;\n\n if (activeTabId && startTool['captureData'].has(activeTabId)) {\n // If current active tab is capturing, prioritize stopping it\n primaryTabId = activeTabId;\n console.log(\n `NetworkDebuggerStopTool: Active tab ${activeTabId} is capturing, will stop it first.`,\n );\n } else if (ongoingCaptures.length === 1) {\n // If only one tab is capturing, stop it\n primaryTabId = ongoingCaptures[0];\n console.log(\n `NetworkDebuggerStopTool: Only one tab ${primaryTabId} is capturing, stopping it.`,\n );\n } else {\n // If multiple tabs are capturing but current active tab is not among them, stop the first one\n primaryTabId = ongoingCaptures[0];\n console.log(\n `NetworkDebuggerStopTool: Multiple tabs capturing, active tab not among them. Stopping tab ${primaryTabId} first.`,\n );\n }\n\n // Stop capture for the primary tab\n const result = await this.performStop(startTool, primaryTabId);\n\n // If multiple tabs are capturing, stop other tabs\n if (ongoingCaptures.length > 1) {\n const otherTabIds = ongoingCaptures.filter((id) => id !== primaryTabId);\n console.log(\n `NetworkDebuggerStopTool: Stopping ${otherTabIds.length} additional captures: ${otherTabIds.join(', ')}`,\n );\n\n for (const tabId of otherTabIds) {\n try {\n await startTool.stopCapture(tabId);\n } catch (error) {\n console.error(`NetworkDebuggerStopTool: Error stopping capture on tab ${tabId}:`, error);\n }\n }\n }\n\n return result;\n }\n\n private async performStop(\n startTool: NetworkDebuggerStartTool,\n tabId: number,\n ): Promise {\n console.log(`NetworkDebuggerStopTool: Attempting to stop capture for tab ${tabId}.`);\n const stopResult = await startTool.stopCapture(tabId);\n\n if (!stopResult?.success) {\n return createErrorResponse(\n stopResult?.message ||\n `Failed to stop network capture for tab ${tabId}. It might not have been capturing.`,\n );\n }\n\n const resultData = stopResult.data || {};\n\n // Get all tabs still capturing (there might be other tabs still capturing after stopping)\n const remainingCaptures = Array.from(startTool['captureData'].keys());\n\n // Sort requests by time\n if (resultData.requests && Array.isArray(resultData.requests)) {\n resultData.requests.sort(\n (a: NetworkRequestInfo, b: NetworkRequestInfo) =>\n (a.requestTime || 0) - (b.requestTime || 0),\n );\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: `Capture for tab ${tabId} (${resultData.tabUrl || 'N/A'}) stopped. ${resultData.requestCount || 0} requests captured.`,\n tabId: tabId,\n tabUrl: resultData.tabUrl || 'N/A',\n tabTitle: resultData.tabTitle || 'Unknown Tab',\n requestCount: resultData.requestCount || 0,\n commonRequestHeaders: resultData.commonRequestHeaders || {},\n commonResponseHeaders: resultData.commonResponseHeaders || {},\n requests: resultData.requests || [],\n captureStartTime: resultData.captureStartTime,\n captureEndTime: resultData.captureEndTime,\n totalDurationMs: resultData.totalDurationMs,\n settingsUsed: resultData.settingsUsed || {},\n remainingCaptures: remainingCaptures,\n totalRequestsReceived: resultData.totalRequestsReceived || resultData.requestCount || 0,\n requestLimitReached: resultData.requestLimitReached || false,\n }),\n },\n ],\n isError: false,\n };\n }\n}\n\nexport const networkDebuggerStartTool = new NetworkDebuggerStartTool();\nexport const networkDebuggerStopTool = new NetworkDebuggerStopTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/network-capture-web-request.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { LIMITS, NETWORK_FILTERS } from '@/common/constants';\n\n// Static resource file extensions\nconst STATIC_RESOURCE_EXTENSIONS = [\n '.jpg',\n '.jpeg',\n '.png',\n '.gif',\n '.svg',\n '.webp',\n '.ico',\n '.bmp', // Images\n '.css',\n '.scss',\n '.less', // Styles\n '.js',\n '.jsx',\n '.ts',\n '.tsx', // Scripts\n '.woff',\n '.woff2',\n '.ttf',\n '.eot',\n '.otf', // Fonts\n '.mp3',\n '.mp4',\n '.avi',\n '.mov',\n '.wmv',\n '.flv',\n '.ogg',\n '.wav', // Media\n '.pdf',\n '.doc',\n '.docx',\n '.xls',\n '.xlsx',\n '.ppt',\n '.pptx', // Documents\n];\n\n// Ad and analytics domain list\nconst AD_ANALYTICS_DOMAINS = NETWORK_FILTERS.EXCLUDED_DOMAINS;\n\ninterface NetworkCaptureStartToolParams {\n url?: string; // URL to navigate to or focus. If not provided, uses active tab.\n maxCaptureTime?: number; // Maximum capture time (milliseconds)\n inactivityTimeout?: number; // Inactivity timeout (milliseconds)\n includeStatic?: boolean; // Whether to include static resources\n}\n\ninterface NetworkRequestInfo {\n requestId: string;\n url: string;\n method: string;\n type: string;\n requestTime: number;\n requestHeaders?: Record;\n requestBody?: string;\n responseHeaders?: Record;\n responseTime?: number;\n status?: number;\n statusText?: string;\n responseSize?: number;\n responseType?: string;\n responseBody?: string;\n errorText?: string;\n specificRequestHeaders?: Record;\n specificResponseHeaders?: Record;\n mimeType?: string; // Response MIME type\n}\n\ninterface CaptureInfo {\n tabId: number;\n tabUrl: string;\n tabTitle: string;\n startTime: number;\n endTime?: number;\n requests: Record;\n maxCaptureTime: number;\n inactivityTimeout: number;\n includeStatic: boolean;\n limitReached?: boolean; // Whether request count limit is reached\n}\n\n/**\n * Network Capture Start Tool V2 - Uses Chrome webRequest API to start capturing network requests\n */\nclass NetworkCaptureStartTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.NETWORK_CAPTURE_START;\n public static instance: NetworkCaptureStartTool | null = null;\n public captureData: Map = new Map(); // tabId -> capture data\n private captureTimers: Map = new Map(); // tabId -> max capture timer\n private inactivityTimers: Map = new Map(); // tabId -> inactivity timer\n private lastActivityTime: Map = new Map(); // tabId -> timestamp of last activity\n private requestCounters: Map = new Map(); // tabId -> count of captured requests\n public static MAX_REQUESTS_PER_CAPTURE = LIMITS.MAX_NETWORK_REQUESTS; // Maximum capture request count\n private listeners: { [key: string]: (details: any) => void } = {};\n\n // Static resource MIME types list (for filtering)\n private static STATIC_MIME_TYPES_TO_FILTER = [\n 'image/', // All image types\n 'font/', // All font types\n 'audio/', // All audio types\n 'video/', // All video types\n 'text/css',\n 'text/javascript',\n 'application/javascript',\n 'application/x-javascript',\n 'application/pdf',\n 'application/zip',\n 'application/octet-stream', // Usually for downloads or generic binary data\n ];\n\n // API response MIME types list (these types are usually not filtered)\n private static API_MIME_TYPES = [\n 'application/json',\n 'application/xml',\n 'text/xml',\n 'application/x-www-form-urlencoded',\n 'application/graphql',\n 'application/grpc',\n 'application/protobuf',\n 'application/x-protobuf',\n 'application/x-json',\n 'application/ld+json',\n 'application/problem+json',\n 'application/problem+xml',\n 'application/soap+xml',\n 'application/vnd.api+json',\n ];\n\n constructor() {\n super();\n if (NetworkCaptureStartTool.instance) {\n return NetworkCaptureStartTool.instance;\n }\n NetworkCaptureStartTool.instance = this;\n\n // Listen for tab close events\n chrome.tabs.onRemoved.addListener(this.handleTabRemoved.bind(this));\n // Listen for tab creation events\n chrome.tabs.onCreated.addListener(this.handleTabCreated.bind(this));\n }\n\n /**\n * Handle tab close events\n */\n private handleTabRemoved(tabId: number) {\n if (this.captureData.has(tabId)) {\n console.log(`NetworkCaptureV2: Tab ${tabId} was closed, cleaning up resources.`);\n this.cleanupCapture(tabId);\n }\n }\n\n /**\n * Handle tab creation events\n * If a new tab is opened from a tab being captured, automatically start capturing the new tab's requests\n */\n private async handleTabCreated(tab: chrome.tabs.Tab) {\n try {\n // Check if there are any tabs currently capturing\n if (this.captureData.size === 0) return;\n\n // Get the openerTabId of the new tab (ID of the tab that opened this tab)\n const openerTabId = tab.openerTabId;\n if (!openerTabId) return;\n\n // Check if the opener tab is currently capturing\n if (!this.captureData.has(openerTabId)) return;\n\n // Get the new tab's ID\n const newTabId = tab.id;\n if (!newTabId) return;\n\n console.log(\n `NetworkCaptureV2: New tab ${newTabId} created from capturing tab ${openerTabId}, will extend capture to it.`,\n );\n\n // Get the opener tab's capture settings\n const openerCaptureInfo = this.captureData.get(openerTabId);\n if (!openerCaptureInfo) return;\n\n // Wait a short time to ensure the tab is ready\n await new Promise((resolve) => setTimeout(resolve, 500));\n\n // Start capturing requests for the new tab\n await this.startCaptureForTab(newTabId, {\n maxCaptureTime: openerCaptureInfo.maxCaptureTime,\n inactivityTimeout: openerCaptureInfo.inactivityTimeout,\n includeStatic: openerCaptureInfo.includeStatic,\n });\n\n console.log(`NetworkCaptureV2: Successfully extended capture to new tab ${newTabId}`);\n } catch (error) {\n console.error(`NetworkCaptureV2: Error extending capture to new tab:`, error);\n }\n }\n\n /**\n * Determine whether a request should be filtered (based on URL)\n * Uses full URL substring match to support patterns like 'facebook.com/tr'\n */\n private shouldFilterRequest(url: string, includeStatic: boolean): boolean {\n const normalizedUrl = String(url || '').toLowerCase();\n if (!normalizedUrl) return false;\n\n // Check if it's an ad or analytics domain (full URL substring match)\n if (AD_ANALYTICS_DOMAINS.some((pattern) => normalizedUrl.includes(pattern))) {\n return true;\n }\n\n // If not including static resources, check extensions\n if (!includeStatic) {\n try {\n const urlObj = new URL(url);\n const path = urlObj.pathname.toLowerCase();\n if (STATIC_RESOURCE_EXTENSIONS.some((ext) => path.endsWith(ext))) {\n return true;\n }\n } catch {\n return false;\n }\n }\n\n return false;\n }\n\n /**\n * Filter based on MIME type\n */\n private shouldFilterByMimeType(mimeType: string, includeStatic: boolean): boolean {\n if (!mimeType) return false;\n\n // Always keep API response types\n if (NetworkCaptureStartTool.API_MIME_TYPES.some((type) => mimeType.startsWith(type))) {\n return false;\n }\n\n // If not including static resources, filter out static resource MIME types\n if (!includeStatic) {\n // Filter static resource MIME types\n if (\n NetworkCaptureStartTool.STATIC_MIME_TYPES_TO_FILTER.some((type) =>\n mimeType.startsWith(type),\n )\n ) {\n console.log(`NetworkCaptureV2: Filtering static resource by MIME type: ${mimeType}`);\n return true;\n }\n\n // Filter all MIME types starting with text/ (except those already in API_MIME_TYPES)\n if (mimeType.startsWith('text/')) {\n console.log(`NetworkCaptureV2: Filtering text response: ${mimeType}`);\n return true;\n }\n }\n\n return false;\n }\n\n /**\n * Update last activity time and reset inactivity timer\n */\n private updateLastActivityTime(tabId: number): void {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) return;\n\n this.lastActivityTime.set(tabId, Date.now());\n\n // Reset inactivity timer\n if (this.inactivityTimers.has(tabId)) {\n clearTimeout(this.inactivityTimers.get(tabId)!);\n }\n\n if (captureInfo.inactivityTimeout > 0) {\n this.inactivityTimers.set(\n tabId,\n setTimeout(() => this.checkInactivity(tabId), captureInfo.inactivityTimeout),\n );\n }\n }\n\n /**\n * Check for inactivity\n */\n private checkInactivity(tabId: number): void {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) return;\n\n const lastActivity = this.lastActivityTime.get(tabId) || captureInfo.startTime;\n const now = Date.now();\n const inactiveTime = now - lastActivity;\n\n if (inactiveTime >= captureInfo.inactivityTimeout) {\n console.log(\n `NetworkCaptureV2: No activity for ${inactiveTime}ms, stopping capture for tab ${tabId}`,\n );\n this.stopCaptureByInactivity(tabId);\n } else {\n // If inactivity time hasn't been reached yet, continue checking\n const remainingTime = captureInfo.inactivityTimeout - inactiveTime;\n this.inactivityTimers.set(\n tabId,\n setTimeout(() => this.checkInactivity(tabId), remainingTime),\n );\n }\n }\n\n /**\n * Stop capture due to inactivity\n */\n private async stopCaptureByInactivity(tabId: number): Promise {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) return;\n\n console.log(`NetworkCaptureV2: Stopping capture due to inactivity for tab ${tabId}`);\n await this.stopCapture(tabId);\n }\n\n /**\n * Clean up capture resources\n */\n private cleanupCapture(tabId: number): void {\n // Clear timers\n if (this.captureTimers.has(tabId)) {\n clearTimeout(this.captureTimers.get(tabId)!);\n this.captureTimers.delete(tabId);\n }\n\n if (this.inactivityTimers.has(tabId)) {\n clearTimeout(this.inactivityTimers.get(tabId)!);\n this.inactivityTimers.delete(tabId);\n }\n\n // Remove data\n this.lastActivityTime.delete(tabId);\n this.captureData.delete(tabId);\n this.requestCounters.delete(tabId);\n\n console.log(`NetworkCaptureV2: Cleaned up all resources for tab ${tabId}`);\n }\n\n /**\n * Set up request listeners (idempotent - won't add duplicate listeners)\n */\n private setupListeners(): void {\n // Skip if listeners are already set up\n if (this.listeners.onBeforeRequest) {\n return;\n }\n\n // Before request is sent\n this.listeners.onBeforeRequest = (details: chrome.webRequest.WebRequestBodyDetails) => {\n const captureInfo = this.captureData.get(details.tabId);\n if (!captureInfo) return;\n\n if (this.shouldFilterRequest(details.url, captureInfo.includeStatic)) {\n return;\n }\n\n const currentCount = this.requestCounters.get(details.tabId) || 0;\n if (currentCount >= NetworkCaptureStartTool.MAX_REQUESTS_PER_CAPTURE) {\n console.log(\n `NetworkCaptureV2: Request limit (${NetworkCaptureStartTool.MAX_REQUESTS_PER_CAPTURE}) reached for tab ${details.tabId}, ignoring new request: ${details.url}`,\n );\n captureInfo.limitReached = true;\n return;\n }\n\n this.requestCounters.set(details.tabId, currentCount + 1);\n this.updateLastActivityTime(details.tabId);\n\n if (!captureInfo.requests[details.requestId]) {\n captureInfo.requests[details.requestId] = {\n requestId: details.requestId,\n url: details.url,\n method: details.method,\n type: details.type,\n requestTime: details.timeStamp,\n };\n\n if (details.requestBody) {\n const requestBody = this.processRequestBody(details.requestBody);\n if (requestBody) {\n captureInfo.requests[details.requestId].requestBody = requestBody;\n }\n }\n\n console.log(\n `NetworkCaptureV2: Captured request ${currentCount + 1}/${NetworkCaptureStartTool.MAX_REQUESTS_PER_CAPTURE} for tab ${details.tabId}: ${details.method} ${details.url}`,\n );\n }\n };\n\n // Send request headers\n this.listeners.onSendHeaders = (details: chrome.webRequest.WebRequestHeadersDetails) => {\n const captureInfo = this.captureData.get(details.tabId);\n if (!captureInfo || !captureInfo.requests[details.requestId]) return;\n\n if (details.requestHeaders) {\n const headers: Record = {};\n details.requestHeaders.forEach((header) => {\n headers[header.name] = header.value || '';\n });\n captureInfo.requests[details.requestId].requestHeaders = headers;\n }\n };\n\n // Receive response headers\n this.listeners.onHeadersReceived = (details: chrome.webRequest.WebResponseHeadersDetails) => {\n const captureInfo = this.captureData.get(details.tabId);\n if (!captureInfo || !captureInfo.requests[details.requestId]) return;\n\n const requestInfo = captureInfo.requests[details.requestId];\n\n requestInfo.status = details.statusCode;\n requestInfo.statusText = details.statusLine;\n requestInfo.responseTime = details.timeStamp;\n requestInfo.mimeType = details.responseHeaders?.find(\n (h) => h.name.toLowerCase() === 'content-type',\n )?.value;\n\n // Secondary filtering based on MIME type\n if (\n requestInfo.mimeType &&\n this.shouldFilterByMimeType(requestInfo.mimeType, captureInfo.includeStatic)\n ) {\n delete captureInfo.requests[details.requestId];\n\n const currentCount = this.requestCounters.get(details.tabId) || 0;\n if (currentCount > 0) {\n this.requestCounters.set(details.tabId, currentCount - 1);\n }\n\n console.log(\n `NetworkCaptureV2: Filtered request by MIME type (${requestInfo.mimeType}): ${requestInfo.url}`,\n );\n return;\n }\n\n if (details.responseHeaders) {\n const headers: Record = {};\n details.responseHeaders.forEach((header) => {\n headers[header.name] = header.value || '';\n });\n requestInfo.responseHeaders = headers;\n }\n\n this.updateLastActivityTime(details.tabId);\n };\n\n // Request completed\n this.listeners.onCompleted = (details: chrome.webRequest.WebResponseCacheDetails) => {\n const captureInfo = this.captureData.get(details.tabId);\n if (!captureInfo || !captureInfo.requests[details.requestId]) return;\n\n const requestInfo = captureInfo.requests[details.requestId];\n if ('responseSize' in details) {\n requestInfo.responseSize = details.fromCache ? 0 : (details as any).responseSize;\n }\n\n this.updateLastActivityTime(details.tabId);\n };\n\n // Request failed\n this.listeners.onErrorOccurred = (details: chrome.webRequest.WebResponseErrorDetails) => {\n const captureInfo = this.captureData.get(details.tabId);\n if (!captureInfo || !captureInfo.requests[details.requestId]) return;\n\n const requestInfo = captureInfo.requests[details.requestId];\n requestInfo.errorText = details.error;\n\n this.updateLastActivityTime(details.tabId);\n };\n\n // Register all listeners\n chrome.webRequest.onBeforeRequest.addListener(\n this.listeners.onBeforeRequest,\n { urls: [''] },\n ['requestBody'],\n );\n\n chrome.webRequest.onSendHeaders.addListener(\n this.listeners.onSendHeaders,\n { urls: [''] },\n ['requestHeaders'],\n );\n\n chrome.webRequest.onHeadersReceived.addListener(\n this.listeners.onHeadersReceived,\n { urls: [''] },\n ['responseHeaders'],\n );\n\n chrome.webRequest.onCompleted.addListener(this.listeners.onCompleted, { urls: [''] });\n\n chrome.webRequest.onErrorOccurred.addListener(this.listeners.onErrorOccurred, {\n urls: [''],\n });\n }\n\n /**\n * Remove all request listeners\n * Only remove listeners when all tab captures have stopped\n */\n private removeListeners(): void {\n // Don't remove listeners if there are still tabs being captured\n if (this.captureData.size > 0) {\n console.log(\n `NetworkCaptureV2: Still capturing on ${this.captureData.size} tabs, not removing listeners.`,\n );\n return;\n }\n\n console.log(`NetworkCaptureV2: No more active captures, removing all listeners.`);\n\n if (this.listeners.onBeforeRequest) {\n chrome.webRequest.onBeforeRequest.removeListener(this.listeners.onBeforeRequest);\n }\n\n if (this.listeners.onSendHeaders) {\n chrome.webRequest.onSendHeaders.removeListener(this.listeners.onSendHeaders);\n }\n\n if (this.listeners.onHeadersReceived) {\n chrome.webRequest.onHeadersReceived.removeListener(this.listeners.onHeadersReceived);\n }\n\n if (this.listeners.onCompleted) {\n chrome.webRequest.onCompleted.removeListener(this.listeners.onCompleted);\n }\n\n if (this.listeners.onErrorOccurred) {\n chrome.webRequest.onErrorOccurred.removeListener(this.listeners.onErrorOccurred);\n }\n\n // Clear listener object\n this.listeners = {};\n }\n\n /**\n * Process request body data\n */\n private processRequestBody(requestBody: chrome.webRequest.WebRequestBody): string | undefined {\n if (requestBody.raw && requestBody.raw.length > 0) {\n return '[Binary data]';\n } else if (requestBody.formData) {\n return JSON.stringify(requestBody.formData);\n }\n return undefined;\n }\n\n /**\n * Start network request capture for specified tab\n * @param tabId Tab ID\n * @param options Capture options\n */\n private async startCaptureForTab(\n tabId: number,\n options: {\n maxCaptureTime: number;\n inactivityTimeout: number;\n includeStatic: boolean;\n },\n ): Promise {\n const { maxCaptureTime, inactivityTimeout, includeStatic } = options;\n\n // If already capturing, stop first\n if (this.captureData.has(tabId)) {\n console.log(\n `NetworkCaptureV2: Already capturing on tab ${tabId}. Stopping previous session.`,\n );\n await this.stopCapture(tabId);\n }\n\n try {\n // Get tab information\n const tab = await chrome.tabs.get(tabId);\n\n // Initialize capture data\n this.captureData.set(tabId, {\n tabId: tabId,\n tabUrl: tab.url || '',\n tabTitle: tab.title || '',\n startTime: Date.now(),\n requests: {},\n maxCaptureTime,\n inactivityTimeout,\n includeStatic,\n limitReached: false,\n });\n\n // Initialize request counter\n this.requestCounters.set(tabId, 0);\n\n // Set up listeners\n this.setupListeners();\n\n // Update last activity time\n this.updateLastActivityTime(tabId);\n\n console.log(\n `NetworkCaptureV2: Started capture for tab ${tabId} (${tab.url}). Max requests: ${NetworkCaptureStartTool.MAX_REQUESTS_PER_CAPTURE}, Max time: ${maxCaptureTime}ms, Inactivity: ${inactivityTimeout}ms.`,\n );\n\n // Set maximum capture time\n if (maxCaptureTime > 0) {\n this.captureTimers.set(\n tabId,\n setTimeout(async () => {\n console.log(\n `NetworkCaptureV2: Max capture time (${maxCaptureTime}ms) reached for tab ${tabId}.`,\n );\n await this.stopCapture(tabId);\n }, maxCaptureTime),\n );\n }\n } catch (error: any) {\n console.error(`NetworkCaptureV2: Error starting capture for tab ${tabId}:`, error);\n\n // Clean up resources\n if (this.captureData.has(tabId)) {\n this.cleanupCapture(tabId);\n }\n\n throw error;\n }\n }\n\n /**\n * Stop capture\n * @param tabId Tab ID\n */\n public async stopCapture(\n tabId: number,\n ): Promise<{ success: boolean; message?: string; data?: any }> {\n const captureInfo = this.captureData.get(tabId);\n if (!captureInfo) {\n console.log(`NetworkCaptureV2: No capture in progress for tab ${tabId}`);\n return { success: false, message: `No capture in progress for tab ${tabId}` };\n }\n\n try {\n // Record end time\n captureInfo.endTime = Date.now();\n\n // Extract common request and response headers\n const requestsArray = Object.values(captureInfo.requests);\n const commonRequestHeaders = this.analyzeCommonHeaders(requestsArray, 'requestHeaders');\n const commonResponseHeaders = this.analyzeCommonHeaders(requestsArray, 'responseHeaders');\n\n // Process request data, remove common headers\n const processedRequests = requestsArray.map((req) => {\n const finalReq: NetworkRequestInfo = { ...req };\n\n if (finalReq.requestHeaders) {\n finalReq.specificRequestHeaders = this.filterOutCommonHeaders(\n finalReq.requestHeaders,\n commonRequestHeaders,\n );\n delete finalReq.requestHeaders;\n } else {\n finalReq.specificRequestHeaders = {};\n }\n\n if (finalReq.responseHeaders) {\n finalReq.specificResponseHeaders = this.filterOutCommonHeaders(\n finalReq.responseHeaders,\n commonResponseHeaders,\n );\n delete finalReq.responseHeaders;\n } else {\n finalReq.specificResponseHeaders = {};\n }\n\n return finalReq;\n });\n\n // Sort by time\n processedRequests.sort((a, b) => (a.requestTime || 0) - (b.requestTime || 0));\n\n // Remove listeners\n this.removeListeners();\n\n // Prepare result data\n const resultData = {\n captureStartTime: captureInfo.startTime,\n captureEndTime: captureInfo.endTime,\n totalDurationMs: captureInfo.endTime - captureInfo.startTime,\n settingsUsed: {\n maxCaptureTime: captureInfo.maxCaptureTime,\n inactivityTimeout: captureInfo.inactivityTimeout,\n includeStatic: captureInfo.includeStatic,\n maxRequests: NetworkCaptureStartTool.MAX_REQUESTS_PER_CAPTURE,\n },\n commonRequestHeaders,\n commonResponseHeaders,\n requests: processedRequests,\n requestCount: processedRequests.length,\n totalRequestsReceived: this.requestCounters.get(tabId) || 0,\n requestLimitReached: captureInfo.limitReached || false,\n tabUrl: captureInfo.tabUrl,\n tabTitle: captureInfo.tabTitle,\n };\n\n // Clean up resources\n this.cleanupCapture(tabId);\n\n return {\n success: true,\n data: resultData,\n };\n } catch (error: any) {\n console.error(`NetworkCaptureV2: Error stopping capture for tab ${tabId}:`, error);\n\n // Ensure resources are cleaned up\n this.cleanupCapture(tabId);\n\n return {\n success: false,\n message: `Error stopping capture: ${error.message || String(error)}`,\n };\n }\n }\n\n /**\n * Analyze common request or response headers\n */\n private analyzeCommonHeaders(\n requests: NetworkRequestInfo[],\n headerType: 'requestHeaders' | 'responseHeaders',\n ): Record {\n if (!requests || requests.length === 0) return {};\n\n // Find headers that are included in all requests\n const commonHeaders: Record = {};\n const firstRequestWithHeaders = requests.find(\n (req) => req[headerType] && Object.keys(req[headerType] || {}).length > 0,\n );\n\n if (!firstRequestWithHeaders || !firstRequestWithHeaders[headerType]) {\n return {};\n }\n\n // Get all headers from the first request\n const headers = firstRequestWithHeaders[headerType] as Record;\n const headerNames = Object.keys(headers);\n\n // Check if each header exists in all requests with the same value\n for (const name of headerNames) {\n const value = headers[name];\n const isCommon = requests.every((req) => {\n const reqHeaders = req[headerType] as Record;\n return reqHeaders && reqHeaders[name] === value;\n });\n\n if (isCommon) {\n commonHeaders[name] = value;\n }\n }\n\n return commonHeaders;\n }\n\n /**\n * Filter out common headers\n */\n private filterOutCommonHeaders(\n headers: Record,\n commonHeaders: Record,\n ): Record {\n if (!headers || typeof headers !== 'object') return {};\n\n const specificHeaders: Record = {};\n // Use Object.keys to avoid ESLint no-prototype-builtins warning\n Object.keys(headers).forEach((name) => {\n if (!(name in commonHeaders) || headers[name] !== commonHeaders[name]) {\n specificHeaders[name] = headers[name];\n }\n });\n\n return specificHeaders;\n }\n\n async execute(args: NetworkCaptureStartToolParams): Promise {\n const {\n url: targetUrl,\n maxCaptureTime = 3 * 60 * 1000, // Default 3 minutes\n inactivityTimeout = 60 * 1000, // Default 1 minute of inactivity before auto-stop\n includeStatic = false, // Default: don't include static resources\n } = args;\n\n console.log(`NetworkCaptureStartTool: Executing with args:`, args);\n\n try {\n // Get current tab or create new tab\n let tabToOperateOn: chrome.tabs.Tab;\n\n if (targetUrl) {\n // Find tabs matching the URL\n const matchingTabs = await chrome.tabs.query({ url: targetUrl });\n\n if (matchingTabs.length > 0) {\n // Use existing tab\n tabToOperateOn = matchingTabs[0];\n console.log(`NetworkCaptureV2: Found existing tab with URL: ${targetUrl}`);\n } else {\n // Create new tab\n console.log(`NetworkCaptureV2: Creating new tab with URL: ${targetUrl}`);\n tabToOperateOn = await chrome.tabs.create({ url: targetUrl, active: true });\n\n // Wait for page to load\n await new Promise((resolve) => setTimeout(resolve, 1000));\n }\n } else {\n // Use current active tab\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!tabs[0]) {\n return createErrorResponse('No active tab found');\n }\n tabToOperateOn = tabs[0];\n }\n\n if (!tabToOperateOn?.id) {\n return createErrorResponse('Failed to identify or create a tab');\n }\n\n // Use startCaptureForTab method to start capture\n try {\n await this.startCaptureForTab(tabToOperateOn.id, {\n maxCaptureTime,\n inactivityTimeout,\n includeStatic,\n });\n } catch (error: any) {\n return createErrorResponse(\n `Failed to start capture for tab ${tabToOperateOn.id}: ${error.message || String(error)}`,\n );\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'Network capture V2 started successfully, waiting for stop command.',\n tabId: tabToOperateOn.id,\n url: tabToOperateOn.url,\n maxCaptureTime,\n inactivityTimeout,\n includeStatic,\n maxRequests: NetworkCaptureStartTool.MAX_REQUESTS_PER_CAPTURE,\n }),\n },\n ],\n isError: false,\n };\n } catch (error: any) {\n console.error('NetworkCaptureStartTool: Critical error:', error);\n return createErrorResponse(\n `Error in NetworkCaptureStartTool: ${error.message || String(error)}`,\n );\n }\n }\n}\n\n/**\n * Network capture stop tool V2 - Stop webRequest API capture and return results\n */\nclass NetworkCaptureStopTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.NETWORK_CAPTURE_STOP;\n public static instance: NetworkCaptureStopTool | null = null;\n\n constructor() {\n super();\n if (NetworkCaptureStopTool.instance) {\n return NetworkCaptureStopTool.instance;\n }\n NetworkCaptureStopTool.instance = this;\n }\n\n async execute(): Promise {\n console.log(`NetworkCaptureStopTool: Executing`);\n\n try {\n const startTool = NetworkCaptureStartTool.instance;\n\n if (!startTool) {\n return createErrorResponse('Network capture V2 start tool instance not found');\n }\n\n // Get all tabs currently capturing\n const ongoingCaptures = Array.from(startTool.captureData.keys());\n console.log(\n `NetworkCaptureStopTool: Found ${ongoingCaptures.length} ongoing captures: ${ongoingCaptures.join(', ')}`,\n );\n\n if (ongoingCaptures.length === 0) {\n return createErrorResponse('No active network captures found in any tab.');\n }\n\n // Get current active tab\n const activeTabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const activeTabId = activeTabs[0]?.id;\n\n // Determine the primary tab to stop\n let primaryTabId: number;\n\n if (activeTabId && startTool.captureData.has(activeTabId)) {\n // If current active tab is capturing, prioritize stopping it\n primaryTabId = activeTabId;\n console.log(\n `NetworkCaptureStopTool: Active tab ${activeTabId} is capturing, will stop it first.`,\n );\n } else if (ongoingCaptures.length === 1) {\n // If only one tab is capturing, stop it\n primaryTabId = ongoingCaptures[0];\n console.log(\n `NetworkCaptureStopTool: Only one tab ${primaryTabId} is capturing, stopping it.`,\n );\n } else {\n // If multiple tabs are capturing but current active tab is not among them, stop the first one\n primaryTabId = ongoingCaptures[0];\n console.log(\n `NetworkCaptureStopTool: Multiple tabs capturing, active tab not among them. Stopping tab ${primaryTabId} first.`,\n );\n }\n\n const stopResult = await startTool.stopCapture(primaryTabId);\n\n if (!stopResult.success) {\n return createErrorResponse(\n stopResult.message || `Failed to stop network capture for tab ${primaryTabId}`,\n );\n }\n\n // If multiple tabs are capturing, stop other tabs\n if (ongoingCaptures.length > 1) {\n const otherTabIds = ongoingCaptures.filter((id) => id !== primaryTabId);\n console.log(\n `NetworkCaptureStopTool: Stopping ${otherTabIds.length} additional captures: ${otherTabIds.join(', ')}`,\n );\n\n for (const tabId of otherTabIds) {\n try {\n await startTool.stopCapture(tabId);\n } catch (error) {\n console.error(`NetworkCaptureStopTool: Error stopping capture on tab ${tabId}:`, error);\n }\n }\n }\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: `Capture complete. ${stopResult.data?.requestCount || 0} requests captured.`,\n tabId: primaryTabId,\n tabUrl: stopResult.data?.tabUrl || 'N/A',\n tabTitle: stopResult.data?.tabTitle || 'Unknown Tab',\n requestCount: stopResult.data?.requestCount || 0,\n commonRequestHeaders: stopResult.data?.commonRequestHeaders || {},\n commonResponseHeaders: stopResult.data?.commonResponseHeaders || {},\n requests: stopResult.data?.requests || [],\n captureStartTime: stopResult.data?.captureStartTime,\n captureEndTime: stopResult.data?.captureEndTime,\n totalDurationMs: stopResult.data?.totalDurationMs,\n settingsUsed: stopResult.data?.settingsUsed || {},\n totalRequestsReceived: stopResult.data?.totalRequestsReceived || 0,\n requestLimitReached: stopResult.data?.requestLimitReached || false,\n remainingCaptures: Array.from(startTool.captureData.keys()),\n }),\n },\n ],\n isError: false,\n };\n } catch (error: any) {\n console.error('NetworkCaptureStopTool: Critical error:', error);\n return createErrorResponse(\n `Error in NetworkCaptureStopTool: ${error.message || String(error)}`,\n );\n }\n }\n}\n\nexport const networkCaptureStartTool = new NetworkCaptureStartTool();\nexport const networkCaptureStopTool = new NetworkCaptureStopTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { networkCaptureStartTool, networkCaptureStopTool } from './network-capture-web-request';\nimport { networkDebuggerStartTool, networkDebuggerStopTool } from './network-capture-debugger';\n\ntype NetworkCaptureBackend = 'webRequest' | 'debugger';\n\ninterface NetworkCaptureToolParams {\n action: 'start' | 'stop';\n needResponseBody?: boolean;\n url?: string;\n maxCaptureTime?: number;\n inactivityTimeout?: number;\n includeStatic?: boolean;\n}\n\n/**\n * Extract text content from ToolResult\n */\nfunction getFirstText(result: ToolResult): string | undefined {\n const first = result.content?.[0];\n return first && first.type === 'text' ? first.text : undefined;\n}\n\n/**\n * Decorate JSON result with additional fields\n */\nfunction decorateJsonResult(result: ToolResult, extra: Record): ToolResult {\n const text = getFirstText(result);\n if (typeof text !== 'string') return result;\n\n try {\n const parsed = JSON.parse(text);\n if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n return {\n ...result,\n content: [{ type: 'text', text: JSON.stringify({ ...parsed, ...extra }) }],\n };\n }\n } catch {\n // If the underlying tool didn't return JSON, keep it as-is\n }\n return result;\n}\n\n/**\n * Check if debugger-based capture is active\n */\nfunction isDebuggerCaptureActive(): boolean {\n const captureData = (\n networkDebuggerStartTool as unknown as { captureData?: Map }\n ).captureData;\n return captureData instanceof Map && captureData.size > 0;\n}\n\n/**\n * Check if webRequest-based capture is active\n */\nfunction isWebRequestCaptureActive(): boolean {\n return networkCaptureStartTool.captureData.size > 0;\n}\n\n/**\n * Unified Network Capture Tool\n *\n * Provides a single entry point for network capture, automatically selecting\n * the appropriate backend based on the `needResponseBody` parameter:\n * - needResponseBody=false (default): uses webRequest API (lightweight, no debugger conflict)\n * - needResponseBody=true: uses Debugger API (captures response body, may conflict with DevTools)\n */\nclass NetworkCaptureTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.NETWORK_CAPTURE;\n\n async execute(args: NetworkCaptureToolParams): Promise {\n const action = args?.action;\n if (action !== 'start' && action !== 'stop') {\n return createErrorResponse('Parameter [action] is required and must be one of: start, stop');\n }\n\n const wantBody = args?.needResponseBody === true;\n const debuggerActive = isDebuggerCaptureActive();\n const webActive = isWebRequestCaptureActive();\n\n if (action === 'start') {\n return this.handleStart(args, wantBody, debuggerActive, webActive);\n }\n\n return this.handleStop(args, debuggerActive, webActive);\n }\n\n private async handleStart(\n args: NetworkCaptureToolParams,\n wantBody: boolean,\n debuggerActive: boolean,\n webActive: boolean,\n ): Promise {\n // Prevent any capture conflict (cross-mode or same-mode)\n if (debuggerActive || webActive) {\n const activeMode = debuggerActive ? 'debugger' : 'webRequest';\n return createErrorResponse(\n `Network capture is already active in ${activeMode} mode. Stop it before starting a new capture.`,\n );\n }\n\n const delegate = wantBody ? networkDebuggerStartTool : networkCaptureStartTool;\n const backend: NetworkCaptureBackend = wantBody ? 'debugger' : 'webRequest';\n\n const result = await delegate.execute({\n url: args.url,\n maxCaptureTime: args.maxCaptureTime,\n inactivityTimeout: args.inactivityTimeout,\n includeStatic: args.includeStatic,\n });\n\n return decorateJsonResult(result, { backend, needResponseBody: wantBody });\n }\n\n private async handleStop(\n args: NetworkCaptureToolParams,\n debuggerActive: boolean,\n webActive: boolean,\n ): Promise {\n // Determine which backend to stop\n let backendToStop: NetworkCaptureBackend | null = null;\n\n // If user explicitly specified needResponseBody, try to stop that specific backend\n if (args?.needResponseBody === true) {\n backendToStop = debuggerActive ? 'debugger' : null;\n } else if (args?.needResponseBody === false) {\n backendToStop = webActive ? 'webRequest' : null;\n }\n\n // If no explicit preference or the specified backend isn't active, auto-detect\n if (!backendToStop) {\n if (debuggerActive) {\n backendToStop = 'debugger';\n } else if (webActive) {\n backendToStop = 'webRequest';\n }\n }\n\n if (!backendToStop) {\n return createErrorResponse('No active network captures found in any tab.');\n }\n\n const delegateStop =\n backendToStop === 'debugger' ? networkDebuggerStopTool : networkCaptureStopTool;\n const result = await delegateStop.execute();\n\n return decorateJsonResult(result, {\n backend: backendToStop,\n needResponseBody: backendToStop === 'debugger',\n });\n }\n}\n\nexport const networkCaptureTool = new NetworkCaptureTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/network-request.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\n\nconst DEFAULT_NETWORK_REQUEST_TIMEOUT = 30000; // For sending a single request via content script\n\ninterface NetworkRequestToolParams {\n url: string; // URL is always required\n method?: string; // Defaults to GET\n headers?: Record; // User-provided headers\n body?: any; // User-provided body\n timeout?: number; // Timeout for the network request itself\n // Optional multipart/form-data descriptor. When provided, overrides body and lets the helper build FormData.\n // Shape: { fields?: Record, files?: Array<{ name: string, fileUrl?: string, filePath?: string, base64Data?: string, filename?: string, contentType?: string }> }\n // Or a compact array: [ [name, fileSpec, filename?], ... ] where fileSpec can be 'url:...', 'file:/abs/path', 'base64:...'\n formData?: any;\n}\n\n/**\n * NetworkRequestTool - Sends network requests based on provided parameters.\n */\nclass NetworkRequestTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.NETWORK_REQUEST;\n\n async execute(args: NetworkRequestToolParams): Promise {\n const {\n url,\n method = 'GET',\n headers = {},\n body,\n timeout = DEFAULT_NETWORK_REQUEST_TIMEOUT,\n } = args;\n\n console.log(`NetworkRequestTool: Executing with options:`, args);\n\n if (!url) {\n return createErrorResponse('URL parameter is required.');\n }\n\n try {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!tabs[0]?.id) {\n return createErrorResponse('No active tab found or tab has no ID.');\n }\n const activeTabId = tabs[0].id;\n\n // Ensure content script is available in the target tab\n await this.injectContentScript(activeTabId, ['inject-scripts/network-helper.js']);\n\n console.log(\n `NetworkRequestTool: Sending to content script: URL=${url}, Method=${method}, Headers=${Object.keys(headers).join(',')}, BodyType=${typeof body}`,\n );\n\n const resultFromContentScript = await this.sendMessageToTab(activeTabId, {\n action: TOOL_MESSAGE_TYPES.NETWORK_SEND_REQUEST,\n url: url,\n method: method,\n headers: headers,\n body: body,\n formData: args.formData || null,\n timeout: timeout,\n });\n\n console.log(`NetworkRequestTool: Response from content script:`, resultFromContentScript);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(resultFromContentScript),\n },\n ],\n isError: !resultFromContentScript?.success,\n };\n } catch (error: any) {\n console.error('NetworkRequestTool: Error sending network request:', error);\n return createErrorResponse(\n `Error sending network request: ${error.message || String(error)}`,\n );\n }\n }\n}\n\nexport const networkRequestTool = new NetworkRequestTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/performance.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\n\ntype OwnerTag = 'performance';\n\ninterface StartTraceParams {\n reload?: boolean; // whether to reload the page after starting trace\n autoStop?: boolean; // whether to auto stop after a short duration\n durationMs?: number; // custom duration when autoStop is true (default 5000)\n}\n\ninterface StopTraceParams {\n saveToDownloads?: boolean; // save trace to Downloads as JSON (default true)\n filenamePrefix?: string; // filename prefix (default 'performance_trace')\n}\n\ninterface AnalyzeInsightParams {\n insightName?: string; // placeholder for future deep insights\n}\n\ntype DebuggeeEvent = (source: chrome.debugger.Debuggee, method: string, params?: any) => void;\n\ninterface TraceSessionState {\n recording: boolean;\n events: any[];\n startedAt: number;\n pageUrl?: string;\n listener: DebuggeeEvent;\n stopResolver?: (value: { completed: boolean }) => void;\n stopPromise?: Promise<{ completed: boolean }>;\n}\n\nconst sessions = new Map();\nconst LAST_RESULTS = new Map<\n number,\n {\n events: any[];\n startedAt: number;\n endedAt: number;\n tabUrl: string;\n saved?: { downloadId?: number; filename?: string; fullPath?: string };\n metrics?: Record;\n }\n>();\n\nfunction tracingCategories(): string[] {\n // Keep broadly consistent with other project\n return [\n '-*',\n 'blink.console',\n 'blink.user_timing',\n 'devtools.timeline',\n 'disabled-by-default-devtools.screenshot',\n 'disabled-by-default-devtools.timeline',\n 'disabled-by-default-devtools.timeline.invalidationTracking',\n 'disabled-by-default-devtools.timeline.frame',\n 'disabled-by-default-devtools.timeline.stack',\n 'disabled-by-default-v8.cpu_profiler',\n 'disabled-by-default-v8.cpu_profiler.hires',\n 'latencyInfo',\n 'loading',\n 'disabled-by-default-lighthouse',\n 'v8.execute',\n 'v8',\n ];\n}\n\nasync function enablePerformanceMetrics(tabId: number): Promise> {\n try {\n await cdpSessionManager.sendCommand(tabId, 'Performance.enable');\n const result = (await cdpSessionManager.sendCommand(tabId, 'Performance.getMetrics')) as {\n metrics: Array<{ name: string; value: number }>;\n };\n await cdpSessionManager.sendCommand(tabId, 'Performance.disable');\n const map: Record = {};\n for (const m of result.metrics || []) map[m.name] = m.value;\n return map;\n } catch (e) {\n return {};\n }\n}\n\nasync function saveTraceToDownloads(\n json: string,\n filenamePrefix = 'performance_trace',\n): Promise<{ downloadId?: number; filename?: string; fullPath?: string }> {\n try {\n const timestamp = new Date().toISOString().replace(/[:.]/g, '-');\n const filename = `${filenamePrefix}_${timestamp}.json`;\n const dataUrl = `data:application/json;base64,${btoa(unescape(encodeURIComponent(json)))}`;\n const downloadId = await chrome.downloads.download({ url: dataUrl, filename, saveAs: false });\n // Attempt to resolve full path\n try {\n await new Promise((r) => setTimeout(r, 120));\n const [item] = await chrome.downloads.search({ id: downloadId });\n return { downloadId, filename, fullPath: item?.filename };\n } catch {\n return { downloadId, filename };\n }\n } catch {\n return {};\n }\n}\n\nasync function saveTraceToNativeTemp(\n json: string,\n filenamePrefix = 'performance_trace',\n): Promise<{ filename?: string; fullPath?: string } | undefined> {\n try {\n const timestamp = new Date().toISOString().replace(/[:.]/g, '-');\n const filename = `${filenamePrefix}_${timestamp}.json`;\n const base64 = btoa(unescape(encodeURIComponent(json)));\n\n const requestId = `trace-temp-${Date.now()}-${Math.random().toString(36).slice(2)}`;\n const timeoutMs = 30000;\n const resp = await new Promise((resolve, reject) => {\n const timer = setTimeout(() => {\n chrome.runtime.onMessage.removeListener(listener);\n reject(new Error('Native temp save timed out'));\n }, timeoutMs);\n const listener = (message: any) => {\n if (\n message &&\n message.type === 'file_operation_response' &&\n message.responseToRequestId === requestId\n ) {\n clearTimeout(timer);\n chrome.runtime.onMessage.removeListener(listener);\n resolve(message.payload);\n }\n };\n chrome.runtime.onMessage.addListener(listener);\n chrome.runtime\n .sendMessage({\n type: 'forward_to_native',\n message: {\n type: 'file_operation',\n requestId,\n payload: {\n action: 'prepareFile',\n base64Data: base64,\n fileName: filename,\n },\n },\n })\n .catch((err) => {\n clearTimeout(timer);\n chrome.runtime.onMessage.removeListener(listener);\n reject(err);\n });\n });\n\n if (resp && resp.success && resp.filePath) {\n return { filename, fullPath: resp.filePath };\n }\n } catch {\n // ignore, fallback will apply\n }\n return undefined;\n}\n\nasync function cleanupNativeTempFile(filePath: string): Promise {\n if (!filePath) return;\n try {\n const requestId = `trace-clean-${Date.now()}-${Math.random().toString(36).slice(2)}`;\n const timeoutMs = 10000;\n await new Promise((resolve) => {\n const timer = setTimeout(() => {\n chrome.runtime.onMessage.removeListener(listener);\n resolve(); // best-effort\n }, timeoutMs);\n const listener = (message: any) => {\n if (\n message &&\n message.type === 'file_operation_response' &&\n message.responseToRequestId === requestId\n ) {\n clearTimeout(timer);\n chrome.runtime.onMessage.removeListener(listener);\n resolve();\n }\n };\n chrome.runtime.onMessage.addListener(listener);\n chrome.runtime\n .sendMessage({\n type: 'forward_to_native',\n message: {\n type: 'file_operation',\n requestId,\n payload: {\n action: 'cleanupFile',\n filePath,\n },\n },\n })\n .catch(() => {\n clearTimeout(timer);\n chrome.runtime.onMessage.removeListener(listener);\n resolve();\n });\n });\n } catch {\n // ignore\n }\n}\n\nfunction getOrCreateStopPromise(session: TraceSessionState): Promise<{ completed: boolean }> {\n if (session.stopPromise) return session.stopPromise;\n session.stopPromise = new Promise((resolve) => {\n session.stopResolver = resolve;\n });\n return session.stopPromise;\n}\n\n/**\n * Start performance trace\n */\nclass PerformanceStartTraceTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.PERFORMANCE_START_TRACE;\n\n async execute(args: StartTraceParams): Promise {\n const { reload = false, autoStop = false, durationMs = 5000 } = args || {};\n\n try {\n const [activeTab] = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!activeTab?.id) {\n return createErrorResponse('No active tab found');\n }\n const tabId = activeTab.id;\n const existed = sessions.get(tabId);\n if (existed?.recording) {\n return {\n content: [{ type: 'text', text: 'Error: a performance trace is already running.' }],\n isError: false,\n };\n }\n\n await cdpSessionManager.attach(tabId, 'performance');\n\n const state: TraceSessionState = {\n recording: true,\n events: [],\n startedAt: Date.now(),\n pageUrl: activeTab.url || '',\n listener: (source, method, params) => {\n if (source.tabId !== tabId) return;\n if (method === 'Tracing.dataCollected' && params?.value) {\n try {\n state.events.push(...(params.value as any[]));\n } catch {\n // ignore\n }\n } else if (method === 'Tracing.tracingComplete') {\n state.recording = false;\n state.stopResolver?.({ completed: true });\n }\n },\n };\n chrome.debugger.onEvent.addListener(state.listener);\n sessions.set(tabId, state);\n\n // Start tracing with categories\n const cats = tracingCategories().join(',');\n await cdpSessionManager.sendCommand(tabId, 'Tracing.start', {\n categories: cats,\n options: 'record-as-much-as-possible',\n transferMode: 'ReportEvents',\n });\n\n if (reload) {\n try {\n await cdpSessionManager.sendCommand(tabId, 'Page.reload', { ignoreCache: true });\n } catch {\n // best effort; ignore if fails\n }\n }\n\n if (autoStop) {\n setTimeout(\n async () => {\n try {\n await cdpSessionManager.sendCommand(tabId, 'Tracing.end');\n } catch {\n // ignore\n }\n },\n Math.max(1000, Math.min(durationMs, 60000)),\n );\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'Performance trace is recording. Use performance_stop_trace to stop it.',\n reload,\n autoStop,\n }),\n },\n ],\n isError: false,\n };\n } catch (e: any) {\n return createErrorResponse(`Failed to start performance trace: ${e?.message || e}`);\n }\n }\n}\n\n/**\n * Stop performance trace\n */\nclass PerformanceStopTraceTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.PERFORMANCE_STOP_TRACE;\n\n async execute(args: StopTraceParams): Promise {\n const { saveToDownloads = true, filenamePrefix } = args || {};\n try {\n const [activeTab] = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!activeTab?.id) return createErrorResponse('No active tab found');\n const tabId = activeTab.id;\n const session = sessions.get(tabId);\n if (!session) {\n return {\n content: [\n { type: 'text', text: 'No performance trace session found for the current tab.' },\n ],\n isError: false,\n };\n }\n\n let stopResult: { completed: boolean } = { completed: false };\n if (session.recording) {\n // End tracing and wait for completion signal\n await cdpSessionManager.sendCommand(tabId, 'Tracing.end');\n await getOrCreateStopPromise(session);\n stopResult = await session.stopPromise!;\n } else {\n // Already auto-stopped; proceed to finalize without waiting\n stopResult = { completed: true };\n }\n // Fetch metrics before detach\n const metrics = await enablePerformanceMetrics(tabId);\n\n // Cleanup event listener and detach\n try {\n chrome.debugger.onEvent.removeListener(session.listener);\n } catch {\n // ignore\n }\n try {\n await cdpSessionManager.detach(tabId, 'performance');\n } catch {\n // ignore\n }\n\n const endedAt = Date.now();\n const trace = { traceEvents: session.events };\n const json = JSON.stringify(trace);\n\n let saved: { downloadId?: number; filename?: string; fullPath?: string } | undefined;\n if (saveToDownloads) {\n saved = await saveTraceToDownloads(json, filenamePrefix || 'performance_trace');\n } else {\n // Persist to native temp directory so that analysis can run without Downloads permission\n const tempSaved = await saveTraceToNativeTemp(json, filenamePrefix || 'performance_trace');\n if (tempSaved) {\n saved = { ...tempSaved } as any;\n }\n }\n\n LAST_RESULTS.set(tabId, {\n events: session.events,\n startedAt: session.startedAt,\n endedAt,\n tabUrl: session.pageUrl || '',\n saved,\n metrics,\n });\n\n sessions.delete(tabId);\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: 'The performance trace has been stopped.',\n eventCount: session.events.length,\n saved,\n metrics,\n startedAt: session.startedAt,\n endedAt,\n durationMs: endedAt - session.startedAt,\n url: session.pageUrl || '',\n tracingCompleted: stopResult?.completed === true,\n }),\n },\n ],\n isError: false,\n };\n } catch (e: any) {\n return createErrorResponse(`Failed to stop performance trace: ${e?.message || e}`);\n }\n }\n}\n\n/**\n * Analyze last trace (lightweight)\n * Note: Deep insights require DevTools front-end trace engine on the native side; this is a\n * pragmatic first step returning basic metrics and a quick event histogram.\n */\nclass PerformanceAnalyzeInsightTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.PERFORMANCE_ANALYZE_INSIGHT;\n\n async execute(args: AnalyzeInsightParams & { timeoutMs?: number }): Promise {\n const { insightName } = args || {};\n try {\n const [activeTab] = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!activeTab?.id) return createErrorResponse('No active tab found');\n const tabId = activeTab.id;\n const result = LAST_RESULTS.get(tabId);\n if (!result) {\n return {\n content: [\n {\n type: 'text',\n text: 'No recorded traces found. Start and stop a performance trace first.',\n },\n ],\n isError: false,\n };\n }\n\n // Prefer native-side deep analysis when we have a saved file path\n const fullPath = (result.saved && (result.saved as any).fullPath) || undefined;\n if (fullPath) {\n try {\n const requestId = `trace-analyze-${Date.now()}-${Math.random().toString(36).slice(2)}`;\n const timeoutMs = Math.max(10000, Math.min((args as any)?.timeoutMs ?? 60000, 300000));\n const resp = await new Promise((resolve, reject) => {\n const timer = setTimeout(() => {\n chrome.runtime.onMessage.removeListener(listener);\n reject(new Error('Native trace analysis timed out'));\n }, timeoutMs);\n const listener = (message: any) => {\n if (\n message &&\n message.type === 'file_operation_response' &&\n message.responseToRequestId === requestId\n ) {\n clearTimeout(timer);\n chrome.runtime.onMessage.removeListener(listener);\n resolve(message.payload);\n }\n };\n chrome.runtime.onMessage.addListener(listener);\n chrome.runtime\n .sendMessage({\n type: 'forward_to_native',\n message: {\n type: 'file_operation',\n requestId,\n payload: { action: 'analyzeTrace', traceFilePath: fullPath, insightName },\n },\n })\n .catch((err) => {\n clearTimeout(timer);\n chrome.runtime.onMessage.removeListener(listener);\n reject(err);\n });\n });\n if (resp && resp.success) {\n // Best-effort cleanup for temp files (Downloads paths are ignored by native cleaner)\n await cleanupNativeTempFile(fullPath);\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n url: result.tabUrl,\n startedAt: result.startedAt,\n endedAt: result.endedAt,\n durationMs: result.endedAt - result.startedAt,\n metrics: result.metrics || {},\n saved: result.saved,\n summary: resp.summary,\n insight: resp.insight,\n }),\n },\n ],\n isError: false,\n };\n }\n // If native returned error, fall through to lightweight analysis\n } catch (e) {\n // Fallback to lightweight analysis below\n }\n }\n\n // Lightweight fallback (when no saved file path)\n const counts = new Map();\n for (const ev of result.events.slice(0, 100000)) {\n const n = typeof (ev as any)?.name === 'string' ? (ev as any).name : 'unknown';\n counts.set(n, (counts.get(n) || 0) + 1);\n }\n const top = [...counts.entries()]\n .sort((a, b) => b[1] - a[1])\n .slice(0, 20)\n .map(([name, count]) => ({ name, count }));\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n info: 'Lightweight analysis (no saved file path). Native-side deep analysis unavailable.',\n requestedInsight: insightName || null,\n url: result.tabUrl,\n startedAt: result.startedAt,\n endedAt: result.endedAt,\n durationMs: result.endedAt - result.startedAt,\n metrics: result.metrics || {},\n topEventNames: top,\n saved: result.saved,\n }),\n },\n ],\n isError: false,\n };\n } catch (e: any) {\n return createErrorResponse(`Failed to analyze trace: ${e?.message || e}`);\n }\n }\n}\n\nexport const performanceStartTraceTool = new PerformanceStartTraceTool();\nexport const performanceStopTraceTool = new PerformanceStopTraceTool();\nexport const performanceAnalyzeInsightTool = new PerformanceAnalyzeInsightTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/read-page.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport { ERROR_MESSAGES } from '@/common/constants';\nimport { listMarkersForUrl } from '@/entrypoints/background/element-marker/element-marker-storage';\n\ninterface ReadPageStats {\n processed: number;\n included: number;\n durationMs: number;\n}\n\ninterface ReadPageParams {\n filter?: 'interactive'; // when omitted, return all visible elements\n depth?: number; // maximum DOM depth to traverse (0 = root only)\n refId?: string; // focus on subtree rooted at this refId\n tabId?: number; // target existing tab id\n windowId?: number; // when no tabId, pick active tab from this window\n}\n\nclass ReadPageTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.READ_PAGE;\n\n // Execute read page\n async execute(args: ReadPageParams): Promise {\n const { filter, depth, refId } = args || {};\n\n // Validate refId parameter\n const focusRefId = typeof refId === 'string' ? refId.trim() : '';\n if (refId !== undefined && !focusRefId) {\n return createErrorResponse(\n `${ERROR_MESSAGES.INVALID_PARAMETERS}: refId must be a non-empty string`,\n );\n }\n\n // Validate depth parameter\n const requestedDepth = depth === undefined ? undefined : Number(depth);\n if (requestedDepth !== undefined && (!Number.isInteger(requestedDepth) || requestedDepth < 0)) {\n return createErrorResponse(\n `${ERROR_MESSAGES.INVALID_PARAMETERS}: depth must be a non-negative integer`,\n );\n }\n\n // Track if user explicitly controlled the output (skip sparse heuristics)\n const userControlled = requestedDepth !== undefined || !!focusRefId;\n\n try {\n // Tip text returned to callers to guide next action\n const standardTips =\n \"If the specific element you need is missing from the returned data, use the 'screenshot' tool to capture the current viewport and confirm the element's on-screen coordinates. Also note: 'markedElements' are user-marked elements and have the highest priority when choosing targets.\";\n\n const explicit = await this.tryGetTab(args?.tabId);\n const tab = explicit || (await this.getActiveTabOrThrowInWindow(args?.windowId));\n if (!tab.id)\n return createErrorResponse(ERROR_MESSAGES.TAB_NOT_FOUND + ': Active tab has no ID');\n\n // Load any user-marked elements for this URL (priority hints)\n const currentUrl = String(tab.url || '');\n const userMarkers = currentUrl ? await listMarkersForUrl(currentUrl) : [];\n\n // Inject helper in ISOLATED world to enable chrome.runtime messaging\n // Inject into all frames to support same-origin iframe operations\n await this.injectContentScript(\n tab.id,\n ['inject-scripts/accessibility-tree-helper.js'],\n false,\n 'ISOLATED',\n true,\n );\n\n // Ask content script to generate accessibility tree\n const resp = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.GENERATE_ACCESSIBILITY_TREE,\n filter: filter || null,\n depth: requestedDepth,\n refId: focusRefId || undefined,\n });\n\n // Evaluate tree result and decide whether to fallback\n const treeOk = resp && resp.success === true;\n const pageContent: string =\n resp && typeof resp.pageContent === 'string' ? resp.pageContent : '';\n\n // Extract stats from response\n const stats: ReadPageStats | null =\n treeOk && resp?.stats\n ? {\n processed: resp.stats.processed ?? 0,\n included: resp.stats.included ?? 0,\n durationMs: resp.stats.durationMs ?? 0,\n }\n : null;\n\n const lines = pageContent\n ? pageContent.split('\\n').filter((l: string) => l.trim().length > 0).length\n : 0;\n const refCount = Array.isArray(resp?.refMap) ? resp.refMap.length : 0;\n\n // Skip sparse heuristics when user explicitly controls output\n const isSparse = !userControlled && lines < 10 && refCount < 3;\n\n // Build user-marked elements for inclusion\n const markedElements = userMarkers.map((m) => ({\n name: m.name,\n selector: m.selector,\n selectorType: m.selectorType || 'css',\n urlMatch: { type: m.matchType, origin: m.origin, path: m.path },\n source: 'marker',\n priority: 'highest',\n }));\n\n // Helper to convert elements array to pageContent format\n const formatElementsAsPageContent = (elements: any[]): string => {\n const out: string[] = [];\n for (const e of elements || []) {\n const type = typeof e?.type === 'string' && e.type ? e.type : 'element';\n const rawText = typeof e?.text === 'string' ? e.text.trim() : '';\n const text =\n rawText.length > 0\n ? ` \"${rawText.replace(/\\s+/g, ' ').slice(0, 100).replace(/\"/g, '\\\\\"')}\"`\n : '';\n const selector =\n typeof e?.selector === 'string' && e.selector ? ` selector=\"${e.selector}\"` : '';\n const coords =\n e?.coordinates && Number.isFinite(e.coordinates.x) && Number.isFinite(e.coordinates.y)\n ? ` (x=${Math.round(e.coordinates.x)},y=${Math.round(e.coordinates.y)})`\n : '';\n out.push(`- ${type}${text}${selector}${coords}`);\n if (out.length >= 150) break;\n }\n return out.join('\\n');\n };\n\n // Unified base payload structure - consistent keys for stable contract\n const basePayload: Record = {\n success: true,\n filter: filter || 'all',\n pageContent,\n tips: standardTips,\n viewport: treeOk ? resp.viewport : { width: null, height: null, dpr: null },\n stats: stats || { processed: 0, included: 0, durationMs: 0 },\n refMapCount: refCount,\n sparse: treeOk ? isSparse : false,\n depth: requestedDepth ?? null,\n focus: focusRefId ? { refId: focusRefId, found: treeOk } : null,\n markedElements,\n elements: [],\n count: 0,\n fallbackUsed: false,\n fallbackSource: null,\n reason: null,\n };\n\n // Normal path: return tree\n if (treeOk && !isSparse) {\n return {\n content: [{ type: 'text', text: JSON.stringify(basePayload) }],\n isError: false,\n };\n }\n\n // When refId is explicitly provided, do not fallback (refs are frame-local and may expire)\n if (focusRefId) {\n return createErrorResponse(resp?.error || `refId \"${focusRefId}\" not found or expired`);\n }\n\n // When user explicitly controls depth, do not override with fallback heuristics\n if (requestedDepth !== undefined) {\n return createErrorResponse(resp?.error || 'Failed to generate accessibility tree');\n }\n\n // Fallback path: try get_interactive_elements once\n try {\n await this.injectContentScript(tab.id, ['inject-scripts/interactive-elements-helper.js']);\n const fallback = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.GET_INTERACTIVE_ELEMENTS,\n includeCoordinates: true,\n });\n\n if (fallback && fallback.success && Array.isArray(fallback.elements)) {\n const limited = fallback.elements.slice(0, 150);\n // Merge user markers at the front, de-duplicated by selector\n const markerEls = userMarkers.map((m) => ({\n type: 'marker',\n selector: m.selector,\n text: m.name,\n selectorType: m.selectorType || 'css',\n isInteractive: true,\n source: 'marker',\n priority: 'highest',\n }));\n const seen = new Set(markerEls.map((e) => e.selector));\n const merged = [...markerEls, ...limited.filter((e: any) => !seen.has(e.selector))];\n\n basePayload.fallbackUsed = true;\n basePayload.fallbackSource = 'get_interactive_elements';\n basePayload.reason = treeOk ? 'sparse_tree' : resp?.error || 'tree_failed';\n basePayload.elements = merged;\n basePayload.count = fallback.elements.length;\n if (!basePayload.pageContent) {\n basePayload.pageContent = formatElementsAsPageContent(merged);\n }\n\n return {\n content: [{ type: 'text', text: JSON.stringify(basePayload) }],\n isError: false,\n };\n }\n } catch (fallbackErr) {\n console.warn('read_page fallback failed:', fallbackErr);\n }\n\n // If we reach here, both tree (usable) and fallback failed\n return createErrorResponse(\n treeOk\n ? 'Accessibility tree is too sparse and fallback failed'\n : resp?.error || 'Failed to generate accessibility tree and fallback failed',\n );\n } catch (error) {\n console.error('Error in read page tool:', error);\n return createErrorResponse(\n `Error generating accessibility tree: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const readPageTool = new ReadPageTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport {\n canvasToDataURL,\n createImageBitmapFromUrl,\n cropAndResizeImage,\n stitchImages,\n compressImage,\n} from '../../../../utils/image-utils';\nimport { screenshotContextManager } from '@/utils/screenshot-context';\n\n// Screenshot-specific constants\nconst SCREENSHOT_CONSTANTS = {\n SCROLL_DELAY_MS: 350, // Time to wait after scroll for rendering and lazy loading\n CAPTURE_STITCH_DELAY_MS: 50, // Small delay between captures in a scroll sequence\n MAX_CAPTURE_PARTS: 50, // Maximum number of parts to capture (for infinite scroll pages)\n MAX_CAPTURE_HEIGHT_PX: 50000, // Maximum height in pixels to capture\n PIXEL_TOLERANCE: 1,\n SCRIPT_INIT_DELAY: 100, // Delay for script initialization\n} as {\n readonly SCROLL_DELAY_MS: number;\n CAPTURE_STITCH_DELAY_MS: number; // This one is mutable\n readonly MAX_CAPTURE_PARTS: number;\n readonly MAX_CAPTURE_HEIGHT_PX: number;\n readonly PIXEL_TOLERANCE: number;\n readonly SCRIPT_INIT_DELAY: number;\n};\n\n// Adjust CAPTURE_STITCH_DELAY_MS to respect Chrome's capture rate if available in runtime\n// Some TS typings don't expose MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND; use a safe cast with a sane fallback.\nconst __MAX_CAP_RATE: number | undefined = (chrome.tabs as any)\n ?.MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND;\nif (typeof __MAX_CAP_RATE === 'number' && __MAX_CAP_RATE > 0) {\n // Minimum interval between consecutive captureVisibleTab calls (ms)\n const minIntervalMs = Math.ceil(1000 / __MAX_CAP_RATE);\n // Our capture loop already waits SCROLL_DELAY_MS between scroll and capture; add any extra delay needed\n const requiredExtraDelay = Math.max(0, minIntervalMs - SCREENSHOT_CONSTANTS.SCROLL_DELAY_MS);\n SCREENSHOT_CONSTANTS.CAPTURE_STITCH_DELAY_MS = Math.max(\n requiredExtraDelay,\n SCREENSHOT_CONSTANTS.CAPTURE_STITCH_DELAY_MS,\n );\n}\n\ninterface ScreenshotToolParams {\n name: string;\n selector?: string;\n tabId?: number;\n background?: boolean;\n windowId?: number;\n width?: number;\n height?: number;\n storeBase64?: boolean;\n fullPage?: boolean;\n savePng?: boolean;\n maxHeight?: number; // Maximum height to capture in pixels (for infinite scroll pages)\n}\n\n/** Page details returned by screenshot-helper content script */\ninterface ScreenshotPageDetails {\n totalWidth: number;\n totalHeight: number;\n viewportWidth: number;\n viewportHeight: number;\n devicePixelRatio: number;\n currentScrollX: number;\n currentScrollY: number;\n}\n\nconst PAGE_DETAILS_REQUIRED_FIELDS: Array = [\n 'totalWidth',\n 'totalHeight',\n 'viewportWidth',\n 'viewportHeight',\n 'devicePixelRatio',\n 'currentScrollX',\n 'currentScrollY',\n];\n\n/**\n * Validates and asserts that the response from content script contains valid page details\n */\nfunction assertValidPageDetails(details: unknown): ScreenshotPageDetails {\n if (!details || typeof details !== 'object') {\n throw new Error(\n 'Screenshot helper did not respond. The content script may not be injected or cannot run on this page.',\n );\n }\n\n const candidate = details as Partial;\n const invalidFields = PAGE_DETAILS_REQUIRED_FIELDS.filter(\n (field) => typeof candidate[field] !== 'number' || !Number.isFinite(candidate[field]),\n );\n\n if (invalidFields.length > 0) {\n throw new Error(\n `Screenshot helper returned invalid page details (missing/invalid: ${invalidFields.join(', ')}).`,\n );\n }\n\n return candidate as ScreenshotPageDetails;\n}\n\n/**\n * Tool for capturing screenshots of web pages\n */\nclass ScreenshotTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.SCREENSHOT;\n\n /**\n * Execute screenshot operation\n */\n async execute(args: ScreenshotToolParams): Promise {\n const {\n name = 'screenshot',\n selector,\n storeBase64 = false,\n fullPage = false,\n savePng = true,\n } = args;\n\n console.log(`Starting screenshot with options:`, args);\n\n // Resolve target tab (explicit or active)\n const explicit = await this.tryGetTab(args.tabId);\n const tab = explicit || (await this.getActiveTabOrThrowInWindow(args.windowId));\n\n // Check URL restrictions\n if (\n tab.url?.startsWith('chrome://') ||\n tab.url?.startsWith('edge://') ||\n tab.url?.startsWith('https://chrome.google.com/webstore') ||\n tab.url?.startsWith('https://microsoftedge.microsoft.com/')\n ) {\n return createErrorResponse(\n 'Cannot capture special browser pages or web store pages due to security restrictions.',\n );\n }\n\n let finalImageDataUrl: string | undefined;\n let finalImageWidthCss: number | undefined;\n let finalImageHeightCss: number | undefined;\n const results: any = { base64: null, fileSaved: false };\n let originalScroll: { x: number; y: number } | null = null;\n let didPreparePage = false;\n let pageDetails: ScreenshotPageDetails | undefined;\n\n try {\n const background = args.background === true;\n // CDP path: background=true with simple viewport capture (no fullPage, no selector)\n const canUseCdpCapture = background && !fullPage && !selector;\n\n // === Path 1: CDP viewport capture (no content script needed) ===\n if (canUseCdpCapture) {\n try {\n const tabId = tab.id!;\n const { cdpSessionManager } = await import('@/utils/cdp-session-manager');\n await cdpSessionManager.withSession(tabId, 'screenshot', async () => {\n const metrics: any = await cdpSessionManager.sendCommand(\n tabId,\n 'Page.getLayoutMetrics',\n {},\n );\n const viewport = metrics?.layoutViewport ||\n metrics?.visualViewport || {\n clientWidth: 800,\n clientHeight: 600,\n pageX: 0,\n pageY: 0,\n };\n const shot: any = await cdpSessionManager.sendCommand(tabId, 'Page.captureScreenshot', {\n format: 'png',\n });\n const base64Data = typeof shot?.data === 'string' ? shot.data : '';\n if (!base64Data) {\n throw new Error('CDP Page.captureScreenshot returned empty data');\n }\n finalImageDataUrl = `data:image/png;base64,${base64Data}`;\n finalImageWidthCss = Math.round(viewport.clientWidth || 800);\n finalImageHeightCss = Math.round(viewport.clientHeight || 600);\n });\n } catch (e) {\n console.warn('CDP viewport capture failed, falling back to helper path:', e);\n }\n }\n\n // === Path 2: Helper-assisted capture (requires content script) ===\n if (!finalImageDataUrl) {\n // Always inject helper when we need pageDetails\n await this.injectContentScript(tab.id!, ['inject-scripts/screenshot-helper.js']);\n await new Promise((resolve) => setTimeout(resolve, SCREENSHOT_CONSTANTS.SCRIPT_INIT_DELAY));\n\n // Prepare page (hide scrollbars, handle fixed elements)\n const prepareResp = await this.sendMessageToTab(tab.id!, {\n action: TOOL_MESSAGE_TYPES.SCREENSHOT_PREPARE_PAGE_FOR_CAPTURE,\n options: { fullPage },\n });\n if (!prepareResp || prepareResp.success !== true) {\n throw new Error(\n 'Screenshot helper did not acknowledge page preparation. The content script may not be injected or cannot run on this page.',\n );\n }\n didPreparePage = true;\n\n // Get page details with validation\n const rawPageDetails = await this.sendMessageToTab(tab.id!, {\n action: TOOL_MESSAGE_TYPES.SCREENSHOT_GET_PAGE_DETAILS,\n });\n pageDetails = assertValidPageDetails(rawPageDetails);\n originalScroll = { x: pageDetails.currentScrollX, y: pageDetails.currentScrollY };\n\n if (fullPage) {\n this.logInfo('Capturing full page...');\n finalImageDataUrl = await this._captureFullPage(tab.id!, args, pageDetails);\n // Compute final CSS size\n if (args.width && args.height) {\n finalImageWidthCss = args.width;\n finalImageHeightCss = args.height;\n } else if (args.width && !args.height) {\n finalImageWidthCss = args.width;\n const ratio = pageDetails.totalHeight / pageDetails.totalWidth;\n finalImageHeightCss = Math.round(args.width * ratio);\n } else if (!args.width && args.height) {\n finalImageHeightCss = args.height;\n const ratio = pageDetails.totalWidth / pageDetails.totalHeight;\n finalImageWidthCss = Math.round(args.height * ratio);\n } else {\n finalImageWidthCss = pageDetails.totalWidth;\n finalImageHeightCss = pageDetails.totalHeight;\n }\n } else if (selector) {\n this.logInfo(`Capturing element: ${selector}`);\n finalImageDataUrl = await this._captureElement(\n tab.id!,\n args,\n pageDetails.devicePixelRatio,\n );\n if (args.width && args.height) {\n finalImageWidthCss = args.width;\n finalImageHeightCss = args.height;\n } else {\n finalImageWidthCss = pageDetails.viewportWidth;\n finalImageHeightCss = pageDetails.viewportHeight;\n }\n } else {\n // Visible area only\n this.logInfo('Capturing visible area...');\n finalImageDataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, { format: 'png' });\n finalImageWidthCss = pageDetails.viewportWidth;\n finalImageHeightCss = pageDetails.viewportHeight;\n }\n }\n\n if (!finalImageDataUrl) {\n throw new Error('Failed to capture image data');\n }\n\n // 2. Process output\n // Update screenshot context for coordinate scaling by tools like chrome_computer\n try {\n if (typeof finalImageWidthCss === 'number' && typeof finalImageHeightCss === 'number') {\n let hostname = '';\n try {\n hostname = tab.url ? new URL(tab.url).hostname : '';\n } catch {\n // ignore\n }\n // Use pageDetails if available, otherwise fall back to final image dimensions\n const viewportWidth = pageDetails?.viewportWidth ?? finalImageWidthCss;\n const viewportHeight = pageDetails?.viewportHeight ?? finalImageHeightCss;\n screenshotContextManager.setContext(tab.id!, {\n screenshotWidth: finalImageWidthCss,\n screenshotHeight: finalImageHeightCss,\n viewportWidth,\n viewportHeight,\n devicePixelRatio: pageDetails?.devicePixelRatio,\n hostname,\n });\n }\n } catch (e) {\n console.warn('Failed to set screenshot context:', e);\n }\n if (storeBase64 === true) {\n // Compress image for base64 output to reduce size\n const compressed = await compressImage(finalImageDataUrl, {\n scale: 0.7, // Reduce dimensions by 30%\n quality: 0.8, // 80% quality for good balance\n format: 'image/jpeg', // JPEG for better compression\n });\n\n // Include base64 data in response (without prefix)\n const base64Data = compressed.dataUrl.replace(/^data:image\\/[^;]+;base64,/, '');\n results.base64 = base64Data;\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({ base64Data, mimeType: compressed.mimeType }),\n },\n ],\n isError: false,\n };\n }\n\n if (savePng === true) {\n // Save PNG file to downloads\n this.logInfo('Saving PNG...');\n try {\n // Generate filename\n const timestamp = new Date().toISOString().replace(/[:.]/g, '-');\n const filename = `${name.replace(/[^a-z0-9_-]/gi, '_') || 'screenshot'}_${timestamp}.png`;\n\n // Use Chrome's download API to save the file\n const downloadId = await chrome.downloads.download({\n url: finalImageDataUrl,\n filename: filename,\n saveAs: false,\n });\n\n results.downloadId = downloadId;\n results.filename = filename;\n results.fileSaved = true;\n\n // Try to get the full file path\n try {\n // Wait a moment to ensure download info is updated\n await new Promise((resolve) => setTimeout(resolve, 100));\n\n // Search for download item to get full path\n const [downloadItem] = await chrome.downloads.search({ id: downloadId });\n if (downloadItem && downloadItem.filename) {\n // Add full path to response\n results.fullPath = downloadItem.filename;\n }\n } catch (pathError) {\n console.warn('Could not get full file path:', pathError);\n }\n } catch (error) {\n console.error('Error saving PNG file:', error);\n results.saveError = String(error instanceof Error ? error.message : error);\n }\n }\n } catch (error) {\n console.error('Error during screenshot execution:', error);\n return createErrorResponse(\n `Screenshot error: ${error instanceof Error ? error.message : JSON.stringify(error)}`,\n );\n } finally {\n // 3. Reset page only if we prepared it\n if (didPreparePage) {\n try {\n // Only include scroll position if we successfully captured it\n const resetMessage: Record = {\n action: TOOL_MESSAGE_TYPES.SCREENSHOT_RESET_PAGE_AFTER_CAPTURE,\n };\n if (originalScroll) {\n resetMessage.scrollX = originalScroll.x;\n resetMessage.scrollY = originalScroll.y;\n }\n await this.sendMessageToTab(tab.id!, resetMessage);\n } catch (err) {\n console.warn('Failed to reset page, tab might have closed:', err);\n }\n }\n }\n\n this.logInfo('Screenshot completed!');\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n message: `Screenshot [${name}] captured successfully`,\n tabId: tab.id,\n url: tab.url,\n name: name,\n ...results,\n }),\n },\n ],\n isError: false,\n };\n }\n\n /**\n * Log information\n */\n private logInfo(message: string) {\n console.log(`[Screenshot Tool] ${message}`);\n }\n\n /**\n * Capture specific element\n */\n async _captureElement(\n tabId: number,\n options: ScreenshotToolParams,\n pageDpr: number,\n ): Promise {\n const elementDetails = await this.sendMessageToTab(tabId, {\n action: TOOL_MESSAGE_TYPES.SCREENSHOT_GET_ELEMENT_DETAILS,\n selector: options.selector,\n });\n\n const dpr = elementDetails.devicePixelRatio || pageDpr || 1;\n\n // Element rect is viewport-relative, in CSS pixels\n // captureVisibleTab captures in physical pixels\n const cropRectPx = {\n x: elementDetails.rect.x * dpr,\n y: elementDetails.rect.y * dpr,\n width: elementDetails.rect.width * dpr,\n height: elementDetails.rect.height * dpr,\n };\n\n // Small delay to ensure element is fully rendered after scrollIntoView\n await new Promise((resolve) => setTimeout(resolve, SCREENSHOT_CONSTANTS.SCRIPT_INIT_DELAY));\n\n const visibleCaptureDataUrl = await chrome.tabs.captureVisibleTab({ format: 'png' });\n if (!visibleCaptureDataUrl) {\n throw new Error('Failed to capture visible tab for element cropping');\n }\n\n const croppedCanvas = await cropAndResizeImage(\n visibleCaptureDataUrl,\n cropRectPx,\n dpr,\n options.width, // Target output width in CSS pixels\n options.height, // Target output height in CSS pixels\n );\n return canvasToDataURL(croppedCanvas);\n }\n\n /**\n * Capture full page\n */\n async _captureFullPage(\n tabId: number,\n options: ScreenshotToolParams,\n initialPageDetails: any,\n ): Promise {\n const dpr = initialPageDetails.devicePixelRatio;\n const totalWidthCss = options.width || initialPageDetails.totalWidth; // Use option width if provided\n const totalHeightCss = initialPageDetails.totalHeight; // Full page always uses actual height\n\n // Apply maximum height limit for infinite scroll pages\n const maxHeightPx = options.maxHeight || SCREENSHOT_CONSTANTS.MAX_CAPTURE_HEIGHT_PX;\n const limitedHeightCss = Math.min(totalHeightCss, maxHeightPx / dpr);\n\n const totalWidthPx = totalWidthCss * dpr;\n const totalHeightPx = limitedHeightCss * dpr;\n\n // Viewport dimensions (CSS pixels) - logged for debugging\n this.logInfo(\n `Viewport size: ${initialPageDetails.viewportWidth}x${initialPageDetails.viewportHeight} CSS pixels`,\n );\n this.logInfo(\n `Page dimensions: ${totalWidthCss}x${totalHeightCss} CSS pixels (limited to ${limitedHeightCss} height)`,\n );\n\n const viewportHeightCss = initialPageDetails.viewportHeight;\n\n const capturedParts = [];\n let currentScrollYCss = 0;\n let capturedHeightPx = 0;\n let partIndex = 0;\n\n while (capturedHeightPx < totalHeightPx && partIndex < SCREENSHOT_CONSTANTS.MAX_CAPTURE_PARTS) {\n this.logInfo(\n `Capturing part ${partIndex + 1}... (${Math.round((capturedHeightPx / totalHeightPx) * 100)}%)`,\n );\n\n if (currentScrollYCss > 0) {\n // Don't scroll for the first part if already at top\n const scrollResp = await this.sendMessageToTab(tabId, {\n action: TOOL_MESSAGE_TYPES.SCREENSHOT_SCROLL_PAGE,\n x: 0,\n y: currentScrollYCss,\n scrollDelay: SCREENSHOT_CONSTANTS.SCROLL_DELAY_MS,\n });\n // Update currentScrollYCss based on actual scroll achieved\n currentScrollYCss = scrollResp.newScrollY;\n }\n\n // Ensure rendering after scroll\n await new Promise((resolve) =>\n setTimeout(resolve, SCREENSHOT_CONSTANTS.CAPTURE_STITCH_DELAY_MS),\n );\n\n const dataUrl = await chrome.tabs.captureVisibleTab({ format: 'png' });\n if (!dataUrl) throw new Error('captureVisibleTab returned empty during full page capture');\n\n const yOffsetPx = currentScrollYCss * dpr;\n capturedParts.push({ dataUrl, y: yOffsetPx });\n\n const imgForHeight = await createImageBitmapFromUrl(dataUrl); // To get actual captured height\n const lastPartEffectiveHeightPx = Math.min(imgForHeight.height, totalHeightPx - yOffsetPx);\n\n capturedHeightPx = yOffsetPx + lastPartEffectiveHeightPx;\n\n if (capturedHeightPx >= totalHeightPx - SCREENSHOT_CONSTANTS.PIXEL_TOLERANCE) break;\n\n currentScrollYCss += viewportHeightCss;\n // Prevent overscrolling past the document height for the next scroll command\n if (\n currentScrollYCss > totalHeightCss - viewportHeightCss &&\n currentScrollYCss < totalHeightCss\n ) {\n currentScrollYCss = totalHeightCss - viewportHeightCss;\n }\n partIndex++;\n }\n\n // Check if we hit any limits\n if (partIndex >= SCREENSHOT_CONSTANTS.MAX_CAPTURE_PARTS) {\n this.logInfo(\n `Reached maximum number of capture parts (${SCREENSHOT_CONSTANTS.MAX_CAPTURE_PARTS}). This may be an infinite scroll page.`,\n );\n }\n if (totalHeightCss > limitedHeightCss) {\n this.logInfo(\n `Page height (${totalHeightCss}px) exceeds maximum capture height (${maxHeightPx / dpr}px). Capturing limited portion.`,\n );\n }\n\n this.logInfo('Stitching image...');\n const finalCanvas = await stitchImages(capturedParts, totalWidthPx, totalHeightPx);\n\n // If user specified width but not height (or vice versa for full page), resize maintaining aspect ratio\n let outputCanvas = finalCanvas;\n if (options.width && !options.height) {\n const targetWidthPx = options.width * dpr;\n const aspectRatio = finalCanvas.height / finalCanvas.width;\n const targetHeightPx = targetWidthPx * aspectRatio;\n outputCanvas = new OffscreenCanvas(targetWidthPx, targetHeightPx);\n const ctx = outputCanvas.getContext('2d');\n if (ctx) {\n ctx.drawImage(finalCanvas, 0, 0, targetWidthPx, targetHeightPx);\n }\n } else if (options.height && !options.width) {\n const targetHeightPx = options.height * dpr;\n const aspectRatio = finalCanvas.width / finalCanvas.height;\n const targetWidthPx = targetHeightPx * aspectRatio;\n outputCanvas = new OffscreenCanvas(targetWidthPx, targetHeightPx);\n const ctx = outputCanvas.getContext('2d');\n if (ctx) {\n ctx.drawImage(finalCanvas, 0, 0, targetWidthPx, targetHeightPx);\n }\n } else if (options.width && options.height) {\n // Both specified, direct resize\n const targetWidthPx = options.width * dpr;\n const targetHeightPx = options.height * dpr;\n outputCanvas = new OffscreenCanvas(targetWidthPx, targetHeightPx);\n const ctx = outputCanvas.getContext('2d');\n if (ctx) {\n ctx.drawImage(finalCanvas, 0, 0, targetWidthPx, targetHeightPx);\n }\n }\n\n return canvasToDataURL(outputCanvas);\n }\n}\n\nexport const screenshotTool = new ScreenshotTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/userscript.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { ExecutionWorld, STORAGE_KEYS } from '@/common/constants';\nimport { cdpSessionManager } from '@/utils/cdp-session-manager';\n\ntype UserscriptAction =\n | 'create'\n | 'list'\n | 'get'\n | 'enable'\n | 'disable'\n | 'update'\n | 'remove'\n | 'send_command'\n | 'export';\n\ninterface UserscriptArgsBase {\n action: UserscriptAction;\n args?: any;\n}\n\ninterface CreateArgs {\n script: string;\n name?: string;\n description?: string;\n matches?: string[];\n excludes?: string[];\n persist?: boolean; // default true\n runAt?: 'document_start' | 'document_end' | 'document_idle' | 'auto'; // default auto(document_idle)\n world?: 'auto' | 'ISOLATED' | 'MAIN'; // default auto(ISOLATED)\n allFrames?: boolean; // default true\n mode?: 'auto' | 'css' | 'persistent' | 'once'; // default auto\n dnrFallback?: boolean; // default true\n tags?: string[];\n}\n\ntype UpdateArgs = Partial> & { id: string; script?: string };\n\ninterface UserscriptRecord {\n id: string;\n name?: string;\n description?: string;\n script: string;\n sourceType: 'JS' | 'CSS' | 'TM';\n matches: string[];\n excludes: string[];\n runAt: 'document_start' | 'document_end' | 'document_idle';\n world: 'ISOLATED' | 'MAIN';\n allFrames: boolean;\n persist: boolean;\n dnrFallback: boolean;\n tags?: string[];\n enabled: boolean;\n createdAt: number;\n updatedAt: number;\n installedBy?: string;\n lastError?: string;\n applyCount?: number;\n lastAppliedAt?: number;\n sha256?: string;\n cspBlocked?: boolean;\n}\n\n// In-memory tracking of active injections per tab\ntype ActiveInjection = { kind: 'css' | 'js'; world?: 'ISOLATED' | 'MAIN' };\nconst activeInjections: Map> = new Map();\n\nasync function loadAllRecords(): Promise> {\n const res = await chrome.storage.local.get([STORAGE_KEYS.USERSCRIPTS]);\n return (res[STORAGE_KEYS.USERSCRIPTS] as Record) || {};\n}\n\nasync function saveAllRecords(records: Record): Promise {\n await chrome.storage.local.set({ [STORAGE_KEYS.USERSCRIPTS]: records });\n}\n\n// Simple FNV-1a hash for deterministic IDs\nfunction fnv1a(str: string): string {\n let h = 0x811c9dc5;\n for (let i = 0; i < str.length; i++) {\n h ^= str.charCodeAt(i);\n h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);\n }\n // Force to unsigned and hex\n return (h >>> 0).toString(16);\n}\n\nfunction now(): number {\n return Date.now();\n}\n\nasync function computeSHA256(input: string): Promise {\n const enc = new TextEncoder().encode(input);\n const digest = await crypto.subtle.digest('SHA-256', enc);\n const bytes = Array.from(new Uint8Array(digest));\n return bytes.map((b) => b.toString(16).padStart(2, '0')).join('');\n}\n\nasync function probeUnsafeEvalInMain(tabId: number): Promise {\n try {\n const res = await chrome.scripting.executeScript({\n target: { tabId, allFrames: false },\n world: ExecutionWorld.MAIN,\n func: () => {\n try {\n // If page CSP blocks unsafe-eval, this will throw\n return !!new Function('return 1')();\n } catch {\n return false;\n }\n },\n });\n return Array.isArray(res) && res[0] && (res[0] as any).result === true;\n } catch {\n return false;\n }\n}\n\n// Basic TM header parser (subset)\nfunction parseUserscriptMeta(source: string): {\n meta: Record;\n isTM: boolean;\n} {\n const meta: Record = {};\n const start = source.indexOf('==UserScript==');\n const end = source.indexOf('==/UserScript==');\n if (start !== -1 && end !== -1 && end > start) {\n const block = source.slice(start, end).split(/\\r?\\n/);\n for (const line of block) {\n const m = line.match(/@([\\w-]+)\\s+(.+)/);\n if (m) {\n const k = m[1].trim();\n const v = m[2].trim();\n if (!meta[k]) meta[k] = [];\n meta[k].push(v);\n }\n }\n return { meta, isTM: true };\n }\n return { meta: {}, isTM: false };\n}\n\nfunction pick(arr: T[] | undefined): T | undefined {\n return arr && arr.length > 0 ? arr[0] : undefined;\n}\n\nfunction deriveName(meta: Record, fallback?: string): string | undefined {\n return pick(meta['name']) || fallback;\n}\n\nfunction toBoolean(val: any, d: boolean): boolean {\n return typeof val === 'boolean' ? val : d;\n}\n\n// Very light CSS heuristic\nfunction isLikelyCSS(source: string): boolean {\n const trimmed = source.trim();\n if (trimmed.startsWith('/*') && trimmed.includes('==UserStyle')) return true;\n if (/^[.#\\w\\-\\s*,:>+~\\n\\r{}();'\"%!@/]+$/.test(trimmed)) {\n // no obvious JS keywords\n if (\n !/(function|=>|var\\s|let\\s|const\\s|document\\.|window\\.|\\beval\\b|new\\s+Function)/.test(trimmed)\n ) {\n // has CSS braces and colons\n const colon = (trimmed.match(/:/g) || []).length;\n const brace = (trimmed.match(/[{}]/g) || []).length;\n return colon > 0 && brace >= 2;\n }\n }\n return false;\n}\n\nfunction normalizeMatches(matches?: string[], currentUrl?: string): string[] {\n if (matches && matches.length > 0) return matches;\n if (!currentUrl) return [''];\n try {\n const u = new URL(currentUrl);\n const host = u.hostname;\n const base = host.startsWith('www.') ? host.slice(4) : host;\n return [`${u.protocol}//*.${base}/*`, `${u.protocol}//${host}/*`];\n } catch {\n return [''];\n }\n}\n\n// Simple URL match using chrome match patterns subset\nfunction matchUrl(patterns: string[], url?: string): boolean {\n if (!url) return false;\n try {\n const u = new URL(url);\n for (const p of patterns) {\n if (p === '') return true;\n const m = p.match(/^(\\*|https?:)\\/\\/([^/]+)\\/(.*)$/);\n if (!m) continue;\n const proto = m[1];\n const host = m[2];\n const path = m[3];\n if (proto !== '*' && proto !== u.protocol.replace(':', '')) continue;\n // host wildcard\n const hostRegex = new RegExp(\n '^' +\n host\n .split('.')\n .map((h) => (h === '*' ? '[^.]+' : h.replace(/[-/\\\\^$*+?.()|[\\]{}]/g, '\\\\$&')))\n .join('\\\\.') +\n '$',\n );\n if (!hostRegex.test(u.hostname)) continue;\n // path wildcard\n const pathRegex = new RegExp(\n '^' + path.replace(/[.+?^${}()|[\\]\\\\]/g, '\\\\$&').replace(/\\*/g, '.*') + '$',\n );\n const testPath = (u.pathname + (u.search || '') + (u.hash || '')).replace(/^\\//, '');\n if (pathRegex.test(testPath)) return true;\n }\n } catch {\n return false;\n }\n return false;\n}\n\nasync function getActiveTab(): Promise {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n return tabs[0] || null;\n}\n\nasync function insertCssToTab(tabId: number, css: string, allFrames: boolean) {\n await chrome.scripting.insertCSS({ target: { tabId, allFrames }, css });\n}\n\nasync function removeCssFromTab(tabId: number, css: string, allFrames: boolean) {\n try {\n await chrome.scripting.removeCSS({ target: { tabId, allFrames }, css });\n } catch (e) {\n // ignore if not present\n }\n}\n\nasync function injectJsPersistent(\n tabId: number,\n code: string,\n world: 'ISOLATED' | 'MAIN',\n allFrames: boolean,\n) {\n if (world === ExecutionWorld.MAIN) {\n // Ensure bridge is present in ISOLATED\n await chrome.scripting.executeScript({\n target: { tabId, allFrames },\n files: ['inject-scripts/inject-bridge.js'],\n world: ExecutionWorld.ISOLATED,\n });\n // MAIN world code with command handler wrapper\n const wrapped = `(() => {\n try {\n // Optional command API: window.__userscript_onCommand(action, payload)\n window.addEventListener('chrome-mcp:execute', (ev) => {\n const { action, payload, requestId } = ev.detail || {};\n try {\n let result;\n const handler = (window as any).__userscript_onCommand;\n if (typeof handler === 'function') {\n result = handler(action, payload);\n }\n window.dispatchEvent(new CustomEvent('chrome-mcp:response', { detail: { requestId, data: result } }));\n } catch (err) {\n window.dispatchEvent(new CustomEvent('chrome-mcp:response', { detail: { requestId, error: String(err && (err as any).message || err) } }));\n }\n });\n (new Function(${JSON.stringify(code)}))();\n } catch (e) {\n console.warn('Userscript MAIN injection error:', e);\n }\n })();`;\n await chrome.scripting.executeScript({\n target: { tabId, allFrames },\n func: (src) => {\n try {\n // Using Function constructor intentionally to evaluate user-provided script\n new Function(src)();\n } catch (e) {\n console.warn('Userscript MAIN wrapper execution error:', e);\n }\n },\n args: [wrapped],\n world: ExecutionWorld.MAIN,\n });\n } else {\n // ISOLATED world code with message handler\n await chrome.scripting.executeScript({\n target: { tabId, allFrames },\n func: (userCode) => {\n try {\n const handlerName = '__userscript_onCommand__';\n (chrome.runtime.onMessage as any).addListener(\n (req: any, _sender: any, sendResponse: any) => {\n if (!req || req.type !== 'userscript:command') return;\n const { action, payload, scriptId } = req;\n try {\n const handler = (globalThis as any)[handlerName];\n let result;\n if (typeof handler === 'function') {\n result = handler(action, payload, scriptId);\n }\n sendResponse({ data: result });\n } catch (err) {\n sendResponse({ error: String((err && (err as any).message) || err) });\n }\n return true;\n },\n );\n // Using Function constructor intentionally to evaluate user-provided script\n new Function(userCode)();\n } catch (e) {\n console.warn('Userscript ISOLATED injection error:', e);\n }\n },\n args: [code],\n world: ExecutionWorld.ISOLATED,\n });\n }\n}\n\nfunction setActiveInjection(tabId: number, id: string, inj: ActiveInjection) {\n let m = activeInjections.get(tabId);\n if (!m) {\n m = new Map();\n activeInjections.set(tabId, m);\n }\n m.set(id, inj);\n}\n\nfunction clearActiveInjection(tabId: number, id: string) {\n const m = activeInjections.get(tabId);\n if (m) m.delete(id);\n}\n\nasync function reinjectForTab(tabId: number, url?: string) {\n // Emergency global switch\n const flag = (await chrome.storage.local.get([STORAGE_KEYS.USERSCRIPTS_DISABLED]))[\n STORAGE_KEYS.USERSCRIPTS_DISABLED\n ];\n if (flag) return;\n const all = await loadAllRecords();\n for (const rec of Object.values(all)) {\n if (!rec.enabled || !rec.persist) continue;\n if (!matchUrl(rec.matches, url)) continue;\n try {\n if (rec.sourceType === 'CSS') {\n await insertCssToTab(tabId, rec.script, rec.allFrames);\n setActiveInjection(tabId, rec.id, { kind: 'css' });\n } else {\n // Probe CSP when targeting MAIN\n if (rec.world === 'MAIN') {\n const ok = await probeUnsafeEvalInMain(tabId);\n if (!ok) {\n rec.cspBlocked = true;\n await injectJsPersistent(tabId, rec.script, 'ISOLATED', rec.allFrames);\n setActiveInjection(tabId, rec.id, { kind: 'js', world: 'ISOLATED' });\n continue;\n }\n }\n await injectJsPersistent(tabId, rec.script, rec.world, rec.allFrames);\n setActiveInjection(tabId, rec.id, { kind: 'js', world: rec.world });\n }\n } catch (e) {\n console.warn('Reinject failed for tab', tabId, rec.id, e);\n }\n }\n}\n\n// Tab update listener: re-apply enabled persistent scripts\nchrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {\n if (changeInfo.status === 'complete') {\n reinjectForTab(tabId, tab.url).catch(() => {});\n }\n});\n\n// webNavigation based runAt mapping\nchrome.webNavigation.onCommitted.addListener(async (details) => {\n if (details.frameId !== 0) return;\n const tab = await chrome.tabs.get(details.tabId).catch(() => null);\n if (!tab) return;\n const disabled = (await chrome.storage.local.get([STORAGE_KEYS.USERSCRIPTS_DISABLED]))[\n STORAGE_KEYS.USERSCRIPTS_DISABLED\n ];\n if (disabled) return;\n const all = await loadAllRecords();\n for (const rec of Object.values(all)) {\n if (!rec.enabled || !rec.persist || rec.runAt !== 'document_start') continue;\n if (!matchUrl(rec.matches, tab.url)) continue;\n try {\n if (rec.sourceType === 'CSS') await insertCssToTab(details.tabId, rec.script, rec.allFrames);\n else await injectJsPersistent(details.tabId, rec.script, rec.world, rec.allFrames);\n } catch {\n // noop\n }\n }\n});\n\nchrome.webNavigation.onDOMContentLoaded.addListener(async (details) => {\n if (details.frameId !== 0) return;\n const tab = await chrome.tabs.get(details.tabId).catch(() => null);\n if (!tab) return;\n const disabled = (await chrome.storage.local.get([STORAGE_KEYS.USERSCRIPTS_DISABLED]))[\n STORAGE_KEYS.USERSCRIPTS_DISABLED\n ];\n if (disabled) return;\n const all = await loadAllRecords();\n for (const rec of Object.values(all)) {\n if (!rec.enabled || !rec.persist || rec.runAt !== 'document_end') continue;\n if (!matchUrl(rec.matches, tab.url)) continue;\n try {\n if (rec.sourceType === 'CSS') await insertCssToTab(details.tabId, rec.script, rec.allFrames);\n else await injectJsPersistent(details.tabId, rec.script, rec.world, rec.allFrames);\n } catch {\n // noop\n }\n }\n});\n\nclass UserscriptTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.USERSCRIPT;\n\n async execute(params: UserscriptArgsBase): Promise {\n try {\n const { action } = params;\n const args = params.args || {};\n\n switch (action) {\n case 'create':\n return await this.create(args as CreateArgs);\n case 'list':\n return await this.list(args);\n case 'get':\n return await this.get(args);\n case 'enable':\n return await this.enable(args, true);\n case 'disable':\n return await this.enable(args, false);\n case 'update':\n return await this.update(args as UpdateArgs);\n case 'remove':\n return await this.remove(args);\n case 'send_command':\n return await this.sendCommand(args);\n case 'export':\n return await this.exportAll();\n default:\n return createErrorResponse(`Unknown action: ${String(action)}`);\n }\n } catch (error) {\n console.error('Userscript tool error:', error);\n return createErrorResponse(\n `Userscript error: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n private async create(args: CreateArgs): Promise {\n const active = await getActiveTab();\n if (!active || !active.id) return createErrorResponse('No active tab found');\n const currentUrl = active.url;\n\n const emergency = (await chrome.storage.local.get([STORAGE_KEYS.USERSCRIPTS_DISABLED]))[\n STORAGE_KEYS.USERSCRIPTS_DISABLED\n ];\n\n const { meta, isTM } = parseUserscriptMeta(args.script);\n const name = args.name || deriveName(meta, undefined);\n const description = args.description || pick(meta['description']);\n const matches = normalizeMatches(args.matches || meta['match'] || meta['include'], currentUrl);\n const excludes = args.excludes || meta['exclude'] || [];\n\n const runAt: UserscriptRecord['runAt'] =\n (args.runAt && args.runAt !== 'auto' ? args.runAt : (pick(meta['run-at']) as any)) ||\n 'document_idle';\n const requestedWorld =\n (args.world && args.world !== 'auto' ? args.world : (pick(meta['inject-into']) as any)) ||\n 'ISOLATED';\n const allFrames = toBoolean(args.allFrames, true);\n const persist = toBoolean(args.persist, true);\n const dnrFallback = toBoolean(args.dnrFallback, true);\n const mode = args.mode || 'auto';\n\n const sourceType: UserscriptRecord['sourceType'] = isTM\n ? 'TM'\n : mode === 'css' || isLikelyCSS(args.script)\n ? 'CSS'\n : 'JS';\n\n const sha256 = await computeSHA256(args.script).catch(() => undefined);\n const id = `us_${fnv1a((name || '') + '|' + args.script)}`;\n\n const record: UserscriptRecord = {\n id,\n name,\n description,\n script: args.script,\n sourceType,\n matches,\n excludes,\n runAt,\n world: requestedWorld === 'MAIN' ? 'MAIN' : 'ISOLATED',\n allFrames,\n persist,\n dnrFallback,\n tags: args.tags,\n enabled: true,\n createdAt: now(),\n updatedAt: now(),\n applyCount: 0,\n sha256,\n };\n\n const all = await loadAllRecords();\n if (record.persist) {\n all[id] = record;\n await saveAllRecords(all);\n }\n\n // Apply to current tab immediately if matches\n let applied = false;\n const fallbacks: string[] = [];\n let cspBlocked = false;\n const t0 = performance.now();\n try {\n if (mode === 'once') {\n // Once: CDP evaluate in page\n await cdpSessionManager.withSession(active.id!, 'userscript_once', async () => {\n const expression = `(function(){try{return (function(){${record.script}\\n})()}catch(e){return {__error:String(e&&e.message||e)}}})()`;\n const result: any = await cdpSessionManager.sendCommand(active.id!, 'Runtime.evaluate', {\n expression,\n returnByValue: true,\n awaitPromise: true,\n });\n if (result?.result?.value?.__error) {\n throw new Error(result.result.value.__error);\n }\n });\n applied = true;\n } else if (sourceType === 'CSS') {\n await insertCssToTab(active.id!, record.script, record.allFrames);\n setActiveInjection(active.id!, id, { kind: 'css' });\n applied = true;\n } else {\n // Probe CSP preflight when target MAIN\n if (record.world === 'MAIN') {\n const ok = await probeUnsafeEvalInMain(active.id!);\n if (!ok) {\n cspBlocked = true;\n fallbacks.push('MAIN->ISOLATED');\n await injectJsPersistent(active.id!, record.script, 'ISOLATED', record.allFrames);\n setActiveInjection(active.id!, id, { kind: 'js', world: 'ISOLATED' });\n applied = true;\n }\n }\n if (!applied) {\n await injectJsPersistent(active.id!, record.script, record.world, record.allFrames);\n setActiveInjection(active.id!, id, { kind: 'js', world: record.world });\n applied = true;\n }\n }\n } catch (e) {\n if (record.persist) {\n all[id].lastError = e instanceof Error ? e.message : String(e);\n all[id].cspBlocked = cspBlocked;\n await saveAllRecords(all);\n }\n }\n\n const result = {\n id,\n status: record.persist && all[id]?.lastError ? 'queued' : applied ? 'applied' : 'queued',\n strategy: {\n kind:\n mode === 'once'\n ? 'once_cdp'\n : sourceType === 'CSS'\n ? 'insertCSS'\n : `persistent_${(record.persist ? all[id]?.world || record.world : record.world).toLowerCase()}`,\n runAt: record.persist ? all[id]?.runAt || record.runAt : record.runAt,\n world: record.persist ? all[id]?.world || record.world : record.world,\n allFrames: record.persist ? (all[id]?.allFrames ?? record.allFrames) : record.allFrames,\n fallbacksTried: fallbacks,\n cspBlocked,\n },\n warnings: emergency ? ['USERSCRIPTS_DISABLED is ON, injection skipped'] : [],\n metrics: { injectMs: Math.round(performance.now() - t0) },\n };\n\n return {\n content: [{ type: 'text', text: JSON.stringify(result) }],\n isError: false,\n };\n }\n\n private async list(args: any): Promise {\n const all = await loadAllRecords();\n const q = (args && args.query ? String(args.query).toLowerCase() : '').trim();\n const status = args && args.status ? String(args.status) : '';\n const domain = args && args.domain ? String(args.domain) : '';\n const items = Object.values(all)\n .filter((r) => (status ? (status === 'enabled' ? r.enabled : !r.enabled) : true))\n .filter((r) => (domain ? matchUrl(r.matches, `https://${domain}/`) : true))\n .filter((r) =>\n q\n ? (r.name || '').toLowerCase().includes(q) ||\n (r.description || '').toLowerCase().includes(q)\n : true,\n )\n .map((r) => ({\n id: r.id,\n name: r.name,\n status: r.enabled ? 'enabled' : 'disabled',\n sourceType: r.sourceType,\n matches: r.matches,\n world: r.world,\n runAt: r.runAt,\n tags: r.tags || [],\n lastError: r.lastError,\n updatedAt: r.updatedAt,\n applyCount: r.applyCount || 0,\n lastAppliedAt: r.lastAppliedAt || null,\n }));\n return {\n content: [{ type: 'text', text: JSON.stringify({ ok: true, items }) }],\n isError: false,\n };\n }\n\n private async get(args: any): Promise {\n const { id } = args || {};\n if (!id) return createErrorResponse('id is required');\n const all = await loadAllRecords();\n const rec = all[id];\n if (!rec) return createErrorResponse('userscript not found');\n return {\n content: [{ type: 'text', text: JSON.stringify({ ok: true, record: rec }) }],\n isError: false,\n };\n }\n\n private async enable(args: any, enabled: boolean): Promise {\n const { id } = args || {};\n if (!id) return createErrorResponse('id is required');\n const all = await loadAllRecords();\n const rec = all[id];\n if (!rec) return createErrorResponse('userscript not found');\n rec.enabled = enabled;\n rec.updatedAt = now();\n await saveAllRecords(all);\n return { content: [{ type: 'text', text: JSON.stringify({ ok: true }) }], isError: false };\n }\n\n private async update(args: UpdateArgs): Promise {\n const { id, ...rest } = args;\n if (!id) return createErrorResponse('id is required');\n const all = await loadAllRecords();\n const rec = all[id];\n if (!rec) return createErrorResponse('userscript not found');\n\n if (rest.name !== undefined) rec.name = rest.name;\n if (rest.description !== undefined) rec.description = rest.description;\n if (rest.matches) rec.matches = rest.matches;\n if (rest.excludes) rec.excludes = rest.excludes;\n if (rest.runAt && rest.runAt !== 'auto') rec.runAt = rest.runAt;\n if (rest.world && rest.world !== 'auto') rec.world = rest.world as any;\n if (typeof rest.allFrames === 'boolean') rec.allFrames = rest.allFrames;\n if (typeof rest.persist === 'boolean') rec.persist = rest.persist;\n if (typeof rest.dnrFallback === 'boolean') rec.dnrFallback = rest.dnrFallback;\n if (rest.tags) rec.tags = rest.tags;\n if (typeof rest.script === 'string') rec.script = rest.script;\n rec.updatedAt = now();\n await saveAllRecords(all);\n return { content: [{ type: 'text', text: JSON.stringify({ ok: true }) }], isError: false };\n }\n\n private async remove(args: any): Promise {\n const { id } = args || {};\n if (!id) return createErrorResponse('id is required');\n const all = await loadAllRecords();\n const rec = all[id];\n if (!rec) return createErrorResponse('userscript not found');\n delete all[id];\n await saveAllRecords(all);\n\n // Attempt cleanup on active tab\n const active = await getActiveTab();\n if (active && active.id) {\n try {\n if (rec.sourceType === 'CSS') {\n await removeCssFromTab(active.id, rec.script, rec.allFrames);\n } else {\n // Send cleanup signal via bridge (MAIN) or ignore if isolated\n chrome.tabs.sendMessage(active.id, { type: 'chrome-mcp:cleanup' }).catch(() => {});\n }\n clearActiveInjection(active.id, rec.id);\n } catch (err) {\n console.warn('Userscript cleanup failed:', err);\n }\n }\n\n return { content: [{ type: 'text', text: JSON.stringify({ ok: true }) }], isError: false };\n }\n\n private async sendCommand(args: any): Promise {\n const { id, payload, tabId } = args || {};\n if (!id) return createErrorResponse('id is required');\n const tab = tabId ? await chrome.tabs.get(tabId).catch(() => null) : await getActiveTab();\n if (!tab || !tab.id) return createErrorResponse('No active tab found');\n\n const all = await loadAllRecords();\n const rec = all[id];\n if (!rec) return createErrorResponse('userscript not found');\n\n try {\n if (rec.world === 'MAIN') {\n // Use bridge\n const result = await chrome.tabs.sendMessage(tab.id, {\n action: 'userscript:command',\n payload,\n targetWorld: 'MAIN',\n });\n return {\n content: [{ type: 'text', text: JSON.stringify({ ok: true, result }) }],\n isError: false,\n };\n } else {\n // ISOLATED handler\n const result = await chrome.tabs.sendMessage(tab.id, {\n type: 'userscript:command',\n action: 'userscript:command',\n payload,\n scriptId: id,\n });\n return {\n content: [{ type: 'text', text: JSON.stringify({ ok: true, result }) }],\n isError: false,\n };\n }\n } catch (e) {\n return createErrorResponse(\n `send_command failed: ${e instanceof Error ? e.message : String(e)}`,\n );\n }\n }\n\n private async exportAll(): Promise {\n const all = await loadAllRecords();\n return {\n content: [{ type: 'text', text: JSON.stringify({ ok: true, data: all }) }],\n isError: false,\n };\n }\n}\n\nexport const userscriptTool = new UserscriptTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/vector-search.ts", "content": "/**\n * Vectorized tab content search tool\n * Uses vector database for efficient semantic search\n */\n\nimport { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { ContentIndexer } from '@/utils/content-indexer';\nimport { LIMITS, ERROR_MESSAGES } from '@/common/constants';\nimport type { SearchResult } from '@/utils/vector-database';\n\ninterface VectorSearchResult {\n tabId: number;\n url: string;\n title: string;\n semanticScore: number;\n matchedSnippet: string;\n chunkSource: string;\n timestamp: number;\n}\n\n/**\n * Tool for vectorized search of tab content using semantic similarity\n */\nclass VectorSearchTabsContentTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.SEARCH_TABS_CONTENT;\n private contentIndexer: ContentIndexer;\n private isInitialized = false;\n\n constructor() {\n super();\n this.contentIndexer = new ContentIndexer({\n autoIndex: true,\n maxChunksPerPage: LIMITS.MAX_SEARCH_RESULTS,\n skipDuplicates: true,\n });\n }\n\n private async initializeIndexer(): Promise {\n try {\n await this.contentIndexer.initialize();\n this.isInitialized = true;\n console.log('VectorSearchTabsContentTool: Content indexer initialized successfully');\n } catch (error) {\n console.error('VectorSearchTabsContentTool: Failed to initialize content indexer:', error);\n this.isInitialized = false;\n }\n }\n\n async execute(args: { query: string }): Promise {\n try {\n const { query } = args;\n\n if (!query || query.trim().length === 0) {\n return createErrorResponse(\n ERROR_MESSAGES.INVALID_PARAMETERS + ': Query parameter is required and cannot be empty',\n );\n }\n\n console.log(`VectorSearchTabsContentTool: Starting vector search with query: \"${query}\"`);\n\n // Check semantic engine status\n if (!this.contentIndexer.isSemanticEngineReady()) {\n if (this.contentIndexer.isSemanticEngineInitializing()) {\n return createErrorResponse(\n 'Vector search engine is still initializing (model downloading). Please wait a moment and try again.',\n );\n } else {\n // Try to initialize\n console.log('VectorSearchTabsContentTool: Initializing content indexer...');\n await this.initializeIndexer();\n\n // Check semantic engine status again\n if (!this.contentIndexer.isSemanticEngineReady()) {\n return createErrorResponse('Failed to initialize vector search engine');\n }\n }\n }\n\n // Execute vector search, get more results for deduplication\n const searchResults = await this.contentIndexer.searchContent(query, 50);\n\n // Convert search results format\n const vectorSearchResults = this.convertSearchResults(searchResults);\n\n // Deduplicate by tab, keep only the highest similarity fragment per tab\n const deduplicatedResults = this.deduplicateByTab(vectorSearchResults);\n\n // Sort by similarity and get top 10 results\n const topResults = deduplicatedResults\n .sort((a, b) => b.semanticScore - a.semanticScore)\n .slice(0, 10);\n\n // Get index statistics\n const stats = this.contentIndexer.getStats();\n\n const result = {\n success: true,\n totalTabsSearched: stats.totalTabs,\n matchedTabsCount: topResults.length,\n vectorSearchEnabled: true,\n indexStats: {\n totalDocuments: stats.totalDocuments,\n totalTabs: stats.totalTabs,\n indexedPages: stats.indexedPages,\n semanticEngineReady: stats.semanticEngineReady,\n semanticEngineInitializing: stats.semanticEngineInitializing,\n },\n matchedTabs: topResults.map((result) => ({\n tabId: result.tabId,\n url: result.url,\n title: result.title,\n semanticScore: result.semanticScore,\n matchedSnippets: [result.matchedSnippet],\n chunkSource: result.chunkSource,\n timestamp: result.timestamp,\n })),\n };\n\n console.log(\n `VectorSearchTabsContentTool: Found ${topResults.length} results with vector search`,\n );\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(result, null, 2),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('VectorSearchTabsContentTool: Search failed:', error);\n return createErrorResponse(\n `Vector search failed: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n\n /**\n * Ensure all tabs are indexed\n */\n private async ensureTabsIndexed(tabs: chrome.tabs.Tab[]): Promise {\n const indexPromises = tabs\n .filter((tab) => tab.id)\n .map(async (tab) => {\n try {\n await this.contentIndexer.indexTabContent(tab.id!);\n } catch (error) {\n console.warn(`VectorSearchTabsContentTool: Failed to index tab ${tab.id}:`, error);\n }\n });\n\n await Promise.allSettled(indexPromises);\n }\n\n /**\n * Convert search results format\n */\n private convertSearchResults(searchResults: SearchResult[]): VectorSearchResult[] {\n return searchResults.map((result) => ({\n tabId: result.document.tabId,\n url: result.document.url,\n title: result.document.title,\n semanticScore: result.similarity,\n matchedSnippet: this.extractSnippet(result.document.chunk.text),\n chunkSource: result.document.chunk.source,\n timestamp: result.document.timestamp,\n }));\n }\n\n /**\n * Deduplicate by tab, keep only the highest similarity fragment per tab\n */\n private deduplicateByTab(results: VectorSearchResult[]): VectorSearchResult[] {\n const tabMap = new Map();\n\n for (const result of results) {\n const existingResult = tabMap.get(result.tabId);\n\n // If this tab has no result yet, or current result has higher similarity, update it\n if (!existingResult || result.semanticScore > existingResult.semanticScore) {\n tabMap.set(result.tabId, result);\n }\n }\n\n return Array.from(tabMap.values());\n }\n\n /**\n * Extract text snippet for display\n */\n private extractSnippet(text: string, maxLength: number = 200): string {\n if (text.length <= maxLength) {\n return text;\n }\n\n // Try to truncate at sentence boundary\n const truncated = text.substring(0, maxLength);\n const lastSentenceEnd = Math.max(\n truncated.lastIndexOf('.'),\n truncated.lastIndexOf('!'),\n truncated.lastIndexOf('?'),\n truncated.lastIndexOf('。'),\n truncated.lastIndexOf('！'),\n truncated.lastIndexOf('？'),\n );\n\n if (lastSentenceEnd > maxLength * 0.7) {\n return truncated.substring(0, lastSentenceEnd + 1);\n }\n\n // If no suitable sentence boundary found, truncate at word boundary\n const lastSpaceIndex = truncated.lastIndexOf(' ');\n if (lastSpaceIndex > maxLength * 0.8) {\n return truncated.substring(0, lastSpaceIndex) + '...';\n }\n\n return truncated + '...';\n }\n\n /**\n * Get index statistics\n */\n public async getIndexStats() {\n if (!this.isInitialized) {\n // Don't automatically initialize - just return basic stats\n return {\n totalDocuments: 0,\n totalTabs: 0,\n indexSize: 0,\n indexedPages: 0,\n isInitialized: false,\n semanticEngineReady: false,\n semanticEngineInitializing: false,\n };\n }\n return this.contentIndexer.getStats();\n }\n\n /**\n * Manually rebuild index\n */\n public async rebuildIndex(): Promise {\n if (!this.isInitialized) {\n await this.initializeIndexer();\n }\n\n try {\n // Clear existing indexes\n await this.contentIndexer.clearAllIndexes();\n\n // Get all tabs and reindex\n const windows = await chrome.windows.getAll({ populate: true });\n const allTabs: chrome.tabs.Tab[] = [];\n\n for (const window of windows) {\n if (window.tabs) {\n allTabs.push(...window.tabs);\n }\n }\n\n const validTabs = allTabs.filter(\n (tab) =>\n tab.id &&\n tab.url &&\n !tab.url.startsWith('chrome://') &&\n !tab.url.startsWith('chrome-extension://') &&\n !tab.url.startsWith('edge://') &&\n !tab.url.startsWith('about:'),\n );\n\n await this.ensureTabsIndexed(validTabs);\n\n console.log(`VectorSearchTabsContentTool: Rebuilt index for ${validTabs.length} tabs`);\n } catch (error) {\n console.error('VectorSearchTabsContentTool: Failed to rebuild index:', error);\n throw error;\n }\n }\n\n /**\n * Manually index specified tab\n */\n public async indexTab(tabId: number): Promise {\n if (!this.isInitialized) {\n await this.initializeIndexer();\n }\n\n await this.contentIndexer.indexTabContent(tabId);\n }\n\n /**\n * Remove index for specified tab\n */\n public async removeTabIndex(tabId: number): Promise {\n if (!this.isInitialized) {\n return;\n }\n\n await this.contentIndexer.removeTabIndex(tabId);\n }\n}\n\n// Export tool instance\nexport const vectorSearchTabsContentTool = new VectorSearchTabsContentTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/web-fetcher.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { TOOL_MESSAGE_TYPES } from '@/common/message-types';\n\ninterface WebFetcherToolParams {\n htmlContent?: boolean; // get the visible HTML content of the current page. default: false\n textContent?: boolean; // get the visible text content of the current page. default: true\n url?: string; // optional URL to fetch content from (if not provided, uses active tab)\n selector?: string; // optional CSS selector to get content from a specific element\n tabId?: number; // target existing tab id\n background?: boolean; // do not activate/focus\n windowId?: number; // target window id to pick active tab or create tab\n}\n\nclass WebFetcherTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.WEB_FETCHER;\n\n /**\n * Execute web fetcher operation\n */\n async execute(args: WebFetcherToolParams): Promise {\n // Handle mutually exclusive parameters: if htmlContent is true, textContent is forced to false\n const htmlContent = args.htmlContent === true;\n const textContent = htmlContent ? false : args.textContent !== false; // Default is true, unless htmlContent is true or textContent is explicitly set to false\n const url = args.url;\n const selector = args.selector;\n const explicitTabId = args.tabId;\n const background = args.background === true;\n const windowId = args.windowId;\n\n console.log(`Starting web fetcher with options:`, {\n htmlContent,\n textContent,\n url,\n selector,\n });\n\n try {\n // Get tab to fetch content from\n let tab;\n\n if (typeof explicitTabId === 'number') {\n tab = await chrome.tabs.get(explicitTabId);\n } else if (url) {\n // If URL is provided, check if it's already open\n console.log(`Checking if URL is already open: ${url}`);\n const allTabs = await chrome.tabs.query({});\n\n // Find tab with matching URL\n const matchingTabs = allTabs.filter((t) => {\n // Normalize URLs for comparison (remove trailing slashes)\n const tabUrl = t.url?.endsWith('/') ? t.url.slice(0, -1) : t.url;\n const targetUrl = url.endsWith('/') ? url.slice(0, -1) : url;\n return tabUrl === targetUrl;\n });\n\n if (matchingTabs.length > 0) {\n // Use existing tab\n tab = matchingTabs[0];\n console.log(`Found existing tab with URL: ${url}, tab ID: ${tab.id}`);\n } else {\n // Create new tab with the URL\n console.log(`No existing tab found with URL: ${url}, creating new tab`);\n tab = await chrome.tabs.create({ url, active: background ? false : true });\n\n // Wait for page to load\n console.log('Waiting for page to load...');\n await new Promise((resolve) => setTimeout(resolve, 3000));\n }\n } else {\n // Use active tab (prefer specified window)\n const tabs =\n typeof windowId === 'number'\n ? await chrome.tabs.query({ active: true, windowId })\n : await chrome.tabs.query({ active: true, currentWindow: true });\n if (!tabs[0]) {\n return createErrorResponse('No active tab found');\n }\n tab = tabs[0];\n }\n\n if (!tab.id) {\n return createErrorResponse('Tab has no ID');\n }\n\n // Optionally bring tab/window to foreground\n if (!background) {\n await chrome.tabs.update(tab.id, { active: true });\n await chrome.windows.update(tab.windowId, { focused: true });\n }\n\n // Prepare result object\n const result: any = {\n success: true,\n url: tab.url,\n title: tab.title,\n };\n\n await this.injectContentScript(tab.id, ['inject-scripts/web-fetcher-helper.js']);\n\n // Get HTML content if requested\n if (htmlContent) {\n const htmlResponse = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.WEB_FETCHER_GET_HTML_CONTENT,\n selector: selector,\n });\n\n if (htmlResponse.success) {\n result.htmlContent = htmlResponse.htmlContent;\n } else {\n console.error('Failed to get HTML content:', htmlResponse.error);\n result.htmlContentError = htmlResponse.error;\n }\n }\n\n // Get text content if requested (and htmlContent is not true)\n if (textContent) {\n const textResponse = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.WEB_FETCHER_GET_TEXT_CONTENT,\n selector: selector,\n });\n\n if (textResponse.success) {\n result.textContent = textResponse.textContent;\n\n // Include article metadata if available\n if (textResponse.article) {\n result.article = {\n title: textResponse.article.title,\n byline: textResponse.article.byline,\n siteName: textResponse.article.siteName,\n excerpt: textResponse.article.excerpt,\n lang: textResponse.article.lang,\n };\n }\n\n // Include page metadata if available\n if (textResponse.metadata) {\n result.metadata = textResponse.metadata;\n }\n } else {\n console.error('Failed to get text content:', textResponse.error);\n result.textContentError = textResponse.error;\n }\n }\n\n // Interactive elements feature has been removed\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(result),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in web fetcher:', error);\n return createErrorResponse(\n `Error fetching web content: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const webFetcherTool = new WebFetcherTool();\n\ninterface GetInteractiveElementsToolParams {\n textQuery?: string; // Text to search for within interactive elements (fuzzy search)\n selector?: string; // CSS selector to filter interactive elements\n includeCoordinates?: boolean; // Include element coordinates in the response (default: true)\n types?: string[]; // Types of interactive elements to include (default: all types)\n}\n\nclass GetInteractiveElementsTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.GET_INTERACTIVE_ELEMENTS;\n\n /**\n * Execute get interactive elements operation\n */\n async execute(args: GetInteractiveElementsToolParams): Promise {\n const { textQuery, selector, includeCoordinates = true, types } = args;\n\n console.log(`Starting get interactive elements with options:`, args);\n\n try {\n // Get current tab\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n if (!tabs[0]) {\n return createErrorResponse('No active tab found');\n }\n\n const tab = tabs[0];\n if (!tab.id) {\n return createErrorResponse('Active tab has no ID');\n }\n\n // Ensure content script is injected\n await this.injectContentScript(tab.id, ['inject-scripts/interactive-elements-helper.js']);\n\n // Send message to content script\n const result = await this.sendMessageToTab(tab.id, {\n action: TOOL_MESSAGE_TYPES.GET_INTERACTIVE_ELEMENTS,\n textQuery,\n selector,\n includeCoordinates,\n types,\n });\n\n if (!result.success) {\n return createErrorResponse(result.error || 'Failed to get interactive elements');\n }\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({\n success: true,\n elements: result.elements,\n count: result.elements.length,\n query: {\n textQuery,\n selector,\n types: types || 'all',\n },\n }),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in get interactive elements operation:', error);\n return createErrorResponse(\n `Error getting interactive elements: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const getInteractiveElementsTool = new GetInteractiveElementsTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/browser/window.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { BaseBrowserToolExecutor } from '../base-browser';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\n\nclass WindowTool extends BaseBrowserToolExecutor {\n name = TOOL_NAMES.BROWSER.GET_WINDOWS_AND_TABS;\n async execute(): Promise {\n try {\n const windows = await chrome.windows.getAll({ populate: true });\n let tabCount = 0;\n\n const structuredWindows = windows.map((window) => {\n const tabs =\n window.tabs?.map((tab) => {\n tabCount++;\n return {\n tabId: tab.id || 0,\n url: tab.url || '',\n title: tab.title || '',\n active: tab.active || false,\n };\n }) || [];\n\n return {\n windowId: window.id || 0,\n tabs: tabs,\n };\n });\n\n const result = {\n windowCount: windows.length,\n tabCount: tabCount,\n windows: structuredWindows,\n };\n\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(result),\n },\n ],\n isError: false,\n };\n } catch (error) {\n console.error('Error in WindowTool.execute:', error);\n return createErrorResponse(\n `Error getting windows and tabs information: ${error instanceof Error ? error.message : String(error)}`,\n );\n }\n }\n}\n\nexport const windowTool = new WindowTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/index.ts", "content": "import { createErrorResponse } from '@/common/tool-handler';\nimport { ERROR_MESSAGES } from '@/common/constants';\nimport * as browserTools from './browser';\nimport { flowRunTool, listPublishedFlowsTool } from './record-replay';\n\nconst tools = { ...browserTools, flowRunTool, listPublishedFlowsTool } as any;\nconst toolsMap = new Map(Object.values(tools).map((tool: any) => [tool.name, tool]));\n\n/**\n * Tool call parameter interface\n */\nexport interface ToolCallParam {\n name: string;\n args: any;\n}\n\n/**\n * Handle tool execution\n */\nexport const handleCallTool = async (param: ToolCallParam) => {\n const tool = toolsMap.get(param.name);\n if (!tool) {\n return createErrorResponse(`Tool ${param.name} not found`);\n }\n\n try {\n return await tool.execute(param.args);\n } catch (error) {\n console.error(`Tool execution failed for ${param.name}:`, error);\n return createErrorResponse(\n error instanceof Error ? error.message : ERROR_MESSAGES.TOOL_EXECUTION_FAILED,\n );\n }\n};\n" }, { "path": "app/chrome-extension/entrypoints/background/tools/record-replay.ts", "content": "import { createErrorResponse, ToolResult } from '@/common/tool-handler';\nimport { TOOL_NAMES } from 'chrome-mcp-shared';\nimport { listPublished } from '../record-replay/flow-store';\nimport { getFlow } from '../record-replay/flow-store';\nimport { runFlow } from '../record-replay/flow-runner';\n\nclass FlowRunTool {\n name = TOOL_NAMES.RECORD_REPLAY.FLOW_RUN;\n async execute(args: any): Promise {\n const {\n flowId,\n args: vars,\n tabTarget,\n refresh,\n captureNetwork,\n returnLogs,\n timeoutMs,\n startUrl,\n } = args || {};\n if (!flowId) return createErrorResponse('flowId is required');\n const flow = await getFlow(flowId);\n if (!flow) return createErrorResponse(`Flow not found: ${flowId}`);\n const result = await runFlow(flow, {\n tabTarget,\n refresh,\n captureNetwork,\n returnLogs,\n timeoutMs,\n startUrl,\n args: vars,\n });\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(result),\n },\n ],\n isError: false,\n };\n }\n}\n\nclass ListPublishedTool {\n name = TOOL_NAMES.RECORD_REPLAY.LIST_PUBLISHED;\n async execute(): Promise {\n const list = await listPublished();\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify({ success: true, published: list }),\n },\n ],\n isError: false,\n };\n }\n}\n\nexport const flowRunTool = new FlowRunTool();\nexport const listPublishedFlowsTool = new ListPublishedTool();\n" }, { "path": "app/chrome-extension/entrypoints/background/utils/sidepanel.ts", "content": "/**\n * Sidepanel Utilities\n *\n * Shared helpers for opening and managing the Chrome sidepanel from background modules.\n * Used by web-editor, quick-panel, and other modules that need to trigger sidepanel navigation.\n */\n\n/**\n * Best-effort open the sidepanel with AgentChat tab selected.\n *\n * @param tabId - Tab ID to associate with sidepanel\n * @param windowId - Optional window ID for fallback when tab-level open fails\n * @param sessionId - Optional session ID to navigate directly to chat view (deep-link)\n *\n * @remarks\n * This function is intentionally resilient - it will not throw on failures.\n * Sidepanel availability varies across Chrome versions and contexts.\n */\nexport async function openAgentChatSidepanel(\n tabId: number,\n windowId?: number,\n sessionId?: string,\n): Promise {\n try {\n // Build deep-link path with optional session navigation\n let path = 'sidepanel.html?tab=agent-chat';\n if (sessionId) {\n path += `&view=chat&sessionId=${encodeURIComponent(sessionId)}`;\n }\n\n // Configure sidepanel options for this tab\n\n const sidePanel = chrome.sidePanel as any;\n\n if (sidePanel?.setOptions) {\n await sidePanel.setOptions({\n tabId,\n path,\n enabled: true,\n });\n }\n\n // Attempt to open the sidepanel\n if (sidePanel?.open) {\n try {\n await sidePanel.open({ tabId });\n } catch {\n // Fallback to window-level open if tab-level fails\n // This handles cases where the tab is in a special state\n if (typeof windowId === 'number') {\n await sidePanel.open({ windowId });\n }\n }\n }\n } catch {\n // Best-effort: side panel may be unavailable in some Chrome versions/environments\n // Intentionally suppress errors to avoid breaking calling code\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/background/web-editor/index.ts", "content": "import { BACKGROUND_MESSAGE_TYPES } from '@/common/message-types';\nimport {\n WEB_EDITOR_V2_ACTIONS,\n WEB_EDITOR_V1_ACTIONS,\n type ElementChangeSummary,\n type WebEditorApplyBatchPayload,\n type WebEditorTxChangedPayload,\n type WebEditorHighlightElementPayload,\n type WebEditorRevertElementPayload,\n type WebEditorCancelExecutionPayload,\n type WebEditorCancelExecutionResponse,\n} from '@/common/web-editor-types';\nimport { openAgentChatSidepanel } from '../utils/sidepanel';\n\nconst CONTEXT_MENU_ID = 'web_editor_toggle';\nconst COMMAND_KEY = 'toggle_web_editor';\nconst DEFAULT_NATIVE_SERVER_PORT = 12306;\n\n/** Storage key prefix for TX change session data (per-tab isolation) */\nconst WEB_EDITOR_TX_CHANGED_SESSION_KEY_PREFIX = 'web-editor-v2-tx-changed-';\nconst WEB_EDITOR_SELECTION_SESSION_KEY_PREFIX = 'web-editor-v2-selection-';\n\n/** Storage key prefix for excluded element keys (per-tab isolation, managed by sidepanel) */\nconst WEB_EDITOR_EXCLUDED_KEYS_SESSION_KEY_PREFIX = 'web-editor-v2-excluded-keys-';\n\n/** Storage key for AgentChat selected session ID */\nconst STORAGE_KEY_SELECTED_SESSION = 'agent-selected-session-id';\n\n// In-memory execution status cache (per requestId)\ninterface ExecutionStatusEntry {\n status: string;\n message?: string;\n updatedAt: number;\n result?: { success: boolean; summary?: string; error?: string };\n}\nconst executionStatusCache = new Map();\nconst STATUS_CACHE_TTL = 5 * 60 * 1000; // 5 minutes\n\nfunction cleanupExpiredStatuses(): void {\n const now = Date.now();\n for (const [key, entry] of executionStatusCache) {\n if (now - entry.updatedAt > STATUS_CACHE_TTL) {\n executionStatusCache.delete(key);\n }\n }\n}\n\nfunction setExecutionStatus(\n requestId: string,\n status: string,\n message?: string,\n result?: ExecutionStatusEntry['result'],\n): void {\n executionStatusCache.set(requestId, {\n status,\n message,\n updatedAt: Date.now(),\n result,\n });\n // Periodic cleanup\n if (executionStatusCache.size > 100) {\n cleanupExpiredStatuses();\n }\n}\n\nfunction getExecutionStatus(requestId: string): ExecutionStatusEntry | undefined {\n return executionStatusCache.get(requestId);\n}\n\n// SSE connections for status updates (per sessionId)\nconst sseConnections = new Map();\n\n/**\n * Start SSE subscription for a session to receive status updates\n */\nasync function subscribeToSessionStatus(\n sessionId: string,\n requestId: string,\n port: number,\n): Promise {\n // Close existing connection for this session if any\n const existing = sseConnections.get(sessionId);\n if (existing) {\n existing.abort.abort();\n sseConnections.delete(sessionId);\n }\n\n const abortController = new AbortController();\n sseConnections.set(sessionId, { abort: abortController, lastRequestId: requestId });\n\n // Set initial status\n setExecutionStatus(requestId, 'starting', 'Connecting to Agent...');\n\n const sseUrl = `http://127.0.0.1:${port}/agent/chat/${encodeURIComponent(sessionId)}/stream`;\n\n try {\n const response = await fetch(sseUrl, {\n method: 'GET',\n headers: { Accept: 'text/event-stream' },\n signal: abortController.signal,\n });\n\n if (!response.ok || !response.body) {\n setExecutionStatus(requestId, 'running', 'Agent processing...');\n return;\n }\n\n const reader = response.body.getReader();\n const decoder = new TextDecoder();\n let buffer = '';\n\n setExecutionStatus(requestId, 'running', 'Agent processing...');\n\n // Read SSE stream\n\n while (true) {\n const { done, value } = await reader.read();\n if (done) break;\n\n buffer += decoder.decode(value, { stream: true });\n const lines = buffer.split('\\n');\n buffer = lines.pop() ?? '';\n\n for (const line of lines) {\n if (line.startsWith('data:')) {\n try {\n const data = JSON.parse(line.slice(5).trim());\n handleSseEvent(requestId, data);\n } catch {\n // Ignore parse errors\n }\n }\n }\n }\n } catch (err) {\n if (err instanceof Error && err.name === 'AbortError') {\n // Intentionally aborted, not an error\n return;\n }\n // Connection error - mark as unknown but not failed (Agent may still be running)\n const cached = getExecutionStatus(requestId);\n if (cached && !['completed', 'failed', 'cancelled'].includes(cached.status)) {\n setExecutionStatus(requestId, 'running', 'Agent processing (connection lost)...');\n }\n } finally {\n sseConnections.delete(sessionId);\n }\n}\n\n/**\n * Handle SSE event from Agent stream\n */\nfunction handleSseEvent(requestId: string, event: unknown): void {\n if (!event || typeof event !== 'object') return;\n const e = event as Record;\n const type = e.type;\n const data = e.data as Record | undefined;\n\n // Check if this event is for our request\n const eventRequestId = data?.requestId as string | undefined;\n if (eventRequestId && eventRequestId !== requestId) return;\n\n if (type === 'status' && data) {\n const status = data.status as string;\n const message = data.message as string | undefined;\n\n // Map Agent status to our status\n // - 'ready' -> 'running' (ready is a running sub-state)\n // - 'error' -> 'failed' (normalize server 'error' to UI 'failed')\n let mappedStatus = status;\n if (status === 'ready') mappedStatus = 'running';\n if (status === 'error') mappedStatus = 'failed';\n\n setExecutionStatus(requestId, mappedStatus, message);\n } else if (type === 'message' && data) {\n // Update status to show we're receiving messages\n const cached = getExecutionStatus(requestId);\n if (cached && cached.status === 'starting') {\n setExecutionStatus(requestId, 'running', 'Agent is working...');\n }\n\n // Check for completion indicators in message content\n const role = data.role as string | undefined;\n const isFinal = data.isFinal as boolean | undefined;\n if (role === 'assistant' && isFinal) {\n const content = data.content as string | undefined;\n setExecutionStatus(requestId, 'completed', 'Completed', {\n success: true,\n summary: content?.slice(0, 200),\n });\n }\n } else if (type === 'error') {\n const errorMsg = (e.error as string) || 'Unknown error';\n setExecutionStatus(requestId, 'failed', errorMsg, {\n success: false,\n error: errorMsg,\n });\n }\n}\n\n/**\n * Web Editor version configuration\n * - v1: Legacy inject-scripts/web-editor.js (IIFE, ~850 lines)\n * - v2: New TypeScript-based web-editor-v2.js (WXT unlisted script)\n *\n * Set USE_WEB_EDITOR_V2 to true to enable v2.\n * This flag allows gradual rollout and easy rollback.\n */\nconst USE_WEB_EDITOR_V2 = true;\n\n/** Script path for v1 (legacy) */\nconst V1_SCRIPT_PATH = 'inject-scripts/web-editor.js';\n\n/** Script path for v2 (WXT unlisted script output) */\nconst V2_SCRIPT_PATH = 'web-editor-v2.js';\n\n/** Script path for Phase 7 props agent (MAIN world) */\nconst PROPS_AGENT_SCRIPT_PATH = 'inject-scripts/props-agent.js';\n\ntype WebEditorInstructionType = 'update_text' | 'update_style';\n\ninterface WebEditorFingerprint {\n tag: string;\n id?: string;\n classes: string[];\n text?: string;\n}\n\n/** Debug source from React/Vue fiber (file, line, component name) */\ninterface DebugSource {\n file: string;\n line?: number;\n column?: number;\n componentName?: string;\n}\n\n/** Style operation details (before/after diff) */\ninterface StyleOperation {\n type: 'update_style';\n before: Record;\n after: Record;\n removed: string[];\n}\n\ninterface WebEditorApplyPayload {\n pageUrl: string;\n targetFile?: string;\n fingerprint: WebEditorFingerprint;\n techStackHint?: string[];\n instruction: {\n type: WebEditorInstructionType;\n description: string;\n text?: string;\n style?: Record;\n };\n\n // V2 extended fields (best-effort, optional)\n selectorCandidates?: string[];\n debugSource?: DebugSource;\n operation?: StyleOperation;\n}\n\nfunction normalizeString(value: unknown): string {\n return typeof value === 'string' ? value : '';\n}\n\nfunction normalizeStringArray(value: unknown): string[] {\n if (!Array.isArray(value)) return [];\n return value.map((item) => normalizeString(item)).filter(Boolean);\n}\n\nfunction normalizeStyleMap(value: unknown): Record | undefined {\n if (!value || typeof value !== 'object') return undefined;\n const out: Record = {};\n for (const [k, v] of Object.entries(value as Record)) {\n const key = normalizeString(k).trim();\n const val = normalizeString(v).trim();\n if (!key || !val) continue;\n out[key] = val;\n }\n return Object.keys(out).length ? out : undefined;\n}\n\nfunction normalizeStyleMapAllowEmpty(value: unknown): Record | undefined {\n if (!value || typeof value !== 'object') return undefined;\n const out: Record = {};\n for (const [k, v] of Object.entries(value as Record)) {\n const key = normalizeString(k).trim();\n if (!key) continue;\n // Allow empty values (represents removed styles)\n out[key] = normalizeString(v).trim();\n }\n return Object.keys(out).length ? out : undefined;\n}\n\nfunction normalizeDebugSource(value: unknown): DebugSource | undefined {\n if (!value || typeof value !== 'object') return undefined;\n const obj = value as Record;\n const file = normalizeString(obj.file).trim();\n if (!file) return undefined;\n\n const source: DebugSource = { file };\n const line = Number(obj.line);\n if (Number.isFinite(line) && line > 0) source.line = line;\n const column = Number(obj.column);\n if (Number.isFinite(column) && column >= 0) source.column = column;\n const componentName = normalizeString(obj.componentName).trim();\n if (componentName) source.componentName = componentName;\n\n return source;\n}\n\nfunction normalizeOperation(value: unknown): StyleOperation | undefined {\n if (!value || typeof value !== 'object') return undefined;\n const obj = value as Record;\n if (obj.type !== 'update_style') return undefined;\n\n const before = normalizeStyleMapAllowEmpty(obj.before);\n const after = normalizeStyleMapAllowEmpty(obj.after);\n const removed = normalizeStringArray(obj.removed);\n\n if (!before && !after && removed.length === 0) return undefined;\n\n return {\n type: 'update_style',\n before: before ?? {},\n after: after ?? {},\n removed,\n };\n}\n\nfunction normalizeApplyPayload(raw: unknown): WebEditorApplyPayload {\n const obj = (raw && typeof raw === 'object' ? raw : {}) as Record;\n const pageUrl = normalizeString(obj.pageUrl).trim();\n const targetFile = normalizeString(obj.targetFile).trim() || undefined;\n const techStackHint = normalizeStringArray(obj.techStackHint);\n\n const fingerprintRaw = (\n obj.fingerprint && typeof obj.fingerprint === 'object' ? obj.fingerprint : {}\n ) as Record;\n const fingerprint: WebEditorFingerprint = {\n tag: normalizeString(fingerprintRaw.tag).trim() || 'unknown',\n id: normalizeString(fingerprintRaw.id).trim() || undefined,\n classes: normalizeStringArray(fingerprintRaw.classes),\n text: normalizeString(fingerprintRaw.text).trim() || undefined,\n };\n\n const instructionRaw = (\n obj.instruction && typeof obj.instruction === 'object' ? obj.instruction : {}\n ) as Record;\n const type = normalizeString(instructionRaw.type).trim() as WebEditorInstructionType;\n if (type !== 'update_text' && type !== 'update_style') {\n throw new Error('Invalid instruction.type');\n }\n\n const instruction = {\n type,\n description: normalizeString(instructionRaw.description).trim() || '',\n text: normalizeString(instructionRaw.text).trim() || undefined,\n style: normalizeStyleMap(instructionRaw.style),\n };\n\n if (!pageUrl) {\n throw new Error('pageUrl is required');\n }\n if (!instruction.description) {\n throw new Error('instruction.description is required');\n }\n\n // V2 extended fields (optional)\n const selectorCandidates = normalizeStringArray(obj.selectorCandidates);\n const debugSource = normalizeDebugSource(obj.debugSource);\n const operation = normalizeOperation(obj.operation);\n\n return {\n pageUrl,\n targetFile,\n fingerprint,\n techStackHint: techStackHint.length ? techStackHint : undefined,\n instruction,\n selectorCandidates: selectorCandidates.length ? selectorCandidates : undefined,\n debugSource,\n operation,\n };\n}\n\n/**\n * Normalize and validate batch apply payload.\n * Runtime validation for WebEditorApplyBatchPayload.\n */\nfunction normalizeApplyBatchPayload(raw: unknown): WebEditorApplyBatchPayload {\n const obj = (raw && typeof raw === 'object' ? raw : {}) as Record;\n\n const tabIdRaw = Number(obj.tabId);\n const tabId = Number.isFinite(tabIdRaw) && tabIdRaw > 0 ? tabIdRaw : 0;\n\n const elements = Array.isArray(obj.elements) ? (obj.elements as ElementChangeSummary[]) : [];\n\n const excludedKeys = Array.isArray(obj.excludedKeys)\n ? obj.excludedKeys.map((k) => normalizeString(k).trim()).filter((k): k is string => Boolean(k))\n : [];\n\n const pageUrl = normalizeString(obj.pageUrl).trim() || undefined;\n\n return { tabId, elements, excludedKeys, pageUrl };\n}\n\n/**\n * Build a batch prompt for multiple element changes.\n * Designed for AgentChat integration to apply multiple visual edits at once.\n */\nfunction buildAgentPromptBatch(elements: readonly ElementChangeSummary[], pageUrl: string): string {\n const lines: string[] = [];\n\n // Header\n lines.push('You are a senior frontend engineer working in a local codebase.');\n lines.push(\n 'Goal: persist a batch of visual edits from the browser into the source code with minimal changes.',\n );\n lines.push('');\n\n // Page context\n lines.push(`Page URL: ${pageUrl}`);\n lines.push('');\n\n lines.push('## Batch Changes');\n lines.push(`Total elements: ${elements.length}`);\n lines.push('');\n lines.push(\n 'For each element, prefer \"source\" (file/line/component) when available; otherwise use selectors/fingerprint to locate it.',\n );\n lines.push('');\n\n // Element details\n elements.forEach((element, index) => {\n const title = element.fullLabel || element.label || element.elementKey;\n lines.push(`### ${index + 1}. ${title}`);\n lines.push(`- elementKey: ${element.elementKey}`);\n lines.push(`- change type: ${element.type}`);\n\n // Debug source (high-confidence location)\n const ds = element.debugSource ?? element.locator?.debugSource;\n if (ds?.file) {\n const loc = ds.line ? `${ds.file}:${ds.line}${ds.column ? `:${ds.column}` : ''}` : ds.file;\n lines.push(`- source: ${loc}${ds.componentName ? ` (${ds.componentName})` : ''}`);\n }\n\n // Locator hints for fallback\n if (element.locator?.selectors?.length) {\n lines.push('- selectors:');\n for (const sel of element.locator.selectors.slice(0, 5)) {\n lines.push(` - ${sel}`);\n }\n }\n if (element.locator?.fingerprint) {\n lines.push(`- fingerprint: ${element.locator.fingerprint}`);\n }\n if (Array.isArray(element.locator?.path) && element.locator.path.length > 0) {\n lines.push(`- path: ${JSON.stringify(element.locator.path)}`);\n }\n if (element.locator?.shadowHostChain?.length) {\n lines.push(`- shadowHostChain: ${JSON.stringify(element.locator.shadowHostChain)}`);\n }\n lines.push('');\n\n // Net effect details\n const net = element.netEffect;\n lines.push('#### Net Effect (apply these final values)');\n\n if (net.textChange) {\n lines.push('##### Text');\n lines.push(`- before: ${JSON.stringify(net.textChange.before)}`);\n lines.push(`- after: ${JSON.stringify(net.textChange.after)}`);\n lines.push('');\n }\n\n if (net.classChanges) {\n lines.push('##### Classes');\n lines.push(`- before: ${net.classChanges.before.join(' ')}`);\n lines.push(`- after: ${net.classChanges.after.join(' ')}`);\n lines.push('');\n }\n\n if (net.styleChanges) {\n lines.push('##### Styles (before → after)');\n const before = net.styleChanges.before ?? {};\n const after = net.styleChanges.after ?? {};\n const allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);\n for (const key of Array.from(allKeys).sort()) {\n const beforeVal = before[key] ?? '(unset)';\n const afterRaw = Object.prototype.hasOwnProperty.call(after, key) ? after[key] : '(unset)';\n const afterVal = afterRaw === '' ? '(removed)' : afterRaw;\n if (beforeVal !== afterVal) {\n lines.push(`- ${key}: \"${beforeVal}\" → \"${afterVal}\"`);\n }\n }\n lines.push('');\n }\n\n // Fallback message if no specific changes\n if (!net.textChange && !net.classChanges && !net.styleChanges) {\n lines.push(\n '- No net effect details available; use locator hints to inspect the element in code.',\n );\n lines.push('');\n }\n });\n\n // Instructions\n lines.push('## How to Apply');\n lines.push('1. Use \"source\" when available to go directly to the component file.');\n lines.push('2. Otherwise, use selectors/fingerprint/path to locate the element in the codebase.');\n lines.push('3. Apply the net effect with minimal changes and correct styling conventions.');\n lines.push('4. Avoid generated/bundled outputs; update source files only.');\n lines.push('');\n\n // Output format\n lines.push('## Constraints');\n lines.push('- Make the smallest safe edit possible for each element');\n lines.push(\n '- If Tailwind/CSS Modules/styled-components are used, update the correct styling source',\n );\n lines.push('- Do not change unrelated behavior or formatting');\n lines.push('');\n\n lines.push(\n '## Output\\nApply all the changes in the repo, then reply with a short summary of what file(s) you modified and the exact changes made.',\n );\n\n return lines.join('\\n');\n}\n\nfunction buildAgentPrompt(payload: WebEditorApplyPayload): string {\n const lines: string[] = [];\n\n // Header\n lines.push('You are a senior frontend engineer working in a local codebase.');\n lines.push(\n 'Goal: persist a visual edit from the browser into the source code with minimal changes.',\n );\n lines.push('');\n\n // Page context\n lines.push(`Page URL: ${payload.pageUrl}`);\n lines.push('');\n\n // == Source Location (high-confidence if debugSource available) ==\n const ds = payload.debugSource;\n if (ds?.file) {\n lines.push('## Source Location (from React/Vue debug info)');\n const loc = ds.line ? `${ds.file}:${ds.line}${ds.column ? `:${ds.column}` : ''}` : ds.file;\n lines.push(`- file: ${loc}`);\n if (ds.componentName) lines.push(`- component: ${ds.componentName}`);\n lines.push('');\n lines.push('This is high-confidence source location extracted from framework debug info.');\n lines.push('Start your search here. Only fall back to fingerprint if this file is invalid.');\n lines.push('');\n } else if (payload.targetFile) {\n lines.push(`## Target File (best-effort): ${payload.targetFile}`);\n lines.push(\n 'If this path is invalid or points to node_modules, fall back to fingerprint search.',\n );\n lines.push('');\n }\n\n // == Element Fingerprint ==\n lines.push('## Element Fingerprint');\n lines.push(`- tag: ${payload.fingerprint.tag}`);\n if (payload.fingerprint.id) lines.push(`- id: ${payload.fingerprint.id}`);\n if (payload.fingerprint.classes?.length) {\n lines.push(`- classes: ${payload.fingerprint.classes.join(' ')}`);\n }\n if (payload.fingerprint.text) lines.push(`- text: ${payload.fingerprint.text}`);\n lines.push('');\n\n // == CSS Selectors (for precise matching) ==\n if (payload.selectorCandidates?.length) {\n lines.push('## CSS Selectors (ordered by specificity)');\n for (const sel of payload.selectorCandidates.slice(0, 5)) {\n lines.push(`- ${sel}`);\n }\n lines.push('');\n lines.push('Use these selectors to grep the codebase if file location is unavailable.');\n lines.push('');\n }\n\n // == Tech Stack ==\n if (payload.techStackHint?.length) {\n lines.push(`## Tech Stack: ${payload.techStackHint.join(', ')}`);\n lines.push('');\n }\n\n // == Requested Change ==\n lines.push('## Requested Change');\n lines.push(`- type: ${payload.instruction.type}`);\n lines.push(`- description: ${payload.instruction.description}`);\n\n if (payload.instruction.type === 'update_text' && payload.instruction.text !== undefined) {\n lines.push(`- new text: ${JSON.stringify(payload.instruction.text)}`);\n }\n\n // For style updates, show detailed before/after diff if available\n if (payload.instruction.type === 'update_style') {\n const op = payload.operation;\n if (op && (Object.keys(op.before).length > 0 || Object.keys(op.after).length > 0)) {\n lines.push('');\n lines.push('### Style Changes (before → after)');\n const allKeys = new Set([...Object.keys(op.before), ...Object.keys(op.after)]);\n for (const key of allKeys) {\n const before = op.before[key] ?? '(unset)';\n const after = op.after[key] ?? '(removed)';\n if (before !== after) {\n lines.push(` ${key}: \"${before}\" → \"${after}\"`);\n }\n }\n if (op.removed.length > 0) {\n lines.push(` [Removed]: ${op.removed.join(', ')}`);\n }\n } else if (payload.instruction.style) {\n lines.push(`- style map: ${JSON.stringify(payload.instruction.style, null, 2)}`);\n }\n }\n lines.push('');\n\n // == Instructions ==\n lines.push('## How to Apply');\n if (ds?.file) {\n lines.push(`1. Open ${ds.file}${ds.line ? ` around line ${ds.line}` : ''}`);\n if (ds.componentName) {\n lines.push(`2. Locate the \"${ds.componentName}\" component definition`);\n }\n lines.push(\n `3. Find the element matching tag=\"${payload.fingerprint.tag}\"${payload.fingerprint.classes?.length ? ` with classes including \"${payload.fingerprint.classes[0]}\"` : ''}`,\n );\n lines.push('4. Apply the requested style/text change');\n } else if (payload.targetFile) {\n lines.push(`1. Open ${payload.targetFile}`);\n lines.push('2. Search for the element by matching fingerprint (tag, classes, text)');\n lines.push('3. If not found, use repo-wide search with selectors or class names');\n lines.push('4. Apply the requested change');\n } else {\n lines.push('1. Use repo-wide search (rg) with class names or text from fingerprint');\n if (payload.selectorCandidates?.length) {\n lines.push(`2. Try searching for: \"${payload.selectorCandidates[0]}\"`);\n }\n lines.push('3. Locate the component/template containing this element');\n lines.push('4. Apply the requested change');\n }\n lines.push('');\n\n // == Constraints ==\n lines.push('## Constraints');\n lines.push('- Make the smallest safe edit possible');\n if (payload.techStackHint?.includes('Tailwind')) {\n lines.push('- Tailwind detected: prefer updating className over inline styles');\n }\n if (payload.techStackHint?.includes('React') || payload.techStackHint?.includes('Vue')) {\n lines.push('- Update the component source, not generated/bundled code');\n }\n lines.push('- If CSS Modules or styled-components are used, update the correct styling source');\n lines.push('- Do not change unrelated behavior or formatting');\n lines.push('');\n\n // == Output ==\n lines.push(\n '## Output\\nApply the change in the repo, then reply with a short summary of what file(s) you modified and the exact change made.',\n );\n\n return lines.join('\\n');\n}\n\nasync function ensureContextMenu(): Promise {\n try {\n if (!(chrome as any).contextMenus?.create) return;\n try {\n await chrome.contextMenus.remove(CONTEXT_MENU_ID);\n } catch {}\n await chrome.contextMenus.create({\n id: CONTEXT_MENU_ID,\n title: '切换网页编辑模式',\n contexts: ['all'],\n });\n } catch (error) {\n console.warn('[WebEditor] Failed to ensure context menu:', error);\n }\n}\n\n/**\n * Get the appropriate action constants based on version\n */\nfunction getActions() {\n return USE_WEB_EDITOR_V2 ? WEB_EDITOR_V2_ACTIONS : WEB_EDITOR_V1_ACTIONS;\n}\n\n/**\n * Ensure the web editor script is injected into the tab\n * Supports both v1 (legacy) and v2 (new) versions\n *\n * V1 and V2 use different action names to avoid conflicts:\n * - V1: web_editor_ping, web_editor_toggle, etc.\n * - V2: web_editor_ping_v2, web_editor_toggle_v2, etc.\n */\nasync function ensureEditorInjected(tabId: number): Promise {\n const scriptPath = USE_WEB_EDITOR_V2 ? V2_SCRIPT_PATH : V1_SCRIPT_PATH;\n const logPrefix = USE_WEB_EDITOR_V2 ? '[WebEditorV2]' : '[WebEditor]';\n const actions = getActions();\n\n // Try to ping existing instance using version-specific action\n try {\n const pong: { status?: string; version?: number } = await chrome.tabs.sendMessage(\n tabId,\n { action: actions.PING },\n { frameId: 0 },\n );\n\n if (pong?.status === 'pong') {\n // Already injected with correct version\n return;\n }\n } catch {\n // No existing instance, fallthrough to inject\n }\n\n // Inject the script\n try {\n await chrome.scripting.executeScript({\n target: { tabId },\n files: [scriptPath],\n world: 'ISOLATED',\n });\n console.log(`${logPrefix} Script injected successfully`);\n } catch (error) {\n console.warn(`${logPrefix} Failed to inject editor script:`, error);\n }\n}\n\n/**\n * Inject props agent into MAIN world for Phase 7 Props editing\n * Only inject for v2 editor\n */\nasync function ensurePropsAgentInjected(tabId: number): Promise {\n if (!USE_WEB_EDITOR_V2) return;\n\n try {\n await chrome.scripting.executeScript({\n target: { tabId },\n files: [PROPS_AGENT_SCRIPT_PATH],\n world: 'MAIN',\n });\n } catch (error) {\n // Best-effort: some pages (chrome://, extensions, PDF) block injection\n console.warn('[WebEditorV2] Failed to inject props agent:', error);\n }\n}\n\n/**\n * Send cleanup event to props agent\n */\nasync function sendPropsAgentCleanup(tabId: number): Promise {\n if (!USE_WEB_EDITOR_V2) return;\n\n try {\n // Dispatch cleanup event in ISOLATED world\n // CustomEvent crosses worlds and is observed by MAIN agent\n await chrome.scripting.executeScript({\n target: { tabId },\n func: () => {\n try {\n window.dispatchEvent(new CustomEvent('web-editor-props:cleanup'));\n } catch {\n // ignore\n }\n },\n world: 'ISOLATED',\n });\n } catch (error) {\n // Best-effort cleanup; ignore failures if tab is gone or injection blocked\n console.warn('[WebEditorV2] Failed to send props agent cleanup:', error);\n }\n}\n\n// =============================================================================\n// Phase 7.1.6: Early Injection for Props Agent\n// =============================================================================\n\n/**\n * Content script ID prefix for early injection (document_start).\n * Registered scripts persist across sessions and survive browser restarts.\n */\nconst PROPS_AGENT_EARLY_INJECTION_ID_PREFIX = 'mcp_we_props_early';\n\n/**\n * Result of early injection registration\n */\ninterface EarlyInjectionResult {\n id: string;\n host: string;\n matches: string[];\n alreadyRegistered: boolean;\n}\n\n/**\n * Sanitize a string for use in content script ID\n * Only allows alphanumeric, underscore, and hyphen\n */\nfunction sanitizeContentScriptId(input: string): string {\n const cleaned = String(input ?? '')\n .toLowerCase()\n .replace(/[^a-z0-9_-]+/g, '_')\n .replace(/^_+|_+$/g, '');\n return cleaned.slice(0, 80) || 'site';\n}\n\n/**\n * Build match patterns from tab URL for early injection.\n * Returns patterns for the specific host only (not all URLs).\n */\nfunction buildEarlyInjectionPatterns(tabUrl: string): { host: string; matches: string[] } {\n let url: URL;\n try {\n url = new URL(tabUrl);\n } catch {\n throw new Error('Invalid tab URL');\n }\n\n if (url.protocol !== 'http:' && url.protocol !== 'https:') {\n throw new Error(`Early injection only supports http/https pages (got ${url.protocol})`);\n }\n\n const host = url.hostname.trim();\n if (!host) {\n throw new Error('Unable to derive host from tab URL');\n }\n\n // Match all paths on this host for both http and https\n return { host, matches: [`*://${host}/*`] };\n}\n\n/**\n * Register props agent for early injection (document_start, MAIN world).\n * This allows capturing React DevTools hook before React initializes.\n *\n * The registration is per-host and persists across sessions.\n */\nasync function registerPropsAgentEarlyInjection(tabUrl: string): Promise {\n const { host, matches } = buildEarlyInjectionPatterns(tabUrl);\n const id = `${PROPS_AGENT_EARLY_INJECTION_ID_PREFIX}_${sanitizeContentScriptId(host)}`;\n\n // Check if already registered (idempotent)\n let alreadyRegistered = false;\n try {\n const existing = await chrome.scripting.getRegisteredContentScripts({ ids: [id] });\n alreadyRegistered = existing.some((s) => s.id === id);\n } catch {\n // API might not support getRegisteredContentScripts in all contexts\n alreadyRegistered = false;\n }\n\n if (!alreadyRegistered) {\n await chrome.scripting.registerContentScripts([\n {\n id,\n js: [PROPS_AGENT_SCRIPT_PATH],\n matches,\n runAt: 'document_start',\n world: 'MAIN',\n allFrames: false,\n persistAcrossSessions: true,\n },\n ]);\n console.log(`[WebEditorV2] Registered early injection for ${host}`);\n }\n\n return { id, host, matches, alreadyRegistered };\n}\n\nasync function toggleEditorInTab(tabId: number): Promise<{ active?: boolean }> {\n await ensureEditorInjected(tabId);\n const logPrefix = USE_WEB_EDITOR_V2 ? '[WebEditorV2]' : '[WebEditor]';\n const actions = getActions();\n\n try {\n const resp: { active?: boolean } = await chrome.tabs.sendMessage(\n tabId,\n { action: actions.TOGGLE },\n { frameId: 0 },\n );\n const active = typeof resp?.active === 'boolean' ? resp.active : undefined;\n\n // Phase 7: Inject props agent on start; cleanup on stop\n if (active === true) {\n await ensurePropsAgentInjected(tabId);\n } else if (active === false) {\n await sendPropsAgentCleanup(tabId);\n }\n\n return { active };\n } catch (error) {\n console.warn(`${logPrefix} Failed to toggle editor in tab:`, error);\n return {};\n }\n}\n\nasync function getActiveTabId(): Promise {\n try {\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n return typeof tabId === 'number' ? tabId : null;\n } catch {\n return null;\n }\n}\n\nexport function initWebEditorListeners(): void {\n ensureContextMenu().catch(() => {});\n\n // Clean up session storage when tab is closed to avoid stale data\n chrome.tabs.onRemoved.addListener((tabId) => {\n try {\n const keys = [\n `${WEB_EDITOR_TX_CHANGED_SESSION_KEY_PREFIX}${tabId}`,\n `${WEB_EDITOR_SELECTION_SESSION_KEY_PREFIX}${tabId}`,\n `${WEB_EDITOR_EXCLUDED_KEYS_SESSION_KEY_PREFIX}${tabId}`,\n ];\n chrome.storage.session.remove(keys).catch(() => {});\n } catch {}\n });\n\n if ((chrome as any).contextMenus?.onClicked?.addListener) {\n chrome.contextMenus.onClicked.addListener(async (info, tab) => {\n try {\n if (info.menuItemId !== CONTEXT_MENU_ID) return;\n const tabId = tab?.id;\n if (typeof tabId !== 'number') return;\n await toggleEditorInTab(tabId);\n } catch {}\n });\n }\n\n chrome.commands.onCommand.addListener(async (command) => {\n try {\n if (command !== COMMAND_KEY) return;\n const tabId = await getActiveTabId();\n if (typeof tabId !== 'number') return;\n await toggleEditorInTab(tabId);\n } catch {}\n });\n\n chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {\n try {\n // Phase 7.1.6: Handle early injection registration request\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_PROPS_REGISTER_EARLY_INJECTION) {\n (async () => {\n const senderTab = (_sender as chrome.runtime.MessageSender)?.tab;\n const senderTabId = senderTab?.id;\n const senderTabUrl = senderTab?.url;\n\n if (typeof senderTabId !== 'number' || typeof senderTabUrl !== 'string') {\n return sendResponse({\n success: false,\n error: 'Sender tab information is required',\n });\n }\n\n try {\n const result = await registerPropsAgentEarlyInjection(senderTabUrl);\n\n // Respond first, then reload (to avoid message port closing during navigation)\n sendResponse({ success: true, ...result });\n\n // Small delay to ensure response is sent before navigation\n await new Promise((resolve) => setTimeout(resolve, 50));\n\n // Reload the tab so early injection takes effect\n try {\n await chrome.tabs.reload(senderTabId);\n } catch {\n // Best-effort: some tabs may block reload\n }\n } catch (err) {\n sendResponse({\n success: false,\n error: err instanceof Error ? err.message : String(err),\n });\n }\n })();\n return true; // Async response\n }\n\n // =====================================================================\n // WEB_EDITOR_OPEN_SOURCE: Open component source file in VSCode\n // =====================================================================\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_OPEN_SOURCE) {\n (async () => {\n try {\n const payload = message.payload as { debugSource?: unknown } | undefined;\n const debugSource = payload?.debugSource;\n\n if (!debugSource || typeof debugSource !== 'object') {\n return sendResponse({ success: false, error: 'debugSource is required' });\n }\n\n const rec = debugSource as Record;\n const file = typeof rec.file === 'string' ? rec.file.trim() : '';\n if (!file) {\n return sendResponse({ success: false, error: 'debugSource.file is required' });\n }\n\n // Read server port and selected project\n const stored = await chrome.storage.local.get([\n 'nativeServerPort',\n 'agent-selected-project-id',\n ]);\n const portRaw = stored.nativeServerPort;\n const port = Number.isFinite(Number(portRaw))\n ? Number(portRaw)\n : DEFAULT_NATIVE_SERVER_PORT;\n const projectId = stored['agent-selected-project-id'];\n\n if (!projectId || typeof projectId !== 'string') {\n return sendResponse({\n success: false,\n error: 'No project selected. Please select a project in AgentChat first.',\n });\n }\n\n // Prepare line/column\n const lineRaw = Number(rec.line);\n const columnRaw = Number(rec.column);\n const line = Number.isFinite(lineRaw) && lineRaw > 0 ? lineRaw : undefined;\n const column = Number.isFinite(columnRaw) && columnRaw > 0 ? columnRaw : undefined;\n\n // Call native-server to open file (server will validate project and path)\n const openResp = await fetch(\n `http://127.0.0.1:${port}/agent/projects/${encodeURIComponent(projectId)}/open-file`,\n {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n filePath: file,\n line,\n column,\n }),\n },\n );\n\n // Try to parse JSON response for detailed error\n let result: { success: boolean; error?: string };\n try {\n result = await openResp.json();\n } catch {\n const text = await openResp.text().catch(() => '');\n result = {\n success: false,\n error: text || `HTTP ${openResp.status}`,\n };\n }\n\n sendResponse(result);\n } catch (err) {\n sendResponse({\n success: false,\n error: err instanceof Error ? err.message : String(err),\n });\n }\n })();\n return true; // Async response\n }\n\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_TOGGLE) {\n getActiveTabId()\n .then(async (tabId) => {\n if (typeof tabId !== 'number') return sendResponse({ success: false });\n const result = await toggleEditorInTab(tabId);\n sendResponse({ success: true, ...result });\n })\n .catch(() => sendResponse({ success: false }));\n return true;\n }\n\n // =======================================================================\n // Phase 1.5: Handle TX_CHANGED broadcast from web-editor\n // =======================================================================\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_TX_CHANGED) {\n (async () => {\n const senderTabId = (_sender as chrome.runtime.MessageSender)?.tab?.id;\n if (typeof senderTabId !== 'number') {\n sendResponse({ success: false, error: 'Sender tabId is required' });\n return;\n }\n\n const rawPayload = message.payload as WebEditorTxChangedPayload | undefined;\n if (!rawPayload || typeof rawPayload !== 'object') {\n sendResponse({ success: false, error: 'Invalid payload' });\n return;\n }\n\n // Hydrate payload with tabId from sender\n const payload: WebEditorTxChangedPayload = { ...rawPayload, tabId: senderTabId };\n const storageKey = `${WEB_EDITOR_TX_CHANGED_SESSION_KEY_PREFIX}${senderTabId}`;\n\n // Persist to session storage for cold-start recovery\n // Remove keys on clear to avoid stale data (rollback still has edits, so keep it)\n if (payload.action === 'clear') {\n // Clear TX state and excluded keys together\n const excludedKey = `${WEB_EDITOR_EXCLUDED_KEYS_SESSION_KEY_PREFIX}${senderTabId}`;\n await chrome.storage.session.remove([storageKey, excludedKey]);\n } else {\n await chrome.storage.session.set({ [storageKey]: payload });\n }\n\n // Broadcast to sidepanel (best-effort, ignore errors if sidepanel is closed)\n chrome.runtime\n .sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_TX_CHANGED,\n payload,\n })\n .catch(() => {\n // Ignore errors - sidepanel may be closed\n });\n\n sendResponse({ success: true });\n })().catch((error) => {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n });\n return true;\n }\n\n // =======================================================================\n // Selection sync: Handle SELECTION_CHANGED broadcast from web-editor\n // =======================================================================\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_SELECTION_CHANGED) {\n (async () => {\n const senderTabId = (_sender as chrome.runtime.MessageSender)?.tab?.id;\n if (typeof senderTabId !== 'number') {\n sendResponse({ success: false, error: 'Sender tabId is required' });\n return;\n }\n\n const rawPayload = message.payload as\n | import('@/common/web-editor-types').WebEditorSelectionChangedPayload\n | undefined;\n if (!rawPayload || typeof rawPayload !== 'object') {\n sendResponse({ success: false, error: 'Invalid payload' });\n return;\n }\n\n // Hydrate payload with tabId from sender\n const payload = { ...rawPayload, tabId: senderTabId };\n const storageKey = `${WEB_EDITOR_SELECTION_SESSION_KEY_PREFIX}${senderTabId}`;\n\n // Persist to session storage for cold-start recovery\n // Remove key on deselection to avoid stale data\n if (payload.selected === null) {\n await chrome.storage.session.remove(storageKey);\n } else {\n await chrome.storage.session.set({ [storageKey]: payload });\n }\n\n // Broadcast to sidepanel (best-effort, ignore errors if sidepanel is closed)\n chrome.runtime\n .sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_SELECTION_CHANGED,\n payload,\n })\n .catch(() => {\n // Ignore errors - sidepanel may be closed\n });\n\n sendResponse({ success: true });\n })().catch((error) => {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n });\n return true;\n }\n\n // =======================================================================\n // Clear selection: Handle CLEAR_SELECTION from sidepanel (after send)\n // =======================================================================\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_CLEAR_SELECTION) {\n (async () => {\n const payload = message.payload as { tabId?: number } | undefined;\n const targetTabId = payload?.tabId;\n\n if (typeof targetTabId !== 'number' || targetTabId <= 0) {\n sendResponse({ success: false, error: 'Invalid tabId' });\n return;\n }\n\n // Forward to content script (web-editor-v2)\n try {\n await chrome.tabs.sendMessage(targetTabId, {\n action: WEB_EDITOR_V2_ACTIONS.CLEAR_SELECTION,\n });\n sendResponse({ success: true });\n } catch (error) {\n // Tab may be closed or web-editor not active - this is expected\n sendResponse({\n success: false,\n error: error instanceof Error ? error.message : 'Failed to send to tab',\n });\n }\n })().catch((error) => {\n // Catch any unhandled errors in the async IIFE\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n });\n return true;\n }\n\n // =======================================================================\n // Phase 1.5: Handle APPLY_BATCH from web-editor toolbar\n // =======================================================================\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_APPLY_BATCH) {\n const payload = normalizeApplyBatchPayload(message.payload);\n (async () => {\n const senderTabId = (_sender as chrome.runtime.MessageSender)?.tab?.id;\n const senderWindowId = (_sender as chrome.runtime.MessageSender)?.tab?.windowId;\n\n // Read storage for server port and selected session\n const stored = await chrome.storage.local.get([\n 'nativeServerPort',\n STORAGE_KEY_SELECTED_SESSION,\n ]);\n\n const portRaw = stored?.nativeServerPort;\n const port = Number.isFinite(Number(portRaw))\n ? Number(portRaw)\n : DEFAULT_NATIVE_SERVER_PORT;\n\n const sessionId = normalizeString(stored?.[STORAGE_KEY_SELECTED_SESSION]).trim();\n\n // Best-effort: open AgentChat sidepanel so user can see the session\n // Pass sessionId for deep linking directly to chat view\n if (typeof senderTabId === 'number') {\n openAgentChatSidepanel(senderTabId, senderWindowId, sessionId || undefined).catch(\n () => {},\n );\n }\n\n if (!sessionId) {\n // No session selected - sidepanel is already being opened (best-effort)\n // User needs to select or create a session manually\n sendResponse({\n success: false,\n error:\n 'No Agent session selected. Please select or create a session in AgentChat, then try Apply again.',\n });\n return;\n }\n\n // Hydrate payload with tabId\n const hydratedPayload: WebEditorApplyBatchPayload =\n typeof senderTabId === 'number' ? { ...payload, tabId: senderTabId } : payload;\n\n // Read excluded keys from session storage (per-tab, managed by sidepanel)\n let sessionExcludedKeys: string[] = [];\n if (typeof senderTabId === 'number') {\n const excludedSessionKey = `${WEB_EDITOR_EXCLUDED_KEYS_SESSION_KEY_PREFIX}${senderTabId}`;\n try {\n if (chrome.storage?.session?.get) {\n const stored = (await chrome.storage.session.get(excludedSessionKey)) as Record<\n string,\n unknown\n >;\n const raw = stored?.[excludedSessionKey];\n sessionExcludedKeys = Array.isArray(raw)\n ? raw.map((k) => normalizeString(k).trim()).filter(Boolean)\n : [];\n }\n } catch {\n // Best-effort: ignore session storage failures\n }\n }\n\n // Filter out excluded elements (union: payload excludedKeys + session excludedKeys)\n const excluded = new Set([...hydratedPayload.excludedKeys, ...sessionExcludedKeys]);\n const elements = hydratedPayload.elements.filter((e) => !excluded.has(e.elementKey));\n if (elements.length === 0) {\n sendResponse({ success: false, error: 'No elements selected to apply.' });\n return;\n }\n\n // Build page URL from payload or sender tab\n const pageUrl =\n normalizeString(hydratedPayload.pageUrl).trim() ||\n normalizeString((_sender as chrome.runtime.MessageSender)?.tab?.url).trim() ||\n 'unknown';\n\n // Build batch prompt and send to agent\n const instruction = buildAgentPromptBatch(elements, pageUrl);\n const url = `http://127.0.0.1:${port}/agent/chat/${encodeURIComponent(sessionId)}/act`;\n\n // Extract element labels for compact display\n const elementLabels = elements.slice(0, 5).map((e) => e.label);\n\n const resp = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n instruction,\n // Pass dbSessionId so backend loads session-level configuration (engine, model, options)\n dbSessionId: sessionId,\n // Display text for UI (compact representation)\n displayText: `Apply ${elements.length} change${elements.length === 1 ? '' : 's'}`,\n // Client metadata for special message rendering\n clientMeta: {\n kind: 'web_editor_apply_batch',\n pageUrl,\n elementCount: elements.length,\n elementLabels,\n },\n }),\n });\n\n if (!resp.ok) {\n const text = await resp.text().catch(() => '');\n sendResponse({\n success: false,\n error: text || `HTTP ${resp.status}`,\n });\n return;\n }\n\n const json: any = await resp.json().catch(() => ({}));\n const requestId = json?.requestId as string | undefined;\n\n if (requestId) {\n // Start SSE subscription for status updates (fire and forget)\n subscribeToSessionStatus(sessionId, requestId, port).catch(() => {});\n }\n\n sendResponse({ success: true, requestId, sessionId });\n })().catch((error) => {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n });\n return true;\n }\n\n // =======================================================================\n // Phase 1.8: Handle HIGHLIGHT_ELEMENT from sidepanel chips hover\n // =======================================================================\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_HIGHLIGHT_ELEMENT) {\n const payload = message.payload as WebEditorHighlightElementPayload | undefined;\n (async () => {\n // Validate payload\n const tabId = payload?.tabId;\n if (typeof tabId !== 'number' || !Number.isFinite(tabId) || tabId <= 0) {\n sendResponse({ success: false, error: 'Invalid tabId' });\n return;\n }\n\n const mode = payload?.mode;\n if (mode !== 'hover' && mode !== 'clear') {\n sendResponse({ success: false, error: 'Invalid mode' });\n return;\n }\n\n // Clear mode: forward directly without locator/selector validation\n // This prevents overlay residue when sidepanel unmounts\n if (mode === 'clear') {\n try {\n const response = await chrome.tabs.sendMessage(tabId, {\n action: WEB_EDITOR_V2_ACTIONS.HIGHLIGHT_ELEMENT,\n mode: 'clear',\n });\n sendResponse({ success: true, response });\n } catch (error) {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n }\n return;\n }\n\n // Hover mode: validate and forward locator\n const locator = payload?.locator;\n if (!locator || typeof locator !== 'object') {\n sendResponse({ success: false, error: 'Invalid locator' });\n return;\n }\n\n // Extract best selector for fallback highlighting\n const selectors = Array.isArray(locator.selectors) ? locator.selectors : [];\n const primarySelector = selectors.find(\n (s): s is string => typeof s === 'string' && s.trim().length > 0,\n );\n\n if (!primarySelector) {\n sendResponse({ success: false, error: 'No valid selector in locator' });\n return;\n }\n\n // Forward to web-editor content script\n try {\n const response = await chrome.tabs.sendMessage(tabId, {\n action: WEB_EDITOR_V2_ACTIONS.HIGHLIGHT_ELEMENT,\n locator, // Full locator for Shadow DOM/iframe support\n selector: primarySelector, // Backward compatibility fallback\n mode,\n elementKey: payload.elementKey,\n });\n\n sendResponse({ success: true, response });\n } catch (error) {\n // Content script might not be available\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n }\n })().catch((error) => {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n });\n return true;\n }\n\n // =======================================================================\n // Phase 2: Handle REVERT_ELEMENT from sidepanel chips\n // =======================================================================\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_REVERT_ELEMENT) {\n const payload = message.payload as WebEditorRevertElementPayload | undefined;\n (async () => {\n // Validate payload\n const tabId = payload?.tabId;\n if (typeof tabId !== 'number' || !Number.isFinite(tabId) || tabId <= 0) {\n sendResponse({ success: false, error: 'Invalid tabId' });\n return;\n }\n\n const elementKey = payload?.elementKey;\n if (typeof elementKey !== 'string' || !elementKey.trim()) {\n sendResponse({ success: false, error: 'Invalid elementKey' });\n return;\n }\n\n // Forward to web-editor content script (frameId: 0 for main frame only)\n try {\n const response = await chrome.tabs.sendMessage(\n tabId,\n {\n action: WEB_EDITOR_V2_ACTIONS.REVERT_ELEMENT,\n elementKey,\n },\n { frameId: 0 },\n );\n\n sendResponse({ success: true, ...response });\n } catch (error) {\n // Content script might not be available\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n }\n })().catch((error) => {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n });\n return true;\n }\n\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_APPLY) {\n const payload = normalizeApplyPayload(message.payload);\n (async () => {\n const senderTabId = (_sender as any)?.tab?.id;\n const sessionId =\n typeof senderTabId === 'number' ? `web-editor-${senderTabId}` : 'web-editor';\n\n const stored = await chrome.storage.local.get([\n 'nativeServerPort',\n 'agent-selected-project-id',\n ]);\n const portRaw = stored?.nativeServerPort;\n const port = Number.isFinite(Number(portRaw))\n ? Number(portRaw)\n : DEFAULT_NATIVE_SERVER_PORT;\n\n const projectId = normalizeString(stored?.['agent-selected-project-id']).trim() || '';\n\n if (!projectId) {\n return sendResponse({\n success: false,\n error:\n 'No Agent project selected. Open Side Panel → 智能助手 and select/create a project first.',\n });\n }\n\n const instruction = buildAgentPrompt(payload);\n const url = `http://127.0.0.1:${port}/agent/chat/${encodeURIComponent(sessionId)}/act`;\n\n const resp = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n instruction,\n projectId,\n }),\n });\n\n if (!resp.ok) {\n const text = await resp.text().catch(() => '');\n return sendResponse({\n success: false,\n error: text || `HTTP ${resp.status}`,\n });\n }\n\n const json: any = await resp.json().catch(() => ({}));\n const requestId = json?.requestId as string | undefined;\n\n if (requestId) {\n // Start SSE subscription for status updates (fire and forget)\n subscribeToSessionStatus(sessionId, requestId, port).catch(() => {});\n }\n\n return sendResponse({ success: true, requestId, sessionId });\n })().catch((error) => {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n });\n return true;\n }\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_STATUS_QUERY) {\n const { requestId } = message;\n if (!requestId || typeof requestId !== 'string') {\n sendResponse({ success: false, error: 'requestId is required' });\n return false;\n }\n\n const entry = getExecutionStatus(requestId);\n if (!entry) {\n // No status yet - likely still pending or not tracked\n sendResponse({ success: true, status: 'pending', message: 'Waiting for status...' });\n } else {\n sendResponse({\n success: true,\n status: entry.status,\n message: entry.message,\n result: entry.result,\n });\n }\n return false; // Synchronous response\n }\n\n // =======================================================================\n // Cancel Execution: Handle WEB_EDITOR_CANCEL_EXECUTION from toolbar/sidepanel\n // =======================================================================\n if (message?.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_CANCEL_EXECUTION) {\n const payload = message.payload as WebEditorCancelExecutionPayload | undefined;\n (async () => {\n // Validate payload\n const sessionId = payload?.sessionId?.trim();\n const requestId = payload?.requestId?.trim();\n\n if (!sessionId) {\n sendResponse({\n success: false,\n error: 'sessionId is required',\n } as WebEditorCancelExecutionResponse);\n return;\n }\n if (!requestId) {\n sendResponse({\n success: false,\n error: 'requestId is required',\n } as WebEditorCancelExecutionResponse);\n return;\n }\n\n // Get server port\n const stored = await chrome.storage.local.get(['nativeServerPort']);\n const port = stored.nativeServerPort || DEFAULT_NATIVE_SERVER_PORT;\n\n try {\n // Call cancel API\n const cancelUrl = `http://127.0.0.1:${port}/agent/chat/${encodeURIComponent(sessionId)}/cancel/${encodeURIComponent(requestId)}`;\n const response = await fetch(cancelUrl, { method: 'DELETE' });\n\n if (!response.ok) {\n const errorText = await response.text().catch(() => `HTTP ${response.status}`);\n sendResponse({\n success: false,\n error: errorText,\n } as WebEditorCancelExecutionResponse);\n return;\n }\n\n // Update local execution status cache\n setExecutionStatus(requestId, 'cancelled', 'Execution cancelled by user');\n\n // Abort SSE connection for this session\n const sseConnection = sseConnections.get(sessionId);\n if (sseConnection && sseConnection.lastRequestId === requestId) {\n sseConnection.abort.abort();\n sseConnections.delete(sessionId);\n }\n\n sendResponse({ success: true } as WebEditorCancelExecutionResponse);\n } catch (error) {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n } as WebEditorCancelExecutionResponse);\n }\n })().catch((error) => {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n } as WebEditorCancelExecutionResponse);\n });\n return true; // Will respond asynchronously\n }\n } catch (error) {\n sendResponse({\n success: false,\n error: String(error instanceof Error ? error.message : error),\n });\n }\n return false;\n });\n}\n" }, { "path": "app/chrome-extension/entrypoints/builder/App.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/builder/index.html", "content": "\n\n \n \n \n 工作流编辑器\n \n \n \n
\n \n \n\n" }, { "path": "app/chrome-extension/entrypoints/builder/main.ts", "content": "import { createApp } from 'vue';\nimport App from './App.vue';\n\n// Tailwind first, then custom tokens\nimport '../styles/tailwind.css';\n\ncreateApp(App).mount('#app');\n" }, { "path": "app/chrome-extension/entrypoints/content.ts", "content": "export default defineContentScript({\n matches: ['*://*.google.com/*'],\n main() {},\n});\n" }, { "path": "app/chrome-extension/entrypoints/element-picker.content.ts", "content": "/**\n * Element Picker Content Script\n *\n * Renders the Element Picker Panel UI (Quick Panel style) and forwards UI events\n * to background while a chrome_request_element_selection session is active.\n *\n * This script only runs in the top frame and handles:\n * - Displaying the element picker panel UI\n * - Forwarding user actions (cancel, confirm, etc.) to background\n * - Receiving state updates from background\n */\n\nimport {\n createElementPickerController,\n type ElementPickerController,\n type ElementPickerUiState,\n} from '@/shared/element-picker';\nimport { BACKGROUND_MESSAGE_TYPES, TOOL_MESSAGE_TYPES } from '@/common/message-types';\nimport type { PickedElement } from 'chrome-mcp-shared';\n\n// ============================================================\n// Message Types\n// ============================================================\n\ninterface UiShowMessage {\n action: typeof TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_SHOW;\n sessionId: string;\n requests: Array<{ id: string; name: string; description?: string }>;\n activeRequestId: string | null;\n deadlineTs: number;\n}\n\ninterface UiUpdateMessage {\n action: typeof TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_UPDATE;\n sessionId: string;\n activeRequestId: string | null;\n selections: Record;\n deadlineTs: number;\n errorMessage: string | null;\n}\n\ninterface UiHideMessage {\n action: typeof TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_HIDE;\n sessionId: string;\n}\n\ninterface UiPingMessage {\n action: typeof TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_PING;\n}\n\ntype PickerMessage = UiPingMessage | UiShowMessage | UiUpdateMessage | UiHideMessage;\n\n// ============================================================\n// Content Script Definition\n// ============================================================\n\nexport default defineContentScript({\n matches: [''],\n runAt: 'document_idle',\n\n main() {\n // Only mount UI in the top frame\n if (window.top !== window) return;\n\n let controller: ElementPickerController | null = null;\n let currentSessionId: string | null = null;\n\n /**\n * Ensure the controller is created and configured.\n */\n function ensureController(): ElementPickerController {\n if (controller) return controller;\n\n controller = createElementPickerController({\n onCancel: () => {\n if (!currentSessionId) return;\n void chrome.runtime.sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.ELEMENT_PICKER_UI_EVENT,\n sessionId: currentSessionId,\n event: 'cancel',\n });\n },\n onConfirm: () => {\n if (!currentSessionId) return;\n void chrome.runtime.sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.ELEMENT_PICKER_UI_EVENT,\n sessionId: currentSessionId,\n event: 'confirm',\n });\n },\n onSetActiveRequest: (requestId: string) => {\n if (!currentSessionId) return;\n void chrome.runtime.sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.ELEMENT_PICKER_UI_EVENT,\n sessionId: currentSessionId,\n event: 'set_active_request',\n requestId,\n });\n },\n onClearSelection: (requestId: string) => {\n if (!currentSessionId) return;\n void chrome.runtime.sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.ELEMENT_PICKER_UI_EVENT,\n sessionId: currentSessionId,\n event: 'clear_selection',\n requestId,\n });\n },\n });\n\n return controller;\n }\n\n /**\n * Handle incoming messages from background.\n */\n function handleMessage(\n message: unknown,\n _sender: chrome.runtime.MessageSender,\n sendResponse: (response?: unknown) => void,\n ): boolean | void {\n const msg = message as PickerMessage | undefined;\n if (!msg?.action) return false;\n\n // Respond to ping (used by background to check if UI script is ready)\n if (msg.action === TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_PING) {\n sendResponse({ success: true });\n return true;\n }\n\n // Show the picker panel\n if (msg.action === TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_SHOW) {\n const showMsg = msg as UiShowMessage;\n currentSessionId = typeof showMsg.sessionId === 'string' ? showMsg.sessionId : null;\n\n if (!currentSessionId) {\n sendResponse({ success: false, error: 'Missing sessionId' });\n return true;\n }\n\n const ctrl = ensureController();\n const initialState: ElementPickerUiState = {\n sessionId: currentSessionId,\n requests: Array.isArray(showMsg.requests) ? showMsg.requests : [],\n activeRequestId: showMsg.activeRequestId ?? null,\n selections: {},\n deadlineTs: typeof showMsg.deadlineTs === 'number' ? showMsg.deadlineTs : Date.now(),\n errorMessage: null,\n };\n ctrl.show(initialState);\n sendResponse({ success: true });\n return true;\n }\n\n // Update the picker panel state\n if (msg.action === TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_UPDATE) {\n const updateMsg = msg as UiUpdateMessage;\n\n if (!currentSessionId || updateMsg.sessionId !== currentSessionId) {\n sendResponse({ success: false, error: 'Session mismatch' });\n return true;\n }\n\n controller?.update({\n sessionId: currentSessionId,\n activeRequestId: updateMsg.activeRequestId ?? null,\n selections: updateMsg.selections || {},\n deadlineTs: updateMsg.deadlineTs,\n errorMessage: updateMsg.errorMessage ?? null,\n });\n sendResponse({ success: true });\n return true;\n }\n\n // Hide the picker panel\n if (msg.action === TOOL_MESSAGE_TYPES.ELEMENT_PICKER_UI_HIDE) {\n const hideMsg = msg as UiHideMessage;\n\n // Best-effort hide even if session mismatches\n if (currentSessionId && hideMsg.sessionId !== currentSessionId) {\n // Log but don't fail\n console.warn('[ElementPicker] Session mismatch on hide, hiding anyway');\n }\n\n controller?.hide();\n currentSessionId = null;\n sendResponse({ success: true });\n return true;\n }\n\n return false;\n }\n\n // Register message listener\n chrome.runtime.onMessage.addListener(handleMessage);\n\n // Cleanup on page unload\n window.addEventListener('unload', () => {\n chrome.runtime.onMessage.removeListener(handleMessage);\n controller?.dispose();\n controller = null;\n currentSessionId = null;\n });\n },\n});\n" }, { "path": "app/chrome-extension/entrypoints/offscreen/gif-encoder.ts", "content": "/**\n * GIF Encoder Module for Offscreen Document\n *\n * Handles GIF encoding using the gifenc library in the offscreen document context.\n * This module provides frame-by-frame GIF encoding with palette quantization.\n */\n\nimport { GIFEncoder, quantize, applyPalette } from 'gifenc';\nimport { MessageTarget, OFFSCREEN_MESSAGE_TYPES } from '@/common/message-types';\n\n// ============================================================================\n// Types\n// ============================================================================\n\ninterface GifEncoderState {\n encoder: ReturnType | null;\n width: number;\n height: number;\n frameCount: number;\n isInitialized: boolean;\n}\n\ninterface GifAddFrameMessage {\n target: MessageTarget;\n type: typeof OFFSCREEN_MESSAGE_TYPES.GIF_ADD_FRAME;\n imageData: number[];\n width: number;\n height: number;\n delay: number;\n maxColors?: number;\n}\n\ninterface GifFinishMessage {\n target: MessageTarget;\n type: typeof OFFSCREEN_MESSAGE_TYPES.GIF_FINISH;\n}\n\ninterface GifResetMessage {\n target: MessageTarget;\n type: typeof OFFSCREEN_MESSAGE_TYPES.GIF_RESET;\n}\n\ntype GifMessage = GifAddFrameMessage | GifFinishMessage | GifResetMessage;\n\ninterface GifMessageResponse {\n success: boolean;\n error?: string;\n frameCount?: number;\n gifData?: number[];\n byteLength?: number;\n}\n\n// ============================================================================\n// State\n// ============================================================================\n\nconst state: GifEncoderState = {\n encoder: null,\n width: 0,\n height: 0,\n frameCount: 0,\n isInitialized: false,\n};\n\n// ============================================================================\n// Handlers\n// ============================================================================\n\nfunction initializeEncoder(width: number, height: number): void {\n state.encoder = GIFEncoder();\n state.width = width;\n state.height = height;\n state.frameCount = 0;\n state.isInitialized = true;\n}\n\nfunction addFrame(\n imageData: Uint8ClampedArray,\n width: number,\n height: number,\n delay: number,\n maxColors: number = 256,\n): void {\n // Initialize encoder on first frame\n if (!state.isInitialized || state.width !== width || state.height !== height) {\n initializeEncoder(width, height);\n }\n\n if (!state.encoder) {\n throw new Error('GIF encoder not initialized');\n }\n\n // Quantize colors to create palette\n const palette = quantize(imageData, maxColors, { format: 'rgb444' });\n\n // Map pixels to palette indices\n const indexedPixels = applyPalette(imageData, palette, 'rgb444');\n\n // Write frame to encoder\n state.encoder.writeFrame(indexedPixels, width, height, {\n palette,\n delay,\n dispose: 2, // Restore to background color\n });\n\n state.frameCount++;\n}\n\nfunction finishEncoding(): Uint8Array {\n if (!state.encoder) {\n throw new Error('GIF encoder not initialized');\n }\n\n state.encoder.finish();\n const bytes = state.encoder.bytes();\n\n // Reset state after finishing\n resetEncoder();\n\n return bytes;\n}\n\nfunction resetEncoder(): void {\n if (state.encoder) {\n state.encoder.reset();\n }\n state.encoder = null;\n state.width = 0;\n state.height = 0;\n state.frameCount = 0;\n state.isInitialized = false;\n}\n\n// ============================================================================\n// Message Handler\n// ============================================================================\n\nfunction isGifMessage(message: unknown): message is GifMessage {\n if (!message || typeof message !== 'object') return false;\n const msg = message as Record;\n if (msg.target !== MessageTarget.Offscreen) return false;\n\n const gifTypes = [\n OFFSCREEN_MESSAGE_TYPES.GIF_ADD_FRAME,\n OFFSCREEN_MESSAGE_TYPES.GIF_FINISH,\n OFFSCREEN_MESSAGE_TYPES.GIF_RESET,\n ];\n\n return gifTypes.includes(msg.type as string);\n}\n\nexport function handleGifMessage(\n message: unknown,\n sendResponse: (response: GifMessageResponse) => void,\n): boolean {\n if (!isGifMessage(message)) {\n return false;\n }\n\n try {\n switch (message.type) {\n case OFFSCREEN_MESSAGE_TYPES.GIF_ADD_FRAME: {\n const { imageData, width, height, delay, maxColors } = message;\n const clampedData = new Uint8ClampedArray(imageData);\n addFrame(clampedData, width, height, delay, maxColors);\n sendResponse({\n success: true,\n frameCount: state.frameCount,\n });\n break;\n }\n\n case OFFSCREEN_MESSAGE_TYPES.GIF_FINISH: {\n const gifBytes = finishEncoding();\n sendResponse({\n success: true,\n gifData: Array.from(gifBytes),\n byteLength: gifBytes.byteLength,\n });\n break;\n }\n\n case OFFSCREEN_MESSAGE_TYPES.GIF_RESET: {\n resetEncoder();\n sendResponse({ success: true });\n break;\n }\n\n default:\n sendResponse({ success: false, error: `Unknown GIF message type` });\n }\n } catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n console.error('GIF encoder error:', errorMessage);\n sendResponse({ success: false, error: errorMessage });\n }\n\n return true;\n}\n\nconsole.log('GIF encoder module loaded');\n" }, { "path": "app/chrome-extension/entrypoints/offscreen/index.html", "content": "\n\n \n \n \n \n \n \n" }, { "path": "app/chrome-extension/entrypoints/offscreen/main.ts", "content": "import { SemanticSimilarityEngine } from '@/utils/semantic-similarity-engine';\nimport {\n MessageTarget,\n SendMessageType,\n OFFSCREEN_MESSAGE_TYPES,\n BACKGROUND_MESSAGE_TYPES,\n} from '@/common/message-types';\nimport { handleGifMessage } from './gif-encoder';\nimport { initKeepalive } from './rr-keepalive';\n\n// 初始化 RR V3 Keepalive\ninitKeepalive();\n\n// Global semantic similarity engine instance\nlet similarityEngine: SemanticSimilarityEngine | null = null;\ninterface OffscreenMessage {\n target: MessageTarget | string;\n type: SendMessageType | string;\n}\n\ninterface SimilarityEngineInitMessage extends OffscreenMessage {\n type: SendMessageType.SimilarityEngineInit;\n config: any;\n}\n\ninterface SimilarityEngineComputeBatchMessage extends OffscreenMessage {\n type: SendMessageType.SimilarityEngineComputeBatch;\n pairs: { text1: string; text2: string }[];\n options?: Record;\n}\n\ninterface SimilarityEngineGetEmbeddingMessage extends OffscreenMessage {\n type: 'similarityEngineCompute';\n text: string;\n options?: Record;\n}\n\ninterface SimilarityEngineGetEmbeddingsBatchMessage extends OffscreenMessage {\n type: 'similarityEngineBatchCompute';\n texts: string[];\n options?: Record;\n}\n\ninterface SimilarityEngineStatusMessage extends OffscreenMessage {\n type: 'similarityEngineStatus';\n}\n\ntype MessageResponse = {\n result?: string;\n error?: string;\n success?: boolean;\n similarities?: number[];\n embedding?: number[];\n embeddings?: number[][];\n isInitialized?: boolean;\n currentConfig?: any;\n};\n\n// Listen for messages from the extension\nchrome.runtime.onMessage.addListener(\n (\n message: OffscreenMessage,\n _sender: chrome.runtime.MessageSender,\n sendResponse: (response: MessageResponse) => void,\n ) => {\n if (message.target !== MessageTarget.Offscreen) {\n return;\n }\n\n // Handle GIF encoding messages first\n if (handleGifMessage(message, sendResponse)) {\n return true;\n }\n\n try {\n switch (message.type) {\n case SendMessageType.SimilarityEngineInit:\n case OFFSCREEN_MESSAGE_TYPES.SIMILARITY_ENGINE_INIT: {\n const initMsg = message as SimilarityEngineInitMessage;\n console.log('Offscreen: Received similarity engine init message:', message.type);\n handleSimilarityEngineInit(initMsg.config)\n .then(() => sendResponse({ success: true }))\n .catch((error) => sendResponse({ success: false, error: error.message }));\n break;\n }\n\n case SendMessageType.SimilarityEngineComputeBatch: {\n const computeMsg = message as SimilarityEngineComputeBatchMessage;\n handleComputeSimilarityBatch(computeMsg.pairs, computeMsg.options)\n .then((similarities) => sendResponse({ success: true, similarities }))\n .catch((error) => sendResponse({ success: false, error: error.message }));\n break;\n }\n\n case OFFSCREEN_MESSAGE_TYPES.SIMILARITY_ENGINE_COMPUTE: {\n const embeddingMsg = message as SimilarityEngineGetEmbeddingMessage;\n handleGetEmbedding(embeddingMsg.text, embeddingMsg.options)\n .then((embedding) => {\n console.log('Offscreen: Sending embedding response:', {\n length: embedding.length,\n type: typeof embedding,\n constructor: embedding.constructor.name,\n isFloat32Array: embedding instanceof Float32Array,\n firstFewValues: Array.from(embedding.slice(0, 5)),\n });\n const embeddingArray = Array.from(embedding);\n console.log('Offscreen: Converted to array:', {\n length: embeddingArray.length,\n type: typeof embeddingArray,\n isArray: Array.isArray(embeddingArray),\n firstFewValues: embeddingArray.slice(0, 5),\n });\n sendResponse({ success: true, embedding: embeddingArray });\n })\n .catch((error) => sendResponse({ success: false, error: error.message }));\n break;\n }\n\n case OFFSCREEN_MESSAGE_TYPES.SIMILARITY_ENGINE_BATCH_COMPUTE: {\n const batchMsg = message as SimilarityEngineGetEmbeddingsBatchMessage;\n handleGetEmbeddingsBatch(batchMsg.texts, batchMsg.options)\n .then((embeddings) =>\n sendResponse({\n success: true,\n embeddings: embeddings.map((emb) => Array.from(emb)),\n }),\n )\n .catch((error) => sendResponse({ success: false, error: error.message }));\n break;\n }\n\n case OFFSCREEN_MESSAGE_TYPES.SIMILARITY_ENGINE_STATUS: {\n handleGetEngineStatus()\n .then((status: any) => sendResponse({ success: true, ...status }))\n .catch((error: any) => sendResponse({ success: false, error: error.message }));\n break;\n }\n\n default:\n sendResponse({ error: `Unknown message type: ${message.type}` });\n }\n } catch (error) {\n if (error instanceof Error) {\n sendResponse({ error: error.message });\n } else {\n sendResponse({ error: 'Unknown error occurred' });\n }\n }\n\n // Return true to indicate we'll respond asynchronously\n return true;\n },\n);\n\n// Global variable to track current model state\nlet currentModelConfig: any = null;\n\n/**\n * Check if engine reinitialization is needed\n */\nfunction needsReinitialization(newConfig: any): boolean {\n if (!similarityEngine || !currentModelConfig) {\n return true;\n }\n\n // Check if key configuration has changed\n const keyFields = ['modelPreset', 'modelVersion', 'modelIdentifier', 'dimension'];\n for (const field of keyFields) {\n if (newConfig[field] !== currentModelConfig[field]) {\n console.log(\n `Offscreen: ${field} changed from ${currentModelConfig[field]} to ${newConfig[field]}`,\n );\n return true;\n }\n }\n\n return false;\n}\n\n/**\n * Progress callback function type\n */\ntype ProgressCallback = (progress: { status: string; progress: number; message?: string }) => void;\n\n/**\n * Initialize semantic similarity engine\n */\nasync function handleSimilarityEngineInit(config: any): Promise {\n console.log('Offscreen: Initializing semantic similarity engine with config:', config);\n console.log('Offscreen: Config useLocalFiles:', config.useLocalFiles);\n console.log('Offscreen: Config modelPreset:', config.modelPreset);\n console.log('Offscreen: Config modelVersion:', config.modelVersion);\n console.log('Offscreen: Config modelDimension:', config.modelDimension);\n console.log('Offscreen: Config modelIdentifier:', config.modelIdentifier);\n\n // Check if reinitialization is needed\n const needsReinit = needsReinitialization(config);\n console.log('Offscreen: Needs reinitialization:', needsReinit);\n\n if (!needsReinit) {\n console.log('Offscreen: Using existing engine (no changes detected)');\n await updateModelStatus('ready', 100);\n return;\n }\n\n // If engine already exists, clean up old instance first (support model switching)\n if (similarityEngine) {\n console.log('Offscreen: Cleaning up existing engine for model switch...');\n try {\n // Properly call dispose method to clean up all resources\n await similarityEngine.dispose();\n console.log('Offscreen: Previous engine disposed successfully');\n } catch (error) {\n console.warn('Offscreen: Failed to dispose previous engine:', error);\n }\n similarityEngine = null;\n currentModelConfig = null;\n\n // Clear vector data in IndexedDB to ensure data consistency\n try {\n console.log('Offscreen: Clearing IndexedDB vector data for model switch...');\n await clearVectorIndexedDB();\n console.log('Offscreen: IndexedDB vector data cleared successfully');\n } catch (error) {\n console.warn('Offscreen: Failed to clear IndexedDB vector data:', error);\n }\n }\n\n try {\n // Update status to initializing\n await updateModelStatus('initializing', 10);\n\n // Create progress callback function\n const progressCallback: ProgressCallback = async (progress) => {\n console.log('Offscreen: Progress update:', progress);\n await updateModelStatus(progress.status, progress.progress);\n };\n\n // Create engine instance and pass progress callback\n similarityEngine = new SemanticSimilarityEngine(config);\n console.log('Offscreen: Starting engine initialization with progress tracking...');\n\n // Use enhanced initialization method (if progress callback is supported)\n if (typeof (similarityEngine as any).initializeWithProgress === 'function') {\n await (similarityEngine as any).initializeWithProgress(progressCallback);\n } else {\n // Fallback to standard initialization method\n console.log('Offscreen: Using standard initialization (no progress callback support)');\n await updateModelStatus('downloading', 30);\n await similarityEngine.initialize();\n await updateModelStatus('ready', 100);\n }\n\n // Save current configuration\n currentModelConfig = { ...config };\n\n console.log('Offscreen: Semantic similarity engine initialized successfully');\n } catch (error) {\n console.error('Offscreen: Failed to initialize semantic similarity engine:', error);\n // Update status to error\n const errorMessage = error instanceof Error ? error.message : 'Unknown initialization error';\n const errorType = analyzeErrorType(errorMessage);\n await updateModelStatus('error', 0, errorMessage, errorType);\n // Clean up failed instance\n similarityEngine = null;\n currentModelConfig = null;\n throw error;\n }\n}\n\n/**\n * Clear vector data in IndexedDB\n */\nasync function clearVectorIndexedDB(): Promise {\n try {\n // Clear vector search related IndexedDB databases\n const dbNames = ['VectorSearchDB', 'ContentIndexerDB', 'SemanticSimilarityDB'];\n\n for (const dbName of dbNames) {\n try {\n // Try to delete database\n const deleteRequest = indexedDB.deleteDatabase(dbName);\n await new Promise((resolve, _reject) => {\n deleteRequest.onsuccess = () => {\n console.log(`Offscreen: Successfully deleted database: ${dbName}`);\n resolve();\n };\n deleteRequest.onerror = () => {\n console.warn(`Offscreen: Failed to delete database: ${dbName}`, deleteRequest.error);\n resolve(); // 不阻塞其他数据库的清理\n };\n deleteRequest.onblocked = () => {\n console.warn(`Offscreen: Database deletion blocked: ${dbName}`);\n resolve(); // 不阻塞其他数据库的清理\n };\n });\n } catch (error) {\n console.warn(`Offscreen: Error deleting database ${dbName}:`, error);\n }\n }\n } catch (error) {\n console.error('Offscreen: Failed to clear vector IndexedDB:', error);\n throw error;\n }\n}\n\n// Analyze error type\nfunction analyzeErrorType(errorMessage: string): 'network' | 'file' | 'unknown' {\n const message = errorMessage.toLowerCase();\n\n if (\n message.includes('network') ||\n message.includes('fetch') ||\n message.includes('timeout') ||\n message.includes('connection') ||\n message.includes('cors') ||\n message.includes('failed to fetch')\n ) {\n return 'network';\n }\n\n if (\n message.includes('corrupt') ||\n message.includes('invalid') ||\n message.includes('format') ||\n message.includes('parse') ||\n message.includes('decode') ||\n message.includes('onnx')\n ) {\n return 'file';\n }\n\n return 'unknown';\n}\n\n// Helper function to update model status\nasync function updateModelStatus(\n status: string,\n progress: number,\n errorMessage?: string,\n errorType?: string,\n) {\n try {\n const modelState = {\n status,\n downloadProgress: progress,\n isDownloading: status === 'downloading' || status === 'initializing',\n lastUpdated: Date.now(),\n errorMessage: errorMessage || '',\n errorType: errorType || '',\n };\n\n // In offscreen document, update storage through message passing to background script\n // because offscreen document may not have direct chrome.storage access\n if (typeof chrome !== 'undefined' && chrome.storage && chrome.storage.local) {\n await chrome.storage.local.set({ modelState });\n } else {\n // If chrome.storage is not available, pass message to background script\n console.log('Offscreen: chrome.storage not available, sending message to background');\n try {\n await chrome.runtime.sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.UPDATE_MODEL_STATUS,\n modelState: modelState,\n });\n } catch (messageError) {\n console.error('Offscreen: Failed to send status update message:', messageError);\n }\n }\n } catch (error) {\n console.error('Offscreen: Failed to update model status:', error);\n }\n}\n\n/**\n * Batch compute semantic similarity\n */\nasync function handleComputeSimilarityBatch(\n pairs: { text1: string; text2: string }[],\n options: Record = {},\n): Promise {\n if (!similarityEngine) {\n throw new Error('Similarity engine not initialized. Please reinitialize the engine.');\n }\n\n console.log(`Offscreen: Computing similarities for ${pairs.length} pairs`);\n const similarities = await similarityEngine.computeSimilarityBatch(pairs, options);\n console.log('Offscreen: Similarity computation completed');\n\n return similarities;\n}\n\n/**\n * Get embedding vector for single text\n */\nasync function handleGetEmbedding(\n text: string,\n options: Record = {},\n): Promise {\n if (!similarityEngine) {\n throw new Error('Similarity engine not initialized. Please reinitialize the engine.');\n }\n\n console.log(`Offscreen: Getting embedding for text: \"${text.substring(0, 50)}...\"`);\n const embedding = await similarityEngine.getEmbedding(text, options);\n console.log('Offscreen: Embedding computation completed');\n\n return embedding;\n}\n\n/**\n * Batch get embedding vectors for texts\n */\nasync function handleGetEmbeddingsBatch(\n texts: string[],\n options: Record = {},\n): Promise {\n if (!similarityEngine) {\n throw new Error('Similarity engine not initialized. Please reinitialize the engine.');\n }\n\n console.log(`Offscreen: Getting embeddings for ${texts.length} texts`);\n const embeddings = await similarityEngine.getEmbeddingsBatch(texts, options);\n console.log('Offscreen: Batch embedding computation completed');\n\n return embeddings;\n}\n\n/**\n * Get engine status\n */\nasync function handleGetEngineStatus(): Promise<{\n isInitialized: boolean;\n currentConfig: any;\n}> {\n return {\n isInitialized: !!similarityEngine,\n currentConfig: currentModelConfig,\n };\n}\n\nconsole.log('Offscreen: Semantic similarity engine handler loaded');\n" }, { "path": "app/chrome-extension/entrypoints/offscreen/rr-keepalive.ts", "content": "/**\n * @fileoverview Offscreen Keepalive\n * @description Keeps the MV3 service worker alive using an Offscreen Document + Port heartbeat.\n *\n * Architecture:\n * - Offscreen connects to Background (Service Worker) via a named Port.\n * - Offscreen sends periodic `keepalive.ping` messages while keepalive is enabled.\n * - Background replies with `keepalive.pong` to confirm the channel is alive.\n *\n * Contract:\n * - After `stop`, keepalive must fully stop: no ping loop, no Port, and no reconnection attempts.\n * - After `start`, keepalive must (re)connect if needed and resume the ping loop.\n */\n\nimport {\n RR_V3_KEEPALIVE_PORT_NAME,\n DEFAULT_KEEPALIVE_PING_INTERVAL_MS,\n type KeepaliveMessage,\n} from '@/common/rr-v3-keepalive-protocol';\n\n// ==================== Runtime Control Protocol ====================\n\nconst KEEPALIVE_CONTROL_MESSAGE_TYPE = 'rr_v3_keepalive.control' as const;\n\ntype KeepaliveControlCommand = 'start' | 'stop';\n\ninterface KeepaliveControlMessage {\n type: typeof KEEPALIVE_CONTROL_MESSAGE_TYPE;\n command: KeepaliveControlCommand;\n}\n\nfunction isKeepaliveControlMessage(value: unknown): value is KeepaliveControlMessage {\n if (!value || typeof value !== 'object') return false;\n const v = value as Record;\n if (v.type !== KEEPALIVE_CONTROL_MESSAGE_TYPE) return false;\n return v.command === 'start' || v.command === 'stop';\n}\n\n// ==================== State ====================\n\nlet initialized = false;\nlet keepalivePort: chrome.runtime.Port | null = null;\nlet pingTimer: ReturnType | null = null;\n/** Whether keepalive is desired (set by start/stop commands from Background) */\nlet keepaliveDesired = false;\nlet reconnectTimer: ReturnType | null = null;\n\n// ==================== Type Guards ====================\n\n/**\n * Type guard for KeepaliveMessage.\n */\nfunction isKeepaliveMessage(value: unknown): value is KeepaliveMessage {\n if (!value || typeof value !== 'object') return false;\n const v = value as Record;\n\n const type = v.type;\n if (\n type !== 'keepalive.ping' &&\n type !== 'keepalive.pong' &&\n type !== 'keepalive.start' &&\n type !== 'keepalive.stop'\n ) {\n return false;\n }\n\n return typeof v.timestamp === 'number' && Number.isFinite(v.timestamp);\n}\n\n// ==================== Port Management ====================\n\n/**\n * Schedule a reconnect attempt to maintain the Port connection.\n * Only reconnect while keepalive is desired.\n */\nfunction scheduleReconnect(delayMs = 1000): void {\n if (!initialized) return;\n if (!keepaliveDesired) return;\n if (reconnectTimer) return;\n\n reconnectTimer = setTimeout(() => {\n reconnectTimer = null;\n if (!initialized) return;\n if (!keepaliveDesired) return;\n if (!keepalivePort) {\n console.log('[rr-keepalive] Attempting scheduled reconnect...');\n keepalivePort = connectToBackground();\n }\n }, delayMs);\n}\n\n/**\n * Create a Port connection to Background.\n */\nfunction connectToBackground(): chrome.runtime.Port | null {\n if (typeof chrome === 'undefined' || !chrome.runtime?.connect) {\n console.warn('[rr-keepalive] chrome.runtime.connect not available');\n return null;\n }\n\n try {\n const port = chrome.runtime.connect({ name: RR_V3_KEEPALIVE_PORT_NAME });\n\n port.onMessage.addListener((msg: unknown) => {\n if (!isKeepaliveMessage(msg)) return;\n\n if (msg.type === 'keepalive.start') {\n console.log('[rr-keepalive] Received start command via Port');\n startPingLoop();\n } else if (msg.type === 'keepalive.stop') {\n console.log('[rr-keepalive] Received stop command via Port');\n stopPingLoop();\n } else if (msg.type === 'keepalive.pong') {\n // Background replied to our ping.\n console.debug('[rr-keepalive] Received pong');\n }\n });\n\n port.onDisconnect.addListener(() => {\n console.log('[rr-keepalive] Port disconnected');\n keepalivePort = null;\n // Only reconnect if keepalive is still desired.\n scheduleReconnect(1000);\n });\n\n console.log('[rr-keepalive] Connected to background');\n return port;\n } catch (e) {\n console.warn('[rr-keepalive] Failed to connect:', e);\n return null;\n }\n}\n\n// ==================== Ping Loop ====================\n\n/**\n * Send a ping message to Background.\n */\nfunction sendPing(): void {\n if (!keepalivePort) {\n keepalivePort = connectToBackground();\n }\n\n if (!keepalivePort) return;\n\n const msg: KeepaliveMessage = {\n type: 'keepalive.ping',\n timestamp: Date.now(),\n };\n\n try {\n keepalivePort.postMessage(msg);\n console.debug('[rr-keepalive] Sent ping');\n } catch (e) {\n console.warn('[rr-keepalive] Failed to send ping:', e);\n keepalivePort = null;\n scheduleReconnect(1000);\n }\n}\n\n/**\n * Start the ping loop.\n */\nfunction startPingLoop(): void {\n if (pingTimer) return;\n\n keepaliveDesired = true;\n\n // Ensure we have a Port connection.\n if (!keepalivePort) {\n keepalivePort = connectToBackground();\n }\n\n // Send one ping immediately.\n sendPing();\n\n // Start the interval timer.\n pingTimer = setInterval(() => {\n sendPing();\n }, DEFAULT_KEEPALIVE_PING_INTERVAL_MS);\n\n console.log(\n `[rr-keepalive] Ping loop started (interval=${DEFAULT_KEEPALIVE_PING_INTERVAL_MS}ms)`,\n );\n}\n\n/**\n * Stop the ping loop.\n * This must fully stop keepalive: no timer, no Port, and no reconnection attempts.\n */\nfunction stopPingLoop(): void {\n keepaliveDesired = false;\n\n if (pingTimer) {\n clearInterval(pingTimer);\n pingTimer = null;\n }\n\n if (reconnectTimer) {\n clearTimeout(reconnectTimer);\n reconnectTimer = null;\n }\n\n // Disconnect the Port to fully stop keepalive.\n if (keepalivePort) {\n try {\n keepalivePort.disconnect();\n } catch {\n // Ignore\n }\n keepalivePort = null;\n }\n\n console.log('[rr-keepalive] Ping loop stopped');\n}\n\n// ==================== Public API ====================\n\n/**\n * Initialize keepalive control handlers.\n * @description Registers the runtime control listener and waits for start/stop commands.\n */\nexport function initKeepalive(): void {\n if (initialized) return;\n initialized = true;\n\n // Check Chrome API availability.\n if (typeof chrome === 'undefined' || !chrome.runtime?.onMessage) {\n console.warn('[rr-keepalive] chrome.runtime.onMessage not available');\n return;\n }\n\n // Listen for runtime control messages from Background.\n // This allows Background to send start/stop even when Port is not connected.\n chrome.runtime.onMessage.addListener((msg: unknown, _sender, sendResponse) => {\n if (!isKeepaliveControlMessage(msg)) return;\n\n if (msg.command === 'start') {\n console.log('[rr-keepalive] Received runtime start command');\n startPingLoop();\n } else {\n console.log('[rr-keepalive] Received runtime stop command');\n stopPingLoop();\n }\n\n try {\n sendResponse({ ok: true });\n } catch {\n // Ignore\n }\n });\n\n // Also establish initial Port connection for backwards compatibility.\n if (chrome.runtime?.connect) {\n keepalivePort = connectToBackground();\n }\n\n console.log('[rr-keepalive] Keepalive initialized');\n}\n\n/**\n * Check whether keepalive is active.\n */\nexport function isKeepaliveActive(): boolean {\n return keepaliveDesired && pingTimer !== null && keepalivePort !== null;\n}\n\n/**\n * Get the active port count (for debugging).\n * @deprecated Use isKeepaliveActive() instead\n */\nexport function getActivePortCount(): number {\n return keepalivePort ? 1 : 0;\n}\n\n// Re-export for backwards compatibility\nexport {\n RR_V3_KEEPALIVE_PORT_NAME,\n type KeepaliveMessage,\n} from '@/common/rr-v3-keepalive-protocol';\n" }, { "path": "app/chrome-extension/entrypoints/options/App.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/Canvas.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/EdgePropertyPanel.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/KeyValueEditor.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/PropertyPanel.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/Sidebar.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/TriggerPanel.vue", "content": "/** * @fileoverview Trigger Panel Component for Builder * @description * A floating panel for\nmanaging V3 triggers in the Builder interface. * * Features: * - Lists all triggers for the current\nflow * - Enable/disable toggle for all trigger types * - Create/edit/delete for panel-managed\ntriggers (interval, once) * - Manual trigger support for 'manual' type triggers * * Ownership model:\n* - Node-managed triggers (ID prefix: trg_/sch_): Created by trigger node sync, read-only in panel *\n- Panel-managed triggers (interval, once): Full CRUD in panel */\n\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/nodes/NodeCard.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/nodes/NodeIf.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/nodes/node-util.ts", "content": "// node-util.ts - shared UI helpers for node components\n// Note: comments in English\n\nimport type { NodeBase } from '@/entrypoints/background/record-replay/types';\nimport { summarizeNode as summarize } from '../../model/transforms';\nimport ILucideMousePointerClick from '~icons/lucide/mouse-pointer-click';\nimport ILucideEdit3 from '~icons/lucide/edit-3';\nimport ILucideKeyboard from '~icons/lucide/keyboard';\nimport ILucideCompass from '~icons/lucide/compass';\nimport ILucideGlobe from '~icons/lucide/globe';\nimport ILucideFileCode2 from '~icons/lucide/file-code-2';\nimport ILucideScan from '~icons/lucide/scan';\nimport ILucideHourglass from '~icons/lucide/hourglass';\nimport ILucideCheckCircle2 from '~icons/lucide/check-circle-2';\nimport ILucideGitBranch from '~icons/lucide/git-branch';\nimport ILucideRepeat from '~icons/lucide/repeat';\nimport ILucideRefreshCcw from '~icons/lucide/refresh-ccw';\nimport ILucideSquare from '~icons/lucide/square';\nimport ILucideArrowLeftRight from '~icons/lucide/arrow-left-right';\nimport ILucideX from '~icons/lucide/x';\nimport ILucideZap from '~icons/lucide/zap';\nimport ILucideCamera from '~icons/lucide/camera';\nimport ILucideBell from '~icons/lucide/bell';\nimport ILucideWrench from '~icons/lucide/wrench';\nimport ILucideFrame from '~icons/lucide/frame';\nimport ILucideDownload from '~icons/lucide/download';\nimport ILucideArrowUpDown from '~icons/lucide/arrow-up-down';\nimport ILucideMoveVertical from '~icons/lucide/move-vertical';\n\nexport function iconComp(t?: string) {\n switch (t) {\n case 'trigger':\n return ILucideZap;\n case 'click':\n case 'dblclick':\n return ILucideMousePointerClick;\n case 'fill':\n return ILucideEdit3;\n case 'drag':\n return ILucideArrowUpDown;\n case 'scroll':\n return ILucideMoveVertical;\n case 'key':\n return ILucideKeyboard;\n case 'navigate':\n return ILucideCompass;\n case 'http':\n return ILucideGlobe;\n case 'script':\n return ILucideFileCode2;\n case 'screenshot':\n return ILucideCamera;\n case 'triggerEvent':\n return ILucideBell;\n case 'setAttribute':\n return ILucideWrench;\n case 'loopElements':\n return ILucideRepeat;\n case 'switchFrame':\n return ILucideFrame;\n case 'handleDownload':\n return ILucideDownload;\n case 'extract':\n return ILucideScan;\n case 'wait':\n return ILucideHourglass;\n case 'assert':\n return ILucideCheckCircle2;\n case 'if':\n return ILucideGitBranch;\n case 'foreach':\n return ILucideRepeat;\n case 'while':\n return ILucideRefreshCcw;\n case 'openTab':\n return ILucideSquare;\n case 'switchTab':\n return ILucideArrowLeftRight;\n case 'closeTab':\n return ILucideX;\n case 'delay':\n return ILucideHourglass;\n default:\n return ILucideSquare;\n }\n}\n\nexport function getTypeLabel(type?: string) {\n const labels: Record = {\n trigger: '触发器',\n click: '点击',\n fill: '填充',\n navigate: '导航',\n wait: '等待',\n extract: '提取',\n http: 'HTTP',\n script: '脚本',\n if: '条件',\n foreach: '循环',\n assert: '断言',\n key: '键盘',\n drag: '拖拽',\n dblclick: '双击',\n openTab: '打开标签',\n switchTab: '切换标签',\n closeTab: '关闭标签',\n delay: '延迟',\n scroll: '滚动',\n while: '循环',\n };\n return labels[String(type || '')] || type || '';\n}\n\nexport function nodeSubtitle(node?: NodeBase | null): string {\n if (!node) return '';\n const summary = summarize(node);\n if (!summary) return node.type || '';\n return summary.length > 40 ? summary.slice(0, 40) + '...' : summary;\n}\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyAssert.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyClick.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyCloseTab.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyDelay.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyDrag.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyExecuteFlow.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyExtract.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyFill.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyForeach.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyFormRenderer.vue", "content": "\n\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyFromSpec.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyHandleDownload.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyHttp.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyIf.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyKey.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyLoopElements.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyNavigate.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyOpenTab.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyScreenshot.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyScript.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyScroll.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertySetAttribute.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertySwitchFrame.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertySwitchTab.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyTrigger.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyTriggerEvent.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyWait.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/PropertyWhile.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/components/properties/SelectorEditor.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/model/form-widget-registry.ts", "content": "// form-widget-registry.ts — global widget registry for PropertyFormRenderer\nimport FieldExpression from '@/entrypoints/popup/components/builder/widgets/FieldExpression.vue';\nimport FieldSelector from '@/entrypoints/popup/components/builder/widgets/FieldSelector.vue';\nimport FieldDuration from '@/entrypoints/popup/components/builder/widgets/FieldDuration.vue';\nimport FieldCode from '@/entrypoints/popup/components/builder/widgets/FieldCode.vue';\nimport FieldKeySequence from '@/entrypoints/popup/components/builder/widgets/FieldKeySequence.vue';\nimport FieldTargetLocator from '@/entrypoints/popup/components/builder/widgets/FieldTargetLocator.vue';\nimport type { Component } from 'vue';\n\nconst REG = new Map();\n\nexport function registerDefaultWidgets() {\n REG.set('expression', FieldExpression as unknown as Component);\n REG.set('selector', FieldSelector as unknown as Component);\n REG.set('duration', FieldDuration as unknown as Component);\n REG.set('code', FieldCode as unknown as Component);\n REG.set('keysequence', FieldKeySequence as unknown as Component);\n // Structured TargetLocator based on a selector input\n REG.set('targetlocator', FieldTargetLocator as unknown as Component);\n}\n\nexport function getWidget(name?: string): Component | null {\n if (!name) return null;\n return REG.get(name) || null;\n}\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/model/node-spec-registry.ts", "content": "export * from 'chrome-mcp-shared';\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/model/node-spec.ts", "content": "export * from 'chrome-mcp-shared';\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/model/node-specs-builtin.ts", "content": "export * from 'chrome-mcp-shared';\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/model/toast.ts", "content": "// toast.ts - lightweight toast event bus for builder UI\n// Usage: import { toast } and call toast('message', 'warn'|'error'|'info')\n\nexport type ToastLevel = 'info' | 'warn' | 'error';\n\nexport function toast(message: string, level: ToastLevel = 'warn') {\n try {\n const ev = new CustomEvent('rr_toast', { detail: { message: String(message), level } });\n window.dispatchEvent(ev);\n } catch {\n // as a last resort\n console[level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log']('[toast]', message);\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/model/transforms.ts", "content": "import type {\n Flow as FlowV2,\n NodeBase,\n Edge as EdgeV2,\n} from '@/entrypoints/background/record-replay/types';\nimport {\n nodesToSteps as sharedNodesToSteps,\n stepsToNodes as sharedStepsToNodes,\n topoOrder as sharedTopoOrder,\n} from 'chrome-mcp-shared';\nimport { STEP_TYPES } from 'chrome-mcp-shared';\nimport { EDGE_LABELS } from 'chrome-mcp-shared';\n\nexport function newId(prefix: string) {\n return `${prefix}_${Math.random().toString(36).slice(2, 8)}`;\n}\n\nexport type NodeType = NodeBase['type'];\n\nexport function defaultConfigFor(t: NodeType): any {\n if ((t as any) === 'trigger') return { type: 'manual', description: '' };\n if (t === STEP_TYPES.CLICK || t === STEP_TYPES.FILL)\n return { target: { candidates: [] }, value: t === STEP_TYPES.FILL ? '' : undefined };\n if (t === STEP_TYPES.IF)\n return { branches: [{ id: newId('case'), name: '', expr: '' }], else: true };\n if (t === STEP_TYPES.NAVIGATE) return { url: '' };\n if (t === STEP_TYPES.WAIT) return { condition: { text: '', appear: true } };\n if (t === STEP_TYPES.ASSERT) return { assert: { exists: '' } };\n if (t === STEP_TYPES.KEY) return { keys: '' };\n if (t === STEP_TYPES.DELAY) return { ms: 1000 };\n if (t === STEP_TYPES.HTTP) return { method: 'GET', url: '', headers: {}, body: null, saveAs: '' };\n if (t === STEP_TYPES.EXTRACT) return { selector: '', attr: 'text', js: '', saveAs: '' };\n if (t === STEP_TYPES.SCREENSHOT) return { selector: '', fullPage: false, saveAs: 'shot' };\n if (t === STEP_TYPES.DRAG)\n return { start: { candidates: [] }, end: { candidates: [] }, path: [] };\n if (t === STEP_TYPES.SCROLL)\n return { mode: 'offset', offset: { x: 0, y: 300 }, target: { candidates: [] } };\n if (t === STEP_TYPES.TRIGGER_EVENT)\n return { target: { candidates: [] }, event: 'input', bubbles: true, cancelable: false };\n if (t === STEP_TYPES.SET_ATTRIBUTE) return { target: { candidates: [] }, name: '', value: '' };\n if (t === STEP_TYPES.LOOP_ELEMENTS)\n return { selector: '', saveAs: 'elements', itemVar: 'item', subflowId: '' };\n if (t === STEP_TYPES.SWITCH_FRAME) return { frame: { index: 0, urlContains: '' } };\n if (t === STEP_TYPES.HANDLE_DOWNLOAD)\n return { filenameContains: '', waitForComplete: true, timeoutMs: 60000, saveAs: 'download' };\n if (t === STEP_TYPES.EXECUTE_FLOW) return { flowId: '', inline: true, args: {} };\n if (t === STEP_TYPES.OPEN_TAB) return { url: '', newWindow: false };\n if (t === STEP_TYPES.SWITCH_TAB) return { tabId: null, urlContains: '', titleContains: '' };\n if (t === STEP_TYPES.CLOSE_TAB) return { tabIds: [], url: '' };\n if (t === STEP_TYPES.SCRIPT) return { world: 'ISOLATED', code: '', saveAs: '', assign: {} };\n return {};\n}\n\nexport function stepsToNodes(steps: any[]): NodeBase[] {\n const base = sharedStepsToNodes(steps) as unknown as NodeBase[];\n // add simple UI positions\n base.forEach((n, i) => {\n (n as any).ui = (n as any).ui || { x: 200, y: 120 + i * 120 };\n });\n return base;\n}\n\nexport function topoOrder(nodes: NodeBase[], edges: EdgeV2[]): NodeBase[] {\n const filtered = (edges || []).filter((e) => !e.label || e.label === EDGE_LABELS.DEFAULT);\n return sharedTopoOrder(nodes as any, filtered as any) as any;\n}\n\nexport function nodesToSteps(nodes: NodeBase[], edges: EdgeV2[]): any[] {\n // Exclude non-executable nodes like 'trigger' and cut edges from them\n const execNodes = (nodes || []).filter((n) => n.type !== ('trigger' as any));\n const filtered = (edges || []).filter(\n (e) =>\n (!e.label || e.label === EDGE_LABELS.DEFAULT) && !execNodes.every((n) => n.id !== e.from),\n );\n return sharedNodesToSteps(execNodes as any, filtered as any);\n}\n\nexport function autoChainEdges(nodes: NodeBase[]): EdgeV2[] {\n const arr: EdgeV2[] = [];\n for (let i = 0; i < nodes.length - 1; i++)\n arr.push({\n id: newId('e'),\n from: nodes[i].id,\n to: nodes[i + 1].id,\n label: EDGE_LABELS.DEFAULT,\n });\n return arr;\n}\n\nexport function summarizeNode(n?: NodeBase | null): string {\n if (!n) return '';\n if (n.type === STEP_TYPES.CLICK || n.type === STEP_TYPES.FILL)\n return n.config?.target?.candidates?.[0]?.value || '未配置选择器';\n if (n.type === STEP_TYPES.NAVIGATE) return n.config?.url || '';\n if (n.type === STEP_TYPES.KEY) return n.config?.keys || '';\n if (n.type === STEP_TYPES.DELAY) return `${Number(n.config?.ms || 0)}ms`;\n if (n.type === STEP_TYPES.HTTP) return `${n.config?.method || 'GET'} ${n.config?.url || ''}`;\n if (n.type === STEP_TYPES.EXTRACT)\n return `${n.config?.selector || ''} -> ${n.config?.saveAs || ''}`;\n if (n.type === STEP_TYPES.SCREENSHOT)\n return n.config?.selector\n ? `el(${n.config.selector}) -> ${n.config?.saveAs || ''}`\n : `fullPage -> ${n.config?.saveAs || ''}`;\n if (n.type === STEP_TYPES.TRIGGER_EVENT)\n return `${n.config?.event || ''} ${n.config?.target?.candidates?.[0]?.value || ''}`;\n if (n.type === STEP_TYPES.SET_ATTRIBUTE)\n return `${n.config?.name || ''}=${n.config?.value ?? ''}`;\n if (n.type === STEP_TYPES.LOOP_ELEMENTS)\n return `${n.config?.selector || ''} as ${n.config?.itemVar || 'item'} -> ${n.config?.subflowId || ''}`;\n if (n.type === STEP_TYPES.SWITCH_FRAME)\n return n.config?.frame?.urlContains\n ? `url~${n.config.frame.urlContains}`\n : `index=${Number(n.config?.frame?.index ?? 0)}`;\n if (n.type === STEP_TYPES.OPEN_TAB) return `open ${n.config?.url || ''}`;\n if (n.type === STEP_TYPES.SWITCH_TAB)\n return `switch ${n.config?.tabId || n.config?.urlContains || n.config?.titleContains || ''}`;\n if (n.type === STEP_TYPES.CLOSE_TAB) return `close ${n.config?.url || ''}`;\n if (n.type === STEP_TYPES.HANDLE_DOWNLOAD) return `download ${n.config?.filenameContains || ''}`;\n if (n.type === STEP_TYPES.WAIT) return JSON.stringify(n.config?.condition || {});\n if (n.type === STEP_TYPES.ASSERT) return JSON.stringify(n.config?.assert || {});\n if (n.type === STEP_TYPES.IF) {\n const cnt = Array.isArray(n.config?.branches) ? n.config.branches.length : 0;\n return `if/else 分支数 ${cnt}${n.config?.else === false ? '' : ' + else'}`;\n }\n if (n.type === STEP_TYPES.SCRIPT) return (n.config?.code || '').slice(0, 30);\n if (n.type === STEP_TYPES.DRAG) {\n const a = n.config?.start?.candidates?.[0]?.value || '';\n const b = n.config?.end?.candidates?.[0]?.value || '';\n return a || b ? `${a} -> ${b}` : '拖拽';\n }\n if (n.type === STEP_TYPES.SCROLL) {\n const mode = n.config?.mode || 'offset';\n if (mode === 'offset' || mode === 'container') {\n const x = Number(n.config?.offset?.x ?? 0);\n const y = Number(n.config?.offset?.y ?? 0);\n return `${mode} (${x}, ${y})`;\n }\n const sel = n.config?.target?.candidates?.[0]?.value || '';\n return sel ? `element ${sel}` : 'element';\n }\n if (n.type === STEP_TYPES.EXECUTE_FLOW) return `exec ${n.config?.flowId || ''}`;\n return '';\n}\n\nexport function cloneFlow(flow: FlowV2): FlowV2 {\n return JSON.parse(JSON.stringify(flow));\n}\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/model/ui-nodes.ts", "content": "// ui-nodes.ts — UI registry for builder nodes (sidebar, canvas, properties)\n// Comments in English to explain intent.\n\nimport { markRaw, type Component } from 'vue';\nimport type { NodeBase, NodeType } from '@/entrypoints/background/record-replay/types';\nimport { NODE_TYPES } from '@/common/node-types';\nimport { defaultConfigFor as fallbackDefaultConfig } from '@/entrypoints/popup/components/builder/model/transforms';\nimport { validateNode as fallbackValidateNode } from '@/entrypoints/popup/components/builder/model/validation';\nimport {\n listNodeSpecs,\n getNodeSpec,\n} from '@/entrypoints/popup/components/builder/model/node-spec-registry';\nimport { STEP_TYPES } from 'chrome-mcp-shared';\n\n// Canvas renderer components\nimport NodeCard from '@/entrypoints/popup/components/builder/components/nodes/NodeCard.vue';\nimport NodeIf from '@/entrypoints/popup/components/builder/components/nodes/NodeIf.vue';\n\n// Property components (per-node or shared)\nimport PropClick from '@/entrypoints/popup/components/builder/components/properties/PropertyClick.vue';\nimport PropFill from '@/entrypoints/popup/components/builder/components/properties/PropertyFill.vue';\nimport PropTriggerEvent from '@/entrypoints/popup/components/builder/components/properties/PropertyTriggerEvent.vue';\nimport PropSetAttribute from '@/entrypoints/popup/components/builder/components/properties/PropertySetAttribute.vue';\nimport PropDrag from '@/entrypoints/popup/components/builder/components/properties/PropertyDrag.vue';\nimport PropScroll from '@/entrypoints/popup/components/builder/components/properties/PropertyScroll.vue';\nimport PropNavigate from '@/entrypoints/popup/components/builder/components/properties/PropertyNavigate.vue';\nimport PropertyFromSpec from '@/entrypoints/popup/components/builder/components/properties/PropertyFromSpec.vue';\nimport { registerBuiltinSpecs } from '@/entrypoints/popup/components/builder/model/node-specs-builtin';\n\n// Register builtin NodeSpecs at module init\nregisterBuiltinSpecs();\nimport PropWait from '@/entrypoints/popup/components/builder/components/properties/PropertyWait.vue';\nimport PropAssert from '@/entrypoints/popup/components/builder/components/properties/PropertyAssert.vue';\nimport PropDelay from '@/entrypoints/popup/components/builder/components/properties/PropertyDelay.vue';\nimport PropHttp from '@/entrypoints/popup/components/builder/components/properties/PropertyHttp.vue';\nimport PropExtract from '@/entrypoints/popup/components/builder/components/properties/PropertyExtract.vue';\nimport PropScreenshot from '@/entrypoints/popup/components/builder/components/properties/PropertyScreenshot.vue';\nimport PropLoopElements from '@/entrypoints/popup/components/builder/components/properties/PropertyLoopElements.vue';\nimport PropSwitchFrame from '@/entrypoints/popup/components/builder/components/properties/PropertySwitchFrame.vue';\nimport PropHandleDownload from '@/entrypoints/popup/components/builder/components/properties/PropertyHandleDownload.vue';\nimport PropExecuteFlow from '@/entrypoints/popup/components/builder/components/properties/PropertyExecuteFlow.vue';\nimport PropOpenTab from '@/entrypoints/popup/components/builder/components/properties/PropertyOpenTab.vue';\nimport PropSwitchTab from '@/entrypoints/popup/components/builder/components/properties/PropertySwitchTab.vue';\nimport PropCloseTab from '@/entrypoints/popup/components/builder/components/properties/PropertyCloseTab.vue';\nimport PropKey from '@/entrypoints/popup/components/builder/components/properties/PropertyKey.vue';\nimport PropIf from '@/entrypoints/popup/components/builder/components/properties/PropertyIf.vue';\nimport PropForeach from '@/entrypoints/popup/components/builder/components/properties/PropertyForeach.vue';\nimport PropWhile from '@/entrypoints/popup/components/builder/components/properties/PropertyWhile.vue';\nimport PropScript from '@/entrypoints/popup/components/builder/components/properties/PropertyScript.vue';\nimport PropTrigger from '@/entrypoints/popup/components/builder/components/properties/PropertyTrigger.vue';\n\nexport type NodeCategory = 'Flow' | 'Actions' | 'Logic' | 'Tools' | 'Tabs' | 'Page';\n\nexport interface NodeUIConfig {\n type: NodeType;\n label: string;\n category: NodeCategory;\n iconClass: string; // reuse existing Sidebar.css color classes\n canvas: Component; // canvas renderer\n property: Component; // property renderer\n docUrl?: string;\n io?: { inputs?: number | 'any'; outputs?: number | 'any' };\n defaultConfig?: () => any;\n validate?: (node: NodeBase) => string[];\n}\n\n// Registry contents generated from NodeSpec; use existing color/icon CSS classes\nconst baseCard = NodeCard as Component;\n\nfunction specToUi(spec: any): NodeUIConfig {\n const canvas = spec.type === (STEP_TYPES.IF as any) ? (NodeIf as Component) : baseCard;\n const outputs = Array.isArray(spec.ports?.outputs) ? spec.ports.outputs.length : 'any';\n return {\n type: spec.type as any,\n label: spec.display?.label || String(spec.type),\n category: (spec.display?.category || 'Actions') as any,\n iconClass: spec.display?.iconClass || 'icon-default',\n // Mark component refs as raw to prevent them from being proxied/reactive by consumers\n canvas: markRaw(canvas) as Component,\n property: markRaw(PropertyFromSpec) as Component,\n io: { inputs: spec.ports?.inputs ?? 1, outputs },\n defaultConfig: () => ({ ...(spec.defaults || {}) }),\n validate: (node: NodeBase) => {\n try {\n const cfg = (node as any)?.config || {};\n return (getNodeSpec(node.type as any)?.validate?.(cfg) || []) as string[];\n } catch {\n return [];\n }\n },\n } as any;\n}\n\nexport const NODE_UI_LIST: NodeUIConfig[] = listNodeSpecs().map(specToUi);\n\nconst REGISTRY_MAP: Record = Object.fromEntries(\n NODE_UI_LIST.map((n) => [n.type, n]),\n);\nexport const NODE_UI_REGISTRY = REGISTRY_MAP as Record;\n\nexport const NODE_CATEGORIES: NodeCategory[] = [\n 'Flow',\n 'Actions',\n 'Logic',\n 'Tools',\n 'Tabs',\n 'Page',\n];\n\nexport function listByCategory(): Record {\n const out: Record = {\n Flow: [],\n Actions: [],\n Logic: [],\n Tools: [],\n Tabs: [],\n Page: [],\n };\n for (const n of NODE_UI_LIST) out[n.category].push(n);\n return out;\n}\n\nexport function canvasTypeKey(t: NodeType): string {\n // Map to VueFlow node-types key, unique per node type\n return `rr-${t}`;\n}\n\n// Default config resolver with registry override\nexport function defaultConfigOf(t: NodeType): any {\n // Prefer NodeSpec defaults\n const spec = getNodeSpec(t as any);\n if (spec?.defaults) return { ...spec.defaults };\n const item = (NODE_UI_REGISTRY as any)[t] as NodeUIConfig | undefined;\n if (item?.defaultConfig) return item.defaultConfig();\n return fallbackDefaultConfig(t as any);\n}\n\n// Validation via registry where present\nexport function validateNodeWithRegistry(n: NodeBase): string[] {\n // Prefer NodeSpec validate\n try {\n const spec = getNodeSpec(n.type as any);\n if (spec?.validate) return spec.validate((n as any).config || {}) || [];\n } catch {}\n const item = (NODE_UI_REGISTRY as any)[n.type] as NodeUIConfig | undefined;\n if (item?.validate) {\n try {\n return item.validate(n) || [];\n } catch {}\n }\n return fallbackValidateNode(n);\n}\n\n// Allow external modules to register extra UI nodes\nexport function registerExtraUiNodes(list: NodeUIConfig[]) {\n for (const n of list) {\n (NODE_UI_LIST as any).push(n);\n (REGISTRY_MAP as any)[n.type] = n;\n }\n}\n\n// IO constraints helper with sensible defaults for our graph\nexport function getIoConstraint(t: NodeType): { inputs: number | 'any'; outputs: number | 'any' } {\n const item = (NODE_UI_REGISTRY as any)[t] as NodeUIConfig | undefined;\n const io = item?.io || {};\n // Defaults: most nodes have single input; outputs unlimited unless otherwise defined\n let inputs: number | 'any' = (io.inputs as any) ?? 1;\n let outputs: number | 'any' = (io.outputs as any) ?? 'any';\n if ((t as any) === 'trigger') inputs = 0;\n if ((t as any) === 'if') outputs = 'any';\n return { inputs, outputs };\n}\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/model/validation.ts", "content": "import type { NodeBase } from '@/entrypoints/background/record-replay/types';\nimport { STEP_TYPES } from 'chrome-mcp-shared';\n\nexport function validateNode(n: NodeBase): string[] {\n const errs: string[] = [];\n const c: any = n.config || {};\n\n switch (n.type) {\n case STEP_TYPES.CLICK:\n case STEP_TYPES.DBLCLICK:\n case 'fill': {\n const hasCandidate = !!c?.target?.candidates?.length;\n if (!hasCandidate) errs.push('缺少目标选择器候选');\n if (n.type === 'fill' && (!('value' in c) || c.value === undefined)) errs.push('缺少输入值');\n break;\n }\n case STEP_TYPES.WAIT: {\n if (!c?.condition) errs.push('缺少等待条件');\n break;\n }\n case STEP_TYPES.ASSERT: {\n if (!c?.assert) errs.push('缺少断言条件');\n break;\n }\n case STEP_TYPES.NAVIGATE: {\n if (!c?.url) errs.push('缺少 URL');\n break;\n }\n case STEP_TYPES.HTTP: {\n if (!c?.url) errs.push('HTTP: 缺少 URL');\n if (c?.assign && typeof c.assign === 'object') {\n const pathRe = /^[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+|\\[\\d+\\])*$/;\n for (const v of Object.values(c.assign)) {\n const s = String(v);\n if (!pathRe.test(s)) errs.push(`Assign: 路径非法 ${s}`);\n }\n }\n break;\n }\n case STEP_TYPES.HANDLE_DOWNLOAD: {\n // filenameContains 可选\n break;\n }\n case STEP_TYPES.EXTRACT: {\n if (!c?.saveAs) errs.push('Extract: 需填写保存变量名');\n if (!c?.selector && !c?.js) errs.push('Extract: 需提供 selector 或 js');\n break;\n }\n case STEP_TYPES.SWITCH_TAB: {\n if (!c?.tabId && !c?.urlContains && !c?.titleContains)\n errs.push('SwitchTab: 需提供 tabId 或 URL/标题包含');\n break;\n }\n case STEP_TYPES.SCREENSHOT: {\n // selector 可空（全页/可视区），不强制\n break;\n }\n case STEP_TYPES.TRIGGER_EVENT: {\n const hasCandidate = !!c?.target?.candidates?.length;\n if (!hasCandidate) errs.push('缺少目标选择器候选');\n if (!String(c?.event || '').trim()) errs.push('需提供事件类型');\n break;\n }\n case STEP_TYPES.IF: {\n const arr = Array.isArray(c?.branches) ? c.branches : [];\n if (arr.length === 0) errs.push('需添加至少一个条件分支');\n for (let i = 0; i < arr.length; i++) {\n if (!String(arr[i]?.expr || '').trim()) errs.push(`分支${i + 1}: 需填写条件表达式`);\n }\n break;\n }\n case STEP_TYPES.SET_ATTRIBUTE: {\n const hasCandidate = !!c?.target?.candidates?.length;\n if (!hasCandidate) errs.push('缺少目标选择器候选');\n if (!String(c?.name || '').trim()) errs.push('需提供属性名');\n break;\n }\n case STEP_TYPES.LOOP_ELEMENTS: {\n if (!String(c?.selector || '').trim()) errs.push('需提供元素选择器');\n if (!String(c?.subflowId || '').trim()) errs.push('需提供子流 ID');\n break;\n }\n case STEP_TYPES.SWITCH_FRAME: {\n // Both index/urlContains optional; empty means switch back to top frame\n break;\n }\n case STEP_TYPES.EXECUTE_FLOW: {\n if (!String(c?.flowId || '').trim()) errs.push('需选择要执行的工作流');\n break;\n }\n case STEP_TYPES.CLOSE_TAB: {\n // 允许空（关闭当前标签页），不强制\n break;\n }\n case STEP_TYPES.SCRIPT: {\n // 若配置了 saveAs/assign，应提供 code\n const hasAssign = c?.assign && Object.keys(c.assign).length > 0;\n if ((c?.saveAs || hasAssign) && !String(c?.code || '').trim())\n errs.push('Script: 配置了保存/映射但缺少代码');\n if (hasAssign) {\n const pathRe = /^[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+|\\[\\d+\\])*$/;\n for (const v of Object.values(c.assign || {})) {\n const s = String(v);\n if (!pathRe.test(s)) errs.push(`Assign: 路径非法 ${s}`);\n }\n }\n break;\n }\n }\n return errs;\n}\n\nexport function validateFlow(nodes: NodeBase[]): {\n totalErrors: number;\n nodeErrors: Record;\n} {\n const nodeErrors: Record = {};\n let totalErrors = 0;\n for (const n of nodes) {\n const e = validateNode(n);\n if (e.length) {\n nodeErrors[n.id] = e;\n totalErrors += e.length;\n }\n }\n return { totalErrors, nodeErrors };\n}\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/model/variables.ts", "content": "// variables.ts — Shared variable suggestion types for builder UI\nexport type VariableOrigin = 'global' | 'node';\n\nexport interface VariableOption {\n key: string;\n origin: VariableOrigin;\n nodeId?: string;\n nodeName?: string;\n}\n\nexport const VAR_TOKEN_OPEN = '{';\nexport const VAR_TOKEN_CLOSE = '}';\nexport const VAR_PLACEHOLDER = '{}';\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/store/useBuilderStore.ts", "content": "import { reactive, ref } from 'vue';\nimport type {\n Flow as FlowV2,\n NodeBase,\n Edge as EdgeV2,\n} from '@/entrypoints/background/record-replay/types';\nimport {\n autoChainEdges,\n cloneFlow,\n newId,\n stepsToNodes,\n summarizeNode,\n topoOrder,\n} from '../model/transforms';\nimport { defaultConfigOf, getIoConstraint } from '../model/ui-nodes';\nimport { toast } from '../model/toast';\n\nexport function useBuilderStore(initial?: FlowV2 | null) {\n const flowLocal = reactive({ id: '', name: '', version: 1, steps: [], variables: [] });\n const nodes = reactive([]);\n const edges = reactive([]);\n const activeNodeId = ref(null);\n const activeEdgeId = ref(null);\n const pendingFrom = ref(null);\n const pendingLabel = ref('default');\n const paletteTypes = [\n 'trigger',\n 'click',\n 'drag',\n 'scroll',\n 'fill',\n 'if',\n 'foreach',\n 'while',\n 'key',\n 'wait',\n 'assert',\n 'navigate',\n 'script',\n 'delay',\n 'http',\n 'extract',\n 'screenshot',\n 'triggerEvent',\n 'setAttribute',\n 'loopElements',\n 'switchFrame',\n 'handleDownload',\n 'executeFlow',\n 'openTab',\n 'switchTab',\n 'closeTab',\n ] as NodeBase['type'][];\n\n // --- history (undo/redo) ---\n type Snapshot = {\n flow: Pick;\n nodes: NodeBase[];\n edges: EdgeV2[];\n };\n const HISTORY_MAX = 50;\n const past: Snapshot[] = [];\n const future: Snapshot[] = [];\n function takeSnapshot(): Snapshot {\n return {\n flow: { name: flowLocal.name, description: flowLocal.description } as any,\n nodes: JSON.parse(JSON.stringify(nodes)),\n edges: JSON.parse(JSON.stringify(edges)),\n };\n }\n function applySnapshot(s: Snapshot) {\n flowLocal.name = (s.flow as any).name || '';\n (flowLocal as any).description = (s.flow as any).description || '';\n nodes.splice(0, nodes.length, ...JSON.parse(JSON.stringify(s.nodes)));\n edges.splice(0, edges.length, ...JSON.parse(JSON.stringify(s.edges)));\n }\n function recordChange() {\n past.push(takeSnapshot());\n // clear redo stack on new change\n future.length = 0;\n if (past.length > HISTORY_MAX) past.splice(0, past.length - HISTORY_MAX);\n }\n function undo() {\n if (past.length === 0) return;\n const current = takeSnapshot();\n const prev = past.pop()!;\n future.push(current);\n applySnapshot(prev);\n }\n function redo() {\n if (future.length === 0) return;\n const current = takeSnapshot();\n const next = future.pop()!;\n past.push(current);\n applySnapshot(next);\n }\n\n function layoutIfNeeded() {\n const startX = 120,\n startY = 80,\n gapY = 120;\n nodes.forEach((n, i) => {\n if (!n.ui || isNaN(n.ui.x) || isNaN(n.ui.y)) n.ui = { x: startX, y: startY + i * gapY };\n });\n }\n\n function initFromFlow(flow: FlowV2) {\n const deep = cloneFlow(flow);\n Object.assign(flowLocal, deep);\n // DAG is required - flow-store guarantees nodes/edges via normalization\n // steps fallback removed (deprecated field no longer returned)\n nodes.splice(0, nodes.length, ...(Array.isArray(deep.nodes) ? deep.nodes : []));\n edges.splice(\n 0,\n edges.length,\n ...(Array.isArray(deep.edges) && deep.edges.length ? deep.edges : autoChainEdges(nodes)),\n );\n layoutIfNeeded();\n activeNodeId.value = nodes[0]?.id || null;\n activeEdgeId.value = null;\n // reset history\n past.length = 0;\n future.length = 0;\n past.push(takeSnapshot());\n }\n\n function selectNode(id: string | null) {\n // When click on empty canvas, id can be null => deselect\n if (id && pendingFrom.value && pendingFrom.value !== id) {\n onConnect(pendingFrom.value, id, pendingLabel.value);\n pendingFrom.value = null;\n }\n activeNodeId.value = id || null;\n // selecting a node should clear edge selection\n if (id) activeEdgeId.value = null;\n }\n\n function selectEdge(id: string | null) {\n activeEdgeId.value = id || null;\n if (id) activeNodeId.value = null;\n }\n\n function addNode(t: NodeBase['type']) {\n const id = newId(t);\n const n: NodeBase = {\n id,\n type: t,\n name: '',\n config: defaultConfigOf(t),\n ui: { x: 200 + nodes.length * 24, y: 120 + nodes.length * 96 },\n };\n nodes.push(n);\n if (nodes.length > 1) {\n const prev = nodes[nodes.length - 2];\n edges.push({ id: newId('e'), from: prev.id, to: id, label: 'default' });\n }\n activeNodeId.value = id;\n recordChange();\n }\n\n function addNodeAt(t: NodeBase['type'], x: number, y: number) {\n const id = newId(t);\n const n: NodeBase = {\n id,\n type: t,\n name: '',\n config: defaultConfigOf(t),\n ui: { x: Math.round(x), y: Math.round(y) },\n };\n nodes.push(n);\n activeNodeId.value = id;\n recordChange();\n }\n\n function duplicateNode(id: string) {\n const src = nodes.find((n) => n.id === id);\n if (!src) return;\n const cp: NodeBase = JSON.parse(JSON.stringify(src));\n cp.id = newId(src.type);\n cp.name = src.name ? `${src.name} Copy` : '';\n const baseX = cp.ui && typeof cp.ui.x === 'number' ? cp.ui.x : 200;\n const baseY = cp.ui && typeof cp.ui.y === 'number' ? cp.ui.y : 120;\n cp.ui = { x: baseX + 40, y: baseY + 40 };\n nodes.push(cp);\n activeNodeId.value = cp.id;\n recordChange();\n }\n\n function removeNode(id: string) {\n const idx = nodes.findIndex((n) => n.id === id);\n if (idx < 0) return;\n nodes.splice(idx, 1);\n for (let i = edges.length - 1; i >= 0; i--) {\n const e = edges[i];\n if (e.from === id || e.to === id) edges.splice(i, 1);\n }\n // After removal, do not auto-select another node to avoid accidental batch deletes\n activeNodeId.value = null;\n activeEdgeId.value = null;\n recordChange();\n }\n\n function removeEdge(id: string) {\n const idx = edges.findIndex((e) => e.id === id);\n if (idx < 0) return;\n edges.splice(idx, 1);\n if (activeEdgeId.value === id) activeEdgeId.value = null;\n recordChange();\n }\n\n function setNodePosition(id: string, x: number, y: number) {\n const n = nodes.find((n) => n.id === id);\n if (!n) return;\n n.ui = { x: Math.round(x), y: Math.round(y) };\n // 不计入历史栈，避免频繁记录；由用户触发操作（连接/新增/删除等）记录。\n }\n\n function connectFrom(id: string, label: string = 'default') {\n pendingFrom.value = id;\n pendingLabel.value = label;\n }\n\n function onConnect(sourceId: string, targetId: string, label: string = 'default') {\n // prevent self-loop\n if (sourceId === targetId) {\n toast('不能连接到自身', 'warn');\n return;\n }\n // IO constraints\n try {\n const src = nodes.find((n) => n.id === sourceId);\n const dst = nodes.find((n) => n.id === targetId);\n if (!src || !dst) return;\n const srcIo = getIoConstraint(src.type as any);\n const dstIo = getIoConstraint(dst.type as any);\n // Inputs: respect numeric maximum; 'any' means unlimited\n const incoming = edges.filter((e) => e.to === targetId).length;\n if (dstIo.inputs !== 'any' && incoming >= (dstIo.inputs as number)) {\n toast(`该节点最多允许 ${dstIo.inputs} 条入边`, 'warn');\n return;\n }\n // Outputs: respect numeric maximum when defined\n if (srcIo.outputs !== 'any') {\n const outgoing = edges.filter((e) => e.from === sourceId).length;\n if (outgoing >= (srcIo.outputs as number)) {\n toast(`该节点最多允许 ${srcIo.outputs} 条出边`, 'warn');\n return;\n }\n }\n } catch {}\n // 单一同标签出边：删除同源 + 同标签的已有边\n for (let i = edges.length - 1; i >= 0; i--) {\n const e = edges[i];\n const lab = e.label || 'default';\n if (e.from === sourceId && lab === label) edges.splice(i, 1);\n }\n // avoid duplicate for same pair+label\n if (\n edges.some(\n (e) => e.from === sourceId && e.to === targetId && (e.label || 'default') === label,\n )\n )\n return;\n edges.push({ id: newId('e'), from: sourceId, to: targetId, label });\n recordChange();\n // auto select the newly created edge\n try {\n const last = edges[edges.length - 1];\n activeEdgeId.value = last?.id || null;\n activeNodeId.value = null;\n } catch {}\n }\n\n /**\n * Derive available variables for the property panel.\n * - Includes declared flow variables (global)\n * - Includes variables produced by preceding nodes (saveAs/assign/itemVar etc.)\n * If currentId is provided, only nodes before it in topological order are considered.\n */\n function listAvailableVariables(currentId?: string): Array<{\n key: string;\n origin: 'global' | 'node';\n nodeId?: string;\n nodeName?: string;\n }> {\n const result: Array<{\n key: string;\n origin: 'global' | 'node';\n nodeId?: string;\n nodeName?: string;\n }> = [];\n const seen = new Set();\n\n // 1) Flow-declared variables\n const declared = (flowLocal.variables || []) as Array<{ key: string }>;\n for (const v of declared) {\n const k = String(v?.key || '').trim();\n if (!k || seen.has(k)) continue;\n seen.add(k);\n result.push({ key: k, origin: 'global' });\n }\n\n // 2) Variables derived from previous nodes\n const ordered = topoOrder(nodes as any, edges as any);\n let cutoffIndex =\n typeof currentId === 'string' ? ordered.findIndex((n) => n.id === currentId) : -1;\n if (cutoffIndex < 0) cutoffIndex = ordered.length; // include all if not found\n const prevNodes = ordered.slice(0, cutoffIndex);\n for (const n of prevNodes) {\n const cfg: any = (n as any).config || {};\n const nodeName = String((n as any).name || n.id || 'node');\n const pushVar = (k: string) => {\n const key = String(k || '').trim();\n if (!key || seen.has(key)) return;\n seen.add(key);\n result.push({ key, origin: 'node', nodeId: n.id, nodeName });\n };\n // Generic saveAs\n if (typeof cfg.saveAs === 'string') pushVar(cfg.saveAs);\n // assign mapping (keys are variable names)\n if (cfg.assign && typeof cfg.assign === 'object') {\n for (const k of Object.keys(cfg.assign)) pushVar(k);\n }\n // loop elements: list var + item var\n if ((n as any).type === 'loopElements') {\n if (typeof cfg.saveAs === 'string') pushVar(cfg.saveAs);\n if (typeof cfg.itemVar === 'string') pushVar(cfg.itemVar);\n }\n }\n\n return result;\n }\n\n function importFromSteps() {\n const arr = stepsToNodes(flowLocal.steps || []);\n nodes.splice(0, nodes.length, ...arr);\n edges.splice(0, edges.length, ...autoChainEdges(arr));\n layoutIfNeeded();\n recordChange();\n }\n\n // --- subflow management ---\n const currentSubflowId = ref(null);\n function ensureSubflows() {\n if (!flowLocal.subflows) (flowLocal as any).subflows = {} as any;\n }\n function listSubflowIds(): string[] {\n ensureSubflows();\n return Object.keys((flowLocal as any).subflows || {});\n }\n function addSubflow(id: string) {\n ensureSubflows();\n const sf = (flowLocal as any).subflows as any;\n if (!id || sf[id]) return;\n sf[id] = { nodes: [], edges: [] };\n recordChange();\n }\n function removeSubflow(id: string) {\n ensureSubflows();\n const sf = (flowLocal as any).subflows as any;\n if (!sf[id]) return;\n delete sf[id];\n if (currentSubflowId.value === id) switchToMain();\n recordChange();\n }\n function flushCurrent() {\n if (!currentSubflowId.value) {\n // write back main\n (flowLocal as any).nodes = JSON.parse(JSON.stringify(nodes));\n (flowLocal as any).edges = JSON.parse(JSON.stringify(edges));\n return;\n }\n ensureSubflows();\n (flowLocal as any).subflows[currentSubflowId.value] = {\n nodes: JSON.parse(JSON.stringify(nodes)),\n edges: JSON.parse(JSON.stringify(edges)),\n };\n }\n function switchToMain() {\n flushCurrent();\n currentSubflowId.value = null;\n nodes.splice(0, nodes.length, ...JSON.parse(JSON.stringify((flowLocal.nodes || []) as any)));\n edges.splice(0, edges.length, ...JSON.parse(JSON.stringify((flowLocal.edges || []) as any)));\n layoutIfNeeded();\n }\n function switchToSubflow(id: string) {\n flushCurrent();\n currentSubflowId.value = id;\n ensureSubflows();\n const sf = (flowLocal as any).subflows[id] || { nodes: [], edges: [] };\n nodes.splice(0, nodes.length, ...JSON.parse(JSON.stringify(sf.nodes || [])));\n edges.splice(0, edges.length, ...JSON.parse(JSON.stringify(sf.edges || [])));\n layoutIfNeeded();\n }\n const isEditingMain = () => currentSubflowId.value == null;\n\n /**\n * Export flow for saving. This properly handles subflow editing:\n * 1. Flushes current canvas state back to flowLocal\n * 2. Returns a deep copy to avoid reference issues\n *\n * IMPORTANT: Always use this method for saving instead of directly\n * accessing store.nodes/edges, which may contain subflow data.\n *\n * NOTE: flow.steps is no longer written here. The storage layer (flow-store.ts)\n * will strip steps on save. Only nodes/edges are the source of truth.\n */\n function exportFlowForSave(): FlowV2 {\n // Step 1: Flush current canvas state to flowLocal\n flushCurrent();\n\n // Step 2: Return deep copy to prevent mutation\n return JSON.parse(JSON.stringify(flowLocal));\n }\n\n function summarize(id?: string) {\n const n = nodes.find((x) => x.id === id);\n return summarizeNode(n || null);\n }\n\n // 备用布局：分层 + 重心排序（不依赖外部库）\n function layoutFallback() {\n const idMap = new Map();\n nodes.forEach((n) => idMap.set(n.id, n));\n\n // Build graph using all edges (include branches like case:/else/onError)\n const inEdges = new Map();\n const outEdges = new Map();\n for (const n of nodes) {\n inEdges.set(n.id, []);\n outEdges.set(n.id, []);\n }\n for (const e of edges) {\n if (!idMap.has(e.from) || !idMap.has(e.to)) continue;\n inEdges.get(e.to)!.push(e);\n outEdges.get(e.from)!.push(e);\n }\n\n // Kahn topo with all edges; fall back to original order on cycles\n const indeg = new Map();\n nodes.forEach((n) => indeg.set(n.id, inEdges.get(n.id)!.length));\n const q: string[] = [];\n // Prefer trigger and existing left-most nodes first for stability\n const roots = nodes\n .filter((n) => (indeg.get(n.id) || 0) === 0)\n .sort(\n (a, b) =>\n (a.type === ('trigger' as any) ? -1 : 0) - (b.type === ('trigger' as any) ? -1 : 0),\n );\n roots.forEach((r) => q.push(r.id));\n const topo: string[] = [];\n const indegMut = new Map(indeg);\n while (q.length) {\n const v = q.shift()!;\n topo.push(v);\n for (const e of outEdges.get(v) || []) {\n const d = (indegMut.get(e.to) || 0) - 1;\n indegMut.set(e.to, d);\n if (d === 0) q.push(e.to);\n }\n }\n if (topo.length < nodes.length) {\n // Graph may contain cycles; append remaining nodes in original order\n for (const n of nodes) if (!topo.includes(n.id)) topo.push(n.id);\n }\n\n // Level assignment: level = max(parent.level + 1)\n const level = new Map();\n for (const id of topo) {\n const parents = inEdges.get(id) || [];\n let lv = 0;\n for (const e of parents) lv = Math.max(lv, (level.get(e.from) || 0) + 1);\n // Ensure trigger stays at level 0\n const node = idMap.get(id)!;\n if ((node.type as any) === 'trigger') lv = 0;\n level.set(id, lv);\n }\n\n // Group nodes by level\n const maxLevel = Math.max(0, ...Array.from(level.values()));\n const layers: string[][] = Array.from({ length: maxLevel + 1 }, () => []);\n for (const id of topo) layers[level.get(id) || 0].push(id);\n\n // Barycenter/median ordering per layer based on parent y-index\n const yIndex = new Map();\n // initialize first layer stable order\n layers[0].forEach((id, i) => yIndex.set(id, i));\n for (let lv = 1; lv < layers.length; lv++) {\n const arr = layers[lv];\n const scored = arr.map((id) => {\n const ps = inEdges.get(id) || [];\n const parentIdx = ps\n .map((e) => yIndex.get(e.from))\n .filter((v): v is number => typeof v === 'number');\n const score = parentIdx.length\n ? parentIdx.reduce((a, b) => a + b, 0) / parentIdx.length\n : 1e9;\n return { id, score };\n });\n scored.sort((a, b) => a.score - b.score);\n scored.forEach((s, i) => yIndex.set(s.id, i));\n layers[lv] = scored.map((s) => s.id);\n }\n\n // Place nodes\n const startX = 120;\n const startY = 80;\n const stepX = 280; // tighter than 300 to reduce wide gaps\n const stepY = 110;\n for (let lv = 0; lv < layers.length; lv++) {\n const arr = layers[lv];\n for (let i = 0; i < arr.length; i++) {\n const id = arr[i];\n const n = idMap.get(id)!;\n n.ui = { x: startX + lv * stepX, y: startY + i * stepY } as any;\n }\n }\n recordChange();\n }\n\n // 自动排版（ELK 优先）：\n // - 动态引入 elkjs，避免常驻体积\n // - 失败则回退到 layoutFallback()\n async function layoutAuto() {\n try {\n // Dynamic import of bundled build to avoid 'web-worker' resolution issues\n const mod: any = await import('elkjs/lib/elk.bundled.js');\n const ELK = mod.default || mod.ELK || mod;\n const elk = new ELK();\n\n // Estimate node sizes (px). Keep close to actual NodeCard dimensions.\n const estimateSize = (n: NodeBase) => {\n const baseW = 280;\n let baseH = 72;\n if ((n.type as any) === 'if') baseH = 110;\n return { width: baseW, height: baseH };\n };\n\n const children = nodes.map((n) => ({ id: n.id, ...estimateSize(n) }));\n const elkEdges = edges\n .filter((e) => nodes.some((n) => n.id === e.from) && nodes.some((n) => n.id === e.to))\n .map((e) => ({ id: e.id, sources: [e.from], targets: [e.to] }));\n\n const graph = {\n id: 'root',\n layoutOptions: {\n 'elk.algorithm': 'layered',\n 'elk.direction': 'RIGHT',\n 'elk.layered.spacing.nodeNodeBetweenLayers': '80',\n 'elk.spacing.nodeNode': '40',\n 'elk.layered.crossingMinimization.strategy': 'LAYER_SWEEP',\n },\n children,\n edges: elkEdges,\n } as any;\n\n const res = await elk.layout(graph);\n const pos = new Map();\n for (const c of res.children || []) {\n pos.set(String(c.id), { x: Math.round(c.x || 0), y: Math.round(c.y || 0) });\n }\n // anchor\n const startX = 120;\n const startY = 80;\n for (const n of nodes) {\n const p = pos.get(n.id);\n if (p) n.ui = { x: startX + p.x, y: startY + p.y } as any;\n }\n recordChange();\n } catch (e) {\n // Fallback without dependency\n try {\n layoutFallback();\n toast('ELK 自动布局不可用，已使用备用布局', 'warn');\n } catch {}\n }\n }\n\n if (initial) initFromFlow(initial);\n\n return {\n flowLocal,\n nodes,\n edges,\n activeNodeId,\n activeEdgeId,\n pendingFrom,\n pendingLabel,\n currentSubflowId,\n paletteTypes,\n undo,\n redo,\n initFromFlow,\n selectNode,\n selectEdge,\n addNode,\n duplicateNode,\n removeNode,\n removeEdge,\n setNodePosition,\n addNodeAt,\n connectFrom,\n onConnect,\n listAvailableVariables,\n listSubflowIds,\n addSubflow,\n removeSubflow,\n switchToMain,\n switchToSubflow,\n isEditingMain,\n importFromSteps,\n exportFlowForSave,\n summarize,\n layoutAuto,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/widgets/FieldCode.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/widgets/FieldDuration.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/widgets/FieldExpression.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/widgets/FieldKeySequence.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/widgets/FieldSelector.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/widgets/FieldTargetLocator.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/builder/widgets/VarInput.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/BoltIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/CheckIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/DatabaseIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/DocumentIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/EditIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/MarkerIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/RecordIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/RefreshIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/StopIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/TabIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/TrashIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/VectorIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/WorkflowIcon.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/popup/components/icons/index.ts", "content": "export { default as DocumentIcon } from './DocumentIcon.vue';\nexport { default as DatabaseIcon } from './DatabaseIcon.vue';\nexport { default as BoltIcon } from './BoltIcon.vue';\nexport { default as TrashIcon } from './TrashIcon.vue';\nexport { default as CheckIcon } from './CheckIcon.vue';\nexport { default as TabIcon } from './TabIcon.vue';\nexport { default as VectorIcon } from './VectorIcon.vue';\nexport { default as RecordIcon } from './RecordIcon.vue';\nexport { default as StopIcon } from './StopIcon.vue';\nexport { default as WorkflowIcon } from './WorkflowIcon.vue';\nexport { default as RefreshIcon } from './RefreshIcon.vue';\nexport { default as EditIcon } from './EditIcon.vue';\nexport { default as MarkerIcon } from './MarkerIcon.vue';\n" }, { "path": "app/chrome-extension/entrypoints/popup/index.html", "content": "\n\n \n \n \n Default Popup Title\n \n \n \n
\n \n \n\n" }, { "path": "app/chrome-extension/entrypoints/popup/main.ts", "content": "import { createApp } from 'vue';\nimport { NativeMessageType } from 'chrome-mcp-shared';\nimport './style.css';\n// 引入AgentChat主题样式\nimport '../sidepanel/styles/agent-chat.css';\nimport { preloadAgentTheme } from '../sidepanel/composables/useAgentTheme';\nimport App from './App.vue';\n\n// 在Vue挂载前预加载主题，防止主题闪烁\npreloadAgentTheme().then(() => {\n // Trigger ensure native connection (fire-and-forget, don't block UI mounting)\n void chrome.runtime.sendMessage({ type: NativeMessageType.ENSURE_NATIVE }).catch(() => {\n // Silent failure - background will handle reconnection\n });\n createApp(App).mount('#app');\n});\n" }, { "path": "app/chrome-extension/entrypoints/popup/style.css", "content": "/* 现代化全局样式 */\n:root {\n /* 字体系统 */\n font-family:\n -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;\n line-height: 1.6;\n font-weight: 400;\n\n /* 颜色系统 */\n --primary-gradient: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\n --primary-color: #667eea;\n --primary-dark: #5a67d8;\n --secondary-color: #764ba2;\n\n --success-color: #48bb78;\n --warning-color: #ed8936;\n --error-color: #f56565;\n --info-color: #4299e1;\n\n --text-primary: #2d3748;\n --text-secondary: #4a5568;\n --text-muted: #718096;\n --text-light: #a0aec0;\n\n --bg-primary: #ffffff;\n --bg-secondary: #f7fafc;\n --bg-tertiary: #edf2f7;\n --bg-overlay: rgba(255, 255, 255, 0.95);\n\n --border-color: #e2e8f0;\n --border-light: #f1f5f9;\n --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1);\n --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);\n --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);\n --shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.1);\n\n /* 间距系统 */\n --spacing-xs: 4px;\n --spacing-sm: 8px;\n --spacing-md: 12px;\n --spacing-lg: 16px;\n --spacing-xl: 20px;\n --spacing-2xl: 24px;\n --spacing-3xl: 32px;\n\n /* 圆角系统 */\n --radius-sm: 4px;\n --radius-md: 6px;\n --radius-lg: 8px;\n --radius-xl: 12px;\n --radius-2xl: 16px;\n\n /* 动画 */\n --transition-fast: 0.15s ease;\n --transition-normal: 0.3s ease;\n --transition-slow: 0.5s ease;\n\n /* 字体渲染优化 */\n font-synthesis: none;\n text-rendering: optimizeLegibility;\n -webkit-font-smoothing: antialiased;\n -moz-osx-font-smoothing: grayscale;\n -webkit-text-size-adjust: 100%;\n}\n\n/* 重置样式 */\n* {\n box-sizing: border-box;\n margin: 0;\n padding: 0;\n}\n\nbody {\n margin: 0;\n padding: 0;\n width: 400px;\n min-height: 500px;\n max-height: 600px;\n overflow: hidden;\n font-family: inherit;\n background: var(--bg-secondary);\n color: var(--text-primary);\n}\n\n#app {\n width: 100%;\n height: 100%;\n margin: 0;\n padding: 0;\n}\n\n/* 链接样式 */\na {\n color: var(--primary-color);\n text-decoration: none;\n transition: color var(--transition-fast);\n}\n\na:hover {\n color: var(--primary-dark);\n}\n\n/* 按钮基础样式重置 */\nbutton {\n font-family: inherit;\n font-size: inherit;\n line-height: inherit;\n border: none;\n background: none;\n cursor: pointer;\n transition: all var(--transition-normal);\n}\n\nbutton:disabled {\n cursor: not-allowed;\n opacity: 0.6;\n}\n\n/* 输入框基础样式 */\ninput,\ntextarea,\nselect {\n font-family: inherit;\n font-size: inherit;\n line-height: inherit;\n border: 1px solid var(--border-color);\n border-radius: var(--radius-md);\n padding: var(--spacing-sm) var(--spacing-md);\n background: var(--bg-primary);\n color: var(--text-primary);\n transition: all var(--transition-fast);\n}\n\ninput:focus,\ntextarea:focus,\nselect:focus {\n outline: none;\n border-color: var(--primary-color);\n box-shadow: 0 0 0 3px rgba(102, 126, 234, 0.1);\n}\n\n/* 滚动条样式 */\n::-webkit-scrollbar {\n width: 8px;\n height: 8px;\n}\n\n::-webkit-scrollbar-track {\n background: var(--bg-tertiary);\n border-radius: var(--radius-sm);\n}\n\n::-webkit-scrollbar-thumb {\n background: var(--border-color);\n border-radius: var(--radius-sm);\n transition: background var(--transition-fast);\n}\n\n::-webkit-scrollbar-thumb:hover {\n background: var(--text-muted);\n}\n\n/* 选择文本样式 */\n::selection {\n background: rgba(102, 126, 234, 0.2);\n color: var(--text-primary);\n}\n\n/* 焦点可见性 */\n:focus-visible {\n outline: 2px solid var(--primary-color);\n outline-offset: 2px;\n}\n\n/* 动画关键帧 */\n@keyframes fadeIn {\n from {\n opacity: 0;\n }\n to {\n opacity: 1;\n }\n}\n\n@keyframes slideUp {\n from {\n opacity: 0;\n transform: translateY(10px);\n }\n to {\n opacity: 1;\n transform: translateY(0);\n }\n}\n\n@keyframes slideDown {\n from {\n opacity: 0;\n transform: translateY(-10px);\n }\n to {\n opacity: 1;\n transform: translateY(0);\n }\n}\n\n@keyframes scaleIn {\n from {\n opacity: 0;\n transform: scale(0.95);\n }\n to {\n opacity: 1;\n transform: scale(1);\n }\n}\n\n/* 响应式断点 */\n@media (max-width: 420px) {\n :root {\n --spacing-xs: 3px;\n --spacing-sm: 6px;\n --spacing-md: 10px;\n --spacing-lg: 14px;\n --spacing-xl: 18px;\n --spacing-2xl: 22px;\n --spacing-3xl: 28px;\n }\n}\n\n/* 高对比度模式支持 */\n@media (prefers-contrast: high) {\n :root {\n --border-color: #000000;\n --text-muted: #000000;\n }\n}\n\n/* 减少动画偏好 */\n@media (prefers-reduced-motion: reduce) {\n * {\n animation-duration: 0.01ms !important;\n animation-iteration-count: 1 !important;\n transition-duration: 0.01ms !important;\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/quick-panel.content.ts", "content": "/**\n * Quick Panel Content Script\n *\n * This content script manages the Quick Panel AI Chat feature on web pages.\n * It responds to:\n * - Background messages (toggle_quick_panel from keyboard shortcut)\n * - Direct programmatic calls\n *\n * The Quick Panel provides a floating AI chat interface that:\n * - Uses Shadow DOM for style isolation\n * - Streams AI responses in real-time\n * - Supports keyboard shortcuts (Enter to send, Esc to close)\n * - Collects page context (URL, selection) automatically\n */\n\nimport { createQuickPanelController, type QuickPanelController } from '@/shared/quick-panel';\n\nexport default defineContentScript({\n matches: [''],\n runAt: 'document_idle',\n\n main() {\n console.log('[QuickPanelContentScript] Content script loaded on:', window.location.href);\n let controller: QuickPanelController | null = null;\n\n /**\n * Ensure controller is initialized (lazy initialization)\n */\n function ensureController(): QuickPanelController {\n if (!controller) {\n controller = createQuickPanelController({\n title: 'Agent',\n subtitle: 'Quick Panel',\n placeholder: 'Ask about this page...',\n });\n }\n return controller;\n }\n\n /**\n * Handle messages from background script\n */\n function handleMessage(\n message: unknown,\n _sender: chrome.runtime.MessageSender,\n sendResponse: (response?: unknown) => void,\n ): boolean | void {\n const msg = message as { action?: string } | undefined;\n\n if (msg?.action === 'toggle_quick_panel') {\n console.log('[QuickPanelContentScript] Received toggle_quick_panel message');\n try {\n const ctrl = ensureController();\n ctrl.toggle();\n const visible = ctrl.isVisible();\n console.log('[QuickPanelContentScript] Toggle completed, visible:', visible);\n sendResponse({ success: true, visible });\n } catch (err) {\n console.error('[QuickPanelContentScript] Toggle error:', err);\n sendResponse({ success: false, error: String(err) });\n }\n return true; // Async response\n }\n\n if (msg?.action === 'show_quick_panel') {\n try {\n const ctrl = ensureController();\n ctrl.show();\n sendResponse({ success: true });\n } catch (err) {\n console.error('[QuickPanelContentScript] Show error:', err);\n sendResponse({ success: false, error: String(err) });\n }\n return true;\n }\n\n if (msg?.action === 'hide_quick_panel') {\n try {\n if (controller) {\n controller.hide();\n }\n sendResponse({ success: true });\n } catch (err) {\n console.error('[QuickPanelContentScript] Hide error:', err);\n sendResponse({ success: false, error: String(err) });\n }\n return true;\n }\n\n if (msg?.action === 'get_quick_panel_status') {\n sendResponse({\n success: true,\n visible: controller?.isVisible() ?? false,\n initialized: controller !== null,\n });\n return true;\n }\n\n // Not handled\n return false;\n }\n\n // Register message listener\n chrome.runtime.onMessage.addListener(handleMessage);\n\n // Cleanup on page unload\n window.addEventListener('unload', () => {\n chrome.runtime.onMessage.removeListener(handleMessage);\n if (controller) {\n controller.dispose();\n controller = null;\n }\n });\n },\n});\n" }, { "path": "app/chrome-extension/entrypoints/shared/composables/index.ts", "content": "/**\n * @fileoverview Shared UI Composables\n * @description Composables shared between multiple UI entrypoints (Sidepanel, Builder, Popup, etc.)\n *\n * Note: These composables are for UI-only use. Do not import them in background scripts\n * as they depend on Vue and will bloat the service worker bundle.\n */\n\n// RR V3 RPC Client\nexport { useRRV3Rpc } from './useRRV3Rpc';\nexport type { UseRRV3Rpc, UseRRV3RpcOptions, RpcRequestOptions } from './useRRV3Rpc';\n" }, { "path": "app/chrome-extension/entrypoints/shared/composables/useRRV3Rpc.ts", "content": "/**\n * @fileoverview RR V3 Port-RPC Client Composable (Shared)\n * @description RPC client for UI components to connect with Background Service Worker\n *\n * This composable is shared between Sidepanel, Builder, and other UI entrypoints.\n *\n * Responsibilities:\n * - Connect to background via chrome.runtime.Port\n * - Provide request/response RPC calls (with timeout and cancellation)\n * - Support event stream subscription\n * - Auto-reconnect with exponential backoff\n *\n * Design considerations:\n * - MV3 service worker may be terminated due to idle, causing Port disconnect\n * - Implement idempotent reconnection and subscription recovery\n */\n\nimport { computed, onUnmounted, ref, shallowRef, type ComputedRef, type Ref } from 'vue';\n\nimport type { JsonObject, JsonValue } from '@/entrypoints/background/record-replay-v3/domain/json';\nimport type { RunEvent } from '@/entrypoints/background/record-replay-v3/domain/events';\nimport type { RunId } from '@/entrypoints/background/record-replay-v3/domain/ids';\nimport {\n RR_V3_PORT_NAME,\n createRpcRequest,\n isRpcEvent,\n isRpcResponse,\n type RpcMethod,\n} from '@/entrypoints/background/record-replay-v3/engine/transport/rpc';\n\n// ==================== Types ====================\n\n/** RPC request options */\nexport interface RpcRequestOptions {\n /** Timeout in milliseconds, 0 means no timeout */\n timeoutMs?: number;\n /** Abort signal for cancellation */\n signal?: AbortSignal;\n}\n\n/** Composable configuration */\nexport interface UseRRV3RpcOptions {\n /** Default request timeout (ms) */\n requestTimeoutMs?: number;\n /** Maximum reconnect attempts */\n maxReconnectAttempts?: number;\n /** Base delay for reconnection (ms) */\n baseReconnectDelayMs?: number;\n /** Auto-connect on initialization */\n autoConnect?: boolean;\n /** Connection state change callback */\n onConnectionChange?: (connected: boolean) => void;\n /** Error callback */\n onError?: (error: string) => void;\n}\n\n/** Event listener function */\ntype EventListener = (event: RunEvent) => void;\n\n/** Pending request entry */\ninterface PendingRequest {\n method: RpcMethod;\n resolve: (value: JsonValue) => void;\n reject: (error: Error) => void;\n timeoutId: ReturnType | null;\n /** AbortSignal reference for cleanup */\n signal?: AbortSignal;\n /** Abort handler for cleanup */\n abortHandler?: () => void;\n}\n\n/** Composable return type */\nexport interface UseRRV3Rpc {\n // Connection state\n connected: Ref;\n connecting: Ref;\n reconnecting: Ref;\n reconnectAttempts: Ref;\n lastError: Ref;\n isReady: ComputedRef;\n\n // Diagnostics\n pendingCount: Ref;\n subscribedRunIds: Ref>;\n\n // Connection lifecycle\n connect: () => Promise;\n disconnect: (reason?: string) => void;\n ensureConnected: () => Promise;\n\n // RPC calls\n request: (\n method: RpcMethod,\n params?: JsonObject,\n options?: RpcRequestOptions,\n ) => Promise;\n\n // Event subscription\n subscribe: (runId?: RunId | null) => Promise;\n unsubscribe: (runId?: RunId | null) => Promise;\n onEvent: (listener: EventListener) => () => void;\n}\n\n// ==================== Helpers ====================\n\nfunction toErrorMessage(error: unknown): string {\n return error instanceof Error ? error.message : String(error);\n}\n\nfunction isRunEvent(value: unknown): value is RunEvent {\n if (typeof value !== 'object' || value === null) return false;\n const obj = value as Record;\n return (\n typeof obj.runId === 'string' &&\n typeof obj.type === 'string' &&\n typeof obj.seq === 'number' &&\n typeof obj.ts === 'number'\n );\n}\n\n// ==================== Composable ====================\n\n/**\n * RR V3 Port-RPC client\n */\nexport function useRRV3Rpc(options: UseRRV3RpcOptions = {}): UseRRV3Rpc {\n // Configuration\n const DEFAULT_TIMEOUT_MS = options.requestTimeoutMs ?? 12_000;\n const MAX_RECONNECT_ATTEMPTS = options.maxReconnectAttempts ?? 8;\n const BASE_RECONNECT_DELAY_MS = options.baseReconnectDelayMs ?? 500;\n\n // Reactive state\n const connected = ref(false);\n const connecting = ref(false);\n const reconnecting = ref(false);\n const reconnectAttempts = ref(0);\n const lastError = ref(null);\n const pendingCount = ref(0);\n const subscribedRunIds = ref>([]);\n\n // Internal state (non-reactive)\n const port = shallowRef(null);\n const pendingRequests = new Map();\n const eventListeners = new Set();\n const desiredSubscriptions = new Set();\n let connectPromise: Promise | null = null;\n let reconnectTimer: ReturnType | null = null;\n let manualDisconnect = false;\n\n // Computed\n const isReady = computed(() => connected.value && port.value !== null);\n\n // ==================== Internal Methods ====================\n\n function setError(message: string | null): void {\n lastError.value = message;\n if (message) options.onError?.(message);\n }\n\n function setConnected(next: boolean): void {\n if (connected.value === next) return;\n connected.value = next;\n options.onConnectionChange?.(next);\n }\n\n function syncSubscriptionsSnapshot(): void {\n const arr = Array.from(desiredSubscriptions.values());\n arr.sort((a, b) => {\n // Both null - equal\n if (a === null && b === null) return 0;\n // null comes first\n if (a === null) return -1;\n if (b === null) return 1;\n return String(a).localeCompare(String(b));\n });\n subscribedRunIds.value = arr;\n }\n\n /**\n * Clean up a pending request entry (timeout, abort listener)\n */\n function cleanupPendingRequest(entry: PendingRequest): void {\n if (entry.timeoutId) {\n clearTimeout(entry.timeoutId);\n entry.timeoutId = null;\n }\n if (entry.signal && entry.abortHandler) {\n try {\n entry.signal.removeEventListener('abort', entry.abortHandler);\n } catch {\n // Ignore - signal may be invalid\n }\n }\n }\n\n function rejectAllPending(reason: string): void {\n const error = new Error(reason);\n for (const [requestId, entry] of pendingRequests) {\n cleanupPendingRequest(entry);\n entry.reject(error);\n pendingRequests.delete(requestId);\n }\n pendingCount.value = 0;\n }\n\n async function rehydrateSubscriptions(): Promise {\n if (!isReady.value || desiredSubscriptions.size === 0) return;\n\n for (const runId of desiredSubscriptions) {\n try {\n const params: JsonObject = runId === null ? {} : { runId };\n await request('rr_v3.subscribe', params).catch(() => {\n // Best-effort, ignore errors\n });\n } catch {\n // Ignore\n }\n }\n }\n\n function scheduleReconnect(): void {\n if (manualDisconnect || reconnectTimer) return;\n\n if (reconnectAttempts.value >= MAX_RECONNECT_ATTEMPTS) {\n reconnecting.value = false;\n setError('RR V3 RPC: max reconnect attempts reached');\n return;\n }\n\n reconnecting.value = true;\n const delay = BASE_RECONNECT_DELAY_MS * Math.pow(2, reconnectAttempts.value);\n\n reconnectTimer = setTimeout(() => {\n reconnectTimer = null;\n reconnectAttempts.value += 1;\n void connect().then((ok) => {\n if (!ok) scheduleReconnect();\n });\n }, delay);\n }\n\n // ==================== Port Handlers ====================\n\n function handlePortDisconnect(): void {\n // Capture disconnect reason for debugging\n const disconnectReason = chrome.runtime.lastError?.message;\n const reason = disconnectReason\n ? `RR V3 RPC disconnected: ${disconnectReason}`\n : 'RR V3 RPC disconnected';\n\n port.value = null;\n setConnected(false);\n connecting.value = false;\n rejectAllPending(reason);\n\n // Update lastError for UI visibility (only on unexpected disconnect)\n if (!manualDisconnect) {\n setError(reason);\n scheduleReconnect();\n }\n }\n\n function handlePortMessage(msg: unknown): void {\n // Handle RPC response\n if (isRpcResponse(msg)) {\n const entry = pendingRequests.get(msg.requestId);\n if (!entry) return;\n\n pendingRequests.delete(msg.requestId);\n pendingCount.value = pendingRequests.size;\n\n // Clean up timeout and abort listener\n cleanupPendingRequest(entry);\n\n if (msg.ok) {\n entry.resolve(msg.result as JsonValue);\n } else {\n entry.reject(new Error(msg.error || `RPC error: ${entry.method}`));\n }\n return;\n }\n\n // Handle event push\n if (isRpcEvent(msg)) {\n const event = msg.event;\n if (!isRunEvent(event)) return;\n\n for (const listener of eventListeners) {\n try {\n listener(event);\n } catch (e) {\n console.error('[useRRV3Rpc] Event listener error:', e);\n }\n }\n }\n }\n\n // ==================== Public Methods ====================\n\n async function connect(): Promise {\n if (isReady.value) return true;\n if (connectPromise) return connectPromise;\n\n connectPromise = (async () => {\n manualDisconnect = false;\n connecting.value = true;\n setError(null);\n\n try {\n if (typeof chrome === 'undefined' || !chrome.runtime?.connect) {\n setError('chrome.runtime.connect not available');\n return false;\n }\n\n const p = chrome.runtime.connect({ name: RR_V3_PORT_NAME });\n port.value = p;\n\n // Reset reconnect state\n reconnectAttempts.value = 0;\n reconnecting.value = false;\n if (reconnectTimer) {\n clearTimeout(reconnectTimer);\n reconnectTimer = null;\n }\n\n p.onMessage.addListener(handlePortMessage);\n p.onDisconnect.addListener(handlePortDisconnect);\n\n setConnected(true);\n\n // Restore subscriptions\n void rehydrateSubscriptions();\n\n return true;\n } catch (error) {\n setError(`Connection failed: ${toErrorMessage(error)}`);\n return false;\n } finally {\n connecting.value = false;\n connectPromise = null;\n }\n })();\n\n return connectPromise;\n }\n\n function disconnect(reason?: string): void {\n manualDisconnect = true;\n\n if (reconnectTimer) {\n clearTimeout(reconnectTimer);\n reconnectTimer = null;\n }\n reconnecting.value = false;\n\n const p = port.value;\n port.value = null;\n setConnected(false);\n connecting.value = false;\n\n rejectAllPending(reason || 'RR V3 RPC: client disconnected');\n\n if (p) {\n try {\n p.onMessage.removeListener(handlePortMessage);\n p.onDisconnect.removeListener(handlePortDisconnect);\n p.disconnect();\n } catch {\n // Ignore\n }\n }\n }\n\n async function ensureConnected(): Promise {\n if (isReady.value) return true;\n return connect();\n }\n\n async function request(\n method: RpcMethod,\n params?: JsonObject,\n reqOptions: RpcRequestOptions = {},\n ): Promise {\n const ready = await ensureConnected();\n const p = port.value;\n\n if (!ready || !p) {\n throw new Error('RR V3 RPC: not connected');\n }\n\n const timeoutMs = reqOptions.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n const { signal } = reqOptions;\n\n if (signal?.aborted) {\n throw new Error('RPC request already aborted');\n }\n\n const req = createRpcRequest(method, params);\n\n return new Promise((resolve, reject) => {\n const entry: PendingRequest = {\n method,\n resolve: resolve as (value: JsonValue) => void,\n reject,\n timeoutId: null,\n signal,\n };\n\n // Helper to complete request with cleanup\n const complete = (fn: () => void) => {\n pendingRequests.delete(req.requestId);\n pendingCount.value = pendingRequests.size;\n cleanupPendingRequest(entry);\n fn();\n };\n\n // Timeout handling\n if (timeoutMs > 0) {\n entry.timeoutId = setTimeout(() => {\n complete(() => reject(new Error(`RPC timeout (${timeoutMs}ms): ${method}`)));\n }, timeoutMs);\n }\n\n // Abort handling\n if (signal) {\n const onAbort = () => {\n complete(() => reject(new Error('RPC request aborted')));\n };\n entry.abortHandler = onAbort;\n signal.addEventListener('abort', onAbort, { once: true });\n }\n\n pendingRequests.set(req.requestId, entry);\n pendingCount.value = pendingRequests.size;\n\n try {\n p.postMessage(req);\n } catch (e) {\n complete(() => reject(new Error(`Failed to send RPC request: ${toErrorMessage(e)}`)));\n }\n });\n }\n\n async function subscribe(runId: RunId | null = null): Promise {\n desiredSubscriptions.add(runId);\n syncSubscriptionsSnapshot();\n\n try {\n const params: JsonObject = runId === null ? {} : { runId };\n await request('rr_v3.subscribe', params);\n return true;\n } catch (error) {\n setError(toErrorMessage(error));\n return false;\n }\n }\n\n async function unsubscribe(runId: RunId | null = null): Promise {\n desiredSubscriptions.delete(runId);\n syncSubscriptionsSnapshot();\n\n try {\n const params: JsonObject = runId === null ? {} : { runId };\n await request('rr_v3.unsubscribe', params);\n return true;\n } catch (error) {\n setError(toErrorMessage(error));\n return false;\n }\n }\n\n function onEvent(listener: EventListener): () => void {\n eventListeners.add(listener);\n return () => eventListeners.delete(listener);\n }\n\n // ==================== Lifecycle ====================\n\n onUnmounted(() => {\n disconnect('Component unmounted');\n });\n\n if (options.autoConnect) {\n void ensureConnected();\n }\n\n return {\n connected,\n connecting,\n reconnecting,\n reconnectAttempts,\n lastError,\n isReady,\n pendingCount,\n subscribedRunIds,\n connect,\n disconnect,\n ensureConnected,\n request,\n subscribe,\n unsubscribe,\n onEvent,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/shared/utils/index.ts", "content": "/**\n * @fileoverview Shared Utilities Index\n * @description Utility functions shared between UI entrypoints\n */\n\n// Flow conversion utilities\nexport {\n flowV2ToV3ForRpc,\n flowV3ToV2ForBuilder,\n isFlowV3,\n isFlowV2,\n extractFlowCandidates,\n type FlowConversionResult,\n} from './rr-flow-convert';\n" }, { "path": "app/chrome-extension/entrypoints/shared/utils/rr-flow-convert.ts", "content": "/**\n * @fileoverview V2/V3 Flow 双向转换工具\n * @description 桥接 Builder V2 Flow 类型与 V3 RPC FlowV3 类型\n *\n * 设计说明:\n * - Builder store 目前仍使用 V2 类型 (type, version, steps)\n * - RPC 层使用 V3 类型 (kind, schemaVersion, entryNodeId)\n * - 本模块提供 UI 层的类型转换，封装底层转换器\n */\n\nimport type { Flow as FlowV2 } from '@/entrypoints/background/record-replay/types';\nimport type { FlowV3 } from '@/entrypoints/background/record-replay-v3/domain/flow';\nimport {\n convertFlowV2ToV3,\n convertFlowV3ToV2,\n} from '@/entrypoints/background/record-replay-v3/storage/import/v2-to-v3';\n\n// ==================== Types ====================\n\nexport interface FlowConversionResult {\n flow: T;\n warnings: string[];\n}\n\n// ==================== V2 -> V3 (for RPC calls) ====================\n\n/**\n * 将 V2 Flow 转换为 V3 格式，用于 RPC 保存\n * @param flowV2 Builder store 中的 V2 Flow\n * @returns V3 Flow 和警告信息\n * @throws 转换失败时抛出错误\n */\nexport function flowV2ToV3ForRpc(flowV2: FlowV2): FlowConversionResult {\n const result = convertFlowV2ToV3(flowV2 as unknown as Parameters[0]);\n\n if (!result.success || !result.data) {\n const errorMsg =\n result.errors.length > 0 ? result.errors.join('; ') : 'Unknown conversion error';\n throw new Error(`V2→V3 conversion failed: ${errorMsg}`);\n }\n\n return {\n flow: result.data,\n warnings: result.warnings,\n };\n}\n\n// ==================== V3 -> V2 (for Builder display) ====================\n\n/**\n * 将 V3 Flow 转换为 V2 格式，用于 Builder 显示和编辑\n * @param flowV3 从 RPC 获取的 V3 Flow\n * @returns V2 Flow 和警告信息\n * @throws 转换失败时抛出错误\n */\nexport function flowV3ToV2ForBuilder(flowV3: FlowV3): FlowConversionResult {\n const result = convertFlowV3ToV2(flowV3);\n\n if (!result.success || !result.data) {\n const errorMsg =\n result.errors.length > 0 ? result.errors.join('; ') : 'Unknown conversion error';\n throw new Error(`V3→V2 conversion failed: ${errorMsg}`);\n }\n\n return {\n flow: result.data as unknown as FlowV2,\n warnings: result.warnings,\n };\n}\n\n// ==================== Type Guards ====================\n\n/**\n * 判断是否为 V3 Flow\n * @description 用于导入时判断 JSON 格式\n */\nexport function isFlowV3(value: unknown): value is FlowV3 {\n if (!value || typeof value !== 'object' || Array.isArray(value)) {\n return false;\n }\n\n const obj = value as Record;\n return (\n obj.schemaVersion === 3 &&\n typeof obj.id === 'string' &&\n typeof obj.name === 'string' &&\n typeof obj.entryNodeId === 'string' &&\n Array.isArray(obj.nodes)\n );\n}\n\n/**\n * 判断是否为 V2 Flow\n * @description 用于导入时判断 JSON 格式\n */\nexport function isFlowV2(value: unknown): value is FlowV2 {\n if (!value || typeof value !== 'object' || Array.isArray(value)) {\n return false;\n }\n\n const obj = value as Record;\n return (\n typeof obj.id === 'string' &&\n typeof obj.name === 'string' &&\n // V2 有 version 字段（数字），且没有 schemaVersion\n typeof obj.version === 'number' &&\n obj.schemaVersion === undefined &&\n // V2 可能有 steps 或 nodes\n (Array.isArray(obj.steps) || Array.isArray(obj.nodes))\n );\n}\n\n// ==================== Import Helpers ====================\n\n/**\n * 从导入的 JSON 中提取 Flow 候选列表\n * @description 支持单个 Flow、Flow 数组、或 { flows: Flow[] } 格式\n */\nexport function extractFlowCandidates(parsed: unknown): unknown[] {\n // 数组格式\n if (Array.isArray(parsed)) {\n return parsed;\n }\n\n // 对象格式\n if (parsed && typeof parsed === 'object') {\n const obj = parsed as Record;\n\n // { flows: [...] } 格式\n if (Array.isArray(obj.flows)) {\n return obj.flows;\n }\n\n // 单个 Flow 对象\n if (obj.id && (Array.isArray(obj.steps) || Array.isArray(obj.nodes))) {\n return [obj];\n }\n }\n\n return [];\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/App.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/AgentChat.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/SidepanelNavigator.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent/AttachmentPreview.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent/ChatInput.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent/CliSettings.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent/ConnectionStatus.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent/MessageItem.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent/MessageList.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent/ProjectCreateForm.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent/ProjectSelector.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent/index.ts", "content": "/**\n * Agent Chat Components\n * Export all sub-components for the agent chat feature.\n */\nexport { default as ConnectionStatus } from './ConnectionStatus.vue';\nexport { default as ProjectSelector } from './ProjectSelector.vue';\nexport { default as ProjectCreateForm } from './ProjectCreateForm.vue';\nexport { default as CliSettings } from './CliSettings.vue';\nexport { default as MessageList } from './MessageList.vue';\nexport { default as MessageItem } from './MessageItem.vue';\nexport { default as ChatInput } from './ChatInput.vue';\nexport { default as AttachmentPreview } from './AttachmentPreview.vue';\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentChatShell.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentComposer.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentConversation.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentOpenProjectMenu.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentProjectMenu.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentRequestThread.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentSessionListItem.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentSessionMenu.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentSessionSettingsPanel.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentSessionsView.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentSettingsMenu.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentTimeline.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentTimelineItem.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AgentTopBar.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/ApplyMessageChip.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/AttachmentCachePanel.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/ComposerDrawer.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/ElementChip.vue", "content": "\n\n\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/FakeCaretOverlay.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/SelectionChip.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/WebEditorChanges.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/index.ts", "content": "/**\n * AgentChat Components\n * Export all components for the redesigned AgentChat UI.\n */\nexport { default as AgentChatShell } from './AgentChatShell.vue';\nexport { default as AgentTopBar } from './AgentTopBar.vue';\nexport { default as AgentComposer } from './AgentComposer.vue';\nexport { default as WebEditorChanges } from './WebEditorChanges.vue';\nexport { default as ElementChip } from './ElementChip.vue';\nexport { default as SelectionChip } from './SelectionChip.vue';\nexport { default as AgentConversation } from './AgentConversation.vue';\nexport { default as AgentRequestThread } from './AgentRequestThread.vue';\nexport { default as AgentTimeline } from './AgentTimeline.vue';\nexport { default as AgentTimelineItem } from './AgentTimelineItem.vue';\nexport { default as AgentSettingsMenu } from './AgentSettingsMenu.vue';\nexport { default as AgentProjectMenu } from './AgentProjectMenu.vue';\nexport { default as AgentSessionMenu } from './AgentSessionMenu.vue';\nexport { default as AgentSessionSettingsPanel } from './AgentSessionSettingsPanel.vue';\nexport { default as AgentSessionsView } from './AgentSessionsView.vue';\nexport { default as AgentSessionListItem } from './AgentSessionListItem.vue';\nexport { default as AgentOpenProjectMenu } from './AgentOpenProjectMenu.vue';\nexport { default as FakeCaretOverlay } from './FakeCaretOverlay.vue';\n\n// Timeline step components\nexport { default as TimelineNarrativeStep } from './timeline/TimelineNarrativeStep.vue';\nexport { default as TimelineToolCallStep } from './timeline/TimelineToolCallStep.vue';\nexport { default as TimelineToolResultCardStep } from './timeline/TimelineToolResultCardStep.vue';\nexport { default as TimelineStatusStep } from './timeline/TimelineStatusStep.vue';\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/timeline/ThinkingNode.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/timeline/TimelineNarrativeStep.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/timeline/TimelineStatusStep.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/timeline/TimelineToolCallStep.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/timeline/TimelineToolResultCardStep.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/timeline/TimelineUserPromptStep.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/agent-chat/timeline/markstream-thinking.ts", "content": "/**\n * Markstream-vue custom component registration for tag.\n *\n * This module registers a custom renderer for tags in markdown content.\n * When markstream-vue encounters ..., it will use ThinkingNode.vue\n * to render a collapsible thinking section instead of raw HTML.\n *\n * Usage:\n * 1. Import this module once (side-effect import) to register the component\n * 2. Add `custom-id=\"agentchat\"` and `:custom-html-tags=\"['thinking']\"` to MarkdownRender\n */\nimport { setCustomComponents } from 'markstream-vue';\nimport ThinkingNode from './ThinkingNode.vue';\n\n/** Scope ID for AgentChat markdown rendering */\nexport const AGENTCHAT_MD_SCOPE = 'agentchat';\n\n// Register the thinking node component\nsetCustomComponents(AGENTCHAT_MD_SCOPE, {\n thinking: ThinkingNode,\n});\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/rr-v3/DebuggerPanel.vue", "content": "\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/workflows/WorkflowListItem.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/workflows/WorkflowsView.vue", "content": "\n\n\n\n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/components/workflows/index.ts", "content": "export { default as WorkflowsView } from './WorkflowsView.vue';\nexport { default as WorkflowListItem } from './WorkflowListItem.vue';\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/index.ts", "content": "/**\n * Agent Chat Composables\n * Export all composables for agent chat functionality.\n */\nexport { useAgentServer } from './useAgentServer';\nexport { useAgentChat } from './useAgentChat';\nexport { useAgentProjects } from './useAgentProjects';\nexport { useAgentSessions } from './useAgentSessions';\nexport { useAttachments, type AttachmentWithPreview } from './useAttachments';\nexport { useAgentTheme, preloadAgentTheme, THEME_LABELS } from './useAgentTheme';\nexport { useAgentThreads, AGENT_SERVER_PORT_KEY } from './useAgentThreads';\nexport { useWebEditorTxState, WEB_EDITOR_TX_STATE_INJECTION_KEY } from './useWebEditorTxState';\nexport { useAgentChatViewRoute } from './useAgentChatViewRoute';\n\nexport type { UseAgentServerOptions } from './useAgentServer';\nexport type { UseAgentChatOptions } from './useAgentChat';\nexport type { UseAgentProjectsOptions } from './useAgentProjects';\nexport type { UseAgentSessionsOptions } from './useAgentSessions';\nexport type { AgentThemeId, UseAgentTheme } from './useAgentTheme';\nexport type {\n AgentThread,\n TimelineItem,\n ToolPresentation,\n ToolKind,\n ToolSeverity,\n AgentThreadState,\n UseAgentThreadsOptions,\n ThreadHeader,\n WebEditorApplyMeta,\n} from './useAgentThreads';\nexport type { UseWebEditorTxStateOptions, WebEditorTxStateReturn } from './useWebEditorTxState';\nexport type {\n AgentChatView,\n AgentChatRouteState,\n UseAgentChatViewRouteOptions,\n UseAgentChatViewRoute,\n} from './useAgentChatViewRoute';\n\n// RR V3 Composables\nexport { useRRV3Rpc } from './useRRV3Rpc';\nexport { useRRV3Debugger } from './useRRV3Debugger';\nexport type { UseRRV3Rpc, UseRRV3RpcOptions, RpcRequestOptions } from './useRRV3Rpc';\nexport type { UseRRV3Debugger, UseRRV3DebuggerOptions } from './useRRV3Debugger';\n\n// Textarea Auto-Resize\nexport { useTextareaAutoResize } from './useTextareaAutoResize';\nexport type {\n UseTextareaAutoResizeOptions,\n UseTextareaAutoResizeReturn,\n} from './useTextareaAutoResize';\n\n// Fake Caret (comet tail animation)\nexport { useFakeCaret } from './useFakeCaret';\nexport type { UseFakeCaretOptions, UseFakeCaretReturn, FakeCaretTrailPoint } from './useFakeCaret';\n\n// Open Project Preference\nexport { useOpenProjectPreference } from './useOpenProjectPreference';\nexport type {\n UseOpenProjectPreferenceOptions,\n UseOpenProjectPreference,\n} from './useOpenProjectPreference';\n\n// Agent Input Preferences (fake caret, etc.)\nexport { useAgentInputPreferences } from './useAgentInputPreferences';\nexport type { UseAgentInputPreferences } from './useAgentInputPreferences';\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useAgentChat.ts", "content": "/**\n * Composable for managing Agent Chat state and messages.\n * Handles message sending, receiving, and cancellation.\n */\nimport { ref, computed } from 'vue';\nimport type {\n AgentMessage,\n AgentActRequest,\n AgentActRequestClientMeta,\n AgentAttachment,\n RealtimeEvent,\n AgentStatusEvent,\n AgentCliPreference,\n AgentUsageStats,\n} from 'chrome-mcp-shared';\n\n/**\n * Request lifecycle state.\n * - 'idle': No active request\n * - 'starting': Request accepted, waiting for engine initialization\n * - 'ready': Engine initialized, preparing to run\n * - 'running': Engine actively processing (may emit tool_use/tool_result)\n * - 'completed': Request finished successfully\n * - 'cancelled': Request was cancelled by user\n * - 'error': Request failed with error\n */\nexport type RequestState = 'idle' | AgentStatusEvent['status'];\n\nexport interface UseAgentChatOptions {\n getServerPort: () => number | null;\n getSessionId: () => string;\n ensureServer: () => Promise;\n openEventSource: () => void;\n}\n\nexport function useAgentChat(options: UseAgentChatOptions) {\n // State\n const messages = ref([]);\n const input = ref('');\n const sending = ref(false);\n /**\n * Message-level streaming state.\n * True when receiving delta updates for assistant/tool messages.\n * Note: This is separate from requestState - a request can be 'running'\n * even when isStreaming is false (e.g., during tool execution).\n */\n const isStreaming = ref(false);\n /**\n * Request lifecycle state driven by status events.\n * Use this (via isRequestActive) for UI elements like stop button,\n * loading indicators, and running badges.\n */\n const requestState = ref('idle');\n const errorMessage = ref(null);\n const currentRequestId = ref(null);\n const cancelling = ref(false);\n const attachments = ref([]);\n const lastUsage = ref(null);\n\n // Computed\n const canSend = computed(() => {\n return input.value.trim().length > 0 && !sending.value;\n });\n\n /**\n * Whether there is an active request in progress.\n * Use this for UI elements like stop button, loading indicators, and running badges.\n */\n const isRequestActive = computed(() => {\n return (\n requestState.value === 'starting' ||\n requestState.value === 'ready' ||\n requestState.value === 'running'\n );\n });\n\n /**\n * Check if an incoming event belongs to a different active request.\n * Used to filter out stale events from previous requests.\n */\n function isDifferentActiveRequest(incomingRequestId?: string): boolean {\n const incoming = incomingRequestId?.trim();\n const current = currentRequestId.value?.trim();\n // No incoming ID or no current ID means we can't determine - don't filter\n if (!incoming || !current) return false;\n // Same request ID - don't filter\n if (incoming === current) return false;\n // Different request ID while we have an active request - filter it out\n return isRequestActive.value;\n }\n\n /**\n * Handle incoming realtime events.\n * Events are filtered by sessionId to prevent cross-session state pollution\n * when user switches sessions while SSE connection is still active.\n */\n function handleRealtimeEvent(event: RealtimeEvent): void {\n const currentSessionId = options.getSessionId();\n\n switch (event.type) {\n case 'message':\n // Guard: only handle messages for the current session\n if (event.data.sessionId !== currentSessionId) {\n return;\n }\n handleMessageEvent(event.data);\n break;\n case 'status':\n // Guard: only handle status for the current session\n if (event.data.sessionId !== currentSessionId) {\n return;\n }\n handleStatusEvent(event.data);\n break;\n case 'error':\n // Error events may not have sessionId, but if they do, filter\n if (event.data?.sessionId && event.data.sessionId !== currentSessionId) {\n return;\n }\n // Filter out errors from different active requests\n if (isDifferentActiveRequest(event.data?.requestId)) {\n return;\n }\n errorMessage.value = event.error;\n isStreaming.value = false;\n requestState.value = 'error';\n // Clear requestId if it matches the error event's requestId (or unconditionally if no requestId in error)\n if (!event.data?.requestId || event.data.requestId === currentRequestId.value) {\n currentRequestId.value = null;\n }\n break;\n case 'connected':\n console.log('[AgentChat] Connected to session:', event.data.sessionId);\n break;\n case 'heartbeat':\n // Heartbeat received, connection is alive\n break;\n case 'usage':\n // Guard: only accept usage for the current session\n if (event.data?.sessionId && event.data.sessionId !== currentSessionId) {\n return;\n }\n lastUsage.value = event.data;\n break;\n }\n }\n\n // Handle message events\n function handleMessageEvent(msg: AgentMessage): void {\n // For user messages from server, replace local optimistic message\n // Server echoes user message with real id/metadata, but we want to keep our display text\n // (which doesn't include injected context like web editor selection)\n if (msg.role === 'user' && msg.requestId) {\n const optimisticIndex = messages.value.findIndex(\n (m) => m.role === 'user' && m.requestId === msg.requestId && m.id.startsWith('temp-'),\n );\n if (optimisticIndex >= 0) {\n // Replace optimistic message: keep display content, update id and metadata\n const optimistic = messages.value[optimisticIndex];\n messages.value[optimisticIndex] = {\n ...msg,\n // Preserve the display content (user's raw input without injected context)\n content: optimistic.content,\n // Prefer server metadata, fallback to optimistic metadata (for chip rendering)\n metadata: msg.metadata ?? optimistic.metadata,\n };\n return;\n }\n }\n\n // Check if this message belongs to a different active request\n // Note: We still save the message to messages array (for auditing/replay),\n // but skip state updates if it's from a stale request\n const msgRequestId = msg.requestId?.trim() || undefined;\n const isStaleForState = isDifferentActiveRequest(msgRequestId);\n\n const existingIndex = messages.value.findIndex((m) => m.id === msg.id);\n\n if (existingIndex >= 0) {\n // Update existing message (streaming update)\n messages.value[existingIndex] = msg;\n } else {\n // Add new message - always save, even if stale for state\n messages.value.push(msg);\n }\n\n // Skip state updates for messages from different active requests\n if (isStaleForState) {\n return;\n }\n\n // Track requestId from messages (handles cases where status events were missed)\n if (msgRequestId && msgRequestId !== currentRequestId.value) {\n currentRequestId.value = msgRequestId;\n }\n\n // Update message-level streaming state (delta updates)\n // Note: This does NOT affect requestState - tool_use with isStreaming=false\n // should not stop the overall request, only indicate this message is complete\n if (msg.role === 'assistant' || msg.role === 'tool') {\n isStreaming.value = msg.isStreaming === true && !msg.isFinal;\n\n // If we're receiving model/tool output but requestState hasn't progressed to 'running',\n // update it. This handles:\n // 1. Edge case where status events were missed due to SSE timing\n // 2. User enters AgentChat mid-request (e.g., from Quick Panel/toolbar trigger)\n // 3. SSE reconnection after temporary disconnect\n if (\n requestState.value === 'idle' ||\n requestState.value === 'starting' ||\n requestState.value === 'ready'\n ) {\n requestState.value = 'running';\n }\n }\n }\n\n // Handle status events\n function handleStatusEvent(status: AgentStatusEvent): void {\n const statusRequestId = status.requestId?.trim() || undefined;\n\n // Filter out status events from different active requests\n if (isDifferentActiveRequest(statusRequestId)) {\n return;\n }\n\n // Track requestId from status events\n if (statusRequestId && statusRequestId !== currentRequestId.value) {\n currentRequestId.value = statusRequestId;\n }\n\n // Update request lifecycle state (driven by status events only)\n requestState.value = status.status;\n\n switch (status.status) {\n case 'starting':\n case 'ready':\n case 'running':\n // Request is active - no additional state changes needed\n break;\n case 'completed':\n case 'error':\n case 'cancelled':\n // Request finished - clear message streaming and requestId\n isStreaming.value = false;\n // Reset cancelling state (in case we were waiting for SSE confirmation)\n cancelling.value = false;\n if (!statusRequestId || statusRequestId === currentRequestId.value) {\n currentRequestId.value = null;\n }\n break;\n }\n }\n\n // Send message\n async function send(\n chatOptions: {\n cliPreference?: string;\n model?: string;\n projectId?: string;\n projectRoot?: string;\n dbSessionId?: string;\n /**\n * Optional instruction to send instead of input.value.\n * When provided, this is used as the actual instruction sent to the server,\n * while input.value is still used for UI display in the optimistic message.\n * This is useful for injecting context (e.g., web editor selection) into the prompt\n * without showing it in the chat UI.\n */\n instruction?: string;\n /**\n * Optional compact display text stored in the user message metadata.\n * When provided, the UI can render a special header (e.g., a chip) instead\n * of the raw prompt content.\n */\n displayText?: string;\n /**\n * Optional client metadata to persist with the user message.\n * Used for special UI rendering (e.g., web editor apply/selection chips).\n */\n clientMeta?: AgentActRequestClientMeta;\n } = {},\n ): Promise {\n // User-visible content is always the user's raw input\n const userText = input.value.trim();\n // Actual instruction sent to server can be overridden (e.g., with context prepended)\n const instructionText = chatOptions.instruction?.trim() || userText;\n\n if (!userText) return;\n\n const ready = await options.ensureServer();\n const serverPort = options.getServerPort();\n const sessionId = options.getSessionId();\n\n if (!ready || !serverPort) {\n errorMessage.value = 'Agent server is not available.';\n return;\n }\n\n // Ensure SSE is connected before sending\n options.openEventSource();\n\n // Generate requestId on client side for optimistic message matching\n // Server will use this requestId when echoing user message via SSE\n const requestId = crypto.randomUUID();\n\n // Create optimistic user message for immediate feedback\n // Note: Use userText for UI, not instructionText (which may contain injected context)\n const tempMessageId = `temp-${Date.now()}`;\n const optimisticMessage: AgentMessage = {\n id: tempMessageId,\n sessionId: sessionId,\n role: 'user',\n content: userText,\n messageType: 'chat',\n requestId, // Include requestId so we can match with server-echoed message\n createdAt: new Date().toISOString(),\n // Include metadata for immediate chip rendering (before server echo)\n metadata:\n chatOptions.displayText || chatOptions.clientMeta\n ? {\n displayText: chatOptions.displayText?.trim(),\n clientMeta: chatOptions.clientMeta,\n }\n : undefined,\n };\n\n // Add user message immediately\n messages.value.push(optimisticMessage);\n\n const payload: AgentActRequest = {\n // Use instructionText which may include injected context (e.g., web editor selection)\n instruction: instructionText,\n requestId, // Send requestId to server so it can be used in SSE events\n // Optional metadata for special UI rendering (stored with the user message)\n displayText: chatOptions.displayText?.trim() || undefined,\n clientMeta: chatOptions.clientMeta,\n cliPreference: chatOptions.cliPreference\n ? (chatOptions.cliPreference as AgentCliPreference)\n : undefined,\n model: chatOptions.model?.trim() || undefined,\n projectId: chatOptions.projectId || undefined,\n projectRoot: chatOptions.projectRoot?.trim() || undefined,\n dbSessionId: chatOptions.dbSessionId || undefined,\n attachments: attachments.value.length > 0 ? attachments.value : undefined,\n };\n\n sending.value = true;\n // Initialize request lifecycle state - request begins once we dispatch /act\n requestState.value = 'starting';\n currentRequestId.value = requestId;\n // Reset message-level streaming; it will be driven by message.isStreaming deltas\n isStreaming.value = false;\n errorMessage.value = null;\n\n // Clear input immediately for better UX\n const savedInput = input.value;\n input.value = '';\n const savedAttachments = [...attachments.value];\n attachments.value = [];\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/chat/${encodeURIComponent(sessionId)}/act`;\n\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(payload),\n });\n\n if (!response.ok) {\n const text = await response.text().catch(() => '');\n throw new Error(text || `HTTP ${response.status}`);\n }\n\n const result = await response.json().catch(() => ({}));\n\n // Guard: only update state if we're still on the same session\n // This prevents cross-session state pollution when user switches during request\n const currentSessionId = options.getSessionId();\n if (currentSessionId !== sessionId) {\n // Session changed during request - discard result silently\n // The optimistic message will be cleared when messages are reloaded\n isStreaming.value = false;\n requestState.value = 'idle';\n currentRequestId.value = null;\n return;\n }\n\n // Update currentRequestId from response (should match our client-generated one)\n // This is used for cancel functionality\n if (result.requestId) {\n currentRequestId.value = result.requestId;\n } else {\n // Fallback: use our client-generated requestId\n currentRequestId.value = requestId;\n }\n } catch (error: unknown) {\n // Guard: only handle error if still on same session\n const currentSessionId = options.getSessionId();\n if (currentSessionId !== sessionId) {\n isStreaming.value = false;\n requestState.value = 'idle';\n currentRequestId.value = null;\n return;\n }\n\n console.error('Failed to send agent act request:', error);\n errorMessage.value =\n error instanceof Error ? error.message : 'Failed to send request to agent server.';\n // Restore input on error\n input.value = savedInput;\n attachments.value = savedAttachments;\n // Remove optimistic message on error\n const msgIndex = messages.value.findIndex((m) => m.id === tempMessageId);\n if (msgIndex >= 0) {\n messages.value.splice(msgIndex, 1);\n }\n isStreaming.value = false;\n requestState.value = 'idle';\n currentRequestId.value = null;\n } finally {\n sending.value = false;\n }\n }\n\n // Cancel current request\n async function cancelCurrentRequest(): Promise {\n if (!currentRequestId.value) return;\n\n const serverPort = options.getServerPort();\n const sessionId = options.getSessionId();\n\n if (!serverPort) return;\n\n cancelling.value = true;\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/chat/${encodeURIComponent(sessionId)}/cancel/${encodeURIComponent(currentRequestId.value)}`;\n\n const response = await fetch(url, { method: 'DELETE' });\n const data = await response.json().catch(() => null);\n\n // Check if cancel was successful\n // Backend returns { success: boolean, message?: string }\n const isSuccess = response.ok && data?.success !== false;\n\n if (!isSuccess) {\n // Cancel failed - show error but keep request state intact\n // so user can try again or wait for natural completion\n const errorMsg = data?.message || `Failed to cancel request (HTTP ${response.status})`;\n console.error('Cancel request failed:', errorMsg);\n errorMessage.value = errorMsg;\n return;\n }\n\n // Cancel request sent successfully\n // Note: We intentionally do NOT clear currentRequestId/requestState here\n // The actual state cleanup will happen when we receive the 'cancelled' status event via SSE\n // This ensures UI stays consistent with backend state and avoids race conditions\n // Keep cancelling=true so UI shows \"Stopping...\" until SSE confirms\n // cancelling will be reset when handleStatusEvent receives 'cancelled' status\n } catch (error) {\n console.error('Failed to cancel request:', error);\n errorMessage.value = error instanceof Error ? error.message : 'Failed to cancel request';\n // Only reset cancelling on error, not on success\n cancelling.value = false;\n }\n }\n\n // Clear messages\n function clearMessages(): void {\n messages.value = [];\n }\n\n // Set messages (for loading history)\n function setMessages(newMessages: AgentMessage[]): void {\n messages.value = newMessages;\n }\n\n return {\n // State\n messages,\n input,\n sending,\n isStreaming,\n requestState,\n errorMessage,\n currentRequestId,\n cancelling,\n attachments,\n lastUsage,\n\n // Computed\n canSend,\n isRequestActive,\n\n // Methods\n handleRealtimeEvent,\n send,\n cancelCurrentRequest,\n clearMessages,\n setMessages,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useAgentChatViewRoute.ts", "content": "/**\n * Composable for managing AgentChat view routing.\n *\n * Handles navigation between 'sessions' (list) and 'chat' (conversation) views\n * without requiring vue-router. Supports URL parameters for deep linking.\n *\n * URL Parameters:\n * - `view`: 'sessions' | 'chat' (default: 'sessions')\n * - `sessionId`: Session ID to open directly in chat view\n *\n * Example URLs:\n * - `sidepanel.html?tab=agent-chat` → sessions list\n * - `sidepanel.html?tab=agent-chat&view=chat&sessionId=xxx` → direct to chat\n */\nimport { ref, computed } from 'vue';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Available view modes */\nexport type AgentChatView = 'sessions' | 'chat';\n\n/** Route state */\nexport interface AgentChatRouteState {\n view: AgentChatView;\n sessionId: string | null;\n}\n\n/** Options for useAgentChatViewRoute */\nexport interface UseAgentChatViewRouteOptions {\n /**\n * Callback when route changes.\n * Called after internal state is updated.\n */\n onRouteChange?: (state: AgentChatRouteState) => void;\n}\n\n// =============================================================================\n// Constants\n// =============================================================================\n\nconst DEFAULT_VIEW: AgentChatView = 'sessions';\nconst URL_PARAM_VIEW = 'view';\nconst URL_PARAM_SESSION_ID = 'sessionId';\n\n// =============================================================================\n// Helpers\n// =============================================================================\n\n/**\n * Parse view from URL parameter.\n * Returns default if invalid.\n */\nfunction parseView(value: string | null): AgentChatView {\n if (value === 'sessions' || value === 'chat') {\n return value;\n }\n return DEFAULT_VIEW;\n}\n\n/**\n * Update URL parameters without page reload.\n * Preserves existing parameters (like `tab`).\n */\nfunction updateUrlParams(view: AgentChatView, sessionId: string | null): void {\n try {\n const url = new URL(window.location.href);\n\n // Update view param\n if (view === DEFAULT_VIEW) {\n url.searchParams.delete(URL_PARAM_VIEW);\n } else {\n url.searchParams.set(URL_PARAM_VIEW, view);\n }\n\n // Update sessionId param\n if (sessionId) {\n url.searchParams.set(URL_PARAM_SESSION_ID, sessionId);\n } else {\n url.searchParams.delete(URL_PARAM_SESSION_ID);\n }\n\n // Update URL without reload\n window.history.replaceState({}, '', url.toString());\n } catch {\n // Ignore URL update errors (e.g., in non-browser environment)\n }\n}\n\n// =============================================================================\n// Composable\n// =============================================================================\n\nexport function useAgentChatViewRoute(options: UseAgentChatViewRouteOptions = {}) {\n // ==========================================================================\n // State\n // ==========================================================================\n\n const currentView = ref(DEFAULT_VIEW);\n const currentSessionId = ref(null);\n\n // ==========================================================================\n // Computed\n // ==========================================================================\n\n /** Whether currently showing sessions list */\n const isSessionsView = computed(() => currentView.value === 'sessions');\n\n /** Whether currently showing chat conversation */\n const isChatView = computed(() => currentView.value === 'chat');\n\n /** Current route state */\n const routeState = computed(() => ({\n view: currentView.value,\n sessionId: currentSessionId.value,\n }));\n\n // ==========================================================================\n // Actions\n // ==========================================================================\n\n /**\n * Navigate to sessions list view.\n * Clears sessionId from URL.\n */\n function goToSessions(): void {\n currentView.value = 'sessions';\n // Don't clear sessionId internally - it's used to highlight selected session\n updateUrlParams('sessions', null);\n options.onRouteChange?.(routeState.value);\n }\n\n /**\n * Navigate to chat view for a specific session.\n * @param sessionId - Session ID to open\n */\n function goToChat(sessionId: string): void {\n if (!sessionId) {\n console.warn('[useAgentChatViewRoute] goToChat called without sessionId');\n return;\n }\n\n currentView.value = 'chat';\n currentSessionId.value = sessionId;\n updateUrlParams('chat', sessionId);\n options.onRouteChange?.(routeState.value);\n }\n\n /**\n * Initialize route from URL parameters.\n * Should be called on mount.\n * @returns Initial route state\n */\n function initFromUrl(): AgentChatRouteState {\n try {\n const params = new URLSearchParams(window.location.search);\n const viewParam = params.get(URL_PARAM_VIEW);\n const sessionIdParam = params.get(URL_PARAM_SESSION_ID);\n\n const view = parseView(viewParam);\n const sessionId = sessionIdParam?.trim() || null;\n\n // If view=chat but no sessionId, fall back to sessions\n if (view === 'chat' && !sessionId) {\n currentView.value = 'sessions';\n currentSessionId.value = null;\n } else {\n currentView.value = view;\n currentSessionId.value = sessionId;\n }\n } catch {\n // Use defaults on error\n currentView.value = DEFAULT_VIEW;\n currentSessionId.value = null;\n }\n\n return routeState.value;\n }\n\n /**\n * Update session ID without changing view.\n * Updates URL based on current view and sessionId:\n * - In chat view: always update URL with sessionId\n * - In sessions view with null sessionId: clear sessionId from URL (cleanup)\n */\n function setSessionId(sessionId: string | null): void {\n currentSessionId.value = sessionId;\n\n if (currentView.value === 'chat') {\n // In chat view, always sync URL with current sessionId\n updateUrlParams('chat', sessionId);\n } else if (sessionId === null) {\n // In sessions view, clear any stale sessionId from URL\n // This handles edge cases like deleting the last session\n updateUrlParams('sessions', null);\n }\n }\n\n // ==========================================================================\n // Lifecycle\n // ==========================================================================\n\n // Note: We don't call initFromUrl() here because AgentChat.vue needs to\n // call it after loading sessions (to verify sessionId exists).\n // Caller is responsible for calling initFromUrl() at the right time.\n\n // ==========================================================================\n // Return\n // ==========================================================================\n\n return {\n // State\n currentView,\n currentSessionId,\n\n // Computed\n isSessionsView,\n isChatView,\n routeState,\n\n // Actions\n goToSessions,\n goToChat,\n initFromUrl,\n setSessionId,\n };\n}\n\n// =============================================================================\n// Type Export\n// =============================================================================\n\nexport type UseAgentChatViewRoute = ReturnType;\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useAgentInputPreferences.ts", "content": "/**\n * Composable for user-facing input preferences in AgentChat.\n * Preferences are persisted in chrome.storage.local.\n */\nimport { ref, type Ref } from 'vue';\n\n// =============================================================================\n// Constants\n// =============================================================================\n\nconst STORAGE_KEY_FAKE_CARET = 'agent-chat-fake-caret-enabled';\n\n// =============================================================================\n// Types\n// =============================================================================\n\nexport interface UseAgentInputPreferences {\n /** Whether the fake caret + comet trail is enabled (opt-in). Default: false */\n fakeCaretEnabled: Ref;\n /** Whether preferences have been loaded from storage */\n ready: Ref;\n /** Load preferences from chrome.storage.local (call on mount) */\n init: () => Promise;\n /** Persist and update fake caret preference */\n setFakeCaretEnabled: (enabled: boolean) => Promise;\n}\n\n// =============================================================================\n// Composable\n// =============================================================================\n\n/**\n * Composable for managing user input preferences.\n *\n * Features:\n * - Fake caret toggle (opt-in, default off)\n * - Persistence via chrome.storage.local\n * - Graceful fallback when storage is unavailable\n */\nexport function useAgentInputPreferences(): UseAgentInputPreferences {\n const fakeCaretEnabled = ref(false);\n const ready = ref(false);\n\n /**\n * Load preferences from chrome.storage.local.\n * Should be called during component mount.\n */\n async function init(): Promise {\n try {\n if (typeof chrome === 'undefined' || !chrome.storage?.local) {\n ready.value = true;\n return;\n }\n\n const result = await chrome.storage.local.get(STORAGE_KEY_FAKE_CARET);\n const stored = result[STORAGE_KEY_FAKE_CARET];\n\n if (typeof stored === 'boolean') {\n fakeCaretEnabled.value = stored;\n }\n } catch (error) {\n console.error('[useAgentInputPreferences] Failed to load preferences:', error);\n } finally {\n ready.value = true;\n }\n }\n\n /**\n * Update and persist the fake caret preference.\n */\n async function setFakeCaretEnabled(enabled: boolean): Promise {\n fakeCaretEnabled.value = enabled;\n\n try {\n if (typeof chrome === 'undefined' || !chrome.storage?.local) return;\n await chrome.storage.local.set({ [STORAGE_KEY_FAKE_CARET]: enabled });\n } catch (error) {\n console.error('[useAgentInputPreferences] Failed to save fake caret preference:', error);\n }\n }\n\n return {\n fakeCaretEnabled,\n ready,\n init,\n setFakeCaretEnabled,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useAgentProjects.ts", "content": "/**\n * Composable for managing Agent Projects.\n * Handles project CRUD, selection, and persistence.\n */\nimport { ref, computed, watch } from 'vue';\nimport type { AgentProject, AgentStoredMessage } from 'chrome-mcp-shared';\n\nconst STORAGE_KEY_SELECTED_PROJECT = 'agent-selected-project-id';\n\ninterface PathValidationResult {\n valid: boolean;\n absolute: string;\n exists: boolean;\n needsCreation: boolean;\n error?: string;\n}\n\n/**\n * Normalize path for comparison (handle trailing slashes and separators).\n */\nfunction normalizePathForComparison(path: string): string {\n // Remove trailing slashes and normalize separators\n return path\n .trim()\n .replace(/[/\\\\]+$/, '')\n .replace(/\\\\/g, '/')\n .toLowerCase();\n}\n\nexport interface UseAgentProjectsOptions {\n getServerPort: () => number | null;\n ensureServer: () => Promise;\n onHistoryLoaded?: (messages: AgentStoredMessage[]) => void;\n}\n\nexport function useAgentProjects(options: UseAgentProjectsOptions) {\n // State\n const projects = ref([]);\n const selectedProjectId = ref('');\n const isLoadingProjects = ref(false);\n const showCreateProject = ref(false);\n const newProjectName = ref('');\n const newProjectRootPath = ref('');\n const isCreatingProject = ref(false);\n const projectError = ref(null);\n\n // Computed\n const selectedProject = computed(() => {\n return projects.value.find((p) => p.id === selectedProjectId.value) || null;\n });\n\n const canCreateProject = computed(() => {\n return newProjectName.value.trim().length > 0 && newProjectRootPath.value.trim().length > 0;\n });\n\n // Load selected project from storage\n async function loadSelectedProjectId(): Promise {\n try {\n const result = await chrome.storage.local.get(STORAGE_KEY_SELECTED_PROJECT);\n if (result[STORAGE_KEY_SELECTED_PROJECT]) {\n selectedProjectId.value = result[STORAGE_KEY_SELECTED_PROJECT];\n }\n } catch (error) {\n console.error('Failed to load selected project ID:', error);\n }\n }\n\n // Save selected project to storage\n async function saveSelectedProjectId(): Promise {\n try {\n await chrome.storage.local.set({\n [STORAGE_KEY_SELECTED_PROJECT]: selectedProjectId.value,\n });\n } catch (error) {\n console.error('Failed to save selected project ID:', error);\n }\n }\n\n // Fetch projects from server\n async function fetchProjects(): Promise {\n const serverPort = options.getServerPort();\n if (!serverPort) return;\n\n isLoadingProjects.value = true;\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/projects`;\n const response = await fetch(url);\n if (response.ok) {\n const data = await response.json();\n projects.value = data.projects || [];\n }\n } catch (error) {\n console.error('Failed to fetch projects:', error);\n } finally {\n isLoadingProjects.value = false;\n }\n }\n\n // Refresh projects\n async function refreshProjects(): Promise {\n const ready = await options.ensureServer();\n if (!ready) return;\n await fetchProjects();\n }\n\n // Track pending history load with nonce to prevent A→B→A race conditions\n let historyLoadNonce = 0;\n\n /**\n * Load chat history for a project with race-condition protection.\n * Uses a nonce to handle A→B→A scenarios.\n */\n async function loadChatHistory(projectId: string): Promise {\n const serverPort = options.getServerPort();\n if (!serverPort || !projectId) return;\n\n // Increment nonce - any subsequent load will invalidate this one\n const myNonce = ++historyLoadNonce;\n\n const isStillValid = (): boolean => {\n return myNonce === historyLoadNonce && selectedProjectId.value === projectId;\n };\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/chat/${encodeURIComponent(projectId)}/messages?limit=100`;\n const response = await fetch(url);\n\n if (!isStillValid()) return;\n\n if (response.ok) {\n const result = await response.json();\n\n if (!isStillValid()) return;\n\n // Server returns { success, data: messages[], totalCount, pagination }\n const stored = result.data || [];\n options.onHistoryLoaded?.(stored);\n }\n } catch (error) {\n console.error('Failed to load chat history:', error);\n }\n }\n\n // Validate path before creating project\n async function validatePath(rootPath: string): Promise {\n const serverPort = options.getServerPort();\n if (!serverPort) return null;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/projects/validate-path`;\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ rootPath }),\n });\n\n if (!response.ok) {\n const text = await response.text().catch(() => '');\n throw new Error(text || `Validation failed: HTTP ${response.status}`);\n }\n\n return await response.json();\n } catch (error) {\n console.error('Failed to validate path:', error);\n return null;\n }\n }\n\n // Create project\n async function createProject(): Promise {\n const name = newProjectName.value.trim();\n const rootPath = newProjectRootPath.value.trim();\n if (!name || !rootPath) return null;\n\n const ready = await options.ensureServer();\n const serverPort = options.getServerPort();\n if (!ready || !serverPort) {\n projectError.value = 'Agent server is not available.';\n return null;\n }\n\n isCreatingProject.value = true;\n projectError.value = null;\n\n try {\n // Step 1: Validate the path\n const validation = await validatePath(rootPath);\n if (!validation) {\n projectError.value = 'Failed to validate path';\n return null;\n }\n\n if (!validation.valid) {\n projectError.value = validation.error || 'Invalid path';\n return null;\n }\n\n // Step 2: If directory doesn't exist, ask user for confirmation\n let allowCreate = false;\n if (validation.needsCreation) {\n const confirmed = confirm(\n `目录 \"${validation.absolute}\" 不存在，是否创建？\\n\\nThe directory \"${validation.absolute}\" does not exist. Create it?`,\n );\n if (!confirmed) {\n return null;\n }\n allowCreate = true;\n }\n\n // Step 3: Create the project\n const url = `http://127.0.0.1:${serverPort}/agent/projects`;\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ name, rootPath, allowCreate }),\n });\n\n if (!response.ok) {\n const text = await response.text().catch(() => '');\n throw new Error(text || `HTTP ${response.status}`);\n }\n\n const payload = await response.json();\n const project = payload?.project as AgentProject | undefined;\n\n if (project?.id) {\n // Update local state\n const others = projects.value.filter((p) => p.id !== project.id);\n projects.value = [...others, project];\n selectedProjectId.value = project.id;\n await saveSelectedProjectId();\n await loadChatHistory(project.id);\n\n // Clear form\n newProjectName.value = '';\n newProjectRootPath.value = '';\n showCreateProject.value = false;\n\n return project;\n } else {\n projectError.value = 'Project created but response is invalid.';\n return null;\n }\n } catch (error: unknown) {\n console.error('Failed to create project:', error);\n projectError.value = error instanceof Error ? error.message : 'Failed to create project.';\n return null;\n } finally {\n isCreatingProject.value = false;\n }\n }\n\n // Toggle create project form\n function toggleCreateProject(): void {\n showCreateProject.value = !showCreateProject.value;\n if (!showCreateProject.value) {\n newProjectName.value = '';\n newProjectRootPath.value = '';\n projectError.value = null;\n }\n }\n\n // Get default project root path for a project name\n async function getDefaultProjectRoot(projectName: string): Promise {\n const serverPort = options.getServerPort();\n if (!serverPort || !projectName.trim()) return null;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/projects/default-root`;\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ projectName: projectName.trim() }),\n });\n if (response.ok) {\n const data = await response.json();\n return data.path || null;\n }\n return null;\n } catch (error) {\n console.error('Failed to get default project root:', error);\n return null;\n }\n }\n\n // Open directory picker dialog\n async function pickDirectory(): Promise {\n const ready = await options.ensureServer();\n const serverPort = options.getServerPort();\n if (!ready || !serverPort) {\n projectError.value = 'Server not available';\n return null;\n }\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/projects/pick-directory`;\n const response = await fetch(url, { method: 'POST' });\n\n // Handle HTTP errors (e.g., 404 means server version mismatch)\n if (!response.ok) {\n if (response.status === 404) {\n projectError.value =\n 'Directory picker not available. Please rebuild and restart the native server.';\n } else {\n projectError.value = `Server error: HTTP ${response.status}`;\n }\n return null;\n }\n\n const data = await response.json();\n\n if (data.success && data.path) {\n return data.path;\n } else if (data.cancelled) {\n return null; // User cancelled, not an error\n } else {\n projectError.value = data.error || 'Failed to open directory picker';\n return null;\n }\n } catch (error) {\n console.error('Failed to open directory picker:', error);\n projectError.value = 'Failed to open directory picker';\n return null;\n }\n }\n\n // Ensure default project exists (auto-create if no projects)\n async function ensureDefaultProject(): Promise {\n const ready = await options.ensureServer();\n const serverPort = options.getServerPort();\n if (!ready || !serverPort) return null;\n\n try {\n // First fetch current projects\n await fetchProjects();\n\n // If there are already projects, no need to create default\n if (projects.value.length > 0) {\n return null;\n }\n\n // Get default workspace directory from server\n const defaultRootUrl = `http://127.0.0.1:${serverPort}/agent/projects/default-root`;\n const defaultRootResponse = await fetch(defaultRootUrl, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ projectName: 'default' }),\n });\n const defaultRootData = await defaultRootResponse.json();\n const defaultRoot = defaultRootData.path;\n\n if (!defaultRoot) {\n console.error('Failed to get default project root');\n return null;\n }\n\n // Create default project\n const createUrl = `http://127.0.0.1:${serverPort}/agent/projects`;\n const createResponse = await fetch(createUrl, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n name: 'Default',\n rootPath: defaultRoot,\n allowCreate: true,\n }),\n });\n\n if (!createResponse.ok) {\n const text = await createResponse.text().catch(() => '');\n console.error('Failed to create default project:', text);\n return null;\n }\n\n const payload = await createResponse.json();\n const project = payload?.project as AgentProject | undefined;\n\n if (project?.id) {\n projects.value = [project];\n selectedProjectId.value = project.id;\n await saveSelectedProjectId();\n return project;\n }\n\n return null;\n } catch (error) {\n console.error('Failed to ensure default project:', error);\n return null;\n }\n }\n\n // Create project from a directory path (used when user picks a directory)\n async function createProjectFromPath(\n rootPath: string,\n name: string,\n ): Promise {\n const ready = await options.ensureServer();\n const serverPort = options.getServerPort();\n if (!ready || !serverPort) {\n projectError.value = 'Agent server is not available.';\n return null;\n }\n\n projectError.value = null;\n\n try {\n // Validate the path first\n const validation = await validatePath(rootPath);\n if (!validation) {\n projectError.value = 'Failed to validate path';\n return null;\n }\n\n if (!validation.valid) {\n projectError.value = validation.error || 'Invalid path';\n return null;\n }\n\n // Check if project with same path already exists\n const normalizedPath = normalizePathForComparison(validation.absolute);\n const existingProject = projects.value.find(\n (p) => normalizePathForComparison(p.rootPath) === normalizedPath,\n );\n\n if (existingProject) {\n // Project already exists - select it instead of creating a new one\n const shouldSwitch = confirm(\n `目录 \"${validation.absolute}\" 已存在对应的项目：${existingProject.name}\\n\\n` +\n `是否切换到该项目？\\n\\n` +\n `A project already exists for \"${validation.absolute}\": ${existingProject.name}\\n` +\n `Switch to that project?`,\n );\n if (shouldSwitch) {\n selectedProjectId.value = existingProject.id;\n await saveSelectedProjectId();\n await loadChatHistory(existingProject.id);\n return existingProject;\n }\n // User declined to switch, return null to indicate no action taken\n return null;\n }\n\n // If directory doesn't exist, ask user for confirmation\n let allowCreate = false;\n if (validation.needsCreation) {\n const confirmed = confirm(\n `目录 \"${validation.absolute}\" 不存在，是否创建？\\n\\nThe directory \"${validation.absolute}\" does not exist. Create it?`,\n );\n if (!confirmed) {\n return null;\n }\n allowCreate = true;\n }\n\n // Create the project\n const url = `http://127.0.0.1:${serverPort}/agent/projects`;\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ name, rootPath, allowCreate }),\n });\n\n if (!response.ok) {\n const text = await response.text().catch(() => '');\n throw new Error(text || `HTTP ${response.status}`);\n }\n\n const payload = await response.json();\n const project = payload?.project as AgentProject | undefined;\n\n if (project?.id) {\n // Update local state\n const others = projects.value.filter((p) => p.id !== project.id);\n projects.value = [...others, project];\n selectedProjectId.value = project.id;\n await saveSelectedProjectId();\n await loadChatHistory(project.id);\n\n return project;\n } else {\n projectError.value = 'Project created but response is invalid.';\n return null;\n }\n } catch (error: unknown) {\n console.error('Failed to create project from path:', error);\n projectError.value = error instanceof Error ? error.message : 'Failed to create project.';\n return null;\n }\n }\n\n // Handle project change\n async function handleProjectChanged(): Promise {\n await saveSelectedProjectId();\n if (selectedProjectId.value) {\n await loadChatHistory(selectedProjectId.value);\n }\n }\n\n // Save project preference (CLI, model, useCcr, enableChromeMcp)\n async function saveProjectPreference(\n cli?: string,\n model?: string,\n useCcr?: boolean,\n enableChromeMcp?: boolean,\n ): Promise {\n const project = selectedProject.value;\n const serverPort = options.getServerPort();\n if (!project || !serverPort) return;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/projects`;\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n id: project.id,\n name: project.name,\n rootPath: project.rootPath,\n // Normalize and allow empty string (means \"Auto/Default\")\n preferredCli: cli?.trim() ?? project.preferredCli,\n selectedModel: model?.trim() ?? project.selectedModel,\n useCcr: useCcr ?? project.useCcr,\n enableChromeMcp: enableChromeMcp ?? project.enableChromeMcp,\n }),\n });\n\n // Update local project state if successful\n if (response.ok) {\n const payload = await response.json();\n const updatedProject = payload?.project as AgentProject | undefined;\n if (updatedProject?.id) {\n const index = projects.value.findIndex((p) => p.id === updatedProject.id);\n if (index !== -1) {\n projects.value[index] = updatedProject;\n }\n }\n }\n } catch (error) {\n console.error('Failed to save project preference:', error);\n }\n }\n\n return {\n // State\n projects,\n selectedProjectId,\n isLoadingProjects,\n showCreateProject,\n newProjectName,\n newProjectRootPath,\n isCreatingProject,\n projectError,\n\n // Computed\n selectedProject,\n canCreateProject,\n\n // Methods\n loadSelectedProjectId,\n saveSelectedProjectId,\n fetchProjects,\n refreshProjects,\n loadChatHistory,\n createProject,\n toggleCreateProject,\n handleProjectChanged,\n saveProjectPreference,\n getDefaultProjectRoot,\n pickDirectory,\n ensureDefaultProject,\n createProjectFromPath,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useAgentServer.ts", "content": "/**\n * Composable for managing Agent Server connection state.\n * Handles native host connection, server status, and SSE stream.\n */\nimport { ref, computed, onUnmounted } from 'vue';\nimport { NativeMessageType } from 'chrome-mcp-shared';\nimport { BACKGROUND_MESSAGE_TYPES } from '@/common/message-types';\nimport type { AgentEngineInfo, RealtimeEvent } from 'chrome-mcp-shared';\n\ninterface ServerStatus {\n isRunning: boolean;\n port?: number;\n lastUpdated: number;\n}\n\nexport interface UseAgentServerOptions {\n /**\n * Get the session ID for SSE routing.\n * Must be provided by caller (typically DB session ID).\n */\n getSessionId?: () => string;\n onMessage?: (event: RealtimeEvent) => void;\n onError?: (error: string) => void;\n}\n\nexport function useAgentServer(options: UseAgentServerOptions = {}) {\n // State\n const serverPort = ref(null);\n const nativeConnected = ref(false);\n const serverStatus = ref(null);\n const connecting = ref(false);\n const engines = ref([]);\n const eventSource = ref(null);\n\n // Reconnection state\n let reconnectAttempts = 0;\n const MAX_RECONNECT_ATTEMPTS = 5;\n const BASE_RECONNECT_DELAY = 1000;\n\n // Track which sessionId the current SSE connection is subscribed to\n let currentStreamSessionId: string | null = null;\n\n // Computed\n const isServerReady = computed(() => {\n return nativeConnected.value && serverStatus.value?.isRunning && serverPort.value !== null;\n });\n\n // Check native host connection using existing message type\n async function checkNativeHost(): Promise {\n try {\n const response = await chrome.runtime.sendMessage({\n type: NativeMessageType.PING_NATIVE,\n });\n nativeConnected.value = response?.connected ?? false;\n return nativeConnected.value;\n } catch (error) {\n console.error('Failed to check native host:', error);\n nativeConnected.value = false;\n return false;\n }\n }\n\n /**\n * Start native host connection.\n * @param forceConnect - If true, use CONNECT_NATIVE (re-enables auto-connect).\n * If false, use ENSURE_NATIVE (respects current auto-connect setting).\n */\n async function startNativeHost(forceConnect = false): Promise {\n try {\n const response = await chrome.runtime.sendMessage({\n type: forceConnect ? NativeMessageType.CONNECT_NATIVE : NativeMessageType.ENSURE_NATIVE,\n });\n // Handle both response formats: { connected: boolean } and { success: boolean }\n nativeConnected.value =\n typeof response?.connected === 'boolean'\n ? response.connected\n : (response?.success ?? false);\n return nativeConnected.value;\n } catch (error) {\n console.error('Failed to start native host:', error);\n nativeConnected.value = false;\n return false;\n }\n }\n\n // Get server status using existing message type\n async function getServerStatus(): Promise {\n try {\n const response = await chrome.runtime.sendMessage({\n type: BACKGROUND_MESSAGE_TYPES.GET_SERVER_STATUS,\n });\n if (response?.serverStatus) {\n serverStatus.value = response.serverStatus;\n if (response.serverStatus.port) {\n serverPort.value = response.serverStatus.port;\n }\n // Also update native connected status from response\n if (typeof response.connected === 'boolean') {\n nativeConnected.value = response.connected;\n }\n return response.serverStatus;\n }\n return null;\n } catch (error) {\n console.error('Failed to get server status:', error);\n return null;\n }\n }\n\n interface EnsureNativeServerOptions {\n /** If true, use CONNECT_NATIVE to re-enable auto-connect */\n forceConnect?: boolean;\n }\n\n // Ensure native server is ready\n async function ensureNativeServer(opts: EnsureNativeServerOptions = {}): Promise {\n const { forceConnect = false } = opts;\n connecting.value = true;\n try {\n // Step 1: Check native host connection\n let connected = await checkNativeHost();\n if (!connected) {\n // Try to start native host\n connected = await startNativeHost(forceConnect);\n if (!connected) {\n console.error('Failed to connect to native host');\n return false;\n }\n // Wait for connection to stabilize\n await new Promise((resolve) => setTimeout(resolve, 500));\n }\n\n // Step 2: Get server status\n const status = await getServerStatus();\n if (!status?.isRunning || !status.port) {\n console.error('Server not running or port not available', status);\n return false;\n }\n\n // Step 3: Fetch engines\n await fetchEngines();\n\n return true;\n } finally {\n connecting.value = false;\n }\n }\n\n // Fetch available engines\n async function fetchEngines(): Promise {\n if (!serverPort.value) return;\n try {\n const url = `http://127.0.0.1:${serverPort.value}/agent/engines`;\n const response = await fetch(url);\n if (response.ok) {\n const data = await response.json();\n engines.value = data.engines || [];\n }\n } catch (error) {\n console.error('Failed to fetch engines:', error);\n }\n }\n\n // Check if SSE is connected\n function isEventSourceConnected(): boolean {\n return eventSource.value !== null && eventSource.value.readyState === EventSource.OPEN;\n }\n\n // Open SSE connection (skip if already connected to same session)\n function openEventSource(): void {\n const targetSessionId = options.getSessionId?.()?.trim() ?? '';\n if (!serverPort.value || !targetSessionId) return;\n\n // Skip if already connected to the same session\n if (isEventSourceConnected() && currentStreamSessionId === targetSessionId) {\n console.log('[AgentServer] SSE already connected to session, skipping reconnect');\n return;\n }\n\n // Close existing connection before subscribing to a new session\n closeEventSource();\n\n currentStreamSessionId = targetSessionId;\n const url = `http://127.0.0.1:${serverPort.value}/agent/chat/${encodeURIComponent(targetSessionId)}/stream`;\n const es = new EventSource(url);\n\n es.onopen = () => {\n console.log('[AgentServer] SSE connection opened');\n reconnectAttempts = 0;\n };\n\n es.onmessage = (event) => {\n try {\n const parsed = JSON.parse(event.data) as RealtimeEvent;\n options.onMessage?.(parsed);\n } catch (err) {\n console.error('[AgentServer] Failed to parse SSE message:', err);\n }\n };\n\n es.onerror = (error) => {\n console.error('[AgentServer] SSE error:', error);\n es.close();\n eventSource.value = null;\n\n // Attempt reconnection with exponential backoff\n if (reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {\n const delay = BASE_RECONNECT_DELAY * Math.pow(2, reconnectAttempts);\n reconnectAttempts++;\n console.log(`[AgentServer] Reconnecting in ${delay}ms (attempt ${reconnectAttempts})`);\n setTimeout(() => {\n if (isServerReady.value) {\n openEventSource();\n }\n }, delay);\n } else {\n options.onError?.('SSE connection failed after multiple attempts');\n }\n };\n\n eventSource.value = es;\n }\n\n // Close SSE connection\n function closeEventSource(): void {\n if (eventSource.value) {\n eventSource.value.close();\n eventSource.value = null;\n }\n currentStreamSessionId = null;\n }\n\n // Reconnect to server (explicit user action, re-enables auto-connect)\n async function reconnect(): Promise {\n closeEventSource();\n reconnectAttempts = 0;\n // Explicit user reconnect: force connect to re-enable auto-connect in background\n await ensureNativeServer({ forceConnect: true });\n if (isServerReady.value) {\n openEventSource();\n }\n }\n\n // Initialize\n async function initialize(): Promise {\n await ensureNativeServer();\n // Note: SSE connection is now opened explicitly when session is ready\n }\n\n // Cleanup on unmount\n onUnmounted(() => {\n closeEventSource();\n });\n\n return {\n // State\n serverPort,\n nativeConnected,\n serverStatus,\n connecting,\n engines,\n eventSource,\n\n // Computed\n isServerReady,\n\n // Methods\n ensureNativeServer,\n fetchEngines,\n openEventSource,\n closeEventSource,\n isEventSourceConnected,\n reconnect,\n initialize,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useAgentSessions.ts", "content": "/**\n * Composable for managing Agent Sessions.\n * Sessions represent independent conversations within a project.\n * Each session has its own engine configuration, chat history, and resume state.\n */\nimport { ref, computed, watch } from 'vue';\nimport type {\n AgentSession,\n AgentCliPreference,\n CreateAgentSessionInput,\n UpdateAgentSessionInput,\n AgentStoredMessage,\n AgentManagementInfo,\n} from 'chrome-mcp-shared';\n\nconst STORAGE_KEY_SELECTED_SESSION = 'agent-selected-session-id';\n\nexport interface UseAgentSessionsOptions {\n getServerPort: () => number | null;\n ensureServer: () => Promise;\n onSessionChanged?: (sessionId: string) => void;\n onHistoryLoaded?: (messages: AgentStoredMessage[]) => void;\n}\n\nexport function useAgentSessions(options: UseAgentSessionsOptions) {\n // State\n const sessions = ref([]);\n const allSessions = ref([]); // All sessions across all projects\n const selectedSessionId = ref('');\n const isLoadingSessions = ref(false);\n const isLoadingAllSessions = ref(false);\n const isCreatingSession = ref(false);\n const sessionError = ref(null);\n\n // Computed\n const selectedSession = computed(() => {\n return sessions.value.find((s) => s.id === selectedSessionId.value) || null;\n });\n\n const hasSessions = computed(() => sessions.value.length > 0);\n\n // Load selected session from storage\n async function loadSelectedSessionId(): Promise {\n try {\n const result = await chrome.storage.local.get(STORAGE_KEY_SELECTED_SESSION);\n if (result[STORAGE_KEY_SELECTED_SESSION]) {\n selectedSessionId.value = result[STORAGE_KEY_SELECTED_SESSION];\n }\n } catch (error) {\n console.error('Failed to load selected session ID:', error);\n }\n }\n\n // Save selected session to storage\n async function saveSelectedSessionId(): Promise {\n try {\n await chrome.storage.local.set({\n [STORAGE_KEY_SELECTED_SESSION]: selectedSessionId.value,\n });\n } catch (error) {\n console.error('Failed to save selected session ID:', error);\n }\n }\n\n // Track pending session fetch with nonce to prevent A→B→A race conditions\n let fetchSessionsNonce = 0;\n\n /**\n * Fetch sessions for a project with race-condition protection.\n * Uses a nonce to handle A→B→A scenarios.\n */\n async function fetchSessions(projectId: string): Promise {\n const serverPort = options.getServerPort();\n if (!serverPort || !projectId) return;\n\n // Increment nonce - any subsequent fetch will invalidate this one\n const myNonce = ++fetchSessionsNonce;\n\n const isStillValid = (): boolean => {\n return myNonce === fetchSessionsNonce;\n };\n\n isLoadingSessions.value = true;\n sessionError.value = null;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/projects/${encodeURIComponent(projectId)}/sessions`;\n const response = await fetch(url);\n\n if (!isStillValid()) return;\n\n if (response.ok) {\n const data = await response.json();\n\n if (!isStillValid()) return;\n\n sessions.value = data.sessions || [];\n\n // If we have sessions but no selection, select the most recent one\n if (sessions.value.length > 0 && !selectedSessionId.value) {\n selectedSessionId.value = sessions.value[0].id;\n await saveSelectedSessionId();\n }\n } else {\n const text = await response.text().catch(() => '');\n sessionError.value = text || `HTTP ${response.status}`;\n }\n } catch (error) {\n console.error('Failed to fetch sessions:', error);\n sessionError.value = error instanceof Error ? error.message : 'Failed to fetch sessions';\n } finally {\n isLoadingSessions.value = false;\n }\n }\n\n // Track pending all sessions fetch with nonce\n let fetchAllSessionsNonce = 0;\n\n /**\n * Fetch all sessions across all projects.\n * Used for the global sessions list view.\n */\n async function fetchAllSessions(): Promise {\n const serverPort = options.getServerPort();\n if (!serverPort) return;\n\n const myNonce = ++fetchAllSessionsNonce;\n\n const isStillValid = (): boolean => {\n return myNonce === fetchAllSessionsNonce;\n };\n\n isLoadingAllSessions.value = true;\n sessionError.value = null;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/sessions`;\n const response = await fetch(url);\n\n if (!isStillValid()) return;\n\n if (response.ok) {\n const data = await response.json();\n\n if (!isStillValid()) return;\n\n allSessions.value = data.sessions || [];\n } else {\n const text = await response.text().catch(() => '');\n sessionError.value = text || `HTTP ${response.status}`;\n }\n } catch (error) {\n console.error('Failed to fetch all sessions:', error);\n sessionError.value = error instanceof Error ? error.message : 'Failed to fetch sessions';\n } finally {\n isLoadingAllSessions.value = false;\n }\n }\n\n // Track pending create session with nonce to prevent cross-project pollution\n let createSessionNonce = 0;\n\n /**\n * Create a new session with race-condition protection.\n * Uses a nonce to prevent cross-project state pollution when user switches\n * projects during session creation.\n */\n async function createSession(\n projectId: string,\n input: CreateAgentSessionInput,\n ): Promise {\n const ready = await options.ensureServer();\n const serverPort = options.getServerPort();\n if (!ready || !serverPort) {\n sessionError.value = 'Server not available';\n return null;\n }\n\n // Increment nonce - any subsequent create will invalidate this one\n const myNonce = ++createSessionNonce;\n\n isCreatingSession.value = true;\n sessionError.value = null;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/projects/${encodeURIComponent(projectId)}/sessions`;\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(input),\n });\n\n // Guard: check if this is still the expected create operation\n if (myNonce !== createSessionNonce) {\n // A newer create was initiated - discard this result\n return null;\n }\n\n if (!response.ok) {\n const text = await response.text().catch(() => '');\n throw new Error(text || `HTTP ${response.status}`);\n }\n\n const data = await response.json();\n\n // Re-check after json parsing\n if (myNonce !== createSessionNonce) {\n return null;\n }\n\n const session = data.session as AgentSession | undefined;\n\n if (session?.id) {\n // Add to local list and select it\n sessions.value = [session, ...sessions.value];\n // Also add to allSessions (at front, as it's the newest)\n allSessions.value = [session, ...allSessions.value.filter((s) => s.id !== session.id)];\n selectedSessionId.value = session.id;\n await saveSelectedSessionId();\n options.onSessionChanged?.(session.id);\n return session;\n }\n\n sessionError.value = 'Session created but response is invalid';\n return null;\n } catch (error) {\n // Guard: only handle error if still valid\n if (myNonce !== createSessionNonce) {\n return null;\n }\n console.error('Failed to create session:', error);\n sessionError.value = error instanceof Error ? error.message : 'Failed to create session';\n return null;\n } finally {\n isCreatingSession.value = false;\n }\n }\n\n // Get a session by ID\n async function getSession(sessionId: string): Promise {\n const serverPort = options.getServerPort();\n if (!serverPort || !sessionId) return null;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/sessions/${encodeURIComponent(sessionId)}`;\n const response = await fetch(url);\n if (response.ok) {\n const data = await response.json();\n return data.session || null;\n }\n return null;\n } catch (error) {\n console.error('Failed to get session:', error);\n return null;\n }\n }\n\n // Update a session\n async function updateSession(\n sessionId: string,\n updates: UpdateAgentSessionInput,\n ): Promise {\n const serverPort = options.getServerPort();\n if (!serverPort || !sessionId) return null;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/sessions/${encodeURIComponent(sessionId)}`;\n const response = await fetch(url, {\n method: 'PATCH',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(updates),\n });\n\n if (!response.ok) {\n const text = await response.text().catch(() => '');\n throw new Error(text || `HTTP ${response.status}`);\n }\n\n const data = await response.json();\n const session = data.session as AgentSession | undefined;\n\n if (session?.id) {\n // Update local list\n const index = sessions.value.findIndex((s) => s.id === session.id);\n if (index !== -1) {\n sessions.value[index] = session;\n }\n // Also update allSessions (in-place to preserve order)\n const allIndex = allSessions.value.findIndex((s) => s.id === session.id);\n if (allIndex !== -1) {\n allSessions.value[allIndex] = session;\n }\n return session;\n }\n\n return null;\n } catch (error) {\n console.error('Failed to update session:', error);\n sessionError.value = error instanceof Error ? error.message : 'Failed to update session';\n return null;\n }\n }\n\n // Delete a session\n async function deleteSession(sessionId: string): Promise {\n const serverPort = options.getServerPort();\n if (!serverPort || !sessionId) return false;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/sessions/${encodeURIComponent(sessionId)}`;\n const response = await fetch(url, { method: 'DELETE' });\n\n if (response.ok || response.status === 204) {\n // Remove from local list\n sessions.value = sessions.value.filter((s) => s.id !== sessionId);\n // Also remove from allSessions\n allSessions.value = allSessions.value.filter((s) => s.id !== sessionId);\n\n // If deleted session was selected, select another one\n if (selectedSessionId.value === sessionId) {\n selectedSessionId.value = sessions.value[0]?.id || '';\n await saveSelectedSessionId();\n if (selectedSessionId.value) {\n options.onSessionChanged?.(selectedSessionId.value);\n }\n }\n return true;\n }\n\n return false;\n } catch (error) {\n console.error('Failed to delete session:', error);\n return false;\n }\n }\n\n // Select a session\n async function selectSession(sessionId: string): Promise {\n if (selectedSessionId.value === sessionId) return;\n\n selectedSessionId.value = sessionId;\n await saveSelectedSessionId();\n options.onSessionChanged?.(sessionId);\n }\n\n // Create a default session for a project if none exist\n async function ensureDefaultSession(\n projectId: string,\n engineName: AgentCliPreference = 'claude',\n ): Promise {\n await fetchSessions(projectId);\n\n // If sessions exist, select the first one if none selected\n if (sessions.value.length > 0) {\n if (\n !selectedSessionId.value ||\n !sessions.value.find((s) => s.id === selectedSessionId.value)\n ) {\n await selectSession(sessions.value[0].id);\n }\n return selectedSession.value;\n }\n\n // Create default session\n return createSession(projectId, {\n engineName,\n name: 'Default Session',\n });\n }\n\n // Rename a session\n async function renameSession(sessionId: string, name: string): Promise {\n const result = await updateSession(sessionId, { name });\n return result !== null;\n }\n\n // Reset a session conversation (delete messages + clear engineSessionId)\n async function resetConversation(sessionId: string): Promise<{\n deletedMessages: number;\n clearedEngineSessionId: boolean;\n session: AgentSession | null;\n } | null> {\n const ready = await options.ensureServer();\n const serverPort = options.getServerPort();\n if (!ready || !serverPort || !sessionId) {\n sessionError.value = 'Server not available';\n return null;\n }\n\n sessionError.value = null;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/sessions/${encodeURIComponent(sessionId)}/reset`;\n const response = await fetch(url, { method: 'POST' });\n\n if (!response.ok) {\n const text = await response.text().catch(() => '');\n throw new Error(text || `HTTP ${response.status}`);\n }\n\n const data = await response.json();\n const session = data.session as AgentSession | null;\n\n // Update local session state\n if (session?.id) {\n const index = sessions.value.findIndex((s) => s.id === session.id);\n if (index !== -1) {\n sessions.value[index] = session;\n }\n }\n\n return {\n deletedMessages: typeof data.deletedMessages === 'number' ? data.deletedMessages : 0,\n clearedEngineSessionId: data.clearedEngineSessionId === true,\n session,\n };\n } catch (error) {\n console.error('Failed to reset conversation:', error);\n sessionError.value = error instanceof Error ? error.message : 'Failed to reset conversation';\n return null;\n }\n }\n\n // Fetch Claude SDK management info for a session\n async function fetchClaudeInfo(sessionId: string): Promise<{\n managementInfo: AgentManagementInfo | null;\n sessionId: string;\n engineName: string;\n } | null> {\n const serverPort = options.getServerPort();\n if (!serverPort || !sessionId) return null;\n\n try {\n const url = `http://127.0.0.1:${serverPort}/agent/sessions/${encodeURIComponent(sessionId)}/claude-info`;\n const response = await fetch(url);\n\n if (!response.ok) {\n const text = await response.text().catch(() => '');\n throw new Error(text || `HTTP ${response.status}`);\n }\n\n const data = await response.json();\n return {\n managementInfo: data.managementInfo ?? null,\n sessionId: data.sessionId ?? sessionId,\n engineName: data.engineName ?? '',\n };\n } catch (error) {\n console.error('Failed to fetch Claude info:', error);\n return null;\n }\n }\n\n // Clear sessions when project changes\n function clearSessions(): void {\n sessions.value = [];\n selectedSessionId.value = '';\n }\n\n /**\n * Update session preview and updatedAt locally (without server call).\n * Used when sending a message to update the display immediately.\n * Always updates updatedAt so the session moves to the top of the list.\n * @param sessionId - The session to update\n * @param preview - The preview text (user's raw input)\n * @param previewMeta - Optional structured metadata for special rendering (e.g., web editor apply chip)\n */\n function updateSessionPreview(\n sessionId: string,\n preview: string,\n previewMeta?: AgentSession['previewMeta'],\n ): void {\n // Truncate to 50 chars with ellipsis\n const maxLen = 50;\n const trimmed = preview.trim().replace(/\\s+/g, ' ');\n const truncated = trimmed.length > maxLen ? trimmed.slice(0, maxLen - 1) + '…' : trimmed;\n\n // Always update updatedAt to move session to top of list\n const now = new Date().toISOString();\n\n // Update in current project sessions\n const index = sessions.value.findIndex((s) => s.id === sessionId);\n if (index !== -1) {\n sessions.value[index] = {\n ...sessions.value[index],\n // Only update preview if not already set\n preview: sessions.value[index].preview || truncated,\n previewMeta: sessions.value[index].previewMeta || previewMeta,\n // Always update timestamp so session moves to top\n updatedAt: now,\n };\n }\n\n // Also update in allSessions for global list view\n const allIndex = allSessions.value.findIndex((s) => s.id === sessionId);\n if (allIndex !== -1) {\n allSessions.value[allIndex] = {\n ...allSessions.value[allIndex],\n preview: allSessions.value[allIndex].preview || truncated,\n previewMeta: allSessions.value[allIndex].previewMeta || previewMeta,\n updatedAt: now,\n };\n }\n }\n\n return {\n // State\n sessions,\n allSessions,\n selectedSessionId,\n isLoadingSessions,\n isLoadingAllSessions,\n isCreatingSession,\n sessionError,\n\n // Computed\n selectedSession,\n hasSessions,\n\n // Methods\n loadSelectedSessionId,\n saveSelectedSessionId,\n fetchSessions,\n fetchAllSessions,\n createSession,\n getSession,\n updateSession,\n deleteSession,\n selectSession,\n ensureDefaultSession,\n renameSession,\n resetConversation,\n fetchClaudeInfo,\n clearSessions,\n updateSessionPreview,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useAgentTheme.ts", "content": "/**\n * Composable for managing AgentChat theme.\n * Handles theme persistence and application.\n */\nimport { ref, type Ref } from 'vue';\n\n/** Available theme identifiers */\nexport type AgentThemeId =\n | 'warm-editorial'\n | 'blueprint-architect'\n | 'zen-journal'\n | 'neo-pop'\n | 'dark-console'\n | 'swiss-grid';\n\n/** Storage key for persisting theme preference */\nconst STORAGE_KEY_THEME = 'agentTheme';\n\n/** Default theme when none is set */\nconst DEFAULT_THEME: AgentThemeId = 'warm-editorial';\n\n/** Valid theme IDs for validation */\nconst VALID_THEMES: AgentThemeId[] = [\n 'warm-editorial',\n 'blueprint-architect',\n 'zen-journal',\n 'neo-pop',\n 'dark-console',\n 'swiss-grid',\n];\n\n/** Theme display names for UI */\nexport const THEME_LABELS: Record = {\n 'warm-editorial': 'Editorial',\n 'blueprint-architect': 'Blueprint',\n 'zen-journal': 'Zen',\n 'neo-pop': 'Neo-Pop',\n 'dark-console': 'Console',\n 'swiss-grid': 'Swiss',\n};\n\nexport interface UseAgentTheme {\n /** Current theme ID */\n theme: Ref;\n /** Whether theme has been loaded from storage */\n ready: Ref;\n /** Set and persist a new theme */\n setTheme: (id: AgentThemeId) => Promise;\n /** Load theme from storage (call on mount) */\n initTheme: () => Promise;\n /** Apply theme to a DOM element */\n applyTo: (el: HTMLElement) => void;\n /** Get the preloaded theme from document (set by main.ts) */\n getPreloadedTheme: () => AgentThemeId;\n}\n\n/**\n * Check if a string is a valid theme ID\n */\nfunction isValidTheme(value: unknown): value is AgentThemeId {\n return typeof value === 'string' && VALID_THEMES.includes(value as AgentThemeId);\n}\n\n/**\n * Get theme from document element (preloaded by main.ts)\n */\nfunction getThemeFromDocument(): AgentThemeId {\n const value = document.documentElement.dataset.agentTheme;\n return isValidTheme(value) ? value : DEFAULT_THEME;\n}\n\n/**\n * Composable for managing AgentChat theme\n */\nexport function useAgentTheme(): UseAgentTheme {\n // Initialize with preloaded theme (or default)\n const theme = ref(getThemeFromDocument());\n const ready = ref(false);\n\n /**\n * Load theme from chrome.storage.local\n */\n async function initTheme(): Promise {\n try {\n const result = await chrome.storage.local.get(STORAGE_KEY_THEME);\n const stored = result[STORAGE_KEY_THEME];\n\n if (isValidTheme(stored)) {\n theme.value = stored;\n } else {\n // Use preloaded or default\n theme.value = getThemeFromDocument();\n }\n } catch (error) {\n console.error('[useAgentTheme] Failed to load theme:', error);\n theme.value = getThemeFromDocument();\n } finally {\n ready.value = true;\n }\n }\n\n /**\n * Set and persist a new theme\n */\n async function setTheme(id: AgentThemeId): Promise {\n if (!isValidTheme(id)) {\n console.warn('[useAgentTheme] Invalid theme ID:', id);\n return;\n }\n\n // Update immediately for responsive UI\n theme.value = id;\n\n // Also update document element for consistency\n document.documentElement.dataset.agentTheme = id;\n\n // Persist to storage\n try {\n await chrome.storage.local.set({ [STORAGE_KEY_THEME]: id });\n } catch (error) {\n console.error('[useAgentTheme] Failed to save theme:', error);\n }\n }\n\n /**\n * Apply theme to a DOM element\n */\n function applyTo(el: HTMLElement): void {\n el.dataset.agentTheme = theme.value;\n }\n\n /**\n * Get the preloaded theme from document\n */\n function getPreloadedTheme(): AgentThemeId {\n return getThemeFromDocument();\n }\n\n return {\n theme,\n ready,\n setTheme,\n initTheme,\n applyTo,\n getPreloadedTheme,\n };\n}\n\n/**\n * Preload theme before Vue mounts (call in main.ts)\n * This prevents theme flashing on page load.\n */\nexport async function preloadAgentTheme(): Promise {\n let themeId: AgentThemeId = DEFAULT_THEME;\n\n try {\n const result = await chrome.storage.local.get(STORAGE_KEY_THEME);\n const stored = result[STORAGE_KEY_THEME];\n\n if (isValidTheme(stored)) {\n themeId = stored;\n }\n } catch (error) {\n console.error('[preloadAgentTheme] Failed to load theme:', error);\n }\n\n // Set on document element for immediate application\n document.documentElement.dataset.agentTheme = themeId;\n\n return themeId;\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts", "content": "/**\n * Composable for grouping messages into conversation threads.\n * Transforms flat AgentMessage[] into structured AgentThread[] for UI rendering.\n */\nimport { computed, type InjectionKey, type Ref } from 'vue';\nimport type {\n AgentMessage,\n AgentMessageAttachmentMetadata,\n AttachmentMetadata,\n} from 'chrome-mcp-shared';\nimport type { RequestState } from './useAgentChat';\n\n/**\n * Injection key for agent server port.\n * Provided by AgentChat.vue for child components to access attachment URLs.\n */\nexport const AGENT_SERVER_PORT_KEY: InjectionKey> = Symbol('agentServerPort');\n\n/** Thread state */\nexport type AgentThreadState =\n | 'idle'\n | 'starting'\n | 'running'\n | 'completed'\n | 'error'\n | 'cancelled';\n\n/** Tool kinds for presentation */\nexport type ToolKind = 'grep' | 'read' | 'edit' | 'run' | 'plan' | 'generic';\n\n/** Tool severity for styling */\nexport type ToolSeverity = 'info' | 'success' | 'warning' | 'error';\n\n/** Diff statistics for edit operations */\nexport interface DiffStats {\n addedLines?: number;\n deletedLines?: number;\n totalLines?: number;\n}\n\n/** Structured tool presentation */\nexport interface ToolPresentation {\n kind: ToolKind;\n label: string;\n title: string;\n subtitle?: string;\n details?: string;\n files?: string[];\n /** File path for single-file operations */\n filePath?: string;\n /** Diff statistics for edit/write operations */\n diffStats?: DiffStats;\n command?: string;\n /** Command description from bash tool */\n commandDescription?: string;\n query?: string;\n /** Search pattern for grep/glob */\n pattern?: string;\n /** Search path */\n searchPath?: string;\n engine?: string;\n severity: ToolSeverity;\n phase: 'use' | 'result';\n raw: { content: string; metadata?: Record };\n}\n\n/** Timeline item types */\nexport type TimelineItem =\n | {\n kind: 'user_prompt';\n id: string;\n requestId?: string;\n createdAt: string;\n messageId: string;\n text: string;\n attachments: AttachmentMetadata[];\n }\n | {\n kind: 'assistant_text';\n id: string;\n requestId?: string;\n createdAt: string;\n messageId: string;\n text: string;\n isStreaming: boolean;\n }\n | {\n kind: 'tool_use';\n id: string;\n requestId?: string;\n createdAt: string;\n messageId: string;\n tool: ToolPresentation;\n isStreaming: boolean;\n }\n | {\n kind: 'tool_result';\n id: string;\n requestId?: string;\n createdAt: string;\n messageId: string;\n tool: ToolPresentation;\n isError: boolean;\n }\n | {\n kind: 'status';\n id: string;\n requestId?: string;\n createdAt: string;\n status: string;\n text?: string;\n };\n\n/** Client metadata for web editor apply messages */\nexport interface WebEditorApplyMeta {\n kind: 'web_editor_apply_batch' | 'web_editor_apply_single';\n pageUrl?: string;\n elementCount?: number;\n elementLabels?: string[];\n}\n\n/** Thread header data for special message types */\nexport interface ThreadHeader {\n /** Display text (compact representation) */\n displayText?: string;\n /** Full prompt content for hover display */\n fullContent: string;\n /** Web editor apply metadata */\n webEditorApply?: WebEditorApplyMeta;\n}\n\n/** A grouped conversation thread */\nexport interface AgentThread {\n id: string;\n requestId?: string;\n title: string;\n createdAt: string;\n state: AgentThreadState;\n items: TimelineItem[];\n /** Attachments from the user prompt (for display in thread header) */\n attachments: AttachmentMetadata[];\n /** Thread header data for special message rendering */\n header?: ThreadHeader;\n}\n\n/** Options for useAgentThreads */\nexport interface UseAgentThreadsOptions {\n messages: Ref;\n /** Request lifecycle state (replaces isStreaming for thread state calculation) */\n requestState: Ref;\n currentRequestId: Ref;\n}\n\n/**\n * Normalize a string for comparison\n */\nfunction normalize(s: string | undefined): string {\n return (s ?? '').toLowerCase().trim();\n}\n\n/**\n * Get first string from multiple candidates\n */\nfunction firstString(...args: unknown[]): string | undefined {\n for (const arg of args) {\n if (typeof arg === 'string' && arg.trim()) {\n return arg.trim();\n }\n }\n return undefined;\n}\n\n/**\n * Extract text after a prefix (e.g., \"Running: \")\n */\nfunction extractAfterPrefix(content: string, prefix: string): string | undefined {\n const idx = content.indexOf(prefix);\n if (idx === -1) return undefined;\n return content.slice(idx + prefix.length).trim();\n}\n\n/**\n * Summarize content to one line\n */\nfunction summarizeOneLine(content: string): string {\n const line = content.split('\\n')[0]?.trim() ?? '';\n return line.length > 60 ? line.slice(0, 57) + '...' : line;\n}\n\n/**\n * Title case a string\n */\nfunction titleCase(s: string): string {\n return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();\n}\n\n/**\n * Extract file name from path\n */\nfunction getFileName(filePath: string): string {\n return filePath.split('/').pop() || filePath;\n}\n\n/**\n * Build diff stats from metadata\n */\nfunction buildDiffStats(meta: Record): DiffStats | undefined {\n const addedLines = typeof meta.addedLines === 'number' ? meta.addedLines : undefined;\n const deletedLines = typeof meta.deletedLines === 'number' ? meta.deletedLines : undefined;\n const totalLines = typeof meta.totalLines === 'number' ? meta.totalLines : undefined;\n\n if (addedLines !== undefined || deletedLines !== undefined || totalLines !== undefined) {\n return { addedLines, deletedLines, totalLines };\n }\n return undefined;\n}\n\n/**\n * Present a tool message as ToolPresentation\n */\nfunction presentTool(msg: AgentMessage): ToolPresentation {\n const meta = (msg.metadata ?? {}) as Record;\n const phase = msg.messageType === 'tool_use' ? 'use' : 'result';\n const engine = msg.cliSource;\n\n const toolName =\n firstString(meta.toolName as string, meta.tool_name as string) ??\n (typeof engine === 'string' ? engine : undefined) ??\n 'tool';\n\n const isError =\n meta.is_error === true ||\n meta.isError === true ||\n (typeof msg.content === 'string' && msg.content.trimStart().startsWith('Error:'));\n\n // Extract common metadata fields\n const filePath = firstString(meta.filePath as string);\n const command = firstString(meta.command as string);\n const commandDescription = firstString(meta.commandDescription as string);\n const pattern = firstString(meta.pattern as string);\n const searchPath = firstString(meta.searchPath as string);\n const diffStats = buildDiffStats(meta);\n\n // Rule 1: Plan / TodoWrite\n if (\n meta.planPhase ||\n normalize(toolName) === 'plan' ||\n normalize(toolName) === 'todo_write' ||\n normalize(toolName) === 'todowrite'\n ) {\n const todoCount = typeof meta.todoCount === 'number' ? meta.todoCount : undefined;\n return {\n kind: 'plan',\n label: 'Plan',\n title: todoCount ? `${todoCount} tasks` : summarizeOneLine(msg.content) || 'Plan update',\n details: phase === 'result' ? msg.content : undefined,\n engine,\n severity: isError ? 'error' : 'info',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n }\n\n // Rule 2: Edit tool with file path and diff stats\n if (\n normalize(toolName).includes('edit') ||\n normalize(toolName) === 'apply_patch' ||\n normalize(toolName) === 'patch_file'\n ) {\n const fileName = filePath ? getFileName(filePath) : undefined;\n return {\n kind: 'edit',\n label: 'Edit',\n title: fileName || filePath || 'File',\n filePath,\n diffStats,\n details: phase === 'result' ? msg.content : undefined,\n engine,\n severity: isError ? 'error' : 'success',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n }\n\n // Rule 3: Write/Create tool\n if (normalize(toolName).includes('write') || normalize(toolName) === 'create_file') {\n const fileName = filePath ? getFileName(filePath) : undefined;\n return {\n kind: 'edit',\n label: 'Write',\n title: fileName || filePath || 'File',\n filePath,\n diffStats,\n details: phase === 'result' ? msg.content : undefined,\n engine,\n severity: isError ? 'error' : 'success',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n }\n\n // Rule 4: File summary (Codex file_change -> metadata.files)\n const files = Array.isArray(meta.files)\n ? (meta.files as string[]).filter((x) => typeof x === 'string')\n : [];\n if (files.length > 0) {\n const title = files.length === 1 ? getFileName(files[0]) : `${files.length} files`;\n return {\n kind: 'edit',\n label: 'Edit',\n title,\n subtitle: files.length > 1 ? files.slice(0, 3).map(getFileName).join(', ') : undefined,\n files,\n filePath: files.length === 1 ? files[0] : undefined,\n diffStats,\n details: phase === 'result' ? msg.content : undefined,\n engine,\n severity: isError ? 'error' : 'success',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n }\n\n // Rule 5: Command (Bash/shell)\n if (\n normalize(toolName) === 'bash' ||\n normalize(toolName).includes('shell') ||\n typeof command === 'string' ||\n msg.content.startsWith('Running:') ||\n msg.content.startsWith('Ran:')\n ) {\n const extractedCommand =\n command ??\n extractAfterPrefix(msg.content, 'Running:') ??\n extractAfterPrefix(msg.content, 'Ran:') ??\n undefined;\n\n const details =\n firstString(meta.output as string) ?? (phase === 'result' ? msg.content : undefined);\n\n return {\n kind: 'run',\n label: 'Run',\n title: commandDescription || extractedCommand?.trim() || 'Command',\n subtitle: commandDescription && extractedCommand ? extractedCommand.trim() : undefined,\n command: extractedCommand?.trim(),\n commandDescription,\n details,\n engine,\n severity: isError ? 'error' : phase === 'result' ? 'success' : 'info',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n }\n\n // Rule 6: Grep/Search with pattern\n if (normalize(toolName) === 'grep' || normalize(toolName).includes('search') || pattern) {\n const queryFromContent = extractAfterPrefix(msg.content, 'Searching:');\n const displayPattern = pattern || queryFromContent?.trim();\n return {\n kind: 'grep',\n label: 'Grep',\n title: displayPattern || 'Search',\n pattern: displayPattern,\n searchPath,\n query: displayPattern,\n details: phase === 'result' ? msg.content : undefined,\n engine,\n severity: isError ? 'error' : 'info',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n }\n\n // Rule 7: Glob with pattern\n if (normalize(toolName) === 'glob' || normalize(toolName) === 'glob_files') {\n return {\n kind: 'grep',\n label: 'Glob',\n title: pattern || 'Pattern search',\n pattern,\n searchPath,\n details: phase === 'result' ? msg.content : undefined,\n engine,\n severity: isError ? 'error' : 'info',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n }\n\n // Rule 8: Read tool\n if (normalize(toolName).includes('read') || filePath) {\n const fileName = filePath ? getFileName(filePath) : undefined;\n return {\n kind: 'read',\n label: 'Read',\n title: fileName || filePath || 'File',\n filePath,\n engine,\n severity: isError ? 'error' : phase === 'result' ? 'success' : 'info',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n }\n\n // Rule 9: Read / Edit by action (fallback for content-based detection)\n const action = firstString(meta.action as string);\n const fileFromContent = extractAfterPrefix(msg.content, 'Operating on:')?.trim();\n const inferredKind =\n action === 'Read'\n ? 'read'\n : action === 'Edited' || action === 'Created' || action === 'Deleted'\n ? 'edit'\n : null;\n\n if (fileFromContent || inferredKind) {\n const kind: ToolKind = inferredKind ?? 'read';\n return {\n kind,\n label: kind === 'read' ? 'Read' : 'Edit',\n title: fileFromContent ? getFileName(fileFromContent) : toolName,\n filePath: fileFromContent,\n diffStats: kind === 'edit' ? diffStats : undefined,\n engine,\n severity: isError ? 'error' : phase === 'result' ? 'success' : 'info',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n }\n\n // Fallback: generic tool\n return {\n kind: 'generic',\n label: titleCase(toolName),\n title: summarizeOneLine(msg.content) || `Using ${toolName}`,\n details: phase === 'result' ? msg.content : undefined,\n engine,\n severity: isError ? 'error' : 'info',\n phase,\n raw: { content: msg.content, metadata: meta },\n };\n}\n\n/**\n * Type guard for AttachmentMetadata.\n * Validates that an unknown value conforms to the AttachmentMetadata interface.\n * Includes semantic validation (non-empty strings, valid numbers).\n */\nfunction isAttachmentMetadata(value: unknown): value is AttachmentMetadata {\n if (!value || typeof value !== 'object') return false;\n const v = value as Record;\n const index = v.index;\n const sizeBytes = v.sizeBytes;\n return (\n v.version === 1 &&\n v.kind === 'image' &&\n typeof v.projectId === 'string' &&\n (v.projectId as string).trim().length > 0 &&\n typeof v.messageId === 'string' &&\n (v.messageId as string).trim().length > 0 &&\n typeof index === 'number' &&\n Number.isInteger(index) &&\n index >= 0 &&\n typeof v.filename === 'string' &&\n (v.filename as string).trim().length > 0 &&\n typeof v.urlPath === 'string' &&\n (v.urlPath as string).trim().length > 0 &&\n typeof v.mimeType === 'string' &&\n (v.mimeType as string).trim().length > 0 &&\n typeof sizeBytes === 'number' &&\n Number.isFinite(sizeBytes) &&\n sizeBytes >= 0 &&\n typeof v.originalName === 'string' &&\n (v.originalName as string).trim().length > 0 &&\n typeof v.createdAt === 'string' &&\n (v.createdAt as string).trim().length > 0\n );\n}\n\n/**\n * Extract validated attachments from a message's metadata.\n * Returns sorted by index for consistent display order.\n */\nfunction getMessageAttachments(msg: AgentMessage): AttachmentMetadata[] {\n const meta = (msg.metadata ?? {}) as AgentMessageAttachmentMetadata;\n const attachments = meta.attachments;\n if (!Array.isArray(attachments)) return [];\n return attachments.filter(isAttachmentMetadata).sort((a, b) => a.index - b.index);\n}\n\n/**\n * Map a message to a timeline item\n */\nfunction mapMessageToTimelineItem(msg: AgentMessage): TimelineItem | null {\n const createdAt = msg.createdAt;\n const requestId = msg.requestId?.trim() || undefined;\n\n // User chat messages are displayed in thread header (title + attachments),\n // so we don't create timeline items for them to avoid duplicate display.\n if (msg.role === 'user' && msg.messageType === 'chat') {\n return null;\n }\n\n if (msg.role === 'assistant' && msg.messageType === 'chat') {\n return {\n kind: 'assistant_text',\n id: msg.id,\n requestId,\n createdAt,\n messageId: msg.id,\n text: msg.content,\n isStreaming: msg.isStreaming === true && !msg.isFinal,\n };\n }\n\n if (msg.role === 'tool' && msg.messageType === 'tool_use') {\n return {\n kind: 'tool_use',\n id: msg.id,\n requestId,\n createdAt,\n messageId: msg.id,\n tool: presentTool(msg),\n isStreaming: msg.isStreaming === true && !msg.isFinal,\n };\n }\n\n if (msg.role === 'tool' && msg.messageType === 'tool_result') {\n const tool = presentTool(msg);\n return {\n kind: 'tool_result',\n id: msg.id,\n requestId,\n createdAt,\n messageId: msg.id,\n tool,\n isError: tool.severity === 'error',\n };\n }\n\n // Status messages\n if (msg.messageType === 'status' || msg.role === 'system') {\n return {\n kind: 'status',\n id: `status:${requestId ?? 'legacy'}:${msg.id}`,\n requestId,\n createdAt,\n status: 'ready',\n text: msg.content,\n };\n }\n\n return null;\n}\n\n/**\n * Build threads from messages\n */\nfunction buildThreads(\n messages: AgentMessage[],\n requestState: RequestState,\n currentRequestId: string | null,\n): AgentThread[] {\n // Sort messages by createdAt\n const sortedMessages = [...messages].sort((a, b) => a.createdAt.localeCompare(b.createdAt));\n\n // Group messages by requestId or legacy grouping\n let legacyCounter = 0;\n let currentLegacyKey: string | null = null;\n\n const groups = new Map<\n string,\n {\n key: string;\n requestId?: string;\n firstAt: string;\n title?: string;\n items: TimelineItem[];\n attachments: AttachmentMetadata[];\n /** Thread header for special message types */\n header?: ThreadHeader;\n }\n >();\n\n function ensureGroup(key: string, requestId: string | undefined, createdAt: string) {\n if (!groups.has(key)) {\n groups.set(key, { key, requestId, firstAt: createdAt, items: [], attachments: [] });\n }\n return groups.get(key)!;\n }\n\n for (const msg of sortedMessages) {\n const rid = msg.requestId?.trim() || undefined;\n\n // Determine group key\n let key: string;\n if (rid) {\n key = `rid:${rid}`;\n } else {\n if (msg.role === 'user') {\n currentLegacyKey = `legacy:${legacyCounter++}`;\n }\n key = currentLegacyKey ?? 'legacy:orphan';\n }\n\n const group = ensureGroup(key, rid, msg.createdAt);\n\n // Title, attachments, and header: first user chat message in group wins\n if (!group.title && msg.role === 'user' && msg.messageType === 'chat') {\n const fullContent = msg.content.trim();\n const attachments = getMessageAttachments(msg);\n const meta = (msg.metadata ?? {}) as Record;\n\n // Extract client metadata for special message types (with runtime validation)\n const rawClientMeta = meta.clientMeta;\n const rawDisplayText = meta.displayText;\n\n // Validate clientMeta structure\n const clientMeta: WebEditorApplyMeta | undefined =\n rawClientMeta &&\n typeof rawClientMeta === 'object' &&\n 'kind' in rawClientMeta &&\n typeof (rawClientMeta as Record).kind === 'string' &&\n ((rawClientMeta as Record).kind === 'web_editor_apply_batch' ||\n (rawClientMeta as Record).kind === 'web_editor_apply_single')\n ? (rawClientMeta as WebEditorApplyMeta)\n : undefined;\n\n const displayText = typeof rawDisplayText === 'string' ? rawDisplayText : undefined;\n\n // Store attachments for thread header display\n if (attachments.length > 0) {\n group.attachments = attachments;\n }\n\n // Build thread header for special message types\n if (clientMeta?.kind?.startsWith('web_editor_apply')) {\n group.header = {\n displayText: displayText || `Apply ${clientMeta.elementCount ?? 0} changes`,\n fullContent,\n webEditorApply: clientMeta,\n };\n // Use display text as title for web editor apply messages\n group.title = displayText || `Apply ${clientMeta.elementCount ?? 0} changes`;\n } else if (fullContent) {\n group.title = fullContent;\n } else {\n // Image-only message - use attachment count as title\n group.title =\n attachments.length > 0\n ? `Sent ${attachments.length} image${attachments.length === 1 ? '' : 's'}`\n : 'Untitled request';\n }\n\n group.firstAt = msg.createdAt;\n }\n\n // Map message to timeline item\n const item = mapMessageToTimelineItem(msg);\n if (item) group.items.push(item);\n\n // Update earliest timestamp\n if (msg.createdAt < group.firstAt) group.firstAt = msg.createdAt;\n }\n\n // Convert groups to threads\n const threads: AgentThread[] = [];\n\n for (const g of groups.values()) {\n const requestId = g.requestId;\n\n // Determine thread state based on requestState (not isStreaming)\n // This ensures the thread shows as running even during tool execution\n const isActiveRequest =\n requestState === 'starting' || requestState === 'ready' || requestState === 'running';\n\n let state: AgentThreadState = 'completed';\n if (isActiveRequest && currentRequestId && requestId === currentRequestId) {\n // Map requestState to thread state\n state = requestState === 'running' ? 'running' : 'starting';\n } else if (g.items.some((item) => item.kind === 'status')) {\n state = 'idle';\n }\n\n // Sort items by createdAt\n const items = [...g.items].sort((a, b) => a.createdAt.localeCompare(b.createdAt));\n\n // Add status item for active requests\n // Use stable ID without Date.now() to prevent component remount on each render\n if (state === 'running' || state === 'starting') {\n const statusText = state === 'running' ? 'Working...' : 'Starting...';\n items.push({\n kind: 'status',\n id: `status:streaming:${requestId ?? 'current'}`,\n requestId,\n createdAt: new Date().toISOString(),\n status: state,\n text: statusText,\n });\n }\n\n threads.push({\n id: g.key,\n requestId,\n title: g.title ?? 'Untitled request',\n createdAt: g.firstAt,\n state,\n items,\n attachments: g.attachments,\n header: g.header,\n });\n }\n\n // Sort threads by createdAt\n return threads.sort((a, b) => a.createdAt.localeCompare(b.createdAt));\n}\n\n/**\n * Composable for managing agent threads\n */\nexport function useAgentThreads(options: UseAgentThreadsOptions) {\n const threads = computed(() => {\n return buildThreads(\n options.messages.value,\n options.requestState.value,\n options.currentRequestId.value,\n );\n });\n\n return {\n threads,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useAttachments.ts", "content": "/**\n * Composable for managing file attachments.\n * Handles file selection, drag-drop, paste, conversion, preview, and removal.\n */\nimport { ref, computed } from 'vue';\nimport type { AgentAttachment } from 'chrome-mcp-shared';\n\nconst MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB\nconst MAX_ATTACHMENTS = 10; // Maximum number of attachments\n\n// Allowed image MIME types (exclude SVG for security)\nconst ALLOWED_IMAGE_TYPES = new Set([\n 'image/png',\n 'image/jpeg',\n 'image/jpg',\n 'image/gif',\n 'image/webp',\n]);\n\n/**\n * Extended attachment type with preview URL support.\n */\nexport interface AttachmentWithPreview extends AgentAttachment {\n /** Data URL for image preview (data:xxx;base64,...) */\n previewUrl?: string;\n}\n\nexport function useAttachments() {\n const attachments = ref([]);\n const fileInputRef = ref(null);\n const error = ref(null);\n const isDragOver = ref(false);\n\n // Computed: check if we have any image attachments\n const hasImages = computed(() => attachments.value.some((a) => a.type === 'image'));\n\n // Computed: check if we can add more attachments\n const canAddMore = computed(() => attachments.value.length < MAX_ATTACHMENTS);\n\n /**\n * Open file picker for image selection.\n */\n function openFilePicker(): void {\n fileInputRef.value?.click();\n }\n\n /**\n * Convert file to base64 string.\n */\n function fileToBase64(file: File): Promise {\n return new Promise((resolve, reject) => {\n const reader = new FileReader();\n reader.onload = () => {\n const result = reader.result as string;\n // Remove data:xxx;base64, prefix\n const base64 = result.split(',')[1];\n resolve(base64);\n };\n reader.onerror = () => reject(reader.error);\n reader.readAsDataURL(file);\n });\n }\n\n /**\n * Generate preview URL for image attachments.\n */\n function getPreviewUrl(attachment: AttachmentWithPreview): string {\n if (attachment.previewUrl) {\n return attachment.previewUrl;\n }\n // Generate data URL from base64\n return `data:${attachment.mimeType};base64,${attachment.dataBase64}`;\n }\n\n /**\n * Process files and add them as attachments.\n * This is the core method used by file input, drag-drop, and paste handlers.\n */\n async function handleFiles(files: File[]): Promise {\n error.value = null;\n\n // Filter to only allowed image types (exclude SVG for security)\n const imageFiles = files.filter((file) => ALLOWED_IMAGE_TYPES.has(file.type));\n if (imageFiles.length === 0) {\n error.value = 'Only PNG, JPEG, GIF, and WebP images are supported.';\n return;\n }\n\n // Check attachment limit\n const remaining = MAX_ATTACHMENTS - attachments.value.length;\n if (remaining <= 0) {\n error.value = `Maximum ${MAX_ATTACHMENTS} attachments allowed.`;\n return;\n }\n\n const filesToProcess = imageFiles.slice(0, remaining);\n if (filesToProcess.length < imageFiles.length) {\n error.value = `Only ${remaining} more attachment(s) allowed. Some files were skipped.`;\n }\n\n for (const file of filesToProcess) {\n // Validate file size\n if (file.size > MAX_FILE_SIZE) {\n error.value = `File \"${file.name}\" is too large. Maximum size is 10MB.`;\n continue;\n }\n\n try {\n const base64 = await fileToBase64(file);\n const previewUrl = `data:${file.type};base64,${base64}`;\n\n attachments.value.push({\n type: 'image',\n name: file.name,\n mimeType: file.type || 'image/png',\n dataBase64: base64,\n previewUrl,\n });\n } catch (err) {\n console.error('Failed to read file:', err);\n error.value = `Failed to read file \"${file.name}\".`;\n }\n }\n }\n\n /**\n * Handle file selection from input element.\n */\n async function handleFileSelect(event: Event): Promise {\n const input = event.target as HTMLInputElement;\n const files = input.files;\n if (!files || files.length === 0) return;\n\n await handleFiles(Array.from(files));\n\n // Clear input to allow selecting the same file again\n input.value = '';\n }\n\n /**\n * Handle drag over event - update visual state.\n */\n function handleDragOver(event: DragEvent): void {\n event.preventDefault();\n event.stopPropagation();\n isDragOver.value = true;\n }\n\n /**\n * Handle drag leave event - reset visual state.\n */\n function handleDragLeave(event: DragEvent): void {\n event.preventDefault();\n event.stopPropagation();\n isDragOver.value = false;\n }\n\n /**\n * Handle drop event - process dropped files.\n */\n async function handleDrop(event: DragEvent): Promise {\n event.preventDefault();\n event.stopPropagation();\n isDragOver.value = false;\n\n const files = event.dataTransfer?.files;\n if (!files || files.length === 0) return;\n\n await handleFiles(Array.from(files));\n }\n\n /**\n * Handle paste event - extract and process pasted images.\n */\n async function handlePaste(event: ClipboardEvent): Promise {\n const items = event.clipboardData?.items;\n if (!items) return;\n\n const imageFiles: File[] = [];\n for (const item of items) {\n // Only allow specific image types (exclude SVG for security)\n if (ALLOWED_IMAGE_TYPES.has(item.type)) {\n const file = item.getAsFile();\n if (file) {\n // Generate a name for pasted images (they don't have one)\n const ext = item.type.split('/')[1] || 'png';\n const namedFile = new File([file], `pasted-image-${Date.now()}.${ext}`, {\n type: file.type,\n });\n imageFiles.push(namedFile);\n }\n }\n }\n\n if (imageFiles.length > 0) {\n // Prevent default paste behavior for images\n event.preventDefault();\n await handleFiles(imageFiles);\n }\n // Let text paste through normally\n }\n\n /**\n * Remove attachment by index.\n */\n function removeAttachment(index: number): void {\n attachments.value.splice(index, 1);\n error.value = null;\n }\n\n /**\n * Clear all attachments.\n */\n function clearAttachments(): void {\n attachments.value = [];\n error.value = null;\n }\n\n /**\n * Get attachments for sending (strips preview URLs).\n */\n function getAttachments(): AgentAttachment[] | undefined {\n if (attachments.value.length === 0) return undefined;\n\n return attachments.value.map(({ type, name, mimeType, dataBase64 }) => ({\n type,\n name,\n mimeType,\n dataBase64,\n }));\n }\n\n return {\n // State\n attachments,\n fileInputRef,\n error,\n isDragOver,\n\n // Computed\n hasImages,\n canAddMore,\n\n // Methods\n openFilePicker,\n handleFileSelect,\n handleFiles,\n handleDragOver,\n handleDragLeave,\n handleDrop,\n handlePaste,\n removeAttachment,\n clearAttachments,\n getAttachments,\n getPreviewUrl,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useFakeCaret.ts", "content": "/**\n * Composable for rendering a \"fake\" caret overlay on top of a textarea.\n *\n * Implementation notes:\n * - We do NOT intercept input; we only compute caret coordinates.\n * - A hidden \"mirror\" element is used to measure caret position reliably with wrapping.\n * - The actual textarea input/IME/selection behavior is preserved.\n * - When calculation is unreliable (IME/selection/error), we fall back to native caret.\n */\nimport {\n computed,\n onUnmounted,\n ref,\n watch,\n type CSSProperties,\n type ComputedRef,\n type Ref,\n} from 'vue';\n\n// =============================================================================\n// Types\n// =============================================================================\n\nexport interface FakeCaretTrailPoint {\n x: number;\n y: number;\n alpha: number;\n}\n\nexport interface UseFakeCaretOptions {\n /** Reference to the textarea element */\n textareaRef: Ref;\n /**\n * Feature flag for enabling the fake caret.\n * When false, the composable will report showFakeCaret=false\n * and the caller should display the native caret.\n */\n enabled?: Ref;\n}\n\nexport interface UseFakeCaretReturn {\n /** Style for the overlay container (position: absolute, inset: 0) */\n overlayStyle: ComputedRef;\n /** Whether to show the fake caret (false when degraded) */\n showFakeCaret: ComputedRef;\n /** Current X position of caret (animated) */\n caretX: Ref;\n /** Current Y position of caret (animated) */\n caretY: Ref;\n /** Trail points for comet tail effect */\n trail: Ref;\n /** Manually trigger position update */\n updatePosition: () => void;\n}\n\n// =============================================================================\n// Constants\n// =============================================================================\n\nconst MAX_TRAIL_POINTS = 24;\nconst TRAIL_DECAY = 0.86;\nconst TRAIL_MIN_ALPHA = 0.06;\nconst TRAIL_MIN_DISTANCE_PX = 0.35;\nconst SMOOTHING = 0.35;\nconst SNAP_DISTANCE_PX = 0.2;\n\n// =============================================================================\n// Helpers\n// =============================================================================\n\nfunction isFiniteNumber(v: unknown): v is number {\n return typeof v === 'number' && Number.isFinite(v);\n}\n\nfunction clamp(v: number, min: number, max: number): number {\n return Math.min(max, Math.max(min, v));\n}\n\n// =============================================================================\n// Main Composable\n// =============================================================================\n\nexport function useFakeCaret(options: UseFakeCaretOptions): UseFakeCaretReturn {\n // Default to disabled (opt-in) for safer rollout\n const enabled = options.enabled ?? ref(false);\n\n // Position state (animated values)\n const caretX = ref(0);\n const caretY = ref(0);\n const trail = ref([]);\n\n // Internal state\n const isFocused = ref(false);\n const isComposing = ref(false);\n const hasSelection = ref(false);\n const hasValidMeasurement = ref(false);\n const prefersReducedMotion = ref(false);\n\n // Target position (raw measurement)\n let targetX = 0;\n let targetY = 0;\n\n // Animation state\n let scheduled = false;\n let rafId: number | null = null;\n\n // Mirror element for measurement\n let mirrorEl: HTMLDivElement | null = null;\n let lastMirrorKey = '';\n\n // Resize observer\n let resizeObserver: ResizeObserver | null = null;\n\n // Trail tracking\n let lastTrailX = 0;\n let lastTrailY = 0;\n\n // Disposed flag to prevent operations after unmount\n let disposed = false;\n\n // ---------------------------------------------------------------------------\n // Computed Properties\n // ---------------------------------------------------------------------------\n\n const overlayStyle = computed(() => ({\n position: 'absolute',\n inset: 0,\n pointerEvents: 'none',\n overflow: 'hidden',\n }));\n\n const showFakeCaret = computed(() => {\n if (!enabled.value) return false;\n const el = options.textareaRef.value;\n if (!el) return false;\n if (!isFocused.value) return false;\n if (isComposing.value) return false;\n if (hasSelection.value) return false;\n return hasValidMeasurement.value;\n });\n\n // ---------------------------------------------------------------------------\n // Mirror Element Management\n // ---------------------------------------------------------------------------\n\n function ensureMirror(): HTMLDivElement | null {\n if (disposed) return null;\n if (mirrorEl) return mirrorEl;\n if (typeof document === 'undefined' || !document.body) return null;\n\n const el = document.createElement('div');\n el.setAttribute('data-ac-fake-caret-mirror', 'true');\n el.style.position = 'fixed';\n el.style.top = '0';\n el.style.left = '-10000px';\n el.style.visibility = 'hidden';\n el.style.pointerEvents = 'none';\n el.style.whiteSpace = 'pre-wrap';\n el.style.wordBreak = 'break-word';\n el.style.overflowWrap = 'break-word';\n el.style.overflow = 'auto';\n el.style.contain = 'layout style paint';\n el.style.border = '0';\n el.style.background = 'transparent';\n\n document.body.appendChild(el);\n mirrorEl = el;\n return mirrorEl;\n }\n\n function syncMirrorStyle(textarea: HTMLTextAreaElement, mirror: HTMLDivElement): void {\n const cs = window.getComputedStyle(textarea);\n\n // clientWidth includes padding but excludes scrollbar\n const width = `${textarea.clientWidth}px`;\n const height = `${textarea.clientHeight}px`;\n const tabSize = cs.getPropertyValue('tab-size');\n\n // Build cache key to avoid unnecessary style updates\n const key = [\n width,\n height,\n cs.font,\n cs.padding,\n cs.letterSpacing,\n cs.lineHeight,\n cs.textTransform,\n cs.textIndent,\n cs.textAlign,\n cs.direction,\n tabSize,\n ].join('|');\n\n if (key === lastMirrorKey) return;\n lastMirrorKey = key;\n\n mirror.style.boxSizing = 'border-box';\n mirror.style.width = width;\n mirror.style.height = height;\n mirror.style.padding = cs.padding;\n mirror.style.font = cs.font;\n mirror.style.letterSpacing = cs.letterSpacing;\n mirror.style.lineHeight = cs.lineHeight;\n mirror.style.textTransform = cs.textTransform;\n mirror.style.textIndent = cs.textIndent;\n mirror.style.textAlign = cs.textAlign;\n mirror.style.direction = cs.direction;\n\n if (tabSize) {\n mirror.style.setProperty('tab-size', tabSize);\n }\n }\n\n // ---------------------------------------------------------------------------\n // Caret Position Measurement\n // ---------------------------------------------------------------------------\n\n function measureCaret(textarea: HTMLTextAreaElement): { x: number; y: number } | null {\n const start = textarea.selectionStart;\n const end = textarea.selectionEnd;\n\n if (!isFiniteNumber(start) || !isFiniteNumber(end)) {\n hasSelection.value = false;\n return null;\n }\n\n hasSelection.value = start !== end;\n if (hasSelection.value) return null;\n if (isComposing.value) return null;\n if (textarea.clientWidth <= 0 || textarea.clientHeight <= 0) return null;\n\n const mirror = ensureMirror();\n if (!mirror) return null;\n\n syncMirrorStyle(textarea, mirror);\n\n // Keep mirror scroll in sync\n mirror.scrollTop = textarea.scrollTop;\n mirror.scrollLeft = textarea.scrollLeft;\n\n // Build mirror DOM: [beforeText][marker]\n mirror.innerHTML = '';\n const beforeText = textarea.value.slice(0, start);\n mirror.appendChild(document.createTextNode(beforeText));\n\n const marker = document.createElement('span');\n marker.textContent = '\\u200b'; // Zero-width space\n marker.style.display = 'inline-block';\n marker.style.width = '1px';\n marker.style.height = '1em';\n mirror.appendChild(marker);\n\n const markerRect = marker.getBoundingClientRect();\n const mirrorRect = mirror.getBoundingClientRect();\n\n const x = markerRect.left - mirrorRect.left;\n const y = markerRect.top - mirrorRect.top;\n\n if (!isFiniteNumber(x) || !isFiniteNumber(y)) return null;\n\n // Clamp to textarea viewport\n const clampedX = clamp(x, 0, textarea.clientWidth + 2);\n const clampedY = clamp(y, 0, textarea.clientHeight + 2);\n\n // If wildly off, treat as invalid\n if (Math.abs(clampedX - x) > 20 || Math.abs(clampedY - y) > 20) {\n return null;\n }\n\n return { x: clampedX, y: clampedY };\n }\n\n // ---------------------------------------------------------------------------\n // Position Updates\n // ---------------------------------------------------------------------------\n\n function applyTarget(x: number, y: number): void {\n const positionChanged = targetX !== x || targetY !== y;\n targetX = x;\n targetY = y;\n\n // Skip animation if reduced motion preferred\n if (prefersReducedMotion.value) {\n caretX.value = x;\n caretY.value = y;\n trail.value = [];\n lastTrailX = x;\n lastTrailY = y;\n return;\n }\n\n // Restart RAF if position changed (may have been stopped when idle)\n if (positionChanged && showFakeCaret.value) {\n startLoop();\n }\n }\n\n function updateNow(): void {\n const textarea = options.textareaRef.value;\n if (!textarea) {\n hasValidMeasurement.value = false;\n return;\n }\n\n // Only measure when we intend to show the fake caret\n if (!enabled.value || !isFocused.value || isComposing.value) {\n hasValidMeasurement.value = false;\n return;\n }\n\n const pos = measureCaret(textarea);\n if (!pos) {\n hasValidMeasurement.value = false;\n return;\n }\n\n hasValidMeasurement.value = true;\n applyTarget(pos.x, pos.y);\n }\n\n function scheduleUpdate(): void {\n if (disposed) return;\n if (scheduled) return;\n scheduled = true;\n requestAnimationFrame(() => {\n scheduled = false;\n if (!disposed) {\n updateNow();\n }\n });\n }\n\n function updatePosition(): void {\n scheduleUpdate();\n }\n\n // ---------------------------------------------------------------------------\n // Animation Loop\n // ---------------------------------------------------------------------------\n\n function tick(): void {\n if (!showFakeCaret.value) return;\n if (prefersReducedMotion.value) return;\n\n // Smooth caret position\n const dx = targetX - caretX.value;\n const dy = targetY - caretY.value;\n\n // Check if caret has snapped to target\n const isSnapped = Math.abs(dx) < SNAP_DISTANCE_PX && Math.abs(dy) < SNAP_DISTANCE_PX;\n\n if (isSnapped) {\n caretX.value = targetX;\n caretY.value = targetY;\n } else {\n caretX.value = caretX.value + dx * SMOOTHING;\n caretY.value = caretY.value + dy * SMOOTHING;\n }\n\n // Update trail (comet tail effect)\n const currentTrail = trail.value;\n const nextTrail: FakeCaretTrailPoint[] = [];\n\n // Fade existing points\n for (const p of currentTrail) {\n const alpha = p.alpha * TRAIL_DECAY;\n if (alpha >= TRAIL_MIN_ALPHA) {\n nextTrail.push({ ...p, alpha });\n }\n }\n\n // Add new point if moved enough\n const moved =\n Math.abs(caretX.value - lastTrailX) + Math.abs(caretY.value - lastTrailY) >\n TRAIL_MIN_DISTANCE_PX;\n\n if (moved) {\n nextTrail.push({ x: caretX.value, y: caretY.value, alpha: 1 });\n lastTrailX = caretX.value;\n lastTrailY = caretY.value;\n }\n\n // Only update trail ref if content changed (avoid triggering watchers)\n // Note: must compare alpha too, otherwise fade animation won't work\n const trailChanged =\n nextTrail.length !== currentTrail.length ||\n nextTrail.some(\n (p, i) =>\n p.x !== currentTrail[i]?.x ||\n p.y !== currentTrail[i]?.y ||\n Math.abs(p.alpha - (currentTrail[i]?.alpha ?? 0)) > 0.001,\n );\n\n if (trailChanged) {\n // Keep only the last N points\n if (nextTrail.length > MAX_TRAIL_POINTS) {\n trail.value = nextTrail.slice(nextTrail.length - MAX_TRAIL_POINTS);\n } else {\n trail.value = nextTrail;\n }\n }\n\n // Stop RAF when idle: snapped to target and trail has fully faded\n if (isSnapped && nextTrail.length === 0) {\n stopLoop();\n }\n }\n\n function startLoop(): void {\n if (disposed) return;\n if (rafId !== null) return;\n const loop = () => {\n if (disposed) {\n rafId = null;\n return;\n }\n rafId = requestAnimationFrame(loop);\n tick();\n };\n rafId = requestAnimationFrame(loop);\n }\n\n function stopLoop(): void {\n if (rafId !== null) {\n cancelAnimationFrame(rafId);\n rafId = null;\n }\n }\n\n // ---------------------------------------------------------------------------\n // Reduced Motion Preference\n // ---------------------------------------------------------------------------\n\n let media: MediaQueryList | null = null;\n let onMediaChange: ((e: MediaQueryListEvent) => void) | null = null;\n\n if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {\n media = window.matchMedia('(prefers-reduced-motion: reduce)');\n prefersReducedMotion.value = media.matches;\n onMediaChange = (e: MediaQueryListEvent) => {\n prefersReducedMotion.value = e.matches;\n trail.value = [];\n scheduleUpdate();\n };\n try {\n media.addEventListener('change', onMediaChange);\n } catch {\n // Safari < 14 fallback\n media.addListener(onMediaChange as EventListener);\n }\n }\n\n // ---------------------------------------------------------------------------\n // Textarea Event Binding\n // ---------------------------------------------------------------------------\n\n watch(\n () => options.textareaRef.value,\n (el, _prev, onCleanup) => {\n if (!el) return;\n\n const handleFocus = () => {\n isFocused.value = true;\n scheduleUpdate();\n };\n const handleBlur = () => {\n isFocused.value = false;\n hasValidMeasurement.value = false;\n stopLoop();\n trail.value = [];\n };\n const handleInput = () => scheduleUpdate();\n const handleKey = () => scheduleUpdate();\n const handleMouse = () => scheduleUpdate();\n const handleScroll = () => scheduleUpdate();\n const handleSelect = () => scheduleUpdate();\n const handleCompositionStart = () => {\n isComposing.value = true;\n scheduleUpdate();\n };\n const handleCompositionEnd = () => {\n isComposing.value = false;\n scheduleUpdate();\n };\n\n el.addEventListener('focus', handleFocus);\n el.addEventListener('blur', handleBlur);\n el.addEventListener('input', handleInput);\n el.addEventListener('keydown', handleKey);\n el.addEventListener('keyup', handleKey);\n el.addEventListener('click', handleMouse);\n el.addEventListener('mouseup', handleMouse);\n el.addEventListener('scroll', handleScroll, { passive: true });\n el.addEventListener('select', handleSelect);\n el.addEventListener('compositionstart', handleCompositionStart);\n el.addEventListener('compositionend', handleCompositionEnd);\n\n // Initialize focus state\n isFocused.value = typeof document !== 'undefined' && document.activeElement === el;\n\n // Observe size changes\n if (typeof ResizeObserver !== 'undefined') {\n resizeObserver?.disconnect();\n resizeObserver = new ResizeObserver(() => scheduleUpdate());\n resizeObserver.observe(el);\n }\n\n // Initial measurement\n scheduleUpdate();\n\n onCleanup(() => {\n el.removeEventListener('focus', handleFocus);\n el.removeEventListener('blur', handleBlur);\n el.removeEventListener('input', handleInput);\n el.removeEventListener('keydown', handleKey);\n el.removeEventListener('keyup', handleKey);\n el.removeEventListener('click', handleMouse);\n el.removeEventListener('mouseup', handleMouse);\n el.removeEventListener('scroll', handleScroll);\n el.removeEventListener('select', handleSelect);\n el.removeEventListener('compositionstart', handleCompositionStart);\n el.removeEventListener('compositionend', handleCompositionEnd);\n resizeObserver?.disconnect();\n resizeObserver = null;\n });\n },\n { immediate: true },\n );\n\n // ---------------------------------------------------------------------------\n // Watchers for State Changes\n // ---------------------------------------------------------------------------\n\n watch(\n prefersReducedMotion,\n (reduced) => {\n if (reduced) {\n stopLoop();\n trail.value = [];\n scheduleUpdate();\n return;\n }\n if (showFakeCaret.value) {\n startLoop();\n }\n },\n { immediate: true },\n );\n\n watch(\n showFakeCaret,\n (show) => {\n if (!show) {\n stopLoop();\n trail.value = [];\n return;\n }\n\n // Start animation when showing\n scheduleUpdate();\n if (!prefersReducedMotion.value) {\n startLoop();\n }\n },\n { immediate: true },\n );\n\n watch(\n enabled,\n (v) => {\n if (!v) {\n stopLoop();\n trail.value = [];\n hasValidMeasurement.value = false;\n } else {\n scheduleUpdate();\n }\n },\n { immediate: true },\n );\n\n // ---------------------------------------------------------------------------\n // Cleanup\n // ---------------------------------------------------------------------------\n\n onUnmounted(() => {\n disposed = true;\n stopLoop();\n resizeObserver?.disconnect();\n resizeObserver = null;\n\n if (mirrorEl && mirrorEl.parentNode) {\n mirrorEl.parentNode.removeChild(mirrorEl);\n }\n mirrorEl = null;\n\n if (media && onMediaChange) {\n try {\n media.removeEventListener('change', onMediaChange);\n } catch {\n media.removeListener(onMediaChange as EventListener);\n }\n }\n });\n\n return {\n overlayStyle,\n showFakeCaret,\n caretX,\n caretY,\n trail,\n updatePosition,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useFloatingDrag.ts", "content": "/**\n * Vue composable for floating drag functionality.\n * Wraps the installFloatingDrag utility for use in Vue components.\n */\n\nimport { ref, onMounted, onUnmounted, type Ref } from 'vue';\nimport {\n installFloatingDrag,\n type FloatingPosition,\n} from '@/entrypoints/web-editor-v2/ui/floating-drag';\n\nconst STORAGE_KEY = 'sidepanel_navigator_position';\n\nexport interface UseFloatingDragOptions {\n /** Storage key for position persistence */\n storageKey?: string;\n /** Margin from viewport edges in pixels */\n clampMargin?: number;\n /** Threshold for distinguishing click vs drag (ms) */\n clickThresholdMs?: number;\n /** Movement threshold for drag activation (px) */\n moveThresholdPx?: number;\n /** Default position calculator (called when no saved position exists) */\n getDefaultPosition?: () => FloatingPosition;\n}\n\nexport interface UseFloatingDragReturn {\n /** Current position (reactive) */\n position: Ref;\n /** Whether dragging is in progress */\n isDragging: Ref;\n /** Reset position to default */\n resetToDefault: () => void;\n /** Computed style object for binding */\n positionStyle: Ref<{ left: string; top: string }>;\n}\n\n/**\n * Calculate default position (bottom-right corner with margin)\n */\nfunction getDefaultBottomRightPosition(\n buttonSize: number = 40,\n margin: number = 12,\n): FloatingPosition {\n return {\n left: window.innerWidth - buttonSize - margin,\n top: window.innerHeight - buttonSize - margin,\n };\n}\n\n/**\n * Load position from chrome.storage.local\n */\nasync function loadPosition(storageKey: string): Promise {\n try {\n const result = await chrome.storage.local.get(storageKey);\n const saved = result[storageKey];\n if (\n saved &&\n typeof saved.left === 'number' &&\n typeof saved.top === 'number' &&\n Number.isFinite(saved.left) &&\n Number.isFinite(saved.top)\n ) {\n return saved as FloatingPosition;\n }\n } catch (e) {\n console.warn('Failed to load navigator position:', e);\n }\n return null;\n}\n\n/**\n * Save position to chrome.storage.local\n */\nasync function savePosition(storageKey: string, position: FloatingPosition): Promise {\n try {\n await chrome.storage.local.set({ [storageKey]: position });\n } catch (e) {\n console.warn('Failed to save navigator position:', e);\n }\n}\n\n/**\n * Vue composable for making an element draggable with position persistence.\n */\nexport function useFloatingDrag(\n handleRef: Ref,\n targetRef: Ref,\n options: UseFloatingDragOptions = {},\n): UseFloatingDragReturn {\n const {\n storageKey = STORAGE_KEY,\n clampMargin = 12,\n clickThresholdMs = 150,\n moveThresholdPx = 5,\n getDefaultPosition = () => getDefaultBottomRightPosition(40, clampMargin),\n } = options;\n\n const position = ref(getDefaultPosition());\n const isDragging = ref(false);\n const positionStyle = ref({ left: `${position.value.left}px`, top: `${position.value.top}px` });\n\n let cleanup: (() => void) | null = null;\n\n function updatePositionStyle(): void {\n positionStyle.value = {\n left: `${position.value.left}px`,\n top: `${position.value.top}px`,\n };\n }\n\n function resetToDefault(): void {\n position.value = getDefaultPosition();\n updatePositionStyle();\n savePosition(storageKey, position.value);\n }\n\n async function initPosition(): Promise {\n const saved = await loadPosition(storageKey);\n if (saved) {\n // Validate position is within current viewport\n const maxLeft = window.innerWidth - 40 - clampMargin;\n const maxTop = window.innerHeight - 40 - clampMargin;\n position.value = {\n left: Math.min(Math.max(clampMargin, saved.left), maxLeft),\n top: Math.min(Math.max(clampMargin, saved.top), maxTop),\n };\n } else {\n position.value = getDefaultPosition();\n }\n updatePositionStyle();\n }\n\n onMounted(async () => {\n await initPosition();\n\n // Wait for refs to be available\n await new Promise((resolve) => setTimeout(resolve, 0));\n\n if (!handleRef.value || !targetRef.value) {\n console.warn('useFloatingDrag: handleRef or targetRef is null');\n return;\n }\n\n cleanup = installFloatingDrag({\n handleEl: handleRef.value,\n targetEl: targetRef.value,\n onPositionChange: (pos) => {\n position.value = pos;\n updatePositionStyle();\n savePosition(storageKey, pos);\n },\n clampMargin,\n clickThresholdMs,\n moveThresholdPx,\n });\n\n // Monitor dragging state via data attribute\n const observer = new MutationObserver(() => {\n isDragging.value = handleRef.value?.dataset.dragging === 'true';\n });\n if (handleRef.value) {\n observer.observe(handleRef.value, { attributes: true, attributeFilter: ['data-dragging'] });\n }\n });\n\n onUnmounted(() => {\n cleanup?.();\n });\n\n return {\n position,\n isDragging,\n resetToDefault,\n positionStyle,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useOpenProjectPreference.ts", "content": "/**\n * Composable for managing user preference for opening project directory.\n * Stores the default target (vscode/terminal) in chrome.storage.local.\n */\nimport { ref, type Ref } from 'vue';\nimport type { OpenProjectTarget, OpenProjectResponse } from 'chrome-mcp-shared';\n\n// Storage key for default open target\nconst STORAGE_KEY = 'agent-open-project-default';\n\nexport interface UseOpenProjectPreferenceOptions {\n /**\n * Server port for API calls.\n * Should be provided from useAgentServer.\n */\n getServerPort: () => number | null;\n}\n\nexport interface UseOpenProjectPreference {\n /** Current default target (null if not set) */\n defaultTarget: Ref;\n /** Loading state */\n loading: Ref;\n /** Load default target from storage */\n loadDefaultTarget: () => Promise;\n /** Save default target to storage */\n saveDefaultTarget: (target: OpenProjectTarget) => Promise;\n /** Open project by session ID */\n openBySession: (sessionId: string, target: OpenProjectTarget) => Promise;\n /** Open project by project ID */\n openByProject: (projectId: string, target: OpenProjectTarget) => Promise;\n}\n\nexport function useOpenProjectPreference(\n options: UseOpenProjectPreferenceOptions,\n): UseOpenProjectPreference {\n const defaultTarget = ref(null);\n const loading = ref(false);\n\n /**\n * Load default target from chrome.storage.local.\n */\n async function loadDefaultTarget(): Promise {\n try {\n const result = await chrome.storage.local.get(STORAGE_KEY);\n const stored = result[STORAGE_KEY];\n if (stored === 'vscode' || stored === 'terminal') {\n defaultTarget.value = stored;\n }\n } catch (error) {\n console.error('[OpenProjectPreference] Failed to load default target:', error);\n }\n }\n\n /**\n * Save default target to chrome.storage.local.\n */\n async function saveDefaultTarget(target: OpenProjectTarget): Promise {\n try {\n await chrome.storage.local.set({ [STORAGE_KEY]: target });\n defaultTarget.value = target;\n } catch (error) {\n console.error('[OpenProjectPreference] Failed to save default target:', error);\n }\n }\n\n /**\n * Open project directory by session ID.\n */\n async function openBySession(\n sessionId: string,\n target: OpenProjectTarget,\n ): Promise {\n const port = options.getServerPort();\n if (!port) {\n return { success: false, error: 'Server not connected' };\n }\n\n loading.value = true;\n try {\n const url = `http://127.0.0.1:${port}/agent/sessions/${encodeURIComponent(sessionId)}/open`;\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ target }),\n });\n\n const data = (await response.json()) as OpenProjectResponse;\n return data;\n } catch (error) {\n const message = error instanceof Error ? error.message : String(error);\n return { success: false, error: message };\n } finally {\n loading.value = false;\n }\n }\n\n /**\n * Open project directory by project ID.\n */\n async function openByProject(\n projectId: string,\n target: OpenProjectTarget,\n ): Promise {\n const port = options.getServerPort();\n if (!port) {\n return { success: false, error: 'Server not connected' };\n }\n\n loading.value = true;\n try {\n const url = `http://127.0.0.1:${port}/agent/projects/${encodeURIComponent(projectId)}/open`;\n const response = await fetch(url, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ target }),\n });\n\n const data = (await response.json()) as OpenProjectResponse;\n return data;\n } catch (error) {\n const message = error instanceof Error ? error.message : String(error);\n return { success: false, error: message };\n } finally {\n loading.value = false;\n }\n }\n\n return {\n defaultTarget,\n loading,\n loadDefaultTarget,\n saveDefaultTarget,\n openBySession,\n openByProject,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useRRV3Debugger.ts", "content": "/**\n * @fileoverview RR V3 Debugger Composable\n * @description Debugger state management, wraps all DebuggerCommand operations\n *\n * Responsibilities:\n * - Send all debug commands via rr_v3.debug RPC method\n * - Maintain reactive DebuggerState\n * - Provide consistent error handling and response normalization\n */\n\nimport { computed, onUnmounted, ref, type ComputedRef, type Ref } from 'vue';\n\nimport type {\n DebuggerCommand,\n DebuggerResponse,\n DebuggerState,\n} from '@/entrypoints/background/record-replay-v3/domain/debug';\nimport type { NodeId, RunId } from '@/entrypoints/background/record-replay-v3/domain/ids';\nimport type { JsonObject, JsonValue } from '@/entrypoints/background/record-replay-v3/domain/json';\nimport type { RunEvent } from '@/entrypoints/background/record-replay-v3/domain/events';\n\nimport { useRRV3Rpc, type UseRRV3Rpc } from './useRRV3Rpc';\n\n// ==================== Types ====================\n\n/** Composable configuration */\nexport interface UseRRV3DebuggerOptions {\n /** Shared RPC client instance, creates new if not provided */\n rpc?: UseRRV3Rpc;\n /** Current runId resolver for command defaults */\n getRunId?: () => RunId | null;\n /** State update callback */\n onStateChange?: (state: DebuggerState) => void;\n /** Error callback */\n onError?: (error: string) => void;\n /**\n * Auto-refresh DebuggerState when relevant events are received.\n * Only effective when attached to a run.\n * Events: run.paused, run.resumed, node.started\n */\n autoRefreshOnEvents?: boolean;\n}\n\n/** Composable return type */\nexport interface UseRRV3Debugger {\n /** RPC client instance */\n rpc: UseRRV3Rpc;\n\n // State\n state: Ref;\n lastError: Ref;\n busy: Ref;\n\n // Derived state\n currentRunId: ComputedRef;\n isAttached: ComputedRef;\n isPaused: ComputedRef;\n\n // Connection control\n attach: (runId?: RunId) => Promise;\n detach: (runId?: RunId) => Promise;\n\n // Execution control\n pause: (runId?: RunId) => Promise;\n resume: (runId?: RunId) => Promise;\n stepOver: (runId?: RunId) => Promise;\n\n // Breakpoint management\n setBreakpoints: (nodeIds: NodeId[], runId?: RunId) => Promise;\n addBreakpoint: (nodeId: NodeId, runId?: RunId) => Promise;\n removeBreakpoint: (nodeId: NodeId, runId?: RunId) => Promise;\n\n // State query\n getState: (runId?: RunId) => Promise;\n\n // Variable operations\n getVar: (name: string, runId?: RunId) => Promise;\n setVar: (name: string, value: JsonValue, runId?: RunId) => Promise;\n}\n\n// ==================== Helpers ====================\n\nfunction toErrorMessage(error: unknown): string {\n return error instanceof Error ? error.message : String(error);\n}\n\n/**\n * Validate breakpoint structure\n */\nfunction isValidBreakpoint(value: unknown): boolean {\n if (typeof value !== 'object' || value === null) return false;\n const bp = value as Record;\n return typeof bp.nodeId === 'string' && typeof bp.enabled === 'boolean';\n}\n\n/**\n * Validate DebuggerState structure\n */\nfunction isValidDebuggerState(value: unknown): value is DebuggerState {\n if (typeof value !== 'object' || value === null) return false;\n const obj = value as Record;\n return (\n typeof obj.runId === 'string' &&\n (obj.status === 'attached' || obj.status === 'detached') &&\n (obj.execution === 'running' || obj.execution === 'paused') &&\n Array.isArray(obj.breakpoints) &&\n obj.breakpoints.every(isValidBreakpoint)\n );\n}\n\n/**\n * Normalize RPC response to DebuggerResponse\n */\nfunction normalizeResponse(raw: JsonValue): DebuggerResponse {\n if (typeof raw !== 'object' || raw === null) {\n return { ok: false, error: 'Invalid response format' };\n }\n\n const obj = raw as Record;\n\n if (obj.ok === true) {\n const responseState = obj.state;\n // Validate state if present\n if (responseState !== undefined && !isValidDebuggerState(responseState)) {\n return { ok: false, error: 'Invalid DebuggerState in response' };\n }\n return {\n ok: true,\n state: responseState as DebuggerState | undefined,\n value: obj.value as JsonValue | undefined,\n };\n }\n\n if (obj.ok === false) {\n return {\n ok: false,\n error: typeof obj.error === 'string' ? obj.error : 'Unknown error',\n };\n }\n\n return { ok: false, error: 'Response missing ok field' };\n}\n\n// ==================== Composable ====================\n\n/** Events that trigger state refresh */\nconst STATE_REFRESH_EVENTS = new Set(['run.paused', 'run.resumed', 'node.started']);\n\n/**\n * RR V3 Debugger client\n */\nexport function useRRV3Debugger(options: UseRRV3DebuggerOptions = {}): UseRRV3Debugger {\n // RPC client (use provided or create new)\n const rpc = options.rpc ?? useRRV3Rpc();\n\n // State\n const state = ref(null);\n const lastError = ref(null);\n const busy = ref(false);\n\n // Derived state\n const currentRunId = computed(() => {\n // Prefer external resolver\n const fromGetter = options.getRunId?.();\n if (fromGetter) return fromGetter;\n // Fallback to current state\n return state.value?.runId ?? null;\n });\n\n const isAttached = computed(() => state.value?.status === 'attached');\n const isPaused = computed(() => state.value?.execution === 'paused');\n\n // ==================== Internal Methods ====================\n\n function setError(message: string | null): void {\n lastError.value = message;\n if (message) options.onError?.(message);\n }\n\n function updateState(next?: DebuggerState): void {\n if (!next) return;\n state.value = next;\n options.onStateChange?.(next);\n }\n\n function resolveRunId(explicit?: RunId): RunId | null {\n if (explicit) return explicit;\n return currentRunId.value;\n }\n\n /**\n * Send debug command\n */\n async function send(cmd: DebuggerCommand): Promise {\n busy.value = true;\n try {\n const raw = await rpc.request('rr_v3.debug', cmd as unknown as JsonObject);\n const response = normalizeResponse(raw);\n\n if (response.ok) {\n setError(null);\n if (response.state) {\n updateState(response.state);\n }\n } else {\n setError(response.error);\n }\n\n return response;\n } catch (error) {\n const message = toErrorMessage(error);\n setError(message);\n return { ok: false, error: message };\n } finally {\n busy.value = false;\n }\n }\n\n /**\n * Create error response for missing runId\n */\n function missingRunIdError(commandType: string): DebuggerResponse {\n const message = `${commandType} requires runId`;\n setError(message);\n return { ok: false, error: message };\n }\n\n // ==================== Public Methods ====================\n\n async function attach(runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.attach');\n return send({ type: 'debug.attach', runId: resolved });\n }\n\n async function detach(runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.detach');\n return send({ type: 'debug.detach', runId: resolved });\n }\n\n async function pause(runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.pause');\n return send({ type: 'debug.pause', runId: resolved });\n }\n\n async function resume(runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.resume');\n return send({ type: 'debug.resume', runId: resolved });\n }\n\n async function stepOver(runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.stepOver');\n return send({ type: 'debug.stepOver', runId: resolved });\n }\n\n async function setBreakpoints(nodeIds: NodeId[], runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.setBreakpoints');\n return send({ type: 'debug.setBreakpoints', runId: resolved, nodeIds });\n }\n\n async function addBreakpoint(nodeId: NodeId, runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.addBreakpoint');\n return send({ type: 'debug.addBreakpoint', runId: resolved, nodeId });\n }\n\n async function removeBreakpoint(nodeId: NodeId, runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.removeBreakpoint');\n return send({ type: 'debug.removeBreakpoint', runId: resolved, nodeId });\n }\n\n async function getState(runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.getState');\n return send({ type: 'debug.getState', runId: resolved });\n }\n\n async function getVar(name: string, runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.getVar');\n return send({ type: 'debug.getVar', runId: resolved, name });\n }\n\n async function setVar(name: string, value: JsonValue, runId?: RunId): Promise {\n const resolved = resolveRunId(runId);\n if (!resolved) return missingRunIdError('debug.setVar');\n return send({ type: 'debug.setVar', runId: resolved, name, value });\n }\n\n // ==================== Event Auto-Refresh ====================\n\n // State refresh scheduling (debounced)\n let refreshScheduled = false;\n let refreshTimer: ReturnType | null = null;\n\n /**\n * Schedule a debounced state refresh\n * Uses microtask to coalesce multiple events in the same tick\n */\n function scheduleRefresh(): void {\n if (refreshScheduled) return;\n refreshScheduled = true;\n\n // Clear any existing timer\n if (refreshTimer) {\n clearTimeout(refreshTimer);\n refreshTimer = null;\n }\n\n // Use microtask for same-tick debouncing\n queueMicrotask(async () => {\n refreshScheduled = false;\n // Don't update busy state for auto-refresh to avoid UI flicker\n try {\n const resolved = currentRunId.value;\n if (!resolved || !isAttached.value) return;\n const raw = await rpc.request('rr_v3.debug', {\n type: 'debug.getState',\n runId: resolved,\n } as unknown as JsonObject);\n const response = normalizeResponse(raw);\n if (response.ok && response.state) {\n updateState(response.state);\n }\n } catch {\n // Ignore errors in auto-refresh\n }\n });\n }\n\n /**\n * Handle incoming events for auto-refresh\n */\n function handleEvent(event: RunEvent): void {\n // Only refresh if attached and event is for current run\n if (!isAttached.value) return;\n if (event.runId !== currentRunId.value) return;\n if (!STATE_REFRESH_EVENTS.has(event.type)) return;\n\n scheduleRefresh();\n }\n\n // Setup event listener if autoRefreshOnEvents is enabled\n let unsubscribeEvents: (() => void) | null = null;\n if (options.autoRefreshOnEvents) {\n unsubscribeEvents = rpc.onEvent(handleEvent);\n }\n\n // Cleanup on unmount\n onUnmounted(() => {\n unsubscribeEvents?.();\n if (refreshTimer) {\n clearTimeout(refreshTimer);\n }\n });\n\n return {\n rpc,\n state,\n lastError,\n busy,\n currentRunId,\n isAttached,\n isPaused,\n attach,\n detach,\n pause,\n resume,\n stepOver,\n setBreakpoints,\n addBreakpoint,\n removeBreakpoint,\n getState,\n getVar,\n setVar,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useRRV3Rpc.ts", "content": "/**\n * @fileoverview Re-export shared useRRV3Rpc composable\n * @description This file re-exports the shared composable for backward compatibility\n */\n\nexport {\n useRRV3Rpc,\n type UseRRV3Rpc,\n type UseRRV3RpcOptions,\n type RpcRequestOptions,\n} from '@/entrypoints/shared/composables/useRRV3Rpc';\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useTextareaAutoResize.ts", "content": "/**\n * Composable for textarea auto-resize functionality.\n * Automatically adjusts textarea height based on content while respecting min/max constraints.\n */\nimport { ref, watch, nextTick, onMounted, onUnmounted, type Ref } from 'vue';\n\nexport interface UseTextareaAutoResizeOptions {\n /** Ref to the textarea element */\n textareaRef: Ref;\n /** Ref to the textarea value (for watching changes) */\n value: Ref;\n /** Minimum height in pixels */\n minHeight?: number;\n /** Maximum height in pixels */\n maxHeight?: number;\n}\n\nexport interface UseTextareaAutoResizeReturn {\n /** Current calculated height */\n height: Ref;\n /** Whether content exceeds max height (textarea is overflowing) */\n isOverflowing: Ref;\n /** Manually trigger height recalculation */\n recalculate: () => void;\n}\n\nconst DEFAULT_MIN_HEIGHT = 50;\nconst DEFAULT_MAX_HEIGHT = 200;\n\n/**\n * Composable for auto-resizing textarea based on content.\n *\n * Features:\n * - Automatically adjusts height on input\n * - Respects min/max height constraints\n * - Handles width changes (line wrapping affects height)\n * - Uses requestAnimationFrame for performance\n */\nexport function useTextareaAutoResize(\n options: UseTextareaAutoResizeOptions,\n): UseTextareaAutoResizeReturn {\n const {\n textareaRef,\n value,\n minHeight = DEFAULT_MIN_HEIGHT,\n maxHeight = DEFAULT_MAX_HEIGHT,\n } = options;\n\n const height = ref(minHeight);\n const isOverflowing = ref(false);\n\n let scheduled = false;\n let resizeObserver: ResizeObserver | null = null;\n let lastWidth = 0;\n\n /**\n * Calculate textarea height based on content.\n * Only updates the reactive `height` and `isOverflowing` refs.\n * The actual DOM height is controlled via :style binding in the template.\n */\n function recalculate(): void {\n const el = textareaRef.value;\n if (!el) return;\n\n // Temporarily set height to 'auto' to get accurate scrollHeight\n // Save current height to minimize visual flicker\n const currentHeight = el.style.height;\n el.style.height = 'auto';\n\n const contentHeight = el.scrollHeight;\n const clampedHeight = Math.min(maxHeight, Math.max(minHeight, contentHeight));\n\n // Restore height immediately (the actual height is controlled by Vue binding)\n el.style.height = currentHeight;\n\n // Update reactive state\n height.value = clampedHeight;\n // Add small tolerance (1px) to account for rounding\n isOverflowing.value = contentHeight > maxHeight + 1;\n }\n\n /**\n * Schedule height recalculation using requestAnimationFrame.\n * Batches multiple calls within the same frame for performance.\n */\n function scheduleRecalculate(): void {\n if (scheduled) return;\n scheduled = true;\n requestAnimationFrame(() => {\n scheduled = false;\n recalculate();\n });\n }\n\n // Watch value changes\n watch(\n value,\n async () => {\n await nextTick();\n scheduleRecalculate();\n },\n { flush: 'post' },\n );\n\n // Watch textarea ref changes (in case it's replaced)\n watch(\n textareaRef,\n async (newEl, oldEl) => {\n // Cleanup old observer\n if (resizeObserver && oldEl) {\n resizeObserver.unobserve(oldEl);\n }\n\n if (!newEl) return;\n\n await nextTick();\n scheduleRecalculate();\n\n // Setup new observer for width changes\n if (resizeObserver) {\n lastWidth = newEl.offsetWidth;\n resizeObserver.observe(newEl);\n }\n },\n { immediate: true },\n );\n\n onMounted(() => {\n const el = textareaRef.value;\n if (!el) return;\n\n // Initial calculation\n scheduleRecalculate();\n\n // Setup ResizeObserver for width changes\n // Width changes affect line wrapping, which affects scrollHeight\n if (typeof ResizeObserver !== 'undefined') {\n lastWidth = el.offsetWidth;\n resizeObserver = new ResizeObserver(() => {\n const current = textareaRef.value;\n if (!current) return;\n\n const currentWidth = current.offsetWidth;\n if (currentWidth !== lastWidth) {\n lastWidth = currentWidth;\n scheduleRecalculate();\n }\n });\n resizeObserver.observe(el);\n }\n });\n\n onUnmounted(() => {\n resizeObserver?.disconnect();\n resizeObserver = null;\n });\n\n return {\n height,\n isOverflowing,\n recalculate,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useWebEditorTxState.ts", "content": "/**\n * Composable for managing Web Editor TX (Transaction) state in Sidepanel.\n *\n * Responsibilities:\n * - Listen to WEB_EDITOR_TX_CHANGED messages from background\n * - Persist and recover state from chrome.storage.session\n * - Manage excluded element keys for selective Apply\n * - Provide reactive state for AgentChat chips UI\n *\n * Architecture:\n * - The composable should be initialized ONCE at the AgentChat.vue level\n * - It is then provided via Vue's provide/inject to child components\n * - This prevents duplicate event listener registration\n */\nimport { computed, onMounted, onUnmounted, ref, type InjectionKey } from 'vue';\nimport { BACKGROUND_MESSAGE_TYPES } from '@/common/message-types';\nimport type {\n ElementChangeSummary,\n SelectedElementSummary,\n WebEditorElementKey,\n WebEditorSelectionChangedPayload,\n WebEditorTxChangedPayload,\n WebEditorTxChangeAction,\n} from '@/common/web-editor-types';\n\n// =============================================================================\n// Constants\n// =============================================================================\n\nconst WEB_EDITOR_TX_CHANGED_SESSION_KEY_PREFIX = 'web-editor-v2-tx-changed-';\nconst WEB_EDITOR_EXCLUDED_KEYS_SESSION_KEY_PREFIX = 'web-editor-v2-excluded-keys-';\nconst WEB_EDITOR_SELECTION_SESSION_KEY_PREFIX = 'web-editor-v2-selection-';\n\nconst VALID_TX_ACTIONS = new Set([\n 'push',\n 'merge',\n 'undo',\n 'redo',\n 'clear',\n 'rollback',\n]);\n\n// =============================================================================\n// Internal Helpers\n// =============================================================================\n\nfunction isValidTabId(value: unknown): value is number {\n return typeof value === 'number' && Number.isFinite(value) && value > 0;\n}\n\nfunction buildTxSessionKey(tabId: number): string {\n return `${WEB_EDITOR_TX_CHANGED_SESSION_KEY_PREFIX}${tabId}`;\n}\n\nfunction buildExcludedKeysSessionKey(tabId: number): string {\n return `${WEB_EDITOR_EXCLUDED_KEYS_SESSION_KEY_PREFIX}${tabId}`;\n}\n\nfunction buildSelectionSessionKey(tabId: number): string {\n return `${WEB_EDITOR_SELECTION_SESSION_KEY_PREFIX}${tabId}`;\n}\n\n/**\n * Normalize and validate selection changed payload from storage or message.\n * Returns null if the payload is invalid.\n */\nfunction normalizeSelectionPayload(raw: unknown): WebEditorSelectionChangedPayload | null {\n if (!raw || typeof raw !== 'object') return null;\n const obj = raw as Record;\n\n const tabId = Number(obj.tabId);\n if (!Number.isFinite(tabId) || tabId <= 0) return null;\n\n // Selected can be null (deselection) or an object\n const selectedRaw = obj.selected;\n let selected: SelectedElementSummary | null = null;\n\n if (selectedRaw && typeof selectedRaw === 'object') {\n const sel = selectedRaw as Record;\n const elementKey = typeof sel.elementKey === 'string' ? sel.elementKey.trim() : '';\n if (!elementKey) return null; // Invalid selection\n\n selected = {\n elementKey,\n locator: sel.locator as SelectedElementSummary['locator'],\n label: typeof sel.label === 'string' ? sel.label : '',\n fullLabel: typeof sel.fullLabel === 'string' ? sel.fullLabel : '',\n tagName: typeof sel.tagName === 'string' ? sel.tagName : '',\n updatedAt: typeof sel.updatedAt === 'number' ? sel.updatedAt : Date.now(),\n };\n }\n\n return {\n tabId,\n selected,\n pageUrl: typeof obj.pageUrl === 'string' ? obj.pageUrl : undefined,\n };\n}\n\n/**\n * Normalize and validate TX changed payload from storage or message.\n * Returns null if the payload is invalid.\n */\nfunction normalizeTxChangedPayload(raw: unknown): WebEditorTxChangedPayload | null {\n if (!raw || typeof raw !== 'object') return null;\n const obj = raw as Record;\n\n const tabId = Number(obj.tabId);\n if (!Number.isFinite(tabId) || tabId <= 0) return null;\n\n const actionRaw = typeof obj.action === 'string' ? obj.action : '';\n if (!VALID_TX_ACTIONS.has(actionRaw as WebEditorTxChangeAction)) return null;\n const action = actionRaw as WebEditorTxChangeAction;\n\n // Filter elements to ensure minimal validity (elementKey must be a non-empty string)\n const rawElements = Array.isArray(obj.elements) ? obj.elements : [];\n const elements = rawElements.filter(\n (e): e is ElementChangeSummary =>\n e &&\n typeof e === 'object' &&\n typeof (e as any).elementKey === 'string' &&\n (e as any).elementKey,\n );\n\n const undoCountRaw = Number(obj.undoCount);\n const redoCountRaw = Number(obj.redoCount);\n const undoCount = Number.isFinite(undoCountRaw) && undoCountRaw >= 0 ? undoCountRaw : 0;\n const redoCount = Number.isFinite(redoCountRaw) && redoCountRaw >= 0 ? redoCountRaw : 0;\n\n const hasApplicableChanges = Boolean(obj.hasApplicableChanges);\n const pageUrl = typeof obj.pageUrl === 'string' ? obj.pageUrl : undefined;\n\n return {\n tabId,\n action,\n elements,\n undoCount,\n redoCount,\n hasApplicableChanges,\n pageUrl,\n };\n}\n\n/**\n * Normalize and deduplicate excluded keys array from storage.\n * Filters out invalid entries and removes duplicates.\n */\nfunction normalizeExcludedKeys(raw: unknown): WebEditorElementKey[] {\n if (!Array.isArray(raw)) return [];\n\n const result: WebEditorElementKey[] = [];\n const seen = new Set();\n\n for (const item of raw) {\n const key = String(item ?? '').trim();\n if (!key || seen.has(key)) continue;\n seen.add(key);\n result.push(key);\n }\n\n return result;\n}\n\n/**\n * Persist excluded keys to session storage (per-tab).\n * Best-effort: silently ignores failures.\n */\nasync function persistExcludedKeys(\n tabId: number,\n keys: readonly WebEditorElementKey[],\n): Promise {\n if (!isValidTabId(tabId)) return;\n\n try {\n if (typeof chrome === 'undefined' || !chrome.storage?.session?.set) return;\n const storageKey = buildExcludedKeysSessionKey(tabId);\n await chrome.storage.session.set({ [storageKey]: [...keys] });\n } catch (error) {\n console.error('[useWebEditorTxState] Failed to persist excluded keys:', error);\n }\n}\n\n/**\n * Default implementation for getting active tab ID.\n */\nasync function getActiveTabIdDefault(): Promise {\n try {\n if (typeof chrome === 'undefined' || !chrome.tabs?.query) return null;\n const tabs = await chrome.tabs.query({ active: true, currentWindow: true });\n const tabId = tabs?.[0]?.id;\n return typeof tabId === 'number' ? tabId : null;\n } catch {\n return null;\n }\n}\n\n/**\n * Get current window ID for filtering tab activation events.\n * This prevents processing tab switches from other Chrome windows.\n */\nasync function getCurrentWindowId(): Promise {\n try {\n if (typeof chrome === 'undefined' || !chrome.windows?.getCurrent) return null;\n const win = await chrome.windows.getCurrent();\n return typeof win?.id === 'number' ? win.id : null;\n } catch {\n return null;\n }\n}\n\n// =============================================================================\n// Public API\n// =============================================================================\n\nexport interface UseWebEditorTxStateOptions {\n /**\n * Optional override for resolving the \"current tab\" in sidepanel.\n * Defaults to chrome.tabs.query({ active: true, currentWindow: true }).\n */\n getActiveTabId?: () => Promise;\n /**\n * If provided, skips querying the active tab on mount.\n */\n initialTabId?: number | null;\n}\n\nexport function useWebEditorTxState(options: UseWebEditorTxStateOptions = {}) {\n // ==========================================================================\n // State\n // ==========================================================================\n\n /** Current tab ID being tracked */\n const tabId = ref(\n isValidTabId(options.initialTabId) ? options.initialTabId : null,\n );\n\n /** Current TX state from web-editor */\n const txState = ref(null);\n\n /** Currently selected element (for context, may not have edits) */\n const selectedElement = ref(null);\n\n /** Page URL from selection (may differ from txState.pageUrl if selection is newer) */\n const selectionPageUrl = ref(null);\n\n /** Excluded element keys (user-deselected elements) */\n const excludedKeys = ref([]);\n\n // ==========================================================================\n // Computed\n // ==========================================================================\n\n /** All elements from TX state */\n const allElements = computed(() => txState.value?.elements ?? []);\n\n /** Set of excluded keys for O(1) lookup */\n const excludedKeySet = computed(() => new Set(excludedKeys.value));\n\n /** Elements that will be applied (not excluded) */\n const applicableElements = computed(() => {\n const set = excludedKeySet.value;\n return allElements.value.filter((e) => !set.has(e.elementKey));\n });\n\n /** Elements that are excluded by user */\n const excludedElements = computed(() => {\n const set = excludedKeySet.value;\n return allElements.value.filter((e) => set.has(e.elementKey));\n });\n\n /** Whether there are applicable changes to send to Agent */\n const hasChanges = computed(() => applicableElements.value.length > 0);\n\n /** Whether there is a selected element */\n const hasSelection = computed(() => selectedElement.value !== null);\n\n /**\n * Whether the selected element is also in the edits list.\n * Used to decide if we need a separate \"selection-only\" chip.\n */\n const isSelectionInEdits = computed(() => {\n const sel = selectedElement.value;\n if (!sel) return false;\n return allElements.value.some((e) => e.elementKey === sel.elementKey);\n });\n\n /** Whether to show the web editor section (has edits OR has selection) */\n const hasContent = computed(\n () => hasChanges.value || hasSelection.value || allElements.value.length > 0,\n );\n\n // ==========================================================================\n // Actions\n // ==========================================================================\n\n /**\n * Toggle an element's excluded state.\n * Automatically persists to session storage.\n */\n function toggleExclude(elementKey: WebEditorElementKey): void {\n const key = String(elementKey ?? '').trim();\n if (!key) return;\n\n const current = excludedKeys.value;\n const idx = current.indexOf(key);\n if (idx >= 0) {\n // Remove from excluded list\n excludedKeys.value = [...current.slice(0, idx), ...current.slice(idx + 1)];\n } else {\n // Add to excluded list\n excludedKeys.value = [...current, key];\n }\n\n // Persist to session storage\n if (isValidTabId(tabId.value)) {\n void persistExcludedKeys(tabId.value, excludedKeys.value);\n }\n }\n\n /**\n * Clear all excluded elements.\n * Automatically persists to session storage.\n */\n function clearExcluded(): void {\n excludedKeys.value = [];\n\n // Persist to session storage\n if (isValidTabId(tabId.value)) {\n void persistExcludedKeys(tabId.value, excludedKeys.value);\n }\n }\n\n /**\n * Remove excluded keys that no longer exist in the current TX state.\n * This prevents stale keys when elements are undone/cleared.\n */\n function pruneStaleExcludedKeys(elements: readonly ElementChangeSummary[] | null): void {\n if (!elements || !isValidTabId(tabId.value)) return;\n\n const validKeys = new Set(elements.map((e) => e.elementKey));\n const prunedKeys = excludedKeys.value.filter((k) => validKeys.has(k));\n\n // Only update if there are stale keys to remove\n if (prunedKeys.length === excludedKeys.value.length) return;\n\n excludedKeys.value = prunedKeys;\n void persistExcludedKeys(tabId.value, prunedKeys);\n }\n\n /** Sequence counter to prevent stale async updates */\n let refreshSeq = 0;\n\n /**\n * Refresh TX state from session storage for a specific tab.\n * Also restores excluded keys from storage.\n * On tab change, immediately clears state to prevent cross-tab pollution.\n */\n async function refreshFromStorage(targetTabId: number): Promise {\n if (!isValidTabId(targetTabId)) {\n tabId.value = null;\n txState.value = null;\n excludedKeys.value = [];\n selectedElement.value = null;\n selectionPageUrl.value = null;\n return;\n }\n\n // On tab change, immediately clear state to prevent UI showing stale data\n const isTabChange = tabId.value !== targetTabId;\n if (isTabChange) {\n txState.value = null;\n excludedKeys.value = [];\n selectedElement.value = null;\n selectionPageUrl.value = null;\n }\n tabId.value = targetTabId;\n\n const seq = ++refreshSeq;\n const txKey = buildTxSessionKey(targetTabId);\n const excludedKey = buildExcludedKeysSessionKey(targetTabId);\n const selectionKey = buildSelectionSessionKey(targetTabId);\n\n try {\n if (typeof chrome === 'undefined' || !chrome.storage?.session?.get) {\n txState.value = null;\n excludedKeys.value = [];\n selectedElement.value = null;\n selectionPageUrl.value = null;\n return;\n }\n\n // Fetch TX state, excluded keys, and selection in one call\n const result = (await chrome.storage.session.get([\n txKey,\n excludedKey,\n selectionKey,\n ])) as Record;\n\n // Check for stale async response\n if (seq !== refreshSeq) return;\n\n // Update TX state\n const nextTxState = normalizeTxChangedPayload(result?.[txKey]);\n txState.value = nextTxState;\n\n // Restore excluded keys from storage\n excludedKeys.value = normalizeExcludedKeys(result?.[excludedKey]);\n\n // Restore selection from storage\n const nextSelection = normalizeSelectionPayload(result?.[selectionKey]);\n selectedElement.value = nextSelection?.selected ?? null;\n selectionPageUrl.value = nextSelection?.pageUrl ?? null;\n\n // Prune stale excluded keys based on current elements\n pruneStaleExcludedKeys(nextTxState?.elements ?? null);\n } catch (error) {\n console.error('[useWebEditorTxState] Failed to refresh from session storage:', error);\n // On error, ensure clean state to prevent showing stale data\n txState.value = null;\n excludedKeys.value = [];\n selectedElement.value = null;\n selectionPageUrl.value = null;\n }\n }\n\n // ==========================================================================\n // Message Listeners\n // ==========================================================================\n\n /**\n * Handle runtime messages from background.\n */\n const onRuntimeMessage = (\n message: unknown,\n _sender: chrome.runtime.MessageSender,\n _sendResponse: (response?: unknown) => void,\n ): void => {\n const msg =\n message && typeof message === 'object' ? (message as Record) : null;\n if (!msg) return;\n\n // Handle TX changed messages\n if (msg.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_TX_CHANGED) {\n const next = normalizeTxChangedPayload(msg.payload);\n if (!next) return;\n\n // Only process messages for the current tab\n if (!isValidTabId(tabId.value)) return;\n if (next.tabId !== tabId.value) return;\n\n txState.value = next;\n\n // Prune excluded keys that no longer exist (e.g., after undo/clear)\n pruneStaleExcludedKeys(next.elements);\n return;\n }\n\n // Handle selection changed messages\n if (msg.type === BACKGROUND_MESSAGE_TYPES.WEB_EDITOR_SELECTION_CHANGED) {\n const next = normalizeSelectionPayload(msg.payload);\n if (!next) return;\n\n // Only process messages for the current tab\n if (!isValidTabId(tabId.value)) return;\n if (next.tabId !== tabId.value) return;\n\n selectedElement.value = next.selected;\n // Store pageUrl from selection for context building\n selectionPageUrl.value = next.pageUrl ?? null;\n return;\n }\n };\n\n /**\n * Handle session storage changes (fallback for cold start).\n * Only handles TX state changes; excluded keys are managed explicitly.\n */\n const onSessionChanged = (changes: { [key: string]: chrome.storage.StorageChange }): void => {\n if (!isValidTabId(tabId.value)) return;\n const txKey = buildTxSessionKey(tabId.value);\n\n const change = changes?.[txKey];\n if (!change) return;\n\n if (change.newValue === undefined) {\n txState.value = null;\n // Clear excluded keys when TX state is cleared\n pruneStaleExcludedKeys([]);\n return;\n }\n\n const next = normalizeTxChangedPayload(change.newValue);\n txState.value = next;\n\n // Prune stale excluded keys\n pruneStaleExcludedKeys(next?.elements ?? []);\n };\n\n /** Cleanup function for storage listener */\n let removeStorageListener: (() => void) | null = null;\n\n /** Cleanup function for tab activated listener */\n let removeTabActivatedListener: (() => void) | null = null;\n\n /** Cached window ID to filter tab activation events from other windows */\n let currentWindowId: number | null = null;\n\n /**\n * Handle tab activation events.\n * Updates tabId and loads TX state when user switches to a different tab.\n *\n * Note: currentWindowId filtering is best-effort. If getCurrentWindowId() fails,\n * events from all windows will be processed (acceptable fallback behavior).\n */\n const onTabActivated = (activeInfo: chrome.tabs.TabActiveInfo): void => {\n try {\n // Ignore events from other windows (best-effort filter)\n if (currentWindowId !== null && activeInfo.windowId !== currentWindowId) return;\n\n const nextTabId = activeInfo.tabId;\n if (!isValidTabId(nextTabId)) return;\n\n // Skip if already tracking this tab\n if (nextTabId === tabId.value) return;\n\n // Load TX state for the newly activated tab\n void refreshFromStorage(nextTabId);\n } catch (error) {\n console.error('[useWebEditorTxState] Failed to handle tab activation:', error);\n }\n };\n\n // ==========================================================================\n // Lifecycle\n // ==========================================================================\n\n onMounted(async () => {\n // Register runtime message listener\n try {\n if (typeof chrome !== 'undefined' && chrome.runtime?.onMessage?.addListener) {\n chrome.runtime.onMessage.addListener(onRuntimeMessage);\n }\n } catch (error) {\n console.error('Failed to register WebEditor TX runtime listener:', error);\n }\n\n // Register session storage listener\n try {\n if (typeof chrome !== 'undefined' && chrome.storage?.session?.onChanged?.addListener) {\n // Prefer session-specific listener if available\n chrome.storage.session.onChanged.addListener(onSessionChanged);\n removeStorageListener = () => {\n try {\n chrome.storage.session.onChanged.removeListener(onSessionChanged);\n } catch {}\n };\n } else if (typeof chrome !== 'undefined' && chrome.storage?.onChanged?.addListener) {\n // Fallback to generic storage listener with area filter\n const onChanged = (\n changes: { [key: string]: chrome.storage.StorageChange },\n areaName: chrome.storage.AreaName,\n ) => {\n if (areaName !== 'session') return;\n onSessionChanged(changes);\n };\n\n chrome.storage.onChanged.addListener(onChanged);\n removeStorageListener = () => {\n try {\n chrome.storage.onChanged.removeListener(onChanged);\n } catch {}\n };\n }\n } catch (error) {\n console.error('Failed to register WebEditor TX storage listener:', error);\n }\n\n // Cache current window ID for filtering tab activation events\n currentWindowId = await getCurrentWindowId();\n\n // Register tab activation listener to track tab switches\n try {\n if (typeof chrome !== 'undefined' && chrome.tabs?.onActivated?.addListener) {\n chrome.tabs.onActivated.addListener(onTabActivated);\n removeTabActivatedListener = () => {\n try {\n chrome.tabs.onActivated.removeListener(onTabActivated);\n } catch {}\n };\n }\n } catch (error) {\n console.error('[useWebEditorTxState] Failed to register tab activation listener:', error);\n }\n\n // Initialize tab ID if not provided\n const getActiveTabId = options.getActiveTabId ?? getActiveTabIdDefault;\n\n if (!isValidTabId(tabId.value)) {\n const active = await getActiveTabId().catch(() => null);\n if (isValidTabId(active)) {\n tabId.value = active;\n }\n }\n\n // Load initial state from storage\n if (isValidTabId(tabId.value)) {\n await refreshFromStorage(tabId.value);\n }\n });\n\n onUnmounted(() => {\n // Clean up runtime message listener\n try {\n if (typeof chrome !== 'undefined' && chrome.runtime?.onMessage?.removeListener) {\n chrome.runtime.onMessage.removeListener(onRuntimeMessage);\n }\n } catch {}\n\n // Clean up storage listener\n removeStorageListener?.();\n removeStorageListener = null;\n\n // Clean up tab activation listener\n removeTabActivatedListener?.();\n removeTabActivatedListener = null;\n });\n\n // ==========================================================================\n // Return\n // ==========================================================================\n\n return {\n // State\n tabId,\n txState,\n excludedKeys,\n selectedElement,\n selectionPageUrl,\n\n // UI State (computed)\n allElements,\n hasChanges,\n hasSelection,\n isSelectionInEdits,\n hasContent,\n applicableElements,\n excludedElements,\n\n // Actions\n toggleExclude,\n clearExcluded,\n refreshFromStorage,\n };\n}\n\n// =============================================================================\n// Type Exports & Injection Key\n// =============================================================================\n\n/**\n * Return type of useWebEditorTxState composable.\n * Used for type-safe provide/inject.\n */\nexport type WebEditorTxStateReturn = ReturnType;\n\n/**\n * Injection key for providing WebEditorTxState to child components.\n * Use this with Vue's provide/inject pattern to avoid duplicate listener registration.\n *\n * @example\n * // In AgentChat.vue (parent)\n * const webEditorTx = useWebEditorTxState();\n * provide(WEB_EDITOR_TX_STATE_INJECTION_KEY, webEditorTx);\n *\n * // In WebEditorChanges.vue (child)\n * const tx = inject(WEB_EDITOR_TX_STATE_INJECTION_KEY);\n */\nexport const WEB_EDITOR_TX_STATE_INJECTION_KEY: InjectionKey =\n Symbol('web-editor-tx-state');\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/composables/useWorkflowsV3.ts", "content": "/**\n * @fileoverview V3 Workflows Data Layer Composable\n * @description Provides V3 workflows data management for Sidepanel UI\n *\n * This composable wraps the V3 RPC client and provides:\n * - Flow listing, running, and deletion\n * - Run listing and event subscription\n * - Trigger management\n * - Data mapping from V3 types to UI types\n */\n\nimport { onMounted, onUnmounted, ref, type Ref } from 'vue';\n\nimport type { FlowV3 } from '@/entrypoints/background/record-replay-v3/domain/flow';\nimport type { RunRecordV3 } from '@/entrypoints/background/record-replay-v3/domain/events';\nimport type { TriggerSpec } from '@/entrypoints/background/record-replay-v3/domain/triggers';\nimport type { FlowId, RunId } from '@/entrypoints/background/record-replay-v3/domain/ids';\nimport { useRRV3Rpc } from './useRRV3Rpc';\n\n// ==================== UI Types ====================\n\n/** Flow type for UI display (compatible with existing WorkflowsView) */\nexport interface FlowLite {\n id: string;\n name: string;\n description?: string;\n meta?: {\n domain?: string;\n tags?: string[];\n bindings?: Array<{\n kind?: string; // V3 uses 'kind'\n type?: string; // V2 uses 'type'\n value: string;\n }>;\n };\n}\n\n/** Run type for UI display (compatible with existing WorkflowsView) */\nexport interface RunLite {\n id: string;\n flowId: string;\n startedAt: string;\n finishedAt?: string;\n /**\n * Terminal success status: true=succeeded, false=failed/canceled, undefined=in progress\n * UI should check `isInProgress` first to distinguish in-progress from failed\n */\n success?: boolean;\n /** Whether the run is still in progress (queued/running/paused) */\n isInProgress: boolean;\n status: RunRecordV3['status'];\n entries: unknown[];\n}\n\n/** Trigger type for UI display */\nexport interface TriggerLite {\n id: string;\n type: string; // UI uses 'type', V3 uses 'kind'\n kind: string; // V3 uses 'kind'\n flowId: string;\n enabled?: boolean;\n match?: Array<{ kind: string; value: string }>; // For URL triggers\n [key: string]: unknown;\n}\n\n// ==================== Mappers ====================\n\n/** Convert V3 FlowV3 to UI FlowLite */\nfunction mapFlowV3ToLite(flow: FlowV3): FlowLite {\n return {\n id: flow.id,\n name: flow.name,\n description: flow.description,\n meta: {\n tags: flow.meta?.tags,\n bindings: flow.meta?.bindings?.map((b) => ({\n kind: b.kind,\n type: b.kind, // For V2 compatibility\n value: b.value,\n })),\n },\n };\n}\n\n/** Convert V3 RunRecordV3 to UI RunLite */\nfunction mapRunV3ToLite(run: RunRecordV3): RunLite {\n // Determine if run is in progress\n const inProgressStatuses = ['queued', 'running', 'paused'];\n const isInProgress = inProgressStatuses.includes(run.status);\n\n // Map V3 status to success boolean for terminal states only\n let success: boolean | undefined;\n if (run.status === 'succeeded') success = true;\n else if (run.status === 'failed' || run.status === 'canceled') success = false;\n // For in-progress states, success remains undefined\n\n return {\n id: run.id,\n flowId: run.flowId,\n startedAt: run.startedAt\n ? new Date(run.startedAt).toISOString()\n : new Date(run.createdAt).toISOString(),\n finishedAt: run.finishedAt ? new Date(run.finishedAt).toISOString() : undefined,\n success,\n isInProgress,\n status: run.status,\n entries: [], // V3 doesn't have entries in RunRecord, use getEvents for details\n };\n}\n\n/** Convert V3 TriggerSpec to UI TriggerLite */\nfunction mapTriggerV3ToLite(trigger: TriggerSpec): TriggerLite {\n return {\n ...trigger,\n type: trigger.kind, // Map 'kind' to 'type' for UI compatibility\n kind: trigger.kind,\n } as TriggerLite;\n}\n\n// ==================== Composable ====================\n\nexport interface UseWorkflowsV3Options {\n /** Auto-refresh interval in ms (0 = disabled) */\n autoRefreshMs?: number;\n /** Auto-connect on mount */\n autoConnect?: boolean;\n}\n\nexport interface UseWorkflowsV3Return {\n // Connection state\n connected: Ref;\n loading: Ref;\n error: Ref;\n\n // Data\n flows: Ref;\n runs: Ref;\n triggers: Ref;\n\n // Actions\n refresh: () => Promise;\n refreshFlows: () => Promise;\n refreshRuns: () => Promise;\n refreshTriggers: () => Promise;\n runFlow: (flowId: string) => Promise<{ runId: string } | null>;\n deleteFlow: (flowId: string) => Promise;\n exportFlow: (flowId: string) => Promise;\n deleteTrigger: (triggerId: string) => Promise;\n\n // V3-specific\n getFlowById: (flowId: string) => Promise;\n getRunEvents: (runId: string) => Promise;\n}\n\n/**\n * V3 Workflows data layer composable\n */\nexport function useWorkflowsV3(options: UseWorkflowsV3Options = {}): UseWorkflowsV3Return {\n const { autoRefreshMs = 0, autoConnect = true } = options;\n\n // RPC client\n const rpc = useRRV3Rpc({ autoConnect });\n\n // State\n const loading = ref(false);\n const error = ref(null);\n const flows = ref([]);\n const runs = ref([]);\n const triggers = ref([]);\n\n // Auto-refresh timer\n let refreshTimer: ReturnType | null = null;\n // Event subscription cleanup function\n let eventUnsubscribe: (() => void) | null = null;\n\n // ==================== Actions ====================\n\n async function refreshFlows(): Promise {\n try {\n const result = (await rpc.request('rr_v3.listFlows')) as FlowV3[] | null;\n flows.value = (result || []).map(mapFlowV3ToLite);\n } catch (e) {\n console.warn('[useWorkflowsV3] Failed to refresh flows:', e);\n error.value = e instanceof Error ? e.message : String(e);\n }\n }\n\n async function refreshRuns(): Promise {\n try {\n const result = (await rpc.request('rr_v3.listRuns')) as RunRecordV3[] | null;\n // Sort by createdAt descending (newest first)\n const sorted = (result || []).slice().sort((a, b) => b.createdAt - a.createdAt);\n runs.value = sorted.map(mapRunV3ToLite);\n } catch (e) {\n console.warn('[useWorkflowsV3] Failed to refresh runs:', e);\n error.value = e instanceof Error ? e.message : String(e);\n }\n }\n\n async function refreshTriggers(): Promise {\n try {\n const result = (await rpc.request('rr_v3.listTriggers')) as TriggerSpec[] | null;\n triggers.value = (result || []).map(mapTriggerV3ToLite);\n } catch (e) {\n console.warn('[useWorkflowsV3] Failed to refresh triggers:', e);\n error.value = e instanceof Error ? e.message : String(e);\n }\n }\n\n async function refresh(): Promise {\n loading.value = true;\n error.value = null;\n try {\n await Promise.all([refreshFlows(), refreshRuns(), refreshTriggers()]);\n } finally {\n loading.value = false;\n }\n }\n\n async function runFlow(flowId: string): Promise<{ runId: string } | null> {\n try {\n const result = (await rpc.request('rr_v3.enqueueRun', {\n flowId: flowId as FlowId,\n })) as { runId: RunId; position: number } | null;\n // Refresh runs to show the new run\n void refreshRuns();\n return result ? { runId: result.runId } : null;\n } catch (e) {\n console.warn('[useWorkflowsV3] Failed to run flow:', e);\n error.value = e instanceof Error ? e.message : String(e);\n return null;\n }\n }\n\n async function deleteFlow(flowId: string): Promise {\n try {\n await rpc.request('rr_v3.deleteFlow', { flowId: flowId as FlowId });\n // Refresh flows after deletion\n void refreshFlows();\n return true;\n } catch (e) {\n console.warn('[useWorkflowsV3] Failed to delete flow:', e);\n error.value = e instanceof Error ? e.message : String(e);\n return false;\n }\n }\n\n async function exportFlow(flowId: string): Promise {\n try {\n const result = (await rpc.request('rr_v3.getFlow', {\n flowId: flowId as FlowId,\n })) as FlowV3 | null;\n return result;\n } catch (e) {\n console.warn('[useWorkflowsV3] Failed to export flow:', e);\n error.value = e instanceof Error ? e.message : String(e);\n return null;\n }\n }\n\n async function deleteTrigger(triggerId: string): Promise {\n try {\n await rpc.request('rr_v3.deleteTrigger', { triggerId });\n // Refresh triggers after deletion\n void refreshTriggers();\n return true;\n } catch (e) {\n console.warn('[useWorkflowsV3] Failed to delete trigger:', e);\n error.value = e instanceof Error ? e.message : String(e);\n return false;\n }\n }\n\n async function getFlowById(flowId: string): Promise {\n try {\n return (await rpc.request('rr_v3.getFlow', {\n flowId: flowId as FlowId,\n })) as FlowV3 | null;\n } catch (e) {\n console.warn('[useWorkflowsV3] Failed to get flow:', e);\n return null;\n }\n }\n\n async function getRunEvents(runId: string): Promise {\n try {\n return (await rpc.request('rr_v3.getEvents', {\n runId: runId as RunId,\n })) as unknown[];\n } catch (e) {\n console.warn('[useWorkflowsV3] Failed to get run events:', e);\n return [];\n }\n }\n\n // ==================== Lifecycle ====================\n\n onMounted(async () => {\n if (autoConnect) {\n await rpc.ensureConnected();\n await refresh();\n }\n\n // Setup auto-refresh\n if (autoRefreshMs > 0) {\n refreshTimer = setInterval(() => {\n void refresh();\n }, autoRefreshMs);\n }\n\n // Subscribe to all run events for real-time updates\n void rpc.subscribe(null);\n eventUnsubscribe = rpc.onEvent((event) => {\n // Refresh runs when run status changes\n const runStatusEvents = [\n 'run.queued',\n 'run.started',\n 'run.succeeded',\n 'run.failed',\n 'run.canceled',\n 'run.paused',\n 'run.resumed',\n 'run.recovered',\n ];\n if (runStatusEvents.includes(event.type)) {\n void refreshRuns();\n }\n });\n });\n\n onUnmounted(() => {\n // Cleanup auto-refresh timer\n if (refreshTimer) {\n clearInterval(refreshTimer);\n refreshTimer = null;\n }\n // Cleanup event subscription\n if (eventUnsubscribe) {\n eventUnsubscribe();\n eventUnsubscribe = null;\n }\n // Unsubscribe from run events\n void rpc.unsubscribe(null);\n });\n\n return {\n connected: rpc.connected,\n loading,\n error,\n flows,\n runs,\n triggers,\n refresh,\n refreshFlows,\n refreshRuns,\n refreshTriggers,\n runFlow,\n deleteFlow,\n exportFlow,\n deleteTrigger,\n getFlowById,\n getRunEvents,\n };\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/index.html", "content": "\n\n \n \n \n 工作流管理\n \n \n \n
\n \n \n\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/main.ts", "content": "import { createApp } from 'vue';\nimport { NativeMessageType } from 'chrome-mcp-shared';\nimport App from './App.vue';\n\n// Tailwind first, then custom tokens\nimport '../styles/tailwind.css';\n// AgentChat theme tokens\nimport './styles/agent-chat.css';\n\nimport { preloadAgentTheme } from './composables';\n\n/**\n * Initialize and mount the Vue app.\n * Preloads theme before mounting to prevent flash.\n */\nasync function init(): Promise {\n // Preload theme from storage and apply to document\n // This happens before Vue mounts, preventing theme flash\n await preloadAgentTheme();\n\n // Trigger ensure native connection (fire-and-forget, don't block UI mounting)\n void chrome.runtime.sendMessage({ type: NativeMessageType.ENSURE_NATIVE }).catch(() => {\n // Silent failure - background will handle reconnection\n });\n\n // Mount Vue app\n createApp(App).mount('#app');\n}\n\ninit();\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/styles/agent-chat.css", "content": "/**\n * AgentChat Theme System\n *\n * This file defines the CSS variable tokens for the AgentChat component.\n * All components must only use these tokens - never hardcode colors.\n *\n * Themes:\n * - warm-editorial (default): Warm, editorial style from agent-ux.html\n * - blueprint-architect: Blueprint grid with technical aesthetic\n * - zen-journal: Calm journal / graphite accent (Muji style)\n * - neo-pop: Thick borders + hard shadow (Brutalist)\n * - dark-console: Dark terminal/console style\n * - swiss-grid: High-contrast brutalist/swiss style\n */\n\n@layer base {\n .agent-theme {\n /* ========================================\n Font Stacks (system font fallbacks)\n ======================================== */\n --ac-font-sans:\n 'Inter', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial,\n 'Apple Color Emoji', 'Segoe UI Emoji';\n --ac-font-serif: 'Newsreader', ui-serif, Georgia, Cambria, 'Times New Roman', Times, serif;\n --ac-font-mono:\n 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',\n 'Courier New', monospace;\n --ac-font-grotesk:\n 'Space Grotesk', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial;\n\n /* Semantic font tokens */\n --ac-font-body: var(--ac-font-sans);\n --ac-font-heading: var(--ac-font-serif);\n --ac-font-code: var(--ac-font-mono);\n\n /* ========================================\n Geometry (Shape & Spacing)\n ======================================== */\n --ac-border-width: 1px;\n --ac-border-width-strong: 2px;\n --ac-radius-container: 0px;\n --ac-radius-card: 12px;\n --ac-radius-inner: 8px;\n --ac-radius-button: 8px;\n\n /* Motion */\n --ac-motion-fast: 120ms;\n --ac-motion-normal: 180ms;\n\n /* Timeline sizing */\n --ac-timeline-line-width: 1px;\n --ac-timeline-node-size: 8px;\n --ac-timeline-indent: 24px;\n\n /* Scrollbar sizing */\n --ac-scrollbar-size: 4px;\n\n /* ========================================\n WARM EDITORIAL (Default Theme)\n ======================================== */\n\n /* Background */\n --ac-bg: #fdfcf8;\n --ac-bg-pattern: none;\n --ac-bg-pattern-size: 16px 16px;\n\n /* Header */\n --ac-header-bg: rgba(253, 252, 248, 0.95);\n --ac-header-border: rgba(245, 245, 244, 0.5);\n\n /* Surfaces */\n --ac-surface: #ffffff;\n --ac-surface-muted: #f2f0eb;\n --ac-surface-inset: #f2f0eb;\n\n /* Text */\n --ac-text: #1a1a1a;\n --ac-text-muted: #6e6e6e;\n --ac-text-subtle: #a8a29e;\n --ac-text-inverse: #ffffff;\n --ac-text-placeholder: #a8a29e;\n\n /* Borders */\n --ac-border: #e7e5e4;\n --ac-border-strong: #d6d3d1;\n\n /* Hover states */\n --ac-hover-bg: #f5f5f4;\n --ac-hover-bg-subtle: #fafaf9;\n\n /* Accent (terracotta) */\n --ac-accent: #d97757;\n --ac-accent-hover: #c4664a;\n --ac-accent-subtle: rgba(217, 119, 87, 0.12);\n --ac-accent-contrast: #ffffff;\n --ac-accent-2: var(--ac-accent);\n\n /* Links */\n --ac-link: var(--ac-accent);\n --ac-link-hover: var(--ac-accent-hover);\n\n /* Selection */\n --ac-selection-bg: #ffedd5;\n --ac-selection-text: #7c2d12;\n\n /* Shadows */\n --ac-shadow-card: 0 1px 3px rgba(0, 0, 0, 0.08);\n --ac-shadow-float: 0 4px 20px -2px rgba(0, 0, 0, 0.05);\n\n /* Focus */\n --ac-focus-ring: rgba(214, 211, 209, 0.9);\n\n /* Timeline */\n --ac-timeline-line: #e7e5e4;\n --ac-timeline-node: #d6d3d1;\n --ac-timeline-node-hover: #a8a29e;\n --ac-timeline-node-active: var(--ac-accent);\n --ac-timeline-node-active-border: var(--ac-accent);\n --ac-timeline-node-tool: #94a3b8;\n --ac-timeline-node-pulse-shadow:\n 0 0 0 2px rgba(217, 119, 87, 0.25), 0 0 12px rgba(217, 119, 87, 0.2);\n\n /* Chips/Pills */\n --ac-chip-bg: #f2f0eb;\n --ac-chip-text: #1a1a1a;\n --ac-chip-border: #e7e5e4;\n\n /* Code blocks */\n --ac-code-bg: #ffffff;\n --ac-code-text: #1a1a1a;\n --ac-code-border: #e7e5e4;\n\n /* Diff colors */\n --ac-diff-add-bg: rgba(240, 253, 244, 0.6);\n --ac-diff-add-text: #15803d;\n --ac-diff-add-border: #4ade80;\n --ac-diff-del-bg: rgba(254, 242, 242, 0.6);\n --ac-diff-del-text: #b91c1c;\n --ac-diff-del-border: #fca5a5;\n\n /* Status colors */\n --ac-success: #22c55e;\n --ac-warning: #f59e0b;\n --ac-danger: #ef4444;\n\n /* Scrollbar */\n --ac-scrollbar-thumb: #e5e5e5;\n --ac-scrollbar-thumb-hover: #d4d4d4;\n }\n\n /* ========================================\n WARM EDITORIAL (Explicit for clarity)\n ======================================== */\n .agent-theme[data-agent-theme='warm-editorial'] {\n --ac-font-body: var(--ac-font-sans);\n --ac-font-heading: var(--ac-font-serif);\n --ac-font-code: var(--ac-font-mono);\n\n --ac-bg: #fdfcf8;\n --ac-bg-pattern: none;\n --ac-header-bg: rgba(253, 252, 248, 0.95);\n --ac-header-border: rgba(245, 245, 244, 0.5);\n --ac-surface: #ffffff;\n --ac-surface-muted: #f2f0eb;\n --ac-text: #1a1a1a;\n --ac-text-muted: #6e6e6e;\n --ac-text-subtle: #a8a29e;\n --ac-border: #e7e5e4;\n --ac-accent: #d97757;\n --ac-shadow-card: 0 1px 3px rgba(0, 0, 0, 0.08);\n --ac-radius-card: 12px;\n --ac-border-width: 1px;\n }\n\n /* ========================================\n BLUEPRINT ARCHITECT\n ======================================== */\n .agent-theme[data-agent-theme='blueprint-architect'] {\n --ac-font-body: var(--ac-font-grotesk);\n --ac-font-heading: var(--ac-font-grotesk);\n --ac-font-code: var(--ac-font-mono);\n\n --ac-bg: #f7fbff;\n --ac-bg-pattern:\n linear-gradient(to right, rgba(37, 99, 235, 0.14) 1px, transparent 1px),\n linear-gradient(to bottom, rgba(37, 99, 235, 0.14) 1px, transparent 1px);\n --ac-bg-pattern-size: 24px 24px;\n\n --ac-header-bg: rgba(247, 251, 255, 0.86);\n --ac-header-border: rgba(37, 99, 235, 0.25);\n\n --ac-surface: rgba(255, 255, 255, 0.92);\n --ac-surface-muted: rgba(239, 246, 255, 0.9);\n --ac-surface-inset: rgba(239, 246, 255, 0.9);\n\n --ac-text: #0b1220;\n --ac-text-muted: #1f2a44;\n --ac-text-subtle: #475569;\n --ac-text-inverse: #ffffff;\n --ac-text-placeholder: #64748b;\n\n --ac-border: rgba(37, 99, 235, 0.25);\n --ac-border-strong: rgba(37, 99, 235, 0.45);\n\n --ac-hover-bg: rgba(37, 99, 235, 0.08);\n --ac-hover-bg-subtle: rgba(37, 99, 235, 0.05);\n\n --ac-accent: #2563eb;\n --ac-accent-hover: #1d4ed8;\n --ac-accent-subtle: rgba(37, 99, 235, 0.12);\n --ac-accent-contrast: #ffffff;\n\n --ac-accent-2: #0ea5e9;\n --ac-link: var(--ac-accent);\n --ac-link-hover: var(--ac-accent-hover);\n\n --ac-selection-bg: rgba(37, 99, 235, 0.16);\n --ac-selection-text: #0b1220;\n\n --ac-shadow-card: 0 1px 3px rgba(2, 6, 23, 0.12);\n --ac-shadow-float: 0 10px 28px -10px rgba(2, 6, 23, 0.22);\n --ac-focus-ring: rgba(37, 99, 235, 0.4);\n\n --ac-timeline-line: rgba(37, 99, 235, 0.35);\n --ac-timeline-node: rgba(37, 99, 235, 0.35);\n --ac-timeline-node-hover: rgba(37, 99, 235, 0.55);\n --ac-timeline-node-active: var(--ac-accent);\n --ac-timeline-node-active-border: var(--ac-accent);\n --ac-timeline-node-tool: rgba(37, 99, 235, 0.5);\n --ac-timeline-node-pulse-shadow:\n 0 0 0 2px rgba(37, 99, 235, 0.25), 0 0 12px rgba(37, 99, 235, 0.2);\n\n --ac-chip-bg: rgba(239, 246, 255, 0.9);\n --ac-chip-text: #0b1220;\n --ac-chip-border: rgba(37, 99, 235, 0.25);\n\n --ac-code-bg: rgba(255, 255, 255, 0.92);\n --ac-code-text: #0b1220;\n --ac-code-border: rgba(37, 99, 235, 0.25);\n\n --ac-diff-add-bg: rgba(34, 197, 94, 0.12);\n --ac-diff-add-text: #15803d;\n --ac-diff-add-border: rgba(34, 197, 94, 0.4);\n --ac-diff-del-bg: rgba(239, 68, 68, 0.12);\n --ac-diff-del-text: #b91c1c;\n --ac-diff-del-border: rgba(239, 68, 68, 0.4);\n\n --ac-scrollbar-thumb: rgba(37, 99, 235, 0.2);\n --ac-scrollbar-thumb-hover: rgba(37, 99, 235, 0.35);\n }\n\n /* ========================================\n ZEN JOURNAL\n ======================================== */\n .agent-theme[data-agent-theme='zen-journal'] {\n --ac-font-body: var(--ac-font-serif);\n --ac-font-heading: var(--ac-font-serif);\n --ac-font-code: var(--ac-font-mono);\n\n --ac-bg: #fafaf9;\n --ac-bg-pattern: linear-gradient(to bottom, rgba(120, 113, 108, 0.07) 1px, transparent 1px);\n --ac-bg-pattern-size: 100% 28px;\n\n --ac-header-bg: rgba(250, 250, 249, 0.92);\n --ac-header-border: rgba(231, 229, 228, 0.9);\n\n --ac-surface: rgba(255, 255, 255, 0.92);\n --ac-surface-muted: rgba(245, 245, 244, 0.92);\n --ac-surface-inset: rgba(245, 245, 244, 0.92);\n\n --ac-text: #1c1917;\n --ac-text-muted: #44403c;\n --ac-text-subtle: #78716c;\n --ac-text-inverse: #ffffff;\n --ac-text-placeholder: #a8a29e;\n\n --ac-border: #e7e5e4;\n --ac-border-strong: #d6d3d1;\n\n --ac-hover-bg: rgba(120, 113, 108, 0.08);\n --ac-hover-bg-subtle: rgba(120, 113, 108, 0.05);\n\n --ac-accent: #57534e;\n --ac-accent-hover: #44403c;\n --ac-accent-subtle: rgba(87, 83, 78, 0.12);\n --ac-accent-contrast: #ffffff;\n --ac-accent-2: var(--ac-accent);\n\n --ac-link: var(--ac-accent);\n --ac-link-hover: var(--ac-accent-hover);\n\n --ac-selection-bg: rgba(87, 83, 78, 0.18);\n --ac-selection-text: #1c1917;\n\n --ac-shadow-card: 0 1px 3px rgba(0, 0, 0, 0.06);\n --ac-shadow-float: 0 14px 34px -18px rgba(0, 0, 0, 0.18);\n --ac-focus-ring: rgba(87, 83, 78, 0.35);\n\n --ac-timeline-line: #e7e5e4;\n --ac-timeline-node: #d6d3d1;\n --ac-timeline-node-hover: #a8a29e;\n --ac-timeline-node-active: var(--ac-accent);\n --ac-timeline-node-active-border: var(--ac-accent);\n --ac-timeline-node-tool: #94a3b8;\n --ac-timeline-node-pulse-shadow:\n 0 0 0 2px rgba(87, 83, 78, 0.25), 0 0 12px rgba(87, 83, 78, 0.2);\n\n --ac-chip-bg: rgba(245, 245, 244, 0.92);\n --ac-chip-text: #1c1917;\n --ac-chip-border: #e7e5e4;\n\n --ac-code-bg: rgba(255, 255, 255, 0.92);\n --ac-code-text: #1c1917;\n --ac-code-border: #e7e5e4;\n\n --ac-diff-add-bg: rgba(34, 197, 94, 0.1);\n --ac-diff-add-text: #15803d;\n --ac-diff-add-border: rgba(34, 197, 94, 0.35);\n --ac-diff-del-bg: rgba(239, 68, 68, 0.1);\n --ac-diff-del-text: #b91c1c;\n --ac-diff-del-border: rgba(239, 68, 68, 0.35);\n\n --ac-scrollbar-thumb: rgba(120, 113, 108, 0.15);\n --ac-scrollbar-thumb-hover: rgba(120, 113, 108, 0.25);\n }\n\n /* ========================================\n NEO POP\n ======================================== */\n .agent-theme[data-agent-theme='neo-pop'] {\n --ac-font-body: var(--ac-font-sans);\n --ac-font-heading: var(--ac-font-grotesk);\n --ac-font-code: var(--ac-font-mono);\n\n --ac-border-width: 4px;\n --ac-border-width-strong: 4px;\n --ac-radius-card: 0px;\n --ac-radius-inner: 0px;\n --ac-radius-button: 0px;\n\n --ac-bg: #fff7ed;\n --ac-bg-pattern: radial-gradient(rgba(17, 24, 39, 0.12) 1px, transparent 1px);\n --ac-bg-pattern-size: 18px 18px;\n\n --ac-header-bg: rgba(255, 247, 237, 0.92);\n --ac-header-border: #111827;\n\n --ac-surface: #ffffff;\n --ac-surface-muted: #ffedd5;\n --ac-surface-inset: #ffffff;\n\n --ac-text: #111827;\n --ac-text-muted: #374151;\n --ac-text-subtle: #6b7280;\n --ac-text-inverse: #ffffff;\n --ac-text-placeholder: #9ca3af;\n\n --ac-border: #111827;\n --ac-border-strong: #111827;\n\n --ac-hover-bg: rgba(17, 24, 39, 0.06);\n --ac-hover-bg-subtle: rgba(17, 24, 39, 0.04);\n\n --ac-accent: #ff3d7f;\n --ac-accent-hover: #ff1f6a;\n --ac-accent-subtle: rgba(255, 61, 127, 0.14);\n --ac-accent-contrast: #ffffff;\n\n --ac-accent-2: #22d3ee;\n --ac-link: var(--ac-accent-2);\n --ac-link-hover: #06b6d4;\n\n --ac-selection-bg: rgba(255, 61, 127, 0.25);\n --ac-selection-text: #111827;\n\n --ac-shadow-card: 6px 6px 0 0 var(--ac-border);\n --ac-shadow-float: 8px 8px 0 0 var(--ac-border);\n --ac-focus-ring: rgba(17, 24, 39, 0.35);\n\n --ac-timeline-line-width: 4px;\n --ac-timeline-line: #111827;\n --ac-timeline-node: #111827;\n --ac-timeline-node-hover: #374151;\n --ac-timeline-node-active: var(--ac-accent);\n --ac-timeline-node-active-border: #111827;\n --ac-timeline-node-tool: #6b7280;\n --ac-timeline-node-pulse-shadow: 0 0 0 2px rgba(17, 24, 39, 1);\n\n --ac-chip-bg: #ffffff;\n --ac-chip-text: #111827;\n --ac-chip-border: #111827;\n\n --ac-code-bg: #ffffff;\n --ac-code-text: #111827;\n --ac-code-border: #111827;\n\n --ac-diff-add-bg: rgba(34, 197, 94, 0.18);\n --ac-diff-add-text: #15803d;\n --ac-diff-add-border: #111827;\n --ac-diff-del-bg: rgba(239, 68, 68, 0.18);\n --ac-diff-del-text: #b91c1c;\n --ac-diff-del-border: #111827;\n\n --ac-scrollbar-thumb: rgba(17, 24, 39, 0.25);\n --ac-scrollbar-thumb-hover: rgba(17, 24, 39, 0.4);\n }\n\n /* ========================================\n DARK CONSOLE\n ======================================== */\n .agent-theme[data-agent-theme='dark-console'] {\n --ac-font-body: var(--ac-font-mono);\n --ac-font-heading: var(--ac-font-mono);\n --ac-font-code: var(--ac-font-mono);\n\n --ac-bg: #0f1117;\n --ac-bg-pattern: none;\n --ac-bg-pattern-size: 16px 16px;\n\n --ac-header-bg: #0f1117;\n --ac-header-border: #1f2937;\n\n --ac-surface: #0f1117;\n --ac-surface-muted: #0a0c10;\n --ac-surface-inset: #1a1d26;\n\n --ac-text: #e5e7eb;\n --ac-text-muted: #9ca3af;\n --ac-text-subtle: #6b7280;\n --ac-text-inverse: #0a0c10;\n --ac-text-placeholder: #4b5563;\n\n --ac-border: #1f2937;\n --ac-border-strong: #374151;\n\n --ac-hover-bg: rgba(255, 255, 255, 0.06);\n --ac-hover-bg-subtle: rgba(255, 255, 255, 0.04);\n\n --ac-accent: #c084fc;\n --ac-accent-hover: #d8b4fe;\n --ac-accent-subtle: rgba(192, 132, 252, 0.14);\n --ac-accent-contrast: #0a0c10;\n\n --ac-accent-2: #60a5fa;\n --ac-link: var(--ac-accent-2);\n --ac-link-hover: #93c5fd;\n\n --ac-selection-bg: rgba(192, 132, 252, 0.25);\n --ac-selection-text: #ffffff;\n\n --ac-shadow-card: none;\n --ac-shadow-float: none;\n --ac-focus-ring: rgba(192, 132, 252, 0.35);\n\n --ac-timeline-line-width: 2px;\n --ac-timeline-line: #1f2937;\n --ac-timeline-node: #374151;\n --ac-timeline-node-hover: #6b7280;\n --ac-timeline-node-active: var(--ac-accent);\n --ac-timeline-node-active-border: var(--ac-accent);\n --ac-timeline-node-tool: #64748b;\n --ac-timeline-node-pulse-shadow:\n 0 0 0 2px rgba(192, 132, 252, 0.35), 0 0 14px rgba(192, 132, 252, 0.25);\n\n --ac-chip-bg: rgba(255, 255, 255, 0.06);\n --ac-chip-text: #e5e7eb;\n --ac-chip-border: rgba(255, 255, 255, 0.1);\n\n --ac-code-bg: #0a0c10;\n --ac-code-text: #e5e7eb;\n --ac-code-border: #1f2937;\n\n --ac-diff-add-bg: rgba(74, 222, 128, 0.1);\n --ac-diff-add-text: #4ade80;\n --ac-diff-add-border: rgba(74, 222, 128, 0.35);\n\n --ac-diff-del-bg: rgba(248, 113, 113, 0.1);\n --ac-diff-del-text: #f87171;\n --ac-diff-del-border: rgba(248, 113, 113, 0.35);\n\n --ac-scrollbar-thumb: rgba(255, 255, 255, 0.12);\n --ac-scrollbar-thumb-hover: rgba(255, 255, 255, 0.22);\n }\n\n /* ========================================\n SWISS GRID\n ======================================== */\n .agent-theme[data-agent-theme='swiss-grid'] {\n --ac-font-body: var(--ac-font-grotesk);\n --ac-font-heading: var(--ac-font-grotesk);\n --ac-font-code: var(--ac-font-mono);\n\n --ac-bg: #ffffff;\n --ac-bg-pattern: radial-gradient(#e5e7eb 1px, transparent 1px);\n --ac-bg-pattern-size: 16px 16px;\n\n --ac-header-bg: #ffffff;\n --ac-header-border: #000000;\n\n --ac-surface: #ffffff;\n --ac-surface-muted: #f3f4f6;\n --ac-surface-inset: #ffffff;\n\n --ac-text: #000000;\n --ac-text-muted: #374151;\n --ac-text-subtle: #6b7280;\n --ac-text-inverse: #ffffff;\n --ac-text-placeholder: #9ca3af;\n\n --ac-border: #000000;\n --ac-border-strong: #000000;\n\n --ac-hover-bg: #f3f4f6;\n --ac-hover-bg-subtle: #f9fafb;\n\n --ac-accent: #000000;\n --ac-accent-hover: #111827;\n --ac-accent-subtle: rgba(0, 0, 0, 0.06);\n --ac-accent-contrast: #ffffff;\n --ac-accent-2: #000000;\n\n --ac-link: #000000;\n --ac-link-hover: #111827;\n\n --ac-selection-bg: #000000;\n --ac-selection-text: #ffffff;\n\n --ac-border-width: 2px;\n --ac-border-width-strong: 2px;\n --ac-radius-card: 0px;\n --ac-radius-inner: 0px;\n --ac-radius-button: 0px;\n\n --ac-shadow-card: 4px 4px 0 0 rgba(0, 0, 0, 1);\n --ac-shadow-float: 4px 4px 0 0 rgba(0, 0, 0, 1);\n --ac-focus-ring: rgba(0, 0, 0, 0.5);\n\n --ac-timeline-line-width: 2px;\n --ac-timeline-line: #000000;\n --ac-timeline-node: #000000;\n --ac-timeline-node-hover: #111827;\n --ac-timeline-node-active: #000000;\n --ac-timeline-node-active-border: #000000;\n --ac-timeline-node-tool: #4b5563;\n --ac-timeline-node-pulse-shadow: 0 0 0 2px rgba(0, 0, 0, 1);\n\n --ac-chip-bg: #ffffff;\n --ac-chip-text: #000000;\n --ac-chip-border: #000000;\n\n --ac-code-bg: #ffffff;\n --ac-code-text: #000000;\n --ac-code-border: #000000;\n\n --ac-diff-add-bg: #000000;\n --ac-diff-add-text: #ffffff;\n --ac-diff-add-border: #000000;\n\n --ac-diff-del-bg: #f3f4f6;\n --ac-diff-del-text: #6b7280;\n --ac-diff-del-border: #000000;\n\n --ac-scrollbar-thumb: rgba(0, 0, 0, 0.25);\n --ac-scrollbar-thumb-hover: rgba(0, 0, 0, 0.4);\n }\n\n /* ========================================\n Base Styles (apply to .agent-theme)\n ======================================== */\n .agent-theme {\n color: var(--ac-text);\n background: var(--ac-bg);\n background-image: var(--ac-bg-pattern);\n background-size: var(--ac-bg-pattern-size);\n font-family: var(--ac-font-body);\n }\n\n .agent-theme ::selection {\n background: var(--ac-selection-bg);\n color: var(--ac-selection-text);\n }\n\n /* ========================================\n Scrollbar Styles\n ======================================== */\n .agent-theme .ac-scroll {\n scrollbar-width: thin;\n scrollbar-color: var(--ac-scrollbar-thumb) transparent;\n }\n\n .agent-theme .ac-scroll::-webkit-scrollbar {\n width: var(--ac-scrollbar-size);\n height: var(--ac-scrollbar-size);\n }\n\n .agent-theme .ac-scroll::-webkit-scrollbar-track {\n background: transparent;\n }\n\n .agent-theme .ac-scroll::-webkit-scrollbar-thumb {\n background-color: var(--ac-scrollbar-thumb);\n border-radius: 999px;\n }\n\n .agent-theme .ac-scroll::-webkit-scrollbar-thumb:hover {\n background-color: var(--ac-scrollbar-thumb-hover);\n }\n\n /* Hide scrollbar but keep functionality */\n .agent-theme .ac-scroll-hidden {\n scrollbar-width: none;\n -ms-overflow-style: none;\n }\n\n .agent-theme .ac-scroll-hidden::-webkit-scrollbar {\n display: none;\n }\n\n /* ========================================\n Utility Classes\n ======================================== */\n\n /* Focus ring */\n .agent-theme .ac-focus-ring:focus-visible {\n outline: none;\n box-shadow: 0 0 0 2px var(--ac-focus-ring);\n }\n\n /* Hover utilities */\n .agent-theme .ac-hover-bg:hover {\n background-color: var(--ac-hover-bg);\n }\n\n .agent-theme .ac-hover-text:hover {\n color: var(--ac-text);\n }\n\n .agent-theme .ac-hover-link:hover {\n color: var(--ac-link);\n }\n\n .agent-theme .ac-hover-accent:hover {\n color: var(--ac-accent);\n }\n\n /* Button/interactive element base */\n .agent-theme .ac-btn {\n cursor: pointer;\n transition:\n background-color var(--ac-motion-fast),\n color var(--ac-motion-fast);\n }\n\n .agent-theme .ac-btn:hover {\n background-color: var(--ac-hover-bg);\n }\n\n /* Menu item */\n .agent-theme .ac-menu-item {\n cursor: pointer;\n transition: background-color var(--ac-motion-fast);\n }\n\n .agent-theme .ac-menu-item:hover {\n background-color: var(--ac-hover-bg);\n }\n\n /* Chip/pill hover */\n .agent-theme .ac-chip-hover:hover {\n color: var(--ac-link);\n }\n\n /* Pulse animation for streaming indicator */\n @keyframes ac-pulse {\n 0%,\n 100% {\n opacity: 1;\n }\n 50% {\n opacity: 0.5;\n }\n }\n\n .agent-theme .ac-pulse {\n animation: ac-pulse 1.5s cubic-bezier(0.4, 0, 0.6, 1) infinite;\n }\n\n /* Respect reduced motion preference */\n @media (prefers-reduced-motion: reduce) {\n .agent-theme .ac-pulse {\n animation: none;\n }\n }\n\n /* ============================================================\n Loading Animation - Shimmer Text & Scribble Icon\n ============================================================ */\n\n /* 文案 shimmer 渐变动画 - 光从左到右扫过效果 */\n .agent-theme .text-shimmer {\n display: inline-block;\n background: linear-gradient(\n 90deg,\n var(--ac-accent, #d97757) 0%,\n var(--ac-accent, #d97757) 40%,\n #ffe0d0 50%,\n var(--ac-accent, #d97757) 60%,\n var(--ac-accent, #d97757) 100%\n );\n background-size: 250% 100%;\n background-repeat: no-repeat;\n color: transparent;\n -webkit-background-clip: text;\n background-clip: text;\n -webkit-text-fill-color: transparent;\n animation: ac-shimmer 1.8s ease-in-out infinite;\n }\n\n @keyframes ac-shimmer {\n 0% {\n background-position: 100% 50%;\n }\n 100% {\n background-position: 0% 50%;\n }\n }\n\n /* 螺旋图标 - 笔迹重绘动画 */\n .agent-theme .loading-scribble path {\n stroke-dasharray: 300;\n stroke-dashoffset: 300;\n animation: ac-scribble-draw 2s ease-in-out infinite;\n }\n\n .agent-theme .loading-scribble {\n animation: ac-slight-rotate 8s linear infinite;\n }\n\n @keyframes ac-scribble-draw {\n 0% {\n stroke-dashoffset: 300;\n }\n 50% {\n stroke-dashoffset: 0;\n }\n 100% {\n stroke-dashoffset: -300;\n }\n }\n\n @keyframes ac-slight-rotate {\n 0% {\n transform: rotate(0deg);\n }\n 100% {\n transform: rotate(360deg);\n }\n }\n\n /* Respect reduced motion preference for loading animations */\n @media (prefers-reduced-motion: reduce) {\n .agent-theme .text-shimmer {\n animation: none;\n background: none;\n color: var(--ac-accent);\n }\n\n .agent-theme .loading-scribble,\n .agent-theme .loading-scribble path {\n animation: none;\n }\n\n .agent-theme .loading-scribble path {\n stroke-dashoffset: 0;\n }\n }\n\n /* ============================================================\n Tooltip System - CSS-only tooltips using data-tooltip attribute\n ============================================================ */\n .agent-theme [data-tooltip] {\n position: relative;\n }\n\n .agent-theme [data-tooltip]::after {\n content: attr(data-tooltip);\n position: absolute;\n bottom: calc(100% + 6px);\n left: 50%;\n transform: translateX(-50%);\n padding: 4px 8px;\n font-size: 11px;\n font-family: var(--ac-font-sans);\n font-weight: 400;\n line-height: 1.3;\n white-space: nowrap;\n color: var(--ac-text-inverse);\n background-color: var(--ac-text);\n border-radius: var(--ac-radius-button);\n opacity: 0;\n visibility: hidden;\n transition:\n opacity 150ms ease,\n visibility 150ms ease;\n pointer-events: none;\n z-index: 99999;\n }\n\n .agent-theme [data-tooltip]:hover::after {\n opacity: 1;\n visibility: visible;\n }\n\n /* Tooltip arrow */\n .agent-theme [data-tooltip]::before {\n content: '';\n position: absolute;\n bottom: calc(100% + 2px);\n left: 50%;\n transform: translateX(-50%);\n border: 4px solid transparent;\n border-top-color: var(--ac-text);\n opacity: 0;\n visibility: hidden;\n transition:\n opacity 150ms ease,\n visibility 150ms ease;\n pointer-events: none;\n z-index: 99999;\n }\n\n .agent-theme [data-tooltip]:hover::before {\n opacity: 1;\n visibility: visible;\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/sidepanel/utils/loading-texts.ts", "content": "/**\n * 随机 Loading 文案\n * 用于 TimelineStatusStep 组件展示趣味等待提示\n */\n\nconst loadingTexts = [\n // 必选神梗\n '本来应该从从容容游刃有余',\n '现在是匆匆忙忙连滚带爬',\n '我知道你很急，但是先别急',\n '在知识的海洋里狗刨',\n '让子弹再飞一会儿',\n '正在为您手搓答案',\n '浪浪山小妖怪集结中',\n '别催，已经在写了（新建文件夹）',\n '正在汗流浃背地思考中',\n 'CPU 都要给我干烧了',\n // 生活气息\n '村咖慢焙，精华需要时间',\n '知识煎饼翻面中',\n '敬自己一杯，马上好',\n '正在把灵感放入烤箱',\n '让答案再泡一会儿',\n '情绪价值拉满中',\n '正在为您编织语言的毛衣',\n // 脑洞大开\n '神经元蹦迪中',\n '熬夜的猫头鹰在思考',\n '给答案上色中',\n '正在疯狂翻阅知识库',\n '大脑马戏团开演',\n '正在把 0 和 1 捏在一起',\n '正在憋个大招',\n '放大镜有点起雾，擦擦',\n '试图理解这个离谱的需求',\n // 玄幻\n '正在施法，莫打扰',\n '唤醒硅基朋友',\n '正在连接赛博空间的智慧',\n '道友请留步，正在推演',\n '穿越知识黑洞',\n '正在反向解析人类意图',\n '水晶球有点模糊，拍两下',\n // 职场\n '代码跑得比记者还快',\n '主理人已上线，请稍候',\n '快马加鞭赶来中',\n '正在光速搬运知识',\n '拼图最后一块',\n '答案即将杀青',\n '发射倒计时',\n '目标锁定中',\n];\n\n/**\n * 获取随机 Loading 文案\n */\nexport function getRandomLoadingText(): string {\n return loadingTexts[Math.floor(Math.random() * loadingTexts.length)];\n}\n" }, { "path": "app/chrome-extension/entrypoints/styles/tailwind.css", "content": "@import 'tailwindcss';\n\n/* App background and card helpers */\n@layer base {\n html,\n body,\n #app {\n height: 100%;\n }\n body {\n @apply bg-slate-50 text-slate-800;\n }\n\n /* Record&Replay builder design tokens */\n .rr-theme {\n --rr-bg: #f8fafc;\n --rr-topbar: rgba(255, 255, 255, 0.9);\n --rr-card: #ffffff;\n --rr-elevated: #ffffff;\n --rr-border: #e5e7eb;\n --rr-subtle: #f3f4f6;\n --rr-text: #0f172a;\n --rr-text-weak: #475569;\n --rr-muted: #64748b;\n --rr-brand: #7c3aed;\n --rr-brand-strong: #5b21b6;\n --rr-accent: #0ea5e9;\n --rr-success: #10b981;\n --rr-warn: #f59e0b;\n --rr-danger: #ef4444;\n --rr-dot: rgba(2, 6, 23, 0.08);\n }\n .rr-theme[data-theme='dark'] {\n --rr-bg: #0b1020;\n --rr-topbar: rgba(12, 15, 24, 0.8);\n --rr-card: #0f1528;\n --rr-elevated: #121a33;\n --rr-border: rgba(255, 255, 255, 0.08);\n --rr-subtle: rgba(255, 255, 255, 0.04);\n --rr-text: #e5e7eb;\n --rr-text-weak: #cbd5e1;\n --rr-muted: #94a3b8;\n --rr-brand: #a78bfa;\n --rr-brand-strong: #7c3aed;\n --rr-accent: #38bdf8;\n --rr-success: #34d399;\n --rr-warn: #fbbf24;\n --rr-danger: #f87171;\n --rr-dot: rgba(226, 232, 240, 0.08);\n }\n}\n\n@layer components {\n .card {\n @apply rounded-xl shadow-md border;\n background: var(--rr-card);\n border-color: var(--rr-border);\n }\n /* Generic buttons used across builder */\n .btn {\n @apply inline-flex items-center justify-center rounded-lg px-3 py-2 text-sm font-medium transition;\n background: var(--rr-card);\n color: var(--rr-text);\n border: 1px solid var(--rr-border);\n }\n .btn:hover {\n @apply shadow-sm;\n background: var(--rr-subtle);\n }\n .btn[disabled] {\n @apply opacity-60 cursor-not-allowed;\n }\n .btn.primary {\n color: #fff;\n background: var(--rr-brand-strong);\n border-color: var(--rr-brand-strong);\n }\n .btn.primary:hover {\n filter: brightness(1.05);\n }\n .btn.ghost {\n background: transparent;\n border-color: transparent;\n }\n\n .mini {\n @apply inline-flex items-center justify-center rounded-md px-2 py-1 text-xs font-medium;\n background: var(--rr-card);\n color: var(--rr-text);\n border: 1px solid var(--rr-border);\n }\n .mini:hover {\n background: var(--rr-subtle);\n }\n .mini.danger {\n background: color-mix(in oklab, var(--rr-danger) 8%, transparent);\n border-color: color-mix(in oklab, var(--rr-danger) 24%, var(--rr-border));\n color: var(--rr-text);\n }\n\n .input {\n @apply w-full px-3 py-2 rounded-lg text-sm;\n background: var(--rr-card);\n color: var(--rr-text);\n border: 1px solid var(--rr-border);\n outline: none;\n }\n .input:focus {\n box-shadow: 0 0 0 3px color-mix(in oklab, var(--rr-brand) 26%, transparent);\n border-color: var(--rr-brand);\n }\n .select {\n @apply w-full px-3 py-2 rounded-lg text-sm;\n background: var(--rr-card);\n color: var(--rr-text);\n border: 1px solid var(--rr-border);\n outline: none;\n }\n .textarea {\n @apply w-full rounded-lg text-sm;\n padding: 10px 12px;\n background: var(--rr-card);\n color: var(--rr-text);\n border: 1px solid var(--rr-border);\n outline: none;\n }\n .label {\n @apply text-sm;\n color: var(--rr-muted);\n }\n .badge {\n @apply inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium;\n }\n .badge-purple {\n background: color-mix(in oklab, var(--rr-brand) 14%, transparent);\n color: var(--rr-brand);\n }\n\n /* Builder topbar */\n .rr-topbar {\n height: 56px;\n border-bottom: 1px solid var(--rr-border);\n background: var(--rr-topbar);\n }\n\n /* Dot grid background utility for canvas container */\n .rr-dot-grid {\n background-image: radial-gradient(var(--rr-dot) 1px, transparent 1px);\n background-size: 20px 20px;\n }\n}\n" }, { "path": "app/chrome-extension/entrypoints/web-editor-v2/attr-ui-refactor.md", "content": "# Property Panel UI 重构计划\n\n## 背景\n\n当前属性面板的 UI 实现与设计稿 `attr-ui.html` 存在较大差异。本文档详细规划了重构任务，按照优先级从高到低排列，目标是让属性面板的视觉效果和交互体验与设计稿一致。\n\n### 参考文件\n\n- **设计稿**：`/attr-ui.html`\n- **当前样式**：`ui/shadow-host.ts`\n- **面板结构**：`ui/property-panel/property-panel.ts`\n- **控件组件**：`ui/property-panel/controls/*.ts`\n\n---\n\n## 前置任务（已完成）\n\n### 0.1 最小化 Bug 修复 ✅\n\n**问题**：toolbar 和属性面板最小化时，只是背景消失了，里面的内容实际上还在\n\n**根因**：CSS 中 `display: flex/inline-flex` 覆盖了 `[hidden]` 属性的默认 `display: none`\n\n**解决方案**：\n\n- [x] 在 `shadow-host.ts` 末尾添加全局 `[hidden] { display: none !important; }` 规则\n\n### 0.2 输入框优化 ✅\n\n**问题**：\n\n1. 输入框显示 placeholder 而非真实值\n2. Number 类型输入框不支持键盘上下键调整\n\n**解决方案**：\n\n- [x] 创建 `ui/property-panel/controls/number-stepping.ts` 工具模块\n - 支持 ArrowUp/ArrowDown 键盘步进\n - 支持 Shift (10x)、Alt (0.1x) 修饰键\n - 支持多种 CSS 单位 (px, %, rem, em, vh, vw, vmin, vmax)\n- [x] 修改所有 control 显示真实值（inline 优先，fallback 到 computed）\n- [x] 为所有数值输入框添加 keyboard stepping 支持：\n - `size-control.ts` - Width/Height\n - `spacing-control.ts` - Margin/Padding\n - `position-control.ts` - Top/Right/Bottom/Left/Z-Index\n - `layout-control.ts` - Gap\n - `typography-control.ts` - Font Size/Line Height\n - `appearance-control.ts` - Opacity/Border Radius/Border Width\n\n---\n\n## 阶段一：基础视觉系统对齐 ✅ 已完成\n\n### 1.1 颜色方案重构 ✅\n\n**目标**：将颜色系统从当前的灰色调整为设计稿的白底+灰输入框风格\n\n| 属性 | 旧值 | 新值 | 状态 |\n| ------------ | ----------------- | --------------------------------- | ---- |\n| 面板背景 | `#f8f8f8` | `#ffffff` | ✅ |\n| 输入框背景 | `#f0f0f0` | `#f3f3f3` | ✅ |\n| 输入框 hover | `#e8e8e8` (bg) | `border #e0e0e0` (inset) | ✅ |\n| 输入框 focus | `box-shadow` 外圈 | `inset 2px border #3b82f6` + 白底 | ✅ |\n| 边框色 | `#e8e8e8` | `#e5e5e5` | ✅ |\n\n**完成的任务**：\n\n- [x] 更新 CSS 变量定义 (`shadow-host.ts:56-97`)\n- [x] 修改输入框 hover/focus 样式为 inset border 模式\n- [x] 面板背景改为纯白\n\n### 1.2 字体与字号调整 ✅\n\n| 属性 | 旧值 | 新值 | 状态 |\n| ------------ | -------- | ------------------------- | ---- |\n| 面板基础字号 | `13px` | `11px` | ✅ |\n| 标签字号 | `11px` | `10px` | ✅ |\n| 输入框字号 | `12px` | `11px` | ✅ |\n| 字体家族 | 系统字体 | Inter + 系统字体 fallback | ✅ |\n\n**完成的任务**：\n\n- [x] 添加 Inter 字体声明（使用系统字体 fallback）\n- [x] 调整面板、标签、输入框的字号\n- [x] 移除标签的大写样式\n\n### 1.3 间距与边距调整 ✅\n\n| 属性 | 旧值 | 新值 | 状态 |\n| ------------- | ----------- | ---------- | ---- |\n| 面板宽度 | `320px` | `280px` | ✅ |\n| Header 内边距 | `10px 14px` | `8px 12px` | ✅ |\n| Body gap | `10px` | `12px` | ✅ |\n\n**完成的任务**：\n\n- [x] 调整 `.we-panel`, `.we-prop-body`, `.we-field-group` 的 padding/gap\n- [x] 调整 header 的 padding\n\n### 1.4 圆角与阴影 ✅\n\n| 属性 | 旧值 | 新值 | 状态 |\n| ---------- | ----------- | ------------------ | ---- |\n| 面板阴影 | `0 1px 2px` | Tailwind shadow-xl | ✅ |\n| 输入框圆角 | `6px` | `4px` | ✅ |\n| Tab 阴影 | 无 | `shadow-sm` | ✅ |\n\n**完成的任务**：\n\n- [x] 增强面板阴影效果（双层阴影模拟 shadow-xl）\n- [x] 调整输入框圆角为 4px\n- [x] 为激活的 Tab 添加阴影\n\n### 1.5 Group/Section 样式重构 ✅\n\n| 属性 | 旧样式 | 新样式 | 状态 |\n| ------------ | ----------- | ----------- | ---- |\n| Group 边框 | 卡片边框 | 无边框 | ✅ |\n| Section 分隔 | 无 | 顶部分隔线 | ✅ |\n| Header 样式 | 粗体 + 大字 | 11px + #333 | ✅ |\n\n**完成的任务**：\n\n- [x] 移除 `.we-group` 的边框和背景\n- [x] 添加 Section 间的分隔线 (`border-top`)\n- [x] 调整 Group header 样式\n\n---\n\n## 阶段二：输入容器组件重构 ✅ 基础完成\n\n### 2.1 建立输入容器系统 ✅\n\n**背景**：设计稿的输入框不是单体 input，而是一个容器系统，支持：\n\n- 前缀（prefix）：标签、图标\n- 后缀（suffix）：单位、图标\n- 容器驱动的 hover/focus 样式\n\n**当前结构**：\n\n```html\n
\n Width\n \n
\n```\n\n**目标结构**：\n\n```html\n
\n Position\n
\n \n X\n \n \n px\n \n
\n
\n```\n\n**已完成**：\n\n- [x] 在 `shadow-host.ts` 中定义 `.we-input-container` 样式\n- [x] 定义 `.we-input-container__prefix` 和 `.we-input-container__suffix` 样式\n- [x] 创建 `ui/property-panel/components/input-container.ts` 组件\n- [x] 将 hover/focus 样式移到容器级别（使用 `:focus-within`）\n\n### 2.2 更新各 Control 使用新容器 ✅ 已完成\n\n**需要更新的控件**：\n\n- [x] `size-control.ts` - Width/Height（2列布局 + W/H 前缀 + 动态单位后缀）\n- [x] `spacing-control.ts` - Margin/Padding（重构为 2x2 网格 + 方向图标 + 动态单位后缀）\n- [x] `position-control.ts` - Top/Right/Bottom/Left/Z-Index（T/R/B/L 前缀 + 动态单位后缀）\n- [x] `layout-control.ts` - Gap（图标前缀 + 动态单位后缀）\n- [x] `typography-control.ts` - Font Size/Line Height（动态单位后缀，line-height 智能显示）\n- [ ] `appearance-control.ts` - Opacity/Border Radius/Border Width（待实施）\n\n**已完成的共享模块**：\n\n- [x] 创建 `css-helpers.ts` 共享模块（extractUnitSuffix, hasExplicitUnit, normalizeLength）\n- [x] 所有控件使用共享 helper，消除重复代码\n\n---\n\n## 阶段三：Section 结构重构（待实施）\n\n### 3.1 Tab 信息架构调整\n\n**当前**：4 个 Tab（Design/CSS/Props/DOM）\n**设计稿**：2 个 Tab（Design/CSS）\n\n**方案选择**：\n\n- **方案 A**：保留 4 个 Tab，调整为溢出菜单\n- **方案 B**：将 Props/DOM 移到其他入口\n- **方案 C**：保持 4 个 Tab，调整样式适应\n\n**任务**：\n\n- [ ] 确定 Tab 数量的产品决策\n- [ ] 实现选定方案\n\n---\n\n## 阶段四：功能组件实现（待实施）\n\n### 4.1 Flow 布局图标组 ✅ 已完成\n\n**设计稿位置**：`attr-ui.html:133-156`\n**功能**：4 个图标按钮控制 `flex-direction`\n\n```\n[→] Row\n[↓] Column\n[←] Row Reverse\n[↑] Column Reverse\n```\n\n**已完成**：\n\n- [x] 创建 `ui/property-panel/components/icon-button-group.ts` 通用组件\n- [x] 在 `shadow-host.ts` 中添加 `.we-icon-button-group` 样式\n- [x] 在 `layout-control.ts` 中用图标组替换 Direction select\n- [x] 添加对应的 SVG 箭头图标（row/column/row-reverse/column-reverse）\n\n### 4.2 Alignment 九宫格 ✅ 已完成\n\n**设计稿位置**：`attr-ui.html:166-208`\n**功能**：3x3 网格控制 `justify-content` + `align-items`\n\n```\n[↖][↑][↗]\n[←][·][→]\n[↙][↓][↘]\n```\n\n**已完成**：\n\n- [x] 创建 `ui/property-panel/components/alignment-grid.ts` 组件\n- [x] 在 `shadow-host.ts` 中添加 `.we-alignment-grid` 样式\n- [x] 替换 `layout-control.ts` 中的 Justify/Align select\n- [x] 使用 `beginMultiStyle` 实现两个属性的原子提交\n\n### 4.3 修复 Color Picker ✅ 部分完成\n\n**当前问题**：\n\n- `showPicker()` 无 try/catch，可能抛错\n- alpha 通道被丢弃\n- token 值 `var(--xxx)` 显示不正确\n\n**已完成**：\n\n- [x] 添加 `showPicker()` 的错误处理（try/catch + fallback to click）\n- [x] 改进 `var()` 值的解析和显示（通过 placeholder 传入 computed value）\n\n**待实施**：\n\n- [ ] 支持 alpha 通道（RGBA/HSLA）- 需要引入第三方 color picker\n- [ ] 考虑引入第三方 color picker（如 `@simonwep/pickr`）\n\n---\n\n## 阶段五：新功能模块（待实施）\n\n### 5.1 Shadow & Blur 控制\n\n**设计稿位置**：`attr-ui.html:396-425`\n**功能**：\n\n- 启用/禁用开关\n- 类型选择（Drop shadow/Inner shadow/Layer Blur/Backdrop Blur）\n- 可见性控制\n\n**CSS 属性**：\n\n- `box-shadow`\n- `filter: blur()`\n- `backdrop-filter: blur()`\n\n**任务**：\n\n- [x] 创建 `ui/property-panel/controls/effects-control.ts`\n- [x] 实现 `box-shadow` 值解析和编辑\n- [x] 实现 `filter` 值解析和编辑\n- [x] 实现 `backdrop-filter` 值解析和编辑\n- [x] 添加类型切换 UI\n- [ ] 添加启用/禁用开关（可选，后续实现）\n\n### 5.2 渐变编辑器\n\n**设计稿位置**：`attr-ui.html:269-325`\n**功能**：\n\n- Linear/Radial 渐变类型\n- 颜色停止点（color stops）\n- 角度控制\n- 翻转按钮\n\n**CSS 属性**：\n\n- `background-image: linear-gradient(...)`\n- `background-image: radial-gradient(...)`\n\n**任务**：\n\n- [x] 创建 `ui/property-panel/controls/gradient-control.ts`\n- [x] 实现渐变值解析（CSS gradient → 数据结构）\n- [x] 实现角度/位置输入\n- [x] 实现 2 个颜色停止点的编辑\n- [x] 集成到 property-panel（作为独立的 Gradient 控制组）\n- [ ] 实现渐变预览 slider（可选，后续优化）\n- [ ] 实现 color stop 添加/删除/拖拽（可选，后续优化）\n\n### 5.3 Token/变量 Pill 显示\n\n**设计稿位置**：`attr-ui.html:374-384`\n**功能**：当值为 CSS 变量时，显示为可点击的 pill\n\n**任务**：\n\n- [ ] 检测 `var(--xxx)` 值\n- [ ] 渲染为 pill 样式\n- [ ] 点击打开 token picker\n\n---\n\n## 阶段六：代码质量（贯穿始终）\n\n### 6.1 样式系统统一\n\n- [x] 所有颜色使用 CSS 变量（阶段一完成）\n- [ ] 所有尺寸使用一致的 token\n- [ ] 移除 inline style，统一到 `shadow-host.ts`\n\n### 6.2 组件复用\n\n- [ ] 提取通用组件到 `ui/property-panel/components/`\n- [ ] 统一事件处理模式\n- [ ] 统一 disabled/enabled 状态处理\n\n### 6.3 类型安全\n\n- [ ] 所有组件使用 TypeScript 严格类型\n- [ ] 定义清晰的接口和类型\n- [ ] 移除 any 类型断言\n\n---\n\n## 实施进度\n\n| 阶段 | 任务 | 状态 | 备注 |\n| ---- | ------------------ | ------- | -------------------------------------------- |\n| 0.1 | 最小化 Bug 修复 | ✅ | 添加全局 `[hidden]` 规则 |\n| 0.2 | 输入框优化 | ✅ | number-stepping + 真实值显示 |\n| 1.1 | 颜色方案重构 | ✅ | 白底 + 灰输入框 + inset focus |\n| 1.2 | 字体与字号调整 | ✅ | 11px 基准 + Inter 字体 |\n| 1.3 | 间距与边距调整 | ✅ | 更紧凑的布局 |\n| 1.4 | 圆角与阴影 | ✅ | shadow-xl + 4px 圆角 |\n| 1.5 | Group/Section 样式 | ✅ | 分隔线风格 |\n| 2.1 | 输入容器系统 | ✅ | 组件 + CSS 样式 |\n| 2.2 | 更新 Controls | ✅ | 所有主要控件已迁移，共享 css-helpers.ts |\n| 3.1 | Tab 信息架构 | 待实施 | |\n| 4.1 | Flow 图标组 | ✅ | icon-button-group.ts + 集成到 layout-control |\n| 4.2 | Alignment 九宫格 | ✅ | alignment-grid.ts + 集成到 layout-control |\n| 4.3 | 修复 Color Picker | ✅ 部分 | showPicker 异常处理 + var() 解析 |\n| 5.1 | Shadow & Blur | ✅ | effects-control.ts + 集成到 property-panel |\n| 5.2 | 渐变编辑器 | ✅ | gradient-control.ts + 集成到 property-panel |\n| 5.3 | Token Pill | 待实施 | |\n\n---\n\n## 注意事项\n\n1. **渐进式实施**：每个 Phase 完成后应可独立测试和发布\n2. **保持向后兼容**：重构过程中不应破坏现有功能\n3. **设计决策记录**：遇到设计稿与实际需求冲突时，记录决策原因\n4. **性能考虑**：新增组件需考虑渲染性能，避免不必要的 DOM 操作\n" }, { "path": "app/chrome-extension/entrypoints/web-editor-v2/constants.ts", "content": "/**\n * Web Editor V2 Constants\n *\n * Centralized configuration values for the visual editor.\n * All magic strings/numbers should be defined here.\n */\n\n/** Editor version number */\nexport const WEB_EDITOR_V2_VERSION = 2 as const;\n\n/** Log prefix for console messages */\nexport const WEB_EDITOR_V2_LOG_PREFIX = '[WebEditorV2]' as const;\n\n// =============================================================================\n// DOM Element IDs\n// =============================================================================\n\n/** Shadow host element ID */\nexport const WEB_EDITOR_V2_HOST_ID = '__mcp_web_editor_v2_host__';\n\n/** Overlay container ID (for Canvas and visual feedback) */\nexport const WEB_EDITOR_V2_OVERLAY_ID = '__mcp_web_editor_v2_overlay__';\n\n/** UI container ID (for panels and controls) */\nexport const WEB_EDITOR_V2_UI_ID = '__mcp_web_editor_v2_ui__';\n\n// =============================================================================\n// Styling\n// =============================================================================\n\n/** Maximum z-index to ensure editor is always on top */\nexport const WEB_EDITOR_V2_Z_INDEX = 2147483647;\n\n/** Default panel width */\nexport const WEB_EDITOR_V2_PANEL_WIDTH = 320;\n\n// =============================================================================\n// Colors (Design System)\n// =============================================================================\n\nexport const WEB_EDITOR_V2_COLORS = {\n /** Hover highlight color */\n hover: '#3b82f6', // blue-500\n /** Selected element color */\n selected: '#22c55e', // green-500\n /** Selection box border */\n selectionBorder: '#6366f1', // indigo-500\n /** Drag ghost color */\n dragGhost: 'rgba(99, 102, 241, 0.3)',\n /** Insertion line color */\n insertionLine: '#f59e0b', // amber-500\n /** Alignment guide line color (snap guides) */\n guideLine: '#ec4899', // pink-500\n /** Distance label background (Phase 4.3) */\n distanceLabelBg: 'rgba(15, 23, 42, 0.92)', // slate-900 @ 92%\n /** Distance label border (Phase 4.3) */\n distanceLabelBorder: 'rgba(51, 65, 85, 0.5)', // slate-600 @ 50%\n /** Distance label text (Phase 4.3) */\n distanceLabelText: 'rgba(255, 255, 255, 0.98)',\n} as const;\n\n// =============================================================================\n// Drag Reorder (Phase 2.4-2.6)\n// =============================================================================\n\n/** Minimum pointer movement (px) to start dragging */\nexport const WEB_EDITOR_V2_DRAG_THRESHOLD_PX = 5;\n\n/** Hysteresis (px) for stable before/after decision to avoid flip-flop */\nexport const WEB_EDITOR_V2_DRAG_HYSTERESIS_PX = 6;\n\n/** Max elements to inspect per hit-test (elementsFromPoint) */\nexport const WEB_EDITOR_V2_DRAG_MAX_HIT_ELEMENTS = 8;\n\n/** Insertion indicator line width in CSS pixels */\nexport const WEB_EDITOR_V2_INSERTION_LINE_WIDTH = 3;\n\n// =============================================================================\n// Snapping & Alignment Guides (Phase 4.2)\n// =============================================================================\n\n/** Snap threshold in CSS pixels - distance at which snapping activates */\nexport const WEB_EDITOR_V2_SNAP_THRESHOLD_PX = 6;\n\n/** Hysteresis in CSS pixels - keeps snap stable near boundary to prevent flicker */\nexport const WEB_EDITOR_V2_SNAP_HYSTERESIS_PX = 2;\n\n/** Maximum sibling elements to consider for snapping (nearest first) */\nexport const WEB_EDITOR_V2_SNAP_MAX_ANCHOR_ELEMENTS = 30;\n\n/** Maximum siblings to scan before applying distance filter */\nexport const WEB_EDITOR_V2_SNAP_MAX_SIBLINGS_SCAN = 300;\n\n/** Alignment guide line width in CSS pixels */\nexport const WEB_EDITOR_V2_GUIDE_LINE_WIDTH = 1;\n\n// =============================================================================\n// Distance Labels (Phase 4.3)\n// =============================================================================\n\n/** Minimum distance (px) to display a label - hides 0 and sub-pixel gaps */\nexport const WEB_EDITOR_V2_DISTANCE_LABEL_MIN_PX = 1;\n\n/** Measurement line width in CSS pixels */\nexport const WEB_EDITOR_V2_DISTANCE_LINE_WIDTH = 1;\n\n/** Tick size at the ends of measurement lines (CSS pixels) */\nexport const WEB_EDITOR_V2_DISTANCE_TICK_SIZE = 4;\n\n/** Font used for distance label pills */\nexport const WEB_EDITOR_V2_DISTANCE_LABEL_FONT =\n '600 11px system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif';\n\n/** Horizontal padding inside distance label pill (CSS pixels) */\nexport const WEB_EDITOR_V2_DISTANCE_LABEL_PADDING_X = 6;\n\n/** Vertical padding inside distance label pill (CSS pixels) */\nexport const WEB_EDITOR_V2_DISTANCE_LABEL_PADDING_Y = 3;\n\n/** Border radius for distance label pill (CSS pixels) */\nexport const WEB_EDITOR_V2_DISTANCE_LABEL_RADIUS = 4;\n\n/** Offset from the measurement line to place the pill (CSS pixels) */\nexport const WEB_EDITOR_V2_DISTANCE_LABEL_OFFSET = 8;\n" }, { "path": "app/chrome-extension/entrypoints/web-editor-v2/core/css-compare.ts", "content": "/**\n * CSS Compare Utilities (Phase 4.8)\n *\n * Provides robust CSS value comparison for HMR consistency verification.\n *\n * Design goals:\n * - Compare computed style values (format-agnostic: \"1rem\" vs \"16px\" both resolve to same computed value)\n * - Handle numeric tolerance for px-based values and transform matrices\n * - Provide detailed diff information for UI feedback\n *\n * Why computed styles?\n * - Editor mutates live DOM via inline styles for immediate preview\n * - Agent may persist changes via classes/CSS modules/Tailwind, not inline styles\n * - Comparing computed values avoids false mismatches from authoring format differences\n */\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Detailed diff for a single CSS property */\nexport interface ComputedDiffItem {\n /** CSS property name */\n readonly property: string;\n /** Expected value (from baseline) */\n readonly expected: string;\n /** Actual value (from current DOM) */\n readonly actual: string;\n /** Whether values match */\n readonly match: boolean;\n /** How comparison was determined */\n readonly reason?: 'exact' | 'px_epsilon' | 'matrix_epsilon' | 'string';\n}\n\n/** Result of comparing two computed style maps */\nexport interface CompareComputedResult {\n /** Overall match status */\n readonly matches: boolean;\n /** Per-property diff details */\n readonly diffs: readonly ComputedDiffItem[];\n}\n\n/** Options for CSS value comparison */\nexport interface CompareComputedOptions {\n /**\n * Epsilon for px-based numeric comparison.\n * Defaults to 0.5 to tolerate sub-pixel jitter from rounding.\n */\n readonly pxEpsilon?: number;\n /**\n * Epsilon for matrix()/matrix3d() numeric comparison.\n * Defaults to 1e-3 for floating-point precision tolerance.\n */\n readonly matrixEpsilon?: number;\n}\n\n// =============================================================================\n// Constants\n// =============================================================================\n\nconst DEFAULT_PX_EPSILON = 0.5;\nconst DEFAULT_MATRIX_EPSILON = 1e-3;\n\n// Regex patterns (defined once for performance)\nconst PX_VALUE_REGEX = /(-?\\d*\\.?\\d+(?:e[+-]?\\d+)?)px/gi;\nconst MATRIX_NUMBER_REGEX = /-?\\d*\\.?\\d+(?:e[+-]?\\d+)?/gi;\n\n// =============================================================================\n// Public API\n// =============================================================================\n\n/**\n * Normalize text content for robust comparison.\n * Collapses whitespace and trims edges.\n */\nexport function normalizeText(text: string): string {\n return String(text ?? '')\n .replace(/\\s+/g, ' ')\n .trim();\n}\n\n/**\n * Read computed style values for specified CSS properties.\n *\n * @param element - Target element\n * @param properties - CSS property names to read\n * @returns Map of property name to computed value (normalized)\n */\nexport function readComputedMap(\n element: Element,\n properties: readonly string[],\n): Record {\n const result: Record = {};\n\n // Deduplicate and filter empty property names\n const uniqueProps: string[] = [];\n const seen = new Set();\n for (const raw of properties) {\n const prop = String(raw ?? '').trim();\n if (!prop || seen.has(prop)) continue;\n seen.add(prop);\n uniqueProps.push(prop);\n }\n\n // Safely get computed style declaration\n let computed: CSSStyleDeclaration | null = null;\n try {\n computed = window.getComputedStyle(element);\n } catch {\n // Element may not be attached to DOM or other edge cases\n computed = null;\n }\n\n // Read each property\n for (const property of uniqueProps) {\n let value = '';\n try {\n value = computed?.getPropertyValue(property) ?? '';\n } catch {\n value = '';\n }\n result[property] = normalizeCssValue(value);\n }\n\n return result;\n}\n\n/**\n * Compare two computed style maps with numeric tolerance.\n *\n * Comparison strategy:\n * 1. Exact string match → pass\n * 2. matrix()/matrix3d() numeric tolerance → pass if within epsilon\n * 3. px-based numeric tolerance → pass if same shape and within epsilon\n * 4. Otherwise → fail\n *\n * @param expected - Baseline computed values\n * @param actual - Current computed values\n * @param options - Comparison options\n * @returns Comparison result with per-property diffs\n */\nexport function compareComputed(\n expected: Readonly>,\n actual: Readonly>,\n options: CompareComputedOptions = {},\n): CompareComputedResult {\n const pxEps = Number.isFinite(options.pxEpsilon) ? options.pxEpsilon! : DEFAULT_PX_EPSILON;\n const matrixEps = Number.isFinite(options.matrixEpsilon)\n ? options.matrixEpsilon!\n : DEFAULT_MATRIX_EPSILON;\n\n const diffs: ComputedDiffItem[] = [];\n\n for (const property of Object.keys(expected)) {\n const exp = normalizeCssValue(expected[property] ?? '');\n const act = normalizeCssValue(actual[property] ?? '');\n\n const { match, reason } = compareSingleValue(exp, act, pxEps, matrixEps);\n diffs.push({ property, expected: exp, actual: act, match, reason });\n }\n\n const matches = diffs.every((d) => d.match);\n return { matches, diffs };\n}\n\n// =============================================================================\n// Internal Helpers\n// =============================================================================\n\n/**\n * Normalize a CSS value string for consistent comparison.\n * Collapses whitespace and normalizes spacing around punctuation.\n */\nfunction normalizeCssValue(raw: string): string {\n return String(raw ?? '')\n .replace(/\\s+/g, ' ') // Collapse whitespace\n .replace(/,\\s+/g, ',') // Remove space after commas\n .replace(/\\(\\s+/g, '(') // Remove space after open paren\n .replace(/\\s+\\)/g, ')') // Remove space before close paren\n .trim();\n}\n\n/**\n * Check if two numbers are approximately equal within epsilon.\n */\nfunction approximatelyEqual(a: number, b: number, epsilon: number): boolean {\n return Math.abs(a - b) <= epsilon;\n}\n\n/**\n * Check if value looks like a CSS matrix transform.\n */\nfunction isMatrixValue(value: string): boolean {\n const lower = value.toLowerCase();\n return lower.startsWith('matrix(') || lower.startsWith('matrix3d(');\n}\n\n/**\n * Extract numeric components from a matrix() or matrix3d() value.\n * Returns null if not a valid matrix or contains invalid numbers.\n */\nfunction extractMatrixNumbers(value: string): number[] | null {\n if (!isMatrixValue(value)) return null;\n\n const matches = value.match(MATRIX_NUMBER_REGEX);\n if (!matches || matches.length === 0) return null;\n\n const nums: number[] = [];\n for (const m of matches) {\n const n = Number(m);\n if (!Number.isFinite(n)) return null;\n nums.push(n);\n }\n\n return nums.length > 0 ? nums : null;\n}\n\n/**\n * Extract px numeric values from a CSS value string.\n * Returns null if no px values found or contains invalid numbers.\n */\nfunction extractPxNumbers(value: string): number[] | null {\n const nums: number[] = [];\n\n // Reset regex state (global flag requires this)\n PX_VALUE_REGEX.lastIndex = 0;\n\n let match: RegExpExecArray | null;\n while ((match = PX_VALUE_REGEX.exec(value)) !== null) {\n const n = Number(match[1]);\n if (!Number.isFinite(n)) return null;\n nums.push(n);\n }\n\n return nums.length > 0 ? nums : null;\n}\n\n/**\n * Get the \"shape\" of a px-based value by replacing numeric values with placeholders.\n * Used to ensure we're comparing structurally similar values.\n */\nfunction pxValueShape(value: string): string {\n // Reset regex state\n PX_VALUE_REGEX.lastIndex = 0;\n return normalizeCssValue(value).replace(PX_VALUE_REGEX, '#px');\n}\n\n/**\n * Compare two matrix values with numeric tolerance.\n */\nfunction compareMatrixWithEpsilon(expected: string, actual: string, epsilon: number): boolean {\n const expNums = extractMatrixNumbers(expected);\n const actNums = extractMatrixNumbers(actual);\n\n if (!expNums || !actNums) return false;\n if (expNums.length !== actNums.length) return false;\n\n // Ensure both are same type (matrix vs matrix3d)\n const expKind = expected.toLowerCase().startsWith('matrix3d(') ? 'matrix3d' : 'matrix';\n const actKind = actual.toLowerCase().startsWith('matrix3d(') ? 'matrix3d' : 'matrix';\n if (expKind !== actKind) return false;\n\n // Compare each component with epsilon\n for (let i = 0; i < expNums.length; i++) {\n if (!approximatelyEqual(expNums[i]!, actNums[i]!, epsilon)) return false;\n }\n\n return true;\n}\n\n/**\n * Compare two px-based values with numeric tolerance.\n */\nfunction comparePxWithEpsilon(expected: string, actual: string, epsilon: number): boolean {\n const expNums = extractPxNumbers(expected);\n const actNums = extractPxNumbers(actual);\n\n if (!expNums || !actNums) return false;\n if (expNums.length !== actNums.length) return false;\n\n // Ensure values have same structure (e.g., \"10px 20px\" vs \"10px 20px\", not \"10px\" vs \"10px solid\")\n if (pxValueShape(expected) !== pxValueShape(actual)) return false;\n\n // Compare each px value with epsilon\n for (let i = 0; i < expNums.length; i++) {\n if (!approximatelyEqual(expNums[i]!, actNums[i]!, epsilon)) return false;\n }\n\n return true;\n}\n\n/**\n * Compare a single CSS value pair with all available strategies.\n */\nfunction compareSingleValue(\n expected: string,\n actual: string,\n pxEpsilon: number,\n matrixEpsilon: number,\n): { match: boolean; reason: ComputedDiffItem['reason'] } {\n // 1. Exact string match (fastest path)\n if (expected === actual) {\n return { match: true, reason: 'exact' };\n }\n\n // 2. Matrix tolerance comparison\n if (isMatrixValue(expected) && isMatrixValue(actual)) {\n if (compareMatrixWithEpsilon(expected, actual, matrixEpsilon)) {\n return { match: true, reason: 'matrix_epsilon' };\n }\n }\n\n // 3. Px tolerance comparison\n const expHasPx = PX_VALUE_REGEX.test(expected);\n PX_VALUE_REGEX.lastIndex = 0; // Reset after test\n const actHasPx = PX_VALUE_REGEX.test(actual);\n PX_VALUE_REGEX.lastIndex = 0; // Reset after test\n\n if (expHasPx && actHasPx) {\n if (comparePxWithEpsilon(expected, actual, pxEpsilon)) {\n return { match: true, reason: 'px_epsilon' };\n }\n }\n\n // 4. No match\n return { match: false, reason: 'string' };\n}\n" }, { "path": "app/chrome-extension/entrypoints/web-editor-v2/core/cssom-styles-collector.ts", "content": "/**\n * CSSOM Styles Collector (Phase 4.6)\n *\n * Provides CSS rule collection and cascade computation using CSSOM.\n * Used for the CSS panel's style source tracking feature.\n *\n * Design goals:\n * - Collect matched CSS rules for an element via CSSOM\n * - Compute cascade (specificity + source order + !important)\n * - Track inherited styles from ancestor elements\n * - Handle Shadow DOM stylesheets\n * - Produce UI-ready snapshot for rendering\n *\n * Limitations (CSSOM-only approach):\n * - No reliable file:line info (only href/label available)\n * - @container/@scope rules are not evaluated\n * - @layer ordering is approximated via source order\n */\n\n// =============================================================================\n// Public Types (UI-ready snapshot)\n// =============================================================================\n\nexport type Specificity = readonly [inline: number, ids: number, classes: number, types: number];\n\nexport type DeclStatus = 'active' | 'overridden';\n\nexport interface CssRuleSource {\n url?: string;\n label: string;\n}\n\nexport interface CssDeclView {\n id: string;\n name: string;\n value: string;\n important: boolean;\n affects: readonly string[];\n status: DeclStatus;\n}\n\nexport interface CssRuleView {\n id: string;\n origin: 'inline' | 'rule';\n selector: string;\n matchedSelector?: string;\n specificity?: Specificity;\n source?: CssRuleSource;\n order: number;\n decls: CssDeclView[];\n}\n\nexport interface CssSectionView {\n kind: 'inline' | 'matched' | 'inherited';\n title: string;\n inheritedFrom?: { label: string };\n rules: CssRuleView[];\n}\n\nexport interface CssPanelSnapshot {\n target: {\n label: string;\n root: 'document' | 'shadow';\n };\n warnings: string[];\n stats: {\n roots: number;\n styleSheets: number;\n rulesScanned: number;\n matchedRules: number;\n };\n sections: CssSectionView[];\n}\n\n// =============================================================================\n// Internal Types (cascade + collection)\n// =============================================================================\n\ninterface DeclCandidate {\n id: string;\n important: boolean;\n specificity: Specificity;\n sourceOrder: readonly [sheetIndex: number, ruleOrder: number, declIndex: number];\n property: string;\n value: string;\n affects: readonly string[];\n ownerRuleId: string;\n ownerElementId: number;\n}\n\ninterface FlatStyleRule {\n sheetIndex: number;\n order: number;\n selectorText: string;\n style: CSSStyleDeclaration;\n source: CssRuleSource;\n}\n\ninterface RuleIndex {\n root: Document | ShadowRoot;\n rootId: number;\n flatRules: FlatStyleRule[];\n warnings: string[];\n stats: { styleSheets: number; rulesScanned: number };\n}\n\ninterface CollectElementOptions {\n includeInline: boolean;\n declFilter: (decl: { property: string; affects: readonly string[] }) => boolean;\n}\n\ninterface CollectedElementRules {\n element: Element;\n elementId: number;\n root: Document | ShadowRoot;\n rootType: 'document' | 'shadow';\n inlineRule: CssRuleView | null;\n matchedRules: CssRuleView[];\n candidates: DeclCandidate[];\n warnings: string[];\n stats: { matchedRules: number };\n}\n\n// =============================================================================\n// Specificity (Selectors Level 4)\n// =============================================================================\n\nconst ZERO_SPEC: Specificity = [0, 0, 0, 0] as const;\n\nexport function compareSpecificity(a: Specificity, b: Specificity): number {\n for (let i = 0; i < 4; i++) {\n if (a[i] !== b[i]) return a[i] > b[i] ? 1 : -1;\n }\n return 0;\n}\n\nfunction splitSelectorList(input: string): string[] {\n const out: string[] = [];\n let start = 0;\n let depthParen = 0;\n let depthBrack = 0;\n let quote: \"'\" | '\"' | null = null;\n\n for (let i = 0; i < input.length; i++) {\n const ch = input[i];\n\n if (quote) {\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n if (ch === quote) quote = null;\n continue;\n }\n\n if (ch === '\"' || ch === \"'\") {\n quote = ch;\n continue;\n }\n\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n\n if (ch === '[') depthBrack += 1;\n else if (ch === ']' && depthBrack > 0) depthBrack -= 1;\n else if (ch === '(') depthParen += 1;\n else if (ch === ')' && depthParen > 0) depthParen -= 1;\n\n if (ch === ',' && depthParen === 0 && depthBrack === 0) {\n const part = input.slice(start, i).trim();\n if (part) out.push(part);\n start = i + 1;\n }\n }\n\n const tail = input.slice(start).trim();\n if (tail) out.push(tail);\n return out;\n}\n\nfunction maxSpecificity(list: readonly Specificity[]): Specificity {\n let best: Specificity = ZERO_SPEC;\n for (const s of list) if (compareSpecificity(s, best) > 0) best = s;\n return best;\n}\n\nfunction computeSelectorSpecificity(selector: string): Specificity {\n let ids = 0;\n let classes = 0;\n let types = 0;\n\n let expectType = true;\n\n for (let i = 0; i < selector.length; i++) {\n const ch = selector[i];\n\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n\n if (ch === '[') {\n classes += 1;\n i = consumeBracket(selector, i);\n expectType = false;\n continue;\n }\n\n if (isCombinatorOrWhitespace(selector, i)) {\n i = consumeWhitespaceAndCombinators(selector, i);\n expectType = true;\n continue;\n }\n\n if (ch === '#') {\n ids += 1;\n i = consumeIdent(selector, i + 1) - 1;\n expectType = false;\n continue;\n }\n\n if (ch === '.') {\n classes += 1;\n i = consumeIdent(selector, i + 1) - 1;\n expectType = false;\n continue;\n }\n\n if (ch === ':') {\n const isPseudoEl = selector[i + 1] === ':';\n if (isPseudoEl) {\n types += 1;\n const nameStart = i + 2;\n const nameEnd = consumeIdent(selector, nameStart);\n const name = selector.slice(nameStart, nameEnd).toLowerCase();\n i = nameEnd - 1;\n\n if (selector[i + 1] === '(' && name === 'slotted') {\n const { content, endIndex } = consumeParenFunction(selector, i + 1);\n const maxArg = maxSpecificity(splitSelectorList(content).map(computeSelectorSpecificity));\n ids += maxArg[1];\n classes += maxArg[2];\n types += maxArg[3];\n i = endIndex;\n }\n\n expectType = false;\n continue;\n }\n\n const nameStart = i + 1;\n const nameEnd = consumeIdent(selector, nameStart);\n const name = selector.slice(nameStart, nameEnd).toLowerCase();\n\n if (LEGACY_PSEUDO_ELEMENTS.has(name)) {\n types += 1;\n i = nameEnd - 1;\n expectType = false;\n continue;\n }\n\n if (selector[nameEnd] === '(') {\n const { content, endIndex } = consumeParenFunction(selector, nameEnd);\n i = endIndex;\n\n if (name === 'where') {\n expectType = false;\n continue;\n }\n\n if (name === 'is' || name === 'not' || name === 'has') {\n const maxArg = maxSpecificity(splitSelectorList(content).map(computeSelectorSpecificity));\n ids += maxArg[1];\n classes += maxArg[2];\n types += maxArg[3];\n expectType = false;\n continue;\n }\n\n if (name === 'nth-child' || name === 'nth-last-child') {\n classes += 1;\n const ofSelectors = extractNthOfSelectorList(content);\n if (ofSelectors) {\n const maxArg = maxSpecificity(\n splitSelectorList(ofSelectors).map(computeSelectorSpecificity),\n );\n ids += maxArg[1];\n classes += maxArg[2];\n types += maxArg[3];\n }\n expectType = false;\n continue;\n }\n\n // Other functional pseudo-classes count as class specificity (+1).\n classes += 1;\n expectType = false;\n continue;\n }\n\n classes += 1;\n i = nameEnd - 1;\n expectType = false;\n continue;\n }\n\n if (expectType) {\n if (ch === '*') {\n expectType = false;\n continue;\n }\n if (isIdentStart(ch)) {\n types += 1;\n i = consumeIdent(selector, i + 1) - 1;\n expectType = false;\n continue;\n }\n }\n }\n\n return [0, ids, classes, types] as const;\n}\n\n/**\n * For a selector list, returns the matched selector with max specificity among matches.\n */\nfunction computeMatchedRuleSpecificity(\n element: Element,\n selectorText: string,\n): { matchedSelector: string; specificity: Specificity } | null {\n const selectors = splitSelectorList(selectorText);\n let bestSel: string | null = null;\n let bestSpec: Specificity = ZERO_SPEC;\n\n for (const sel of selectors) {\n try {\n if (!element.matches(sel)) continue;\n const spec = computeSelectorSpecificity(sel);\n if (!bestSel || compareSpecificity(spec, bestSpec) > 0) {\n bestSel = sel;\n bestSpec = spec;\n }\n } catch {\n // Invalid selector for matches() (e.g. pseudo-elements) => ignore.\n }\n }\n\n return bestSel ? { matchedSelector: bestSel, specificity: bestSpec } : null;\n}\n\nconst LEGACY_PSEUDO_ELEMENTS = new Set([\n 'before',\n 'after',\n 'first-line',\n 'first-letter',\n 'selection',\n 'backdrop',\n 'placeholder',\n]);\n\nfunction isIdentStart(ch: string): boolean {\n return /[a-zA-Z_]/.test(ch) || ch.charCodeAt(0) >= 0x80;\n}\n\nfunction consumeIdent(s: string, start: number): number {\n let i = start;\n for (; i < s.length; i++) {\n const ch = s[i];\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n if (/[a-zA-Z0-9_-]/.test(ch) || ch.charCodeAt(0) >= 0x80) continue;\n break;\n }\n return i;\n}\n\nfunction consumeBracket(s: string, openIndex: number): number {\n let depth = 1;\n let quote: \"'\" | '\"' | null = null;\n\n for (let i = openIndex + 1; i < s.length; i++) {\n const ch = s[i];\n if (quote) {\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n if (ch === quote) quote = null;\n continue;\n }\n if (ch === '\"' || ch === \"'\") {\n quote = ch;\n continue;\n }\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n if (ch === '[') depth += 1;\n else if (ch === ']') {\n depth -= 1;\n if (depth === 0) return i;\n }\n }\n return s.length - 1;\n}\n\nfunction consumeParenFunction(\n s: string,\n openParenIndex: number,\n): { content: string; endIndex: number } {\n let depth = 1;\n let quote: \"'\" | '\"' | null = null;\n\n for (let i = openParenIndex + 1; i < s.length; i++) {\n const ch = s[i];\n if (quote) {\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n if (ch === quote) quote = null;\n continue;\n }\n if (ch === '\"' || ch === \"'\") {\n quote = ch;\n continue;\n }\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n if (ch === '[') i = consumeBracket(s, i);\n else if (ch === '(') depth += 1;\n else if (ch === ')') {\n depth -= 1;\n if (depth === 0) return { content: s.slice(openParenIndex + 1, i), endIndex: i };\n }\n }\n return { content: s.slice(openParenIndex + 1), endIndex: s.length - 1 };\n}\n\nfunction isCombinatorOrWhitespace(s: string, i: number): boolean {\n const ch = s[i];\n return /\\s/.test(ch) || ch === '>' || ch === '+' || ch === '~' || ch === '|';\n}\n\nfunction consumeWhitespaceAndCombinators(s: string, i: number): number {\n let j = i;\n while (j < s.length && /\\s/.test(s[j])) j++;\n if (s[j] === '|' && s[j + 1] === '|') return j + 1;\n if (s[j] === '>' || s[j] === '+' || s[j] === '~' || s[j] === '|') return j;\n return j - 1;\n}\n\nfunction extractNthOfSelectorList(content: string): string | null {\n let depthParen = 0;\n let depthBrack = 0;\n let quote: \"'\" | '\"' | null = null;\n\n for (let i = 0; i < content.length; i++) {\n const ch = content[i];\n\n if (quote) {\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n if (ch === quote) quote = null;\n continue;\n }\n\n if (ch === '\"' || ch === \"'\") {\n quote = ch;\n continue;\n }\n\n if (ch === '\\\\') {\n i += 1;\n continue;\n }\n\n if (ch === '[') depthBrack += 1;\n else if (ch === ']' && depthBrack > 0) depthBrack -= 1;\n else if (ch === '(') depthParen += 1;\n else if (ch === ')' && depthParen > 0) depthParen -= 1;\n\n if (depthParen === 0 && depthBrack === 0) {\n if (isOfTokenAt(content, i)) return content.slice(i + 2).trimStart();\n }\n }\n\n return null;\n}\n\nfunction isOfTokenAt(s: string, i: number): boolean {\n if (s[i] !== 'o' || s[i + 1] !== 'f') return false;\n const prev = s[i - 1];\n const next = s[i + 2];\n const prevOk = prev === undefined || /\\s/.test(prev);\n const nextOk = next === undefined || /\\s/.test(next);\n return prevOk && nextOk;\n}\n\n// =============================================================================\n// Inherited properties\n// =============================================================================\n\nexport const INHERITED_PROPERTIES = new Set([\n // Color & appearance\n 'color',\n 'color-scheme',\n 'caret-color',\n 'accent-color',\n\n // Typography / fonts\n 'font',\n 'font-family',\n 'font-feature-settings',\n 'font-kerning',\n 'font-language-override',\n 'font-optical-sizing',\n 'font-palette',\n 'font-size',\n 'font-size-adjust',\n 'font-stretch',\n 'font-style',\n 'font-synthesis',\n 'font-synthesis-small-caps',\n 'font-synthesis-style',\n 'font-synthesis-weight',\n 'font-variant',\n 'font-variant-alternates',\n 'font-variant-caps',\n 'font-variant-east-asian',\n 'font-variant-emoji',\n 'font-variant-ligatures',\n 'font-variant-numeric',\n 'font-variant-position',\n 'font-variation-settings',\n 'font-weight',\n 'letter-spacing',\n 'line-height',\n 'text-rendering',\n 'text-size-adjust',\n 'text-transform',\n 'text-indent',\n 'text-align',\n 'text-align-last',\n 'text-justify',\n 'text-shadow',\n 'text-emphasis-color',\n 'text-emphasis-position',\n 'text-emphasis-style',\n 'text-underline-position',\n 'tab-size',\n 'white-space',\n 'word-break',\n 'overflow-wrap',\n 'word-spacing',\n 'hyphens',\n 'line-break',\n\n // Writing / bidi\n 'direction',\n 'unicode-bidi',\n 'writing-mode',\n 'text-orientation',\n 'text-combine-upright',\n\n // Lists\n 'list-style',\n 'list-style-image',\n 'list-style-position',\n 'list-style-type',\n\n // Tables\n 'border-collapse',\n 'border-spacing',\n 'caption-side',\n 'empty-cells',\n\n // Visibility / interaction\n 'cursor',\n 'visibility',\n 'pointer-events',\n 'user-select',\n\n // Quotes & pagination\n 'quotes',\n 'orphans',\n 'widows',\n\n // SVG\n 'fill',\n 'fill-opacity',\n 'fill-rule',\n 'stroke',\n 'stroke-width',\n 'stroke-linecap',\n 'stroke-linejoin',\n 'stroke-miterlimit',\n 'stroke-dasharray',\n 'stroke-dashoffset',\n 'stroke-opacity',\n 'paint-order',\n 'shape-rendering',\n 'image-rendering',\n 'color-interpolation',\n 'color-interpolation-filters',\n 'color-rendering',\n 'dominant-baseline',\n 'alignment-baseline',\n 'baseline-shift',\n 'text-anchor',\n 'stop-color',\n 'stop-opacity',\n 'flood-color',\n 'flood-opacity',\n 'lighting-color',\n 'marker',\n 'marker-start',\n 'marker-mid',\n 'marker-end',\n]);\n\nexport function isInheritableProperty(property: string): boolean {\n const p = String(property || '').trim();\n if (!p) return false;\n if (p.startsWith('--')) return true;\n return INHERITED_PROPERTIES.has(p.toLowerCase());\n}\n\n// =============================================================================\n// Shorthand expansion\n// =============================================================================\n\nexport const SHORTHAND_TO_LONGHANDS: Record = {\n // Spacing\n margin: ['margin-top', 'margin-right', 'margin-bottom', 'margin-left'],\n padding: ['padding-top', 'padding-right', 'padding-bottom', 'padding-left'],\n inset: ['top', 'right', 'bottom', 'left'],\n\n // Border\n border: [\n 'border-top-width',\n 'border-right-width',\n 'border-bottom-width',\n 'border-left-width',\n 'border-top-style',\n 'border-right-style',\n 'border-bottom-style',\n 'border-left-style',\n 'border-top-color',\n 'border-right-color',\n 'border-bottom-color',\n 'border-left-color',\n ],\n 'border-width': [\n 'border-top-width',\n 'border-right-width',\n 'border-bottom-width',\n 'border-left-width',\n ],\n 'border-style': [\n 'border-top-style',\n 'border-right-style',\n 'border-bottom-style',\n 'border-left-style',\n ],\n 'border-color': [\n 'border-top-color',\n 'border-right-color',\n 'border-bottom-color',\n 'border-left-color',\n ],\n\n 'border-top': ['border-top-width', 'border-top-style', 'border-top-color'],\n 'border-right': ['border-right-width', 'border-right-style', 'border-right-color'],\n 'border-bottom': ['border-bottom-width', 'border-bottom-style', 'border-bottom-color'],\n 'border-left': ['border-left-width', 'border-left-style', 'border-left-color'],\n\n 'border-radius': [\n 'border-top-left-radius',\n 'border-top-right-radius',\n 'border-bottom-right-radius',\n 'border-bottom-left-radius',\n ],\n\n outline: ['outline-color', 'outline-style', 'outline-width'],\n\n // Background\n background: [\n 'background-attachment',\n 'background-clip',\n 'background-color',\n 'background-image',\n 'background-origin',\n 'background-position',\n 'background-repeat',\n 'background-size',\n ],\n\n // Font\n font: [\n 'font-style',\n 'font-variant',\n 'font-weight',\n 'font-stretch',\n 'font-size',\n 'line-height',\n 'font-family',\n ],\n\n // Flexbox\n flex: ['flex-grow', 'flex-shrink', 'flex-basis'],\n 'flex-flow': ['flex-direction', 'flex-wrap'],\n\n // Alignment\n 'place-content': ['align-content', 'justify-content'],\n 'place-items': ['align-items', 'justify-items'],\n 'place-self': ['align-self', 'justify-self'],\n\n // Gaps\n gap: ['row-gap', 'column-gap'],\n 'grid-gap': ['row-gap', 'column-gap'],\n\n // Overflow\n overflow: ['overflow-x', 'overflow-y'],\n\n // Grid\n 'grid-area': ['grid-row-start', 'grid-column-start', 'grid-row-end', 'grid-column-end'],\n 'grid-row': ['grid-row-start', 'grid-row-end'],\n 'grid-column': ['grid-column-start', 'grid-column-end'],\n 'grid-template': ['grid-template-rows', 'grid-template-columns', 'grid-template-areas'],\n\n // Text\n 'text-emphasis': ['text-emphasis-style', 'text-emphasis-color'],\n 'text-decoration': [\n 'text-decoration-line',\n 'text-decoration-style',\n 'text-decoration-color',\n 'text-decoration-thickness',\n ],\n\n // Animations / transitions\n transition: [\n 'transition-property',\n 'transition-duration',\n 'transition-timing-function',\n 'transition-delay',\n ],\n animation: [\n 'animation-name',\n 'animation-duration',\n 'animation-timing-function',\n 'animation-delay',\n 'animation-iteration-count',\n 'animation-direction',\n 'animation-fill-mode',\n 'animation-play-state',\n ],\n\n // Multi-column\n columns: ['column-width', 'column-count'],\n 'column-rule': ['column-rule-width', 'column-rule-style', 'column-rule-color'],\n\n // Lists\n 'list-style': ['list-style-position', 'list-style-image', 'list-style-type'],\n};\n\nexport function expandToLonghands(property: string): readonly string[] {\n const raw = String(property || '').trim();\n if (!raw) return [];\n if (raw.startsWith('--')) return [raw];\n const p = raw.toLowerCase();\n return SHORTHAND_TO_LONGHANDS[p] ?? [p];\n}\n\nfunction normalizePropertyName(property: string): string {\n const raw = String(property || '').trim();\n if (!raw) return '';\n if (raw.startsWith('--')) return raw;\n return raw.toLowerCase();\n}\n\n// =============================================================================\n// Cascade / override\n// =============================================================================\n\nfunction compareSourceOrder(\n a: readonly [number, number, number],\n b: readonly [number, number, number],\n): number {\n if (a[0] !== b[0]) return a[0] > b[0] ? 1 : -1;\n if (a[1] !== b[1]) return a[1] > b[1] ? 1 : -1;\n if (a[2] !== b[2]) return a[2] > b[2] ? 1 : -1;\n return 0;\n}\n\nfunction compareCascade(a: DeclCandidate, b: DeclCandidate): number {\n if (a.important !== b.important) return a.important ? 1 : -1;\n const spec = compareSpecificity(a.specificity, b.specificity);\n if (spec !== 0) return spec;\n return compareSourceOrder(a.sourceOrder, b.sourceOrder);\n}\n\nfunction computeOverrides(candidates: readonly DeclCandidate[]): {\n winners: Map;\n declStatus: Map;\n} {\n const winners = new Map();\n\n for (const cand of candidates) {\n for (const longhand of cand.affects) {\n const cur = winners.get(longhand);\n if (!cur || compareCascade(cand, cur) > 0) winners.set(longhand, cand);\n }\n }\n\n const declStatus = new Map();\n for (const cand of candidates) declStatus.set(cand.id, 'overridden');\n for (const [, winner] of winners) declStatus.set(winner.id, 'active');\n\n return { winners, declStatus };\n}\n\n// =============================================================================\n// CSSOM Rule Index\n// =============================================================================\n\nconst CONTAINER_RULE = (globalThis as unknown as { CSSRule?: { CONTAINER_RULE?: number } }).CSSRule\n ?.CONTAINER_RULE;\nconst SCOPE_RULE = (globalThis as unknown as { CSSRule?: { SCOPE_RULE?: number } }).CSSRule\n ?.SCOPE_RULE;\n\nfunction isSheetApplicable(sheet: CSSStyleSheet): boolean {\n if ((sheet as { disabled?: boolean }).disabled) return false;\n\n try {\n const mediaText = sheet.media?.mediaText?.trim() ?? '';\n if (!mediaText || mediaText.toLowerCase() === 'all') return true;\n return window.matchMedia(mediaText).matches;\n } catch {\n return true;\n }\n}\n\nfunction describeStyleSheet(sheet: CSSStyleSheet, fallbackIndex: number): CssRuleSource {\n const href = typeof sheet.href === 'string' ? sheet.href : undefined;\n\n if (href) {\n const file = href.split('/').pop()?.split('?')[0] ?? href;\n return { url: href, label: file };\n }\n\n const ownerNode = sheet.ownerNode as Node | null | undefined;\n if (ownerNode && ownerNode.nodeType === Node.ELEMENT_NODE) {\n const el = ownerNode as Element;\n if (el.tagName === 'STYLE') return { label: `\n" }, { "path": "app/chrome-extension/entrypoints/welcome/index.html", "content": "\n\n \n \n \n Welcome to Chrome MCP Server\n \n \n \n
\n \n \n\n" }, { "path": "app/chrome-extension/entrypoints/welcome/main.ts", "content": "import { createApp } from 'vue';\nimport App from './App.vue';\n\n// Tailwind first, then custom tokens\nimport '../styles/tailwind.css';\n\ncreateApp(App).mount('#app');\n" }, { "path": "app/chrome-extension/env.d.ts", "content": "/// \ndeclare module '*.vue' {\n import type { DefineComponent } from 'vue';\n type Props = Record;\n type RawBindings = Record;\n const component: DefineComponent;\n export default component;\n}\n" }, { "path": "app/chrome-extension/eslint.config.js", "content": "import js from '@eslint/js';\nimport globals from 'globals';\nimport tseslint from 'typescript-eslint';\nimport pluginVue from 'eslint-plugin-vue';\nimport { defineConfig } from 'eslint/config';\nimport prettierConfig from 'eslint-config-prettier';\n\nexport default defineConfig([\n // Global ignores - these apply to all configurations\n {\n ignores: [\n 'dist/**',\n '.output/**',\n '.wxt/**',\n 'node_modules/**',\n 'logs/**',\n '*.log',\n '.cache/**',\n '.temp/**',\n '.vscode/**',\n '!.vscode/extensions.json',\n '.idea/**',\n '.DS_Store',\n 'Thumbs.db',\n '*.zip',\n '*.tar.gz',\n 'stats.html',\n 'stats-*.json',\n 'libs/**',\n 'workers/**',\n 'public/libs/**',\n ],\n },\n js.configs.recommended,\n {\n files: ['**/*.{js,mjs,cjs,ts,vue}'],\n languageOptions: {\n globals: {\n ...globals.browser,\n chrome: 'readonly',\n },\n },\n },\n ...tseslint.configs.recommended,\n {\n rules: {\n '@typescript-eslint/no-explicit-any': 'off',\n '@typescript-eslint/no-unused-vars': 'off',\n 'no-empty': 'off',\n },\n },\n pluginVue.configs['flat/essential'],\n { files: ['**/*.vue'], languageOptions: { parserOptions: { parser: tseslint.parser } } },\n // Prettier configuration - must be placed last to override previous rules\n prettierConfig,\n]);\n" }, { "path": "app/chrome-extension/inject-scripts/accessibility-tree-helper.js", "content": "/* eslint-disable */\n// accessibility-tree-helper.js\n// Injected script to generate an accessibility-like tree of the visible page\n// Elements receive stable refs (ref_*) via WeakRef mapping for later reference.\n\n(function () {\n if (window.__ACCESSIBILITY_TREE_HELPER_INITIALIZED__) return;\n window.__ACCESSIBILITY_TREE_HELPER_INITIALIZED__ = true;\n\n // Traversal and output limits to ensure stability on very large/complex pages\n const MAX_DEPTH = 30; // maximum DOM depth to traverse\n const MAX_NODES = 4000; // hard limit to avoid long blocking on huge DOMs\n const MAX_LINE_LABEL = 100; // max characters for a single label in output\n const REF_MAP_LIMIT = 1000; // limit size of the ref map to keep payload small\n\n // Keep a weak map from ref id to elements\n if (!window.__claudeElementMap) window.__claudeElementMap = {};\n if (!window.__claudeRefCounter) window.__claudeRefCounter = 0;\n\n /**\n * Infer ARIA-like role from element\n * @param {Element} el\n * @returns {string}\n */\n function inferRole(el) {\n const role = el.getAttribute('role');\n if (role) return role;\n const tag = el.tagName.toLowerCase();\n const type = el.getAttribute('type') || '';\n const map = {\n a: 'link',\n button: 'button',\n input:\n type === 'submit' || type === 'button'\n ? 'button'\n : type === 'checkbox'\n ? 'checkbox'\n : type === 'radio'\n ? 'radio'\n : type === 'file'\n ? 'button'\n : 'textbox',\n select: 'combobox',\n textarea: 'textbox',\n h1: 'heading',\n h2: 'heading',\n h3: 'heading',\n h4: 'heading',\n h5: 'heading',\n h6: 'heading',\n img: 'image',\n nav: 'navigation',\n main: 'main',\n header: 'banner',\n footer: 'contentinfo',\n section: 'region',\n article: 'article',\n aside: 'complementary',\n form: 'form',\n table: 'table',\n ul: 'list',\n ol: 'list',\n li: 'listitem',\n label: 'label',\n };\n return map[tag] || 'generic';\n }\n\n /**\n * Derive readable label for element\n * @param {Element} el\n * @returns {string}\n */\n function inferLabel(el) {\n const tag = el.tagName.toLowerCase();\n if (tag === 'select') {\n const sel = /** @type {HTMLSelectElement} */ (el);\n const opt = sel.querySelector('option[selected]') || sel.options[sel.selectedIndex];\n if (opt && opt.textContent) return opt.textContent.trim();\n }\n const aria = el.getAttribute('aria-label');\n if (aria && aria.trim()) return aria.trim();\n const placeholder = el.getAttribute('placeholder');\n if (placeholder && placeholder.trim()) return placeholder.trim();\n const title = el.getAttribute('title');\n if (title && title.trim()) return title.trim();\n const alt = el.getAttribute('alt');\n if (alt && alt.trim()) return alt.trim();\n if (/** @type {HTMLElement} */ (el).id) {\n const lab = document.querySelector(`label[for=\"${/** @type {HTMLElement} */ (el).id}\"]`);\n if (lab && lab.textContent && lab.textContent.trim()) return lab.textContent.trim();\n }\n if (tag === 'input') {\n const input = /** @type {HTMLInputElement} */ (el);\n const type = input.getAttribute('type') || '';\n const val = input.getAttribute('value');\n if (type === 'submit' && val && val.trim()) return val.trim();\n if (input.value && input.value.length < 50 && input.value.trim()) return input.value.trim();\n }\n if (['button', 'a', 'summary'].includes(tag)) {\n let text = '';\n for (let i = 0; i < el.childNodes.length; i++) {\n const n = el.childNodes[i];\n if (n.nodeType === Node.TEXT_NODE) text += n.textContent || '';\n }\n if (text.trim()) return text.trim();\n }\n if (/^h[1-6]$/.test(tag)) {\n const t = el.textContent;\n if (t && t.trim()) return t.trim().substring(0, MAX_LINE_LABEL);\n }\n if (tag === 'img') {\n const src = el.getAttribute('src');\n if (src) {\n const file = src.split('/').pop()?.split('?')[0];\n return `Image: ${file}`;\n }\n }\n let agg = '';\n for (let i = 0; i < el.childNodes.length; i++) {\n const n = el.childNodes[i];\n if (n.nodeType === Node.TEXT_NODE) agg += n.textContent || '';\n }\n if (agg && agg.trim() && agg.trim().length >= 3) {\n const v = agg.trim();\n return v.length > 50 ? v.substring(0, 50) + '...' : v;\n }\n return '';\n }\n\n /**\n * Check if element is visible in DOM\n * @param {Element} el\n */\n function isVisible(el) {\n const cs = window.getComputedStyle(/** @type {HTMLElement} */ (el));\n if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return false;\n const he = /** @type {HTMLElement} */ (el);\n return he.offsetWidth > 0 && he.offsetHeight > 0;\n }\n\n /**\n * Whether the element is interactive\n * @param {Element} el\n */\n function isInteractive(el) {\n // Native interactive tags\n const tag = el.tagName.toLowerCase();\n if (['a', 'button', 'input', 'select', 'textarea', 'details', 'summary'].includes(tag))\n return true;\n\n // Generic interactive hints\n if (el.getAttribute('onclick') != null) return true;\n if (\n el.getAttribute('tabindex') != null &&\n String(el.getAttribute('tabindex')).trim() !== '' &&\n !String(el.getAttribute('tabindex')).trim().startsWith('-')\n )\n return true;\n if (el.getAttribute('contenteditable') === 'true') return true;\n\n // ARIA roles commonly used by custom elements\n const role = (el.getAttribute && el.getAttribute('role')) || '';\n const interactiveRoles = new Set([\n 'button',\n 'link',\n 'checkbox',\n 'radio',\n 'switch',\n 'slider',\n 'option',\n 'menuitem',\n 'textbox',\n 'searchbox',\n 'combobox',\n 'spinbutton',\n 'tab',\n 'treeitem',\n ]);\n if (role && interactiveRoles.has(role.toLowerCase())) return true;\n\n // Shadow host case: treat host as interactive if its open shadow root contains\n // an interactive control (textarea/input/select/button/a or contenteditable).\n try {\n const anyEl = /** @type {any} */ (el);\n const sr = anyEl && anyEl.shadowRoot ? anyEl.shadowRoot : null;\n if (sr) {\n const inner = sr.querySelector(\n 'input, textarea, select, button, a[href], [contenteditable=\"true\"], [role=\"button\"], [role=\"link\"], [role=\"textbox\"], [role=\"combobox\"], [role=\"searchbox\"], [role=\"menuitem\"], [role=\"option\"], [role=\"switch\"], [role=\"radio\"], [role=\"checkbox\"], [role=\"tab\"], [role=\"slider\"]',\n );\n if (inner) return true;\n }\n } catch (_) {\n /* ignore */\n }\n return false;\n }\n\n /**\n * Structural containers useful to include\n * @param {Element} el\n */\n function isStructural(el) {\n const tag = el.tagName.toLowerCase();\n if (\n [\n 'h1',\n 'h2',\n 'h3',\n 'h4',\n 'h5',\n 'h6',\n 'nav',\n 'main',\n 'header',\n 'footer',\n 'section',\n 'article',\n 'aside',\n ].includes(tag)\n )\n return true;\n return el.getAttribute('role') != null;\n }\n\n /**\n * Form-ish containers to keep\n * @param {Element} el\n */\n function isFormishContainer(el) {\n const tag = el.tagName.toLowerCase();\n const role = (el.getAttribute && el.getAttribute('role')) || '';\n const id = /** @type {HTMLElement} */ (el).id || '';\n // Normalize className for HTML/SVG elements\n let cls = '';\n try {\n const attr = el.getAttribute && el.getAttribute('class');\n if (typeof attr === 'string') cls = attr;\n else {\n const cn = /** @type {any} */ (el).className;\n if (typeof cn === 'string') cls = cn;\n else if (cn && typeof cn.baseVal === 'string') cls = cn.baseVal;\n }\n } catch (e) {\n /* ignore */\n }\n return (\n role === 'search' ||\n role === 'form' ||\n role === 'group' ||\n role === 'toolbar' ||\n role === 'navigation' ||\n tag === 'form' ||\n tag === 'fieldset' ||\n tag === 'nav' ||\n tag === 'legend' ||\n id.includes('search') ||\n cls.includes('search') ||\n id.includes('form') ||\n cls.includes('form') ||\n id.includes('menu') ||\n cls.includes('menu') ||\n id.includes('nav') ||\n cls.includes('nav')\n );\n }\n\n // Utility: query CSS across open shadow roots (best-effort)\n function querySelectorDeepFirst(selector) {\n try {\n // Fast path\n const direct = document.querySelector(selector);\n if (direct) return direct;\n } catch (_) {}\n const visited = new Set();\n const stack = [document.documentElement];\n while (stack.length) {\n const node = stack.pop();\n if (!node || visited.has(node)) continue;\n visited.add(node);\n try {\n const root = /** @type {any} */ (node).shadowRoot || (node.nodeType === 9 ? node : null);\n if (root) {\n try {\n const hit = root.querySelector(selector);\n if (hit) return hit;\n } catch (_) {}\n }\n } catch (_) {}\n // Traverse DOM and shadow roots\n try {\n const children = /** @type {Element} */ (node).children || [];\n for (let i = 0; i < children.length; i++) stack.push(children[i]);\n const sr = /** @type {any} */ (node).shadowRoot;\n if (sr && sr.children) {\n for (let i = 0; i < sr.children.length; i++) stack.push(sr.children[i]);\n }\n } catch (_) {}\n }\n return null;\n }\n\n /**\n * Query CSS selector and return match info including uniqueness check.\n * @param {string} selector - CSS selector to query\n * @param {boolean} allowMultiple - If true, skip uniqueness check and return first match\n * @returns {{element: Element | null, matchCount: number, error?: string}}\n * Note: matchCount is capped at 2 (where 2 means \"2 or more\") for performance\n */\n function querySelectorWithUniquenessCheck(selector, allowMultiple = false) {\n const seen = new Set();\n let firstMatch = null;\n let matchCount = 0;\n\n const recordMatch = (el) => {\n if (!(el instanceof Element) || seen.has(el)) return false;\n seen.add(el);\n matchCount++;\n if (!firstMatch) firstMatch = el;\n // Short-circuit if:\n // - allowMultiple is true and we found first match (no need to continue)\n // - allowMultiple is false and we found multiple matches\n if (allowMultiple && firstMatch) return true;\n if (!allowMultiple && matchCount >= 2) return true;\n return false;\n };\n\n // Query in main document\n let selectorError = null;\n try {\n const directMatches = document.querySelectorAll(selector);\n for (let i = 0; i < directMatches.length; i++) {\n if (recordMatch(directMatches[i])) {\n // Early exit: either found first match (allowMultiple) or found multiple (not allowed)\n return { element: firstMatch, matchCount: allowMultiple ? 1 : 2 };\n }\n }\n } catch (e) {\n selectorError = e;\n }\n\n if (selectorError) {\n return {\n element: null,\n matchCount: 0,\n error: `Invalid CSS selector \"${selector}\": ${selectorError.message || selectorError}`,\n };\n }\n\n // If allowMultiple and we already have a match, return immediately\n if (allowMultiple && firstMatch) {\n return { element: firstMatch, matchCount: 1 };\n }\n\n // Query in shadow DOMs\n const visited = new Set();\n const stack = [document.documentElement];\n while (stack.length) {\n const node = stack.pop();\n if (!node || visited.has(node)) continue;\n visited.add(node);\n\n try {\n const shadowRoot = /** @type {any} */ (node).shadowRoot;\n if (shadowRoot) {\n try {\n const shadowMatches = shadowRoot.querySelectorAll(selector);\n for (let i = 0; i < shadowMatches.length; i++) {\n if (recordMatch(shadowMatches[i])) {\n // Early exit: either found first match (allowMultiple) or found multiple (not allowed)\n return { element: firstMatch, matchCount: allowMultiple ? 1 : 2 };\n }\n }\n } catch (e) {\n return {\n element: null,\n matchCount: 0,\n error: `Invalid CSS selector \"${selector}\": ${e.message || e}`,\n };\n }\n\n // Add shadow root children to stack\n try {\n const shadowChildren = shadowRoot.children || [];\n for (let i = 0; i < shadowChildren.length; i++) {\n stack.push(shadowChildren[i]);\n }\n } catch (_) {}\n }\n } catch (_) {}\n\n // Add regular children to stack\n try {\n const children = /** @type {Element} */ (node).children || [];\n for (let i = 0; i < children.length; i++) {\n stack.push(children[i]);\n }\n } catch (_) {}\n }\n\n return { element: firstMatch, matchCount: Math.min(matchCount, 2) };\n }\n\n /**\n * Query XPath selector and return match info including uniqueness check.\n * @param {string} selector - XPath selector to query\n * @param {boolean} allowMultiple - If true, skip uniqueness check and return first match\n * @returns {{element: Element | null, matchCount: number, error?: string}}\n * Note: matchCount is capped at 2 (where 2 means \"2 or more\") for performance\n */\n function queryXPathWithUniquenessCheck(selector, allowMultiple = false) {\n if (!selector) {\n return { element: null, matchCount: 0 };\n }\n\n try {\n if (allowMultiple) {\n // When multiple matches are allowed, use ANY_UNORDERED_NODE_TYPE for performance\n // This returns just the first match without evaluating the entire result set\n const result = document.evaluate(\n selector,\n document,\n null,\n XPathResult.ANY_UNORDERED_NODE_TYPE,\n null,\n );\n const firstMatch =\n result.singleNodeValue instanceof Element\n ? /** @type {Element} */ (result.singleNodeValue)\n : null;\n return { element: firstMatch, matchCount: firstMatch ? 1 : 0 };\n } else {\n // When uniqueness is required, use ORDERED_NODE_SNAPSHOT_TYPE to count matches\n const snapshot = document.evaluate(\n selector,\n document,\n null,\n XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n null,\n );\n const totalMatches = snapshot.snapshotLength;\n // Cap at 2 for performance (2 means \"2 or more\")\n const matchCount = Math.min(totalMatches, 2);\n const firstMatch =\n totalMatches > 0 && snapshot.snapshotItem(0) instanceof Element\n ? /** @type {Element} */ (snapshot.snapshotItem(0))\n : null;\n return { element: firstMatch, matchCount };\n }\n } catch (e) {\n return {\n element: null,\n matchCount: 0,\n error: `Invalid XPath \"${selector}\": ${e.message || e}`,\n };\n }\n }\n\n /**\n * Whether to include element in tree under config\n * @param {Element} el\n * @param {{filter?: 'all'|'interactive'}} cfg\n */\n function shouldInclude(el, cfg) {\n const tag = el.tagName.toLowerCase();\n if (['script', 'style', 'meta', 'link', 'title', 'noscript'].includes(tag)) return false;\n if (el.getAttribute('aria-hidden') === 'true') return false;\n if (!isVisible(el)) return false;\n if (cfg.filter !== 'all') {\n const r = /** @type {HTMLElement} */ (el).getBoundingClientRect();\n if (\n !(r.top < window.innerHeight && r.bottom > 0 && r.left < window.innerWidth && r.right > 0)\n )\n return false;\n }\n if (cfg.filter === 'interactive') return isInteractive(el);\n if (isInteractive(el)) return true;\n if (isStructural(el)) return true;\n if (inferLabel(el).length > 0) return true;\n return isFormishContainer(el);\n }\n\n /**\n * Generate a fairly stable CSS selector\n * @param {Element} el\n * @returns {string}\n */\n function generateSelector(el) {\n if (!(el instanceof Element)) return '';\n if (/** @type {HTMLElement} */ (el).id) {\n const idSel = `#${CSS.escape(/** @type {HTMLElement} */ (el).id)}`;\n if (document.querySelectorAll(idSel).length === 1) return idSel;\n }\n for (const attr of ['data-testid', 'data-cy', 'name']) {\n const attrValue = el.getAttribute(attr);\n if (attrValue) {\n const s = `[${attr}=\"${CSS.escape(attrValue)}\"]`;\n if (document.querySelectorAll(s).length === 1) return s;\n }\n }\n let path = '';\n let current = el;\n while (current && current.nodeType === Node.ELEMENT_NODE && current.tagName !== 'BODY') {\n let selector = current.tagName.toLowerCase();\n const parent = current.parentElement;\n if (parent) {\n const siblings = Array.from(parent.children).filter(\n (child) => child.tagName === current.tagName,\n );\n if (siblings.length > 1) {\n const index = siblings.indexOf(current) + 1;\n selector += `:nth-of-type(${index})`;\n }\n }\n path = path ? `${selector} > ${path}` : selector;\n current = parent;\n }\n return path ? `body > ${path}` : 'body';\n }\n\n /**\n * Traverse DOM and build pageContent lines; collect ref map for interactive nodes.\n * @param {Element} el\n * @param {number} depth\n * @param {{filter?: 'all'|'interactive', maxDepth?: number}} cfg\n * @param {string[]} out\n * @param {Array<{ref:string, selector:string, rect:{x:number,y:number,width:number,height:number}}>} refMap\n */\n function traverse(el, depth, cfg, out, refMap, state) {\n const maxDepth = cfg && typeof cfg.maxDepth === 'number' ? cfg.maxDepth : MAX_DEPTH;\n if (depth > maxDepth || !el || !el.tagName) return;\n if (state.processed >= MAX_NODES) return;\n if (state.visited.has(el)) return;\n state.visited.add(el);\n const include = shouldInclude(el, cfg) || depth === 0;\n if (include) {\n const role = inferRole(el);\n let label = inferLabel(el);\n let refId = null;\n for (const k in window.__claudeElementMap) {\n if (window.__claudeElementMap[k].deref && window.__claudeElementMap[k].deref() === el) {\n refId = k;\n break;\n }\n }\n if (!refId) {\n refId = `ref_${++window.__claudeRefCounter}`;\n window.__claudeElementMap[refId] = new WeakRef(el);\n }\n const rect = /** @type {HTMLElement} */ (el).getBoundingClientRect();\n const cx = Math.round(rect.left + rect.width / 2);\n const cy = Math.round(rect.top + rect.height / 2);\n let line = `${' '.repeat(depth)}- ${role}`;\n if (label) {\n label = label.replace(/\\s+/g, ' ').substring(0, MAX_LINE_LABEL);\n line += ` \"${label.replace(/\"/g, '\\\\\"')}\"`;\n }\n line += ` [ref=${refId}] (x=${cx},y=${cy})`;\n if (/** @type {HTMLElement} */ (el).id) line += ` id=\"${/** @type {HTMLElement} */ (el).id}\"`;\n const href = el.getAttribute('href');\n if (href) line += ` href=\"${href}\"`;\n const type = el.getAttribute('type');\n if (type) line += ` type=\"${type}\"`;\n const placeholder = el.getAttribute('placeholder');\n if (placeholder) line += ` placeholder=\"${placeholder}\"`;\n // Surface disabled/pointer-events for better agent judgement\n try {\n const disabled = el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true';\n if (disabled) line += ` disabled`;\n const cs = window.getComputedStyle(/** @type {HTMLElement} */ (el));\n if (cs && cs.pointerEvents === 'none') line += ` pe=none`;\n } catch (_) {\n /* ignore style issues */\n }\n out.push(line);\n state.included++;\n state.processed++;\n\n // Only collect ref mapping for interactive elements to limit cost\n if (isInteractive(el) && refMap.length < REF_MAP_LIMIT) {\n refMap.push({\n ref: /** @type {string} */ (refId),\n selector: generateSelector(el),\n rect: {\n x: rect.x,\n y: rect.y,\n width: rect.width,\n height: rect.height,\n },\n });\n }\n }\n if (state.processed >= MAX_NODES) return;\n // Traverse light DOM children\n if (/** @type {HTMLElement} */ (el).children && depth < maxDepth) {\n const children = /** @type {HTMLElement} */ (el).children;\n for (let i = 0; i < children.length; i++) {\n if (state.processed >= MAX_NODES) break;\n traverse(children[i], include ? depth + 1 : depth, cfg, out, refMap, state);\n }\n }\n // Traverse shadow DOM roots (limited by maxDepth and MAX_NODES)\n try {\n const anyEl = /** @type {any} */ (el);\n if (anyEl && anyEl.shadowRoot && depth < maxDepth) {\n const srChildren = anyEl.shadowRoot.children || [];\n for (let i = 0; i < srChildren.length; i++) {\n if (state.processed >= MAX_NODES) break;\n traverse(srChildren[i], include ? depth + 1 : depth, cfg, out, refMap, state);\n }\n }\n } catch (_) {\n /* ignore shadow errors */\n }\n }\n\n /**\n * Generate tree and return\n * @param {'all'|'interactive'|null} filter\n * @param {{maxDepth?: number, refId?: string}|undefined} options\n */\n function __generateAccessibilityTree(filter, options) {\n try {\n const start = performance && performance.now ? performance.now() : Date.now();\n const out = [];\n const cfg = { filter: filter || undefined };\n\n // Clamp maxDepth to MAX_DEPTH to keep costs bounded\n if (options && Number.isFinite(options.maxDepth)) {\n const d = Math.max(0, Math.floor(Number(options.maxDepth)));\n cfg.maxDepth = Math.min(d, MAX_DEPTH);\n }\n\n const refMap = [];\n const state = { processed: 0, included: 0, visited: new WeakSet() };\n\n // Determine root element (body or refId-specified element)\n let focus = null;\n let root = document.body;\n if (options && options.refId) {\n const refIdStr = String(options.refId || '').trim();\n if (refIdStr) {\n const el = resolveRef(refIdStr);\n if (!el || !(el instanceof Element)) {\n return { error: `ref \"${refIdStr}\" not found or expired` };\n }\n root = el;\n focus = { refId: refIdStr };\n }\n }\n\n if (root) traverse(root, 0, cfg, out, refMap, state);\n for (const k in window.__claudeElementMap) {\n if (!window.__claudeElementMap[k].deref || !window.__claudeElementMap[k].deref())\n delete window.__claudeElementMap[k];\n }\n const pageContent = out\n .filter((line) => !/^\\s*- generic \\[ref=ref_\\d+\\]$/.test(line))\n .join('\\n');\n const end = performance && performance.now ? performance.now() : Date.now();\n return {\n pageContent,\n focus,\n viewport: {\n width: window.innerWidth,\n height: window.innerHeight,\n dpr: window.devicePixelRatio || 1,\n },\n stats: {\n processed: state.processed,\n included: state.included,\n durationMs: Math.round(end - start),\n },\n refMap,\n };\n } catch (err) {\n throw new Error(\n 'Error generating accessibility tree: ' +\n (err && err.message ? err.message : 'Unknown error'),\n );\n }\n }\n\n // Expose API on window\n window.__generateAccessibilityTree = __generateAccessibilityTree;\n\n // ============================================================================\n // Hover for Ref (DOM Fallback Support)\n // ============================================================================\n\n async function handleHoverForRef(ref) {\n if (!ref) return { success: false, error: 'ref is required' };\n const el = resolveRef(ref);\n if (el) {\n dispatchHoverEvents(el);\n return { success: true, target: summarizeElement(el) };\n }\n return await forwardHoverRefToChildren(ref);\n }\n\n function resolveRef(ref) {\n const map = window.__claudeElementMap || {};\n const weak = map[ref];\n return weak && typeof weak.deref === 'function' ? weak.deref() : null;\n }\n\n function dispatchHoverEvents(el) {\n const rect = el.getBoundingClientRect();\n const center = {\n x: Math.round(rect.left + rect.width / 2),\n y: Math.round(rect.top + rect.height / 2),\n };\n ['mousemove', 'mouseover', 'mouseenter'].forEach((type) => {\n el.dispatchEvent(\n new MouseEvent(type, {\n bubbles: true,\n cancelable: true,\n clientX: center.x,\n clientY: center.y,\n view: window,\n }),\n );\n });\n }\n\n function summarizeElement(el) {\n return {\n tagName: el.tagName,\n id: el.id || '',\n className: el.className || '',\n text: (el.textContent || '').trim().slice(0, 100),\n };\n }\n\n function forwardHoverRefToChildren(ref) {\n return new Promise((resolve) => {\n const frames = Array.from(document.querySelectorAll('iframe, frame'));\n if (!frames.length) {\n resolve({ success: false, error: `ref \"${ref}\" not found` });\n return;\n }\n const reqId = `hover_ref_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n const listener = (ev) => {\n const data = ev?.data;\n if (!data || data.type !== 'rr-bridge-hover-ref-result' || data.reqId !== reqId) return;\n window.removeEventListener('message', listener, true);\n resolve(data.result);\n };\n window.addEventListener('message', listener, true);\n setTimeout(() => {\n window.removeEventListener('message', listener, true);\n resolve({ success: false, error: `ref \"${ref}\" not found in child frames` });\n }, 1500);\n for (const frame of frames) {\n try {\n frame.contentWindow?.postMessage({ type: 'rr-bridge-hover-ref', reqId, ref }, '*');\n } catch {}\n }\n });\n }\n\n // Chrome message bridge for ping and tree generation\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n try {\n if (request && request.action === 'chrome_read_page_ping') {\n sendResponse({ status: 'pong' });\n return false;\n }\n if (request && request.action === 'rr_overlay') {\n try {\n const cmd = request.cmd || 'init';\n let root = document.getElementById('__rr_overlay_root');\n if (!root) {\n root = document.createElement('div');\n root.id = '__rr_overlay_root';\n Object.assign(root.style, {\n position: 'fixed',\n right: '8px',\n bottom: '8px',\n zIndex: 2_147_483_647,\n maxWidth: '40vw',\n maxHeight: '40vh',\n overflow: 'auto',\n background: 'rgba(0,0,0,0.6)',\n color: '#fff',\n fontFamily:\n 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", \"Courier New\", monospace',\n fontSize: '12px',\n padding: '8px',\n borderRadius: '6px',\n boxShadow: '0 2px 8px rgba(0,0,0,0.3)',\n });\n const title = document.createElement('div');\n title.textContent = 'Record-Replay 运行日志';\n Object.assign(title.style, { fontWeight: 'bold', marginBottom: '6px' });\n const body = document.createElement('div');\n body.id = '__rr_overlay_body';\n root.appendChild(title);\n root.appendChild(body);\n document.documentElement.appendChild(root);\n }\n const body = document.getElementById('__rr_overlay_body');\n if (cmd === 'append' && body) {\n const line = document.createElement('div');\n line.textContent = String(request.text || '');\n body.appendChild(line);\n body.scrollTop = body.scrollHeight;\n }\n if (cmd === 'done' && root) {\n root.style.opacity = '0.5';\n }\n sendResponse({ success: true });\n return true;\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n // Element picker: start a temporary overlay to let user pick an element\n if (request && request.action === 'rr_picker_start') {\n try {\n // state\n const state = { active: true };\n const hostId = '__rr_picker_host__';\n let host = document.getElementById(hostId);\n if (host) host.remove();\n host = document.createElement('div');\n host.id = hostId;\n Object.assign(host.style, {\n position: 'fixed',\n inset: '0',\n zIndex: 2147483646,\n cursor: 'crosshair',\n background: 'rgba(0,0,0,0.0)',\n });\n const box = document.createElement('div');\n Object.assign(box.style, {\n position: 'fixed',\n border: '2px solid #3b82f6',\n background: 'rgba(59,130,246,0.15)',\n pointerEvents: 'none',\n });\n const tip = document.createElement('div');\n tip.textContent = '点击选取元素（Esc 取消）';\n Object.assign(tip.style, {\n position: 'fixed',\n top: '10px',\n left: '10px',\n background: 'rgba(0,0,0,0.7)',\n color: '#fff',\n padding: '6px 10px',\n borderRadius: '6px',\n fontSize: '12px',\n fontFamily: 'system-ui,-apple-system,Segoe UI,Roboto,Arial',\n });\n host.appendChild(box);\n host.appendChild(tip);\n document.documentElement.appendChild(host);\n\n const cleanup = () => {\n try {\n host.remove();\n } catch {}\n try {\n document.removeEventListener('mousemove', onMove, true);\n } catch {}\n try {\n document.removeEventListener('click', onClick, true);\n } catch {}\n try {\n document.removeEventListener('keydown', onKey, true);\n } catch {}\n state.active = false;\n };\n\n const onMove = (e) => {\n if (!state.active) return;\n const el = e.target instanceof Element ? e.target : null;\n if (!el) return;\n try {\n const r = el.getBoundingClientRect();\n Object.assign(box.style, {\n left: `${Math.round(r.left)}px`,\n top: `${Math.round(r.top)}px`,\n width: `${Math.round(Math.max(0, r.width))}px`,\n height: `${Math.round(Math.max(0, r.height))}px`,\n display: r.width > 0 && r.height > 0 ? 'block' : 'none',\n });\n } catch {}\n };\n const uniqueClassSelector = (node) => {\n try {\n const classes = Array.from(node.classList || []).filter(\n (c) => c && /^[a-zA-Z0-9_-]+$/.test(c),\n );\n for (const cls of classes) {\n const sel = `.${CSS.escape(cls)}`;\n if (document.querySelectorAll(sel).length === 1) return sel;\n }\n const tag = node.tagName ? node.tagName.toLowerCase() : '';\n for (const cls of classes) {\n const sel = `${tag}.${CSS.escape(cls)}`;\n if (document.querySelectorAll(sel).length === 1) return sel;\n }\n for (let i = 0; i < Math.min(classes.length, 3); i++) {\n for (let j = i + 1; j < Math.min(classes.length, 3); j++) {\n const sel = `.${CSS.escape(classes[i])}.${CSS.escape(classes[j])}`;\n if (document.querySelectorAll(sel).length === 1) return sel;\n }\n }\n } catch {}\n return '';\n };\n const computeCandidates = (el) => {\n const cands = [];\n // css by id / class / short path\n if (el.id) {\n const idSel = `#${CSS.escape(el.id)}`;\n if (document.querySelectorAll(idSel).length === 1)\n cands.push({ type: 'css', value: idSel });\n }\n const classSel = uniqueClassSelector(el);\n if (classSel) cands.push({ type: 'css', value: classSel });\n // data-* and name\n for (const attr of ['data-testid', 'data-cy', 'name']) {\n const val = el.getAttribute(attr);\n if (val) {\n const s = `[${attr}=\"${CSS.escape(val)}\"]`;\n if (document.querySelectorAll(s).length === 1)\n cands.push({ type: 'attr', value: s });\n }\n }\n // aria\n const aria = el.getAttribute && el.getAttribute('aria-label');\n if (aria) cands.push({ type: 'aria', value: `textbox[name=${aria}]` });\n // text for clickable\n const tag = (el.tagName || '').toLowerCase();\n if (['button', 'a', 'summary'].includes(tag)) {\n const text = (el.textContent || '').trim();\n if (text) cands.push({ type: 'text', value: text.substring(0, 64) });\n }\n // fallback path selector\n const gen = (node) => {\n if (!(node instanceof Element)) return '';\n let path = '';\n let current = node;\n while (\n current &&\n current.nodeType === Node.ELEMENT_NODE &&\n current.tagName !== 'BODY'\n ) {\n let sel = current.tagName.toLowerCase();\n const parent = current.parentElement;\n if (parent) {\n const siblings = Array.from(parent.children).filter(\n (child) => child.tagName === current.tagName,\n );\n if (siblings.length > 1) {\n const index = siblings.indexOf(current) + 1;\n sel += `:nth-of-type(${index})`;\n }\n }\n path = path ? `${sel} > ${path}` : sel;\n current = parent;\n }\n return path ? `body > ${path}` : 'body';\n };\n const pathSel = gen(el);\n if (pathSel) cands.push({ type: 'css', value: pathSel });\n return cands;\n };\n const onClick = (e) => {\n if (!state.active) return;\n e.preventDefault();\n e.stopPropagation();\n const el = e.target instanceof Element ? e.target : null;\n if (!el) {\n cleanup();\n sendResponse({ success: false, error: 'no element' });\n return true;\n }\n // create ref\n try {\n if (!window.__claudeElementMap) window.__claudeElementMap = {};\n if (!window.__claudeRefCounter) window.__claudeRefCounter = 0;\n } catch {}\n let refId = null;\n try {\n for (const k in window.__claudeElementMap) {\n if (\n window.__claudeElementMap[k].deref &&\n window.__claudeElementMap[k].deref() === el\n ) {\n refId = k;\n break;\n }\n }\n if (!refId) {\n refId = `ref_${++window.__claudeRefCounter}`;\n window.__claudeElementMap[refId] = new WeakRef(el);\n }\n } catch {}\n const cands = computeCandidates(el);\n cleanup();\n sendResponse({ success: true, ref: refId, candidates: cands });\n return true;\n };\n const onKey = (e) => {\n if (e.key === 'Escape') {\n cleanup();\n sendResponse({ success: false, cancelled: true });\n }\n };\n document.addEventListener('mousemove', onMove, true);\n document.addEventListener('click', onClick, true);\n document.addEventListener('keydown', onKey, true);\n return true; // async\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n if (request && request.action === 'rr_picker_stop') {\n try {\n const host = document.getElementById('__rr_picker_host__');\n if (host) host.remove();\n sendResponse({ success: true });\n return true;\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n if (request && request.action === 'generateAccessibilityTree') {\n const result = __generateAccessibilityTree(request.filter || null, {\n maxDepth: request.depth,\n refId: request.refId,\n });\n if (result && result.error) {\n sendResponse({ success: false, error: result.error });\n return true;\n }\n sendResponse({ success: true, ...result });\n return true;\n }\n if (request && request.action === 'ensureRefForSelector') {\n try {\n // Composite selector support: \"frameSelector |> innerSelector\"\n const maybeSel = String(request.selector || '').trim();\n const allowMultiple = !!request.allowMultiple;\n if (maybeSel.includes('|>')) {\n try {\n const parts = maybeSel\n .split('|>')\n .map((s) => s.trim())\n .filter(Boolean);\n if (parts.length >= 2) {\n const frameSel = parts[0];\n const innerSel = parts.slice(1).join(' |> ');\n // Find target frame element in current document\n let frameEl = null;\n try {\n frameEl = querySelectorDeepFirst(frameSel) || document.querySelector(frameSel);\n } catch {}\n if (\n !frameEl ||\n !(frameEl instanceof HTMLIFrameElement || frameEl instanceof HTMLFrameElement)\n ) {\n sendResponse({\n success: false,\n error: `Composite frame selector not found: ${frameSel}`,\n });\n return true;\n }\n const cw = frameEl.contentWindow;\n if (!cw) {\n sendResponse({\n success: false,\n error: 'Unable to obtain contentWindow of target frame',\n });\n return true;\n }\n // Bridge to child frame via postMessage with timeout\n const reqId = `rrc_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n const BRIDGE_TIMEOUT_MS = 5000; // 5 second timeout for iframe bridge\n let responded = false;\n let timeoutHandle = null;\n\n const cleanup = () => {\n window.removeEventListener('message', listener, true);\n if (timeoutHandle) {\n clearTimeout(timeoutHandle);\n timeoutHandle = null;\n }\n };\n\n const listener = (ev) => {\n try {\n const data = ev && ev.data;\n if (\n !data ||\n data.type !== 'rr-bridge-ensure-ref-result' ||\n data.reqId !== reqId\n )\n return;\n // Validate source is the expected frame (security check)\n if (ev.source !== cw) return;\n\n if (responded) return; // Already timed out\n responded = true;\n cleanup();\n\n if (data.success) {\n sendResponse({\n success: true,\n ref: data.ref,\n center: data.center,\n href: data.href,\n });\n } else {\n sendResponse({ success: false, error: data.error || 'child failed' });\n }\n } catch (e) {\n if (!responded) {\n responded = true;\n cleanup();\n sendResponse({\n success: false,\n error: String(e && e.message ? e.message : e),\n });\n }\n }\n };\n\n // Set up timeout to prevent infinite wait\n timeoutHandle = setTimeout(() => {\n if (!responded) {\n responded = true;\n cleanup();\n sendResponse({\n success: false,\n error: `iframe bridge timeout after ${BRIDGE_TIMEOUT_MS}ms`,\n });\n }\n }, BRIDGE_TIMEOUT_MS);\n\n window.addEventListener('message', listener, true);\n cw.postMessage(\n {\n type: 'rr-bridge-ensure-ref',\n reqId,\n selector: innerSel,\n useText: !!request.useText,\n isXPath: !!request.isXPath,\n tagName: String(request.tagName || ''),\n allowMultiple: !!request.allowMultiple,\n },\n '*',\n );\n return true; // async response via message bridge\n }\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n // Support CSS selector, XPath, or visible text search\n const useText = !!request.useText;\n const textQuery = String(request.text || '').trim();\n const sel = String(request.selector || '').trim();\n const isXPath = !!request.isXPath;\n const limitTag = String(request.tagName || '')\n .trim()\n .toUpperCase();\n let el = null;\n if (useText && textQuery) {\n const normalize = (s) =>\n String(s || '')\n .replace(/\\s+/g, ' ')\n .trim()\n .toLowerCase();\n const query = normalize(textQuery);\n const bigrams = (s) => {\n const arr = [];\n for (let i = 0; i < s.length - 1; i++) arr.push(s.slice(i, i + 2));\n return arr;\n };\n const dice = (a, b) => {\n if (!a || !b) return 0;\n const A = bigrams(a);\n const B = bigrams(b);\n if (A.length === 0 || B.length === 0) return 0;\n let inter = 0;\n const map = new Map();\n for (const t of A) map.set(t, (map.get(t) || 0) + 1);\n for (const t of B) {\n const c = map.get(t) || 0;\n if (c > 0) {\n inter++;\n map.set(t, c - 1);\n }\n }\n return (2 * inter) / (A.length + B.length);\n };\n let best = { el: null, score: 0 };\n // Deep traversal including shadow roots\n const stack = [document.documentElement];\n let visited = 0;\n while (stack.length) {\n const node = /** @type {any} */ (stack.pop());\n if (!node || !(node instanceof Element)) continue;\n try {\n if (limitTag && String(node.tagName || '').toUpperCase() !== limitTag) {\n // still traverse into children/shadow for performance? yes\n } else {\n const cs = window.getComputedStyle(node);\n if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') {\n /* skip hidden */\n } else {\n const rect = /** @type {HTMLElement} */ (node).getBoundingClientRect();\n if (rect.width > 0 && rect.height > 0) {\n const txt = normalize(node.textContent || '');\n if (txt) {\n if (txt.includes(query)) {\n el = /** @type {Element} */ (node);\n break;\n }\n const sc = dice(txt, query);\n if (sc > best.score)\n best = { el: /** @type {Element} */ (node), score: sc };\n }\n }\n }\n }\n } catch {}\n // push children and shadow children\n try {\n const children = node.children || [];\n for (let i = 0; i < children.length; i++) stack.push(children[i]);\n } catch {}\n try {\n const sr = node.shadowRoot;\n if (sr && sr.children) {\n for (let i = 0; i < sr.children.length; i++) stack.push(sr.children[i]);\n }\n } catch {}\n if (++visited > 8000) break;\n }\n if (!el && best.el && best.score >= 0.6) el = best.el;\n } else if (isXPath) {\n if (!sel) {\n sendResponse({ success: false, error: 'selector is required' });\n return true;\n }\n const result = queryXPathWithUniquenessCheck(sel, allowMultiple);\n if (result.error) {\n sendResponse({ success: false, error: result.error });\n return true;\n }\n if (result.matchCount === 0) {\n sendResponse({ success: false, error: `selector not found: ${sel}` });\n return true;\n }\n if (!allowMultiple && result.matchCount > 1) {\n sendResponse({\n success: false,\n error: `Selector \"${sel}\" matched multiple elements. Please refine the selector to match only one element.`,\n });\n return true;\n }\n el = result.element;\n } else {\n if (!sel) {\n sendResponse({ success: false, error: 'selector is required' });\n return true;\n }\n const result = querySelectorWithUniquenessCheck(sel, allowMultiple);\n if (result.error) {\n sendResponse({ success: false, error: result.error });\n return true;\n }\n if (result.matchCount === 0) {\n sendResponse({ success: false, error: `selector not found: ${sel}` });\n return true;\n }\n if (!allowMultiple && result.matchCount > 1) {\n sendResponse({\n success: false,\n error: `Selector \"${sel}\" matched multiple elements. Please refine the selector to match only one element.`,\n });\n return true;\n }\n el = result.element;\n }\n if (!el) {\n sendResponse({ success: false, error: `selector not found: ${sel}` });\n return true;\n }\n let refId = null;\n for (const k in window.__claudeElementMap) {\n if (window.__claudeElementMap[k].deref && window.__claudeElementMap[k].deref() === el) {\n refId = k;\n break;\n }\n }\n if (!refId) {\n refId = `ref_${++window.__claudeRefCounter}`;\n window.__claudeElementMap[refId] = new WeakRef(el);\n }\n const rect = /** @type {HTMLElement} */ (el).getBoundingClientRect();\n sendResponse({\n success: true,\n ref: refId,\n center: {\n x: Math.round(rect.left + rect.width / 2),\n y: Math.round(rect.top + rect.height / 2),\n },\n });\n return true;\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n if (request && request.action === 'dispatchHoverForRef') {\n handleHoverForRef(String(request.ref || '').trim())\n .then((result) => sendResponse(result))\n .catch((error) =>\n sendResponse({ success: false, error: error?.message || String(error) }),\n );\n return true;\n }\n if (request && request.action === 'getAttributeForSelector') {\n try {\n const sel = String(request.selector || '').trim();\n const name = String(request.name || '').trim();\n if (!sel || !name) {\n sendResponse({ success: false, error: 'selector and name are required' });\n return true;\n }\n const el = document.querySelector(sel) || querySelectorDeepFirst(sel);\n if (!el) {\n sendResponse({ success: false, error: `selector not found: ${sel}` });\n return true;\n }\n let value = null;\n if (name === 'text' || name === 'textContent') {\n value = (el.textContent || '').trim();\n } else if (name === 'value') {\n try {\n value = /** @type {HTMLInputElement} */ (el).value ?? null;\n } catch (_) {\n value = el.getAttribute('value');\n }\n } else {\n value = el.getAttribute(name);\n }\n sendResponse({ success: true, value });\n return true;\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n if (request && request.action === 'collectVariables') {\n try {\n let vars = Array.isArray(request.variables) ? request.variables : [];\n if ((!vars || vars.length === 0) && request.payload) {\n try {\n const p = JSON.parse(String(request.payload || '{}'));\n if (Array.isArray(p.variables)) vars = p.variables;\n } catch {}\n }\n const useOverlay = request.useOverlay !== false; // default true\n const values = {};\n if (!useOverlay) {\n for (const v of vars) {\n const key = String(v && v.key ? v.key : '');\n if (!key) continue;\n const label = v.label || key;\n const def = v.default || '';\n const promptText = `请输入参数 ${label} (${key})`;\n let val = window.prompt(promptText, def);\n if (typeof val !== 'string') val = def;\n values[key] = val;\n }\n sendResponse({ success: true, values });\n return true;\n }\n // Build overlay form\n const hostId = '__rr_var_overlay__';\n let host = document.getElementById(hostId);\n if (host) host.remove();\n host = document.createElement('div');\n host.id = hostId;\n Object.assign(host.style, {\n position: 'fixed',\n inset: '0',\n background: 'rgba(0,0,0,0.35)',\n zIndex: 2147483646,\n display: 'flex',\n alignItems: 'center',\n justifyContent: 'center',\n });\n const panel = document.createElement('div');\n Object.assign(panel.style, {\n background: '#fff',\n borderRadius: '8px',\n width: 'min(520px, 96vw)',\n maxHeight: '80vh',\n overflow: 'auto',\n boxShadow: '0 8px 24px rgba(0,0,0,0.2)',\n padding: '16px',\n fontFamily: 'system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif',\n });\n const title = document.createElement('div');\n title.textContent = '请输入回放参数';\n Object.assign(title.style, { fontSize: '16px', fontWeight: '600', marginBottom: '12px' });\n const form = document.createElement('form');\n for (const v of vars) {\n const row = document.createElement('div');\n Object.assign(row.style, { marginBottom: '10px' });\n const label = document.createElement('label');\n label.textContent = `${v.label || v.key}${v.sensitive ? ' (敏感)' : ''}`;\n Object.assign(label.style, {\n display: 'block',\n marginBottom: '6px',\n fontWeight: '500',\n });\n const input = document.createElement('input');\n input.type = v.sensitive ? 'password' : 'text';\n input.name = String(v.key);\n input.value = String(v.default || '');\n Object.assign(input.style, {\n width: '100%',\n boxSizing: 'border-box',\n padding: '8px 10px',\n border: '1px solid #d0d7de',\n borderRadius: '6px',\n outline: 'none',\n });\n row.appendChild(label);\n row.appendChild(input);\n form.appendChild(row);\n }\n const actions = document.createElement('div');\n Object.assign(actions.style, { display: 'flex', gap: '8px', marginTop: '12px' });\n const ok = document.createElement('button');\n ok.type = 'submit';\n ok.textContent = '确定';\n Object.assign(ok.style, {\n background: '#0969da',\n color: '#fff',\n border: 'none',\n padding: '8px 16px',\n borderRadius: '6px',\n cursor: 'pointer',\n });\n const cancel = document.createElement('button');\n cancel.type = 'button';\n cancel.textContent = '取消';\n Object.assign(cancel.style, {\n background: '#f3f4f6',\n color: '#111',\n border: '1px solid #d0d7de',\n padding: '8px 16px',\n borderRadius: '6px',\n cursor: 'pointer',\n });\n actions.appendChild(ok);\n actions.appendChild(cancel);\n panel.appendChild(title);\n panel.appendChild(form);\n panel.appendChild(actions);\n host.appendChild(panel);\n document.documentElement.appendChild(host);\n\n const cleanup = () => {\n try {\n host.remove();\n } catch {}\n };\n cancel.onclick = () => {\n cleanup();\n sendResponse({ success: false, cancelled: true });\n };\n form.onsubmit = (e) => {\n e.preventDefault();\n for (const v of vars) {\n const el = form.querySelector(`input[name=\"${CSS.escape(String(v.key))}\"]`);\n if (el) values[v.key] = /** @type {HTMLInputElement} */ (el).value;\n }\n cleanup();\n sendResponse({ success: true, values });\n };\n return true; // async\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n if (request && request.action === 'resolveRef') {\n const ref = request.ref;\n try {\n const map = window.__claudeElementMap;\n const weak = map && map[ref];\n const el = weak && typeof weak.deref === 'function' ? weak.deref() : null;\n if (!el || !(el instanceof Element)) {\n sendResponse({ success: false, error: `ref \"${ref}\" not found or expired` });\n return true;\n }\n const rect = /** @type {HTMLElement} */ (el).getBoundingClientRect();\n sendResponse({\n success: true,\n rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },\n center: {\n x: Math.round(rect.left + rect.width / 2),\n y: Math.round(rect.top + rect.height / 2),\n },\n selector: (function () {\n // Simple selector generation inline to avoid duplication\n const generateSelector = function (node) {\n if (!(node instanceof Element)) return '';\n if (node.id) {\n const idSel = `#${CSS.escape(node.id)}`;\n if (document.querySelectorAll(idSel).length === 1) return idSel;\n }\n // prefer unique class selectors if available\n try {\n const classes = Array.from(node.classList || []).filter(\n (c) => c && /^[a-zA-Z0-9_-]+$/.test(c),\n );\n for (const cls of classes) {\n const sel = `.${CSS.escape(cls)}`;\n if (document.querySelectorAll(sel).length === 1) return sel;\n }\n const tag = node.tagName ? node.tagName.toLowerCase() : '';\n for (const cls of classes) {\n const sel = `${tag}.${CSS.escape(cls)}`;\n if (document.querySelectorAll(sel).length === 1) return sel;\n }\n for (let i = 0; i < Math.min(classes.length, 3); i++) {\n for (let j = i + 1; j < Math.min(classes.length, 3); j++) {\n const sel = `.${CSS.escape(classes[i])}.${CSS.escape(classes[j])}`;\n if (document.querySelectorAll(sel).length === 1) return sel;\n }\n }\n } catch {}\n for (const attr of ['data-testid', 'data-cy', 'name']) {\n const val = node.getAttribute(attr);\n if (val) {\n const s = `[${attr}=\"${CSS.escape(val)}\"]`;\n if (document.querySelectorAll(s).length === 1) return s;\n }\n }\n let path = '';\n let current = node;\n while (\n current &&\n current.nodeType === Node.ELEMENT_NODE &&\n current.tagName !== 'BODY'\n ) {\n let sel = current.tagName.toLowerCase();\n const parent = current.parentElement;\n if (parent) {\n const siblings = Array.from(parent.children).filter(\n (c) => c.tagName === current.tagName,\n );\n if (siblings.length > 1) {\n const idx = siblings.indexOf(current) + 1;\n sel += `:nth-of-type(${idx})`;\n }\n }\n path = path ? `${sel} > ${path}` : sel;\n current = parent;\n }\n return path ? `body > ${path}` : 'body';\n };\n return generateSelector(el);\n })(),\n });\n return true;\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n if (request && request.action === 'verifyFingerprint') {\n try {\n const ref = String(request.ref || '').trim();\n const fingerprint = String(request.fingerprint || '').trim();\n if (!ref || !fingerprint) {\n sendResponse({ success: false, error: 'ref and fingerprint are required' });\n return true;\n }\n const map = window.__claudeElementMap;\n const weak = map && map[ref];\n const el = weak && typeof weak.deref === 'function' ? weak.deref() : null;\n if (!el || !(el instanceof Element)) {\n sendResponse({ success: false, error: `ref \"${ref}\" not found or expired` });\n return true;\n }\n // 验证指纹：解析存储的指纹并与当前元素对比\n const parts = fingerprint.split('|');\n const storedTag = parts[0] || 'unknown';\n const currentTag = el.tagName ? String(el.tagName).toLowerCase() : 'unknown';\n // Tag 必须匹配\n if (storedTag !== currentTag) {\n sendResponse({ success: true, match: false });\n return true;\n }\n // 如果存储的指纹有 id，当前元素必须有相同的 id\n const storedIdPart = parts.find((p) => p.startsWith('id='));\n if (storedIdPart) {\n const storedId = storedIdPart.slice(3);\n const currentId = el.id ? String(el.id).trim() : '';\n if (storedId !== currentId) {\n sendResponse({ success: true, match: false });\n return true;\n }\n }\n sendResponse({ success: true, match: true });\n return true;\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n if (request && request.action === 'focusByRef') {\n try {\n const ref = String(request.ref || '');\n const map = window.__claudeElementMap || {};\n const weak = map[ref];\n const el = weak && typeof weak.deref === 'function' ? weak.deref() : null;\n if (!el || !(el instanceof Element)) {\n sendResponse({ success: false, error: `ref \"${ref}\" not found or expired` });\n return true;\n }\n try {\n /** @type {HTMLElement} */ (el).scrollIntoView({\n behavior: 'instant',\n block: 'center',\n inline: 'nearest',\n });\n } catch {}\n try {\n /** @type {HTMLElement} */ (el).focus && /** @type {HTMLElement} */ (el).focus();\n } catch {}\n sendResponse({ success: true });\n return true;\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n }\n } catch (e) {\n sendResponse({ success: false, error: e && e.message ? e.message : String(e) });\n return true;\n }\n return false;\n });\n\n console.log('Accessibility tree helper script loaded');\n // Cross-frame bridge: child listens for ensure-ref requests from parent (composite selector)\n try {\n window.addEventListener(\n 'message',\n (ev) => {\n try {\n const data = ev && ev.data;\n // Handle hover-ref bridge requests from parent frame\n if (data && data.type === 'rr-bridge-hover-ref') {\n handleHoverForRef(data.ref)\n .then((result) => {\n ev.source?.postMessage(\n { type: 'rr-bridge-hover-ref-result', reqId: data.reqId, result },\n '*',\n );\n })\n .catch((error) => {\n ev.source?.postMessage(\n {\n type: 'rr-bridge-hover-ref-result',\n reqId: data.reqId,\n result: { success: false, error: error?.message || String(error) },\n },\n '*',\n );\n });\n return;\n }\n if (!data || data.type !== 'rr-bridge-ensure-ref') return;\n const { reqId, selector, useText, isXPath, tagName } = data || {};\n const respond = (payload) => {\n try {\n ev.source &&\n ev.source.postMessage(\n { type: 'rr-bridge-ensure-ref-result', reqId, ...payload },\n '*',\n );\n } catch {}\n };\n try {\n const sel = String(selector || '').trim();\n const limitTag = String(tagName || '')\n .trim()\n .toUpperCase();\n let el = null;\n if (useText && sel) {\n const normalize = (s) =>\n String(s || '')\n .replace(/\\s+/g, ' ')\n .trim()\n .toLowerCase();\n const query = normalize(sel);\n const bigrams = (s) => {\n const arr = [];\n for (let i = 0; i < s.length - 1; i++) arr.push(s.slice(i, i + 2));\n return arr;\n };\n const dice = (a, b) => {\n if (!a || !b) return 0;\n const A = bigrams(a),\n B = bigrams(b);\n if (!A.length || !B.length) return 0;\n let inter = 0;\n const m = new Map();\n for (const t of A) m.set(t, (m.get(t) || 0) + 1);\n for (const t of B) {\n const c = m.get(t) || 0;\n if (c > 0) {\n inter++;\n m.set(t, c - 1);\n }\n }\n return (2 * inter) / (A.length + B.length);\n };\n let best = { el: null, score: 0 };\n const stack = [document.documentElement];\n while (stack.length) {\n const node = stack.pop();\n if (!node || !(node instanceof Element)) continue;\n try {\n if (limitTag && String(node.tagName || '').toUpperCase() !== limitTag) {\n } else {\n const cs = window.getComputedStyle(node);\n if (cs.display !== 'none' && cs.visibility !== 'hidden' && cs.opacity !== '0') {\n const rect = node.getBoundingClientRect();\n if (rect.width > 0 && rect.height > 0) {\n const txt = normalize(node.textContent || '');\n if (txt) {\n if (txt.includes(query)) {\n el = node;\n break;\n }\n const sc = dice(txt, query);\n if (sc > best.score) best = { el: node, score: sc };\n }\n }\n }\n }\n } catch {}\n try {\n const children = node.children || [];\n for (let i = 0; i < children.length; i++) stack.push(children[i]);\n const sr = node.shadowRoot;\n if (sr && sr.children)\n for (let i = 0; i < sr.children.length; i++) stack.push(sr.children[i]);\n } catch {}\n }\n if (!el && best.el) el = best.el;\n } else if (isXPath) {\n if (!sel) {\n respond({ success: false, error: 'selector is required' });\n return;\n }\n const allowMultiple = !!data.allowMultiple;\n const result = queryXPathWithUniquenessCheck(sel, allowMultiple);\n if (result.error) {\n respond({ success: false, error: result.error });\n return;\n }\n if (result.matchCount === 0) {\n respond({ success: false, error: `Selector \"${sel}\" not found in child frame` });\n return;\n }\n if (!allowMultiple && result.matchCount > 1) {\n respond({\n success: false,\n error: `Selector \"${sel}\" matched multiple elements inside frame. Please refine the selector to match only one element.`,\n });\n return;\n }\n el = result.element;\n } else {\n if (!sel) {\n respond({ success: false, error: 'selector is required' });\n return;\n }\n const allowMultiple = !!data.allowMultiple;\n const result = querySelectorWithUniquenessCheck(sel, allowMultiple);\n if (result.error) {\n respond({ success: false, error: result.error });\n return;\n }\n if (result.matchCount === 0) {\n respond({ success: false, error: `Selector \"${sel}\" not found in child frame` });\n return;\n }\n if (!allowMultiple && result.matchCount > 1) {\n respond({\n success: false,\n error: `Selector \"${sel}\" matched multiple elements inside frame. Please refine the selector to match only one element.`,\n });\n return;\n }\n el = result.element;\n }\n if (!el || !(el instanceof Element)) {\n respond({ success: false, error: 'Element not found in child frame' });\n return;\n }\n if (!window.__claudeElementMap) window.__claudeElementMap = {};\n if (!window.__claudeRefCounter) window.__claudeRefCounter = 0;\n let refId = null;\n for (const k in window.__claudeElementMap) {\n const w = window.__claudeElementMap[k];\n if (w && typeof w.deref === 'function' && w.deref && w.deref() === el) {\n refId = k;\n break;\n }\n }\n if (!refId) {\n refId = `ref_${++window.__claudeRefCounter}`;\n window.__claudeElementMap[refId] = new WeakRef(el);\n }\n const rect = el.getBoundingClientRect();\n respond({\n success: true,\n ref: refId,\n center: {\n x: Math.round(rect.left + rect.width / 2),\n y: Math.round(rect.top + rect.height / 2),\n },\n href: String(location && location.href ? location.href : ''),\n });\n } catch (e) {\n respond({ success: false, error: String(e && e.message ? e.message : e) });\n }\n } catch {}\n },\n true,\n );\n } catch {}\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/click-helper.js", "content": "/* eslint-disable */\n// click-helper.js\n// This script is injected into the page to handle click operations\n\nif (window.__CLICK_HELPER_INITIALIZED__) {\n // Already initialized, skip\n} else {\n window.__CLICK_HELPER_INITIALIZED__ = true;\n /**\n * Click on an element matching the selector or at specific coordinates\n * @param {string} selector - CSS selector for the element to click\n * @param {boolean} waitForNavigation - Whether to wait for navigation to complete after click\n * @param {number} timeout - Timeout in milliseconds for waiting for the element or navigation\n * @param {Object} coordinates - Optional coordinates for clicking at a specific position\n * @param {number} coordinates.x - X coordinate relative to the viewport\n * @param {number} coordinates.y - Y coordinate relative to the viewport\n * @returns {Promise} - Result of the click operation\n */\n async function clickElement(\n selector,\n waitForNavigation = false,\n timeout = 5000,\n coordinates = null,\n ref = null,\n double = false,\n options = {},\n ) {\n try {\n let element = null;\n let elementInfo = null;\n let clickX, clickY;\n\n if (ref && typeof ref === 'string') {\n // Resolve element from weak map\n let target = null;\n try {\n const map = window.__claudeElementMap;\n const weak = map && map[ref];\n target = weak && typeof weak.deref === 'function' ? weak.deref() : null;\n } catch (e) {\n // ignore\n }\n\n if (!target || !(target instanceof Element)) {\n return {\n error: `Element ref \"${ref}\" not found. Please call chrome_read_page first and ensure the ref is still valid.`,\n };\n }\n\n element = target;\n element.scrollIntoView({ behavior: 'auto', block: 'center', inline: 'center' });\n await new Promise((resolve) => setTimeout(resolve, 80));\n\n const rect = element.getBoundingClientRect();\n clickX = rect.left + rect.width / 2;\n clickY = rect.top + rect.height / 2;\n elementInfo = {\n tagName: element.tagName,\n id: element.id,\n className: element.className,\n text: element.textContent?.trim().substring(0, 100) || '',\n href: element.href || null,\n type: element.type || null,\n isVisible: true,\n rect: {\n x: rect.x,\n y: rect.y,\n width: rect.width,\n height: rect.height,\n top: rect.top,\n right: rect.right,\n bottom: rect.bottom,\n left: rect.left,\n },\n clickMethod: 'ref',\n ref,\n };\n } else if (\n coordinates &&\n typeof coordinates.x === 'number' &&\n typeof coordinates.y === 'number'\n ) {\n clickX = coordinates.x;\n clickY = coordinates.y;\n\n element = document.elementFromPoint(clickX, clickY);\n\n if (element) {\n const rect = element.getBoundingClientRect();\n elementInfo = {\n tagName: element.tagName,\n id: element.id,\n className: element.className,\n text: element.textContent?.trim().substring(0, 100) || '',\n href: element.href || null,\n type: element.type || null,\n isVisible: true,\n rect: {\n x: rect.x,\n y: rect.y,\n width: rect.width,\n height: rect.height,\n top: rect.top,\n right: rect.right,\n bottom: rect.bottom,\n left: rect.left,\n },\n clickMethod: 'coordinates',\n clickPosition: { x: clickX, y: clickY },\n };\n } else {\n elementInfo = {\n clickMethod: 'coordinates',\n clickPosition: { x: clickX, y: clickY },\n warning: 'No element found at the specified coordinates',\n };\n }\n } else {\n element = document.querySelector(selector);\n if (!element) {\n return {\n error: `Element with selector \"${selector}\" not found`,\n };\n }\n\n const rect = element.getBoundingClientRect();\n elementInfo = {\n tagName: element.tagName,\n id: element.id,\n className: element.className,\n text: element.textContent?.trim().substring(0, 100) || '',\n href: element.href || null,\n type: element.type || null,\n isVisible: true,\n rect: {\n x: rect.x,\n y: rect.y,\n width: rect.width,\n height: rect.height,\n top: rect.top,\n right: rect.right,\n bottom: rect.bottom,\n left: rect.left,\n },\n clickMethod: 'selector',\n };\n\n // First sroll so that the element is in view, then check visibility.\n element.scrollIntoView({ behavior: 'auto', block: 'center', inline: 'center' });\n await new Promise((resolve) => setTimeout(resolve, 100));\n elementInfo.isVisible = isElementVisible(element);\n if (!elementInfo.isVisible) {\n return {\n error: `Element with selector \"${selector}\" is not visible`,\n elementInfo,\n };\n }\n\n const updatedRect = element.getBoundingClientRect();\n clickX = updatedRect.left + updatedRect.width / 2;\n clickY = updatedRect.top + updatedRect.height / 2;\n }\n\n let navigationPromise;\n if (waitForNavigation) {\n navigationPromise = new Promise((resolve) => {\n const beforeUnloadListener = () => {\n window.removeEventListener('beforeunload', beforeUnloadListener);\n resolve(true);\n };\n window.addEventListener('beforeunload', beforeUnloadListener);\n\n setTimeout(() => {\n window.removeEventListener('beforeunload', beforeUnloadListener);\n resolve(false);\n }, timeout);\n });\n }\n\n if (\n element &&\n (elementInfo.clickMethod === 'selector' || elementInfo.clickMethod === 'ref')\n ) {\n if (double) {\n dispatchClickSequence(element, clickX, clickY, options, true);\n } else {\n dispatchClickSequence(element, clickX, clickY, options, false);\n }\n } else {\n if (double) simulateDoubleClick(clickX, clickY, options);\n else simulateClick(clickX, clickY, options);\n }\n\n // Wait for navigation if needed\n let navigationOccurred = false;\n if (waitForNavigation) {\n navigationOccurred = await navigationPromise;\n }\n\n return {\n success: true,\n message: 'Element clicked successfully',\n elementInfo,\n navigationOccurred,\n };\n } catch (error) {\n return {\n error: `Error clicking element: ${error.message}`,\n };\n }\n }\n\n /**\n * Simulate a mouse click at specific coordinates\n * @param {number} x - X coordinate relative to the viewport\n * @param {number} y - Y coordinate relative to the viewport\n */\n function simulateClick(x, y, options = {}) {\n const element = document.elementFromPoint(x, y);\n if (!element) return;\n dispatchClickSequence(element, x, y, options, false);\n }\n\n /**\n * Simulate a double click sequence at specific coordinates\n */\n function simulateDoubleClick(x, y, options = {}) {\n const element = document.elementFromPoint(x, y);\n if (!element) return;\n dispatchClickSequence(element, x, y, options, true);\n }\n\n /**\n * Simulate double click using element when available\n */\n function simulateDomDoubleClick(element, x, y, options) {\n dispatchClickSequence(element, x, y, options, true);\n }\n\n function normalizeMouseOpts(x, y, options = {}) {\n const bubbles = options.bubbles !== false; // default true\n const cancelable = options.cancelable !== false; // default true\n const altKey = !!(options.modifiers && options.modifiers.altKey);\n const ctrlKey = !!(options.modifiers && options.modifiers.ctrlKey);\n const metaKey = !!(options.modifiers && options.modifiers.metaKey);\n const shiftKey = !!(options.modifiers && options.modifiers.shiftKey);\n const btn = String(options.button || 'left');\n const button = btn === 'right' ? 2 : btn === 'middle' ? 1 : 0;\n const buttons = btn === 'right' ? 2 : btn === 'middle' ? 4 : 1;\n return {\n bubbles,\n cancelable,\n altKey,\n ctrlKey,\n metaKey,\n shiftKey,\n button,\n buttons,\n clientX: x,\n clientY: y,\n view: window,\n };\n }\n\n function dispatchClickSequence(element, x, y, options = {}, isDouble = false) {\n const base = normalizeMouseOpts(x, y, options);\n const down = new MouseEvent('mousedown', base);\n const up = new MouseEvent('mouseup', base);\n const click = new MouseEvent('click', base);\n try {\n element.dispatchEvent(down);\n } catch {}\n try {\n element.dispatchEvent(up);\n } catch {}\n try {\n element.dispatchEvent(click);\n } catch {}\n if (base.button === 2) {\n // right button contextmenu\n const ctx = new MouseEvent('contextmenu', base);\n try {\n element.dispatchEvent(ctx);\n } catch {}\n }\n if (isDouble) {\n // second sequence + dblclick\n setTimeout(() => {\n try {\n element.dispatchEvent(new MouseEvent('mousedown', base));\n } catch {}\n try {\n element.dispatchEvent(new MouseEvent('mouseup', base));\n } catch {}\n try {\n element.dispatchEvent(new MouseEvent('click', base));\n } catch {}\n try {\n element.dispatchEvent(new MouseEvent('dblclick', base));\n } catch {}\n }, 30);\n }\n }\n\n /**\n * Check if an element is visible\n * @param {Element} element - The element to check\n * @returns {boolean} - Whether the element is visible\n */\n function isElementVisible(element) {\n if (!element) return false;\n\n const style = window.getComputedStyle(element);\n if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {\n return false;\n }\n\n const rect = element.getBoundingClientRect();\n if (rect.width === 0 || rect.height === 0) {\n return false;\n }\n\n if (\n rect.bottom < 0 ||\n rect.top > window.innerHeight ||\n rect.right < 0 ||\n rect.left > window.innerWidth\n ) {\n return false;\n }\n\n const centerX = rect.left + rect.width / 2;\n const centerY = rect.top + rect.height / 2;\n\n const elementAtPoint = document.elementFromPoint(centerX, centerY);\n if (!elementAtPoint) return false;\n\n return element === elementAtPoint || element.contains(elementAtPoint);\n }\n\n // Listen for messages from the extension\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n if (request.action === 'clickElement') {\n clickElement(\n request.selector,\n request.waitForNavigation,\n request.timeout,\n request.coordinates,\n request.ref,\n !!request.double,\n {\n button: request.button,\n bubbles: request.bubbles,\n cancelable: request.cancelable,\n modifiers: request.modifiers,\n },\n )\n .then(sendResponse)\n .catch((error) => {\n sendResponse({\n error: `Unexpected error: ${error.message}`,\n });\n });\n return true; // Indicates async response\n } else if (request.action === 'chrome_click_element_ping') {\n sendResponse({ status: 'pong' });\n return false;\n }\n });\n}\n" }, { "path": "app/chrome-extension/inject-scripts/dom-observer.js", "content": "/* eslint-disable */\n// dom-observer.js - observe DOM for triggers and notify background\n(function () {\n if (window.__RR_DOM_OBSERVER__) return;\n window.__RR_DOM_OBSERVER__ = true;\n\n const active = { triggers: [], hits: new Map() };\n\n function now() {\n return Date.now();\n }\n\n function applyTriggers(list) {\n try {\n active.triggers = Array.isArray(list) ? list.slice() : [];\n active.hits.clear();\n checkAll();\n } catch (e) {}\n }\n\n function checkAll() {\n try {\n for (const t of active.triggers) {\n maybeFire(t);\n }\n } catch (e) {}\n }\n\n function maybeFire(t) {\n try {\n const appear = t.appear !== false; // default true\n const sel = String(t.selector || '').trim();\n if (!sel) return;\n const exists = !!document.querySelector(sel);\n const key = t.id;\n const last = active.hits.get(key) || 0;\n const debounce = Math.max(0, Number(t.debounceMs ?? 800));\n if (now() - last < debounce) return;\n const should = appear ? exists : !exists;\n if (should) {\n active.hits.set(key, now());\n chrome.runtime.sendMessage({\n action: 'dom_trigger_fired',\n triggerId: t.id,\n url: location.href,\n });\n if (t.once !== false) removeTrigger(t.id);\n }\n } catch (e) {}\n }\n\n function removeTrigger(id) {\n try {\n active.triggers = active.triggers.filter((x) => x.id !== id);\n } catch (e) {}\n }\n\n const mo = new MutationObserver(() => {\n checkAll();\n });\n try {\n mo.observe(document.documentElement || document, {\n childList: true,\n subtree: true,\n attributes: false,\n characterData: false,\n });\n } catch (e) {}\n\n chrome.runtime.onMessage.addListener((req, _sender, sendResponse) => {\n try {\n if (req && req.action === 'dom_observer_ping') {\n sendResponse({ status: 'pong' });\n return false;\n }\n if (req && req.action === 'set_dom_triggers') {\n applyTriggers(req.triggers || []);\n sendResponse({ success: true, count: active.triggers.length });\n return true;\n }\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n return false;\n });\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/element-marker.js", "content": "/* eslint-disable */\n(function () {\n if (window.__ELEMENT_MARKER_INSTALLED__) return;\n window.__ELEMENT_MARKER_INSTALLED__ = true;\n\n const IS_MAIN = window === window.top;\n\n // ============================================================================\n // Utility Functions\n // ============================================================================\n\n function sleep(ms) {\n return new Promise((resolve) => setTimeout(resolve, ms));\n }\n\n // ============================================================================\n // Constants & Configuration\n // ============================================================================\n\n const CONFIG = {\n DEFAULTS: {\n PREFS: {\n preferId: true,\n preferStableAttr: true,\n preferClass: true,\n },\n SELECTOR_TYPE: 'css',\n LIST_MODE: false,\n },\n Z_INDEX: {\n OVERLAY: 2147483646,\n HIGHLIGHTER: 2147483645,\n RECTS: 2147483644,\n },\n COLORS: {\n PRIMARY: '#2563eb',\n SUCCESS: '#10b981',\n WARNING: '#f59e0b',\n DANGER: '#ef4444',\n HOVER: '#10b981',\n VERIFY: '#3b82f6',\n },\n };\n\n // ============================================================================\n // Panel Host Module - Shadow DOM Management\n // ============================================================================\n\n const PanelHost = (() => {\n let hostElement = null;\n let shadowRoot = null;\n\n const PANEL_STYLES = `\n * {\n box-sizing: border-box;\n margin: 0;\n padding: 0;\n }\n\n .em-panel {\n width: 400px;\n background: #ffffff;\n border-radius: 12px;\n box-shadow: 0 10px 40px rgba(0, 0, 0, 0.15);\n font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;\n padding: 20px;\n transition: opacity 150ms ease;\n }\n\n\n /* Header */\n .em-header {\n display: flex;\n align-items: center;\n justify-content: space-between;\n margin-bottom: 20px;\n user-select: none;\n }\n\n .em-title {\n font-size: 20px;\n font-weight: 500;\n color: #262626;\n }\n\n .em-header-actions {\n display: flex;\n gap: 4px;\n align-items: center;\n }\n\n .em-icon-btn {\n width: 32px;\n height: 32px;\n display: flex;\n align-items: center;\n justify-content: center;\n border: none;\n background: transparent;\n color: #a3a3a3;\n cursor: pointer;\n transition: color 150ms ease;\n padding: 0;\n }\n\n .em-icon-btn:hover {\n color: #525252;\n }\n\n .em-icon-btn svg {\n width: 20px;\n height: 20px;\n stroke-width: 2;\n }\n\n /* Controls Row */\n .em-controls {\n display: flex;\n gap: 8px;\n margin-bottom: 12px;\n }\n\n .em-select-wrapper {\n flex: 1;\n position: relative;\n }\n\n .em-select {\n width: 100%;\n height: 44px;\n padding: 0 40px 0 16px;\n background: #f5f5f5;\n color: #262626;\n font-size: 15px;\n border: none;\n border-radius: 10px;\n appearance: none;\n cursor: pointer;\n outline: none;\n font-family: inherit;\n font-weight: 400;\n }\n\n .em-select-wrapper::after {\n content: '';\n position: absolute;\n right: 16px;\n top: 50%;\n transform: translateY(-50%);\n width: 0;\n height: 0;\n border-left: 5px solid transparent;\n border-right: 5px solid transparent;\n border-top: 6px solid #737373;\n pointer-events: none;\n }\n\n .em-square-btn {\n width: 44px;\n height: 44px;\n display: flex;\n align-items: center;\n justify-content: center;\n background: #f5f5f5;\n border: none;\n border-radius: 10px;\n cursor: pointer;\n transition: background 150ms ease;\n padding: 0;\n }\n\n .em-square-btn:hover {\n background: #e5e5e5;\n }\n\n .em-square-btn.active {\n background: #2563eb;\n }\n\n .em-square-btn.active svg {\n color: #ffffff;\n }\n\n .em-square-btn svg {\n width: 18px;\n height: 18px;\n color: #525252;\n stroke-width: 2;\n }\n\n /* Selector Display */\n .em-selector-display {\n display: flex;\n align-items: center;\n gap: 10px;\n height: 44px;\n padding: 0 12px 0 16px;\n background: #f5f5f5;\n border-radius: 10px;\n margin-bottom: 16px;\n }\n\n .em-selector-display svg {\n width: 18px;\n height: 18px;\n color: #a3a3a3;\n flex-shrink: 0;\n stroke-width: 2;\n }\n\n .em-selector-text {\n flex: 1;\n font-size: 14px;\n color: #525252;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n user-select: text;\n }\n\n .em-selector-nav {\n display: flex;\n gap: 2px;\n }\n\n .em-nav-btn {\n width: 28px;\n height: 28px;\n display: flex;\n align-items: center;\n justify-content: center;\n border: none;\n background: transparent;\n cursor: pointer;\n transition: background 150ms ease;\n border-radius: 6px;\n padding: 0;\n }\n\n .em-nav-btn:hover {\n background: #e5e5e5;\n }\n\n .em-nav-btn svg {\n width: 16px;\n height: 16px;\n color: #525252;\n stroke-width: 2;\n }\n\n /* Tabs */\n .em-tabs {\n display: inline-flex;\n gap: 2px;\n padding: 2px;\n background: #f5f5f5;\n border-radius: 8px;\n margin-bottom: 16px;\n }\n\n .em-tab {\n padding: 6px 16px;\n font-size: 12px;\n font-weight: 500;\n color: #737373;\n background: transparent;\n border: none;\n border-radius: 6px;\n cursor: pointer;\n transition: all 150ms ease;\n }\n\n .em-tab:hover {\n color: #404040;\n }\n\n .em-tab.active {\n color: #262626;\n background: #ffffff;\n box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);\n }\n\n /* Content */\n .em-content {\n margin-bottom: 0;\n }\n\n #__em_tab_settings {\n max-height: min(60vh, 480px);\n overflow-y: auto;\n scrollbar-width: none; /* Firefox */\n -ms-overflow-style: none; /* IE and Edge */\n }\n\n #__em_tab_settings::-webkit-scrollbar {\n display: none; /* Chrome, Safari, Opera */\n }\n\n .em-section-title {\n font-size: 13px;\n color: #737373;\n margin-bottom: 16px;\n font-weight: 400;\n }\n\n .em-attributes {\n display: flex;\n flex-direction: column;\n gap: 12px;\n }\n\n .em-attribute {\n display: flex;\n flex-direction: column;\n gap: 6px;\n }\n\n .em-attribute-label {\n font-size: 12px;\n color: #a3a3a3;\n font-weight: 400;\n }\n\n .em-attribute-value {\n display: flex;\n align-items: center;\n gap: 10px;\n min-height: 44px;\n padding: 0 12px 0 16px;\n background: #f5f5f5;\n border-radius: 10px;\n }\n\n .em-attribute-value.editable {\n padding: 0 16px;\n }\n\n .em-attribute-value svg {\n width: 18px;\n height: 18px;\n stroke-width: 2;\n cursor: pointer;\n transition: color 150ms ease;\n flex-shrink: 0;\n }\n\n .em-attribute-value svg.copy-icon {\n color: #a3a3a3;\n }\n\n .em-attribute-value svg.copy-icon:hover {\n color: #525252;\n }\n\n .em-attribute-value svg.copy-icon.disabled {\n color: #d4d4d4;\n cursor: default;\n }\n\n .em-attribute-text {\n flex: 1;\n font-size: 14px;\n color: #404040;\n user-select: text;\n }\n\n .em-attribute-text.empty {\n color: #a3a3a3;\n }\n\n .em-input {\n flex: 1;\n border: none;\n background: transparent;\n font-size: 14px;\n color: #404040;\n font-family: inherit;\n outline: none;\n padding: 0;\n height: 44px;\n }\n\n .em-input::placeholder {\n color: #a3a3a3;\n }\n\n /* Settings Panel */\n .em-settings {\n display: flex;\n flex-direction: column;\n gap: 16px;\n }\n\n .em-settings-group {\n display: flex;\n flex-direction: column;\n gap: 8px;\n }\n\n .em-settings-label {\n font-size: 12px;\n font-weight: 500;\n color: #737373;\n }\n\n .em-checkbox-group {\n display: flex;\n flex-direction: column;\n gap: 10px;\n }\n\n .em-checkbox-label {\n display: flex;\n align-items: center;\n gap: 8px;\n font-size: 14px;\n color: #404040;\n cursor: pointer;\n }\n\n .em-checkbox-label input[type=\"checkbox\"] {\n width: 18px;\n height: 18px;\n cursor: pointer;\n margin: 0;\n }\n\n /* Action Buttons */\n .em-actions {\n display: flex;\n gap: 8px;\n margin-top: 20px;\n }\n\n .em-btn {\n flex: 1;\n height: 40px;\n border: none;\n border-radius: 8px;\n font-size: 14px;\n font-weight: 600;\n cursor: pointer;\n transition: all 150ms ease;\n }\n\n .em-btn-primary {\n background: #2563eb;\n color: #ffffff;\n }\n\n .em-btn-primary:hover {\n background: #1d4ed8;\n transform: translateY(-1px);\n box-shadow: 0 4px 12px rgba(37, 99, 235, 0.3);\n }\n\n .em-btn-success {\n background: #10b981;\n color: #ffffff;\n }\n\n .em-btn-success:hover {\n background: #059669;\n transform: translateY(-1px);\n box-shadow: 0 4px 12px rgba(16, 185, 129, 0.3);\n }\n\n .em-btn-ghost {\n background: #f5f5f5;\n color: #404040;\n }\n\n .em-btn-ghost:hover {\n background: #e5e5e5;\n }\n\n /* Footer */\n .em-footer {\n font-size: 12px;\n color: #a3a3a3;\n text-align: center;\n margin-top: 16px;\n }\n\n .em-footer kbd {\n display: inline-block;\n padding: 2px 6px;\n background: #f5f5f5;\n border-radius: 4px;\n font-family: monospace;\n font-size: 11px;\n color: #737373;\n }\n\n /* Status */\n .em-status {\n font-size: 13px;\n padding: 10px 12px;\n border-radius: 8px;\n margin-bottom: 12px;\n display: flex;\n align-items: center;\n gap: 6px;\n }\n\n .em-status.idle {\n display: none;\n }\n\n .em-status.running {\n background: rgba(37, 99, 235, 0.1);\n color: #2563eb;\n }\n\n .em-status.success {\n background: rgba(16, 185, 129, 0.1);\n color: #10b981;\n }\n\n .em-status.failure {\n background: rgba(239, 68, 68, 0.1);\n color: #ef4444;\n }\n\n /* Grid Layout */\n .em-grid {\n display: grid;\n grid-template-columns: repeat(2, 1fr);\n gap: 12px;\n }\n\n .em-field {\n display: flex;\n flex-direction: column;\n gap: 6px;\n }\n\n .em-field-label {\n font-size: 12px;\n color: #a3a3a3;\n }\n\n .em-field-input {\n height: 40px;\n padding: 0 12px;\n background: #f5f5f5;\n border: none;\n border-radius: 8px;\n font-size: 14px;\n color: #404040;\n font-family: inherit;\n outline: none;\n }\n\n .em-field-input:focus {\n background: #e5e5e5;\n }\n\n /* Details/Accordion */\n .em-details {\n margin-top: 12px;\n padding-top: 12px;\n border-top: 1px solid #f5f5f5;\n }\n\n .em-details summary {\n cursor: pointer;\n font-size: 13px;\n font-weight: 600;\n color: #737373;\n padding: 8px 0;\n user-select: none;\n list-style: none;\n }\n\n .em-details summary::-webkit-details-marker {\n display: none;\n }\n\n .em-details summary:hover {\n color: #404040;\n }\n\n .em-details[open] summary {\n margin-bottom: 12px;\n }\n\n /* Dragging state */\n body[data-em-dragging] {\n user-select: none !important;\n cursor: grabbing !important;\n }\n\n body[data-em-dragging] * {\n cursor: grabbing !important;\n }\n\n /* SVG Icons */\n svg {\n fill: none;\n stroke: currentColor;\n }\n\n .em-drag-handle {\n cursor: grab;\n }\n\n .em-drag-handle:active {\n cursor: grabbing;\n }\n `;\n\n const PANEL_TEMPLATE = `\n
\n \n
\n

元素标注

\n
\n \n
\n
\n\n \n
\n
\n \n
\n \n \n
\n\n \n
\n \n \n \n Click an element to select\n
\n \n \n
\n
\n\n \n
\n \n \n
\n\n \n
\n\n \n
\n

#1 Element

\n \n
\n
\n
name
\n
\n \n
\n
\n\n
\n
selector
\n
\n \n \n \n -\n
\n
\n
\n\n

Selector Preferences

\n
\n
\n \n \n \n
\n
\n\n
\n \n
\n\n
\n \n \n
\n
\n\n \n
\n
\n
\n
Action
\n
\n \n
\n
\n\n \n
\n
Text
\n \n
\n\n
\n
Keys
\n \n
\n\n
\n
Scroll Direction
\n
\n \n
\n
\n
Amount (1-10, ~100px each)
\n \n
\n
\n\n \n
\n
\n
\n
Button
\n \n
\n
\n
Timeout (ms)
\n \n
\n
\n\n
\n \n \n \n \n \n
\n
\n\n
\n \n
\n\n \n
\n
Recent Executions
\n
\n
\n
\n
\n\n \n
\n Click or press Space to select an element\n
\n
\n `;\n\n function mount() {\n if (hostElement) return { host: hostElement, shadow: shadowRoot };\n\n hostElement = document.createElement('div');\n hostElement.id = '__element_marker_overlay';\n Object.assign(hostElement.style, {\n position: 'fixed',\n top: '24px',\n right: '24px',\n zIndex: String(CONFIG.Z_INDEX.OVERLAY),\n pointerEvents: 'none',\n });\n\n shadowRoot = hostElement.attachShadow({ mode: 'open' });\n shadowRoot.innerHTML = `${PANEL_TEMPLATE}`;\n\n hostElement.querySelector = (...args) => shadowRoot.querySelector(...args);\n hostElement.querySelectorAll = (...args) => shadowRoot.querySelectorAll(...args);\n\n const panel = shadowRoot.querySelector('.em-panel');\n if (panel) {\n panel.style.pointerEvents = 'auto';\n }\n\n document.documentElement.appendChild(hostElement);\n return { host: hostElement, shadow: shadowRoot };\n }\n\n function unmount() {\n if (hostElement?.parentNode) {\n hostElement.parentNode.removeChild(hostElement);\n }\n hostElement = null;\n shadowRoot = null;\n }\n\n function getHost() {\n return hostElement;\n }\n\n function getShadow() {\n return shadowRoot;\n }\n\n return {\n mount,\n unmount,\n getHost,\n getShadow,\n };\n })();\n\n // ============================================================================\n // State Store Module - Centralized State Management\n // ============================================================================\n\n const StateStore = (() => {\n const state = {\n selectorType: CONFIG.DEFAULTS.SELECTOR_TYPE,\n listMode: CONFIG.DEFAULTS.LIST_MODE,\n prefs: { ...CONFIG.DEFAULTS.PREFS },\n activeTab: 'attributes',\n validation: {\n status: 'idle',\n message: '',\n },\n validationHistory: [], // Last 5 validation results\n };\n\n const listeners = new Set();\n\n function init() {\n return state;\n }\n\n function get(key) {\n return key ? state[key] : state;\n }\n\n function set(partial) {\n const changed = {};\n\n Object.keys(partial).forEach((key) => {\n if (JSON.stringify(state[key]) !== JSON.stringify(partial[key])) {\n changed[key] = true;\n state[key] = partial[key];\n }\n });\n\n if (Object.keys(changed).length === 0) return;\n\n if (changed.validation) {\n updateValidationUI();\n }\n if (changed.activeTab) {\n updateTabUI();\n }\n if (changed.listMode) {\n updateListModeUI();\n }\n if (changed.validationHistory) {\n updateValidationHistoryUI();\n }\n\n notifyListeners();\n }\n\n function subscribe(callback) {\n listeners.add(callback);\n return () => listeners.delete(callback);\n }\n\n function notifyListeners() {\n listeners.forEach((cb) => {\n try {\n cb(state);\n } catch (err) {\n console.error('[StateStore] Listener error:', err);\n }\n });\n }\n\n function updateValidationUI() {\n const statusEl = PanelHost.getShadow()?.getElementById('__em_status');\n if (!statusEl) return;\n\n const { status, message } = state.validation;\n statusEl.className = `em-status ${status}`;\n statusEl.textContent = message;\n }\n\n function updateListModeUI() {\n const shadow = PanelHost.getShadow();\n if (!shadow) return;\n\n const btn = shadow.getElementById('__em_toggle_list');\n if (!btn) return;\n\n if (state.listMode) {\n btn.classList.add('active');\n } else {\n btn.classList.remove('active');\n }\n }\n\n function updateTabUI() {\n const shadow = PanelHost.getShadow();\n if (!shadow) return;\n\n const tabs = shadow.querySelectorAll('.em-tab');\n tabs.forEach((tab) => {\n if (tab.dataset.tab === state.activeTab) {\n tab.classList.add('active');\n } else {\n tab.classList.remove('active');\n }\n });\n\n const attrContent = shadow.getElementById('__em_tab_attributes');\n const executeContent = shadow.getElementById('__em_tab_execute');\n\n if (attrContent)\n attrContent.style.display = state.activeTab === 'attributes' ? 'block' : 'none';\n if (executeContent)\n executeContent.style.display = state.activeTab === 'execute' ? 'block' : 'none';\n\n // Sync interaction mode when tab changes\n syncInteractionMode();\n }\n\n function updateValidationHistoryUI() {\n const shadow = PanelHost.getShadow();\n if (!shadow) return;\n\n const historyContainer = shadow.getElementById('__em_execution_history');\n const historyList = shadow.getElementById('__em_history_list');\n if (!historyContainer || !historyList) return;\n\n if (state.validationHistory.length === 0) {\n historyContainer.style.display = 'none';\n return;\n }\n\n historyContainer.style.display = 'block';\n historyList.innerHTML = state.validationHistory\n .slice(-5)\n .reverse()\n .map((entry) => {\n const icon = entry.success ? '✓' : '✗';\n const color = entry.success ? '#10b981' : '#ef4444';\n const timestamp = new Date(entry.timestamp).toLocaleTimeString();\n return `
\n ${icon}\n ${entry.action}\n ${timestamp}\n
`;\n })\n .join('');\n }\n\n return {\n init,\n get,\n set,\n subscribe,\n };\n })();\n\n // ============================================================================\n // Drag Controller Module\n // ============================================================================\n\n const DragController = (() => {\n let dragging = false;\n let startPos = { x: 0, y: 0 };\n let startOffset = { top: 0, right: 0 };\n\n function init(handleElement) {\n if (!handleElement) return;\n handleElement.addEventListener('mousedown', onDragStart);\n }\n\n function onDragStart(event) {\n event.preventDefault();\n dragging = true;\n\n const host = PanelHost.getHost();\n if (!host) return;\n\n startPos = { x: event.clientX, y: event.clientY };\n startOffset = {\n top: parseInt(host.style.top) || 0,\n right: parseInt(host.style.right) || 0,\n };\n\n document.addEventListener('mousemove', onDragMove, { capture: true, passive: false });\n document.addEventListener('mouseup', onDragEnd, { capture: true, passive: false });\n document.body.setAttribute('data-em-dragging', 'true');\n }\n\n function onDragMove(event) {\n if (!dragging) return;\n event.preventDefault();\n event.stopPropagation();\n\n const host = PanelHost.getHost();\n if (!host) return;\n\n const deltaX = event.clientX - startPos.x;\n const deltaY = event.clientY - startPos.y;\n\n const newTop = Math.max(8, startOffset.top + deltaY);\n const newRight = Math.max(8, startOffset.right - deltaX);\n\n host.style.top = `${newTop}px`;\n host.style.right = `${newRight}px`;\n }\n\n function onDragEnd(event) {\n if (!dragging) return;\n event.preventDefault();\n event.stopPropagation();\n\n dragging = false;\n document.removeEventListener('mousemove', onDragMove, { capture: true });\n document.removeEventListener('mouseup', onDragEnd, { capture: true });\n document.body.removeAttribute('data-em-dragging');\n }\n\n function destroy() {\n if (dragging) {\n onDragEnd(new MouseEvent('mouseup'));\n }\n }\n\n return { init, destroy };\n })();\n\n // [继续下一部分...]\n // ============================================================================\n // Selector Engine - Heuristic Selector Generation\n // ============================================================================\n\n function generateSelector(el) {\n if (!(el instanceof Element)) return '';\n\n const prefs = StateStore.get('prefs');\n\n if (prefs.preferId && el.id) {\n const idSel = `#${CSS.escape(el.id)}`;\n if (isDeepSelectorUnique(idSel, el)) return idSel;\n }\n\n if (prefs.preferStableAttr) {\n const attrNames = [\n 'data-testid',\n 'data-testId',\n 'data-test',\n 'data-qa',\n 'data-cy',\n 'name',\n 'title',\n 'alt',\n 'aria-label',\n ];\n const tag = el.tagName.toLowerCase();\n\n for (const attr of attrNames) {\n const v = el.getAttribute(attr);\n if (!v) continue;\n const attrSel = `[${attr}=\"${CSS.escape(v)}\"]`;\n const testSel = /^(input|textarea|select)$/i.test(tag) ? `${tag}${attrSel}` : attrSel;\n if (isDeepSelectorUnique(testSel, el)) return testSel;\n }\n }\n\n if (prefs.preferClass) {\n try {\n const classes = Array.from(el.classList || []).filter(\n (c) => c && /^[a-zA-Z0-9_-]+$/.test(c),\n );\n const tag = el.tagName.toLowerCase();\n\n for (const cls of classes) {\n const sel = `.${CSS.escape(cls)}`;\n if (isDeepSelectorUnique(sel, el)) return sel;\n }\n\n for (const cls of classes) {\n const sel = `${tag}.${CSS.escape(cls)}`;\n if (isDeepSelectorUnique(sel, el)) return sel;\n }\n\n for (let i = 0; i < Math.min(classes.length, 3); i++) {\n for (let j = i + 1; j < Math.min(classes.length, 3); j++) {\n const sel = `.${CSS.escape(classes[i])}.${CSS.escape(classes[j])}`;\n if (isDeepSelectorUnique(sel, el)) return sel;\n }\n }\n } catch {}\n }\n\n if (prefs.preferStableAttr) {\n try {\n let cur = el;\n const anchorAttrs = [\n 'id',\n 'data-testid',\n 'data-testId',\n 'data-test',\n 'data-qa',\n 'data-cy',\n 'name',\n ];\n\n // Detect shadow DOM boundary\n const root = el.getRootNode();\n const isShadowElement = root instanceof ShadowRoot;\n const boundary = isShadowElement ? root.host : document.body;\n\n while (cur && cur !== boundary) {\n if (cur.id) {\n const anchor = `#${CSS.escape(cur.id)}`;\n if (isDeepSelectorUnique(anchor, cur)) {\n const rel = buildPathFromAncestor(cur, el);\n const composed = rel ? `${anchor} ${rel}` : anchor;\n if (isDeepSelectorUnique(composed, el)) return composed;\n }\n }\n\n for (const attr of anchorAttrs) {\n const val = cur.getAttribute(attr);\n if (!val) continue;\n const aSel = `[${attr}=\"${CSS.escape(val)}\"]`;\n if (isDeepSelectorUnique(aSel, cur)) {\n const rel = buildPathFromAncestor(cur, el);\n const composed = rel ? `${aSel} ${rel}` : aSel;\n if (isDeepSelectorUnique(composed, el)) return composed;\n }\n }\n cur = cur.parentElement;\n }\n } catch {}\n }\n\n return buildFullPath(el);\n }\n\n function buildPathFromAncestor(ancestor, target) {\n const segs = [];\n let cur = target;\n\n // Detect if we're inside shadow DOM\n const root = target.getRootNode();\n const isShadowElement = root instanceof ShadowRoot;\n const boundary = isShadowElement ? root.host : document.body;\n\n while (cur && cur !== ancestor && cur !== boundary) {\n let seg = cur.tagName.toLowerCase();\n const parent = cur.parentElement;\n\n if (parent) {\n const siblings = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);\n if (siblings.length > 1) {\n seg += `:nth-of-type(${siblings.indexOf(cur) + 1})`;\n }\n }\n\n segs.unshift(seg);\n cur = parent;\n\n // Stop if we've reached the shadow root host\n if (isShadowElement && cur === boundary) {\n break;\n }\n }\n\n return segs.join(' > ');\n }\n\n function buildFullPath(el) {\n let path = '';\n let current = el;\n\n // Detect if the element is inside a shadow DOM\n const root = el.getRootNode();\n const isShadowElement = root instanceof ShadowRoot;\n\n // Determine the boundary where we should stop traversing\n const boundary = isShadowElement ? root.host : document.body;\n\n while (current && current.nodeType === Node.ELEMENT_NODE && current !== boundary) {\n let sel = current.tagName.toLowerCase();\n const parent = current.parentElement;\n\n if (parent) {\n const siblings = Array.from(parent.children).filter((c) => c.tagName === current.tagName);\n if (siblings.length > 1) {\n sel += `:nth-of-type(${siblings.indexOf(current) + 1})`;\n }\n }\n\n path = path ? `${sel} > ${path}` : sel;\n current = parent;\n\n // Stop if we've reached the shadow root host\n if (isShadowElement && current === boundary) {\n break;\n }\n }\n\n // For shadow DOM elements, don't prepend \"body >\"\n // The selector should be relative within the shadow tree\n if (isShadowElement) {\n return path || el.tagName.toLowerCase();\n }\n\n // For light DOM elements, keep the original behavior\n return path ? `body > ${path}` : 'body';\n }\n\n function generateXPath(el) {\n if (!(el instanceof Element)) return '';\n if (el.id) return `//*[@id=\"${el.id}\"]`;\n\n const segs = [];\n let cur = el;\n\n while (cur && cur.nodeType === 1 && cur !== document.documentElement) {\n const tag = cur.tagName.toLowerCase();\n\n if (cur.id) {\n segs.unshift(`//*[@id=\"${cur.id}\"]`);\n break;\n }\n\n let i = 1;\n let sib = cur;\n while ((sib = sib.previousElementSibling)) {\n if (sib.tagName.toLowerCase() === tag) i++;\n }\n\n segs.unshift(`${tag}[${i}]`);\n cur = cur.parentElement;\n }\n\n return segs[0]?.startsWith('//*') ? segs.join('/') : '//' + segs.join('/');\n }\n\n function generateListSelector(target) {\n const list = computeElementList(target);\n const selected = list?.[0] || target;\n const parent = selected.parentElement;\n\n if (!parent) return generateSelector(target);\n\n const parentSel = generateSelector(parent);\n const childRel = generateSelectorWithinRoot(selected, parent);\n\n return parentSel && childRel ? `${parentSel} ${childRel}` : generateSelector(target);\n }\n\n function generateSelectorWithinRoot(el, root) {\n if (!(el instanceof Element)) return '';\n\n const tag = el.tagName.toLowerCase();\n\n // Use isDeepSelectorUnique for ID to support shadow DOM elements\n if (el.id) {\n const idSel = `#${CSS.escape(el.id)}`;\n if (isDeepSelectorUnique(idSel, el)) return idSel;\n }\n\n const attrNames = [\n 'data-testid',\n 'data-testId',\n 'data-test',\n 'data-qa',\n 'data-cy',\n 'name',\n 'title',\n 'alt',\n 'aria-label',\n ];\n\n // Use isDeepSelectorUnique for attributes to support shadow DOM elements\n for (const attr of attrNames) {\n const v = el.getAttribute(attr);\n if (!v) continue;\n const aSel = `[${attr}=\"${CSS.escape(v)}\"]`;\n const testSel = /^(input|textarea|select)$/i.test(tag) ? `${tag}${aSel}` : aSel;\n if (isDeepSelectorUnique(testSel, el)) return testSel;\n }\n\n try {\n const classes = Array.from(el.classList || []).filter((c) => c && /^[a-zA-Z0-9_-]+$/.test(c));\n\n // Use isDeepSelectorUnique for classes to support shadow DOM elements\n for (const cls of classes) {\n const sel = `.${CSS.escape(cls)}`;\n if (isDeepSelectorUnique(sel, el)) return sel;\n }\n\n for (const cls of classes) {\n const sel = `${tag}.${CSS.escape(cls)}`;\n if (isDeepSelectorUnique(sel, el)) return sel;\n }\n } catch {}\n\n return buildPathFromAncestor(root, el);\n }\n\n function getAccessibleName(el) {\n try {\n const labelledby = el.getAttribute('aria-labelledby');\n if (labelledby) {\n const labelEl = document.getElementById(labelledby);\n if (labelEl) return (labelEl.textContent || '').trim();\n }\n\n const ariaLabel = el.getAttribute('aria-label');\n if (ariaLabel) return ariaLabel.trim();\n\n if (el.id) {\n const label = document.querySelector(`label[for=\"${el.id}\"]`);\n if (label) return (label.textContent || '').trim();\n }\n\n const parentLabel = el.closest('label');\n if (parentLabel) return (parentLabel.textContent || '').trim();\n\n return (\n el.getAttribute('placeholder') ||\n el.getAttribute('value') ||\n el.textContent ||\n ''\n ).trim();\n } catch {\n return '';\n }\n }\n\n // ============================================================================\n // List Mode Utilities\n // ============================================================================\n\n function getAllSiblings(el, selector) {\n const siblings = [el];\n const validate = (element) => {\n const isSameTag = el.tagName === element.tagName;\n let ok = isSameTag;\n if (selector) {\n try {\n ok = ok && !!element.querySelector(selector);\n } catch {}\n }\n return ok;\n };\n\n let next = el;\n let prev = el;\n let elementIndex = 1;\n\n while ((prev = prev?.previousElementSibling)) {\n if (validate(prev)) {\n elementIndex += 1;\n siblings.unshift(prev);\n }\n }\n\n while ((next = next?.nextElementSibling)) {\n if (validate(next)) siblings.push(next);\n }\n\n return { elements: siblings, index: elementIndex };\n }\n\n function getElementList(el, maxDepth = 50, paths = []) {\n if (maxDepth === 0 || !el || el.tagName === 'BODY') return null;\n\n let selector = el.tagName.toLowerCase();\n const { elements, index } = getAllSiblings(el, paths.join(' > '));\n let siblings = elements;\n\n if (index !== 1) selector += `:nth-of-type(${index})`;\n paths.unshift(selector);\n\n if (siblings.length === 1) {\n siblings = getElementList(el.parentElement, maxDepth - 1, paths);\n }\n\n return siblings;\n }\n\n function computeElementList(target) {\n try {\n return getElementList(target) || [target];\n } catch {\n return [target];\n }\n }\n\n // ============================================================================\n // Deep Query (Shadow DOM Support)\n // ============================================================================\n\n function* walkAllNodesDeep(root) {\n const stack = [root];\n let count = 0;\n const MAX = 10000;\n\n while (stack.length) {\n const node = stack.pop();\n if (!node || ++count > MAX) continue;\n\n // Skip overlay elements to prevent panel self-highlighting\n if (isOverlayElement(node)) {\n continue;\n }\n\n yield node;\n\n try {\n if (node.children) {\n const children = Array.from(node.children);\n for (let i = children.length - 1; i >= 0; i--) {\n stack.push(children[i]);\n }\n }\n\n if (node.shadowRoot?.children) {\n const srChildren = Array.from(node.shadowRoot.children);\n for (let i = srChildren.length - 1; i >= 0; i--) {\n stack.push(srChildren[i]);\n }\n }\n } catch {}\n }\n }\n\n function queryAllDeep(selector) {\n const results = [];\n for (const node of walkAllNodesDeep(document)) {\n if (!(node instanceof Element)) continue;\n try {\n if (node.matches(selector)) results.push(node);\n } catch {}\n }\n return results;\n }\n\n /**\n * Check if a selector uniquely identifies the target element across the entire DOM tree,\n * including shadow DOM boundaries.\n *\n * This function uses queryAllDeep to traverse both light DOM and shadow DOM,\n * ensuring that selectors work correctly for elements inside shadow roots.\n *\n * @param {string} selector - The CSS selector to test\n * @param {Element} target - The target element that should be uniquely identified\n * @returns {boolean} True if the selector matches exactly one element and it's the target\n */\n function isDeepSelectorUnique(selector, target) {\n if (!selector || !(target instanceof Element)) return false;\n try {\n const matches = queryAllDeep(selector);\n return matches.length === 1 && matches[0] === target;\n } catch (error) {\n return false;\n }\n }\n\n function evaluateXPathAll(xpath) {\n try {\n const arr = [];\n const res = document.evaluate(\n xpath,\n document,\n null,\n XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n null,\n );\n\n for (let i = 0; i < res.snapshotLength; i++) {\n const n = res.snapshotItem(i);\n // Filter out overlay elements to prevent panel self-highlighting\n if (n?.nodeType === 1 && !isOverlayElement(n)) {\n arr.push(n);\n }\n }\n return arr;\n } catch {\n return [];\n }\n }\n\n // ============================================================================\n // Highlighter & Rects Management\n // ============================================================================\n\n const STATE = {\n active: false,\n hoverEl: null,\n selectedEl: null,\n box: null,\n highlighter: null,\n listenersAttached: false,\n rectsHost: null,\n hoveredList: [],\n verifyRectsActive: false, // Track if verify rects are showing\n // Performance optimization: rAF throttling for hover\n hoverRafId: null,\n lastHoverTarget: null,\n // DOM pooling for rect elements\n rectPool: [],\n rectPoolUsed: 0,\n };\n\n function ensureHighlighter() {\n if (STATE.highlighter) return STATE.highlighter;\n\n const hl = document.createElement('div');\n hl.id = '__element_marker_highlight';\n Object.assign(hl.style, {\n position: 'fixed',\n zIndex: String(CONFIG.Z_INDEX.HIGHLIGHTER),\n pointerEvents: 'none',\n border: `2px solid ${CONFIG.COLORS.HOVER}`,\n borderRadius: '4px',\n boxShadow: `0 0 0 2px ${CONFIG.COLORS.HOVER}33`,\n transition: 'all 100ms ease-out',\n });\n\n document.documentElement.appendChild(hl);\n STATE.highlighter = hl;\n return hl;\n }\n\n function ensureRectsHost() {\n if (STATE.rectsHost) return STATE.rectsHost;\n\n const host = document.createElement('div');\n host.id = '__element_marker_rects';\n Object.assign(host.style, {\n position: 'fixed',\n zIndex: String(CONFIG.Z_INDEX.RECTS),\n pointerEvents: 'none',\n inset: '0',\n });\n\n document.documentElement.appendChild(host);\n STATE.rectsHost = host;\n return host;\n }\n\n function moveHighlighterTo(el) {\n const hl = ensureHighlighter();\n const r = el.getBoundingClientRect();\n hl.style.left = `${r.left}px`;\n hl.style.top = `${r.top}px`;\n hl.style.width = `${r.width}px`;\n hl.style.height = `${r.height}px`;\n hl.style.display = 'block';\n }\n\n function clearHighlighter() {\n if (STATE.highlighter) STATE.highlighter.style.display = 'none';\n // Only clear hover rects, not verify rects\n if (!STATE.verifyRectsActive) {\n clearRects();\n }\n }\n\n function clearRects() {\n // Hide all pooled rect boxes instead of destroying them\n const used = STATE.rectPoolUsed || 0;\n for (let i = 0; i < used; i++) {\n const box = STATE.rectPool[i];\n if (box) box.style.display = 'none';\n }\n STATE.rectPoolUsed = 0;\n STATE.verifyRectsActive = false;\n // Invalidate lastHoverTarget so next hover will redraw even on same element\n STATE.lastHoverTarget = null;\n }\n\n /**\n * Get or create a rect box from the pool\n * @param {HTMLElement} host - The container element\n * @param {number} index - The pool index\n * @returns {HTMLDivElement} The rect box element\n */\n function getOrCreateRectBox(host, index) {\n let box = STATE.rectPool[index];\n if (!box) {\n box = document.createElement('div');\n Object.assign(box.style, {\n position: 'fixed',\n pointerEvents: 'none',\n borderRadius: '4px',\n transition: 'all 100ms ease-out',\n display: 'none',\n });\n STATE.rectPool[index] = box;\n }\n // Ensure the box is attached to the host\n if (!box.isConnected) {\n host.appendChild(box);\n }\n return box;\n }\n\n // Maximum rect pool size to prevent memory bloat\n const MAX_RECT_POOL_SIZE = 100;\n\n /**\n * Draw rect boxes with pooling optimization\n * @param {Array<{x: number, y: number, width: number, height: number}>} rects - Rect data\n * @param {Object} options - Drawing options\n * @param {boolean} options.isVerify - Whether this is a verify highlight (affects verifyRectsActive)\n */\n function drawRectBoxes(\n rects,\n { color = CONFIG.COLORS.HOVER, dashed = true, offsetX = 0, offsetY = 0, isVerify = false } = {},\n ) {\n const host = ensureRectsHost();\n const prevUsed = STATE.rectPoolUsed || 0;\n // Limit rect count to prevent memory bloat\n const count = Math.min(Array.isArray(rects) ? rects.length : 0, MAX_RECT_POOL_SIZE);\n\n // Update or show rect boxes\n for (let i = 0; i < count; i++) {\n const r = rects[i];\n if (!r) continue;\n\n const x = Number.isFinite(r.left) ? r.left : Number.isFinite(r.x) ? r.x : 0;\n const y = Number.isFinite(r.top) ? r.top : Number.isFinite(r.y) ? r.y : 0;\n const w = Number.isFinite(r.width) ? r.width : 0;\n const h = Number.isFinite(r.height) ? r.height : 0;\n\n const box = getOrCreateRectBox(host, i);\n Object.assign(box.style, {\n left: `${offsetX + x}px`,\n top: `${offsetY + y}px`,\n width: `${w}px`,\n height: `${h}px`,\n border: `2px ${dashed ? 'dashed' : 'solid'} ${color}`,\n boxShadow: `0 0 0 2px ${color}22`,\n display: 'block',\n });\n }\n\n // Hide excess boxes from previous render\n for (let i = count; i < prevUsed; i++) {\n const box = STATE.rectPool[i];\n if (box) box.style.display = 'none';\n }\n\n STATE.rectPoolUsed = count;\n // Reset verifyRectsActive for hover operations (so clearHighlighter works correctly)\n // Only set to true when isVerify is explicitly true\n STATE.verifyRectsActive = isVerify;\n }\n\n function drawRects(elements, color = CONFIG.COLORS.HOVER, dashed = true, isVerify = false) {\n const rects = elements.map((el) => {\n const r = el.getBoundingClientRect();\n return { x: r.left, y: r.top, width: r.width, height: r.height };\n });\n drawRectBoxes(rects, { color, dashed, isVerify });\n }\n\n // ============================================================================\n // Interaction Logic\n // ============================================================================\n\n function isInsidePanel(target) {\n const shadow = PanelHost.getShadow();\n return !!shadow && target instanceof Node && shadow.contains(target);\n }\n\n /**\n * Check if a node belongs to the element marker overlay (panel host or its shadow DOM)\n * This is used to filter out overlay elements from query results to prevent self-highlighting\n *\n * @param {Node} node - The node to check\n * @returns {boolean} True if the node is part of the overlay\n */\n function isOverlayElement(node) {\n if (!(node instanceof Node)) return false;\n\n const host = PanelHost.getHost();\n if (!host) return false;\n\n // Check if node is the panel host itself\n if (node === host) return true;\n\n // Check if node is within the shadow DOM of the panel host\n const root = typeof node.getRootNode === 'function' ? node.getRootNode() : null;\n return root instanceof ShadowRoot && root.host === host;\n }\n\n /**\n * Filter out overlay elements from an array of elements\n * This ensures that panel components are never included in highlight/verification results\n *\n * @param {Array} elements - Array of elements to filter\n * @returns {Array} Filtered array without overlay elements\n */\n function filterOverlayElements(elements) {\n if (!Array.isArray(elements)) return [];\n return elements.filter((node) => !isOverlayElement(node));\n }\n\n /**\n * Get the effective event target for page element selection, considering shadow DOM boundaries.\n *\n * This function resolves the real target element from a pointer event by walking the\n * composed path (if available) to find the innermost page element, skipping overlay elements.\n *\n * Background:\n * - When events bubble up from inside shadow DOM, they get \"retargeted\" at shadow boundaries\n * - By the time a window-level listener receives the event, ev.target points to the shadow host\n * - composedPath() exposes the original event path before retargeting\n * - This allows us to select elements inside shadow DOM (e.g., internals)\n *\n * IMPORTANT: This function should only be called AFTER verifying the event is not from\n * overlay UI (panel buttons, etc). Otherwise it will filter out overlay elements and break\n * panel interactions.\n *\n * @param {Event} ev - The pointer event (mousemove, click, etc.)\n * @returns {Element|null} The innermost non-overlay page element, or null if none found\n */\n function getDeepPageTarget(ev) {\n if (!ev) return null;\n\n // Try to walk the composed path to find the innermost non-overlay element\n try {\n const path = typeof ev.composedPath === 'function' ? ev.composedPath() : null;\n if (Array.isArray(path) && path.length > 0) {\n // Walk from innermost to outermost, find the first real page element\n for (const node of path) {\n if (node instanceof Element && !isOverlayElement(node)) {\n return node;\n }\n }\n }\n } catch (error) {\n // composedPath() may throw in some edge cases (e.g., detached nodes)\n // Fall through to use ev.target\n }\n\n // Fallback: use ev.target if composedPath is unavailable or all nodes were filtered\n const fallback = ev.target instanceof Element ? ev.target : null;\n // If fallback is overlay, return null (caller should handle this case)\n if (fallback && !isOverlayElement(fallback)) {\n return fallback;\n }\n return null;\n }\n\n // Store pending hover event for rAF processing\n let pendingHoverEvent = null;\n\n /**\n * Process mouse move event - the actual hover update logic\n * Separated from onMouseMove for rAF throttling\n */\n function processMouseMove(ev) {\n if (!STATE.active) return;\n\n const rawTarget = ev?.target;\n if (!(rawTarget instanceof Element)) {\n STATE.hoverEl = null;\n STATE.lastHoverTarget = null;\n clearHighlighter();\n return;\n }\n\n const host = PanelHost.getHost();\n if ((host && rawTarget === host) || isInsidePanel(rawTarget)) {\n STATE.hoverEl = null;\n STATE.lastHoverTarget = null;\n clearHighlighter();\n return;\n }\n\n const target = getDeepPageTarget(ev) || rawTarget;\n STATE.hoverEl = target;\n\n // Get current listMode\n let listMode = false;\n try {\n listMode = !!StateStore.get('listMode');\n } catch {}\n\n // Skip update if target and mode haven't changed\n const last = STATE.lastHoverTarget;\n if (last && last.element === target && last.listMode === listMode) {\n return;\n }\n STATE.lastHoverTarget = { element: target, listMode };\n\n if (!IS_MAIN) {\n try {\n const list = listMode ? computeElementList(target) || [target] : [target];\n const rects = list.map((el) => {\n const r = el.getBoundingClientRect();\n return { x: r.left, y: r.top, width: r.width, height: r.height };\n });\n\n // Performance: Don't generate selector on hover (defer to click)\n window.top.postMessage({ type: 'em_hover', rects }, '*');\n } catch {}\n return;\n }\n\n if (listMode) {\n STATE.hoveredList = computeElementList(target) || [target];\n drawRects(STATE.hoveredList);\n } else {\n moveHighlighterTo(target);\n }\n }\n\n /**\n * Mouse move handler with rAF throttling\n * Ensures hover updates are batched to animation frame rate\n */\n function onMouseMove(ev) {\n if (!STATE.active) return;\n\n // Store the latest event\n pendingHoverEvent = ev;\n\n // Skip if already scheduled\n if (STATE.hoverRafId != null) return;\n\n // Schedule processing on next animation frame\n STATE.hoverRafId = requestAnimationFrame(() => {\n STATE.hoverRafId = null;\n const latest = pendingHoverEvent;\n pendingHoverEvent = null;\n if (!latest) return;\n processMouseMove(latest);\n });\n }\n\n // ============================================================================\n // Event Listeners Management\n // ============================================================================\n\n function attachPointerListeners() {\n if (STATE.listenersAttached) return;\n window.addEventListener('mousemove', onMouseMove, true);\n window.addEventListener('click', onClick, true);\n STATE.listenersAttached = true;\n }\n\n function detachPointerListeners() {\n if (!STATE.listenersAttached) return;\n window.removeEventListener('mousemove', onMouseMove, true);\n window.removeEventListener('click', onClick, true);\n STATE.listenersAttached = false;\n }\n\n function attachKeyboardListener() {\n window.addEventListener('keydown', onKeyDown, true);\n }\n\n function detachKeyboardListener() {\n window.removeEventListener('keydown', onKeyDown, true);\n }\n\n function syncInteractionMode() {\n if (!STATE.active) return;\n const activeTab = StateStore.get('activeTab');\n if (activeTab === 'execute') {\n // In execute mode, detach pointer listeners to allow real interactions\n // but keep keyboard listener for Esc key\n detachPointerListeners();\n // Only clear the hover highlighter, not the verification rects\n if (STATE.highlighter) STATE.highlighter.style.display = 'none';\n } else {\n // In attributes mode, attach all listeners for element selection\n attachPointerListeners();\n }\n }\n\n // ============================================================================\n // Event Handlers\n // ============================================================================\n\n function onClick(ev) {\n if (!STATE.active) return;\n\n // First, use the raw ev.target to check for overlay UI\n // This ensures panel buttons and other UI elements remain interactive\n const rawTarget = ev.target;\n const host = PanelHost.getHost();\n\n // Check if raw target is the panel host itself or inside the shadow DOM\n // IMPORTANT: Return early WITHOUT preventDefault to allow overlay button clicks\n if ((host && rawTarget === host) || isInsidePanel(rawTarget)) {\n return;\n }\n\n // Now we know it's a page element, prevent default and get deep target\n ev.preventDefault();\n ev.stopPropagation();\n\n if (!(rawTarget instanceof Element)) return;\n\n // Get the deep target (considering shadow DOM) after confirming it's not overlay\n const target = getDeepPageTarget(ev) || rawTarget;\n\n if (!IS_MAIN) {\n try {\n const selectorType = StateStore.get('selectorType');\n const listMode = StateStore.get('listMode');\n\n const sel =\n selectorType === 'xpath'\n ? generateXPath(target)\n : listMode\n ? generateListSelector(target)\n : generateSelector(target);\n\n window.top.postMessage({ type: 'em_click', innerSel: sel }, '*');\n } catch {}\n return;\n }\n\n setSelection(target);\n }\n\n function onKeyDown(e) {\n if (!STATE.active) return;\n\n // Check if the focused element is inside the panel - if so, don't handle selection keys\n if (isInsidePanel(e.target)) {\n // Key event is from panel, don't interfere\n if (e.key !== 'Escape') return; // Still allow Escape to close\n }\n\n // In execute mode, only handle Escape to close - don't intercept other keys\n // This allows real page interactions (typing, scrolling, etc.)\n const activeTab = StateStore.get('activeTab');\n if (activeTab === 'execute') {\n if (e.key === 'Escape') {\n e.preventDefault();\n stop();\n }\n return; // Don't intercept Space/Arrow keys in execute mode\n }\n\n if (e.key === 'Escape') {\n e.preventDefault();\n stop();\n } else if (e.key === ' ' || e.code === 'Space') {\n e.preventDefault();\n const t = STATE.hoverEl || STATE.selectedEl;\n if (t) setSelection(t);\n } else if (e.key === 'ArrowUp') {\n e.preventDefault();\n const base = STATE.selectedEl || STATE.hoverEl;\n if (base?.parentElement) setSelection(base.parentElement);\n } else if (e.key === 'ArrowDown') {\n e.preventDefault();\n const base = STATE.selectedEl || STATE.hoverEl;\n if (base?.firstElementChild) setSelection(base.firstElementChild);\n }\n }\n\n function setSelection(el) {\n if (!(el instanceof Element)) return;\n\n STATE.selectedEl = el;\n\n const selectorType = StateStore.get('selectorType');\n const listMode = StateStore.get('listMode');\n\n const sel =\n selectorType === 'xpath'\n ? generateXPath(el)\n : listMode\n ? generateListSelector(el)\n : generateSelector(el);\n\n const name = getAccessibleName(el) || el.tagName.toLowerCase();\n\n const selectorText = STATE.box?.querySelector('#__em_selector');\n const inputName = STATE.box?.querySelector('#__em_name');\n const selectorDisplay = STATE.box?.querySelector('#__em_selector_text');\n\n if (selectorText) selectorText.textContent = sel;\n if (selectorDisplay) selectorDisplay.textContent = sel;\n if (inputName && !inputName.value) inputName.value = name;\n\n moveHighlighterTo(el);\n }\n\n // ============================================================================\n // Validation Logic\n // ============================================================================\n\n /**\n * Verify selector by highlighting only (non-destructive)\n */\n async function verifyHighlightOnly() {\n try {\n const selector = STATE.box?.querySelector('#__em_selector')?.textContent?.trim();\n if (!selector) return;\n\n StateStore.set({\n validation: { status: 'running', message: 'Verifying selector...' },\n });\n\n const selectorType = StateStore.get('selectorType');\n const listMode = StateStore.get('listMode');\n const effectiveType = listMode ? 'css' : selectorType;\n\n // Query for matches\n const matches =\n effectiveType === 'xpath' ? evaluateXPathAll(selector) : queryAllDeep(selector);\n\n // Additional defense: filter out any overlay elements that might have slipped through\n const filteredMatches = filterOverlayElements(matches);\n\n if (!filteredMatches || filteredMatches.length === 0) {\n StateStore.set({\n validation: { status: 'failure', message: 'No elements found' },\n });\n return;\n }\n\n // Scroll first match into view\n const primaryMatch = filteredMatches[0];\n if (primaryMatch) {\n primaryMatch.scrollIntoView({\n block: 'center',\n inline: 'center',\n behavior: 'smooth',\n });\n }\n\n await sleep(200);\n\n // Highlight matches with isVerify=true to prevent clearing on hover\n drawRects(filteredMatches, CONFIG.COLORS.VERIFY, false, true);\n\n StateStore.set({\n validation: {\n status: 'success',\n message: `Found ${filteredMatches.length} element${filteredMatches.length > 1 ? 's' : ''}`,\n },\n });\n\n // Auto-clear highlight after 2 seconds\n setTimeout(() => {\n clearRects();\n StateStore.set({\n validation: { status: 'idle', message: '' },\n });\n }, 2000);\n } catch (error) {\n console.error('[verifyHighlightOnly] error:', error);\n StateStore.set({\n validation: { status: 'failure', message: error.message || 'Verification failed' },\n });\n }\n }\n\n /**\n * Execute action on selector (destructive)\n */\n async function verifySelectorNow() {\n try {\n const selector = STATE.box?.querySelector('#__em_selector')?.textContent?.trim();\n if (!selector) return;\n\n StateStore.set({\n validation: { status: 'running', message: 'Executing action...' },\n });\n\n const selectorType = StateStore.get('selectorType');\n const listMode = StateStore.get('listMode');\n\n const effectiveType = listMode ? 'css' : selectorType;\n\n const matches =\n effectiveType === 'xpath' ? evaluateXPathAll(selector) : queryAllDeep(selector);\n\n // Additional defense: filter out any overlay elements that might have slipped through\n const filteredMatches = filterOverlayElements(matches);\n\n if (!filteredMatches || filteredMatches.length === 0) {\n StateStore.set({\n validation: { status: 'failure', message: 'No elements found' },\n });\n return;\n }\n\n drawRects(filteredMatches, CONFIG.COLORS.VERIFY, false);\n\n const action = STATE.box?.querySelector('#__em_action')?.value || 'hover';\n\n const payload = {\n type: 'element_marker_validate',\n selector,\n selectorType: effectiveType,\n action,\n listMode,\n };\n\n // Action-specific parameters with validation\n if (action === 'type_text') {\n const actionText = String(\n STATE.box?.querySelector('#__em_action_text')?.value || '',\n ).trim();\n if (!actionText) {\n StateStore.set({\n validation: { status: 'failure', message: 'Text is required for type_text' },\n });\n return;\n }\n payload.text = actionText;\n }\n\n if (action === 'press_keys') {\n const actionKeys = String(\n STATE.box?.querySelector('#__em_action_keys')?.value || '',\n ).trim();\n if (!actionKeys) {\n StateStore.set({\n validation: { status: 'failure', message: 'Keys are required for press_keys' },\n });\n return;\n }\n payload.keys = actionKeys;\n }\n\n if (action === 'scroll') {\n const direction = STATE.box?.querySelector('#__em_scroll_direction')?.value || 'down';\n const rawAmount = Number(STATE.box?.querySelector('#__em_scroll_distance')?.value);\n // Clamp to 1-10 range (backend expects ticks, not pixels)\n const amount = Math.max(\n 1,\n Math.min(Math.round(Number.isFinite(rawAmount) ? rawAmount : 3), 10),\n );\n payload.scrollDirection = direction;\n payload.scrollAmount = amount;\n }\n\n if (['left_click', 'double_click', 'right_click'].includes(action)) {\n payload.modifiers = {\n altKey: !!STATE.box?.querySelector('#__em_mod_alt')?.checked,\n ctrlKey: !!STATE.box?.querySelector('#__em_mod_ctrl')?.checked,\n metaKey: !!STATE.box?.querySelector('#__em_mod_meta')?.checked,\n shiftKey: !!STATE.box?.querySelector('#__em_mod_shift')?.checked,\n };\n payload.button = STATE.box?.querySelector('#__em_btn')?.value || 'left';\n payload.waitForNavigation = !!STATE.box?.querySelector('#__em_wait_nav')?.checked;\n payload.timeoutMs = Number(STATE.box?.querySelector('#__em_nav_timeout')?.value) || 3000;\n }\n\n const res = await chrome.runtime.sendMessage(payload);\n\n const success = !!res?.tool?.ok;\n const newEntry = {\n action,\n success,\n timestamp: Date.now(),\n matchCount: filteredMatches.length,\n };\n const history = [...(StateStore.get('validationHistory') || []), newEntry].slice(-5);\n\n if (res?.tool?.ok) {\n StateStore.set({\n validation: {\n status: 'success',\n message: `✓ 验证成功 (匹配 ${filteredMatches.length} 个元素)`,\n },\n validationHistory: history,\n });\n } else {\n StateStore.set({\n validation: {\n status: 'failure',\n message: res?.tool?.error || '验证失败',\n },\n validationHistory: history,\n });\n }\n } catch (err) {\n const newEntry = {\n action: STATE.box?.querySelector('#__em_action')?.value || 'hover',\n success: false,\n timestamp: Date.now(),\n matchCount: 0,\n };\n const history = [...(StateStore.get('validationHistory') || []), newEntry].slice(-5);\n\n StateStore.set({\n validation: {\n status: 'failure',\n message: `错误: ${err.message}`,\n },\n validationHistory: history,\n });\n }\n }\n\n /**\n * Highlight selector from external request (popup/background)\n * Supports composite iframe selectors: \"frameSelector |> innerSelector\"\n */\n async function highlightSelectorExternal({ selector, selectorType = 'css', listMode = false }) {\n const normalized = String(selector || '').trim();\n if (!normalized) {\n return { success: false, error: 'selector is required' };\n }\n\n try {\n // Handle composite iframe selector\n if (normalized.includes('|>')) {\n const parts = normalized\n .split('|>')\n .map((s) => s.trim())\n .filter(Boolean);\n\n if (parts.length >= 2) {\n const frameSel = parts[0];\n const innerSel = parts.slice(1).join(' |> ');\n\n // Find frame element\n let frameEl = null;\n try {\n frameEl = querySelectorDeepFirst(frameSel) || document.querySelector(frameSel);\n } catch {}\n\n if (\n !frameEl ||\n !(frameEl instanceof HTMLIFrameElement || frameEl instanceof HTMLFrameElement)\n ) {\n return { success: false, error: `Frame element not found: ${frameSel}` };\n }\n\n const cw = frameEl.contentWindow;\n if (!cw) {\n return { success: false, error: 'Unable to access frame contentWindow' };\n }\n\n // Forward highlight request to iframe\n return new Promise((resolve) => {\n const reqId = `em_highlight_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;\n const listener = (ev) => {\n try {\n const data = ev?.data;\n if (!data || data.type !== 'em-highlight-result' || data.reqId !== reqId) return;\n window.removeEventListener('message', listener, true);\n resolve(data.result);\n } catch {}\n };\n\n window.addEventListener('message', listener, true);\n setTimeout(() => {\n window.removeEventListener('message', listener, true);\n resolve({ success: false, error: 'Frame highlight timeout' });\n }, 3000);\n\n cw.postMessage(\n {\n type: 'em-highlight-request',\n reqId,\n selector: innerSel,\n selectorType,\n listMode,\n },\n '*',\n );\n });\n }\n }\n\n // Handle normal selector (non-iframe)\n const effectiveType = listMode ? 'css' : selectorType;\n const matches =\n effectiveType === 'xpath' ? evaluateXPathAll(normalized) : queryAllDeep(normalized);\n\n // Additional defense: filter out any overlay elements that might have slipped through\n const filteredMatches = filterOverlayElements(matches);\n\n if (!filteredMatches || filteredMatches.length === 0) {\n return { success: false, error: 'No elements found for selector' };\n }\n\n // Scroll first match into view\n const primaryMatch = filteredMatches[0];\n if (primaryMatch) {\n primaryMatch.scrollIntoView({\n block: 'center',\n inline: 'center',\n behavior: 'smooth',\n });\n }\n\n await sleep(150);\n\n // Draw highlight rectangles\n drawRects(filteredMatches, CONFIG.COLORS.VERIFY, false);\n\n // Auto-clear after 2 seconds\n setTimeout(() => {\n clearRects();\n }, 2000);\n\n return { success: true, count: filteredMatches.length };\n } catch (error) {\n return { success: false, error: error.message || String(error) };\n }\n }\n\n function copySelectorNow() {\n try {\n const sel = STATE.box?.querySelector('#__em_selector')?.textContent?.trim();\n if (!sel) return;\n navigator.clipboard?.writeText(sel).catch(() => {});\n\n StateStore.set({\n validation: { status: 'success', message: '✓ 已复制到剪贴板' },\n });\n\n setTimeout(() => {\n StateStore.set({ validation: { status: 'idle', message: '' } });\n }, 2000);\n } catch {}\n }\n\n async function save() {\n try {\n const name = STATE.box?.querySelector('#__em_name')?.value?.trim();\n const selector = STATE.box?.querySelector('#__em_selector')?.textContent?.trim();\n\n if (!selector) return;\n\n const url = location.href;\n let selectorType = StateStore.get('selectorType');\n const listMode = StateStore.get('listMode');\n\n if (listMode && selectorType === 'xpath') {\n selectorType = 'css';\n }\n\n await chrome.runtime.sendMessage({\n type: 'element_marker_save',\n marker: {\n url,\n name: name || selector,\n selector,\n selectorType,\n listMode,\n },\n });\n } catch {}\n\n stop();\n }\n\n // ============================================================================\n // Lifecycle Management\n // ============================================================================\n\n function start() {\n if (STATE.active) return;\n STATE.active = true;\n\n if (IS_MAIN) {\n const { host } = PanelHost.mount();\n STATE.box = host;\n StateStore.init();\n bindControls();\n }\n\n ensureHighlighter();\n ensureRectsHost();\n\n attachPointerListeners();\n attachKeyboardListener();\n syncInteractionMode();\n }\n\n function stop() {\n STATE.active = false;\n\n detachPointerListeners();\n detachKeyboardListener();\n\n // Cancel pending rAF\n if (STATE.hoverRafId != null) {\n cancelAnimationFrame(STATE.hoverRafId);\n STATE.hoverRafId = null;\n }\n pendingHoverEvent = null;\n\n try {\n STATE.highlighter?.remove();\n STATE.rectsHost?.remove();\n PanelHost.unmount();\n DragController.destroy();\n } catch {}\n\n STATE.highlighter = null;\n STATE.rectsHost = null;\n STATE.box = null;\n STATE.hoveredList = [];\n STATE.hoverEl = null;\n STATE.selectedEl = null;\n STATE.lastHoverTarget = null;\n STATE.verifyRectsActive = false;\n\n // Clear rect pool to release DOM references\n STATE.rectPool.length = 0;\n STATE.rectPoolUsed = 0;\n }\n\n // ============================================================================\n // Controls Binding\n // ============================================================================\n\n function bindControls() {\n const host = STATE.box;\n if (!host) return;\n\n // Close/Cancel\n host.querySelector('#__em_close')?.addEventListener('click', stop);\n host.querySelector('#__em_cancel')?.addEventListener('click', stop);\n\n // Save\n host.querySelector('#__em_save')?.addEventListener('click', save);\n\n // Verify (highlight only) & Execute (real action)\n host.querySelector('#__em_verify')?.addEventListener('click', verifyHighlightOnly);\n host.querySelector('#__em_execute')?.addEventListener('click', verifySelectorNow);\n\n // Copy\n host.querySelector('#__em_copy')?.addEventListener('click', copySelectorNow);\n host.querySelector('#__em_copy_selector')?.addEventListener('click', copySelectorNow);\n\n // Action change handler - show/hide action-specific options\n host.querySelector('#__em_action')?.addEventListener('change', (e) => {\n updateActionSpecificUI(e.target.value);\n });\n\n // Selector type\n host.querySelector('#__em_selector_type')?.addEventListener('change', (e) => {\n const newType = e.target.value;\n const listMode = StateStore.get('listMode');\n\n // If switching to XPath while in list mode, disable list mode\n if (newType === 'xpath' && listMode) {\n StateStore.set({ selectorType: newType, listMode: false });\n } else {\n StateStore.set({ selectorType: newType });\n }\n\n // Regenerate selector for the currently selected element\n if (STATE.selectedEl) {\n setSelection(STATE.selectedEl);\n }\n // Note: If no selectedEl (e.g., iframe selections or manual input),\n // preserve existing selector text instead of clearing it\n });\n\n // List mode toggle\n host.querySelector('#__em_toggle_list')?.addEventListener('click', (e) => {\n const listMode = StateStore.get('listMode');\n const newListMode = !listMode;\n\n // If enabling list mode, force CSS selector type\n if (newListMode) {\n StateStore.set({ listMode: true, selectorType: 'css' });\n const selectorTypeSelect = host.querySelector('#__em_selector_type');\n if (selectorTypeSelect) selectorTypeSelect.value = 'css';\n } else {\n StateStore.set({ listMode: false });\n }\n\n // Update button active state\n const btn = e.currentTarget;\n if (btn) {\n if (newListMode) {\n btn.classList.add('active');\n } else {\n btn.classList.remove('active');\n }\n }\n\n // Regenerate selector for the currently selected element\n if (STATE.selectedEl) {\n setSelection(STATE.selectedEl);\n }\n\n clearHighlighter();\n });\n\n // Tab toggle (switch between Attributes and Execute)\n host.querySelector('#__em_toggle_tab')?.addEventListener('click', () => {\n const currentTab = StateStore.get('activeTab');\n StateStore.set({ activeTab: currentTab === 'attributes' ? 'execute' : 'attributes' });\n });\n\n // Tab switching\n const tabs = host.querySelectorAll('.em-tab');\n tabs.forEach((tab) => {\n tab.addEventListener('click', () => {\n StateStore.set({ activeTab: tab.dataset.tab });\n });\n });\n\n // Navigation buttons\n host.querySelector('#__em_nav_up')?.addEventListener('click', () => {\n const base = STATE.selectedEl || STATE.hoverEl;\n if (base?.parentElement) setSelection(base.parentElement);\n });\n\n host.querySelector('#__em_nav_down')?.addEventListener('click', () => {\n const base = STATE.selectedEl || STATE.hoverEl;\n if (base?.firstElementChild) setSelection(base.firstElementChild);\n });\n\n // Preferences\n host.querySelector('#__em_pref_id')?.addEventListener('change', (e) => {\n const prefs = { ...StateStore.get('prefs'), preferId: !!e.target.checked };\n StateStore.set({ prefs });\n });\n host.querySelector('#__em_pref_attr')?.addEventListener('change', (e) => {\n const prefs = { ...StateStore.get('prefs'), preferStableAttr: !!e.target.checked };\n StateStore.set({ prefs });\n });\n host.querySelector('#__em_pref_class')?.addEventListener('change', (e) => {\n const prefs = { ...StateStore.get('prefs'), preferClass: !!e.target.checked };\n StateStore.set({ prefs });\n });\n\n // Drag - use entire header as drag handle\n const dragHandle = host.querySelector('#__em_drag_handle');\n if (dragHandle) {\n DragController.init(dragHandle);\n }\n\n syncUIWithState();\n }\n\n function updateActionSpecificUI(action) {\n const host = STATE.box;\n if (!host) return;\n\n // Hide all action-specific groups\n const textGroup = host.querySelector('#__em_action_text_group');\n const keysGroup = host.querySelector('#__em_action_keys_group');\n const scrollOptions = host.querySelector('#__em_scroll_options');\n const clickOptions = host.querySelector('#__em_click_options');\n\n if (textGroup) textGroup.style.display = 'none';\n if (keysGroup) keysGroup.style.display = 'none';\n if (scrollOptions) scrollOptions.style.display = 'none';\n if (clickOptions) clickOptions.style.display = 'none';\n\n // Show relevant options based on action\n if (action === 'type_text') {\n if (textGroup) textGroup.style.display = 'block';\n } else if (action === 'press_keys') {\n if (keysGroup) keysGroup.style.display = 'block';\n } else if (action === 'scroll') {\n if (scrollOptions) scrollOptions.style.display = 'block';\n } else if (['left_click', 'double_click', 'right_click'].includes(action)) {\n if (clickOptions) clickOptions.style.display = 'block';\n\n // For right_click, button selector is not relevant (always 'right')\n // Hide the button field for right_click\n const buttonField = host.querySelector('#__em_btn')?.closest('.em-field');\n if (buttonField) {\n buttonField.style.display = action === 'right_click' ? 'none' : 'block';\n }\n }\n // hover: no extra options needed\n }\n\n function syncUIWithState() {\n const host = STATE.box;\n if (!host) return;\n\n const state = StateStore.get();\n\n const typeSelect = host.querySelector('#__em_selector_type');\n if (typeSelect) typeSelect.value = state.selectorType;\n\n // Initialize list mode button state\n const listModeBtn = host.querySelector('#__em_toggle_list');\n if (listModeBtn) {\n if (state.listMode) {\n listModeBtn.classList.add('active');\n } else {\n listModeBtn.classList.remove('active');\n }\n }\n\n const prefId = host.querySelector('#__em_pref_id');\n const prefAttr = host.querySelector('#__em_pref_attr');\n const prefClass = host.querySelector('#__em_pref_class');\n if (prefId) prefId.checked = state.prefs.preferId;\n if (prefAttr) prefAttr.checked = state.prefs.preferStableAttr;\n if (prefClass) prefClass.checked = state.prefs.preferClass;\n\n // Initialize action-specific UI\n const actionSelect = host.querySelector('#__em_action');\n if (actionSelect) {\n updateActionSpecificUI(actionSelect.value);\n }\n }\n\n // ============================================================================\n // Cross-Frame Bridge\n // ============================================================================\n\n // Register window message listener in all frames (not just main)\n // to support cross-frame highlighting from popup validation\n window.addEventListener(\n 'message',\n (ev) => {\n try {\n const data = ev?.data;\n if (!data) return;\n\n // Handle iframe highlight request (works even when overlay is inactive)\n if (data.type === 'em-highlight-request') {\n highlightSelectorExternal({\n selector: data.selector,\n selectorType: data.selectorType || 'css',\n listMode: !!data.listMode,\n })\n .then((result) => {\n window.parent.postMessage(\n {\n type: 'em-highlight-result',\n reqId: data.reqId,\n result,\n },\n '*',\n );\n })\n .catch((error) => {\n window.parent.postMessage(\n {\n type: 'em-highlight-result',\n reqId: data.reqId,\n result: { success: false, error: error?.message || String(error) },\n },\n '*',\n );\n });\n return;\n }\n\n // Following messages only relevant when overlay is active\n if (!STATE.active) return;\n\n // Only main frame handles these overlay-related messages\n if (!IS_MAIN) return;\n\n const iframes = Array.from(document.querySelectorAll('iframe'));\n const host = iframes.find((f) => {\n try {\n return f.contentWindow === ev.source;\n } catch {\n return false;\n }\n });\n\n if (!host) return;\n\n const base = host.getBoundingClientRect();\n\n if (data.type === 'em_hover' && Array.isArray(data.rects)) {\n // Use pooled rect boxes for better performance\n drawRectBoxes(data.rects, {\n offsetX: base.left,\n offsetY: base.top,\n color: CONFIG.COLORS.HOVER,\n dashed: true,\n });\n } else if (data.type === 'em_click' && data.innerSel) {\n const frameSel = generateSelector(host);\n const composite = frameSel ? `${frameSel} |> ${data.innerSel}` : data.innerSel;\n const selectorText = STATE.box?.querySelector('#__em_selector');\n const selectorDisplay = STATE.box?.querySelector('#__em_selector_text');\n if (selectorText) selectorText.textContent = composite;\n if (selectorDisplay) selectorDisplay.textContent = composite;\n }\n } catch {}\n },\n true,\n );\n\n // ============================================================================\n // Message Handlers\n // ============================================================================\n\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n if (request?.action === 'element_marker_start') {\n start();\n sendResponse({ ok: true });\n return true;\n } else if (request?.action === 'element_marker_ping') {\n sendResponse({ status: 'pong' });\n return false;\n } else if (request?.action === 'element_marker_highlight') {\n highlightSelectorExternal({\n selector: request.selector,\n selectorType: request.selectorType,\n listMode: !!request.listMode,\n })\n .then((result) => sendResponse(result))\n .catch((error) => sendResponse({ success: false, error: error?.message || String(error) }));\n return true;\n }\n return false;\n });\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/element-picker.js", "content": "/* eslint-disable */\n/**\n * Element Picker Inject Script\n *\n * Injected script to let the user manually pick elements for chrome_request_element_selection.\n * - Writes refs into window.__claudeElementMap (compatible with accessibility-tree-helper.js)\n * - Generates stable CSS selectors (prefers id/data-testid/etc.)\n * - Supports iframe picking by reporting selection via chrome.runtime.sendMessage (background reads sender.frameId)\n */\n\n(function () {\n 'use strict';\n\n // Prevent double initialization\n if (window.__MCP_ELEMENT_PICKER_INITIALIZED__) return;\n window.__MCP_ELEMENT_PICKER_INITIALIZED__ = true;\n\n // ============================================================\n // Constants\n // ============================================================\n\n const UI_HOST_ID = '__mcp_element_picker_host__';\n const HIGHLIGHT_ID = '__mcp_element_picker_highlight__';\n const MAX_TEXT_LEN = 160;\n\n // Highlight colors matching Editorial accent (terracotta)\n const HIGHLIGHT_COLOR = '#d97757';\n const HIGHLIGHT_BG = 'rgba(217, 119, 87, 0.08)';\n const HIGHLIGHT_BORDER = 'rgba(217, 119, 87, 0.4)';\n\n // ============================================================\n // State\n // ============================================================\n\n const STATE = {\n active: false,\n sessionId: null,\n activeRequestId: null,\n listenersAttached: false,\n hoverRafId: null,\n pendingHoverEvent: null,\n lastHoverEl: null,\n highlighter: null,\n };\n\n // ============================================================\n // CSS Escape Helper\n // ============================================================\n\n function cssEscape(value) {\n try {\n if (window.CSS && typeof window.CSS.escape === 'function') {\n return window.CSS.escape(value);\n }\n } catch {\n // Fallback\n }\n return String(value).replace(/[^a-zA-Z0-9_-]/g, (c) => `\\\\${c}`);\n }\n\n // ============================================================\n // UI Detection Helpers\n // ============================================================\n\n function getUiHost() {\n try {\n return document.getElementById(UI_HOST_ID);\n } catch {\n return null;\n }\n }\n\n function isOverlayElement(node) {\n if (!(node instanceof Node)) return false;\n const host = getUiHost();\n if (!host) return false;\n if (node === host) return true;\n const root = typeof node.getRootNode === 'function' ? node.getRootNode() : null;\n return root instanceof ShadowRoot && root.host === host;\n }\n\n function isEventFromUi(ev) {\n if (!ev) return false;\n try {\n if (typeof ev.composedPath === 'function') {\n const path = ev.composedPath();\n if (Array.isArray(path)) {\n return path.some((n) => isOverlayElement(n));\n }\n }\n } catch {\n // Fallback\n }\n return isOverlayElement(ev.target);\n }\n\n /**\n * Get the deepest page target from an event, handling Shadow DOM.\n */\n function getDeepPageTarget(ev) {\n if (!ev) return null;\n try {\n const path = typeof ev.composedPath === 'function' ? ev.composedPath() : null;\n if (Array.isArray(path) && path.length > 0) {\n for (const node of path) {\n if (node instanceof Element && !isOverlayElement(node)) {\n return node;\n }\n }\n }\n } catch {\n // Fallback\n }\n const fallback = ev.target instanceof Element ? ev.target : null;\n if (fallback && !isOverlayElement(fallback)) {\n return fallback;\n }\n return null;\n }\n\n // ============================================================\n // Highlighter\n // ============================================================\n\n function ensureHighlighter() {\n if (STATE.highlighter && STATE.highlighter.isConnected) {\n return STATE.highlighter;\n }\n\n // Remove any existing highlighter\n try {\n const existing = document.getElementById(HIGHLIGHT_ID);\n if (existing) existing.remove();\n } catch {\n // Best effort\n }\n\n const hl = document.createElement('div');\n hl.id = HIGHLIGHT_ID;\n Object.assign(hl.style, {\n position: 'fixed',\n left: '0px',\n top: '0px',\n width: '0px',\n height: '0px',\n border: `2px solid ${HIGHLIGHT_COLOR}`,\n borderRadius: '4px',\n boxShadow: `0 0 0 1px ${HIGHLIGHT_BORDER}`,\n background: HIGHLIGHT_BG,\n pointerEvents: 'none',\n zIndex: '2147483647',\n display: 'none',\n transition: 'transform 60ms linear, width 60ms linear, height 60ms linear',\n });\n\n try {\n (document.documentElement || document.body).appendChild(hl);\n } catch {\n // Best effort\n }\n\n STATE.highlighter = hl;\n return hl;\n }\n\n function clearHighlighter() {\n const hl = STATE.highlighter;\n if (!hl) return;\n try {\n hl.style.display = 'none';\n } catch {\n // Best effort\n }\n }\n\n function moveHighlighterTo(el) {\n const hl = ensureHighlighter();\n if (!hl || !(el instanceof Element)) return;\n\n let rect;\n try {\n rect = el.getBoundingClientRect();\n } catch {\n clearHighlighter();\n return;\n }\n\n if (!rect || rect.width <= 0 || rect.height <= 0) {\n clearHighlighter();\n return;\n }\n\n try {\n hl.style.display = 'block';\n hl.style.transform = `translate(${Math.round(rect.left)}px, ${Math.round(rect.top)}px)`;\n hl.style.width = `${Math.round(rect.width)}px`;\n hl.style.height = `${Math.round(rect.height)}px`;\n } catch {\n // Best effort\n }\n }\n\n // ============================================================\n // Selector Uniqueness Check (Optimized)\n // ============================================================\n\n /**\n * Check if element is inside a Shadow DOM.\n */\n function isInShadowDom(el) {\n try {\n const root = el.getRootNode();\n return root instanceof ShadowRoot;\n } catch {\n return false;\n }\n }\n\n /**\n * Fast uniqueness check using native querySelectorAll.\n * For Shadow DOM elements, queries within their shadow root only.\n */\n function isSelectorUnique(selector, target) {\n if (!selector || !(target instanceof Element)) return false;\n\n try {\n // For elements not in Shadow DOM, use fast native query\n if (!isInShadowDom(target)) {\n const matches = document.querySelectorAll(selector);\n return matches.length === 1 && matches[0] === target;\n }\n\n // For Shadow DOM elements, query within their root\n const root = target.getRootNode();\n if (root instanceof ShadowRoot) {\n const matches = root.querySelectorAll(selector);\n return matches.length === 1 && matches[0] === target;\n }\n\n return false;\n } catch {\n return false;\n }\n }\n\n // ============================================================\n // Selector Generation (Stable & Unique)\n // ============================================================\n\n function buildPathFromAncestor(ancestor, target) {\n const segs = [];\n let cur = target;\n\n const root = target.getRootNode();\n const isShadowElement = root instanceof ShadowRoot;\n const boundary = isShadowElement ? root.host : document.body;\n\n while (cur && cur !== ancestor && cur !== boundary) {\n let seg = cur.tagName.toLowerCase();\n const parent = cur.parentElement;\n if (parent) {\n const siblings = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);\n if (siblings.length > 1) {\n seg += `:nth-of-type(${siblings.indexOf(cur) + 1})`;\n }\n }\n segs.unshift(seg);\n cur = parent;\n if (isShadowElement && cur === boundary) break;\n }\n\n return segs.join(' > ');\n }\n\n function buildFullPath(el) {\n let path = '';\n let current = el;\n\n const root = el.getRootNode();\n const isShadowElement = root instanceof ShadowRoot;\n const boundary = isShadowElement ? root.host : document.body;\n\n while (current && current.nodeType === Node.ELEMENT_NODE && current !== boundary) {\n let sel = current.tagName.toLowerCase();\n const parent = current.parentElement;\n if (parent) {\n const siblings = Array.from(parent.children).filter((c) => c.tagName === current.tagName);\n if (siblings.length > 1) {\n sel += `:nth-of-type(${siblings.indexOf(current) + 1})`;\n }\n }\n path = path ? `${sel} > ${path}` : sel;\n current = parent;\n if (isShadowElement && current === boundary) break;\n }\n\n if (isShadowElement) return path || el.tagName.toLowerCase();\n return path ? `body > ${path}` : 'body';\n }\n\n /**\n * Generate a stable CSS selector for an element.\n * Prioritizes: id > data-testid/data-test/etc > anchor + relative path > full path\n */\n function generateSelector(el) {\n if (!(el instanceof Element)) return '';\n\n // Prefer unique IDs\n try {\n if (el.id) {\n const idSel = `#${cssEscape(el.id)}`;\n if (isSelectorUnique(idSel, el)) return idSel;\n }\n } catch {\n // Continue\n }\n\n // Prefer stable test attributes\n try {\n const attrNames = [\n 'data-testid',\n 'data-testId',\n 'data-test',\n 'data-qa',\n 'data-cy',\n 'name',\n 'aria-label',\n 'title',\n 'alt',\n ];\n const tag = el.tagName.toLowerCase();\n for (const attr of attrNames) {\n const v = el.getAttribute(attr);\n if (!v) continue;\n const attrSel = `[${attr}=\"${cssEscape(v)}\"]`;\n const testSel = /^(input|textarea|select)$/i.test(tag) ? `${tag}${attrSel}` : attrSel;\n if (isSelectorUnique(testSel, el)) return testSel;\n }\n } catch {\n // Continue\n }\n\n // Anchor + relative path\n try {\n let cur = el;\n const anchorAttrs = [\n 'id',\n 'data-testid',\n 'data-testId',\n 'data-test',\n 'data-qa',\n 'data-cy',\n 'name',\n ];\n\n const root = el.getRootNode();\n const isShadowElement = root instanceof ShadowRoot;\n const boundary = isShadowElement ? root.host : document.body;\n\n while (cur && cur !== boundary) {\n if (cur.id) {\n const anchor = `#${cssEscape(cur.id)}`;\n if (isSelectorUnique(anchor, cur)) {\n const rel = buildPathFromAncestor(cur, el);\n const composed = rel ? `${anchor} ${rel}` : anchor;\n if (isSelectorUnique(composed, el)) return composed;\n }\n }\n\n for (const attr of anchorAttrs) {\n const val = cur.getAttribute(attr);\n if (!val) continue;\n const aSel = `[${attr}=\"${cssEscape(val)}\"]`;\n if (isSelectorUnique(aSel, cur)) {\n const rel = buildPathFromAncestor(cur, el);\n const composed = rel ? `${aSel} ${rel}` : aSel;\n if (isSelectorUnique(composed, el)) return composed;\n }\n }\n\n cur = cur.parentElement;\n }\n } catch {\n // Continue\n }\n\n // Fallback to full path\n return buildFullPath(el);\n }\n\n // ============================================================\n // Text Summarization\n // ============================================================\n\n function summarizeText(el) {\n if (!(el instanceof Element)) return '';\n try {\n const aria = el.getAttribute('aria-label');\n if (aria && aria.trim()) return aria.trim().slice(0, MAX_TEXT_LEN);\n const placeholder = el.getAttribute('placeholder');\n if (placeholder && placeholder.trim()) return placeholder.trim().slice(0, MAX_TEXT_LEN);\n const title = el.getAttribute('title');\n if (title && title.trim()) return title.trim().slice(0, MAX_TEXT_LEN);\n const alt = el.getAttribute('alt');\n if (alt && alt.trim()) return alt.trim().slice(0, MAX_TEXT_LEN);\n } catch {\n // Continue\n }\n try {\n const t = (el.textContent || '').trim().replace(/\\s+/g, ' ');\n return t ? t.slice(0, MAX_TEXT_LEN) : '';\n } catch {\n return '';\n }\n }\n\n // ============================================================\n // Ref Management (Compatible with accessibility-tree-helper.js)\n // ============================================================\n\n function ensureRefForElement(el) {\n try {\n if (!window.__claudeElementMap) window.__claudeElementMap = {};\n if (!window.__claudeRefCounter) window.__claudeRefCounter = 0;\n } catch {\n // Best effort\n }\n\n // Check if element already has a ref\n let refId = null;\n try {\n for (const k in window.__claudeElementMap) {\n const w = window.__claudeElementMap[k];\n if (w && w.deref && w.deref() === el) {\n refId = k;\n break;\n }\n }\n } catch {\n // Continue\n }\n\n // Create new ref if needed\n if (!refId) {\n try {\n refId = `ref_${++window.__claudeRefCounter}`;\n window.__claudeElementMap[refId] = new WeakRef(el);\n } catch {\n // Continue\n }\n }\n\n return refId || '';\n }\n\n // ============================================================\n // Communication\n // ============================================================\n\n function sendFrameEvent(payload) {\n try {\n chrome.runtime.sendMessage(payload);\n } catch {\n // Best effort\n }\n }\n\n // ============================================================\n // Event Handlers\n // ============================================================\n\n function processMouseMove(ev) {\n if (!STATE.active) return;\n\n // Skip if event is from our UI\n if (isEventFromUi(ev)) {\n STATE.lastHoverEl = null;\n clearHighlighter();\n return;\n }\n\n const target = getDeepPageTarget(ev);\n if (!target) {\n STATE.lastHoverEl = null;\n clearHighlighter();\n return;\n }\n\n // Skip if same element\n if (STATE.lastHoverEl === target) return;\n STATE.lastHoverEl = target;\n moveHighlighterTo(target);\n }\n\n function onMouseMove(ev) {\n if (!STATE.active) return;\n STATE.pendingHoverEvent = ev;\n if (STATE.hoverRafId != null) return;\n STATE.hoverRafId = requestAnimationFrame(() => {\n STATE.hoverRafId = null;\n const latest = STATE.pendingHoverEvent;\n STATE.pendingHoverEvent = null;\n if (!latest) return;\n processMouseMove(latest);\n });\n }\n\n function onClick(ev) {\n if (!STATE.active) return;\n\n // Allow UI interactions without interference\n if (isEventFromUi(ev)) return;\n\n const rawTarget = ev.target instanceof Element ? ev.target : null;\n if (!rawTarget) return;\n\n // Require an active request id so background can map the selection\n if (!STATE.sessionId || !STATE.activeRequestId) return;\n\n ev.preventDefault();\n ev.stopPropagation();\n\n const target = getDeepPageTarget(ev) || rawTarget;\n if (!(target instanceof Element)) return;\n\n const ref = ensureRefForElement(target);\n const selector = generateSelector(target);\n let rect;\n try {\n rect = target.getBoundingClientRect();\n } catch {\n rect = { x: 0, y: 0, width: 0, height: 0, left: 0, top: 0 };\n }\n\n const center = {\n x: Math.round(rect.left + rect.width / 2),\n y: Math.round(rect.top + rect.height / 2),\n };\n\n sendFrameEvent({\n type: 'element_picker_frame_event',\n sessionId: STATE.sessionId,\n event: 'selected',\n requestId: STATE.activeRequestId,\n element: {\n ref,\n selector,\n selectorType: 'css',\n rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },\n center,\n text: summarizeText(target),\n tagName: target.tagName ? String(target.tagName).toLowerCase() : '',\n },\n });\n }\n\n function onKeyDown(ev) {\n if (!STATE.active) return;\n if (ev && ev.key === 'Escape') {\n if (isEventFromUi(ev)) return;\n ev.preventDefault();\n ev.stopPropagation();\n if (STATE.sessionId) {\n sendFrameEvent({\n type: 'element_picker_frame_event',\n sessionId: STATE.sessionId,\n event: 'cancel',\n });\n }\n }\n }\n\n // ============================================================\n // Listener Management\n // ============================================================\n\n function attachListeners() {\n if (STATE.listenersAttached) return;\n window.addEventListener('mousemove', onMouseMove, true);\n window.addEventListener('click', onClick, true);\n window.addEventListener('keydown', onKeyDown, true);\n STATE.listenersAttached = true;\n }\n\n function detachListeners() {\n if (!STATE.listenersAttached) return;\n window.removeEventListener('mousemove', onMouseMove, true);\n window.removeEventListener('click', onClick, true);\n window.removeEventListener('keydown', onKeyDown, true);\n STATE.listenersAttached = false;\n }\n\n // ============================================================\n // Session Management API\n // ============================================================\n\n function startSession(payload) {\n const sessionId = payload && payload.sessionId ? String(payload.sessionId) : '';\n if (!sessionId) return;\n\n STATE.active = true;\n STATE.sessionId = sessionId;\n STATE.activeRequestId =\n payload && payload.activeRequestId ? String(payload.activeRequestId) : null;\n ensureHighlighter();\n attachListeners();\n }\n\n function stopSession(payload) {\n const sessionId = payload && payload.sessionId ? String(payload.sessionId) : '';\n // Only stop if session matches or no specific session requested\n if (sessionId && STATE.sessionId && sessionId !== STATE.sessionId) return;\n\n STATE.active = false;\n STATE.sessionId = null;\n STATE.activeRequestId = null;\n STATE.lastHoverEl = null;\n detachListeners();\n clearHighlighter();\n\n // Remove highlighter element\n try {\n const hl = STATE.highlighter;\n if (hl && hl.remove) hl.remove();\n } catch {\n // Best effort\n }\n STATE.highlighter = null;\n }\n\n function setActiveRequest(payload) {\n const sessionId = payload && payload.sessionId ? String(payload.sessionId) : '';\n if (sessionId && STATE.sessionId && sessionId !== STATE.sessionId) return;\n STATE.activeRequestId =\n payload && payload.activeRequestId ? String(payload.activeRequestId) : null;\n }\n\n // ============================================================\n // Expose API for Background Script\n // ============================================================\n\n window.__mcpElementPicker = {\n startSession,\n stopSession,\n setActiveRequest,\n };\n\n // ============================================================\n // Message Listener (for direct communication)\n // ============================================================\n\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n try {\n if (request && request.action === 'chrome_request_element_selection_ping') {\n sendResponse({ status: 'pong' });\n return false;\n }\n if (request && request.action === 'elementPickerStart') {\n startSession(request);\n sendResponse({ success: true });\n return false;\n }\n if (request && request.action === 'elementPickerStop') {\n stopSession(request);\n sendResponse({ success: true });\n return false;\n }\n if (request && request.action === 'elementPickerSetActiveRequest') {\n setActiveRequest(request);\n sendResponse({ success: true });\n return false;\n }\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return false;\n }\n return false;\n });\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/fill-helper.js", "content": "/* eslint-disable */\n// fill-helper.js\n// This script is injected into the page to handle form filling operations\n\nif (window.__FILL_HELPER_INITIALIZED__) {\n // Already initialized, skip\n} else {\n window.__FILL_HELPER_INITIALIZED__ = true;\n /**\n * Fill an input element with the specified value\n * @param {string} selector - CSS selector for the element to fill\n * @param {string} value - Value to fill into the element\n * @returns {Promise} - Result of the fill operation\n */\n async function fillElement(selector, value, ref = null) {\n try {\n // Find the element\n let element = null;\n if (ref && typeof ref === 'string') {\n try {\n const map = window.__claudeElementMap;\n const weak = map && map[ref];\n element = weak && typeof weak.deref === 'function' ? weak.deref() : null;\n } catch (e) {\n // ignore\n }\n if (!element || !(element instanceof Element)) {\n return {\n error: `Element ref \"${ref}\" not found. Please call chrome_read_page first and ensure the ref is still valid.`,\n };\n }\n } else {\n element = document.querySelector(selector);\n }\n if (!element) {\n return {\n error: selector\n ? `Element with selector \"${selector}\" not found`\n : `Element for ref not found`,\n };\n }\n\n // Get element information\n const rect = element.getBoundingClientRect();\n const elementInfo = {\n tagName: element.tagName,\n id: element.id,\n className: element.className,\n type: element.type || null,\n isVisible: isElementVisible(element),\n rect: {\n x: rect.x,\n y: rect.y,\n width: rect.width,\n height: rect.height,\n top: rect.top,\n right: rect.right,\n bottom: rect.bottom,\n left: rect.left,\n },\n };\n\n // Check if element is visible\n if (!elementInfo.isVisible) {\n return {\n error: `Element with selector \"${selector}\" is not visible`,\n elementInfo,\n };\n }\n\n // Check if element is an input, textarea, or select\n const validTags = ['INPUT', 'TEXTAREA', 'SELECT'];\n // Keep a permissive list to allow type-specific branches below to handle behavior\n const validInputTypes = [\n 'text',\n 'email',\n 'password',\n 'number',\n 'search',\n 'tel',\n 'url',\n 'date',\n 'datetime-local',\n 'month',\n 'time',\n 'week',\n 'color',\n 'checkbox',\n 'radio',\n 'range',\n ];\n\n if (!validTags.includes(element.tagName)) {\n // If the element is a custom element with open shadow root, try to find a fillable inner control\n try {\n const anyEl = /** @type {any} */ (element);\n const sr = anyEl && anyEl.shadowRoot ? anyEl.shadowRoot : null;\n if (sr) {\n // Search common fillable targets inside shadow root (breadth-first)\n const queue = Array.from(sr.children || []);\n const isFillable = (el) =>\n !!el &&\n (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT');\n while (queue.length) {\n const cur = queue.shift();\n if (!cur) continue;\n if (isFillable(cur)) {\n element = cur;\n break;\n }\n try {\n const children = cur.children || [];\n for (let i = 0; i < children.length; i++) queue.push(children[i]);\n const innerSr = /** @type {any} */ (cur).shadowRoot;\n if (innerSr && innerSr.children) {\n for (let i = 0; i < innerSr.children.length; i++) queue.push(innerSr.children[i]);\n }\n } catch (_) {}\n }\n if (!validTags.includes(element.tagName)) {\n return {\n error: `Element with selector \"${selector}\" is not a fillable element (must be INPUT, TEXTAREA, or SELECT)`,\n elementInfo,\n };\n }\n } else {\n return {\n error: `Element with selector \"${selector}\" is not a fillable element (must be INPUT, TEXTAREA, or SELECT)`,\n elementInfo,\n };\n }\n } catch (_) {\n return {\n error: `Element with selector \"${selector}\" is not a fillable element (must be INPUT, TEXTAREA, or SELECT)`,\n elementInfo,\n };\n }\n }\n\n // For input elements, check if the type is valid (allow type-specific branches below)\n if (\n element.tagName === 'INPUT' &&\n !validInputTypes.includes(element.type) &&\n element.type !== null\n ) {\n return {\n error: `Input element with selector \"${selector}\" has type \"${element.type}\" which is not fillable`,\n elementInfo,\n };\n }\n\n // Scroll element into view\n element.scrollIntoView({ behavior: 'auto', block: 'center', inline: 'center' });\n await new Promise((resolve) => setTimeout(resolve, 100));\n\n // Focus the element\n element.focus();\n\n // Type-specific handling for tricky inputs first\n if (element.tagName === 'INPUT' && element.type === 'checkbox') {\n // Accept boolean or string-like boolean\n let checkedVal;\n if (typeof value === 'boolean') {\n checkedVal = value;\n } else if (typeof value === 'string') {\n const v = value.trim().toLowerCase();\n if (['true', '1', 'yes', 'on'].includes(v)) checkedVal = true;\n else if (['false', '0', 'no', 'off'].includes(v)) checkedVal = false;\n }\n if (typeof checkedVal !== 'boolean') {\n return {\n error:\n 'Checkbox requires a boolean (true/false) or a boolean-like string (\"true\"/\"false\"/\"on\"/\"off\").',\n elementInfo,\n };\n }\n const previous = element.checked;\n element.checked = checkedVal;\n element.focus();\n element.dispatchEvent(new Event('input', { bubbles: true }));\n element.dispatchEvent(new Event('change', { bubbles: true }));\n element.blur();\n return {\n success: true,\n message: `Checkbox set to ${element.checked}`,\n elementInfo: { ...elementInfo, checked: element.checked, previousChecked: previous },\n };\n }\n\n if (element.tagName === 'INPUT' && element.type === 'radio') {\n // For radios, the selector/ref should target the specific input to select\n const previous = element.checked;\n element.checked = true;\n element.focus();\n element.dispatchEvent(new Event('input', { bubbles: true }));\n element.dispatchEvent(new Event('change', { bubbles: true }));\n element.blur();\n return {\n success: true,\n message: 'Radio selected',\n elementInfo: {\n ...elementInfo,\n checked: element.checked,\n previousChecked: previous,\n name: element.name || null,\n },\n };\n }\n\n if (element.tagName === 'INPUT' && element.type === 'range') {\n const numericValue = typeof value === 'number' ? value : Number(value);\n if (Number.isNaN(numericValue)) {\n return { error: 'Range input requires a numeric value', elementInfo };\n }\n const previous = element.value;\n element.value = String(numericValue);\n element.focus();\n element.dispatchEvent(new Event('input', { bubbles: true }));\n element.dispatchEvent(new Event('change', { bubbles: true }));\n element.blur();\n return {\n success: true,\n message: `Set range to ${element.value} (min: ${element.min}, max: ${element.max})`,\n elementInfo: { ...elementInfo, value: element.value },\n };\n }\n\n if (element.tagName === 'INPUT' && element.type === 'number') {\n if (value !== '' && value !== null && value !== undefined && Number.isNaN(Number(value))) {\n return { error: 'Number input requires a numeric value', elementInfo };\n }\n const previous = element.value;\n element.value = String(value ?? '');\n element.focus();\n element.dispatchEvent(new Event('input', { bubbles: true }));\n element.dispatchEvent(new Event('change', { bubbles: true }));\n element.blur();\n return {\n success: true,\n message: `Set number input to ${element.value} (previous: ${previous})`,\n elementInfo: { ...elementInfo, value: element.value },\n };\n }\n\n // Fill the element based on its type\n if (element.tagName === 'SELECT') {\n // For select elements, find the option with matching value or text\n let optionFound = false;\n for (const option of element.options) {\n if (option.value === value || option.text === value) {\n element.value = option.value;\n optionFound = true;\n break;\n }\n }\n\n if (!optionFound) {\n return {\n error: `No option with value or text \"${value}\" found in select element`,\n elementInfo,\n };\n }\n\n // Trigger change event\n element.dispatchEvent(new Event('change', { bubbles: true }));\n } else {\n // For input and textarea elements\n // Clear the current value then set new value\n element.value = '';\n element.dispatchEvent(new Event('input', { bubbles: true }));\n\n element.value = String(value);\n\n element.dispatchEvent(new Event('input', { bubbles: true }));\n element.dispatchEvent(new Event('change', { bubbles: true }));\n }\n\n // Blur the element\n element.blur();\n\n return {\n success: true,\n message: 'Element filled successfully',\n elementInfo: {\n ...elementInfo,\n value: element.value, // Include the final value in the response\n },\n };\n } catch (error) {\n return {\n error: `Error filling element: ${error.message}`,\n };\n }\n }\n\n /**\n * Check if an element is visible\n * @param {Element} element - The element to check\n * @returns {boolean} - Whether the element is visible\n */\n function isElementVisible(element) {\n if (!element) return false;\n\n const style = window.getComputedStyle(element);\n if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {\n return false;\n }\n\n const rect = element.getBoundingClientRect();\n if (rect.width === 0 || rect.height === 0) {\n return false;\n }\n\n // Check if element is within viewport\n if (\n rect.bottom < 0 ||\n rect.top > window.innerHeight ||\n rect.right < 0 ||\n rect.left > window.innerWidth\n ) {\n return false;\n }\n\n // Check if element is actually visible at its center point\n const centerX = rect.left + rect.width / 2;\n const centerY = rect.top + rect.height / 2;\n\n const elementAtPoint = document.elementFromPoint(centerX, centerY);\n if (!elementAtPoint) return false;\n\n return element === elementAtPoint || element.contains(elementAtPoint);\n }\n\n // Listen for messages from the extension\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n if (request.action === 'fillElement') {\n fillElement(request.selector, request.value, request.ref)\n .then(sendResponse)\n .catch((error) => {\n sendResponse({\n error: `Unexpected error: ${error.message}`,\n });\n });\n return true; // Indicates async response\n } else if (request.action === 'chrome_fill_or_select_ping') {\n sendResponse({ status: 'pong' });\n return false;\n }\n });\n}\n" }, { "path": "app/chrome-extension/inject-scripts/inject-bridge.js", "content": "/* eslint-disable */\n\n(() => {\n // Prevent duplicate injection of the bridge itself.\n if (window.__INJECT_SCRIPT_TOOL_UNIVERSAL_BRIDGE_LOADED__) return;\n window.__INJECT_SCRIPT_TOOL_UNIVERSAL_BRIDGE_LOADED__ = true;\n const EVENT_NAME = {\n RESPONSE: 'chrome-mcp:response',\n CLEANUP: 'chrome-mcp:cleanup',\n EXECUTE: 'chrome-mcp:execute',\n };\n const pendingRequests = new Map();\n\n const messageHandler = (request, _sender, sendResponse) => {\n // --- Lifecycle Command ---\n if (request.type === EVENT_NAME.CLEANUP) {\n window.dispatchEvent(new CustomEvent(EVENT_NAME.CLEANUP));\n // Acknowledge cleanup signal received, but don't hold the connection.\n sendResponse({ success: true });\n return true;\n }\n\n // --- Execution Command for MAIN world ---\n if (request.targetWorld === 'MAIN') {\n const requestId = `req-${Date.now()}-${Math.random()}`;\n pendingRequests.set(requestId, sendResponse);\n\n window.dispatchEvent(\n new CustomEvent(EVENT_NAME.EXECUTE, {\n detail: {\n action: request.action,\n payload: request.payload,\n requestId: requestId,\n },\n }),\n );\n return true; // Async response is expected.\n }\n // Note: Requests for ISOLATED world are handled by the user's isolatedWorldCode script directly.\n // This listener won't process them unless it's the only script in ISOLATED world.\n };\n\n chrome.runtime.onMessage.addListener(messageHandler);\n\n // Listen for responses coming back from the MAIN world.\n const responseHandler = (event) => {\n const { requestId, data, error } = event.detail;\n if (pendingRequests.has(requestId)) {\n const sendResponse = pendingRequests.get(requestId);\n sendResponse({ data, error });\n pendingRequests.delete(requestId);\n }\n };\n window.addEventListener(EVENT_NAME.RESPONSE, responseHandler);\n\n // --- Self Cleanup ---\n // When the cleanup signal arrives, this bridge must also clean itself up.\n const cleanupHandler = () => {\n chrome.runtime.onMessage.removeListener(messageHandler);\n window.removeEventListener(EVENT_NAME.RESPONSE, responseHandler);\n window.removeEventListener(EVENT_NAME.CLEANUP, cleanupHandler);\n delete window.__INJECT_SCRIPT_TOOL_UNIVERSAL_BRIDGE_LOADED__;\n };\n window.addEventListener(EVENT_NAME.CLEANUP, cleanupHandler);\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/interactive-elements-helper.js", "content": "/* eslint-disable */\n// interactive-elements-helper.js\n// This script is injected into the page to find interactive elements.\n// Final version by Calvin, featuring a multi-layered fallback strategy\n// and comprehensive element support, built on a performant and reliable core.\n\n(function () {\n // Prevent re-initialization\n if (window.__INTERACTIVE_ELEMENTS_HELPER_INITIALIZED__) {\n return;\n }\n window.__INTERACTIVE_ELEMENTS_HELPER_INITIALIZED__ = true;\n\n /**\n * @typedef {Object} ElementInfo\n * @property {string} type - The type of the element (e.g., 'button', 'link').\n * @property {string} selector - A CSS selector to uniquely identify the element.\n * @property {string} text - The visible text or accessible name of the element.\n * @property {boolean} isInteractive - Whether the element is currently interactive.\n * @property {Object} [coordinates] - The coordinates of the element if requested.\n * @property {boolean} [disabled] - For elements that can be disabled.\n * @property {string} [href] - For links.\n * @property {boolean} [checked] - for checkboxes and radio buttons.\n */\n\n /**\n * Configuration for element types and their corresponding selectors.\n * Now more comprehensive with common ARIA roles.\n */\n const ELEMENT_CONFIG = {\n button: 'button, input[type=\"button\"], input[type=\"submit\"], [role=\"button\"]',\n link: 'a[href], [role=\"link\"]',\n input:\n 'input:not([type=\"button\"]):not([type=\"submit\"]):not([type=\"checkbox\"]):not([type=\"radio\"])',\n checkbox: 'input[type=\"checkbox\"], [role=\"checkbox\"]',\n radio: 'input[type=\"radio\"], [role=\"radio\"]',\n textarea: 'textarea, [role=\"textbox\"], [role=\"searchbox\"]',\n select: 'select, [role=\"combobox\"]',\n tab: '[role=\"tab\"]',\n // Generic interactive elements: combines tabindex, common roles, and explicit handlers.\n // This is the key to finding custom-built interactive components.\n interactive: `[onclick], [tabindex]:not([tabindex^=\"-\"]), [role=\"menuitem\"], [role=\"slider\"], [role=\"option\"], [role=\"treeitem\"], [role=\"switch\"]`,\n };\n\n // A combined selector for ANY interactive element, used in the fallback logic.\n const ANY_INTERACTIVE_SELECTOR = Object.values(ELEMENT_CONFIG).join(', ');\n\n // Query helpers that pierce open shadow roots. These are used only in fallback paths or\n // when a selector is explicitly provided, to keep costs bounded.\n function* walkAllNodesDeep(root) {\n const stack = [root];\n const MAX = 12000; // safety bound\n let count = 0;\n while (stack.length) {\n const node = stack.pop();\n if (!node) continue;\n if (++count > MAX) break;\n yield node;\n const anyNode = /** @type {any} */ (node);\n try {\n const children = node.children ? Array.from(node.children) : [];\n for (let i = children.length - 1; i >= 0; i--) stack.push(children[i]);\n const sr = anyNode && anyNode.shadowRoot ? anyNode.shadowRoot : null;\n if (sr && sr.children) {\n const srChildren = Array.from(sr.children);\n for (let i = srChildren.length - 1; i >= 0; i--) stack.push(srChildren[i]);\n }\n } catch (_) {\n /* ignore */\n }\n }\n }\n\n function querySelectorAllDeep(selector, root = document) {\n const results = [];\n for (const node of walkAllNodesDeep(root)) {\n if (!(node instanceof Element)) continue;\n try {\n if (node.matches && node.matches(selector)) results.push(node);\n } catch (_) {\n /* ignore invalid selectors for given node */\n }\n }\n return results;\n }\n\n // --- Core Helper Functions ---\n\n /**\n * Checks if an element is genuinely visible on the page.\n * \"Visible\" means it's not styled with display:none, visibility:hidden, etc.\n * This check intentionally IGNORES whether the element is within the current viewport.\n * @param {Element} el The element to check.\n * @returns {boolean} True if the element is visible.\n */\n function isElementVisible(el) {\n if (!el || !el.isConnected) return false;\n\n const style = window.getComputedStyle(el);\n if (\n style.display === 'none' ||\n style.visibility === 'hidden' ||\n parseFloat(style.opacity) === 0\n ) {\n return false;\n }\n\n const rect = el.getBoundingClientRect();\n return rect.width > 0 || rect.height > 0 || el.tagName === 'A'; // Allow zero-size anchors as they can still be navigated\n }\n\n /**\n * Checks if an element is considered interactive (not disabled or hidden from accessibility).\n * @param {Element} el The element to check.\n * @returns {boolean} True if the element is interactive.\n */\n function isElementInteractive(el) {\n if (el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true') {\n return false;\n }\n if (el.closest('[aria-hidden=\"true\"]')) {\n return false;\n }\n return true;\n }\n\n /**\n * Generates a reasonably stable CSS selector for a given element.\n * @param {Element} el The element.\n * @returns {string} A CSS selector.\n */\n function generateSelector(el) {\n if (!(el instanceof Element)) return '';\n\n if (el.id) {\n const idSelector = `#${CSS.escape(el.id)}`;\n if (document.querySelectorAll(idSelector).length === 1) return idSelector;\n }\n\n for (const attr of ['data-testid', 'data-cy', 'name']) {\n const attrValue = el.getAttribute(attr);\n if (attrValue) {\n const attrSelector = `[${attr}=\"${CSS.escape(attrValue)}\"]`;\n if (document.querySelectorAll(attrSelector).length === 1) return attrSelector;\n }\n }\n\n let path = '';\n let current = el;\n while (current && current.nodeType === Node.ELEMENT_NODE && current.tagName !== 'BODY') {\n let selector = current.tagName.toLowerCase();\n const parent = current.parentElement;\n if (parent) {\n const siblings = Array.from(parent.children).filter(\n (child) => child.tagName === current.tagName,\n );\n if (siblings.length > 1) {\n const index = siblings.indexOf(current) + 1;\n selector += `:nth-of-type(${index})`;\n }\n }\n path = path ? `${selector} > ${path}` : selector;\n current = parent;\n }\n return path ? `body > ${path}` : 'body';\n }\n\n /**\n * Finds the accessible name for an element (label, aria-label, etc.).\n * @param {Element} el The element.\n * @returns {string} The accessible name.\n */\n function getAccessibleName(el) {\n const labelledby = el.getAttribute('aria-labelledby');\n if (labelledby) {\n const labelElement = document.getElementById(labelledby);\n if (labelElement) return labelElement.textContent?.trim() || '';\n }\n const ariaLabel = el.getAttribute('aria-label');\n if (ariaLabel) return ariaLabel.trim();\n if (el.id) {\n const label = document.querySelector(`label[for=\"${el.id}\"]`);\n if (label) return label.textContent?.trim() || '';\n }\n const parentLabel = el.closest('label');\n if (parentLabel) return parentLabel.textContent?.trim() || '';\n return (\n el.getAttribute('placeholder') ||\n el.getAttribute('value') ||\n el.textContent?.trim() ||\n el.getAttribute('title') ||\n ''\n );\n }\n\n /**\n * Simple subsequence matching for fuzzy search.\n * @param {string} text The text to search within.\n * @param {string} query The query subsequence.\n * @returns {boolean}\n */\n function fuzzyMatch(text, query) {\n if (!text || !query) return false;\n const lowerText = text.toLowerCase();\n const lowerQuery = query.toLowerCase();\n let textIndex = 0;\n let queryIndex = 0;\n while (textIndex < lowerText.length && queryIndex < lowerQuery.length) {\n if (lowerText[textIndex] === lowerQuery[queryIndex]) {\n queryIndex++;\n }\n textIndex++;\n }\n return queryIndex === lowerQuery.length;\n }\n\n /**\n * Creates the standardized info object for an element.\n * Modified to handle the new 'text' type from the final fallback.\n */\n function createElementInfo(el, type, includeCoordinates, isInteractiveOverride = null) {\n const isActuallyInteractive = isElementInteractive(el);\n const info = {\n type,\n selector: generateSelector(el),\n text: getAccessibleName(el) || el.textContent?.trim(),\n isInteractive: isInteractiveOverride !== null ? isInteractiveOverride : isActuallyInteractive,\n disabled: el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true',\n };\n if (includeCoordinates) {\n const rect = el.getBoundingClientRect();\n info.coordinates = {\n x: rect.left + rect.width / 2,\n y: rect.top + rect.height / 2,\n rect: {\n x: rect.x,\n y: rect.y,\n width: rect.width,\n height: rect.height,\n top: rect.top,\n right: rect.right,\n bottom: rect.bottom,\n left: rect.left,\n },\n };\n }\n return info;\n }\n\n /**\n * [CORE UTILITY] Finds interactive elements based on a set of types.\n * This is our high-performance Layer 1 search function.\n */\n function findInteractiveElements(options = {}) {\n const { textQuery, includeCoordinates = true, types = Object.keys(ELEMENT_CONFIG) } = options;\n\n const selectorsToFind = types\n .map((type) => ELEMENT_CONFIG[type])\n .filter(Boolean)\n .join(', ');\n if (!selectorsToFind) return [];\n\n const targetElements = querySelectorAllDeep(selectorsToFind);\n const uniqueElements = new Set(targetElements);\n const results = [];\n\n for (const el of uniqueElements) {\n if (!isElementVisible(el) || !isElementInteractive(el)) continue;\n\n const accessibleName = getAccessibleName(el);\n if (textQuery && !fuzzyMatch(accessibleName, textQuery)) continue;\n\n let elementType = 'unknown';\n for (const [type, typeSelector] of Object.entries(ELEMENT_CONFIG)) {\n if (el.matches(typeSelector)) {\n elementType = type;\n break;\n }\n }\n results.push(createElementInfo(el, elementType, includeCoordinates));\n }\n return results;\n }\n\n /**\n * [ORCHESTRATOR] The main entry point that implements the 3-layer fallback logic.\n * @param {object} options - The main search options.\n * @returns {ElementInfo[]}\n */\n function findElementsByTextWithFallback(options = {}) {\n const { textQuery, includeCoordinates = true } = options;\n\n if (!textQuery) {\n return findInteractiveElements({ ...options, types: Object.keys(ELEMENT_CONFIG) });\n }\n\n // --- Layer 1: High-reliability search for interactive elements matching text ---\n let results = findInteractiveElements({ ...options, types: Object.keys(ELEMENT_CONFIG) });\n if (results.length > 0) {\n return results;\n }\n\n // --- Layer 2: Find text, then find its interactive ancestor ---\n const lowerCaseText = textQuery.toLowerCase();\n const xPath = `//text()[contains(translate(., 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'), '${lowerCaseText}')]`;\n const textNodes = document.evaluate(\n xPath,\n document,\n null,\n XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n null,\n );\n\n const interactiveElements = new Set();\n if (textNodes.snapshotLength > 0) {\n for (let i = 0; i < textNodes.snapshotLength; i++) {\n const parentElement = textNodes.snapshotItem(i).parentElement;\n if (parentElement) {\n const interactiveAncestor = parentElement.closest(ANY_INTERACTIVE_SELECTOR);\n if (\n interactiveAncestor &&\n isElementVisible(interactiveAncestor) &&\n isElementInteractive(interactiveAncestor)\n ) {\n interactiveElements.add(interactiveAncestor);\n }\n }\n }\n\n if (interactiveElements.size > 0) {\n return Array.from(interactiveElements).map((el) => {\n let elementType = 'interactive';\n for (const [type, typeSelector] of Object.entries(ELEMENT_CONFIG)) {\n if (el.matches(typeSelector)) {\n elementType = type;\n break;\n }\n }\n return createElementInfo(el, elementType, includeCoordinates);\n });\n }\n }\n\n // --- Layer 3: Final fallback, return any element containing the text ---\n const leafElements = new Set();\n for (let i = 0; i < textNodes.snapshotLength; i++) {\n const parentElement = textNodes.snapshotItem(i).parentElement;\n if (parentElement && isElementVisible(parentElement)) {\n leafElements.add(parentElement);\n }\n }\n\n const finalElements = Array.from(leafElements).filter((el) => {\n return ![...leafElements].some((otherEl) => el !== otherEl && el.contains(otherEl));\n });\n\n return finalElements.map((el) => createElementInfo(el, 'text', includeCoordinates, true));\n }\n\n // --- Chrome Message Listener ---\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n if (request.action === 'getInteractiveElements') {\n try {\n let elements;\n if (request.selector) {\n // If a selector is provided, bypass the text-based logic and use a direct query.\n const foundEls = querySelectorAllDeep(request.selector);\n elements = foundEls.map((el) =>\n createElementInfo(\n el,\n 'selected',\n request.includeCoordinates !== false,\n isElementInteractive(el),\n ),\n );\n } else {\n // Otherwise, use our powerful multi-layered text search\n elements = findElementsByTextWithFallback(request);\n }\n sendResponse({ success: true, elements });\n } catch (error) {\n console.error('Error in getInteractiveElements:', error);\n sendResponse({ success: false, error: error.message });\n }\n return true; // Async response\n } else if (request.action === 'chrome_get_interactive_elements_ping') {\n sendResponse({ status: 'pong' });\n return false;\n }\n });\n\n console.log('Interactive elements helper script loaded');\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/keyboard-helper.js", "content": "/* eslint-disable */\n// keyboard-helper.js\n// This script is injected into the page to handle keyboard event simulation\n\nif (window.__KEYBOARD_HELPER_INITIALIZED__) {\n // Already initialized, skip\n} else {\n window.__KEYBOARD_HELPER_INITIALIZED__ = true;\n\n // A map for special keys to their KeyboardEvent properties\n // Key names should be lowercase for matching\n const SPECIAL_KEY_MAP = {\n enter: { key: 'Enter', code: 'Enter', keyCode: 13 },\n tab: { key: 'Tab', code: 'Tab', keyCode: 9 },\n esc: { key: 'Escape', code: 'Escape', keyCode: 27 },\n escape: { key: 'Escape', code: 'Escape', keyCode: 27 },\n space: { key: ' ', code: 'Space', keyCode: 32 },\n backspace: { key: 'Backspace', code: 'Backspace', keyCode: 8 },\n delete: { key: 'Delete', code: 'Delete', keyCode: 46 },\n del: { key: 'Delete', code: 'Delete', keyCode: 46 },\n up: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },\n arrowup: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },\n down: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },\n arrowdown: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },\n left: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },\n arrowleft: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },\n right: { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },\n arrowright: { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },\n home: { key: 'Home', code: 'Home', keyCode: 36 },\n end: { key: 'End', code: 'End', keyCode: 35 },\n pageup: { key: 'PageUp', code: 'PageUp', keyCode: 33 },\n pagedown: { key: 'PageDown', code: 'PageDown', keyCode: 34 },\n insert: { key: 'Insert', code: 'Insert', keyCode: 45 },\n // Function keys\n ...Object.fromEntries(\n Array.from({ length: 12 }, (_, i) => [\n `f${i + 1}`,\n { key: `F${i + 1}`, code: `F${i + 1}`, keyCode: 112 + i },\n ]),\n ),\n };\n\n const MODIFIER_KEYS = {\n ctrl: 'ctrlKey',\n control: 'ctrlKey',\n alt: 'altKey',\n shift: 'shiftKey',\n meta: 'metaKey',\n command: 'metaKey',\n cmd: 'metaKey',\n };\n\n /**\n * Parses a key string (e.g., \"Ctrl+Shift+A\", \"Enter\") into a main key and modifiers.\n * @param {string} keyString - String representation of a single key press (can include modifiers).\n * @returns { {key: string, code: string, keyCode: number, charCode?: number, modifiers: {ctrlKey:boolean, altKey:boolean, shiftKey:boolean, metaKey:boolean}} | null }\n * Returns null if the keyString is invalid or represents only modifiers.\n */\n function parseSingleKeyCombination(keyString) {\n const parts = keyString.split('+').map((part) => part.trim().toLowerCase());\n const modifiers = {\n ctrlKey: false,\n altKey: false,\n shiftKey: false,\n metaKey: false,\n };\n let mainKeyPart = null;\n\n for (const part of parts) {\n if (MODIFIER_KEYS[part]) {\n modifiers[MODIFIER_KEYS[part]] = true;\n } else if (mainKeyPart === null) {\n // First non-modifier is the main key\n mainKeyPart = part;\n } else {\n // Invalid format: multiple main keys in a single combination (e.g., \"Ctrl+A+B\")\n console.error(`Invalid key combination string: ${keyString}. Multiple main keys found.`);\n return null;\n }\n }\n\n if (!mainKeyPart) {\n // This case could happen if the keyString is something like \"Ctrl+\" or just \"Ctrl\"\n // If the intent was to press JUST 'Control', the input should be 'Control' not 'Control+'\n // Let's check if mainKeyPart is actually a modifier name used as a main key\n if (Object.keys(MODIFIER_KEYS).includes(parts[parts.length - 1]) && parts.length === 1) {\n mainKeyPart = parts[parts.length - 1]; // e.g. user wants to press \"Control\" key itself\n // For \"Control\" key itself, key: \"Control\", code: \"ControlLeft\" (or Right)\n if (mainKeyPart === 'ctrl' || mainKeyPart === 'control')\n return { key: 'Control', code: 'ControlLeft', keyCode: 17, modifiers };\n if (mainKeyPart === 'alt') return { key: 'Alt', code: 'AltLeft', keyCode: 18, modifiers };\n if (mainKeyPart === 'shift')\n return { key: 'Shift', code: 'ShiftLeft', keyCode: 16, modifiers };\n if (mainKeyPart === 'meta' || mainKeyPart === 'command' || mainKeyPart === 'cmd')\n return { key: 'Meta', code: 'MetaLeft', keyCode: 91, modifiers };\n } else {\n console.error(`Invalid key combination string: ${keyString}. No main key specified.`);\n return null;\n }\n }\n\n const specialKey = SPECIAL_KEY_MAP[mainKeyPart];\n if (specialKey) {\n return { ...specialKey, modifiers };\n }\n\n // For single characters or other unmapped keys\n if (mainKeyPart.length === 1) {\n const charCode = mainKeyPart.charCodeAt(0);\n // If Shift is active and it's a letter, use the uppercase version for 'key'\n // This mimics more closely how keyboards behave.\n let keyChar = mainKeyPart;\n if (modifiers.shiftKey && mainKeyPart.match(/^[a-z]$/i)) {\n keyChar = mainKeyPart.toUpperCase();\n }\n\n return {\n key: keyChar,\n code: `Key${mainKeyPart.toUpperCase()}`, // 'a' -> KeyA, 'A' -> KeyA\n keyCode: charCode,\n charCode: charCode, // charCode is legacy, but some old systems might use it\n modifiers,\n };\n }\n\n console.error(`Unknown key: ${mainKeyPart} in string \"${keyString}\"`);\n return null; // Or handle as an error\n }\n\n /**\n * Simulates a single key press (keydown, (keypress), keyup) for a parsed key.\n * @param { {key: string, code: string, keyCode: number, charCode?: number, modifiers: object} } parsedKeyInfo\n * @param {Element} element - Target element.\n * @returns {{success: boolean, error?: string}}\n */\n function dispatchKeyEvents(parsedKeyInfo, element) {\n if (!parsedKeyInfo) return { success: false, error: 'Invalid key info provided for dispatch.' };\n\n const { key, code, keyCode, charCode, modifiers } = parsedKeyInfo;\n\n const eventOptions = {\n key: key,\n code: code,\n bubbles: true,\n cancelable: true,\n composed: true, // Important for shadow DOM\n view: window,\n ...modifiers, // ctrlKey, altKey, shiftKey, metaKey\n // keyCode/which are deprecated but often set for compatibility\n keyCode: keyCode || (key.length === 1 ? key.charCodeAt(0) : 0),\n which: keyCode || (key.length === 1 ? key.charCodeAt(0) : 0),\n };\n\n try {\n const kdRes = element.dispatchEvent(new KeyboardEvent('keydown', eventOptions));\n\n // keypress is deprecated, but simulate if it's a character key or Enter\n // Only dispatch if keydown was not cancelled and it's a character producing key\n if (kdRes && (key.length === 1 || key === 'Enter' || key === ' ')) {\n const keypressOptions = { ...eventOptions };\n if (charCode) keypressOptions.charCode = charCode;\n element.dispatchEvent(new KeyboardEvent('keypress', keypressOptions));\n }\n\n element.dispatchEvent(new KeyboardEvent('keyup', eventOptions));\n return { success: true };\n } catch (error) {\n console.error(`Error dispatching key events for \"${key}\":`, error);\n return {\n success: false,\n error: `Error dispatching key events for \"${key}\": ${error.message}`,\n };\n }\n }\n\n /**\n * Simulate keyboard events on an element or document\n * @param {string} keysSequenceString - String representation of key(s) (e.g., \"Enter\", \"Ctrl+C, A, B\")\n * @param {Element} targetElement - Element to dispatch events on (optional)\n * @param {number} delay - Delay between key sequences in milliseconds (optional)\n * @returns {Promise} - Result of the keyboard operation\n */\n async function simulateKeyboard(keysSequenceString, targetElement = null, delay = 0) {\n try {\n const element = targetElement || document.activeElement || document.body;\n\n if (element !== document.activeElement && typeof element.focus === 'function') {\n element.focus();\n await new Promise((resolve) => setTimeout(resolve, 50)); // Small delay for focus\n }\n\n const keyCombinations = keysSequenceString\n .split(',')\n .map((k) => k.trim())\n .filter((k) => k.length > 0);\n const operationResults = [];\n\n for (let i = 0; i < keyCombinations.length; i++) {\n const comboString = keyCombinations[i];\n const parsedKeyInfo = parseSingleKeyCombination(comboString);\n\n if (!parsedKeyInfo) {\n operationResults.push({\n keyCombination: comboString,\n success: false,\n error: `Invalid key string or combination: ${comboString}`,\n });\n continue; // Skip to next combination in sequence\n }\n\n const dispatchResult = dispatchKeyEvents(parsedKeyInfo, element);\n operationResults.push({\n keyCombination: comboString,\n ...dispatchResult,\n });\n\n if (dispatchResult.error) {\n // Optionally, decide if sequence should stop on first error\n // For now, we continue but log the error in results\n console.warn(\n `Failed to simulate key combination \"${comboString}\": ${dispatchResult.error}`,\n );\n }\n\n if (delay > 0 && i < keyCombinations.length - 1) {\n await new Promise((resolve) => setTimeout(resolve, delay));\n }\n }\n\n // Check if all individual operations were successful\n const overallSuccess = operationResults.every((r) => r.success);\n\n return {\n success: overallSuccess,\n message: overallSuccess\n ? `Keyboard events simulated successfully: ${keysSequenceString}`\n : `Some keyboard events failed for: ${keysSequenceString}`,\n results: operationResults, // Detailed results for each key combination\n targetElement: {\n tagName: element.tagName,\n id: element.id,\n className: element.className,\n type: element.type, // if applicable e.g. for input\n },\n };\n } catch (error) {\n console.error('Error in simulateKeyboard:', error);\n return {\n success: false,\n error: `Error simulating keyboard events: ${error.message}`,\n results: [],\n };\n }\n }\n\n // Listener for messages from the extension\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n if (request.action === 'simulateKeyboard') {\n let targetEl = null;\n if (request.selector) {\n targetEl = document.querySelector(request.selector);\n if (!targetEl) {\n sendResponse({\n success: false,\n error: `Element with selector \"${request.selector}\" not found`,\n results: [],\n });\n return true; // Keep channel open for async response\n }\n }\n\n simulateKeyboard(request.keys, targetEl, request.delay)\n .then(sendResponse)\n .catch((error) => {\n // This catch is for unexpected errors in simulateKeyboard promise chain itself\n console.error('Unexpected error in simulateKeyboard promise chain:', error);\n sendResponse({\n success: false,\n error: `Unexpected error during keyboard simulation: ${error.message}`,\n results: [],\n });\n });\n return true; // Indicates async response is expected\n } else if (request.action === 'chrome_keyboard_ping') {\n sendResponse({ status: 'pong', initialized: true }); // Respond that it's initialized\n return false; // Synchronous response\n }\n // Not our message, or no async response needed\n return false;\n });\n}\n" }, { "path": "app/chrome-extension/inject-scripts/network-helper.js", "content": "/* eslint-disable */\n/**\n * Network Capture Helper\n *\n * This script helps replay network requests with the original cookies and headers.\n */\n\n// Prevent duplicate initialization\nif (window.__NETWORK_CAPTURE_HELPER_INITIALIZED__) {\n // Already initialized, skip\n} else {\n window.__NETWORK_CAPTURE_HELPER_INITIALIZED__ = true;\n\n /**\n * Replay a network request\n * @param {string} url - The URL to send the request to\n * @param {string} method - The HTTP method to use\n * @param {Object} headers - The headers to include in the request\n * @param {any} body - The body of the request\n * @param {number} timeout - Timeout in milliseconds (default: 30000)\n * @returns {Promise} - The response data\n */\n async function replayNetworkRequest(\n url,\n method,\n headers,\n body,\n timeout = 30000,\n formDataDescriptor = null,\n ) {\n try {\n // Create fetch options\n const options = {\n method: method,\n headers: headers || {},\n credentials: 'include', // Include cookies\n mode: 'cors',\n cache: 'no-cache',\n };\n\n // Helper: convert base64 to Blob\n const base64ToBlob = (base64, contentType = 'application/octet-stream') => {\n try {\n const decodedString = atob(base64);\n const len = decodedString.length;\n const bytes = new Uint8Array(len);\n for (let i = 0; i < len; i++) bytes[i] = decodedString.charCodeAt(i);\n return new Blob([bytes], { type: contentType });\n } catch (e) {\n return new Blob([]);\n }\n };\n\n // Helper: request native to read filePath into base64\n const readFileBase64 = (path) =>\n new Promise((resolve) => {\n const requestId = `net-helper-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;\n const timeoutId = setTimeout(() => {\n cleanup();\n resolve(null);\n }, 30000);\n function onMessage(msg) {\n if (\n msg &&\n msg.type === 'file_operation_response' &&\n msg.responseToRequestId === requestId\n ) {\n cleanup();\n const p = msg.payload || {};\n if (p.success && p.base64Data)\n resolve({ base64: p.base64Data, fileName: p.fileName });\n else resolve(null);\n }\n }\n function cleanup() {\n clearTimeout(timeoutId);\n chrome.runtime.onMessage.removeListener(onMessage);\n }\n chrome.runtime.onMessage.addListener(onMessage);\n chrome.runtime\n .sendMessage({\n type: 'forward_to_native',\n message: {\n type: 'file_operation',\n requestId,\n payload: { action: 'readBase64File', filePath: path },\n },\n })\n .catch(() => {\n cleanup();\n resolve(null);\n });\n });\n\n // Build multipart/form-data if descriptor is provided\n if (method !== 'GET' && method !== 'HEAD' && formDataDescriptor) {\n const fd = new FormData();\n try {\n if (Array.isArray(formDataDescriptor)) {\n for (const item of formDataDescriptor) {\n if (!Array.isArray(item) || item.length < 2) continue;\n const name = String(item[0] || 'file');\n const spec = String(item[1] || '');\n const filenameHint = item[2] ? String(item[2]) : undefined;\n if (/^(https?:\\/\\/|url:)/i.test(spec)) {\n const url = spec.replace(/^url:/i, '');\n const resp = await fetch(url);\n const blob = await resp.blob();\n const fn =\n filenameHint || url.split('?')[0].split('#')[0].split('/').pop() || 'file';\n fd.append(name, blob, fn);\n } else if (/^base64:/i.test(spec)) {\n const b64 = spec.replace(/^base64:/i, '');\n const blob = base64ToBlob(b64);\n fd.append(name, blob, filenameHint || 'file');\n } else if (/^file:/i.test(spec)) {\n const p = spec.replace(/^file:/i, '');\n const res = await readFileBase64(p);\n if (res && res.base64) {\n const blob = base64ToBlob(res.base64);\n fd.append(name, blob, filenameHint || res.fileName || 'file');\n }\n } else {\n // treat as string field\n fd.append(name, spec);\n }\n }\n } else if (typeof formDataDescriptor === 'object') {\n const fds = formDataDescriptor;\n const fields = fds.fields || {};\n const files = Array.isArray(fds.files) ? fds.files : [];\n for (const [k, v] of Object.entries(fields)) fd.append(String(k), String(v));\n for (const file of files) {\n const name = String(file.name || 'file');\n if (file.fileUrl) {\n const resp = await fetch(String(file.fileUrl));\n const blob = await resp.blob();\n const fn =\n file.filename ||\n String(file.fileUrl).split('?')[0].split('#')[0].split('/').pop() ||\n 'file';\n fd.append(name, blob, fn);\n } else if (file.base64Data) {\n const blob = base64ToBlob(\n String(file.base64Data),\n String(file.contentType || 'application/octet-stream'),\n );\n fd.append(name, blob, file.filename || 'file');\n } else if (file.filePath) {\n const res = await readFileBase64(String(file.filePath));\n if (res && res.base64) {\n const blob = base64ToBlob(\n res.base64,\n String(file.contentType || 'application/octet-stream'),\n );\n fd.append(name, blob, file.filename || res.fileName || 'file');\n }\n }\n }\n }\n } catch (e) {\n console.warn('Failed to construct FormData:', e);\n }\n // Let browser set the correct multipart boundary\n try {\n if (options.headers) {\n delete options.headers['content-type'];\n delete options.headers['Content-Type'];\n }\n } catch {}\n options.body = fd;\n } else if (method !== 'GET' && method !== 'HEAD' && body !== undefined) {\n // Fallback to raw body\n options.body = body;\n }\n\n // 创建一个带超时的 fetch\n const fetchWithTimeout = async (url, options, timeout) => {\n const controller = new AbortController();\n const signal = controller.signal;\n\n // 设置超时\n const timeoutId = setTimeout(() => controller.abort(), timeout);\n\n try {\n const response = await fetch(url, { ...options, signal });\n clearTimeout(timeoutId);\n return response;\n } catch (error) {\n clearTimeout(timeoutId);\n throw error;\n }\n };\n\n // 发送带超时的请求\n const response = await fetchWithTimeout(url, options, timeout);\n\n // Process response\n const responseData = {\n status: response.status,\n statusText: response.statusText,\n headers: {},\n };\n\n // Get response headers\n response.headers.forEach((value, key) => {\n responseData.headers[key] = value;\n });\n\n // Try to get response body based on content type\n const contentType = response.headers.get('content-type') || '';\n\n try {\n if (contentType.includes('application/json')) {\n responseData.body = await response.json();\n } else if (\n contentType.includes('text/') ||\n contentType.includes('application/xml') ||\n contentType.includes('application/javascript')\n ) {\n responseData.body = await response.text();\n } else {\n // For binary data, just indicate it was received but not parsed\n responseData.body = '[Binary data not displayed]';\n }\n } catch (error) {\n responseData.body = `[Error parsing response body: ${error.message}]`;\n }\n\n return {\n success: true,\n response: responseData,\n };\n } catch (error) {\n console.error('Error replaying request:', error);\n return {\n success: false,\n error: `Error replaying request: ${error.message}`,\n };\n }\n }\n\n // Listen for messages from the extension\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n // Respond to ping message\n if (request.action === 'chrome_network_request_ping') {\n sendResponse({ status: 'pong' });\n return false; // Synchronous response\n } else if (request.action === 'sendPureNetworkRequest') {\n replayNetworkRequest(\n request.url,\n request.method,\n request.headers,\n request.body,\n request.timeout,\n request.formData,\n )\n .then(sendResponse)\n .catch((error) => {\n sendResponse({\n success: false,\n error: `Unexpected error: ${error.message}`,\n });\n });\n return true; // Indicates async response\n }\n });\n}\n" }, { "path": "app/chrome-extension/inject-scripts/props-agent.js", "content": "/* eslint-disable */\n// @ts-nocheck\n/**\n * Props Agent - MAIN World Script\n *\n * Runtime hacking agent for React/Vue Props editing.\n * Communicates with ISOLATED world via CustomEvent.\n *\n * Architecture:\n * - Transport: CustomEvent-based request/response\n * - Locator: Simplified ElementLocator resolution\n * - ReactAdapter: DevTools Hook detection/injection + overrideProps\n * - VueAdapter: __vueParentComponent + $forceUpdate\n * - Serializer: Safe Props serialization with type preservation\n * - Handlers: Request operation dispatch\n *\n * @module props-agent\n */\n(() => {\n 'use strict';\n\n // =============================================================================\n // Constants & Guards\n // =============================================================================\n\n const GLOBAL_KEY = '__MCP_WEB_EDITOR_PROPS_AGENT__';\n if (window[GLOBAL_KEY]) return;\n\n const PROTOCOL_VERSION = 1;\n const LOG_PREFIX = '[PropsAgent]';\n\n const EVENT_NAME = Object.freeze({\n REQUEST: 'web-editor-props:request',\n RESPONSE: 'web-editor-props:response',\n CLEANUP: 'web-editor-props:cleanup',\n });\n\n const REACT_HOOK_NAME = '__REACT_DEVTOOLS_GLOBAL_HOOK__';\n\n /** @type {'READY' | 'HOOK_PRESENT_NO_RENDERERS' | 'RENDERERS_NO_EDITING' | 'HOOK_MISSING'} */\n const HOOK_STATUS = Object.freeze({\n READY: 'READY',\n HOOK_PRESENT_NO_RENDERERS: 'HOOK_PRESENT_NO_RENDERERS',\n RENDERERS_NO_EDITING: 'RENDERERS_NO_EDITING',\n HOOK_MISSING: 'HOOK_MISSING',\n });\n\n const SERIALIZE_LIMITS = Object.freeze({\n maxDepth: 4,\n maxEntries: 100,\n maxArrayLength: 50,\n maxStringLength: 1500,\n });\n\n // =============================================================================\n // Utilities\n // =============================================================================\n\n function isObject(value) {\n return value !== null && typeof value === 'object';\n }\n\n function safeString(value) {\n try {\n if (typeof value === 'string') return value;\n if (value === null || value === undefined) return '';\n return String(value);\n } catch {\n return '';\n }\n }\n\n function logWarn(...args) {\n try {\n console.warn(LOG_PREFIX, ...args);\n } catch {\n // Silently ignore\n }\n }\n\n // =============================================================================\n // Transport Layer\n // =============================================================================\n\n const Transport = {\n dispatchResponse(detail) {\n try {\n window.dispatchEvent(new CustomEvent(EVENT_NAME.RESPONSE, { detail }));\n } catch (err) {\n logWarn('Failed to dispatch response:', err);\n }\n },\n\n createResponse(requestId, success, data, error) {\n const response = {\n v: PROTOCOL_VERSION,\n requestId,\n success: Boolean(success),\n };\n if (data !== undefined) response.data = data;\n if (error !== undefined) response.error = safeString(error);\n return response;\n },\n\n normalizeRequest(detail) {\n if (!isObject(detail)) return null;\n if (detail.v !== PROTOCOL_VERSION) return null;\n\n const requestId = typeof detail.requestId === 'string' ? detail.requestId : '';\n const op = typeof detail.op === 'string' ? detail.op : '';\n if (!requestId || !op) return null;\n\n return {\n v: PROTOCOL_VERSION,\n requestId,\n op,\n locator: detail.locator,\n payload: detail.payload,\n };\n },\n };\n\n // =============================================================================\n // Locator - Element Resolution\n // =============================================================================\n\n const Locator = {\n safeQuerySelector(root, selector) {\n try {\n if (!root || typeof selector !== 'string' || !selector.trim()) return null;\n return root.querySelector(selector);\n } catch {\n return null;\n }\n },\n\n safeQuerySelectorAll(root, selector) {\n try {\n if (!root || typeof selector !== 'string' || !selector.trim()) return [];\n return Array.from(root.querySelectorAll(selector));\n } catch {\n return [];\n }\n },\n\n isSelectorUnique(root, selector) {\n return this.safeQuerySelectorAll(root, selector).length === 1;\n },\n\n computeFingerprint(element) {\n try {\n const parts = [];\n const tag = element?.tagName ? String(element.tagName).toLowerCase() : 'unknown';\n parts.push(tag);\n const id = element?.id ? String(element.id).trim() : '';\n if (id) parts.push(`id=${id}`);\n return parts.join('|');\n } catch {\n return '';\n }\n },\n\n verifyFingerprint(element, fingerprint) {\n try {\n const current = this.computeFingerprint(element);\n const storedParts = safeString(fingerprint).split('|');\n const currentParts = current.split('|');\n\n // Tag must match\n if (storedParts[0] !== currentParts[0]) return false;\n\n // If stored has id, current must have same id\n const storedId = storedParts.find((p) => p.startsWith('id='));\n const currentId = currentParts.find((p) => p.startsWith('id='));\n if (storedId && storedId !== currentId) return false;\n\n return true;\n } catch {\n return false;\n }\n },\n\n normalizeStringArray(value) {\n if (!Array.isArray(value)) return [];\n return value.map((v) => safeString(v).trim()).filter(Boolean);\n },\n\n /**\n * Resolve ElementLocator to DOM element\n * Simplified version for MAIN world (no iframe support yet)\n */\n locate(locator, rootDocument = document) {\n try {\n if (!isObject(locator)) return null;\n\n let queryRoot = rootDocument;\n\n // Traverse Shadow DOM host chain\n const shadowHostChain = this.normalizeStringArray(locator.shadowHostChain);\n for (const hostSelector of shadowHostChain) {\n if (!this.isSelectorUnique(queryRoot, hostSelector)) return null;\n const host = this.safeQuerySelector(queryRoot, hostSelector);\n if (!host) return null;\n const shadowRoot = host.shadowRoot;\n if (!shadowRoot) return null;\n queryRoot = shadowRoot;\n }\n\n // Try each selector candidate\n const selectors = this.normalizeStringArray(locator.selectors);\n for (const selector of selectors) {\n if (!this.isSelectorUnique(queryRoot, selector)) continue;\n const element = this.safeQuerySelector(queryRoot, selector);\n if (!element) continue;\n\n // Verify fingerprint if provided\n const fp = safeString(locator.fingerprint);\n if (fp && !this.verifyFingerprint(element, fp)) continue;\n\n return element;\n }\n } catch {\n // Best-effort\n }\n return null;\n },\n };\n\n // =============================================================================\n // React Adapter\n // =============================================================================\n\n const ReactAdapter = {\n /** Store original values for reset (fiber -> { renderer, originals: Map }) */\n overrideStore: typeof WeakMap === 'function' ? new WeakMap() : null,\n\n /** Flag to avoid repeated hook installation attempts */\n hookInstallAttempted: false,\n\n getHook() {\n try {\n return window[REACT_HOOK_NAME] || null;\n } catch {\n return null;\n }\n },\n\n /**\n * Install minimal DevTools hook if missing.\n * Note: This only helps if React hasn't initialized yet.\n * Only attempts once per session to avoid repeated pollution.\n */\n installMinimalHook() {\n // Only attempt once per session\n if (this.hookInstallAttempted) {\n return { installed: false, hook: this.getHook(), skipped: true };\n }\n this.hookInstallAttempted = true;\n try {\n const existing = window[REACT_HOOK_NAME];\n if (existing && typeof existing.inject === 'function') {\n return { installed: false, hook: existing };\n }\n\n const listeners = Object.create(null);\n\n const hook = {\n renderers: new Map(),\n supportsFiber: true,\n\n inject(renderer) {\n try {\n const id = this.renderers.size + 1;\n this.renderers.set(id, renderer);\n this.emit('renderer', { id, renderer });\n return id;\n } catch {\n return 0;\n }\n },\n\n // Required lifecycle callbacks (no-ops)\n onCommitFiberRoot() {},\n onCommitFiberUnmount() {},\n onPostCommitFiberRoot() {},\n setStrictMode() {},\n checkDCE() {},\n\n // Event emitter\n on(event, fn) {\n if (typeof event !== 'string' || typeof fn !== 'function') return;\n if (!listeners[event]) listeners[event] = new Set();\n listeners[event].add(fn);\n },\n\n off(event, fn) {\n if (typeof event !== 'string' || typeof fn !== 'function') return;\n listeners[event]?.delete(fn);\n },\n\n emit(event, data) {\n const set = listeners[event];\n if (!set) return;\n for (const fn of Array.from(set)) {\n try {\n fn(data);\n } catch {\n // Listener errors must not break the hook\n }\n }\n },\n\n sub(event, fn) {\n this.on(event, fn);\n return () => this.off(event, fn);\n },\n };\n\n window[REACT_HOOK_NAME] = hook;\n return { installed: true, hook };\n } catch (err) {\n return { installed: false, hook: null, error: err };\n }\n },\n\n /**\n * Normalize hook.renderers to array format\n */\n normalizeRenderers(hook) {\n const result = [];\n if (!hook) return result;\n\n try {\n const renderers = hook.renderers;\n if (renderers instanceof Map) {\n for (const [id, renderer] of renderers.entries()) {\n result.push({ id, renderer });\n }\n } else if (renderers && typeof renderers === 'object') {\n for (const [id, renderer] of Object.entries(renderers)) {\n result.push({ id, renderer });\n }\n }\n } catch {\n // Best-effort\n }\n return result;\n },\n\n /**\n * Detect Hook status (4 states)\n */\n detectStatus() {\n const hook = this.getHook();\n\n if (!hook || typeof hook.inject !== 'function') {\n return {\n hookStatus: HOOK_STATUS.HOOK_MISSING,\n hook: null,\n renderers: [],\n editableRenderers: [],\n };\n }\n\n const renderers = this.normalizeRenderers(hook);\n if (!renderers.length) {\n return {\n hookStatus: HOOK_STATUS.HOOK_PRESENT_NO_RENDERERS,\n hook,\n renderers,\n editableRenderers: [],\n };\n }\n\n const editableRenderers = renderers.filter(\n (r) => r?.renderer && typeof r.renderer.overrideProps === 'function',\n );\n\n if (editableRenderers.length) {\n return {\n hookStatus: HOOK_STATUS.READY,\n hook,\n renderers,\n editableRenderers,\n };\n }\n\n return {\n hookStatus: HOOK_STATUS.RENDERERS_NO_EDITING,\n hook,\n renderers,\n editableRenderers: [],\n };\n },\n\n /**\n * Get React version from renderer or global.\n * Prioritizes specific renderer version for multi-renderer scenarios.\n *\n * @param {object} hookInfo - Result from detectStatus()\n * @param {object} [specificRenderer] - Specific renderer to prefer (from resolveFiberWithRenderer)\n * @returns {string | undefined}\n */\n getVersion(hookInfo, specificRenderer) {\n try {\n // Priority 1: Specific renderer version (for multi-renderer scenarios)\n if (specificRenderer) {\n const version = specificRenderer.version;\n if (typeof version === 'string' && version.trim()) {\n return version.trim();\n }\n }\n\n // Priority 2: Any renderer with version\n const renderers = hookInfo?.renderers || [];\n for (const item of renderers) {\n const version = item?.renderer?.version;\n if (typeof version === 'string' && version.trim()) {\n return version.trim();\n }\n }\n\n // Priority 3: Global React object (if exposed)\n if (typeof window !== 'undefined' && window.React?.version) {\n return String(window.React.version).trim();\n }\n } catch {\n // Best-effort\n }\n return undefined;\n },\n\n /**\n * Find React fiber from DOM node\n */\n findFiberFromDOM(node) {\n try {\n if (!node || typeof node !== 'object') return null;\n const keys = Object.keys(node);\n for (const key of keys) {\n if (key.startsWith('__reactFiber$') || key.startsWith('__reactInternalInstance$')) {\n return node[key];\n }\n }\n } catch {\n // Best-effort\n }\n return null;\n },\n\n /**\n * Check if fiber tag is a component (Function/Class/ForwardRef etc.)\n */\n isComponentTag(tag) {\n // 0=FunctionComponent, 1=ClassComponent, 2=IndeterminateComponent,\n // 11=ForwardRef, 14=MemoComponent, 15=SimpleMemoComponent\n return tag === 0 || tag === 1 || tag === 2 || tag === 11 || tag === 14 || tag === 15;\n },\n\n /**\n * Find nearest component fiber by walking up the fiber tree\n */\n findNearestComponentFiber(fiber) {\n try {\n let current = fiber;\n for (let i = 0; i < 60 && current; i++) {\n if (this.isComponentTag(current.tag)) return current;\n current = current.return;\n }\n } catch {\n // Best-effort\n }\n return null;\n },\n\n /**\n * Get component display name from fiber\n */\n getComponentName(fiber) {\n try {\n const type = fiber?.type || fiber?.elementType;\n if (!type) return 'Anonymous';\n if (typeof type === 'string') return type;\n return safeString(type.displayName || type.name) || 'Anonymous';\n } catch {\n return 'Anonymous';\n }\n },\n\n /**\n * Extract debug source from React Fiber.\n * Walks up the fiber tree checking _debugSource and _debugOwner._debugSource.\n *\n * @param {object} fiber - React Fiber node\n * @returns {{ file: string, line?: number, column?: number, componentName?: string } | null}\n */\n getDebugSource(fiber) {\n try {\n let current = fiber;\n for (let i = 0; i < 40 && current; i++) {\n if (!isObject(current)) break;\n\n // Try direct _debugSource first\n const src = isObject(current._debugSource) ? current._debugSource : null;\n if (src) {\n const file = safeString(src.fileName).trim();\n if (file) {\n return this.buildDebugSourceResult(file, src.lineNumber, src.columnNumber, current);\n }\n }\n\n // Fallback to _debugOwner._debugSource\n const owner = isObject(current._debugOwner) ? current._debugOwner : null;\n const ownerSrc = owner && isObject(owner._debugSource) ? owner._debugSource : null;\n if (ownerSrc) {\n const ownerFile = safeString(ownerSrc.fileName).trim();\n if (ownerFile) {\n return this.buildDebugSourceResult(\n ownerFile,\n ownerSrc.lineNumber,\n ownerSrc.columnNumber,\n owner,\n );\n }\n }\n\n current = current.return;\n }\n } catch {\n // Best-effort extraction\n }\n return null;\n },\n\n /**\n * Build debug source result with validated line/column values.\n * @private\n */\n buildDebugSourceResult(file, lineNumber, columnNumber, fiberForName) {\n const line = Number(lineNumber);\n const column = Number(columnNumber);\n return {\n file,\n line: Number.isFinite(line) && line > 0 ? line : undefined,\n column: Number.isFinite(column) && column > 0 ? column : undefined,\n componentName: this.getComponentName(fiberForName),\n };\n },\n\n /**\n * Resolve fiber using renderer.findFiberByHostInstance when available\n */\n resolveFiberWithRenderer(element, hookInfo) {\n // Prefer renderer API (returns renderer-owned fiber suitable for overrideProps)\n try {\n const renderers = hookInfo?.renderers || [];\n for (const item of renderers) {\n const renderer = item?.renderer;\n if (!renderer || typeof renderer.findFiberByHostInstance !== 'function') continue;\n try {\n const fiber = renderer.findFiberByHostInstance(element);\n if (fiber) return { fiber, renderer };\n } catch {\n // Try next renderer\n }\n }\n } catch {\n // Best-effort\n }\n\n // Fallback: DOM-attached fiber reference\n const fallback = this.findFiberFromDOM(element);\n return { fiber: fallback, renderer: null };\n },\n\n /**\n * Record original value for reset\n */\n recordOriginal(fiber, renderer, path, existed, value) {\n if (!this.overrideStore || !fiber) return;\n\n try {\n const key = JSON.stringify(path);\n let store = this.overrideStore.get(fiber);\n\n if (!store) {\n store = { renderer: renderer || null, originals: new Map() };\n this.overrideStore.set(fiber, store);\n\n // Also store by alternate to improve reset hit rate\n if (fiber.alternate && typeof fiber.alternate === 'object') {\n this.overrideStore.set(fiber.alternate, store);\n }\n }\n\n if (!store.originals.has(key)) {\n store.originals.set(key, { path, existed, value });\n }\n\n if (!store.renderer && renderer) {\n store.renderer = renderer;\n }\n } catch {\n // Best-effort\n }\n },\n\n /**\n * Get stored originals for fiber\n */\n getOriginals(fiber) {\n if (!this.overrideStore || !fiber) return null;\n return this.overrideStore.get(fiber) || null;\n },\n\n /**\n * Clear stored originals for fiber\n */\n clearOriginals(fiber) {\n if (!this.overrideStore || !fiber) return;\n const store = this.overrideStore.get(fiber);\n if (store?.originals) store.originals.clear();\n },\n };\n\n // =============================================================================\n // Vue Adapter\n // =============================================================================\n\n const VueAdapter = {\n /** Store original values for reset (instance -> Map) */\n overrideStore: typeof WeakMap === 'function' ? new WeakMap() : null,\n\n /**\n * Find Vue 3 component instance from DOM node\n */\n findInstanceFromDOM(node) {\n try {\n if (!node || typeof node !== 'object') return null;\n return node.__vueParentComponent || null;\n } catch {\n return null;\n }\n },\n\n /**\n * Get component name from instance\n */\n getComponentName(instance) {\n try {\n const type = instance?.type;\n return safeString(type?.name || type?.__name) || 'Anonymous';\n } catch {\n return 'Anonymous';\n }\n },\n\n /**\n * Check if instance appears to be from dev build\n */\n isDevBuild(instance) {\n try {\n const type = instance?.type;\n const file = type?.__file;\n return typeof file === 'string' && !!file.trim();\n } catch {\n return false;\n }\n },\n\n /**\n * Parse Vue inspector location attribute value.\n * Format: \"src/components/Foo.vue:23:7\" or \"C:\\path\\file.vue:10:5\" (Windows)\n *\n * Uses trailing regex to safely handle Windows paths with drive letters.\n *\n * @param {string} value - The data-v-inspector attribute value\n * @returns {{ file: string, line?: number, column?: number } | null}\n */\n parseVInspector(value) {\n if (typeof value !== 'string') return null;\n const raw = value.trim();\n if (!raw) return null;\n\n // Match only trailing :line or :line:column to avoid Windows drive letter issues\n const match = raw.match(/:([\\d]+)(?::([\\d]+))?$/);\n if (!match) {\n // No line info, return file only\n return { file: raw };\n }\n\n const file = raw.slice(0, match.index).trim();\n if (!file) return null;\n\n const line = Number.parseInt(match[1], 10);\n const column = match[2] ? Number.parseInt(match[2], 10) : undefined;\n\n return {\n file,\n line: Number.isFinite(line) && line > 0 ? line : undefined,\n column: Number.isFinite(column) && column > 0 ? column : undefined,\n };\n },\n\n /**\n * Walk up DOM tree to find data-v-inspector attribute.\n * This attribute is injected by @vitejs/plugin-vue-inspector.\n *\n * @param {Element} element - Starting DOM element\n * @param {number} [maxDepth=15] - Maximum depth to traverse\n * @returns {{ file: string, line?: number, column?: number } | null}\n */\n findInspectorLocation(element, maxDepth = 15) {\n try {\n let node = element;\n for (let depth = 0; depth < maxDepth && node; depth++) {\n if (typeof node.getAttribute === 'function') {\n const attr = node.getAttribute('data-v-inspector');\n if (attr) {\n const parsed = this.parseVInspector(attr);\n if (parsed?.file) return parsed;\n }\n }\n node = node.parentElement;\n }\n } catch {\n // Best-effort extraction\n }\n return null;\n },\n\n /**\n * Get Vue component debug source.\n * Priority: data-v-inspector (has line/column) > type.__file (file only)\n *\n * @param {object} instance - Vue component instance\n * @param {Element} targetElement - DOM element for inspector lookup\n * @returns {{ file: string, line?: number, column?: number, componentName?: string } | null}\n */\n getDebugSource(instance, targetElement) {\n try {\n // Priority 1: data-v-inspector attribute (has precise line/column)\n const inspector = this.findInspectorLocation(targetElement);\n if (inspector?.file) {\n return {\n file: inspector.file,\n line: inspector.line,\n column: inspector.column,\n componentName: this.getComponentName(instance),\n };\n }\n\n // Priority 2: type.__file (file only, no line/column)\n const typeFile = instance?.type?.__file;\n if (typeof typeFile === 'string') {\n const file = typeFile.trim();\n if (file) {\n return {\n file,\n componentName: this.getComponentName(instance),\n };\n }\n }\n } catch {\n // Best-effort extraction\n }\n return null;\n },\n\n /**\n * Get Vue 3 version from instance.\n * Note: This adapter only supports Vue 3 (via __vueParentComponent).\n *\n * @param {object} instance - Vue 3 component instance\n * @returns {string | undefined}\n */\n getVersion(instance) {\n try {\n // Vue 3: Get version from app context\n const appVersion = instance?.appContext?.app?.version;\n if (typeof appVersion === 'string' && appVersion.trim()) {\n return appVersion.trim();\n }\n } catch {\n // Best-effort\n }\n return undefined;\n },\n\n /**\n * Get writable props container (vnode.props or instance.props)\n * @deprecated Use getWriteContainers for better targeting\n */\n getPropsContainer(instance) {\n try {\n const vnodeProps = instance?.vnode?.props;\n if (vnodeProps && typeof vnodeProps === 'object') return vnodeProps;\n } catch {\n // ignore\n }\n\n try {\n const props = instance?.props;\n if (props && typeof props === 'object') return props;\n } catch {\n // ignore\n }\n\n return null;\n },\n\n /**\n * Check if a key is a declared prop (vs fallthrough attr).\n * Uses component type definition and runtime props object.\n */\n isDeclaredProp(instance, key) {\n // Check type.props definition first\n try {\n const opts = instance?.type?.props;\n if (Array.isArray(opts)) return opts.includes(key);\n if (isObject(opts)) return Object.prototype.hasOwnProperty.call(opts, key);\n } catch {\n // ignore\n }\n\n // Fallback: if key exists in instance.props, treat as declared\n try {\n const props = instance?.props;\n if (isObject(props)) {\n return Object.prototype.hasOwnProperty.call(props, key);\n }\n } catch {\n // ignore\n }\n\n return false;\n },\n\n /**\n * Get write container candidates for a prop kind ('props' | 'attrs').\n * Returns array of containers to try in order.\n */\n getWriteContainers(instance, kind) {\n const containers = [];\n const seen = typeof Set === 'function' ? new Set() : null;\n\n const addContainer = (obj) => {\n if (!obj || typeof obj !== 'object') return;\n if (seen) {\n if (seen.has(obj)) return;\n seen.add(obj);\n }\n containers.push(obj);\n };\n\n if (!instance || typeof instance !== 'object') return containers;\n\n // Primary container based on kind\n if (kind === 'attrs') {\n try {\n addContainer(instance.attrs);\n } catch {\n // ignore\n }\n } else {\n try {\n addContainer(instance.props);\n } catch {\n // ignore\n }\n }\n\n // Fallback: vnode.props (often more writable)\n try {\n addContainer(instance?.vnode?.props);\n } catch {\n // ignore\n }\n\n return containers;\n },\n\n /**\n * Get logical root for reading a prop kind.\n */\n getReadRoot(instance, kind) {\n if (kind === 'attrs') {\n try {\n if (isObject(instance?.attrs)) return instance.attrs;\n } catch {\n // ignore\n }\n } else {\n try {\n if (isObject(instance?.props)) return instance.props;\n } catch {\n // ignore\n }\n }\n\n // Fallback\n try {\n if (isObject(instance?.vnode?.props)) return instance.vnode.props;\n } catch {\n // ignore\n }\n\n return null;\n },\n\n /**\n * Get raw vnode props object\n */\n getVNodeProps(instance) {\n try {\n const p = instance?.vnode?.props;\n return isObject(p) ? p : null;\n } catch {\n return null;\n }\n },\n\n /**\n * Apply new raw props via instance.next + instance.update() so Vue runs its internal\n * updateProps/updateSlots pipeline (closest to a parent-driven props update).\n * This is the correct way to trigger Vue3 props update.\n */\n applyNextProps(instance, nextRawProps) {\n try {\n const vnode = instance?.vnode;\n if (!vnode || typeof vnode !== 'object') return false;\n\n // Vue3 PatchFlags.FULL_PROPS = 16\n const FULL_PROPS = 16;\n const prevFlag = typeof vnode.patchFlag === 'number' ? vnode.patchFlag : 0;\n const patchFlag = prevFlag >= 0 ? prevFlag | FULL_PROPS : FULL_PROPS;\n\n // Create next vnode with updated props\n const nextVNode = Object.assign({}, vnode, {\n props: nextRawProps,\n patchFlag,\n dynamicProps: null,\n component: instance,\n });\n\n instance.next = nextVNode;\n\n // Trigger update\n if (instance && typeof instance.update === 'function') {\n instance.update();\n return true;\n }\n\n const proxy = instance?.proxy;\n if (proxy && typeof proxy.$forceUpdate === 'function') {\n proxy.$forceUpdate();\n return true;\n }\n } catch {\n // ignore\n }\n return false;\n },\n\n /**\n * Trigger Vue re-render (fallback, may not work for props changes)\n */\n forceUpdate(instance) {\n try {\n const proxy = instance?.proxy;\n if (proxy && typeof proxy.$forceUpdate === 'function') {\n proxy.$forceUpdate();\n return true;\n }\n } catch {\n // ignore\n }\n\n try {\n if (instance && typeof instance.update === 'function') {\n instance.update();\n return true;\n }\n } catch {\n // ignore\n }\n\n return false;\n },\n\n /**\n * Immutable update helper for nested props\n */\n copyWithSet(root, path, value) {\n if (!Array.isArray(path) || path.length === 0) return value;\n\n const seg = path[0];\n const rest = path.slice(1);\n const isIndex = typeof seg === 'number';\n\n let base = root;\n if (\n base === null ||\n base === undefined ||\n (typeof base !== 'object' && !Array.isArray(base))\n ) {\n base = isIndex ? [] : {};\n }\n\n const clone = Array.isArray(base) ? base.slice() : { ...base };\n clone[seg] = this.copyWithSet(clone[seg], rest, value);\n return clone;\n },\n\n /**\n * Record original value for reset\n * @param {object} instance - Vue component instance\n * @param {Array} path - Prop path\n * @param {boolean} existed - Whether the prop existed before\n * @param {*} value - Original value\n * @param {'props'|'attrs'} [targetKind] - Target container kind (for accurate reset)\n */\n recordOriginal(instance, path, existed, value, targetKind) {\n if (!this.overrideStore || !instance) return;\n\n try {\n const key = JSON.stringify(path);\n let store = this.overrideStore.get(instance);\n\n if (!store) {\n store = new Map();\n this.overrideStore.set(instance, store);\n }\n\n if (!store.has(key)) {\n store.set(key, { path, existed, value, targetKind });\n }\n } catch {\n // Best-effort\n }\n },\n\n /**\n * Get stored originals for instance\n */\n getOriginals(instance) {\n if (!this.overrideStore || !instance) return null;\n return this.overrideStore.get(instance) || null;\n },\n\n /**\n * Clear stored originals for instance\n */\n clearOriginals(instance) {\n if (!this.overrideStore || !instance) return;\n const store = this.overrideStore.get(instance);\n if (store) store.clear();\n },\n };\n\n // =============================================================================\n // Framework Detector\n // =============================================================================\n\n const FrameworkDetector = {\n /**\n * Detect framework for element (walks up DOM tree)\n */\n detect(element, maxDepth = 15) {\n let node = element;\n\n for (let depth = 0; depth < maxDepth && node; depth++) {\n // React first (more common)\n const fiber = ReactAdapter.findFiberFromDOM(node);\n if (fiber) {\n return { framework: 'react', node, data: fiber };\n }\n\n // Vue 3\n const vue = VueAdapter.findInstanceFromDOM(node);\n if (vue) {\n return { framework: 'vue', node, data: vue };\n }\n\n node = node.parentElement;\n }\n\n return { framework: 'unknown', node: null, data: null };\n },\n };\n\n // =============================================================================\n // Serializer\n // =============================================================================\n\n const Serializer = {\n /**\n * Check if value is a React element\n */\n isReactElement(value) {\n try {\n if (!value || typeof value !== 'object') return false;\n const t = value.$$typeof;\n if (!t) return false;\n\n if (typeof Symbol === 'function' && Symbol.for) {\n return (\n t === Symbol.for('react.element') ||\n t === Symbol.for('react.transitional.element') ||\n t === Symbol.for('react.portal')\n );\n }\n\n // Fallback heuristic\n return !!(value.type && value.props);\n } catch {\n return false;\n }\n },\n\n /**\n * Get React element display string\n */\n reactElementDisplay(value) {\n try {\n const type = value?.type;\n if (typeof type === 'string') return `<${type} />`;\n if (typeof type === 'function') {\n return `<${safeString(type.displayName || type.name) || 'Anonymous'} />`;\n }\n if (type && typeof type === 'object') {\n const name = safeString(type.displayName || type.name) || 'Anonymous';\n return `<${name} />`;\n }\n } catch {\n // ignore\n }\n return '';\n },\n\n /**\n * Check if value is an editable primitive\n */\n isEditablePrimitive(value) {\n if (value === null || value === undefined) return true;\n const t = typeof value;\n if (t === 'string' || t === 'boolean') return true;\n if (t === 'number') return Number.isFinite(value);\n return false;\n },\n\n /**\n * Create serialization context for cycle detection\n */\n createContext() {\n return {\n seen: typeof WeakMap === 'function' ? new WeakMap() : null,\n nextId: 1,\n };\n },\n\n /**\n * Serialize a value with type information\n */\n serializeValue(value, ctx, depth = 0) {\n try {\n if (value === null) return { kind: 'null' };\n if (value === undefined) return { kind: 'undefined' };\n\n const t = typeof value;\n\n if (t === 'string') {\n if (value.length > SERIALIZE_LIMITS.maxStringLength) {\n return {\n kind: 'string',\n value: value.slice(0, SERIALIZE_LIMITS.maxStringLength),\n truncated: true,\n length: value.length,\n };\n }\n return { kind: 'string', value };\n }\n\n if (t === 'number') {\n if (Number.isFinite(value)) return { kind: 'number', value };\n if (Number.isNaN(value)) return { kind: 'number', special: 'NaN' };\n return { kind: 'number', special: value > 0 ? 'Infinity' : '-Infinity' };\n }\n\n if (t === 'boolean') return { kind: 'boolean', value };\n if (t === 'bigint') return { kind: 'bigint', value: value.toString() };\n if (t === 'symbol') return { kind: 'symbol', description: safeString(value) };\n if (t === 'function')\n return { kind: 'function', name: safeString(value.name) || undefined };\n\n // Object types\n if (this.isReactElement(value)) {\n return { kind: 'react_element', display: this.reactElementDisplay(value) };\n }\n\n if (typeof Element !== 'undefined' && value instanceof Element) {\n return {\n kind: 'dom_element',\n tagName: safeString(value.tagName).toLowerCase(),\n id: safeString(value.id) || undefined,\n className: safeString(value.className) || undefined,\n };\n }\n\n if (value instanceof Date) {\n let iso = '';\n try {\n iso = value.toISOString();\n } catch {\n iso = safeString(value);\n }\n return { kind: 'date', value: iso };\n }\n\n if (value instanceof RegExp) {\n return { kind: 'regexp', source: value.source, flags: value.flags };\n }\n\n if (value instanceof Error) {\n return {\n kind: 'error',\n name: safeString(value.name) || 'Error',\n message: safeString(value.message),\n };\n }\n\n // Depth limit\n if (depth >= SERIALIZE_LIMITS.maxDepth) {\n return {\n kind: 'max_depth',\n type: Object.prototype.toString.call(value),\n preview: safeString(value),\n };\n }\n\n // Circular reference detection\n if (ctx?.seen) {\n const existingId = ctx.seen.get(value);\n if (existingId) return { kind: 'circular', refId: existingId };\n ctx.seen.set(value, ctx.nextId++);\n }\n\n // Array\n if (Array.isArray(value)) {\n const max = Math.min(value.length, SERIALIZE_LIMITS.maxArrayLength);\n const items = [];\n for (let i = 0; i < max; i++) {\n items.push(this.serializeValue(value[i], ctx, depth + 1));\n }\n return {\n kind: 'array',\n length: value.length,\n truncated: value.length > max,\n items,\n };\n }\n\n // Map\n if (value instanceof Map) {\n const entries = [];\n let count = 0;\n for (const [k, v] of value.entries()) {\n if (count >= SERIALIZE_LIMITS.maxEntries) break;\n entries.push({\n key: this.serializeValue(k, ctx, depth + 1),\n value: this.serializeValue(v, ctx, depth + 1),\n });\n count++;\n }\n return {\n kind: 'map',\n size: value.size,\n truncated: value.size > count,\n entries,\n };\n }\n\n // Set\n if (value instanceof Set) {\n const items = [];\n let count = 0;\n for (const v of value.values()) {\n if (count >= SERIALIZE_LIMITS.maxEntries) break;\n items.push(this.serializeValue(v, ctx, depth + 1));\n count++;\n }\n return {\n kind: 'set',\n size: value.size,\n truncated: value.size > count,\n items,\n };\n }\n\n // Plain object\n const constructorName = value?.constructor?.name;\n const name = typeof constructorName === 'string' ? constructorName : undefined;\n const keys = Object.keys(value);\n const limitedKeys = keys.slice(0, SERIALIZE_LIMITS.maxEntries);\n const entries = limitedKeys.map((k) => ({\n key: k,\n value: this.serializeValue(value[k], ctx, depth + 1),\n }));\n\n return {\n kind: 'object',\n name: name !== 'Object' ? name : undefined,\n truncated: keys.length > limitedKeys.length,\n entries,\n };\n } catch (err) {\n return { kind: 'unknown', type: typeof value, preview: safeString(err) };\n }\n },\n\n /**\n * Serialize props object to structured format\n * @param {object} props - Props object to serialize\n * @param {Record>} [enumValuesByKey] - Optional enum values by prop key\n */\n serializeProps(props, enumValuesByKey) {\n const ctx = this.createContext();\n const entries = [];\n const enumMap = isObject(enumValuesByKey) ? enumValuesByKey : null;\n\n if (!props || (typeof props !== 'object' && typeof props !== 'function')) {\n return { kind: 'props', entries: [] };\n }\n\n const keys = Object.keys(props);\n const limited = keys.slice(0, SERIALIZE_LIMITS.maxEntries);\n\n for (const key of limited) {\n let raw;\n try {\n raw = props[key];\n } catch {\n raw = undefined;\n }\n\n const entry = {\n key,\n editable: this.isEditablePrimitive(raw),\n value: this.serializeValue(raw, ctx, 0),\n };\n\n // Attach enum values if available\n const enumValues = enumMap ? enumMap[key] : null;\n if (Array.isArray(enumValues) && enumValues.length > 0) {\n entry.enumValues = enumValues.slice(0, EnumIntrospection.MAX_ENUM_VALUES);\n }\n\n entries.push(entry);\n }\n\n const result = { kind: 'props', entries };\n if (keys.length > limited.length) result.truncated = true;\n return result;\n },\n };\n\n // =============================================================================\n // Enum Introspection (Best-effort)\n // =============================================================================\n\n /**\n * Best-effort enum value extraction from React/Vue runtime metadata.\n *\n * React: Relies on __docgenInfo (Storybook/react-docgen output)\n * Vue: Relies on explicit values/validator.values in props options\n */\n const EnumIntrospection = {\n MAX_ENUM_VALUES: 50,\n\n /**\n * Normalize a raw enum value to primitive\n */\n normalizeEnumValue(raw) {\n if (raw === null || raw === undefined) return null;\n\n if (typeof raw === 'boolean') return raw;\n if (typeof raw === 'number') return Number.isFinite(raw) ? raw : null;\n\n const s = safeString(raw).trim();\n if (!s) return null;\n\n // Strip surrounding quotes: \"'primary'\" -> \"primary\"\n const m = s.match(/^(['\"])(.*)\\1$/);\n const unquoted = m ? m[2] : s;\n\n if (unquoted === 'true') return true;\n if (unquoted === 'false') return false;\n\n if (/^-?(?:\\d+|\\d*\\.\\d+)$/.test(unquoted)) {\n const n = Number(unquoted);\n if (Number.isFinite(n)) return n;\n }\n\n return unquoted;\n },\n\n /**\n * Normalize array of enum values, deduplicate\n */\n normalizeEnumList(list) {\n if (!Array.isArray(list)) return [];\n const out = [];\n const seen = new Set();\n\n for (const item of list) {\n const v = this.normalizeEnumValue(item);\n if (v === null) continue;\n const key =\n typeof v === 'string' ? `s:${v}` : typeof v === 'number' ? `n:${v}` : `b:${v ? 1 : 0}`;\n if (seen.has(key)) continue;\n seen.add(key);\n out.push(v);\n if (out.length >= this.MAX_ENUM_VALUES) break;\n }\n\n return out;\n },\n\n /**\n * Extract enum values from React docgen prop info\n * (e.g., from Storybook's __docgenInfo)\n */\n extractDocgenEnumValues(propInfo) {\n if (!isObject(propInfo)) return [];\n\n // Check type.name === 'enum' with type.value array\n const t = propInfo.type;\n if (isObject(t) && t.name === 'enum' && Array.isArray(t.value)) {\n const rawList = t.value.map((item) =>\n isObject(item) && 'value' in item ? item.value : item,\n );\n return this.normalizeEnumList(rawList);\n }\n\n // Check tsType for TypeScript enums\n const ts = propInfo.tsType;\n if (isObject(ts) && ts.name === 'union' && Array.isArray(ts.elements)) {\n const rawList = ts.elements.map((el) =>\n isObject(el) && 'value' in el ? el.value : el.name,\n );\n return this.normalizeEnumList(rawList);\n }\n\n return [];\n },\n\n /**\n * Get enum values map for React component\n */\n getReactEnumValues(componentFiber) {\n try {\n const type = componentFiber?.type || componentFiber?.elementType;\n if (!type) return {};\n\n const docgen = type.__docgenInfo;\n if (!isObject(docgen) || !isObject(docgen.props)) return {};\n\n const result = {};\n for (const [key, info] of Object.entries(docgen.props)) {\n const values = this.extractDocgenEnumValues(info);\n if (values.length > 0) result[key] = values;\n }\n return result;\n } catch {\n return {};\n }\n },\n\n /**\n * Extract enum values from Vue prop option\n */\n extractVuePropEnumValues(propOption) {\n if (!isObject(propOption)) return [];\n\n // Check explicit values array\n if (Array.isArray(propOption.values)) {\n return this.normalizeEnumList(propOption.values);\n }\n\n // Check validator with values/allowedValues\n const validator = propOption.validator;\n if (validator && Array.isArray(validator.values)) {\n return this.normalizeEnumList(validator.values);\n }\n if (validator && Array.isArray(validator.allowedValues)) {\n return this.normalizeEnumList(validator.allowedValues);\n }\n\n return [];\n },\n\n /**\n * Get enum values map for Vue component\n */\n getVueEnumValues(instance) {\n try {\n const propsOptions = instance?.type?.props;\n if (!isObject(propsOptions)) return {};\n\n const result = {};\n for (const [key, opt] of Object.entries(propsOptions)) {\n const values = this.extractVuePropEnumValues(opt);\n if (values.length > 0) result[key] = values;\n }\n return result;\n } catch {\n return {};\n }\n },\n };\n\n // =============================================================================\n // Value Access Helpers\n // =============================================================================\n\n function getValueAtPath(root, path) {\n let current = root;\n\n for (let i = 0; i < path.length; i++) {\n const seg = path[i];\n if (!isObject(current) && !Array.isArray(current)) {\n return { ok: false, existed: false, value: undefined };\n }\n\n const has = Object.prototype.hasOwnProperty.call(current, seg);\n current = current[seg];\n\n if (!has && i === path.length - 1) {\n return { ok: true, existed: false, value: undefined };\n }\n }\n\n return { ok: true, existed: true, value: current };\n }\n\n // Dangerous keys that could cause prototype pollution or unexpected behavior\n const DANGEROUS_KEYS = new Set([\n '__proto__',\n 'constructor',\n 'prototype',\n '__defineGetter__',\n '__defineSetter__',\n '__lookupGetter__',\n '__lookupSetter__',\n ]);\n\n function isDangerousKey(key) {\n return typeof key === 'string' && DANGEROUS_KEYS.has(key);\n }\n\n function normalizePropPath(value) {\n if (!Array.isArray(value) || value.length === 0 || value.length > 32) return null;\n\n const result = [];\n for (const seg of value) {\n if (typeof seg === 'string') {\n const s = seg.trim();\n if (!s) return null;\n // Reject dangerous keys to prevent prototype pollution\n if (isDangerousKey(s)) return null;\n result.push(s);\n } else if (typeof seg === 'number' && Number.isInteger(seg) && seg >= 0 && seg <= 1e6) {\n result.push(seg);\n } else {\n return null;\n }\n }\n return result;\n }\n\n function decodeIncomingValue(raw) {\n // Bridge encodes undefined as { $we: 'undefined' }\n if (isObject(raw) && raw.$we === 'undefined') return undefined;\n return raw;\n }\n\n // =============================================================================\n // Capabilities Builder\n // =============================================================================\n\n function makeCapabilities(init) {\n return {\n canRead: Boolean(init?.canRead),\n canWrite: Boolean(init?.canWrite),\n canWriteHooks: Boolean(init?.canWriteHooks),\n };\n }\n\n function buildResponseData(init) {\n const data = {};\n if (init?.hookStatus) data.hookStatus = init.hookStatus;\n if (typeof init?.needsRefresh === 'boolean') data.needsRefresh = init.needsRefresh;\n if (init?.framework) data.framework = init.framework;\n if (init?.frameworkVersion) data.frameworkVersion = init.frameworkVersion;\n if (init?.componentName) data.componentName = init.componentName;\n if (init?.debugSource) data.debugSource = init.debugSource;\n if (init?.props) data.props = init.props;\n if (init?.capabilities) data.capabilities = init.capabilities;\n if (init?.meta) data.meta = init.meta;\n return data;\n }\n\n // =============================================================================\n // Request Handlers\n // =============================================================================\n\n const Handlers = {\n resolveTarget(locator) {\n if (!locator) return null;\n const el = Locator.locate(locator, document);\n // Return element if connected to DOM; otherwise return null\n return el?.isConnected ? el : null;\n },\n\n /**\n * Handle 'probe' operation - Detect capabilities without reading props\n */\n handleProbe(req) {\n // Check initial hook status\n const preStatus = ReactAdapter.detectStatus();\n const initialHookStatus = preStatus.hookStatus;\n\n // Try to install hook if missing (only helps if React hasn't initialized)\n if (initialHookStatus === HOOK_STATUS.HOOK_MISSING) {\n ReactAdapter.installMinimalHook();\n }\n\n const hookInfo = ReactAdapter.detectStatus();\n // Report original status if hook was missing (so UI knows refresh is needed)\n const hookStatus =\n initialHookStatus === HOOK_STATUS.HOOK_MISSING\n ? HOOK_STATUS.HOOK_MISSING\n : hookInfo.hookStatus;\n\n const target = this.resolveTarget(req.locator);\n const fw = target ? FrameworkDetector.detect(target) : { framework: 'unknown', data: null };\n\n let componentName;\n let debugSource;\n let canRead = false;\n let canWrite = false;\n let needsRefresh = false;\n\n let frameworkVersion;\n\n if (fw.framework === 'react') {\n const fiberInfo = ReactAdapter.resolveFiberWithRenderer(target, hookInfo);\n const componentFiber = fiberInfo.fiber\n ? ReactAdapter.findNearestComponentFiber(fiberInfo.fiber)\n : null;\n\n componentName = componentFiber ? ReactAdapter.getComponentName(componentFiber) : undefined;\n // Extract debug source from component fiber or raw fiber\n const sourceFiber = componentFiber || fiberInfo.fiber;\n debugSource = sourceFiber ? ReactAdapter.getDebugSource(sourceFiber) : undefined;\n // Pass specific renderer to prioritize its version in multi-renderer scenarios\n frameworkVersion = ReactAdapter.getVersion(hookInfo, fiberInfo.renderer);\n canRead = Boolean(componentFiber);\n canWrite = hookStatus === HOOK_STATUS.READY && Boolean(componentFiber);\n needsRefresh = canRead && hookStatus !== HOOK_STATUS.READY;\n } else if (fw.framework === 'vue') {\n const instance = fw.data;\n componentName = VueAdapter.getComponentName(instance);\n debugSource = instance ? VueAdapter.getDebugSource(instance, target) : undefined;\n frameworkVersion = VueAdapter.getVersion(instance);\n canRead = Boolean(instance);\n canWrite = Boolean(instance) && VueAdapter.isDevBuild(instance);\n needsRefresh = false;\n }\n\n const data = buildResponseData({\n hookStatus,\n framework: fw.framework,\n frameworkVersion,\n componentName,\n debugSource,\n capabilities: makeCapabilities({ canRead, canWrite, canWriteHooks: false }),\n needsRefresh,\n });\n\n return Transport.createResponse(req.requestId, true, data);\n },\n\n /**\n * Handle 'read' operation - Read component props\n */\n handleRead(req) {\n const target = this.resolveTarget(req.locator);\n if (!target) {\n return Transport.createResponse(\n req.requestId,\n false,\n undefined,\n 'Target element not found',\n );\n }\n\n const preStatus = ReactAdapter.detectStatus();\n if (preStatus.hookStatus === HOOK_STATUS.HOOK_MISSING) {\n ReactAdapter.installMinimalHook();\n }\n\n const hookInfo = ReactAdapter.detectStatus();\n const hookStatus =\n preStatus.hookStatus === HOOK_STATUS.HOOK_MISSING\n ? HOOK_STATUS.HOOK_MISSING\n : hookInfo.hookStatus;\n\n const fw = FrameworkDetector.detect(target);\n\n if (fw.framework === 'react') {\n const fiberInfo = ReactAdapter.resolveFiberWithRenderer(target, hookInfo);\n const componentFiber = fiberInfo.fiber\n ? ReactAdapter.findNearestComponentFiber(fiberInfo.fiber)\n : null;\n\n // Extract debug source even if component fiber not found\n const sourceFiber = componentFiber || fiberInfo.fiber;\n const debugSource = sourceFiber ? ReactAdapter.getDebugSource(sourceFiber) : undefined;\n // Pass specific renderer to prioritize its version in multi-renderer scenarios\n const frameworkVersion = ReactAdapter.getVersion(hookInfo, fiberInfo.renderer);\n\n if (!componentFiber) {\n const data = buildResponseData({\n hookStatus,\n framework: 'react',\n frameworkVersion,\n debugSource,\n capabilities: makeCapabilities({ canRead: false, canWrite: false }),\n needsRefresh: false,\n });\n return Transport.createResponse(\n req.requestId,\n false,\n data,\n 'React component fiber not found',\n );\n }\n\n const props = componentFiber.memoizedProps;\n const enumValuesByKey = EnumIntrospection.getReactEnumValues(componentFiber);\n const serialized = Serializer.serializeProps(props, enumValuesByKey);\n const componentName = ReactAdapter.getComponentName(componentFiber);\n const canWrite = hookStatus === HOOK_STATUS.READY;\n const needsRefresh = hookStatus !== HOOK_STATUS.READY;\n\n const data = buildResponseData({\n hookStatus,\n framework: 'react',\n frameworkVersion,\n componentName,\n debugSource,\n props: serialized,\n capabilities: makeCapabilities({ canRead: true, canWrite, canWriteHooks: false }),\n needsRefresh,\n });\n\n return Transport.createResponse(req.requestId, true, data);\n }\n\n if (fw.framework === 'vue') {\n const instance = fw.data;\n const frameworkVersion = VueAdapter.getVersion(instance);\n\n if (!instance) {\n const data = buildResponseData({\n hookStatus,\n framework: 'vue',\n frameworkVersion,\n capabilities: makeCapabilities({ canRead: false, canWrite: false }),\n needsRefresh: false,\n });\n return Transport.createResponse(\n req.requestId,\n false,\n data,\n 'Vue component instance not found',\n );\n }\n\n const componentName = VueAdapter.getComponentName(instance);\n const debugSource = VueAdapter.getDebugSource(instance, target);\n\n // Read both props and attrs\n let rootProps = null;\n let rootAttrs = null;\n try {\n rootProps = instance.props;\n } catch {\n rootProps = null;\n }\n try {\n rootAttrs = instance.attrs;\n } catch {\n rootAttrs = null;\n }\n\n // Serialize props with enum introspection\n const enumValuesByKey = EnumIntrospection.getVueEnumValues(instance);\n const serializedProps = Serializer.serializeProps(rootProps, enumValuesByKey);\n const serializedAttrs = Serializer.serializeProps(rootAttrs, null);\n\n // Merge entries with source annotation\n const mergedEntries = [];\n if (Array.isArray(serializedProps.entries)) {\n for (const entry of serializedProps.entries) {\n mergedEntries.push({ ...entry, source: 'props' });\n }\n }\n if (Array.isArray(serializedAttrs.entries)) {\n for (const entry of serializedAttrs.entries) {\n mergedEntries.push({ ...entry, source: 'attrs' });\n }\n }\n\n const serialized = {\n kind: 'props',\n entries: mergedEntries,\n };\n if (serializedProps.truncated || serializedAttrs.truncated) {\n serialized.truncated = true;\n }\n\n const canWrite = VueAdapter.isDevBuild(instance);\n\n const data = buildResponseData({\n hookStatus,\n framework: 'vue',\n frameworkVersion,\n componentName,\n debugSource,\n props: serialized,\n capabilities: makeCapabilities({ canRead: true, canWrite, canWriteHooks: false }),\n needsRefresh: false,\n });\n\n return Transport.createResponse(req.requestId, true, data);\n }\n\n // Unknown framework\n const data = buildResponseData({\n hookStatus,\n framework: 'unknown',\n capabilities: makeCapabilities({ canRead: false, canWrite: false }),\n needsRefresh: false,\n });\n\n return Transport.createResponse(req.requestId, false, data, 'Not a React/Vue component');\n },\n\n /**\n * Handle 'write' operation - Modify component props\n */\n handleWrite(req) {\n const target = this.resolveTarget(req.locator);\n if (!target) {\n return Transport.createResponse(\n req.requestId,\n false,\n undefined,\n 'Target element not found',\n );\n }\n\n const path = normalizePropPath(req.payload?.propPath);\n if (!path) {\n return Transport.createResponse(req.requestId, false, undefined, 'Invalid propPath');\n }\n\n const rawValue = req.payload?.propValue;\n const value = decodeIncomingValue(rawValue);\n if (!Serializer.isEditablePrimitive(value)) {\n return Transport.createResponse(\n req.requestId,\n false,\n undefined,\n 'Only primitive prop values are supported',\n );\n }\n\n const preStatus = ReactAdapter.detectStatus();\n if (preStatus.hookStatus === HOOK_STATUS.HOOK_MISSING) {\n ReactAdapter.installMinimalHook();\n }\n\n const hookInfo = ReactAdapter.detectStatus();\n const hookStatus =\n preStatus.hookStatus === HOOK_STATUS.HOOK_MISSING\n ? HOOK_STATUS.HOOK_MISSING\n : hookInfo.hookStatus;\n\n const fw = FrameworkDetector.detect(target);\n\n if (fw.framework === 'react') {\n const fiberInfo = ReactAdapter.resolveFiberWithRenderer(target, hookInfo);\n const componentFiber = fiberInfo.fiber\n ? ReactAdapter.findNearestComponentFiber(fiberInfo.fiber)\n : null;\n\n const componentName = componentFiber\n ? ReactAdapter.getComponentName(componentFiber)\n : undefined;\n const canRead = Boolean(componentFiber);\n const canWrite = hookStatus === HOOK_STATUS.READY && Boolean(componentFiber);\n const needsRefresh = canRead && hookStatus !== HOOK_STATUS.READY;\n\n const base = buildResponseData({\n hookStatus,\n framework: 'react',\n componentName,\n capabilities: makeCapabilities({ canRead, canWrite, canWriteHooks: false }),\n needsRefresh,\n });\n\n if (!componentFiber) {\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'React component fiber not found',\n );\n }\n\n if (hookStatus !== HOOK_STATUS.READY) {\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'React DevTools editing API unavailable. Use a Development build and refresh the page.',\n );\n }\n\n // Check current value for editability and record original\n const props = componentFiber.memoizedProps;\n const read = getValueAtPath(props, path);\n if (read.ok && read.existed && !Serializer.isEditablePrimitive(read.value)) {\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'Target prop is not a primitive (read-only)',\n );\n }\n\n // Try renderers with overrideProps\n const candidates = (hookInfo.editableRenderers || [])\n .map((r) => r.renderer)\n .filter(Boolean);\n const preferred =\n fiberInfo.renderer && typeof fiberInfo.renderer.overrideProps === 'function'\n ? fiberInfo.renderer\n : null;\n const ordered = preferred\n ? [preferred, ...candidates.filter((r) => r !== preferred)]\n : candidates;\n\n let usedRenderer = null;\n let lastErr = null;\n\n for (const renderer of ordered) {\n try {\n renderer.overrideProps(componentFiber, path, value);\n usedRenderer = renderer;\n break;\n } catch (err) {\n lastErr = err;\n }\n }\n\n if (!usedRenderer) {\n base.meta = { write: { method: 'overrideProps', error: safeString(lastErr) } };\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'Failed to write props via overrideProps',\n );\n }\n\n ReactAdapter.recordOriginal(componentFiber, usedRenderer, path, read.existed, read.value);\n base.meta = { write: { method: 'overrideProps' } };\n\n return Transport.createResponse(req.requestId, true, base);\n }\n\n if (fw.framework === 'vue') {\n const instance = fw.data;\n const componentName = VueAdapter.getComponentName(instance);\n const canRead = Boolean(instance);\n const canWrite = Boolean(instance) && VueAdapter.isDevBuild(instance);\n\n const base = buildResponseData({\n hookStatus,\n framework: 'vue',\n componentName,\n capabilities: makeCapabilities({ canRead, canWrite, canWriteHooks: false }),\n needsRefresh: false,\n });\n\n if (!instance) {\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'Vue component instance not found',\n );\n }\n\n if (!VueAdapter.isDevBuild(instance)) {\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'Vue dev metadata missing. Use a Development build.',\n );\n }\n\n // Vue props keys must be strings at top level\n if (typeof path[0] !== 'string') {\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'Vue propPath must start with a string key',\n );\n }\n\n const propName = path[0];\n const subPath = path.slice(1);\n\n // Infer target kind based on whether key is declared prop\n const targetKind = VueAdapter.isDeclaredProp(instance, propName) ? 'props' : 'attrs';\n\n // Check current value from logical root\n const readRoot = VueAdapter.getReadRoot(instance, targetKind) || {};\n const read = getValueAtPath(readRoot, path);\n if (read.ok && read.existed && !Serializer.isEditablePrimitive(read.value)) {\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'Target prop is not a primitive (read-only)',\n );\n }\n\n // Build next vnode props (the correct way to update Vue3 props)\n const currentRawProps = VueAdapter.getVNodeProps(instance) || {};\n const nextRawProps = { ...currentRawProps };\n\n try {\n if (subPath.length === 0) {\n nextRawProps[propName] = value;\n } else {\n const prev = nextRawProps[propName];\n nextRawProps[propName] = VueAdapter.copyWithSet(prev, subPath, value);\n }\n } catch (err) {\n base.meta = {\n write: { method: 'vueNextVNode', target: targetKind, error: safeString(err) },\n };\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'Failed to build Vue props patch',\n );\n }\n\n // Apply via instance.next + update() to trigger Vue's internal updateProps pipeline\n if (!VueAdapter.applyNextProps(instance, nextRawProps)) {\n base.meta = {\n write: { method: 'vueNextVNode', target: targetKind, error: 'No update method' },\n };\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'Vue update method not available',\n );\n }\n\n // Record original for reset only after successful write (include targetKind for accurate reset)\n VueAdapter.recordOriginal(instance, path, read.existed, read.value, targetKind);\n\n base.meta = { write: { method: 'vueNextVNode', target: targetKind } };\n return Transport.createResponse(req.requestId, true, base);\n }\n\n return Transport.createResponse(req.requestId, false, undefined, 'Not a React/Vue component');\n },\n\n /**\n * Handle 'reset' operation - Restore original props values\n */\n handleReset(req) {\n const target = this.resolveTarget(req.locator);\n if (!target) {\n return Transport.createResponse(\n req.requestId,\n false,\n undefined,\n 'Target element not found',\n );\n }\n\n const preStatus = ReactAdapter.detectStatus();\n if (preStatus.hookStatus === HOOK_STATUS.HOOK_MISSING) {\n ReactAdapter.installMinimalHook();\n }\n\n const hookInfo = ReactAdapter.detectStatus();\n const hookStatus =\n preStatus.hookStatus === HOOK_STATUS.HOOK_MISSING\n ? HOOK_STATUS.HOOK_MISSING\n : hookInfo.hookStatus;\n\n const fw = FrameworkDetector.detect(target);\n\n if (fw.framework === 'react') {\n const fiberInfo = ReactAdapter.resolveFiberWithRenderer(target, hookInfo);\n const componentFiber = fiberInfo.fiber\n ? ReactAdapter.findNearestComponentFiber(fiberInfo.fiber)\n : null;\n\n const componentName = componentFiber\n ? ReactAdapter.getComponentName(componentFiber)\n : undefined;\n const canRead = Boolean(componentFiber);\n const canWrite = hookStatus === HOOK_STATUS.READY && Boolean(componentFiber);\n const needsRefresh = canRead && hookStatus !== HOOK_STATUS.READY;\n\n const base = buildResponseData({\n hookStatus,\n framework: 'react',\n componentName,\n capabilities: makeCapabilities({ canRead, canWrite, canWriteHooks: false }),\n needsRefresh,\n });\n\n if (!componentFiber) {\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'React component fiber not found',\n );\n }\n\n const store = ReactAdapter.getOriginals(componentFiber);\n if (!store?.originals?.size) {\n base.meta = { reset: { method: 'refresh', reason: 'noOverrides' } };\n base.needsRefresh = true;\n return Transport.createResponse(req.requestId, true, base);\n }\n\n if (hookStatus !== HOOK_STATUS.READY) {\n base.meta = { reset: { method: 'refresh', reason: 'hookNotReady' } };\n base.needsRefresh = true;\n return Transport.createResponse(req.requestId, true, base);\n }\n\n const renderer = store.renderer;\n if (!renderer || typeof renderer.overrideProps !== 'function') {\n base.meta = { reset: { method: 'refresh', reason: 'missingRenderer' } };\n base.needsRefresh = true;\n return Transport.createResponse(req.requestId, true, base);\n }\n\n let reverted = 0;\n for (const entry of store.originals.values()) {\n try {\n renderer.overrideProps(componentFiber, entry.path, entry.value);\n reverted++;\n } catch {\n // Continue reverting others\n }\n }\n\n ReactAdapter.clearOriginals(componentFiber);\n base.meta = { reset: { method: 'overrideProps', reverted } };\n\n return Transport.createResponse(req.requestId, true, base);\n }\n\n if (fw.framework === 'vue') {\n const instance = fw.data;\n const componentName = VueAdapter.getComponentName(instance);\n const canRead = Boolean(instance);\n const canWrite = Boolean(instance) && VueAdapter.isDevBuild(instance);\n\n const base = buildResponseData({\n hookStatus,\n framework: 'vue',\n componentName,\n capabilities: makeCapabilities({ canRead, canWrite, canWriteHooks: false }),\n needsRefresh: false,\n });\n\n if (!instance) {\n return Transport.createResponse(\n req.requestId,\n false,\n base,\n 'Vue component instance not found',\n );\n }\n\n const store = VueAdapter.getOriginals(instance);\n if (!store?.size) {\n base.meta = { reset: { method: 'refresh', reason: 'noOverrides' } };\n base.needsRefresh = true;\n return Transport.createResponse(req.requestId, true, base);\n }\n\n // Build next vnode props with all originals restored\n const currentRawProps = VueAdapter.getVNodeProps(instance) || {};\n const nextRawProps = { ...currentRawProps };\n\n let reverted = 0;\n for (const entry of store.values()) {\n const path = entry.path;\n if (!Array.isArray(path) || typeof path[0] !== 'string') continue;\n\n const propName = path[0];\n const subPath = path.slice(1);\n\n try {\n if (subPath.length === 0) {\n if (entry.existed) {\n nextRawProps[propName] = entry.value;\n } else {\n delete nextRawProps[propName];\n }\n } else {\n const prev = nextRawProps[propName];\n nextRawProps[propName] = VueAdapter.copyWithSet(prev, subPath, entry.value);\n }\n reverted++;\n } catch {\n // Continue with other entries\n }\n }\n\n // Apply via instance.next + update() to trigger Vue's internal updateProps pipeline\n if (!VueAdapter.applyNextProps(instance, nextRawProps)) {\n base.meta = { reset: { method: 'refresh', reason: 'noUpdate' } };\n base.needsRefresh = true;\n return Transport.createResponse(req.requestId, true, base);\n }\n\n VueAdapter.clearOriginals(instance);\n base.meta = { reset: { method: 'vueNextVNode', reverted } };\n\n return Transport.createResponse(req.requestId, true, base);\n }\n\n return Transport.createResponse(req.requestId, false, undefined, 'Not a React/Vue component');\n },\n\n /**\n * Handle 'cleanup' operation - Dispose agent\n */\n handleCleanup(req) {\n const resp = Transport.createResponse(req.requestId, true, {\n meta: { cleanup: { ok: true } },\n });\n Lifecycle.dispose('request');\n return resp;\n },\n\n /**\n * Route request to appropriate handler\n */\n handle(req) {\n switch (req.op) {\n case 'probe':\n return this.handleProbe(req);\n case 'read':\n return this.handleRead(req);\n case 'write':\n return this.handleWrite(req);\n case 'reset':\n return this.handleReset(req);\n case 'cleanup':\n return this.handleCleanup(req);\n default:\n return Transport.createResponse(\n req.requestId,\n false,\n undefined,\n `Unsupported op: ${safeString(req.op)}`,\n );\n }\n },\n };\n\n // =============================================================================\n // Lifecycle Management\n // =============================================================================\n\n const Lifecycle = {\n disposed: false,\n\n onRequestEvent(event) {\n try {\n if (Lifecycle.disposed) return;\n\n const detail = event?.detail;\n const req = Transport.normalizeRequest(detail);\n if (!req) return;\n\n const resp = Handlers.handle(req);\n Transport.dispatchResponse(resp);\n } catch (err) {\n try {\n const requestId = event?.detail?.requestId;\n if (typeof requestId === 'string' && requestId) {\n Transport.dispatchResponse(\n Transport.createResponse(requestId, false, undefined, safeString(err)),\n );\n }\n } catch {\n // ignore\n }\n }\n },\n\n onCleanupEvent() {\n Lifecycle.dispose('external-event');\n },\n\n dispose(reason) {\n if (this.disposed) return;\n this.disposed = true;\n\n try {\n window.removeEventListener(EVENT_NAME.REQUEST, this.onRequestEvent, true);\n window.removeEventListener(EVENT_NAME.CLEANUP, this.onCleanupEvent, true);\n } catch {\n // ignore\n }\n\n try {\n delete window[GLOBAL_KEY];\n } catch {\n // ignore\n }\n\n if (reason) {\n logWarn('Disposed:', reason);\n }\n },\n\n init() {\n // Use capture phase to avoid page stopPropagation interfering\n window.addEventListener(EVENT_NAME.REQUEST, this.onRequestEvent, true);\n window.addEventListener(EVENT_NAME.CLEANUP, this.onCleanupEvent, true);\n\n window[GLOBAL_KEY] = {\n version: PROTOCOL_VERSION,\n dispose: () => this.dispose('manual'),\n };\n\n // Early injection: install minimal hook before React loads (document_start)\n // This is critical for capturing React renderers that initialize early\n if (document.readyState === 'loading') {\n try {\n const status = ReactAdapter.detectStatus();\n if (status.hookStatus === HOOK_STATUS.HOOK_MISSING) {\n ReactAdapter.installMinimalHook();\n logWarn('Installed minimal hook during early injection');\n }\n } catch (err) {\n // Best-effort: early injection may fail in some environments\n logWarn('Early hook injection failed:', err);\n }\n }\n },\n };\n\n // Initialize\n Lifecycle.init();\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/recorder.js", "content": "/* eslint-disable */\n// recorder.js - content script for recording user interactions into steps\n\n(function () {\n if (window.__RR_RECORDER_INSTALLED__) return;\n window.__RR_RECORDER_INSTALLED__ = true;\n\n // ================================================================\n // 1) CONFIG + STATELESS HELPERS (namespaced)\n // ================================================================\n const CONFIG = {\n // Increase debounce to improve step merging for slow/DOM-replacing inputs\n INPUT_DEBOUNCE_MS: 800,\n BATCH_SEND_MS: 100,\n SCROLL_DEBOUNCE_MS: 350,\n SENSITIVE_INPUT_TYPES: new Set(['password']),\n UI_MAX_STEPS: 30,\n // Maximum time to hold flush while user is typing (prevents unbounded batch accumulation)\n MAX_TYPING_HOLD_MS: 1500,\n };\n // Cross-frame event channel\n const FRAME_EVENT = 'rr_iframe_event';\n\n // Memoization caches for selector computations during recording\n const __cacheUnique = new WeakMap();\n const __cachePath = new WeakMap();\n\n const SelectorEngine = {\n buildTarget(el) {\n const candidates = [];\n const attrNames = ['data-testid', 'data-testId', 'data-test', 'data-qa', 'data-cy'];\n for (const an of attrNames) {\n const v = el.getAttribute && el.getAttribute(an);\n if (v) candidates.push({ type: 'attr', value: `[${an}=\"${CSS.escape(v)}\"]` });\n }\n const classSel = this._uniqueClassSelector(el);\n if (classSel) candidates.push({ type: 'css', value: classSel });\n const css = this._generateSelector(el);\n if (css) candidates.push({ type: 'css', value: css });\n const name = el.getAttribute && el.getAttribute('name');\n if (name) candidates.push({ type: 'attr', value: `[name=\"${CSS.escape(name)}\"]` });\n const title = el.getAttribute && el.getAttribute('title');\n if (title) candidates.push({ type: 'attr', value: `[title=\"${CSS.escape(title)}\"]` });\n const alt = el.getAttribute && el.getAttribute('alt');\n if (alt) candidates.push({ type: 'attr', value: `[alt=\"${CSS.escape(alt)}\"]` });\n const aria = el.getAttribute && el.getAttribute('aria-label');\n const role = el.getAttribute && el.getAttribute('role');\n if (aria) {\n if (role) candidates.push({ type: 'aria', value: `${role}[name=${aria}]` });\n else candidates.push({ type: 'aria', value: `textbox[name=${aria}]` });\n }\n const tag = el.tagName?.toLowerCase?.() || '';\n if (['button', 'a', 'summary'].includes(tag)) {\n const text = (el.textContent || '').trim();\n if (text) candidates.push({ type: 'text', value: text.substring(0, 64) });\n }\n const selector = SelectorEngine._choosePrimary(el, candidates);\n return { selector, candidates, tag };\n },\n\n _choosePrimary(el, candidates) {\n if (el.id && document.querySelectorAll(`#${CSS.escape(el.id)}`).length === 1) {\n return `#${CSS.escape(el.id)}`;\n }\n const priority = ['attr', 'css'];\n for (const p of priority) {\n const c = candidates.find((c) => c.type === p);\n if (c) {\n try {\n const tag = el.tagName ? el.tagName.toLowerCase() : '';\n if (p === 'attr' && (tag === 'input' || tag === 'textarea' || tag === 'select')) {\n const val = String(c.value || '').trim();\n if (val.startsWith('[')) return `${tag}${val}`;\n }\n } catch {}\n return c.value;\n }\n }\n if (candidates.length) return candidates[0].value;\n return SelectorEngine._generateSelector(el) || '';\n },\n\n _uniqueClassSelector(el) {\n if (__cacheUnique.has(el)) return __cacheUnique.get(el);\n let result = '';\n try {\n const classes = Array.from(el.classList || []).filter(\n (c) => c && /^[a-zA-Z0-9_-]+$/.test(c),\n );\n for (const cls of classes) {\n const sel = `.${CSS.escape(cls)}`;\n if (document.querySelectorAll(sel).length === 1) {\n result = sel;\n break;\n }\n }\n if (!result) {\n const tag = el.tagName ? el.tagName.toLowerCase() : '';\n for (const cls of classes) {\n const sel = `${tag}.${CSS.escape(cls)}`;\n if (document.querySelectorAll(sel).length === 1) {\n result = sel;\n break;\n }\n }\n }\n if (!result) {\n for (let i = 0; i < Math.min(classes.length, 3) && !result; i++) {\n for (let j = i + 1; j < Math.min(classes.length, 3); j++) {\n const sel = `.${CSS.escape(classes[i])}.${CSS.escape(classes[j])}`;\n if (document.querySelectorAll(sel).length === 1) {\n result = sel;\n break;\n }\n }\n }\n }\n } catch {}\n __cacheUnique.set(el, result);\n return result;\n },\n\n _generateSelector(el) {\n if (!(el instanceof Element)) return '';\n if (__cachePath.has(el)) return __cachePath.get(el);\n if (el.id) {\n const idSel = `#${CSS.escape(el.id)}`;\n if (document.querySelectorAll(idSel).length === 1) return idSel;\n }\n for (const attr of ['data-testid', 'data-cy', 'name']) {\n const attrValue = el.getAttribute(attr);\n if (attrValue) {\n const s = `[${attr}=\"${CSS.escape(attrValue)}\"]`;\n if (document.querySelectorAll(s).length === 1) return s;\n }\n }\n let path = '';\n let current = el;\n while (current && current.nodeType === Node.ELEMENT_NODE && current.tagName !== 'BODY') {\n let selector = current.tagName.toLowerCase();\n const parent = current.parentElement;\n if (parent) {\n const siblings = Array.from(parent.children).filter(\n (child) => child.tagName === current.tagName,\n );\n if (siblings.length > 1) {\n const index = siblings.indexOf(current) + 1;\n selector += `:nth-of-type(${index})`;\n }\n }\n path = path ? `${selector} > ${path}` : selector;\n current = parent;\n }\n const res = path ? `body > ${path}` : 'body';\n __cachePath.set(el, res);\n return res;\n },\n };\n // Extend SelectorEngine with a shared ref helper (attached after declaration)\n SelectorEngine._ensureGlobalRef = function (el) {\n try {\n if (!window.__claudeElementMap) window.__claudeElementMap = {};\n if (!window.__claudeRefCounter) window.__claudeRefCounter = 0;\n for (const k in window.__claudeElementMap) {\n const w = window.__claudeElementMap[k];\n if (w && typeof w.deref === 'function' && w.deref() === el) return k;\n }\n const id = `ref_${++window.__claudeRefCounter}`;\n window.__claudeElementMap[id] = new WeakRef(el);\n return id;\n } catch {\n return null;\n }\n };\n\n // ================================================================\n // 2) UI CLASS (injected via constructor)\n // ================================================================\n class UI {\n constructor(recorder) {\n this.recorder = recorder;\n this._box = null;\n // Timeline elements state\n this._timeline = null;\n this._count = 0;\n this._timelineBox = null;\n this._collapsed = false;\n }\n ensure() {\n const rec = this.recorder;\n if (window !== window.top) return;\n let root = document.getElementById('__rr_rec_overlay');\n if (root) return;\n root = document.createElement('div');\n root.id = '__rr_rec_overlay';\n Object.assign(root.style, {\n position: 'fixed',\n top: '10px',\n right: '10px',\n zIndex: 2147483646,\n fontFamily: 'system-ui,-apple-system,Segoe UI,Roboto,Arial',\n });\n root.innerHTML = `\n
\n 录制中\n \n \n \n \n \n
`;\n document.documentElement.appendChild(root);\n // Build timeline container just below the panel\n const timeline = document.createElement('div');\n timeline.id = '__rr_rec_timeline';\n Object.assign(timeline.style, {\n marginTop: '8px',\n width: '360px',\n maxHeight: '220px',\n overflow: 'auto',\n background: 'rgba(17,24,39,0.85)',\n color: '#F9FAFB',\n border: '1px solid rgba(255,255,255,0.2)',\n borderRadius: '8px',\n boxShadow: '0 4px 16px rgba(0,0,0,0.18)',\n padding: '8px 10px',\n fontSize: '12px',\n lineHeight: '1.4',\n });\n const header = document.createElement('div');\n header.textContent = '已录制步骤';\n header.style.opacity = '0.8';\n header.style.marginBottom = '4px';\n const list = document.createElement('ol');\n list.id = '__rr_rec_timeline_list';\n list.style.listStyle = 'none';\n list.style.margin = '0';\n list.style.padding = '0';\n list.style.display = 'flex';\n list.style.flexDirection = 'column';\n list.style.gap = '4px';\n timeline.appendChild(header);\n timeline.appendChild(list);\n root.appendChild(timeline);\n this._timeline = list;\n this._timelineBox = timeline;\n const btnPause = root.querySelector('#__rr_pause');\n const btnStop = root.querySelector('#__rr_stop');\n const hideChk = root.querySelector('#__rr_hide_values');\n const highlightChk = root.querySelector('#__rr_enable_highlight');\n const btnToggle = root.querySelector('#__rr_toggle_timeline');\n hideChk.checked = !!rec.hideInputValues;\n hideChk.addEventListener('change', () => (rec.hideInputValues = hideChk.checked));\n highlightChk.checked = !!rec.highlightEnabled;\n highlightChk.addEventListener('change', () => {\n rec.highlightEnabled = !!highlightChk.checked;\n rec._updateHoverListener();\n });\n if (btnToggle) {\n btnToggle.addEventListener('click', () => {\n this._collapsed = !this._collapsed;\n if (this._timelineBox)\n this._timelineBox.style.display = this._collapsed ? 'none' : 'block';\n btnToggle.textContent = this._collapsed ? '展开' : '折叠';\n });\n }\n btnPause.addEventListener('click', () => {\n if (!rec.isPaused) rec.pause();\n else rec.resume();\n });\n btnStop.addEventListener('click', () => {\n chrome.runtime.sendMessage({ type: 'rr_stop_recording' });\n });\n this._box = document.createElement('div');\n Object.assign(this._box.style, {\n position: 'fixed',\n border: '2px solid rgba(59,130,246,0.9)',\n borderRadius: '4px',\n background: 'rgba(59,130,246,0.15)',\n pointerEvents: 'none',\n zIndex: 2147483645,\n });\n document.documentElement.appendChild(this._box);\n if (rec.highlightEnabled)\n document.addEventListener('mousemove', rec._onMouseMove, { capture: true, passive: true });\n this.updateStatus();\n }\n remove() {\n if (window === window.top) {\n const root = document.getElementById('__rr_rec_overlay');\n if (root) root.remove();\n if (this._box) this._box.remove();\n this._timeline = null;\n this._timelineBox = null;\n }\n }\n updateStatus() {\n const badge = document.getElementById('__rr_badge');\n const pauseBtn = document.getElementById('__rr_pause');\n if (badge) badge.textContent = this.recorder.isPaused ? '已暂停' : '录制中';\n if (pauseBtn) pauseBtn.textContent = this.recorder.isPaused ? '继续' : '暂停';\n }\n\n // Reset the timeline list content\n resetTimeline() {\n this._count = 0;\n const list = this._timeline || document.getElementById('__rr_rec_timeline_list') || null;\n if (list) list.innerHTML = '';\n }\n\n // Append a new recorded step into the timeline UI\n appendStep(step) {\n const list = this._timeline || document.getElementById('__rr_rec_timeline_list') || null;\n if (!list) return;\n this._count += 1;\n const item = document.createElement('li');\n const text = this._formatStepText(step, this._count);\n item.setAttribute('data-step-id', step.id || '');\n item.style.display = 'flex';\n item.style.alignItems = 'flex-start';\n item.style.gap = '6px';\n item.innerHTML = `\n ${this._count}.\n ${text}\n `;\n list.appendChild(item);\n while (list.children.length > CONFIG.UI_MAX_STEPS) {\n list.removeChild(list.firstChild);\n }\n const container = list.parentElement;\n if (container) container.scrollTop = container.scrollHeight;\n }\n\n /**\n * Apply a full timeline update from background.\n * Steps can be upserted in place (same id, updated fields) during fill debouncing.\n * Uses smart diffing to minimize DOM operations while ensuring fill values are accurate.\n */\n applyTimelineUpdate(steps) {\n try {\n if (window !== window.top) return;\n const list = Array.isArray(steps) ? steps : [];\n const total = list.length;\n // Ensure UI exists\n if (!this._timeline) this.ensure();\n if (!this._timeline) return;\n if (total === 0) {\n this.resetTimeline();\n return;\n }\n\n // Calculate the window of steps to display (last N steps)\n const windowStart = Math.max(0, total - CONFIG.UI_MAX_STEPS);\n const windowSteps = list.slice(windowStart);\n\n // Get current displayed step IDs\n const currentItems = this._timeline.children;\n const currentIds = [];\n for (let i = 0; i < currentItems.length; i++) {\n currentIds.push(currentItems[i].getAttribute('data-step-id') || '');\n }\n\n // Check if we need a full rebuild or can do incremental update\n const newIds = windowSteps.map((s) => s.id || '');\n const needsRebuild =\n currentIds.length !== newIds.length || currentIds.some((id, i) => id !== newIds[i]);\n\n if (needsRebuild) {\n // Full rebuild: either structure changed or it's simpler to rebuild\n this.resetTimeline();\n for (let i = 0; i < windowSteps.length; i++) {\n this._appendStepWithIndex(windowSteps[i], windowStart + i + 1);\n }\n } else {\n // Incremental update: same steps, just update values\n for (let i = 0; i < windowSteps.length; i++) {\n const step = windowSteps[i];\n const item = currentItems[i];\n if (item) {\n // Update the text content for this step\n const textSpan = item.querySelector('span:last-child');\n if (textSpan) {\n const newText = this._formatStepText(step, windowStart + i + 1);\n if (textSpan.textContent !== newText) {\n textSpan.textContent = newText;\n }\n }\n }\n }\n }\n this._count = total;\n } catch {}\n }\n\n /**\n * Internal method to append a step with a specific display index.\n * Used by applyTimelineUpdate for proper numbering.\n */\n _appendStepWithIndex(step, displayIndex) {\n const list = this._timeline || document.getElementById('__rr_rec_timeline_list') || null;\n if (!list) return;\n const item = document.createElement('li');\n const text = this._formatStepText(step, displayIndex);\n item.setAttribute('data-step-id', step.id || '');\n item.style.display = 'flex';\n item.style.alignItems = 'flex-start';\n item.style.gap = '6px';\n item.innerHTML = `\n ${displayIndex}.\n ${text}\n `;\n list.appendChild(item);\n const container = list.parentElement;\n if (container) container.scrollTop = container.scrollHeight;\n }\n\n // Create a short, human-readable text for a recorded step\n _formatStepText(step, _idx) {\n try {\n if (!step || typeof step !== 'object') return '未知步骤';\n const t = step.type;\n const sel = step.target && step.target.selector ? step.target.selector : '';\n if (t === 'click' || t === 'dblclick') {\n return `${t === 'dblclick' ? '双击' : '点击'}: ${sel || '(document)'}`;\n }\n if (t === 'fill') {\n const val = step.value;\n const shown = typeof val === 'string' && val.length > 0 ? val : String(val);\n return `输入: ${sel} = ${shown}`;\n }\n if (t === 'scroll') {\n const mode = step.mode === 'container' ? '容器' : '页面';\n const off = step.offset || {};\n return `滚动(${mode}): y=${off.y ?? 0}, x=${off.x ?? 0}`;\n }\n if (t === 'openTab') return `打开标签页: ${step.url || ''}`;\n if (t === 'switchTab') return `切换标签页: 包含 ${step.urlContains || ''}`;\n if (t === 'switchFrame')\n return `切换Frame: 包含 ${step.frame && step.frame.urlContains ? step.frame.urlContains : ''}`;\n if (t === 'waitFor') return `等待: ${sel || step.until || ''}`;\n return `${t}`;\n } catch (_) {\n return '步骤';\n }\n }\n }\n\n // ================================================================\n // 3) MAIN CLASS: ContentRecorder (stateful)\n // ================================================================\n class ContentRecorder {\n constructor() {\n // State\n this.isRecording = false;\n this.isPaused = false;\n this.hideInputValues = false;\n this.highlightEnabled = true;\n this.hoverRAF = 0;\n this.frameSwitchPushed = false;\n this.batch = [];\n this.batchTimer = null;\n this.scrollTimer = null;\n\n // Local, content-side buffer for batching/merging steps during recording.\n // Not the authoritative Flow (background holds the real one).\n this.sessionBuffer = this._createSessionBuffer();\n // lastFill tracks the most recent fill step for debounce/merge\n // el: DOM element reference for reading final value on finalize\n this.lastFill = { step: null, ts: 0, el: null };\n // Input activity tracking for flush gate (separate from merge state)\n // Updated by both local input and iframe upsert messages\n this._lastInputActivityTs = 0;\n // Flush gate: tracks when a typing burst started to enforce MAX_TYPING_HOLD_MS\n this._typingBurstStartTs = 0;\n // Force flush timer: ensures MAX_TYPING_HOLD_MS is a hard upper bound\n // This timer is NOT reset on each input, only cleared on actual flush\n this._forceFlushTimer = null;\n // Recording-time element identity map (not persisted)\n this.el2ref = new WeakMap();\n this.refCounter = 0;\n\n // Bind handlers\n this._onClick = this._onClick.bind(this);\n this._onInput = this._onInput.bind(this);\n this._onDocInput = this._onDocInput.bind(this);\n this._onChange = this._onChange.bind(this);\n this._onMouseMove = this._onMouseMove.bind(this);\n this._onScroll = this._onScroll.bind(this);\n this._onFocusIn = this._onFocusIn.bind(this);\n this._onFocusOut = this._onFocusOut.bind(this);\n this._onKeyDown = this._onKeyDown.bind(this);\n this._onKeyUp = this._onKeyUp.bind(this);\n this._onWindowMessage = this._onWindowMessage.bind(this);\n // Page lifecycle handlers for best-effort flush on navigation/close\n this._onPageHide = this._onPageHide.bind(this);\n this._onVisibilityChange = this._onVisibilityChange.bind(this);\n this.ui = new UI(this);\n this._scrollPending = null;\n\n // Focus tracking for per-element input listening\n this._focusedEl = null;\n // Keyboard state for combo recording\n this._pressed = new Set();\n this._lastKeyTs = 0;\n // Map to avoid duplicate switchFrame per iframe source (keyed by frame selector)\n this._frameSwitchMap = new Set();\n }\n\n // Lifecycle\n start(flowMeta) {\n // Idempotent start: if already recording (and not paused), just ensure UI and listeners\n if (this.isRecording && !this.isPaused) {\n this.ui.ensure();\n this._updateHoverListener();\n return;\n }\n // If paused, treat start as resume to avoid resetting local buffer/UI timeline\n if (this.isPaused) {\n this.resume();\n return;\n }\n this._reset(flowMeta || {});\n this.isRecording = true;\n this.isPaused = false;\n this._attach();\n this.ui.ensure();\n this.ui.resetTimeline();\n }\n\n /**\n * Stop recording and flush all pending data.\n * This is the reliable stop that ensures no data is lost.\n * Waits for background to acknowledge receipt of all data before returning.\n * @returns {Promise<{ack: boolean, steps: number, variables: number}>}\n */\n async stop() {\n if (!this.isRecording) {\n return { ack: true, steps: 0, variables: 0 };\n }\n\n this.isRecording = false;\n // Stop should clear paused state so detach fully cleans up (and barrier works consistently)\n this.isPaused = false;\n\n // Step 1: Finalize pending click (dblclick detector)\n this._finalizePendingClick();\n\n // Step 2: Finalize any pending input (draft mode)\n this._finalizePendingInput();\n\n // Step 3: Finalize any pending scroll\n this._finalizePendingScroll();\n\n // Step 4: In iframes, ensure the top-frame aggregator has processed our final postMessages\n // before we ACK the background stop (prevents missing iframe steps)\n let topSyncOk = true;\n if (window !== window.top) {\n topSyncOk = await this._syncStopBarrierToTop();\n }\n\n // Step 5: Clear timers BEFORE flush (prevent race conditions)\n if (this.batchTimer) clearTimeout(this.batchTimer);\n this.batchTimer = null;\n if (this.scrollTimer) clearTimeout(this.scrollTimer);\n this.scrollTimer = null;\n if (this.hoverRAF) cancelAnimationFrame(this.hoverRAF);\n this.hoverRAF = 0;\n\n // Step 6: Flush any remaining batched steps and WAIT for ack\n const stepsCount = this.batch.length;\n let stepsAck = true;\n if (stepsCount > 0) {\n stepsAck = await this._flush();\n }\n\n // Step 7: Send all collected variables and WAIT for ack\n const variablesCount = this.sessionBuffer.variables?.length || 0;\n let variablesAck = true;\n if (variablesCount > 0) {\n variablesAck = await this._sendVariables();\n }\n\n // Step 8: Detach listeners and clean up UI\n this._detach();\n this.ui.remove();\n\n // Step 9: Reset state\n this.lastFill = { step: null, ts: 0, el: null };\n this._lastInputActivityTs = 0;\n this._typingBurstStartTs = 0;\n if (this._forceFlushTimer) {\n clearTimeout(this._forceFlushTimer);\n this._forceFlushTimer = null;\n }\n this.sessionBuffer.steps = [];\n\n // Return acknowledgment with stats\n // ack is true only if all sends were acknowledged\n return {\n ack: stepsAck && variablesAck && topSyncOk,\n steps: stepsCount,\n variables: variablesCount,\n };\n }\n\n /**\n * Finalize a pending click that hasn't been emitted yet.\n * The dblclick detector holds single clicks temporarily to detect double-clicks.\n * This ensures stop/pause flush includes the last single click.\n */\n _finalizePendingClick() {\n try {\n if (this._pendingClickTimer) clearTimeout(this._pendingClickTimer);\n } catch {}\n this._pendingClickTimer = null;\n\n try {\n if (this._pendingClick) this._pushStep(this._pendingClick);\n } catch {}\n this._pendingClick = null;\n }\n\n /**\n * Finalize any pending input that hasn't been flushed yet.\n * This ensures the last input value is captured before stop/pause/navigation.\n * Uses lastFill.el (DOM reference) to read the current value.\n */\n _finalizePendingInput() {\n const last = this.lastFill;\n if (!last || !last.step) return;\n\n // Commit the latest value from the DOM element\n try {\n const el = last.el;\n if (el) {\n const freshValue = this._getElementValue(el, last.step.value);\n if (freshValue !== last.step.value) {\n last.step.value = freshValue;\n this.sessionBuffer.meta.updatedAt = new Date().toISOString();\n }\n }\n } catch {\n // Element may no longer exist, that's OK - we keep the last known value\n }\n\n // Enqueue for upsert to ensure background gets the final value\n try {\n this._enqueueForUpsert(last.step);\n } catch {}\n\n // Reset state\n this.lastFill = { step: null, ts: 0, el: null };\n this._typingBurstStartTs = 0;\n }\n\n /**\n * Get the current value from an element, handling sensitive fields and contenteditable.\n * @param {Element} el - The element to read from\n * @param {string} existingValue - The existing recorded value (may be a variable placeholder)\n * @returns {string} The value to record\n */\n _getElementValue(el, existingValue) {\n if (!el) return existingValue || '';\n\n const isContentEditable =\n el.nodeType === 1 && /** @type {HTMLElement} */ (el).isContentEditable === true;\n\n // If existing value is already a variable placeholder, preserve it\n // Use strict pattern to avoid false positives for user input like \"{abc}\"\n const existing = typeof existingValue === 'string' ? existingValue : '';\n const varPlaceholderPattern =\n /^\\{(?:var_[a-z0-9]{4}|file_[a-z0-9]{4}|[a-zA-Z_][a-zA-Z0-9_]*)\\}$/;\n if (varPlaceholderPattern.test(existing)) {\n return existing;\n }\n\n // Check if this is a sensitive field\n const isSensitive =\n this.hideInputValues ||\n (!isContentEditable &&\n CONFIG.SENSITIVE_INPUT_TYPES.has(\n ((el.getAttribute && el.getAttribute('type')) || '').toLowerCase(),\n ));\n\n if (isSensitive) {\n // Return existing variable or create new one (should already exist from initial capture)\n return existing;\n }\n\n // Read fresh value from DOM\n try {\n if (isContentEditable) {\n return /** @type {HTMLElement} */ (el).innerText || '';\n }\n if (\n el instanceof HTMLInputElement ||\n el instanceof HTMLTextAreaElement ||\n el instanceof HTMLSelectElement\n ) {\n return el.value || '';\n }\n } catch {}\n\n return existing || '';\n }\n\n /**\n * Finalize any pending scroll that hasn't been committed yet.\n * Converts the pending scroll data into a proper scroll step.\n */\n _finalizePendingScroll() {\n if (!this._scrollPending) return;\n\n const pending = this._scrollPending;\n this._scrollPending = null;\n\n const { isDoc, target, top, left } = pending;\n\n // Try merge with last step (same logic as _onScroll timer callback)\n const steps = this.sessionBuffer.steps;\n const last = steps.length ? steps[steps.length - 1] : null;\n if (last && last.type === 'scroll') {\n const sameDoc = isDoc && !last.target && last.mode === 'offset';\n const sameEl =\n !isDoc &&\n last.target &&\n last.target.selector &&\n target &&\n last.target.selector === target.selector &&\n last.mode === 'container';\n if (sameDoc || sameEl) {\n last.offset = { y: top, x: left };\n this.sessionBuffer.meta.updatedAt = new Date().toISOString();\n return;\n }\n }\n\n // Create new scroll step\n if (isDoc) {\n this._pushStep({\n type: 'scroll',\n mode: 'offset',\n offset: { y: top, x: left },\n screenshotOnFail: false,\n });\n } else {\n this._pushStep({\n type: 'scroll',\n mode: 'container',\n target: target,\n offset: { y: top, x: left },\n screenshotOnFail: false,\n });\n }\n }\n\n /**\n * Send all collected variables to background.\n * @returns {Promise} - Resolves when background acknowledges receipt\n */\n async _sendVariables() {\n if (!this.sessionBuffer.variables || this.sessionBuffer.variables.length === 0) {\n return true;\n }\n return this._send({ kind: 'variables', variables: this.sessionBuffer.variables });\n }\n\n /**\n * Pause recording. Flushes pending data before pausing.\n */\n pause() {\n if (!this.isRecording || this.isPaused) return;\n\n // Finalize pending data before pausing\n this._finalizePendingClick();\n this._finalizePendingInput();\n this._finalizePendingScroll();\n\n // Flush batched steps\n if (this.batch.length > 0) {\n this._flush();\n }\n\n // Clear timers\n if (this.batchTimer) clearTimeout(this.batchTimer);\n this.batchTimer = null;\n if (this.scrollTimer) clearTimeout(this.scrollTimer);\n this.scrollTimer = null;\n\n this.isPaused = true;\n this._detach();\n this.ui.updateStatus();\n }\n\n /**\n * Resume recording after pause.\n */\n resume() {\n if (!this.isPaused) return;\n\n this.isRecording = true;\n this.isPaused = false;\n this._attach();\n this.ui.ensure();\n this.ui.updateStatus();\n }\n\n // DOM listeners\n _attach() {\n document.addEventListener('click', this._onClick, true);\n // Use focusin/out to attach input listener only to focused element\n document.addEventListener('focusin', this._onFocusIn, true);\n document.addEventListener('focusout', this._onFocusOut, true);\n // Document-level input capture to support Shadow DOM (custom elements)\n // Use capture phase + composedPath to find inner editable control\n document.addEventListener('input', this._onDocInput, true);\n document.addEventListener('change', this._onChange, true);\n // capture-phase scroll to catch non-bubbling events on any container (passive to avoid jank)\n document.addEventListener('scroll', this._onScroll, { capture: true, passive: true });\n // Keyboard: record Enter and modifier combos\n document.addEventListener('keydown', this._onKeyDown, true);\n document.addEventListener('keyup', this._onKeyUp, true);\n // Page lifecycle: best-effort flush on navigation/close\n window.addEventListener('pagehide', this._onPageHide, true);\n document.addEventListener('visibilitychange', this._onVisibilityChange, true);\n // Cross-frame: top window aggregates iframe-recorded steps\n if (window === window.top) window.addEventListener('message', this._onWindowMessage, true);\n this._updateHoverListener();\n }\n\n _detach() {\n document.removeEventListener('click', this._onClick, true);\n document.removeEventListener('focusin', this._onFocusIn, true);\n document.removeEventListener('focusout', this._onFocusOut, true);\n document.removeEventListener('input', this._onDocInput, true);\n document.removeEventListener('change', this._onChange, true);\n document.removeEventListener('scroll', this._onScroll, { capture: true });\n document.removeEventListener('keydown', this._onKeyDown, true);\n document.removeEventListener('keyup', this._onKeyUp, true);\n window.removeEventListener('pagehide', this._onPageHide, true);\n document.removeEventListener('visibilitychange', this._onVisibilityChange, true);\n document.removeEventListener('mousemove', this._onMouseMove, { capture: true });\n // Keep top-frame aggregator alive during pause; stop() clears isPaused and will remove it\n if (window === window.top && !this.isPaused)\n window.removeEventListener('message', this._onWindowMessage, true);\n // Detach per-element input listener if any\n if (this._focusedEl) this._focusedEl.removeEventListener('input', this._onInput, true);\n this._focusedEl = null;\n // Best-effort cleanup for timers/raf when detaching\n if (this.batchTimer) clearTimeout(this.batchTimer);\n this.batchTimer = null;\n if (this.scrollTimer) clearTimeout(this.scrollTimer);\n this.scrollTimer = null;\n if (this.hoverRAF) cancelAnimationFrame(this.hoverRAF);\n this.hoverRAF = 0;\n // Clear pending click state (stop/pause flush it before detach)\n if (this._pendingClickTimer) {\n clearTimeout(this._pendingClickTimer);\n }\n this._pendingClickTimer = null;\n this._pendingClick = null;\n }\n\n _updateHoverListener() {\n if (window !== window.top) return;\n document.removeEventListener('mousemove', this._onMouseMove, { capture: true });\n if (this.isRecording && !this.isPaused && this.highlightEnabled) {\n document.addEventListener('mousemove', this._onMouseMove, { capture: true, passive: true });\n }\n }\n\n // Flow helpers (content-side buffer only)\n _createSessionBuffer() {\n const nowIso = new Date().toISOString();\n return {\n id: `flow_${Date.now()}`,\n name: '未命名录制',\n version: 1,\n steps: [],\n variables: [],\n meta: { createdAt: nowIso, updatedAt: nowIso },\n };\n }\n\n _reset(meta) {\n this.sessionBuffer = this._createSessionBuffer();\n try {\n if (meta && typeof meta === 'object') {\n if (meta.id) this.sessionBuffer.id = String(meta.id);\n if (meta.name) this.sessionBuffer.name = String(meta.name);\n if (meta.description) this.sessionBuffer.description = String(meta.description);\n }\n } catch {}\n this.lastFill = { step: null, ts: 0, el: null };\n this._lastInputActivityTs = 0;\n this._typingBurstStartTs = 0;\n if (this._forceFlushTimer) {\n clearTimeout(this._forceFlushTimer);\n this._forceFlushTimer = null;\n }\n this.frameSwitchPushed = false;\n }\n\n /**\n * Update input activity timestamp (used for flush gate).\n * Called on local input and iframe upsert messages.\n */\n _updateInputActivity() {\n const now = Date.now();\n const prevActivityTs = this._lastInputActivityTs || 0;\n this._lastInputActivityTs = now;\n // Start a new burst if previous one expired (or this is first input)\n if (!this._typingBurstStartTs || now - prevActivityTs > CONFIG.INPUT_DEBOUNCE_MS) {\n this._typingBurstStartTs = now;\n // Start force flush timer (hard upper bound for MAX_TYPING_HOLD_MS)\n this._startForceFlushTimer();\n }\n }\n\n /**\n * Start the force flush timer.\n * This timer ensures MAX_TYPING_HOLD_MS is a hard upper bound.\n * Unlike batchTimer, this timer is NOT reset on each input.\n */\n _startForceFlushTimer() {\n // Don't restart if already running\n if (this._forceFlushTimer) return;\n this._forceFlushTimer = setTimeout(() => {\n this._forceFlushTimer = null;\n // Force flush regardless of current input state\n if (this.batch.length > 0) {\n this._flush();\n }\n }, CONFIG.MAX_TYPING_HOLD_MS);\n }\n\n /**\n * Clear the force flush timer (called on actual flush).\n */\n _clearForceFlushTimer() {\n if (this._forceFlushTimer) {\n clearTimeout(this._forceFlushTimer);\n this._forceFlushTimer = null;\n }\n this._typingBurstStartTs = 0;\n }\n\n /**\n * Unified commit and flush logic.\n * Called at commit points: focusout, Enter key, pagehide, visibilitychange.\n * @param {Object} options\n * @param {boolean} [options.bestEffort=false] - If true, don't await (for unload events)\n */\n _commitAndFlush(options = {}) {\n if (!this.isRecording || this.isPaused) return;\n\n try {\n this._finalizePendingInput();\n this._finalizePendingScroll();\n } catch {}\n\n // Reset flush gate to allow immediate flush\n this._lastInputActivityTs = 0;\n this._typingBurstStartTs = 0;\n this._clearForceFlushTimer();\n\n // Flush (best-effort for unload events)\n try {\n if (this.batch.length > 0) this._flush();\n } catch {}\n try {\n const variablesCount = this.sessionBuffer.variables?.length || 0;\n if (variablesCount > 0) this._sendVariables();\n } catch {}\n\n // If in iframe, ask top to flush too\n this._requestTopFlush();\n }\n\n _pushStep(step) {\n step.id = step.id || `step_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;\n // In iframes, forward to top for aggregation (compute frame selector there)\n if (window !== window.top) {\n try {\n const payload = {\n kind: 'iframeStep',\n href: String(location && location.href ? location.href : ''),\n step,\n };\n window.top.postMessage({ type: FRAME_EVENT, payload }, '*');\n return; // Do not push locally in subframe\n } catch {}\n }\n // Top window: optionally insert a switchFrame if this step originated from an iframe message\n this.sessionBuffer.steps.push(step);\n this.sessionBuffer.meta.updatedAt = new Date().toISOString();\n this.batch.push(step);\n\n // Track input activity for fill steps (to enforce flush gate)\n if (step && step.type === 'fill') {\n this._updateInputActivity();\n }\n\n this._scheduleFlush();\n }\n\n /**\n * Calculate the appropriate flush delay based on typing activity.\n * During active typing, delay flush to avoid sending incomplete values.\n * Note: MAX_TYPING_HOLD_MS is enforced by _forceFlushTimer, not here.\n * @returns {number} Delay in milliseconds before next flush\n */\n _getFlushDelayMs() {\n const now = Date.now();\n const lastInputTs = this._lastInputActivityTs || 0;\n\n // If no recent input activity, use default batch delay\n if (!lastInputTs || now - lastInputTs >= CONFIG.INPUT_DEBOUNCE_MS) {\n return CONFIG.BATCH_SEND_MS;\n }\n\n // Wait for input debounce to complete\n const notBefore = lastInputTs + CONFIG.INPUT_DEBOUNCE_MS;\n const delay = Math.max(CONFIG.BATCH_SEND_MS, notBefore - now);\n\n return delay;\n }\n\n /**\n * Schedule a batch flush with appropriate delay.\n * Respects typing gate to avoid flushing incomplete fill values.\n */\n _scheduleFlush() {\n if (this.batchTimer) {\n clearTimeout(this.batchTimer);\n }\n const delay = this._getFlushDelayMs();\n this.batchTimer = setTimeout(() => {\n this.batchTimer = null;\n this._flush();\n }, delay);\n }\n\n /**\n * Request top frame to immediately flush its aggregated buffer.\n * Used by iframes on commit points (focusout, navigation) to ensure\n * their updates are sent to background promptly.\n */\n _requestTopFlush() {\n if (window === window.top) return;\n try {\n const payload = {\n kind: 'iframeFlush',\n href: String(location && location.href ? location.href : ''),\n };\n window.top.postMessage({ type: FRAME_EVENT, payload }, '*');\n } catch {}\n }\n\n /**\n * Iframe -> top stop barrier sync.\n * Ensures the top frame has processed all prior iframe postMessages (steps/upserts)\n * before this iframe responds to background STOP.\n * @returns {Promise}\n */\n _syncStopBarrierToTop() {\n if (window === window.top) return Promise.resolve(true);\n const id = `sb_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;\n const href = String(location && location.href ? location.href : '');\n const timeoutMs = 400;\n\n return new Promise((resolve) => {\n let done = false;\n const cleanup = (ok) => {\n if (done) return;\n done = true;\n try {\n window.removeEventListener('message', onMessage, true);\n } catch {}\n try {\n clearTimeout(t);\n } catch {}\n resolve(!!ok);\n };\n\n const onMessage = (ev) => {\n try {\n if (ev.source !== window.top) return;\n const d = ev && ev.data;\n if (!d || d.type !== FRAME_EVENT || !d.payload) return;\n const p = d.payload || {};\n if (p.kind !== 'iframeStopBarrierAck' || p.id !== id) return;\n cleanup(true);\n } catch {}\n };\n\n const t = setTimeout(() => cleanup(false), timeoutMs);\n try {\n window.addEventListener('message', onMessage, true);\n window.top.postMessage(\n { type: FRAME_EVENT, payload: { kind: 'iframeStopBarrier', id, href } },\n '*',\n );\n } catch {\n cleanup(false);\n }\n });\n }\n\n /**\n * Best-effort drain and flush on page navigation/close.\n * Called by pagehide/visibilitychange handlers.\n * Does not await - unload events are time-constrained.\n */\n _bestEffortDrainAndFlush() {\n if (!this.isRecording || this.isPaused) return;\n\n // Flush pending single click (dblclick detector) before we may be unloaded\n this._finalizePendingClick();\n\n // Cancel timers (unload may not wait for them)\n try {\n if (this.batchTimer) clearTimeout(this.batchTimer);\n this.batchTimer = null;\n if (this.scrollTimer) clearTimeout(this.scrollTimer);\n this.scrollTimer = null;\n } catch {}\n\n // Use unified commit and flush\n this._commitAndFlush({ bestEffort: true });\n }\n\n /**\n * Handle pagehide event - best-effort flush before navigation/close.\n */\n _onPageHide() {\n this._bestEffortDrainAndFlush();\n }\n\n /**\n * Handle visibilitychange event - flush when page becomes hidden.\n * This catches some cases that pagehide misses (e.g., tab switch before navigation).\n */\n _onVisibilityChange() {\n try {\n if (document.visibilityState === 'hidden') {\n this._bestEffortDrainAndFlush();\n }\n } catch {}\n }\n\n /**\n * Flush batched steps to background.\n * @returns {Promise} - Resolves when background acknowledges receipt\n */\n async _flush() {\n if (!this.batch.length) return true;\n\n // Clear force flush timer since we're flushing now\n this._clearForceFlushTimer();\n\n const steps = this.batch.map((s) => {\n // sanitize internal fields before sending to background\n const { _recordingRef, ...rest } = s || {};\n return rest;\n });\n this.batch.length = 0;\n return this._send({ kind: 'steps', steps });\n }\n\n /**\n * Send payload to background and wait for acknowledgment.\n * @param {Object} payload - The payload to send\n * @returns {Promise} - Resolves true if background acknowledged, false otherwise\n */\n _send(payload) {\n return new Promise((resolve) => {\n try {\n chrome.runtime.sendMessage({ type: 'rr_recorder_event', payload }, (response) => {\n // Check for runtime error (e.g., no receiver)\n if (chrome.runtime.lastError) {\n console.warn('Recorder: send failed', chrome.runtime.lastError.message);\n resolve(false);\n return;\n }\n resolve(response && response.ok);\n });\n } catch (e) {\n console.warn('Recorder: send exception', e);\n resolve(false);\n }\n });\n }\n\n _addVariable(key, sensitive, defVal) {\n if (!this.sessionBuffer.variables) this.sessionBuffer.variables = [];\n if (this.sessionBuffer.variables.find((v) => v.key === key)) return;\n this.sessionBuffer.variables.push({ key, sensitive: !!sensitive, default: defVal || '' });\n }\n\n // Handlers\n // Pending click state for dblclick detection\n _pendingClick = null;\n _pendingClickTimer = null;\n _DBLCLICK_THRESHOLD_MS = 300;\n\n _onClick(e) {\n if (!this.isRecording || this.isPaused) return;\n const el = e.target instanceof Element ? e.target : null;\n if (!el) return;\n try {\n if (el instanceof HTMLInputElement) {\n const t = (el.getAttribute && el.getAttribute('type')) || '';\n const tt = String(t).toLowerCase();\n if (tt === 'checkbox' || tt === 'radio') return; // avoid duplicate with change\n }\n const overlay = document.getElementById('__rr_rec_overlay');\n if (overlay && (el === overlay || (el.closest && el.closest('#__rr_rec_overlay')))) return;\n const a = el.closest && el.closest('a[href]');\n const href = a && a.getAttribute && a.getAttribute('href');\n const tgt = a && a.getAttribute && a.getAttribute('target');\n if (a && href && tgt && tgt.toLowerCase() === '_blank') {\n try {\n const abs = new URL(href, location.href).href;\n this._pushStep({ type: 'openTab', url: abs });\n this._pushStep({ type: 'switchTab', urlContains: abs });\n return;\n } catch (_) {\n this._pushStep({ type: 'openTab', url: href });\n this._pushStep({ type: 'switchTab', urlContains: href });\n return;\n }\n }\n } catch {}\n\n const target = SelectorEngine.buildTarget(el);\n try {\n const gref = SelectorEngine._ensureGlobalRef && SelectorEngine._ensureGlobalRef(el);\n if (gref) target.ref = gref;\n } catch {}\n\n // Double-click detection: if e.detail >= 2 means this is the second click of a dblclick\n if (e.detail >= 2) {\n // Cancel pending single click and record dblclick instead\n if (this._pendingClickTimer) {\n clearTimeout(this._pendingClickTimer);\n this._pendingClickTimer = null;\n }\n this._pendingClick = null;\n this._pushStep({\n type: 'dblclick',\n target,\n screenshotOnFail: true,\n });\n return;\n }\n\n // Single click: wait briefly to see if it becomes a dblclick\n // Cancel any previous pending click first\n if (this._pendingClickTimer) {\n clearTimeout(this._pendingClickTimer);\n // Flush previous pending click before starting new one\n if (this._pendingClick) {\n this._pushStep(this._pendingClick);\n }\n }\n\n this._pendingClick = {\n type: 'click',\n target,\n screenshotOnFail: true,\n };\n\n this._pendingClickTimer = setTimeout(() => {\n if (this._pendingClick) {\n this._pushStep(this._pendingClick);\n this._pendingClick = null;\n }\n this._pendingClickTimer = null;\n }, this._DBLCLICK_THRESHOLD_MS);\n }\n\n // Per-element input handler (attached on focusin for native inputs/textarea/contenteditable)\n _onInput(e) {\n if (!this.isRecording || this.isPaused) return;\n // Avoid mid-composition spam (IME): handle final committed value\n try {\n if (e && typeof e.isComposing === 'boolean' && e.isComposing) return;\n } catch {}\n const target = e.target;\n // Support input/textarea and contenteditable elements\n const el =\n target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement\n ? target\n : target &&\n target.nodeType === 1 &&\n /** @type {HTMLElement} */ (target).isContentEditable === true\n ? /** @type {HTMLElement} */ (target)\n : null;\n if (!el) return;\n this._handleInputForElement(el);\n }\n\n // Document-level input handler: supports composed events from Shadow DOM (custom elements)\n _onDocInput(e) {\n if (!this.isRecording || this.isPaused) return;\n try {\n if (e && typeof e.isComposing === 'boolean' && e.isComposing) return;\n } catch {}\n // Avoid double handling when per-element listener already attached to same element\n if (this._focusedEl && e.target === this._focusedEl) return;\n // Find the innermost editable element from composedPath\n const path = typeof e.composedPath === 'function' ? e.composedPath() : [];\n let el = null;\n for (let i = 0; i < path.length; i++) {\n const n = path[i];\n if (n instanceof HTMLInputElement || n instanceof HTMLTextAreaElement) {\n el = n;\n break;\n }\n // Also check for contenteditable\n if (n && n.nodeType === 1 && /** @type {HTMLElement} */ (n).isContentEditable === true) {\n el = /** @type {HTMLElement} */ (n);\n break;\n }\n }\n // As a fallback, walk down activeElement chain (deep active element via shadow roots)\n if (!el) {\n try {\n let ae = document.activeElement;\n let guard = 0;\n while (ae && guard++ < 10) {\n if (ae instanceof HTMLInputElement || ae instanceof HTMLTextAreaElement) {\n el = ae;\n break;\n }\n // Check contenteditable in shadow DOM traversal\n if (\n ae &&\n ae.nodeType === 1 &&\n /** @type {HTMLElement} */ (ae).isContentEditable === true\n ) {\n el = /** @type {HTMLElement} */ (ae);\n break;\n }\n const anyAe = ae;\n if (anyAe && anyAe.shadowRoot && anyAe.shadowRoot.activeElement) {\n ae = anyAe.shadowRoot.activeElement;\n continue;\n }\n break;\n }\n } catch {}\n }\n if (!el) return;\n this._handleInputForElement(el);\n }\n\n // Shared input processing logic (debounce/merge/sensitivity)\n // Uses Draft/Upsert model: updates are re-enqueued to ensure background gets final value\n _handleInputForElement(el) {\n try {\n const t = (el.getAttribute && el.getAttribute('type')) || '';\n const tt = String(t).toLowerCase();\n if (tt === 'checkbox' || tt === 'radio' || tt === 'file') return;\n } catch {}\n const elRef = this._getElRef(el);\n const target = SelectorEngine.buildTarget(el);\n\n // Check if element is contenteditable\n const isContentEditable =\n el.nodeType === 1 && /** @type {HTMLElement} */ (el).isContentEditable === true;\n\n const isSensitive =\n this.hideInputValues ||\n (!isContentEditable &&\n CONFIG.SENSITIVE_INPUT_TYPES.has(\n ((el.getAttribute && el.getAttribute('type')) || '').toLowerCase(),\n ));\n\n // Get value: use .value for input/textarea, .innerText for contenteditable\n let value = isContentEditable\n ? /** @type {HTMLElement} */ (el).innerText || ''\n : el.value || '';\n if (isSensitive) {\n const varKey = el.name ? el.name : `var_${Math.random().toString(36).slice(2, 6)}`;\n this._addVariable(varKey, true, '');\n value = `{${varKey}}`;\n }\n const nowTs = Date.now();\n const last = this.lastFill.step;\n const sameRef = !!(last && last._recordingRef === elRef);\n const sameSelector = !!(\n last &&\n last.target &&\n last.target.selector &&\n target &&\n target.selector &&\n last.target.selector === target.selector\n );\n const within = nowTs - this.lastFill.ts <= CONFIG.INPUT_DEBOUNCE_MS;\n if ((sameRef || sameSelector) && within) {\n // Update existing step's value\n this.lastFill.step.value = value;\n this.sessionBuffer.meta.updatedAt = new Date().toISOString();\n this.lastFill.ts = nowTs;\n this.lastFill.el = el; // Keep DOM reference updated for finalize\n // Keep flush gate aligned to the latest keystroke\n this._updateInputActivity();\n // Re-enqueue the updated step for upsert (ensures background gets final value)\n this._enqueueForUpsert(this.lastFill.step);\n return;\n }\n const newStep = { type: 'fill', target, value, screenshotOnFail: true };\n newStep._recordingRef = elRef;\n this._pushStep(newStep);\n this.lastFill = { step: newStep, ts: nowTs, el: el };\n }\n\n /**\n * Enqueue a step for upsert - if step with same id exists in batch, update it.\n * This ensures the background receives the final value for fill steps.\n * In iframes, forwards to top window to maintain selector composition consistency.\n */\n _enqueueForUpsert(step) {\n if (!step || !step.id) return;\n\n // In iframes, forward upsert updates to top so we don't lose composed selectors.\n // The top window aggregates iframe steps and computes \"frame |> inner\" selectors.\n // If iframe sends directly to background, it would overwrite the composed selector.\n if (window !== window.top) {\n try {\n const payload = {\n kind: 'iframeStepUpsert',\n href: String(location && location.href ? location.href : ''),\n step,\n };\n window.top.postMessage({ type: FRAME_EVENT, payload }, '*');\n } catch {}\n return;\n }\n\n // Check if step already in batch\n const existingIdx = this.batch.findIndex((s) => s.id === step.id);\n if (existingIdx >= 0) {\n // Update existing entry in batch\n this.batch[existingIdx] = step;\n } else {\n // Add to batch (step was already flushed, so we need to send update)\n this.batch.push(step);\n }\n\n // Schedule flush with appropriate delay (respects typing gate)\n this._scheduleFlush();\n }\n\n _onChange(e) {\n if (!this.isRecording || this.isPaused) return;\n const el = e.target;\n if (el instanceof HTMLSelectElement) {\n const val = el.value;\n const nowTs = Date.now();\n const elRef = this._getElRef(el);\n const sameRef = !!(this.lastFill.step && this.lastFill.step._recordingRef === elRef);\n const within = nowTs - this.lastFill.ts <= CONFIG.INPUT_DEBOUNCE_MS;\n if (sameRef && within) {\n this.lastFill.step.value = val;\n this.sessionBuffer.meta.updatedAt = new Date().toISOString();\n this.lastFill.ts = nowTs;\n this.lastFill.el = el; // Keep DOM reference updated\n // Re-enqueue for upsert\n this._enqueueForUpsert(this.lastFill.step);\n return;\n }\n const target = SelectorEngine.buildTarget(el);\n try {\n const gref = SelectorEngine._ensureGlobalRef && SelectorEngine._ensureGlobalRef(el);\n if (gref) target.ref = gref;\n } catch {}\n const st = { type: 'fill', target, value: val, screenshotOnFail: true };\n st._recordingRef = elRef;\n this._pushStep(st);\n this.lastFill = { step: st, ts: nowTs, el: el };\n return;\n }\n if (el instanceof HTMLInputElement) {\n const t = (el.getAttribute && el.getAttribute('type')) || '';\n const tt = String(t).toLowerCase();\n const target = SelectorEngine.buildTarget(el);\n try {\n const gref = SelectorEngine._ensureGlobalRef && SelectorEngine._ensureGlobalRef(el);\n if (gref) target.ref = gref;\n } catch {}\n const elRef = this._getElRef(el);\n if (tt === 'checkbox') {\n const st = { type: 'fill', target, value: !!el.checked, screenshotOnFail: true };\n st._recordingRef = elRef;\n this._pushStep(st);\n return;\n }\n if (tt === 'radio') {\n const st = { type: 'fill', target, value: true, screenshotOnFail: true };\n st._recordingRef = elRef;\n this._pushStep(st);\n return;\n }\n if (tt === 'file') {\n const varKey = el.name ? el.name : `file_${Math.random().toString(36).slice(2, 6)}`;\n this._addVariable(varKey, false, '');\n this._pushStep({ type: 'fill', target, value: `{${varKey}}`, screenshotOnFail: true });\n return;\n }\n }\n }\n\n _getElRef(el) {\n try {\n let ref = this.el2ref.get(el);\n if (ref) return ref;\n ref = `ref_${++this.refCounter}`;\n this.el2ref.set(el, ref);\n return ref;\n } catch {\n // Fallback to timestamp-based ref if WeakMap fails (should not happen)\n return `ref_${Date.now()}`;\n }\n }\n\n // UI handled by injected UI class\n\n _onFocusIn(e) {\n if (!this.isRecording || this.isPaused) return;\n const el = e.target;\n const isEditable =\n el instanceof HTMLInputElement ||\n el instanceof HTMLTextAreaElement ||\n (el && el.nodeType === 1 && /** @type {HTMLElement} */ (el).isContentEditable === true);\n if (!isEditable) return;\n if (this._focusedEl && this._focusedEl !== el)\n this._focusedEl.removeEventListener('input', this._onInput, true);\n el.addEventListener('input', this._onInput, true);\n this._focusedEl = el;\n }\n\n _onFocusOut(e) {\n const el = e.target;\n if (!el) return;\n if (this._focusedEl === el) {\n // Commit point: leaving an input field - finalize and flush pending input\n // This ensures we don't lose values when user tabs away or clicks elsewhere\n this._commitAndFlush();\n el.removeEventListener('input', this._onInput, true);\n this._focusedEl = null;\n }\n }\n\n _onMouseMove(e) {\n if (!this.highlightEnabled || !this.ui._box || !this.isRecording || this.isPaused) return;\n if (this.hoverRAF) return;\n const el = e.target instanceof Element ? e.target : null;\n if (!el) return;\n this.hoverRAF = requestAnimationFrame(() => {\n try {\n const r = el.getBoundingClientRect();\n Object.assign(this.ui._box.style, {\n left: `${Math.round(r.left)}px`,\n top: `${Math.round(r.top)}px`,\n width: `${Math.round(Math.max(0, r.width))}px`,\n height: `${Math.round(Math.max(0, r.height))}px`,\n display: r.width > 0 && r.height > 0 ? 'block' : 'none',\n });\n } catch {}\n this.hoverRAF = 0;\n });\n }\n\n _onScroll(e) {\n if (!this.isRecording || this.isPaused) return;\n try {\n const overlay = document.getElementById('__rr_rec_overlay');\n if (overlay) {\n // Use composedPath for shadow DOM compatibility, fallback to target\n const path = typeof e.composedPath === 'function' ? e.composedPath() : [e.target];\n for (const element of path) {\n // If the event path contains our overlay, ignore this scroll event\n if (element === overlay) {\n return;\n }\n }\n }\n } catch {\n // ignore\n }\n // Determine scroll source and positions\n const isDoc = e.target === document;\n const el = isDoc ? document.documentElement : e.target instanceof Element ? e.target : null;\n if (!el) return;\n let top = 0,\n left = 0;\n try {\n if (isDoc) {\n top =\n typeof window.scrollY === 'number'\n ? window.scrollY\n : document.documentElement.scrollTop || 0;\n left =\n typeof window.scrollX === 'number'\n ? window.scrollX\n : document.documentElement.scrollLeft || 0;\n } else {\n top = el.scrollTop || 0;\n left = el.scrollLeft || 0;\n }\n } catch {}\n const target = isDoc ? null : SelectorEngine.buildTarget(el);\n // Debounce/coalesce\n this._scrollPending = { isDoc, target, top, left };\n if (this.scrollTimer) {\n clearTimeout(this.scrollTimer);\n }\n this.scrollTimer = setTimeout(() => {\n this.scrollTimer = null;\n const pending = this._scrollPending;\n this._scrollPending = null;\n if (!pending) return;\n const { isDoc: pDoc, target: pTarget, top: pTop, left: pLeft } = pending;\n // Try merge with last step\n const steps = this.sessionBuffer.steps;\n const last = steps.length ? steps[steps.length - 1] : null;\n if (last && last.type === 'scroll') {\n const sameDoc = pDoc && !last.target && last.mode === 'offset';\n const sameEl =\n !pDoc &&\n last.target &&\n last.target.selector &&\n pTarget &&\n last.target.selector === pTarget.selector &&\n last.mode === 'container';\n if (sameDoc || sameEl) {\n last.offset = { y: pTop, x: pLeft };\n this.sessionBuffer.meta.updatedAt = new Date().toISOString();\n return;\n }\n }\n // New scroll step\n if (pDoc) {\n this._pushStep({\n type: 'scroll',\n mode: 'offset',\n offset: { y: pTop, x: pLeft },\n screenshotOnFail: false,\n });\n } else {\n this._pushStep({\n type: 'scroll',\n mode: 'container',\n target: pTarget,\n offset: { y: pTop, x: pLeft },\n screenshotOnFail: false,\n });\n }\n }, CONFIG.SCROLL_DEBOUNCE_MS);\n }\n\n // Minimal key recorder: record Enter and modifier combos; avoid plain typing\n _onKeyDown(e) {\n if (!this.isRecording || this.isPaused) return;\n try {\n // Ignore autorepeat to prevent spam\n if (e.repeat) return;\n const key = String(e.key || '').toLowerCase();\n const isModifier = key === 'shift' || key === 'control' || key === 'meta' || key === 'alt';\n const isEditable =\n e.target instanceof HTMLInputElement ||\n e.target instanceof HTMLTextAreaElement ||\n (e.target &&\n e.target.nodeType === 1 &&\n /** @type {HTMLElement} */ (e.target).isContentEditable === true);\n const enterKey = key === 'enter';\n\n // Track pressed modifiers\n if (isModifier) this._pressed.add(key);\n\n // Handle Enter in editable contexts (including contenteditable)\n if (isEditable && enterKey) {\n // Commit point: Enter may trigger form submission/navigation\n // Record explicit key action with target first\n const target = SelectorEngine.buildTarget(/** @type {Element} */ (e.target));\n const combo = this._formatKeysCombo(e, 'Enter');\n this._pushStep({ type: 'key', keys: combo, target, screenshotOnFail: false });\n\n // Then commit and flush (form submit may navigate away)\n this._commitAndFlush();\n\n this._lastKeyTs = Date.now();\n return;\n }\n\n // For non-text fields: record modifier combos and special keys\n const special = enterKey || key === 'escape' || key === 'tab';\n if (special || e.ctrlKey || e.metaKey || e.altKey || e.shiftKey) {\n const comboName = this._formatKeysCombo(e, e.key);\n this._pushStep({ type: 'key', keys: comboName, screenshotOnFail: false });\n this._lastKeyTs = Date.now();\n }\n } catch {}\n }\n\n _onKeyUp(e) {\n const key = String(e.key || '').toLowerCase();\n if (key === 'shift' || key === 'control' || key === 'meta' || key === 'alt')\n this._pressed.delete(key);\n }\n\n _formatKeysCombo(e, mainKey) {\n const parts = [];\n if (e.ctrlKey) parts.push('Ctrl');\n if (e.altKey) parts.push('Alt');\n if (e.shiftKey) parts.push('Shift');\n if (e.metaKey) parts.push('Meta');\n const mk = String(mainKey || '').trim();\n // Normalize common names to match keyboard-helper parsing\n const norm = (s) => {\n const k = s.toLowerCase();\n if (k === 'escape') return 'Esc';\n if (k === ' ') return 'Space';\n if (k.length === 1) return k.toUpperCase();\n return s;\n };\n parts.push(norm(mk));\n return parts.join('+');\n }\n\n // Top-level aggregator: receives iframe events and merges into session\n _onWindowMessage(ev) {\n try {\n const d = ev && ev.data;\n if (!d || d.type !== FRAME_EVENT || !d.payload) return;\n\n // Security: validate message source is from a known iframe in our page\n // ev.source must match contentWindow of an iframe element we control\n let frameEl = null;\n try {\n const frames = document.querySelectorAll('iframe,frame');\n for (let i = 0; i < frames.length; i++) {\n const f = frames[i];\n if (f && f.contentWindow === ev.source) {\n frameEl = f;\n break;\n }\n }\n } catch {}\n\n // Reject messages not from a recognized iframe in our document\n if (!frameEl) {\n // Message source is not from a child iframe we control - ignore\n return;\n }\n\n // Additional origin check: only accept from same origin or about:blank iframes\n // (cross-origin iframes legitimately send from their origin)\n try {\n const selfOrigin = window.location.origin;\n const msgOrigin = ev.origin;\n // Allow same-origin, null (for sandboxed iframes), or if iframe src is same-origin\n const frameSrc = frameEl.getAttribute('src') || '';\n let iframeSameOrigin = false;\n try {\n if (!frameSrc || frameSrc === 'about:blank') {\n iframeSameOrigin = true;\n } else {\n const frameUrl = new URL(frameSrc, selfOrigin);\n iframeSameOrigin = frameUrl.origin === selfOrigin;\n }\n } catch {\n // Invalid URL - assume cross-origin\n }\n // If iframe is same-origin, message origin should match\n if (iframeSameOrigin && msgOrigin !== selfOrigin && msgOrigin !== 'null') {\n return; // Origin mismatch for same-origin iframe - suspicious\n }\n } catch {}\n\n const payload = d.payload || {};\n const kind = payload.kind;\n\n // Stop barrier sync: ACK back to the iframe so it can finish stop only after\n // its final postMessages have been processed by the top aggregator\n if (kind === 'iframeStopBarrier') {\n try {\n const id = payload.id;\n if (id && ev.source && typeof ev.source.postMessage === 'function') {\n ev.source.postMessage(\n { type: FRAME_EVENT, payload: { kind: 'iframeStopBarrierAck', id } },\n '*',\n );\n }\n } catch {}\n return;\n }\n\n // Handle iframe flush request: immediately flush top's aggregated buffer\n if (kind === 'iframeFlush') {\n this._lastInputActivityTs = 0;\n this._typingBurstStartTs = 0;\n this._clearForceFlushTimer();\n if (this.batchTimer) clearTimeout(this.batchTimer);\n this.batchTimer = null;\n if (this.batch.length > 0) this._flush();\n return;\n }\n\n const { step, href } = payload;\n if (!step || typeof step !== 'object') return;\n\n // Compose frame selector for iframe steps\n const frameTarget = SelectorEngine.buildTarget(frameEl);\n const frameSel = frameTarget?.selector || '';\n\n // For upsert: find existing step in session and update it\n if (kind === 'iframeStepUpsert') {\n // Update input activity for iframe fills (enables flush gate for iframe input)\n if (step.type === 'fill') {\n this._updateInputActivity();\n }\n\n // Find step by id in session buffer and update its value\n const existingIdx = this.sessionBuffer.steps.findIndex((s) => s.id === step.id);\n if (existingIdx >= 0) {\n // Update value but preserve the composed selector\n this.sessionBuffer.steps[existingIdx].value = step.value;\n this.sessionBuffer.meta.updatedAt = new Date().toISOString();\n // Also update in batch if present\n const batchIdx = this.batch.findIndex((s) => s.id === step.id);\n if (batchIdx >= 0) {\n this.batch[batchIdx].value = step.value;\n } else {\n // Step was already flushed, add updated version to batch\n const updatedStep = { ...this.sessionBuffer.steps[existingIdx] };\n this.batch.push(updatedStep);\n }\n this._scheduleFlush();\n }\n return;\n }\n\n // Regular iframe step: compose composite selector and push\n if (step.target) {\n const inner = String(step.target.selector || '').trim();\n if (frameSel && inner) {\n const composite = `${frameSel} |> ${inner}`;\n step.target.selector = composite;\n if (Array.isArray(step.target.candidates)) {\n step.target.candidates.unshift({ type: 'css', value: composite });\n }\n }\n }\n this._pushStep(step);\n } catch {}\n }\n }\n\n // ================================================================\n // 3) SINGLETON + MESSAGE HANDLERS\n // ================================================================\n let recorderInstance = null;\n function getRecorder() {\n if (!recorderInstance) recorderInstance = new ContentRecorder();\n return recorderInstance;\n }\n\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n try {\n if (!request || !request.action) return false;\n if (request.action === 'rr_timeline_update') {\n const rec = getRecorder();\n // Only respond to timeline updates when recording is active\n if (!rec.isRecording) {\n sendResponse({ ok: true, ignored: true });\n return true;\n }\n // Replace entire timeline to avoid divergence across tabs\n const steps = Array.isArray(request.steps) ? request.steps : [];\n rec.ui.applyTimelineUpdate(steps);\n sendResponse({ ok: true });\n return true;\n }\n if (request.action === 'rr_recorder_control') {\n const rec = getRecorder();\n const cmd = request.cmd;\n if (cmd === 'start') {\n rec.start(request.meta || {});\n sendResponse({ success: true });\n return true;\n }\n if (cmd === 'pause') {\n rec.pause();\n sendResponse({ success: true });\n return true;\n }\n if (cmd === 'resume') {\n rec.resume();\n sendResponse({ success: true });\n return true;\n }\n if (cmd === 'stop') {\n // Stop is now async - flush all data and wait for ack before responding\n rec\n .stop()\n .then((result) => {\n sendResponse({ success: true, ack: result.ack, stats: result });\n })\n .catch((err) => {\n sendResponse({ success: false, ack: false, error: String(err) });\n });\n return true; // Keep channel open for async response\n }\n sendResponse({ success: false, error: 'Unknown command' });\n return true;\n }\n // Handle direct stop message with ack (sent by recorder-manager)\n if (request.action === 'stop' && request.requireAck) {\n const rec = getRecorder();\n rec\n .stop()\n .then((result) => {\n sendResponse({ ack: result.ack, stats: result });\n })\n .catch(() => {\n sendResponse({ ack: false });\n });\n return true;\n }\n if (request.action === 'rr_recorder_ping') {\n sendResponse({ status: 'pong' });\n return false;\n }\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n return false;\n });\n\n console.log('Record & Replay recorder.js loaded');\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/screenshot-helper.js", "content": "/* eslint-disable */\n/**\n * Screenshot helper content script\n * Handles page preparation, scrolling, element positioning, etc.\n */\n\nif (window.__SCREENSHOT_HELPER_INITIALIZED__) {\n // Already initialized, skip\n} else {\n window.__SCREENSHOT_HELPER_INITIALIZED__ = true;\n\n // Save original styles\n let originalOverflowStyle = '';\n let hiddenFixedElements = [];\n\n /**\n * Get fixed/sticky positioned elements\n * @returns Array of fixed/sticky elements\n */\n function getFixedElements() {\n const fixed = [];\n\n document.querySelectorAll('*').forEach((el) => {\n const htmlEl = el;\n const style = window.getComputedStyle(htmlEl);\n if (style.position === 'fixed' || style.position === 'sticky') {\n // Filter out tiny or invisible elements, and elements that are part of the extension UI\n if (\n htmlEl.offsetWidth > 1 &&\n htmlEl.offsetHeight > 1 &&\n !htmlEl.id.startsWith('chrome-mcp-')\n ) {\n fixed.push({\n element: htmlEl,\n originalDisplay: htmlEl.style.display,\n originalVisibility: htmlEl.style.visibility,\n });\n }\n }\n });\n return fixed;\n }\n\n /**\n * Hide fixed/sticky elements\n */\n function hideFixedElements() {\n hiddenFixedElements = getFixedElements();\n hiddenFixedElements.forEach((item) => {\n item.element.style.display = 'none';\n });\n }\n\n /**\n * Restore fixed/sticky elements\n */\n function showFixedElements() {\n hiddenFixedElements.forEach((item) => {\n item.element.style.display = item.originalDisplay || '';\n });\n hiddenFixedElements = [];\n }\n\n // Listen for messages from the extension\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n // Respond to ping message\n if (request.action === 'chrome_screenshot_ping') {\n sendResponse({ status: 'pong' });\n return false; // Synchronous response\n }\n\n // Prepare page for capture\n else if (request.action === 'preparePageForCapture') {\n originalOverflowStyle = document.documentElement.style.overflow;\n document.documentElement.style.overflow = 'hidden'; // Hide main scrollbar\n if (request.options?.fullPage) {\n // Only hide fixed elements for full page to avoid flicker\n hideFixedElements();\n }\n // Give styles a moment to apply\n setTimeout(() => {\n sendResponse({ success: true });\n }, 50);\n return true; // Async response\n }\n\n // Get page details\n else if (request.action === 'getPageDetails') {\n const body = document.body;\n const html = document.documentElement;\n sendResponse({\n totalWidth: Math.max(\n body.scrollWidth,\n body.offsetWidth,\n html.clientWidth,\n html.scrollWidth,\n html.offsetWidth,\n ),\n totalHeight: Math.max(\n body.scrollHeight,\n body.offsetHeight,\n html.clientHeight,\n html.scrollHeight,\n html.offsetHeight,\n ),\n viewportWidth: window.innerWidth,\n viewportHeight: window.innerHeight,\n devicePixelRatio: window.devicePixelRatio || 1,\n currentScrollX: window.scrollX,\n currentScrollY: window.scrollY,\n });\n }\n\n // Get element details\n else if (request.action === 'getElementDetails') {\n const element = document.querySelector(request.selector);\n if (element) {\n element.scrollIntoView({ behavior: 'instant', block: 'nearest', inline: 'nearest' });\n setTimeout(() => {\n // Wait for scroll\n const rect = element.getBoundingClientRect();\n sendResponse({\n rect: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },\n devicePixelRatio: window.devicePixelRatio || 1,\n });\n }, 200); // Increased delay for scrollIntoView\n return true; // Async response\n } else {\n sendResponse({ error: `Element with selector \"${request.selector}\" not found.` });\n }\n return true; // Async response\n }\n\n // Scroll page\n else if (request.action === 'scrollPage') {\n window.scrollTo({ left: request.x, top: request.y, behavior: 'instant' });\n // Wait for scroll and potential reflows/lazy-loading\n setTimeout(() => {\n sendResponse({\n success: true,\n newScrollX: window.scrollX,\n newScrollY: window.scrollY,\n });\n }, request.scrollDelay || 300); // Configurable delay\n return true; // Async response\n }\n\n // Reset page\n else if (request.action === 'resetPageAfterCapture') {\n document.documentElement.style.overflow = originalOverflowStyle;\n showFixedElements();\n if (typeof request.scrollX !== 'undefined' && typeof request.scrollY !== 'undefined') {\n window.scrollTo({ left: request.scrollX, top: request.scrollY, behavior: 'instant' });\n }\n sendResponse({ success: true });\n }\n\n return false; // Synchronous response\n });\n}\n" }, { "path": "app/chrome-extension/inject-scripts/wait-helper.js", "content": "/* eslint-disable */\n// wait-helper.js\n// Listen for text appearance/disappearance in the current document using MutationObserver.\n// Returns a stable ref (compatible with accessibility-tree-helper) for the first matching element.\n\n(function () {\n if (window.__WAIT_HELPER_INITIALIZED__) return;\n window.__WAIT_HELPER_INITIALIZED__ = true;\n\n // Ensure ref mapping infra exists (compatible with accessibility-tree-helper.js)\n if (!window.__claudeElementMap) window.__claudeElementMap = {};\n if (!window.__claudeRefCounter) window.__claudeRefCounter = 0;\n\n function isVisible(el) {\n try {\n if (!(el instanceof Element)) return false;\n const style = getComputedStyle(el);\n if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0')\n return false;\n const rect = el.getBoundingClientRect();\n if (rect.width <= 0 || rect.height <= 0) return false;\n return true;\n } catch {\n return false;\n }\n }\n\n function normalize(str) {\n return String(str || '')\n .replace(/\\s+/g, ' ')\n .trim()\n .toLowerCase();\n }\n\n function matchesText(el, needle) {\n const t = normalize(needle);\n if (!t) return false;\n try {\n if (!isVisible(el)) return false;\n const aria = el.getAttribute('aria-label');\n if (aria && normalize(aria).includes(t)) return true;\n const title = el.getAttribute('title');\n if (title && normalize(title).includes(t)) return true;\n const alt = el.getAttribute('alt');\n if (alt && normalize(alt).includes(t)) return true;\n const placeholder = el.getAttribute('placeholder');\n if (placeholder && normalize(placeholder).includes(t)) return true;\n // input/textarea value\n if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {\n const value = el.value || el.getAttribute('value');\n if (value && normalize(value).includes(t)) return true;\n }\n const text = el.innerText || el.textContent || '';\n if (normalize(text).includes(t)) return true;\n } catch {}\n return false;\n }\n\n function findElementByText(text) {\n // Fast path: query common interactive elements first\n const prioritized = Array.from(\n document.querySelectorAll('a,button,input,textarea,select,label,summary,[role]'),\n );\n for (const el of prioritized) if (matchesText(el, text)) return el;\n\n // Fallback: broader scan with cap to avoid blocking on huge pages\n const walker = document.createTreeWalker(\n document.body || document.documentElement,\n NodeFilter.SHOW_ELEMENT,\n );\n let count = 0;\n while (walker.nextNode()) {\n const el = /** @type {Element} */ (walker.currentNode);\n if (matchesText(el, text)) return el;\n if (++count > 5000) break; // Hard cap to avoid long scans\n }\n return null;\n }\n\n function ensureRefForElement(el) {\n // Try to reuse an existing ref\n for (const k in window.__claudeElementMap) {\n const weak = window.__claudeElementMap[k];\n if (weak && typeof weak.deref === 'function' && weak.deref() === el) return k;\n }\n const refId = `ref_${++window.__claudeRefCounter}`;\n window.__claudeElementMap[refId] = new WeakRef(el);\n return refId;\n }\n\n function centerOf(el) {\n const r = el.getBoundingClientRect();\n return { x: Math.round(r.left + r.width / 2), y: Math.round(r.top + r.height / 2) };\n }\n\n function waitFor({ text, appear = true, timeout = 5000 }) {\n return new Promise((resolve) => {\n const start = Date.now();\n let resolved = false;\n\n const check = () => {\n try {\n const match = findElementByText(text);\n if (appear) {\n if (match) {\n const ref = ensureRefForElement(match);\n const center = centerOf(match);\n done({ success: true, matched: { ref, center }, tookMs: Date.now() - start });\n }\n } else {\n // wait for disappearance\n if (!match) {\n done({ success: true, matched: null, tookMs: Date.now() - start });\n }\n }\n } catch {}\n };\n\n const done = (result) => {\n if (resolved) return;\n resolved = true;\n obs && obs.disconnect();\n clearTimeout(timer);\n resolve(result);\n };\n\n const obs = new MutationObserver(() => check());\n try {\n obs.observe(document.documentElement || document.body, {\n subtree: true,\n childList: true,\n characterData: true,\n attributes: true,\n });\n } catch {}\n\n // Initial check\n check();\n const timer = setTimeout(\n () => {\n done({ success: false, reason: 'timeout', tookMs: Date.now() - start });\n },\n Math.max(0, timeout),\n );\n });\n }\n\n function waitForSelector({ selector, visible = true, timeout = 5000 }) {\n return new Promise((resolve) => {\n const start = Date.now();\n let resolved = false;\n\n const isMatch = () => {\n try {\n const el = document.querySelector(selector);\n if (!el) return null;\n if (!visible) return el;\n return isVisible(el) ? el : null;\n } catch {\n return null;\n }\n };\n\n const done = (result) => {\n if (resolved) return;\n resolved = true;\n obs && obs.disconnect();\n clearTimeout(timer);\n resolve(result);\n };\n\n const check = () => {\n const el = isMatch();\n if (el) {\n const ref = ensureRefForElement(el);\n const center = centerOf(el);\n done({ success: true, matched: { ref, center }, tookMs: Date.now() - start });\n }\n };\n\n const obs = new MutationObserver(check);\n try {\n obs.observe(document.documentElement || document.body, {\n subtree: true,\n childList: true,\n characterData: true,\n attributes: true,\n });\n } catch {}\n\n // initial check\n check();\n const timer = setTimeout(\n () => done({ success: false, reason: 'timeout', tookMs: Date.now() - start }),\n Math.max(0, timeout),\n );\n });\n }\n\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n try {\n if (request && request.action === 'wait_helper_ping') {\n sendResponse({ status: 'pong' });\n return false;\n }\n if (request && request.action === 'waitForText') {\n const text = String(request.text || '').trim();\n const appear = request.appear !== false; // default true\n const timeout = Number(request.timeout || 5000);\n if (!text) {\n sendResponse({ success: false, error: 'text is required' });\n return true;\n }\n waitFor({ text, appear, timeout }).then((res) => sendResponse(res));\n return true; // async\n }\n if (request && request.action === 'waitForSelector') {\n const selector = String(request.selector || '').trim();\n const visible = request.visible !== false; // default true\n const timeout = Number(request.timeout || 5000);\n if (!selector) {\n sendResponse({ success: false, error: 'selector is required' });\n return true;\n }\n waitForSelector({ selector, visible, timeout }).then((res) => sendResponse(res));\n return true; // async\n }\n } catch (e) {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n return true;\n }\n return false;\n });\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/web-editor.js", "content": "/* eslint-disable */\n\n(() => {\n const GLOBAL_KEY = '__MCP_WEB_EDITOR__';\n if (window[GLOBAL_KEY]) return;\n\n const IS_MAIN = window === window.top;\n const COLORS = {\n hover: '#3b82f6', // blue-500\n selected: '#22c55e', // green-500\n backdrop: 'rgba(15, 23, 42, 0.15)', // slate-900 @ 15%\n };\n\n const clamp = (v, min, max) => Math.min(max, Math.max(min, v));\n\n const normalizeTextSnippet = (value, maxLen) => {\n return String(value || '')\n .replace(/\\s+/g, ' ')\n .trim()\n .slice(0, maxLen || 80);\n };\n\n const containsPoint = (rect, x, y) => {\n if (!rect) return false;\n return x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom;\n };\n\n const getElementLabel = (el) => {\n if (!(el instanceof Element)) return '';\n const tag = String(el.tagName || '').toLowerCase();\n const id = el.id ? `#${el.id}` : '';\n const classes =\n el.classList && el.classList.length\n ? `.${Array.from(el.classList).slice(0, 3).join('.')}`\n : '';\n return `${tag}${id}${classes}`;\n };\n\n const detectTailwind = (classes) => {\n try {\n const patterns = [\n /^bg-/,\n /^text-/,\n /^p[trblxy]?-/,\n /^m[trblxy]?-/,\n /^flex$/,\n /^grid$/,\n /^items-/,\n /^justify-/,\n /^gap-/,\n /^rounded/,\n /^shadow/,\n /^border/,\n ];\n for (const cls of classes || []) {\n if (patterns.some((p) => p.test(cls))) return true;\n }\n } catch {}\n return false;\n };\n\n const findReactFileFromFiber = (fiber) => {\n try {\n let current = fiber;\n for (let i = 0; i < 40 && current; i++) {\n const src = current._debugSource;\n if (src && src.fileName && typeof src.fileName === 'string') return src.fileName;\n const owner = current._debugOwner;\n const ownerSrc = owner && owner._debugSource;\n if (ownerSrc && ownerSrc.fileName && typeof ownerSrc.fileName === 'string')\n return ownerSrc.fileName;\n current = current.return;\n }\n } catch {}\n return '';\n };\n\n const findReactSourceFile = (el) => {\n try {\n let node = el;\n for (let depth = 0; depth < 15 && node; depth++) {\n const keys = Object.keys(node);\n for (const k of keys) {\n if (k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$')) {\n const fiber = node[k];\n const found = findReactFileFromFiber(fiber);\n if (found) return found;\n }\n }\n node = node.parentElement;\n }\n } catch {}\n return '';\n };\n\n const findVueSourceFile = (el) => {\n try {\n let node = el;\n for (let depth = 0; depth < 15 && node; depth++) {\n const inst = node.__vueParentComponent;\n if (inst && inst.type && inst.type.__file) return String(inst.type.__file);\n node = node.parentElement;\n }\n } catch {}\n return '';\n };\n\n const resolveTargetFile = (el) => {\n try {\n let node = el;\n for (let depth = 0; depth < 20 && node; depth++) {\n const reactFile = findReactSourceFile(node);\n if (reactFile && !reactFile.includes('node_modules')) return reactFile;\n const vueFile = findVueSourceFile(node);\n if (vueFile && !vueFile.includes('node_modules')) return vueFile;\n node = node.parentElement;\n }\n } catch {}\n return '';\n };\n\n const findMeaningfulElement = (el, clientX, clientY) => {\n try {\n let current = el instanceof Element ? el : null;\n for (let i = 0; i < 8 && current; i++) {\n const tag = String(current.tagName || '').toUpperCase();\n if (tag === 'HTML' || tag === 'BODY') {\n const deeper = document.elementFromPoint(clientX, clientY);\n if (deeper && deeper !== current && deeper instanceof Element) {\n current = deeper;\n continue;\n }\n return current;\n }\n\n let style;\n try {\n style = window.getComputedStyle(current);\n } catch {\n return current;\n }\n\n const bg = String(style.backgroundColor || '').toLowerCase();\n const isTransparentBg = bg === 'transparent' || bg === 'rgba(0, 0, 0, 0)';\n const borderWidth = [\n style.borderTopWidth,\n style.borderRightWidth,\n style.borderBottomWidth,\n style.borderLeftWidth,\n ]\n .map((x) => String(x || '0px'))\n .join(',');\n const hasBorder = borderWidth !== '0px,0px,0px,0px';\n\n if (!isTransparentBg || hasBorder) return current;\n\n const rect = current.getBoundingClientRect();\n if (!rect || rect.width <= 0 || rect.height <= 0) return current;\n\n let bestChild = null;\n let bestArea = Infinity;\n const children = Array.from(current.children || []);\n for (const child of children) {\n if (!(child instanceof Element)) continue;\n const r = child.getBoundingClientRect();\n if (!r || r.width <= 0 || r.height <= 0) continue;\n if (!containsPoint(r, clientX, clientY)) continue;\n const area = r.width * r.height;\n if (area < bestArea) {\n bestArea = area;\n bestChild = child;\n }\n }\n\n if (!bestChild) return current;\n\n const childRect = bestChild.getBoundingClientRect();\n const sameSize =\n Math.abs(rect.width - childRect.width) < 2 &&\n Math.abs(rect.height - childRect.height) < 2;\n if (!sameSize) return current;\n\n current = bestChild;\n }\n } catch {}\n return el instanceof Element ? el : null;\n };\n\n const createToastHost = () => {\n const host = document.createElement('div');\n Object.assign(host.style, {\n position: 'fixed',\n left: '12px',\n bottom: '12px',\n zIndex: 2147483647,\n display: 'flex',\n flexDirection: 'column',\n gap: '8px',\n pointerEvents: 'none',\n });\n return host;\n };\n\n const showToast = (state, message, kind) => {\n try {\n if (!state.toastHost) return;\n const item = document.createElement('div');\n const bg =\n kind === 'error'\n ? 'rgba(220, 38, 38, 0.92)'\n : kind === 'success'\n ? 'rgba(22, 163, 74, 0.92)'\n : 'rgba(15, 23, 42, 0.92)';\n Object.assign(item.style, {\n background: bg,\n color: '#fff',\n padding: '8px 10px',\n borderRadius: '10px',\n fontSize: '12px',\n fontFamily: 'system-ui,-apple-system,Segoe UI,Roboto,Arial',\n boxShadow: '0 6px 18px rgba(0,0,0,0.22)',\n maxWidth: '340px',\n lineHeight: '1.35',\n });\n item.textContent = String(message || '');\n state.toastHost.appendChild(item);\n setTimeout(() => {\n try {\n item.remove();\n } catch {}\n }, 2800);\n } catch {}\n };\n\n const buildStyleMapFromInput = (raw) => {\n const out = {};\n const text = String(raw || '').trim();\n if (!text) return out;\n const parts = text\n .split(';')\n .map((s) => s.trim())\n .filter(Boolean);\n for (const part of parts) {\n const idx = part.indexOf(':');\n if (idx <= 0) continue;\n const key = part.slice(0, idx).trim();\n const value = part.slice(idx + 1).trim();\n if (!key || !value) continue;\n out[key] = value;\n }\n return out;\n };\n\n const applyInlineStyleMap = (el, styles) => {\n try {\n if (!(el instanceof Element)) return;\n const entries = Object.entries(styles || {});\n for (const [key, value] of entries) {\n if (!key || !value) continue;\n try {\n el.style.setProperty(key, value);\n } catch {}\n }\n } catch {}\n };\n\n const state = {\n active: false,\n root: null,\n canvas: null,\n ctx: null,\n raf: 0,\n dpr: 1,\n viewport: { w: 0, h: 0 },\n hoveredEl: null,\n selectedEl: null,\n hoverRect: null,\n selectedRect: null,\n toolbar: null,\n toastHost: null,\n inputText: '',\n inputStyle: '',\n lastPointer: { x: 0, y: 0 },\n };\n\n const ensureCanvas = () => {\n if (!state.canvas || !state.ctx) return;\n const dpr = window.devicePixelRatio || 1;\n const w = Math.max(1, window.innerWidth || document.documentElement.clientWidth || 1);\n const h = Math.max(1, window.innerHeight || document.documentElement.clientHeight || 1);\n if (state.viewport.w === w && state.viewport.h === h && Math.abs(state.dpr - dpr) < 0.01)\n return;\n state.dpr = dpr;\n state.viewport = { w, h };\n state.canvas.width = Math.round(w * dpr);\n state.canvas.height = Math.round(h * dpr);\n state.canvas.style.width = `${w}px`;\n state.canvas.style.height = `${h}px`;\n state.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);\n };\n\n const drawRect = (rect, color, dashed) => {\n if (!rect || !state.ctx) return;\n const ctx = state.ctx;\n const x = Math.round(rect.left) + 0.5;\n const y = Math.round(rect.top) + 0.5;\n const w = Math.max(0, Math.round(rect.width));\n const h = Math.max(0, Math.round(rect.height));\n if (w <= 0 || h <= 0) return;\n ctx.save();\n ctx.lineWidth = 2;\n ctx.strokeStyle = color;\n ctx.fillStyle = `${color}22`;\n if (dashed) ctx.setLineDash([6, 4]);\n ctx.beginPath();\n ctx.rect(x, y, w, h);\n ctx.fill();\n ctx.stroke();\n ctx.restore();\n };\n\n const draw = () => {\n if (!state.active || !state.ctx) return;\n ensureCanvas();\n const ctx = state.ctx;\n ctx.clearRect(0, 0, state.viewport.w, state.viewport.h);\n\n // Keep selected rect fresh in case HMR/layout changes.\n try {\n if (state.selectedEl && state.selectedEl instanceof Element) {\n state.selectedRect = state.selectedEl.getBoundingClientRect();\n }\n } catch {}\n try {\n if (state.hoveredEl && state.hoveredEl instanceof Element) {\n state.hoverRect = state.hoveredEl.getBoundingClientRect();\n }\n } catch {}\n\n drawRect(state.hoverRect, COLORS.hover, true);\n drawRect(state.selectedRect, COLORS.selected, false);\n\n // Keep toolbar anchored to the selected element.\n positionToolbar();\n };\n\n const tick = () => {\n if (!state.active) return;\n draw();\n state.raf = requestAnimationFrame(tick);\n };\n\n const isInToolbar = (target) => {\n try {\n if (!target || !(target instanceof Node)) return false;\n if (!state.toolbar) return false;\n return state.toolbar.contains(target);\n } catch {\n return false;\n }\n };\n\n const updateHover = (el, clientX, clientY) => {\n const picked = findMeaningfulElement(el, clientX, clientY);\n state.hoveredEl = picked;\n try {\n state.hoverRect = picked ? picked.getBoundingClientRect() : null;\n } catch {\n state.hoverRect = null;\n }\n };\n\n const positionToolbar = () => {\n try {\n if (!state.toolbar || !state.selectedRect) return;\n const pad = 10;\n const maxW = 420;\n const rect = state.selectedRect;\n const preferredLeft = clamp(\n Math.round(rect.left),\n pad,\n Math.max(pad, window.innerWidth - maxW - pad),\n );\n const preferredTop = Math.round(rect.top - 12);\n const top = preferredTop < 80 ? Math.round(rect.bottom + 12) : preferredTop;\n Object.assign(state.toolbar.style, {\n left: `${preferredLeft}px`,\n top: `${clamp(top, pad, Math.max(pad, window.innerHeight - 180))}px`,\n });\n } catch {}\n };\n\n const updateToolbarHeader = () => {\n try {\n if (!state.toolbar) return;\n const label = state.toolbar.querySelector('[data-role=\"label\"]');\n if (!label) return;\n label.textContent = state.selectedEl ? getElementLabel(state.selectedEl) : 'No selection';\n } catch {}\n };\n\n const buildApplyPayload = (instruction) => {\n const el = state.selectedEl;\n const tag = el && el.tagName ? String(el.tagName || '').toLowerCase() : 'unknown';\n const id = el && el.id ? String(el.id) : undefined;\n const classes = el && el.classList ? Array.from(el.classList).slice(0, 24) : [];\n const text = normalizeTextSnippet(el ? el.textContent : '', 96);\n const fingerprint = { tag, id, classes, text };\n const targetFile = el ? resolveTargetFile(el) : '';\n const hints = [];\n try {\n if (el) {\n const r = findReactSourceFile(el);\n const v = findVueSourceFile(el);\n if (r) hints.push('React');\n if (v) hints.push('Vue');\n }\n if (detectTailwind(classes)) hints.push('Tailwind');\n } catch {}\n return {\n pageUrl: String(location && location.href ? location.href : ''),\n targetFile: targetFile || undefined,\n fingerprint,\n techStackHint: hints.length ? hints : undefined,\n instruction,\n };\n };\n\n const onMouseMove = (e) => {\n if (!state.active) return;\n if (isInToolbar(e.target)) return;\n state.lastPointer = { x: e.clientX, y: e.clientY };\n const el = e.target instanceof Element ? e.target : null;\n if (!el) return;\n updateHover(el, e.clientX, e.clientY);\n };\n\n const onClick = (e) => {\n if (!state.active) return;\n if (isInToolbar(e.target)) return;\n try {\n e.preventDefault();\n e.stopPropagation();\n } catch {}\n const el = state.hoveredEl;\n if (!el) return;\n state.selectedEl = el;\n try {\n state.selectedRect = el.getBoundingClientRect();\n } catch {\n state.selectedRect = null;\n }\n updateToolbarHeader();\n positionToolbar();\n };\n\n const intercept = (e) => {\n if (!state.active) return;\n if (isInToolbar(e.target)) return;\n // Allow scroll/wheel to keep navigation usable in edit mode.\n if (e.type === 'wheel') return;\n try {\n e.preventDefault();\n e.stopPropagation();\n } catch {}\n };\n\n const onKeyDown = (e) => {\n if (!state.active) return;\n if (isInToolbar(e.target)) return;\n if (e.key === 'Escape') {\n try {\n e.preventDefault();\n e.stopPropagation();\n } catch {}\n stop();\n return;\n }\n };\n\n const buildToolbar = () => {\n const box = document.createElement('div');\n state.toolbar = box;\n Object.assign(box.style, {\n position: 'fixed',\n left: '12px',\n top: '12px',\n zIndex: 2147483647,\n pointerEvents: 'auto',\n width: 'min(420px, calc(100vw - 24px))',\n background: 'rgba(255,255,255,0.96)',\n border: '1px solid rgba(148, 163, 184, 0.6)',\n borderRadius: '12px',\n boxShadow: '0 10px 30px rgba(0,0,0,0.18)',\n fontFamily: 'system-ui,-apple-system,Segoe UI,Roboto,Arial',\n color: '#0f172a',\n overflow: 'hidden',\n });\n\n const header = document.createElement('div');\n Object.assign(header.style, {\n display: 'flex',\n alignItems: 'center',\n justifyContent: 'space-between',\n gap: '10px',\n padding: '10px 12px',\n background: 'rgba(248,250,252,0.9)',\n borderBottom: '1px solid rgba(148, 163, 184, 0.35)',\n });\n const label = document.createElement('div');\n label.setAttribute('data-role', 'label');\n Object.assign(label.style, {\n fontSize: '12px',\n fontWeight: '600',\n whiteSpace: 'nowrap',\n overflow: 'hidden',\n textOverflow: 'ellipsis',\n maxWidth: '280px',\n });\n label.textContent = 'Select an element';\n\n const btnExit = document.createElement('button');\n btnExit.textContent = 'Exit (Esc)';\n Object.assign(btnExit.style, {\n fontSize: '12px',\n padding: '6px 10px',\n borderRadius: '10px',\n border: '1px solid rgba(148,163,184,0.6)',\n background: '#fff',\n cursor: 'pointer',\n });\n btnExit.addEventListener('click', () => stop());\n\n header.appendChild(label);\n header.appendChild(btnExit);\n\n const body = document.createElement('div');\n Object.assign(body.style, {\n padding: '10px 12px 12px',\n display: 'flex',\n flexDirection: 'column',\n gap: '10px',\n });\n\n const mkRow = (titleText) => {\n const row = document.createElement('div');\n Object.assign(row.style, {\n display: 'flex',\n flexDirection: 'column',\n gap: '6px',\n });\n const title = document.createElement('div');\n title.textContent = titleText;\n Object.assign(title.style, { fontSize: '12px', fontWeight: '600', color: '#334155' });\n row.appendChild(title);\n return { row, title };\n };\n\n const mkActions = () => {\n const actions = document.createElement('div');\n Object.assign(actions.style, {\n display: 'flex',\n gap: '8px',\n alignItems: 'center',\n flexWrap: 'wrap',\n });\n return actions;\n };\n\n const mkButton = (text, variant) => {\n const btn = document.createElement('button');\n btn.textContent = text;\n const bg = variant === 'primary' ? '#0f172a' : '#fff';\n const color = variant === 'primary' ? '#fff' : '#0f172a';\n Object.assign(btn.style, {\n fontSize: '12px',\n padding: '7px 10px',\n borderRadius: '10px',\n border: '1px solid rgba(148,163,184,0.6)',\n background: bg,\n color,\n cursor: 'pointer',\n });\n return btn;\n };\n\n // Text edit\n const textRow = mkRow('Text');\n const textInput = document.createElement('input');\n textInput.type = 'text';\n textInput.placeholder = 'New text…';\n Object.assign(textInput.style, {\n width: '100%',\n padding: '8px 10px',\n borderRadius: '10px',\n border: '1px solid rgba(148,163,184,0.6)',\n fontSize: '12px',\n outline: 'none',\n });\n textInput.addEventListener('input', () => {\n state.inputText = textInput.value;\n });\n const textActions = mkActions();\n const btnApplyText = mkButton('Apply (DOM)', 'secondary');\n btnApplyText.addEventListener('click', () => {\n if (!state.selectedEl) return showToast(state, 'No selection', 'error');\n const v = String(state.inputText || '').trim();\n if (!v) return showToast(state, 'Text is empty', 'error');\n try {\n state.selectedEl.textContent = v;\n showToast(state, 'Text applied (DOM)', 'success');\n } catch {\n showToast(state, 'Failed to apply text', 'error');\n }\n });\n const btnSyncText = mkButton('Sync to Code', 'primary');\n btnSyncText.addEventListener('click', async () => {\n if (!state.selectedEl) return showToast(state, 'No selection', 'error');\n const v = String(state.inputText || '').trim();\n if (!v) return showToast(state, 'Text is empty', 'error');\n const payload = buildApplyPayload({\n type: 'update_text',\n description: `Set the element text to: ${JSON.stringify(v)}`,\n text: v,\n });\n try {\n const resp = await chrome.runtime.sendMessage({ type: 'web_editor_apply', payload });\n if (resp && resp.success) {\n showToast(state, `Agent accepted (requestId=${resp.requestId || 'n/a'})`, 'success');\n } else {\n showToast(state, resp?.error || 'Agent request failed', 'error');\n }\n } catch (err) {\n showToast(state, String(err && err.message ? err.message : err), 'error');\n }\n });\n textActions.appendChild(btnApplyText);\n textActions.appendChild(btnSyncText);\n textRow.row.appendChild(textInput);\n textRow.row.appendChild(textActions);\n\n // Style edit\n const styleRow = mkRow('Style (CSS declarations)');\n const styleInput = document.createElement('input');\n styleInput.type = 'text';\n styleInput.placeholder = 'e.g. background-color: #f3f4f6; padding: 12px';\n Object.assign(styleInput.style, {\n width: '100%',\n padding: '8px 10px',\n borderRadius: '10px',\n border: '1px solid rgba(148,163,184,0.6)',\n fontSize: '12px',\n outline: 'none',\n });\n styleInput.addEventListener('input', () => {\n state.inputStyle = styleInput.value;\n });\n const styleActions = mkActions();\n const btnApplyStyle = mkButton('Apply (DOM)', 'secondary');\n btnApplyStyle.addEventListener('click', () => {\n if (!state.selectedEl) return showToast(state, 'No selection', 'error');\n const map = buildStyleMapFromInput(state.inputStyle);\n const keys = Object.keys(map);\n if (!keys.length) return showToast(state, 'No valid declarations', 'error');\n applyInlineStyleMap(state.selectedEl, map);\n showToast(state, 'Style applied (DOM)', 'success');\n });\n const btnSyncStyle = mkButton('Sync to Code', 'primary');\n btnSyncStyle.addEventListener('click', async () => {\n if (!state.selectedEl) return showToast(state, 'No selection', 'error');\n const map = buildStyleMapFromInput(state.inputStyle);\n const keys = Object.keys(map);\n if (!keys.length) return showToast(state, 'No valid declarations', 'error');\n const decl = keys.map((k) => `${k}: ${map[k]}`).join('; ');\n const payload = buildApplyPayload({\n type: 'update_style',\n description: `Apply CSS declarations: ${decl}`,\n style: map,\n });\n try {\n const resp = await chrome.runtime.sendMessage({ type: 'web_editor_apply', payload });\n if (resp && resp.success) {\n showToast(state, `Agent accepted (requestId=${resp.requestId || 'n/a'})`, 'success');\n } else {\n showToast(state, resp?.error || 'Agent request failed', 'error');\n }\n } catch (err) {\n showToast(state, String(err && err.message ? err.message : err), 'error');\n }\n });\n styleActions.appendChild(btnApplyStyle);\n styleActions.appendChild(btnSyncStyle);\n styleRow.row.appendChild(styleInput);\n styleRow.row.appendChild(styleActions);\n\n body.appendChild(textRow.row);\n body.appendChild(styleRow.row);\n box.appendChild(header);\n box.appendChild(body);\n return box;\n };\n\n const start = () => {\n if (!IS_MAIN) return;\n if (state.active) return;\n state.active = true;\n\n const root = document.createElement('div');\n state.root = root;\n root.id = '__mcp_web_editor_root';\n Object.assign(root.style, {\n position: 'fixed',\n inset: '0',\n zIndex: 2147483647,\n pointerEvents: 'none',\n });\n\n const canvas = document.createElement('canvas');\n state.canvas = canvas;\n Object.assign(canvas.style, {\n position: 'fixed',\n inset: '0',\n width: '100%',\n height: '100%',\n pointerEvents: 'none',\n });\n root.appendChild(canvas);\n\n try {\n const ctx = canvas.getContext('2d');\n state.ctx = ctx;\n } catch {\n state.ctx = null;\n }\n\n const toolbar = buildToolbar();\n root.appendChild(toolbar);\n\n const toastHost = createToastHost();\n state.toastHost = toastHost;\n root.appendChild(toastHost);\n\n document.documentElement.appendChild(root);\n\n document.addEventListener('mousemove', onMouseMove, { capture: true, passive: true });\n document.addEventListener('click', onClick, true);\n document.addEventListener('mousedown', intercept, true);\n document.addEventListener('mouseup', intercept, true);\n document.addEventListener('dblclick', intercept, true);\n document.addEventListener('contextmenu', intercept, true);\n document.addEventListener('submit', intercept, true);\n document.addEventListener('keydown', onKeyDown, true);\n\n // Visual cue\n showToast(state, 'Web Editor: ON (Esc to exit)', 'info');\n\n // Start RAF\n state.raf = requestAnimationFrame(tick);\n };\n\n const stop = () => {\n if (!IS_MAIN) return;\n if (!state.active) return;\n state.active = false;\n\n try {\n if (state.raf) cancelAnimationFrame(state.raf);\n } catch {}\n state.raf = 0;\n\n try {\n document.removeEventListener('mousemove', onMouseMove, true);\n document.removeEventListener('click', onClick, true);\n document.removeEventListener('mousedown', intercept, true);\n document.removeEventListener('mouseup', intercept, true);\n document.removeEventListener('dblclick', intercept, true);\n document.removeEventListener('contextmenu', intercept, true);\n document.removeEventListener('submit', intercept, true);\n document.removeEventListener('keydown', onKeyDown, true);\n } catch {}\n\n try {\n state.root && state.root.remove();\n } catch {}\n\n state.root = null;\n state.canvas = null;\n state.ctx = null;\n state.hoveredEl = null;\n state.selectedEl = null;\n state.hoverRect = null;\n state.selectedRect = null;\n state.toolbar = null;\n state.toastHost = null;\n state.inputText = '';\n state.inputStyle = '';\n };\n\n const toggle = () => {\n if (!IS_MAIN) return false;\n if (state.active) {\n stop();\n return false;\n }\n start();\n return true;\n };\n\n // Expose minimal API for debugging\n window[GLOBAL_KEY] = {\n start,\n stop,\n toggle,\n getState: () => ({ active: state.active }),\n };\n\n // Message handler (background -> tab)\n chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {\n try {\n if (!IS_MAIN) return false;\n if (request && request.action === 'web_editor_ping') {\n sendResponse({ status: 'pong' });\n return false;\n }\n if (request && request.action === 'web_editor_toggle') {\n const active = toggle();\n sendResponse({ active });\n return true;\n }\n if (request && request.action === 'web_editor_start') {\n start();\n sendResponse({ active: true });\n return true;\n }\n if (request && request.action === 'web_editor_stop') {\n stop();\n sendResponse({ active: false });\n return true;\n }\n } catch (e) {\n try {\n sendResponse({ success: false, error: String(e && e.message ? e.message : e) });\n } catch {}\n return true;\n }\n return false;\n });\n})();\n" }, { "path": "app/chrome-extension/inject-scripts/web-fetcher-helper.js", "content": "/* eslint-disable */\n\nif (window.__WEB_FETCHER_HELPER_INITIALIZED__) {\n // Already initialized, skip\n} else {\n window.__WEB_FETCHER_HELPER_INITIALIZED__ = true;\n\n /*\n * Copyright (c) 2010 Arc90 Inc\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n /*\n * This code is heavily based on Arc90's readability.js (1.7.1) script\n * available at: http://code.google.com/p/arc90labs-readability\n */\n\n /**\n * Public constructor.\n * @param {HTMLDocument} doc The document to parse.\n * @param {Object} options The options object.\n */\n function Readability(doc, options) {\n // In some older versions, people passed a URI as the first argument. Cope:\n if (options && options.documentElement) {\n doc = options;\n options = arguments[2];\n } else if (!doc || !doc.documentElement) {\n throw new Error('First argument to Readability constructor should be a document object.');\n }\n options = options || {};\n\n this._doc = doc;\n this._docJSDOMParser = this._doc.firstChild.__JSDOMParser__;\n this._articleTitle = null;\n this._articleByline = null;\n this._articleDir = null;\n this._articleSiteName = null;\n this._attempts = [];\n this._metadata = {};\n\n // Configurable options\n this._debug = !!options.debug;\n this._maxElemsToParse = options.maxElemsToParse || this.DEFAULT_MAX_ELEMS_TO_PARSE;\n this._nbTopCandidates = options.nbTopCandidates || this.DEFAULT_N_TOP_CANDIDATES;\n this._charThreshold = options.charThreshold || this.DEFAULT_CHAR_THRESHOLD;\n this._classesToPreserve = this.CLASSES_TO_PRESERVE.concat(options.classesToPreserve || []);\n this._keepClasses = !!options.keepClasses;\n this._serializer =\n options.serializer ||\n function (el) {\n return el.innerHTML;\n };\n this._disableJSONLD = !!options.disableJSONLD;\n this._allowedVideoRegex = options.allowedVideoRegex || this.REGEXPS.videos;\n this._linkDensityModifier = options.linkDensityModifier || 0;\n\n // Start with all flags set\n this._flags =\n this.FLAG_STRIP_UNLIKELYS | this.FLAG_WEIGHT_CLASSES | this.FLAG_CLEAN_CONDITIONALLY;\n\n // Control whether log messages are sent to the console\n if (this._debug) {\n let logNode = function (node) {\n if (node.nodeType == node.TEXT_NODE) {\n return `${node.nodeName} (\"${node.textContent}\")`;\n }\n let attrPairs = Array.from(node.attributes || [], function (attr) {\n return `${attr.name}=\"${attr.value}\"`;\n }).join(' ');\n return `<${node.localName} ${attrPairs}>`;\n };\n this.log = function () {\n if (typeof console !== 'undefined') {\n let args = Array.from(arguments, (arg) => {\n if (arg && arg.nodeType == this.ELEMENT_NODE) {\n return logNode(arg);\n }\n return arg;\n });\n args.unshift('Reader: (Readability)');\n\n // Debug logging removed\n } else if (typeof dump !== 'undefined') {\n /* global dump */\n var msg = Array.prototype.map\n .call(arguments, function (x) {\n return x && x.nodeName ? logNode(x) : x;\n })\n .join(' ');\n dump('Reader: (Readability) ' + msg + '\\n');\n }\n };\n } else {\n this.log = function () {};\n }\n }\n\n Readability.prototype = {\n FLAG_STRIP_UNLIKELYS: 0x1,\n FLAG_WEIGHT_CLASSES: 0x2,\n FLAG_CLEAN_CONDITIONALLY: 0x4,\n\n // https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType\n ELEMENT_NODE: 1,\n TEXT_NODE: 3,\n\n // Max number of nodes supported by this parser. Default: 0 (no limit)\n DEFAULT_MAX_ELEMS_TO_PARSE: 0,\n\n // The number of top candidates to consider when analysing how\n // tight the competition is among candidates.\n DEFAULT_N_TOP_CANDIDATES: 5,\n\n // Element tags to score by default.\n DEFAULT_TAGS_TO_SCORE: 'section,h2,h3,h4,h5,h6,p,td,pre'.toUpperCase().split(','),\n\n // The default number of chars an article must have in order to return a result\n DEFAULT_CHAR_THRESHOLD: 500,\n\n // All of the regular expressions in use within readability.\n // Defined up here so we don't instantiate them repeatedly in loops.\n REGEXPS: {\n // NOTE: These two regular expressions are duplicated in\n // Readability-readerable.js. Please keep both copies in sync.\n unlikelyCandidates:\n /-ad-|ai2html|banner|breadcrumbs|combx|comment|community|cover-wrap|disqus|extra|footer|gdpr|header|legends|menu|related|remark|replies|rss|shoutbox|sidebar|skyscraper|social|sponsor|supplemental|ad-break|agegate|pagination|pager|popup|yom-remote/i,\n okMaybeItsACandidate: /and|article|body|column|content|main|shadow/i,\n\n positive:\n /article|body|content|entry|hentry|h-entry|main|page|pagination|post|text|blog|story/i,\n negative:\n /-ad-|hidden|^hid$| hid$| hid |^hid |banner|combx|comment|com-|contact|footer|gdpr|masthead|media|meta|outbrain|promo|related|scroll|share|shoutbox|sidebar|skyscraper|sponsor|shopping|tags|widget/i,\n extraneous:\n /print|archive|comment|discuss|e[\\-]?mail|share|reply|all|login|sign|single|utility/i,\n byline: /byline|author|dateline|writtenby|p-author/i,\n replaceFonts: /<(\\/?)font[^>]*>/gi,\n normalize: /\\s{2,}/g,\n videos:\n /\\/\\/(www\\.)?((dailymotion|youtube|youtube-nocookie|player\\.vimeo|v\\.qq)\\.com|(archive|upload\\.wikimedia)\\.org|player\\.twitch\\.tv)/i,\n shareElements: /(\\b|_)(share|sharedaddy)(\\b|_)/i,\n nextLink: /(next|weiter|continue|>([^\\|]|$)|»([^\\|]|$))/i,\n prevLink: /(prev|earl|old|new|<|«)/i,\n tokenize: /\\W+/g,\n whitespace: /^\\s*$/,\n hasContent: /\\S$/,\n hashUrl: /^#.+/,\n srcsetUrl: /(\\S+)(\\s+[\\d.]+[xw])?(\\s*(?:,|$))/g,\n b64DataUrl: /^data:\\s*([^\\s;,]+)\\s*;\\s*base64\\s*,/i,\n // Commas as used in Latin, Sindhi, Chinese and various other scripts.\n // see: https://en.wikipedia.org/wiki/Comma#Comma_variants\n commas: /\\u002C|\\u060C|\\uFE50|\\uFE10|\\uFE11|\\u2E41|\\u2E34|\\u2E32|\\uFF0C/g,\n // See: https://schema.org/Article\n jsonLdArticleTypes:\n /^Article|AdvertiserContentArticle|NewsArticle|AnalysisNewsArticle|AskPublicNewsArticle|BackgroundNewsArticle|OpinionNewsArticle|ReportageNewsArticle|ReviewNewsArticle|Report|SatiricalArticle|ScholarlyArticle|MedicalScholarlyArticle|SocialMediaPosting|BlogPosting|LiveBlogPosting|DiscussionForumPosting|TechArticle|APIReference$/,\n // used to see if a node's content matches words commonly used for ad blocks or loading indicators\n adWords: /^(ad(vertising|vertisement)?|pub(licité)?|werb(ung)?|广告|Реклама|Anuncio)$/iu,\n loadingWords: /^((loading|正在加载|Загрузка|chargement|cargando)(…|\\.\\.\\.)?)$/iu,\n },\n\n UNLIKELY_ROLES: [\n 'menu',\n 'menubar',\n 'complementary',\n 'navigation',\n 'alert',\n 'alertdialog',\n 'dialog',\n ],\n\n DIV_TO_P_ELEMS: new Set(['BLOCKQUOTE', 'DL', 'DIV', 'IMG', 'OL', 'P', 'PRE', 'TABLE', 'UL']),\n\n ALTER_TO_DIV_EXCEPTIONS: ['DIV', 'ARTICLE', 'SECTION', 'P', 'OL', 'UL'],\n\n PRESENTATIONAL_ATTRIBUTES: [\n 'align',\n 'background',\n 'bgcolor',\n 'border',\n 'cellpadding',\n 'cellspacing',\n 'frame',\n 'hspace',\n 'rules',\n 'style',\n 'valign',\n 'vspace',\n ],\n\n DEPRECATED_SIZE_ATTRIBUTE_ELEMS: ['TABLE', 'TH', 'TD', 'HR', 'PRE'],\n\n // The commented out elements qualify as phrasing content but tend to be\n // removed by readability when put into paragraphs, so we ignore them here.\n PHRASING_ELEMS: [\n // \"CANVAS\", \"IFRAME\", \"SVG\", \"VIDEO\",\n 'ABBR',\n 'AUDIO',\n 'B',\n 'BDO',\n 'BR',\n 'BUTTON',\n 'CITE',\n 'CODE',\n 'DATA',\n 'DATALIST',\n 'DFN',\n 'EM',\n 'EMBED',\n 'I',\n 'IMG',\n 'INPUT',\n 'KBD',\n 'LABEL',\n 'MARK',\n 'MATH',\n 'METER',\n 'NOSCRIPT',\n 'OBJECT',\n 'OUTPUT',\n 'PROGRESS',\n 'Q',\n 'RUBY',\n 'SAMP',\n 'SCRIPT',\n 'SELECT',\n 'SMALL',\n 'SPAN',\n 'STRONG',\n 'SUB',\n 'SUP',\n 'TEXTAREA',\n 'TIME',\n 'VAR',\n 'WBR',\n ],\n\n // These are the classes that readability sets itself.\n CLASSES_TO_PRESERVE: ['page'],\n\n // These are the list of HTML entities that need to be escaped.\n HTML_ESCAPE_MAP: {\n lt: '<',\n gt: '>',\n amp: '&',\n quot: '\"',\n apos: \"'\",\n },\n\n /**\n * Run any post-process modifications to article content as necessary.\n *\n * @param Element\n * @return void\n **/\n _postProcessContent(articleContent) {\n // Readability cannot open relative uris so we convert them to absolute uris.\n this._fixRelativeUris(articleContent);\n\n this._simplifyNestedElements(articleContent);\n\n if (!this._keepClasses) {\n // Remove classes.\n this._cleanClasses(articleContent);\n }\n },\n\n /**\n * Iterates over a NodeList, calls `filterFn` for each node and removes node\n * if function returned `true`.\n *\n * If function is not passed, removes all the nodes in node list.\n *\n * @param NodeList nodeList The nodes to operate on\n * @param Function filterFn the function to use as a filter\n * @return void\n */\n _removeNodes(nodeList, filterFn) {\n // Avoid ever operating on live node lists.\n if (this._docJSDOMParser && nodeList._isLiveNodeList) {\n throw new Error('Do not pass live node lists to _removeNodes');\n }\n for (var i = nodeList.length - 1; i >= 0; i--) {\n var node = nodeList[i];\n var parentNode = node.parentNode;\n if (parentNode) {\n if (!filterFn || filterFn.call(this, node, i, nodeList)) {\n parentNode.removeChild(node);\n }\n }\n }\n },\n\n /**\n * Iterates over a NodeList, and calls _setNodeTag for each node.\n *\n * @param NodeList nodeList The nodes to operate on\n * @param String newTagName the new tag name to use\n * @return void\n */\n _replaceNodeTags(nodeList, newTagName) {\n // Avoid ever operating on live node lists.\n if (this._docJSDOMParser && nodeList._isLiveNodeList) {\n throw new Error('Do not pass live node lists to _replaceNodeTags');\n }\n for (const node of nodeList) {\n this._setNodeTag(node, newTagName);\n }\n },\n\n /**\n * Iterate over a NodeList, which doesn't natively fully implement the Array\n * interface.\n *\n * For convenience, the current object context is applied to the provided\n * iterate function.\n *\n * @param NodeList nodeList The NodeList.\n * @param Function fn The iterate function.\n * @return void\n */\n _forEachNode(nodeList, fn) {\n Array.prototype.forEach.call(nodeList, fn, this);\n },\n\n /**\n * Iterate over a NodeList, and return the first node that passes\n * the supplied test function\n *\n * For convenience, the current object context is applied to the provided\n * test function.\n *\n * @param NodeList nodeList The NodeList.\n * @param Function fn The test function.\n * @return void\n */\n _findNode(nodeList, fn) {\n return Array.prototype.find.call(nodeList, fn, this);\n },\n\n /**\n * Iterate over a NodeList, return true if any of the provided iterate\n * function calls returns true, false otherwise.\n *\n * For convenience, the current object context is applied to the\n * provided iterate function.\n *\n * @param NodeList nodeList The NodeList.\n * @param Function fn The iterate function.\n * @return Boolean\n */\n _someNode(nodeList, fn) {\n return Array.prototype.some.call(nodeList, fn, this);\n },\n\n /**\n * Iterate over a NodeList, return true if all of the provided iterate\n * function calls return true, false otherwise.\n *\n * For convenience, the current object context is applied to the\n * provided iterate function.\n *\n * @param NodeList nodeList The NodeList.\n * @param Function fn The iterate function.\n * @return Boolean\n */\n _everyNode(nodeList, fn) {\n return Array.prototype.every.call(nodeList, fn, this);\n },\n\n _getAllNodesWithTag(node, tagNames) {\n if (node.querySelectorAll) {\n return node.querySelectorAll(tagNames.join(','));\n }\n return [].concat.apply(\n [],\n tagNames.map(function (tag) {\n var collection = node.getElementsByTagName(tag);\n return Array.isArray(collection) ? collection : Array.from(collection);\n }),\n );\n },\n\n /**\n * Removes the class=\"\" attribute from every element in the given\n * subtree, except those that match CLASSES_TO_PRESERVE and\n * the classesToPreserve array from the options object.\n *\n * @param Element\n * @return void\n */\n _cleanClasses(node) {\n var classesToPreserve = this._classesToPreserve;\n var className = (node.getAttribute('class') || '')\n .split(/\\s+/)\n .filter((cls) => classesToPreserve.includes(cls))\n .join(' ');\n\n if (className) {\n node.setAttribute('class', className);\n } else {\n node.removeAttribute('class');\n }\n\n for (node = node.firstElementChild; node; node = node.nextElementSibling) {\n this._cleanClasses(node);\n }\n },\n\n /**\n * Tests whether a string is a URL or not.\n *\n * @param {string} str The string to test\n * @return {boolean} true if str is a URL, false if not\n */\n _isUrl(str) {\n try {\n new URL(str);\n return true;\n } catch {\n return false;\n }\n },\n /**\n * Converts each and uri in the given element to an absolute URI,\n * ignoring #ref URIs.\n *\n * @param Element\n * @return void\n */\n _fixRelativeUris(articleContent) {\n var baseURI = this._doc.baseURI;\n var documentURI = this._doc.documentURI;\n function toAbsoluteURI(uri) {\n // Leave hash links alone if the base URI matches the document URI:\n if (baseURI == documentURI && uri.charAt(0) == '#') {\n return uri;\n }\n\n // Otherwise, resolve against base URI:\n try {\n return new URL(uri, baseURI).href;\n } catch (ex) {\n // Something went wrong, just return the original:\n }\n return uri;\n }\n\n var links = this._getAllNodesWithTag(articleContent, ['a']);\n this._forEachNode(links, function (link) {\n var href = link.getAttribute('href');\n if (href) {\n // Remove links with javascript: URIs, since\n // they won't work after scripts have been removed from the page.\n if (href.indexOf('javascript:') === 0) {\n // if the link only contains simple text content, it can be converted to a text node\n if (link.childNodes.length === 1 && link.childNodes[0].nodeType === this.TEXT_NODE) {\n var text = this._doc.createTextNode(link.textContent);\n link.parentNode.replaceChild(text, link);\n } else {\n // if the link has multiple children, they should all be preserved\n var container = this._doc.createElement('span');\n while (link.firstChild) {\n container.appendChild(link.firstChild);\n }\n link.parentNode.replaceChild(container, link);\n }\n } else {\n link.setAttribute('href', toAbsoluteURI(href));\n }\n }\n });\n\n var medias = this._getAllNodesWithTag(articleContent, [\n 'img',\n 'picture',\n 'figure',\n 'video',\n 'audio',\n 'source',\n ]);\n\n this._forEachNode(medias, function (media) {\n var src = media.getAttribute('src');\n var poster = media.getAttribute('poster');\n var srcset = media.getAttribute('srcset');\n\n if (src) {\n media.setAttribute('src', toAbsoluteURI(src));\n }\n\n if (poster) {\n media.setAttribute('poster', toAbsoluteURI(poster));\n }\n\n if (srcset) {\n var newSrcset = srcset.replace(this.REGEXPS.srcsetUrl, function (_, p1, p2, p3) {\n return toAbsoluteURI(p1) + (p2 || '') + p3;\n });\n\n media.setAttribute('srcset', newSrcset);\n }\n });\n },\n\n _simplifyNestedElements(articleContent) {\n var node = articleContent;\n\n while (node) {\n if (\n node.parentNode &&\n ['DIV', 'SECTION'].includes(node.tagName) &&\n !(node.id && node.id.startsWith('readability'))\n ) {\n if (this._isElementWithoutContent(node)) {\n node = this._removeAndGetNext(node);\n continue;\n } else if (\n this._hasSingleTagInsideElement(node, 'DIV') ||\n this._hasSingleTagInsideElement(node, 'SECTION')\n ) {\n var child = node.children[0];\n for (var i = 0; i < node.attributes.length; i++) {\n child.setAttributeNode(node.attributes[i].cloneNode());\n }\n node.parentNode.replaceChild(child, node);\n node = child;\n continue;\n }\n }\n\n node = this._getNextNode(node);\n }\n },\n\n /**\n * Get the article title as an H1.\n *\n * @return string\n **/\n _getArticleTitle() {\n var doc = this._doc;\n var curTitle = '';\n var origTitle = '';\n\n try {\n curTitle = origTitle = doc.title.trim();\n\n // If they had an element with id \"title\" in their HTML\n if (typeof curTitle !== 'string') {\n curTitle = origTitle = this._getInnerText(doc.getElementsByTagName('title')[0]);\n }\n } catch (e) {\n /* ignore exceptions setting the title. */\n }\n\n var titleHadHierarchicalSeparators = false;\n function wordCount(str) {\n return str.split(/\\s+/).length;\n }\n\n // If there's a separator in the title, first remove the final part\n if (/ [\\|\\-\\\\\\/>»] /.test(curTitle)) {\n titleHadHierarchicalSeparators = / [\\\\\\/>»] /.test(curTitle);\n let allSeparators = Array.from(origTitle.matchAll(/ [\\|\\-\\\\\\/>»] /gi));\n curTitle = origTitle.substring(0, allSeparators.pop().index);\n\n // If the resulting title is too short, remove the first part instead:\n if (wordCount(curTitle) < 3) {\n curTitle = origTitle.replace(/^[^\\|\\-\\\\\\/>»]*[\\|\\-\\\\\\/>»]/gi, '');\n }\n } else if (curTitle.includes(': ')) {\n // Check if we have an heading containing this exact string, so we\n // could assume it's the full title.\n var headings = this._getAllNodesWithTag(doc, ['h1', 'h2']);\n var trimmedTitle = curTitle.trim();\n var match = this._someNode(headings, function (heading) {\n return heading.textContent.trim() === trimmedTitle;\n });\n\n // If we don't, let's extract the title out of the original title string.\n if (!match) {\n curTitle = origTitle.substring(origTitle.lastIndexOf(':') + 1);\n\n // If the title is now too short, try the first colon instead:\n if (wordCount(curTitle) < 3) {\n curTitle = origTitle.substring(origTitle.indexOf(':') + 1);\n // But if we have too many words before the colon there's something weird\n // with the titles and the H tags so let's just use the original title instead\n } else if (wordCount(origTitle.substr(0, origTitle.indexOf(':'))) > 5) {\n curTitle = origTitle;\n }\n }\n } else if (curTitle.length > 150 || curTitle.length < 15) {\n var hOnes = doc.getElementsByTagName('h1');\n\n if (hOnes.length === 1) {\n curTitle = this._getInnerText(hOnes[0]);\n }\n }\n\n curTitle = curTitle.trim().replace(this.REGEXPS.normalize, ' ');\n // If we now have 4 words or fewer as our title, and either no\n // 'hierarchical' separators (\\, /, > or ») were found in the original\n // title or we decreased the number of words by more than 1 word, use\n // the original title.\n var curTitleWordCount = wordCount(curTitle);\n if (\n curTitleWordCount <= 4 &&\n (!titleHadHierarchicalSeparators ||\n curTitleWordCount != wordCount(origTitle.replace(/[\\|\\-\\\\\\/>»]+/g, '')) - 1)\n ) {\n curTitle = origTitle;\n }\n\n return curTitle;\n },\n\n /**\n * Prepare the HTML document for readability to scrape it.\n * This includes things like stripping javascript, CSS, and handling terrible markup.\n *\n * @return void\n **/\n _prepDocument() {\n var doc = this._doc;\n\n // Remove all style tags in head\n this._removeNodes(this._getAllNodesWithTag(doc, ['style']));\n\n if (doc.body) {\n this._replaceBrs(doc.body);\n }\n\n this._replaceNodeTags(this._getAllNodesWithTag(doc, ['font']), 'SPAN');\n },\n\n /**\n * Finds the next node, starting from the given node, and ignoring\n * whitespace in between. If the given node is an element, the same node is\n * returned.\n */\n _nextNode(node) {\n var next = node;\n while (\n next &&\n next.nodeType != this.ELEMENT_NODE &&\n this.REGEXPS.whitespace.test(next.textContent)\n ) {\n next = next.nextSibling;\n }\n return next;\n },\n\n /**\n * Replaces 2 or more successive
elements with a single

.\n * Whitespace between
elements are ignored. For example:\n *

foo
bar


abc
\n * will become:\n *
foo
bar

abc

\n */\n _replaceBrs(elem) {\n this._forEachNode(this._getAllNodesWithTag(elem, ['br']), function (br) {\n var next = br.nextSibling;\n\n // Whether 2 or more
elements have been found and replaced with a\n //

block.\n var replaced = false;\n\n // If we find a
chain, remove the
s until we hit another node\n // or non-whitespace. This leaves behind the first
in the chain\n // (which will be replaced with a

later).\n while ((next = this._nextNode(next)) && next.tagName == 'BR') {\n replaced = true;\n var brSibling = next.nextSibling;\n next.remove();\n next = brSibling;\n }\n\n // If we removed a
chain, replace the remaining
with a

. Add\n // all sibling nodes as children of the

until we hit another
\n // chain.\n if (replaced) {\n var p = this._doc.createElement('p');\n br.parentNode.replaceChild(p, br);\n\n next = p.nextSibling;\n while (next) {\n // If we've hit another

, we're done adding children to this

.\n if (next.tagName == 'BR') {\n var nextElem = this._nextNode(next.nextSibling);\n if (nextElem && nextElem.tagName == 'BR') {\n break;\n }\n }\n\n if (!this._isPhrasingContent(next)) {\n break;\n }\n\n // Otherwise, make this node a child of the new

.\n var sibling = next.nextSibling;\n p.appendChild(next);\n next = sibling;\n }\n\n while (p.lastChild && this._isWhitespace(p.lastChild)) {\n p.lastChild.remove();\n }\n\n if (p.parentNode.tagName === 'P') {\n this._setNodeTag(p.parentNode, 'DIV');\n }\n }\n });\n },\n\n _setNodeTag(node, tag) {\n this.log('_setNodeTag', node, tag);\n if (this._docJSDOMParser) {\n node.localName = tag.toLowerCase();\n node.tagName = tag.toUpperCase();\n return node;\n }\n\n var replacement = node.ownerDocument.createElement(tag);\n while (node.firstChild) {\n replacement.appendChild(node.firstChild);\n }\n node.parentNode.replaceChild(replacement, node);\n if (node.readability) {\n replacement.readability = node.readability;\n }\n\n for (var i = 0; i < node.attributes.length; i++) {\n replacement.setAttributeNode(node.attributes[i].cloneNode());\n }\n return replacement;\n },\n\n /**\n * Prepare the article node for display. Clean out any inline styles,\n * iframes, forms, strip extraneous

tags, etc.\n *\n * @param Element\n * @return void\n **/\n _prepArticle(articleContent) {\n this._cleanStyles(articleContent);\n\n // Check for data tables before we continue, to avoid removing items in\n // those tables, which will often be isolated even though they're\n // visually linked to other content-ful elements (text, images, etc.).\n this._markDataTables(articleContent);\n\n this._fixLazyImages(articleContent);\n\n // Clean out junk from the article content\n this._cleanConditionally(articleContent, 'form');\n this._cleanConditionally(articleContent, 'fieldset');\n this._clean(articleContent, 'object');\n this._clean(articleContent, 'embed');\n this._clean(articleContent, 'footer');\n this._clean(articleContent, 'link');\n this._clean(articleContent, 'aside');\n\n // Clean out elements with little content that have \"share\" in their id/class combinations from final top candidates,\n // which means we don't remove the top candidates even they have \"share\".\n\n var shareElementThreshold = this.DEFAULT_CHAR_THRESHOLD;\n\n this._forEachNode(articleContent.children, function (topCandidate) {\n this._cleanMatchedNodes(topCandidate, function (node, matchString) {\n return (\n this.REGEXPS.shareElements.test(matchString) &&\n node.textContent.length < shareElementThreshold\n );\n });\n });\n\n this._clean(articleContent, 'iframe');\n this._clean(articleContent, 'input');\n this._clean(articleContent, 'textarea');\n this._clean(articleContent, 'select');\n this._clean(articleContent, 'button');\n this._cleanHeaders(articleContent);\n\n // Do these last as the previous stuff may have removed junk\n // that will affect these\n this._cleanConditionally(articleContent, 'table');\n this._cleanConditionally(articleContent, 'ul');\n this._cleanConditionally(articleContent, 'div');\n\n // replace H1 with H2 as H1 should be only title that is displayed separately\n this._replaceNodeTags(this._getAllNodesWithTag(articleContent, ['h1']), 'h2');\n\n // Remove extra paragraphs\n this._removeNodes(this._getAllNodesWithTag(articleContent, ['p']), function (paragraph) {\n // At this point, nasty iframes have been removed; only embedded video\n // ones remain.\n var contentElementCount = this._getAllNodesWithTag(paragraph, [\n 'img',\n 'embed',\n 'object',\n 'iframe',\n ]).length;\n return contentElementCount === 0 && !this._getInnerText(paragraph, false);\n });\n\n this._forEachNode(this._getAllNodesWithTag(articleContent, ['br']), function (br) {\n var next = this._nextNode(br.nextSibling);\n if (next && next.tagName == 'P') {\n br.remove();\n }\n });\n\n // Remove single-cell tables\n this._forEachNode(this._getAllNodesWithTag(articleContent, ['table']), function (table) {\n var tbody = this._hasSingleTagInsideElement(table, 'TBODY')\n ? table.firstElementChild\n : table;\n if (this._hasSingleTagInsideElement(tbody, 'TR')) {\n var row = tbody.firstElementChild;\n if (this._hasSingleTagInsideElement(row, 'TD')) {\n var cell = row.firstElementChild;\n cell = this._setNodeTag(\n cell,\n this._everyNode(cell.childNodes, this._isPhrasingContent) ? 'P' : 'DIV',\n );\n table.parentNode.replaceChild(cell, table);\n }\n }\n });\n },\n\n /**\n * Initialize a node with the readability object. Also checks the\n * className/id for special names to add to its score.\n *\n * @param Element\n * @return void\n **/\n _initializeNode(node) {\n node.readability = { contentScore: 0 };\n\n switch (node.tagName) {\n case 'DIV':\n node.readability.contentScore += 5;\n break;\n\n case 'PRE':\n case 'TD':\n case 'BLOCKQUOTE':\n node.readability.contentScore += 3;\n break;\n\n case 'ADDRESS':\n case 'OL':\n case 'UL':\n case 'DL':\n case 'DD':\n case 'DT':\n case 'LI':\n case 'FORM':\n node.readability.contentScore -= 3;\n break;\n\n case 'H1':\n case 'H2':\n case 'H3':\n case 'H4':\n case 'H5':\n case 'H6':\n case 'TH':\n node.readability.contentScore -= 5;\n break;\n }\n\n node.readability.contentScore += this._getClassWeight(node);\n },\n\n _removeAndGetNext(node) {\n var nextNode = this._getNextNode(node, true);\n node.remove();\n return nextNode;\n },\n\n /**\n * Traverse the DOM from node to node, starting at the node passed in.\n * Pass true for the second parameter to indicate this node itself\n * (and its kids) are going away, and we want the next node over.\n *\n * Calling this in a loop will traverse the DOM depth-first.\n *\n * @param {Element} node\n * @param {boolean} ignoreSelfAndKids\n * @return {Element}\n */\n _getNextNode(node, ignoreSelfAndKids) {\n // First check for kids if those aren't being ignored\n if (!ignoreSelfAndKids && node.firstElementChild) {\n return node.firstElementChild;\n }\n // Then for siblings...\n if (node.nextElementSibling) {\n return node.nextElementSibling;\n }\n // And finally, move up the parent chain *and* find a sibling\n // (because this is depth-first traversal, we will have already\n // seen the parent nodes themselves).\n do {\n node = node.parentNode;\n } while (node && !node.nextElementSibling);\n return node && node.nextElementSibling;\n },\n\n // compares second text to first one\n // 1 = same text, 0 = completely different text\n // works the way that it splits both texts into words and then finds words that are unique in second text\n // the result is given by the lower length of unique parts\n _textSimilarity(textA, textB) {\n var tokensA = textA.toLowerCase().split(this.REGEXPS.tokenize).filter(Boolean);\n var tokensB = textB.toLowerCase().split(this.REGEXPS.tokenize).filter(Boolean);\n if (!tokensA.length || !tokensB.length) {\n return 0;\n }\n var uniqTokensB = tokensB.filter((token) => !tokensA.includes(token));\n var distanceB = uniqTokensB.join(' ').length / tokensB.join(' ').length;\n return 1 - distanceB;\n },\n\n /**\n * Checks whether an element node contains a valid byline\n *\n * @param node {Element}\n * @param matchString {string}\n * @return boolean\n */\n _isValidByline(node, matchString) {\n var rel = node.getAttribute('rel');\n var itemprop = node.getAttribute('itemprop');\n var bylineLength = node.textContent.trim().length;\n\n return (\n (rel === 'author' ||\n (itemprop && itemprop.includes('author')) ||\n this.REGEXPS.byline.test(matchString)) &&\n !!bylineLength &&\n bylineLength < 100\n );\n },\n\n _getNodeAncestors(node, maxDepth) {\n maxDepth = maxDepth || 0;\n var i = 0,\n ancestors = [];\n while (node.parentNode) {\n ancestors.push(node.parentNode);\n if (maxDepth && ++i === maxDepth) {\n break;\n }\n node = node.parentNode;\n }\n return ancestors;\n },\n\n /***\n * grabArticle - Using a variety of metrics (content score, classname, element types), find the content that is\n * most likely to be the stuff a user wants to read. Then return it wrapped up in a div.\n *\n * @param page a document to run upon. Needs to be a full document, complete with body.\n * @return Element\n **/\n\n _grabArticle(page) {\n this.log('**** grabArticle ****');\n var doc = this._doc;\n var isPaging = page !== null;\n page = page ? page : this._doc.body;\n\n // We can't grab an article if we don't have a page!\n if (!page) {\n this.log('No body found in document. Abort.');\n return null;\n }\n\n var pageCacheHtml = page.innerHTML;\n\n while (true) {\n this.log('Starting grabArticle loop');\n var stripUnlikelyCandidates = this._flagIsActive(this.FLAG_STRIP_UNLIKELYS);\n\n // First, node prepping. Trash nodes that look cruddy (like ones with the\n // class name \"comment\", etc), and turn divs into P tags where they have been\n // used inappropriately (as in, where they contain no other block level elements.)\n var elementsToScore = [];\n var node = this._doc.documentElement;\n\n let shouldRemoveTitleHeader = true;\n\n while (node) {\n if (node.tagName === 'HTML') {\n this._articleLang = node.getAttribute('lang');\n }\n\n var matchString = node.className + ' ' + node.id;\n\n if (!this._isProbablyVisible(node)) {\n this.log('Removing hidden node - ' + matchString);\n node = this._removeAndGetNext(node);\n continue;\n }\n\n // User is not able to see elements applied with both \"aria-modal = true\" and \"role = dialog\"\n if (node.getAttribute('aria-modal') == 'true' && node.getAttribute('role') == 'dialog') {\n node = this._removeAndGetNext(node);\n continue;\n }\n\n // If we don't have a byline yet check to see if this node is a byline; if it is store the byline and remove the node.\n if (\n !this._articleByline &&\n !this._metadata.byline &&\n this._isValidByline(node, matchString)\n ) {\n // Find child node matching [itemprop=\"name\"] and use that if it exists for a more accurate author name byline\n var endOfSearchMarkerNode = this._getNextNode(node, true);\n var next = this._getNextNode(node);\n var itemPropNameNode = null;\n while (next && next != endOfSearchMarkerNode) {\n var itemprop = next.getAttribute('itemprop');\n if (itemprop && itemprop.includes('name')) {\n itemPropNameNode = next;\n break;\n } else {\n next = this._getNextNode(next);\n }\n }\n this._articleByline = (itemPropNameNode ?? node).textContent.trim();\n node = this._removeAndGetNext(node);\n continue;\n }\n\n if (shouldRemoveTitleHeader && this._headerDuplicatesTitle(node)) {\n this.log('Removing header: ', node.textContent.trim(), this._articleTitle.trim());\n shouldRemoveTitleHeader = false;\n node = this._removeAndGetNext(node);\n continue;\n }\n\n // Remove unlikely candidates\n if (stripUnlikelyCandidates) {\n if (\n this.REGEXPS.unlikelyCandidates.test(matchString) &&\n !this.REGEXPS.okMaybeItsACandidate.test(matchString) &&\n !this._hasAncestorTag(node, 'table') &&\n !this._hasAncestorTag(node, 'code') &&\n node.tagName !== 'BODY' &&\n node.tagName !== 'A'\n ) {\n this.log('Removing unlikely candidate - ' + matchString);\n node = this._removeAndGetNext(node);\n continue;\n }\n\n if (this.UNLIKELY_ROLES.includes(node.getAttribute('role'))) {\n this.log(\n 'Removing content with role ' + node.getAttribute('role') + ' - ' + matchString,\n );\n node = this._removeAndGetNext(node);\n continue;\n }\n }\n\n // Remove DIV, SECTION, and HEADER nodes without any content(e.g. text, image, video, or iframe).\n if (\n (node.tagName === 'DIV' ||\n node.tagName === 'SECTION' ||\n node.tagName === 'HEADER' ||\n node.tagName === 'H1' ||\n node.tagName === 'H2' ||\n node.tagName === 'H3' ||\n node.tagName === 'H4' ||\n node.tagName === 'H5' ||\n node.tagName === 'H6') &&\n this._isElementWithoutContent(node)\n ) {\n node = this._removeAndGetNext(node);\n continue;\n }\n\n if (this.DEFAULT_TAGS_TO_SCORE.includes(node.tagName)) {\n elementsToScore.push(node);\n }\n\n // Turn all divs that don't have children block level elements into p's\n if (node.tagName === 'DIV') {\n // Put phrasing content into paragraphs.\n var p = null;\n var childNode = node.firstChild;\n while (childNode) {\n var nextSibling = childNode.nextSibling;\n if (this._isPhrasingContent(childNode)) {\n if (p !== null) {\n p.appendChild(childNode);\n } else if (!this._isWhitespace(childNode)) {\n p = doc.createElement('p');\n node.replaceChild(p, childNode);\n p.appendChild(childNode);\n }\n } else if (p !== null) {\n while (p.lastChild && this._isWhitespace(p.lastChild)) {\n p.lastChild.remove();\n }\n p = null;\n }\n childNode = nextSibling;\n }\n\n // Sites like http://mobile.slate.com encloses each paragraph with a DIV\n // element. DIVs with only a P element inside and no text content can be\n // safely converted into plain P elements to avoid confusing the scoring\n // algorithm with DIVs with are, in practice, paragraphs.\n if (this._hasSingleTagInsideElement(node, 'P') && this._getLinkDensity(node) < 0.25) {\n var newNode = node.children[0];\n node.parentNode.replaceChild(newNode, node);\n node = newNode;\n elementsToScore.push(node);\n } else if (!this._hasChildBlockElement(node)) {\n node = this._setNodeTag(node, 'P');\n elementsToScore.push(node);\n }\n }\n node = this._getNextNode(node);\n }\n\n /**\n * Loop through all paragraphs, and assign a score to them based on how content-y they look.\n * Then add their score to their parent node.\n *\n * A score is determined by things like number of commas, class names, etc. Maybe eventually link density.\n **/\n var candidates = [];\n this._forEachNode(elementsToScore, function (elementToScore) {\n if (\n !elementToScore.parentNode ||\n typeof elementToScore.parentNode.tagName === 'undefined'\n ) {\n return;\n }\n\n // If this paragraph is less than 25 characters, don't even count it.\n var innerText = this._getInnerText(elementToScore);\n if (innerText.length < 25) {\n return;\n }\n\n // Exclude nodes with no ancestor.\n var ancestors = this._getNodeAncestors(elementToScore, 5);\n if (ancestors.length === 0) {\n return;\n }\n\n var contentScore = 0;\n\n // Add a point for the paragraph itself as a base.\n contentScore += 1;\n\n // Add points for any commas within this paragraph.\n contentScore += innerText.split(this.REGEXPS.commas).length;\n\n // For every 100 characters in this paragraph, add another point. Up to 3 points.\n contentScore += Math.min(Math.floor(innerText.length / 100), 3);\n\n // Initialize and score ancestors.\n this._forEachNode(ancestors, function (ancestor, level) {\n if (\n !ancestor.tagName ||\n !ancestor.parentNode ||\n typeof ancestor.parentNode.tagName === 'undefined'\n ) {\n return;\n }\n\n if (typeof ancestor.readability === 'undefined') {\n this._initializeNode(ancestor);\n candidates.push(ancestor);\n }\n\n // Node score divider:\n // - parent: 1 (no division)\n // - grandparent: 2\n // - great grandparent+: ancestor level * 3\n if (level === 0) {\n var scoreDivider = 1;\n } else if (level === 1) {\n scoreDivider = 2;\n } else {\n scoreDivider = level * 3;\n }\n ancestor.readability.contentScore += contentScore / scoreDivider;\n });\n });\n\n // After we've calculated scores, loop through all of the possible\n // candidate nodes we found and find the one with the highest score.\n var topCandidates = [];\n for (var c = 0, cl = candidates.length; c < cl; c += 1) {\n var candidate = candidates[c];\n\n // Scale the final candidates score based on link density. Good content\n // should have a relatively small link density (5% or less) and be mostly\n // unaffected by this operation.\n var candidateScore =\n candidate.readability.contentScore * (1 - this._getLinkDensity(candidate));\n candidate.readability.contentScore = candidateScore;\n\n this.log('Candidate:', candidate, 'with score ' + candidateScore);\n\n for (var t = 0; t < this._nbTopCandidates; t++) {\n var aTopCandidate = topCandidates[t];\n\n if (!aTopCandidate || candidateScore > aTopCandidate.readability.contentScore) {\n topCandidates.splice(t, 0, candidate);\n if (topCandidates.length > this._nbTopCandidates) {\n topCandidates.pop();\n }\n break;\n }\n }\n }\n\n var topCandidate = topCandidates[0] || null;\n var neededToCreateTopCandidate = false;\n var parentOfTopCandidate;\n\n // If we still have no top candidate, just use the body as a last resort.\n // We also have to copy the body node so it is something we can modify.\n if (topCandidate === null || topCandidate.tagName === 'BODY') {\n // Move all of the page's children into topCandidate\n topCandidate = doc.createElement('DIV');\n neededToCreateTopCandidate = true;\n // Move everything (not just elements, also text nodes etc.) into the container\n // so we even include text directly in the body:\n while (page.firstChild) {\n this.log('Moving child out:', page.firstChild);\n topCandidate.appendChild(page.firstChild);\n }\n\n page.appendChild(topCandidate);\n\n this._initializeNode(topCandidate);\n } else if (topCandidate) {\n // Find a better top candidate node if it contains (at least three) nodes which belong to `topCandidates` array\n // and whose scores are quite closed with current `topCandidate` node.\n var alternativeCandidateAncestors = [];\n for (var i = 1; i < topCandidates.length; i++) {\n if (\n topCandidates[i].readability.contentScore / topCandidate.readability.contentScore >=\n 0.75\n ) {\n alternativeCandidateAncestors.push(this._getNodeAncestors(topCandidates[i]));\n }\n }\n var MINIMUM_TOPCANDIDATES = 3;\n if (alternativeCandidateAncestors.length >= MINIMUM_TOPCANDIDATES) {\n parentOfTopCandidate = topCandidate.parentNode;\n while (parentOfTopCandidate && parentOfTopCandidate.tagName !== 'BODY') {\n var listsContainingThisAncestor = 0;\n for (\n var ancestorIndex = 0;\n ancestorIndex < alternativeCandidateAncestors.length &&\n listsContainingThisAncestor < MINIMUM_TOPCANDIDATES;\n ancestorIndex++\n ) {\n listsContainingThisAncestor += Number(\n alternativeCandidateAncestors[ancestorIndex].includes(parentOfTopCandidate),\n );\n }\n if (listsContainingThisAncestor >= MINIMUM_TOPCANDIDATES) {\n topCandidate = parentOfTopCandidate;\n break;\n }\n parentOfTopCandidate = parentOfTopCandidate.parentNode;\n }\n }\n if (!topCandidate.readability) {\n this._initializeNode(topCandidate);\n }\n\n // Because of our bonus system, parents of candidates might have scores\n // themselves. They get half of the node. There won't be nodes with higher\n // scores than our topCandidate, but if we see the score going *up* in the first\n // few steps up the tree, that's a decent sign that there might be more content\n // lurking in other places that we want to unify in. The sibling stuff\n // below does some of that - but only if we've looked high enough up the DOM\n // tree.\n parentOfTopCandidate = topCandidate.parentNode;\n var lastScore = topCandidate.readability.contentScore;\n // The scores shouldn't get too low.\n var scoreThreshold = lastScore / 3;\n while (parentOfTopCandidate && parentOfTopCandidate.tagName !== 'BODY') {\n if (!parentOfTopCandidate.readability) {\n parentOfTopCandidate = parentOfTopCandidate.parentNode;\n continue;\n }\n var parentScore = parentOfTopCandidate.readability.contentScore;\n if (parentScore < scoreThreshold) {\n break;\n }\n if (parentScore > lastScore) {\n // Alright! We found a better parent to use.\n topCandidate = parentOfTopCandidate;\n break;\n }\n lastScore = parentOfTopCandidate.readability.contentScore;\n parentOfTopCandidate = parentOfTopCandidate.parentNode;\n }\n\n // If the top candidate is the only child, use parent instead. This will help sibling\n // joining logic when adjacent content is actually located in parent's sibling node.\n parentOfTopCandidate = topCandidate.parentNode;\n while (\n parentOfTopCandidate &&\n parentOfTopCandidate.tagName != 'BODY' &&\n parentOfTopCandidate.children.length == 1\n ) {\n topCandidate = parentOfTopCandidate;\n parentOfTopCandidate = topCandidate.parentNode;\n }\n if (!topCandidate.readability) {\n this._initializeNode(topCandidate);\n }\n }\n\n // Now that we have the top candidate, look through its siblings for content\n // that might also be related. Things like preambles, content split by ads\n // that we removed, etc.\n var articleContent = doc.createElement('DIV');\n if (isPaging) {\n articleContent.id = 'readability-content';\n }\n\n var siblingScoreThreshold = Math.max(10, topCandidate.readability.contentScore * 0.2);\n // Keep potential top candidate's parent node to try to get text direction of it later.\n parentOfTopCandidate = topCandidate.parentNode;\n var siblings = parentOfTopCandidate.children;\n\n for (var s = 0, sl = siblings.length; s < sl; s++) {\n var sibling = siblings[s];\n var append = false;\n\n this.log(\n 'Looking at sibling node:',\n sibling,\n sibling.readability ? 'with score ' + sibling.readability.contentScore : '',\n );\n this.log(\n 'Sibling has score',\n sibling.readability ? sibling.readability.contentScore : 'Unknown',\n );\n\n if (sibling === topCandidate) {\n append = true;\n } else {\n var contentBonus = 0;\n\n // Give a bonus if sibling nodes and top candidates have the example same classname\n if (sibling.className === topCandidate.className && topCandidate.className !== '') {\n contentBonus += topCandidate.readability.contentScore * 0.2;\n }\n\n if (\n sibling.readability &&\n sibling.readability.contentScore + contentBonus >= siblingScoreThreshold\n ) {\n append = true;\n } else if (sibling.nodeName === 'P') {\n var linkDensity = this._getLinkDensity(sibling);\n var nodeContent = this._getInnerText(sibling);\n var nodeLength = nodeContent.length;\n\n if (nodeLength > 80 && linkDensity < 0.25) {\n append = true;\n } else if (\n nodeLength < 80 &&\n nodeLength > 0 &&\n linkDensity === 0 &&\n nodeContent.search(/\\.( |$)/) !== -1\n ) {\n append = true;\n }\n }\n }\n\n if (append) {\n this.log('Appending node:', sibling);\n\n if (!this.ALTER_TO_DIV_EXCEPTIONS.includes(sibling.nodeName)) {\n // We have a node that isn't a common block level element, like a form or td tag.\n // Turn it into a div so it doesn't get filtered out later by accident.\n this.log('Altering sibling:', sibling, 'to div.');\n\n sibling = this._setNodeTag(sibling, 'DIV');\n }\n\n articleContent.appendChild(sibling);\n // Fetch children again to make it compatible\n // with DOM parsers without live collection support.\n siblings = parentOfTopCandidate.children;\n // siblings is a reference to the children array, and\n // sibling is removed from the array when we call appendChild().\n // As a result, we must revisit this index since the nodes\n // have been shifted.\n s -= 1;\n sl -= 1;\n }\n }\n\n if (this._debug) {\n this.log('Article content pre-prep: ' + articleContent.innerHTML);\n }\n // So we have all of the content that we need. Now we clean it up for presentation.\n this._prepArticle(articleContent);\n if (this._debug) {\n this.log('Article content post-prep: ' + articleContent.innerHTML);\n }\n\n if (neededToCreateTopCandidate) {\n // We already created a fake div thing, and there wouldn't have been any siblings left\n // for the previous loop, so there's no point trying to create a new div, and then\n // move all the children over. Just assign IDs and class names here. No need to append\n // because that already happened anyway.\n topCandidate.id = 'readability-page-1';\n topCandidate.className = 'page';\n } else {\n var div = doc.createElement('DIV');\n div.id = 'readability-page-1';\n div.className = 'page';\n while (articleContent.firstChild) {\n div.appendChild(articleContent.firstChild);\n }\n articleContent.appendChild(div);\n }\n\n if (this._debug) {\n this.log('Article content after paging: ' + articleContent.innerHTML);\n }\n\n var parseSuccessful = true;\n\n // Now that we've gone through the full algorithm, check to see if\n // we got any meaningful content. If we didn't, we may need to re-run\n // grabArticle with different flags set. This gives us a higher likelihood of\n // finding the content, and the sieve approach gives us a higher likelihood of\n // finding the -right- content.\n var textLength = this._getInnerText(articleContent, true).length;\n if (textLength < this._charThreshold) {\n parseSuccessful = false;\n // eslint-disable-next-line no-unsanitized/property\n page.innerHTML = pageCacheHtml;\n\n this._attempts.push({\n articleContent,\n textLength,\n });\n\n if (this._flagIsActive(this.FLAG_STRIP_UNLIKELYS)) {\n this._removeFlag(this.FLAG_STRIP_UNLIKELYS);\n } else if (this._flagIsActive(this.FLAG_WEIGHT_CLASSES)) {\n this._removeFlag(this.FLAG_WEIGHT_CLASSES);\n } else if (this._flagIsActive(this.FLAG_CLEAN_CONDITIONALLY)) {\n this._removeFlag(this.FLAG_CLEAN_CONDITIONALLY);\n } else {\n // No luck after removing flags, just return the longest text we found during the different loops\n this._attempts.sort(function (a, b) {\n return b.textLength - a.textLength;\n });\n\n // But first check if we actually have something\n if (!this._attempts[0].textLength) {\n return null;\n }\n\n articleContent = this._attempts[0].articleContent;\n parseSuccessful = true;\n }\n }\n\n if (parseSuccessful) {\n // Find out text direction from ancestors of final top candidate.\n var ancestors = [parentOfTopCandidate, topCandidate].concat(\n this._getNodeAncestors(parentOfTopCandidate),\n );\n this._someNode(ancestors, function (ancestor) {\n if (!ancestor.tagName) {\n return false;\n }\n var articleDir = ancestor.getAttribute('dir');\n if (articleDir) {\n this._articleDir = articleDir;\n return true;\n }\n return false;\n });\n return articleContent;\n }\n }\n },\n\n /**\n * Converts some of the common HTML entities in string to their corresponding characters.\n *\n * @param str {string} - a string to unescape.\n * @return string without HTML entity.\n */\n _unescapeHtmlEntities(str) {\n if (!str) {\n return str;\n }\n\n var htmlEscapeMap = this.HTML_ESCAPE_MAP;\n return str\n .replace(/&(quot|amp|apos|lt|gt);/g, function (_, tag) {\n return htmlEscapeMap[tag];\n })\n .replace(/&#(?:x([0-9a-f]+)|([0-9]+));/gi, function (_, hex, numStr) {\n var num = parseInt(hex || numStr, hex ? 16 : 10);\n\n // these character references are replaced by a conforming HTML parser\n if (num == 0 || num > 0x10ffff || (num >= 0xd800 && num <= 0xdfff)) {\n num = 0xfffd;\n }\n\n return String.fromCodePoint(num);\n });\n },\n\n /**\n * Try to extract metadata from JSON-LD object.\n * For now, only Schema.org objects of type Article or its subtypes are supported.\n * @return Object with any metadata that could be extracted (possibly none)\n */\n _getJSONLD(doc) {\n var scripts = this._getAllNodesWithTag(doc, ['script']);\n\n var metadata;\n\n this._forEachNode(scripts, function (jsonLdElement) {\n if (!metadata && jsonLdElement.getAttribute('type') === 'application/ld+json') {\n try {\n // Strip CDATA markers if present\n var content = jsonLdElement.textContent.replace(/^\\s*\\s*$/g, '');\n var parsed = JSON.parse(content);\n\n if (Array.isArray(parsed)) {\n parsed = parsed.find((it) => {\n return it['@type'] && it['@type'].match(this.REGEXPS.jsonLdArticleTypes);\n });\n if (!parsed) {\n return;\n }\n }\n\n var schemaDotOrgRegex = /^https?\\:\\/\\/schema\\.org\\/?$/;\n var matches =\n (typeof parsed['@context'] === 'string' &&\n parsed['@context'].match(schemaDotOrgRegex)) ||\n (typeof parsed['@context'] === 'object' &&\n typeof parsed['@context']['@vocab'] == 'string' &&\n parsed['@context']['@vocab'].match(schemaDotOrgRegex));\n\n if (!matches) {\n return;\n }\n\n if (!parsed['@type'] && Array.isArray(parsed['@graph'])) {\n parsed = parsed['@graph'].find((it) => {\n return (it['@type'] || '').match(this.REGEXPS.jsonLdArticleTypes);\n });\n }\n\n if (\n !parsed ||\n !parsed['@type'] ||\n !parsed['@type'].match(this.REGEXPS.jsonLdArticleTypes)\n ) {\n return;\n }\n\n metadata = {};\n\n if (\n typeof parsed.name === 'string' &&\n typeof parsed.headline === 'string' &&\n parsed.name !== parsed.headline\n ) {\n // we have both name and headline element in the JSON-LD. They should both be the same but some websites like aktualne.cz\n // put their own name into \"name\" and the article title to \"headline\" which confuses Readability. So we try to check if either\n // \"name\" or \"headline\" closely matches the html title, and if so, use that one. If not, then we use \"name\" by default.\n\n var title = this._getArticleTitle();\n var nameMatches = this._textSimilarity(parsed.name, title) > 0.75;\n var headlineMatches = this._textSimilarity(parsed.headline, title) > 0.75;\n\n if (headlineMatches && !nameMatches) {\n metadata.title = parsed.headline;\n } else {\n metadata.title = parsed.name;\n }\n } else if (typeof parsed.name === 'string') {\n metadata.title = parsed.name.trim();\n } else if (typeof parsed.headline === 'string') {\n metadata.title = parsed.headline.trim();\n }\n if (parsed.author) {\n if (typeof parsed.author.name === 'string') {\n metadata.byline = parsed.author.name.trim();\n } else if (\n Array.isArray(parsed.author) &&\n parsed.author[0] &&\n typeof parsed.author[0].name === 'string'\n ) {\n metadata.byline = parsed.author\n .filter(function (author) {\n return author && typeof author.name === 'string';\n })\n .map(function (author) {\n return author.name.trim();\n })\n .join(', ');\n }\n }\n if (typeof parsed.description === 'string') {\n metadata.excerpt = parsed.description.trim();\n }\n if (parsed.publisher && typeof parsed.publisher.name === 'string') {\n metadata.siteName = parsed.publisher.name.trim();\n }\n if (typeof parsed.datePublished === 'string') {\n metadata.datePublished = parsed.datePublished.trim();\n }\n } catch (err) {\n this.log(err.message);\n }\n }\n });\n return metadata ? metadata : {};\n },\n\n /**\n * Attempts to get excerpt and byline metadata for the article.\n *\n * @param {Object} jsonld — object containing any metadata that\n * could be extracted from JSON-LD object.\n *\n * @return Object with optional \"excerpt\" and \"byline\" properties\n */\n _getArticleMetadata(jsonld) {\n var metadata = {};\n var values = {};\n var metaElements = this._doc.getElementsByTagName('meta');\n\n // property is a space-separated list of values\n var propertyPattern =\n /\\s*(article|dc|dcterm|og|twitter)\\s*:\\s*(author|creator|description|published_time|title|site_name)\\s*/gi;\n\n // name is a single value\n var namePattern =\n /^\\s*(?:(dc|dcterm|og|twitter|parsely|weibo:(article|webpage))\\s*[-\\.:]\\s*)?(author|creator|pub-date|description|title|site_name)\\s*$/i;\n\n // Find description tags.\n this._forEachNode(metaElements, function (element) {\n var elementName = element.getAttribute('name');\n var elementProperty = element.getAttribute('property');\n var content = element.getAttribute('content');\n if (!content) {\n return;\n }\n var matches = null;\n var name = null;\n\n if (elementProperty) {\n matches = elementProperty.match(propertyPattern);\n if (matches) {\n // Convert to lowercase, and remove any whitespace\n // so we can match below.\n name = matches[0].toLowerCase().replace(/\\s/g, '');\n // multiple authors\n values[name] = content.trim();\n }\n }\n if (!matches && elementName && namePattern.test(elementName)) {\n name = elementName;\n if (content) {\n // Convert to lowercase, remove any whitespace, and convert dots\n // to colons so we can match below.\n name = name.toLowerCase().replace(/\\s/g, '').replace(/\\./g, ':');\n values[name] = content.trim();\n }\n }\n });\n\n // get title\n metadata.title =\n jsonld.title ||\n values['dc:title'] ||\n values['dcterm:title'] ||\n values['og:title'] ||\n values['weibo:article:title'] ||\n values['weibo:webpage:title'] ||\n values.title ||\n values['twitter:title'] ||\n values['parsely-title'];\n\n if (!metadata.title) {\n metadata.title = this._getArticleTitle();\n }\n\n const articleAuthor =\n typeof values['article:author'] === 'string' && !this._isUrl(values['article:author'])\n ? values['article:author']\n : undefined;\n\n // get author\n metadata.byline =\n jsonld.byline ||\n values['dc:creator'] ||\n values['dcterm:creator'] ||\n values.author ||\n values['parsely-author'] ||\n articleAuthor;\n\n // get description\n metadata.excerpt =\n jsonld.excerpt ||\n values['dc:description'] ||\n values['dcterm:description'] ||\n values['og:description'] ||\n values['weibo:article:description'] ||\n values['weibo:webpage:description'] ||\n values.description ||\n values['twitter:description'];\n\n // get site name\n metadata.siteName = jsonld.siteName || values['og:site_name'];\n\n // get article published time\n metadata.publishedTime =\n jsonld.datePublished ||\n values['article:published_time'] ||\n values['parsely-pub-date'] ||\n null;\n\n // in many sites the meta value is escaped with HTML entities,\n // so here we need to unescape it\n metadata.title = this._unescapeHtmlEntities(metadata.title);\n metadata.byline = this._unescapeHtmlEntities(metadata.byline);\n metadata.excerpt = this._unescapeHtmlEntities(metadata.excerpt);\n metadata.siteName = this._unescapeHtmlEntities(metadata.siteName);\n metadata.publishedTime = this._unescapeHtmlEntities(metadata.publishedTime);\n\n return metadata;\n },\n\n /**\n * Check if node is image, or if node contains exactly only one image\n * whether as a direct child or as its descendants.\n *\n * @param Element\n **/\n _isSingleImage(node) {\n while (node) {\n if (node.tagName === 'IMG') {\n return true;\n }\n if (node.children.length !== 1 || node.textContent.trim() !== '') {\n return false;\n }\n node = node.children[0];\n }\n return false;\n },\n\n /**\n * Find all