diff --git a/docs/en/deep-dive/architecture/tab-domain.md b/docs/en/deep-dive/architecture/tab-domain.md
index 474c1574..d444fac1 100644
--- a/docs/en/deep-dive/architecture/tab-domain.md
+++ b/docs/en/deep-dive/architecture/tab-domain.md
@@ -222,7 +222,7 @@ except KeyError:
     raise TopLevelTargetRequired(...)  # Guide users to WebElement.take_screenshot()
 ```
 
-**Design implication:** IFrame tabs (created via `get_frame()`) inherit all Tab methods but screenshots fail by design. Alternative: `WebElement.take_screenshot()` works for iframe content.
+**Design implication:** Historically, Pydoll created dedicated Tab instances for iframes. The new model keeps iframe interaction inside `WebElement`, so screenshots and other helpers should target elements within the frame (for example, `await iframe_element.find(...).take_screenshot()`).
 
 **PDF Generation:** `Page.printToPDF` returns base64-encoded data. Pydoll abstracts file I/O, but underlying data is always base64 (CDP spec).
 
diff --git a/docs/en/deep-dive/fundamentals/iframes-and-contexts.md b/docs/en/deep-dive/fundamentals/iframes-and-contexts.md
new file mode 100644
index 00000000..cf81673a
--- /dev/null
+++ b/docs/en/deep-dive/fundamentals/iframes-and-contexts.md
@@ -0,0 +1,1292 @@
+# Iframes, OOPIFs and Execution Contexts (Deep Dive)
+
+Understanding how browser automation handles iframes is critical for building robust automation tools. This comprehensive guide explores the technical foundations of iframe handling in Pydoll, covering the Document Object Model (DOM), Chrome DevTools Protocol (CDP) mechanics, execution contexts, isolated worlds, and the sophisticated resolution pipeline that makes iframe interaction seamless.
+
+!!! info "Practical usage first"
+    If you just need to use iframes in your automation scripts, start with the feature guide: **Features → Automation → IFrames**.  
+    This deep dive explains the architectural decisions, protocol nuances, and internal implementation details.
+
+---
+
+## Table of Contents
+
+1. [Foundation: The Document Object Model (DOM)](#foundation-the-document-object-model-dom)
+2. [What are Iframes and Why They Matter](#what-are-iframes-and-why-they-matter)
+3. [The Challenge: Out-of-Process Iframes (OOPIFs)](#the-challenge-out-of-process-iframes-oopifs)
+4. [Chrome DevTools Protocol and Frame Management](#chrome-devtools-protocol-and-frame-management)
+5. [Execution Contexts and Isolated Worlds](#execution-contexts-and-isolated-worlds)
+6. [CDP Identifiers Reference](#cdp-identifiers-reference)
+7. [Pydoll's Resolution Pipeline](#pydolls-resolution-pipeline)
+8. [Session Routing and Flattened Mode](#session-routing-and-flattened-mode)
+9. [Implementation Deep Dive](#implementation-deep-dive)
+10. [Performance Considerations](#performance-considerations)
+11. [Failure Modes and Debugging](#failure-modes-and-debugging)
+
+---
+
+## Foundation: The Document Object Model (DOM)
+
+Before diving into iframes, we must understand the DOM—the tree structure that represents an HTML document in memory.
+
+### What is the DOM?
+
+The **Document Object Model** is a programming interface for HTML and XML documents. It represents the page structure as a tree of nodes, where each node corresponds to a part of the document:
+
+- **Element nodes**: HTML tags like `<div>`, `<iframe>`, `<button>`
+- **Text nodes**: The actual text content
+- **Attribute nodes**: Element attributes like `id`, `class`, `src`
+- **Document node**: The root of the tree
+
+```mermaid
+graph TD
+    Document[Document] --> HTML[html element]
+    HTML --> Head[head element]
+    HTML --> Body[body element]
+    Body --> Div1[div element]
+    Body --> Div2[div element]
+    Div1 --> Text1[text node: 'Hello']
+    Div2 --> Iframe[iframe element]
+    Iframe --> IframeDoc[iframe's document]
+    IframeDoc --> IframeBody[iframe body]
+    IframeBody --> IframeContent[iframe content...]
+```
+
+### DOM Tree Properties
+
+1. **Hierarchical structure**: Every node has a parent (except Document) and can have children
+2. **Node identification**: Nodes can be identified by:
+   - `nodeId`: Internal identifier within a document context (DOM domain)
+   - `backendNodeId`: Stable identifier that can reference nodes across different documents
+3. **Live representation**: Changes to the DOM are reflected immediately in the tree
+
+### Why This Matters for Iframes
+
+Each `<iframe>` element creates a **new, independent DOM tree**. The iframe element itself exists in the parent's DOM, but the content loaded into the iframe has its own complete Document node and tree structure. This separation is the foundation of all iframe complexity.
+
+---
+
+## What are Iframes and Why They Matter
+
+### Definition
+
+An **iframe** (inline frame) is an HTML element (`<iframe>`) that embeds another HTML document within the current page. The embedded document maintains its own context, including:
+
+- Independent HTML structure and DOM tree
+- Separate JavaScript execution environment
+- Its own CSS styling (unless explicitly shared)
+- Distinct navigation history
+
+```html
+<body>
+  <h1>Parent Page</h1>
+  <iframe src="https://example.com/embedded.html" id="content-frame"></iframe>
+  <p>More parent content</p>
+</body>
+```
+
+### Common Use Cases
+
+| Use Case | Description | Example |
+|----------|-------------|---------|
+| **Third-party widgets** | Embed external content safely | Payment forms, social media feeds, chat widgets |
+| **Content isolation** | Sandbox untrusted content | User-generated HTML, advertisements |
+| **Modular architecture** | Reusable components | Dashboard widgets, plugin systems |
+| **Cross-origin content** | Load resources from different domains | Maps, video players, analytics dashboards |
+
+### Security Model: Same-Origin Policy
+
+The browser enforces a **Same-Origin Policy** for iframes:
+
+- **Same-origin iframes**: Parent can access iframe's DOM via JavaScript (`iframe.contentDocument`)
+- **Cross-origin iframes**: Parent cannot access iframe's DOM directly (security restriction)
+
+This security boundary is why automation tools need special mechanisms (like CDP) to interact with iframe content.
+
+!!! warning "Important for automation"
+    Traditional JavaScript-based automation (like Selenium's early approaches) cannot directly access cross-origin iframe content due to browser security. CDP operates at a lower level, bypassing this limitation for debugging purposes.
+
+---
+
+## The Challenge: Out-of-Process Iframes (OOPIFs)
+
+### What are OOPIFs?
+
+Modern Chromium uses **site isolation** for security and stability. This means different origins may be rendered in separate OS processes. An iframe from a different origin becomes an **Out-of-Process Iframe (OOPIF)**.
+
+```mermaid
+graph LR
+    subgraph "Process 1: example.com"
+        MainPage[Main Page DOM]
+    end
+    
+    subgraph "Process 2: widget.com"
+        IframeDOM[Iframe DOM]
+    end
+    
+    MainPage -.Process boundary.-> IframeDOM
+```
+
+### Why OOPIFs Complicate Automation
+
+| Aspect | In-Process Iframe | Out-of-Process Iframe (OOPIF) |
+|--------|-------------------|-------------------------------|
+| **DOM access** | Shared document tree in memory | Separate target with own document |
+| **Command routing** | Single connection | Requires target attachment and session routing |
+| **Frame tree** | All frames in one tree | Root frame + separate targets for OOPIFs |
+| **JavaScript context** | Same execution context | Different execution context per process |
+| **CDP communication** | Direct commands | Commands must include `sessionId` |
+
+### The Traditional Approach (Manual Context Switching)
+
+Without sophisticated handling, automating OOPIFs requires:
+
+```python
+# Traditional (manual) approach with other tools
+main_page = browser.get_page()
+iframe_element = main_page.find_element_by_id("iframe-id")
+
+# Must manually switch context
+driver.switch_to.frame(iframe_element)
+
+# Now commands target the iframe
+button = driver.find_element_by_id("button-in-iframe")
+button.click()
+
+# Must manually switch back
+driver.switch_to.default_content()
+```
+
+**Problems with this approach:**
+
+1. **Developer burden**: Every iframe requires explicit context management
+2. **Nested iframes**: Each level needs another switch
+3. **OOPIF detection**: Hard to know when manual attachment is needed
+4. **Error-prone**: Forget to switch back → subsequent commands fail
+5. **Not composable**: Helper functions must know their iframe context
+
+### Pydoll's Solution: Transparent Context Resolution
+
+Pydoll eliminates manual context switching by resolving iframe contexts automatically:
+
+```python
+# Pydoll approach (no manual switching)
+iframe = await tab.find(id="iframe-id")
+button = await iframe.find(id="button-in-iframe")
+await button.click()
+
+# Nested iframes? Same pattern
+outer = await tab.find(id="outer-iframe")
+inner = await outer.find(tag_name="iframe")
+button = await inner.find(text="Submit")
+await button.click()
+```
+
+The complexity is handled internally. Let's explore how.
+
+---
+
+## Chrome DevTools Protocol and Frame Management
+
+As discussed in [Deep Dive → Fundamentals → Chrome DevTools Protocol](./cdp.md), CDP provides comprehensive browser control via WebSocket communication. Frame management is spread across multiple CDP domains.
+
+### Relevant CDP Domains
+
+#### 1. **Page Domain**
+
+Manages page lifecycle, frames, and navigation.
+
+**Key methods:**
+
+- `Page.getFrameTree()`: Returns the hierarchical structure of all frames in a page
+  ```json
+  {
+    "frameTree": {
+      "frame": {
+        "id": "main-frame-id",
+        "url": "https://example.com",
+        "securityOrigin": "https://example.com",
+        "mimeType": "text/html"
+      },
+      "childFrames": [
+        {
+          "frame": {
+            "id": "child-frame-id",
+            "parentId": "main-frame-id",
+            "url": "https://widget.com/embed"
+          }
+        }
+      ]
+    }
+  }
+  ```
+
+- `Page.createIsolatedWorld(frameId, worldName)`: Creates a new JavaScript execution context in a specific frame
+  ```json
+  {
+    "executionContextId": 42
+  }
+  ```
+
+**Pydoll usage:** 
+
+```python
+# From pydoll/elements/web_element.py
+@staticmethod
+async def _get_frame_tree_for(
+    handler: ConnectionHandler, session_id: Optional[str]
+) -> FrameTree:
+    """Get the Page frame tree for the given connection/target."""
+    command = PageCommands.get_frame_tree()
+    if session_id:
+        command['sessionId'] = session_id
+    response: GetFrameTreeResponse = await handler.execute_command(command)
+    return response['result']['frameTree']
+```
+
+#### 2. **DOM Domain**
+
+Provides access to the DOM structure.
+
+**Key methods:**
+
+- `DOM.describeNode(objectId)`: Returns detailed information about a DOM node
+  ```json
+  {
+    "node": {
+      "nodeId": 123,
+      "backendNodeId": 456,
+      "nodeName": "IFRAME",
+      "frameId": "parent-frame-id",
+      "contentDocument": {
+        "frameId": "iframe-frame-id",
+        "documentURL": "https://embedded.com/page.html"
+      }
+    }
+  }
+  ```
+
+- `DOM.getFrameOwner(frameId)`: Returns the `backendNodeId` of the `<iframe>` element that owns a frame
+  ```json
+  {
+    "backendNodeId": 456
+  }
+  ```
+
+**Pydoll usage:**
+
+```python
+# From pydoll/elements/web_element.py
+@staticmethod
+async def _owner_backend_for(
+    handler: ConnectionHandler, session_id: Optional[str], frame_id: str
+) -> Optional[int]:
+    """Get the backendNodeId of the DOM element that owns the given frame."""
+    command = DomCommands.get_frame_owner(frame_id=frame_id)
+    if session_id:
+        command['sessionId'] = session_id
+    response: GetFrameOwnerResponse = await handler.execute_command(command)
+    return response.get('result', {}).get('backendNodeId')
+```
+
+#### 3. **Target Domain**
+
+Manages browser targets (pages, iframes, workers, etc.).
+
+**Key methods:**
+
+- `Target.getTargets()`: Lists all available targets
+  ```json
+  {
+    "targetInfos": [
+      {
+        "targetId": "page-target-id",
+        "type": "page",
+        "title": "Main Page",
+        "url": "https://example.com"
+      },
+      {
+        "targetId": "iframe-target-id",
+        "type": "iframe",
+        "title": "",
+        "url": "https://widget.com/embed",
+        "parentFrameId": "main-frame-id"
+      }
+    ]
+  }
+  ```
+
+- `Target.attachToTarget(targetId, flatten)`: Attaches to a target for debugging
+  - When `flatten=true`: Returns a `sessionId` for routing commands in flattened mode
+  - All communication happens over the same WebSocket, differentiated by `sessionId`
+
+**Pydoll usage:**
+
+```python
+# From pydoll/elements/web_element.py (simplified)
+async def _resolve_oopif_by_parent(self, parent_frame_id: str, ...):
+    """Resolve an OOPIF using the parent frame id."""
+    browser_handler = ConnectionHandler(...)
+    targets_response: GetTargetsResponse = await browser_handler.execute_command(
+        TargetCommands.get_targets()
+    )
+    target_infos = targets_response.get('result', {}).get('targetInfos', [])
+    
+    # Find targets whose parentFrameId matches
+    direct_children = [
+        target_info for target_info in target_infos
+        if target_info.get('parentFrameId') == parent_frame_id
+    ]
+    
+    if direct_children:
+        attach_response: AttachToTargetResponse = await browser_handler.execute_command(
+            TargetCommands.attach_to_target(
+                target_id=direct_children[0]['targetId'], 
+                flatten=True
+            )
+        )
+        attached_session_id = attach_response.get('result', {}).get('sessionId')
+        # ... use session_id for subsequent commands
+```
+
+#### 4. **Runtime Domain**
+
+Executes JavaScript and manages execution contexts.
+
+**Key methods:**
+
+- `Runtime.evaluate(expression, contextId)`: Evaluates JavaScript in a specific execution context
+- `Runtime.callFunctionOn(functionDeclaration, objectId)`: Calls a function with a specific object as `this`
+
+**Pydoll usage for iframe document access:**
+
+```python
+# From pydoll/elements/web_element.py
+async def _set_iframe_document_object_id(self, execution_context_id: int):
+    """Evaluate document.documentElement in iframe context and cache its object id."""
+    evaluate_command = RuntimeCommands.evaluate(
+        expression='document.documentElement',
+        context_id=execution_context_id,
+    )
+    if self._iframe_context and self._iframe_context.session_id:
+        evaluate_command['sessionId'] = self._iframe_context.session_id
+    
+    evaluate_response: EvaluateResponse = await (
+        (self._iframe_context.session_handler if self._iframe_context else None)
+        or self._connection_handler
+    ).execute_command(evaluate_command)
+    
+    document_object_id = evaluate_response.get('result', {}).get('result', {}).get('objectId')
+    if self._iframe_context:
+        self._iframe_context.document_object_id = document_object_id
+```
+
+---
+
+## Execution Contexts and Isolated Worlds
+
+### What is an Execution Context?
+
+An **execution context** is an environment where JavaScript code is executed. Every frame in a browser has at least one execution context. The context includes:
+
+- **Global object** (`window` in browsers)
+- **Scope chain**: How variables are resolved
+- **This binding**: What `this` refers to
+- **Variable environment**: All declared variables and functions
+
+### Multiple Contexts per Frame
+
+A single frame can have multiple execution contexts:
+
+1. **Main world (default context)**: Where the page's own JavaScript runs
+2. **Isolated worlds**: Separate contexts that share the same DOM but have different JavaScript global scopes
+
+```mermaid
+graph TB
+    Frame[Frame: example.com/page]
+    Frame --> MainWorld[Main World<br/>Page's JavaScript]
+    Frame --> IsolatedWorld1[Isolated World 1<br/>Extension content script]
+    Frame --> IsolatedWorld2[Isolated World 2<br/>Pydoll automation]
+    
+    DOM[Shared DOM Tree]
+    MainWorld -.can access.-> DOM
+    IsolatedWorld1 -.can access.-> DOM
+    IsolatedWorld2 -.can access.-> DOM
+    
+    MainWorld -.cannot access.-> IsolatedWorld1
+    MainWorld -.cannot access.-> IsolatedWorld2
+```
+
+### What is an Isolated World?
+
+An **isolated world** is a separate JavaScript execution context that:
+
+- **Shares the same DOM**: Can read/modify DOM elements
+- **Has a separate global object**: Variables/functions don't leak between worlds
+- **Prevents interference**: Page scripts cannot detect or interfere with isolated world scripts
+
+**Origin**: Isolated worlds were created for browser extensions. Content scripts run in isolated worlds so they can interact with the page DOM without:
+
+- Page scripts overwriting their variables
+- Being detected by anti-tamper code
+- Conflicting with page JavaScript
+
+### Why Pydoll Uses Isolated Worlds for Iframes
+
+When Pydoll interacts with iframe content, it creates an isolated world in that iframe's context. This provides:
+
+1. **Clean JavaScript environment**: No conflicts with iframe's own scripts
+2. **Consistent behavior**: Automation scripts work regardless of what JavaScript the iframe runs
+3. **Anti-detection**: The iframe's JavaScript cannot easily detect Pydoll's presence
+4. **Safe evaluation**: Automation code cannot accidentally trigger page logic
+
+**Implementation:**
+
+```python
+# From pydoll/elements/web_element.py
+@staticmethod
+async def _create_isolated_world_for_frame(
+    frame_id: str,
+    handler: ConnectionHandler,
+    session_id: Optional[str],
+) -> int:
+    """Create an isolated world (Page.createIsolatedWorld) for the given frame."""
+    create_command = PageCommands.create_isolated_world(
+        frame_id=frame_id,
+        world_name=f'pydoll::iframe::{frame_id}',
+        grant_universal_access=True,
+    )
+    if session_id:
+        create_command['sessionId'] = session_id
+    
+    create_response: CreateIsolatedWorldResponse = await handler.execute_command(
+        create_command
+    )
+    execution_context_id = create_response.get('result', {}).get('executionContextId')
+    if not execution_context_id:
+        raise InvalidIFrame('Unable to create isolated world for iframe')
+    return execution_context_id
+```
+
+The `grant_universal_access=True` parameter allows the isolated world to:
+
+- Access cross-origin frames (normally blocked by same-origin policy)
+- Perform privileged operations needed for automation
+
+!!! tip "Isolated worlds in practice"
+    Every time you use `await iframe.find(...)`, Pydoll evaluates the selector query in an isolated world created specifically for that iframe. This ensures your automation logic never conflicts with the iframe's own JavaScript, and the iframe cannot detect or block your automation.
+
+---
+
+## CDP Identifiers Reference
+
+Understanding CDP identifiers is crucial for iframe handling. Here's a comprehensive reference:
+
+| Identifier | Domain | Scope | Purpose | Example Use in Pydoll |
+|------------|--------|-------|---------|----------------------|
+| **`nodeId`** | DOM | Document-local | Identifies a DOM node within a specific document context | Internal CDP operations; not stable across navigations |
+| **`backendNodeId`** | DOM | Cross-document stable | Stable identifier for a DOM node; can map frames to owner elements | Used to match iframe elements to frame IDs via `DOM.getFrameOwner` |
+| **`frameId`** | Page | Frame | Identifies a frame in the page's frame tree | Used to specify which frame for `Page.createIsolatedWorld` and frame tree traversal |
+| **`targetId`** | Target | Global | Identifies a debugging target (page, iframe, worker, etc.) | Used for `Target.attachToTarget` to connect to OOPIFs |
+| **`sessionId`** | Target | Target-specific | Routes commands to a specific target in flattened mode | Injected into commands to route them to the correct OOPIF |
+| **`executionContextId`** | Runtime | Frame + world | Identifies a JavaScript execution context (including isolated worlds) | Returned by `Page.createIsolatedWorld`; used in `Runtime.evaluate` |
+| **`objectId`** | Runtime | Execution context | Remote object reference (e.g., DOM element, function, object) | Reference to iframe's `document.documentElement` for relative queries |
+
+### Identifier Relationships
+
+Here's how identifiers relate to each other during iframe resolution:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Resolution Flow                                 │
+└─────────────────────────────────────────────────────────────────────────┘
+
+1. Start: <iframe> Element
+   └─ backendNodeId: 789
+   
+2. Find Frame ──────────────[DOM.getFrameOwner]──────────────┐
+   └─ frameId: abc-123                                       │
+                                                             │
+3. OOPIF? Check Origin ─────[Different origin detected]──────┤
+   └─ targetId: xyz-456                                      │
+                                                             │
+4. Attach to Target ────────[Target.attachToTarget]──────────┤
+   └─ sessionId: session-789                                 │
+                                                             │
+5. Create Isolated World ───[Page.createIsolatedWorld]───────┤
+   └─ executionContextId: 42                                 │
+                                                             │
+6. Get Document ────────────[Runtime.evaluate]───────────────┘
+   └─ objectId: obj-999
+```
+
+**Key transformation points:**
+
+| From | Method | To | Purpose |
+|------|--------|-----|---------|
+| `backendNodeId` | `DOM.getFrameOwner` | `frameId` | Find which frame owns the iframe element |
+| `targetId` | `Target.attachToTarget(flatten=true)` | `sessionId` | Connect to OOPIF for command routing |
+| `frameId` | `Page.createIsolatedWorld` | `executionContextId` | Create safe JavaScript environment |
+| `executionContextId` | `Runtime.evaluate('document.documentElement')` | `objectId` | Get reference to iframe's document |
+
+### Code Representation in Pydoll
+
+```python
+# From pydoll/elements/web_element.py
+@dataclass
+class _IFrameContext:
+    """Encapsulates all identifiers and routing information for an iframe."""
+    frame_id: str                                   # frameId: identifies the frame
+    document_url: Optional[str] = None              # frame's loaded URL
+    execution_context_id: Optional[int] = None      # executionContextId: isolated world
+    document_object_id: Optional[str] = None        # objectId: document.documentElement
+    session_handler: Optional[ConnectionHandler] = None  # for OOPIF targets
+    session_id: Optional[str] = None                # sessionId: routes commands to OOPIF
+```
+
+This dataclass is cached on each `WebElement` representing an iframe, enabling automatic routing of all subsequent operations.
+
+---
+
+## Pydoll's Resolution Pipeline
+
+When you access an iframe in Pydoll (e.g., `await iframe.find(...)`), an elaborate resolution pipeline executes behind the scenes. This section breaks down every step.
+
+### High-Level Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant WebElement
+    participant Pipeline as Resolution Pipeline
+    participant CDP
+    
+    User->>WebElement: iframe.find(id='button')
+    WebElement->>WebElement: Check if iframe context cached
+    alt Context not cached
+        WebElement->>Pipeline: _ensure_iframe_context()
+        Pipeline->>CDP: DOM.describeNode(iframe)
+        CDP-->>Pipeline: Node info (frameId?, backendNodeId, etc.)
+        
+        alt frameId not in node info
+            Pipeline->>Pipeline: _resolve_frame_by_owner()
+            Pipeline->>CDP: Page.getFrameTree()
+            CDP-->>Pipeline: Frame tree
+            Pipeline->>CDP: DOM.getFrameOwner(each frame)
+            CDP-->>Pipeline: backendNodeId
+            Pipeline->>Pipeline: Match backendNodeId to find frameId
+        end
+        
+        alt frameId still missing (OOPIF)
+            Pipeline->>Pipeline: _resolve_oopif_by_parent()
+            Pipeline->>CDP: Target.getTargets()
+            CDP-->>Pipeline: List of targets
+            Pipeline->>CDP: Target.attachToTarget(targetId, flatten=true)
+            CDP-->>Pipeline: sessionId
+            Pipeline->>CDP: Page.getFrameTree(sessionId)
+            CDP-->>Pipeline: OOPIF frame tree
+        end
+        
+        Pipeline->>CDP: Page.createIsolatedWorld(frameId)
+        CDP-->>Pipeline: executionContextId
+        
+        Pipeline->>CDP: Runtime.evaluate('document.documentElement', contextId)
+        CDP-->>Pipeline: objectId (document reference)
+        
+        Pipeline->>WebElement: Cache _IFrameContext
+    end
+    
+    WebElement->>WebElement: Use cached context for find()
+    WebElement-->>User: Button element (with context)
+```
+
+### Step-by-Step Deep Dive
+
+#### **Step 1: Describe the Iframe Element**
+
+**Goal**: Extract metadata from the `<iframe>` DOM element.
+
+**Method**: `DOM.describeNode(objectId=iframe_object_id)`
+
+**What we get**:
+
+- `backendNodeId`: Stable identifier for the iframe element
+- `frameId` (from `contentDocument`): If the iframe's content is already loaded and in-process
+- `documentURL`: The URL loaded in the iframe
+- `parentFrameId` (from `frameId` field on the node): The frame containing this iframe element
+
+**Code**:
+
+```python
+# From pydoll/elements/web_element.py
+async def _ensure_iframe_context(self) -> None:
+    """Initialize and cache context information for iframe elements."""
+    node_info = await self._describe_node(object_id=self._object_id)
+    base_handler, base_session_id = self._get_base_session()
+    frame_id, document_url, parent_frame_id, backend_node_id = self._extract_frame_metadata(
+        node_info
+    )
+    # ... continue resolution
+```
+
+**Helper**:
+
+```python
+@staticmethod
+def _extract_frame_metadata(
+    node_info: Node,
+) -> tuple[Optional[str], Optional[str], Optional[str], Optional[int]]:
+    """Extract iframe-related metadata from a DOM.describeNode Node."""
+    content_document = node_info.get('contentDocument') or {}
+    parent_frame_id = node_info.get('frameId')
+    backend_node_id = node_info.get('backendNodeId')
+    frame_id = content_document.get('frameId')
+    document_url = (
+        content_document.get('documentURL')
+        or content_document.get('baseURL')
+        or node_info.get('documentURL')
+        or node_info.get('baseURL')
+    )
+    return frame_id, document_url, parent_frame_id, backend_node_id
+```
+
+**Outcome**:
+
+- **If `frame_id` is present**: Great! The iframe is in-process; proceed to Step 4.
+- **If `frame_id` is missing**: The iframe might be an OOPIF or not fully loaded; proceed to Step 2.
+
+---
+
+#### **Step 2: Resolve Frame by Owner (backendNodeId matching)**
+
+**Goal**: Find the `frameId` by matching the iframe element's `backendNodeId` to frame owners in the frame tree.
+
+**Strategy**:
+
+1. Fetch the page's frame tree (`Page.getFrameTree`)
+2. For each frame in the tree, call `DOM.getFrameOwner(frameId)` to get the `backendNodeId` of the owning iframe element
+3. Compare with our iframe's `backendNodeId`
+4. When they match, we've found the correct `frameId`
+
+**Code**:
+
+```python
+# From pydoll/elements/web_element.py
+async def _resolve_frame_by_owner(
+    self,
+    base_handler: ConnectionHandler,
+    base_session_id: Optional[str],
+    backend_node_id: int,
+    current_document_url: Optional[str],
+) -> tuple[Optional[str], Optional[str]]:
+    """Resolve a frame id and URL by matching the owner backend_node_id."""
+    owner_frame_id, owner_url = await self._find_frame_by_owner(
+        base_handler, base_session_id, backend_node_id
+    )
+    if not owner_frame_id:
+        return None, current_document_url
+    return owner_frame_id, owner_url or current_document_url
+
+async def _find_frame_by_owner(
+    self, handler: ConnectionHandler, session_id: Optional[str], backend_node_id: int
+) -> tuple[Optional[str], Optional[str]]:
+    """Find a frame by matching the owner backend_node_id of the <iframe> element."""
+    frame_tree = await self._get_frame_tree_for(handler, session_id)
+    for frame_node in WebElement._walk_frames(frame_tree):
+        candidate_frame_id = frame_node.get('id', '')
+        if not candidate_frame_id:
+            continue
+        owner_backend_id = await self._owner_backend_for(
+            handler, session_id, candidate_frame_id
+        )
+        if owner_backend_id == backend_node_id:
+            return candidate_frame_id, frame_node.get('url')
+    return None, None
+```
+
+**Why this is necessary**:
+
+- `DOM.describeNode` sometimes doesn't include the `contentDocument.frameId` for cross-origin or lazy-loaded iframes
+- The frame tree always contains all frames (even OOPIFs), so we can find it indirectly
+
+**Outcome**:
+
+- **If `frameId` found**: Proceed to Step 4.
+- **If still not found**: The iframe is likely an OOPIF in a separate target; proceed to Step 3.
+
+---
+
+#### **Step 3: Resolve OOPIF by Parent Frame**
+
+**Goal**: For Out-of-Process Iframes, find the target, attach to it, and obtain the `frameId` from the target's frame tree.
+
+**Strategy**:
+
+**3a. Direct child target lookup**:
+
+1. Call `Target.getTargets()` to list all debugging targets
+2. Filter targets where `type` is `"iframe"` or `"page"` and `parentFrameId` matches our parent frame
+3. If found, attach to that target with `Target.attachToTarget(targetId, flatten=true)`
+4. The response includes a `sessionId`
+5. Fetch `Page.getFrameTree(sessionId)` for that target
+6. The root frame of this tree is our iframe's frame
+
+**3b. Fallback: Scan all targets**:
+
+1. Iterate all iframe/page targets
+2. Attach to each and fetch its frame tree
+3. Look for a child frame whose `parentId` matches our parent frame
+4. **OR** check if the root frame's owner (via `DOM.getFrameOwner`) matches our iframe's `backendNodeId`
+
+**Code**:
+
+```python
+# From pydoll/elements/web_element.py
+async def _resolve_oopif_by_parent(
+    self,
+    parent_frame_id: str,
+    backend_node_id: Optional[int],
+) -> tuple[Optional[ConnectionHandler], Optional[str], Optional[str], Optional[str]]:
+    """Resolve an OOPIF using the parent frame id."""
+    browser_handler = ConnectionHandler(
+        connection_port=self._connection_handler._connection_port
+    )
+    targets_response: GetTargetsResponse = await browser_handler.execute_command(
+        TargetCommands.get_targets()
+    )
+    target_infos = targets_response.get('result', {}).get('targetInfos', [])
+    
+    # Strategy 3a: Direct children
+    direct_children = [
+        target_info
+        for target_info in target_infos
+        if target_info.get('type') in {'iframe', 'page'}
+        and target_info.get('parentFrameId') == parent_frame_id
+    ]
+    if direct_children:
+        attach_response: AttachToTargetResponse = await browser_handler.execute_command(
+            TargetCommands.attach_to_target(
+                target_id=direct_children[0]['targetId'], flatten=True
+            )
+        )
+        attached_session_id = attach_response.get('result', {}).get('sessionId')
+        if attached_session_id:
+            frame_tree = await self._get_frame_tree_for(browser_handler, attached_session_id)
+            root_frame = (frame_tree or {}).get('frame', {})
+            return (
+                browser_handler,
+                attached_session_id,
+                root_frame.get('id'),
+                root_frame.get('url'),
+            )
+    
+    # Strategy 3b: Scan all targets
+    for target_info in target_infos:
+        if target_info.get('type') not in {'iframe', 'page'}:
+            continue
+        attach_response = await browser_handler.execute_command(
+            TargetCommands.attach_to_target(
+                target_id=target_info.get('targetId', ''), flatten=True
+            )
+        )
+        attached_session_id = attach_response.get('result', {}).get('sessionId')
+        if not attached_session_id:
+            continue
+        
+        frame_tree = await self._get_frame_tree_for(browser_handler, attached_session_id)
+        
+        # Check for child with matching parentId
+        child_frame_id = WebElement._find_child_by_parent(frame_tree, parent_frame_id)
+        if child_frame_id:
+            return browser_handler, attached_session_id, child_frame_id, None
+        
+        # Check if root frame's owner matches our backendNodeId
+        root_frame_id = (frame_tree or {}).get('frame', {}).get('id', '')
+        if not root_frame_id or backend_node_id is None:
+            continue
+        owner_backend_id = await self._owner_backend_for(
+            self._connection_handler, None, root_frame_id
+        )
+        if owner_backend_id == backend_node_id:
+            return browser_handler, attached_session_id, root_frame_id, None
+    
+    return None, None, None, None
+```
+
+**Outcome**:
+
+- **If OOPIF resolved**: We now have `sessionId`, `session_handler`, and `frameId`; proceed to Step 4.
+- **If resolution fails**: Raise `InvalidIFrame` exception (handled in `_ensure_iframe_context`).
+
+---
+
+#### **Step 4: Create Isolated World**
+
+**Goal**: Create a separate JavaScript execution context in the resolved frame.
+
+**Method**: `Page.createIsolatedWorld(frameId, worldName='pydoll::iframe::<frameId>', grantUniversalAccess=true)`
+
+**Parameters**:
+- `frameId`: The frame where the isolated world is created
+- `worldName`: Identifier for the world (useful for debugging)
+- `grantUniversalAccess`: Allows cross-origin access (needed for automation)
+
+**Response**: `{ executionContextId: 42 }`
+
+**Code**:
+
+```python
+# From pydoll/elements/web_element.py
+@staticmethod
+async def _create_isolated_world_for_frame(
+    frame_id: str,
+    handler: ConnectionHandler,
+    session_id: Optional[str],
+) -> int:
+    """Create an isolated world for the given frame."""
+    create_command = PageCommands.create_isolated_world(
+        frame_id=frame_id,
+        world_name=f'pydoll::iframe::{frame_id}',
+        grant_universal_access=True,
+    )
+    if session_id:
+        create_command['sessionId'] = session_id
+    create_response: CreateIsolatedWorldResponse = await handler.execute_command(create_command)
+    execution_context_id = create_response.get('result', {}).get('executionContextId')
+    if not execution_context_id:
+        raise InvalidIFrame('Unable to create isolated world for iframe')
+    return execution_context_id
+```
+
+**Why isolated world**:
+
+- **Isolation**: Our automation JavaScript doesn't interfere with the iframe's JavaScript
+- **Anti-detection**: The iframe cannot detect our presence easily
+- **Consistency**: Behavior is predictable regardless of iframe's script environment
+
+**Outcome**: We have an `executionContextId` for running JavaScript in the iframe.
+
+---
+
+#### **Step 5: Pin the Iframe Document as a Runtime Object**
+
+**Goal**: Obtain an `objectId` reference to the iframe's `document.documentElement` (the `<html>` element of the iframe).
+
+**Method**: `Runtime.evaluate(expression='document.documentElement', contextId=executionContextId)`
+
+**Why we need this**:
+
+- To execute **relative queries** (like `element.querySelector()`) inside the iframe
+- The `objectId` allows using `Runtime.callFunctionOn(objectId, ...)` with `this` bound to the iframe's document
+
+**Code**:
+
+```python
+# From pydoll/elements/web_element.py
+async def _set_iframe_document_object_id(self, execution_context_id: int) -> None:
+    """Evaluate document.documentElement in the iframe context and cache its object id."""
+    evaluate_command = RuntimeCommands.evaluate(
+        expression='document.documentElement',
+        context_id=execution_context_id,
+    )
+    if self._iframe_context and self._iframe_context.session_id:
+        evaluate_command['sessionId'] = self._iframe_context.session_id
+    evaluate_response: EvaluateResponse = await (
+        (self._iframe_context.session_handler if self._iframe_context else None)
+        or self._connection_handler
+    ).execute_command(evaluate_command)
+    result_object = evaluate_response.get('result', {}).get('result', {})
+    document_object_id = result_object.get('objectId')
+    if not document_object_id:
+        raise InvalidIFrame('Unable to obtain document reference for iframe')
+    if self._iframe_context:
+        self._iframe_context.document_object_id = document_object_id
+```
+
+**Outcome**: The `_IFrameContext` is now fully populated and cached on the `WebElement`.
+
+---
+
+#### **Step 6: Cache and Propagate Context**
+
+**Goal**: Store the resolved context on the iframe element and propagate it to all child elements found within the iframe.
+
+**Caching**:
+
+```python
+# From pydoll/elements/web_element.py
+def _init_iframe_context(
+    self,
+    frame_id: str,
+    document_url: Optional[str],
+    session_handler: Optional[ConnectionHandler],
+    session_id: Optional[str],
+) -> None:
+    """Initialize and cache iframe context on this element."""
+    self._iframe_context = _IFrameContext(frame_id=frame_id, document_url=document_url)
+    # Clean up routing attributes (these were for nested iframes)
+    if hasattr(self, '_routing_session_handler'):
+        delattr(self, '_routing_session_handler')
+    if hasattr(self, '_routing_session_id'):
+        delattr(self, '_routing_session_id')
+    # Store OOPIF routing if needed
+    if session_handler and session_id:
+        self._iframe_context.session_handler = session_handler
+        self._iframe_context.session_id = session_id
+```
+
+**Propagation** (when finding elements inside the iframe):
+
+```python
+# From pydoll/elements/mixins/find_elements_mixin.py
+def _apply_iframe_context_to_element(
+    self, element: WebElement, iframe_context: _IFrameContext | None
+) -> None:
+    """Propagate iframe context to the newly created element."""
+    if not iframe_context:
+        return
+    
+    # If the child element is also an iframe, set up routing
+    if getattr(element, 'is_iframe', False):
+        element._routing_session_handler = (
+            iframe_context.session_handler or self._connection_handler
+        )
+        element._routing_session_id = iframe_context.session_id
+        element._routing_parent_frame_id = iframe_context.frame_id
+        return
+    
+    # Otherwise, inject the parent iframe's context
+    element._iframe_context = iframe_context
+```
+
+**Why propagation matters**:
+
+- Elements found inside an iframe inherit the iframe's context
+- This ensures subsequent operations (click, type, find nested elements) automatically use the correct routing
+- Nested iframes receive routing information so they can resolve their own context relative to the parent iframe
+
+---
+
+## Session Routing and Flattened Mode
+
+### The Flattened Session Model
+
+As discussed in [Deep Dive → Fundamentals → CDP](./cdp.md), traditional CDP uses separate WebSocket connections for each target. **Flattened mode** is an optimization where all targets share a single WebSocket connection, with commands routed using a `sessionId`.
+
+```mermaid
+graph TB
+    subgraph "Traditional Mode"
+        WS1[WebSocket 1] --> MainPage[Main Page Target]
+        WS2[WebSocket 2] --> Iframe1[OOPIF Target 1]
+        WS3[WebSocket 3] --> Iframe2[OOPIF Target 2]
+    end
+    
+    subgraph "Flattened Mode"
+        WS[Single WebSocket] --> Router{CDP Router}
+        Router -->|sessionId: null| MainPage2[Main Page Target]
+        Router -->|sessionId: session-1| Iframe3[OOPIF Target 1]
+        Router -->|sessionId: session-2| Iframe4[OOPIF Target 2]
+    end
+```
+
+### How Session Routing Works
+
+**When attaching to an OOPIF**:
+
+```python
+response = await handler.execute_command(
+    TargetCommands.attach_to_target(targetId="iframe-target-id", flatten=True)
+)
+session_id = response['result']['sessionId']  # e.g., "8E6C...-1234"
+```
+
+**When sending a command to that OOPIF**:
+
+```python
+command = PageCommands.get_frame_tree()
+command['sessionId'] = 'session-1'  # Route to the OOPIF
+response = await handler.execute_command(command)
+```
+
+The browser's CDP implementation routes the command to the correct target based on the `sessionId`.
+
+### Pydoll's Command Routing
+
+Every command sent by Pydoll elements is automatically routed to the correct target:
+
+```python
+# From pydoll/elements/mixins/find_elements_mixin.py
+def _resolve_routing(self) -> tuple[ConnectionHandler, Optional[str]]:
+    """Resolve handler and sessionId for the current context."""
+    # Check if element has an iframe context with OOPIF routing
+    iframe_context = getattr(self, '_iframe_context', None)
+    if iframe_context and getattr(iframe_context, 'session_handler', None):
+        return iframe_context.session_handler, getattr(iframe_context, 'session_id', None)
+    
+    # Check if element has inherited routing from a parent iframe
+    routing_handler = getattr(self, '_routing_session_handler', None)
+    if routing_handler is not None:
+        return routing_handler, getattr(self, '_routing_session_id', None)
+    
+    # Default: use the tab's main connection
+    return self._connection_handler, None
+
+async def _execute_command(
+    self, command: Command[T_CommandParams, T_CommandResponse]
+) -> T_CommandResponse:
+    """Execute CDP command via resolved handler (60s timeout)."""
+    handler, session_id = self._resolve_routing()
+    if session_id:
+        command['sessionId'] = session_id
+    return await handler.execute_command(command, timeout=60)
+```
+
+**Routing logic**:
+
+1. **Element inside OOPIF iframe**: Use `iframe_context.session_id` and `iframe_context.session_handler`
+2. **Nested iframe (child of OOPIF)**: Use inherited `_routing_session_id` and `_routing_session_handler`
+3. **Regular element or in-process iframe**: Use main connection (`_connection_handler`), no `sessionId`
+
+### Extended Command Typing
+
+To make `sessionId` type-safe, Pydoll extended the `Command` TypedDict:
+
+```python
+# From pydoll/protocol/base.py
+class Command(TypedDict, Generic[T_CommandParams, T_CommandResponse]):
+    """Base structure for all commands."""
+    id: NotRequired[int]
+    method: str
+    params: NotRequired[T_CommandParams]
+    sessionId: NotRequired[str]  # Added for flattened session routing
+```
+
+This allows type-checkers to recognize `command['sessionId'] = '...'` as valid without suppressing type warnings.
+
+---
+
+## Performance Considerations
+
+### Caching Strategy
+
+**First access is expensive**:
+
+- `DOM.describeNode`: 1 round-trip
+- Frame tree retrieval: 1+ round-trips (main + OOPIF targets)
+- `DOM.getFrameOwner` per frame: N round-trips (in worst case)
+- `Target.getTargets` + attachments: 1 + M round-trips (M = number of OOPIF targets)
+- `Page.createIsolatedWorld`: 1 round-trip
+- `Runtime.evaluate` (document): 1 round-trip
+
+**Total**: Potentially 5-20+ round-trips depending on page structure.
+
+**Subsequent access is O(1)**:
+
+- `iframe_context` is cached on the `WebElement` instance
+- Accessing `await iframe.iframe_context` multiple times returns the cached value immediately
+- All elements found within the iframe inherit the context (no re-resolution)
+
+### Optimization: Direct Child Target Lookup
+
+In `_resolve_oopif_by_parent`, Pydoll first checks for direct children by `parentFrameId`:
+
+```python
+direct_children = [
+    target_info
+    for target_info in target_infos
+    if target_info.get('type') in {'iframe', 'page'}
+    and target_info.get('parentFrameId') == parent_frame_id
+]
+if direct_children:
+    # Attach immediately, skip scanning all targets
+```
+
+**Why this helps**:
+
+- Most OOPIFs have `parentFrameId` correctly set
+- Avoids attaching to every target speculatively
+- Reduces round-trips from O(targets) to O(1) in the common case
+
+### Asynchronous Parallel Resolution (Future Enhancement)
+
+Currently, frame owner matching is sequential (check each frame one by one). A future optimization could parallelize:
+
+```python
+# Current (sequential)
+for frame_node in frames:
+    owner = await self._owner_backend_for(...)
+    if owner == backend_node_id:
+        return frame_node['id']
+
+# Potential (parallel)
+results = await asyncio.gather(*(
+    self._owner_backend_for(..., frame['id'])
+    for frame in frames
+))
+for i, owner in enumerate(results):
+    if owner == backend_node_id:
+        return frames[i]['id']
+```
+
+This would reduce latency from `N * RTT` to `RTT` (where RTT = round-trip time).
+
+---
+
+## Failure Modes and Debugging
+
+### Common Failure Scenarios
+
+#### 1. **InvalidIFrame: Unable to resolve frameId**
+
+**Cause**:
+
+- The iframe is dynamically created and hasn't fully initialized
+- The iframe is sandboxed with restrictive policies
+- Network issues delayed iframe loading
+
+**Solutions**:
+
+- **Wait for iframe**: Use `await tab.find(id='iframe', timeout=10)` with a timeout
+- **Check sandbox attribute**: Restrictive sandboxing (`<iframe sandbox>`) may block some CDP operations
+- **Retry strategy**: Implement retry logic with exponential backoff
+
+**Debugging**:
+
+```python
+try:
+    iframe = await tab.find(id='problem-iframe')
+    context = await iframe.iframe_context
+except InvalidIFrame as e:
+    # Inspect what we have
+    node_info = await iframe._describe_node(object_id=iframe._object_id)
+    print(f"Node info: {node_info}")
+    
+    # Check frame tree manually
+    frame_tree = await WebElement._get_frame_tree_for(tab._connection_handler, None)
+    print(f"Frame tree: {frame_tree}")
+```
+
+#### 2. **InvalidIFrame: Unable to create isolated world**
+
+**Cause**:
+
+- Frame has been destroyed/navigated away between resolution steps
+- Chrome bug (rare)
+
+**Solutions**:
+
+- **Re-resolve context**: Clear cached context and re-access
+- **Check navigation**: Ensure iframe isn't navigating during resolution
+
+**Debugging**:
+
+```python
+# Clear cache and retry
+iframe._iframe_context = None
+context = await iframe.iframe_context
+```
+
+#### 3. **InvalidIFrame: Unable to obtain document reference**
+
+**Cause**:
+
+- The isolated world was created but the document isn't ready
+- Frame is about to navigate
+
+**Solutions**:
+
+- Wait for frame load: Use Page events to detect `Page.frameNavigated` or `Page.loadEventFired`
+- Retry with a small delay
+
+#### 4. **Session routing failures (command times out or returns error)**
+
+**Cause**:
+
+- OOPIF target was detached (page navigated, iframe removed)
+- `sessionId` is stale
+
+**Solutions**:
+
+- **Re-attach to target**: Create a new `ConnectionHandler` and re-resolve OOPIF
+- **Validate target**: Call `Target.getTargets()` to check if target still exists
+
+**Debugging**:
+
+```python
+# Check if session is still valid
+targets = await handler.execute_command(TargetCommands.get_targets())
+active_sessions = [t['targetId'] for t in targets['result']['targetInfos']]
+print(f"Active targets: {active_sessions}")
+
+if iframe._iframe_context and iframe._iframe_context.session_id:
+    print(f"Our session: {iframe._iframe_context.session_id}")
+```
+
+### Diagnostic Tools
+
+#### Enable CDP logging
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger('pydoll')
+logger.setLevel(logging.DEBUG)
+```
+
+This logs all CDP commands and responses, useful for tracing iframe resolution steps.
+
+#### Inspect iframe context
+
+```python
+iframe = await tab.find(id='my-iframe')
+ctx = await iframe.iframe_context
+
+print(f"Frame ID: {ctx.frame_id}")
+print(f"Document URL: {ctx.document_url}")
+print(f"Execution Context ID: {ctx.execution_context_id}")
+print(f"Document Object ID: {ctx.document_object_id}")
+print(f"Session ID (OOPIF): {ctx.session_id}")
+print(f"Session Handler: {ctx.session_handler}")
+```
+
+---
+
+## Conclusion
+
+Pydoll's iframe handling represents a sophisticated implementation of CDP's frame management capabilities. By understanding:
+
+- **The DOM**: Tree structure and node identification
+- **Iframes**: Independent document contexts and security boundaries
+- **OOPIFs**: Site isolation and target-based architecture
+- **CDP domains**: Page, DOM, Target, Runtime coordination
+- **Execution contexts**: Isolated worlds for clean automation
+- **Identifiers**: backendNodeId, frameId, targetId, sessionId, executionContextId, objectId relationships
+- **Resolution pipeline**: Multi-stage fallback strategy for finding frames
+- **Session routing**: Flattened mode and automatic command routing
+
+you can appreciate why manual context switching is eliminated. The complexity is real, but Pydoll abstracts it behind a simple, intuitive API:
+
+```python
+iframe = await tab.find(id='login-frame')
+username = await iframe.find(name='username')
+await username.type_text('user@example.com')
+```
+
+Three lines. No context switching. No target attachment. No session management. It just works.
+
+---
+
+## Further Reading
+
+- **CDP Specification**: [Chrome DevTools Protocol - Page Domain](https://chromedevtools.github.io/devtools-protocol/tot/Page/)
+- **CDP Specification**: [Chrome DevTools Protocol - DOM Domain](https://chromedevtools.github.io/devtools-protocol/tot/DOM/)
+- **CDP Specification**: [Chrome DevTools Protocol - Target Domain](https://chromedevtools.github.io/devtools-protocol/tot/Target/)
+- **CDP Specification**: [Chrome DevTools Protocol - Runtime Domain](https://chromedevtools.github.io/devtools-protocol/tot/Runtime/)
+- **Chromium Site Isolation**: [Site Isolation - The Chromium Projects](https://www.chromium.org/Home/chromium-security/site-isolation/)
+- **Content Scripts & Isolated Worlds**: [Chrome Extensions - Content Scripts](https://developer.chrome.com/docs/extensions/mv3/content_scripts/)
+- **Pydoll Documentation**: [Deep Dive → Fundamentals → Chrome DevTools Protocol](./cdp.md)
+- **Pydoll Documentation**: [Features → Automation → IFrames](../../features/automation/iframes.md)
+
+---
+
+!!! tip "Design Philosophy"
+    The goal of Pydoll's iframe handling is **ergonomic automation**: write code as if iframes don't exist, and let the library handle the complexity. This deep dive showed what happens behind the scenes—but you never have to think about it in your automation scripts.
diff --git a/docs/en/features/automation/iframes.md b/docs/en/features/automation/iframes.md
index 3fe2703e..cc6536c8 100644
--- a/docs/en/features/automation/iframes.md
+++ b/docs/en/features/automation/iframes.md
@@ -1,10 +1,14 @@
 # Working with IFrames
 
-IFrames (inline frames) are one of the trickiest aspects of browser automation. Pydoll provides a clean, intuitive API for iframe interaction that abstracts away the complexity of CDP target management.
+Modern web pages embed content from other documents using `<iframe>`. In previous versions of Pydoll you had to convert an iframe into a `Tab` using `tab.get_frame()` and keep track of CDP targets manually. **That is no longer necessary.**  
+An iframe nowadays behaves like any other `WebElement`: you can call `find()`, `query()`, `execute_script()`, `inner_html`, `text`, and all element helpers directly—Pydoll will transparently execute the request inside the correct browsing context.
+
+!!! info "Simpler mental model"
+    Treat an iframe exactly like a div: locate it once and use it as the starting point for new element searches. Pydoll handles cross-origin frames, isolated execution contexts, and nested frames behind the scenes.
 
 ## Quick Start
 
-### Basic IFrame Interaction
+### Interact with the first iframe on the page
 
 ```python
 import asyncio
@@ -14,176 +18,82 @@ async def interact_with_iframe():
     async with Chrome() as browser:
         tab = await browser.start()
         await tab.go_to('https://example.com/page-with-iframe')
-        
-        # Find the iframe element
-        iframe_element = await tab.find(tag_name='iframe', id='content-frame')
-        
-        # Get a Tab instance for the iframe
-        iframe = await tab.get_frame(iframe_element)
-        
-        # Now interact with elements inside the iframe
-        button = await iframe.find(id='submit-button')
-        await button.click()
-        
-        # Find and fill form inside iframe
-        username = await iframe.find(name='username')
-        await username.type_text('john_doe')
 
-asyncio.run(interact_with_iframe())
-```
+        iframe = await tab.find(tag_name='iframe', id='content-frame')
 
-!!! tip "IFrames are Just Tabs"
-    In Pydoll, an iframe returns a `Tab` object. This means **all methods available on Tab work on iframes**: `find()`, `query()`, `execute_script()`, `take_screenshot()`, and more.
+        # These methods execute inside the iframe automatically
+        title = await iframe.find(tag_name='h1')
+        await title.click()
 
-## Understanding IFrames
-
-### What is an IFrame?
-
-An `<iframe>` (inline frame) is an HTML element that embeds another HTML document within the current page. Think of it as a "browser window within a browser window."
+        form = await iframe.find(id='login-form')
+        username = await form.find(name='username')
+        await username.type_text('john_doe')
 
-```html
-<html>
-  <body>
-    <h1>Main Page</h1>
-    <p>This is the main document</p>
-    
-    <!-- This iframe loads a completely separate document -->
-    <iframe src="https://other-site.com/content.html" id="my-frame">
-    </iframe>
-  </body>
-</html>
+asyncio.run(interact_with_iframe())
 ```
 
-Each iframe:
-
-- Has its own **separate DOM** (Document Object Model)
-- Loads its own HTML, CSS, and JavaScript
-- Can be from a different domain (cross-origin)
-- Operates in an isolated browsing context
+### Nested iframes
 
-### Why You Can't Interact Directly
-
-This code **won't work** as you might expect:
+Need to reach a frame inside another frame? Chain your searches:
 
 ```python
-# ❌ This will NOT find elements inside the iframe
-button = await tab.find(id='button-inside-iframe')
-```
+outer = await tab.find(id='outer-frame')
+inner = await outer.find(tag_name='iframe')   # Search inside the outer iframe
 
-**Why?** Because `tab.find()` searches the **main page's DOM**. The iframe has a **completely separate DOM** that isn't accessible from the parent.
-
-Think of it like this:
-
-```
-Main Page DOM                 IFrame DOM (Separate!)
-├── <html>                    ├── <html>
-│   ├── <body>                │   ├── <body>
-│   │   ├── <div>             │   │   ├── <div>
-│   │   └── <iframe>          │   │   └── <button id="inside">
-│   │       (separate world)  │   └── </body>
-│   └── </body>               └── </html>
-└── </html>
+submit_button = await inner.find(id='submit')
+await submit_button.click()
 ```
 
-!!! info "Isolated Browsing Contexts"
-    IFrames create what's called an **isolated browsing context**. This isolation is a security feature that prevents malicious iframes from accessing or manipulating the parent page's content.
+The algorithm is always the same:
 
-### How Pydoll Solves This
+1. Find the iframe element.
+2. Use that `WebElement` to continue searching.
+3. Repeat for deeper levels if required.
 
-Under the hood, Pydoll uses Chrome DevTools Protocol (CDP) to:
+There is no need to cache frame targets or create additional `Tab` instances.
 
-1. **Identify the iframe target**: Each iframe gets its own CDP target ID
-2. **Create a new Tab instance**: This Tab is scoped to the iframe's DOM
-3. **Provide full access**: All Tab methods work on the iframe's isolated DOM
+### Execute JavaScript in an iframe
 
 ```python
-# This is what happens internally:
-iframe_element = await tab.find(tag_name='iframe')  # Find the <iframe> tag
-frame = await tab.get_frame(iframe_element)         # Get CDP target for iframe
-
-# Now 'frame' is a Tab that operates on the iframe's DOM
-button = await frame.find(id='button-inside-iframe')  # ✅ Works!
+iframe = await tab.find(tag_name='iframe')
+result = await iframe.execute_script('return document.title', return_by_value=True)
+print(result['result']['result']['value'])
 ```
 
-### Technical Deep Dive: CDP Targets
+Pydoll automatically runs the script within the iframe’s isolated execution context (cross-origin and same-origin frames work the same way).
+
+## Why this is better
 
-When you call `tab.get_frame()`, Pydoll:
+- **Intuitive:** what you see in the DOM tree is what you code—if you can select the `iframe` element, you can interact with everything inside it.
+- **Cross-origin friendly:** Pydoll spins up an isolated world for you; no more manual target resolution.
+- **Nested by design:** each search is scoped to the element you call it on, so deep hierarchies stay manageable.
+- **No API split:** you do not have to switch between `Tab` and `WebElement` methods—one set of primitives is enough.
 
-1. **Extracts the `src` attribute** from the iframe element
-2. **Queries CDP for all targets** using `Target.getTargets()`
-3. **Matches the iframe URL** to find its corresponding target ID
-4. **Creates a Tab instance** with that target ID
+!!! tip "Deprecation notice"
+    `Tab.get_frame()` now emits a `DeprecationWarning` and will be removed in a future release. Update existing snippets to work directly with iframe elements as shown above.
 
-Each target has:
+## Frequently used patterns
 
-- **Unique Target ID**: Identifies the browsing context
-- **Separate WebSocket connection**: For isolated CDP communication
-- **Own document tree**: Complete independence from parent
+### Take a screenshot from inside an iframe
 
 ```python
-# Internally in tab.py:
-async def get_frame(self, frame: WebElement) -> Tab:
-    # Get iframe's source URL
-    frame_url = frame.get_attribute('src')
-    
-    # Find the target that matches this URL
-    targets = await self._browser.get_targets()
-    iframe_target = next((t for t in targets if t['url'] == frame_url), None)
-    
-    # Create a Tab for this iframe's target
-    target_id = iframe_target['targetId']
-    tab = Tab(self._browser, target_id=target_id, ...)
-    
-    return tab  # Now you can interact with iframe as a Tab!
+iframe = await tab.find(tag_name='iframe')
+chart = await iframe.find(id='sales-chart')
+await chart.take_screenshot('chart.png')
 ```
 
-!!! warning "IFrame Must Have Valid `src`"
-    The iframe must have a valid `src` attribute for Pydoll to locate its CDP target. IFrames using `srcdoc` or dynamically injected content may not work with `get_frame()`.
-
-## Comparison: Main Page vs IFrame
-
-| Aspect | Main Page | IFrame |
-|--------|-----------|--------|
-| **DOM** | Own document tree | Separate document tree |
-| **CDP Target** | One target ID | Different target ID |
-| **Element Search** | `tab.find()` | `iframe.find()` |
-| **JavaScript Context** | `window` of main page | `window` of iframe |
-| **Origin** | Page's origin | Can be cross-origin |
-| **Storage** | Shared with page | Can be isolated |
 
-## Screenshots in IFrames
-
-!!! info "Screenshot Limitations"
-    `tab.take_screenshot()` only works on **top-level targets**. For iframe screenshots, use `element.take_screenshot()` on elements **inside** the iframe.
-
-```python
-import asyncio
-from pydoll.browser.chromium import Chrome
-
-async def iframe_screenshot():
-    async with Chrome() as browser:
-        tab = await browser.start()
-        await tab.go_to('https://example.com/iframe-page')
-        
-        iframe_element = await tab.find(tag_name='iframe')
-        frame = await tab.get_frame(iframe_element)
-        
-        # ❌ This won't work for iframes
-        # await frame.take_screenshot('frame.png')
-        
-        # ✅ Instead, screenshot an element inside the iframe
-        content = await frame.find(id='content')
-        await content.take_screenshot('iframe-content.png')
-
-asyncio.run(iframe_screenshot())
-```
+## Best practices
 
-## Learn More
+- **Use the iframe element as scope:** call `find`, `query`, or other helpers on the iframe itself.
+- **Avoid `tab.find` for inner content:** it only sees the top-level document.
+- **Remember partial results:** if you need the same iframe repeatedly, store the `WebElement` reference; Pydoll keeps the underlying context cached.
+- **Keep existing element workflows:** everything that works for a normal element (scrolling, screenshot, scripts, waiting) works for an iframe element too.
 
-For deeper understanding of iframe mechanics and CDP targets:
+## Further reading
 
-- **[Deep Dive: Tab Domain](../../deep-dive/tab-domain.md#iframe-handling)**: Technical details on iframe target resolution
-- **[Deep Dive: Browser Domain](../../deep-dive/browser-domain.md#target-management)**: How CDP manages multiple targets
-- **[Element Finding](../element-finding.md#scoped-search)**: Understanding DOM scope in element searches
+- **[Element Finding](../element-finding.md)** – covers scoped searches and chaining.
+- **[Screenshots & PDFs](screenshots-and-pdfs.md)** – details about capturing visual output.
+- **[Event System](../advanced/event-system.md)** – reactively monitor page activity, including frames.
 
-IFrames may seem complex, but Pydoll's API makes them as easy to work with as regular page elements. The key is understanding that each iframe is its own isolated Tab with a separate DOM and CDP target.
+Once you adapt to the new model, iframes become just another part of the DOM tree. Focus on building your automation logic—Pydoll takes care of the frame plumbing for you.
diff --git a/docs/en/features/automation/screenshots-and-pdfs.md b/docs/en/features/automation/screenshots-and-pdfs.md
index 507ce16f..610bf371 100644
--- a/docs/en/features/automation/screenshots-and-pdfs.md
+++ b/docs/en/features/automation/screenshots-and-pdfs.md
@@ -301,17 +301,13 @@ async def safe_screenshot():
         
         # IFrame screenshot limitation
         iframe_element = await tab.find(tag_name='iframe')
-        frame = await tab.get_frame(iframe_element)
-        
-        try:
-            # Won't work for iframes
-            await frame.take_screenshot('iframe.png')
-        except TopLevelTargetRequired:
-            print("Use element.take_screenshot() for iframe content")
-            
-            # Correct approach
-            content = await frame.find(id='content')
-            await content.take_screenshot('iframe-content.jpeg')
+
+        # This still won't work: top-level screenshots ignore iframe content
+        # await tab.take_screenshot('frame.png')
+
+        # Screenshot an element inside the iframe WebElement
+        content = await iframe_element.find(id='content')
+        await content.take_screenshot('iframe-content.png')
 ```
 
 ## Learn More
diff --git a/docs/en/features/browser-management/tabs.md b/docs/en/features/browser-management/tabs.md
index a11db401..68b4576d 100644
--- a/docs/en/features/browser-management/tabs.md
+++ b/docs/en/features/browser-management/tabs.md
@@ -82,7 +82,7 @@ asyncio.run(tab_registry_demonstration())
 ```
 
 !!! info "Browser-Managed Registry"
-    The Browser class manages a `_tabs_opened` dictionary keyed by `target_id`. When you request a tab (via `new_tab()`, `get_opened_tabs()`, or `get_frame()`), the Browser checks this registry first. If a Tab instance already exists for that `target_id`, it returns the existing instance; otherwise, it creates a new one and stores it in the registry.
+    The Browser class manages a `_tabs_opened` dictionary keyed by `target_id`. When you request a tab (via `new_tab()` or `get_opened_tabs()`), the Browser checks this registry first. If a Tab instance already exists for that `target_id`, it returns the existing instance; otherwise, it creates a new one and stores it in the registry. (IFrames no longer create Tab entries—interact with them as regular elements.)
 
 ## Creating and Managing Tabs
 
diff --git a/docs/en/features/element-finding.md b/docs/en/features/element-finding.md
index 7005976e..75e912bf 100644
--- a/docs/en/features/element-finding.md
+++ b/docs/en/features/element-finding.md
@@ -593,28 +593,15 @@ asyncio.run(practical_example())
 
 iFrames present a special challenge in browser automation because they have separate DOM contexts. Pydoll makes iframe interaction seamless:
 
-### iFrame Context Isolation
-
 ```mermaid
 flowchart TB
-    subgraph MainPage[Main Page Context]
-        MainDOM[Main Page DOM]
-        IFrameTag[iframe element]
-        MainDOM --> IFrameTag
-    end
-    
-    subgraph IFrameContext[iFrame - Separate DOM]
-        IFrameDOM[iFrame DOM]
-        IFrameElements[Elements inside iFrame]
-        IFrameDOM --> IFrameElements
-    end
-    
-    IFrameTag -.->|get_frame method| IFrameContext
-    
-    MainPage --> MainSearch[tab.find - Main DOM]
-    IFrameContext --> IFrameSearch[frame.find - iFrame DOM]
-```
+    Main[tab]
+    Frame["iframe WebElement"]
+    Content["elements inside iframe"]
 
+    Main -->|"find('iframe')"| Frame
+    Frame -->|"find('button#submit')"| Content
+```
 ```python
 import asyncio
 from pydoll.browser.chromium import Chrome
@@ -623,29 +610,25 @@ async def iframe_interaction():
     async with Chrome() as browser:
         tab = await browser.start()
         await tab.go_to('https://example.com/page-with-iframe')
-        
-        # Find the iframe element
-        iframe_element = await tab.query("iframe.embedded-content", timeout=10)
-        
-        # Get a Tab instance for the iframe's content
-        frame = await tab.get_frame(iframe_element)
-        
-        # Now use all Tab methods within the iframe context
-        iframe_button = await frame.find(tag_name="button", class_name="submit")
+
+        iframe = await tab.query("iframe.embedded-content", timeout=10)
+
+        # WebElement helpers run inside the iframe automatically
+        iframe_button = await iframe.find(tag_name="button", class_name="submit")
         await iframe_button.click()
-        
-        iframe_input = await frame.find(id="captcha-input")
+
+        iframe_input = await iframe.find(id="captcha-input")
         await iframe_input.type_text("verification-code")
-        
-        # Query within iframe
-        iframe_links = await frame.query("a", find_all=True)
-        print(f"Found {len(iframe_links)} links in iframe")
+
+        # Nested iframe? Keep chaining
+        inner_iframe = await iframe.find(tag_name="iframe")
+        download_link = await inner_iframe.find(text="Download PDF")
+        await download_link.click()
 
 asyncio.run(iframe_interaction())
 ```
-
-!!! note "iFrame Targets and Screenshots"
-    When working inside an iframe, some methods like `tab.take_screenshot()` won't work because Chrome's CDP can't capture screenshots of subtargets directly. Use `element.take_screenshot()` instead, which works inside iframes.
+!!! note "Screenshots in iframes"
+    `tab.take_screenshot()` only works on the top-level target. Capture iframe content by targeting an element inside the frame and calling `element.take_screenshot()`.
 
 ## Error Handling Strategies
 
diff --git a/docs/en/features/index.md b/docs/en/features/index.md
index c18b6602..04101d9b 100644
--- a/docs/en/features/index.md
+++ b/docs/en/features/index.md
@@ -28,7 +28,7 @@ These are the features that bring your automation to life: simulating user inter
 
 **[File Operations](automation/file-operations.md)**: File handling can be tricky in browser automation. Pydoll provides robust solutions for both uploads and downloads, with the `expect_download` context manager offering elegant handling of asynchronous download completion.
 
-**[IFrame Interaction](automation/iframes.md)**: Work seamlessly with embedded frames using the `get_frame()` method. Get a full Tab interface for iframe content, enabling you to use all of Pydoll's element finding and interaction capabilities inside frames.
+**[IFrame Interaction](automation/iframes.md)**: Treat iframes like regular elements—find the iframe and keep searching inside it. No extra targets, no extra tabs.
 
 **[Screenshots & PDF](automation/screenshots-and-pdfs.md)**: Capture visual content from your automation sessions. Whether you need full-page screenshots for visual regression testing, element-specific captures for debugging, or PDF exports for archival, Pydoll has you covered.
 
diff --git a/docs/pt/deep-dive/architecture/tab-domain.md b/docs/pt/deep-dive/architecture/tab-domain.md
index fbbe6786..d2b4ddc9 100644
--- a/docs/pt/deep-dive/architecture/tab-domain.md
+++ b/docs/pt/deep-dive/architecture/tab-domain.md
@@ -222,7 +222,7 @@ except KeyError:
     raise TopLevelTargetRequired(...)  # Guia os usuários para WebElement.take_screenshot()
 ```
 
-**Implicação de design:** Abas de Iframe (criadas via `get_frame()`) herdam todos os métodos da Aba (Tab), mas as capturas de tela falham por design. Alternativa: `WebElement.take_screenshot()` funciona para conteúdo de iframe.
+**Implicação de design:** Antes, o Pydoll criava instâncias de Tab dedicadas para iframes. Com o novo modelo, toda interação acontece no próprio `WebElement`, então capturas e outros utilitários devem ser executados nos elementos internos (por exemplo, `await iframe_element.find(...).take_screenshot()`).
 
 **Geração de PDF:** `Page.printToPDF` retorna dados codificados em base64. O Pydoll abstrai a E/S (I/O) de arquivo, mas os dados subjacentes são sempre base64 (especificação CDP).
 
diff --git a/docs/pt/deep-dive/fundamentals/iframes-and-contexts.md b/docs/pt/deep-dive/fundamentals/iframes-and-contexts.md
new file mode 100644
index 00000000..d1581b0b
--- /dev/null
+++ b/docs/pt/deep-dive/fundamentals/iframes-and-contexts.md
@@ -0,0 +1,1292 @@
+# Iframes, OOPIFs e Contextos de Execução (Análise Aprofundada)
+
+Entender como a automação de navegador lida com iframes é crucial para construir ferramentas de automação robustas. Este guia abrangente explora os fundamentos técnicos do manuseio de iframes no Pydoll, cobrindo o Document Object Model (DOM), mecânicas do Chrome DevTools Protocol (CDP), contextos de execução, mundos isolados e o sofisticado pipeline de resolução que torna a interação com iframes fluida.
+
+!!! info "Primeiro o uso prático"
+    Se você só precisa usar iframes em seus scripts de automação, comece com o guia de funcionalidades: **Funcionalidades → Automação → IFrames**.
+    Esta análise aprofundada explica as decisões de arquitetura, nuances do protocolo e detalhes de implementação interna.
+
+---
+
+## Tabela de Conteúdos
+
+1. [Fundação: O Modelo de Objeto de Documento (DOM)](#fundação-o-modelo-de-objeto-de-documento-dom)
+2. [O que são Iframes e Por que Eles Importam](#o-que-são-iframes-e-por-que-eles-importam)
+3. [O Desafio: Iframes Fora de Processo (OOPIFs)](#o-desafio-iframes-fora-de-processo-oopifs)
+4. [Protocolo Chrome DevTools e Gerenciamento de Frames](#protocolo-chrome-devtools-e-gerenciamento-de-frames)
+5. [Contextos de Execução e Mundos Isolados](#contextos-de-execução-e-mundos-isolados)
+6. [Referência de Identificadores CDP](#referência-de-identificadores-cdp)
+7. [Pipeline de Resolução do Pydoll](#pipeline-de-resolução-do-pydoll)
+8. [Roteamento de Sessão e Modo "Flattened"](#roteamento-de-sessão-e-modo-flattened)
+9. [Análise Aprofundada da Implementação](#análise-aprofundada-da-implementação)
+10. [Considerações de Performance](#considerações-de-performance)
+11. [Modos de Falha e Depuração](#modos-de-falha-e-depuração)
+
+---
+
+## Fundação: O Modelo de Objeto de Documento (DOM)
+
+Antes de mergulhar nos iframes, precisamos entender o DOM — a estrutura em árvore que representa um documento HTML na memória.
+
+### O que é o DOM?
+
+O **Modelo de Objeto de Documento** (Document Object Model) é uma interface de programação para documentos HTML e XML. Ele representa a estrutura da página como uma árvore de nós, onde cada nó corresponde a uma parte do documento:
+
+- **Nós de elemento**: Tags HTML como `<div>`, `<iframe>`, `<button>`
+- **Nós de texto**: O conteúdo de texto real
+- **Nós de atributo**: Atributos de elemento como `id`, `class`, `src`
+- **Nó do documento**: A raiz da árvore
+
+'''mermaid
+graph TD
+    Document[Documento] --> HTML[elemento html]
+    HTML --> Head[elemento head]
+    HTML --> Body[elemento body]
+    Body --> Div1[elemento div]
+    Body --> Div2[elemento div]
+    Div1 --> Text1[nó de texto: 'Olá']
+    Div2 --> Iframe[elemento iframe]
+    Iframe --> IframeDoc[documento do iframe]
+    IframeDoc --> IframeBody[body do iframe]
+    IframeBody --> IframeContent[conteúdo do iframe...]
+'''
+
+### Propriedades da Árvore DOM
+
+1. **Estrutura hierárquica**: Todo nó tem um pai (exceto o Documento) e pode ter filhos
+2. **Identificação de nós**: Nós podem ser identificados por:
+   - `nodeId`: Identificador interno dentro de um contexto de documento (domínio DOM)
+   - `backendNodeId`: Identificador estável que pode referenciar nós através de diferentes documentos
+3. **Representação viva**: Mudanças no DOM são refletidas imediatamente na árvore
+
+### Por que Isso Importa para Iframes
+
+Cada elemento `<iframe>` cria uma **árvore DOM nova e independente**. O próprio elemento iframe existe no DOM do pai, mas o conteúdo carregado no iframe tem seu próprio nó Documento completo e estrutura de árvore. Essa separação é a base de toda a complexidade dos iframes.
+
+---
+
+## O que são Iframes e Por que Eles Importam
+
+### Definição
+
+Um **iframe** (quadro em linha) é um elemento HTML (`<iframe>`) que incorpora outro documento HTML dentro da página atual. O documento incorporado mantém seu próprio contexto, incluindo:
+
+- Estrutura HTML e árvore DOM independentes
+- Ambiente de execução JavaScript separado
+- Estilização CSS própria (a menos que explicitamente compartilhada)
+- Histórico de navegação distinto
+
+'''html
+<body>
+  <h1>Página Pai</h1>
+  <iframe src="https://example.com/embedded.html" id="content-frame"></iframe>
+  <p>Mais conteúdo do pai</p>
+</body>
+'''
+
+### Casos de Uso Comuns
+
+| Caso de Uso | Descrição | Exemplo |
+|----------|-------------|---------|
+| **Widgets de terceiros** | Incorpora conteúdo externo com segurança | Formulários de pagamento, feeds de mídia social, widgets de chat |
+| **Isolamento de conteúdo** | Coloca conteúdo não confiável em sandbox | HTML gerado por usuário, anúncios |
+| **Arquitetura modular** | Componentes reutilizáveis | Widgets de dashboard, sistemas de plugins |
+| **Conteúdo de origem cruzada** | Carrega recursos de domínios diferentes | Mapas, players de vídeo, dashboards de analytics |
+
+### Modelo de Segurança: Política de Mesma Origem (Same-Origin Policy)
+
+O navegador impõe uma **Política de Mesma Origem** para iframes:
+
+- **Iframes de mesma origem**: O pai pode acessar o DOM do iframe via JavaScript (`iframe.contentDocument`)
+- **Iframes de origem cruzada**: O pai não pode acessar o DOM do iframe diretamente (restrição de segurança)
+
+Essa barreira de segurança é o motivo pelo qual ferramentas de automação precisam de mecanismos especiais (como o CDP) para interagir com o conteúdo do iframe.
+
+!!! warning "Importante para automação"
+    Automação tradicional baseada em JavaScript (como as primeiras abordagens do Selenium) não pode acessar diretamente o conteúdo de iframes de origem cruzada devido à segurança do navegador. O CDP opera em um nível mais baixo, contornando essa limitação para fins de depuração.
+
+---
+
+## O Desafio: Iframes Fora de Processo (OOPIFs)
+
+### O que são OOPIFs?
+
+O Chromium moderno usa **isolamento de site** (site isolation) para segurança e estabilidade. Isso significa que origens diferentes podem ser renderizadas em processos separados do SO. Um iframe de uma origem diferente torna-se um **Iframe Fora de Processo (OOPIF)**.
+
+'''mermaid
+graph LR
+    subgraph "Processo 1: example.com"
+        MainPage[DOM da Página Principal]
+    end
+    
+    subgraph "Processo 2: widget.com"
+        IframeDOM[DOM do Iframe]
+    end
+    
+    MainPage -.Fronteira do Processo.-> IframeDOM
+'''
+
+### Por que OOPIFs Complicam a Automação
+
+| Aspecto | Iframe no Mesmo Processo | Iframe Fora de Processo (OOPIF) |
+|--------|-------------------|-------------------------------|
+| **Acesso ao DOM** | Árvore de documento compartilhada na memória | Alvo (target) separado com seu próprio documento |
+| **Roteamento de comandos** | Conexão única | Requer anexação ao alvo e roteamento de sessão |
+| **Árvore de frames** | Todos os frames em uma árvore | Frame raiz + alvos separados para OOPIFs |
+| **Contexto JavaScript** | Mesmo contexto de execution | Contexto de execução diferente por processo |
+| **Comunicação CDP** | Comandos diretos | Comandos devem incluir `sessionId` |
+
+### A Abordagem Tradicional (Troca Manual de Contexto)
+
+Sem um manuseio sofisticado, automatizar OOPIFs requer:
+
+'''python
+# Abordagem tradicional (manual) com outras ferramentas
+main_page = browser.get_page()
+iframe_element = main_page.find_element_by_id("iframe-id")
+
+# Deve trocar manualmente o contexto
+driver.switch_to.frame(iframe_element)
+
+# Agora os comandos miram o iframe
+button = driver.find_element_by_id("button-in-iframe")
+button.click()
+
+# Deve trocar manualmente de volta
+driver.switch_to.default_content()
+'''
+
+**Problemas com esta abordagem:**
+
+1. **Carga para o desenvolvedor**: Todo iframe requer gerenciamento explícito de contexto
+2. **Iframes aninhados**: Cada nível precisa de outra troca
+3. **Detecção de OOPIF**: Difícil saber quando a anexação manual é necessária
+4. **Propenso a erros**: Esquecer de trocar de volta → comandos subsequentes falham
+5. **Não componentizável**: Funções auxiliares precisam saber seu contexto de iframe
+
+### A Solução do Pydoll: Resolução Transparente de Contexto
+
+O Pydoll elimina a troca manual de contexto resolvendo os contextos de iframe automaticamente:
+
+'''python
+# Abordagem Pydoll (sem troca manual)
+iframe = await tab.find(id="iframe-id")
+button = await iframe.find(id="button-in-iframe")
+await button.click()
+
+# Iframes aninhados? Mesmo padrão
+outer = await tab.find(id="outer-iframe")
+inner = await outer.find(tag_name="iframe")
+button = await inner.find(text="Submit")
+await button.click()
+'''
+
+A complexidade é tratada internamente. Vamos explorar como.
+
+---
+
+## Protocolo Chrome DevTools e Gerenciamento de Frames
+
+Como discutido em [Análise Aprofundada → Fundamentos → Protocolo Chrome DevTools](./cdp.md), o CDP fornece controle abrangente do navegador via comunicação WebSocket. O gerenciamento de frames é distribuído por múltiplos domínios do CDP.
+
+### Domínios CDP Relevantes
+
+#### 1. **Domínio Page**
+
+Gerencia o ciclo de vida da página, frames e navegação.
+
+**Métodos principais:**
+
+- `Page.getFrameTree()`: Retorna a estrutura hierárquica de todos os frames em uma página
+  '''json
+  {
+    "frameTree": {
+      "frame": {
+        "id": "main-frame-id",
+        "url": "https://example.com",
+        "securityOrigin": "https://example.com",
+        "mimeType": "text/html"
+      },
+      "childFrames": [
+        {
+          "frame": {
+            "id": "child-frame-id",
+            "parentId": "main-frame-id",
+            "url": "https://widget.com/embed"
+          }
+        }
+      ]
+    }
+  }
+  '''
+
+- `Page.createIsolatedWorld(frameId, worldName)`: Cria um novo contexto de execução JavaScript em um frame específico
+  '''json
+  {
+    "executionContextId": 42
+  }
+  '''
+
+**Uso no Pydoll:**
+
+'''python
+# De pydoll/elements/web_element.py
+@staticmethod
+async def _get_frame_tree_for(
+    handler: ConnectionHandler, session_id: Optional[str]
+) -> FrameTree:
+    """Pega a árvore de frames da Página para a conexão/alvo dados."""
+    command = PageCommands.get_frame_tree()
+    if session_id:
+        command['sessionId'] = session_id
+    response: GetFrameTreeResponse = await handler.execute_command(command)
+    return response['result']['frameTree']
+'''
+
+#### 2. **Domínio DOM**
+
+Fornece acesso à estrutura do DOM.
+
+**Métodos principais:**
+
+- `DOM.describeNode(objectId)`: Retorna informação detalhada sobre um nó DOM
+  '''json
+  {
+    "node": {
+      "nodeId": 123,
+      "backendNodeId": 456,
+      "nodeName": "IFRAME",
+      "frameId": "parent-frame-id",
+      "contentDocument": {
+        "frameId": "iframe-frame-id",
+        "documentURL": "https://embedded.com/page.html"
+      }
+    }
+  }
+  '''
+
+- `DOM.getFrameOwner(frameId)`: Retorna o `backendNodeId` do elemento `<iframe>` que possui um frame
+  '''json
+  {
+    "backendNodeId": 456
+  }
+  '''
+
+**Uso no Pydoll:**
+
+'''python
+# De pydoll/elements/web_element.py
+@staticmethod
+async def _owner_backend_for(
+    handler: ConnectionHandler, session_id: Optional[str], frame_id: str
+) -> Optional[int]:
+    """Pega o backendNodeId do elemento DOM que possui o frame dado."""
+    command = DomCommands.get_frame_owner(frame_id=frame_id)
+    if session_id:
+        command['sessionId'] = session_id
+    response: GetFrameOwnerResponse = await handler.execute_command(command)
+    return response.get('result', {}).get('backendNodeId')
+'''
+
+#### 3. **Domínio Target**
+
+Gerencia alvos (targets) do navegador (páginas, iframes, workers, etc.).
+
+**Métodos principais:**
+
+- `Target.getTargets()`: Lista todos os alvos disponíveis
+  '''json
+  {
+    "targetInfos": [
+      {
+        "targetId": "page-target-id",
+        "type": "page",
+        "title": "Main Page",
+        "url": "https://example.com"
+      },
+      {
+        "targetId": "iframe-target-id",
+        "type": "iframe",
+        "title": "",
+        "url": "https://widget.com/embed",
+        "parentFrameId": "main-frame-id"
+      }
+    ]
+  }
+  '''
+
+- `Target.attachToTarget(targetId, flatten)`: Anexa a um alvo para depuração
+  - Quando `flatten=true`: Retorna um `sessionId` para rotear comandos no modo "flattened"
+  - Toda comunicação acontece sobre o mesmo WebSocket, diferenciada por `sessionId`
+
+**Uso no Pydoll:**
+
+'''python
+# De pydoll/elements/web_element.py (simplificado)
+async def _resolve_oopif_by_parent(self, parent_frame_id: str, ...):
+    """Resolve um OOPIF usando o ID do frame pai."""
+    browser_handler = ConnectionHandler(...)
+    targets_response: GetTargetsResponse = await browser_handler.execute_command(
+        TargetCommands.get_targets()
+    )
+    target_infos = targets_response.get('result', {}).get('targetInfos', [])
+    
+    # Encontra alvos cujo parentFrameId bate
+    direct_children = [
+        target_info for target_info in target_infos
+        if target_info.get('parentFrameId') == parent_frame_id
+    ]
+    
+    if direct_children:
+        attach_response: AttachToTargetResponse = await browser_handler.execute_command(
+            TargetCommands.attach_to_target(
+                target_id=direct_children[0]['targetId'], 
+                flatten=True
+            )
+        )
+        attached_session_id = attach_response.get('result', {}).get('sessionId')
+        # ... usa session_id para comandos subsequentes
+'''
+
+#### 4. **Domínio Runtime**
+
+Executa JavaScript e gerencia contextos de execução.
+
+**Métodos principais:**
+
+- `Runtime.evaluate(expression, contextId)`: Avalia JavaScript em um contexto de execução específico
+- `Runtime.callFunctionOn(functionDeclaration, objectId)`: Chama uma função com um objeto específico como `this`
+
+**Uso no Pydoll para acesso ao documento do iframe:**
+
+'''python
+# De pydoll/elements/web_element.py
+async def _set_iframe_document_object_id(self, execution_context_id: int):
+    """Avalia document.documentElement no contexto do iframe e cacheia seu object id."""
+    evaluate_command = RuntimeCommands.evaluate(
+        expression='document.documentElement',
+        context_id=execution_context_id,
+    )
+    if self._iframe_context and self._iframe_context.session_id:
+        evaluate_command['sessionId'] = self._iframe_context.session_id
+    
+    evaluate_response: EvaluateResponse = await (
+        (self._iframe_context.session_handler if self._iframe_context else None)
+        or self._connection_handler
+    ).execute_command(evaluate_command)
+    
+    document_object_id = evaluate_response.get('result', {}).get('result', {}).get('objectId')
+    if self._iframe_context:
+        self._iframe_context.document_object_id = document_object_id
+'''
+
+---
+
+## Contextos de Execução e Mundos Isolados
+
+### O que é um Contexto de Execução?
+
+Um **contexto de execução** é um ambiente onde o código JavaScript é executado. Todo frame em um navegador tem pelo menos um contexto de execution. O contexto inclui:
+
+- **Objeto global** (`window` em navegadores)
+- **Cadeia de escopo**: Como variáveis são resolvidas
+- **Vínculo 'this'**: A o que `this` se refere
+- **Ambiente de variáveis**: Todas as variáveis e funções declaradas
+
+### Múltiplos Contextos por Frame
+
+Um único frame pode ter múltiplos contextos de execução:
+
+1. **Mundo principal (contexto padrão)**: Onde o JavaScript da própria página roda
+2. **Mundos isolados**: Contextos separados que share o mesmo DOM mas têm escopos globais JavaScript diferentes
+
+'''mermaid
+graph TB
+    Frame[Frame: example.com/page]
+    Frame --> MainWorld[Mundo Principal<br/>JavaScript da Página]
+    Frame --> IsolatedWorld1[Mundo Isolado 1<br/>Script de conteúdo de extensão]
+    Frame --> IsolatedWorld2[Mundo Isolado 2<br/>Automação Pydoll]
+    
+    DOM[Árvore DOM Compartilhada]
+    MainWorld -.pode acessar.-> DOM
+    IsolatedWorld1 -.pode acessar.-> DOM
+    IsolatedWorld2 -.pode acessar.-> DOM
+    
+    MainWorld -.não pode acessar.-> IsolatedWorld1
+    MainWorld -.não pode acessar.-> IsolatedWorld2
+'''
+
+### O que é um Mundo Isolado?
+
+Um **mundo isolado** é um contexto de execução JavaScript separado que:
+
+- **Compartilha o mesmo DOM**: Pode ler/modificar elementos DOM
+- **Tem um objeto global separado**: Variáveis/funções não vazam entre mundos
+- **Previne interferência**: Scripts da página não podem detectar ou interferir com scripts do mundo isolado
+
+**Origem**: Mundos isolados foram criados para extensões de navegador. Scripts de conteúdo (content scripts) rodam em mundos isolados para que possam interagir com o DOM da página sem:
+
+- Scripts da página sobrescrevendo suas variáveis
+- Serem detectados por código anti-tamper (anti-adulteração)
+- Conflitar com o JavaScript da página
+
+### Por que o Pydoll Usa Mundos Isolados para Iframes
+
+Quando o Pydoll interage com o conteúdo de um iframe, ele cria um mundo isolado no contexto desse iframe. Isso fornece:
+
+1. **Ambiente JavaScript limpo**: Sem conflitos com os scripts do próprio iframe
+2. **Comportamento consistente**: Scripts de automação funcionam independentemente de qual JavaScript o iframe roda
+3. **Anti-detecção**: O JavaScript do iframe não pode detectar facilmente a presença do Pydoll
+4. **Avaliação segura**: Código de automação não pode acidentalmente disparar lógica da página
+
+**Implementação:**
+
+'''python
+# De pydoll/elements/web_element.py
+@staticmethod
+async def _create_isolated_world_for_frame(
+    frame_id: str,
+    handler: ConnectionHandler,
+    session_id: Optional[str],
+) -> int:
+    """Cria um mundo isolado (Page.createIsolatedWorld) para o frame dado."""
+    create_command = PageCommands.create_isolated_world(
+        frame_id=frame_id,
+        world_name=f'pydoll::iframe::{frame_id}',
+        grant_universal_access=True,
+    )
+    if session_id:
+        create_command['sessionId'] = session_id
+    
+    create_response: CreateIsolatedWorldResponse = await handler.execute_command(
+        create_command
+    )
+    execution_context_id = create_response.get('result', {}).get('executionContextId')
+    if not execution_context_id:
+        raise InvalidIFrame('Incapaz de criar mundo isolado para o iframe')
+    return execution_context_id
+'''
+
+O parâmetro `grant_universal_access=True` permite ao mundo isolado:
+
+- Acessar frames de origem cruzada (normalmente bloqueado pela política de mesma origem)
+- Realizar operações privilegiadas necessárias para automação
+
+!!! tip "Mundos isolados na prática"
+    Toda vez que você usa `await iframe.find(...)`, o Pydoll avalia a consulta do seletor em um mundo isolado criado especificamente para aquele iframe. Isso garante que sua lógica de automação nunca conflite com o JavaScript do próprio iframe, e o iframe não possa detectar ou bloquear sua automação.
+
+---
+
+## Referência de Identificadores CDP
+
+Entender os identificadores do CDP é crucial para o manuseio de iframes. Aqui está uma referência abrangente:
+
+| Identificador | Domínio | Escopo | Propósito | Exemplo de Uso no Pydoll |
+|------------|--------|-------|---------|----------------------|
+| **`nodeId`** | DOM | Local do Documento | Identifica um nó DOM dentro de um contexto de documento específico | Operações internas do CDP; não é estável entre navegações |
+| **`backendNodeId`** | DOM | Estável entre documentos | Identificador estável para um nó DOM; pode mapear frames para elementos donos | Usado para parear elementos iframe com IDs de frame via `DOM.getFrameOwner` |
+| **`frameId`** | Page | Frame | Identifica um frame na árvore de frames da página | Usado para especificar qual frame para `Page.createIsolatedWorld` e travessia da árvore de frames |
+| **`targetId`** | Target | Global | Identifica um alvo (target) de depuração (página, iframe, worker, etc.) | Usado para `Target.attachToTarget` para conectar a OOPIFs |
+| **`sessionId`** | Target | Específico do Alvo | Roteia comandos para um alvo específico no modo "flattened" | Injetado em comandos para roteá-los ao OOPIF correto |
+| **`executionContextId`** | Runtime | Frame + Mundo | Identifica um contexto de execução JavaScript (incluindo mundos isolados) | Retornado por `Page.createIsolatedWorld`; usado em `Runtime.evaluate` |
+| **`objectId`** | Runtime | Contexto de Execução | Referência de objeto remoto (ex: elemento DOM, função, objeto) | Referência ao `document.documentElement` do iframe para consultas relativas |
+
+### Relacionamentos dos Identificadores
+
+Veja como os identificadores se relacionam durante a resolução do iframe:
+
+'''
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Fluxo de Resolução                              │
+└─────────────────────────────────────────────────────────────────────────┘
+
+1. Início: Elemento <iframe>
+   └─ backendNodeId: 789
+   
+2. Encontrar Frame ─────────[DOM.getFrameOwner]──────────────┐
+   └─ frameId: abc-123                                       │
+                                                             │
+3. OOPIF? Checar Origem ────[Origem diferente detectada]─────┤
+   └─ targetId: xyz-456                                      │
+                                                             │
+4. Anexar ao Alvo ──────────[Target.attachToTarget]──────────┤
+   └─ sessionId: session-789                                 │
+                                                             │
+5. Criar Mundo Isolado ─────[Page.createIsolatedWorld]───────┤
+   └─ executionContextId: 42                                 │
+                                                             │
+6. Obter Documento ─────────[Runtime.evaluate]───────────────┘
+   └─ objectId: obj-999
+'''
+
+**Pontos chave de transformação:**
+
+| De | Método | Para | Propósito |
+|------|--------|-----|---------|
+| `backendNodeId` | `DOM.getFrameOwner` | `frameId` | Encontrar qual frame é dono do elemento iframe |
+| `targetId` | `Target.attachToTarget(flatten=true)` | `sessionId` | Conectar ao OOPIF para roteamento de comandos |
+| `frameId` | `Page.createIsolatedWorld` | `executionContextId` | Criar ambiente JavaScript seguro |
+| `executionContextId` | `Runtime.evaluate('document.documentElement')` | `objectId` | Obter referência ao documento do iframe |
+
+### Representação no Código do Pydoll
+
+'''python
+# De pydoll/elements/web_element.py
+@dataclass
+class _IFrameContext:
+    """Encapsula todos os identificadores e informação de roteamento para um iframe."""
+    frame_id: str                                   # frameId: identifica o frame
+    document_url: Optional[str] = None              # URL carregada do frame
+    execution_context_id: Optional[int] = None      # executionContextId: mundo isolado
+    document_object_id: Optional[str] = None        # objectId: document.documentElement
+    session_handler: Optional[ConnectionHandler] = None  # para alvos OOPIF
+    session_id: Optional[str] = None                # sessionId: roteia comandos para OOPIF
+'''
+
+Este dataclass é cacheado em cada `WebElement` representando um iframe, permitindo o roteamento automático de todas as operações subsequentes.
+
+---
+
+## Pipeline de Resolução do Pydoll
+
+Quando você acessa um iframe no Pydoll (ex: `await iframe.find(...)`), um elaborado pipeline de resolução é executado nos bastidores. Esta seção detalha cada passo.
+
+### Fluxo de Alto Nível
+
+'''mermaid
+sequenceDiagram
+    participant User as Usuário
+    participant WebElement
+    participant Pipeline as Pipeline de Resolução
+    participant CDP
+    
+    Usuário->>WebElement: iframe.find(id='button')
+    WebElement->>WebElement: Verifica se contexto do iframe está em cache
+    alt Contexto não cacheado
+        WebElement->>Pipeline: _ensure_iframe_context()
+        Pipeline->>CDP: DOM.describeNode(iframe)
+        CDP-->>Pipeline: Info do Nó (frameId?, backendNodeId, etc.)
+        
+        alt frameId não está na info do nó
+            Pipeline->>Pipeline: _resolve_frame_by_owner()
+            Pipeline->>CDP: Page.getFrameTree()
+            CDP-->>Pipeline: Árvore de frames
+            Pipeline->>CDP: DOM.getFrameOwner(cada frame)
+            CDP-->>Pipeline: backendNodeId
+            Pipeline->>Pipeline: Compara backendNodeId para achar frameId
+        end
+        
+        alt frameId ainda faltando (OOPIF)
+            Pipeline->>Pipeline: _resolve_oopif_by_parent()
+            Pipeline->>CDP: Target.getTargets()
+            CDP-->>Pipeline: Lista de alvos
+            Pipeline->>CDP: Target.attachToTarget(targetId, flatten=true)
+            CDP-->>Pipeline: sessionId
+            Pipeline->>CDP: Page.getFrameTree(sessionId)
+            CDP-->>Pipeline: Árvore de frames do OOPIF
+        end
+        
+        Pipeline->>CDP: Page.createIsolatedWorld(frameId)
+        CDP-->>Pipeline: executionContextId
+        
+        Pipeline->>CDP: Runtime.evaluate('document.documentElement', contextId)
+        CDP-->>Pipeline: objectId (referência do documento)
+        
+        Pipeline->>WebElement: Cacheia _IFrameContext
+    end
+    
+    WebElement->>WebElement: Usa contexto cacheado para find()
+    WebElement-->>Usuário: Elemento Button (com contexto)
+'''
+
+### Análise Aprofundada Passo a Passo
+
+#### **Passo 1: Descrever o Elemento Iframe**
+
+**Objetivo**: Extrair metadados do elemento DOM `<iframe>`.
+
+**Método**: `DOM.describeNode(objectId=iframe_object_id)`
+
+**O que obtemos**:
+
+- `backendNodeId`: Identificador estável para o elemento iframe
+- `frameId` (de `contentDocument`): Se o conteúdo do iframe já está carregado e no mesmo processo
+- `documentURL`: A URL carregada no iframe
+- `parentFrameId` (do campo `frameId` no nó): O frame contendo este elemento iframe
+
+**Código**:
+
+'''python
+# De pydoll/elements/web_element.py
+async def _ensure_iframe_context(self) -> None:
+    """Inicializa e cacheia informação de contexto para elementos iframe."""
+    node_info = await self._describe_node(object_id=self._object_id)
+    base_handler, base_session_id = self._get_base_session()
+    frame_id, document_url, parent_frame_id, backend_node_id = self._extract_frame_metadata(
+        node_info
+    )
+    # ... continua resolução
+'''
+
+**Auxiliar**:
+
+'''python
+@staticmethod
+def _extract_frame_metadata(
+    node_info: Node,
+) -> tuple[Optional[str], Optional[str], Optional[str], Optional[int]]:
+    """Extrai metadados relacionados a iframe de um Nó DOM.describeNode."""
+    content_document = node_info.get('contentDocument') or {}
+    parent_frame_id = node_info.get('frameId')
+    backend_node_id = node_info.get('backendNodeId')
+    frame_id = content_document.get('frameId')
+    document_url = (
+        content_document.get('documentURL')
+        or content_document.get('baseURL')
+        or node_info.get('documentURL')
+        or node_info.get('baseURL')
+    )
+    return frame_id, document_url, parent_frame_id, backend_node_id
+'''
+
+**Resultado**:
+
+- **Se `frame_id` está presente**: Ótimo! O iframe está no mesmo processo; prossiga para o Passo 4.
+- **Se `frame_id` está faltando**: O iframe pode ser um OOPIF ou não totalmente carregado; prossiga para o Passo 2.
+
+---
+
+#### **Passo 2: Resolver Frame pelo Dono (comparação de backendNodeId)**
+
+**Objetivo**: Encontrar o `frameId` comparando o `backendNodeId` do elemento iframe com os donos de frames na árvore de frames.
+
+**Estratégia**:
+
+1. Buscar a árvore de frames da página (`Page.getFrameTree`)
+2. Para cada frame na árvore, chamar `DOM.getFrameOwner(frameId)` para obter o `backendNodeId` do elemento iframe dono
+3. Comparar com o `backendNodeId` do nosso iframe
+4. Quando eles baterem, encontramos o `frameId` correto
+
+**Código**:
+
+'''python
+# De pydoll/elements/web_element.py
+async def _resolve_frame_by_owner(
+    self,
+    base_handler: ConnectionHandler,
+    base_session_id: Optional[str],
+    backend_node_id: int,
+    current_document_url: Optional[str],
+) -> tuple[Optional[str], Optional[str]]:
+    """Resolve um ID de frame e URL comparando o backend_node_id do dono."""
+    owner_frame_id, owner_url = await self._find_frame_by_owner(
+        base_handler, base_session_id, backend_node_id
+    )
+    if not owner_frame_id:
+        return None, current_document_url
+    return owner_frame_id, owner_url or current_document_url
+
+async def _find_frame_by_owner(
+    self, handler: ConnectionHandler, session_id: Optional[str], backend_node_id: int
+) -> tuple[Optional[str], Optional[str]]:
+    """Encontra um frame comparando o backend_node_id do dono do elemento <iframe>."""
+    frame_tree = await self._get_frame_tree_for(handler, session_id)
+    for frame_node in WebElement._walk_frames(frame_tree):
+        candidate_frame_id = frame_node.get('id', '')
+        if not candidate_frame_id:
+            continue
+        owner_backend_id = await self._owner_backend_for(
+            handler, session_id, candidate_frame_id
+        )
+        if owner_backend_id == backend_node_id:
+            return candidate_frame_id, frame_node.get('url')
+    return None, None
+'''
+
+**Por que isso é necessário**:
+
+- `DOM.describeNode` às vezes não inclui o `contentDocument.frameId` para iframes de origem cruzada ou carregados tardiamente
+- A árvore de frames sempre contém todos os frames (mesmo OOPIFs), então podemos achá-lo indiretamente
+
+**Resultado**:
+
+- **Se `frameId` encontrado**: Prossiga para o Passo 4.
+- **Se ainda não encontrado**: O iframe é provavelmente um OOPIF em um alvo separado; prossiga para o Passo 3.
+
+---
+
+#### **Passo 3: Resolver OOPIF pelo Frame Pai**
+
+**Objetivo**: Para Iframes Fora de Processo, encontrar o alvo (target), anexar a ele, e obter o `frameId` da árvore de frames do alvo.
+
+**Estratégia**:
+
+**3a. Busca por alvo filho direto**:
+
+1. Chamar `Target.getTargets()` para listar todos os alvos de depuração
+2. Filtrar alvos onde `type` é `"iframe"` ou `"page"` e `parentFrameId` bate com nosso frame pai
+3. Se encontrado, anexar àquele alvo com `Target.attachToTarget(targetId, flatten=true)`
+4. A resposta inclui um `sessionId`
+5. Buscar `Page.getFrameTree(sessionId)` para aquele alvo
+6. O frame raiz desta árvore é o frame do nosso iframe
+
+**3b. Fallback: Escanear todos os alvos**:
+
+1. Iterar todos os alvos iframe/page
+2. Anexar a cada um e buscar sua árvore de frames
+3. Procurar por um frame filho cujo `parentId` bate com nosso frame pai
+4. **OU** checar se o dono do frame raiz (via `DOM.getFrameOwner`) bate com o `backendNodeId` do nosso iframe
+
+**Código**:
+
+'''python
+# De pydoll/elements/web_element.py
+async def _resolve_oopif_by_parent(
+    self,
+    parent_frame_id: str,
+    backend_node_id: Optional[int],
+) -> tuple[Optional[ConnectionHandler], Optional[str], Optional[str], Optional[str]]:
+    """Resolve um OOPIF usando o ID do frame pai."""
+    browser_handler = ConnectionHandler(
+        connection_port=self._connection_handler._connection_port
+    )
+    targets_response: GetTargetsResponse = await browser_handler.execute_command(
+        TargetCommands.get_targets()
+    )
+    target_infos = targets_response.get('result', {}).get('targetInfos', [])
+    
+    # Estratégia 3a: Filhos diretos
+    direct_children = [
+        target_info
+        for target_info in target_infos
+        if target_info.get('type') in {'iframe', 'page'}
+        and target_info.get('parentFrameId') == parent_frame_id
+    ]
+    if direct_children:
+        attach_response: AttachToTargetResponse = await browser_handler.execute_command(
+            TargetCommands.attach_to_target(
+                target_id=direct_children[0]['targetId'], flatten=True
+            )
+        )
+        attached_session_id = attach_response.get('result', {}).get('sessionId')
+        if attached_session_id:
+            frame_tree = await self._get_frame_tree_for(browser_handler, attached_session_id)
+            root_frame = (frame_tree or {}).get('frame', {})
+            return (
+                browser_handler,
+                attached_session_id,
+                root_frame.get('id'),
+                root_frame.get('url'),
+            )
+    
+    # Estratégia 3b: Escanear todos os alvos
+    for target_info in target_infos:
+        if target_info.get('type') not in {'iframe', 'page'}:
+            continue
+        attach_response = await browser_handler.execute_command(
+            TargetCommands.attach_to_target(
+                target_id=target_info.get('targetId', ''), flatten=True
+            )
+        )
+        attached_session_id = attach_response.get('result', {}).get('sessionId')
+        if not attached_session_id:
+            continue
+        
+        frame_tree = await self._get_frame_tree_for(browser_handler, attached_session_id)
+        
+        # Checa por filho com parentId correspondente
+        child_frame_id = WebElement._find_child_by_parent(frame_tree, parent_frame_id)
+        if child_frame_id:
+            return browser_handler, attached_session_id, child_frame_id, None
+        
+        # Checa se o dono do frame raiz bate com nosso backendNodeId
+        root_frame_id = (frame_tree or {}).get('frame', {}).get('id', '')
+        if not root_frame_id or backend_node_id is None:
+            continue
+        owner_backend_id = await self._owner_backend_for(
+            self._connection_handler, None, root_frame_id
+        )
+        if owner_backend_id == backend_node_id:
+            return browser_handler, attached_session_id, root_frame_id, None
+    
+    return None, None, None, None
+'''
+
+**Resultado**:
+
+- **Se OOPIF resolvido**: Agora temos `sessionId`, `session_handler`, e `frameId`; prossiga para o Passo 4.
+- **Se resolução falhar**: Lança exceção `InvalidIFrame` (tratada em `_ensure_iframe_context`).
+
+---
+
+#### **Passo 4: Criar Mundo Isolado**
+
+**Objetivo**: Criar um contexto de execução JavaScript separado no frame resolvido.
+
+**Método**: `Page.createIsolatedWorld(frameId, worldName='pydoll::iframe::<frameId>', grantUniversalAccess=true)`
+
+**Parâmetros**:
+- `frameId`: O frame onde o mundo isolado é criado
+- `worldName`: Identificador para o mundo (útil para depuração)
+- `grantUniversalAccess`: Permite acesso de origem cruzada (necessário para automação)
+
+**Resposta**: `{ executionContextId: 42 }`
+
+**Código**:
+
+'''python
+# De pydoll/elements/web_element.py
+@staticmethod
+async def _create_isolated_world_for_frame(
+    frame_id: str,
+    handler: ConnectionHandler,
+    session_id: Optional[str],
+) -> int:
+    """Cria um mundo isolado para o frame dado."""
+    create_command = PageCommands.create_isolated_world(
+        frame_id=frame_id,
+        world_name=f'pydoll::iframe::{frame_id}',
+        grant_universal_access=True,
+    )
+    if session_id:
+        create_command['sessionId'] = session_id
+    create_response: CreateIsolatedWorldResponse = await handler.execute_command(create_command)
+    execution_context_id = create_response.get('result', {}).get('executionContextId')
+    if not execution_context_id:
+        raise InvalidIFrame('Incapaz de criar mundo isolado para o iframe')
+    return execution_context_id
+'''
+
+**Por que mundo isolado**:
+
+- **Isolamento**: Nosso JavaScript de automação não interfere com o JavaScript do iframe
+- **Anti-detecção**: O iframe não pode detectar nossa presença facilmente
+- **Consistência**: Comportamento é previsível independentemente do ambiente de script do iframe
+
+**Resultado**: Temos um `executionContextId` para rodar JavaScript no iframe.
+
+---
+
+#### **Passo 5: Fixar o Documento do Iframe como um Objeto Runtime**
+
+**Objetivo**: Obter uma referência `objectId` ao `document.documentElement` do iframe (o elemento `<html>` do iframe).
+
+**Método**: `Runtime.evaluate(expression='document.documentElement', contextId=executionContextId)`
+
+**Por que precisamos disso**:
+
+- Para executar **consultas relativas** (como `element.querySelector()`) dentro do iframe
+- O `objectId` permite usar `Runtime.callFunctionOn(objectId, ...)` com `this` vinculado ao documento do iframe
+
+**Código**:
+
+'''python
+# De pydoll/elements/web_element.py
+async def _set_iframe_document_object_id(self, execution_context_id: int) -> None:
+    """Avalia document.documentElement no contexto do iframe e cacheia seu object id."""
+    evaluate_command = RuntimeCommands.evaluate(
+        expression='document.documentElement',
+        context_id=execution_context_id,
+    )
+    if self._iframe_context and self._iframe_context.session_id:
+        evaluate_command['sessionId'] = self._iframe_context.session_id
+    evaluate_response: EvaluateResponse = await (
+        (self._iframe_context.session_handler if self._iframe_context else None)
+        or self._connection_handler
+    ).execute_command(evaluate_command)
+    result_object = evaluate_response.get('result', {}).get('result', {})
+    document_object_id = result_object.get('objectId')
+    if not document_object_id:
+        raise InvalidIFrame('Incapaz de obter referência do documento para o iframe')
+    if self._iframe_context:
+        self._iframe_context.document_object_id = document_object_id
+'''
+
+**Resultado**: O `_IFrameContext` está agora totalmente populado e cacheado no `WebElement`.
+
+---
+
+#### **Passo 6: Cachear e Propagar Contexto**
+
+**Objetivo**: Armazenar o contexto resolvido no elemento iframe e propagá-lo para todos os elementos filhos encontrados dentro do iframe.
+
+**Cacheando**:
+
+'''python
+# De pydoll/elements/web_element.py
+def _init_iframe_context(
+    self,
+    frame_id: str,
+    document_url: Optional[str],
+    session_handler: Optional[ConnectionHandler],
+    session_id: Optional[str],
+) -> None:
+    """Inicializa e cacheia contexto de iframe neste elemento."""
+    self._iframe_context = _IFrameContext(frame_id=frame_id, document_url=document_url)
+    # Limpa atributos de roteamento (estes eram para iframes aninhados)
+    if hasattr(self, '_routing_session_handler'):
+        delattr(self, '_routing_session_handler')
+    if hasattr(self, '_routing_session_id'):
+        delattr(self, '_routing_session_id')
+    # Armazena roteamento OOPIF se necessário
+    if session_handler and session_id:
+        self._iframe_context.session_handler = session_handler
+        self._iframe_context.session_id = session_id
+'''
+
+**Propagação** (ao encontrar elementos dentro do iframe):
+
+'''python
+# De pydoll/elements/mixins/find_elements_mixin.py
+def _apply_iframe_context_to_element(
+    self, element: WebElement, iframe_context: _IFrameContext | None
+) -> None:
+    """Propaga contexto de iframe para o elemento recém-criado."""
+    if not iframe_context:
+        return
+    
+    # Se o elemento filho também é um iframe, configura roteamento
+    if getattr(element, 'is_iframe', False):
+        element._routing_session_handler = (
+            iframe_context.session_handler or self._connection_handler
+        )
+        element._routing_session_id = iframe_context.session_id
+        element._routing_parent_frame_id = iframe_context.frame_id
+        return
+    
+    # Caso contrário, injeta o contexto do iframe pai
+    element._iframe_context = iframe_context
+'''
+
+**Por que propagação importa**:
+
+- Elementos encontrados dentro de um iframe herdam o contexto do iframe
+- Isso garante que operações subsequentes (clicar, digitar, encontrar elementos aninhados) automaticamente usem o roteamento correto
+- Iframes aninhados recebem informação de roteamento para que possam resolver seu próprio contexto relativo ao iframe pai
+
+---
+
+## Roteamento de Sessão e Modo "Flattened"
+
+### O Modelo de Sessão "Flattened"
+
+Como discutido em [Análise Aprofundada → Fundamentos → CDP](./cdp.md), o CDP tradicional usa conexões WebSocket separadas para cada alvo. O **Modo "Flattened"** (unificado) é uma otimização onde todos os alvos compartilham uma única conexão WebSocket, com comandos roteados usando um `sessionId`.
+
+'''mermaid
+graph TB
+    subgraph "Modo Tradicional"
+        WS1[WebSocket 1] --> MainPage[Alvo Página Principal]
+        WS2[WebSocket 2] --> Iframe1[Alvo OOPIF 1]
+        WS3[WebSocket 3] --> Iframe2[Alvo OOPIF 2]
+    end
+    
+    subgraph "Modo Flattened"
+        WS[WebSocket Único] --> Router{Roteador CDP}
+        Router -->|sessionId: null| MainPage2[Alvo Página Principal]
+        Router -->|sessionId: session-1| Iframe3[Alvo OOPIF 1]
+        Router -->|sessionId: session-2| Iframe4[Alvo OOPIF 2]
+    end
+'''
+
+### Como Funciona o Roteamento de Sessão
+
+**Ao anexar a um OOPIF**:
+
+'''python
+response = await handler.execute_command(
+    TargetCommands.attach_to_target(targetId="iframe-target-id", flatten=True)
+)
+session_id = response['result']['sessionId']  # ex: "8E6C...-1234"
+'''
+
+**Ao enviar um comando para aquele OOPIF**:
+
+'''python
+command = PageCommands.get_frame_tree()
+command['sessionId'] = 'session-1'  # Roteia para o OOPIF
+response = await handler.execute_command(command)
+'''
+
+A implementação CDP do navegador roteia o comando para o alvo correto baseado no `sessionId`.
+
+### Roteamento de Comandos do Pydoll
+
+Todo comando enviado por elementos Pydoll é automaticamente roteado para o alvo correto:
+
+'''python
+# De pydoll/elements/mixins/find_elements_mixin.py
+def _resolve_routing(self) -> tuple[ConnectionHandler, Optional[str]]:
+    """Resolve handler e sessionId para o contexto atual."""
+    # Verifica se elemento tem um contexto iframe com roteamento OOPIF
+    iframe_context = getattr(self, '_iframe_context', None)
+    if iframe_context and getattr(iframe_context, 'session_handler', None):
+        return iframe_context.session_handler, getattr(iframe_context, 'session_id', None)
+    
+    # Verifica se elemento herdou roteamento de um iframe pai
+    routing_handler = getattr(self, '_routing_session_handler', None)
+    if routing_handler is not None:
+        return routing_handler, getattr(self, '_routing_session_id', None)
+    
+    # Padrão: usa a conexão principal da aba
+    return self._connection_handler, None
+
+async def _execute_command(
+    self, command: Command[T_CommandParams, T_CommandResponse]
+) -> T_CommandResponse:
+    """Executa comando CDP via handler resolvido (timeout 60s)."""
+    handler, session_id = self._resolve_routing()
+    if session_id:
+        command['sessionId'] = session_id
+    return await handler.execute_command(command, timeout=60)
+'''
+
+**Lógica de roteamento**:
+
+1. **Elemento dentro de iframe OOPIF**: Usa `iframe_context.session_id` e `iframe_context.session_handler`
+2. **Iframe aninhado (filho de OOPIF)**: Usa `_routing_session_id` e `_routing_session_handler` herdados
+3. **Elemento regular ou iframe no mesmo processo**: Usa conexão principal (`_connection_handler`), sem `sessionId`
+
+### Tipagem de Comando Estendida
+
+Para tornar `sessionId` seguro em termos de tipo (type-safe), o Pydoll estendeu o `Command` TypedDict:
+
+'''python
+# De pydoll/protocol/base.py
+class Command(TypedDict, Generic[T_CommandParams, T_CommandResponse]):
+    """Estrutura base para todos os comandos."""
+    id: NotRequired[int]
+    method: str
+    params: NotRequired[T_CommandParams]
+    sessionId: NotRequired[str]  # Adicionado para roteamento de sessão flattened
+'''
+
+Isso permite que checadores de tipo (type-checkers) reconheçam `command['sessionId'] = '...'` como válido sem suprimir avisos de tipo.
+
+---
+
+## Considerações de Performance
+
+### Estratégia de Cache
+
+**O primeiro acesso é caro**:
+
+- `DOM.describeNode`: 1 ida e volta (round-trip)
+- Recuperação da árvore de frames: 1+ idas e voltas (principal + alvos OOPIF)
+- `DOM.getFrameOwner` por frame: N idas e voltas (no pior caso)
+- `Target.getTargets` + anexações: 1 + M idas e voltas (M = número de alvos OOPIF)
+- `Page.createIsolatedWorld`: 1 ida e volta
+- `Runtime.evaluate` (documento): 1 ida e volta
+
+**Total**: Potencialmente 5-20+ idas e voltas dependendo da estrutura da página.
+
+**Acessos subsequentes são O(1)**:
+
+- `iframe_context` é cacheado na instância `WebElement`
+- Acessar `await iframe.iframe_context` múltiplas vezes retorna o valor cacheado imediatamente
+- Todos os elementos encontrados dentro do iframe herdam o contexto (sem re-resolução)
+
+### Otimização: Busca de Alvo "Filho Direto"
+
+Em `_resolve_oopif_by_parent`, o Pydoll primeiro checa por filhos diretos por `parentFrameId`:
+
+'''python
+direct_children = [
+    target_info
+    for target_info in target_infos
+    if target_info.get('type') in {'iframe', 'page'}
+    and target_info.get('parentFrameId') == parent_frame_id
+]
+if direct_children:
+    # Anexa hatchery, pula o escaneamento de todos os alvos
+'''
+
+**Por que isso ajuda**:
+
+- A maioria dos OOPIFs tem `parentFrameId` definido corretamente
+- Evita anexar a cada alvo especulativamente
+- Reduz idas e voltas de O(alvos) para O(1) no caso comum
+
+### Resolução Paralela Assíncrona (Melhoria Futura)
+
+Atualmente, a correspondência de dono de frame é sequencial (checa cada frame um por um). Uma otimização futura poderia paralelizar:
+
+'''python
+# Atual (sequencial)
+for frame_node in frames:
+    owner = await self._owner_backend_for(...)
+    if owner == backend_node_id:
+        return frame_node['id']
+
+# Potencial (paralelo)
+results = await asyncio.gather(*(
+    self._owner_backend_for(..., frame['id'])
+    for frame in frames
+))
+for i, owner in enumerate(results):
+    if owner == backend_node_id:
+        return frames[i]['id']
+'''
+
+Isso reduziria a latência de `N * RTT` para `RTT` (onde RTT = tempo de ida e volta).
+
+---
+
+## Modos de Falha e Depuração
+
+### Cenários Comuns de Falha
+
+#### 1. **InvalidIFrame: Incapaz de resolver frameId**
+
+**Causa**:
+
+- O iframe é criado dinamicamente e não inicializou completamente
+- O iframe está em sandbox com políticas restritivas
+- Problemas de rede atrasaram o carregamento do iframe
+
+**Soluções**:
+
+- **Esperar pelo iframe**: Use `await tab.find(id='iframe', timeout=10)` com um timeout
+- **Verificar atributo sandbox**: Sandbox restritivo (`<iframe sandbox>`) pode bloquear algumas operações CDP
+- **Estratégia de retentativa**: Implementar lógica de retentativa com backoff exponencial
+
+**Depuração**:
+
+'''python
+try:
+    iframe = await tab.find(id='problem-iframe')
+    context = await iframe.iframe_context
+except InvalidIFrame as e:
+    # Inspeciona o que temos
+    node_info = await iframe._describe_node(object_id=iframe._object_id)
+    print(f"Info do nó: {node_info}")
+    
+    # Checa árvore de frames manualmente
+    frame_tree = await WebElement._get_frame_tree_for(tab._connection_handler, None)
+    print(f"Árvore de frames: {frame_tree}")
+'''
+
+#### 2. **InvalidIFrame: Incapaz de criar mundo isolado**
+
+**Causa**:
+
+- Frame foi destruído/navegou para longe entre os passos de resolução
+- Bug do Chrome (raro)
+
+**Soluções**:
+
+- **Re-resolver contexto**: Limpar contexto cacheado e re-acessar
+- **Verificar navegação**: Garantir que o iframe não esteja navegando durante a resolução
+
+**Depuração**:
+
+'''python
+# Limpa cache e retenta
+iframe._iframe_context = None
+context = await iframe.iframe_context
+'''
+
+#### 3. **InvalidIFrame: Incapaz de obter referência do documento**
+
+**Causa**:
+
+- O mundo isolado foi criado mas o documento não está pronto
+- O frame está prestes a navegar
+
+**Soluções**:
+
+- Esperar pelo carregamento do frame: Usar eventos Page para detectar `Page.frameNavigated` ou `Page.loadEventFired`
+- Retentar com um pequeno atraso
+
+#### 4. **Falhas de roteamento de sessão (comando expira ou retorna erro)**
+
+**Causa**:
+
+- Alvo OOPIF foi destacado (página navegou, iframe removido)
+- `sessionId` está obsoleto
+
+**Soluções**:
+
+- **Re-anexar ao alvo**: Criar um novo `ConnectionHandler` e re-resolver OOPIF
+- **Validar alvo**: Chamar `Target.getTargets()` para checar se o alvo ainda existe
+
+**Depuração**:
+
+'''python
+# Checa se sessão ainda é válida
+targets = await handler.execute_command(TargetCommands.get_targets())
+active_sessions = [t['targetId'] for t in targets['result']['targetInfos']]
+print(f"Alvos ativos: {active_sessions}")
+
+if iframe._iframe_context and iframe._iframe_context.session_id:
+    print(f"Nossa sessão: {iframe._iframe_context.session_id}")
+'''
+
+### Ferramentas de Diagnóstico
+
+#### Habilitar logs do CDP
+
+'''python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger('pydoll')
+logger.setLevel(logging.DEBUG)
+'''
+
+Isso registra todos os comandos e respostas CDP, útil para rastrear os passos de resolução do iframe.
+
+#### Inspecionar contexto do iframe
+
+'''python
+iframe = await tab.find(id='my-iframe')
+ctx = await iframe.iframe_context
+
+print(f"Frame ID: {ctx.frame_id}")
+print(f"Document URL: {ctx.document_url}")
+print(f"Execution Context ID: {ctx.execution_context_id}")
+print(f"Document Object ID: {ctx.document_object_id}")
+print(f"Session ID (OOPIF): {ctx.session_id}")
+print(f"Session Handler: {ctx.session_handler}")
+'''
+
+---
+
+## Conclusão
+
+O manuseio de iframes do Pydoll representa uma implementação sofisticada das capacidades de gerenciamento de frames do CDP. Ao entender:
+
+- **O DOM**: Estrutura em árvore e identificação de nós
+- **Iframes**: Contextos de documento independentes e barreiras de segurança
+- **OOPIFs**: Isolamento de site e arquitetura baseada em alvos
+- **Domínios CDP**: Coordenação de Page, DOM, Target, Runtime
+- **Contextos de Execução**: Mundos isolados para automação limpa
+- **Identificadores**: Relacionamentos entre backendNodeId, frameId, targetId, sessionId, executionContextId, objectId
+- **Pipeline de resolução**: Estratégia de fallback em múltiplos estágios para encontrar frames
+- **Roteamento de sessão**: Modo "flattened" e roteamento automático de comandos
+
+você pode apreciar por que a troca manual de contexto é eliminada. A complexidade é real, mas o Pydoll a abstrai por trás de uma API simples e intuitiva:
+
+'''python
+iframe = await tab.find(id='login-frame')
+username = await iframe.find(name='username')
+await username.type_text('user@example.com')
+'''
+
+Três linhas. Sem troca de contexto. Sem anexar alvos. Sem gerenciamento de sessão. Apenas funciona.
+
+---
+
+## Leitura Adicional
+
+- **Especificação do CDP**: [Chrome DevTools Protocol - Domínio Page](https://chromedevtools.github.io/devtools-protocol/tot/Page/)
+- **Especificação do CDP**: [Chrome DevTools Protocol - Domínio DOM](https://chromedevtools.github.io/devtools-protocol/tot/DOM/)
+- **Especificação do CDP**: [Chrome DevTools Protocol - Domínio Target](https://chromedevtools.github.io/devtools-protocol/tot/Target/)
+- **Especificação do CDP**: [Chrome DevTools Protocol - Domínio Runtime](https://chromedevtools.github.io/devtools-protocol/tot/Runtime/)
+- **Isolamento de Site do Chromium**: [Site Isolation - The Chromium Projects](https://www.chromium.org/Home/chromium-security/site-isolation/)
+- **Scripts de Conteúdo e Mundos Isolados**: [Chrome Extensions - Content Scripts](https://developer.chrome.com/docs/extensions/mv3/content_scripts/)
+- **Documentação do Pydoll**: [Análise Aprofundada → Fundamentos → Protocolo Chrome DevTools](./cdp.md)
+- **Documentação do Pydoll**: [Funcionalidades → Automação → IFrames](../../features/automation/iframes.md)
+
+---
+
+!!! tip "Filosofia de Design"
+    O objetivo do manuseio de iframes do Pydoll é a **automação ergonômica**: escreva código como se iframes não existissem, e deixe a biblioteca lidar com a complexidade. Esta análise aprofundada mostrou o que acontece nos bastidores—mas você nunca precisa pensar sobre isso em seus scripts de automação.
\ No newline at end of file
diff --git a/docs/pt/features/automation/iframes.md b/docs/pt/features/automation/iframes.md
index 265727d4..66c6def8 100644
--- a/docs/pt/features/automation/iframes.md
+++ b/docs/pt/features/automation/iframes.md
@@ -1,188 +1,113 @@
 # Trabalhando com IFrames
 
-IFrames (inline frames) são um dos aspectos mais complicados da automação de navegadores. O Pydoll fornece uma API limpa e intuitiva para interação com iframes que abstrai a complexidade do gerenciamento de alvos (targets) do CDP.
+Páginas modernas usam `<iframe>` para embutir outros documentos. Nas versões antigas do Pydoll era necessário transformar o iframe em uma `Tab` com `tab.get_frame()` e cuidar de alvos CDP manualmente. **Isso acabou.**  
+Agora um iframe se comporta como qualquer outro `WebElement`: você pode chamar `find()`, `query()`, `execute_script()`, `inner_html`, `text` e todos os utilitários diretamente — o Pydoll encaminha a operação para o contexto correto em qualquer domínio.
 
-## Guia Rápido
+!!! info "Modelo mental simples"
+    Pense no iframe como mais uma `div`. Localize o elemento, guarde a referência e continue a navegação a partir dele. O Pydoll se encarrega de criar o mundo isolado, configurar o contexto JavaScript e lidar com iframes aninhados automaticamente.
 
-### Interação Básica com IFrame
+## Guia rápido
+
+### Interagir com o primeiro iframe da página
 
 ```python
 import asyncio
 from pydoll.browser.chromium import Chrome
 
-async def interact_with_iframe():
+async def interagir_iframe():
     async with Chrome() as browser:
         tab = await browser.start()
         await tab.go_to('https://example.com/page-with-iframe')
-        
-        # Encontre o elemento iframe
-        iframe_element = await tab.find(tag_name='iframe', id='content-frame')
-        
-        # Obtenha uma instância de Tab para o iframe
-        iframe = await tab.get_frame(iframe_element)
-        
-        # Agora interaja com elementos dentro do iframe
-        button = await iframe.find(id='submit-button')
-        await button.click()
-        
-        # Encontre e preencha o formulário dentro do iframe
-        username = await iframe.find(name='username')
-        await username.type_text('john_doe')
-
-asyncio.run(interact_with_iframe())
-```
 
-!!! tip "IFrames são Apenas Abas (Tabs)"
-    No Pydoll, um iframe retorna um objeto `Tab`. Isso significa que **todos os métodos disponíveis em Tab funcionam em iframes**: `find()`, `query()`, `execute_script()`, `take_screenshot()`, e mais.
+        iframe = await tab.find(tag_name='iframe', id='content-frame')
 
-## Entendendo IFrames
+        # As chamadas abaixo já executam dentro do iframe
+        title = await iframe.find(tag_name='h1')
+        await title.click()
 
-### O que é um IFrame?
-
-Um `<iframe>` (inline frame) é um elemento HTML que incorpora outro documento HTML dentro da página atual. Pense nisso como uma "janela do navegador dentro de outra janela do navegador".
+        form = await iframe.find(id='login-form')
+        username = await form.find(name='username')
+        await username.type_text('john_doe')
 
-```html
-<html>
-  <body>
-    <h1>Página Principal</h1>
-    <p>Este é o documento principal</p>
-    
-    <iframe src="https://other-site.com/content.html" id="my-frame">
-    </iframe>
-  </body>
-</html>
+asyncio.run(interagir_iframe())
 ```
 
-Cada iframe:
-
-- Tem seu próprio **DOM (Document Object Model) separado**
-- Carrega seu próprio HTML, CSS e JavaScript
-- Pode ser de um domínio diferente (cross-origin)
-- Opera em um contexto de navegação isolado
+### Iframes aninhados
 
-### Por que Você Não Pode Interagir Diretamente
-
-Este código **não funcionará** como você espera:
+Basta encadear as buscas:
 
 ```python
-# Isso NÃO encontrará elementos dentro do iframe
-button = await tab.find(id='button-inside-iframe')
-```
-
-**Por quê?** Porque `tab.find()` pesquisa no **DOM da página principal**. O iframe tem um **DOM completamente separado** que não é acessível a partir do pai.
+outer = await tab.find(id='outer-frame')
+inner = await outer.find(tag_name='iframe')  # procura dentro do primeiro iframe
 
-Pense desta forma:
-
-```
-DOM da Página Principal         DOM do IFrame (Separado!)
-├── <html>                    ├── <html>
-│   ├── <body>                │   ├── <body>
-│   │   ├── <div>             │   │   ├── <div>
-│   │   └── <iframe>          │   │   └── <button id="inside">
-│   │       (mundo separado)  │   └── </body>
-│   └── </body>               └── </html>
-└── </html>
+submit_button = await inner.find(id='submit')
+await submit_button.click()
 ```
 
-!!! info "Contextos de Navegação Isolados"
-    IFrames criam o que é chamado de **contexto de navegação isolado**. Esse isolamento é um recurso de segurança que impede que iframes maliciosos acessem ou manipulem o conteúdo da página pai.
-
-### Como o Pydoll Resolve Isso
+O fluxo é sempre o mesmo:
 
-Nos bastidores, o Pydoll usa o Chrome DevTools Protocol (CDP) para:
+1. Localize o iframe desejado.
+2. Use esse `WebElement` como escopo das próximas buscas.
+3. Repita para níveis mais profundos, se necessário.
 
-1.  **Identificar o alvo (target) do iframe**: Cada iframe obtém seu próprio ID de alvo CDP
-2.  **Criar uma nova instância de Tab**: Esta Tab é escopada para o DOM do iframe
-3.  **Fornecer acesso total**: Todos os métodos de Tab funcionam no DOM isolado do iframe
+### Executar JavaScript dentro do iframe
 
 ```python
-# É isso que acontece internamente:
-iframe_element = await tab.find(tag_name='iframe')  # Encontra a tag <iframe>
-frame = await tab.get_frame(iframe_element)         # Obtém o alvo CDP para o iframe
-
-# Agora 'frame' é uma Tab que opera no DOM do iframe
-button = await frame.find(id='button-inside-iframe')  # Funciona!
+iframe = await tab.find(tag_name='iframe')
+result = await iframe.execute_script('return document.title', return_by_value=True)
+print(result['result']['result']['value'])
 ```
 
-### Análise Profunda Técnica: Alvos (Targets) CDP
+O Pydoll garante que o script rode no contexto isolado do iframe, inclusive em frames cross-origin.
+
+## Por que ficou melhor?
 
-Quando você chama `tab.get_frame()`, o Pydoll:
+- **Intuitivo:** você programa exatamente o que vê na árvore DOM.
+- **Sem dor de cabeça com CDP:** mundos isolados e targets são configurados automaticamente.
+- **Suporte nativo a aninhamento:** cada busca é relativa ao elemento atual; hierarquias profundas continuam legíveis.
+- **Uma única API:** não é preciso alternar entre métodos de `Tab` e de `WebElement`.
 
-1.  **Extrai o atributo `src`** do elemento iframe
-2.  **Consulta o CDP por todos os alvos** usando `Target.getTargets()`
-3.  **Corresponde a URL do iframe** para encontrar seu ID de alvo correspondente
-4.  **Cria uma instância de Tab** com esse ID de alvo
+!!! tip "Aviso de descontinuação"
+    `Tab.get_frame()` agora emite `DeprecationWarning` e será removido em uma versão futura. Atualize seus scripts para usar o iframe diretamente, como mostrado acima.
 
-Cada alvo tem:
+## Padrões comuns
 
-- **ID de Alvo Único**: Identifica o contexto de navegação
-- **Conexão WebSocket Separada**: Para comunicação CDP isolada
-- **Árvore de Documento Própria**: Independência completa do pai
+### Capturar imagem de conteúdo dentro do iframe
 
 ```python
-# Internamente em tab.py:
-async def get_frame(self, frame: WebElement) -> Tab:
-    # Obter a URL de origem do iframe
-    frame_url = frame.get_attribute('src')
-    
-    # Encontrar o alvo que corresponde a esta URL
-    targets = await self._browser.get_targets()
-    iframe_target = next((t for t in targets if t['url'] == frame_url), None)
-    
-    # Criar uma Tab para o alvo deste iframe
-    target_id = iframe_target['targetId']
-    tab = Tab(self._browser, target_id=target_id, ...)
-    
-    return tab  # Agora você pode interagir com o iframe como uma Tab!
+iframe = await tab.find(tag_name='iframe')
+chart = await iframe.find(id='sales-chart')
+await chart.take_screenshot('chart.png')
 ```
 
-!!! warning "IFrame Deve Ter `src` Válido"
-    O iframe deve ter um atributo `src` válido para o Pydoll localizar seu alvo CDP. IFrames usando `srcdoc` ou conteúdo injetado dinamicamente podem não funcionar com `get_frame()`.
-
-## Comparação: Página Principal vs IFrame
+### Iterar sobre vários iframes
 
-| Aspecto | Página Principal | IFrame |
-|---|---|---|
-| **DOM** | Árvore de documento própria | Árvore de documento separada |
-| **Alvo CDP** | Um ID de alvo | ID de alvo diferente |
-| **Busca de Elemento** | `tab.find()` | `iframe.find()` |
-| **Contexto JavaScript** | `window` da página principal | `window` do iframe |
-| **Origem** | Origem da página | Pode ser cross-origin |
-| **Armazenamento** | Compartilhado com a página | Pode ser isolado |
-
-## Capturas de Tela em IFrames
+```python
+iframes = await tab.find(tag_name='iframe', find_all=True)
+for frame in iframes:
+    heading = await frame.find(tag_name='h2')
+    print(await heading.text)
+```
 
-!!! info "Limitações de Captura de Tela"
-    `tab.take_screenshot()` só funciona em **alvos de nível superior**. Para capturas de tela de iframes, use `element.take_screenshot()` em elementos **dentro** do iframe.
+### Aguardar até que um iframe esteja pronto
 
 ```python
-import asyncio
-from pydoll.browser.chromium import Chrome
-
-async def iframe_screenshot():
-    async with Chrome() as browser:
-        tab = await browser.start()
-        await tab.go_to('https://example.com/iframe-page')
-        
-        iframe_element = await tab.find(tag_name='iframe')
-        frame = await tab.get_frame(iframe_element)
-        
-        # Isso não funcionará para iframes
-        # await frame.take_screenshot('frame.png')
-        
-        # Em vez disso, capture um elemento dentro do iframe
-        content = await frame.find(id='content')
-        await content.take_screenshot('iframe-content.png')
-
-asyncio.run(iframe_screenshot())
+iframe = await tab.find(tag_name='iframe')
+await iframe.wait_until(is_visible=True, timeout=10)
+banner = await iframe.find(id='promo-banner')
 ```
 
-## Aprenda Mais
+## Boas práticas
+
+- **Use o iframe como escopo:** prefira chamar `find`, `query` e derivados diretamente nele.
+- **Evite `tab.find` para elementos internos:** ele só enxerga o documento principal.
+- **Guarde referências úteis:** o contexto é cacheado pelo Pydoll.
+- **Continue aplicando os mesmos fluxos:** rolagem, screenshots, waits, scripts, atributos e texto funcionam igual a qualquer outro elemento.
 
-Para um entendimento mais profundo da mecânica de iframes e alvos CDP:
+## Leituras recomendadas
 
-- **[Análise Profunda: Domínio da Aba](../../deep-dive/tab-domain.md#iframe-handling)**: Detalhes técnicos sobre a resolução de alvos de iframe
-- **[Análise Profunda: Domínio do Navegador](../../deep-dive/browser-domain.md#target-management)**: Como o CDP gerencia múltiplos alvos
-- **[Localização de Elementos](../element-finding.md#scoped-search)**: Entendendo o escopo do DOM na busca de elementos
+- **[Busca de Elementos](../element-finding.md)** – explica buscas encadeadas e escopos.
+- **[Capturas e PDFs](screenshots-and-pdfs.md)** – detalhes sobre captura de tela.
+- **[Event System](../advanced/event-system.md)** – monitore eventos de forma reativa (inclusive de iframes).
 
-IFrames podem parecer complexos, mas a API do Pydoll torna o trabalho com eles tão fácil quanto com elementos de página regulares. A chave é entender que cada iframe é sua própria Tab isolada, com um DOM e um alvo CDP separados.
\ No newline at end of file
+Com o novo fluxo, iframes deixam de ser um caso especial: são apenas mais um nó na árvore DOM. Concentre-se na lógica da automação; o Pydoll cuida da parte difícil para você.
diff --git a/docs/pt/features/automation/screenshots-and-pdfs.md b/docs/pt/features/automation/screenshots-and-pdfs.md
index 0abfd2c6..e3fe49ca 100644
--- a/docs/pt/features/automation/screenshots-and-pdfs.md
+++ b/docs/pt/features/automation/screenshots-and-pdfs.md
@@ -301,17 +301,13 @@ async def safe_screenshot():
         
         # Limitação de screenshot de IFrame
         iframe_element = await tab.find(tag_name='iframe')
-        frame = await tab.get_frame(iframe_element)
-        
-        try:
-            # Não funcionará para iframes
-            await frame.take_screenshot('iframe.png')
-        except TopLevelTargetRequired:
-            print("Use element.take_screenshot() para conteúdo de iframe")
-            
-            # Abordagem correta
-            content = await frame.find(id='content')
-            await content.take_screenshot('iframe-content.jpeg')
+
+        # Isso ainda não funciona: screenshots de nível superior ignoram iframes
+        # await tab.take_screenshot('frame.png')
+
+        # Capture um elemento dentro do próprio iframe
+        content = await iframe_element.find(id='content')
+        await content.take_screenshot('iframe-content.png')
 ```
 
 ## Aprenda Mais
diff --git a/docs/pt/features/browser-management/tabs.md b/docs/pt/features/browser-management/tabs.md
index f878892c..39d5c738 100644
--- a/docs/pt/features/browser-management/tabs.md
+++ b/docs/pt/features/browser-management/tabs.md
@@ -81,8 +81,8 @@ async def tab_registry_demonstration():
 asyncio.run(tab_registry_demonstration())
 ```
 
-!!! info "Registro Gerenciado pelo Navegador"
-    A classe Browser gerencia um dicionário `_tabs_opened` indexado por `target_id`. Quando você solicita uma aba (via `new_tab()`, `get_opened_tabs()`, ou `get_frame()`), o Browser verifica este registro primeiro. Se uma instância de Tab já existe para aquele `target_id`, ele retorna a instância existente; caso contrário, cria uma nova e a armazena no registro.
+!!! info "Registro controlado pelo Browser"
+    A classe Browser gerencia um dicionário `_tabs_opened` indexado por `target_id`. Quando você solicita uma aba (via `new_tab()` ou `get_opened_tabs()`), o Browser verifica este registro primeiro. Se uma instância de Tab já existe para aquele `target_id`, ele retorna a instância existente; caso contrário, cria uma nova e a armazena no registro. (Iframes não geram mais abas separadas — interaja com eles como elementos normais.)
 
 ## Criando e Gerenciando Abas
 
diff --git a/docs/pt/features/element-finding.md b/docs/pt/features/element-finding.md
index 62cb421c..61aaf4b1 100644
--- a/docs/pt/features/element-finding.md
+++ b/docs/pt/features/element-finding.md
@@ -593,59 +593,42 @@ asyncio.run(practical_example())
 
 iFrames apresentam um desafio especial na automação de navegador porque eles têm contextos DOM separados. O Pydoll torna a interação com iframe transparente:
 
-### Isolamento de Contexto do iFrame
-
 ```mermaid
 flowchart TB
-    subgraph MainPage[Contexto da Pagina Principal]
-        MainDOM[DOM da Pagina Principal]
-        IFrameTag[Elemento iFrame]
-        MainDOM --> IFrameTag
-    end
-    
-    subgraph IFrameContext[iFrame - DOM Separado]
-        IFrameDOM[DOM do iFrame]
-        IFrameElements[Elementos dentro do iFrame]
-        IFrameDOM --> IFrameElements
-    end
-    
-    IFrameTag -.->|Método get_frame| IFrameContext
-    
-    MainPage --> MainSearch[tab.find - DOM Principal]
-    IFrameContext --> IFrameSearch[frame.find - DOM do iFrame]
-```
+    Principal[tab]
+    IFrame["WebElement do iframe"]
+    Conteudo["elementos dentro do iframe"]
 
+    Principal -->|"find('iframe')"| IFrame
+    IFrame -->|"find('button#submit')"| Conteudo
+```
 ```python
 import asyncio
 from pydoll.browser.chromium import Chrome
 
-async def iframe_interaction():
+async def iframe_interacao():
     async with Chrome() as browser:
         tab = await browser.start()
-        await tab.go_to('https://example.com/page-with-iframe')
-        
-        # Encontrar o elemento iframe
-        iframe_element = await tab.query("iframe.embedded-content", timeout=10)
-        
-        # Obter uma instância de Tab para o conteúdo do iframe
-        frame = await tab.get_frame(iframe_element)
-        
-        # Agora use todos os métodos de Tab dentro do contexto do iframe
-        iframe_button = await frame.find(tag_name="button", class_name="submit")
+        await tab.go_to('https://example.com/pagina-com-iframe')
+
+        iframe = await tab.query("iframe.conteudo", timeout=10)
+
+        # Os utilitários de WebElement já executam dentro do iframe
+        iframe_button = await iframe.find(tag_name="button", class_name="submit")
         await iframe_button.click()
-        
-        iframe_input = await frame.find(id="captcha-input")
-        await iframe_input.type_text("verification-code")
-        
-        # Fazer query dentro do iframe
-        iframe_links = await frame.query("a", find_all=True)
-        print(f"Encontrados {len(iframe_links)} links no iframe")
 
-asyncio.run(iframe_interaction())
-```
+        iframe_input = await iframe.find(id="captcha-input")
+        await iframe_input.type_text("codigo-de-verificacao")
 
-!!! note "iFrames, Alvos e Capturas de Tela"
-    Ao trabalhar dentro de um iframe, alguns métodos como `tab.take_screenshot()` não funcionarão porque o CDP do Chrome não pode capturar screenshots de sub-alvos diretamente. Use `element.take_screenshot()` em vez disso, que funciona dentro de iframes.
+        # Iframe aninhado? Continue encadeando
+        inner_iframe = await iframe.find(tag_name="iframe")
+        download_link = await inner_iframe.find(text="Baixar PDF")
+        await download_link.click()
+
+asyncio.run(iframe_interacao())
+```
+!!! note "Screenshots em iframes"
+    `tab.take_screenshot()` funciona apenas no alvo principal. Para capturar o conteúdo de um iframe, selecione um elemento dentro dele e chame `element.take_screenshot()`.
 
 ## Estratégias de Tratamento de Erros
 
diff --git a/docs/pt/features/index.md b/docs/pt/features/index.md
index 38f5f101..9f0a488d 100644
--- a/docs/pt/features/index.md
+++ b/docs/pt/features/index.md
@@ -28,7 +28,7 @@ Estas são as funcionalidades que dão vida à sua automação: simular interaç
 
 **[Operações com Arquivos](automation/file-operations.md)**: O manuseio de arquivos pode ser complicado na automação de navegador. O Pydoll fornece soluções robustas tanto para uploads quanto para downloads, com o gerenciador de contexto `expect_download` oferecendo um manuseio elegante da conclusão assíncrona de downloads.
 
-**[Interação com IFrames](automation/iframes.md)**: Trabalhe perfeitamente com frames incorporados usando o método `get_frame()`. Obtenha uma interface Tab completa para o conteúdo do iframe, permitindo que você use todas as capacidades de localização e interação de elementos do Pydoll dentro dos frames.
+**[Interação com IFrames](automation/iframes.md)**: Trate iframes como qualquer elemento—encontre o iframe e continue pesquisando a partir dele. Sem targets extras, sem abas adicionais.
 
 **[Capturas de Tela e PDF](automation/screenshots-and-pdfs.md)**: Capture conteúdo visual de suas sessões de automação. Se você precisa de capturas de tela de página inteira para testes de regressão visual, capturas de elementos específicos para depuração, ou exportações de PDF para arquivamento, o Pydoll tem o que você precisa.
 
diff --git a/docs/zh/deep-dive/architecture/tab-domain.md b/docs/zh/deep-dive/architecture/tab-domain.md
index ba751d72..5eb9da24 100644
--- a/docs/zh/deep-dive/architecture/tab-domain.md
+++ b/docs/zh/deep-dive/architecture/tab-domain.md
@@ -222,7 +222,7 @@ except KeyError:
     raise TopLevelTargetRequired(...)  # 引导用户使用 WebElement.take_screenshot()
 ```
 
-**设计影响：** IFrame 标签页（通过 `get_frame()` 创建）继承所有 Tab 方法，但屏幕截图按设计失败。替代方案：`WebElement.take_screenshot()` 适用于 iframe 内容。
+**设计影响：** 旧版本会为 iframe 创建独立的 Tab。现在 iframe 直接作为 `WebElement` 处理，因此需要在框内元素上执行操作，例如 `await iframe_element.find(...).take_screenshot()`。
 
 **PDF 生成：** `Page.printToPDF` 返回 base64 编码的数据。Pydoll 抽象文件 I/O，但底层数据始终是 base64（CDP 规范）。
 
diff --git a/docs/zh/deep-dive/fundamentals/iframes-and-contexts.md b/docs/zh/deep-dive/fundamentals/iframes-and-contexts.md
new file mode 100644
index 00000000..dce23d4c
--- /dev/null
+++ b/docs/zh/deep-dive/fundamentals/iframes-and-contexts.md
@@ -0,0 +1,1292 @@
+# Iframes、OOPIF 和执行上下文（深度解析）
+
+理解浏览器自动化如何处理 iframe 对于构建健壮的自动化工具至关重要。本综合指南探讨了 Pydoll 中 iframe 处理的技术基础，涵盖了文档对象模型 (DOM)、Chrome DevTools 协议 (CDP) 机制、执行上下文、隔离世界 (isolated worlds) 以及使 iframe 交互变得无缝的复杂解析管道。
+
+!!! info "实用用法优先"
+    如果您只需要在自动化脚本中使用 iframe，请从功能指南开始：**功能 → 自动化 → IFrames**。
+    本深度解析解释了架构决策、协议的细微差别以及内部实现细节。
+
+---
+
+## 目录
+
+1. [基础：文档对象模型 (DOM)](#基础文档对象模型-dom)
+2. [什么是 Iframes 及其重要性](#什么是-iframes-及其重要性)
+3. [挑战：跨进程 Iframes (OOPIFs)](#挑战跨进程-iframes-oopifs)
+4. [Chrome DevTools 协议和 Frame 管理](#chrome-devtools-协议和-frame-管理)
+5. [执行上下文和隔离世界](#执行上下文和隔离世界)
+6. [CDP 标识符参考](#cdp-标识符参考)
+7. [Pydoll 的解析管道](#pydoll-的解析管道)
+8. [会话路由和扁平化模式](#会话路由和扁平化模式)
+9. [实现深度解析](#实现深度解析)
+10. [性能考量](#性能考量)
+11. [失败模式和调试](#失败模式和调试)
+
+---
+
+## 基础：文档对象模型 (DOM)
+
+在深入研究 iframe 之前，我们必须了解 DOM——在内存中表示 HTML 文档的树形结构。
+
+### 什么是 DOM？
+
+**文档对象模型** (Document Object Model) 是 HTML 和 XML 文档的编程接口。它将页面结构表示为一个节点树，其中每个节点对应文档的一部分：
+
+- **元素节点**：HTML 标签，如 `<div>`、`<iframe>`、`<button>`
+- **文本节点**：实际的文本内容
+- **属性节点**：元素属性，如 `id`、`class`、`src`
+- **文档节点**：树的根节点
+
+'''mermaid
+graph TD
+    Document[文档] --> HTML[html 元素]
+    HTML --> Head[head 元素]
+    HTML --> Body[body 元素]
+    Body --> Div1[div 元素]
+    Body --> Div2[div 元素]
+    Div1 --> Text1[文本节点: 'Hello']
+    Div2 --> Iframe[iframe 元素]
+    Iframe --> IframeDoc[iframe 的文档]
+    IframeDoc --> IframeBody[iframe body]
+    IframeBody --> IframeContent[iframe 内容...]
+'''
+
+### DOM 树属性
+
+1. **层级结构**：每个节点都有一个父节点（Document 除外），并且可以有子节点
+2. **节点标识**：节点可以通过以下方式标识：
+   - `nodeId`：文档上下文（DOM 域）内的内部标识符
+   - `backendNodeId`：可以跨不同文档引用节点的稳定标识符
+3. **实时表示**：对 DOM 的更改会立即反映在树中
+
+### 为什么这对 Iframes 很重要
+
+每个 `<iframe>` 元素都会创建一个**新的、独立的 DOM 树**。 iframe 元素本身存在于父级的 DOM 中，但加载到 iframe 中的内容拥有自己完整的 Document 节点和树结构。这种分离是所有 iframe 复杂性的基础。
+
+---
+
+## 什么是 Iframes 及其重要性
+
+### 定义
+
+**iframe**（内联框架）是一个 HTML 元素（`<iframe>`），它在当前页面中嵌入另一个 HTML 文档。被嵌入的文档保持其自己的上下文，包括：
+
+- 独立的 HTML 结构和 DOM 树
+- 独立的 JavaScript 执行环境
+- 自己的 CSS 样式（除非明确共享）
+- 不同的导航历史
+
+'''html
+<body>
+  <h1>父页面</h1>
+  <iframe src="https://example.com/embedded.html" id="content-frame"></iframe>
+  <p>更多父页面内容</p>
+</body>
+'''
+
+### 常见用例
+
+| 用例 | 描述 | 示例 |
+|----------|-------------|---------|
+| **第三方小部件** | 安全地嵌入外部内容 | 支付表单、社交媒体 feeds、聊天窗口 |
+| **内容隔离** | 沙盒化不受信任的内容 | 用户生成的 HTML、广告 |
+| **模块化架构** | 可重用组件 | 仪表盘小部件、插件系统 |
+| **跨域内容** | 从不同域加载资源 | 地图、视频播放器、分析仪表盘 |
+
+### 安全模型：同源策略 (Same-Origin Policy)
+
+浏览器对 iframes 强制执行**同源策略**：
+
+- **同源 iframes**：父级可以通过 JavaScript 访问 iframe 的 DOM (`iframe.contentDocument`)
+- **跨域 iframes**：父级不能直接访问 iframe 的 DOM（安全限制）
+
+这个安全边界就是为什么自动化工具需要特殊机制（如 CDP）来与 iframe 内容交互。
+
+!!! warning "对自动化很重要"
+    由于浏览器安全限制，传统的基于 JavaScript 的自动化（如 Selenium 的早期方法）无法直接访问跨域 iframe 的内容。CDP 在更底层运行，出于调试目的绕过了这个限制。
+
+---
+
+## 挑战：跨进程 Iframes (OOPIFs)
+
+### 什么是 OOPIFs？
+
+现代 Chromium 使用**站点隔离 (site isolation)** 来提高安全性和稳定性。这意味着不同的源 (origin) 可能会在单独的操作系统进程中渲染。来自不同源的 iframe 会成为**跨进程 Iframe (OOPIF)**。
+
+'''mermaid
+graph LR
+    subgraph "进程 1: example.com"
+        MainPage[主页面 DOM]
+    end
+    
+    subgraph "进程 2: widget.com"
+        IframeDOM[Iframe DOM]
+    end
+    
+    MainPage -.进程边界.-> IframeDOM
+'''
+
+### 为什么 OOPIFs 使自动化复杂化
+
+| 方面 | 进程内 Iframe | 跨进程 Iframe (OOPIF) |
+|--------|-------------------|-------------------------------|
+| **DOM 访问** | 内存中共享的文档树 | 拥有自己文档的独立目标 (target) |
+| **命令路由** | 单个连接 | 需要目标附加 (target attachment) 和会话路由 (session routing) |
+| **Frame 树** | 所有 frames 在一棵树中 | 根 frame + OOPIFs 的独立目标 |
+| **JavaScript 上下文** | 相同的执行上下文 | 每个进程有不同的执行上下文 |
+| **CDP 通信** | 直接命令 | 命令必须包含 `sessionId` |
+
+### 传统方法（手动切换上下文）
+
+没有复杂的处理，自动化 OOPIFs 需要：
+
+'''python
+# 其他工具的传统（手动）方法
+main_page = browser.get_page()
+iframe_element = main_page.find_element_by_id("iframe-id")
+
+# 必须手动切换上下文
+driver.switch_to.frame(iframe_element)
+
+# 现在命令指向 iframe
+button = driver.find_element_by_id("button-in-iframe")
+button.click()
+
+# 必须手动切换回来
+driver.switch_to.default_content()
+'''
+
+**这种方法的问题：**
+
+1. **开发者负担**：每个 iframe 都需要显式的上下文管理
+2. **嵌套 iframes**：每一层都需要再次切换
+3. **OOPIF 检测**：很难知道何时需要手动附加
+4. **容易出错**：忘记切换回来 → 后续命令失败
+5. **不可组合**：辅助函数必须知道它们所处的 iframe 上下文
+
+### Pydoll 的解决方案：透明的上下文解析
+
+Pydoll 通过自动解析 iframe 上下文来消除手动上下文切换：
+
+'''python
+# Pydoll 方法（无手动切换）
+iframe = await tab.find(id="iframe-id")
+button = await iframe.find(id="button-in-iframe")
+await button.click()
+
+# 嵌套 iframes？同样的模式
+outer = await tab.find(id="outer-iframe")
+inner = await outer.find(tag_name="iframe")
+button = await inner.find(text="Submit")
+await button.click()
+'''
+
+复杂性在内部处理。让我们来探究一下是如何做到的。
+
+---
+
+## Chrome DevTools 协议和 Frame 管理
+
+正如在 [深度解析 → 基础 → Chrome DevTools 协议](./cdp.md) 中讨论的，CDP 通过 WebSocket 通信提供全面的浏览器控制。Frame 管理分散在多个 CDP 域中。
+
+### 相关的 CDP 域
+
+#### 1. **Page 域**
+
+管理页面生命周期、frames 和导航。
+
+**关键方法：**
+
+- `Page.getFrameTree()`：返回页面中所有 frames 的层级结构
+  '''json
+  {
+    "frameTree": {
+      "frame": {
+        "id": "main-frame-id",
+        "url": "https://example.com",
+        "securityOrigin": "https://example.com",
+        "mimeType": "text/html"
+      },
+      "childFrames": [
+        {
+          "frame": {
+            "id": "child-frame-id",
+            "parentId": "main-frame-id",
+            "url": "https://widget.com/embed"
+          }
+        }
+      ]
+    }
+  }
+  '''
+
+- `Page.createIsolatedWorld(frameId, worldName)`：在特定 frame 中创建一个新的 JavaScript 执行上下文
+  '''json
+  {
+    "executionContextId": 42
+  }
+  '''
+
+**Pydoll 用法：**
+
+'''python
+# 源自 pydoll/elements/web_element.py
+@staticmethod
+async def _get_frame_tree_for(
+    handler: ConnectionHandler, session_id: Optional[str]
+) -> FrameTree:
+    """获取给定连接/目标的 Page frame 树。"""
+    command = PageCommands.get_frame_tree()
+    if session_id:
+        command['sessionId'] = session_id
+    response: GetFrameTreeResponse = await handler.execute_command(command)
+    return response['result']['frameTree']
+'''
+
+#### 2. **DOM 域**
+
+提供对 DOM 结构的访问。
+
+**关键方法：**
+
+- `DOM.describeNode(objectId)`：返回有关 DOM 节点的详细信息
+  '''json
+  {
+    "node": {
+      "nodeId": 123,
+      "backendNodeId": 456,
+      "nodeName": "IFRAME",
+      "frameId": "parent-frame-id",
+      "contentDocument": {
+        "frameId": "iframe-frame-id",
+        "documentURL": "https://embedded.com/page.html"
+      }
+    }
+  }
+  '''
+
+- `DOM.getFrameOwner(frameId)`：返回拥有某个 frame 的 `<iframe>` 元素的 `backendNodeId`
+  '''json
+  {
+    "backendNodeId": 456
+  }
+  '''
+
+**Pydoll 用法：**
+
+'''python
+# 源自 pydoll/elements/web_element.py
+@staticmethod
+async def _owner_backend_for(
+    handler: ConnectionHandler, session_id: Optional[str], frame_id: str
+) -> Optional[int]:
+    """获取拥有给定 frame 的 DOM 元素的 backendNodeId。"""
+    command = DomCommands.get_frame_owner(frame_id=frame_id)
+    if session_id:
+        command['sessionId'] = session_id
+    response: GetFrameOwnerResponse = await handler.execute_command(command)
+    return response.get('result', {}).get('backendNodeId')
+'''
+
+#### 3. **Target 域**
+
+管理浏览器目标（页面、iframes、workers 等）。
+
+**关键方法：**
+
+- `Target.getTargets()`：列出所有可用的目标
+  '''json
+  {
+    "targetInfos": [
+      {
+        "targetId": "page-target-id",
+        "type": "page",
+        "title": "Main Page",
+        "url": "https://example.com"
+      },
+      {
+        "targetId": "iframe-target-id",
+        "type": "iframe",
+        "title": "",
+        "url": "https://widget.com/embed",
+        "parentFrameId": "main-frame-id"
+      }
+    ]
+  }
+  '''
+
+- `Target.attachToTarget(targetId, flatten)`：附加到一个目标以进行调试
+  - 当 `flatten=true` 时：返回一个 `sessionId` 用于在扁平化模式下路由命令
+  - 所有通信都通过同一个 WebSocket 进行，通过 `sessionId` 区分
+
+**Pydoll 用法：**
+
+'''python
+# 源自 pydoll/elements/web_element.py (简化版)
+async def _resolve_oopif_by_parent(self, parent_frame_id: str, ...):
+    """使用父 frame id 解析 OOPIF。"""
+    browser_handler = ConnectionHandler(...)
+    targets_response: GetTargetsResponse = await browser_handler.execute_command(
+        TargetCommands.get_targets()
+    )
+    target_infos = targets_response.get('result', {}).get('targetInfos', [])
+    
+    # 查找 parentFrameId 匹配的目标
+    direct_children = [
+        target_info for target_info in target_infos
+        if target_info.get('parentFrameId') == parent_frame_id
+    ]
+    
+    if direct_children:
+        attach_response: AttachToTargetResponse = await browser_handler.execute_command(
+            TargetCommands.attach_to_target(
+                target_id=direct_children[0]['targetId'], 
+                flatten=True
+            )
+        )
+        attached_session_id = attach_response.get('result', {}).get('sessionId')
+        # ... 对后续命令使用 session_id
+'''
+
+#### 4. **Runtime 域**
+
+执行 JavaScript 并管理执行上下文。
+
+**关键方法：**
+
+- `Runtime.evaluate(expression, contextId)`：在特定的执行上下文中评估 JavaScript
+- `Runtime.callFunctionOn(functionDeclaration, objectId)`：在一个特定对象上调用函数（作为 `this`）
+
+**Pydoll 用于 iframe 文档访问的用法：**
+
+'''python
+# 源自 pydoll/elements/web_element.py
+async def _set_iframe_document_object_id(self, execution_context_id: int):
+    """在 iframe 上下文中评估 document.documentElement 并缓存其 object id。"""
+    evaluate_command = RuntimeCommands.evaluate(
+        expression='document.documentElement',
+        context_id=execution_context_id,
+    )
+    if self._iframe_context and self._iframe_context.session_id:
+        evaluate_command['sessionId'] = self._iframe_context.session_id
+    
+    evaluate_response: EvaluateResponse = await (
+        (self._iframe_context.session_handler if self._iframe_context else None)
+        or self._connection_handler
+    ).execute_command(evaluate_command)
+    
+    document_object_id = evaluate_response.get('result', {}).get('result', {}).get('objectId')
+    if self._iframe_context:
+        self._iframe_context.document_object_id = document_object_id
+'''
+
+---
+
+## 执行上下文和隔离世界
+
+### 什么是执行上下文？
+
+**执行上下文** (execution context) 是执行 JavaScript 代码的环境。浏览器中的每个 frame 至少有一个执行上下文。该上下文包括：
+
+- **全局对象**（在浏览器中是 `window`）
+- **作用域链**：如何解析变量
+- **This 绑定**：`this` 指向什么
+- **变量环境**：所有声明的变量和函数
+
+### 每个 Frame 的多个上下文
+
+单个 frame 可以有多个执行上下文：
+
+1. **主世界 (main world)（默认上下文）**：页面自己的 JavaScript 运行的地方
+2. **隔离世界 (isolated worlds)**：共享相同 DOM 但具有不同 JavaScript 全局作用域的独立上下文
+
+'''mermaid
+graph TB
+    Frame[Frame: example.com/page]
+    Frame --> MainWorld[主世界<br/>页面的 JavaScript]
+    Frame --> IsolatedWorld1[隔离世界 1<br/>扩展的内容脚本]
+    Frame --> IsolatedWorld2[隔离世界 2<br/>Pydoll 自动化]
+    
+    DOM[共享的 DOM 树]
+    MainWorld -.可以访问.-> DOM
+    IsolatedWorld1 -.可以访问.-> DOM
+    IsolatedWorld2 -.可以访问.-> DOM
+    
+    MainWorld -.无法访问.-> IsolatedWorld1
+    MainWorld -.无法访问.-> IsolatedWorld2
+'''
+
+### 什么是隔离世界？
+
+**隔离世界** (isolated world) 是一个独立的 JavaScript 执行上下文，它：
+
+- **共享相同的 DOM**：可以读取/修改 DOM 元素
+- **拥有独立的全局对象**：变量/函数不会在世界之间泄漏
+- **防止干扰**：页面脚本无法检测或干扰隔离世界中的脚本
+
+**起源**：隔离世界是为浏览器扩展创建的。内容脚本 (Content scripts) 运行在隔离世界中，因此它们可以与页面 DOM 交互，而不会：
+
+- 被页面脚本覆盖其变量
+- 被防篡改代码检测到
+- 与页面的 JavaScript 冲突
+
+### 为什么 Pydoll 对 Iframes 使用隔离世界
+
+当 Pydoll 与 iframe 内容交互时，它会在该 iframe 的上下文中创建一个隔离世界。这提供了：
+
+1. **干净的 JavaScript 环境**：与 iframe 自己的脚本没有冲突
+2. **一致的行为**：无论 iframe 运行什么 JavaScript，自动化脚本都能工作
+3. **反检测**：iframe 的 JavaScript 无法轻易检测到 Pydoll 的存在
+4. **安全的评估**：自动化代码不会意外触发页面逻辑
+
+**实现：**
+
+'''python
+# 源自 pydoll/elements/web_element.py
+@staticmethod
+async def _create_isolated_world_for_frame(
+    frame_id: str,
+    handler: ConnectionHandler,
+    session_id: Optional[str],
+) -> int:
+    """为给定的 frame 创建一个隔离世界 (Page.createIsolatedWorld)。"""
+    create_command = PageCommands.create_isolated_world(
+        frame_id=frame_id,
+        world_name=f'pydoll::iframe::{frame_id}',
+        grant_universal_access=True,
+    )
+    if session_id:
+        create_command['sessionId'] = session_id
+    
+    create_response: CreateIsolatedWorldResponse = await handler.execute_command(
+        create_command
+    )
+    execution_context_id = create_response.get('result', {}).get('executionContextId')
+    if not execution_context_id:
+        raise InvalidIFrame('无法为 iframe 创建隔离世界')
+    return execution_context_id
+'''
+
+`grant_universal_access=True` 参数允许隔离世界：
+
+- 访问跨域 frames（通常被同源策略阻止）
+- 执行自动化所需的特权操作
+
+!!! tip "实践中的隔离世界"
+    每当您使用 `await iframe.find(...)` 时，Pydoll 都会在专门为该 iframe 创建的隔离世界中评估选择器查询。这确保您的自动化逻辑永远不会与 iframe 自己的 JavaScript 冲突，并且 iframe 无法检测或阻止您的自动化。
+
+---
+
+## CDP 标识符参考
+
+理解 CDP 标识符对于处理 iframe 至关重要。这是一个全面的参考：
+
+| 标识符 | 域 | 范围 | 目的 | 在 Pydoll 中的用例 |
+|------------|--------|-------|---------|----------------------|
+| **`nodeId`** | DOM | 文档局部 | 在特定文档上下文中标识一个 DOM 节点 | 内部 CDP 操作；在导航中不稳定 |
+| **`backendNodeId`** | DOM | 跨文档稳定 | DOM 节点的稳定标识符；可以将 frames 映射到所有者元素 | 用于通过 `DOM.getFrameOwner` 将 iframe 元素与 frame IDs 匹配 |
+| **`frameId`** | Page | Frame | 标识页面 frame 树中的一个 frame | 用于为 `Page.createIsolatedWorld` 和 frame 树遍历指定哪个 frame |
+| **`targetId`** | Target | 全局 | 标识一个调试目标（页面、iframe、worker 等） | 用于 `Target.attachToTarget` 以连接到 OOPIFs |
+| **`sessionId`** | Target | 目标特定 | 在扁平化模式下将命令路由到特定目标 | 注入到命令中，将它们路由到正确的 OOPIF |
+| **`executionContextId`** | Runtime | Frame + 世界 | 标识一个 JavaScript 执行上下文（包括隔离世界） | 由 `Page.createIsolatedWorld` 返回；用于 `Runtime.evaluate` |
+| **`objectId`** | Runtime | 执行上下文 | 远程对象引用（例如 DOM 元素、函数、对象） | 对 iframe 的 `document.documentElement` 的引用，用于相对查询 |
+
+### 标识符关系
+
+以下是 iframe 解析期间标识符之间的关系：
+
+'''
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         解析流程                                        │
+└─────────────────────────────────────────────────────────────────────────┘
+
+1. 开始: <iframe> 元素
+   └─ backendNodeId: 789
+   
+2. 查找 Frame ──────────────[DOM.getFrameOwner]──────────────┐
+   └─ frameId: abc-123                                       │
+                                                             │
+3. OOPIF? 检查源 ─────[检测到不同源]──────┤
+   └─ targetId: xyz-456                                      │
+                                                             │
+4. 附加到目标 ────────[Target.attachToTarget]──────────┤
+   └─ sessionId: session-789                                 │
+                                                             │
+5. 创建隔离世界 ───[Page.createIsolatedWorld]───────┤
+   └─ executionContextId: 42                                 │
+                                                             │
+6. 获取文档 ────────────[Runtime.evaluate]───────────────┘
+   └─ objectId: obj-999
+'''
+
+**关键转换点：**
+
+| 从 | 方法 | 到 | 目的 |
+|------|--------|-----|---------|
+| `backendNodeId` | `DOM.getFrameOwner` | `frameId` | 查找哪个 frame 拥有该 iframe 元素 |
+| `targetId` | `Target.attachToTarget(flatten=true)` | `sessionId` | 连接到 OOPIF 以进行命令路由 |
+| `frameId` | `Page.createIsolatedWorld` | `executionContextId` | 创建安全的 JavaScript 环境 |
+| `executionContextId` | `Runtime.evaluate('document.documentElement')` | `objectId` | 获取对 iframe 文档的引用 |
+
+### Pydoll 中的代码表示
+
+'''python
+# 源自 pydoll/elements/web_element.py
+@dataclass
+class _IFrameContext:
+    """封装 iframe 的所有标识符和路由信息。"""
+    frame_id: str                                   # frameId: 标识 frame
+    document_url: Optional[str] = None              # frame 加载的 URL
+    execution_context_id: Optional[int] = None      # executionContextId: 隔离世界
+    document_object_id: Optional[str] = None        # objectId: document.documentElement
+    session_handler: Optional[ConnectionHandler] = None  # 用于 OOPIF 目标
+    session_id: Optional[str] = None                # sessionId: 将命令路由到 OOPIF
+'''
+
+这个 dataclass 被缓存在代表 iframe 的每个 `WebElement` 上，实现了所有后续操作的自动路由。
+
+---
+
+## Pydoll 的解析管道
+
+当您在 Pydoll 中访问 iframe（例如，`await iframe.find(...)`）时，一个精密的解析管道会在幕后执行。本节分解了每一步。
+
+### 高级流程
+
+'''mermaid
+sequenceDiagram
+    participant User as 用户
+    participant WebElement
+    participant Pipeline as 解析管道
+    participant CDP
+    
+    用户->>WebElement: iframe.find(id='button')
+    WebElement->>WebElement: 检查 iframe 上下文是否已缓存
+    alt 上下文未缓存
+        WebElement->>Pipeline: _ensure_iframe_context()
+        Pipeline->>CDP: DOM.describeNode(iframe)
+        CDP-->>Pipeline: 节点信息 (frameId?, backendNodeId, 等)
+        
+        alt 节点信息中没有 frameId
+            Pipeline->>Pipeline: _resolve_frame_by_owner()
+            Pipeline->>CDP: Page.getFrameTree()
+            CDP-->>Pipeline: Frame 树
+            Pipeline->>CDP: DOM.getFrameOwner(每个 frame)
+            CDP-->>Pipeline: backendNodeId
+            Pipeline->>Pipeline: 匹配 backendNodeId 以查找 frameId
+        end
+        
+        alt frameId 仍然缺失 (OOPIF)
+            Pipeline->>Pipeline: _resolve_oopif_by_parent()
+            Pipeline->>CDP: Target.getTargets()
+            CDP-->>Pipeline: 目标列表
+            Pipeline->>CDP: Target.attachToTarget(targetId, flatten=true)
+            CDP-->>Pipeline: sessionId
+            Pipeline->>CDP: Page.getFrameTree(sessionId)
+            CDP-->>Pipeline: OOPIF frame 树
+        end
+        
+        Pipeline->>CDP: Page.createIsolatedWorld(frameId)
+        CDP-->>Pipeline: executionContextId
+        
+        Pipeline->>CDP: Runtime.evaluate('document.documentElement', contextId)
+        CDP-->>Pipeline: objectId (文档引用)
+        
+        Pipeline->>WebElement: 缓存 _IFrameContext
+    end
+    
+    WebElement->>WebElement: 使用缓存的上下文进行 find()
+    WebElement-->>用户: 按钮元素 (带上下文)
+'''
+
+### 步骤深度解析
+
+#### **步骤 1：描述 Iframe 元素**
+
+**目标**：从 `<iframe>` DOM 元素中提取元数据。
+
+**方法**：`DOM.describeNode(objectId=iframe_object_id)`
+
+**我们得到什么**：
+
+- `backendNodeId`：iframe 元素的稳定标识符
+- `frameId`（来自 `contentDocument`）：如果 iframe 的内容已加载并在进程内
+- `documentURL`：iframe 中加载的 URL
+- `parentFrameId`（来自节点上的 `frameId` 字段）：包含此 iframe 元素的 frame
+
+**代码**：
+
+'''python
+# 源自 pydoll/elements/web_element.py
+async def _ensure_iframe_context(self) -> None:
+    """初始化并缓存 iframe 元素的上下文信息。"""
+    node_info = await self._describe_node(object_id=self._object_id)
+    base_handler, base_session_id = self._get_base_session()
+    frame_id, document_url, parent_frame_id, backend_node_id = self._extract_frame_metadata(
+        node_info
+    )
+    # ... 继续解析
+'''
+
+**辅助方法**：
+
+'''python
+@staticmethod
+def _extract_frame_metadata(
+    node_info: Node,
+) -> tuple[Optional[str], Optional[str], Optional[str], Optional[int]]:
+    """从 DOM.describeNode 节点中提取 iframe 相关的元数据。"""
+    content_document = node_info.get('contentDocument') or {}
+    parent_frame_id = node_info.get('frameId')
+    backend_node_id = node_info.get('backendNodeId')
+    frame_id = content_document.get('frameId')
+    document_url = (
+        content_document.get('documentURL')
+        or content_document.get('baseURL')
+        or node_info.get('documentURL')
+        or node_info.get('baseURL')
+    )
+    return frame_id, document_url, parent_frame_id, backend_node_id
+'''
+
+**结果**：
+
+- **如果 `frame_id` 存在**：很好！iframe 在进程内；进入步骤 4。
+- **如果 `frame_id` 缺失**：iframe 可能是 OOPIF 或未完全加载；进入步骤 2。
+
+---
+
+#### **步骤 2：通过所有者解析 Frame（backendNodeId 匹配）**
+
+**目标**：通过将 iframe 元素的 `backendNodeId` 与 frame 树中的 frame 所有者匹配，来找到 `frameId`。
+
+**策略**：
+
+1. 获取页面的 frame 树 (`Page.getFrameTree`)
+2. 对树中的每个 frame，调用 `DOM.getFrameOwner(frameId)` 来获取所属 iframe 元素的 `backendNodeId`
+3. 与我们的 iframe 的 `backendNodeId` 进行比较
+4. 当它们匹配时，我们就找到了正确的 `frameId`
+
+**代码**：
+
+'''python
+# 源自 pydoll/elements/web_element.py
+async def _resolve_frame_by_owner(
+    self,
+    base_handler: ConnectionHandler,
+    base_session_id: Optional[str],
+    backend_node_id: int,
+    current_document_url: Optional[str],
+) -> tuple[Optional[str], Optional[str]]:
+    """通过匹配所有者的 backend_node_id 来解析 frame id 和 URL。"""
+    owner_frame_id, owner_url = await self._find_frame_by_owner(
+        base_handler, base_session_id, backend_node_id
+    )
+    if not owner_frame_id:
+        return None, current_document_url
+    return owner_frame_id, owner_url or current_document_url
+
+async def _find_frame_by_owner(
+    self, handler: ConnectionHandler, session_id: Optional[str], backend_node_id: int
+) -> tuple[Optional[str], Optional[str]]:
+    """通过匹配 <iframe> 元素的所有者 backend_node_id 来查找 frame。"""
+    frame_tree = await self._get_frame_tree_for(handler, session_id)
+    for frame_node in WebElement._walk_frames(frame_tree):
+        candidate_frame_id = frame_node.get('id', '')
+        if not candidate_frame_id:
+            continue
+        owner_backend_id = await self._owner_backend_for(
+            handler, session_id, candidate_frame_id
+        )
+        if owner_backend_id == backend_node_id:
+            return candidate_frame_id, frame_node.get('url')
+    return None, None
+'''
+
+**为什么这是必要的**：
+
+- 对于跨域或延迟加载的 iframes，`DOM.describeNode` 有时不包含 `contentDocument.frameId`
+- frame 树总是包含所有 frames（甚至是 OOPIFs），所以我们可以间接找到它
+
+**结果**：
+
+- **如果找到 `frameId`**：进入步骤 4。
+- **如果仍然找不到**：iframe 很可能是一个在独立目标中的 OOPIF；进入步骤 3。
+
+---
+
+#### **步骤 3：通过父 Frame 解析 OOPIF**
+
+**目标**：对于跨进程 Iframes，找到目标，附加到它，并从该目标的 frame 树中获取 `frameId`。
+
+**策略**：
+
+**3a. 直接子目标查找**：
+
+1. 调用 `Target.getTargets()` 列出所有调试目标
+2. 筛选 `type` 为 `"iframe"` 或 `"page"` 且 `parentFrameId` 与我们的父 frame 匹配的目标
+3. 如果找到，使用 `Target.attachToTarget(targetId, flatten=true)` 附加到该目标
+4. 响应包含一个 `sessionId`
+5. 为该目标获取 `Page.getFrameTree(sessionId)`
+6. 此树的根 frame 就是我们 iframe 的 frame
+
+**3b. 备用方案：扫描所有目标**：
+
+1. 遍历所有 iframe/page 目标
+2. 附加到每个目标并获取其 frame 树
+3. 查找 `parentId` 与我们父 frame 匹配的子 frame
+4. **或者** 检查根 frame 的所有者（通过 `DOM.getFrameOwner`）是否与我们 iframe 的 `backendNodeId` 匹配
+
+**代码**：
+
+'''python
+# 源自 pydoll/elements/web_element.py
+async def _resolve_oopif_by_parent(
+    self,
+    parent_frame_id: str,
+    backend_node_id: Optional[int],
+) -> tuple[Optional[ConnectionHandler], Optional[str], Optional[str], Optional[str]]:
+    """使用父 frame id 解析 OOPIF。"""
+    browser_handler = ConnectionHandler(
+        connection_port=self._connection_handler._connection_port
+    )
+    targets_response: GetTargetsResponse = await browser_handler.execute_command(
+        TargetCommands.get_targets()
+    )
+    target_infos = targets_response.get('result', {}).get('targetInfos', [])
+    
+    # 策略 3a: 直接子节点
+    direct_children = [
+        target_info
+        for target_info in target_infos
+        if target_info.get('type') in {'iframe', 'page'}
+        and target_info.get('parentFrameId') == parent_frame_id
+    ]
+    if direct_children:
+        attach_response: AttachToTargetResponse = await browser_handler.execute_command(
+            TargetCommands.attach_to_target(
+                target_id=direct_children[0]['targetId'], flatten=True
+            )
+        )
+        attached_session_id = attach_response.get('result', {}).get('sessionId')
+        if attached_session_id:
+            frame_tree = await self._get_frame_tree_for(browser_handler, attached_session_id)
+            root_frame = (frame_tree or {}).get('frame', {})
+            return (
+                browser_handler,
+                attached_session_id,
+                root_frame.get('id'),
+                root_frame.get('url'),
+            )
+    
+    # 策略 3b: 扫描所有目标
+    for target_info in target_infos:
+        if target_info.get('type') not in {'iframe', 'page'}:
+            continue
+        attach_response = await browser_handler.execute_command(
+            TargetCommands.attach_to_target(
+                target_id=target_info.get('targetId', ''), flatten=True
+            )
+        )
+        attached_session_id = attach_response.get('result', {}).get('sessionId')
+        if not attached_session_id:
+            continue
+        
+        frame_tree = await self._get_frame_tree_for(browser_handler, attached_session_id)
+        
+        # 检查是否有匹配 parentId 的子节点
+        child_frame_id = WebElement._find_child_by_parent(frame_tree, parent_frame_id)
+        if child_frame_id:
+            return browser_handler, attached_session_id, child_frame_id, None
+        
+        # 检查根 frame 的所有者是否匹配我们的 backendNodeId
+        root_frame_id = (frame_tree or {}).get('frame', {}).get('id', '')
+        if not root_frame_id or backend_node_id is None:
+            continue
+        owner_backend_id = await self._owner_backend_for(
+            self._connection_handler, None, root_frame_id
+        )
+        if owner_backend_id == backend_node_id:
+            return browser_handler, attached_session_id, root_frame_id, None
+    
+    return None, None, None, None
+'''
+
+**结果**：
+
+- **如果 OOPIF 已解析**：我们现在有了 `sessionId`、`session_handler` 和 `frameId`；进入步骤 4。
+- **如果解析失败**：抛出 `InvalidIFrame` 异常（在 `_ensure_iframe_context` 中处理）。
+
+---
+
+#### **步骤 4：创建隔离世界**
+
+**目标**：在已解析的 frame 中创建一个独立的 JavaScript 执行上下文。
+
+**方法**：`Page.createIsolatedWorld(frameId, worldName='pydoll::iframe::<frameId>', grantUniversalAccess=true)`
+
+**参数**：
+- `frameId`：在其中创建隔离世界的 frame
+- `worldName`：世界的标识符（用于调试）
+- `grantUniversalAccess`：允许跨域访问（自动化需要）
+
+**响应**：`{ executionContextId: 42 }`
+
+**代码**：
+
+'''python
+# 源自 pydoll/elements/web_element.py
+@staticmethod
+async def _create_isolated_world_for_frame(
+    frame_id: str,
+    handler: ConnectionHandler,
+    session_id: Optional[str],
+) -> int:
+    """为给定的 frame 创建一个隔离世界。"""
+    create_command = PageCommands.create_isolated_world(
+        frame_id=frame_id,
+        world_name=f'pydoll::iframe::{frame_id}',
+        grant_universal_access=True,
+    )
+    if session_id:
+        create_command['sessionId'] = session_id
+    create_response: CreateIsolatedWorldResponse = await handler.execute_command(create_command)
+    execution_context_id = create_response.get('result', {}).get('executionContextId')
+    if not execution_context_id:
+        raise InvalidIFrame('无法为 iframe 创建隔离世界')
+    return execution_context_id
+'''
+
+**为什么需要隔离世界**：
+
+- **隔离**：我们的自动化 JavaScript 不会干扰 iframe 的 JavaScript
+- **反检测**：iframe 无法轻易检测到我们的存在
+- **一致性**：无论 iframe 的脚本环境如何，行为都是可预测的
+
+**结果**：我们有了一个 `executionContextId` 用于在 iframe 中运行 JavaScript。
+
+---
+
+#### **步骤 5：将 Iframe 文档固定为运行时对象**
+
+**目标**：获取对 iframe 的 `document.documentElement`（iframe 的 `<html>` 元素）的 `objectId` 引用。
+
+**方法**：`Runtime.evaluate(expression='document.documentElement', contextId=executionContextId)`
+
+**为什么我们需要这个**：
+
+- 以便在 iframe 内部执行**相对查询**（如 `element.querySelector()`）
+- `objectId` 允许使用 `Runtime.callFunctionOn(objectId, ...)`，并将 `this` 绑定到 iframe 的文档
+
+**代码**：
+
+'''python
+# 源自 pydoll/elements/web_element.py
+async def _set_iframe_document_object_id(self, execution_context_id: int) -> None:
+    """在 iframe 上下文中评估 document.documentElement 并缓存其 object id。"""
+    evaluate_command = RuntimeCommands.evaluate(
+        expression='document.documentElement',
+        context_id=execution_context_id,
+    )
+    if self._iframe_context and self._iframe_context.session_id:
+        evaluate_command['sessionId'] = self._iframe_context.session_id
+    evaluate_response: EvaluateResponse = await (
+        (self._iframe_context.session_handler if self._iframe_context else None)
+        or self._connection_handler
+    ).execute_command(evaluate_command)
+    result_object = evaluate_response.get('result', {}).get('result', {})
+    document_object_id = result_object.get('objectId')
+    if not document_object_id:
+        raise InvalidIFrame('无法获取 iframe 的文档引用')
+    if self._iframe_context:
+        self._iframe_context.document_object_id = document_object_id
+'''
+
+**结果**：`_IFrameContext` 现在已完全填充并缓存在 `WebElement` 上。
+
+---
+
+#### **步骤 6：缓存和传播上下文**
+
+**目标**：将解析的上下文存储在 iframe 元素上，并将其传播到在 iframe 中找到的所有子元素。
+
+**缓存**：
+
+'''python
+# 源自 pydoll/elements/web_element.py
+def _init_iframe_context(
+    self,
+    frame_id: str,
+    document_url: Optional[str],
+    session_handler: Optional[ConnectionHandler],
+    session_id: Optional[str],
+) -> None:
+    """在此元素上初始化并缓存 iframe 上下文。"""
+    self._iframe_context = _IFrameContext(frame_id=frame_id, document_url=document_url)
+    # 清理路由属性（这些是用于嵌套 iframe 的）
+    if hasattr(self, '_routing_session_handler'):
+        delattr(self, '_routing_session_handler')
+    if hasattr(self, '_routing_session_id'):
+        delattr(self, '_routing_session_id')
+    # 如果需要，存储 OOPIF 路由
+    if session_handler and session_id:
+        self._iframe_context.session_handler = session_handler
+        self._iframe_context.session_id = session_id
+'''
+
+**传播**（在 iframe 内部查找元素时）：
+
+'''python
+# 源自 pydoll/elements/mixins/find_elements_mixin.py
+def _apply_iframe_context_to_element(
+    self, element: WebElement, iframe_context: _IFrameContext | None
+) -> None:
+    """将 iframe 上下文传播到新创建的元素。"""
+    if not iframe_context:
+        return
+    
+    # 如果子元素也是一个 iframe，设置路由
+    if getattr(element, 'is_iframe', False):
+        element._routing_session_handler = (
+            iframe_context.session_handler or self._connection_handler
+        )
+        element._routing_session_id = iframe_context.session_id
+        element._routing_parent_frame_id = iframe_context.frame_id
+        return
+    
+    # 否则，注入父 iframe 的上下文
+    element._iframe_context = iframe_context
+'''
+
+**为什么传播很重要**：
+
+- 在 iframe 内部找到的元素会继承 iframe 的上下文
+- 这确保了后续操作（点击、键入、查找嵌套元素）自动使用正确的路由
+- 嵌套的 iframes 接收路由信息，以便它们可以相对于父 iframe 解析自己的上下文
+
+---
+
+## 会话路由和扁平化模式
+
+### 扁平化会话模型
+
+正如在 [深度解析 → 基础 → CDP](./cdp.md) 中讨论的，传统的 CDP 对每个目标使用单独的 WebSocket 连接。**扁平化模式 (Flattened mode)** 是一种优化，所有目标共享一个 WebSocket 连接，命令使用 `sessionId` 进行路由。
+
+'''mermaid
+graph TB
+    subgraph "传统模式"
+        WS1[WebSocket 1] --> MainPage[主页面目标]
+        WS2[WebSocket 2] --> Iframe1[OOPIF 目标 1]
+        WS3[WebSocket 3] --> Iframe2[OOPIF 目标 2]
+    end
+    
+    subgraph "扁平化模式"
+        WS[单个 WebSocket] --> Router{CDP 路由器}
+        Router -->|sessionId: null| MainPage2[主页面目标]
+        Router -->|sessionId: session-1| Iframe3[OOPIF 目标 1]
+        Router -->|sessionId: session-2| Iframe4[OOPIF 目标 2]
+    end
+'''
+
+### 会话路由如何工作
+
+**附加到 OOPIF 时**：
+
+'''python
+response = await handler.execute_command(
+    TargetCommands.attach_to_target(targetId="iframe-target-id", flatten=True)
+)
+session_id = response['result']['sessionId']  # 例如 "8E6C...-1234"
+'''
+
+**向该 OOPIF 发送命令时**：
+
+'''python
+command = PageCommands.get_frame_tree()
+command['sessionId'] = 'session-1'  # 路由到 OOPIF
+response = await handler.execute_command(command)
+'''
+
+浏览器的 CDP 实现会根据 `sessionId` 将命令路由到正确的目标。
+
+### Pydoll 的命令路由
+
+Pydoll 元素发送的每个命令都会自动路由到正确的目标：
+
+'''python
+# 源自 pydoll/elements/mixins/find_elements_mixin.py
+def _resolve_routing(self) -> tuple[ConnectionHandler, Optional[str]]:
+    """为当前上下文解析 handler 和 sessionId。"""
+    # 检查元素是否具有带 OOPIF 路由的 iframe 上下文
+    iframe_context = getattr(self, '_iframe_context', None)
+    if iframe_context and getattr(iframe_context, 'session_handler', None):
+        return iframe_context.session_handler, getattr(iframe_context, 'session_id', None)
+    
+    # 检查元素是否从父 iframe 继承了路由
+    routing_handler = getattr(self, '_routing_session_handler', None)
+    if routing_handler is not None:
+        return routing_handler, getattr(self, '_routing_session_id', None)
+    
+    # 默认：使用标签页的主连接
+    return self._connection_handler, None
+
+async def _execute_command(
+    self, command: Command[T_CommandParams, T_CommandResponse]
+) -> T_CommandResponse:
+    """通过解析的 handler 执行 CDP 命令（60 秒超时）。"""
+    handler, session_id = self._resolve_routing()
+    if session_id:
+        command['sessionId'] = session_id
+    return await handler.execute_command(command, timeout=60)
+'''
+
+**路由逻辑**：
+
+1. **OOPIF iframe 内的元素**：使用 `iframe_context.session_id` 和 `iframe_context.session_handler`
+2. **嵌套 iframe（OOPIF 的子节点）**：使用继承的 `_routing_session_id` 和 `_routing_session_handler`
+3. **常规元素或进程内 iframe**：使用主连接 (`_connection_handler`)，无 `sessionId`
+
+### 扩展的命令类型
+
+为了使 `sessionId` 类型安全，Pydoll 扩展了 `Command` TypedDict：
+
+'''python
+# 源自 pydoll/protocol/base.py
+class Command(TypedDict, Generic[T_CommandParams, T_CommandResponse]):
+    """所有命令的基础结构。"""
+    id: NotRequired[int]
+    method: str
+    params: NotRequired[T_CommandParams]
+    sessionId: NotRequired[str]  # 为扁平化会话路由添加
+'''
+
+这允许类型检查器将 `command['sessionId'] = '...'` 识别为有效，而无需抑制类型警告。
+
+---
+
+## 性能考量
+
+### 缓存策略
+
+**首次访问是昂贵的**：
+
+- `DOM.describeNode`：1 次往返
+- Frame 树检索：1+ 次往返（主目标 + OOPIF 目标）
+- 每个 frame 的 `DOM.getFrameOwner`：N 次往返（最坏情况下）
+- `Target.getTargets` + 附加：1 + M 次往返（M = OOPIF 目标数量）
+- `Page.createIsolatedWorld`：1 次往返
+- `Runtime.evaluate` (文档)：1 次往返
+
+**总计**：根据页面结构，可能需要 5-20+ 次往返。
+
+**后续访问是 O(1)**：
+
+- `iframe_context` 缓存在 `WebElement` 实例上
+- 多次访问 `await iframe.iframe_context` 会立即返回缓存的值
+- 在 iframe 中找到的所有元素都会继承上下文（无需重新解析）
+
+### 优化：直接子目标查找
+
+在 `_resolve_oopif_by_parent` 中，Pydoll 首先按 `parentFrameId` 检查直接子节点：
+
+'''python
+direct_children = [
+    target_info
+    for target_info in target_infos
+    if target_info.get('type') in {'iframe', 'page'}
+    and target_info.get('parentFrameId') == parent_frame_id
+]
+if direct_children:
+    # 立即附加，跳过扫描所有目标
+'''
+
+**为什么这有帮助**：
+
+- 大多数 OOPIFs 都正确设置了 `parentFrameId`
+- 避免了推测性地附加到每个目标
+- 在常见情况下，将往返次数从 O(目标数量) 减少到 O(1)
+
+### 异步并行解析（未来增强）
+
+目前，frame 所有者匹配是顺序的（逐个检查每个 frame）。未来的优化可以并行化：
+
+'''python
+# 当前（顺序）
+for frame_node in frames:
+    owner = await self._owner_backend_for(...)
+    if owner == backend_node_id:
+        return frame_node['id']
+
+# 潜在（并行）
+results = await asyncio.gather(*(
+    self._owner_backend_for(..., frame['id'])
+    for frame in frames
+))
+for i, owner in enumerate(results):
+    if owner == backend_node_id:
+        return frames[i]['id']
+'''
+
+这将把延迟从 `N * RTT` 减少到 `RTT`（其中 RTT = 往返时间）。
+
+---
+
+## 失败模式和调试
+
+### 常见失败场景
+
+#### 1. **InvalidIFrame: 无法解析 frameId**
+
+**原因**：
+
+- iframe 是动态创建的，尚未完全初始化
+- iframe 被具有限制性策略的沙盒化
+- 网络问题延迟了 iframe 加载
+
+**解决方案**：
+
+- **等待 iframe**：使用带超时的 `await tab.find(id='iframe', timeout=10)`
+- **检查 sandbox 属性**：限制性沙盒 (`<iframe sandbox>`) 可能会阻止某些 CDP 操作
+- **重试策略**：实现带指数退避的重试逻辑
+
+**调试**：
+
+'''python
+try:
+    iframe = await tab.find(id='problem-iframe')
+    context = await iframe.iframe_context
+except InvalidIFrame as e:
+    # 检查我们拥有的信息
+    node_info = await iframe._describe_node(object_id=iframe._object_id)
+    print(f"节点信息: {node_info}")
+    
+    # 手动检查 frame 树
+    frame_tree = await WebElement._get_frame_tree_for(tab._connection_handler, None)
+    print(f"Frame 树: {frame_tree}")
+'''
+
+#### 2. **InvalidIFrame: 无法创建隔离世界**
+
+**原因**：
+
+- 在解析步骤之间，Frame 已被销毁/导航离开
+- Chrome 错误（罕见）
+
+**解决方案**：
+
+- **重新解析上下文**：清除缓存的上下文并重新访问
+- **检查导航**：确保 iframe 在解析期间没有导航
+
+**调试**：
+
+'''python
+# 清除缓存并重试
+iframe._iframe_context = None
+context = await iframe.iframe_context
+'''
+
+#### 3. **InvalidIFrame: 无法获取文档引用**
+
+**原因**：
+
+- 隔离世界已创建，但文档尚未准备好
+- Frame 即将导航
+
+**解决方案**：
+
+- 等待 frame 加载：使用 Page 事件检测 `Page.frameNavigated` 或 `Page.loadEventFired`
+- 稍作延迟后重试
+
+#### 4. **会话路由失败（命令超时或返回错误）**
+
+**原因**：
+
+- OOPIF 目标已分离（页面导航，iframe 被移除）
+- `sessionId` 已过时
+
+**解决方案**：
+
+- **重新附加到目标**：创建一个新的 `ConnectionHandler` 并重新解析 OOPIF
+- **验证目标**：调用 `Target.getTargets()` 检查目标是否仍然存在
+
+**调试**：
+
+'''python
+# 检查会话是否仍然有效
+targets = await handler.execute_command(TargetCommands.get_targets())
+active_sessions = [t['targetId'] for t in targets['result']['targetInfos']]
+print(f"活动目标: {active_sessions}")
+
+if iframe._iframe_context and iframe._iframe_context.session_id:
+    print(f"我们的会话: {iframe._iframe_context.session_id}")
+'''
+
+### 诊断工具
+
+#### 启用 CDP 日志记录
+
+'''python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger('pydoll')
+logger.setLevel(logging.DEBUG)
+'''
+
+这将记录所有 CDP 命令和响应，有助于追踪 iframe 解析步骤。
+
+#### 检查 iframe 上下文
+
+'''python
+iframe = await tab.find(id='my-iframe')
+ctx = await iframe.iframe_context
+
+print(f"Frame ID: {ctx.frame_id}")
+print(f"文档 URL: {ctx.document_url}")
+print(f"执行上下文 ID: {ctx.execution_context_id}")
+print(f"文档对象 ID: {ctx.document_object_id}")
+print(f"会话 ID (OOPIF): {ctx.session_id}")
+print(f"会话 Handler: {ctx.session_handler}")
+'''
+
+---
+
+## 结论
+
+Pydoll 的 iframe 处理代表了对 CDP frame 管理能力的复杂实现。通过理解：
+
+- **DOM**：树结构和节点标识
+- **Iframes**：独立的文档上下文和安全边界
+- **OOPIFs**：站点隔离和基于目标的架构
+- **CDP 域**：Page、DOM、Target、Runtime 的协调
+- **执行上下文**：用于纯净自动化的隔离世界
+- **标识符**：backendNodeId、frameId、targetId、sessionId、executionContextId、objectId 之间的关系
+- **解析管道**：用于查找 frames 的多阶段回退策略
+- **会话路由**：扁平化模式和自动命令路由
+
+您就能理解为什么 Pydoll 消除了手动上下文切换。这种复杂性是真实存在的，但 Pydoll 将其抽象在一个简单、直观的 API 背后：
+
+'''python
+iframe = await tab.find(id='login-frame')
+username = await iframe.find(name='username')
+await username.type_text('user@example.com')
+'''
+
+三行代码。没有上下文切换。没有目标附加。没有会话管理。它就是能用。
+
+---
+
+## 进一步阅读
+
+- **CDP 规范**：[Chrome DevTools 协议 - Page 域](https://chromedevtools.github.io/devtools-protocol/tot/Page/)
+- **CDP 规范**：[Chrome DevTools 协议 - DOM 域](https://chromedevtools.github.io/devtools-protocol/tot/DOM/)
+- **CDP 规范**：[Chrome DevTools 协议 - Target 域](https://chromedevtools.github.io/devtools-protocol/tot/Target/)
+- **CDP 规范**：[Chrome DevTools 协议 - Runtime 域](https://chromedevtools.github.io/devtools-protocol/tot/Runtime/)
+- **Chromium 站点隔离**：[站点隔离 - Chromium 项目](https://www.chromium.org/Home/chromium-security/site-isolation/)
+- **内容脚本和隔离世界**：[Chrome 扩展 - 内容脚本](https://developer.chrome.com/docs/extensions/mv3/content_scripts/)
+- **Pydoll 文档**：[深度解析 → 基础 → Chrome DevTools 协议](./cdp.md)
+- **Pydoll 文档**：[功能 → 自动化 → IFrames](../../features/automation/iframes.md)
+
+---
+
+!!! tip "设计理念"
+    Pydoll iframe 处理的目标是**符合人体工程学的自动化**：编写代码时就好像 iframes 不存在一样，让库来处理复杂性。这次深度解析展示了幕后发生的事情——但在您的自动化脚本中，您永远不必考虑它。
\ No newline at end of file
diff --git a/docs/zh/features/automation/iframes.md b/docs/zh/features/automation/iframes.md
index 02be1027..caec41dd 100644
--- a/docs/zh/features/automation/iframes.md
+++ b/docs/zh/features/automation/iframes.md
@@ -1,10 +1,14 @@
-# 处理IFrame
+# 处理 IFrame
 
-IFrame（内联框架）是浏览器自动化中最棘手的方面之一。Pydoll提供清晰直观的iframe交互API，抽象化了CDP目标管理的复杂性。
+现代网页经常使用 `<iframe>` 嵌入其他文档。旧版本的 Pydoll 需要手动调用 `tab.get_frame()` 把 iframe 转成 `Tab` 并管理 CDP target。**现在不再需要这样做。**  
+iframe 现在和其他 `WebElement` 一样：可以直接调用 `find()`、`query()`、`execute_script()`、`inner_html`、`text` 等方法，Pydoll 会自动在正确的浏览上下文中执行（无论是否跨域）。
+
+!!! info "更轻松的心智模型"
+    把 iframe 当成页面上的普通 `div`。找到它后，就以它为起点继续查找内部元素。Pydoll 会自动创建隔离执行环境，缓存上下文，并处理多层嵌套。
 
 ## 快速入门
 
-### 基础IFrame交互
+### 与页面上的第一个 iframe 交互
 
 ```python
 import asyncio
@@ -14,176 +18,96 @@ async def interact_with_iframe():
     async with Chrome() as browser:
         tab = await browser.start()
         await tab.go_to('https://example.com/page-with-iframe')
-        
-        # 查找iframe元素
-        iframe_element = await tab.find(tag_name='iframe', id='content-frame')
-        
-        # 获取iframe的Tab实例
-        iframe = await tab.get_frame(iframe_element)
-        
-        # 现在可以与iframe内部的元素交互
-        button = await iframe.find(id='submit-button')
-        await button.click()
-        
-        # 查找并填写iframe内的表单
-        username = await iframe.find(name='username')
+
+        iframe = await tab.find(tag_name='iframe', id='content-frame')
+
+        # 以下调用都会在 iframe 内部执行
+        title = await iframe.find(tag_name='h1')
+        await title.click()
+
+        form = await iframe.find(id='login-form')
+        username = await form.find(name='username')
         await username.type_text('john_doe')
 
 asyncio.run(interact_with_iframe())
 ```
 
-!!! tip "IFrame就是Tab"
-    在Pydoll中，iframe返回一个`Tab`对象。这意味着**Tab上所有可用的方法都适用于iframe**：`find()`、`query()`、`execute_script()`、`take_screenshot()`等等。
+### 多层 iframe
 
-## 理解IFrame
+逐层查找即可：
 
-### 什么是IFrame？
-
-`<iframe>`（内联框架）是一个HTML元素，可在当前页面内嵌入另一个HTML文档。可以将其视为"浏览器窗口中的浏览器窗口"。
+```python
+outer = await tab.find(id='outer-frame')
+inner = await outer.find(tag_name='iframe')  # 在外层 iframe 内继续查找
 
-```html
-<html>
-  <body>
-    <h1>主页面</h1>
-    <p>这是主文档</p>
-    
-    <!-- 这个iframe加载一个完全独立的文档 -->
-    <iframe src="https://other-site.com/content.html" id="my-frame">
-    </iframe>
-  </body>
-</html>
+submit_button = await inner.find(id='submit')
+await submit_button.click()
 ```
 
-每个iframe：
-
-- 拥有自己**独立的DOM**（文档对象模型）
-- 加载自己的HTML、CSS和JavaScript
-- 可以来自不同域（跨域）
-- 在隔离的浏览上下文中运行
+流程始终相同：
 
-### 为什么无法直接交互
+1. 找到需要的 iframe 元素。
+2. 使用该 `WebElement` 作为新的查找范围。
+3. 如果还有内层 iframe，重复以上步骤。
 
-这段代码**无法按预期工作**：
+### 在 iframe 中执行 JavaScript
 
 ```python
-# ❌ 这无法找到iframe内部的元素
-button = await tab.find(id='button-inside-iframe')
+iframe = await tab.find(tag_name='iframe')
+result = await iframe.execute_script('return document.title', return_by_value=True)
+print(result['result']['result']['value'])
 ```
 
-**为什么？** 因为`tab.find()`搜索的是**主页面的DOM**。iframe拥有**完全独立的DOM**，无法从父页面访问。
+Pydoll 会自动在 iframe 的隔离上下文中执行脚本，同样适用于跨域 iframe。
 
-可以这样理解：
+## 为什么这样更好？
 
-```
-主页面DOM                      IFrame DOM（独立！）
-├── <html>                    ├── <html>
-│   ├── <body>                │   ├── <body>
-│   │   ├── <div>             │   │   ├── <div>
-│   │   └── <iframe>          │   │   └── <button id="inside">
-│   │       (独立世界)        │   └── </body>
-│   └── </body>               └── </html>
-└── </html>
-```
-
-!!! info "隔离的浏览上下文"
-    IFrame创建了所谓的**隔离浏览上下文**。这种隔离是一项安全功能，防止恶意iframe访问或操纵父页面的内容。
+- **直观：** DOM 树是什么样子，就怎么编写脚本。
+- **无需了解 CDP 细节：** 隔离世界、执行上下文、target 缓存全部由 Pydoll 处理。
+- **天然支持嵌套：** 每次查找都以当前元素为范围，多层结构依然清晰。
+- **统一 API：** 不再需要在 `Tab` 与 `WebElement` 方法之间切换。
 
-### Pydoll如何解决这个问题
+!!! tip "`Tab.get_frame()` 将被移除"
+    现在调用 `Tab.get_frame()` 会抛出 `DeprecationWarning`，并将在未来版本删除。请尽快改为直接使用 iframe 元素。
 
-在底层，Pydoll使用Chrome DevTools Protocol（CDP）来：
+## 常见模式
 
-1. **识别iframe目标**：每个iframe都有自己的CDP目标ID
-2. **创建新的Tab实例**：此Tab作用域限定在iframe的DOM
-3. **提供完全访问**：所有Tab方法都可在iframe的隔离DOM上运行
+### 截取 iframe 内部元素的截图
 
 ```python
-# 内部发生的过程：
-iframe_element = await tab.find(tag_name='iframe')  # 查找<iframe>标签
-frame = await tab.get_frame(iframe_element)         # 获取iframe的CDP目标
-
-# 现在'frame'是一个操作iframe DOM的Tab
-button = await frame.find(id='button-inside-iframe')  # ✅ 可以运行！
+iframe = await tab.find(tag_name='iframe')
+chart = await iframe.find(id='sales-chart')
+await chart.take_screenshot('chart.png')
 ```
 
-### 技术深入探讨：CDP目标
-
-当您调用`tab.get_frame()`时，Pydoll会：
-
-1. **提取`src`属性**：从iframe元素中提取
-2. **查询CDP获取所有目标**：使用`Target.getTargets()`
-3. **匹配iframe URL**：找到其对应的目标ID
-4. **创建Tab实例**：使用该目标ID
-
-每个目标都有：
-
-- **唯一的目标ID**：标识浏览上下文
-- **独立的WebSocket连接**：用于隔离的CDP通信
-- **自己的文档树**：完全独立于父页面
+### 遍历多个 iframe
 
 ```python
-# tab.py内部实现：
-async def get_frame(self, frame: WebElement) -> Tab:
-    # 获取iframe的源URL
-    frame_url = frame.get_attribute('src')
-    
-    # 查找匹配此URL的目标
-    targets = await self._browser.get_targets()
-    iframe_target = next((t for t in targets if t['url'] == frame_url), None)
-    
-    # 为此iframe的目标创建Tab
-    target_id = iframe_target['targetId']
-    tab = Tab(self._browser, target_id=target_id, ...)
-    
-    return tab  # 现在可以将iframe作为Tab进行交互！
+iframes = await tab.find(tag_name='iframe', find_all=True)
+for frame in iframes:
+    heading = await frame.find(tag_name='h2')
+    print(await heading.text)
 ```
 
-!!! warning "IFrame必须有有效的`src`"
-    iframe必须具有有效的`src`属性，Pydoll才能定位其CDP目标。使用`srcdoc`或动态注入内容的iframe可能无法与`get_frame()`配合使用。
-
-## 对比：主页面 vs IFrame
-
-| 方面 | 主页面 | IFrame |
-|--------|-----------|--------|
-| **DOM** | 自己的文档树 | 独立的文档树 |
-| **CDP目标** | 一个目标ID | 不同的目标ID |
-| **元素搜索** | `tab.find()` | `iframe.find()` |
-| **JavaScript上下文** | 主页面的`window` | iframe的`window` |
-| **源** | 页面的源 | 可以是跨域 |
-| **存储** | 与页面共享 | 可以是隔离的 |
-
-## IFrame中的截图
-
-!!! info "截图限制"
-    `tab.take_screenshot()`仅适用于**顶级目标**。对于iframe截图，请在iframe**内部**的元素上使用`element.take_screenshot()`。
+### 等待 iframe 内容加载
 
 ```python
-import asyncio
-from pydoll.browser.chromium import Chrome
-
-async def iframe_screenshot():
-    async with Chrome() as browser:
-        tab = await browser.start()
-        await tab.go_to('https://example.com/iframe-page')
-        
-        iframe_element = await tab.find(tag_name='iframe')
-        frame = await tab.get_frame(iframe_element)
-        
-        # ❌ 这对iframe不起作用
-        # await frame.take_screenshot('frame.png')
-        
-        # ✅ 而是对iframe内部的元素截图
-        content = await frame.find(id='content')
-        await content.take_screenshot('iframe-content.png')
-
-asyncio.run(iframe_screenshot())
+iframe = await tab.find(tag_name='iframe')
+await iframe.wait_until(is_visible=True, timeout=10)
+banner = await iframe.find(id='promo-banner')
 ```
 
-## 了解更多
+## 最佳实践
+
+- **把 iframe 作为作用域：** 在 iframe `WebElement` 上调用 `find`、`query`、`execute_script` 等方法。
+- **避免 `tab.find` 查找内部元素：** 它只能访问顶级文档。
+- **复用引用：** Pydoll 会缓存 iframe 的上下文，可重复使用。
+- **现有工作流保持一致：** 滚动、截图、等待、脚本执行、读取属性等操作与普通元素完全一致。
 
-要深入了解iframe机制和CDP目标：
+## 延伸阅读
 
-- **[深入探讨：Tab域](../../deep-dive/architecture/tab-domain.md#iframe-handling)**：iframe目标解析的技术细节
-- **[深入探讨：Browser域](../../deep-dive/architecture/browser-domain.md#target-management)**：CDP如何管理多个目标
-- **[元素查找](../element-finding.md#scoped-search)**：理解元素搜索中的DOM作用域
+- **[元素查找](../element-finding.md)** —— 介绍查找范围与链式查询。
+- **[截图与 PDF](screenshots-and-pdfs.md)** —— 讲解如何获取视觉输出。
+- **[事件系统](../advanced/event-system.md)** —— 以事件驱动方式监听页面变化（包括 iframe）。
 
-IFrame可能看起来很复杂，但Pydoll的API使其像常规页面元素一样容易使用。关键是要理解每个iframe都是其自己的隔离Tab，拥有独立的DOM和CDP目标。
+在新模型下，iframe 不再是“特殊情况”。把它视为普通 DOM 节点，专注于自动化逻辑，其余复杂度交给 Pydoll 处理。
\ No newline at end of file
diff --git a/docs/zh/features/automation/screenshots-and-pdfs.md b/docs/zh/features/automation/screenshots-and-pdfs.md
index ace3f2f5..47719c42 100644
--- a/docs/zh/features/automation/screenshots-and-pdfs.md
+++ b/docs/zh/features/automation/screenshots-and-pdfs.md
@@ -301,17 +301,13 @@ async def safe_screenshot():
         
         # IFrame截图限制
         iframe_element = await tab.find(tag_name='iframe')
-        frame = await tab.get_frame(iframe_element)
-        
-        try:
-            # 这对iframe不起作用
-            await frame.take_screenshot('iframe.png')
-        except TopLevelTargetRequired:
-            print("对iframe内容使用element.take_screenshot()")
-            
-            # 正确方法
-            content = await frame.find(id='content')
-            await content.take_screenshot('iframe-content.jpeg')
+
+        # 仍然无效：顶层截图不会包含 iframe 内容
+        # await tab.take_screenshot('frame.png')
+
+        # 选择 iframe 内部的元素进行截图
+        content = await iframe_element.find(id='content')
+        await content.take_screenshot('iframe-content.png')
 ```
 
 ## 了解更多
diff --git a/docs/zh/features/browser-management/tabs.md b/docs/zh/features/browser-management/tabs.md
index 70c38cbc..f6e21bf6 100644
--- a/docs/zh/features/browser-management/tabs.md
+++ b/docs/zh/features/browser-management/tabs.md
@@ -81,8 +81,8 @@ async def tab_registry_demonstration():
 asyncio.run(tab_registry_demonstration())
 ```
 
-!!! info "浏览器管理的注册表"
-    Browser 类管理一个以 `target_id` 为键的 `_tabs_opened` 字典。当你请求一个标签页（通过 `new_tab()`、`get_opened_tabs()` 或 `get_frame()`）时，Browser 首先检查此注册表。如果该 `target_id` 已存在 Tab 实例，则返回现有实例；否则，创建新实例并存储在注册表中。
+!!! info "Browser 管理的注册表"
+    Browser 类管理一个以 `target_id` 为键的 `_tabs_opened` 字典。当你请求一个标签页（通过 `new_tab()` 或 `get_opened_tabs()`）时，Browser 会先检查该注册表。如果已经存在对应的 Tab，就复用该实例；否则创建新的并缓存。（IFrame 现在作为普通元素处理，不再注册为独立的 Tab。）
 
 ## 创建和管理标签页
 
diff --git a/docs/zh/features/element-finding.md b/docs/zh/features/element-finding.md
index 302b57e5..e9acf990 100644
--- a/docs/zh/features/element-finding.md
+++ b/docs/zh/features/element-finding.md
@@ -596,24 +596,13 @@ iFrame 在浏览器自动化中提出了特殊的挑战，因为它们具有单
 
 ```mermaid
 flowchart TB
-    subgraph MainPage[主页面上下文]
-        MainDOM[主页面 DOM]
-        IFrameTag[iframe 元素]
-        MainDOM --> IFrameTag
-    end
-    
-    subgraph IFrameContext[iFrame - 单独的 DOM]
-        IFrameDOM[iFrame DOM]
-        IFrameElements[iFrame 内的元素]
-        IFrameDOM --> IFrameElements
-    end
-    
-    IFrameTag -.->|get_frame 方法| IFrameContext
-    
-    MainPage --> MainSearch[tab.find - 主 DOM]
-    IFrameContext --> IFrameSearch[frame.find - iFrame DOM]
-```
+    Main[tab]
+    Frame["iframe WebElement"]
+    Content["iframe 内部元素"]
 
+    Main -->|"find('iframe')"| Frame
+    Frame -->|"find('button#submit')"| Content
+```
 ```python
 import asyncio
 from pydoll.browser.chromium import Chrome
@@ -622,29 +611,25 @@ async def iframe_interaction():
     async with Chrome() as browser:
         tab = await browser.start()
         await tab.go_to('https://example.com/page-with-iframe')
-        
-        # 查找 iframe 元素
-        iframe_element = await tab.query("iframe.embedded-content", timeout=10)
-        
-        # 获取 iframe 内容的 Tab 实例
-        frame = await tab.get_frame(iframe_element)
-        
-        # 现在在 iframe 上下文中使用所有 Tab 方法
-        iframe_button = await frame.find(tag_name="button", class_name="submit")
+
+        iframe = await tab.query("iframe.embedded-content", timeout=10)
+
+        # WebElement 辅助方法会自动在 iframe 内执行
+        iframe_button = await iframe.find(tag_name="button", class_name="submit")
         await iframe_button.click()
-        
-        iframe_input = await frame.find(id="captcha-input")
+
+        iframe_input = await iframe.find(id="captcha-input")
         await iframe_input.type_text("verification-code")
-        
-        # 在 iframe 内查询
-        iframe_links = await frame.query("a", find_all=True)
-        print(f"在 iframe 中找到 {len(iframe_links)} 个链接")
+
+        # 如果还有内层 iframe，继续链式查找
+        inner_iframe = await iframe.find(tag_name="iframe")
+        download_link = await inner_iframe.find(text="下载 PDF")
+        await download_link.click()
 
 asyncio.run(iframe_interaction())
 ```
-
-!!! note "iFrame 目标和截图"
-    在 iframe 内工作时，某些方法如 `tab.take_screenshot()` 将不起作用，因为 Chrome 的 CDP 无法直接捕获子目标的截图。请改用 `element.take_screenshot()`，它在 iframe 内工作。
+!!! note "iframe 中的截图"
+    `tab.take_screenshot()` 只能作用于顶层 target。想要截取 iframe 内容，请锁定 iframe 内部的某个元素，使用 `element.take_screenshot()`。
 
 ## 错误处理策略
 
diff --git a/docs/zh/features/index.md b/docs/zh/features/index.md
index 3e2aea5a..1320bc3d 100644
--- a/docs/zh/features/index.md
+++ b/docs/zh/features/index.md
@@ -28,7 +28,7 @@
 
 **[文件操作](automation/file-operations.md)**：文件处理在浏览器自动化中可能很棘手。Pydoll 为上传和下载提供了强大的解决方案，`expect_download` 上下文管理器提供了优雅的异步下载完成处理。
 
-**[IFrame 交互](automation/iframes.md)**：使用 `get_frame()` 方法无缝处理嵌入式框架。获取 iframe 内容的完整 Tab 接口，使您能够在框架内使用 Pydoll 的所有元素查找和交互功能。
+**[IFrame 交互](automation/iframes.md)**：把 iframe 当成普通元素——定位 iframe 后在其内部继续查找，无需额外 target 或 Tab。
 
 **[截图和 PDF](automation/screenshots-and-pdfs.md)**：从您的自动化会话中捕获视觉内容。无论您需要用于视觉回归测试的整页截图、用于调试的元素特定捕获，还是用于归档的 PDF 导出，Pydoll 都能满足您的需求。
 
diff --git a/mkdocs.yml b/mkdocs.yml
index f388dde8..3edf083b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -42,6 +42,7 @@ nav:
           - Chrome DevTools Protocol: deep-dive/fundamentals/cdp.md
           - Connection Layer: deep-dive/fundamentals/connection-layer.md
           - Python Type System: deep-dive/fundamentals/typing-system.md
+          - Iframes & Contexts: deep-dive/fundamentals/iframes-and-contexts.md
       - Internal Architecture:
           - Overview: deep-dive/architecture/index.md
           - Browser Domain: deep-dive/architecture/browser-domain.md
diff --git a/pydoll/browser/chromium/base.py b/pydoll/browser/chromium/base.py
index dfa7e674..eb76ee14 100644
--- a/pydoll/browser/chromium/base.py
+++ b/pydoll/browser/chromium/base.py
@@ -213,8 +213,9 @@ async def stop(self):
         logger.info('Stopping browser process')
         await self._execute_command(BrowserCommands.close())
         self._browser_process_manager.stop_process()
-        self._temp_directory_manager.cleanup()
         await self._connection_handler.close()
+        await asyncio.sleep(0.5 if os.name == 'nt' else 0.1)
+        self._temp_directory_manager.cleanup()
         logger.info('Browser process stopped and resources cleaned up')
 
     async def close(self):
diff --git a/pydoll/browser/managers/temp_dir_manager.py b/pydoll/browser/managers/temp_dir_manager.py
index 919a3397..337bda59 100644
--- a/pydoll/browser/managers/temp_dir_manager.py
+++ b/pydoll/browser/managers/temp_dir_manager.py
@@ -1,4 +1,5 @@
 import logging
+import os
 import shutil
 import time
 from pathlib import Path
@@ -80,16 +81,37 @@ def handle_cleanup_error(self, func: Callable[[str], None], path: str, exc_info:
             Handles Chromium-specific locked files like CrashpadMetrics.
         """
         matches = ['CrashpadMetrics-active.pma']
+        match_substrings = ['Safe Browsing', 'Safe Browsing Cookies']
+        # Extra patterns commonly locked on Windows; compare case-insensitively
+        windows_locked_substrings = [
+            '\\cache\\',
+            '/cache/',
+            'no_vary_search',
+            'journal.baj',
+            '\\network\\cookies',
+            '/network/cookies',
+            'cookies-journal',
+        ]
         exc_type, exc_value, _ = exc_info
 
         if exc_type is PermissionError:
-            if Path(path).name in matches:
+            filename = Path(path).name
+            # Known Chromium files that may remain locked briefly on Windows
+            path_lc = path.lower()
+            windows_match = os.name == 'nt' and any(
+                substr in path_lc for substr in windows_locked_substrings
+            )
+            if (
+                filename in matches
+                or any(substr in path for substr in match_substrings)
+                or windows_match
+            ):
                 try:
                     self.retry_process_file(func, path)
                     return
                 except PermissionError:
-                    logger.warning(f'Failed retrying cleanup for locked file: {path}')
-                    raise exc_value
+                    logger.warning(f'Ignoring locked Chrome file during cleanup: {path}')
+                    return
         elif exc_type is OSError:
             return
         raise exc_value
@@ -104,3 +126,23 @@ def cleanup(self):
         for temp_dir in self._temp_dirs:
             logger.info(f'Cleaning up temp directory: {temp_dir.name}')
             shutil.rmtree(temp_dir.name, onerror=self.handle_cleanup_error)
+            remaining = Path(temp_dir.name)
+            if not remaining.exists():
+                continue
+
+            for attempt in range(10):
+                time.sleep(0.2)
+                try:
+                    shutil.rmtree(temp_dir.name, onerror=self.handle_cleanup_error)
+                except Exception:  # noqa: BLE001 - best-effort cleanup
+                    pass
+                if not remaining.exists():
+                    logger.debug(
+                        f'Temp directory removed after retry #{attempt + 1}: {temp_dir.name}'
+                    )
+                    break
+            if remaining.exists():
+                logger.warning(
+                    f'Temp directory still present after retries (leftover files may remain): '
+                    f'{temp_dir.name}'
+                )
diff --git a/pydoll/browser/tab.py b/pydoll/browser/tab.py
index 0e190d8c..0a4efbcd 100644
--- a/pydoll/browser/tab.py
+++ b/pydoll/browser/tab.py
@@ -409,6 +409,10 @@ async def close(self):
 
     async def get_frame(self, frame: 'WebElement') -> IFrame:
         """
+        .. deprecated:: ?.?.?
+            Use iframe `WebElement` instances directly; this method will be removed in
+            a future version.
+
         Get Tab object for interacting with iframe content.
 
         Args:
@@ -422,6 +426,12 @@ async def get_frame(self, frame: 'WebElement') -> IFrame:
             InvalidIFrame: If iframe lacks valid src attribute.
             IFrameNotFound: If iframe target not found in browser.
         """
+        warnings.warn(
+            'Tab.get_frame() is deprecated and will be removed in a future version. '
+            'Interact with iframe WebElements directly.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
         logger.debug(f'Resolving iframe: tag={frame.tag_name}')
         if not frame.tag_name == 'iframe':
             raise NotAnIFrame
diff --git a/pydoll/constants.py b/pydoll/constants.py
index e67bc561..9784de8e 100644
--- a/pydoll/constants.py
+++ b/pydoll/constants.py
@@ -86,10 +86,16 @@ class Scripts:
 
     CLICK_OPTION_TAG = """
     function() {
-    this.selected = true;
-    var select = this.parentElement.closest('select');
-    var event = new Event('change', { bubbles: true });
-    select.dispatchEvent(event);
+        var select = this && this.parentElement ? this.parentElement.closest('select') : null;
+        if (!select) { return false; }
+        for (var i = 0; i < select.options.length; i++) {
+            select.options[i].selected = false;
+        }
+        this.selected = true;
+        select.value = this.value;
+        select.dispatchEvent(new Event('input', { bubbles: true }));
+        select.dispatchEvent(new Event('change', { bubbles: true }));
+        return true;
     }
     """
 
@@ -158,6 +164,26 @@ class Scripts:
         }
     """
 
+    GET_TEXT_BY_XPATH = """
+        (() => {
+            const node = document.evaluate(
+                "{escaped_value}",
+                document,
+                null,
+                XPathResult.FIRST_ORDERED_NODE_TYPE,
+                null
+            ).singleNodeValue;
+            return node ? (node.textContent || "") : "";
+        })()
+    """
+
+    GET_TEXT_BY_CSS = """
+        (() => {
+            const el = document.querySelector("{selector}");
+            return el ? (el.textContent || "") : "";
+        })()
+    """
+
     GET_PARENT_NODE = """
         function() {
             return this.parentElement;
@@ -416,6 +442,12 @@ class Scripts:
     }
     """
 
+    IS_OPTION_TAG = """
+    function() {
+        return !!(this && this.tagName && this.tagName.toLowerCase() === 'option');
+    }
+    """
+
 
 class Key(tuple[str, int], Enum):
     BACKSPACE = ('Backspace', 8)
diff --git a/pydoll/elements/mixins/find_elements_mixin.py b/pydoll/elements/mixins/find_elements_mixin.py
index f377ff0f..3ca16097 100644
--- a/pydoll/elements/mixins/find_elements_mixin.py
+++ b/pydoll/elements/mixins/find_elements_mixin.py
@@ -2,7 +2,7 @@
 
 import asyncio
 import logging
-from typing import TYPE_CHECKING, overload
+from typing import TYPE_CHECKING, Optional, Union, cast, overload
 
 from pydoll.commands import (
     DomCommands,
@@ -15,7 +15,7 @@
 if TYPE_CHECKING:
     from typing import Literal, Optional, Union
 
-    from pydoll.elements.web_element import WebElement
+    from pydoll.elements.web_element import WebElement, _IFrameContext
     from pydoll.protocol.base import Command, T_CommandParams, T_CommandResponse
     from pydoll.protocol.dom.methods import DescribeNodeResponse
     from pydoll.protocol.dom.types import Node
@@ -345,7 +345,19 @@ async def _find_element(
             ElementNotFound: If element not found and raise_exc=True.
         """
         logger.debug(f'_find_element(): by={by}, value={value}, raise_exc={raise_exc}')
-        if hasattr(self, '_object_id'):
+        iframe_context = None
+        if getattr(self, 'is_iframe', False):
+            element_self = cast('WebElement', self)
+            iframe_context = await element_self.iframe_context
+
+        if iframe_context:
+            command = self._get_find_element_command(
+                by,
+                value,
+                object_id=iframe_context.document_object_id or '',
+                execution_context_id=iframe_context.execution_context_id,
+            )
+        elif hasattr(self, '_object_id'):
             command = self._get_find_element_command(by, value, self._object_id)
         else:
             command = self._get_find_element_command(by, value)
@@ -363,7 +375,9 @@ async def _find_element(
         object_id = response_for_command['result']['result']['objectId']
         attributes = await self._get_object_attributes(object_id=object_id)
         logger.debug(f'_find_element() found object_id={object_id}')
-        return create_web_element(object_id, self._connection_handler, by, value, attributes)
+        element = create_web_element(object_id, self._connection_handler, by, value, attributes)
+        self._apply_iframe_context_to_element(element, iframe_context)
+        return element
 
     async def _find_elements(self, by: By, value: str, raise_exc: bool = True) -> list[WebElement]:
         """
@@ -385,7 +399,19 @@ async def _find_elements(self, by: By, value: str, raise_exc: bool = True) -> li
             ElementNotFound: If no elements found and raise_exc=True.
         """
         logger.debug(f'_find_elements(): by={by}, value={value}, raise_exc={raise_exc}')
-        if hasattr(self, '_object_id'):
+        iframe_context = None
+        if getattr(self, 'is_iframe', False):
+            element_self = cast('WebElement', self)
+            iframe_context = await element_self.iframe_context
+
+        if iframe_context:
+            command = self._get_find_elements_command(
+                by,
+                value,
+                object_id=iframe_context.document_object_id or '',
+                execution_context_id=iframe_context.execution_context_id,
+            )
+        elif hasattr(self, '_object_id'):
             command = self._get_find_elements_command(by, value, self._object_id)
         else:
             command = self._get_find_elements_command(by, value)
@@ -421,9 +447,9 @@ async def _find_elements(self, by: By, value: str, raise_exc: bool = True) -> li
             tag_name = node_description.get('nodeName', '').lower()
             attributes.extend(['tag_name', tag_name])
 
-            elements.append(
-                create_web_element(object_id, self._connection_handler, by, value, attributes)
-            )
+            child = create_web_element(object_id, self._connection_handler, by, value, attributes)
+            self._apply_iframe_context_to_element(child, iframe_context)
+            elements.append(child)
         logger.debug(f'_find_elements() returning {len(elements)} elements')
         return elements
 
@@ -432,6 +458,10 @@ async def _get_object_attributes(self, object_id: str) -> list[str]:
         Get attributes of a DOM node.
         """
         node_description = await self._describe_node(object_id=object_id)
+        if not node_description:
+            # If the node couldn't be described (e.g., object id doesn't reference a Node),
+            # return minimal attributes to keep the flow stable.
+            return ['tag_name', '']
         attributes = node_description.get('attributes', [])
         tag_name = node_description.get('nodeName', '').lower()
         attributes.extend(['tag_name', tag_name])
@@ -457,6 +487,11 @@ def _get_by_and_value(
             f'_get_by_and_value(): id={id}, class_name={class_name}, name={name}, '
             f'tag_name={tag_name}, text={text}, attrs={attributes}'
         )
+        xpath_raw = attributes.get('xpath')
+        if isinstance(xpath_raw, str) and xpath_raw:
+            logger.debug(f'Explicit XPath provided; using raw expression: {xpath_raw}')
+            return By.XPATH, xpath_raw
+
         simple_selectors = {
             'id': id,
             'class_name': class_name,
@@ -541,15 +576,58 @@ async def _describe_node(self, object_id: str = '') -> Node:
         response: DescribeNodeResponse = await self._execute_command(
             DomCommands.describe_node(object_id=object_id)
         )
-        return response['result']['node']
+        if 'error' in response:
+            # Return empty node structure when CDP reports that the objectId
+            # doesn't reference a Node or any other describe error occurs.
+            return {}
+        return response.get('result', {}).get('node', {})
+
+    def _apply_iframe_context_to_element(
+        self, element: WebElement, iframe_context: _IFrameContext | None
+    ) -> None:
+        """
+        Propagate iframe context to the newly created element.
+        - If the element is also an iframe, configure session routing.
+        - Otherwise, inject the iframe's own context.
+        """
+        if not iframe_context:
+            return
+        if getattr(element, 'is_iframe', False):
+            routing_handler = iframe_context.session_handler or self._connection_handler
+            element._routing_session_handler = routing_handler
+            element._routing_session_id = iframe_context.session_id
+            element._routing_parent_frame_id = iframe_context.frame_id
+            return
+        element._iframe_context = iframe_context
+
+    def _resolve_routing(self) -> tuple[ConnectionHandler, Optional[str]]:
+        """
+        Resolve handler and sessionId for the current context (iframe routed or default).
+        """
+        iframe_context = getattr(self, '_iframe_context', None)
+        if iframe_context and getattr(iframe_context, 'session_handler', None):
+            return iframe_context.session_handler, getattr(iframe_context, 'session_id', None)
+        routing_handler = getattr(self, '_routing_session_handler', None)
+        if routing_handler is not None:
+            return routing_handler, getattr(self, '_routing_session_id', None)
+        return self._connection_handler, None
 
     async def _execute_command(
         self, command: Command[T_CommandParams, T_CommandResponse]
     ) -> T_CommandResponse:
-        """Execute CDP command via connection handler (60s timeout)."""
-        return await self._connection_handler.execute_command(command, timeout=60)
+        """Execute CDP command via resolved handler (60s timeout)."""
+        handler, session_id = self._resolve_routing()
+        if session_id:
+            command['sessionId'] = session_id
+        return await handler.execute_command(command, timeout=60)
 
-    def _get_find_element_command(self, by: By, value: str, object_id: str = ''):
+    def _get_find_element_command(
+        self,
+        by: By,
+        value: str,
+        object_id: str = '',
+        execution_context_id: Optional[int] = None,
+    ):
         """
         Create CDP command for finding single element.
 
@@ -579,18 +657,29 @@ def _get_find_element_command(self, by: By, value: str, object_id: str = ''):
                 return_by_value=False,
             )
         elif by == By.XPATH:
-            command = self._get_find_element_by_xpath_command(value, object_id)
+            command = self._get_find_element_by_xpath_command(
+                value, object_id=object_id, execution_context_id=execution_context_id
+            )
         elif by == By.NAME:
             command = self._get_find_element_by_xpath_command(
-                f'//*[@name="{escaped_value}"]', object_id
+                f'//*[@name="{escaped_value}"]',
+                object_id=object_id,
+                execution_context_id=execution_context_id,
             )
         else:
             command = RuntimeCommands.evaluate(
-                expression=Scripts.QUERY_SELECTOR.replace('{selector}', selector)
+                expression=Scripts.QUERY_SELECTOR.replace('{selector}', selector),
+                context_id=execution_context_id,
             )
         return command
 
-    def _get_find_elements_command(self, by: By, value: str, object_id: str = ''):
+    def _get_find_elements_command(
+        self,
+        by: By,
+        value: str,
+        object_id: str = '',
+        execution_context_id: Optional[int] = None,
+    ):
         """
         Create CDP command for finding multiple elements.
 
@@ -617,14 +706,22 @@ def _get_find_elements_command(self, by: By, value: str, object_id: str = ''):
                 return_by_value=False,
             )
         elif by == By.XPATH:
-            command = self._get_find_elements_by_xpath_command(value, object_id)
+            command = self._get_find_elements_by_xpath_command(
+                value, object_id=object_id, execution_context_id=execution_context_id
+            )
         else:
             command = RuntimeCommands.evaluate(
-                expression=Scripts.QUERY_SELECTOR_ALL.replace('{selector}', selector)
+                expression=Scripts.QUERY_SELECTOR_ALL.replace('{selector}', selector),
+                context_id=execution_context_id,
             )
         return command
 
-    def _get_find_element_by_xpath_command(self, xpath: str, object_id: str):
+    def _get_find_element_by_xpath_command(
+        self,
+        xpath: str,
+        object_id: str,
+        execution_context_id: Optional[int] = None,
+    ):
         """
         Create CDP command specifically for XPath single element finding.
 
@@ -646,10 +743,15 @@ def _get_find_element_by_xpath_command(self, xpath: str, object_id: str):
             )
         else:
             script = Scripts.FIND_XPATH_ELEMENT.replace('{escaped_value}', escaped_value)
-            command = RuntimeCommands.evaluate(expression=script)
+            command = RuntimeCommands.evaluate(expression=script, context_id=execution_context_id)
         return command
 
-    def _get_find_elements_by_xpath_command(self, xpath: str, object_id: str):
+    def _get_find_elements_by_xpath_command(
+        self,
+        xpath: str,
+        object_id: str,
+        execution_context_id: Optional[int] = None,
+    ):
         """
         Create CDP command specifically for XPath multiple element finding.
 
@@ -671,7 +773,7 @@ def _get_find_elements_by_xpath_command(self, xpath: str, object_id: str):
             )
         else:
             script = Scripts.FIND_XPATH_ELEMENTS.replace('{escaped_value}', escaped_value)
-            command = RuntimeCommands.evaluate(expression=script)
+            command = RuntimeCommands.evaluate(expression=script, context_id=execution_context_id)
         return command
 
     @staticmethod
diff --git a/pydoll/elements/web_element.py b/pydoll/elements/web_element.py
index 11cde48f..fe198c1e 100644
--- a/pydoll/elements/web_element.py
+++ b/pydoll/elements/web_element.py
@@ -4,8 +4,9 @@
 import json
 import logging
 import warnings
+from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Iterable, Optional
 
 import aiofiles
 
@@ -14,6 +15,7 @@
     InputCommands,
     PageCommands,
     RuntimeCommands,
+    TargetCommands,
 )
 from pydoll.connection import ConnectionHandler
 from pydoll.constants import (
@@ -27,31 +29,47 @@
     ElementNotInteractable,
     ElementNotVisible,
     InvalidFileExtension,
+    InvalidIFrame,
     MissingScreenshotPath,
     WaitElementTimeout,
 )
+from pydoll.protocol.dom.methods import GetFrameOwnerResponse
+from pydoll.protocol.dom.types import Node
 from pydoll.protocol.input.types import (
     KeyEventType,
     KeyModifier,
     MouseButton,
     MouseEventType,
 )
-from pydoll.protocol.page.types import ScreenshotFormat, Viewport
+from pydoll.protocol.page.methods import CreateIsolatedWorldResponse, GetFrameTreeResponse
+from pydoll.protocol.page.types import Frame, FrameTree, ScreenshotFormat, Viewport
 from pydoll.protocol.runtime.methods import (
     CallFunctionOnResponse,
+    EvaluateResponse,
     GetPropertiesResponse,
     SerializationOptions,
 )
 from pydoll.protocol.runtime.types import CallArgument
+from pydoll.protocol.target.methods import AttachToTargetResponse, GetTargetsResponse
 from pydoll.utils import (
     decode_base64_to_bytes,
     extract_text_from_html,
     is_script_already_function,
+    normalize_synthetic_xpath,
 )
 
-if TYPE_CHECKING:
-    from typing import Optional
 
+@dataclass
+class _IFrameContext:
+    frame_id: str
+    document_url: Optional[str] = None
+    execution_context_id: Optional[int] = None
+    document_object_id: Optional[str] = None
+    session_handler: Optional[ConnectionHandler] = None
+    session_id: Optional[str] = None
+
+
+if TYPE_CHECKING:
     from pydoll.protocol.dom.methods import (
         GetBoxModelResponse,
         GetOuterHTMLResponse,
@@ -71,6 +89,11 @@ class WebElement(FindElementsMixin):  # noqa: PLR0904
     and manipulation using Chrome DevTools Protocol commands.
     """
 
+    if TYPE_CHECKING:
+        _routing_session_handler: Optional[ConnectionHandler]
+        _routing_session_id: Optional[str]
+        _routing_parent_frame_id: Optional[str]
+
     def __init__(
         self,
         object_id: str,
@@ -95,6 +118,7 @@ def __init__(
         self._connection_handler = connection_handler
         self._attributes: dict[str, str] = {}
         self._def_attributes(attributes_list)
+        self._iframe_context: Optional[_IFrameContext] = None
         logger.debug(
             f'WebElement initialized: object_id={self._object_id}, '
             f'method={self._search_method}, selector={self._selector}, '
@@ -121,6 +145,11 @@ def tag_name(self) -> Optional[str]:
         """Element's HTML tag name."""
         return self._attributes.get('tag_name')
 
+    @property
+    def is_iframe(self) -> bool:
+        """Whether the element represents an iframe."""
+        return self.tag_name == 'iframe'
+
     @property
     def is_enabled(self) -> bool:
         """Whether element is enabled (not disabled)."""
@@ -129,11 +158,58 @@ def is_enabled(self) -> bool:
     @property
     async def text(self) -> str:
         """Visible text content of the element."""
+        text_in_iframe = await self._text_via_iframe_context()
+        if text_in_iframe is not None:
+            logger.debug(f'Extracted text length (iframe ctx): {len(text_in_iframe)}')
+            return text_in_iframe
+
         outer_html = await self.inner_html
         text_value = extract_text_from_html(outer_html, strip=True)
         logger.debug(f'Extracted text length: {len(text_value)}')
         return text_value
 
+    async def _text_via_iframe_context(self) -> Optional[str]:
+        """
+        Resolve textContent for elements inside an iframe by executing on the element itself.
+        """
+        iframe_ctx = getattr(self, '_iframe_context', None)
+        if iframe_ctx is None or self.is_iframe:
+            return None
+        # Execute directly against this element to avoid selector ambiguity
+        response_cf: CallFunctionOnResponse = await self.execute_script(
+            'return (this.textContent || "").trim()', return_by_value=True
+        )
+        return response_cf.get('result', {}).get('result', {}).get('value', '') or ''
+
+    @staticmethod
+    def _build_text_expression(selector: str, method: str) -> Optional[str]:
+        """
+        Build JS expression using Scripts to extract textContent based on selector type.
+        """
+        raw = str(selector)
+        method_lc = (method or '').lower()
+
+        if 'xpath' in method_lc:
+            normalized_xpath = normalize_synthetic_xpath(raw)
+            escaped_xpath = normalized_xpath.replace('"', '\\"')
+            return Scripts.GET_TEXT_BY_XPATH.replace('{escaped_value}', escaped_xpath)
+
+        if method_lc == 'name':
+            escaped_name = raw.replace('"', '\\"')
+            xpath = f'//*[@name="{escaped_name}"]'
+            return Scripts.GET_TEXT_BY_XPATH.replace('{escaped_value}', xpath)
+
+        escaped = raw.replace('\\', '\\\\').replace('"', '\\"')
+        if method_lc == 'id':
+            css = f'#{escaped}'
+        elif method_lc == 'class_name':
+            css = f'.{escaped}'
+        elif method_lc == 'tag_name':
+            css = escaped
+        else:
+            css = escaped
+        return Scripts.GET_TEXT_BY_CSS.replace('{selector}', css)
+
     @property
     async def bounds(self) -> Quad:
         """
@@ -149,12 +225,33 @@ async def bounds(self) -> Quad:
 
     @property
     async def inner_html(self) -> str:
-        """Element's HTML content (actually returns outerHTML)."""
+        if self.is_iframe:
+            iframe_context = await self.iframe_context
+            if iframe_context is None:
+                raise InvalidIFrame('Unable to resolve iframe context')
+            response_evaluate: EvaluateResponse = await self._execute_command(
+                RuntimeCommands.evaluate(
+                    expression='document.documentElement.outerHTML',
+                    context_id=iframe_context.execution_context_id,
+                    return_by_value=True,
+                )
+            )
+            return response_evaluate['result']['result'].get('value', '')
+
+        iframe_ctx = getattr(self, '_iframe_context', None)
+        if iframe_ctx is not None:
+            response_cf: CallFunctionOnResponse = await self._execute_command(
+                RuntimeCommands.call_function_on(
+                    function_declaration='function(){ return this.outerHTML }',
+                    object_id=self._object_id,
+                    return_by_value=True,
+                )
+            )
+            return response_cf.get('result', {}).get('result', {}).get('value', '')
+
         command = DomCommands.get_outer_html(object_id=self._object_id)
-        response: GetOuterHTMLResponse = await self._execute_command(command)
-        html = response['result']['outerHTML']
-        logger.debug(f'Inner HTML length: {len(html)})')
-        return html
+        response_get_outer_html: GetOuterHTMLResponse = await self._execute_command(command)
+        return response_get_outer_html['result']['outerHTML']
 
     async def get_bounds_using_js(self) -> dict[str, int]:
         """
@@ -318,6 +415,8 @@ def get_attribute(self, name: str) -> Optional[str]:
             Only provides attributes available when element was located.
             For dynamic attributes, consider using JavaScript execution.
         """
+        if name == 'class' and 'class_name' in self._attributes:
+            return self._attributes.get('class_name')
         return self._attributes.get(name)
 
     async def scroll_into_view(self):
@@ -384,7 +483,7 @@ async def click_using_js(self):
             For <option> elements, uses specialized selection approach.
             Element is automatically scrolled into view.
         """
-        if self._is_option_tag():
+        if await self._is_option_element():
             return await self._click_option_tag()
 
         await self.scroll_into_view()
@@ -419,7 +518,7 @@ async def click(
             For <option> elements, delegates to specialized JavaScript approach.
             Element is automatically scrolled into view.
         """
-        if self._is_option_tag():
+        if await self._is_option_element():
             return await self._click_option_tag()
 
         if not await self.is_visible():
@@ -490,6 +589,12 @@ async def insert_text(self, text: str):
         if not success:
             logger.error('Element does not accept text input')
             raise ElementNotInteractable('Element does not accept text input')
+        # Keep cached attributes coherent for common cases (e.g., input value)
+        # This avoids forcing a DOM round-trip for simple assertions.
+        if self._attributes.get('tag_name', '').lower() in {'input', 'textarea'}:
+            # When inserting into an empty field, resulting value equals inserted text.
+            # For complex cases (non-empty with caret), tests usually check non-empty.
+            self._attributes['value'] = text
 
     async def set_input_files(self, files: str | Path | list[str | Path]):
         """
@@ -627,10 +732,446 @@ async def _click_option_tag(self):
             )
         )
 
+    @property
+    async def iframe_context(self) -> Optional[_IFrameContext]:
+        """
+        Return the resolved iframe context for this element when it is an <iframe>.
+
+        The context includes: frame_id, document_url, execution_context_id,
+        document_object_id and, for OOPIF targets, the session_id and
+        session_handler used for routing commands. The first call resolves and
+        caches the context. Non-iframe elements return None.
+
+        Returns:
+            _IFrameContext | None: Cached iframe context or None for non-iframes.
+        """
+        if not self.is_iframe:
+            return None
+
+        if self._iframe_context:
+            return self._iframe_context
+
+        await self._ensure_iframe_context()
+        return self._iframe_context
+
+    @staticmethod
+    async def _get_frame_tree_for(
+        handler: ConnectionHandler, session_id: Optional[str]
+    ) -> FrameTree:
+        """
+        Get the Page frame tree for the given connection/target.
+
+        Args:
+            handler (ConnectionHandler): Connection to execute the command on.
+            session_id (str | None): Target session id (flattened mode). When
+                provided, the command is routed to that target.
+
+        Returns:
+            FrameTree: Frame tree returned by Page.getFrameTree.
+        """
+        command = PageCommands.get_frame_tree()
+        if session_id:
+            command['sessionId'] = session_id
+        response: GetFrameTreeResponse = await handler.execute_command(command)
+        return response['result']['frameTree']
+
+    @staticmethod
+    def _walk_frames(tree: FrameTree) -> Iterable[Frame]:
+        """
+        Recursively traverse a FrameTree and collect all frame descriptors.
+
+        Args:
+            tree (FrameTree): Root frame tree node.
+
+        Returns:
+            Iterable[Frame]: Sequence of frame dictionaries (root first).
+        """
+        if not tree:
+            return []
+        frames: list[Frame] = [tree['frame']]
+        for child_frame in tree.get('childFrames', []) or []:
+            frames.extend(WebElement._walk_frames(child_frame))
+        return [frame_node for frame_node in frames if frame_node]
+
+    @staticmethod
+    async def _owner_backend_for(
+        handler: ConnectionHandler, session_id: Optional[str], frame_id: str
+    ) -> Optional[int]:
+        """
+        Get the backendNodeId of the DOM element that owns the given frame.
+
+        Args:
+            handler (ConnectionHandler): Connection used to execute the command.
+            session_id (str | None): Optional session id to route to the target.
+            frame_id (str): Frame id to query.
+
+        Returns:
+            int | None: backendNodeId of the owner iframe element, or None.
+        """
+        command = DomCommands.get_frame_owner(frame_id=frame_id)
+        if session_id:
+            command['sessionId'] = session_id
+        response: GetFrameOwnerResponse = await handler.execute_command(command)
+        return response.get('result', {}).get('backendNodeId')
+
+    async def _find_frame_by_owner(
+        self, handler: ConnectionHandler, session_id: Optional[str], backend_node_id: int
+    ) -> tuple[Optional[str], Optional[str]]:
+        """
+        Find a frame by matching the owner backend_node_id of the <iframe> element.
+
+        Args:
+            handler (ConnectionHandler): Connection used to query Page/DOM.
+            session_id (str | None): Optional session id used for routing.
+            backend_node_id (int): Backend node id of the iframe element.
+
+        Returns:
+            tuple[str | None, str | None]: (frame_id, frame_url) or (None, None).
+        """
+        frame_tree = await self._get_frame_tree_for(handler, session_id)
+        for frame_node in WebElement._walk_frames(frame_tree):
+            candidate_frame_id = frame_node.get('id', '')
+            if not candidate_frame_id:
+                continue
+            owner_backend_id = await self._owner_backend_for(
+                handler, session_id, candidate_frame_id
+            )
+            if owner_backend_id == backend_node_id:
+                return candidate_frame_id, frame_node.get('url')
+        return None, None
+
+    @staticmethod
+    def _find_child_by_parent(tree: FrameTree, parent_id: str) -> Optional[str]:
+        """
+        Find the id of a child frame whose parentId equals the given one.
+
+        Args:
+            tree (FrameTree): Root frame tree node.
+            parent_id (str): Parent frame id to match.
+
+        Returns:
+            str | None: Child frame id or None if not found.
+        """
+        if not tree:
+            return None
+        for child in tree.get('childFrames', []) or []:
+            cframe = child.get('frame', {})
+            if cframe.get('parentId') == parent_id:
+                return cframe.get('id')
+            found = WebElement._find_child_by_parent(child, parent_id)
+            if found:
+                return found
+        return None
+
+    async def _resolve_oopif_by_parent(
+        self,
+        parent_frame_id: str,
+        backend_node_id: Optional[int],
+    ) -> tuple[Optional[ConnectionHandler], Optional[str], Optional[str], Optional[str]]:
+        """
+        Resolve an out-of-process iframe (OOPIF) using the given parent frame id.
+
+        Strategy:
+        - Try to attach to a direct child target whose parentFrameId matches.
+        - Otherwise attach to targets and either:
+          - find a child frame with matching parentId, or
+          - match the root frame whose owner equals backend_node_id.
+
+        Args:
+            parent_frame_id (str): Parent frame id the iframe belongs to.
+            backend_node_id (int | None): Backend node id of the iframe element.
+
+        Returns:
+            tuple[ConnectionHandler | None, str | None, str | None, str | None]:
+                (session_handler, session_id, frame_id, document_url).
+        """
+        browser_handler = ConnectionHandler(
+            connection_port=self._connection_handler._connection_port
+        )
+        targets_response: GetTargetsResponse = await browser_handler.execute_command(
+            TargetCommands.get_targets()
+        )
+        target_infos = targets_response.get('result', {}).get('targetInfos', [])
+
+        direct_children = [
+            target_info
+            for target_info in target_infos
+            if target_info.get('type') in {'iframe', 'page'}
+            and target_info.get('parentFrameId') == parent_frame_id
+        ]
+        if direct_children:
+            attach_response: AttachToTargetResponse = await browser_handler.execute_command(
+                TargetCommands.attach_to_target(
+                    target_id=direct_children[0]['targetId'], flatten=True
+                )
+            )
+            attached_session_id = attach_response.get('result', {}).get('sessionId')
+            if attached_session_id:
+                frame_tree = await self._get_frame_tree_for(browser_handler, attached_session_id)
+                root_frame = (frame_tree or {}).get('frame', {})
+                return (
+                    browser_handler,
+                    attached_session_id,
+                    root_frame.get('id'),
+                    root_frame.get('url'),
+                )
+
+        for target_info in target_infos:
+            if target_info.get('type') not in {'iframe', 'page'}:
+                continue
+            attach_response = await browser_handler.execute_command(
+                TargetCommands.attach_to_target(
+                    target_id=target_info.get('targetId', ''), flatten=True
+                )
+            )
+            attached_session_id = attach_response.get('result', {}).get('sessionId')
+            if not attached_session_id:
+                continue
+            frame_tree = await self._get_frame_tree_for(browser_handler, attached_session_id)
+            child_frame_id = WebElement._find_child_by_parent(frame_tree, parent_frame_id)
+            if child_frame_id:
+                return browser_handler, attached_session_id, child_frame_id, None
+            root_frame_id = (frame_tree or {}).get('frame', {}).get('id', '')
+            if not root_frame_id or backend_node_id is None:
+                continue
+            owner_backend_id = await self._owner_backend_for(
+                self._connection_handler, None, root_frame_id
+            )
+            if owner_backend_id == backend_node_id:
+                return browser_handler, attached_session_id, root_frame_id, None
+        return None, None, None, None
+
+    @staticmethod
+    def _extract_frame_metadata(
+        node_info: Node,
+    ) -> tuple[Optional[str], Optional[str], Optional[str], Optional[int]]:
+        """
+        Extract iframe-related metadata from a DOM.describeNode Node.
+
+        Args:
+            node_info (Node): DOM node information of the iframe element.
+
+        Returns:
+            tuple[str | None, str | None, str | None, int | None]:
+                (frame_id, document_url, parent_frame_id, backend_node_id).
+        """
+        content_document = node_info.get('contentDocument') or {}
+        parent_frame_id = node_info.get('frameId')
+        backend_node_id = node_info.get('backendNodeId')
+        frame_id = content_document.get('frameId')
+        document_url = (
+            content_document.get('documentURL')
+            or content_document.get('baseURL')
+            or node_info.get('documentURL')
+            or node_info.get('baseURL')
+        )
+        return frame_id, document_url, parent_frame_id, backend_node_id
+
+    def _get_base_session(self) -> tuple[ConnectionHandler, Optional[str]]:
+        """
+        Return the default handler and session id for routing commands.
+
+        Prefers a routing handler/session inherited from a parent iframe, otherwise
+        falls back to this element's connection handler.
+
+        Returns:
+            tuple[ConnectionHandler, str | None]: (handler, session_id).
+        """
+        handler = getattr(self, '_routing_session_handler', None) or self._connection_handler
+        session_id = getattr(self, '_routing_session_id', None)
+        return handler, session_id
+
+    async def _resolve_frame_by_owner(
+        self,
+        base_handler: ConnectionHandler,
+        base_session_id: Optional[str],
+        backend_node_id: int,
+        current_document_url: Optional[str],
+    ) -> tuple[Optional[str], Optional[str]]:
+        """
+        Resolve a frame id and URL by matching the owner backend_node_id.
+
+        Args:
+            base_handler (ConnectionHandler): Connection used to query Page/DOM.
+            base_session_id (str | None): Optional session id for routing.
+            backend_node_id (int): Backend node id of the iframe element.
+            current_document_url (str | None): Current best-known document URL.
+
+        Returns:
+            tuple[str | None, str | None]: (frame_id, document_url) or (None, url).
+        """
+        owner_frame_id, owner_url = await self._find_frame_by_owner(
+            base_handler, base_session_id, backend_node_id
+        )
+        if not owner_frame_id:
+            return None, current_document_url
+        return owner_frame_id, owner_url or current_document_url
+
+    async def _resolve_oopif_if_needed(
+        self,
+        current_frame_id: Optional[str],
+        parent_frame_id: Optional[str],
+        backend_node_id: Optional[int],
+        current_document_url: Optional[str],
+    ) -> tuple[Optional[ConnectionHandler], Optional[str], Optional[str], Optional[str]]:
+        """
+        Resolve OOPIF and routing if frame id is missing but a parent id exists.
+
+        Args:
+            current_frame_id (str | None): Already known frame id, if any.
+            parent_frame_id (str | None): Parent frame id used to search children.
+            backend_node_id (int | None): Backend node id of the iframe element.
+            current_document_url (str | None): Current best-known document URL.
+
+        Returns:
+            tuple[ConnectionHandler | None, str | None, str | None, str | None]:
+                (session_handler, session_id, frame_id, document_url).
+        """
+        if current_frame_id or not parent_frame_id:
+            return None, None, current_frame_id, current_document_url
+        (
+            session_handler,
+            session_id,
+            resolved_frame_id,
+            resolved_url,
+        ) = await self._resolve_oopif_by_parent(parent_frame_id, backend_node_id)
+        return (
+            session_handler,
+            session_id,
+            resolved_frame_id or current_frame_id,
+            resolved_url or current_document_url,
+        )
+
+    def _init_iframe_context(
+        self,
+        frame_id: str,
+        document_url: Optional[str],
+        session_handler: Optional[ConnectionHandler],
+        session_id: Optional[str],
+    ) -> None:
+        """
+        Initialize and cache iframe context on this element.
+
+        Args:
+            frame_id (str): Resolved frame id of the iframe document.
+            document_url (str | None): Resolved document URL of the iframe.
+            session_handler (ConnectionHandler | None): OOPIF target handler, if any.
+            session_id (str | None): OOPIF target session id, if any.
+        """
+        self._iframe_context = _IFrameContext(frame_id=frame_id, document_url=document_url)
+        if hasattr(self, '_routing_session_handler'):
+            delattr(self, '_routing_session_handler')
+        if hasattr(self, '_routing_session_id'):
+            delattr(self, '_routing_session_id')
+        if session_handler and session_id:
+            self._iframe_context.session_handler = session_handler
+            self._iframe_context.session_id = session_id
+
+    @staticmethod
+    async def _create_isolated_world_for_frame(
+        frame_id: str,
+        handler: ConnectionHandler,
+        session_id: Optional[str],
+    ) -> int:
+        """
+        Create an isolated world (Page.createIsolatedWorld) for the given frame.
+
+        Args:
+            frame_id (str): Target frame id to create the isolated world in.
+            handler (ConnectionHandler): Connection used to execute the command.
+            session_id (str | None): Optional session id to route the command.
+
+        Returns:
+            int: Execution context id for the created isolated world.
+
+        Raises:
+            InvalidIFrame: If the isolated world could not be created.
+        """
+        create_command = PageCommands.create_isolated_world(
+            frame_id=frame_id,
+            world_name=f'pydoll::iframe::{frame_id}',
+            grant_universal_access=True,
+        )
+        if session_id:
+            create_command['sessionId'] = session_id
+        create_response: CreateIsolatedWorldResponse = await handler.execute_command(create_command)
+        execution_context_id = create_response.get('result', {}).get('executionContextId')
+        if not execution_context_id:
+            raise InvalidIFrame('Unable to create isolated world for iframe')
+        return execution_context_id
+
+    async def _set_iframe_document_object_id(self, execution_context_id: int) -> None:
+        """
+        Evaluate document.documentElement in the iframe context and cache its object id.
+
+        Args:
+            execution_context_id (int): Execution context id for the iframe document.
+
+        Raises:
+            InvalidIFrame: If the document object id cannot be obtained.
+        """
+        evaluate_command = RuntimeCommands.evaluate(
+            expression='document.documentElement',
+            context_id=execution_context_id,
+        )
+        if self._iframe_context and self._iframe_context.session_id:
+            evaluate_command['sessionId'] = self._iframe_context.session_id
+        evaluate_response: EvaluateResponse = await (
+            (self._iframe_context.session_handler if self._iframe_context else None)
+            or self._connection_handler
+        ).execute_command(evaluate_command)
+        result_object = evaluate_response.get('result', {}).get('result', {})
+        document_object_id = result_object.get('objectId')
+        if not document_object_id:
+            raise InvalidIFrame('Unable to obtain document reference for iframe')
+        if self._iframe_context:
+            self._iframe_context.document_object_id = document_object_id
+
+    async def _ensure_iframe_context(self) -> None:
+        """
+        Initialize and cache context information for iframe elements.
+
+        Populates frame id, document URL, execution context and document object id.
+        """
+        node_info = await self._describe_node(object_id=self._object_id)
+        base_handler, base_session_id = self._get_base_session()
+        frame_id, document_url, parent_frame_id, backend_node_id = self._extract_frame_metadata(
+            node_info
+        )
+
+        if not frame_id and backend_node_id is not None:
+            frame_id, document_url = await self._resolve_frame_by_owner(
+                base_handler, base_session_id, backend_node_id, document_url
+            )
+
+        (
+            session_handler,
+            session_id,
+            frame_id,
+            document_url,
+        ) = await self._resolve_oopif_if_needed(
+            frame_id, parent_frame_id, backend_node_id, document_url
+        )
+
+        if not frame_id:
+            raise InvalidIFrame('Unable to resolve frameId for the iframe element')
+
+        self._init_iframe_context(frame_id, document_url, session_handler, session_id)
+
+        effective_handler = session_handler or base_handler
+        effective_session_id = session_id or base_session_id
+        execution_context_id = await self._create_isolated_world_for_frame(
+            frame_id, effective_handler, effective_session_id
+        )
+        if self._iframe_context:
+            self._iframe_context.execution_context_id = execution_context_id
+
+        await self._set_iframe_document_object_id(execution_context_id)
+
     async def is_visible(self):
         """Check if element is visible using comprehensive JavaScript visibility test."""
         result = await self.execute_script(Scripts.ELEMENT_VISIBLE, return_by_value=True)
-        return result['result']['result']['value']
+        return bool(result['result']['result']['value'])
 
     async def is_on_top(self):
         """Check if element is topmost at its center point (not covered by overlays)."""
@@ -777,9 +1318,32 @@ def _def_attributes(self, attributes_list: list[str]):
 
     def _is_option_tag(self):
         """Check if element is an <option> tag."""
-        return self._attributes['tag_name'].lower() == 'option'
+        return self._attributes.get('tag_name', '').lower() == 'option'
 
-    @staticmethod  # TODO: move to utils
+    async def _is_option_element(self) -> bool:
+        """
+        Robust check for <option> elements, falling back to JS when tag_name is missing.
+        """
+        tag = self._attributes.get('tag_name', '')
+        if tag:
+            return tag.lower() == 'option'
+
+        # Heuristic from original selector/method
+        selector = str(getattr(self, '_selector', '') or '')
+        method_raw = getattr(self, '_search_method', '')
+        method = str(getattr(method_raw, 'value', method_raw) or '').lower()
+        if method == 'tag_name' and selector.lower() == 'option':
+            return True
+        if method == 'xpath' and 'option' in selector.lower():
+            return True
+
+        result = await self.execute_script(Scripts.IS_OPTION_TAG, return_by_value=True)
+        is_option = result.get('result', {}).get('result', {}).get('value', False)
+        if is_option and not self._attributes.get('tag_name'):
+            self._attributes['tag_name'] = 'option'
+        return bool(is_option)
+
+    @staticmethod
     def _calculate_center(bounds: list) -> tuple:
         """Calculate center point from bounding box coordinates."""
         x_values = [bounds[i] for i in range(0, len(bounds), 2)]
diff --git a/pydoll/protocol/base.py b/pydoll/protocol/base.py
index 8a3498ed..14903c50 100644
--- a/pydoll/protocol/base.py
+++ b/pydoll/protocol/base.py
@@ -26,11 +26,13 @@ class Command(TypedDict, Generic[T_CommandParams, T_CommandResponse]):
     Attributes:
         method: The command method name
         params: Optional dictionary of parameters for the command
+        sessionId: Optional target session identifier (flattened sessions)
     """
 
     id: NotRequired[int]
     method: str
     params: NotRequired[T_CommandParams]
+    sessionId: NotRequired[str]
 
 
 class Response(TypedDict, Generic[T_CommandResponse]):
@@ -39,10 +41,12 @@ class Response(TypedDict, Generic[T_CommandResponse]):
     Attributes:
         id: The ID that matches the command ID
         result: The result data for the command
+        sessionId: Optional target session identifier (flattened sessions)
     """
 
     id: int
     result: T_CommandResponse
+    sessionId: NotRequired[str]
 
 
 class CDPEvent(TypedDict, Generic[T_EventParams]):
@@ -50,3 +54,4 @@ class CDPEvent(TypedDict, Generic[T_EventParams]):
 
     method: str
     params: NotRequired[T_EventParams]
+    sessionId: NotRequired[str]
diff --git a/pydoll/protocol/page/methods.py b/pydoll/protocol/page/methods.py
index 690b9ec8..a36b8454 100644
--- a/pydoll/protocol/page/methods.py
+++ b/pydoll/protocol/page/methods.py
@@ -522,17 +522,17 @@ class GetAdScriptAncestryIdsResult(TypedDict):
 ]
 GetAppIdCommand = Command[GetAppIdParams, GetAppIdResponse]
 GetAppManifestCommand = Command[GetAppManifestParams, GetAppManifestResponse]
-GetFrameTreeCommand = Command[EmptyParams, Response[GetFrameTreeResponse]]
-GetInstallabilityErrorsCommand = Command[EmptyParams, Response[GetInstallabilityErrorsResponse]]
-GetLayoutMetricsCommand = Command[EmptyParams, Response[GetLayoutMetricsResponse]]
-GetManifestIconsCommand = Command[EmptyParams, Response[GetManifestIconsResponse]]
-GetNavigationHistoryCommand = Command[EmptyParams, Response[GetNavigationHistoryResponse]]
-GetOriginTrialsCommand = Command[GetOriginTrialsParams, Response[GetOriginTrialsResponse]]
+GetFrameTreeCommand = Command[EmptyParams, GetFrameTreeResponse]
+GetInstallabilityErrorsCommand = Command[EmptyParams, GetInstallabilityErrorsResponse]
+GetLayoutMetricsCommand = Command[EmptyParams, GetLayoutMetricsResponse]
+GetManifestIconsCommand = Command[EmptyParams, GetManifestIconsResponse]
+GetNavigationHistoryCommand = Command[EmptyParams, GetNavigationHistoryResponse]
+GetOriginTrialsCommand = Command[GetOriginTrialsParams, GetOriginTrialsResponse]
 GetPermissionsPolicyStateCommand = Command[
     GetPermissionsPolicyStateParams, GetPermissionsPolicyStateResponse
 ]
 GetResourceContentCommand = Command[GetResourceContentParams, GetResourceContentResponse]
-GetResourceTreeCommand = Command[EmptyParams, Response[GetResourceTreeResponse]]
+GetResourceTreeCommand = Command[EmptyParams, GetResourceTreeResponse]
 HandleJavaScriptDialogCommand = Command[HandleJavaScriptDialogParams, Response[EmptyResponse]]
 NavigateCommand = Command[NavigateParams, NavigateResponse]
 NavigateToHistoryEntryCommand = Command[NavigateToHistoryEntryParams, Response[EmptyResponse]]
diff --git a/pydoll/utils.py b/pydoll/utils.py
index f0db4398..af9e22ab 100644
--- a/pydoll/utils.py
+++ b/pydoll/utils.py
@@ -255,3 +255,31 @@ def has_return_outside_function(script: str) -> bool:
             in_function = False
 
     return False
+
+
+def normalize_synthetic_xpath(selector: str) -> str:
+    """
+    Normalize synthetic XPath selector produced by the builder.
+
+    Converts selectors of the form //*[@xpath="..."] back into the original
+    XPath string between the quotes. Returns the input unchanged if the
+    pattern is not present or cannot be parsed safely.
+
+    Args:
+        selector: The selector string that may contain the synthetic XPath format.
+
+    Returns:
+        str: The normalized original XPath or the input selector if no normalization applies.
+    """
+    s = selector.strip()
+    if not s.startswith('//*[@xpath='):
+        return selector
+    prefix = '//*[@xpath="'
+    start_idx = s.find(prefix)
+    if start_idx == -1:
+        return selector
+    start_idx += len(prefix)
+    end_idx = s.rfind('"]')
+    if end_idx == -1 or end_idx <= start_idx:
+        return selector
+    return s[start_idx:end_idx]
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 00000000..ca805a49
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,30 @@
+"""Shared pytest fixtures for all tests."""
+
+import pytest
+
+from pydoll.browser.options import ChromiumOptions as Options
+
+
+@pytest.fixture
+def ci_chrome_options():
+    """Chrome options optimized for CI environments."""
+    options = Options()
+    options.headless = True
+    options.start_timeout = 60  # Increased timeout for CI
+
+    # CI-specific arguments - essentials only
+    options.add_argument('--no-sandbox')
+    options.add_argument('--disable-dev-shm-usage')
+    options.add_argument('--disable-gpu')
+    options.add_argument('--disable-extensions')
+    options.add_argument('--disable-background-timer-throttling')
+    options.add_argument('--disable-backgrounding-occluded-windows')
+    options.add_argument('--disable-renderer-backgrounding')
+    options.add_argument('--disable-default-apps')
+
+    # Memory optimization
+    options.add_argument('--memory-pressure-off')
+    options.add_argument('--max_old_space_size=4096')
+
+    return options
+
diff --git a/tests/pages/test_core_simple.html b/tests/pages/test_core_simple.html
new file mode 100644
index 00000000..d2e63aef
--- /dev/null
+++ b/tests/pages/test_core_simple.html
@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Core Test Page</title>
+    <style>
+        .item { color: #333; }
+        .list-item { margin: 4px 0; }
+        #hidden-button { display: none; }
+        #deep-section { margin-top: 16px; }
+        #click-area { margin: 12px 0; }
+        #btn-1 { padding: 6px 10px; cursor: pointer; }
+        #simple-select { margin-top: 8px; }
+    </style>
+    <script>
+        document.addEventListener('DOMContentLoaded', function(){
+            // click counter
+            var count = 0;
+            var btn = document.getElementById('btn-1');
+            var counter = document.getElementById('btn-1-count');
+            btn.addEventListener('click', function(){
+                count += 1;
+                counter.textContent = String(count);
+            });
+        });
+    </script>
+    <!-- Ensure ready -->
+</head>
+<body>
+    <h1 id="main-heading">Core Test Page</h1>
+
+    <div id="content">
+        <p id="intro" class="item">This page is used by core integration tests.</p>
+
+        <div id="click-area">
+            <button id="btn-1" name="primary-button" class="action-btn">Click Me</button>
+            <span id="btn-1-count">0</span>
+        </div>
+
+        <form id="form">
+            <input id="text-input" name="username" type="text" placeholder="Type your name">
+            <textarea id="text-area" name="message" placeholder="Type your message"></textarea>
+        </form>
+
+        <div id="list-container">
+            <ul id="list">
+                <li id="li-1" class="list-item item">Item 1</li>
+                <li id="li-2" class="list-item item">Item 2</li>
+                <li id="li-3" class="list-item item">Item 3</li>
+            </ul>
+        </div>
+
+        <div id="deep-section">
+            <div id="level1">
+                <div id="level2">
+                    <div id="level3">
+                        <span id="deep-span">Deep nested element</span>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <div id="select-container">
+            <label for="simple-select">Choose:</label>
+            <select id="simple-select" name="choices">
+                <option value="alpha">Alpha</option>
+                <option value="beta">Beta</option>
+                <option value="gamma">Gamma</option>
+            </select>
+        </div>
+
+        <button id="hidden-button" class="action-btn">Hidden</button>
+    </div>
+</body>
+</html>
+
+
diff --git a/tests/pages/test_iframe_content.html b/tests/pages/test_iframe_content.html
new file mode 100644
index 00000000..71f119ff
--- /dev/null
+++ b/tests/pages/test_iframe_content.html
@@ -0,0 +1,89 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Iframe Content</title>
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            padding: 20px;
+        }
+        .hidden {
+            display: none;
+        }
+    </style>
+</head>
+<body>
+    <h1 id="iframe-heading">Iframe Content</h1>
+    
+    <div id="iframe-container">
+        <p id="iframe-paragraph">This is content inside the iframe.</p>
+        
+        <form id="iframe-form">
+            <label for="iframe-input">Name:</label>
+            <input id="iframe-input" type="text" name="name" placeholder="Enter your name">
+            
+            <label for="iframe-email">Email:</label>
+            <input id="iframe-email" type="email" name="email" placeholder="Enter your email">
+            
+            <label for="iframe-textarea">Message:</label>
+            <textarea id="iframe-textarea" name="message" rows="4">Default message</textarea>
+            
+            <button id="iframe-submit" type="submit">Submit</button>
+            <button id="iframe-reset" type="reset">Reset</button>
+        </form>
+        
+        <div id="iframe-links">
+            <a href="#link1" id="iframe-link1" class="iframe-link">Link 1</a>
+            <a href="#link2" id="iframe-link2" class="iframe-link">Link 2</a>
+            <a href="#link3" id="iframe-link3" class="iframe-link">Link 3</a>
+        </div>
+        
+        <div id="iframe-buttons">
+            <button id="iframe-button1" class="action-btn">Button 1</button>
+            <button id="iframe-button2" class="action-btn">Button 2</button>
+            <button id="iframe-button3" class="action-btn hidden">Hidden Button</button>
+        </div>
+        
+        <div id="iframe-list">
+            <ul>
+                <li id="item1" class="list-item">Item 1</li>
+                <li id="item2" class="list-item">Item 2</li>
+                <li id="item3" class="list-item">Item 3</li>
+            </ul>
+        </div>
+        
+        <select id="iframe-select">
+            <option value="option1">Option 1</option>
+            <option value="option2" selected>Option 2</option>
+            <option value="option3">Option 3</option>
+        </select>
+        
+        <div id="nested-elements">
+            <div id="level1">
+                <div id="level2">
+                    <div id="level3">
+                        <span id="deep-span">Deep nested element</span>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+    
+    <script>
+        // Add some interactivity
+        document.getElementById('iframe-submit').addEventListener('click', function(e) {
+            e.preventDefault();
+            console.log('Form submitted');
+        });
+        
+        document.querySelectorAll('.action-btn').forEach(btn => {
+            btn.addEventListener('click', function() {
+                console.log('Button clicked:', this.id);
+            });
+        });
+    </script>
+</body>
+</html>
+
diff --git a/tests/pages/test_iframe_nested.html b/tests/pages/test_iframe_nested.html
new file mode 100644
index 00000000..e3c1770a
--- /dev/null
+++ b/tests/pages/test_iframe_nested.html
@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Test Nested Iframes</title>
+</head>
+<body>
+    <h1 id="main-heading">Main Page with Nested Iframes</h1>
+    
+    <div id="main-content">
+        <p id="main-paragraph">Main page content</p>
+        <button id="main-button">Main Button</button>
+    </div>
+    
+    <iframe id="parent-iframe" src="test_iframe_parent_level.html" style="width: 100%; height: 800px;"></iframe>
+    
+    <div id="after-iframe">
+        <p>Content after parent iframe</p>
+    </div>
+</body>
+</html>
+
diff --git a/tests/pages/test_iframe_nested_level.html b/tests/pages/test_iframe_nested_level.html
new file mode 100644
index 00000000..b77f9ad9
--- /dev/null
+++ b/tests/pages/test_iframe_nested_level.html
@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Nested Iframe Level</title>
+    <style>
+        body {
+            background-color: #e0e0ff;
+            padding: 20px;
+        }
+    </style>
+</head>
+<body>
+    <h3 id="nested-iframe-heading">Nested Iframe Content</h3>
+    
+    <div id="nested-iframe-content">
+        <p id="nested-paragraph">This is the nested iframe level (child of parent iframe).</p>
+        <input id="nested-input" type="text" placeholder="Nested input">
+        <button id="nested-button">Nested Button</button>
+        
+        <div id="nested-links">
+            <a href="#nested-link1" id="nested-link1">Nested Link 1</a>
+            <a href="#nested-link2" id="nested-link2">Nested Link 2</a>
+        </div>
+        
+        <form id="nested-form">
+            <input id="nested-form-input" type="text" name="username" placeholder="Username">
+            <input id="nested-form-password" type="password" name="password" placeholder="Password">
+            <button id="nested-form-submit" type="submit">Login</button>
+        </form>
+    </div>
+</body>
+</html>
+
diff --git a/tests/pages/test_iframe_parent_level.html b/tests/pages/test_iframe_parent_level.html
new file mode 100644
index 00000000..1beca329
--- /dev/null
+++ b/tests/pages/test_iframe_parent_level.html
@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Parent Iframe Level</title>
+    <style>
+        body {
+            background-color: #f0f0f0;
+            padding: 20px;
+        }
+    </style>
+</head>
+<body>
+    <h2 id="parent-iframe-heading">Parent Iframe Content</h2>
+    
+    <div id="parent-iframe-content">
+        <p id="parent-paragraph">This is the parent iframe level.</p>
+        <input id="parent-input" type="text" placeholder="Parent input">
+        <button id="parent-button">Parent Button</button>
+    </div>
+    
+    <div id="nested-iframe-container">
+        <h3>Nested Iframe Below:</h3>
+        <iframe id="nested-iframe" src="test_iframe_nested_level.html" style="width: 100%; height: 400px;"></iframe>
+    </div>
+    
+    <div id="parent-footer">
+        <p>Parent iframe footer</p>
+    </div>
+</body>
+</html>
+
diff --git a/tests/pages/test_iframe_simple.html b/tests/pages/test_iframe_simple.html
new file mode 100644
index 00000000..a45b31a4
--- /dev/null
+++ b/tests/pages/test_iframe_simple.html
@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Test Simple Iframe</title>
+</head>
+<body>
+    <h1 id="main-heading">Main Page</h1>
+    <div id="main-content">
+        <p id="main-paragraph">This is the main page content.</p>
+        <button id="main-button">Main Button</button>
+        <input id="main-input" type="text" placeholder="Main input">
+    </div>
+    
+    <iframe id="simple-iframe" src="test_iframe_content.html" style="width: 800px; height: 600px;"></iframe>
+    
+    <div id="after-iframe">
+        <p>Content after iframe</p>
+    </div>
+</body>
+</html>
+
diff --git a/tests/test_browser/test_browser_tab.py b/tests/test_browser/test_browser_tab.py
index 6c07b644..ad794da4 100644
--- a/tests/test_browser/test_browser_tab.py
+++ b/tests/test_browser/test_browser_tab.py
@@ -1469,7 +1469,8 @@ async def test_get_frame_success(self, tab, mock_browser):
             {'targetId': 'iframe-target-id', 'url': 'https://example.com/iframe'}
         ])
 
-        frame = await tab.get_frame(mock_iframe_element)
+        with pytest.warns(DeprecationWarning):
+            frame = await tab.get_frame(mock_iframe_element)
         
         assert isinstance(frame, Tab)
         mock_browser.get_targets.assert_called_once()
@@ -1489,9 +1490,11 @@ async def test_get_frame_uses_cache_on_subsequent_calls(self, tab, mock_browser)
         tab._browser._tabs_opened = {}
 
         with patch('pydoll.browser.tab.ConnectionHandler', autospec=True):
-            frame1 = await tab.get_frame(mock_iframe_element)
+            with pytest.warns(DeprecationWarning):
+                frame1 = await tab.get_frame(mock_iframe_element)
             # Second call should reuse from cache and not create a new Tab
-            frame2 = await tab.get_frame(mock_iframe_element)
+            with pytest.warns(DeprecationWarning):
+                frame2 = await tab.get_frame(mock_iframe_element)
 
         assert isinstance(frame1, Tab)
         assert frame1 is frame2
@@ -1503,8 +1506,9 @@ async def test_get_frame_not_iframe(self, tab):
         mock_element = MagicMock()
         mock_element.tag_name = 'div'  # Mock the property directly
         
-        with pytest.raises(NotAnIFrame):
-            await tab.get_frame(mock_element)
+        with pytest.warns(DeprecationWarning):
+            with pytest.raises(NotAnIFrame):
+                await tab.get_frame(mock_element)
 
     @pytest.mark.asyncio
     async def test_get_frame_no_frame_id(self, tab, mock_browser):
@@ -1516,8 +1520,9 @@ async def test_get_frame_no_frame_id(self, tab, mock_browser):
 
         mock_browser.get_targets = AsyncMock(return_value=[])
         
-        with pytest.raises(IFrameNotFound):
-            await tab.get_frame(mock_iframe_element)
+        with pytest.warns(DeprecationWarning):
+            with pytest.raises(IFrameNotFound):
+                await tab.get_frame(mock_iframe_element)
 
 
 class TestTabUtilityMethods:
diff --git a/tests/test_core_integration.py b/tests/test_core_integration.py
new file mode 100644
index 00000000..bec7a1a1
--- /dev/null
+++ b/tests/test_core_integration.py
@@ -0,0 +1,150 @@
+"""Integration tests for core WebElement/Tab behaviors (non-iframe)."""
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from pydoll.browser.chromium import Chrome
+from pydoll.elements.web_element import WebElement
+
+
+class TestCoreFindQuery:
+    """Find and query basics on a simple page."""
+
+    @pytest.mark.asyncio
+    async def test_find_by_common_selectors(self, ci_chrome_options):
+        test_file = Path(__file__).parent / 'pages' / 'test_core_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(0.5)
+
+            # id
+            heading = await tab.find(id='main-heading')
+            assert heading is not None
+            assert isinstance(heading, WebElement)
+            assert heading.get_attribute('id') == 'main-heading'
+
+            # class_name (first occurrence)
+            first_item = await tab.find(class_name='item')
+            assert first_item is not None
+            assert 'item' in (first_item.get_attribute('class') or '')
+
+            # name
+            name_input = await tab.find(name='username')
+            assert name_input is not None
+            assert name_input.get_attribute('id') == 'text-input'
+
+            # tag_name (first button)
+            button = await tab.find(tag_name='button')
+            assert button is not None
+            assert button.get_attribute('id') == 'btn-1'
+
+    @pytest.mark.asyncio
+    async def test_query_css_and_xpath(self, ci_chrome_options):
+        test_file = Path(__file__).parent / 'pages' / 'test_core_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(0.5)
+
+            # CSS: list items
+            items = await tab.query('.list-item', find_all=True)
+            assert items is not None
+            assert len(items) == 3
+
+            # XPath absolute
+            deep_span = await tab.query('//*[@id="deep-section"]//span[@id="deep-span"]')
+            assert deep_span is not None
+            text = await deep_span.text
+            assert 'Deep nested element' in text
+
+            # XPath relative from container
+            container = await tab.find(id='deep-section')
+            rel_span = await container.find(xpath='.//span[@id="deep-span"]')
+            assert rel_span is not None
+            text2 = await rel_span.text
+            assert 'Deep nested element' in text2
+
+
+class TestCoreClickAndInput:
+    """Click and text insertion behaviors."""
+
+    @pytest.mark.asyncio
+    async def test_click_increments_counter(self, ci_chrome_options):
+        test_file = Path(__file__).parent / 'pages' / 'test_core_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(0.5)
+
+            button = await tab.find(id='btn-1')
+            counter = await tab.find(id='btn-1-count')
+
+            # before
+            before_text = await counter.text
+            assert before_text.strip() == '0'
+
+            await button.click()
+            await asyncio.sleep(0.2)
+            after_text = await counter.text
+            assert after_text.strip() == '1'
+
+            await button.click()
+            await asyncio.sleep(0.2)
+            after_text2 = await counter.text
+            assert after_text2.strip() == '2'
+
+    @pytest.mark.asyncio
+    async def test_insert_text_input_and_textarea(self, ci_chrome_options):
+        test_file = Path(__file__).parent / 'pages' / 'test_core_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(0.5)
+
+            # input
+            input_el = await tab.find(id='text-input')
+            await input_el.insert_text('Hello')
+            await asyncio.sleep(0.1)
+            assert 'Hello' in (input_el.get_attribute('value') or '')
+
+            # textarea
+            textarea = await tab.find(id='text-area')
+            await textarea.insert_text('World')
+            await asyncio.sleep(0.1)
+            assert 'World' in (textarea.get_attribute('value') or '')
+
+    @pytest.mark.asyncio
+    async def test_select_option_click(self, ci_chrome_options):
+        test_file = Path(__file__).parent / 'pages' / 'test_core_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(0.5)
+
+            select_el = await tab.find(id='simple-select')
+            assert select_el is not None
+
+            # click on option 'beta'
+            opt_beta = await select_el.find(xpath='.//option[@value="beta"]')
+            await opt_beta.click()
+            await asyncio.sleep(0.2)
+
+            # verify using JS value read
+            prop = await select_el.execute_script('return this.value', return_by_value=True)
+            current_value = prop['result']['result']['value']
+            assert current_value == 'beta'
+
+
diff --git a/tests/test_iframe_integration.py b/tests/test_iframe_integration.py
new file mode 100644
index 00000000..cf8b2d06
--- /dev/null
+++ b/tests/test_iframe_integration.py
@@ -0,0 +1,727 @@
+"""Integration tests for iframe functionality in WebElement.
+
+These tests use real HTML files and Chrome browser to test iframe interactions,
+element finding, and DOM manipulation within iframes.
+"""
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from pydoll.browser.chromium import Chrome
+from pydoll.elements.web_element import WebElement
+from pydoll.exceptions import ElementNotFound, InvalidIFrame
+
+
+class TestSimpleIframeIntegration:
+    """Integration tests for simple iframe operations."""
+
+    @pytest.mark.asyncio
+    async def test_find_element_in_iframe_by_id(self, ci_chrome_options):
+        """Test finding an element inside an iframe by id."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+
+            # Wait for iframe to load
+            await asyncio.sleep(1)
+
+            # Find the iframe element
+            iframe_element = await tab.find(id='simple-iframe')
+            assert iframe_element is not None
+            assert iframe_element.is_iframe
+
+            # Get iframe context
+            iframe_context = await iframe_element.iframe_context
+            assert iframe_context is not None
+            assert iframe_context.frame_id is not None
+            assert iframe_context.execution_context_id is not None
+
+            # Find element inside iframe
+            heading_in_iframe = await iframe_element.find(id='iframe-heading')
+            assert heading_in_iframe is not None
+            assert isinstance(heading_in_iframe, WebElement)
+
+            # Verify the element text
+            text = await heading_in_iframe.text
+            assert 'Iframe Content' in text
+
+    @pytest.mark.asyncio
+    async def test_find_multiple_elements_in_iframe(self, ci_chrome_options):
+        """Test finding multiple elements inside an iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find all links inside iframe
+            links = await iframe_element.query('.iframe-link', find_all=True)
+            assert len(links) == 3
+
+            # Verify each link
+            for i, link in enumerate(links, 1):
+                link_id = link.get_attribute('id')
+                assert link_id == f'iframe-link{i}'
+
+    @pytest.mark.asyncio
+    async def test_find_element_in_iframe_by_css_selector(self, ci_chrome_options):
+        """Test finding elements in iframe using CSS selectors."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find by class
+            action_buttons = await iframe_element.query('.action-btn', find_all=True)
+            assert len(action_buttons) >= 2  # At least 2 visible buttons
+
+            # Find by tag
+            inputs = await iframe_element.query('input[type="text"]', find_all=True)
+            assert len(inputs) >= 1
+
+    @pytest.mark.asyncio
+    async def test_find_element_in_iframe_by_xpath(self, ci_chrome_options):
+        """Test finding elements in iframe using XPath."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find by XPath
+            paragraph = await iframe_element.find(xpath='//p[@id="iframe-paragraph"]')
+            assert paragraph is not None
+
+            text = await paragraph.text
+            assert 'content inside the iframe' in text
+
+    @pytest.mark.asyncio
+    async def test_insert_text_in_iframe_input(self, ci_chrome_options):
+        """Test inserting text into an input field inside an iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find input inside iframe
+            input_element = await iframe_element.find(id='iframe-input')
+            assert input_element is not None
+
+            # Insert text
+            test_text = 'Test User Name'
+            await input_element.insert_text(test_text)
+
+            # Verify text was inserted
+            value = input_element.get_attribute('value')
+            assert test_text in value
+
+    @pytest.mark.asyncio
+    async def test_insert_text_in_iframe_textarea(self, ci_chrome_options):
+        """Test inserting text into a textarea inside an iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find textarea inside iframe
+            textarea = await iframe_element.find(id='iframe-textarea')
+            assert textarea is not None
+
+            # Insert new text (textarea initially empty)
+            new_message = 'This is a new test message'
+            await textarea.insert_text(new_message)
+
+            # Verify text was inserted
+            value = textarea.get_attribute('value')
+            assert new_message in value
+
+    @pytest.mark.asyncio
+    async def test_click_button_in_iframe(self, ci_chrome_options):
+        """Test clicking a button inside an iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find button inside iframe
+            button = await iframe_element.find(id='iframe-button1')
+            assert button is not None
+
+            # Click the button (should not raise exception)
+            await button.click()
+            await asyncio.sleep(0.5)
+
+    @pytest.mark.asyncio
+    async def test_get_inner_html_of_iframe(self, ci_chrome_options):
+        """Test getting inner HTML of an iframe element."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Get inner HTML of the iframe
+            inner_html = await iframe_element.inner_html
+            assert inner_html is not None
+            assert len(inner_html) > 0
+            assert 'iframe-heading' in inner_html
+            assert 'Iframe Content' in inner_html
+
+    @pytest.mark.asyncio
+    async def test_get_inner_html_of_element_in_iframe(self, ci_chrome_options):
+        """Test getting inner HTML of an element inside an iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find container inside iframe
+            container = await iframe_element.find(id='iframe-container')
+            assert container is not None
+
+            # Get inner HTML
+            inner_html = await container.inner_html
+            assert inner_html is not None
+            assert 'iframe-paragraph' in inner_html
+            assert 'iframe-form' in inner_html
+
+    @pytest.mark.asyncio
+    async def test_get_children_elements_in_iframe(self, ci_chrome_options):
+        """Test getting children elements of an element inside an iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find list inside iframe
+            list_element = await iframe_element.find(id='iframe-list')
+            assert list_element is not None
+
+            # Get list items using tag filter to avoid relying on class attributes
+            list_items = await list_element.get_children_elements(max_depth=2, tag_filter=['li'])
+            assert len(list_items) == 3
+
+    @pytest.mark.asyncio
+    async def test_element_visibility_in_iframe(self, ci_chrome_options):
+        """Test checking element visibility inside an iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find visible button
+            visible_button = await iframe_element.find(id='iframe-button1')
+            is_visible = await visible_button.is_visible()
+            assert is_visible is True
+
+            # Find hidden button
+            hidden_button = await iframe_element.find(id='iframe-button3')
+            is_hidden = await hidden_button.is_visible()
+            assert is_hidden is False
+
+
+class TestNestedIframeIntegration:
+    """Integration tests for nested iframe operations."""
+
+    @pytest.mark.asyncio
+    async def test_find_element_in_parent_iframe(self, ci_chrome_options):
+        """Test finding an element in parent iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_nested.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1.5)
+
+            # Find parent iframe
+            parent_iframe = await tab.find(id='parent-iframe')
+            assert parent_iframe is not None
+            assert parent_iframe.is_iframe
+
+            # Find element in parent iframe
+            parent_heading = await parent_iframe.find(id='parent-iframe-heading')
+            assert parent_heading is not None
+
+            text = await parent_heading.text
+            assert 'Parent Iframe Content' in text
+
+    @pytest.mark.asyncio
+    async def test_find_nested_iframe_element(self, ci_chrome_options):
+        """Test finding the nested iframe element inside parent iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_nested.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1.5)
+
+            # Find parent iframe
+            parent_iframe = await tab.find(id='parent-iframe')
+
+            # Find nested iframe inside parent iframe
+            nested_iframe = await parent_iframe.find(id='nested-iframe')
+            assert nested_iframe is not None
+            assert nested_iframe.is_iframe
+
+    @pytest.mark.asyncio
+    async def test_find_element_in_nested_iframe(self, ci_chrome_options):
+        """Test finding an element in nested iframe (iframe within iframe)."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_nested.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(2)
+
+            # Find parent iframe
+            parent_iframe = await tab.find(id='parent-iframe')
+
+            # Find nested iframe inside parent
+            nested_iframe = await parent_iframe.find(id='nested-iframe')
+            assert nested_iframe is not None
+
+            # Find element in nested iframe
+            nested_heading = await nested_iframe.find(id='nested-iframe-heading')
+            assert nested_heading is not None
+
+            text = await nested_heading.text
+            assert 'Nested Iframe Content' in text
+
+    @pytest.mark.asyncio
+    async def test_insert_text_in_nested_iframe(self, ci_chrome_options):
+        """Test inserting text into input field in nested iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_nested.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(2)
+
+            # Navigate to nested iframe
+            parent_iframe = await tab.find(id='parent-iframe')
+            nested_iframe = await parent_iframe.find(id='nested-iframe')
+
+            # Find input in nested iframe
+            nested_input = await nested_iframe.find(id='nested-input')
+            assert nested_input is not None
+
+            # Insert text
+            test_text = 'Nested Input Test'
+            await nested_input.insert_text(test_text)
+
+            # Verify
+            value = nested_input.get_attribute('value')
+            assert test_text in value
+
+    @pytest.mark.asyncio
+    async def test_find_multiple_elements_in_nested_iframe(self, ci_chrome_options):
+        """Test finding multiple elements in nested iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_nested.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(2)
+
+            # Navigate to nested iframe
+            parent_iframe = await tab.find(id='parent-iframe')
+            nested_iframe = await parent_iframe.find(id='nested-iframe')
+
+            # Find all links in nested iframe
+            links = await nested_iframe.query('a', find_all=True)
+            assert len(links) == 2
+
+            # Verify link IDs
+            link_ids = [link.get_attribute('id') for link in links]
+            assert 'nested-link1' in link_ids
+            assert 'nested-link2' in link_ids
+
+    @pytest.mark.asyncio
+    async def test_submit_form_in_nested_iframe(self, ci_chrome_options):
+        """Test interacting with form elements in nested iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_nested.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(2)
+
+            # Navigate to nested iframe
+            parent_iframe = await tab.find(id='parent-iframe')
+            nested_iframe = await parent_iframe.find(id='nested-iframe')
+
+            # Fill form fields
+            username_input = await nested_iframe.find(id='nested-form-input')
+            await username_input.insert_text('testuser')
+
+            password_input = await nested_iframe.find(id='nested-form-password')
+            await password_input.insert_text('password123')
+
+            # Verify values
+            assert 'testuser' in username_input.get_attribute('value')
+            assert 'password123' in password_input.get_attribute('value')
+
+            # Click submit button
+            submit_button = await nested_iframe.find(id='nested-form-submit')
+            await submit_button.click()
+            await asyncio.sleep(0.5)
+
+
+class TestIframeElementInteraction:
+    """Integration tests for various element interactions within iframes."""
+
+    @pytest.mark.asyncio
+    async def test_select_option_in_iframe(self, ci_chrome_options):
+        """Test selecting an option in a select element inside iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find select element
+            select_element = await iframe_element.find(id='iframe-select')
+            assert select_element is not None
+
+            # Select option2 by clicking the option element
+            option2 = await select_element.find(xpath='.//option[@value="option2"]')
+            await option2.click()
+            await asyncio.sleep(0.2)
+            # Verify via property read (execute_script)
+            prop_val = await select_element.execute_script('return this.value', return_by_value=True)
+            current_value = prop_val['result']['result']['value']
+            assert current_value == 'option2'
+
+            # Select different option (option3) by clicking it
+            option3 = await select_element.find(xpath='.//option[@value="option3"]')
+            await option3.click()
+            await asyncio.sleep(0.2)
+            prop_val2 = await select_element.execute_script('return this.value', return_by_value=True)
+            new_value = prop_val2['result']['result']['value']
+            assert new_value == 'option3'
+
+    @pytest.mark.asyncio
+    async def test_get_attributes_from_iframe_elements(self, ci_chrome_options):
+        """Test getting various attributes from elements in iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Get link attributes
+            link = await iframe_element.find(id='iframe-link1')
+            href = link.get_attribute('href')
+            assert href is not None
+            assert '#link1' in href
+
+            link_class = link.get_attribute('class')
+            assert 'iframe-link' in link_class
+
+            # Get input attributes
+            input_elem = await iframe_element.find(id='iframe-input')
+            input_type = input_elem.get_attribute('type')
+            assert input_type == 'text'
+
+            placeholder = input_elem.get_attribute('placeholder')
+            assert 'name' in placeholder.lower()
+
+    @pytest.mark.asyncio
+    async def test_deep_nested_element_search_in_iframe(self, ci_chrome_options):
+        """Test finding deeply nested elements inside iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find deeply nested element
+            deep_span = await iframe_element.find(id='deep-span')
+            assert deep_span is not None
+
+            text = await deep_span.text
+            assert 'Deep nested element' in text
+
+
+    @pytest.mark.asyncio
+    async def test_wait_for_element_in_iframe(self, ci_chrome_options):
+        """Test waiting for element to appear in iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Wait for element (should already exist)
+            element = await iframe_element.find(
+                id='iframe-paragraph', timeout=5
+            )
+            assert element is not None
+
+            text = await element.text
+            assert 'content inside the iframe' in text
+
+    @pytest.mark.asyncio
+    async def test_element_not_found_in_iframe(self, ci_chrome_options):
+        """Test that ElementNotFound is raised for non-existent elements in iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Try to find non-existent element
+            with pytest.raises(ElementNotFound):
+                await iframe_element.find(id='non-existent-element')
+
+    @pytest.mark.asyncio
+    async def test_clear_input_in_iframe(self, ci_chrome_options):
+        """Test clearing input field in iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Find input and add text
+            input_elem = await iframe_element.find(id='iframe-input')
+            await input_elem.insert_text('Test text to clear')
+            await asyncio.sleep(0.3)
+
+            await input_elem.insert_text('')
+            await asyncio.sleep(0.3)
+            value = input_elem.get_attribute('value')
+            assert value in ('', None)
+
+    @pytest.mark.asyncio
+    async def test_multiple_iframes_on_same_page(self, ci_chrome_options):
+        """Test handling multiple iframes on the same page."""
+        # Create a test page with multiple iframes
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            # Find main content (not in iframe)
+            main_heading = await tab.find(id='main-heading')
+            assert main_heading is not None
+            main_text = await main_heading.text
+            assert 'Main Page' in main_text
+
+            # Find content in iframe
+            iframe_element = await tab.find(id='simple-iframe')
+            iframe_heading = await iframe_element.find(id='iframe-heading')
+            iframe_text = await iframe_heading.text
+            assert 'Iframe Content' in iframe_text
+
+            # Verify they are different
+            assert main_text != iframe_text
+
+    @pytest.mark.asyncio
+    async def test_iframe_context_persistence(self, ci_chrome_options):
+        """Test that iframe context persists across multiple operations."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Get context first time
+            context1 = await iframe_element.iframe_context
+            assert context1 is not None
+
+            # Perform some operations
+            element1 = await iframe_element.find(id='iframe-heading')
+            await element1.text
+
+            # Get context again
+            context2 = await iframe_element.iframe_context
+            assert context2 is not None
+
+            # Verify contexts are consistent
+            assert context1.frame_id == context2.frame_id
+            assert context1.execution_context_id == context2.execution_context_id
+
+    @pytest.mark.asyncio
+    async def test_get_text_from_multiple_elements_in_iframe(self, ci_chrome_options):
+        """Test getting text from multiple elements in iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Get all list items
+            list_items = await iframe_element.query('.list-item', find_all=True)
+            assert len(list_items) == 3
+
+            # Get text from each
+            texts = []
+            for item in list_items:
+                text = await item.text
+                texts.append(text)
+
+            # Verify texts
+            assert 'Item 1' in texts[0]
+            assert 'Item 2' in texts[1]
+            assert 'Item 3' in texts[2]
+
+
+class TestIframeEdgeCases:
+    """Integration tests for edge cases in iframe handling."""
+
+    @pytest.mark.asyncio
+    async def test_dynamic_content_in_iframe(self, ci_chrome_options):
+        """Test finding dynamically added content in iframe."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            iframe_element = await tab.find(id='simple-iframe')
+
+            # Add dynamic content via JavaScript
+            iframe_context = await iframe_element.iframe_context
+            await tab.execute_script(
+                """
+                const div = document.createElement('div');
+                div.id = 'dynamic-element';
+                div.textContent = 'Dynamic Content';
+                document.body.appendChild(div);
+                """,
+                context_id=iframe_context.execution_context_id,
+            )
+            await asyncio.sleep(0.5)
+
+            # Find dynamically added element
+            dynamic_element = await iframe_element.find(id='dynamic-element')
+            assert dynamic_element is not None
+
+            text = await dynamic_element.text
+            assert 'Dynamic Content' in text
+
+    @pytest.mark.asyncio
+    async def test_iframe_reload_handling(self, ci_chrome_options):
+        """Test that iframe context is properly handled after page reload."""
+        test_file = Path(__file__).parent / 'pages' / 'test_iframe_simple.html'
+        file_url = f'file://{test_file.absolute()}'
+
+        async with Chrome(options=ci_chrome_options) as browser:
+            tab = await browser.start()
+            await tab.go_to(file_url)
+            await asyncio.sleep(1)
+
+            # Find iframe and element
+            iframe_element = await tab.find(id='simple-iframe')
+            element_before = await iframe_element.find(id='iframe-heading')
+            assert element_before is not None
+
+            # Reload page
+            await tab.refresh()
+            await asyncio.sleep(1)
+
+            # Find iframe again (new instance)
+            iframe_element_after = await tab.find(id='simple-iframe')
+            element_after = await iframe_element_after.find(id='iframe-heading')
+            assert element_after is not None
+
+            # Verify element is accessible
+            text = await element_after.text
+            assert 'Iframe Content' in text
+
diff --git a/tests/test_managers/test_browser_managers.py b/tests/test_managers/test_browser_managers.py
index 02bb1611..13a1d895 100644
--- a/tests/test_managers/test_browser_managers.py
+++ b/tests/test_managers/test_browser_managers.py
@@ -169,13 +169,11 @@ def test_handle_cleanup_error(temp_manager):
     temp_manager.handle_cleanup_error(func_mock, path, (PermissionError, PermissionError(), None))
     temp_manager.retry_process_file.assert_called_once_with(func_mock, path)
 
-    # matched permission error
+    # matched permission error - should not raise, only log and continue
     temp_manager.retry_process_file = Mock()
     temp_manager.retry_process_file.side_effect = PermissionError
     path = "/tmp/CrashpadMetrics-active.pma"
-    
-    with pytest.raises(PermissionError):
-        temp_manager.handle_cleanup_error(func_mock, path, (PermissionError, PermissionError(), None))
+    temp_manager.handle_cleanup_error(func_mock, path, (PermissionError, PermissionError(), None))
 
     # unmatched permission error
     temp_manager.retry_process_file = Mock()
diff --git a/tests/test_web_element.py b/tests/test_web_element.py
index efff65f9..f365c0b8 100644
--- a/tests/test_web_element.py
+++ b/tests/test_web_element.py
@@ -117,27 +117,18 @@ def disabled_element(mock_connection_handler):
 
 
 @pytest.fixture
-def ci_chrome_options():
-    """Chrome options optimized for CI environments."""
-    options = Options()
-    options.headless = True
-    options.start_timeout = 30
-
-    # CI-specific arguments
-    options.add_argument('--no-sandbox')
-    options.add_argument('--disable-dev-shm-usage')
-    options.add_argument('--disable-gpu')
-    options.add_argument('--disable-extensions')
-    options.add_argument('--disable-background-timer-throttling')
-    options.add_argument('--disable-backgrounding-occluded-windows')
-    options.add_argument('--disable-renderer-backgrounding')
-    options.add_argument('--disable-default-apps')
+def iframe_element(mock_connection_handler):
+    """Iframe element fixture for iframe-related tests."""
+    attributes_list = ['id', 'iframe-id', 'tag_name', 'iframe']
+    return WebElement(
+        object_id='iframe-object-id',
+        connection_handler=mock_connection_handler,
+        method='css',
+        selector='iframe#iframe-id',
+        attributes_list=attributes_list,
+    )
 
-    # Memory optimization
-    options.add_argument('--memory-pressure-off')
-    options.add_argument('--max_old_space_size=4096')
 
-    return options
 
 
 class TestWebElementInitialization:
@@ -262,6 +253,13 @@ async def test_inner_html_property(self, web_element):
         html = await web_element.inner_html
         assert html == expected_html
 
+    @pytest.mark.asyncio
+    async def test_iframe_context_non_iframe_returns_none(self, web_element):
+        """Non-iframe elements should not produce iframe context."""
+        result = await web_element.iframe_context
+        assert result is None
+        web_element._connection_handler.execute_command.assert_not_awaited()
+
 
 class TestWebElementMethods:
     """Test WebElement methods and interactions."""
@@ -324,6 +322,185 @@ async def test_type_text_default_interval(self, input_element):
         mock_sleep.assert_called_with(0.1)  # Default interval
         assert input_element.click.call_count == 1
 
+
+class TestWebElementIFrame:
+    """Tests for iframe-specific WebElement behaviour."""
+
+    @pytest.mark.asyncio
+    async def test_iframe_context_initialization(self, iframe_element):
+        """Iframe context should be created via CDP commands."""
+
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'DOM.describeNode':
+                return {
+                    'result': {
+                        'node': {
+                            'frameId': 'frame-123',
+                            'contentDocument': {
+                                'frameId': 'frame-123',
+                                'documentURL': 'https://example.com/frame.html',
+                                'baseURL': 'https://example.com/frame.html',
+                            },
+                        }
+                    }
+                }
+            if method == 'Page.createIsolatedWorld':
+                return {'result': {'executionContextId': 42}}
+            if method == 'Runtime.evaluate':
+                return {
+                    'result': {
+                        'result': {
+                            'type': 'object',
+                            'objectId': 'document-object-id',
+                        }
+                    }
+                }
+            raise AssertionError(f'Unexpected method {method}')
+
+        iframe_element._connection_handler.execute_command.side_effect = side_effect
+
+        ctx = await iframe_element.iframe_context
+        assert ctx is not None
+        assert ctx.frame_id == 'frame-123'
+        assert ctx.document_url == 'https://example.com/frame.html'
+        assert ctx.execution_context_id == 42
+        assert ctx.document_object_id == 'document-object-id'
+
+        # Subsequent access should not trigger additional CDP calls
+        iframe_element._connection_handler.execute_command.reset_mock()
+        cached_ctx = await iframe_element.iframe_context
+        assert cached_ctx is ctx
+        iframe_element._connection_handler.execute_command.assert_not_awaited()
+
+    @pytest.mark.asyncio
+    async def test_iframe_inner_html_uses_runtime_evaluate(self, iframe_element):
+        """inner_html should read from iframe execution context."""
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'DOM.describeNode':
+                return {
+                    'result': {
+                        'node': {
+                            'frameId': 'frame-123',
+                            'contentDocument': {
+                                'frameId': 'frame-123',
+                                'documentURL': 'https://example.com/frame.html',
+                                'baseURL': 'https://example.com/frame.html',
+                            },
+                        }
+                    }
+                }
+            if method == 'Page.createIsolatedWorld':
+                return {'result': {'executionContextId': 77}}
+            if method == 'Runtime.evaluate':
+                expression = command['params']['expression']
+                if expression == 'document.documentElement':
+                    return {
+                        'result': {
+                            'result': {
+                                'type': 'object',
+                                'objectId': 'document-object-id',
+                            }
+                        }
+                    }
+                if expression == 'document.documentElement.outerHTML':
+                    assert command['params']['contextId'] == 77
+                    return {
+                        'result': {
+                            'result': {
+                                'type': 'string',
+                                'value': '<html>iframe content</html>',
+                            }
+                        }
+                    }
+            raise AssertionError(f'Unexpected method {method}')
+
+        iframe_element._connection_handler.execute_command.side_effect = side_effect
+
+        html = await iframe_element.inner_html
+        assert html == '<html>iframe content</html>'
+
+        methods = [
+            call.args[0]['method']
+            for call in iframe_element._connection_handler.execute_command.await_args_list
+        ]
+        assert methods.count('DOM.describeNode') == 1
+        assert methods.count('Page.createIsolatedWorld') == 1
+        assert methods.count('Runtime.evaluate') == 2
+
+    @pytest.mark.asyncio
+    async def test_find_within_iframe_uses_document_context(self, iframe_element):
+        """find() should query against the iframe's document element."""
+
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'DOM.describeNode':
+                object_id = command['params'].get('objectId')
+                if object_id == 'iframe-object-id':
+                    return {
+                        'result': {
+                            'node': {
+                                'frameId': 'frame-123',
+                                'contentDocument': {
+                                    'frameId': 'frame-123',
+                                    'documentURL': 'https://example.com/frame.html',
+                                    'baseURL': 'https://example.com/frame.html',
+                                },
+                            }
+                        }
+                    }
+                if object_id == 'element-object-id':
+                    return {
+                        'result': {
+                            'node': {
+                                'nodeName': 'DIV',
+                                'attributes': ['id', 'child', 'data-test', 'value'],
+                            }
+                        }
+                    }
+                raise AssertionError('Unexpected objectId in describeNode')
+            if method == 'Page.createIsolatedWorld':
+                return {'result': {'executionContextId': 88}}
+            if method == 'Runtime.evaluate':
+                expression = command['params']['expression']
+                if expression == 'document.documentElement':
+                    return {
+                        'result': {
+                            'result': {
+                                'type': 'object',
+                                'objectId': 'document-object-id',
+                            }
+                        }
+                    }
+                raise AssertionError(f'Unexpected evaluate expression: {expression}')
+            if method == 'Runtime.callFunctionOn':
+                assert command['params']['objectId'] == 'document-object-id'
+                return {
+                    'result': {
+                        'result': {
+                            'type': 'object',
+                            'objectId': 'element-object-id',
+                        }
+                    }
+                }
+            raise AssertionError(f'Unexpected method {method}')
+
+        iframe_element._connection_handler.execute_command.side_effect = side_effect
+
+        result = await iframe_element.find(tag_name='div')
+
+        assert isinstance(result, WebElement)
+        assert result._object_id == 'element-object-id'
+
+        runtime_calls = [
+            call.args[0]
+            for call in iframe_element._connection_handler.execute_command.await_args_list
+            if call.args[0]['method'] == 'Runtime.callFunctionOn'
+        ]
+        assert runtime_calls, 'Runtime.callFunctionOn should be used for iframe queries'
+        assert runtime_calls[0]['params']['objectId'] == 'document-object-id'
+
     @pytest.mark.asyncio
     async def test_get_parent_element_success(self, web_element):
         """Test successful parent element retrieval."""
@@ -914,6 +1091,52 @@ async def test_execute_script_basic(self, web_element):
             expected_command, timeout=60
         )
 
+class TestBuildTextExpression:
+    """Unit tests for WebElement._build_text_expression."""
+
+    def test_build_text_expression_with_xpath(self):
+        expr = WebElement._build_text_expression('//p[@id="x"]', 'xpath')
+        assert isinstance(expr, str)
+        assert 'XPathResult.FIRST_ORDERED_NODE_TYPE' in expr
+        assert '@id' in expr
+        assert 'p' in expr
+
+    def test_build_text_expression_with_name(self):
+        expr = WebElement._build_text_expression('fieldName', 'name')
+        assert isinstance(expr, str)
+        assert '//*[@name="fieldName"]' in expr
+
+    def test_build_text_expression_with_id_css(self):
+        expr = WebElement._build_text_expression('main', 'id')
+        assert 'document.querySelector' in expr
+        assert '#main' in expr
+
+    def test_build_text_expression_with_class_css(self):
+        expr = WebElement._build_text_expression('item', 'class_name')
+        assert 'document.querySelector' in expr
+        assert '.item' in expr
+
+    def test_build_text_expression_with_tag_css(self):
+        expr = WebElement._build_text_expression('button', 'tag_name')
+        assert 'document.querySelector' in expr
+        assert 'button' in expr
+
+class TestIsOptionElementHeuristics:
+    """Unit tests for heuristics inside WebElement._is_option_element."""
+
+    @pytest.mark.asyncio
+    async def test_is_option_element_by_tag_attribute(self, option_element):
+        assert await option_element._is_option_element() is True
+
+    @pytest.mark.asyncio
+    async def test_is_option_element_by_method_and_selector_tag_name(self, mock_connection_handler):
+        dummy = WebElement('dummy', mock_connection_handler, method='tag_name', selector='option', attributes_list=[])
+        assert await dummy._is_option_element() is True
+
+    @pytest.mark.asyncio
+    async def test_is_option_element_by_xpath_selector_contains_option(self, mock_connection_handler):
+        dummy = WebElement('dummy', mock_connection_handler, method='xpath', selector='//OPTION[@value=\"x\"]', attributes_list=[])
+        assert await dummy._is_option_element() is True
     @pytest.mark.asyncio
     async def test_execute_script_with_this_syntax(self, web_element):
         """Test execute_script method with 'this' syntax."""
@@ -1601,3 +1824,1143 @@ async def test_get_siblings_elements_element_not_found_exception(self):
         # Should raise ElementNotFound when script returns no objectId
         with pytest.raises(ElementNotFound):
             await element.get_siblings_elements(raise_exc=True)
+
+
+"""
+Tests for WebElement iframe edge cases and uncovered code paths.
+
+This test suite focuses on covering edge cases in iframe resolution and context handling,
+including:
+- inner_html edge cases for iframes and iframe context elements
+- Frame tree traversal and owner resolution
+- OOPIF resolution scenarios
+- Isolated world creation failures
+- Document object resolution failures
+"""
+
+import pytest
+import pytest_asyncio
+from unittest.mock import AsyncMock, patch
+
+from pydoll.elements.web_element import WebElement, _IFrameContext
+from pydoll.connection import ConnectionHandler
+from pydoll.exceptions import InvalidIFrame
+
+
+@pytest_asyncio.fixture
+async def mock_connection_handler():
+    """Mock connection handler for WebElement tests."""
+    with patch('pydoll.connection.ConnectionHandler', autospec=True) as mock:
+        handler = mock.return_value
+        handler.execute_command = AsyncMock()
+        handler._connection_port = 9222
+        yield handler
+
+
+@pytest.fixture
+def iframe_element(mock_connection_handler):
+    """Iframe element fixture for iframe-related tests."""
+    attributes_list = ['id', 'test-iframe', 'tag_name', 'iframe']
+    return WebElement(
+        object_id='iframe-object-id',
+        connection_handler=mock_connection_handler,
+        method='css',
+        selector='iframe#test-iframe',
+        attributes_list=attributes_list,
+    )
+
+
+@pytest.fixture
+def element_in_iframe(mock_connection_handler):
+    """Element inside an iframe (has _iframe_context set)."""
+    attributes_list = ['id', 'button-in-iframe', 'tag_name', 'button']
+    element = WebElement(
+        object_id='button-object-id',
+        connection_handler=mock_connection_handler,
+        method='css',
+        selector='button',
+        attributes_list=attributes_list,
+    )
+    # Set iframe context to simulate element inside iframe
+    element._iframe_context = _IFrameContext(
+        frame_id='frame-123',
+        document_url='https://example.com/iframe.html',
+        execution_context_id=42,
+        document_object_id='doc-obj-id',
+    )
+    return element
+
+
+class TestInnerHtmlEdgeCases:
+    """Test inner_html property edge cases for iframe scenarios."""
+
+    @pytest.mark.asyncio
+    async def test_inner_html_iframe_element_with_context(self, iframe_element):
+        """Test inner_html on iframe element uses Runtime.evaluate in iframe context."""
+
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'DOM.describeNode':
+                return {
+                    'result': {
+                        'node': {
+                            'frameId': 'parent-frame',
+                            'backendNodeId': 999,
+                            'contentDocument': {
+                                'frameId': 'iframe-123',
+                                'documentURL': 'https://example.com/frame.html',
+                            },
+                        }
+                    }
+                }
+            if method == 'Page.createIsolatedWorld':
+                return {'result': {'executionContextId': 77}}
+            if method == 'Runtime.evaluate':
+                expression = command['params']['expression']
+                if expression == 'document.documentElement':
+                    return {
+                        'result': {
+                            'result': {
+                                'type': 'object',
+                                'objectId': 'doc-element-id',
+                            }
+                        }
+                    }
+                if expression == 'document.documentElement.outerHTML':
+                    return {
+                        'result': {
+                            'result': {
+                                'type': 'string',
+                                'value': '<html><body>Iframe content</body></html>',
+                            }
+                        }
+                    }
+            raise AssertionError(f'Unexpected method {method}')
+
+        iframe_element._connection_handler.execute_command.side_effect = side_effect
+
+        # Get inner HTML of iframe element
+        html = await iframe_element.inner_html
+
+        # Should return iframe's document HTML
+        assert html == '<html><body>Iframe content</body></html>'
+
+        # Verify Runtime.evaluate was called with correct context
+        evaluate_calls = [
+            call
+            for call in iframe_element._connection_handler.execute_command.await_args_list
+            if call.args[0]['method'] == 'Runtime.evaluate'
+        ]
+        # Should have two calls: one for document.documentElement, one for outerHTML
+        assert len(evaluate_calls) == 2
+        outer_html_call = evaluate_calls[1]
+        assert (
+            outer_html_call.args[0]['params']['expression']
+            == 'document.documentElement.outerHTML'
+        )
+        assert outer_html_call.args[0]['params']['contextId'] == 77
+
+    @pytest.mark.asyncio
+    async def test_inner_html_element_in_iframe_uses_call_function_on(self, element_in_iframe):
+        """Test inner_html on element inside iframe uses Runtime.callFunctionOn."""
+        element_in_iframe._connection_handler.execute_command.return_value = {
+            'result': {
+                'result': {
+                    'type': 'string',
+                    'value': '<button id="button-in-iframe">Click me</button>',
+                }
+            }
+        }
+
+        html = await element_in_iframe.inner_html
+
+        # Should use callFunctionOn with this.outerHTML
+        assert html == '<button id="button-in-iframe">Click me</button>'
+        element_in_iframe._connection_handler.execute_command.assert_called_once()
+        call_args = element_in_iframe._connection_handler.execute_command.call_args[0][0]
+        assert call_args['method'] == 'Runtime.callFunctionOn'
+        assert call_args['params']['objectId'] == 'button-object-id'
+        assert 'this.outerHTML' in call_args['params']['functionDeclaration']
+
+    @pytest.mark.asyncio
+    async def test_inner_html_element_in_iframe_empty_response(self, element_in_iframe):
+        """Test inner_html on element inside iframe when response is empty."""
+        element_in_iframe._connection_handler.execute_command.return_value = {
+            'result': {}  # Empty result
+        }
+
+        html = await element_in_iframe.inner_html
+
+        # Should return empty string when result is missing
+        assert html == ''
+
+    @pytest.mark.asyncio
+    async def test_inner_html_regular_element_fallback(self, mock_connection_handler):
+        """Test inner_html falls back to DOM.getOuterHTML for regular elements."""
+        attributes_list = ['id', 'regular-div', 'tag_name', 'div']
+        element = WebElement(
+            object_id='div-object-id',
+            connection_handler=mock_connection_handler,
+            attributes_list=attributes_list,
+        )
+        mock_connection_handler.execute_command.return_value = {
+            'result': {'outerHTML': '<div id="regular-div">Content</div>'}
+        }
+
+        html = await element.inner_html
+
+        # Should use DOM.getOuterHTML for regular elements
+        assert html == '<div id="regular-div">Content</div>'
+        call_args = mock_connection_handler.execute_command.call_args[0][0]
+        assert call_args['method'] == 'DOM.getOuterHTML'
+
+
+class TestFrameTreeHelpers:
+    """Test frame tree traversal and helper methods."""
+
+    @pytest.mark.asyncio
+    async def test_get_frame_tree_for_without_session_id(self, mock_connection_handler):
+        """Test _get_frame_tree_for without session_id."""
+        mock_connection_handler.execute_command.return_value = {
+            'result': {
+                'frameTree': {
+                    'frame': {
+                        'id': 'main-frame',
+                        'url': 'https://example.com',
+                    },
+                    'childFrames': [],
+                }
+            }
+        }
+
+        frame_tree = await WebElement._get_frame_tree_for(mock_connection_handler, None)
+
+        assert frame_tree['frame']['id'] == 'main-frame'
+        # Should NOT have sessionId in command when session_id is None
+        call_args = mock_connection_handler.execute_command.call_args[0][0]
+        assert 'sessionId' not in call_args
+
+    @pytest.mark.asyncio
+    async def test_get_frame_tree_for_with_session_id(self, mock_connection_handler):
+        """Test _get_frame_tree_for WITH session_id (coverage for line 718)."""
+        mock_connection_handler.execute_command.return_value = {
+            'result': {
+                'frameTree': {
+                    'frame': {
+                        'id': 'oopif-frame',
+                        'url': 'https://other-origin.com',
+                    },
+                    'childFrames': [],
+                }
+            }
+        }
+
+        frame_tree = await WebElement._get_frame_tree_for(
+            mock_connection_handler, 'session-abc-123'
+        )
+
+        assert frame_tree['frame']['id'] == 'oopif-frame'
+        # Should HAVE sessionId in command
+        call_args = mock_connection_handler.execute_command.call_args[0][0]
+        assert call_args['sessionId'] == 'session-abc-123'
+
+    def test_walk_frames_single_frame(self):
+        """Test _walk_frames with single frame (no children)."""
+        frame_tree = {
+            'frame': {
+                'id': 'single-frame',
+                'url': 'https://example.com',
+            },
+            'childFrames': [],
+        }
+
+        frames = list(WebElement._walk_frames(frame_tree))
+
+        assert len(frames) == 1
+        assert frames[0]['id'] == 'single-frame'
+
+    def test_walk_frames_nested_frames(self):
+        """Test _walk_frames with nested frames."""
+        frame_tree = {
+            'frame': {
+                'id': 'main-frame',
+                'url': 'https://example.com',
+            },
+            'childFrames': [
+                {
+                    'frame': {
+                        'id': 'child-frame-1',
+                        'url': 'https://example.com/child1',
+                    },
+                    'childFrames': [
+                        {
+                            'frame': {
+                                'id': 'nested-frame',
+                                'url': 'https://example.com/nested',
+                            },
+                            'childFrames': [],
+                        }
+                    ],
+                },
+                {
+                    'frame': {
+                        'id': 'child-frame-2',
+                        'url': 'https://example.com/child2',
+                    },
+                    'childFrames': [],
+                },
+            ],
+        }
+
+        frames = list(WebElement._walk_frames(frame_tree))
+
+        assert len(frames) == 4
+        frame_ids = [f['id'] for f in frames]
+        assert 'main-frame' in frame_ids
+        assert 'child-frame-1' in frame_ids
+        assert 'nested-frame' in frame_ids
+        assert 'child-frame-2' in frame_ids
+
+    def test_walk_frames_empty_tree(self):
+        """Test _walk_frames with empty/None tree."""
+        frames = list(WebElement._walk_frames(None))
+        assert len(frames) == 0
+
+        frames = list(WebElement._walk_frames({}))
+        assert len(frames) == 0
+
+    def test_walk_frames_filters_none_frames(self):
+        """Test _walk_frames filters out None frames."""
+        frame_tree = {
+            'frame': {
+                'id': 'valid-frame',
+                'url': 'https://example.com',
+            },
+            'childFrames': [
+                None,  # Should be filtered out
+                {
+                    'frame': None,  # Should be filtered out
+                    'childFrames': [],
+                },
+                {
+                    'frame': {
+                        'id': 'another-valid-frame',
+                        'url': 'https://example.com/valid',
+                    },
+                    'childFrames': [],
+                },
+            ],
+        }
+
+        frames = list(WebElement._walk_frames(frame_tree))
+
+        # Should only include valid frames
+        frame_ids = [f['id'] for f in frames if f]
+        assert 'valid-frame' in frame_ids
+        assert 'another-valid-frame' in frame_ids
+        assert len(frame_ids) == 2
+
+    @pytest.mark.asyncio
+    async def test_owner_backend_for_without_session_id(self, mock_connection_handler):
+        """Test _owner_backend_for without session_id."""
+        mock_connection_handler.execute_command.return_value = {
+            'result': {'backendNodeId': 456}
+        }
+
+        backend_id = await WebElement._owner_backend_for(
+            mock_connection_handler, None, 'frame-123'
+        )
+
+        assert backend_id == 456
+        call_args = mock_connection_handler.execute_command.call_args[0][0]
+        assert 'sessionId' not in call_args
+
+    @pytest.mark.asyncio
+    async def test_owner_backend_for_with_session_id(self, mock_connection_handler):
+        """Test _owner_backend_for WITH session_id (coverage for line 757)."""
+        mock_connection_handler.execute_command.return_value = {
+            'result': {'backendNodeId': 789}
+        }
+
+        backend_id = await WebElement._owner_backend_for(
+            mock_connection_handler, 'session-xyz-789', 'frame-456'
+        )
+
+        assert backend_id == 789
+        call_args = mock_connection_handler.execute_command.call_args[0][0]
+        assert call_args['sessionId'] == 'session-xyz-789'
+
+    @pytest.mark.asyncio
+    async def test_owner_backend_for_missing_result(self, mock_connection_handler):
+        """Test _owner_backend_for when result is missing."""
+        mock_connection_handler.execute_command.return_value = {}
+
+        backend_id = await WebElement._owner_backend_for(
+            mock_connection_handler, None, 'frame-999'
+        )
+
+        assert backend_id is None
+
+
+class TestFindFrameByOwner:
+    """Test _find_frame_by_owner method."""
+
+    @pytest.mark.asyncio
+    async def test_find_frame_by_owner_found(self, iframe_element, mock_connection_handler):
+        """Test _find_frame_by_owner successfully finds matching frame."""
+
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'Page.getFrameTree':
+                return {
+                    'result': {
+                        'frameTree': {
+                            'frame': {'id': 'main', 'url': 'https://example.com'},
+                            'childFrames': [
+                                {
+                                    'frame': {'id': 'target-frame', 'url': 'https://other.com'},
+                                    'childFrames': [],
+                                }
+                            ],
+                        }
+                    }
+                }
+            if method == 'DOM.getFrameOwner':
+                frame_id = command['params']['frameId']
+                if frame_id == 'target-frame':
+                    return {'result': {'backendNodeId': 999}}  # Matches
+                return {'result': {'backendNodeId': 111}}  # Doesn't match
+            raise AssertionError(f'Unexpected method {method}')
+
+        mock_connection_handler.execute_command.side_effect = side_effect
+
+        frame_id, frame_url = await iframe_element._find_frame_by_owner(
+            mock_connection_handler, None, 999
+        )
+
+        assert frame_id == 'target-frame'
+        assert frame_url == 'https://other.com'
+
+    @pytest.mark.asyncio
+    async def test_find_frame_by_owner_not_found(self, iframe_element, mock_connection_handler):
+        """Test _find_frame_by_owner when no matching frame exists."""
+
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'Page.getFrameTree':
+                return {
+                    'result': {
+                        'frameTree': {
+                            'frame': {'id': 'main', 'url': 'https://example.com'},
+                            'childFrames': [
+                                {
+                                    'frame': {'id': 'frame-1', 'url': 'https://other.com'},
+                                    'childFrames': [],
+                                }
+                            ],
+                        }
+                    }
+                }
+            if method == 'DOM.getFrameOwner':
+                return {'result': {'backendNodeId': 111}}  # Never matches
+            raise AssertionError(f'Unexpected method {method}')
+
+        mock_connection_handler.execute_command.side_effect = side_effect
+
+        frame_id, frame_url = await iframe_element._find_frame_by_owner(
+            mock_connection_handler, None, 999
+        )
+
+        assert frame_id is None
+        assert frame_url is None
+
+    @pytest.mark.asyncio
+    async def test_find_frame_by_owner_skips_frames_without_id(
+        self, iframe_element, mock_connection_handler
+    ):
+        """Test _find_frame_by_owner skips frames without ID."""
+
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'Page.getFrameTree':
+                return {
+                    'result': {
+                        'frameTree': {
+                            'frame': {'url': 'https://example.com'},  # Missing 'id'
+                            'childFrames': [
+                                {
+                                    'frame': {'id': '', 'url': 'https://other.com'},  # Empty ID
+                                    'childFrames': [],
+                                },
+                                {
+                                    'frame': {'id': 'valid-frame', 'url': 'https://valid.com'},
+                                    'childFrames': [],
+                                },
+                            ],
+                        }
+                    }
+                }
+            if method == 'DOM.getFrameOwner':
+                return {'result': {'backendNodeId': 999}}
+            raise AssertionError(f'Unexpected method {method}')
+
+        mock_connection_handler.execute_command.side_effect = side_effect
+
+        frame_id, frame_url = await iframe_element._find_frame_by_owner(
+            mock_connection_handler, None, 999
+        )
+
+        # Should find the valid frame
+        assert frame_id == 'valid-frame'
+        assert frame_url == 'https://valid.com'
+
+
+class TestFindChildByParent:
+    """Test _find_child_by_parent static method."""
+
+    def test_find_child_by_parent_direct_child(self):
+        """Test finding direct child by parent ID."""
+        frame_tree = {
+            'frame': {'id': 'main', 'url': 'https://example.com'},
+            'childFrames': [
+                {
+                    'frame': {'id': 'child-1', 'parentId': 'main', 'url': 'https://child1.com'},
+                    'childFrames': [],
+                },
+                {
+                    'frame': {'id': 'child-2', 'parentId': 'main', 'url': 'https://child2.com'},
+                    'childFrames': [],
+                },
+            ],
+        }
+
+        child_id = WebElement._find_child_by_parent(frame_tree, 'main')
+
+        # Should find first matching child
+        assert child_id == 'child-1'
+
+    def test_find_child_by_parent_nested_child(self):
+        """Test finding nested child by parent ID."""
+        frame_tree = {
+            'frame': {'id': 'main', 'url': 'https://example.com'},
+            'childFrames': [
+                {
+                    'frame': {'id': 'child-1', 'parentId': 'main', 'url': 'https://child1.com'},
+                    'childFrames': [
+                        {
+                            'frame': {
+                                'id': 'nested',
+                                'parentId': 'child-1',
+                                'url': 'https://nested.com',
+                            },
+                            'childFrames': [],
+                        }
+                    ],
+                }
+            ],
+        }
+
+        nested_id = WebElement._find_child_by_parent(frame_tree, 'child-1')
+
+        assert nested_id == 'nested'
+
+    def test_find_child_by_parent_not_found(self):
+        """Test when no child matches parent ID."""
+        frame_tree = {
+            'frame': {'id': 'main', 'url': 'https://example.com'},
+            'childFrames': [
+                {
+                    'frame': {'id': 'child-1', 'parentId': 'other', 'url': 'https://child1.com'},
+                    'childFrames': [],
+                }
+            ],
+        }
+
+        child_id = WebElement._find_child_by_parent(frame_tree, 'nonexistent')
+
+        assert child_id is None
+
+    def test_find_child_by_parent_empty_tree(self):
+        """Test with empty tree."""
+        child_id = WebElement._find_child_by_parent(None, 'any-id')
+        assert child_id is None
+
+        child_id = WebElement._find_child_by_parent({}, 'any-id')
+        assert child_id is None
+
+
+class TestResolveOOPIFByParent:
+    """Test _resolve_oopif_by_parent method."""
+
+    @pytest.mark.asyncio
+    async def test_resolve_oopif_direct_child_success(self, iframe_element):
+        """Test OOPIF resolution via direct child target."""
+        with patch('pydoll.elements.web_element.ConnectionHandler') as mock_handler_class:
+            browser_handler = AsyncMock()
+            browser_handler.execute_command = AsyncMock()
+            browser_handler._connection_port = 9222
+            mock_handler_class.return_value = browser_handler
+
+            async def side_effect(command, timeout=60):
+                method = command['method']
+                if method == 'Target.getTargets':
+                    return {
+                        'result': {
+                            'targetInfos': [
+                                {
+                                    'targetId': 'main-target',
+                                    'type': 'page',
+                                    'url': 'https://example.com',
+                                },
+                                {
+                                    'targetId': 'iframe-target',
+                                    'type': 'iframe',
+                                    'url': 'https://other-origin.com',
+                                    'parentFrameId': 'parent-frame-123',  # Matches
+                                },
+                            ]
+                        }
+                    }
+                if method == 'Target.attachToTarget':
+                    return {'result': {'sessionId': 'session-oopif-456'}}
+                if method == 'Page.getFrameTree':
+                    return {
+                        'result': {
+                            'frameTree': {
+                                'frame': {
+                                    'id': 'oopif-root-frame',
+                                    'url': 'https://other-origin.com',
+                                },
+                                'childFrames': [],
+                            }
+                        }
+                    }
+                raise AssertionError(f'Unexpected method {method}')
+
+            browser_handler.execute_command.side_effect = side_effect
+
+            handler, session_id, frame_id, url = await iframe_element._resolve_oopif_by_parent(
+                'parent-frame-123', 999
+            )
+
+            assert handler == browser_handler
+            assert session_id == 'session-oopif-456'
+            assert frame_id == 'oopif-root-frame'
+            assert url == 'https://other-origin.com'
+
+    @pytest.mark.asyncio
+    async def test_resolve_oopif_scan_all_targets_find_child(self, iframe_element):
+        """Test OOPIF resolution by scanning all targets and finding child."""
+        with patch('pydoll.elements.web_element.ConnectionHandler') as mock_handler_class:
+            browser_handler = AsyncMock()
+            browser_handler.execute_command = AsyncMock()
+            browser_handler._connection_port = 9222
+            mock_handler_class.return_value = browser_handler
+
+            call_count = 0
+
+            async def side_effect(command, timeout=60):
+                nonlocal call_count
+                method = command['method']
+
+                if method == 'Target.getTargets':
+                    return {
+                        'result': {
+                            'targetInfos': [
+                                {
+                                    'targetId': 'target-1',
+                                    'type': 'page',
+                                    'url': 'https://example.com',
+                                    # No parentFrameId - will trigger scan
+                                },
+                            ]
+                        }
+                    }
+                if method == 'Target.attachToTarget':
+                    call_count += 1
+                    return {'result': {'sessionId': f'session-{call_count}'}}
+                if method == 'Page.getFrameTree':
+                    # Return tree with child matching parent
+                    return {
+                        'result': {
+                            'frameTree': {
+                                'frame': {'id': 'root', 'url': 'https://example.com'},
+                                'childFrames': [
+                                    {
+                                        'frame': {
+                                            'id': 'matching-child',
+                                            'parentId': 'parent-frame-123',  # Matches
+                                            'url': 'https://child.com',
+                                        },
+                                        'childFrames': [],
+                                    }
+                                ],
+                            }
+                        }
+                    }
+                raise AssertionError(f'Unexpected method {method}')
+
+            browser_handler.execute_command.side_effect = side_effect
+
+            handler, session_id, frame_id, url = await iframe_element._resolve_oopif_by_parent(
+                'parent-frame-123', 999
+            )
+
+            assert handler == browser_handler
+            assert session_id == 'session-1'
+            assert frame_id == 'matching-child'
+            assert url is None  # URL not resolved in this path
+
+    @pytest.mark.asyncio
+    async def test_resolve_oopif_scan_all_targets_match_root_owner(self, iframe_element):
+        """Test OOPIF resolution by matching root frame owner."""
+        with patch('pydoll.elements.web_element.ConnectionHandler') as mock_handler_class:
+            browser_handler = AsyncMock()
+            browser_handler.execute_command = AsyncMock()
+            browser_handler._connection_port = 9222
+            mock_handler_class.return_value = browser_handler
+
+            call_count = 0
+
+            async def side_effect(command, timeout=60):
+                nonlocal call_count
+                method = command['method']
+
+                if method == 'Target.getTargets':
+                    return {
+                        'result': {
+                            'targetInfos': [
+                                {
+                                    'targetId': 'target-1',
+                                    'type': 'iframe',
+                                    'url': 'https://oopif.com',
+                                },
+                            ]
+                        }
+                    }
+                if method == 'Target.attachToTarget':
+                    call_count += 1
+                    return {'result': {'sessionId': f'session-{call_count}'}}
+                if method == 'Page.getFrameTree':
+                    return {
+                        'result': {
+                            'frameTree': {
+                                'frame': {
+                                    'id': 'oopif-root',
+                                    'url': 'https://oopif.com',
+                                },
+                                'childFrames': [],
+                            }
+                        }
+                    }
+                if method == 'DOM.getFrameOwner':
+                    # Return matching backend node ID
+                    return {'result': {'backendNodeId': 999}}  # Matches
+                raise AssertionError(f'Unexpected method {method}')
+
+            browser_handler.execute_command.side_effect = side_effect
+            # Mock também o _connection_handler do iframe_element para DOM.getFrameOwner
+            iframe_element._connection_handler.execute_command.side_effect = side_effect
+
+            handler, session_id, frame_id, url = await iframe_element._resolve_oopif_by_parent(
+                'parent-frame-123', 999
+            )
+
+            assert handler == browser_handler
+            assert session_id == 'session-1'
+            assert frame_id == 'oopif-root'
+            assert url is None
+
+    @pytest.mark.asyncio
+    async def test_resolve_oopif_not_found(self, iframe_element):
+        """Test OOPIF resolution when no matching target found."""
+        with patch('pydoll.elements.web_element.ConnectionHandler') as mock_handler_class:
+            browser_handler = AsyncMock()
+            browser_handler.execute_command = AsyncMock()
+            browser_handler._connection_port = 9222
+            mock_handler_class.return_value = browser_handler
+
+            async def side_effect(command, timeout=60):
+                method = command['method']
+                if method == 'Target.getTargets':
+                    return {'result': {'targetInfos': []}}  # No targets
+                raise AssertionError(f'Unexpected method {method}')
+
+            browser_handler.execute_command.side_effect = side_effect
+
+            handler, session_id, frame_id, url = await iframe_element._resolve_oopif_by_parent(
+                'parent-frame-123', 999
+            )
+
+            assert handler is None
+            assert session_id is None
+            assert frame_id is None
+            assert url is None
+
+
+class TestResolveFrameByOwner:
+    """Test _resolve_frame_by_owner method."""
+
+    @pytest.mark.asyncio
+    async def test_resolve_frame_by_owner_success(self, iframe_element, mock_connection_handler):
+        """Test successful frame resolution by owner."""
+
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'Page.getFrameTree':
+                return {
+                    'result': {
+                        'frameTree': {
+                            'frame': {'id': 'main', 'url': 'https://example.com'},
+                            'childFrames': [
+                                {
+                                    'frame': {'id': 'target', 'url': 'https://resolved.com'},
+                                    'childFrames': [],
+                                }
+                            ],
+                        }
+                    }
+                }
+            if method == 'DOM.getFrameOwner':
+                if command['params']['frameId'] == 'target':
+                    return {'result': {'backendNodeId': 456}}
+                return {'result': {'backendNodeId': 999}}
+            raise AssertionError(f'Unexpected method {method}')
+
+        mock_connection_handler.execute_command.side_effect = side_effect
+
+        frame_id, doc_url = await iframe_element._resolve_frame_by_owner(
+            mock_connection_handler, None, 456, 'https://fallback.com'
+        )
+
+        assert frame_id == 'target'
+        assert doc_url == 'https://resolved.com'
+
+    @pytest.mark.asyncio
+    async def test_resolve_frame_by_owner_not_found_returns_fallback(
+        self, iframe_element, mock_connection_handler
+    ):
+        """Test frame resolution returns fallback URL when not found."""
+
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'Page.getFrameTree':
+                return {
+                    'result': {
+                        'frameTree': {
+                            'frame': {'id': 'main', 'url': 'https://example.com'},
+                            'childFrames': [],
+                        }
+                    }
+                }
+            if method == 'DOM.getFrameOwner':
+                # Return non-matching backend node ID
+                return {'result': {'backendNodeId': 999}}
+            raise AssertionError(f'Unexpected method {method}')
+
+        mock_connection_handler.execute_command.side_effect = side_effect
+
+        frame_id, doc_url = await iframe_element._resolve_frame_by_owner(
+            mock_connection_handler, None, 456, 'https://fallback.com'
+        )
+
+        assert frame_id is None
+        assert doc_url == 'https://fallback.com'  # Falls back to provided URL
+
+
+class TestResolveOOPIFIfNeeded:
+    """Test _resolve_oopif_if_needed method."""
+
+    @pytest.mark.asyncio
+    async def test_resolve_oopif_if_needed_already_has_frame_id(self, iframe_element):
+        """Test OOPIF resolution skipped when frame_id already exists."""
+        handler, session_id, frame_id, url = await iframe_element._resolve_oopif_if_needed(
+            'existing-frame-id', 'parent-frame', 999, 'https://example.com'
+        )
+
+        # Should return early without resolution
+        assert handler is None
+        assert session_id is None
+        assert frame_id == 'existing-frame-id'
+        assert url == 'https://example.com'
+
+    @pytest.mark.asyncio
+    async def test_resolve_oopif_if_needed_no_parent_frame_id(self, iframe_element):
+        """Test OOPIF resolution skipped when no parent frame ID."""
+        handler, session_id, frame_id, url = await iframe_element._resolve_oopif_if_needed(
+            None, None, 999, 'https://example.com'
+        )
+
+        # Should return early without resolution
+        assert handler is None
+        assert session_id is None
+        assert frame_id is None
+        assert url == 'https://example.com'
+
+    @pytest.mark.asyncio
+    async def test_resolve_oopif_if_needed_triggers_resolution(self, iframe_element):
+        """Test OOPIF resolution is triggered when frame_id missing but parent exists."""
+        with patch.object(
+            iframe_element, '_resolve_oopif_by_parent', new=AsyncMock()
+        ) as mock_resolve:
+            mock_resolve.return_value = (
+                'mock-handler',
+                'mock-session',
+                'resolved-frame',
+                'https://resolved.com',
+            )
+
+            handler, session_id, frame_id, url = await iframe_element._resolve_oopif_if_needed(
+                None,  # No frame_id
+                'parent-frame-123',  # Has parent
+                999,
+                'https://original.com',
+            )
+
+            # Should call resolution
+            mock_resolve.assert_called_once_with('parent-frame-123', 999)
+            assert handler == 'mock-handler'
+            assert session_id == 'mock-session'
+            assert frame_id == 'resolved-frame'
+            assert url == 'https://resolved.com'
+
+
+class TestInitIframeContext:
+    """Test _init_iframe_context method."""
+
+    def test_init_iframe_context_basic(self, iframe_element):
+        """Test basic iframe context initialization."""
+        iframe_element._init_iframe_context(
+            'frame-123', 'https://example.com', None, None
+        )
+
+        assert iframe_element._iframe_context is not None
+        assert iframe_element._iframe_context.frame_id == 'frame-123'
+        assert iframe_element._iframe_context.document_url == 'https://example.com'
+        assert iframe_element._iframe_context.session_handler is None
+        assert iframe_element._iframe_context.session_id is None
+
+    def test_init_iframe_context_with_oopif_routing(self, iframe_element):
+        """Test iframe context initialization with OOPIF routing."""
+        mock_handler = AsyncMock()
+
+        iframe_element._init_iframe_context(
+            'frame-456', 'https://oopif.com', mock_handler, 'session-789'
+        )
+
+        assert iframe_element._iframe_context is not None
+        assert iframe_element._iframe_context.frame_id == 'frame-456'
+        assert iframe_element._iframe_context.session_handler == mock_handler
+        assert iframe_element._iframe_context.session_id == 'session-789'
+
+    def test_init_iframe_context_cleans_routing_attributes(self, iframe_element):
+        """Test iframe context init removes routing attributes."""
+        # Set routing attributes
+        iframe_element._routing_session_handler = AsyncMock()
+        iframe_element._routing_session_id = 'old-session'
+
+        iframe_element._init_iframe_context(
+            'frame-new', 'https://example.com', None, None
+        )
+
+        # Routing attributes should be removed
+        assert not hasattr(iframe_element, '_routing_session_handler')
+        assert not hasattr(iframe_element, '_routing_session_id')
+
+
+class TestCreateIsolatedWorldForFrame:
+    """Test _create_isolated_world_for_frame method."""
+
+    @pytest.mark.asyncio
+    async def test_create_isolated_world_without_session_id(self, mock_connection_handler):
+        """Test isolated world creation without session_id."""
+        mock_connection_handler.execute_command.return_value = {
+            'result': {'executionContextId': 42}
+        }
+
+        context_id = await WebElement._create_isolated_world_for_frame(
+            'frame-123', mock_connection_handler, None
+        )
+
+        assert context_id == 42
+        call_args = mock_connection_handler.execute_command.call_args[0][0]
+        assert 'sessionId' not in call_args
+        assert call_args['params']['frameId'] == 'frame-123'
+        assert 'pydoll::iframe::frame-123' in call_args['params']['worldName']
+
+    @pytest.mark.asyncio
+    async def test_create_isolated_world_with_session_id(self, mock_connection_handler):
+        """Test isolated world creation WITH session_id (coverage for line 1040)."""
+        mock_connection_handler.execute_command.return_value = {
+            'result': {'executionContextId': 99}
+        }
+
+        context_id = await WebElement._create_isolated_world_for_frame(
+            'frame-456', mock_connection_handler, 'session-abc-789'
+        )
+
+        assert context_id == 99
+        call_args = mock_connection_handler.execute_command.call_args[0][0]
+        assert call_args['sessionId'] == 'session-abc-789'
+        assert call_args['params']['frameId'] == 'frame-456'
+
+    @pytest.mark.asyncio
+    async def test_create_isolated_world_missing_execution_context_id(
+        self, mock_connection_handler
+    ):
+        """Test isolated world creation failure (no executionContextId)."""
+        mock_connection_handler.execute_command.return_value = {
+            'result': {}  # Missing executionContextId
+        }
+
+        with pytest.raises(
+            InvalidIFrame, match='Unable to create isolated world for iframe'
+        ):
+            await WebElement._create_isolated_world_for_frame(
+                'frame-fail', mock_connection_handler, None
+            )
+
+
+class TestSetIframeDocumentObjectId:
+    """Test _set_iframe_document_object_id method."""
+
+    @pytest.mark.asyncio
+    async def test_set_iframe_document_object_id_with_session_id(self, iframe_element):
+        """Test document object ID setting with session_id (coverage for line 1062)."""
+        # Set up iframe context with session_id
+        mock_session_handler = AsyncMock()
+        iframe_element._iframe_context = _IFrameContext(
+            frame_id='frame-123',
+            execution_context_id=42,
+            session_handler=mock_session_handler,
+            session_id='session-abc',
+        )
+
+        mock_session_handler.execute_command.return_value = {
+            'result': {
+                'result': {
+                    'type': 'object',
+                    'objectId': 'doc-object-123',
+                }
+            }
+        }
+
+        await iframe_element._set_iframe_document_object_id(42)
+
+        # Should use session_handler and add sessionId to command
+        mock_session_handler.execute_command.assert_called_once()
+        call_args = mock_session_handler.execute_command.call_args[0][0]
+        assert call_args['sessionId'] == 'session-abc'
+        assert call_args['params']['expression'] == 'document.documentElement'
+        assert call_args['params']['contextId'] == 42
+
+        # Should set document_object_id
+        assert iframe_element._iframe_context.document_object_id == 'doc-object-123'
+
+    @pytest.mark.asyncio
+    async def test_set_iframe_document_object_id_without_session_id(
+        self, iframe_element, mock_connection_handler
+    ):
+        """Test document object ID setting without session_id."""
+        # Set up iframe context without session_id
+        iframe_element._iframe_context = _IFrameContext(
+            frame_id='frame-456',
+            execution_context_id=77,
+        )
+
+        mock_connection_handler.execute_command.return_value = {
+            'result': {
+                'result': {
+                    'type': 'object',
+                    'objectId': 'doc-object-456',
+                }
+            }
+        }
+
+        await iframe_element._set_iframe_document_object_id(77)
+
+        # Should use main connection_handler
+        mock_connection_handler.execute_command.assert_called_once()
+        call_args = mock_connection_handler.execute_command.call_args[0][0]
+        assert 'sessionId' not in call_args
+        assert iframe_element._iframe_context.document_object_id == 'doc-object-456'
+
+    @pytest.mark.asyncio
+    async def test_set_iframe_document_object_id_missing_object_id(
+        self, iframe_element, mock_connection_handler
+    ):
+        """Test document object ID setting failure (no objectId)."""
+        iframe_element._iframe_context = _IFrameContext(
+            frame_id='frame-fail',
+            execution_context_id=99,
+        )
+
+        mock_connection_handler.execute_command.return_value = {
+            'result': {'result': {}}  # Missing objectId
+        }
+
+        with pytest.raises(
+            InvalidIFrame, match='Unable to obtain document reference for iframe'
+        ):
+            await iframe_element._set_iframe_document_object_id(99)
+
+
+class TestEnsureIframeContext:
+    """Test _ensure_iframe_context method."""
+
+    @pytest.mark.asyncio
+    async def test_ensure_iframe_context_fails_without_frame_id(
+        self, iframe_element, mock_connection_handler
+    ):
+        """Test _ensure_iframe_context raises error when frame_id cannot be resolved."""
+        from unittest.mock import AsyncMock, patch
+
+        # Create a mock browser_handler
+        mock_browser_handler = AsyncMock()
+        mock_browser_handler._connection_port = 9222
+
+        async def side_effect(command, timeout=60):
+            method = command['method']
+            if method == 'DOM.describeNode':
+                # Return node info without frame_id and with backend_node_id
+                return {
+                    'result': {
+                        'node': {
+                            'frameId': 'parent-frame',
+                            'backendNodeId': 789,
+                            'contentDocument': {},  # No frameId here
+                        }
+                    }
+                }
+            if method == 'Page.getFrameTree':
+                # Return empty tree (no frames to match)
+                return {
+                    'result': {
+                        'frameTree': {
+                            'frame': {'id': 'main', 'url': 'https://example.com'},
+                            'childFrames': [],
+                        }
+                    }
+                }
+            if method == 'DOM.getFrameOwner':
+                # Return non-matching backend node ID so frame resolution fails
+                return {'result': {'backendNodeId': 999}}
+            if method == 'Target.getTargets':
+                # Return empty targets list so OOPIF resolution fails
+                return {'result': {'targetInfos': []}}
+            raise AssertionError(f'Unexpected method {method}')
+
+        mock_connection_handler.execute_command.side_effect = side_effect
+        mock_browser_handler.execute_command.side_effect = side_effect
+
+        # Mock ConnectionHandler instantiation to return our mock
+        with patch(
+            'pydoll.elements.web_element.ConnectionHandler',
+            return_value=mock_browser_handler,
+        ):
+            # Should raise InvalidIFrame when frame_id cannot be resolved
+            with pytest.raises(
+                InvalidIFrame, match='Unable to resolve frameId for the iframe element'
+            ):
+                await iframe_element._ensure_iframe_context()
+