docs(interaction-skills): flesh out cross-origin-iframes.md

[shashwatgokhe]

Hey, first time contributing here so be gentle.

I noticed interaction-skills/cross-origin-iframes.md was a one-line scaffold and I had just been bitten by exactly this scenario, so I tried filling it in.

I was driving a web IDE that runs inside a cross-origin iframe and kept hitting the same wall: clicks worked fine, but anything I "typed" seemed to vanish or land in the parent page. After reading helpers.py I figured out what was actually going on — coordinate clicks pass through the iframe boundary because the hit-test happens in Chrome itself, but type_text / press_key only go where focus already is, and focus inside the iframe is a separate thing you have to set first (either by clicking into it or by focusing through its own CDP target).

So this PR rewrites that file with what I wish it had said when I started:

• coordinate clicks just work, that's the default
• when you actually need DOM access, use iframe_target("...") plus js(..., target_id=...)
• for typing, click first or focus first, then type
• a small list of the gotchas I hit (contentDocument throwing, target IDs changing after navigation, nested iframes being separate targets, sandboxed iframes needing a real click)
• a tiny "what do I want to do → use this" table at the bottom

It's all docs, no code touched. I tried to match the tone and density of the other interaction-skills files. Happy to take feedback / cut things / split it up if anything feels off.

---

Summary by cubic

Expanded interaction-skills/cross-origin-iframes.md with clear guidance for interacting with cross-origin iframes. Covers coordinate clicks that pass through, using iframe_target(...) with js(target_id=...) for DOM access, typing workflows that require focus inside the iframe, and key pitfalls (loading, nested targets, navigation, sandbox).

^{Written for commit 8029799. Summary will update on new commits.}

[browser-harness-review]

✅ Skill review passed

Reviewed 1 file(s) — no findings.

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="interaction-skills/cross-origin-iframes.md">

<violation number="1" location="interaction-skills/cross-origin-iframes.md:55">
P2: The recommended polling loop can run forever if the iframe never appears; add a timeout/deadline or use a bounded wait helper.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

P2: The recommended polling loop can run forever if the iframe never appears; add a timeout/deadline or use a bounded wait helper.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At interaction-skills/cross-origin-iframes.md, line 55:

<comment>The recommended polling loop can run forever if the iframe never appears; add a timeout/deadline or use a bounded wait helper.</comment>

<file context>
@@ -1,3 +1,69 @@
+## Pitfalls
+
+- `js("document.querySelectorAll('iframe')")` from the parent only sees the iframe **element**, not the document inside it. `querySelector(...).contentDocument` throws on cross-origin. Use `iframe_target()` instead.
+- `iframe_target()` can return `None` if the iframe is still loading. Either `wait_for_load()` first or poll: `while iframe_target("...") is None: wait(0.5)`.
+- A page can have nested cross-origin iframes (iframe-in-iframe). Each is its own CDP target — `iframe_target()` matches by URL substring, so use a path fragment specific to the inner one.
+- After a navigation inside the iframe, the target ID changes. Re-fetch with `iframe_target()` rather than caching it across navigations.
</file context>