src/frontend_workspaces/README.md

CUGA Frontend Workspaces

Monorepo for the CUGA browser extension and frontend tooling, managed with pnpm workspaces.

📦 Workspace Packages

• extension: Browser extension (Chrome/Edge/Firefox) that serves as the entry point to CUGA
• runtime: DOM/content-script runtime used by the extension and libraries
• shared (@uiagent/shared): Shared TypeScript utilities and types consumed by other packages
• agentic_chat: React-based frontend for the extension's side panel
• frontend: Alternative frontend implementation

🔧 Prerequisites

• Node.js 18+
• pnpm 8+ (Package manager - install with npm install -g pnpm)
• Chromium-based browser (Chrome or Edge). Firefox supported via dedicated scripts.

🚀 Quick Start

1. Install Dependencies

From the workspace root (frontend-workspaces/):

pnpm install

This installs all workspace dependencies and runs post-install steps (e.g., wxt prepare in the extension).

2. Start the Backend Server

• Add use_extension = true to your settings.toml file under advanced_features
• Run the debug VS Code configuration or start the server through the main entrypoint

3. Run the Extension

Copy the environment file and start development:

cd extension
cp .env-example .env  # Edit as needed
cd ..
pnpm --filter extension run dev

WXT will automatically open Chrome with the extension loaded.

📋 pnpm Commands Reference

Core Commands

Task	Command
Install all dependencies	pnpm install
Build all workspaces	pnpm -r build
Clean all node_modules	pnpm -r clean

Extension Commands

Task	Command
Development (Chrome)	pnpm --filter extension run dev
Development (Firefox)	pnpm --filter extension run dev:firefox
Build for production	pnpm --filter extension run build
Build for Firefox	pnpm --filter extension run build:firefox
Release build (copy to releases/)	pnpm --filter extension run release
Release build for Firefox	pnpm --filter extension run release:firefox
Create distribution zip	pnpm --filter extension run zip
Run E2E tests	pnpm --filter extension run e2etest
Type checking	pnpm --filter extension run compile

Frontend Commands

Task	Command
Development server	pnpm --filter frontend run dev
Build for production	pnpm --filter frontend run build
Start production server	pnpm --filter frontend run start

Agentic Chat Commands

Task	Command
Development server	pnpm --filter agentic_chat run dev
Build for production	pnpm --filter agentic_chat run build
Run tests	pnpm --filter agentic_chat run test
Type checking	pnpm --filter agentic_chat run compile

Shared Library Commands

Task	Command
Build shared library	pnpm --filter @uiagent/shared run build
Watch mode	pnpm --filter @uiagent/shared run watch
Clean build	pnpm --filter @uiagent/shared run clean

Runtime Commands

Task	Command
Run tests	pnpm --filter runtime run test

🏗️ Build Process

Extension Build

1. Prepare environment:

   cd extension
   cp .env-example .env  # Edit values as needed
   

2. Build the extension:

   pnpm --filter extension run build
   

3. Load in browser:

   • Open Chrome/Edge → Manage Extensions
   • Enable Developer mode
   • Load Unpacked → select extension/.output/chrome-mv3/

Release Build

Build and copy to releases folder for distribution:

# Chrome/Edge release
pnpm --filter extension run release

# Firefox release  
pnpm --filter extension run release:firefox

This builds the extension, cleans the releases folder, and copies the fresh output to:

• extension/releases/chrome-mv3/ (Chrome/Edge)
• extension/releases/firefox-mv2/ (Firefox)

Distribution Build

Create a distributable zip file:

pnpm --filter extension run zip

Output will be in extension/.output/

🔍 Development Tips

Working with Multiple Packages

# Run command in specific workspace
pnpm --filter extension run [command]

# Run command in all workspaces
pnpm -r run [command]

# Run command in workspaces matching pattern
pnpm --filter "*chat*" run build

Dependency Management

# Add dependency to specific workspace
pnpm --filter extension add [package]

# Add dev dependency
pnpm --filter extension add -D [package]

# Add workspace dependency
pnpm --filter extension add agentic_chat@workspace:*

Debugging

# Watch mode for shared library
pnpm --filter @uiagent/shared run watch

# Development with hot reload
pnpm --filter extension run dev -- --watch --mode development

🌐 Browser Support

Chrome/Edge

• Full support with Manifest V3
• Hot reload during development
• Production builds ready for store submission

Firefox

• Beta support with Manifest V2
• Requires manual :has pseudo-selector enablement
• Use *:firefox script variants

🐛 Troubleshooting

Common Issues

Extension not appearing after build:

• Check terminal output for build directory
• Verify you're loading the correct .output/ folder

Type errors in shared library:

pnpm --filter @uiagent/shared run build
# Then restart dev servers

Dependency resolution issues:

# Clean and reinstall
rm -rf node_modules pnpm-lock.yaml
find . -name "node_modules" -type d -exec rm -rf {} +
pnpm install

Build failures:

• Ensure all workspace dependencies use workspace:* protocol
• Check that shared library is built before extension
• Verify environment files are properly configured

Firefox Specific

• Enable :has pseudo-selector: about:config → layout.css.has-selector.enabled → true
• Full support coming in Firefox 121+

📁 Project Structure

frontend-workspaces/
├── pnpm-workspace.yaml          # pnpm workspace configuration
├── package.json                 # Root package.json
├── extension/                   # Browser extension
│   ├── src/
│   ├── wxt.config.ts           # WXT configuration
│   └── .output/                # Build output
├── agentic_chat/               # React frontend
│   ├── src/
│   └── dist/
├── frontend/                   # Alternative frontend
├── shared/                     # Shared utilities
│   ├── src/
│   └── dist/
└── runtime/                    # Runtime utilities

🔄 Workflow Examples

Full Development Setup

# 1. Install everything
pnpm install

# 2. Build shared library first
pnpm --filter @uiagent/shared run build

# 3. Start extension development
pnpm --filter extension run dev

Production Build

# Build all packages
pnpm -r build

# Or build specific packages in order
pnpm --filter @uiagent/shared run build
pnpm --filter agentic_chat run build  
pnpm --filter extension run build

Testing

# Run all tests
pnpm -r test

# Test specific package
pnpm --filter extension run e2etest