docs: add cross-origin iframe guidance (CDP WebSocket path) to forge references

[Wadehl]

Background

During real-world use of browser-act-skill-forge, a gap was encountered: when the target data is rendered inside a cross-origin iframe, the forge references provided no guidance. The eval command is blocked by the browser's same-origin policy, and without a documented fallback, exploration stalls with no clear next step.

Root Cause

The exploration and output references only cover same-origin scenarios. Cross-origin iframes create a hard split in browser-act's command set:

• state and click work — OS-level accessibility, not subject to same-origin policy
• eval is blocked at the JS layer

This split was not documented, leaving the forge without a defined path for this case.

Verified Solution

Chrome DevTools Protocol (CDP) exposes every frame — including cross-origin iframes — as an independent debugging target listed at http://localhost:9222/json. By connecting directly to the iframe's webSocketDebuggerUrl via the Python websockets library, arbitrary JS can be executed inside the iframe without touching the browser's same-origin enforcement. This was validated end-to-end: virtual scroll triggering, DOM querying, and structured data extraction all work through this path.

Changes

references/exploration_extraction.md

• Added a "Cross-Origin iframe" section after DOM Extraction
• Documents the browser-act capability boundary (state/click ok, eval blocked)
• Provides the CDP WebSocket direct-connect pattern with Python code examples
• Defines the decision rule: use state+click when the a11y tree is sufficient; use CDP when JS execution inside the iframe is required
• Specifies that CDP path scripts are encapsulated as standalone .py files and labeled CDP Direct in the generated Skill

references/output_template.md

• Added CDP Direct as a new named component type under Capability Components
• Provides SKILL.md template block for this type (invocation pattern, output example, error handling)
• Added corresponding Python wrapper template showing the CDP connection pattern (prints result directly, no eval "$(...)" wrapping)
• Extended Filling Specification 增加 Intel Mac wheel 或提供源码分发 #17 to define when the CDP Direct label applies

Design Rationale

The CDP path is Python-native: the WebSocket connection must live in Python, so the script cannot follow the standard "print JS string → eval" contract. Making this a distinct labeled type prevents misuse and keeps the eval "$(...)" wrapper convention unambiguous for all other component types.

[browseract-ai]

Thanks for identifying and documenting this scenario. Cross-origin iframe access is now supported natively by the BrowserAct
CLI through frame-scoped execution:

browser-act --session eval
--scope 'frame:iframe#target'
'/* query DOM, trigger scrolling, or extract structured data */'

The CLI resolves the iframe selector to a concrete frame ID. BrowserAct Core then maps that frame to its owning CDP target
and session—including cross-origin OOPIF targets—and executes Runtime.evaluate directly in the iframe’s execution context.
Scoped element commands such as eval-el, click, input, and get text use the same routing mechanism.

For that reason, we do not plan to merge the proposed CDP Direct approach as written. The documentation could instead be
updated to recommend eval --scope frame:...; otherwise, we can close this PR as superseded by the native frame-scoping
support.

Thanks again for reporting the original usability gap.