Note this is a vibe coded experiement created using clause code. The associated thread on discord is here. https://discord.com/channels/1309454711392305192/1345694579302596699

This project provides tools for inspecting and controlling frames in Chrome, with a focus on IWA (Isolated Web Apps) and controlled frames.

Webviews function as controlled frames in IWAs. Our tools identify these webviews and demonstrate how to control them directly via Chrome DevTools Protocol.

• Connect to a running Chrome instance with remote debugging enabled
• Find IWAs and their associated webviews (controlled frames)
• Inspect and control webviews directly via Chrome DevTools Protocol
• Inject JavaScript into controlled frames to extract data or modify content

• Node.js (v14+) or Bun
• Chrome browser with remote debugging enabled
• For IWA inspection: A running Isolated Web App

# Install dependencies
bun install

To use these tools, Chrome must be running with remote debugging enabled on port 9222:

# MacOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Windows
start chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

The project includes these tools:

1. Basic Chrome Inspector

   bun run inspect-chrome

   This tool simply connects to Chrome and lists all available targets.

2. IWA Frame Inspector

   bun run inspect-iwa

   This tool identifies IWA contexts and inspects their controlled frames.

3. IWA Relations Detector (Recommended)

   bun run find-iwa-relations

   This specialized tool finds the relationship between IWAs and their webviews (controlled frames) with a detailed analysis.

4. Control Webview Frames

   bun run control-webview

   This tool demonstrates how to directly control a webview by injecting JavaScript and showing a visual highlight.

5. Advanced Controlled Frames Detector

   bun run find-controlled-frames

   This advanced tool uses multiple detection techniques to find controlled frames within IWAs.

6. Frame Controller

   bun run control-frames

   This tool demonstrates how to directly control a frame once it's been identified.

In our investigation, we've discovered:

1. Webviews as Controlled Frames: Webviews (type: 'webview') typically function as controlled frames within IWAs.

2. IWA Structure: An IWA (type: 'app' with URL starting with isolated-app://) can contain multiple webviews.

3. Direct Control Method: Each webview can be controlled by connecting directly to its target ID using Chrome DevTools Protocol.

The tools use various techniques to identify controlled frames:

• Target Type Analysis: Looking for webviews related to IWAs
• URL Pattern Matching: Correlating targets using IWA-specific URL patterns
• controlledFrames API: Detecting frames that are programmatically controlled
• Feature Detection: Testing for IWA-specific JavaScript APIs

The project also includes integration with Stagehand for AI-powered browser automation using Claude 3.7:

# Run Stagehand test with Claude 3.7
bun run test:stagehand

See CLAUDE.md for more details on Stagehand setup and usage.

• No targets found: Ensure Chrome is running with remote debugging enabled on port 9222
• Cannot connect to specific target: Some targets may restrict debugging access for security reasons

MIT