browse/PLAN.md

Plan: Web Debugging Commands

Phase 1: Storage & Session Commands

Description

Add commands for inspecting and manipulating browser storage and cookies. These are essential for debugging authentication, session state, and client-side data persistence.

Steps

Step 1.1: Add Cookies Command

• Objective: Implement get/set/clear cookies functionality
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add CookiesCommand type with action: 'get' | 'set' | 'clear'
  • Add optional name, value, url fields for set operation
  • Implement cookies() method using context.cookies() and context.addCookies()
  • Add logging with cookie icon

Step 1.2: Add Storage Command

• Objective: Implement localStorage and sessionStorage read/write/clear
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: Step 1.1
• Implementation:
  • Add StorageCommand type with storage: 'local' | 'session' and action: 'get' | 'set' | 'clear'
  • Implement via page.evaluate() accessing window.localStorage / window.sessionStorage
  • Return all items on get, or specific key if provided

Phase 2: Console & Debugging Commands

Description

Add commands for capturing console output and debugging page state. Critical for understanding client-side errors and application behavior.

Steps

Step 2.1: Add Console Command

• Objective: Capture and return console messages (log, error, warn, info)
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add ConsoleCommand type with optional clear: boolean
  • Store console messages in array via page.on('console')
  • Initialize listener in launch() method
  • Return accumulated messages with type, text, and timestamp

Step 2.2: Add Metrics Command

• Objective: Return performance metrics and DOM statistics
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add MetricsCommand type
  • Use page.evaluate() to gather performance.timing, DOM node counts
  • Return structured metrics object

Phase 3: Interaction Commands

Description

Add commands for advanced page interactions beyond click and type. Enables testing hover states, keyboard shortcuts, and form controls.

Steps

Step 3.1: Add Scroll Command

• Objective: Scroll to position, element, or by delta
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add ScrollCommand with selector?: string, x?: number, y?: number, behavior?: 'smooth' | 'instant'
  • If selector provided, use element.scrollIntoView()
  • Otherwise use window.scrollTo()

Step 3.2: Add Hover Command

• Objective: Trigger hover state on element
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add HoverCommand with selector: string
  • Use page.hover(selector)
  • Return success with element info

Step 3.3: Add Select Command

• Objective: Select option(s) in dropdown/select elements
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add SelectCommand with selector: string, value: string | string[]
  • Use page.selectOption(selector, value)
  • Return selected values

Step 3.4: Add Keys Command

• Objective: Send keyboard shortcuts and special keys
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add KeysCommand with keys: string (e.g., "Control+a", "Escape", "Enter")
  • Use page.keyboard.press() for single keys
  • Support key combinations

Phase 4: Network Commands

Description

Add commands for network inspection and manipulation. Enables debugging API calls, blocking resources, and simulating network conditions.

Steps

Step 4.1: Add Network Logging

• Objective: Capture and return network requests/responses
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add NetworkCommand with action: 'log' | 'clear', optional filter: string
  • Store requests via page.on('request') and page.on('response')
  • Return array of {url, method, status, type, timing}

Step 4.2: Add Block Command

• Objective: Block URLs or patterns (ads, analytics, etc.)
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: Step 4.1
• Implementation:
  • Add BlockCommand with patterns: string[] and action: 'add' | 'remove' | 'clear'
  • Use page.route() to abort matching requests
  • Maintain list of blocked patterns

Step 4.3: Add Throttle Command

• Objective: Simulate slow network conditions
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add ThrottleCommand with preset: 'slow3g' | 'fast3g' | 'offline' | 'none'
  • Use CDP session to set network conditions via Network.emulateNetworkConditions

Phase 5: Output Commands

Description

Add commands for exporting page content in different formats.

Steps

Step 5.1: Add PDF Command

• Objective: Save page as PDF
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add PdfCommand with path: string, optional format, landscape, margin
  • Use page.pdf() (WebKit supports this)
  • Return path to saved file

Step 5.2: Add Accessibility Command

• Objective: Dump accessibility tree snapshot
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add AccessibilityCommand with optional selector for subtree
  • Use page.accessibility.snapshot()
  • Return tree structure

Phase 6: Advanced Commands

Description

Add commands for viewport manipulation, device emulation, and frame handling.

Steps

Step 6.1: Add Viewport Command

• Objective: Resize viewport dynamically
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add ViewportCommand with width: number, height: number
  • Use page.setViewportSize()
  • Return new dimensions

Step 6.2: Add Emulate Command

• Objective: Emulate mobile devices
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: Step 6.1
• Implementation:
  • Add EmulateCommand with device: string (e.g., 'iPhone 12', 'Pixel 5')
  • Use Playwright's device descriptors
  • Apply viewport, userAgent, deviceScaleFactor

Step 6.3: Add Frames Command

• Objective: List and switch to iframe contexts
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add FramesCommand with action: 'list' | 'switch', optional selector or index
  • Use page.frames() to list, frame.locator() to switch context
  • Track current frame for subsequent commands

Step 6.4: Add Dialog Command

• Objective: Handle alert/confirm/prompt dialogs
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add DialogCommand with action: 'accept' | 'dismiss', optional text for prompt
  • Set up page.on('dialog') handler
  • Queue dialogs and respond based on command

Step 6.5: Add Upload Command

• Objective: Fill file input elements
• Files: src/types.ts, src/browser.ts, src/server.ts, src/index.ts
• Dependencies: None
• Implementation:
  • Add UploadCommand with selector: string, files: string[]
  • Use page.setInputFiles(selector, files)
  • Return success with file count

Phase 7: Documentation & Polish

Description

Update documentation and CLI help text with all new commands.

Steps

Step 7.1: Update README

• Objective: Document all new commands with examples
• Files: README.md
• Dependencies: Phases 1-6
• Implementation:
  • Add command reference section
  • Include curl examples for each command
  • Document response formats

Step 7.2: Update CLAUDE.md

• Objective: Update developer documentation
• Files: CLAUDE.md
• Dependencies: Step 7.1
• Implementation:
  • Update architecture section with new command flow
  • Document internal logging format

Step 7.3: Update CLI Help

• Objective: Update --help output with command list
• Files: src/cli.ts
• Dependencies: Phases 1-6
• Implementation:
  • Expand server mode help section
  • Group commands by category