High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: add Lite Engine with Gost-DOM for Chrome-free DOM capture
Yash Jadhavc3ffb99dbd15
diff --git a/cmd/pinchtab/cmd_bridge.go b/cmd/pinchtab/cmd_bridge.goindex 982b54e3..28c22e56 100644--- a/cmd/pinchtab/cmd_bridge.go+++ b/cmd/pinchtab/cmd_bridge.go@@ -13,6 +13,7 @@ import ("github.com/pinchtab/pinchtab/internal/assets""github.com/pinchtab/pinchtab/internal/bridge""github.com/pinchtab/pinchtab/internal/config"+ "github.com/pinchtab/pinchtab/internal/engine""github.com/pinchtab/pinchtab/internal/handlers")@@ -35,6 +36,15 @@ func runBridgeServer(cfg *config.RuntimeConfig) {// Register all bridge handlersh := handlers.New(bridgeInstance, cfg, nil, nil, nil)++ // Wire engine router if mode is "lite" or "auto".+ mode := engine.Mode(cfg.Engine)+ if mode == engine.ModeLite || mode == engine.ModeAuto {+ lite := engine.NewLiteEngine()+ h.Router = engine.NewRouter(mode, lite)+ slog.Info("engine router enabled", "mode", cfg.Engine, "rules", h.Router.Rules())+ }+shutdownOnce := &sync.Once{}doShutdown := func() {shutdownOnce.Do(func() {diff --git a/go.mod b/go.modindex 97ab1995..717a119a 100644--- a/go.mod+++ b/go.mod@@ -6,6 +6,7 @@ require (github.com/chromedp/cdproto v0.0.0-20250803210736-d308e07a266dgithub.com/chromedp/chromedp v0.14.2github.com/gobwas/ws v1.4.0+ github.com/shirou/gopsutil/v4 v4.26.2gopkg.in/yaml.v3 v3.0.1)@@ -16,11 +17,16 @@ require (github.com/go-ole/go-ole v1.2.6 // indirectgithub.com/gobwas/httphead v0.1.0 // indirectgithub.com/gobwas/pool v0.2.1 // indirect+ github.com/gost-dom/browser v0.11.0 // indirect+ github.com/gost-dom/css v0.1.0 // indirect+ github.com/kr/pretty v0.3.0 // indirectgithub.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirectgithub.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect- github.com/shirou/gopsutil/v4 v4.26.2 // indirect+ github.com/rogpeppe/go-internal v1.14.1 // indirectgithub.com/tklauser/go-sysconf v0.3.16 // indirectgithub.com/tklauser/numcpus v0.11.0 // indirectgithub.com/yusufpapurcu/wmi v1.2.4 // indirect+ golang.org/x/net v0.47.0 // indirectgolang.org/x/sys v0.41.0 // indirect+ gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 // indirect)diff --git a/go.sum b/go.sumindex 92913dc6..b99f9dcb 100644--- a/go.sum+++ b/go.sum@@ -4,6 +4,9 @@ github.com/chromedp/chromedp v0.14.2 h1:r3b/WtwM50RsBZHMUm9fsNhhzRStTHrKdr2zmwbZgithub.com/chromedp/chromedp v0.14.2/go.mod h1:rHzAv60xDE7VNy/MYtTUrYreSc0ujt2O1/C3bzctYBo=github.com/chromedp/sysutil v1.1.0 h1:PUFNv5EcprjqXZD9nJb9b/c9ibAbxiYo4exNWZyipwM=github.com/chromedp/sysutil v1.1.0/go.mod h1:WiThHUdltqCNKGc4gaU50XgYjwjYIhKWoHGPTUfWTJ8=+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=github.com/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/ISU=github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=github.com/go-json-experiment/json v0.0.0-20250725192818-e39067aee2d2 h1:iizUGZ9pEquQS5jTGkh4AqeeHCMbfbjeb0zMt0aEFzs=@@ -17,31 +20,59 @@ github.com/gobwas/pool v0.2.1/go.mod h1:q8bcK0KcYlCgd9e7WYLm9LpyS+YeLd8JVDW6Wezmgithub.com/gobwas/ws v1.4.0 h1:CTaoG1tojrh4ucGPcoJFiAQUAsEWekEWvLy7GsVNqGs=github.com/gobwas/ws v1.4.0/go.mod h1:G3gNqMNtPppf5XUz7O4shetPpcZ1VJ7zt18dlUeakrc=github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=+github.com/gost-dom/browser v0.11.0 h1:eBz3bzY6BrfIR7bA6LOJl3aIHW/+0a9GfKjMWcPbe6g=+github.com/gost-dom/browser v0.11.0/go.mod h1:P3WlayFDicfvxIg90iZIqLqYuR84FJ4jYf8Qf3bKevw=+github.com/gost-dom/css v0.1.0 h1:O4aXjnYonQH1EDwKysXCQOgGVLwCWd/+HJeGO15sDIE=+github.com/gost-dom/css v0.1.0/go.mod h1:BYfl+dr6Dzl6RoKn4op6TynJ7GmFqP0kFCM44NEVgNs=+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=+github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=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/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=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=+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU=github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=+github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=github.com/shirou/gopsutil/v4 v4.26.2 h1:X8i6sicvUFih4BmYIGT1m2wwgw2VG9YgrDTi7cIRGUI=github.com/shirou/gopsutil/v4 v4.26.2/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ=+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYICU0nA=github.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI=github.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw=github.com/tklauser/numcpus v0.11.0/go.mod h1:z+LwcLq54uWZTX0u/bGobaV34u6V7KNlTZejzM6/3MQ=github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=+golang.org/x/net v0.0.0-20211216030914-fe4d6282115f/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=+golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=+golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=+golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=-golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA=-golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=+gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY=+gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=+gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=diff --git a/internal/config/config.go b/internal/config/config.goindex 9f328987..62f005dc 100644--- a/internal/config/config.go+++ b/internal/config/config.go@@ -70,6 +70,9 @@ type RuntimeConfig struct {// IDPI (Indirect Prompt Injection defense) settingsIDPI IDPIConfig+ // Engine mode: "chrome" (default), "lite", or "auto"+ Engine string+// Scheduler settings (dashboard mode only)Scheduler SchedulerConfig}@@ -133,6 +136,7 @@ type ServerConfig struct {Bind string `json:"bind,omitempty"`Token string `json:"token,omitempty"`StateDir string `json:"stateDir,omitempty"`+ Engine string `json:"engine,omitempty"`}// BrowserConfig holds Chrome executable/runtime wiring.@@ -539,6 +543,9 @@ func Load() *RuntimeConfig {WrapContent: true,ScanTimeoutSec: 5,},++ // Engine default+ Engine: envOr("PINCHTAB_ENGINE", "chrome"),}finalizeProfileConfig(cfg)@@ -603,6 +610,9 @@ func applyFileConfig(cfg *RuntimeConfig, fc *FileConfig) {if fc.Server.StateDir != "" {cfg.StateDir = fc.Server.StateDir}+ if fc.Server.Engine != "" && os.Getenv("PINCHTAB_ENGINE") == "" {+ cfg.Engine = fc.Server.Engine+ }// Securityif fc.Security.AllowEvaluate != nil {cfg.AllowEvaluate = *fc.Security.AllowEvaluatediff --git a/internal/engine/engine.go b/internal/engine/engine.gonew file mode 100644index 00000000..7629ac33--- /dev/null+++ b/internal/engine/engine.go@@ -0,0 +1,72 @@+// Package engine provides a routing layer that decides whether to fulfil+// a request using the lightweight Gost-DOM engine ("lite") or Chrome (via CDP).+//+// The Router is the single entry point for handler code. Route rules are+// pluggable: callers add / remove rules without touching handlers, bridge,+// or any other package.+package engine++import "context"++// Capability identifies an operation the engine may handle.+type Capability string++const (+ CapNavigate Capability = "navigate"+ CapSnapshot Capability = "snapshot"+ CapText Capability = "text"+ CapClick Capability = "click"+ CapType Capability = "type"+ CapScreenshot Capability = "screenshot"+ CapPDF Capability = "pdf"+ CapEvaluate Capability = "evaluate"+ CapCookies Capability = "cookies"+)++// Mode controls the engine selection strategy.+type Mode string++const (+ ModeChrome Mode = "chrome" // always Chrome (default)+ ModeLite Mode = "lite" // always lite (screenshot/pdf return 501)+ ModeAuto Mode = "auto" // per-request routing via rules+)++// Decision is the routing verdict returned by a RouteRule.+type Decision int++const (+ Undecided Decision = iota // rule has no opinion+ UseLite // route to Gost-DOM+ UseChrome // route to Chrome+)++// NavigateResult is the response from a navigation.+type NavigateResult struct {+ TabID string `json:"tabId"`+ URL string `json:"url"`+ Title string `json:"title"`+}++// SnapshotNode represents a single node in the accessibility-style snapshot.+type SnapshotNode struct {+ Ref string `json:"ref"`+ Role string `json:"role"`+ Name string `json:"name"`+ Tag string `json:"tag,omitempty"`+ Value string `json:"value,omitempty"`+ Depth int `json:"depth"`+ Interactive bool `json:"interactive,omitempty"`+}++// Engine is the minimal interface both lite and chrome wrappers implement.+type Engine interface {+ Name() string+ Navigate(ctx context.Context, url string) (*NavigateResult, error)+ Snapshot(ctx context.Context, filter string) ([]SnapshotNode, error)+ Text(ctx context.Context) (string, error)+ Click(ctx context.Context, ref string) error+ Type(ctx context.Context, ref, text string) error+ Capabilities() []Capability+ Close() error+}diff --git a/internal/engine/lite.go b/internal/engine/lite.gonew file mode 100644index 00000000..2f932059--- /dev/null+++ b/internal/engine/lite.go@@ -0,0 +1,482 @@+package engine++import (+ "bytes"+ "context"+ "errors"+ "fmt"+ "io"+ "net/http"+ "strings"+ "sync"+ "time"++ "github.com/gost-dom/browser/dom"+ "github.com/gost-dom/browser/html"+ gosturl "github.com/gost-dom/browser/url"+ nethtml "golang.org/x/net/html"+)++var ErrLiteNotSupported = errors.New("operation not supported in lite mode")++// liteTab tracks one Gost-DOM window.+type liteTab struct {+ window html.Window+ url string+ refMap map[string]dom.Element+}++// LiteEngine implements Engine using Gost-DOM.+type LiteEngine struct {+ client *http.Client+ tabs map[string]*liteTab+ current string // active tab ID+ seq int // tab ID sequence counter+ mu sync.Mutex+}++// NewLiteEngine creates a Gost-DOM based engine.+func NewLiteEngine() *LiteEngine {+ return &LiteEngine{+ client: &http.Client{Timeout: 30 * time.Second},+ tabs: make(map[string]*liteTab),+ }+}++func (l *LiteEngine) Name() string { return "lite" }++func (l *LiteEngine) Capabilities() []Capability {+ return []Capability{CapNavigate, CapSnapshot, CapText, CapClick, CapType}+}++// Navigate opens a URL in the lite engine and returns the result.+func (l *LiteEngine) Navigate(ctx context.Context, url string) (*NavigateResult, error) {+ l.mu.Lock()+ defer l.mu.Unlock()++ // Fetch HTML via HTTP.+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)+ if err != nil {+ return nil, fmt.Errorf("lite navigate: %w", err)+ }+ req.Header.Set("User-Agent", "Mozilla/5.0 (compatible; PinchTab-Lite/1.0)")+ req.Header.Set("Accept", "text/html,application/xhtml+xml,*/*")++ resp, err := l.client.Do(req)+ if err != nil {+ return nil, fmt.Errorf("lite navigate fetch: %w", err)+ }+ defer resp.Body.Close()++ if resp.StatusCode >= 400 {+ return nil, fmt.Errorf("lite navigate: HTTP %d from %s", resp.StatusCode, url)+ }++ // Detect content type — only process HTML.+ ct := resp.Header.Get("Content-Type")+ if ct != "" && !strings.Contains(ct, "html") && !strings.Contains(ct, "xml") {+ return nil, fmt.Errorf("lite navigate: unsupported content type %q", ct)+ }++ // Strip <script> elements to prevent gost-dom panics (no JS engine).+ cleanBody, err := stripScripts(resp.Body)+ if err != nil {+ return nil, fmt.Errorf("lite navigate strip scripts: %w", err)+ }++ // Parse the cleaned HTML directly using gost-dom's reader API,+ // avoiding a second HTTP fetch.+ parsedURL := gosturl.ParseURL(url)+ win, err := html.NewWindowReader(cleanBody, parsedURL)+ if err != nil {+ return nil, fmt.Errorf("lite navigate open: %w", err)+ }++ l.seq+++ tabID := fmt.Sprintf("lite-%d", l.seq)+ l.tabs[tabID] = &liteTab{+ window: win,+ url: url,+ refMap: make(map[string]dom.Element),+ }+ l.current = tabID++ title := l.getTitle(win)++ return &NavigateResult{+ TabID: tabID,+ URL: url,+ Title: title,+ }, nil+}++// Snapshot returns the DOM tree as snapshot nodes.+func (l *LiteEngine) Snapshot(_ context.Context, filter string) ([]SnapshotNode, error) {+ l.mu.Lock()+ defer l.mu.Unlock()++ tab := l.tabs[l.current]+ if tab == nil || tab.window == nil {+ return nil, errors.New("no page loaded")+ }++ doc := tab.window.Document()+ if doc == nil {+ return nil, errors.New("no document")+ }++ body := doc.Body()+ if body == nil {+ return nil, errors.New("no body element")+ }++ tab.refMap = make(map[string]dom.Element)+ nodes := l.walkDOM(tab, body, filter, 0)+ return nodes, nil+}++// Text returns the visible text content of the page.+func (l *LiteEngine) Text(_ context.Context) (string, error) {+ l.mu.Lock()+ defer l.mu.Unlock()++ tab := l.tabs[l.current]+ if tab == nil || tab.window == nil {+ return "", errors.New("no page loaded")+ }++ doc := tab.window.Document()+ if doc == nil {+ return "", errors.New("no document")+ }++ body := doc.Body()+ if body == nil {+ return "", errors.New("no body element")+ }++ raw := body.TextContent()+ return normalizeWhitespace(raw), nil+}++// Click clicks an element identified by ref.+func (l *LiteEngine) Click(ctx context.Context, ref string) (retErr error) {+ l.mu.Lock()+ defer l.mu.Unlock()++ tab := l.tabs[l.current]+ if tab == nil {+ return errors.New("no page loaded")+ }++ el, ok := tab.refMap[ref]+ if !ok {+ return fmt.Errorf("ref %q not found (take a snapshot first)", ref)+ }++ // Recover from gost-dom panics (e.g., anchor click triggers navigation+ // to a page with scripts, but no JS engine is configured).+ defer func() {+ if r := recover(); r != nil {+ retErr = fmt.Errorf("click recovered from panic: %v", r)+ }+ }()++ if htmlEl, ok := el.(html.HTMLElement); ok {+ htmlEl.Click()+ return nil+ }+ return errors.New("element does not support click")+}++// Type enters text into an element identified by ref.+func (l *LiteEngine) Type(_ context.Context, ref, text string) error {+ l.mu.Lock()+ defer l.mu.Unlock()++ tab := l.tabs[l.current]+ if tab == nil {+ return errors.New("no page loaded")+ }++ el, ok := tab.refMap[ref]+ if !ok {+ return fmt.Errorf("ref %q not found (take a snapshot first)", ref)+ }++ if input, ok := el.(html.HTMLInputElement); ok {+ input.SetValue(text)+ return nil+ }++ el.SetAttribute("value", text)+ return nil+}++// Close shuts down the lite engine and releases resources.+func (l *LiteEngine) Close() error {+ l.mu.Lock()+ defer l.mu.Unlock()++ for _, tab := range l.tabs {+ if tab.window != nil {+ tab.window.Close()+ }+ }+ l.tabs = make(map[string]*liteTab)+ return nil+}++// ---------- helpers ----------++func (l *LiteEngine) walkDOM(tab *liteTab, node dom.Node, filter string, depth int) []SnapshotNode {+ var nodes []SnapshotNode++ el, isElement := node.(dom.Element)+ if !isElement {+ return nodes+ }++ tag := strings.ToLower(el.TagName())++ // Skip non-visible and script/style elements.+ if tag == "script" || tag == "style" || tag == "noscript" || tag == "link" || tag == "meta" {+ return nodes+ }++ role := getRole(el)+ name := getAccessibleName(el)+ interactive := isInteractive(el)++ if filter == "interactive" && !interactive {+ for child := node.FirstChild(); child != nil; child = child.NextSibling() {+ nodes = append(nodes, l.walkDOM(tab, child, filter, depth)...)+ }+ return nodes+ }++ ref := fmt.Sprintf("e%d", len(tab.refMap))+ tab.refMap[ref] = el++ sn := SnapshotNode{+ Ref: ref,+ Role: role,+ Name: name,+ Tag: tag,+ Interactive: interactive,+ Depth: depth,+ }++ if input, ok := el.(html.HTMLInputElement); ok {+ sn.Value = input.Value()+ }++ nodes = append(nodes, sn)++ for child := node.FirstChild(); child != nil; child = child.NextSibling() {+ nodes = append(nodes, l.walkDOM(tab, child, filter, depth+1)...)+ }+ return nodes+}++func (l *LiteEngine) getTitle(win html.Window) string {+ if win == nil {+ return ""+ }+ doc := win.Document()+ if doc == nil {+ return ""+ }+ titleEl, err := doc.QuerySelector("title")+ if err != nil || titleEl == nil {+ return ""+ }+ return strings.TrimSpace(titleEl.TextContent())+}++// getRole maps an element to its implicit ARIA role.+func getRole(el dom.Element) string {+ if role, ok := el.GetAttribute("role"); ok {+ return role+ }++ switch strings.ToLower(el.TagName()) {+ case "a":+ if _, has := el.GetAttribute("href"); has {+ return "link"+ }+ case "button":+ return "button"+ case "input":+ t, _ := el.GetAttribute("type")+ switch t {+ case "submit", "button":+ return "button"+ case "checkbox":+ return "checkbox"+ case "radio":+ return "radio"+ default:+ return "textbox"+ }+ case "textarea":+ return "textbox"+ case "select":+ return "combobox"+ case "img":+ return "img"+ case "nav":+ return "navigation"+ case "main":+ return "main"+ case "header":+ return "banner"+ case "footer":+ return "contentinfo"+ case "aside":+ return "complementary"+ case "form":+ return "form"+ case "h1", "h2", "h3", "h4", "h5", "h6":+ return "heading"+ case "ul", "ol":+ return "list"+ case "li":+ return "listitem"+ case "table":+ return "table"+ case "tr":+ return "row"+ case "td":+ return "cell"+ case "th":+ return "columnheader"+ case "section":+ if _, has := el.GetAttribute("aria-label"); has {+ return "region"+ }+ if _, has := el.GetAttribute("aria-labelledby"); has {+ return "region"+ }+ case "details":+ return "group"+ case "summary":+ return "button"+ case "dialog":+ return "dialog"+ case "article":+ return "article"+ case "p", "div", "span":+ return "generic"+ }+ return "generic"+}++// getAccessibleName resolves an element's accessible name.+func getAccessibleName(el dom.Element) string {+ if label, ok := el.GetAttribute("aria-label"); ok {+ return label+ }+ if title, ok := el.GetAttribute("title"); ok {+ return title+ }+ tag := strings.ToLower(el.TagName())+ if tag == "img" {+ if alt, ok := el.GetAttribute("alt"); ok {+ return alt+ }+ }+ if tag == "input" || tag == "textarea" {+ if ph, ok := el.GetAttribute("placeholder"); ok {+ return ph+ }+ }+ if isInteractive(el) {+ text := strings.TrimSpace(el.TextContent())+ if len(text) > 100 {+ text = text[:100] + "..."+ }+ return text+ }+ return ""+}++// isInteractive returns true for elements a user can interact with.+func isInteractive(el dom.Element) bool {+ switch strings.ToLower(el.TagName()) {+ case "a":+ _, has := el.GetAttribute("href")+ return has+ case "button", "input", "textarea", "select", "summary":+ return true+ }+ if _, ok := el.GetAttribute("onclick"); ok {+ return true+ }+ if idx, ok := el.GetAttribute("tabindex"); ok && idx != "-1" {+ return true+ }+ if role, ok := el.GetAttribute("role"); ok {+ switch role {+ case "button", "link", "tab", "menuitem", "switch", "checkbox", "radio":+ return true+ }+ }+ return false+}++// stripScripts removes <script> elements from HTML to prevent gost-dom+// from panicking when no JavaScript engine is configured.+func stripScripts(r io.Reader) (io.Reader, error) {+ z := nethtml.NewTokenizer(r)+ var buf bytes.Buffer+ inScript := false+ for {+ tt := z.Next()+ switch tt {+ case nethtml.ErrorToken:+ if z.Err() == io.EOF {+ return &buf, nil+ }+ return nil, z.Err()+ case nethtml.StartTagToken:+ tn, _ := z.TagName()+ if string(tn) == "script" {+ inScript = true+ continue+ }+ buf.Write(z.Raw())+ case nethtml.EndTagToken:+ tn, _ := z.TagName()+ if string(tn) == "script" {+ inScript = false+ continue+ }+ buf.Write(z.Raw())+ default:+ if !inScript {+ buf.Write(z.Raw())+ }+ }+ }+}++// normalizeWhitespace collapses runs of whitespace (including blank lines)+// into single spaces while trimming leading/trailing space.+func normalizeWhitespace(s string) string {+ var b strings.Builder+ b.Grow(len(s))+ prev := true // treat start as whitespace+ for _, r := range s {+ if r == ' ' || r == '\t' || r == '\n' || r == '\r' {+ if !prev {+ b.WriteByte(' ')+ prev = true+ }+ continue+ }+ b.WriteRune(r)+ prev = false+ }+ return strings.TrimSpace(b.String())+}diff --git a/internal/engine/lite_test.go b/internal/engine/lite_test.gonew file mode 100644index 00000000..dddb231d--- /dev/null+++ b/internal/engine/lite_test.go@@ -0,0 +1,346 @@+package engine++import (+ "context"+ "net/http"+ "net/http/httptest"+ "strings"+ "testing"+)++func newTestServer(body string) *httptest.Server {+ return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(body))+ }))+}++const testPage = `<!DOCTYPE html>+<html>+<head><title>Test Page</title></head>+<body>+ <h1>Hello World</h1>+ <nav><a href="/about">About</a></nav>+ <main>+ <p>Some content here.</p>+ <button id="btn">Click Me</button>+ <input type="text" placeholder="Enter name">+ <textarea placeholder="Description"></textarea>+ <form><select><option>One</option></select></form>+ </main>+ <footer>Footer text</footer>+</body>+</html>`++func TestLiteEngine_Navigate(t *testing.T) {+ ts := newTestServer(testPage)+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ result, err := lite.Navigate(context.Background(), ts.URL)+ if err != nil {+ t.Fatalf("Navigate: %v", err)+ }+ if result.TabID == "" {+ t.Error("expected non-empty tabId")+ }+ if result.URL != ts.URL {+ t.Errorf("URL = %q, want %q", result.URL, ts.URL)+ }+}++func TestLiteEngine_Snapshot_All(t *testing.T) {+ ts := newTestServer(testPage)+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, err := lite.Navigate(context.Background(), ts.URL)+ if err != nil {+ t.Fatalf("Navigate: %v", err)+ }++ nodes, err := lite.Snapshot(context.Background(), "")+ if err != nil {+ t.Fatalf("Snapshot: %v", err)+ }+ if len(nodes) == 0 {+ t.Fatal("expected nodes in snapshot")+ }++ // Verify roles are assigned+ roleSet := make(map[string]bool)+ for _, n := range nodes {+ roleSet[n.Role] = true+ }+ for _, expected := range []string{"heading", "link", "button", "textbox", "combobox"} {+ if !roleSet[expected] {+ t.Errorf("expected role %q in snapshot, roles found: %v", expected, roleSet)+ }+ }+}++func TestLiteEngine_Snapshot_Interactive(t *testing.T) {+ ts := newTestServer(testPage)+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)++ nodes, err := lite.Snapshot(context.Background(), "interactive")+ if err != nil {+ t.Fatalf("Snapshot interactive: %v", err)+ }++ for _, n := range nodes {+ if !n.Interactive {+ t.Errorf("interactive filter returned non-interactive node: %+v", n)+ }+ }++ if len(nodes) < 3 {+ t.Errorf("expected at least 3 interactive nodes (link, button, input), got %d", len(nodes))+ }+}++func TestLiteEngine_Text(t *testing.T) {+ ts := newTestServer(testPage)+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)++ text, err := lite.Text(context.Background())+ if err != nil {+ t.Fatalf("Text: %v", err)+ }++ for _, want := range []string{"Hello World", "About", "Click Me", "Some content here"} {+ if !strings.Contains(text, want) {+ t.Errorf("text should contain %q, got: %s", want, text)+ }+ }+}++func TestLiteEngine_Click(t *testing.T) {+ ts := newTestServer(testPage)+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)++ nodes, _ := lite.Snapshot(context.Background(), "interactive")+ var buttonRef string+ for _, n := range nodes {+ if n.Role == "button" {+ buttonRef = n.Ref+ break+ }+ }+ if buttonRef == "" {+ t.Fatal("no button found in snapshot")+ }++ if err := lite.Click(context.Background(), buttonRef); err != nil {+ t.Errorf("Click: %v", err)+ }+}++func TestLiteEngine_Type(t *testing.T) {+ ts := newTestServer(testPage)+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)++ nodes, _ := lite.Snapshot(context.Background(), "interactive")+ var inputRef string+ for _, n := range nodes {+ if n.Role == "textbox" {+ inputRef = n.Ref+ break+ }+ }+ if inputRef == "" {+ t.Fatal("no textbox found in snapshot")+ }++ if err := lite.Type(context.Background(), inputRef, "hello"); err != nil {+ t.Errorf("Type: %v", err)+ }+}++func TestLiteEngine_RefNotFound(t *testing.T) {+ lite := NewLiteEngine()+ defer lite.Close()++ // No page loaded+ _, err := lite.Snapshot(context.Background(), "")+ if err == nil {+ t.Error("expected error for snapshot without navigate")+ }++ // After navigate, bad ref+ ts := newTestServer(testPage)+ defer ts.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)+ _, _ = lite.Snapshot(context.Background(), "")++ if err := lite.Click(context.Background(), "nonexistent"); err == nil {+ t.Error("expected error for bad ref")+ }+}++func TestLiteEngine_ScriptStyleSkipped(t *testing.T) {+ page := `<!DOCTYPE html>+<html><head><title>T</title></head>+<body>+<script>var x = 1;</script>+<style>.red { color: red; }</style>+<p>Visible</p>+</body></html>`++ ts := newTestServer(page)+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)+ nodes, _ := lite.Snapshot(context.Background(), "")++ for _, n := range nodes {+ if n.Tag == "script" || n.Tag == "style" {+ t.Errorf("snapshot should skip %s elements", n.Tag)+ }+ }+}++func TestLiteEngine_AriaAttributes(t *testing.T) {+ page := `<!DOCTYPE html>+<html><head><title>Aria</title></head>+<body>+<div role="navigation" aria-label="Main Nav">content</div>+<span role="button" tabindex="0">Custom Btn</span>+</body></html>`++ ts := newTestServer(page)+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)+ nodes, _ := lite.Snapshot(context.Background(), "")++ foundNav := false+ foundBtn := false+ for _, n := range nodes {+ if n.Role == "navigation" && n.Name == "Main Nav" {+ foundNav = true+ }+ if n.Role == "button" && n.Name == "Custom Btn" {+ foundBtn = true+ }+ }+ if !foundNav {+ t.Error("expected to find navigation role with aria-label")+ }+ if !foundBtn {+ t.Error("expected to find button role from role attribute")+ }+}++func TestLiteEngine_MultiTab(t *testing.T) {+ page1 := `<!DOCTYPE html><html><head><title>Page 1</title></head><body><p>First</p></body></html>`+ page2 := `<!DOCTYPE html><html><head><title>Page 2</title></head><body><p>Second</p></body></html>`++ ts1 := newTestServer(page1)+ defer ts1.Close()+ ts2 := newTestServer(page2)+ defer ts2.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ res1, _ := lite.Navigate(context.Background(), ts1.URL)+ res2, _ := lite.Navigate(context.Background(), ts2.URL)++ if res1.TabID == res2.TabID {+ t.Error("tab IDs should be different")+ }++ // Current tab is the most recent (page2)+ text, _ := lite.Text(context.Background())+ if !strings.Contains(text, "Second") {+ t.Errorf("expected page 2 text, got: %s", text)+ }+}++func TestLiteEngine_Close(t *testing.T) {+ ts := newTestServer(testPage)+ defer ts.Close()++ lite := NewLiteEngine()+ _, _ = lite.Navigate(context.Background(), ts.URL)++ if err := lite.Close(); err != nil {+ t.Errorf("Close: %v", err)+ }++ // After close, operations should fail+ _, err := lite.Snapshot(context.Background(), "")+ if err == nil {+ t.Error("expected error after close")+ }+}++func TestLiteEngine_Capabilities(t *testing.T) {+ lite := NewLiteEngine()+ defer lite.Close()++ caps := lite.Capabilities()+ if len(caps) != 5 {+ t.Errorf("expected 5 capabilities, got %d", len(caps))+ }+}++func TestLiteEngine_Name(t *testing.T) {+ lite := NewLiteEngine()+ defer lite.Close()++ if lite.Name() != "lite" {+ t.Errorf("Name() = %q, want %q", lite.Name(), "lite")+ }+}++func TestNormalizeWhitespace(t *testing.T) {+ tests := []struct {+ in string+ want string+ }{+ {"hello world", "hello world"},+ {" hello world ", "hello world"},+ {"line1\n\n\nline2", "line1 line2"},+ {"\t tabs \t and \t spaces", "tabs and spaces"},+ {"", ""},+ }+ for _, tt := range tests {+ got := normalizeWhitespace(tt.in)+ if got != tt.want {+ t.Errorf("normalizeWhitespace(%q) = %q, want %q", tt.in, got, tt.want)+ }+ }+}diff --git a/internal/engine/realworld_test.go b/internal/engine/realworld_test.gonew file mode 100644index 00000000..01f49980--- /dev/null+++ b/internal/engine/realworld_test.go@@ -0,0 +1,1102 @@+package engine++import (+ "context"+ "fmt"+ "net/http"+ "net/http/httptest"+ "strings"+ "testing"+)++// ---------------------------------------------------------------------------+// Realistic page templates simulating common website structures.+// These tests verify the lite engine produces correct accessibility snapshots+// comparable to what Chrome's CDP accessibility tree would return.+// ---------------------------------------------------------------------------++const wikipediaStylePage = `<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Go (programming language) - Wikipedia</title>+ <link rel="stylesheet" href="/static/style.css">+ <script src="/static/app.js"></script>+</head>+<body>+ <header>+ <nav id="top-nav">+ <a href="/" class="logo">Wikipedia</a>+ <form action="/search" method="get">+ <input type="search" name="q" placeholder="Search Wikipedia" aria-label="Search">+ <button type="submit">Search</button>+ </form>+ </nav>+ </header>++ <main id="content">+ <h1>Go (programming language)</h1>+ <p><b>Go</b>, also known as <b>Golang</b>, is a statically typed, compiled+ programming language designed at Google.</p>++ <nav id="toc" aria-label="Table of contents">+ <h2>Contents</h2>+ <ul>+ <li><a href="#history">1 History</a></li>+ <li><a href="#syntax">2 Syntax</a></li>+ <li><a href="#concurrency">3 Concurrency</a></li>+ </ul>+ </nav>++ <section id="history" aria-label="History">+ <h2>History</h2>+ <p>Go was designed at <a href="/wiki/Google">Google</a> in 2007 by+ Robert Griesemer, Rob Pike, and Ken Thompson.</p>+ </section>++ <section id="syntax" aria-label="Syntax">+ <h2>Syntax</h2>+ <p>Go's syntax is similar to C but with memory safety, garbage collection,+ and CSP-style concurrency.</p>+ <pre><code>package main++import "fmt"++func main() {+ fmt.Println("Hello, World!")+}</code></pre>+ </section>++ <section id="concurrency" aria-label="Concurrency">+ <h2>Concurrency</h2>+ <p>Go has built-in support for concurrent programming via goroutines and channels.</p>+ </section>++ <table>+ <tr><th>Feature</th><th>Go</th><th>Rust</th></tr>+ <tr><td>GC</td><td>Yes</td><td>No</td></tr>+ <tr><td>Generics</td><td>Yes (1.18+)</td><td>Yes</td></tr>+ </table>+ </main>++ <footer>+ <p>This page was last edited on 1 January 2026.</p>+ <a href="/privacy">Privacy policy</a> |+ <a href="/terms">Terms of use</a>+ </footer>++ <script>+ document.addEventListener('DOMContentLoaded', function() {+ console.log('loaded');+ });+ </script>+</body>+</html>`++const hackerNewsStylePage = `<!DOCTYPE html>+<html>+<head><title>Hacker News</title></head>+<body>+ <header>+ <nav>+ <a href="/" class="hn-logo"><b>Y</b></a>+ <a href="/newest">new</a> |+ <a href="/threads">threads</a> |+ <a href="/ask">ask</a> |+ <a href="/show">show</a> |+ <a href="/jobs">jobs</a>+ <span style="float:right"><a href="/login">login</a></span>+ </nav>+ </header>+ <main>+ <ol>+ <li>+ <span class="rank">1.</span>+ <a href="https://example.com/article1">Show HN: A new Go framework</a>+ <span class="meta">+ <a href="/user/johndoe">johndoe</a> |+ <a href="/item?id=1001">142 comments</a>+ </span>+ </li>+ <li>+ <span class="rank">2.</span>+ <a href="https://example.com/article2">Why Rust is great for CLI tools</a>+ <span class="meta">+ <a href="/user/janedoe">janedoe</a> |+ <a href="/item?id=1002">89 comments</a>+ </span>+ </li>+ <li>+ <span class="rank">3.</span>+ <a href="https://example.com/article3">The future of WebAssembly</a>+ <span class="meta">+ <a href="/user/alice">alice</a> |+ <a href="/item?id=1003">203 comments</a>+ </span>+ </li>+ </ol>+ <a href="/page2">More</a>+ </main>+ <footer><p>Guidelines | FAQ | Lists | API | Security</p></footer>+</body>+</html>`++const ecommerceStylePage = `<!DOCTYPE html>+<html lang="en">+<head>+ <title>Product - Online Store</title>+ <script src="https://cdn.example.com/analytics.js"></script>+</head>+<body>+ <header>+ <nav aria-label="Main navigation">+ <a href="/">Home</a>+ <a href="/products">Products</a>+ <a href="/cart">Cart (3)</a>+ <button id="menu-toggle" aria-label="Toggle menu">☰</button>+ </nav>+ </header>++ <main>+ <article>+ <h1>Wireless Bluetooth Headphones</h1>+ <img src="/img/headphones.jpg" alt="Black wireless headphones">+ <p>Premium noise-canceling headphones with 30-hour battery life.</p>+ <p>Price: <b>$79.99</b></p>++ <form id="add-to-cart">+ <label for="color">Color:</label>+ <select id="color" name="color">+ <option value="black">Black</option>+ <option value="white">White</option>+ <option value="blue">Blue</option>+ </select>++ <label for="qty">Quantity:</label>+ <input type="number" id="qty" name="qty" value="1" min="1" max="10">++ <button type="submit">Add to Cart</button>+ </form>+ </article>++ <section aria-label="Reviews">+ <h2>Customer Reviews</h2>+ <details>+ <summary>4.5 out of 5 stars (128 reviews)</summary>+ <ul>+ <li>Great sound quality! - Alice</li>+ <li>Battery lasts forever - Bob</li>+ <li>Comfortable for long sessions - Charlie</li>+ </ul>+ </details>+ </section>+ </main>++ <footer>+ <p>© 2026 Online Store</p>+ <a href="/help">Help Center</a>+ </footer>+</body>+</html>`++const formHeavyPage = `<!DOCTYPE html>+<html>+<head><title>Registration Form</title></head>+<body>+ <main>+ <h1>Create Your Account</h1>+ <form action="/register" method="post">+ <div>+ <label for="firstname">First Name</label>+ <input type="text" id="firstname" name="firstname" placeholder="John" required>+ </div>+ <div>+ <label for="lastname">Last Name</label>+ <input type="text" id="lastname" name="lastname" placeholder="Doe" required>+ </div>+ <div>+ <label for="email">Email</label>+ <input type="email" id="email" name="email" placeholder="[email protected]" required>+ </div>+ <div>+ <label for="password">Password</label>+ <input type="password" id="password" name="password" required>+ </div>+ <div>+ <label for="country">Country</label>+ <select id="country" name="country">+ <option value="">Select...</option>+ <option value="us">United States</option>+ <option value="uk">United Kingdom</option>+ <option value="in">India</option>+ </select>+ </div>+ <div>+ <label>Gender</label>+ <input type="radio" id="male" name="gender" value="male"> <label for="male">Male</label>+ <input type="radio" id="female" name="gender" value="female"> <label for="female">Female</label>+ </div>+ <div>+ <input type="checkbox" id="terms" name="terms" required>+ <label for="terms">I agree to the Terms of Service</label>+ </div>+ <div>+ <textarea id="bio" name="bio" placeholder="Tell us about yourself..." rows="4"></textarea>+ </div>+ <button type="submit">Register</button>+ <button type="reset">Clear Form</button>+ </form>+ </main>+</body>+</html>`++const ariaHeavyPage = `<!DOCTYPE html>+<html>+<head><title>Dashboard</title></head>+<body>+ <div role="banner">+ <h1>Analytics Dashboard</h1>+ </div>+ <nav role="navigation" aria-label="Main">+ <ul>+ <li><a href="/dashboard">Dashboard</a></li>+ <li><a href="/reports">Reports</a></li>+ <li><a href="/settings">Settings</a></li>+ </ul>+ </nav>+ <main role="main">+ <section aria-label="Key Metrics">+ <h2>Key Metrics</h2>+ <div role="status" aria-live="polite">Last updated: 5 minutes ago</div>+ <div role="group" aria-label="Metrics cards">+ <div role="region" aria-label="Revenue">+ <h3>Revenue</h3>+ <p>$45,230</p>+ </div>+ <div role="region" aria-label="Users">+ <h3>Active Users</h3>+ <p>1,234</p>+ </div>+ </div>+ </section>+ <div role="tablist" aria-label="Data views">+ <button role="tab" aria-selected="true">Table</button>+ <button role="tab" aria-selected="false">Chart</button>+ <button role="tab" aria-selected="false">Export</button>+ </div>+ <div role="tabpanel" aria-label="Table view">+ <table role="table">+ <tr><th>Date</th><th>Revenue</th><th>Users</th></tr>+ <tr><td>Jan 1</td><td>$1,200</td><td>89</td></tr>+ <tr><td>Jan 2</td><td>$1,450</td><td>102</td></tr>+ </table>+ </div>+ <dialog open aria-label="Welcome">+ <h2>Welcome back!</h2>+ <p>You have 3 new notifications.</p>+ <button>Dismiss</button>+ </dialog>+ </main>+ <footer role="contentinfo">+ <p>Version 2.1.0</p>+ </footer>+</body>+</html>`++const deeplyNestedPage = `<!DOCTYPE html>+<html>+<head><title>Nested</title></head>+<body>+ <div><div><div><div><div>+ <nav>+ <ul>+ <li><a href="/a">Level 5 Link A</a></li>+ <li><a href="/b">Level 5 Link B</a></li>+ </ul>+ </nav>+ <div><div><div>+ <p>Deeply nested paragraph with <a href="/deep">a link inside</a>.</p>+ <form>+ <div><div>+ <input type="text" placeholder="Deep input">+ <button>Deep Button</button>+ </div></div>+ </form>+ </div></div></div>+ </div></div></div></div></div>+</body>+</html>`++const specialCharsPage = `<!DOCTYPE html>+<html>+<head><title>Special & Characters</title></head>+<body>+ <h1>Café & Restaurant</h1>+ <p>Price: <$50 for dégustation menu</p>+ <p>Japanese: 日本語</p>+ <a href="/réservé">Réserver</a>+ <p>Emoji: 😀 🚀 ❤</p>+</body>+</html>`++const emptyAndMinimalPage = `<!DOCTYPE html>+<html>+<head><title>Empty</title></head>+<body></body>+</html>`++// ---------------------------------------------------------------------------+// Test runner+// ---------------------------------------------------------------------------++type realworldTestCase struct {+ name string+ html string+ checks []realworldCheck+}++type realworldCheck struct {+ desc string+ fn func(t *testing.T, lite *LiteEngine)+}++func runRealworldSuite(t *testing.T, tc realworldTestCase) {+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(tc.html))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, err := lite.Navigate(context.Background(), ts.URL)+ if err != nil {+ t.Fatalf("Navigate failed: %v", err)+ }++ for _, c := range tc.checks {+ t.Run(c.desc, func(t *testing.T) {+ c.fn(t, lite)+ })+ }+}++// ---------------------------------------------------------------------------+// Helpers+// ---------------------------------------------------------------------------++func snapshotRoles(t *testing.T, lite *LiteEngine, filter string) map[string]int {+ t.Helper()+ nodes, err := lite.Snapshot(context.Background(), filter)+ if err != nil {+ t.Fatalf("Snapshot(%q): %v", filter, err)+ }+ counts := make(map[string]int)+ for _, n := range nodes {+ counts[n.Role]+++ }+ return counts+}++func snapshotNodes(t *testing.T, lite *LiteEngine, filter string) []SnapshotNode {+ t.Helper()+ nodes, err := lite.Snapshot(context.Background(), filter)+ if err != nil {+ t.Fatalf("Snapshot(%q): %v", filter, err)+ }+ return nodes+}++func getText(t *testing.T, lite *LiteEngine) string {+ t.Helper()+ text, err := lite.Text(context.Background())+ if err != nil {+ t.Fatalf("Text: %v", err)+ }+ return text+}++func requireRole(t *testing.T, nodes []SnapshotNode, role string, minCount int) {+ t.Helper()+ count := 0+ for _, n := range nodes {+ if n.Role == role {+ count+++ }+ }+ if count < minCount {+ t.Errorf("expected >= %d nodes with role=%q, got %d", minCount, role, count)+ }+}++func requireRoleWithName(t *testing.T, nodes []SnapshotNode, role, nameSub string) {+ t.Helper()+ for _, n := range nodes {+ if n.Role == role && strings.Contains(n.Name, nameSub) {+ return+ }+ }+ t.Errorf("no node with role=%q containing name=%q", role, nameSub)+}++func requireTextContains(t *testing.T, text string, subs ...string) {+ t.Helper()+ for _, s := range subs {+ if !strings.Contains(text, s) {+ t.Errorf("expected text to contain %q (len=%d)", s, len(text))+ }+ }+}++func requireTextNotContains(t *testing.T, text string, subs ...string) {+ t.Helper()+ for _, s := range subs {+ if strings.Contains(text, s) {+ t.Errorf("text should NOT contain %q", s)+ }+ }+}++// ---------------------------------------------------------------------------+// Test cases+// ---------------------------------------------------------------------------++func TestRealworld_WikipediaStyle(t *testing.T) {+ runRealworldSuite(t, realworldTestCase{+ name: "Wikipedia-style article",+ html: wikipediaStylePage,+ checks: []realworldCheck{+ {"scripts stripped from text", func(t *testing.T, lite *LiteEngine) {+ text := getText(t, lite)+ requireTextNotContains(t, text, "addEventListener", "console.log", "DOMContentLoaded")+ }},+ {"heading hierarchy", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "heading", 4) // h1 + 3x h2+ }},+ {"navigation landmarks", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "navigation", 2) // top-nav + toc+ }},+ {"sections with aria-label become regions", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRoleWithName(t, nodes, "region", "History")+ requireRoleWithName(t, nodes, "region", "Syntax")+ requireRoleWithName(t, nodes, "region", "Concurrency")+ }},+ {"table structure", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "table", 1)+ requireRole(t, nodes, "row", 3)+ requireRole(t, nodes, "columnheader", 3)+ requireRole(t, nodes, "cell", 4)+ }},+ {"links detected as interactive", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRole(t, nodes, "link", 1) // at minimum the logo link and toc links+ // All should be interactive+ for _, n := range nodes {+ if !n.Interactive {+ t.Errorf("interactive filter returned non-interactive: %+v", n)+ }+ }+ }},+ {"search form elements", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRoleWithName(t, nodes, "textbox", "Search")+ requireRole(t, nodes, "button", 1)+ }},+ {"text content completeness", func(t *testing.T, lite *LiteEngine) {+ text := getText(t, lite)+ requireTextContains(t, text,+ "Go (programming language)",+ "statically typed",+ "Robert Griesemer",+ "goroutines and channels",+ "Privacy policy",+ )+ }},+ {"banner and contentinfo landmarks", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "banner", 1)+ requireRole(t, nodes, "contentinfo", 1)+ }},+ },+ })+}++func TestRealworld_HackerNewsStyle(t *testing.T) {+ runRealworldSuite(t, realworldTestCase{+ name: "Hacker News style",+ html: hackerNewsStylePage,+ checks: []realworldCheck{+ {"all story links detected", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "link", 5) // at minimum the story links+ }},+ {"list structure", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "list", 1)+ requireRole(t, nodes, "listitem", 3)+ }},+ {"text has all headlines", func(t *testing.T, lite *LiteEngine) {+ text := getText(t, lite)+ requireTextContains(t, text,+ "Show HN: A new Go framework",+ "Why Rust is great",+ "future of WebAssembly",+ )+ }},+ {"interactive elements include nav links", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ var names []string+ for _, n := range nodes {+ if n.Name != "" {+ names = append(names, n.Name)+ }+ }+ found := false+ for _, name := range names {+ if strings.Contains(name, "new") || strings.Contains(name, "login") {+ found = true+ break+ }+ }+ if !found {+ t.Errorf("expected nav links in interactive, got names: %v", names)+ }+ }},+ },+ })+}++func TestRealworld_EcommerceStyle(t *testing.T) {+ runRealworldSuite(t, realworldTestCase{+ name: "E-commerce product page",+ html: ecommerceStylePage,+ checks: []realworldCheck{+ {"product heading", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRoleWithName(t, nodes, "heading", "")+ }},+ {"image with alt text", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRoleWithName(t, nodes, "img", "Black wireless headphones")+ }},+ {"color select dropdown", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRole(t, nodes, "combobox", 1)+ }},+ {"number input for quantity", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRole(t, nodes, "textbox", 1) // number input → textbox+ }},+ {"add to cart button", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRoleWithName(t, nodes, "button", "Add to Cart")+ }},+ {"details/summary as group/button", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "group", 1)+ // summary → interactive button+ interNodes := snapshotNodes(t, lite, "interactive")+ foundSummary := false+ for _, n := range interNodes {+ if strings.Contains(n.Name, "4.5 out of 5") {+ foundSummary = true+ break+ }+ }+ if !foundSummary {+ t.Error("expected details summary to be interactive")+ }+ }},+ {"review section landmark", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRoleWithName(t, nodes, "region", "Reviews")+ }},+ {"article structure", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "article", 1)+ }},+ {"scripts from CDN stripped", func(t *testing.T, lite *LiteEngine) {+ text := getText(t, lite)+ requireTextNotContains(t, text, "analytics.js", "cdn.example.com")+ }},+ },+ })+}++func TestRealworld_FormHeavy(t *testing.T) {+ runRealworldSuite(t, realworldTestCase{+ name: "Registration form",+ html: formHeavyPage,+ checks: []realworldCheck{+ {"all text inputs detected", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ textboxCount := 0+ for _, n := range nodes {+ if n.Role == "textbox" {+ textboxCount+++ }+ }+ // firstname, lastname, email, password, bio (textarea)+ if textboxCount < 5 {+ t.Errorf("expected >= 5 textboxes, got %d", textboxCount)+ }+ }},+ {"radio buttons", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRole(t, nodes, "radio", 2)+ }},+ {"checkbox", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRole(t, nodes, "checkbox", 1)+ }},+ {"select dropdown", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRole(t, nodes, "combobox", 1)+ }},+ {"submit and reset buttons", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ btnNames := make(map[string]bool)+ for _, n := range nodes {+ if n.Role == "button" {+ btnNames[n.Name] = true+ }+ }+ if !btnNames["Register"] {+ t.Error("expected Register button")+ }+ if !btnNames["Clear Form"] {+ t.Error("expected Clear Form button")+ }+ }},+ {"form landmark", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "form", 1)+ }},+ {"type into input and verify", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ var firstInput string+ for _, n := range nodes {+ if n.Role == "textbox" {+ firstInput = n.Ref+ break+ }+ }+ if firstInput == "" {+ t.Fatal("no textbox found")+ }+ err := lite.Type(context.Background(), firstInput, "TestUser")+ if err != nil {+ t.Errorf("Type: %v", err)+ }+ }},+ },+ })+}++func TestRealworld_AriaHeavy(t *testing.T) {+ runRealworldSuite(t, realworldTestCase{+ name: "ARIA-heavy dashboard",+ html: ariaHeavyPage,+ checks: []realworldCheck{+ {"banner role from div[role=banner]", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "banner", 1)+ }},+ {"navigation with aria-label", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRoleWithName(t, nodes, "navigation", "Main")+ }},+ {"main role", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "main", 1)+ }},+ {"tablist with tab buttons", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "tablist", 1)+ requireRole(t, nodes, "tab", 3)+ }},+ {"tabs are interactive", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ tabCount := 0+ for _, n := range nodes {+ if n.Role == "tab" {+ tabCount+++ }+ }+ if tabCount < 3 {+ t.Errorf("expected 3 interactive tabs, got %d", tabCount)+ }+ }},+ {"status role detected", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "status", 1)+ }},+ {"region roles with aria-label", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRoleWithName(t, nodes, "region", "Revenue")+ requireRoleWithName(t, nodes, "region", "Users")+ }},+ {"dialog detected", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRoleWithName(t, nodes, "dialog", "Welcome")+ }},+ {"tabpanel role", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "tabpanel", 1)+ }},+ {"contentinfo footer", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "contentinfo", 1)+ }},+ {"table inside tabpanel", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ requireRole(t, nodes, "table", 1)+ requireRole(t, nodes, "row", 3)+ }},+ },+ })+}++func TestRealworld_DeeplyNested(t *testing.T) {+ runRealworldSuite(t, realworldTestCase{+ name: "Deeply nested DOM",+ html: deeplyNestedPage,+ checks: []realworldCheck{+ {"links found through nesting", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRole(t, nodes, "link", 3) // Link A, Link B, link inside p+ }},+ {"deep input and button found", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "interactive")+ requireRole(t, nodes, "textbox", 1)+ requireRole(t, nodes, "button", 1)+ }},+ {"text extraction through nesting", func(t *testing.T, lite *LiteEngine) {+ text := getText(t, lite)+ requireTextContains(t, text, "Level 5 Link A", "Deeply nested paragraph")+ }},+ {"depth values increase with nesting", func(t *testing.T, lite *LiteEngine) {+ nodes := snapshotNodes(t, lite, "")+ maxDepth := 0+ for _, n := range nodes {+ if n.Depth > maxDepth {+ maxDepth = n.Depth+ }+ }+ if maxDepth < 5 {+ t.Errorf("expected maxDepth >= 5 for deeply nested page, got %d", maxDepth)+ }+ }},+ },+ })+}++func TestRealworld_SpecialCharacters(t *testing.T) {+ runRealworldSuite(t, realworldTestCase{+ name: "Special characters & Unicode",+ html: specialCharsPage,+ checks: []realworldCheck{+ {"HTML entities decoded in text", func(t *testing.T, lite *LiteEngine) {+ text := getText(t, lite)+ // & should be decoded to &+ requireTextContains(t, text, "&")+ // < should be decoded+ requireTextContains(t, text, "<$50")+ }},+ {"accented characters", func(t *testing.T, lite *LiteEngine) {+ text := getText(t, lite)+ requireTextContains(t, text, "Caf")+ }},+ {"unicode CJK characters", func(t *testing.T, lite *LiteEngine) {+ text := getText(t, lite)+ requireTextContains(t, text, "日本語")+ }},+ },+ })+}++func TestRealworld_EmptyPage(t *testing.T) {+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(emptyAndMinimalPage))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, err := lite.Navigate(context.Background(), ts.URL)+ if err != nil {+ t.Fatalf("Navigate: %v", err)+ }++ nodes, err := lite.Snapshot(context.Background(), "")+ if err != nil {+ t.Fatalf("Snapshot: %v", err)+ }+ // Empty body should yield 0 or very few nodes+ if len(nodes) > 1 {+ t.Errorf("expected <= 1 nodes for empty page, got %d", len(nodes))+ }++ text, err := lite.Text(context.Background())+ if err != nil {+ t.Fatalf("Text: %v", err)+ }+ if strings.TrimSpace(text) != "" {+ t.Errorf("expected empty text for empty page, got %q", text)+ }+}++func TestRealworld_NonHTMLContentType(t *testing.T) {+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "application/json")+ _, _ = w.Write([]byte(`{"error": "not html"}`))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, err := lite.Navigate(context.Background(), ts.URL)+ if err == nil {+ t.Error("expected error for non-HTML content type")+ }+ if !strings.Contains(err.Error(), "unsupported content type") {+ t.Errorf("unexpected error: %v", err)+ }+}++func TestRealworld_HTTP404(t *testing.T) {+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.WriteHeader(404)+ _, _ = w.Write([]byte("Not Found"))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, err := lite.Navigate(context.Background(), ts.URL)+ if err == nil {+ t.Error("expected error for 404")+ }+ if !strings.Contains(err.Error(), "HTTP 404") {+ t.Errorf("unexpected error: %v", err)+ }+}++func TestRealworld_LargePagePerformance(t *testing.T) {+ // Generate a page with many elements to test performance doesn't degrade+ var b strings.Builder+ b.WriteString(`<!DOCTYPE html><html><head><title>Large</title></head><body>`)+ for i := range 200 {+ b.WriteString(fmt.Sprintf(`<div><h3>Section %d</h3><p>Content %d</p><a href="/s%d">Link %d</a></div>`, i, i, i, i))+ }+ b.WriteString(`</body></html>`)+ largePage := b.String()++ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(largePage))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, err := lite.Navigate(context.Background(), ts.URL)+ if err != nil {+ t.Fatalf("Navigate: %v", err)+ }++ nodes := snapshotNodes(t, lite, "")+ if len(nodes) < 600 { // 200 * (div + h3 + p + a) = 800 minimum+ t.Errorf("expected >= 600 nodes for large page, got %d", len(nodes))+ }++ interNodes := snapshotNodes(t, lite, "interactive")+ if len(interNodes) < 200 {+ t.Errorf("expected >= 200 interactive nodes (links), got %d", len(interNodes))+ }+}++func TestRealworld_MultipleScriptTags(t *testing.T) {+ page := `<!DOCTYPE html>+<html><head>+<script>var x = 1;</script>+<script src="https://cdn.example.com/jquery.js"></script>+<script type="module">import {foo} from './bar.js';</script>+</head><body>+<h1>Content</h1>+<script>document.write('injected');</script>+<p>Visible paragraph</p>+<script>+ // Multi-line script+ function init() {+ var el = document.getElementById('x');+ el.style.display = 'block';+ }+ init();+</script>+</body></html>`++ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(page))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, err := lite.Navigate(context.Background(), ts.URL)+ if err != nil {+ t.Fatalf("Navigate: %v", err)+ }++ text := getText(t, lite)+ requireTextContains(t, text, "Content", "Visible paragraph")+ requireTextNotContains(t, text, "document.write", "init()", "import", "jquery")++ nodes := snapshotNodes(t, lite, "")+ for _, n := range nodes {+ if n.Tag == "script" {+ t.Error("script elements should not appear in snapshot")+ }+ }+}++func TestRealworld_InlineStyles(t *testing.T) {+ page := `<!DOCTYPE html>+<html><head>+<style>.red { color: red; } .hidden { display: none; }</style>+</head><body>+<p class="red">Styled text</p>+<style>.blue { color: blue; }</style>+<p>Normal text</p>+</body></html>`++ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(page))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, err := lite.Navigate(context.Background(), ts.URL)+ if err != nil {+ t.Fatalf("Navigate: %v", err)+ }++ nodes := snapshotNodes(t, lite, "")+ for _, n := range nodes {+ if n.Tag == "style" {+ t.Error("style elements should not appear in snapshot")+ }+ }+}++func TestRealworld_ClickWorkflow(t *testing.T) {+ // Test clicking buttons — buttons should work without navigation side effects+ page := `<!DOCTYPE html>+<html><head><title>Click Test</title></head>+<body>+<button id="btn1">Button 1</button>+<button id="btn2">Button 2</button>+<span role="button" tabindex="0">Custom Button</span>+<input type="submit" value="Submit">+<p>Some content here</p>+</body></html>`++ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(page))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)+ nodes := snapshotNodes(t, lite, "interactive")++ // Click every interactive element — should not error or panic+ for _, n := range nodes {+ err := lite.Click(context.Background(), n.Ref)+ if err != nil {+ t.Errorf("Click(%s role=%s name=%q): %v", n.Ref, n.Role, n.Name, err)+ }+ }++ // Engine should still be usable+ text, err := lite.Text(context.Background())+ if err != nil {+ t.Fatalf("Text after clicks: %v", err)+ }+ if !strings.Contains(text, "Some content here") {+ t.Errorf("unexpected text after clicks: %s", text)+ }+}++func TestRealworld_ClickLinkRecovery(t *testing.T) {+ // Clicking anchor links triggers gost-dom navigation which can panic+ // (no script engine). Verify we recover gracefully.+ page := `<!DOCTYPE html>+<html><head><title>Links</title></head>+<body>+<a href="/page2">Go to Page 2</a>+<a href="/page3">Go to Page 3</a>+</body></html>`++ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(page))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)+ nodes := snapshotNodes(t, lite, "interactive")++ for _, n := range nodes {+ if n.Role == "link" {+ err := lite.Click(context.Background(), n.Ref)+ // Error is acceptable (recovered panic) — the key is it doesn't crash+ _ = err+ }+ }+}++func TestRealworld_TypeWorkflow(t *testing.T) {+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.Header().Set("Content-Type", "text/html; charset=utf-8")+ _, _ = w.Write([]byte(formHeavyPage))+ }))+ defer ts.Close()++ lite := NewLiteEngine()+ defer lite.Close()++ _, _ = lite.Navigate(context.Background(), ts.URL)+ nodes := snapshotNodes(t, lite, "interactive")++ // Type into all textboxes+ for _, n := range nodes {+ if n.Role == "textbox" {+ err := lite.Type(context.Background(), n.Ref, "test-value")+ if err != nil {+ t.Errorf("Type(%s name=%q): %v", n.Ref, n.Name, err)+ }+ }+ }+}diff --git a/internal/engine/router.go b/internal/engine/router.gonew file mode 100644index 00000000..33ae36b5--- /dev/null+++ b/internal/engine/router.go@@ -0,0 +1,124 @@+package engine++import (+ "log/slog"+ "sync"+)++// Router selects the engine for each request.+//+// It evaluates an ordered list of RouteRules, picks the first non-Undecided+// verdict, and delegates to the matching engine. Rules can be added or+// removed at runtime (under a write lock) so that the routing strategy can+// evolve without modifying handlers or bridge code.+type Router struct {+ mode Mode+ lite Engine // may be nil when Mode == ModeChrome+ rules []RouteRule+ mu sync.RWMutex+}++// NewRouter creates a router for the given mode.+// Pass nil for lite when running in chrome-only mode.+func NewRouter(mode Mode, lite Engine) *Router {+ r := &Router{+ mode: mode,+ lite: lite,+ }++ switch mode {+ case ModeLite:+ r.rules = []RouteRule{+ CapabilityRule{}, // screenshot/pdf → chrome always+ DefaultLiteRule{}, // everything else → lite+ }+ case ModeAuto:+ r.rules = []RouteRule{+ CapabilityRule{}, // chrome-only caps first+ ContentHintRule{}, // static pages → lite+ DefaultChromeRule{}, // fallback+ }+ default: // ModeChrome+ r.rules = []RouteRule{+ DefaultChromeRule{},+ }+ }++ return r+}++// AddRule appends a rule to the chain. It is evaluated after all+// currently registered rules but before the default fallback.+func (r *Router) AddRule(rule RouteRule) {+ r.mu.Lock()+ defer r.mu.Unlock()++ // Insert before the last rule (which is the fallback).+ if len(r.rules) > 0 {+ last := r.rules[len(r.rules)-1]+ r.rules[len(r.rules)-1] = rule+ r.rules = append(r.rules, last)+ } else {+ r.rules = append(r.rules, rule)+ }+ slog.Info("engine: rule added", "rule", rule.Name(), "total", len(r.rules))+}++// RemoveRule removes the first rule with the given name.+func (r *Router) RemoveRule(name string) bool {+ r.mu.Lock()+ defer r.mu.Unlock()+ for i, rule := range r.rules {+ if rule.Name() == name {+ r.rules = append(r.rules[:i], r.rules[i+1:]...)+ return true+ }+ }+ return false+}++// Route returns the engine to use for a given operation and URL.+func (r *Router) Route(op Capability, url string) Engine {+ r.mu.RLock()+ defer r.mu.RUnlock()++ for _, rule := range r.rules {+ switch rule.Decide(op, url) {+ case UseLite:+ if r.lite != nil {+ return r.lite+ }+ // lite unavailable — fall through+ case UseChrome:+ return nil // nil signals "use chrome bridge"+ }+ }+ return nil // default: chrome+}++// UseLite returns true when the router would send this operation to the+// lite engine. Convenience helper for handler-level checks.+func (r *Router) UseLite(op Capability, url string) bool {+ return r.Route(op, url) != nil+}++// Lite returns the lite engine (may be nil).+func (r *Router) Lite() Engine {+ return r.lite+}++// Mode returns the configured engine mode.+func (r *Router) Mode() Mode {+ return r.mode+}++// Rules returns a snapshot of the current rule names (for diagnostics).+func (r *Router) Rules() []string {+ r.mu.RLock()+ defer r.mu.RUnlock()+ names := make([]string, len(r.rules))+ for i, rule := range r.rules {+ names[i] = rule.Name()+ }+ return names+}diff --git a/internal/engine/router_test.go b/internal/engine/router_test.gonew file mode 100644index 00000000..d433700a--- /dev/null+++ b/internal/engine/router_test.go@@ -0,0 +1,113 @@+package engine++import (+ "context"+ "testing"+)++// fakeEngine implements Engine for testing.+type fakeEngine struct{ name string }++func (f *fakeEngine) Name() string { return f.name }+func (f *fakeEngine) Navigate(_ context.Context, _ string) (*NavigateResult, error) { return nil, nil }+func (f *fakeEngine) Snapshot(_ context.Context, _ string) ([]SnapshotNode, error) { return nil, nil }+func (f *fakeEngine) Text(_ context.Context) (string, error) { return "", nil }+func (f *fakeEngine) Click(_ context.Context, _ string) error { return nil }+func (f *fakeEngine) Type(_ context.Context, _, _ string) error { return nil }+func (f *fakeEngine) Capabilities() []Capability { return nil }+func (f *fakeEngine) Close() error { return nil }++func TestRouterChromeMode(t *testing.T) {+ r := NewRouter(ModeChrome, nil)+ for _, op := range []Capability{CapNavigate, CapSnapshot, CapText, CapScreenshot} {+ if r.UseLite(op, "https://example.com") {+ t.Errorf("chrome mode should never use lite for %s", op)+ }+ }+}++func TestRouterLiteMode(t *testing.T) {+ r := NewRouter(ModeLite, &fakeEngine{name: "lite"})++ // DOM operations → lite+ for _, op := range []Capability{CapNavigate, CapSnapshot, CapText, CapClick, CapType} {+ if !r.UseLite(op, "https://example.com") {+ t.Errorf("lite mode should use lite for %s", op)+ }+ }+ // Chrome-only operations → chrome+ for _, op := range []Capability{CapScreenshot, CapPDF, CapEvaluate, CapCookies} {+ if r.UseLite(op, "https://example.com") {+ t.Errorf("lite mode should not use lite for %s", op)+ }+ }+}++func TestRouterAutoModeStaticContent(t *testing.T) {+ r := NewRouter(ModeAuto, &fakeEngine{name: "lite"})++ // Static HTML → lite (ContentHintRule)+ if !r.UseLite(CapNavigate, "https://example.com/page.html") {+ t.Error("auto mode should use lite for .html URL")+ }+ // Dynamic page → chrome (no matching rule)+ if r.UseLite(CapNavigate, "https://example.com/app") {+ t.Error("auto mode should use chrome for dynamic URL")+ }+ // Screenshot → always chrome+ if r.UseLite(CapScreenshot, "https://example.com/page.html") {+ t.Error("auto mode should use chrome for screenshot")+ }+}++func TestRouterAutoModeLiteNil(t *testing.T) {+ r := NewRouter(ModeAuto, nil)+ // Even if rule says lite, nil engine → falls through to chrome+ if r.UseLite(CapNavigate, "https://example.com/page.html") {+ t.Error("should not route to lite when lite engine is nil")+ }+}++func TestRouterAddRemoveRule(t *testing.T) {+ r := NewRouter(ModeAuto, &fakeEngine{name: "lite"})++ // Before: dynamic URL → chrome+ if r.UseLite(CapNavigate, "https://example.com/app") {+ t.Error("should route to chrome before custom rule")+ }++ // Add a custom rule that always routes navigate to lite+ r.AddRule(DefaultLiteRule{})++ // After: still chrome because CapabilityRule + ContentHintRule are first+ // and DefaultChromeRule is last. Our added rule goes before the fallback.+ if !r.UseLite(CapNavigate, "https://example.com/app") {+ t.Error("should route to lite after adding DefaultLiteRule")+ }++ // Remove the custom rule+ if !r.RemoveRule("default-lite") {+ t.Error("RemoveRule should return true")+ }++ if r.UseLite(CapNavigate, "https://example.com/app") {+ t.Error("should revert to chrome after removing rule")+ }+}++func TestRouterRulesSnapshot(t *testing.T) {+ r := NewRouter(ModeAuto, &fakeEngine{name: "lite"})+ rules := r.Rules()+ if len(rules) != 3 {+ t.Fatalf("expected 3 rules in auto mode, got %d: %v", len(rules), rules)+ }+ if rules[0] != "capability" {+ t.Errorf("first rule should be capability, got %s", rules[0])+ }+ if rules[1] != "content-hint" {+ t.Errorf("second rule should be content-hint, got %s", rules[1])+ }+ if rules[2] != "default-chrome" {+ t.Errorf("third rule should be default-chrome, got %s", rules[2])+ }+}diff --git a/internal/engine/rules.go b/internal/engine/rules.gonew file mode 100644index 00000000..5a4481fe--- /dev/null+++ b/internal/engine/rules.go@@ -0,0 +1,70 @@+package engine++// RouteRule inspects an incoming operation and returns a routing decision.+// Rules are evaluated in order; the first non-Undecided verdict wins.+type RouteRule interface {+ // Name returns a short human-readable identifier for logging.+ Name() string+ // Decide returns UseLite, UseChrome, or Undecided.+ Decide(op Capability, url string) Decision+}++// ---------- built-in rules ----------++// CapabilityRule routes chrome-only operations (screenshot, pdf, evaluate,+// cookies) to Chrome unconditionally.+type CapabilityRule struct{}++func (CapabilityRule) Name() string { return "capability" }++func (CapabilityRule) Decide(op Capability, _ string) Decision {+ switch op {+ case CapScreenshot, CapPDF, CapEvaluate, CapCookies:+ return UseChrome+ }+ return Undecided+}++// ContentHintRule uses a simple heuristic: if a URL path ends with common+// static-content extensions it is a good candidate for the lite engine.+type ContentHintRule struct{}++func (ContentHintRule) Name() string { return "content-hint" }++func (ContentHintRule) Decide(op Capability, url string) Decision {+ if op != CapNavigate && op != CapSnapshot && op != CapText {+ return Undecided+ }+ // Static content is well-suited for Gost-DOM because it does not+ // rely on JavaScript rendering.+ for _, ext := range []string{".html", ".htm", ".xml", ".txt", ".md"} {+ if len(url) > len(ext) && url[len(url)-len(ext):] == ext {+ return UseLite+ }+ }+ return Undecided+}++// DefaultLiteRule is a catch-all that sends every remaining DOM operation+// to the lite engine. Used when Mode == ModeLite.+type DefaultLiteRule struct{}++func (DefaultLiteRule) Name() string { return "default-lite" }++func (DefaultLiteRule) Decide(op Capability, _ string) Decision {+ switch op {+ case CapNavigate, CapSnapshot, CapText, CapClick, CapType:+ return UseLite+ }+ return Undecided+}++// DefaultChromeRule is a catch-all that sends everything to Chrome.+// Used as the final fallback in ModeAuto.+type DefaultChromeRule struct{}++func (DefaultChromeRule) Name() string { return "default-chrome" }++func (DefaultChromeRule) Decide(_ Capability, _ string) Decision {+ return UseChrome+}diff --git a/internal/engine/rules_test.go b/internal/engine/rules_test.gonew file mode 100644index 00000000..7b2801fd--- /dev/null+++ b/internal/engine/rules_test.go@@ -0,0 +1,80 @@+package engine++import "testing"++func TestCapabilityRule(t *testing.T) {+ r := CapabilityRule{}+ tests := []struct {+ op Capability+ want Decision+ }{+ {CapScreenshot, UseChrome},+ {CapPDF, UseChrome},+ {CapEvaluate, UseChrome},+ {CapCookies, UseChrome},+ {CapNavigate, Undecided},+ {CapSnapshot, Undecided},+ {CapText, Undecided},+ {CapClick, Undecided},+ {CapType, Undecided},+ }+ for _, tt := range tests {+ if got := r.Decide(tt.op, ""); got != tt.want {+ t.Errorf("CapabilityRule(%s) = %d, want %d", tt.op, got, tt.want)+ }+ }+}++func TestContentHintRule(t *testing.T) {+ r := ContentHintRule{}+ tests := []struct {+ op Capability+ url string+ want Decision+ }{+ {CapNavigate, "https://example.com/page.html", UseLite},+ {CapSnapshot, "https://example.com/doc.htm", UseLite},+ {CapText, "https://example.com/feed.xml", UseLite},+ {CapNavigate, "https://example.com/readme.txt", UseLite},+ {CapNavigate, "https://example.com/notes.md", UseLite},+ {CapNavigate, "https://example.com/app", Undecided},+ {CapNavigate, "https://example.com/", Undecided},+ {CapClick, "https://example.com/page.html", Undecided},+ {CapScreenshot, "https://example.com/page.html", Undecided},+ }+ for _, tt := range tests {+ if got := r.Decide(tt.op, tt.url); got != tt.want {+ t.Errorf("ContentHintRule(%s, %q) = %d, want %d", tt.op, tt.url, got, tt.want)+ }+ }+}++func TestDefaultLiteRule(t *testing.T) {+ r := DefaultLiteRule{}+ tests := []struct {+ op Capability+ want Decision+ }{+ {CapNavigate, UseLite},+ {CapSnapshot, UseLite},+ {CapText, UseLite},+ {CapClick, UseLite},+ {CapType, UseLite},+ {CapScreenshot, Undecided},+ {CapPDF, Undecided},+ }+ for _, tt := range tests {+ if got := r.Decide(tt.op, ""); got != tt.want {+ t.Errorf("DefaultLiteRule(%s) = %d, want %d", tt.op, got, tt.want)+ }+ }+}++func TestDefaultChromeRule(t *testing.T) {+ r := DefaultChromeRule{}+ for _, op := range []Capability{CapNavigate, CapScreenshot, CapClick, CapPDF} {+ if got := r.Decide(op, ""); got != UseChrome {+ t.Errorf("DefaultChromeRule(%s) = %d, want UseChrome", op, got)+ }+ }+}diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.goindex ccbf5494..3b58e2c6 100644--- a/internal/handlers/handlers.go+++ b/internal/handlers/handlers.go@@ -10,6 +10,7 @@ import ("github.com/pinchtab/pinchtab/internal/bridge""github.com/pinchtab/pinchtab/internal/config""github.com/pinchtab/pinchtab/internal/dashboard"+ "github.com/pinchtab/pinchtab/internal/engine""github.com/pinchtab/pinchtab/internal/idutil""github.com/pinchtab/pinchtab/internal/semantic")@@ -24,6 +25,7 @@ type Handlers struct {Matcher semantic.ElementMatcherIntentCache *semantic.IntentCacheRecovery *semantic.RecoveryEngine+ Router *engine.Router // optional; nil ⇒ chrome-only}func New(b bridge.BridgeAPI, cfg *config.RuntimeConfig, p bridge.ProfileService, d *dashboard.Dashboard, o bridge.OrchestratorService) *Handlers {@@ -85,6 +87,11 @@ func (h *Handlers) ensureChrome() error {return h.Bridge.EnsureChrome(h.Config)}+// useLite returns true when the engine router routes this operation to lite.+func (h *Handlers) useLite(op engine.Capability, url string) bool {+ return h.Router != nil && h.Router.UseLite(op, url)+}+func (h *Handlers) RegisterRoutes(mux *http.ServeMux, doShutdown func()) {mux.HandleFunc("GET /health", h.HandleHealth)mux.HandleFunc("POST /ensure-chrome", h.HandleEnsureChrome)diff --git a/internal/handlers/navigation.go b/internal/handlers/navigation.goindex effee3af..33d56afa 100644--- a/internal/handlers/navigation.go+++ b/internal/handlers/navigation.go@@ -15,6 +15,7 @@ import ("github.com/chromedp/chromedp""github.com/pinchtab/pinchtab/internal/bridge"+ "github.com/pinchtab/pinchtab/internal/engine""github.com/pinchtab/pinchtab/internal/idpi""github.com/pinchtab/pinchtab/internal/web")@@ -52,12 +53,6 @@ const maxBodySize = 1 << 20//// pinchtab nav https://pinchtab.comfunc (h *Handlers) HandleNavigate(w http.ResponseWriter, r *http.Request) {- // Ensure Chrome is initialized- if err := h.ensureChrome(); err != nil {- web.Error(w, 500, fmt.Errorf("chrome initialization: %w", err))- return- }-var req struct {TabID string `json:"tabId"`URL string `json:"url"`@@ -100,6 +95,20 @@ func (h *Handlers) HandleNavigate(w http.ResponseWriter, r *http.Request) {return}+ // --- Lite engine fast path ---+ if h.useLite(engine.CapNavigate, req.URL) {+ result, err := h.Router.Lite().Navigate(r.Context(), req.URL)+ if err != nil {+ web.Error(w, 502, fmt.Errorf("lite navigate: %w", err))+ return+ }+ w.Header().Set("X-Engine", "lite")+ web.JSON(w, 200, map[string]any{"tabId": result.TabID, "url": result.URL, "title": result.Title})+ return+ }++ // Ensure Chrome is initialized+// Default to creating new tab (API design: /navigate always creates new tab)// Unless explicitly reusing an existing tab by specifying TabIDif req.TabID == "" {diff --git a/internal/handlers/snapshot.go b/internal/handlers/snapshot.goindex 0189d3c4..78d90850 100644--- a/internal/handlers/snapshot.go+++ b/internal/handlers/snapshot.go@@ -13,6 +13,7 @@ import ("github.com/chromedp/chromedp""github.com/pinchtab/pinchtab/internal/bridge"+ "github.com/pinchtab/pinchtab/internal/engine""github.com/pinchtab/pinchtab/internal/idpi""github.com/pinchtab/pinchtab/internal/web""gopkg.in/yaml.v3"@@ -59,6 +60,25 @@ import (// r = requests.get("http://localhost:9867/snapshot", params={"tabId": "abc123", "filter": "interactive"})// tree = r.json()func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {+ filter := r.URL.Query().Get("filter")++ // --- Lite engine fast path ---+ if h.useLite(engine.CapSnapshot, "") {+ nodes, err := h.Router.Lite().Snapshot(r.Context(), filter)+ if err != nil {+ web.Error(w, 500, fmt.Errorf("lite snapshot: %w", err))+ return+ }+ // Convert to bridge.A11yNode for API compatibility.+ flat := make([]bridge.A11yNode, len(nodes))+ for i, n := range nodes {+ flat[i] = bridge.A11yNode{Ref: n.Ref, Role: n.Role, Name: n.Name, Depth: n.Depth, Value: n.Value}+ }+ w.Header().Set("X-Engine", "lite")+ web.JSON(w, 200, map[string]any{"nodes": flat})+ return+ }+// Ensure Chrome is initializedif err := h.ensureChrome(); err != nil {web.Error(w, 500, fmt.Errorf("chrome initialization: %w", err))@@ -66,7 +86,7 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {}tabID := r.URL.Query().Get("tabId")- filter := r.URL.Query().Get("filter")+ // filter already parsed above for lite pathdoDiff := r.URL.Query().Get("diff") == "true"format := r.URL.Query().Get("format")output := r.URL.Query().Get("output")diff --git a/internal/handlers/text.go b/internal/handlers/text.goindex 8e4ffd69..e9b8a060 100644--- a/internal/handlers/text.go+++ b/internal/handlers/text.go@@ -9,6 +9,7 @@ import ("github.com/chromedp/chromedp""github.com/pinchtab/pinchtab/internal/assets"+ "github.com/pinchtab/pinchtab/internal/engine""github.com/pinchtab/pinchtab/internal/idpi""github.com/pinchtab/pinchtab/internal/web")@@ -17,6 +18,19 @@ import (//// @Endpoint GET /textfunc (h *Handlers) HandleText(w http.ResponseWriter, r *http.Request) {+ // --- Lite engine fast path ---+ if h.useLite(engine.CapText, "") {+ text, err := h.Router.Lite().Text(r.Context())+ if err != nil {+ web.Error(w, 500, fmt.Errorf("lite text: %w", err))+ return+ }+ w.Header().Set("X-Engine", "lite")+ w.Header().Set("Content-Type", "text/plain; charset=utf-8")+ _, _ = w.Write([]byte(text))+ return+ }+// Ensure Chrome is initializedif err := h.ensureChrome(); err != nil {web.Error(w, 500, fmt.Errorf("chrome initialization: %w", err))