Embedded Browser & Web Annotations
Relevant source files
The following files were used as context for generating this wiki page:
Termul includes an integrated web browsing system that operates within project workspaces. This system eliminates the need for application switching by providing embedded browser tabs and a specialized annotation workflow for capturing and labeling web content.
Sources: README.md:44-48, CHANGELOG.md:129-131
System Architecture
The browser system uses a split architecture between the React-based renderer and the Tauri/Rust backend. The frontend manages user interactions and session state via Zustand, while the backend handles browser automation and Chrome DevTools Protocol (CDP) interactions.
Component Structure
The following components form the browser UI:
| Component | Responsibility |
|---|---|
BrowserPanel | Serves as the primary container for the child webview tab. |
BrowserControls | Provides navigation (Back, Forward, Reload) and debug tools. |
AnnotationPanel | Manages the interface for creating, reviewing, and labeling annotations. |
AnnotationExportModal | Handles packaging annotations and metadata for external use. |
Sources: README.md:89-91, CHANGELOG.md:129-131
State Management
Browser sessions and annotations rely on two dedicated Zustand stores:
browser-session-store: Manages active tabs, history, and session metadata.annotation-store: Stores captured web states, intent labels, and severity markings.
Sources: README.md:58, README.md:91
Browser Automation and Control
The system integrates with the Chrome DevTools Protocol (CDP) to automate browser actions and retrieve page data. This allows agents to perform web-based tasks and allows the application to monitor browser state changes.
Navigation and Interaction Flow
The BrowserControls component facilitates standard navigation and provides access to debugging tools like the Debug Console.
Sources: src/renderer/components/browser/BrowserControls.tsx, src-tauri/src/browser_automation/cdp.rs
Web Annotation Workflow
Termul provides a specialized workflow for annotating web pages. Users capture specific states of the embedded browser to document findings or requirements.
Annotation Features
- Capture States: Users save the current DOM state and visual representation of a page.
- Labeling: Annotations support intent labels (e.g., bug, feature, observation) and severity levels.
- Review and Export: The
AnnotationPanelallows users to review collected data before exporting it in structured formats via theAnnotationExportModal. - Selector Fix: A known fix ensures element selectors function correctly even when placed inside form tags.
Sources: README.md:46-48, CHANGELOG.md:104-105
Data Flow for Annotations
Sources: README.md:44-48, README.md:89-91
Security and Production Constraints
The browser implementation includes specific security measures to prevent unauthorized access and ensure stability in production environments.
Security and Reliability Measures
- IPC Caller Validation: The system validates the origin of IPC calls from browser tabs to prevent malicious command execution.
- DevTools Gating: The "Debug Console" and
browser_tab_open_devtoolscommand are explicitly disabled in production builds (import.meta.env.PROD). - Error Logging: Tool failures within the browser emit durable host-boundary logs. These logs include error codes and agent IDs but redact sensitive session data and argument values.
- URL Handling: Termul can be configured to open URLs clicked in the terminal within internal browser tabs.
Sources: src/renderer/lib/tests/parity-checklist.test.ts:741-760, AGENTS.md:27-29, CHANGELOG.md:112-113
Configuration Summary
| Feature | Production Behavior | Development Behavior |
|---|---|---|
| DevTools | Disabled/Blocked | Enabled via F12/Controls |
| Error Logging | Redacted (CWE-532) | Full Detail |
| IPC Access | Validated Callers Only | Validated Callers Only |
Sources: src/renderer/lib/tests/parity-checklist.test.ts:741-760, AGENTS.md:27-29
Conclusion
The Embedded Browser and Web Annotation system provides a project-integrated browsing experience. By combining standard navigation with CDP-powered automation and a structured annotation store, Termul enables developers to maintain web context directly alongside their code and terminal sessions. The system maintains strict security boundaries by gating debug tools and validating IPC communication.