go-webview/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Module: forge.lthn.ai/core/go-webview — Chrome DevTools Protocol client for browser automation.

Commands

go test ./...                          # Run all tests (must pass before commit)
go test -v -run TestActionSequence_Good ./...  # Run a single test
gofmt -w .                             # Format code
go vet ./...                           # Static analysis

Prerequisites

Tests and usage require a running Chrome/Chromium with --remote-debugging-port=9222. The package does not launch Chrome itself. Verify with curl http://localhost:9222/json.

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

# Headless (CI)
google-chrome --headless=new --remote-debugging-port=9222 --no-sandbox --disable-gpu

Architecture

Application Code → Webview (high-level API) → CDPClient (WebSocket transport) → Chrome

Single flat package (package webview). No sub-packages.

File	Layer	Purpose
cdp.go	Transport	WebSocket connection, CDP message framing, event dispatch. No browser-level logic.
webview.go	High-level API	Navigate, Click, Type, Screenshot, DOM queries, console capture. Application-facing.
actions.go	Action system	Action interface + concrete types (ClickAction, TypeAction, etc.) + fluent ActionSequence builder.
console.go	Diagnostics	ConsoleWatcher (filtered console capture) and ExceptionWatcher (JS exception tracking).
angular.go	SPA helpers	Angular-specific: Zone.js stability, router navigation, component introspection, ngModel access.

Key patterns:

• CDPClient.Call(ctx, method, params) sends a CDP command and blocks for the response via a pending-channel map.
• Events flow from Chrome → readLoop goroutine → registered handlers (each dispatched in its own goroutine).
• Webview enables Runtime, Page, and DOM CDP domains on construction; console capture starts immediately.
• New action types: add struct + Execute method in actions.go, builder method on ActionSequence, _Good test.
• New SPA framework helpers: create <framework>.go following the angular.go pattern.

Coding Standards

• UK English in all comments, docs, and commit messages (behaviour, colour, initialise)
• EUPL-1.2 licence header (// SPDX-License-Identifier: EUPL-1.2) in every Go file
• Conventional commits: type(scope): description (scopes: cdp, angular, console, actions)
• Co-author trailer on every commit: Co-Authored-By: Virgil <virgil@lethean.io>
• Test naming: _Good (happy path), _Bad (expected errors), _Ugly (panics/edge cases)
• Standard testing.T only — no test frameworks
• Wrap errors with fmt.Errorf("context: %w", err)
• Protect shared state with sync.RWMutex; copy handler slices before calling outside lock

Docs

• docs/architecture.md — CDP connection, DOM queries, console capture, Angular helpers
• docs/development.md — prerequisites, build/test, coding standards, adding actions
• docs/history.md — completed phases, known limitations, future considerations

Forge Push

git push ssh://git@forge.lthn.ai:2223/core/go-webview.git HEAD:main