iOS 26+ Support: Adapt to WebKit Site Isolation and Frame Target Architecture

[auchenberg]

Summary

iOS 26 introduces significant changes to WebKit's inspector protocol as part of Apple's Site Isolation initiative. This breaks inspection on iOS 26+ devices because Inspect expects the traditional Page target architecture, but WebKit is transitioning to a new Frame target model.

Symptoms

Users on iOS 26+ report:

• Page shows isDebuggable: true initially, then switches to isDebuggable: false upon connection
• Errors: 'CSS' domain was not found, 'Debugger' domain was not found, 'Runtime' domain was not found
• Device detection and tab listing work, but inspection fails
• Same device works fine with macOS Safari's Web Inspector

Related issues: #238

Root Cause

Apple is implementing Site Isolation in WebKit, which fundamentally restructures how frames and inspection targets work.

Key WebKit Commits

Date	Commit	Description
Sep 22, 2025	06f8ad1	"Introduce the Frame target type to prep for site isolation" (80+ files)
Jan 6, 2026	283db26	"Remote iframe still can't console log with frame target console support"

Architecture Change

Before (iOS ≤18):

Page Target
├── CSS Domain
├── DOM Domain
├── Debugger Domain
├── Runtime Domain
└── ... all domains

After (iOS 26+):

Page Target (may not exist for remote frames)
└── Target Domain (lifecycle only)

Frame Target(s)
├── CSS Domain
├── DOM Domain
├── Debugger Domain
├── Runtime Domain
└── ... domains migrating here

Why Inspect Breaks

1. Inspect connects expecting a Page target with all domains
2. iOS 26 may not expose a Page target, or the Page target no longer hosts the expected domains
3. Domains (CSS, DOM, Debugger, Runtime) are being migrated to Frame targets
4. When Inspect queries domains on the Page target, WebKit returns "domain was not found"

From WebKit's commit message:

"Frame targets initially have no domains but will gradually inherit or have domains moved from page targets"

And regarding remote frames:

"Remote web processes don't surface a page target to the frontend, so remote frame targets couldn't properly initialize"

Technical Investigation Needed

1. Understand the New Target Model

• Research what target types iOS 26 exposes (Page, Frame, Worker, etc.)
• Determine which domains live on which target types
• Understand Target.targetCreated / Target.targetDestroyed events for Frame targets
• Check if Target.attachToTarget is needed for Frame targets

2. Protocol Changes to Investigate

• Review changes to Target.json protocol file
• Check if targetInfo.type now includes "Frame"
• Understand FrameInspectorController vs PageInspectorController
• Research WebFrameInspectorTarget and WebFrameInspectorTargetProxy

3. Inspect Adaptor Changes Needed

• Support Frame target type in target discovery
• Route domain commands to correct target (Frame vs Page)
• Handle scenarios where Page target doesn't exist
• Update target-based communication to handle multiple Frame targets

Proposed Solution

Phase 1: Detection & Compatibility

• Detect iOS version and target architecture being used
• Log which targets and domains are available
• Graceful fallback when expected domains aren't on Page target

Phase 2: Frame Target Support

• Implement Frame target discovery and attachment
• Route CSS/DOM/Debugger commands to Frame targets when appropriate
• Handle Frame target lifecycle events

Phase 3: Full Site Isolation Support

• Support inspecting multiple Frame targets (cross-origin iframes)
• Handle Frame targets in separate processes
• Support the "no Page target" scenario for remote frames

References

• WebKit Site Isolation Documentation
• WebKit Inspector Protocol - Target.json
• Frame target commit
• Remote iframe console fix

Environment

• iOS Version: 26.0+
• Affected: All platforms (Windows, macOS, Linux)
• Works: macOS Safari Web Inspector (native tool)