2f9ff11204
Change module path from forge.lthn.ai/core/go-webview to dappco.re/go/core/webview. Update all Go imports and documentation references. The go-log dependency uses a replace directive to resolve via the forge until the vanity redirect is configured. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
72 lines
3.3 KiB
Markdown
72 lines
3.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
Module: `dappco.re/go/core/webview` — Chrome DevTools Protocol client for browser automation.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
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`.
|
|
|
|
```bash
|
|
# 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 `coreerr.E("Scope.Method", "description", err)` from `go-log`, never `fmt.Errorf`
|
|
- 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
|
|
|
|
```bash
|
|
git push ssh://git@forge.lthn.ai:2223/core/go-webview.git HEAD:main
|
|
```
|