Skip to content

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.go
index 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 handlers
h := 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.mod
index 97ab1995..717a119a 100644
--- a/go.mod
+++ b/go.mod
@@ -6,6 +6,7 @@ require (
github.com/chromedp/cdproto v0.0.0-20250803210736-d308e07a266d
github.com/chromedp/chromedp v0.14.2
github.com/gobwas/ws v1.4.0
+ github.com/shirou/gopsutil/v4 v4.26.2
gopkg.in/yaml.v3 v3.0.1
)
@@ -16,11 +17,16 @@ require (
github.com/go-ole/go-ole v1.2.6 // indirect
github.com/gobwas/httphead v0.1.0 // indirect
github.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 // indirect
github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
github.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 // indirect
github.com/tklauser/go-sysconf v0.3.16 // indirect
github.com/tklauser/numcpus v0.11.0 // indirect
github.com/yusufpapurcu/wmi v1.2.4 // indirect
+ golang.org/x/net v0.47.0 // indirect
golang.org/x/sys v0.41.0 // indirect
+ gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 // indirect
)
diff --git a/go.sum b/go.sum
index 92913dc6..b99f9dcb 100644
--- a/go.sum
+++ b/go.sum
@@ -4,6 +4,9 @@ github.com/chromedp/chromedp v0.14.2 h1:r3b/WtwM50RsBZHMUm9fsNhhzRStTHrKdr2zmwbZ
github.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+YeLd8JVDW6Wezm
github.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.go
index 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) settings
IDPI 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
+ }
// Security
if fc.Security.AllowEvaluate != nil {
cfg.AllowEvaluate = *fc.Security.AllowEvaluate
diff --git a/internal/engine/engine.go b/internal/engine/engine.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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>&copy; 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 &amp; Characters</title></head>
+<body>
+ <h1>Caf&eacute; &amp; Restaurant</h1>
+ <p>Price: &lt;$50 for d&eacute;gustation menu</p>
+ <p>Japanese: &#x65E5;&#x672C;&#x8A9E;</p>
+ <a href="/r&eacute;serv&eacute;">R&eacute;server</a>
+ <p>Emoji: &#x1F600; &#x1F680; &#x2764;</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)
+ // &amp; should be decoded to &
+ requireTextContains(t, text, "&")
+ // &lt; 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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.ElementMatcher
IntentCache *semantic.IntentCache
Recovery *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.go
index 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.com
func (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 TabID
if req.TabID == "" {
diff --git a/internal/handlers/snapshot.go b/internal/handlers/snapshot.go
index 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 initialized
if 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 path
doDiff := 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.go
index 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 /text
func (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 initialized
if err := h.ensureChrome(); err != nil {
web.Error(w, 500, fmt.Errorf("chrome initialization: %w", err))