Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

phase 1: expand Engine interface with SnapshotResult, TextResult, ActionResult types

Boschc969d58b0817
diff --git a/internal/engine/engine.go b/internal/engine/engine.go
index 2828f8a4..3ac39d79 100644
--- a/internal/engine/engine.go
+++ b/internal/engine/engine.go
@@ -43,9 +43,10 @@ const (
// NavigateResult is the response from a navigation.
type NavigateResult struct {
- TabID string `json:"tabId"`
- URL string `json:"url"`
- Title string `json:"title"`
+ TabID string `json:"tabId"`
+ URL string `json:"url"`
+ Title string `json:"title"`
+ Engine string `json:"engine,omitempty"` // which engine fulfilled the request
}
// SnapshotNode represents a single node in the accessibility-style snapshot.
@@ -59,12 +60,36 @@ type SnapshotNode struct {
Interactive bool `json:"interactive,omitempty"`
}
+// SnapshotResult is the response from a snapshot operation.
+type SnapshotResult struct {
+ Nodes []SnapshotNode `json:"nodes"`
+ URL string `json:"url,omitempty"`
+ Title string `json:"title,omitempty"`
+ Engine string `json:"engine,omitempty"`
+ IDPIWarning string `json:"idpiWarning,omitempty"`
+}
+
+// TextResult is the response from a text extraction operation.
+type TextResult struct {
+ Text string `json:"text"`
+ URL string `json:"url,omitempty"`
+ Title string `json:"title,omitempty"`
+ Truncated bool `json:"truncated,omitempty"`
+ Engine string `json:"engine,omitempty"`
+}
+
+// ActionResult is the response from a click/type/other action.
+type ActionResult struct {
+ Data map[string]any `json:"data,omitempty"`
+ Engine string `json:"engine,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, tabID, filter string) ([]SnapshotNode, error)
- Text(ctx context.Context, tabID string) (string, error)
+ Snapshot(ctx context.Context, tabID, filter string) (*SnapshotResult, error)
+ Text(ctx context.Context, tabID string) (*TextResult, error)
Click(ctx context.Context, tabID, ref string) error
Type(ctx context.Context, tabID, ref, text string) error
Capabilities() []Capability
diff --git a/internal/engine/lite.go b/internal/engine/lite.go
index a1920d08..4d08c918 100644
--- a/internal/engine/lite.go
+++ b/internal/engine/lite.go
@@ -118,7 +118,7 @@ func (l *LiteEngine) Navigate(ctx context.Context, url string) (*NavigateResult,
}
// Snapshot returns the DOM tree as snapshot nodes.
-func (l *LiteEngine) Snapshot(_ context.Context, tabID, filter string) ([]SnapshotNode, error) {
+func (l *LiteEngine) Snapshot(_ context.Context, tabID, filter string) (*SnapshotResult, error) {
l.mu.Lock()
defer l.mu.Unlock()
@@ -139,31 +139,46 @@ func (l *LiteEngine) Snapshot(_ context.Context, tabID, filter string) ([]Snapsh
tab.refMap = make(map[string]dom.Element)
nodes := l.walkDOM(tab, body, filter, 0)
- return nodes, nil
+
+ title := l.getTitle(tab.window)
+
+ return &SnapshotResult{
+ Nodes: nodes,
+ URL: tab.url,
+ Title: title,
+ Engine: "lite",
+ }, nil
}
// Text returns the visible text content of the page.
-func (l *LiteEngine) Text(_ context.Context, tabID string) (string, error) {
+func (l *LiteEngine) Text(_ context.Context, tabID string) (*TextResult, error) {
l.mu.Lock()
defer l.mu.Unlock()
tab, err := l.resolveTab(tabID)
if err != nil {
- return "", err
+ return nil, err
}
doc := tab.window.Document()
if doc == nil {
- return "", errors.New("no document")
+ return nil, errors.New("no document")
}
body := doc.Body()
if body == nil {
- return "", errors.New("no body element")
+ return nil, errors.New("no body element")
}
raw := body.TextContent()
- return normalizeWhitespace(raw), nil
+ title := l.getTitle(tab.window)
+
+ return &TextResult{
+ Text: normalizeWhitespace(raw),
+ URL: tab.url,
+ Title: title,
+ Engine: "lite",
+ }, nil
}
// Click clicks an element identified by ref.
diff --git a/internal/engine/lite_test.go b/internal/engine/lite_test.go
index c141cad4..f6935e2b 100644
--- a/internal/engine/lite_test.go
+++ b/internal/engine/lite_test.go
@@ -63,17 +63,17 @@ func TestLiteEngine_Snapshot_All(t *testing.T) {
t.Fatalf("Navigate: %v", err)
}
- nodes, err := lite.Snapshot(context.Background(), "", "all")
+ result, err := lite.Snapshot(context.Background(), "", "all")
if err != nil {
t.Fatalf("Snapshot: %v", err)
}
- if len(nodes) == 0 {
+ if len(result.Nodes) == 0 {
t.Fatal("expected nodes in snapshot")
}
// Verify roles are assigned
roleSet := make(map[string]bool)
- for _, n := range nodes {
+ for _, n := range result.Nodes {
roleSet[n.Role] = true
}
for _, expected := range []string{"heading", "link", "button", "textbox", "combobox"} {
@@ -92,19 +92,19 @@ func TestLiteEngine_Snapshot_Interactive(t *testing.T) {
_, _ = lite.Navigate(context.Background(), ts.URL)
- nodes, err := lite.Snapshot(context.Background(), "", "interactive")
+ result, err := lite.Snapshot(context.Background(), "", "interactive")
if err != nil {
t.Fatalf("Snapshot interactive: %v", err)
}
- for _, n := range nodes {
+ for _, n := range result.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))
+ if len(result.Nodes) < 3 {
+ t.Errorf("expected at least 3 interactive nodes (link, button, input), got %d", len(result.Nodes))
}
}
@@ -117,14 +117,14 @@ func TestLiteEngine_Text(t *testing.T) {
_, _ = lite.Navigate(context.Background(), ts.URL)
- text, err := lite.Text(context.Background(), "")
+ result, 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)
+ if !strings.Contains(result.Text, want) {
+ t.Errorf("text should contain %q, got: %s", want, result.Text)
}
}
}
@@ -138,9 +138,9 @@ func TestLiteEngine_Click(t *testing.T) {
_, _ = lite.Navigate(context.Background(), ts.URL)
- nodes, _ := lite.Snapshot(context.Background(), "", "interactive")
+ result, _ := lite.Snapshot(context.Background(), "", "interactive")
var buttonRef string
- for _, n := range nodes {
+ for _, n := range result.Nodes {
if n.Role == "button" {
buttonRef = n.Ref
break
@@ -164,9 +164,9 @@ func TestLiteEngine_Type(t *testing.T) {
_, _ = lite.Navigate(context.Background(), ts.URL)
- nodes, _ := lite.Snapshot(context.Background(), "", "interactive")
+ result, _ := lite.Snapshot(context.Background(), "", "interactive")
var inputRef string
- for _, n := range nodes {
+ for _, n := range result.Nodes {
if n.Role == "textbox" {
inputRef = n.Ref
break
@@ -219,9 +219,9 @@ func TestLiteEngine_ScriptStyleSkipped(t *testing.T) {
defer func() { _ = lite.Close() }()
_, _ = lite.Navigate(context.Background(), ts.URL)
- nodes, _ := lite.Snapshot(context.Background(), "", "all")
+ result, _ := lite.Snapshot(context.Background(), "", "all")
- for _, n := range nodes {
+ for _, n := range result.Nodes {
if n.Tag == "script" || n.Tag == "style" {
t.Errorf("snapshot should skip %s elements", n.Tag)
}
@@ -243,11 +243,11 @@ func TestLiteEngine_AriaAttributes(t *testing.T) {
defer func() { _ = lite.Close() }()
_, _ = lite.Navigate(context.Background(), ts.URL)
- nodes, _ := lite.Snapshot(context.Background(), "", "all")
+ result, _ := lite.Snapshot(context.Background(), "", "all")
foundNav := false
foundBtn := false
- for _, n := range nodes {
+ for _, n := range result.Nodes {
if n.Role == "navigation" && n.Name == "Main Nav" {
foundNav = true
}
@@ -283,14 +283,14 @@ func TestLiteEngine_MultiTab(t *testing.T) {
}
// 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)
+ result, _ := lite.Text(context.Background(), "")
+ if !strings.Contains(result.Text, "Second") {
+ t.Errorf("expected page 2 text, got: %s", result.Text)
}
- text, _ = lite.Text(context.Background(), res1.TabID)
- if !strings.Contains(text, "First") {
- t.Errorf("expected page 1 text via tab ID, got: %s", text)
+ result2, _ := lite.Text(context.Background(), res1.TabID)
+ if !strings.Contains(result2.Text, "First") {
+ t.Errorf("expected page 1 text via tab ID, got: %s", result2.Text)
}
}
diff --git a/internal/engine/realworld_test.go b/internal/engine/realworld_test.go
index 9ef9e22f..658e7ee4 100644
--- a/internal/engine/realworld_test.go
+++ b/internal/engine/realworld_test.go
@@ -388,20 +388,20 @@ func runRealworldSuite(t *testing.T, tc realworldTestCase) {
func snapshotNodes(t *testing.T, lite *LiteEngine, filter string) []SnapshotNode {
t.Helper()
- nodes, err := lite.Snapshot(context.Background(), "", filter)
+ result, err := lite.Snapshot(context.Background(), "", filter)
if err != nil {
t.Fatalf("Snapshot(%q): %v", filter, err)
}
- return nodes
+ return result.Nodes
}
func getText(t *testing.T, lite *LiteEngine) string {
t.Helper()
- text, err := lite.Text(context.Background(), "")
+ result, err := lite.Text(context.Background(), "")
if err != nil {
t.Fatalf("Text: %v", err)
}
- return text
+ return result.Text
}
func requireRole(t *testing.T, nodes []SnapshotNode, role string, minCount int) {
@@ -822,21 +822,21 @@ func TestRealworld_EmptyPage(t *testing.T) {
t.Fatalf("Navigate: %v", err)
}
- nodes, err := lite.Snapshot(context.Background(), "", "all")
+ snapRes, err := lite.Snapshot(context.Background(), "", "all")
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))
+ if len(snapRes.Nodes) > 1 {
+ t.Errorf("expected <= 1 nodes for empty page, got %d", len(snapRes.Nodes))
}
- text, err := lite.Text(context.Background(), "")
+ textRes, 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)
+ if strings.TrimSpace(textRes.Text) != "" {
+ t.Errorf("expected empty text for empty page, got %q", textRes.Text)
}
}
@@ -1024,12 +1024,12 @@ func TestRealworld_ClickWorkflow(t *testing.T) {
}
// Engine should still be usable
- text, err := lite.Text(context.Background(), "")
+ textRes2, 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)
+ if !strings.Contains(textRes2.Text, "Some content here") {
+ t.Errorf("unexpected text after clicks: %s", textRes2.Text)
}
}
diff --git a/internal/engine/router_test.go b/internal/engine/router_test.go
index 090ffbca..0b6e8219 100644
--- a/internal/engine/router_test.go
+++ b/internal/engine/router_test.go
@@ -10,10 +10,10 @@ 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) {
+func (f *fakeEngine) Snapshot(_ context.Context, _, _ string) (*SnapshotResult, error) {
return nil, nil
}
-func (f *fakeEngine) Text(_ context.Context, _ string) (string, error) { return "", nil }
+func (f *fakeEngine) Text(_ context.Context, _ string) (*TextResult, error) { return nil, 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 }
diff --git a/internal/handlers/actions_test.go b/internal/handlers/actions_test.go
index bd9efe28..b5e2b74b 100644
--- a/internal/handlers/actions_test.go
+++ b/internal/handlers/actions_test.go
@@ -49,11 +49,11 @@ func (f *fakeLiteEngine) Name() string { return "lite-test" }
func (f *fakeLiteEngine) Navigate(ctx context.Context, url string) (*engine.NavigateResult, error) {
return nil, fmt.Errorf("not implemented")
}
-func (f *fakeLiteEngine) Snapshot(ctx context.Context, tabID, filter string) ([]engine.SnapshotNode, error) {
+func (f *fakeLiteEngine) Snapshot(ctx context.Context, tabID, filter string) (*engine.SnapshotResult, error) {
return nil, fmt.Errorf("not implemented")
}
-func (f *fakeLiteEngine) Text(ctx context.Context, tabID string) (string, error) {
- return "", fmt.Errorf("not implemented")
+func (f *fakeLiteEngine) Text(ctx context.Context, tabID string) (*engine.TextResult, error) {
+ return nil, fmt.Errorf("not implemented")
}
func (f *fakeLiteEngine) Click(ctx context.Context, tabID, ref string) error {
f.clickRefs = append(f.clickRefs, ref)
diff --git a/internal/handlers/snapshot.go b/internal/handlers/snapshot.go
index 2c1734ff..a517e40e 100644
--- a/internal/handlers/snapshot.go
+++ b/internal/handlers/snapshot.go
@@ -66,14 +66,14 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
h.recordReadRequest(r, "snapshot", tabID)
if h.useLite(engine.CapSnapshot, "") {
h.recordEngine(r, "lite")
- nodes, err := h.Router.Lite().Snapshot(r.Context(), tabID, filter)
+ result, err := h.Router.Lite().Snapshot(r.Context(), tabID, filter)
if err != nil {
httpx.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 := make([]bridge.A11yNode, len(result.Nodes))
+ for i, n := range result.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")
diff --git a/internal/handlers/text.go b/internal/handlers/text.go
index f0bc80f0..d089690d 100644
--- a/internal/handlers/text.go
+++ b/internal/handlers/text.go
@@ -22,14 +22,14 @@ func (h *Handlers) HandleText(w http.ResponseWriter, r *http.Request) {
h.recordReadRequest(r, "text", tabID)
if h.useLite(engine.CapText, "") {
h.recordEngine(r, "lite")
- text, err := h.Router.Lite().Text(r.Context(), tabID)
+ result, err := h.Router.Lite().Text(r.Context(), tabID)
if err != nil {
httpx.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))
+ _, _ = w.Write([]byte(result.Text))
return
}