High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: add iframe-aware frame scoping and coverage
Luigi Agosti376b5609477f
diff --git a/cmd/pinchtab/cmd_cli_browser_inspect.go b/cmd/pinchtab/cmd_cli_browser_inspect.goindex 3ae5b771..e295037b 100644--- a/cmd/pinchtab/cmd_cli_browser_inspect.go+++ b/cmd/pinchtab/cmd_cli_browser_inspect.go@@ -16,6 +16,17 @@ var snapCmd = &cobra.Command{},}+var frameCmd = &cobra.Command{+ Use: "frame [target|main]",+ Short: "Show or set the current frame scope",+ Args: cobra.MaximumNArgs(1),+ Run: func(cmd *cobra.Command, args []string) {+ runCLI(func(rt cliRuntime) {+ browseractions.Frame(rt.client, rt.base, rt.token, args, cmd)+ })+ },+}+var screenshotCmd = &cobra.Command{Use: "screenshot",Short: "Take a screenshot",diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.goindex e7cf30df..4c343ce1 100644--- a/cmd/pinchtab/cmd_cli_register.go+++ b/cmd/pinchtab/cmd_cli_register.go@@ -20,6 +20,7 @@ func registerBrowserCommands() {forwardCmd,reloadCmd,snapCmd,+ frameCmd,clickCmd,dblclickCmd,dragCmd,@@ -71,6 +72,7 @@ func registerBrowserCommands() {forwardCmd,reloadCmd,snapCmd,+ frameCmd,clickCmd,dblclickCmd,dragCmd,@@ -204,6 +206,7 @@ func configureBrowserFlags() {forwardCmd,reloadCmd,snapCmd,+ frameCmd,screenshotCmd,pdfCmd,findCmd,diff --git a/docs/commands.md b/docs/commands.mdindex d570415a..62bf2d5c 100644--- a/docs/commands.md+++ b/docs/commands.md@@ -64,7 +64,12 @@ Most element commands accept a unified selector:- text selector such as `text:Submit`- semantic selector such as `find:login button`+Selector lookup is explicit by frame. Unscoped selectors search only the current frame scope, which defaults to `main`. Use `pinchtab frame ...` before selector-based iframe work. Same-origin iframe scopes are supported; cross-origin iframe descendants are not currently exposed.+```bash+pinchtab frame # Show current frame scope+pinchtab frame "#payment-frame" # Scope selectors to an iframe+pinchtab frame main # Return selector scope to the top documentpinchtab click [selector] # Click an element or coordinates with --x/--ypinchtab click --css <selector> # Force CSS selector modepinchtab click --wait-nav <selector> # Click and wait for navigation@@ -117,6 +122,8 @@ pinchtab find --ref-only # Print only the best refpinchtab eval <expression> # Evaluate JavaScript```+`pinchtab eval` is intentionally not frame-scoped. Current `pinchtab frame` state affects selector-based commands such as `snap`, `click`, `fill`, and `type`, but not arbitrary JavaScript evaluation.+## Keyboard, Wait, And Diagnostics```bashdiff --git a/docs/endpoints.md b/docs/endpoints.mdindex b59f5eae..ebcc261a 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -130,6 +130,10 @@ POST /tabs/{id}/actionPOST /tabs/{id}/actionsPOST /waitPOST /tabs/{id}/wait+GET /frame+POST /frame+GET /tabs/{id}/frame+POST /tabs/{id}/frameGET /snapshotGET /tabs/{id}/snapshotGET /text@@ -140,6 +144,8 @@ POST /evaluatePOST /tabs/{id}/evaluate```+`/evaluate` is intentionally separate from selector frame scope. `GET/POST /frame` only affects selector-based `/snapshot` and `/action` calls, not arbitrary JavaScript evaluation.+Action kinds currently include:- `click`@@ -175,6 +181,8 @@ Action targeting fields:- `waitNav`- `dialogAction` and `dialogText`+Selector lookup is limited to the current frame scope. The default scope is `main`. Use `/frame` or `/tabs/{id}/frame` before selector-based iframe actions. Same-origin iframe scopes are supported; cross-origin iframe descendants are not currently exposed.+Snapshot query parameters:- `interactive`@@ -187,6 +195,8 @@ Snapshot query parameters:- `noAnimations`- `output`+`selector` on `/snapshot` follows the same rule: it only searches the current frame scope. It does not automatically pierce into iframes, and cross-origin iframe descendants are not inlined.+Text query parameters:- `mode=raw`diff --git a/docs/reference/cli.md b/docs/reference/cli.mdindex 6ff738fd..18e8f019 100644--- a/docs/reference/cli.md+++ b/docs/reference/cli.md@@ -91,6 +91,7 @@ Common commands:| `pinchtab nav <url>` | Open a new tab and navigate it || `pinchtab quick <url>` | Navigate and snapshot || `pinchtab snap` | Accessibility snapshot |+| `pinchtab frame [target\|main]` | Show or set selector frame scope || `pinchtab click <selector>` | Click an element || `pinchtab mouse move <x> <y>` | Move the pointer to coordinates || `pinchtab mouse down [selector]` | Press a mouse button at the current pointer or a fresh target |@@ -110,6 +111,10 @@ Common commands:Many browser commands accept `--tab <id>` to target an existing tab instead of the active one.+Selector lookup is explicit by frame. Unscoped selectors stay in the main document unless you set a frame first with `pinchtab frame`. Same-origin iframe scopes are supported; cross-origin iframe descendants are not currently exposed.++`pinchtab eval` is separate from that model and does not inherit current frame scope.+Manual handoff is currently API-only:This is currently advisory state only. It marks the tab as `paused_handoff`, but it does not yet provide a guaranteed blocking pause for later automation.diff --git a/docs/reference/click.md b/docs/reference/click.mdindex e71bf641..bcd1fbc1 100644--- a/docs/reference/click.md+++ b/docs/reference/click.md@@ -21,11 +21,14 @@ Notes:- element refs come from `/snapshot`- refs returned for iframe descendants can be clicked directly; no manual frame switch is required+- selector lookup is limited to the current frame scope; the default scope is `main`+- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe actions- the raw action endpoint also accepts `selector`, for example `{"kind":"click","selector":"#login"}`- the CLI also accepts `#login`, `xpath://button`, `text:Submit`, and `find:login button`- `--wait-nav` exists on the top-level CLI command## Related Pages+- [Frame](./frame.md)- [Snapshot](./snapshot.md)- [Navigate](./navigate.md)diff --git a/docs/reference/eval.md b/docs/reference/eval.mdindex d16db720..02a67ec7 100644--- a/docs/reference/eval.md+++ b/docs/reference/eval.md@@ -20,8 +20,12 @@ Notes:- requires `security.allowEvaluate: true`- the tab-scoped variant is `POST /tabs/{id}/evaluate`+- `/evaluate` is intentionally not frame-scoped+- current `/frame` state does not affect `pinchtab eval` or `/evaluate`+- if you need iframe access from `/evaluate`, your expression must handle that explicitly## Related Pages- [Config](./config.md)+- [Frame](./frame.md)- [Tabs](./tabs.md)diff --git a/docs/reference/fill.md b/docs/reference/fill.mdindex f1dfde66..28cf5af3 100644--- a/docs/reference/fill.md+++ b/docs/reference/fill.md@@ -21,9 +21,12 @@ Notes:- the top-level CLI accepts unified selector forms such as `e8`, `#email`, or `text:Email`- refs returned for iframe descendants can be filled directly; no manual frame switch is required+- selector lookup is limited to the current frame scope; the default scope is `main`+- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe fills- for the raw HTTP action endpoint, use `selector` for CSS, XPath, text, or semantic selectors## Related Pages+- [Frame](./frame.md)- [Type](./type.md)- [Snapshot](./snapshot.md)diff --git a/docs/reference/focus.md b/docs/reference/focus.mdindex 3c8c137b..68e34f8f 100644--- a/docs/reference/focus.md+++ b/docs/reference/focus.md@@ -21,7 +21,10 @@ This is useful before keyboard-only flows such as `press Enter` or `type`.The raw action endpoint accepts either `ref` or `selector`. The CLI accepts the same unified selector forms as other top-level action commands.+Selector lookup is limited to the current frame scope. The default scope is `main`; use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe focus calls.+## Related Pages+- [Frame](./frame.md)- [Press](./press.md)- [Type](./type.md)diff --git a/docs/reference/frame.md b/docs/reference/frame.mdnew file mode 100644index 00000000..e9782f0c--- /dev/null+++ b/docs/reference/frame.md@@ -0,0 +1,56 @@+# Frame++Get or set the current frame scope for selector-based snapshots and actions.++By default, selector lookup stays in the main document. To target iframe content with CSS, XPath, or text selectors, set the frame first.++Refs from `/snapshot` are different: if a snapshot includes same-origin iframe descendants, those refs can still be used directly without setting frame scope.++```bash+curl http://localhost:9867/frame++curl -X POST http://localhost:9867/frame \+ -H "Content-Type: application/json" \+ -d '{"target":"#payment-frame"}'++curl -X POST http://localhost:9867/frame \+ -H "Content-Type: application/json" \+ -d '{"target":"main"}'++# CLI Alternative+pinchtab frame+pinchtab frame "#payment-frame"+pinchtab frame main+```++Targets accepted by `POST /frame` and `pinchtab frame`:++- `main` to clear frame scope+- a snapshot ref for an iframe owner+- a selector for an iframe element+- a frame name or frame URL++Typical iframe flow:++```bash+pinchtab snap -i+pinchtab frame "#payment-frame"+pinchtab snap -i+pinchtab fill "#card-number" "4111111111111111"+pinchtab click "#pay-button"+pinchtab frame main+```++Notes:++- selector scope is explicit; unscoped selectors do not automatically pierce into iframes+- same-origin iframe content is supported; cross-origin iframe descendants are not currently exposed as frame scopes+- nested iframes usually require multiple `frame` hops+- the same frame scope applies to selector-based `/snapshot` and `/action` calls+- `/evaluate` is separate and does not inherit frame scope++## Related Pages++- [Snapshot](./snapshot.md)+- [Click](./click.md)+- [Fill](./fill.md)diff --git a/docs/reference/hover.md b/docs/reference/hover.mdindex 03be62e1..f07b6c5d 100644--- a/docs/reference/hover.md+++ b/docs/reference/hover.md@@ -21,7 +21,10 @@ Use this when menus or tooltips appear only after hover.The raw action endpoint accepts either `ref` or `selector`. The CLI accepts unified selector forms such as `e5`, `#menu`, `xpath://button`, `text:Menu`, and `find:account menu`.+Selector lookup is limited to the current frame scope. The default scope is `main`; use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe hover calls.+## Related Pages- [Click](./click.md)+- [Frame](./frame.md)- [Snapshot](./snapshot.md)diff --git a/docs/reference/index.md b/docs/reference/index.mdindex 3237bf15..c7002a86 100644--- a/docs/reference/index.md+++ b/docs/reference/index.md@@ -8,6 +8,7 @@ Note: this index is generated and should be checked against the code when comman- [Click](./click.md)- [Config](./config.md)- [Eval](./eval.md)+- [Frame](./frame.md)- [Fill](./fill.md)- [Find](./find.md)- [Focus](./focus.md)diff --git a/docs/reference/scroll.md b/docs/reference/scroll.mdindex 13f76714..d31c466e 100644--- a/docs/reference/scroll.md+++ b/docs/reference/scroll.md@@ -22,8 +22,11 @@ Notes:- the top-level CLI also accepts a pixel value such as `pinchtab scroll 800`- the raw API uses `scrollY` and `scrollX` for page scrolling- the raw API can also target an element with `ref` or `selector`+- selector lookup is limited to the current frame scope; the default scope is `main`+- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe scrolling## Related Pages+- [Frame](./frame.md)- [Snapshot](./snapshot.md)- [Text](./text.md)diff --git a/docs/reference/select.md b/docs/reference/select.mdindex de6b642c..b276ce32 100644--- a/docs/reference/select.md+++ b/docs/reference/select.md@@ -19,7 +19,10 @@ pinchtab select e12 itThe `value` should match the option value expected by the page. The raw action endpoint accepts `ref` or `selector`, and the CLI accepts the same unified selector forms as the other action commands.+Selector lookup is limited to the current frame scope. The default scope is `main`; use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe selects.+## Related Pages+- [Frame](./frame.md)- [Snapshot](./snapshot.md)- [Focus](./focus.md)diff --git a/docs/reference/snapshot.md b/docs/reference/snapshot.mdindex e4860c12..4b869bec 100644--- a/docs/reference/snapshot.md+++ b/docs/reference/snapshot.md@@ -2,7 +2,9 @@Get an accessibility snapshot of the current page, including element refs that can be reused by action commands.-Iframe content is detected automatically during snapshot capture. Same-origin iframe descendants are included beneath the iframe owner element, and their refs can be reused directly with action commands.+Iframe content is detected automatically during snapshot capture. Same-origin iframe descendants are included beneath the iframe owner element, and their refs can be reused directly with action commands. Cross-origin iframes currently remain as owner nodes only.++Selector scoping is explicit. `selector=...` only searches the current frame scope, which defaults to `main`. To scope selector-based snapshots into an iframe, set the frame first with [`/frame`](./frame.md) or `pinchtab frame`.```bashcurl "http://localhost:9867/snapshot?filter=interactive"@@ -31,4 +33,5 @@ Useful flags:## Related Pages- [Click](./click.md)+- [Frame](./frame.md)- [Tabs](./tabs.md)diff --git a/docs/reference/type.md b/docs/reference/type.mdindex 4dd87708..47f16a3e 100644--- a/docs/reference/type.md+++ b/docs/reference/type.md@@ -21,10 +21,13 @@ Notes:- use `fill` when you want to set the value more directly- the top-level CLI accepts unified selector forms such as `e8`, `#name`, `xpath://input`, or `text:Name`+- selector lookup is limited to the current frame scope; the default scope is `main`+- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe typing- for typing without a target element (into whatever is focused), use `keyboard type`## Related Pages+- [Frame](./frame.md)- [Fill](./fill.md) — Set input value directly- [Keyboard](./keyboard.md) — Low-level keyboard input (type at focused element)- [Snapshot](./snapshot.md)diff --git a/internal/bridge/action_resolve.go b/internal/bridge/action_resolve.goindex 63a0a24d..ddf0e7e4 100644--- a/internal/bridge/action_resolve.go+++ b/internal/bridge/action_resolve.go@@ -4,11 +4,205 @@ import ("context""encoding/json""fmt"+ "strings""github.com/chromedp/chromedp""github.com/pinchtab/pinchtab/internal/selector")+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"`+}++func frameExecutionContextID(ctx context.Context, frameID string) (int64, error) {+ if frameID == "" {+ return 0, nil+ }++ var worldResult json.RawMessage+ err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {+ return chromedp.FromContext(ctx).Target.Execute(ctx, "Page.createIsolatedWorld", map[string]any{+ "frameId": frameID,+ "worldName": "pinchtab-frame-scope",+ }, &worldResult)+ }))+ if err != nil {+ return 0, fmt.Errorf("create isolated world for frame %q: %w", frameID, err)+ }++ var resp struct {+ ExecutionContextID int64 `json:"executionContextId"`+ }+ if err := json.Unmarshal(worldResult, &resp); err != nil {+ return 0, err+ }+ if resp.ExecutionContextID == 0 {+ return 0, fmt.Errorf("frame %q has no execution context", frameID)+ }+ return resp.ExecutionContextID, nil+}++func frameDocumentObjectID(ctx context.Context, frameID string) (string, error) {+ params := map[string]any{+ "expression": "document",+ "returnByValue": false,+ }+ if frameID != "" {+ execID, err := frameExecutionContextID(ctx, frameID)+ if err != nil {+ return "", err+ }+ params["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"`+ }+ if err := json.Unmarshal(docResult, &doc); err != nil {+ return "", err+ }+ if doc.Result.ObjectID == "" {+ 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("no element found")+ }++ return backendNodeIDFromObjectID(ctx, call.Result.ObjectID)+}++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+}+// ResolveXPathToNodeID resolves an XPath expression to a backend node ID// using CDP's DOM.performSearch + DOM.getSearchResults.func ResolveXPathToNodeID(ctx context.Context, xpath string) (int64, error) {@@ -90,29 +284,12 @@ func ResolveXPathToNodeID(ctx context.Context, xpath string) (int64, error) {// ResolveTextToNodeID finds the first element whose visible text content// contains the given string and returns its backend node ID.func ResolveTextToNodeID(ctx context.Context, text string) (int64, error) {- var backendNodeID int64- err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {- var docResult json.RawMessage- if err := chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.evaluate", map[string]any{- "expression": "document",- "returnByValue": false,- }, &docResult); err != nil {- return fmt.Errorf("resolve document: %w", err)- }-- var doc struct {- Result struct {- ObjectID string `json:"objectId"`- } `json:"result"`- }- if err := json.Unmarshal(docResult, &doc); err != nil {- return err- }- if doc.Result.ObjectID == "" {- return fmt.Errorf("document object not found")- }+ return ResolveTextToNodeIDInFrame(ctx, "", text)+}- const findTextFn = `function(needle) {+func ResolveTextToNodeIDInFrame(ctx context.Context, frameID, text string) (int64, error) {+ var backendNodeID int64+ const findTextFn = `function(needle) {const root = this.body || this.documentElement;if (!root) {return null;@@ -189,130 +366,146 @@ func ResolveTextToNodeID(ctx context.Context, text string) (int64, error) {return null;}`- var callResult json.RawMessage- if err := chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.callFunctionOn", map[string]any{- "functionDeclaration": findTextFn,- "objectId": doc.Result.ObjectID,- "arguments": []map[string]any{{"value": text}},- "returnByValue": false,- }, &callResult); err != nil {- return fmt.Errorf("find text node: %w", err)+ err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {+ nid, err := resolveNodeInFrame(ctx, frameID, findTextFn, []map[string]any{{"value": text}})+ if err != nil {+ return fmt.Errorf("text %q not found: %w", text, err)}+ backendNodeID = nid+ return nil+ }))+ return backendNodeID, err+}- var call struct {- Result struct {- ObjectID string `json:"objectId"`- Subtype string `json:"subtype"`- } `json:"result"`- }- if err := json.Unmarshal(callResult, &call); err != nil {- return err- }- if call.Result.ObjectID == "" || call.Result.Subtype == "null" {- return fmt.Errorf("text %q not found", text)- }+// ResolveCSSToNodeID resolves a CSS selector to a backend node ID.+func ResolveCSSToNodeID(ctx context.Context, css string) (int64, error) {+ return ResolveCSSToNodeIDInFrame(ctx, "", css)+}- var nodeResult json.RawMessage- if err := chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.requestNode", map[string]any{- "objectId": call.Result.ObjectID,- }, &nodeResult); err != nil {- return fmt.Errorf("request node: %w", err)- }+func ResolveCSSToNodeIDInFrame(ctx context.Context, frameID, css string) (int64, error) {+ if frameID == "" {+ var backendNodeID int64+ err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {+ var docResult json.RawMessage+ if err := chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.getDocument", map[string]any{"depth": 0}, &docResult); err != nil {+ return fmt.Errorf("get document: %w", err)+ }+ var doc struct {+ Root struct {+ NodeID int64 `json:"nodeId"`+ } `json:"root"`+ }+ if err := json.Unmarshal(docResult, &doc); err != nil {+ return err+ }- var node struct {- NodeID int64 `json:"nodeId"`- }- if err := json.Unmarshal(nodeResult, &node); err != nil {- return err- }- if node.NodeID == 0 {- return fmt.Errorf("text %q resolved to an invalid node", text)- }+ var qResult json.RawMessage+ if err := chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.querySelector", map[string]any{+ "nodeId": doc.Root.NodeID,+ "selector": css,+ }, &qResult); err != nil {+ return fmt.Errorf("querySelector: %w", err)+ }+ var qr struct {+ NodeID int64 `json:"nodeId"`+ }+ if err := json.Unmarshal(qResult, &qr); err != nil {+ return err+ }+ if qr.NodeID == 0 {+ return fmt.Errorf("css %q: no element found", css)+ }- var descResult json.RawMessage- if err := chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.describeNode", map[string]any{- "nodeId": node.NodeID,- }, &descResult); err != nil {- return fmt.Errorf("describe node: %w", err)- }+ var descResult json.RawMessage+ if err := chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.describeNode", map[string]any{+ "nodeId": qr.NodeID,+ }, &descResult); err != nil {+ return 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 err+ }+ backendNodeID = desc.Node.BackendNodeID+ return nil+ }))+ return backendNodeID, err+ }- var desc struct {- Node struct {- BackendNodeID int64 `json:"backendNodeId"`- } `json:"node"`- }- if err := json.Unmarshal(descResult, &desc); err != nil {- return err- }- if desc.Node.BackendNodeID == 0 {- return fmt.Errorf("text %q resolved to an invalid backend node", text)+ var backendNodeID int64+ err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {+ nid, err := resolveNodeInFrame(ctx, frameID, `function(selector) { return this.querySelector(selector); }`, []map[string]any{{"value": css}})+ if err != nil {+ return fmt.Errorf("css %q: %w", css, err)}-- backendNodeID = desc.Node.BackendNodeID+ backendNodeID = nidreturn nil}))return backendNodeID, err}-// ResolveCSSToNodeID resolves a CSS selector to a backend node ID.-func ResolveCSSToNodeID(ctx context.Context, css string) (int64, error) {+func ResolveXPathToNodeIDInFrame(ctx context.Context, frameID, xpath string) (int64, error) {+ if frameID == "" {+ return ResolveXPathToNodeID(ctx, xpath)+ }+var backendNodeID int64err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {- var docResult json.RawMessage- if err := chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.getDocument", map[string]any{"depth": 0}, &docResult); err != nil {- return fmt.Errorf("get document: %w", err)+ nid, err := resolveNodeInFrame(ctx, frameID, `function(xpath) {+ return this.evaluate(xpath, this, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;+ }`, []map[string]any{{"value": xpath}})+ if err != nil {+ return fmt.Errorf("xpath %q: %w", xpath, err)}- var doc struct {- Root struct {- NodeID int64 `json:"nodeId"`- } `json:"root"`- }- if err := json.Unmarshal(docResult, &doc); err != nil {- return err- }-- var qResult json.RawMessage- if err := chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.querySelector", map[string]any{- "nodeId": doc.Root.NodeID,- "selector": css,- }, &qResult); err != nil {- return fmt.Errorf("querySelector: %w", err)- }- var qr struct {- NodeID int64 `json:"nodeId"`- }- if err := json.Unmarshal(qResult, &qr); err != nil {- return err- }- if qr.NodeID == 0 {- return fmt.Errorf("css %q: no element found", css)- }-- var descResult json.RawMessage- if err := chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.describeNode", map[string]any{- "nodeId": qr.NodeID,- }, &descResult); err != nil {- return 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 err- }- backendNodeID = desc.Node.BackendNodeID+ backendNodeID = nidreturn nil}))return backendNodeID, err}-// ResolveUnifiedSelector resolves a parsed selector to a backend node ID.-// For ref selectors, the refCache is consulted. For CSS, XPath, and text-// selectors, CDP is used directly. Semantic selectors are not resolved here-// (they require the semantic matcher at a higher layer).-func ResolveUnifiedSelector(ctx context.Context, sel selector.Selector, refCache *RefCache) (int64, error) {+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:if refCache != nil {@@ -323,13 +516,13 @@ func ResolveUnifiedSelector(ctx context.Context, sel selector.Selector, refCachereturn 0, fmt.Errorf("ref %s not found in snapshot cache", sel.Value)case selector.KindCSS:- return ResolveCSSToNodeID(ctx, sel.Value)+ return ResolveCSSToNodeIDInFrame(ctx, frameID, sel.Value)case selector.KindXPath:- return ResolveXPathToNodeID(ctx, sel.Value)+ return ResolveXPathToNodeIDInFrame(ctx, frameID, sel.Value)case selector.KindText:- return ResolveTextToNodeID(ctx, sel.Value)+ return ResolveTextToNodeIDInFrame(ctx, frameID, sel.Value)case selector.KindSemantic:return 0, fmt.Errorf("semantic selectors must be resolved at the handler layer via /find")@@ -338,3 +531,11 @@ func ResolveUnifiedSelector(ctx context.Context, sel selector.Selector, refCachereturn 0, fmt.Errorf("unknown selector kind: %q", sel.Kind)}}++// ResolveUnifiedSelector resolves a parsed selector to a backend node ID.+// For ref selectors, the refCache is consulted. For CSS, XPath, and text+// selectors, CDP is used directly. Semantic selectors are not resolved here+// (they require the semantic matcher at a higher layer).+func ResolveUnifiedSelector(ctx context.Context, sel selector.Selector, refCache *RefCache) (int64, error) {+ return ResolveUnifiedSelectorInFrame(ctx, sel, refCache, "")+}diff --git a/internal/bridge/bridge.go b/internal/bridge/bridge.goindex 46a917b9..16aa085e 100644--- a/internal/bridge/bridge.go+++ b/internal/bridge/bridge.go@@ -31,10 +31,13 @@ type TabEntry struct {}type RefTarget struct {- BackendNodeID int64 `json:"backendNodeId"`- FrameID string `json:"frameId,omitempty"`- FrameURL string `json:"frameUrl,omitempty"`- FrameName string `json:"frameName,omitempty"`+ BackendNodeID int64 `json:"backendNodeId"`+ FrameID string `json:"frameId,omitempty"`+ FrameURL string `json:"frameUrl,omitempty"`+ FrameName string `json:"frameName,omitempty"`+ ChildFrameID string `json:"childFrameId,omitempty"`+ ChildFrameURL string `json:"childFrameUrl,omitempty"`+ ChildFrameName string `json:"childFrameName,omitempty"`}type RefCache struct {@@ -67,15 +70,29 @@ func RefTargetsFromNodes(nodes []A11yNode) map[string]RefTarget {continue}targets[node.Ref] = RefTarget{- BackendNodeID: node.NodeID,- FrameID: node.FrameID,- FrameURL: node.FrameURL,- FrameName: node.FrameName,+ BackendNodeID: node.NodeID,+ FrameID: node.FrameID,+ FrameURL: node.FrameURL,+ FrameName: node.FrameName,+ ChildFrameID: node.ChildFrameID,+ ChildFrameURL: node.ChildFrameURL,+ ChildFrameName: node.ChildFrameName,}}return targets}+type FrameScope struct {+ FrameID string `json:"frameId,omitempty"`+ FrameURL string `json:"frameUrl,omitempty"`+ FrameName string `json:"frameName,omitempty"`+ OwnerRef string `json:"ownerRef,omitempty"`+}++func (s FrameScope) Active() bool {+ return s.FrameID != ""+}+type Bridge struct {AllocCtx context.ContextAllocCancel context.CancelFuncdiff --git a/internal/bridge/bridge_test.go b/internal/bridge/bridge_test.goindex 57900a1b..89848bb8 100644--- a/internal/bridge/bridge_test.go+++ b/internal/bridge/bridge_test.go@@ -74,11 +74,14 @@ func TestRefCacheLookup(t *testing.T) {func TestRefTargetsFromNodes(t *testing.T) {nodes := []A11yNode{{- Ref: "e0",- NodeID: 100,- FrameID: "frame-1",- FrameURL: "https://example.com/embed",- FrameName: "embed",+ Ref: "e0",+ NodeID: 100,+ FrameID: "frame-1",+ FrameURL: "https://example.com/embed",+ FrameName: "embed",+ ChildFrameID: "frame-1-child",+ ChildFrameURL: "https://example.com/embed/child",+ ChildFrameName: "nested",},{Ref: "e1",@@ -96,6 +99,9 @@ func TestRefTargetsFromNodes(t *testing.T) {if targets["e0"].FrameID != "frame-1" {t.Fatalf("e0 frame id = %q", targets["e0"].FrameID)}+ if targets["e0"].ChildFrameID != "frame-1-child" {+ t.Fatalf("e0 child frame id = %q", targets["e0"].ChildFrameID)+ }if targets["e1"].BackendNodeID != 200 {t.Fatalf("e1 backend node = %d", targets["e1"].BackendNodeID)}diff --git a/internal/bridge/observe/snapshot.go b/internal/bridge/observe/snapshot.goindex 65ab39c9..55243678 100644--- a/internal/bridge/observe/snapshot.go+++ b/internal/bridge/observe/snapshot.go@@ -12,18 +12,21 @@ import ()type A11yNode struct {- Ref string `json:"ref"`- Role string `json:"role"`- Name string `json:"name"`- Depth int `json:"depth"`- Value string `json:"value,omitempty"`- Disabled bool `json:"disabled,omitempty"`- Focused bool `json:"focused,omitempty"`- Hidden bool `json:"hidden,omitempty"`- NodeID int64 `json:"nodeId,omitempty"`- FrameID string `json:"frameId,omitempty"`- FrameURL string `json:"frameUrl,omitempty"`- FrameName string `json:"frameName,omitempty"`+ Ref string `json:"ref"`+ Role string `json:"role"`+ Name string `json:"name"`+ Depth int `json:"depth"`+ Value string `json:"value,omitempty"`+ Disabled bool `json:"disabled,omitempty"`+ Focused bool `json:"focused,omitempty"`+ Hidden bool `json:"hidden,omitempty"`+ NodeID int64 `json:"nodeId,omitempty"`+ FrameID string `json:"frameId,omitempty"`+ FrameURL string `json:"frameUrl,omitempty"`+ FrameName string `json:"frameName,omitempty"`+ ChildFrameID string `json:"childFrameId,omitempty"`+ ChildFrameURL string `json:"childFrameUrl,omitempty"`+ ChildFrameName string `json:"childFrameName,omitempty"`}type RawAXNode struct {@@ -107,25 +110,33 @@ func FrameOwnerMap(ctx context.Context, tree RawFrameTree) map[string]int64 {return owners}-// FetchAXTree returns the merged accessibility tree for the current page and any child frames.-func FetchAXTree(ctx context.Context) ([]RawAXNode, error) {+func FetchFrameTree(ctx context.Context) (RawFrameTree, error) {var frameTreeResult json.RawMessageif err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {return chromedp.FromContext(ctx).Target.Execute(ctx, "Page.getFrameTree", nil, &frameTreeResult)})); err != nil {- return fetchAXTreeForFrame(ctx, "")+ return RawFrameTree{}, err}var frameResp struct {FrameTree RawFrameTree `json:"frameTree"`}if err := json.Unmarshal(frameTreeResult, &frameResp); err != nil {+ return RawFrameTree{}, err+ }+ return frameResp.FrameTree, nil+}++// FetchAXTree returns the merged accessibility tree for the current page and any child frames.+func FetchAXTree(ctx context.Context) ([]RawAXNode, error) {+ frameTree, err := FetchFrameTree(ctx)+ if err != nil {return fetchAXTreeForFrame(ctx, "")}- frameMap := FrameMap(frameResp.FrameTree)- ownerMap := FrameOwnerMap(ctx, frameResp.FrameTree)- ids := FrameIDs(frameResp.FrameTree)+ frameMap := FrameMap(frameTree)+ ownerMap := FrameOwnerMap(ctx, frameTree)+ ids := FrameIDs(frameTree)if len(ids) == 0 {return fetchAXTreeForFrame(ctx, "")}@@ -232,6 +243,7 @@ func BuildSnapshot(nodes []RawAXNode, filter string, maxDepth int) ([]A11yNode,backendToAX := make(map[int64]string, len(nodes))frameRoots := make(map[string][]string, 4)frameOwners := make(map[string]int64, 4)+ ownerToChildFrame := make(map[int64]RawFrame, 4)frameOrder := make([]string, 0, 4)seenFrames := make(map[string]bool, 4)@@ -247,6 +259,11 @@ func BuildSnapshot(nodes []RawAXNode, filter string, maxDepth int) ([]A11yNode,}if n.FrameOwnerNodeID != 0 && frameOwners[n.FrameID] == 0 {frameOwners[n.FrameID] = n.FrameOwnerNodeID+ ownerToChildFrame[n.FrameOwnerNodeID] = RawFrame{+ ID: n.FrameID,+ URL: n.FrameURL,+ Name: n.FrameName,+ }}for _, childID := range n.ChildIDs {parentMap[childID] = n.NodeID@@ -338,6 +355,11 @@ func BuildSnapshot(nodes []RawAXNode, filter string, maxDepth int) ([]A11yNode,FrameURL: n.FrameURL,FrameName: n.FrameName,}+ if childFrame, ok := ownerToChildFrame[n.BackendDOMNodeID]; ok {+ entry.ChildFrameID = childFrame.ID+ entry.ChildFrameURL = childFrame.URL+ entry.ChildFrameName = childFrame.Name+ }if v := n.Value.String(); v != "" {entry.Value = vdiff --git a/internal/bridge/observe_facade.go b/internal/bridge/observe_facade.goindex 8d9217d3..1d8cf9ed 100644--- a/internal/bridge/observe_facade.go+++ b/internal/bridge/observe_facade.go@@ -18,6 +18,7 @@ type RawAXNode = bridgeobserve.RawAXNodetype RawAXValue = bridgeobserve.RawAXValuetype RawAXProp = bridgeobserve.RawAXProptype RawFrame = bridgeobserve.RawFrame+type RawFrameTree = bridgeobserve.RawFrameTreetype rawFrameTree = bridgeobserve.RawFrameTreetype NetworkEntry = bridgeobserve.NetworkEntry@@ -26,14 +27,22 @@ type NetworkFilter = bridgeobserve.NetworkFiltertype NetworkMonitor = bridgeobserve.NetworkMonitortype MemoryMetrics = bridgeobserve.MemoryMetrics-func frameIDs(tree rawFrameTree) []string {+func frameIDs(tree RawFrameTree) []string {return bridgeobserve.FrameIDs(tree)}-func FrameMap(tree rawFrameTree) map[string]RawFrame {+func FrameMap(tree RawFrameTree) map[string]RawFrame {return bridgeobserve.FrameMap(tree)}+func FrameOwnerMap(ctx context.Context, tree RawFrameTree) map[string]int64 {+ return bridgeobserve.FrameOwnerMap(ctx, tree)+}++func FetchFrameTree(ctx context.Context) (RawFrameTree, error) {+ return bridgeobserve.FetchFrameTree(ctx)+}+func FetchAXTree(ctx context.Context) ([]RawAXNode, error) {return bridgeobserve.FetchAXTree(ctx)}diff --git a/internal/bridge/snapshot_test.go b/internal/bridge/snapshot_test.goindex 601b04c8..3477b480 100644--- a/internal/bridge/snapshot_test.go+++ b/internal/bridge/snapshot_test.go@@ -374,6 +374,8 @@ func TestBuildSnapshotNestsFrameContentUnderOwner(t *testing.T) {ChildIDs: []string{"card", "pay"},BackendDOMNodeID: 11,FrameID: "child",+ FrameURL: "https://payments.example/frame",+ FrameName: "payment-frame",FrameOwnerNodeID: 10,},{@@ -382,6 +384,8 @@ func TestBuildSnapshotNestsFrameContentUnderOwner(t *testing.T) {Name: &RawAXValue{Value: json.RawMessage(`"Card number"`)},BackendDOMNodeID: 12,FrameID: "child",+ FrameURL: "https://payments.example/frame",+ FrameName: "payment-frame",FrameOwnerNodeID: 10,},{@@ -390,6 +394,8 @@ func TestBuildSnapshotNestsFrameContentUnderOwner(t *testing.T) {Name: &RawAXValue{Value: json.RawMessage(`"Pay"`)},BackendDOMNodeID: 13,FrameID: "child",+ FrameURL: "https://payments.example/frame",+ FrameName: "payment-frame",FrameOwnerNodeID: 10,},}@@ -401,6 +407,9 @@ func TestBuildSnapshotNestsFrameContentUnderOwner(t *testing.T) {if flat[1].Name != "payment-frame" {t.Fatalf("second node = %q, want iframe owner", flat[1].Name)}+ if flat[1].ChildFrameID != "child" {+ t.Fatalf("iframe child frame id = %q, want child", flat[1].ChildFrameID)+ }if flat[2].Name != "Card number" || flat[2].Depth != 2 {t.Fatalf("textbox = %+v, want nested child at depth 2", flat[2])}diff --git a/internal/bridge/tab_manager.go b/internal/bridge/tab_manager.goindex 7aab0e95..130c2a4a 100644--- a/internal/bridge/tab_manager.go+++ b/internal/bridge/tab_manager.go@@ -28,6 +28,7 @@ type TabManager struct {tabs map[string]*TabEntryaccessed map[string]boolsnapshots map[string]*RefCache+ frameScope map[string]FrameScopeonTabSetup TabSetupFuncdialogMgr *DialogManagerlogStore *ConsoleLogStore@@ -53,6 +54,7 @@ func NewTabManager(browserCtx context.Context, cfg *config.RuntimeConfig, idMgrtabs: make(map[string]*TabEntry),accessed: make(map[string]bool),snapshots: make(map[string]*RefCache),+ frameScope: make(map[string]FrameScope),onTabSetup: onTabSetup,logStore: logStore,executor: NewTabExecutor(maxParallel),@@ -563,6 +565,29 @@ func (tm *TabManager) DeleteRefCache(tabID string) {delete(tm.snapshots, tabID)}+func (tm *TabManager) GetFrameScope(tabID string) (FrameScope, bool) {+ tm.mu.RLock()+ defer tm.mu.RUnlock()+ scope, ok := tm.frameScope[tabID]+ return scope, ok && scope.Active()+}++func (tm *TabManager) SetFrameScope(tabID string, scope FrameScope) {+ tm.mu.Lock()+ defer tm.mu.Unlock()+ if !scope.Active() {+ delete(tm.frameScope, tabID)+ return+ }+ tm.frameScope[tabID] = scope+}++func (tm *TabManager) ClearFrameScope(tabID string) {+ tm.mu.Lock()+ defer tm.mu.Unlock()+ delete(tm.frameScope, tabID)+}+func (tm *TabManager) RegisterTab(tabID string, ctx context.Context) {now := time.Now()tm.mu.Lock()@@ -656,6 +681,7 @@ func (tm *TabManager) purgeTrackedTabState(tabID, cdpTargetID string) bool {tm.mu.Lock()delete(tm.tabs, resolvedTabID)delete(tm.snapshots, resolvedTabID)+ delete(tm.frameScope, resolvedTabID)delete(tm.accessed, resolvedTabID)if tm.currentTab == resolvedTabID {tm.currentTab = ""diff --git a/internal/cli/actions/actions_frame.go b/internal/cli/actions/actions_frame.gonew file mode 100644index 00000000..1c5ee995--- /dev/null+++ b/internal/cli/actions/actions_frame.go@@ -0,0 +1,27 @@+package actions++import (+ "net/http"+ "net/url"++ "github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/spf13/cobra"+)++func Frame(client *http.Client, base, token string, args []string, cmd *cobra.Command) {+ tabID, _ := cmd.Flags().GetString("tab")+ if len(args) == 0 {+ params := url.Values{}+ if tabID != "" {+ params.Set("tabId", tabID)+ }+ apiclient.DoGet(client, base, token, "/frame", params)+ return+ }++ body := map[string]any{"target": args[0]}+ if tabID != "" {+ body["tabId"] = tabID+ }+ apiclient.DoPost(client, base, token, "/frame", body)+}diff --git a/internal/handlers/actions.go b/internal/handlers/actions.goindex c739b5ed..c168721e 100644--- a/internal/handlers/actions.go+++ b/internal/handlers/actions.go@@ -31,6 +31,10 @@ func resolveOwner(r *http.Request, fallback string) string {return strings.TrimSpace(fallback)}+func frameScopedSelectorError(kind string, err error) error {+ return fmt.Errorf("%s in current frame: %w", kind, err)+}+func (h *Handlers) enforceTabLease(tabID, owner string) error {if tabID == "" {return nil@@ -192,25 +196,27 @@ func (h *Handlers) HandleAction(w http.ResponseWriter, r *http.Request) {refMissing = true}case selector.KindCSS:- // CSS selectors are resolved by the bridge action handlers directly- // via chromedp, so we keep req.Selector as-is (the bridge checks- // req.Selector before req.NodeID). Clear Ref so the bridge doesn't- // confuse it with a snapshot ref.req.Ref = ""- req.Selector = sel.Value+ nid, err := bridge.ResolveCSSToNodeIDInFrame(tCtx, h.selectorFrameID(resolvedTabID), sel.Value)+ if err != nil {+ httpx.Error(w, 400, frameScopedSelectorError("css selector", err))+ return+ }+ req.NodeID = nid+ req.Selector = ""case selector.KindXPath:- nid, err := bridge.ResolveXPathToNodeID(tCtx, sel.Value)+ nid, err := bridge.ResolveXPathToNodeIDInFrame(tCtx, h.selectorFrameID(resolvedTabID), sel.Value)if err != nil {- httpx.Error(w, 400, fmt.Errorf("xpath selector: %w", err))+ httpx.Error(w, 400, frameScopedSelectorError("xpath selector", err))return}req.NodeID = nidreq.Selector = ""req.Ref = ""case selector.KindText:- nid, err := bridge.ResolveTextToNodeID(tCtx, sel.Value)+ nid, err := bridge.ResolveTextToNodeIDInFrame(tCtx, h.selectorFrameID(resolvedTabID), sel.Value)if err != nil {- httpx.Error(w, 400, fmt.Errorf("text selector: %w", err))+ httpx.Error(w, 400, frameScopedSelectorError("text selector", err))return}req.NodeID = nid@@ -544,14 +550,27 @@ func (h *Handlers) handleActionsBatch(w http.ResponseWriter, r *http.Request, re}case selector.KindCSS:action.Ref = ""- action.Selector = sel.Value+ nid, resolveErr := bridge.ResolveCSSToNodeIDInFrame(tCtx, h.selectorFrameID(resolvedTabID), sel.Value)+ if resolveErr != nil {+ tCancel()+ results = append(results, actionResult{+ Index: i, Success: false,+ Error: frameScopedSelectorError("css selector", resolveErr).Error(),+ })+ if req.StopOnError {+ break+ }+ continue+ }+ action.NodeID = nid+ action.Selector = ""case selector.KindXPath:- nid, resolveErr := bridge.ResolveXPathToNodeID(tCtx, sel.Value)+ nid, resolveErr := bridge.ResolveXPathToNodeIDInFrame(tCtx, h.selectorFrameID(resolvedTabID), sel.Value)if resolveErr != nil {tCancel()results = append(results, actionResult{Index: i, Success: false,- Error: fmt.Sprintf("xpath selector: %v", resolveErr),+ Error: frameScopedSelectorError("xpath selector", resolveErr).Error(),})if req.StopOnError {break@@ -562,12 +581,12 @@ func (h *Handlers) handleActionsBatch(w http.ResponseWriter, r *http.Request, reaction.Selector = ""action.Ref = ""case selector.KindText:- nid, resolveErr := bridge.ResolveTextToNodeID(tCtx, sel.Value)+ nid, resolveErr := bridge.ResolveTextToNodeIDInFrame(tCtx, h.selectorFrameID(resolvedTabID), sel.Value)if resolveErr != nil {tCancel()results = append(results, actionResult{Index: i, Success: false,- Error: fmt.Sprintf("text selector: %v", resolveErr),+ Error: frameScopedSelectorError("text selector", resolveErr).Error(),})if req.StopOnError {break@@ -823,15 +842,29 @@ func (h *Handlers) HandleMacro(w http.ResponseWriter, r *http.Request) {}case selector.KindCSS:step.Ref = ""- step.Selector = sel.Value+ tCtx, cancel := context.WithTimeout(ctx, stepTimeout)+ nid, resolveErr := bridge.ResolveCSSToNodeIDInFrame(tCtx, h.selectorFrameID(resolvedTabID), sel.Value)+ cancel()+ if resolveErr != nil {+ results = append(results, actionResult{+ Index: i, Success: false,+ Error: frameScopedSelectorError("css selector", resolveErr).Error(),+ })+ if req.StopOnError {+ break+ }+ continue+ }+ step.NodeID = nid+ step.Selector = ""case selector.KindXPath:tCtx, cancel := context.WithTimeout(ctx, stepTimeout)- nid, resolveErr := bridge.ResolveXPathToNodeID(tCtx, sel.Value)+ nid, resolveErr := bridge.ResolveXPathToNodeIDInFrame(tCtx, h.selectorFrameID(resolvedTabID), sel.Value)cancel()if resolveErr != nil {results = append(results, actionResult{Index: i, Success: false,- Error: fmt.Sprintf("xpath selector: %v", resolveErr),+ Error: frameScopedSelectorError("xpath selector", resolveErr).Error(),})if req.StopOnError {break@@ -843,12 +876,12 @@ func (h *Handlers) HandleMacro(w http.ResponseWriter, r *http.Request) {step.Ref = ""case selector.KindText:tCtx, cancel := context.WithTimeout(ctx, stepTimeout)- nid, resolveErr := bridge.ResolveTextToNodeID(tCtx, sel.Value)+ nid, resolveErr := bridge.ResolveTextToNodeIDInFrame(tCtx, h.selectorFrameID(resolvedTabID), sel.Value)cancel()if resolveErr != nil {results = append(results, actionResult{Index: i, Success: false,- Error: fmt.Sprintf("text selector: %v", resolveErr),+ Error: frameScopedSelectorError("text selector", resolveErr).Error(),})if req.StopOnError {breakdiff --git a/internal/handlers/frame.go b/internal/handlers/frame.gonew file mode 100644index 00000000..85c9e984--- /dev/null+++ b/internal/handlers/frame.go@@ -0,0 +1,394 @@+package handlers++import (+ "context"+ "encoding/json"+ "fmt"+ "net/http"+ "strings"++ "github.com/pinchtab/pinchtab/internal/bridge"+ "github.com/pinchtab/pinchtab/internal/httpx"+ "github.com/pinchtab/pinchtab/internal/selector"+)++type frameScopeAPI interface {+ GetFrameScope(tabID string) (bridge.FrameScope, bool)+ SetFrameScope(tabID string, scope bridge.FrameScope)+ ClearFrameScope(tabID string)+}++type frameRequest struct {+ TabID string `json:"tabId,omitempty"`+ Target string `json:"target,omitempty"`+}++func (h *Handlers) frameScopes() frameScopeAPI {+ scopes, _ := h.Bridge.(frameScopeAPI)+ return scopes+}++func (h *Handlers) currentFrameScope(tabID string) (bridge.FrameScope, bool) {+ scopes := h.frameScopes()+ if scopes == nil {+ return bridge.FrameScope{}, false+ }+ return scopes.GetFrameScope(tabID)+}++func (h *Handlers) selectorFrameID(tabID string) string {+ scope, ok := h.currentFrameScope(tabID)+ if !ok {+ return ""+ }+ return scope.FrameID+}++func (h *Handlers) scopeSnapshotNodesByFrame(nodes []bridge.RawAXNode, frameID string) []bridge.RawAXNode {+ if frameID == "" {+ return nodes+ }+ filtered := make([]bridge.RawAXNode, 0, len(nodes))+ for _, node := range nodes {+ if node.FrameID == frameID {+ filtered = append(filtered, node)+ }+ }+ return filtered+}++func (h *Handlers) resolveSelectorNodeID(ctx context.Context, tabID, raw string) (int64, error) {+ sel := selector.Parse(raw)+ cache := h.Bridge.GetRefCache(tabID)+ return bridge.ResolveUnifiedSelectorInFrame(ctx, sel, cache, h.selectorFrameID(tabID))+}++func ownerRefForFrame(cache *bridge.RefCache, frameID string) string {+ if cache == nil || frameID == "" {+ return ""+ }+ for _, node := range cache.Nodes {+ if node.ChildFrameID == frameID {+ return node.Ref+ }+ }+ for ref, target := range cache.Targets {+ if target.ChildFrameID == frameID {+ return ref+ }+ }+ return ""+}++func frameScopeForChildFrame(frameID, ownerRef, fallbackURL, fallbackName string, frames map[string]bridge.RawFrame) (bridge.FrameScope, bool) {+ if frameID == "" {+ return bridge.FrameScope{}, false+ }+ scope := bridge.FrameScope{+ FrameID: frameID,+ FrameURL: fallbackURL,+ FrameName: fallbackName,+ OwnerRef: ownerRef,+ }+ if frame, ok := frames[frameID]; ok {+ if frame.URL != "" {+ scope.FrameURL = frame.URL+ }+ if frame.Name != "" {+ scope.FrameName = frame.Name+ }+ }+ return scope, true+}++func matchFrameByElementMeta(frames map[string]bridge.RawFrame, rootFrameID string, meta bridge.FrameElementMeta) (bridge.FrameScope, bool, error) {+ tag := strings.ToLower(strings.TrimSpace(meta.TagName))+ if tag != "iframe" && tag != "frame" {+ return bridge.FrameScope{}, false, nil+ }++ candidates := make([]bridge.FrameScope, 0, 1)+ addCandidate := func(frameID string, frame bridge.RawFrame) {+ candidates = append(candidates, bridge.FrameScope{+ FrameID: frameID,+ FrameURL: frame.URL,+ FrameName: frame.Name,+ })+ }++ if src := strings.TrimSpace(meta.Src); src != "" {+ for frameID, frame := range frames {+ if frameID == "" || frameID == rootFrameID {+ continue+ }+ if frame.URL == src {+ addCandidate(frameID, frame)+ }+ }+ if len(candidates) == 1 {+ return candidates[0], true, nil+ }+ if len(candidates) > 1 {+ return bridge.FrameScope{}, false, fmt.Errorf("frame selector matched multiple frames for src %q", src)+ }+ }++ label := strings.TrimSpace(meta.Name)+ if label == "" {+ label = strings.TrimSpace(meta.Title)+ }+ if label != "" {+ for frameID, frame := range frames {+ if frameID == "" || frameID == rootFrameID {+ continue+ }+ if frame.Name == label || strings.Contains(frame.URL, label) {+ addCandidate(frameID, frame)+ }+ }+ if len(candidates) == 1 {+ return candidates[0], true, nil+ }+ if len(candidates) > 1 {+ return bridge.FrameScope{}, false, fmt.Errorf("frame selector matched multiple frames for %q", label)+ }+ }++ var only bridge.FrameScope+ count := 0+ for frameID, frame := range frames {+ if frameID == "" || frameID == rootFrameID {+ continue+ }+ only = bridge.FrameScope{FrameID: frameID, FrameURL: frame.URL, FrameName: frame.Name}+ count+++ }+ if count == 1 {+ return only, true, nil+ }+ return bridge.FrameScope{}, false, nil+}++func frameScopeForOwnerNode(nodeID int64, cache *bridge.RefCache, frames map[string]bridge.RawFrame, ownerMap map[string]int64) (bridge.FrameScope, bool) {+ if nodeID == 0 {+ return bridge.FrameScope{}, false+ }+ for frameID, ownerNodeID := range ownerMap {+ if ownerNodeID != nodeID {+ continue+ }+ return frameScopeForChildFrame(frameID, ownerRefForFrame(cache, frameID), "", "", frames)+ }+ if cache == nil {+ return bridge.FrameScope{}, false+ }+ for ref, target := range cache.Targets {+ if target.BackendNodeID != nodeID || target.ChildFrameID == "" {+ continue+ }+ return frameScopeForChildFrame(target.ChildFrameID, ref, target.ChildFrameURL, target.ChildFrameName, frames)+ }+ for _, node := range cache.Nodes {+ if node.NodeID != nodeID || node.ChildFrameID == "" {+ continue+ }+ return frameScopeForChildFrame(node.ChildFrameID, node.Ref, node.ChildFrameURL, node.ChildFrameName, frames)+ }+ return bridge.FrameScope{}, false+}++func matchFrameByMeta(frames map[string]bridge.RawFrame, rootFrameID, target string) ([]bridge.FrameScope, error) {+ target = strings.TrimSpace(target)+ if target == "" {+ return nil, fmt.Errorf("missing frame target")+ }+ matches := make([]bridge.FrameScope, 0, 1)+ for frameID, frame := range frames {+ if frameID == "" || frameID == rootFrameID {+ continue+ }+ if frame.Name == target || frame.URL == target || strings.Contains(frame.URL, target) {+ matches = append(matches, bridge.FrameScope{+ FrameID: frameID,+ FrameURL: frame.URL,+ FrameName: frame.Name,+ })+ }+ }+ if len(matches) > 1 {+ return nil, fmt.Errorf("frame target %q matched multiple frames", target)+ }+ return matches, nil+}++func (h *Handlers) resolveFrameScope(ctx context.Context, tabID, target string) (bridge.FrameScope, bool, error) {+ target = strings.TrimSpace(target)+ if target == "" {+ return bridge.FrameScope{}, false, fmt.Errorf("missing frame target")+ }+ if strings.EqualFold(target, "main") {+ return bridge.FrameScope{}, true, nil+ }++ cache := h.Bridge.GetRefCache(tabID)+ sel := selector.Parse(target)+ var refScope bridge.FrameScope+ var hasRefScope bool+ if sel.Kind == selector.KindRef {+ if cache == nil {+ return bridge.FrameScope{}, false, fmt.Errorf("no snapshot cache available for ref %q", sel.Value)+ }+ refTarget, ok := cache.Lookup(sel.Value)+ if !ok {+ return bridge.FrameScope{}, false, fmt.Errorf("ref %q not found in snapshot cache", sel.Value)+ }+ if refTarget.ChildFrameID != "" {+ return bridge.FrameScope{+ FrameID: refTarget.ChildFrameID,+ FrameURL: refTarget.ChildFrameURL,+ FrameName: refTarget.ChildFrameName,+ OwnerRef: sel.Value,+ }, false, nil+ }+ if refTarget.FrameID != "" {+ refScope = bridge.FrameScope{+ FrameID: refTarget.FrameID,+ FrameURL: refTarget.FrameURL,+ FrameName: refTarget.FrameName,+ }+ hasRefScope = true+ }+ }++ frameTree, err := bridge.FetchFrameTree(ctx)+ if err != nil {+ return bridge.FrameScope{}, false, fmt.Errorf("frame tree: %w", err)+ }+ rootFrameID := frameTree.Frame.ID+ frames := bridge.FrameMap(frameTree)+ ownerMap := bridge.FrameOwnerMap(ctx, frameTree)+ if hasRefScope {+ if refScope.FrameID == rootFrameID {+ return bridge.FrameScope{}, true, nil+ }+ return refScope, false, nil+ }++ if matches, err := matchFrameByMeta(frames, rootFrameID, target); err == nil && len(matches) == 1 {+ scope := matches[0]+ scope.OwnerRef = ownerRefForFrame(cache, scope.FrameID)+ return scope, false, nil+ } else if err != nil {+ return bridge.FrameScope{}, false, err+ }++ switch sel.Kind {+ case selector.KindCSS, selector.KindXPath, selector.KindText:+ nodeID, err := h.resolveSelectorNodeID(ctx, tabID, target)+ if err != nil {+ return bridge.FrameScope{}, false, err+ }+ if scope, ok := frameScopeForOwnerNode(nodeID, cache, frames, ownerMap); ok {+ return scope, false, nil+ }+ if sel.Kind == selector.KindCSS || sel.Kind == selector.KindXPath {+ meta, metaErr := bridge.ResolveFrameElementMetaInFrame(ctx, sel, h.selectorFrameID(tabID))+ if metaErr == nil {+ if scope, ok, matchErr := matchFrameByElementMeta(frames, rootFrameID, meta); matchErr != nil {+ return bridge.FrameScope{}, false, matchErr+ } else if ok {+ scope.OwnerRef = ownerRefForFrame(cache, scope.FrameID)+ return scope, false, nil+ }+ }+ }+ }++ return bridge.FrameScope{}, false, fmt.Errorf("frame target %q did not resolve to an iframe or frame", target)+}++func writeFrameScope(w http.ResponseWriter, tabID string, scope bridge.FrameScope, scoped bool) {+ resp := map[string]any{+ "tabId": tabID,+ "scoped": scoped,+ "target": "main",+ "current": "main",+ }+ if scoped {+ resp["target"] = scope.FrameID+ resp["current"] = scope+ resp["frame"] = scope+ }+ httpx.JSON(w, 200, resp)+}++func (h *Handlers) HandleFrame(w http.ResponseWriter, r *http.Request) {+ tabID := r.URL.Query().Get("tabId")+ var req frameRequest+ if r.Method != http.MethodGet {+ if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, maxBodySize)).Decode(&req); err != nil {+ httpx.Error(w, 400, fmt.Errorf("decode: %w", err))+ return+ }+ if req.TabID != "" {+ tabID = req.TabID+ }+ }++ ctx, resolvedTabID, err := h.tabContextWithHeader(w, r, tabID)+ if err != nil {+ httpx.Error(w, 404, err)+ return+ }++ scopes := h.frameScopes()+ if scopes == nil {+ httpx.Error(w, 501, fmt.Errorf("frame scoping unavailable"))+ return+ }++ if r.Method == http.MethodGet {+ scope, ok := scopes.GetFrameScope(resolvedTabID)+ writeFrameScope(w, resolvedTabID, scope, ok)+ return+ }+ if strings.TrimSpace(req.Target) == "" {+ httpx.Error(w, 400, fmt.Errorf("missing required field 'target'"))+ return+ }++ tCtx, cancel := context.WithTimeout(ctx, h.Config.ActionTimeout)+ defer cancel()+ go httpx.CancelOnClientDone(r.Context(), cancel)++ scope, resetToMain, err := h.resolveFrameScope(tCtx, resolvedTabID, req.Target)+ if err != nil {+ httpx.Error(w, 400, err)+ return+ }+ if resetToMain || !scope.Active() {+ scopes.ClearFrameScope(resolvedTabID)+ writeFrameScope(w, resolvedTabID, bridge.FrameScope{}, false)+ return+ }++ if scope.OwnerRef == "" {+ scope.OwnerRef = ownerRefForFrame(h.Bridge.GetRefCache(resolvedTabID), scope.FrameID)+ }+ scopes.SetFrameScope(resolvedTabID, scope)+ writeFrameScope(w, resolvedTabID, scope, true)+}++func (h *Handlers) HandleTabFrame(w http.ResponseWriter, r *http.Request) {+ tabID := strings.TrimSpace(r.PathValue("id"))+ if tabID == "" {+ httpx.Error(w, 400, fmt.Errorf("missing tab id"))+ return+ }++ wrapped := r.Clone(r.Context())+ q := wrapped.URL.Query()+ q.Set("tabId", tabID)+ wrapped.URL.RawQuery = q.Encode()+ h.HandleFrame(w, wrapped)+}diff --git a/internal/handlers/frame_test.go b/internal/handlers/frame_test.gonew file mode 100644index 00000000..a9b66712--- /dev/null+++ b/internal/handlers/frame_test.go@@ -0,0 +1,123 @@+package handlers++import (+ "net/http"+ "net/http/httptest"+ "strings"+ "testing"++ "github.com/pinchtab/pinchtab/internal/bridge"+ "github.com/pinchtab/pinchtab/internal/config"+)++func TestHandleFrameGetCurrentScope(t *testing.T) {+ mb := &mockBridge{+ frameScopes: map[string]bridge.FrameScope{+ "tab1": {+ FrameID: "child",+ FrameURL: "https://example.com/frame",+ FrameName: "payment-frame",+ OwnerRef: "e3",+ },+ },+ }+ h := New(mb, &config.RuntimeConfig{}, nil, nil, nil)++ req := httptest.NewRequest("GET", "/frame", nil)+ w := httptest.NewRecorder()+ h.HandleFrame(w, req)++ if w.Code != http.StatusOK {+ t.Fatalf("expected 200, got %d", w.Code)+ }+ body := w.Body.String()+ if !strings.Contains(body, `"scoped":true`) {+ t.Fatalf("expected scoped response, got %s", body)+ }+ if !strings.Contains(body, `"frameId":"child"`) {+ t.Fatalf("expected child frame id, got %s", body)+ }+}++func TestHandleFramePostMainClearsScope(t *testing.T) {+ mb := &mockBridge{+ frameScopes: map[string]bridge.FrameScope{+ "tab1": {FrameID: "child"},+ },+ }+ h := New(mb, &config.RuntimeConfig{}, nil, nil, nil)++ req := httptest.NewRequest("POST", "/frame", strings.NewReader(`{"target":"main"}`))+ w := httptest.NewRecorder()+ h.HandleFrame(w, req)++ if w.Code != http.StatusOK {+ t.Fatalf("expected 200, got %d", w.Code)+ }+ if _, ok := mb.GetFrameScope("tab1"); ok {+ t.Fatal("expected frame scope to be cleared")+ }+ if !strings.Contains(w.Body.String(), `"scoped":false`) {+ t.Fatalf("expected unscoped response, got %s", w.Body.String())+ }+}++func TestFrameScopeForOwnerNodeFallsBackToRefCacheTargets(t *testing.T) {+ cache := &bridge.RefCache{+ Targets: map[string]bridge.RefTarget{+ "e3": {+ BackendNodeID: 20,+ ChildFrameID: "child-frame",+ ChildFrameURL: "https://example.com/embed",+ ChildFrameName: "payment-frame",+ },+ },+ }+ frames := map[string]bridge.RawFrame{+ "child-frame": {+ ID: "child-frame",+ URL: "https://example.com/embed",+ Name: "payment-frame",+ },+ }++ scope, ok := frameScopeForOwnerNode(20, cache, frames, nil)+ if !ok {+ t.Fatal("expected frame scope from ref cache fallback")+ }+ if scope.FrameID != "child-frame" {+ t.Fatalf("frame id = %q, want %q", scope.FrameID, "child-frame")+ }+ if scope.OwnerRef != "e3" {+ t.Fatalf("owner ref = %q, want %q", scope.OwnerRef, "e3")+ }+}++func TestMatchFrameByElementMetaMatchesIframeSrc(t *testing.T) {+ frames := map[string]bridge.RawFrame{+ "root": {+ ID: "root",+ URL: "https://example.com",+ Name: "main",+ },+ "child-frame": {+ ID: "child-frame",+ URL: "https://example.com/embed",+ Name: "payment-frame",+ },+ }++ scope, ok, err := matchFrameByElementMeta(frames, "root", bridge.FrameElementMeta{+ TagName: "iframe",+ Src: "https://example.com/embed",+ })+ if err != nil {+ t.Fatalf("matchFrameByElementMeta() error = %v", err)+ }+ if !ok {+ t.Fatal("expected iframe src to match a frame")+ }+ if scope.FrameID != "child-frame" {+ t.Fatalf("frame id = %q, want %q", scope.FrameID, "child-frame")+ }+}diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.goindex 100a3fc1..ff72a3fa 100644--- a/internal/handlers/handlers.go+++ b/internal/handlers/handlers.go@@ -155,6 +155,8 @@ func (h *Handlers) RegisterRoutes(mux *http.ServeMux, doShutdown func()) {mux.HandleFunc("POST /tabs/{id}/forward", h.HandleTabForward)mux.HandleFunc("POST /tabs/{id}/reload", h.HandleTabReload)mux.HandleFunc("GET /tabs/{id}/snapshot", h.HandleTabSnapshot)+ mux.HandleFunc("GET /tabs/{id}/frame", h.HandleTabFrame)+ mux.HandleFunc("POST /tabs/{id}/frame", h.HandleTabFrame)mux.HandleFunc("GET /tabs/{id}/screenshot", h.HandleTabScreenshot)mux.HandleFunc("POST /tabs/{id}/action", h.HandleTabAction)mux.HandleFunc("POST /tabs/{id}/actions", h.HandleTabActions)@@ -165,6 +167,8 @@ func (h *Handlers) RegisterRoutes(mux *http.ServeMux, doShutdown func()) {mux.HandleFunc("GET /tabs/{id}/metrics", h.HandleTabMetrics)mux.HandleFunc("GET /metrics", h.HandleMetrics)mux.HandleFunc("GET /snapshot", h.HandleSnapshot)+ mux.HandleFunc("GET /frame", h.HandleFrame)+ mux.HandleFunc("POST /frame", h.HandleFrame)mux.HandleFunc("GET /screenshot", h.HandleScreenshot)mux.HandleFunc("GET /tabs/{id}/pdf", h.HandleTabPDF)mux.HandleFunc("POST /tabs/{id}/pdf", h.HandleTabPDF)diff --git a/internal/handlers/handlers_test.go b/internal/handlers/handlers_test.goindex 75c07603..ed901a61 100644--- a/internal/handlers/handlers_test.go+++ b/internal/handlers/handlers_test.go@@ -24,6 +24,7 @@ type mockBridge struct {lastConsoleLimit intlastErrorLimit intfingerprintTabs map[string]bool+ frameScopes map[string]bridge.FrameScope}func (m *mockBridge) TabContext(tabID string) (context.Context, string, error) {@@ -123,6 +124,25 @@ func (m *mockBridge) Execute(ctx context.Context, tabID string, task func(ctx coreturn task(ctx)}+func (m *mockBridge) GetFrameScope(tabID string) (bridge.FrameScope, bool) {+ if m.frameScopes == nil {+ return bridge.FrameScope{}, false+ }+ scope, ok := m.frameScopes[tabID]+ return scope, ok && scope.Active()+}++func (m *mockBridge) SetFrameScope(tabID string, scope bridge.FrameScope) {+ if m.frameScopes == nil {+ m.frameScopes = make(map[string]bridge.FrameScope)+ }+ m.frameScopes[tabID] = scope+}++func (m *mockBridge) ClearFrameScope(tabID string) {+ delete(m.frameScopes, tabID)+}+func (m *mockBridge) SetFingerprintRotateActive(tabID string, active bool) {if m.fingerprintTabs == nil {m.fingerprintTabs = make(map[string]bool)diff --git a/internal/handlers/snapshot.go b/internal/handlers/snapshot.goindex a79eadfe..368cdde5 100644--- a/internal/handlers/snapshot.go+++ b/internal/handlers/snapshot.go@@ -143,32 +143,15 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {httpx.Error(w, 500, fmt.Errorf("a11y tree: %w", err))return}+ nodes = h.scopeSnapshotNodesByFrame(nodes, h.selectorFrameID(resolvedTabID))treeResp := struct {Nodes []bridge.RawAXNode `json:"nodes"`}{Nodes: nodes}if selector != "" {- // Unified selector: resolve to a backend node ID for subtree scoping.- // Supports CSS (default), XPath, and text selectors.- var scopeNodeID int64- var scopeErr error-- switch {- case strings.HasPrefix(selector, "xpath:"):- scopeNodeID, scopeErr = bridge.ResolveXPathToNodeID(tCtx, selector[len("xpath:"):])- case strings.HasPrefix(selector, "//") || strings.HasPrefix(selector, "(//"):- scopeNodeID, scopeErr = bridge.ResolveXPathToNodeID(tCtx, selector)- case strings.HasPrefix(selector, "text:"):- scopeNodeID, scopeErr = bridge.ResolveTextToNodeID(tCtx, selector[len("text:"):])- case strings.HasPrefix(selector, "css:"):- scopeNodeID, scopeErr = bridge.ResolveCSSToNodeID(tCtx, selector[len("css:"):])- default:- // Bare selector — treat as CSS (backward compatible)- scopeNodeID, scopeErr = bridge.ResolveCSSToNodeID(tCtx, selector)- }-+ scopeNodeID, scopeErr := h.resolveSelectorNodeID(tCtx, resolvedTabID, selector)if scopeErr != nil {- httpx.Error(w, 400, fmt.Errorf("selector: %w", scopeErr))+ httpx.Error(w, 400, frameScopedSelectorError("selector", scopeErr))return}diff --git a/internal/mcp/handlers.go b/internal/mcp/handlers.goindex eca668e2..fcfeb72c 100644--- a/internal/mcp/handlers.go+++ b/internal/mcp/handlers.go@@ -15,6 +15,7 @@ func handlerMap(c *Client) map[string]func(context.Context, mcp.CallToolRequest)// Navigation"pinchtab_navigate": handleNavigate(c),"pinchtab_snapshot": handleSnapshot(c),+ "pinchtab_frame": handleFrame(c),"pinchtab_screenshot": handleScreenshot(c),"pinchtab_get_text": handleGetText(c),diff --git a/internal/mcp/handlers_navigation.go b/internal/mcp/handlers_navigation.goindex ebf0e4db..c5ec6020 100644--- a/internal/mcp/handlers_navigation.go+++ b/internal/mcp/handlers_navigation.go@@ -74,6 +74,34 @@ func handleSnapshot(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.}}+func handleFrame(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ tabID := optString(r, "tabId")+ target := optString(r, "target")+ if strings.TrimSpace(target) == "" {+ q := url.Values{}+ if tabID != "" {+ q.Set("tabId", tabID)+ }+ body, code, err := c.Get(ctx, "/frame", q)+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ return resultFromBytes(body, code)+ }++ payload := map[string]any{"target": target}+ if tabID != "" {+ payload["tabId"] = tabID+ }+ body, code, err := c.Post(ctx, "/frame", payload)+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ return resultFromBytes(body, code)+ }+}+func normalizeSnapshotFormat(v string) (string, error) {format := strings.ToLower(strings.TrimSpace(v))switch format {diff --git a/internal/mcp/handlers_navigation_test.go b/internal/mcp/handlers_navigation_test.goindex 3faedf69..9b5cd501 100644--- a/internal/mcp/handlers_navigation_test.go+++ b/internal/mcp/handlers_navigation_test.go@@ -96,6 +96,47 @@ func TestHandleSnapshot(t *testing.T) {}}+func TestHandleFrameGet(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_frame", map[string]any{+ "tabId": "t1",+ }, srv)++ text := resultText(t, r)+ if !strings.Contains(text, "/frame") {+ t.Errorf("expected /frame path, got %s", text)+ }+ resp := resultJSON(t, r)+ if got, _ := resp["method"].(string); got != "GET" {+ t.Errorf("method = %q, want GET", got)+ }+}++func TestHandleFrameSet(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_frame", map[string]any{+ "tabId": "t1",+ "target": "main",+ }, srv)++ text := resultText(t, r)+ if !strings.Contains(text, "/frame") {+ t.Errorf("expected /frame path, got %s", text)+ }+ resp := resultJSON(t, r)+ if got, _ := resp["method"].(string); got != "POST" {+ t.Errorf("method = %q, want POST", got)+ }+ body, _ := resp["body"].(map[string]any)+ if got, _ := body["target"].(string); got != "main" {+ t.Errorf("target = %q, want main", got)+ }+}+func TestHandleSnapshotFormatText(t *testing.T) {srv := mockPinchTab()defer srv.Close()diff --git a/internal/mcp/handlers_test.go b/internal/mcp/handlers_test.goindex aca2fec0..21c84ffd 100644--- a/internal/mcp/handlers_test.go+++ b/internal/mcp/handlers_test.go@@ -78,3 +78,12 @@ func resultText(t *testing.T, r *mcp.CallToolResult) string {}return tc.Text}++func resultJSON(t *testing.T, r *mcp.CallToolResult) map[string]any {+ t.Helper()+ var v map[string]any+ if err := json.Unmarshal([]byte(resultText(t, r)), &v); err != nil {+ t.Fatalf("unmarshal result JSON: %v", err)+ }+ return v+}diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.goindex 2fe93abd..2046dd8a 100644--- a/internal/mcp/server_test.go+++ b/internal/mcp/server_test.go@@ -18,8 +18,8 @@ func TestNewServerRegistersAllTools(t *testing.T) {// The server should have registered all tools.// We verify by checking that NewServer doesn't panic — the panic// in NewServer fires if any tool lacks a handler.- if len(tools) != 34 {- t.Errorf("expected 34 tools, got %d", len(tools))+ if len(tools) != 35 {+ t.Errorf("expected 35 tools, got %d", len(tools))}}diff --git a/internal/mcp/tools.go b/internal/mcp/tools.goindex c0a931cd..e0d64e44 100644--- a/internal/mcp/tools.go+++ b/internal/mcp/tools.go@@ -18,11 +18,16 @@ func allTools() []mcp.Tool {mcp.WithBoolean("compact", mcp.Description("Compact format (most token-efficient)")),mcp.WithString("format", mcp.Description("Output format: 'compact' or 'text'")),mcp.WithBoolean("diff", mcp.Description("Only changes since last snapshot")),- mcp.WithString("selector", mcp.Description("Unified selector to scope the snapshot (CSS, XPath, text, or ref)")),+ mcp.WithString("selector", mcp.Description("Unified selector to scope the snapshot (CSS, XPath, text, or ref). Selectors resolve in the current frame scope; use pinchtab_frame for iframe content.")),mcp.WithNumber("maxTokens", mcp.Description("Maximum estimated tokens in response (e.g. 300)")),mcp.WithNumber("depth", mcp.Description("Maximum tree depth (e.g. 3)")),mcp.WithBoolean("noAnimations", mcp.Description("Disable animations before capturing the snapshot")),),+ mcp.NewTool("pinchtab_frame",+ mcp.WithDescription("Get or set the current frame scope for selector-based actions and snapshots"),+ mcp.WithString("tabId", mcp.Description("Target tab ID")),+ mcp.WithString("target", mcp.Description("Frame target: 'main', a snapshot ref, a selector for an iframe element, or a frame name/URL")),+ ),mcp.NewTool("pinchtab_screenshot",mcp.WithDescription("Take a screenshot of the current page"),mcp.WithString("tabId", mcp.Description("Target tab ID")),@@ -40,14 +45,14 @@ func allTools() []mcp.Tool {// ── Interaction ─────────────────────────────────────────────mcp.NewTool("pinchtab_click",mcp.WithDescription("Click an element by selector (ref from snapshot e.g. 'e5', CSS e.g. 'css:#btn', XPath e.g. 'xpath://button', text e.g. 'text:Submit', or semantic e.g. 'find:login button')"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS ('css:#btn' or '#btn'), XPath ('xpath://button'), text ('text:Submit'), or semantic ('find:login button')")),+ mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS ('css:#btn' or '#btn'), XPath ('xpath://button'), text ('text:Submit'), or semantic ('find:login button'). Non-ref selectors resolve in the current frame scope.")),mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),mcp.WithBoolean("waitNav", mcp.Description("Wait for navigation after the click when the element triggers a page change")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_type",mcp.WithDescription("Type text into an input element"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic")),+ mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),mcp.WithString("text", mcp.Required(), mcp.Description("Text to type")),mcp.WithString("tabId", mcp.Description("Target tab ID")),@@ -59,33 +64,33 @@ func allTools() []mcp.Tool {),mcp.NewTool("pinchtab_hover",mcp.WithDescription("Hover over an element"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic")),+ mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_focus",mcp.WithDescription("Focus an element"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic")),+ mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_select",mcp.WithDescription("Select a dropdown option by value"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector for the select element")),+ mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector for the select element. Non-ref selectors resolve in the current frame scope.")),mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),mcp.WithString("value", mcp.Required(), mcp.Description("Option value to select")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_scroll",mcp.WithDescription("Scroll the page or an element"),- mcp.WithString("selector", mcp.Description("Unified selector for element to scroll (omit for page scroll)")),+ mcp.WithString("selector", mcp.Description("Unified selector for element to scroll (omit for page scroll). Non-ref selectors resolve in the current frame scope.")),mcp.WithString("ref", mcp.Description("(deprecated) Element ref to scroll — use 'selector' instead")),mcp.WithNumber("pixels", mcp.Description("Number of pixels to scroll (positive=down, negative=up)")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_fill",mcp.WithDescription("Fill an input field directly via JavaScript dispatch"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic")),+ mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),mcp.WithString("ref", mcp.Description("(deprecated) Element ref — use 'selector' instead")),mcp.WithString("value", mcp.Required(), mcp.Description("Value to fill")),mcp.WithString("tabId", mcp.Description("Target tab ID")),@@ -115,7 +120,7 @@ func allTools() []mcp.Tool {// ── Content ─────────────────────────────────────────────────mcp.NewTool("pinchtab_eval",- mcp.WithDescription("Execute JavaScript in the browser and return the result"),+ mcp.WithDescription("Execute JavaScript in the browser and return the result. This is not frame-scoped; current pinchtab_frame state does not change evaluation context."),mcp.WithString("expression", mcp.Required(), mcp.Description("JavaScript expression to evaluate")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),diff --git a/internal/routes/routes.go b/internal/routes/routes.goindex 9a39d95b..0cb75785 100644--- a/internal/routes/routes.go+++ b/internal/routes/routes.go@@ -52,6 +52,8 @@ var coreEndpoints = []Endpoint{// Content extraction{"GET", "/snapshot", "Accessibility snapshot", CapNone, true},+ {"GET", "/frame", "Get current frame scope", CapNone, true},+ {"POST", "/frame", "Set current frame scope", CapNone, true},{"GET", "/screenshot", "Page screenshot", CapNone, true},{"GET", "/text", "Extract page text", CapNone, true},{"GET", "/pdf", "Export as PDF (GET)", CapNone, true},diff --git a/internal/routes/routes_test.go b/internal/routes/routes_test.goindex 6e5bd06d..0b053200 100644--- a/internal/routes/routes_test.go+++ b/internal/routes/routes_test.go@@ -5,6 +5,38 @@ import ("testing")+func TestFrameEndpointsAreShorthandAndTabScoped(t *testing.T) {+ found := map[string]bool{+ "GET /frame": false,+ "POST /frame": false,+ }+ for _, route := range ShorthandRoutes() {+ if _, ok := found[route]; ok {+ found[route] = true+ }+ }+ for route, ok := range found {+ if !ok {+ t.Fatalf("ShorthandRoutes() missing %s", route)+ }+ }++ wantTabRoutes := map[string]bool{+ "GET /tabs/{id}/frame": false,+ "POST /tabs/{id}/frame": false,+ }+ for _, route := range TabScopedRoutes() {+ if _, ok := wantTabRoutes[route]; ok {+ wantTabRoutes[route] = true+ }+ }+ for route, ok := range wantTabRoutes {+ if !ok {+ t.Fatalf("TabScopedRoutes() missing %s", route)+ }+ }+}+func TestNoDuplicateRoutes(t *testing.T) {seen := make(map[string]bool)for _, ep := range Core() {diff --git a/internal/strategy/simple/simple_test.go b/internal/strategy/simple/simple_test.goindex 12b9b606..349016d5 100644--- a/internal/strategy/simple/simple_test.go+++ b/internal/strategy/simple/simple_test.go@@ -159,3 +159,31 @@ func TestStrategy_RegisterRoutes_RegistersConsoleAndErrorShorthands(t *testing.T})}}++func TestStrategy_RegisterRoutes_RegistersFrameShorthands(t *testing.T) {+ orch := orchestrator.NewOrchestratorWithRunner(t.TempDir(), &mockRunner{portAvail: true})+ orch.ApplyRuntimeConfig(&config.RuntimeConfig{})++ s := &Strategy{orch: orch}+ mux := http.NewServeMux()+ s.RegisterRoutes(mux)++ tests := []struct {+ method string+ path string+ route string+ }{+ {method: http.MethodGet, path: "/frame", route: "GET /frame"},+ {method: http.MethodPost, path: "/frame", route: "POST /frame"},+ }++ for _, tt := range tests {+ t.Run(tt.method+" "+tt.path, func(t *testing.T) {+ req := httptest.NewRequest(tt.method, tt.path, strings.NewReader(`{"target":"main"}`))+ _, pattern := mux.Handler(req)+ if pattern != tt.route {+ t.Fatalf("expected route %q, got %q", tt.route, pattern)+ }+ })+ }+}diff --git a/tests/benchmark/AGENT_TASKS.md b/tests/benchmark/AGENT_TASKS.mdindex 9aa9eed0..bd0ae8c4 100644--- a/tests/benchmark/AGENT_TASKS.md+++ b/tests/benchmark/AGENT_TASKS.md@@ -402,12 +402,12 @@ Download `http://fixtures/download-sample.txt` to a local file.## Group 19: iFrame### 19.1 Read iframe content-Navigate to `http://fixtures/iframe.html` and extract content from inside the embedded iframe.+Navigate to `http://fixtures/iframe.html` and extract content from inside the embedded same-origin iframe.**Verify**: The iframe's inner content includes `IFRAME_INNER_CONTENT_LOADED`.### 19.2 Type into iframe input-Inside the iframe, fill the input with the text "Hello World" and click the Save button.+Inside the same-origin iframe, fill the input with the text "Hello World" and click the Save button. If using selectors, set frame scope first.**Verify**: The iframe shows `IFRAME_INPUT_RECEIVED_HELLO_WORLD`.diff --git a/tests/e2e/fixtures/cross-origin-iframe-content.html b/tests/e2e/fixtures/cross-origin-iframe-content.htmlnew file mode 100644index 00000000..06bc5283--- /dev/null+++ b/tests/e2e/fixtures/cross-origin-iframe-content.html@@ -0,0 +1,20 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Cross Origin Iframe Content</title>+</head>+<body>+ <h2>Cross Origin Payment</h2>+ <label for="cross-origin-code">Cross-origin code</label>+ <input type="text" id="cross-origin-code" name="crossOriginCode">+ <button type="button" id="cross-origin-send">Cross-origin send</button>++ <script>+ document.getElementById('cross-origin-send').addEventListener('click', function() {+ const value = document.getElementById('cross-origin-code').value;+ parent.postMessage({ type: 'cross-origin-submit', value: value }, '*');+ });+ </script>+</body>+</html>diff --git a/tests/e2e/fixtures/cross-origin-iframe.html b/tests/e2e/fixtures/cross-origin-iframe.htmlnew file mode 100644index 00000000..043006f9--- /dev/null+++ b/tests/e2e/fixtures/cross-origin-iframe.html@@ -0,0 +1,28 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Cross Origin Iframe Fixture</title>+</head>+<body>+ <h1>Cross Origin Iframe Fixture</h1>+ <p id="cross-origin-status">CROSS_ORIGIN_READY</p>+ <iframe+ id="cross-origin-frame"+ title="cross-origin-frame"+ name="cross-origin-frame"+ src="http://pivot-target/cross-origin-iframe-content.html"+ width="640"+ height="260"+ ></iframe>++ <script>+ window.addEventListener('message', function(event) {+ const data = event.data || {};+ if (data.type === 'cross-origin-submit') {+ document.getElementById('cross-origin-status').textContent = 'CROSS_ORIGIN_SUBMITTED_' + data.value;+ }+ });+ </script>+</body>+</html>diff --git a/tests/e2e/fixtures/iframe-content.html b/tests/e2e/fixtures/iframe-content.htmlindex bce47a9a..7a36a07d 100644--- a/tests/e2e/fixtures/iframe-content.html+++ b/tests/e2e/fixtures/iframe-content.html@@ -3,17 +3,91 @@<head><meta charset="UTF-8"><title>Iframe Payment Content</title>+ <style>+ body {+ font-family: sans-serif;+ min-height: 1600px;+ margin: 0;+ padding: 16px;+ }++ form,+ .section {+ margin-bottom: 20px;+ }++ label,+ select,+ input,+ button {+ display: block;+ margin: 8px 0;+ }++ #hover-target {+ width: 220px;+ padding: 12px;+ border: 1px solid #999;+ background: #f5f5f5;+ }++ #spacer {+ height: 900px;+ }+ </style></head><body><h2>Payment</h2><form id="payment-form"><label for="card-number">Card number</label><input type="text" id="card-number" name="cardNumber">++ <label for="billing-country">Billing country</label>+ <select id="billing-country" name="billingCountry">+ <option value="">Select country</option>+ <option value="us">United States</option>+ <option value="uk">United Kingdom</option>+ <option value="de">Germany</option>+ </select>++ <label for="save-card">+ <input type="checkbox" id="save-card" name="saveCard">+ Save card for later+ </label>+<button type="button" id="pay-button">Pay</button></form>++ <div class="section">+ <button type="button" id="hover-target">Hover target</button>+ <p id="hover-result"></p>+ <p id="focus-result"></p>+ </div>++ <div id="spacer"></div>+ <button type="button" id="deep-target">Deep target</button>+ <p id="scroll-result"></p>+<p id="payment-result"></p><script>+ window.iframeFixtureState = {+ hoverCount: 0+ };++ document.addEventListener('focusin', function(event) {+ document.getElementById('focus-result').textContent = 'FOCUSED_' + event.target.id;+ });++ document.getElementById('hover-target').addEventListener('mouseenter', function() {+ window.iframeFixtureState.hoverCount += 1;+ document.getElementById('hover-result').textContent = 'HOVERED_' + window.iframeFixtureState.hoverCount;+ });++ document.getElementById('deep-target').addEventListener('click', function() {+ document.getElementById('scroll-result').textContent = 'DEEP_TARGET_CLICKED';+ });+document.getElementById('pay-button').addEventListener('click', function() {const value = document.getElementById('card-number').value;document.getElementById('payment-result').textContent = 'PAYMENT_SUBMITTED_' + value;diff --git a/tests/e2e/fixtures/iframe-rerender-v1.html b/tests/e2e/fixtures/iframe-rerender-v1.htmlnew file mode 100644index 00000000..db453810--- /dev/null+++ b/tests/e2e/fixtures/iframe-rerender-v1.html@@ -0,0 +1,12 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Iframe Rerender V1</title>+</head>+<body>+ <h2>Iframe Rerender V1</h2>+ <label for="legacy-field">Legacy field</label>+ <input type="text" id="legacy-field" name="legacyField">+</body>+</html>diff --git a/tests/e2e/fixtures/iframe-rerender-v2.html b/tests/e2e/fixtures/iframe-rerender-v2.htmlnew file mode 100644index 00000000..aabbd267--- /dev/null+++ b/tests/e2e/fixtures/iframe-rerender-v2.html@@ -0,0 +1,21 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Iframe Rerender V2</title>+</head>+<body>+ <h2>Iframe Rerender V2</h2>+ <label for="fresh-field">Fresh field</label>+ <input type="text" id="fresh-field" name="freshField">+ <button type="button" id="fresh-save">Fresh save</button>+ <p id="fresh-result"></p>++ <script>+ document.getElementById('fresh-save').addEventListener('click', function() {+ const value = document.getElementById('fresh-field').value;+ document.getElementById('fresh-result').textContent = 'FRESH_SAVED_' + value;+ });+ </script>+</body>+</html>diff --git a/tests/e2e/fixtures/iframe-rerender.html b/tests/e2e/fixtures/iframe-rerender.htmlnew file mode 100644index 00000000..5e3b7612--- /dev/null+++ b/tests/e2e/fixtures/iframe-rerender.html@@ -0,0 +1,39 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Iframe Rerender Fixture</title>+</head>+<body>+ <h1>Iframe Rerender Fixture</h1>+ <button type="button" id="replace-frame">Replace frame</button>+ <p id="rerender-status">RERENDER_V1</p>+ <iframe+ id="live-frame"+ title="live-frame"+ name="live-frame"+ src="iframe-rerender-v1.html"+ width="640"+ height="240"+ ></iframe>++ <script>+ window.replaceTestFrame = function() {+ const current = document.getElementById('live-frame');+ const next = document.createElement('iframe');+ next.id = 'live-frame';+ next.title = 'live-frame';+ next.name = 'live-frame';+ next.width = '640';+ next.height = '240';+ next.src = 'iframe-rerender-v2.html';+ current.replaceWith(next);+ document.getElementById('rerender-status').textContent = 'RERENDER_V2';+ };++ document.getElementById('replace-frame').addEventListener('click', function() {+ window.replaceTestFrame();+ });+ </script>+</body>+</html>diff --git a/tests/e2e/fixtures/nested-iframe-inner.html b/tests/e2e/fixtures/nested-iframe-inner.htmlnew file mode 100644index 00000000..260b068c--- /dev/null+++ b/tests/e2e/fixtures/nested-iframe-inner.html@@ -0,0 +1,28 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Inner Nested Frame</title>+</head>+<body>+ <h3>Inner Frame</h3>+ <label for="nested-code">Nested code</label>+ <input type="text" id="nested-code" name="nestedCode">++ <label for="nested-consent">+ <input type="checkbox" id="nested-consent" name="nestedConsent">+ Nested consent+ </label>++ <button type="button" id="nested-save">Nested save</button>+ <p id="nested-result"></p>++ <script>+ document.getElementById('nested-save').addEventListener('click', function() {+ const value = document.getElementById('nested-code').value;+ const checked = document.getElementById('nested-consent').checked;+ document.getElementById('nested-result').textContent = 'NESTED_SAVED_' + value + '_' + checked;+ });+ </script>+</body>+</html>diff --git a/tests/e2e/fixtures/nested-iframe-outer.html b/tests/e2e/fixtures/nested-iframe-outer.htmlnew file mode 100644index 00000000..bc27adf9--- /dev/null+++ b/tests/e2e/fixtures/nested-iframe-outer.html@@ -0,0 +1,19 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Outer Nested Frame</title>+</head>+<body>+ <h2>Outer Frame</h2>+ <p id="outer-frame-status">OUTER_FRAME_READY</p>+ <iframe+ id="inner-payment-frame"+ title="inner-payment-frame"+ name="inner-payment-frame"+ src="nested-iframe-inner.html"+ width="640"+ height="280"+ ></iframe>+</body>+</html>diff --git a/tests/e2e/fixtures/nested-iframe.html b/tests/e2e/fixtures/nested-iframe.htmlnew file mode 100644index 00000000..34fe1f0e--- /dev/null+++ b/tests/e2e/fixtures/nested-iframe.html@@ -0,0 +1,19 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Nested Iframe Fixture</title>+</head>+<body>+ <h1>Nested Iframe Fixture</h1>+ <p>This page contains an iframe that itself contains another iframe.</p>+ <iframe+ id="outer-frame"+ title="outer-frame"+ name="outer-frame"+ src="nested-iframe-outer.html"+ width="720"+ height="420"+ ></iframe>+</body>+</html>diff --git a/tests/e2e/fixtures/srcdoc-iframe.html b/tests/e2e/fixtures/srcdoc-iframe.htmlnew file mode 100644index 00000000..b67bc973--- /dev/null+++ b/tests/e2e/fixtures/srcdoc-iframe.html@@ -0,0 +1,39 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="UTF-8">+ <title>Srcdoc Iframe Fixture</title>+</head>+<body>+ <h1>Srcdoc Iframe Fixture</h1>+ <p>The iframe below is populated with <code>srcdoc</code>.</p>+ <iframe+ id="srcdoc-payment-frame"+ title="srcdoc-payment-frame"+ name="srcdoc-payment-frame"+ width="640"+ height="260"+ ></iframe>++ <script>+ document.getElementById('srcdoc-payment-frame').srcdoc = `+ <!DOCTYPE html>+ <html lang="en">+ <head>+ <meta charset="UTF-8">+ <title>Srcdoc Payment</title>+ </head>+ <body>+ <h2>Srcdoc Payment</h2>+ <label for="srcdoc-code">Srcdoc code</label>+ <input type="text" id="srcdoc-code" name="srcdocCode">+ <label for="srcdoc-optin">+ <input type="checkbox" id="srcdoc-optin" name="srcdocOptin">+ Srcdoc opt-in+ </label>+ </body>+ </html>+ `;+ </script>+</body>+</html>diff --git a/tests/e2e/helpers/api-assertions.sh b/tests/e2e/helpers/api-assertions.shindex b7dccddb..096e26fa 100644--- a/tests/e2e/helpers/api-assertions.sh+++ b/tests/e2e/helpers/api-assertions.sh@@ -91,6 +91,20 @@ assert_json_exists() {fi}+assert_json_not_exists() {+ local json="$1"+ local path="$2"+ local desc="${3:-$path does not exist}"++ if echo "$json" | jq -e "$path" >/dev/null 2>&1; then+ echo -e " ${RED}✗${NC} $desc (unexpected field found)"+ ((ASSERTIONS_FAILED++)) || true+ else+ echo -e " ${GREEN}✓${NC} $desc"+ ((ASSERTIONS_PASSED++)) || true+ fi+}+assert_contains() {local haystack="$1"local needle="$2"diff --git a/tests/e2e/helpers/base.sh b/tests/e2e/helpers/base.shindex fb98a8d8..ff43ced1 100644--- a/tests/e2e/helpers/base.sh+++ b/tests/e2e/helpers/base.sh@@ -161,6 +161,13 @@ find_ref_by_name() {echo "$json" | safe_jq -r "[.nodes[] | select(.name == \"$name\") | .ref] | first // empty"}+find_ref_by_role_and_name() {+ local role="$1"+ local name="$2"+ local json="${3:-$(_e2e_default_ref_json)}"+ echo "$json" | safe_jq -r "[.nodes[] | select(.role == \"$role\" and .name == \"$name\") | .ref] | first // empty"+}+assert_ref_found() {local ref="$1"local desc="${2:-ref}"diff --git a/tests/e2e/scenarios/api/actions-extended.sh b/tests/e2e/scenarios/api/actions-extended.shindex 8172add4..a2542d47 100644--- a/tests/e2e/scenarios/api/actions-extended.sh+++ b/tests/e2e/scenarios/api/actions-extended.sh@@ -195,6 +195,210 @@ require_ref "button" "Pay" PAY_REF && {end_test+# ─────────────────────────────────────────────────────────────────+start_test "iframe: frame-scoped selectors support focus hover select check scroll and click"++navigate_fixture "iframe.html"+fresh_snapshot++pt_get "/snapshot?filter=interactive&selector=%23card-number"+assert_not_ok "unscoped snapshot selector stays in main frame"++pt_post /frame -d '{"target":"#payment-frame"}'+assert_ok "set frame scope from iframe selector"+assert_json_eq "$RESULT" '.scoped' 'true' "frame scope enabled"++pt_get "/snapshot?filter=interactive"+assert_ok "frame-scoped snapshot"+assert_json_exists "$RESULT" '.nodes[] | select(.name == "Card number")' "frame snapshot includes card field"+assert_json_exists "$RESULT" '.nodes[] | select(.name == "Billing country")' "frame snapshot includes select"+assert_json_exists "$RESULT" '.nodes[] | select(.name == "Save card for later")' "frame snapshot includes checkbox"++pt_post /action -d '{"kind":"focus","selector":"#card-number"}'+assert_ok "focus selector inside frame"+pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"payment-frame\"); const doc = frame && frame.contentDocument; return doc && doc.activeElement ? doc.activeElement.id : \"\"; })()"}'+assert_ok "evaluate active element in iframe"+assert_json_eq "$RESULT" '.result' 'card-number' "focus targeted iframe input"++pt_post /action -d '{"kind":"type","selector":"#card-number","text":"5555444433331111"}'+assert_ok "type selector inside frame"+pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"payment-frame\"); const doc = frame && frame.contentDocument; const input = doc && doc.getElementById(\"card-number\"); return input ? input.value : \"\"; })()"}'+assert_ok "evaluate typed card number"+assert_json_eq "$RESULT" '.result' '5555444433331111' "type persisted in iframe input"++pt_post /action -d '{"kind":"hover","selector":"#hover-target"}'+assert_ok "hover selector inside frame"+pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"payment-frame\"); const doc = frame && frame.contentDocument; const result = doc && doc.getElementById(\"hover-result\"); return result ? result.textContent : \"\"; })()"}'+assert_ok "evaluate hover result"+assert_json_eq "$RESULT" '.result' 'HOVERED_1' "hover handler fired inside iframe"++pt_post /action -d '{"kind":"select","selector":"#billing-country","value":"uk"}'+assert_ok "select option inside frame"+pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"payment-frame\"); const doc = frame && frame.contentDocument; const select = doc && doc.getElementById(\"billing-country\"); return select ? select.value : \"\"; })()"}'+assert_ok "evaluate selected country"+assert_json_eq "$RESULT" '.result' 'uk' "select updated iframe dropdown"++pt_post /action -d '{"kind":"check","selector":"#save-card"}'+assert_ok "check checkbox inside frame"+pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"payment-frame\"); const doc = frame && frame.contentDocument; const checkbox = doc && doc.getElementById(\"save-card\"); return checkbox ? checkbox.checked : false; })()"}'+assert_ok "evaluate checked state in iframe"+assert_json_eq "$RESULT" '.result' 'true' "checkbox checked inside iframe"++pt_post /action -d '{"kind":"uncheck","selector":"#save-card"}'+assert_ok "uncheck checkbox inside frame"+pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"payment-frame\"); const doc = frame && frame.contentDocument; const checkbox = doc && doc.getElementById(\"save-card\"); return checkbox ? checkbox.checked : true; })()"}'+assert_ok "evaluate unchecked state in iframe"+assert_json_eq "$RESULT" '.result' 'false' "checkbox unchecked inside iframe"++pt_post /action -d '{"kind":"scrollintoview","selector":"#deep-target"}'+assert_ok "scrollintoview selector inside frame"+pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"payment-frame\"); const doc = frame && frame.contentDocument; const scrolling = doc && doc.scrollingElement; return scrolling ? scrolling.scrollTop > 0 : false; })()"}'+assert_ok "evaluate iframe scroll position"+assert_json_eq "$RESULT" '.result' 'true' "scrollintoview scrolled iframe document"++pt_post /action -d '{"kind":"click","selector":"#deep-target"}'+assert_ok "click selector inside frame after scroll"+pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"payment-frame\"); const doc = frame && frame.contentDocument; const result = doc && doc.getElementById(\"scroll-result\"); return result ? result.textContent : \"\"; })()"}'+assert_ok "evaluate deep target click result"+assert_json_eq "$RESULT" '.result' 'DEEP_TARGET_CLICKED' "click worked inside frame scope"++pt_post /frame -d '{"target":"main"}'+assert_ok "reset frame scope to main"+assert_json_eq "$RESULT" '.scoped' 'false' "frame scope cleared"++pt_get "/snapshot?filter=interactive&selector=%23card-number"+assert_not_ok "selector stops reaching iframe after frame reset"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "iframe: nested frames require explicit frame hops"++navigate_fixture "nested-iframe.html"+fresh_snapshot++pt_get "/snapshot?filter=interactive&selector=%23nested-code"+assert_not_ok "nested selector blocked from main frame"++pt_post /frame -d '{"target":"#outer-frame"}'+assert_ok "set outer frame scope"+assert_json_eq "$RESULT" '.scoped' 'true' "outer frame scope enabled"++pt_post /action -d '{"kind":"focus","selector":"#nested-code"}'+assert_not_ok "inner selector still blocked from outer frame"++pt_post /frame -d '{"target":"#inner-payment-frame"}'+assert_ok "set inner frame scope from outer frame"+assert_json_eq "$RESULT" '.frame.frameName' 'inner-payment-frame' "inner frame selected"++pt_post /action -d '{"kind":"type","selector":"#nested-code","text":"nested-123"}'+assert_ok "type inside nested inner frame"++pt_post /action -d '{"kind":"check","selector":"#nested-consent"}'+assert_ok "check checkbox inside nested inner frame"++pt_post /action -d '{"kind":"click","selector":"#nested-save"}'+assert_ok "click inside nested inner frame"++pt_post /evaluate -d '{"expression":"(() => { const outer = document.getElementById(\"outer-frame\"); const outerDoc = outer && outer.contentDocument; const inner = outerDoc && outerDoc.getElementById(\"inner-payment-frame\"); const innerDoc = inner && inner.contentDocument; const result = innerDoc && innerDoc.getElementById(\"nested-result\"); return result ? result.textContent : \"\"; })()"}'+assert_ok "evaluate nested iframe result"+assert_json_eq "$RESULT" '.result' 'NESTED_SAVED_nested-123_true' "nested frame actions succeeded"++pt_post /frame -d '{"target":"main"}'+assert_ok "reset nested frame scope to main"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "iframe: srcdoc frame-scoped selectors work"++navigate_fixture "srcdoc-iframe.html"+sleep 1+fresh_snapshot++pt_post /frame -d '{"target":"#srcdoc-payment-frame"}'+assert_ok "set srcdoc frame scope"+assert_json_eq "$RESULT" '.scoped' 'true' "srcdoc frame scope enabled"++pt_get "/snapshot?filter=interactive"+assert_ok "srcdoc frame-scoped snapshot"+assert_json_exists "$RESULT" '.nodes[] | select(.name == "Srcdoc code")' "srcdoc snapshot includes textbox"+assert_json_exists "$RESULT" '.nodes[] | select(.name | test("Srcdoc opt-in"))' "srcdoc snapshot includes checkbox"++pt_post /action -d '{"kind":"focus","selector":"#srcdoc-code"}'+assert_ok "focus selector inside srcdoc frame"++pt_post /action -d '{"kind":"type","selector":"#srcdoc-code","text":"srcdoc-321"}'+assert_ok "type selector inside srcdoc frame"++pt_post /action -d '{"kind":"check","selector":"#srcdoc-optin"}'+assert_ok "check selector inside srcdoc frame"++pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"srcdoc-payment-frame\"); const doc = frame && frame.contentDocument; const input = doc && doc.getElementById(\"srcdoc-code\"); const checkbox = doc && doc.getElementById(\"srcdoc-optin\"); const active = doc && doc.activeElement; return { value: input ? input.value : \"\", checked: checkbox ? checkbox.checked : false, active: active ? active.id : \"\" }; })()"}'+assert_ok "evaluate srcdoc iframe state"+assert_json_eq "$RESULT" '.result.value' 'srcdoc-321' "srcdoc input updated"+assert_json_eq "$RESULT" '.result.checked' 'true' "srcdoc checkbox updated"++pt_post /frame -d '{"target":"main"}'+assert_ok "reset srcdoc frame scope to main"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "iframe: stale refs after rerender require a fresh snapshot"++navigate_fixture "iframe-rerender.html"+fresh_snapshot++require_ref "textbox" "Legacy field" LEGACY_REF && {+ pt_post /evaluate -d '{"expression":"window.replaceTestFrame()"}'+ assert_ok "trigger iframe rerender"++ sleep 1++ pt_post /action -d "{\"kind\":\"fill\",\"ref\":\"${LEGACY_REF}\",\"text\":\"stale\"}"+ assert_not_ok "stale iframe ref rejected after rerender"++ fresh_snapshot+ assert_json_not_exists "$RESULT" '.nodes[] | select(.name == "Legacy field")' "legacy field removed after rerender"++ require_ref "textbox" "Fresh field" FRESH_REF && \+ require_ref "button" "Fresh save" FRESH_SAVE_REF && {+ pt_post /action -d "{\"kind\":\"fill\",\"ref\":\"${FRESH_REF}\",\"text\":\"fresh-456\"}"+ assert_ok "fresh iframe ref works after resnapshot"++ pt_post /action -d "{\"kind\":\"click\",\"ref\":\"${FRESH_SAVE_REF}\"}"+ assert_ok "fresh iframe button click works after resnapshot"++ pt_post /evaluate -d '{"expression":"(() => { const frame = document.getElementById(\"live-frame\"); const doc = frame && frame.contentDocument; const result = doc && doc.getElementById(\"fresh-result\"); return result ? result.textContent : \"\"; })()"}'+ assert_ok "evaluate rerendered iframe result"+ assert_json_eq "$RESULT" '.result' 'FRESH_SAVED_fresh-456' "fresh refs work after rerender"+ }+}++end_test++# ─────────────────────────────────────────────────────────────────+start_test "iframe: cross-origin selector scope is not claimed as supported"++navigate_fixture "cross-origin-iframe.html"+sleep 1+fresh_snapshot++pt_post /frame -d '{"target":"#cross-origin-frame"}'+assert_not_ok "cross-origin frame selection is currently unsupported"++pt_get "/snapshot?filter=interactive"+assert_ok "cross-origin frame-scoped snapshot"+assert_json_exists "$RESULT" '.nodes[] | select(.name == "cross-origin-frame")' "cross-origin snapshot keeps iframe owner only"+assert_json_not_exists "$RESULT" '.nodes[] | select(.name == "Cross-origin code")' "cross-origin snapshot does not inline input descendants"+assert_json_not_exists "$RESULT" '.nodes[] | select(.name == "Cross-origin send")' "cross-origin snapshot does not inline button descendants"++pt_post /action -d '{"kind":"type","selector":"#cross-origin-code","text":"424242"}'+assert_not_ok "unscoped selector cannot type into cross-origin iframe"++end_test+# Regression test for GitHub issue #236: press action was typing key names# as literal text instead of dispatching keyboard events.diff --git a/tests/e2e/scenarios/cli/actions-basic.sh b/tests/e2e/scenarios/cli/actions-basic.shindex 4a76c788..459d4608 100644--- a/tests/e2e/scenarios/cli/actions-basic.sh+++ b/tests/e2e/scenarios/cli/actions-basic.sh@@ -147,9 +147,9 @@ end_teststart_test "pinchtab focus <ref>"pt_ok nav "${FIXTURES_URL}/form.html"-pt_ok snap+pt_ok snap --interactive-USERNAME_REF=$(find_ref_by_name "Username:" "$PT_OUT")+USERNAME_REF=$(find_ref_by_role_and_name "textbox" "Username:" "$PT_OUT")if assert_ref_found "$USERNAME_REF" "username input ref"; thenpt_ok focus "$USERNAME_REF"assert_output_contains "focused" "confirms focus action"diff --git a/tests/e2e/scenarios/cli/actions-extended.sh b/tests/e2e/scenarios/cli/actions-extended.shindex 8481e934..49f1c529 100644--- a/tests/e2e/scenarios/cli/actions-extended.sh+++ b/tests/e2e/scenarios/cli/actions-extended.sh@@ -8,9 +8,9 @@ source "${GROUP_DIR}/../../helpers/cli.sh"start_test "pinchtab type <ref> <text>"pt_ok nav "${FIXTURES_URL}/form.html"-pt_ok snap+pt_ok snap --interactive-USERNAME_REF=$(find_ref_by_name "Username:" "$PT_OUT")+USERNAME_REF=$(find_ref_by_role_and_name "textbox" "Username:" "$PT_OUT")if assert_ref_found "$USERNAME_REF" "username input ref"; thenpt_ok type "$USERNAME_REF" "typed-via-ref"assert_output_contains "typed" "confirms text was typed"@@ -53,9 +53,9 @@ end_teststart_test "pinchtab hover (basic)"pt_ok nav "${FIXTURES_URL}/form.html"-pt_ok snap+pt_ok snap --interactive-HOVER_REF=$(find_ref_by_name "Username:" "$PT_OUT")+HOVER_REF=$(find_ref_by_role_and_name "textbox" "Username:" "$PT_OUT")if assert_ref_found "$HOVER_REF" "username input ref"; thenpt_ok hover "$HOVER_REF"fi