High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
package bridge
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"time"
"github.com/chromedp/chromedp"
bridgecdpops "github.com/pinchtab/pinchtab/internal/bridge/cdpops"
"github.com/pinchtab/pinchtab/internal/cdptk"
"github.com/pinchtab/pinchtab/internal/selector"
)
// ErrSelectorNoMatch marks a resolution failure where the selector was valid
// but matched no element (a client-side "not found"), as distinct from a
// CDP/transport fault, an unsupported selector kind, or an internal routing
// error — which must surface as 5xx, not 404. Callers classify with errors.Is.
var ErrSelectorNoMatch = errors.New("selector matched no element")
// ErrSelectorOutsideScope marks a cached ref that still exists but belongs to
// the background document rather than the active modal subtree. Callers must
// not treat this as a stale ref or invoke global semantic recovery.
var ErrSelectorOutsideScope = errors.New("selector target is outside scope")
type FrameElementMeta struct {
TagName string `json:"tagName"`
ID string `json:"id,omitempty"`
Name string `json:"name,omitempty"`
Title string `json:"title,omitempty"`
Src string `json:"src,omitempty"`
}
// FrameExecutionContextID returns a Runtime.executionContextId that
// evaluates in the given frame's document. Safe to call from other packages
// that need to scope `Runtime.evaluate` / `Runtime.callFunctionOn` to a
// frame (for example, the /text handler when a frame scope is active).
// Passes frameID == "" through as a no-op (returns 0, nil) so callers can
// fall back to the default top-level context without branching.
func FrameExecutionContextID(ctx context.Context, frameID string) (int64, error) {
return bridgecdpops.FrameExecutionContextID(ctx, frameID)
}
// isolatedExecutionContextID returns the isolated world's execution context for
// frameID, or for the top frame when frameID is empty. Selector and modal
// discovery run there so page script cannot hide or redirect targets by
// replacing DOM methods in the main world. It never returns a usable zero: a
// caller that cannot get an isolated context gets an error, not the main world.
//
// The frame fallback and the world creation both live with the owner in
// internal/cdptk. This package kept its own copy of that sequence, which is how
// two world names came to exist for one rule.
func isolatedExecutionContextID(ctx context.Context, frameID string) (int64, error) {
return cdptk.IsolatedContextID(ctx, frameID)
}
// IsolatedNodeObjectID converts a backend node id to a JS object handle in the
// isolated world, so Runtime.callFunctionOn against it cannot be answered by
// page script that has redefined the DOM methods the call uses.
//
// The rule has one owner in internal/cdptk, the lowest CDP layer, because the
// same resolution is needed by the clip builder there and this package already
// depends on it. A second implementation here is how the two capture paths
// drifted apart before.
func IsolatedNodeObjectID(ctx context.Context, backendNodeID int64) (string, error) {
return cdptk.IsolatedNodeObjectID(ctx, backendNodeID)
}
// IsolatedNodeObjectIDs resolves several nodes against one isolated context, for an
// operation whose handles are compared in a single call.
func IsolatedNodeObjectIDs(ctx context.Context, backendNodeIDs ...int64) ([]string, error) {
return cdptk.IsolatedNodeObjectIDs(ctx, backendNodeIDs...)
}
func frameDocumentObjectID(ctx context.Context, frameID string) (string, error) {
execID, err := isolatedExecutionContextID(ctx, frameID)
if err != nil {
return "", err
}
params := map[string]any{
"expression": "document",
"returnByValue": false,
"contextId": execID,
}
var docResult json.RawMessage
err = chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
return chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.evaluate", params, &docResult)
}))
if err != nil {
return "", fmt.Errorf("resolve document: %w", err)
}
var doc struct {
Result struct {
ObjectID string `json:"objectId"`
} `json:"result"`
ExceptionDetails *struct {
Text string `json:"text"`
} `json:"exceptionDetails,omitempty"`
}
if err := json.Unmarshal(docResult, &doc); err != nil {
return "", err
}
if doc.Result.ObjectID == "" {
if doc.ExceptionDetails != nil {
return "", fmt.Errorf("resolve document: %s", doc.ExceptionDetails.Text)
}
return "", fmt.Errorf("document object not found")
}
return doc.Result.ObjectID, nil
}
func backendNodeIDFromObjectID(ctx context.Context, objectID string) (int64, error) {
var nodeResult json.RawMessage
err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
return chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.requestNode", map[string]any{
"objectId": objectID,
}, &nodeResult)
}))
if err != nil {
return 0, fmt.Errorf("request node: %w", err)
}
var node struct {
NodeID int64 `json:"nodeId"`
}
if err := json.Unmarshal(nodeResult, &node); err != nil {
return 0, err
}
if node.NodeID == 0 {
return 0, fmt.Errorf("resolved to an invalid node")
}
var descResult json.RawMessage
err = chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
return chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.describeNode", map[string]any{
"nodeId": node.NodeID,
}, &descResult)
}))
if err != nil {
return 0, fmt.Errorf("describe node: %w", err)
}
var desc struct {
Node struct {
BackendNodeID int64 `json:"backendNodeId"`
} `json:"node"`
}
if err := json.Unmarshal(descResult, &desc); err != nil {
return 0, err
}
if desc.Node.BackendNodeID == 0 {
return 0, fmt.Errorf("resolved to an invalid backend node")
}
return desc.Node.BackendNodeID, nil
}
func resolveNodeInFrame(ctx context.Context, frameID, functionDeclaration string, args []map[string]any) (int64, error) {
docObjectID, err := frameDocumentObjectID(ctx, frameID)
if err != nil {
return 0, err
}
var callResult json.RawMessage
err = chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
return chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.callFunctionOn", map[string]any{
"functionDeclaration": functionDeclaration,
"objectId": docObjectID,
"arguments": args,
"returnByValue": false,
}, &callResult)
}))
if err != nil {
return 0, err
}
var call struct {
Result struct {
Type string `json:"type"`
Subtype string `json:"subtype"`
ObjectID string `json:"objectId"`
} `json:"result"`
}
if err := json.Unmarshal(callResult, &call); err != nil {
return 0, err
}
if call.Result.ObjectID == "" || call.Result.Subtype == "null" || call.Result.Type == "undefined" {
return 0, fmt.Errorf("%w", ErrSelectorNoMatch)
}
return backendNodeIDFromObjectID(ctx, call.Result.ObjectID)
}
// TopmostModalNodeIDInFrame returns the backend node ID of the visually
// topmost visible modal owner in a frame. A missing dialog is a normal result,
// not an error. Discovery runs in an isolated world and uses browser hit
// testing rather than comparing local z-index values, which are not comparable
// across stacking contexts or the native top layer.
func TopmostModalNodeIDInFrame(ctx context.Context, frameID string) (int64, bool, error) {
const topmostModalFn = `function() {
const candidates = [];
const seen = new Set();
const composedParent = (node) => node && (node.parentNode || node.host || null);
const composedContains = (ancestor, node) => {
for (let cur = node; cur; cur = composedParent(cur)) if (cur === ancestor) return true;
return false;
};
const visit = (root) => {
if (!root || !root.querySelectorAll) return;
for (const el of root.querySelectorAll('dialog, [aria-modal="true"]')) {
if (!seen.has(el)) { seen.add(el); candidates.push(el); }
}
for (const el of root.querySelectorAll("*")) if (el.shadowRoot) visit(el.shadowRoot);
};
visit(this);
const visible = candidates.filter((el) => {
if (!el || !el.isConnected) return false;
let nativeModal = false;
try { nativeModal = el.matches(":modal"); } catch (_) {}
if (!nativeModal && el.getAttribute("aria-modal") !== "true") return false;
for (let cur = el; cur; cur = composedParent(cur)) {
if (cur.nodeType !== 1) continue;
if (cur.getAttribute("aria-hidden") === "true") return false;
const style = cur.ownerDocument.defaultView.getComputedStyle(cur);
if (style.display === "none" || style.visibility === "hidden" || style.visibility === "collapse") return false;
if (Number.parseFloat(style.opacity || "1") <= 0) return false;
}
const rect = el.getBoundingClientRect();
return rect.width > 0 && rect.height > 0 && rect.right > 0 && rect.bottom > 0 &&
rect.left < el.ownerDocument.defaultView.innerWidth && rect.top < el.ownerDocument.defaultView.innerHeight;
});
if (!visible.length) return null;
// An inner modal owns interaction before any containing modal, regardless
// of the outer element's local z-index.
const leaves = visible.filter((candidate) => !visible.some((other) =>
other !== candidate && composedContains(candidate, other)));
const points = [];
const pointKeys = new Set();
const addPoint = (x, y) => {
x = Math.max(0, Math.min(this.defaultView.innerWidth - 1, x));
y = Math.max(0, Math.min(this.defaultView.innerHeight - 1, y));
const key = Math.round(x) + ":" + Math.round(y);
if (!pointKeys.has(key)) { pointKeys.add(key); points.push([x, y]); }
};
for (const el of leaves) {
const r = el.getBoundingClientRect();
const left = Math.max(0, r.left), right = Math.min(this.defaultView.innerWidth, r.right);
const top = Math.max(0, r.top), bottom = Math.min(this.defaultView.innerHeight, r.bottom);
addPoint((left + right) / 2, (top + bottom) / 2);
addPoint(left + (right - left) * .2, top + (bottom - top) * .2);
addPoint(right - (right - left) * .2, top + (bottom - top) * .2);
addPoint(left + (right - left) * .2, bottom - (bottom - top) * .2);
addPoint(right - (right - left) * .2, bottom - (bottom - top) * .2);
}
const deepHit = (x, y) => {
let root = this, hit = null;
while (root && root.elementFromPoint) {
const next = root.elementFromPoint(x, y);
if (!next || next === hit) break;
hit = next;
root = next.shadowRoot;
}
return hit;
};
let best = null, bestHits = 0;
for (const candidate of leaves) {
let hits = 0;
for (const [x, y] of points) if (composedContains(candidate, deepHit(x, y))) hits++;
if (hits > bestHits || (hits === bestHits && hits > 0)) {
best = candidate;
bestHits = hits;
}
}
return bestHits > 0 ? best : null;
}`
nodeID, err := resolveNodeInFrame(ctx, frameID, topmostModalFn, nil)
if errors.Is(err, ErrSelectorNoMatch) {
return 0, false, nil
}
if err != nil {
return 0, false, fmt.Errorf("resolve topmost dialog: %w", err)
}
return nodeID, true, nil
}
// TopmostModalNodeID gives a top-document modal precedence over a caller's
// current iframe scope. This prevents a stale frame scope from interacting
// with background content underneath a page-level modal. When the top
// document has no modal, it falls back to the requested frame.
func TopmostModalNodeID(ctx context.Context, frameID string) (int64, bool, error) {
nodeID, open, err := TopmostModalNodeIDInFrame(ctx, "")
if err != nil || open || frameID == "" {
return nodeID, open, err
}
return TopmostModalNodeIDInFrame(ctx, frameID)
}
// resolveNodeWithinBackendNode invokes functionDeclaration with the scope
// element as `this` and converts the returned DOM object to a backend node ID.
func resolveNodeWithinBackendNode(ctx context.Context, scopeBackendNodeID int64, functionDeclaration string, args []map[string]any) (int64, error) {
scopeObjectID, err := IsolatedNodeObjectID(ctx, scopeBackendNodeID)
if err != nil {
return 0, fmt.Errorf("resolve scope node: %w", err)
}
params := map[string]any{
"functionDeclaration": functionDeclaration,
"objectId": scopeObjectID,
"returnByValue": false,
}
if len(args) > 0 {
params["arguments"] = args
}
var callResult json.RawMessage
err = chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
return chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.callFunctionOn", params, &callResult)
}))
if err != nil {
return 0, err
}
var call struct {
Result struct {
Type string `json:"type"`
Subtype string `json:"subtype"`
ObjectID string `json:"objectId"`
} `json:"result"`
ExceptionDetails *struct {
Text string `json:"text"`
} `json:"exceptionDetails,omitempty"`
}
if err := json.Unmarshal(callResult, &call); err != nil {
return 0, err
}
if call.ExceptionDetails != nil {
return 0, fmt.Errorf("scoped selector evaluation: %s", call.ExceptionDetails.Text)
}
if call.Result.ObjectID == "" || call.Result.Subtype == "null" || call.Result.Type == "undefined" {
return 0, fmt.Errorf("%w", ErrSelectorNoMatch)
}
return backendNodeIDFromObjectID(ctx, call.Result.ObjectID)
}
// BackendNodeWithinScope reports whether target is the scope node or one of
// its DOM descendants. It is used to reject stale/background snapshot refs
// while a modal dialog owns the interaction surface.
func BackendNodeWithinScope(ctx context.Context, scopeBackendNodeID, targetBackendNodeID int64) (bool, error) {
if scopeBackendNodeID == 0 || targetBackendNodeID == 0 {
return false, nil
}
objectIDs, err := IsolatedNodeObjectIDs(ctx, scopeBackendNodeID, targetBackendNodeID)
if err != nil {
return false, fmt.Errorf("resolve scope and target nodes: %w", err)
}
scopeObjectID, targetObjectID := objectIDs[0], objectIDs[1]
var contains bool
err = chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
var raw json.RawMessage
if err := chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.callFunctionOn", map[string]any{
"functionDeclaration": `function(target) {
for (let cur = target; cur; cur = cur.parentNode || cur.host || null) {
if (cur === this) return true;
}
return false;
}`,
"objectId": scopeObjectID,
"arguments": []map[string]any{{"objectId": targetObjectID}},
"returnByValue": true,
}, &raw); err != nil {
return err
}
var parsed struct {
Result struct {
Value bool `json:"value"`
} `json:"result"`
ExceptionDetails *struct {
Text string `json:"text"`
} `json:"exceptionDetails,omitempty"`
}
if err := json.Unmarshal(raw, &parsed); err != nil {
return err
}
if parsed.ExceptionDetails != nil {
return fmt.Errorf("scope containment check: %s", parsed.ExceptionDetails.Text)
}
contains = parsed.Result.Value
return nil
}))
return contains, err
}
func resolveElementMetaInFrame(ctx context.Context, frameID, functionDeclaration string, args []map[string]any) (FrameElementMeta, error) {
docObjectID, err := frameDocumentObjectID(ctx, frameID)
if err != nil {
return FrameElementMeta{}, err
}
var callResult json.RawMessage
err = chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
return chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.callFunctionOn", map[string]any{
"functionDeclaration": functionDeclaration,
"objectId": docObjectID,
"arguments": args,
"returnByValue": true,
}, &callResult)
}))
if err != nil {
return FrameElementMeta{}, err
}
var call struct {
Result struct {
Type string `json:"type"`
Subtype string `json:"subtype"`
Value json.RawMessage `json:"value"`
} `json:"result"`
}
if err := json.Unmarshal(callResult, &call); err != nil {
return FrameElementMeta{}, err
}
if call.Result.Subtype == "null" || call.Result.Type == "undefined" || len(call.Result.Value) == 0 || string(call.Result.Value) == "null" {
return FrameElementMeta{}, fmt.Errorf("no element found")
}
var meta FrameElementMeta
if err := json.Unmarshal(call.Result.Value, &meta); err != nil {
return FrameElementMeta{}, err
}
meta.TagName = strings.ToLower(meta.TagName)
return meta, nil
}
// jsNormalizeHelper lowercases, collapses runs of whitespace to a single space,
// and trims. Indentation here is cosmetic (JS ignores it); only the runtime
// behavior matters.
const jsNormalizeHelper = `const normalize = (value) => String(value || "")
.toLowerCase()
.replace(/\s+/g, " ")
.trim();`
func ResolveTextToNodeID(ctx context.Context, text string) (int64, error) {
return ResolveTextToNodeIDInFrame(ctx, "", text)
}
func ResolveTextToNodeIDInFrame(ctx context.Context, frameID, text string) (int64, error) {
return resolveSelectorAtInFrame(ctx, frameID, selector.Selector{Kind: selector.KindText, Value: text}, 0, false, false)
}
const resolveSelectorAtFn = `function(kind, value, index, fromEnd, positional) {
const root = this;
` + jsNormalizeHelper + `
const needle = normalize(value);
const unique = (items) => {
const seen = new Set();
const out = [];
for (const item of items) {
if (!item || seen.has(item)) continue;
seen.add(item);
out.push(item);
}
return out;
};
const pick = (items) => {
items = unique(items);
if (!items.length) return null;
const idx = fromEnd ? items.length - 1 : index;
if (idx < 0 || idx >= items.length) return null;
return items[idx];
};
const deepQueryAll = (selector, from) => {
const out = [];
const visit = (scope) => {
if (!scope || !scope.querySelectorAll) return;
if (scope.nodeType === 1 && scope.matches && scope.matches(selector)) out.push(scope);
const elements = Array.from(scope.querySelectorAll("*"));
out.push(...Array.from(scope.querySelectorAll(selector)));
for (const el of elements) if (el.shadowRoot) visit(el.shadowRoot);
};
visit(from || root);
return out;
};
// Source text is not rendered text: a CSS comment or a script string
// mentioning a label is nothing a user can see or click, so matching it
// hands back an element no action can operate on.
const nonRendered = new Set(["script", "style", "noscript", "template"]);
// At equal subtree size a control outranks a plain wrapper carrying the same
// label, so a bare text: lands on the <button> rather than the <div> beside it.
// This ranking is the BARE text: selector's rule only — a positional wrapper
// indexes the document, like css: and xpath:.
const semanticWeight = (el) => {
const tag = (el.tagName || "").toLowerCase();
if (tag === "button" || tag === "a" || tag === "input") return 0.25;
const role = normalize(el.getAttribute && el.getAttribute("role"));
if (role === "button" || role === "link" || role === "textbox") return 0.2;
return 0;
};
// Leaf-most wins: the fewest descendants is the most specific match. This
// REDUCES the match set, so it is shared by both paths — a wrapper chooses
// among matches and must never change which matches exist. What survives stays
// in document order, which is the order first:/last:/nth: index.
const smallestMatches = (matches) => {
const minSize = Math.min(...matches.map((item) => item.size));
return matches
.filter((item) => item.size === minSize)
.map((item) => item.el);
};
// The bare text: selector's own rule, applied to the document-ordered set. It
// has to pick the maximum weight EXPLICITLY: reading element zero of a
// weight-sorted list is what made nth:1 resolve earlier in the document than
// nth:0. Ties keep the first, so equal weights still mean document order.
// A label that IS the query breaks a tie between equally control-like matches
// — "Save" over "Save and exit" — but never outranks control-likeness: a
// heading reading "Sign in" must not take the click from a "Sign in with
// Google" button. A leaf inside a control weighs as that control, so the
// <span>Save</span> of a button is not beaten by a bare "Save changes" button.
const exactBonus = 0.01;
const controlSelector = "button, a, input, [role=button], [role=link], [role=textbox]";
const textWeight = (el, query) => {
const control = (el.closest && el.closest(controlSelector)) || el;
return semanticWeight(control) + (normalize(el.textContent || "") === query ? exactBonus : 0);
};
const bestRanked = (items, query) => {
let best = items[0];
let bestWeight = textWeight(best, query);
for (const el of items) {
const weight = textWeight(el, query);
if (weight > bestWeight) {
best = el;
bestWeight = weight;
}
}
return best;
};
const textCandidates = (query, exactFirst) => {
if (!query) return [];
// textContent, not innerText: innerText forces a synchronous layout per
// element and is O(N^2) on large pages.
const elements = deepQueryAll("*", root.body || root)
.filter((el) => !nonRendered.has((el.tagName || "").toLowerCase()));
const measured = elements.map((el) => ({ el, text: normalize(el.textContent || ""), size: el.getElementsByTagName("*").length }));
// An element whose label IS the query beats one that merely contains it.
// Without this rung the two were one filter — named exact, testing
// includes — so "Save" and "Save and exit" were equally good answers to
// text:Save, both leaf-most, both weighted as buttons, and the tie fell to
// document order. A page listing the longer label first therefore sent
// text:Delete to "Delete all" and reported OK.
//
// Containment still answers when nothing matches outright, so the
// shorthand that reaches "Sign in" by text:Sign is untouched. This is the
// ladder the select-option matcher already documents in
// docs/reference/select.md: exact visible text, then substring.
//
// The rung applies to the positional wrappers, which index what it
// returns. The bare selector takes every containing match and lets
// bestRanked weigh exactness below control-likeness.
if (exactFirst) {
const equals = measured.filter((item) => item.text === query);
if (equals.length) return smallestMatches(equals);
}
const contains = measured.filter((item) => item.text && item.text.includes(query));
if (contains.length) return smallestMatches(contains);
const tokens = query.split(" ").filter(Boolean);
if (!tokens.length) return [];
const fuzzy = measured.filter((item) => {
if (!item.text) return false;
let hits = 0;
for (const token of tokens) if (item.text.includes(token)) hits++;
return hits / tokens.length >= 0.7;
});
if (!fuzzy.length) return [];
return smallestMatches(fuzzy);
};
try {
switch (kind) {
case "css":
return pick(deepQueryAll(value));
case "xpath": {
const document = root.ownerDocument || root;
const result = document.evaluate(value, root, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
const items = [];
for (let i = 0; i < result.snapshotLength; i++) {
const item = result.snapshotItem(i);
if (root.nodeType === 9 || item === root || (root.contains && root.contains(item))) items.push(item);
}
return pick(items);
}
case "text": {
const items = unique(textCandidates(needle, positional));
if (!items.length) return null;
return positional ? pick(items) : bestRanked(items, needle);
}
default:
return null;
}
} catch (e) {
return null;
}
}`
// textLookupDeadline bounds the text scan so a slow resolution cannot eat the
// whole action timeout. It applies wherever text is matched, wrapped or not —
// first:/last:/nth: reach the same scan.
const textLookupDeadline = 3 * time.Second
// resolveSelectorAt is the single entry point for every css/xpath/text
// resolution. scopeLabel names the scope in errors; call runs the resolver
// against whichever root the caller resolved.
// positional says a first:/last:/nth: wrapper asked for this resolution. Plain
// text: and first:text: arrive with the same index and direction — 0 and forward —
// so the two cannot be told apart from the pair alone, and they must be: a bare
// text: ranks by control-likeness while a wrapper indexes the document.
func resolveSelectorAt(ctx context.Context, sel selector.Selector, index int, fromEnd bool, positional bool, scopeLabel string, call func(context.Context, []map[string]any) (int64, error)) (int64, error) {
switch sel.Kind {
case selector.KindCSS, selector.KindXPath, selector.KindText:
default:
return 0, fmt.Errorf("%s selector cannot be used with first/last/nth", sel.Kind)
}
lookupCtx := ctx
if sel.Kind == selector.KindText {
var cancel context.CancelFunc
lookupCtx, cancel = context.WithTimeout(ctx, textLookupDeadline)
defer cancel()
}
nid, err := call(lookupCtx, []map[string]any{
{"value": string(sel.Kind)},
{"value": sel.Value},
{"value": index},
{"value": fromEnd},
{"value": positional},
})
if err != nil {
if lookupCtx.Err() != nil && ctx.Err() == nil {
return 0, fmt.Errorf("%s %q%s lookup timed out after %s (page may be large or unresponsive): %w", sel.Kind, sel.Value, scopeLabel, textLookupDeadline, err)
}
return 0, fmt.Errorf("%s %q%s: %w", sel.Kind, sel.Value, scopeLabel, err)
}
return nid, nil
}
func resolveSelectorAtInFrame(ctx context.Context, frameID string, sel selector.Selector, index int, fromEnd bool, positional bool) (int64, error) {
return resolveSelectorAt(ctx, sel, index, fromEnd, positional, "", func(ctx context.Context, args []map[string]any) (int64, error) {
var backendNodeID int64
err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
nid, err := resolveNodeInFrame(ctx, frameID, resolveSelectorAtFn, args)
if err != nil {
return err
}
backendNodeID = nid
return nil
}))
return backendNodeID, err
})
}
func resolveSelectorAtWithinNode(ctx context.Context, scopeBackendNodeID int64, sel selector.Selector, index int, fromEnd bool, positional bool) (int64, error) {
return resolveSelectorAt(ctx, sel, index, fromEnd, positional, " inside topmost dialog", func(ctx context.Context, args []map[string]any) (int64, error) {
return resolveNodeWithinBackendNode(ctx, scopeBackendNodeID, resolveSelectorAtFn, args)
})
}
// resolveScope is where a search is rooted. Selector grammar — unwrapping
// first:/last:/nth: — does not depend on it, so the recursion below is written
// once against this interface rather than once per scope kind.
type resolveScope interface {
resolveAt(ctx context.Context, sel selector.Selector, index int, fromEnd bool, positional bool) (int64, error)
resolveRef(ctx context.Context, sel selector.Selector, refCache *RefCache) (int64, error)
}
type frameScope struct{ frameID string }
func (s frameScope) resolveAt(ctx context.Context, sel selector.Selector, index int, fromEnd bool, positional bool) (int64, error) {
return resolveSelectorAtInFrame(ctx, s.frameID, sel, index, fromEnd, positional)
}
func (s frameScope) resolveRef(_ context.Context, sel selector.Selector, refCache *RefCache) (int64, error) {
if refCache != nil {
if target, ok := refCache.Lookup(sel.Value); ok {
return target.BackendNodeID, nil
}
}
return 0, fmt.Errorf("ref %s not in snapshot cache: %w", sel.Value, ErrSelectorNoMatch)
}
type nodeScope struct{ backendNodeID int64 }
func (s nodeScope) resolveAt(ctx context.Context, sel selector.Selector, index int, fromEnd bool, positional bool) (int64, error) {
return resolveSelectorAtWithinNode(ctx, s.backendNodeID, sel, index, fromEnd, positional)
}
// resolveRef differs from the frame scope only in containment. A cached ref still exists
// while the dialog owns the interaction surface, so it must be proven to lie
// inside the scope subtree — otherwise a dialog-scoped action silently reaches
// an element behind the dialog. The outside-scope sentinel is distinct from
// not-found: callers must not treat it as a stale ref.
func (s nodeScope) resolveRef(ctx context.Context, sel selector.Selector, refCache *RefCache) (int64, error) {
if refCache == nil {
return 0, fmt.Errorf("ref %s not in snapshot cache: %w", sel.Value, ErrSelectorNoMatch)
}
target, ok := refCache.Lookup(sel.Value)
if !ok {
return 0, fmt.Errorf("ref %s not in snapshot cache: %w", sel.Value, ErrSelectorNoMatch)
}
inside, err := BackendNodeWithinScope(ctx, s.backendNodeID, target.BackendNodeID)
if err != nil {
return 0, fmt.Errorf("validate ref %s against topmost dialog: %w", sel.Value, err)
}
if !inside {
return 0, fmt.Errorf("ref %s is outside the topmost dialog: %w", sel.Value, ErrSelectorOutsideScope)
}
return target.BackendNodeID, nil
}
func errSemanticAtResolver() error {
return fmt.Errorf("semantic selectors must be resolved at the handler layer via /find")
}
func errHandlerLayerKind(kind selector.Kind) error {
return fmt.Errorf("%s selectors must be resolved at the handler layer via semantic", kind)
}
// resolveParsed is the one switch over selector kinds: it turns a
// first:/last:/nth: wrapper into the index/fromEnd pair the recursion carries, and
// hands anything else to the scope. The wrapper arms used to exist twice, split on
// whether the selector arrived parsed or raw — the grammar the scope refactor set
// out to stop duplicating was the part still duplicated. Parsing is now the only
// difference, and it lives in resolveNested.
//
// There is no "unknown selector kind" default. The old parsed-input copy had one and
// no input could reach it: both entry points dispatch here only from a
// case selector.KindFirst, selector.KindLast, selector.KindNth arm, and those arms
// are still the narrow kind check. Keeping a second switch alive to hold an
// unreachable error would be this duplication wearing a different hat.
func resolveParsed(ctx context.Context, scope resolveScope, sel selector.Selector, refCache *RefCache, index int, fromEnd bool, positional bool) (int64, error) {
switch sel.Kind {
case selector.KindFirst:
return resolveNested(ctx, scope, sel.Value, refCache, 0, false, true)
case selector.KindLast:
return resolveNested(ctx, scope, sel.Value, refCache, 0, true, true)
case selector.KindNth:
nth, nestedRaw, err := selector.ParseNth(sel.Value)
if err != nil {
return 0, err
}
return resolveNested(ctx, scope, nestedRaw, refCache, nth, false, true)
case selector.KindRef:
if fromEnd || index != 0 {
return 0, fmt.Errorf("ref selector cannot be used with last/nth")
}
return scope.resolveRef(ctx, sel, refCache)
case selector.KindSemantic:
return 0, errSemanticAtResolver()
default:
return scope.resolveAt(ctx, sel, index, fromEnd, positional)
}
}
func resolveNested(ctx context.Context, scope resolveScope, raw string, refCache *RefCache, index int, fromEnd bool, positional bool) (int64, error) {
return resolveParsed(ctx, scope, selector.Parse(raw), refCache, index, fromEnd, positional)
}
func ResolveXPathToNodeID(ctx context.Context, xpath string) (int64, error) {
return ResolveXPathToNodeIDInFrame(ctx, "", xpath)
}
func ResolveCSSToNodeID(ctx context.Context, css string) (int64, error) {
return ResolveCSSToNodeIDInFrame(ctx, "", css)
}
func ResolveCSSToNodeIDInFrame(ctx context.Context, frameID, css string) (int64, error) {
// Resolve through the deep selector walker (resolveSelectorAtFn → deepQueryAll)
// so a CSS selector matches the first element even when it is nested in an open
// shadow root, not just the light DOM (issue #591). For light-DOM pages this
// returns the same first match as document.querySelector, and it works for both
// the main frame (frameID == "") and sub-frames.
return resolveSelectorAtInFrame(ctx, frameID, selector.Selector{Kind: selector.KindCSS, Value: css}, 0, false, false)
}
// XPath does not pierce shadow roots: document.evaluate cannot cross a shadow
// boundary. It resolves through the shared walker for consistency and
// isolated-world execution, not for shadow support.
func ResolveXPathToNodeIDInFrame(ctx context.Context, frameID, xpath string) (int64, error) {
return resolveSelectorAtInFrame(ctx, frameID, selector.Selector{Kind: selector.KindXPath, Value: xpath}, 0, false, false)
}
func ResolveFrameElementMetaInFrame(ctx context.Context, sel selector.Selector, frameID string) (FrameElementMeta, error) {
switch sel.Kind {
case selector.KindCSS:
return resolveElementMetaInFrame(ctx, frameID, `function(selector) {
const el = this.querySelector(selector);
if (!el) {
return null;
}
return {
tagName: (el.tagName || "").toLowerCase(),
id: el.id || "",
name: el.getAttribute("name") || "",
title: el.getAttribute("title") || "",
src: el.src || ""
};
}`, []map[string]any{{"value": sel.Value}})
case selector.KindXPath:
return resolveElementMetaInFrame(ctx, frameID, `function(xpath) {
const el = this.evaluate(xpath, this, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
if (!el) {
return null;
}
return {
tagName: (el.tagName || "").toLowerCase(),
id: el.id || "",
name: el.getAttribute && el.getAttribute("name") || "",
title: el.getAttribute && el.getAttribute("title") || "",
src: el.src || ""
};
}`, []map[string]any{{"value": sel.Value}})
default:
return FrameElementMeta{}, fmt.Errorf("frame element metadata requires css or xpath selector")
}
}
// ResolveUnifiedSelectorInFrame resolves a parsed selector to a backend node ID.
// Ref selectors still use the ref cache directly; non-ref selectors honor the
// provided frame scope.
func ResolveUnifiedSelectorInFrame(ctx context.Context, sel selector.Selector, refCache *RefCache, frameID string) (int64, error) {
switch sel.Kind {
case selector.KindRef:
return frameScope{frameID}.resolveRef(ctx, sel, refCache)
case selector.KindCSS:
return ResolveCSSToNodeIDInFrame(ctx, frameID, sel.Value)
case selector.KindXPath:
return ResolveXPathToNodeIDInFrame(ctx, frameID, sel.Value)
case selector.KindText:
return ResolveTextToNodeIDInFrame(ctx, frameID, sel.Value)
case selector.KindSemantic:
return 0, errSemanticAtResolver()
case selector.KindRole, selector.KindLabel, selector.KindPlaceholder,
selector.KindAlt, selector.KindTitle, selector.KindTestID:
return 0, errHandlerLayerKind(sel.Kind)
case selector.KindFirst, selector.KindLast, selector.KindNth:
return resolveParsed(ctx, frameScope{frameID}, sel, refCache, 0, false, false)
default:
return 0, fmt.Errorf("unknown selector kind: %q", sel.Kind)
}
}
// ResolveUnifiedSelectorWithinNode resolves a selector strictly inside a DOM
// subtree. Ref selectors are accepted only when their cached backend node is
// still contained by that subtree; all other supported selectors are
// evaluated with the scope element as their root.
func ResolveUnifiedSelectorWithinNode(ctx context.Context, sel selector.Selector, refCache *RefCache, scopeBackendNodeID int64) (int64, error) {
if scopeBackendNodeID == 0 {
return 0, fmt.Errorf("dialog scope is missing")
}
switch sel.Kind {
case selector.KindRef:
return nodeScope{scopeBackendNodeID}.resolveRef(ctx, sel, refCache)
case selector.KindCSS, selector.KindXPath, selector.KindText:
return nodeScope{scopeBackendNodeID}.resolveAt(ctx, sel, 0, false, false)
case selector.KindSemantic:
return 0, errSemanticAtResolver()
case selector.KindRole, selector.KindLabel, selector.KindPlaceholder,
selector.KindAlt, selector.KindTitle, selector.KindTestID:
return 0, errHandlerLayerKind(sel.Kind)
case selector.KindFirst, selector.KindLast, selector.KindNth:
return resolveParsed(ctx, nodeScope{scopeBackendNodeID}, sel, refCache, 0, false, false)
default:
return 0, fmt.Errorf("unknown selector kind: %q", sel.Kind)
}
}
func ResolveUnifiedSelector(ctx context.Context, sel selector.Selector, refCache *RefCache) (int64, error) {
return ResolveUnifiedSelectorInFrame(ctx, sel, refCache, "")
}