A running Chrome or Chromium instance with the remote debugging port enabled is required for any tests or usage that exercises the CDP connection. The package does not launch Chrome itself.
Tests must pass before committing. The integration tests in `webview_test.go` that reference a live browser (`TestNew_Bad_InvalidDebugURL`) are designed to fail gracefully -- they assert that the error is non-nil when connecting to an unavailable port.
UK English throughout all source comments, documentation, commit messages, and identifiers where natural language appears. Use "colour", "organisation", "behaviour", "initialise", not their American equivalents.
### Formatting
Standard `gofmt` formatting is mandatory. Run before committing:
```bash
gofmt -w .
```
### Types and Error Handling
- All exported functions must have Go doc comments.
- Use `fmt.Errorf("context: %w", err)` for error wrapping so callers can use `errors.Is` and `errors.As`.
- Return errors; do not panic in library code.
- Use `context.Context` for all operations that involve I/O or waiting so callers can impose deadlines.
### Concurrency
- Protect shared mutable state with `sync.RWMutex` (read lock for reads, write lock for writes).
- Do not call handlers or callbacks while holding a lock. Copy the slice of handlers, release the lock, then call them.
- CDP WebSocket writes are serialised with a dedicated mutex in `CDPClient`; do not write to `conn` directly from outside `cdp.go`.
### Licence Header
Every Go source file must begin with:
```go
// SPDX-License-Identifier: EUPL-1.2
```
The project is licenced under the European Union Public Licence 1.2 (EUPL-1.2).
## Commit Guidelines
Use conventional commits:
```
type(scope): description
```
Common types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`.
Example scopes: `cdp`, `angular`, `console`, `actions`.
All commits must include the co-author trailer:
```
Co-Authored-By: Virgil <virgil@lethean.io>
```
Full example:
```
feat(console): add ExceptionWatcher with stack trace capture
Subscribes to Runtime.exceptionThrown events and exposes a reactive
WaitForException API consistent with ConsoleWatcher.
Co-Authored-By: Virgil <virgil@lethean.io>
```
## Adding a New Action Type
1. Define a struct in `actions.go` with exported fields for the action's parameters.
2. Implement `Execute(ctx context.Context, wv *Webview) error` on the struct.
3. Add a builder method on `ActionSequence` that appends the new action.
4. Add a `_Good` test in `webview_test.go` that verifies the struct fields are set correctly.
Example:
```go
// SubmitAction submits a form element.
type SubmitAction struct {
Selector string
}
func (a SubmitAction) Execute(ctx context.Context, wv *Webview) error {
