Refactor DevBrowser: flatten structure, rewrite server in Python

Refactor DevBrowser: flatten structure and rewrite server in Python.

Problem

Current structure is over-nested and doesn't follow repo conventions:

Omni/Ide/DevBrowser/
├── skills/
│   └── dev-browser/          # Redundant nesting!
│       ├── SKILL.md
│       ├── src/              # ~1900 lines TypeScript
│       ├── scripts/
│       ├── node_modules/     # 100+ npm dependencies
│       └── package.json
├── extension/                # Chrome extension (must stay TS)
└── package.json              # Just prettier/husky

Import paths are awkward: ../../Ide/DevBrowser/skills/dev-browser/SKILL.md

Target Structure

Omni/Ide/DevBrowser.md        # Skill doc (moved from SKILL.md)
Omni/Ide/DevBrowser.py        # Server rewritten in Python (~500 lines)
Omni/Ide/DevBrowser/
├── Extension/                # Chrome extension (keep as TypeScript)
│   ├── entrypoints/
│   ├── services/
│   └── package.json
└── references/               # Scraping guide etc.

Server Rewrite: TypeScript → Python

Current TypeScript components (~1900 lines)

| File | Lines | Purpose | |------|-------|---------| | src/index.ts | 551 | HTTP server, launches Chromium via Playwright, page management | | src/client.ts | 465 | Client library for agents to connect and control pages | | src/relay.ts | 731 | Relay for extension mode (proxies between extension and clients) | | src/types.ts | 27 | Type definitions | | scripts/start-server.ts | 117 | Server entry point | | scripts/start-relay.ts | 32 | Relay entry point |

Python rewrite plan

Use playwright-python (official Playwright bindings) + FastAPI/Flask.

**Core server (Omni/Ide/DevBrowser.py):**

• Launch headless Chromium with persistent profile
• HTTP API endpoints:
• GET / - server info
• POST /page - create/get named page
• GET /pages - list pages
• DELETE /page/:name - close page
• POST /snapshot/:name - get ARIA snapshot
• POST /select/:name/:ref - select element by snapshot ref
• WebSocket proxy to CDP endpoint
• ~300-500 lines estimated

Client usage stays the same - agents use the HTTP API via curl/fetch or the TypeScript client library. We can keep a minimal client.ts for the npx tsx workflow, or agents can use raw HTTP.

Relay for extension mode:

• Could be a separate Omni/Ide/DevBrowser/Relay.py
• Or combined into main server with --relay flag
• Lower priority since most workflows use headless

Dependencies eliminated

Remove (node_modules, ~100+ packages):

• express, hono, playwright (npm), tsx, typescript, vitest, etc.

Add (Python, managed by bild):

• playwright (pip)
• fastapi or flask
• uvicorn (if FastAPI)

Extension (Keep as TypeScript)

The Chrome extension must stay JavaScript/TypeScript - it runs inside Chrome.

| File | Lines | Purpose | |------|-------|---------| | entrypoints/background.ts | 150 | Extension background script | | services/CDPRouter.ts | 211 | Routes CDP commands | | services/ConnectionManager.ts | 214 | WebSocket connection to relay | | services/StateManager.ts | 28 | Extension state | | services/TabManager.ts | 218 | Tab management |

Move from Omni/Ide/DevBrowser/extension/ → Omni/Ide/DevBrowser/Extension/

Extension is optional - most workflows use headless mode. Only needed when controlling user's real browser with existing cookies/sessions.

Migration Steps

1. Write Python server (Omni/Ide/DevBrowser.py)

• Port core functionality from src/index.ts
• Use playwright-python
• Add CLI with --port, --headless, --profile-dir options
• Make it executable with bild shebang

2. Move and update skill doc

• skills/dev-browser/SKILL.md → Omni/Ide/DevBrowser.md
• Update instructions for Python server
• Update example scripts (may still use npx tsx for client, or convert to Python)

3. Update systemd service (~/.config/systemd/user/devbrowser.service) ini WorkingDirectory=/home/ben/omni/live ExecStart=/home/ben/omni/live/_/nix/Omni/Ide/DevBrowser.py/dev-browser/bin/dev-browser --headless

4. Move extension

• extension/ → Omni/Ide/DevBrowser/Extension/
• Keep its own package.json for wxt build

5. Update import paths in workflows

• Omni/Agent/Workflows/Designer.md: change import to ../../Ide/DevBrowser.md

6. Move references

• skills/dev-browser/references/ → Omni/Ide/DevBrowser/references/

7. Delete old structure

• Remove skills/dev-browser/ (after verifying everything works)
• Remove root package.json (prettier/husky not needed)

8. Test

• Run systemctl --user restart devbrowser
• Run Designer workflow
• Verify screenshots work

Client Library Decision

Options for agent scripts:

A) Keep minimal TypeScript client - agents continue using npx tsx scripts

• Pro: No change to skill instructions
• Con: Still need node_modules for client

B) Raw HTTP from bash - agents use curl

• Pro: Zero dependencies
• Con: More verbose scripts

C) Python client - agents use Python scripts

• Pro: Consistent with server
• Con: Change to skill instructions

Recommend: Start with (A), migrate to (B) or (C) later.

Success Criteria

• [ ] bild Omni/Ide/DevBrowser.py builds successfully
• [ ] Server starts and accepts connections
• [ ] Can create pages, navigate, take screenshots
• [ ] ARIA snapshot works
• [ ] Systemd service runs the Python version
• [ ] Designer workflow works end-to-end
• [ ] Extension still builds (if needed)
• [ ] No more skills/dev-browser/ directory
• [ ] node_modules eliminated (except in Extension/)