From 20c89a61d9e94a99aba0d10eae87886a99c0b1e8 Mon Sep 17 00:00:00 2001 From: Ian Gulliver Date: Sat, 15 Aug 2026 13:16:05 -0700 Subject: [PATCH] Add screenshot capture tool and dev setup docs --- .gitignore | 1 + docs/dev.md | 3 +++ docs/plan.md | 2 +- docs/screenshots.md | 27 ++++++++++++++++++++++++++ docs/setup.md | 11 +++++++++++ go.mod | 12 ++++++++++++ go.sum | 21 ++++++++++++++++++++ tools/screenshot/main.go | 41 ++++++++++++++++++++++++++++++++++++++++ 8 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 docs/screenshots.md create mode 100644 docs/setup.md create mode 100644 go.sum create mode 100644 tools/screenshot/main.go diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b19ec16 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/screenshots/ diff --git a/docs/dev.md b/docs/dev.md index ab5ddd7..b73adb4 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -1,5 +1,7 @@ # Local development +Toolchain prerequisites: see [setup.md](setup.md). + ## Run go run . @@ -16,3 +18,4 @@ The server reads local data from `sampledata/`, mirroring the production Sheets - `internal/data` — data source interface and the CSV sample-data implementation - `internal/directory` — directory app handlers - `web/directory` — directory app page templates and static assets +- `tools/screenshot` — dev-site page capture, see [screenshots.md](screenshots.md) diff --git a/docs/plan.md b/docs/plan.md index 29934bd..071590f 100644 --- a/docs/plan.md +++ b/docs/plan.md @@ -19,7 +19,7 @@ - One command starts the local server. - Templates, static assets, and content reload on change without restarting the server. - A local data mode serves generated, non-production sample data so contributors never need real community data to develop or test. -- A documented screenshot mechanism captures pages from the local dev server, so agents (and humans) can verify visual changes. See `docs/screenshots.md` once it exists. +- A documented screenshot mechanism captures pages from the local dev server, so agents (and humans) can verify visual changes. See `docs/screenshots.md`. ## Directory app diff --git a/docs/screenshots.md b/docs/screenshots.md new file mode 100644 index 0000000..f119e93 --- /dev/null +++ b/docs/screenshots.md @@ -0,0 +1,27 @@ +# Screenshots + +`tools/screenshot` captures pages from the local dev server as PNGs, so humans and agents can verify visual changes. It drives a locally installed Chrome (or Chromium) headless via chromedp; no other browser tooling is required. + +## Usage + +With the server running: + + go run ./tools/screenshot -url http://localhost:8080/directory/ -out screenshots/directory.png -wait header + +Flags: + +- `-url` — page to capture (default `http://localhost:8080/directory/`) +- `-out` — output PNG path (default `screenshots/capture.png`); `screenshots/` is gitignored +- `-wait` — CSS selector that must be visible before capture (default `body`); pass a selector the page's JavaScript renders (for example `.card`) to capture after data loads + +The capture is a full-page screenshot at a 1280×800 viewport. + +## Agent recipe + +One self-contained command that starts the server, captures, and shuts down: + + go run . & + go run ./tools/screenshot -out screenshots/directory.png -wait header + kill $(lsof -ti :8080) + +Then read `screenshots/directory.png` to inspect the result. diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..d3c082e --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,11 @@ +# Dev environment setup + +Development happens on macOS. Two Homebrew installs, and everything in `docs/dev.md` and `docs/screenshots.md` works: + + brew install go + brew install --cask google-chrome + +- **Go** 1.26 or later — builds and runs the server and all tooling (`go run`, `go vet`). +- **Google Chrome** — launched headless by the screenshot tool; never needs to be opened by hand. The tool finds it in its standard install location automatically. + +No Node, no Docker, and no cloud credentials are needed for local development. diff --git a/go.mod b/go.mod index f54468d..ea8e175 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,15 @@ module heliosian go 1.26 + +require github.com/chromedp/chromedp v0.16.0 + +require ( + github.com/chromedp/cdproto v0.0.0-20260714215040-dc233986426f // indirect + github.com/chromedp/sysutil v1.1.0 // indirect + github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68 // indirect + github.com/gobwas/httphead v0.1.0 // indirect + github.com/gobwas/pool v0.2.1 // indirect + github.com/gobwas/ws v1.4.0 // indirect + golang.org/x/sys v0.47.0 // indirect +) diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..59964b8 --- /dev/null +++ b/go.sum @@ -0,0 +1,21 @@ +github.com/chromedp/cdproto v0.0.0-20260714215040-dc233986426f h1:0Z1zcSLEmnj2c2CmJYBqewtS6pxhB39bNWUSEUAWjgk= +github.com/chromedp/cdproto v0.0.0-20260714215040-dc233986426f/go.mod h1:RwFsSODCtFExll+GhHM6R92SARHR3Z3oipaxLHj46C0= +github.com/chromedp/chromedp v0.16.0 h1:rOO4deOm4CbZgBCa8mD9g2rDyIoNs0BkgvNrlbp5ouk= +github.com/chromedp/chromedp v0.16.0/go.mod h1:rbuGKFT1vMcFcFqKfPIO1GpX/N+2s8onm2qMxZLbU5U= +github.com/chromedp/sysutil v1.1.0 h1:PUFNv5EcprjqXZD9nJb9b/c9ibAbxiYo4exNWZyipwM= +github.com/chromedp/sysutil v1.1.0/go.mod h1:WiThHUdltqCNKGc4gaU50XgYjwjYIhKWoHGPTUfWTJ8= +github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68 h1:KZaTBSyshWX3MP5jukJcNSuXDQTO+rNpt0J564dX/eg= +github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg= +github.com/gobwas/httphead v0.1.0 h1:exrUm0f4YX0L7EBwZHuCF4GDp8aJfVeBrlLQrs6NqWU= +github.com/gobwas/httphead v0.1.0/go.mod h1:O/RXo79gxV8G+RqlR/otEwx4Q36zl9rqC5u12GKvMCM= +github.com/gobwas/pool v0.2.1 h1:xfeeEhW7pwmX8nuLVlqbzVc7udMDrwetjEv+TZIz1og= +github.com/gobwas/pool v0.2.1/go.mod h1:q8bcK0KcYlCgd9e7WYLm9LpyS+YeLd8JVDW6WezmKEw= +github.com/gobwas/ws v1.4.0 h1:CTaoG1tojrh4ucGPcoJFiAQUAsEWekEWvLy7GsVNqGs= +github.com/gobwas/ws v1.4.0/go.mod h1:G3gNqMNtPppf5XUz7O4shetPpcZ1VJ7zt18dlUeakrc= +github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80 h1:6Yzfa6GP0rIo/kULo2bwGEkFvCePZ3qHDDTC3/J9Swo= +github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80/go.mod h1:imJHygn/1yfhB7XSJJKlFZKl/J+dCPAknuiaGOshXAs= +github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde h1:x0TT0RDC7UhAVbbWWBzr41ElhJx5tXPWkIHA2HWPRuw= +github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde/go.mod h1:nZgzbfBr3hhjoZnS66nKrHmduYNpc34ny7RK4z5/HM0= +golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs= +golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= diff --git a/tools/screenshot/main.go b/tools/screenshot/main.go new file mode 100644 index 0000000..e98229e --- /dev/null +++ b/tools/screenshot/main.go @@ -0,0 +1,41 @@ +// Command screenshot captures a page from the local dev server as a PNG. +package main + +import ( + "context" + "flag" + "log" + "os" + "path/filepath" + "time" + + "github.com/chromedp/chromedp" +) + +func main() { + url := flag.String("url", "http://localhost:8080/directory/", "page to capture") + out := flag.String("out", "screenshots/capture.png", "output png path") + wait := flag.String("wait", "body", "css selector that must be visible before capturing") + flag.Parse() + ctx, cancelBrowser := chromedp.NewContext(context.Background()) + defer cancelBrowser() + ctx, cancelTimeout := context.WithTimeout(ctx, 30*time.Second) + defer cancelTimeout() + var png []byte + err := chromedp.Run(ctx, + chromedp.EmulateViewport(1280, 800), + chromedp.Navigate(*url), + chromedp.WaitVisible(*wait, chromedp.ByQuery), + chromedp.FullScreenshot(&png, 90), + ) + if err != nil { + log.Fatalf("[ERROR] capture %s: %v", *url, err) + } + if err := os.MkdirAll(filepath.Dir(*out), 0o755); err != nil { + log.Fatalf("[ERROR] create output dir: %v", err) + } + if err := os.WriteFile(*out, png, 0o644); err != nil { + log.Fatalf("[ERROR] write %s: %v", *out, err) + } + log.Printf("captured %s to %s", *url, *out) +}