Skip to content

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.go
index 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.go
index 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.md
index 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 document
pinchtab click [selector] # Click an element or coordinates with --x/--y
pinchtab click --css <selector> # Force CSS selector mode
pinchtab click --wait-nav <selector> # Click and wait for navigation
@@ -117,6 +122,8 @@ pinchtab find --ref-only # Print only the best ref
pinchtab 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
```bash
diff --git a/docs/endpoints.md b/docs/endpoints.md
index b59f5eae..ebcc261a 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -130,6 +130,10 @@ POST /tabs/{id}/action
POST /tabs/{id}/actions
POST /wait
POST /tabs/{id}/wait
+GET /frame
+POST /frame
+GET /tabs/{id}/frame
+POST /tabs/{id}/frame
GET /snapshot
GET /tabs/{id}/snapshot
GET /text
@@ -140,6 +144,8 @@ POST /evaluate
POST /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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
new file mode 100644
index 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.md
index 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.md
index 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.md
index 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.md
index de6b642c..b276ce32 100644
--- a/docs/reference/select.md
+++ b/docs/reference/select.md
@@ -19,7 +19,10 @@ pinchtab select e12 it
The `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.md
index 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`.
```bash
curl "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.md
index 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.go
index 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 = nid
return 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 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)
+ 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 = nid
return 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, refCache
return 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, refCache
return 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.go
index 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.Context
AllocCancel context.CancelFunc
diff --git a/internal/bridge/bridge_test.go b/internal/bridge/bridge_test.go
index 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.go
index 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.RawMessage
if 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 = v
diff --git a/internal/bridge/observe_facade.go b/internal/bridge/observe_facade.go
index 8d9217d3..1d8cf9ed 100644
--- a/internal/bridge/observe_facade.go
+++ b/internal/bridge/observe_facade.go
@@ -18,6 +18,7 @@ type RawAXNode = bridgeobserve.RawAXNode
type RawAXValue = bridgeobserve.RawAXValue
type RawAXProp = bridgeobserve.RawAXProp
type RawFrame = bridgeobserve.RawFrame
+type RawFrameTree = bridgeobserve.RawFrameTree
type rawFrameTree = bridgeobserve.RawFrameTree
type NetworkEntry = bridgeobserve.NetworkEntry
@@ -26,14 +27,22 @@ type NetworkFilter = bridgeobserve.NetworkFilter
type NetworkMonitor = bridgeobserve.NetworkMonitor
type 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.go
index 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.go
index 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]*TabEntry
accessed map[string]bool
snapshots map[string]*RefCache
+ frameScope map[string]FrameScope
onTabSetup TabSetupFunc
dialogMgr *DialogManager
logStore *ConsoleLogStore
@@ -53,6 +54,7 @@ func NewTabManager(browserCtx context.Context, cfg *config.RuntimeConfig, idMgr
tabs: 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.go
new file mode 100644
index 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.go
index 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 = nid
req.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, re
action.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 {
break
diff --git a/internal/handlers/frame.go b/internal/handlers/frame.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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.go
index 75c07603..ed901a61 100644
--- a/internal/handlers/handlers_test.go
+++ b/internal/handlers/handlers_test.go
@@ -24,6 +24,7 @@ type mockBridge struct {
lastConsoleLimit int
lastErrorLimit int
fingerprintTabs 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 co
return 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.md
index 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.html
new file mode 100644
index 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.html
new file mode 100644
index 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.html
index 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.html
new file mode 100644
index 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.html
new file mode 100644
index 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.html
new file mode 100644
index 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.html
new file mode 100644
index 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.html
new file mode 100644
index 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.html
new file mode 100644
index 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.html
new file mode 100644
index 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.sh
index 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.sh
index 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.sh
index 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.sh
index 4a76c788..459d4608 100644
--- a/tests/e2e/scenarios/cli/actions-basic.sh
+++ b/tests/e2e/scenarios/cli/actions-basic.sh
@@ -147,9 +147,9 @@ end_test
start_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"; then
pt_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.sh
index 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"; then
pt_ok type "$USERNAME_REF" "typed-via-ref"
assert_output_contains "typed" "confirms text was typed"
@@ -53,9 +53,9 @@ end_test
start_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"; then
pt_ok hover "$HOVER_REF"
fi