From 62d8bf7b0acb9f6606c144e72e4fec14acb11ef4 Mon Sep 17 00:00:00 2001
From: Scott Taylor <scott.taylor@shopify.com>
Date: Fri, 8 May 2026 17:05:43 -0400
Subject: [PATCH 1/3] Add LP.setSubframeLoading CDP method to skip iframe
 loading

Adds a Lightpanda-specific CDP method that lets drivers opt out of
subframe processing entirely:

  await client.send('LP.setSubframeLoading', { enabled: false });

When disabled, the HTML parser silently bypasses every <iframe> it
encounters: no child Frame is created, no document fetch is issued,
and no Page.frameAttached / Page.frameNavigated /
Runtime.executionContextCreated events are emitted. The driver only
sees the main frame's lifecycle.

Motivation: pages that load large numbers of analytics / pixel
iframes (Shopify storefronts, ad-heavy news sites) trigger #2400
\u2014 each subframe navigation re-registers the main frame's V8 context
under the child's frameId and invalidates the executionContextId the
driver had pinned for the main frame. Subsequent Runtime.evaluate
fails with 'Cannot find context with specified id' (Playwright
surfaces this as 'Execution context was destroyed', Puppeteer hangs
in IsolatedWorld.evaluate waiting for a 'context' event). The proper
fix is per-frame V8 inspector context groups (or per-frame
IsolatedWorld), discussed in #2400; this method gives drivers a
clean opt-in workaround in the meantime.

Mechanism: new bool field Session.subframe_loading_enabled (default
true). Frame.iframeAddedCallback short-circuits when false, marking
the iframe as _executed so the parser doesn't re-deliver it.

Verified against the puppeteer-core repro on
https://www.allbirds.com/products/mens-wool-runners (which
instantiates ~11 web-pixel iframes during initial render):

  baseline (subframe loading ON):
    page.title()  works (lucky timing) but server segfaults on
                  disconnect from the worker re-entrancy bug; iframes
                  do load and trigger the executionContextId churn

  with LP.setSubframeLoading(false):
    [opt-out] LP.setSubframeLoading reply: {}
    [ok] goto status=200 elapsed=6166ms
    [stats] frame_attached_events_seen=0
    [ok] page.title() = "Allbirds Wool Runners, Men's | ..."
    [ok] evaluate(1+1) = 2
    [ok] evaluate(document.title) = "Allbirds Wool Runners, Men's | ..."
    [ok] body.innerHTML.length = 923161

521/521 unit tests still pass.
---
 src/browser/Frame.zig   |  9 +++++++++
 src/browser/Session.zig | 11 +++++++++++
 src/cdp/domains/lp.zig  | 27 +++++++++++++++++++++++++++
 3 files changed, 47 insertions(+)

diff --git a/src/browser/Frame.zig b/src/browser/Frame.zig
index 4b5c60c9c..79b70d882 100644
--- a/src/browser/Frame.zig
+++ b/src/browser/Frame.zig
@@ -1276,6 +1276,15 @@ pub fn iframeAddedCallback(self: *Frame, iframe: *IFrame) !void {
     if (iframe._executed) {
         return;
     }
+    if (!self._session.subframe_loading_enabled) {
+        // The CDP driver opted out of subframe loading via
+        // LP.setSubframeLoading. Mark the iframe as "executed" so the
+        // parser doesn't keep handing it back to us, but skip the child
+        // frame creation / navigation / notification entirely — no child
+        // Frame, no Page.frameAttached, no Runtime.executionContextCreated.
+        iframe._executed = true;
+        return;
+    }
 
     var src = iframe.asElement().getAttributeSafe(comptime .wrap("src")) orelse "";
     if (src.len == 0) {
diff --git a/src/browser/Session.zig b/src/browser/Session.zig
index e8f80e387..09e4716a2 100644
--- a/src/browser/Session.zig
+++ b/src/browser/Session.zig
@@ -76,6 +76,17 @@ _pending: ?*Page = null,
 frame_id_gen: u32 = 0,
 loader_id_gen: u32 = 0,
 
+// When false, the HTML parser silently skips loading <iframe> elements
+// (no child frame is created, no document fetch, no Page.frameAttached /
+// Page.frameNavigated / Runtime.executionContextCreated events emitted).
+// Lets CDP drivers opt out of subframe processing for pages that load
+// large numbers of analytics / pixel iframes — useful as a workaround
+// for #2400 (child-iframe navigation churns the main frame's
+// executionContextId because IsolatedWorld is shared and CONTEXT_GROUP_ID
+// is per-BrowserContext rather than per-frame). Toggled via
+// LP.setSubframeLoading from CDP.
+subframe_loading_enabled: bool = true,
+
 pub fn init(self: *Session, browser: *Browser, notification: *Notification) !void {
     const allocator = browser.app.allocator;
     const arena_pool = browser.arena_pool;
diff --git a/src/cdp/domains/lp.zig b/src/cdp/domains/lp.zig
index 2b042c991..b3666a67b 100644
--- a/src/cdp/domains/lp.zig
+++ b/src/cdp/domains/lp.zig
@@ -42,6 +42,7 @@ pub fn processMessage(cmd: *CDP.Command) !void {
         scrollNode,
         waitForSelector,
         handleJavaScriptDialog,
+        setSubframeLoading,
     }, cmd.input.action) orelse return error.UnknownMethod;
 
     switch (action) {
@@ -56,9 +57,35 @@ pub fn processMessage(cmd: *CDP.Command) !void {
         .scrollNode => return scrollNode(cmd),
         .waitForSelector => return waitForSelector(cmd),
         .handleJavaScriptDialog => return handleJavaScriptDialog(cmd),
+        .setSubframeLoading => return setSubframeLoading(cmd),
     }
 }
 
+// LP.setSubframeLoading { enabled: bool }
+//
+// When called with enabled=false, the HTML parser silently skips loading
+// <iframe> elements: no child Frame is created, no document fetch, and
+// no Page.frameAttached / Page.frameNavigated / Runtime.executionContextCreated
+// events are emitted for the would-be subframe. Useful as an opt-in
+// workaround for pages that load large numbers of analytics / pixel
+// iframes (e.g. shopify storefronts) where each subframe navigation
+// re-registers the main frame's V8 contexts under the child's frameId
+// and invalidates the driver's cached executionContextIds (#2400).
+//
+// Default: enabled=true (current behaviour). Setting enabled=true again
+// re-enables loading for any iframes added to the DOM after the call;
+// already-skipped iframes stay skipped (the parser marks them as
+// _executed when bypassed).
+fn setSubframeLoading(cmd: *CDP.Command) !void {
+    const params = (try cmd.params(struct {
+        enabled: bool,
+    })) orelse return error.InvalidParams;
+
+    const bc = cmd.browser_context orelse return error.NoBrowserContext;
+    bc.session.subframe_loading_enabled = params.enabled;
+    return cmd.sendResult(null, .{});
+}
+
 fn getSemanticTree(cmd: anytype) !void {
     const Params = struct {
         format: ?enum { text } = null,

From b272b0e33c5c6f34f227a6b120b133a35360f561 Mon Sep 17 00:00:00 2001
From: Scott Taylor <scott.taylor@shopify.com>
Date: Fri, 8 May 2026 17:12:54 -0400
Subject: [PATCH 2/3] Add --disable-subframes CLI flag

Complementary to LP.setSubframeLoading (preceding commit): exposes
the same iframe-skip behavior as a CLI option that applies to all
sessions in the process. Useful for:

  * the 'fetch' subcommand (no CDP driver to call LP.setSubframeLoading)
  * 'serve' deployments where the operator wants iframes off by
    default for every connecting client (the LP method can still
    re-enable per-session if needed)
  * Playwright's chromium.connectOverCDP, which can't reliably issue
    custom CDP methods on Lightpanda today: BrowserContext.newCDPSession
    and Browser.newBrowserCDPSession both attach a new CRSession that
    collides with the STARTUP-session reuse from #2399, triggering a
    Playwright internal assertion. With --disable-subframes set on the
    server, Playwright doesn't need to issue any custom CDP \u2014 every
    session inherits subframes-off and the executionContextId churn
    from #2400 never trips.

Verified:

  serve --disable-subframes + plain puppeteer-core goto
    [ok] goto status=200 elapsed=6354ms frameAttached=0

  fetch --disable-subframes --dump html https://www.allbirds.com/...
    exit=0
    html bytes: 1021562
    title: <title>Allbirds Wool Runners, Men's | ...</title>
    iframe count in dumped html: 2  (still in DOM, just not loaded)

521/521 unit tests pass.
---
 src/Config.zig          | 26 ++++++++++++++++++++++++++
 src/browser/Session.zig |  2 ++
 2 files changed, 28 insertions(+)

diff --git a/src/Config.zig b/src/Config.zig
index 8ce27f1d4..3bf453422 100644
--- a/src/Config.zig
+++ b/src/Config.zig
@@ -98,6 +98,7 @@ const CommonOptions = .{
     .{ .name = "cookie_jar", .type = ?[]const u8 },
     .{ .name = "storage_engine", .type = ?Storage.EngineType },
     .{ .name = "storage_sqlite_path", .type = ?[:0]const u8 },
+    .{ .name = "disable_subframes", .type = bool },
 };
 
 fn dumpValidator(_: Allocator, args: *std.process.ArgIterator) !?DumpFormat {
@@ -213,6 +214,20 @@ pub fn obeyRobots(self: *const Config) bool {
     };
 }
 
+// When true, the HTML parser silently skips loading <iframe> elements:
+// no child frame is created, no document fetch, no Page.frameAttached /
+// Page.frameNavigated / Runtime.executionContextCreated events emitted.
+// Useful for pages that load large numbers of analytics / pixel iframes
+// where each subframe navigation invalidates the driver's cached
+// executionContextIds (#2400). The CDP method LP.setSubframeLoading
+// can override this at runtime per-session.
+pub fn disableSubframes(self: *const Config) bool {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.disable_subframes,
+        else => false,
+    };
+}
+
 pub fn httpProxy(self: *const Config) ?[:0]const u8 {
     return switch (self.mode) {
         inline .serve, .fetch, .mcp => |opts| opts.http_proxy,
@@ -500,6 +515,17 @@ pub fn printUsageAndExit(self: *const Config, success: bool) void {
         \\                we make requests towards.
         \\                Defaults to false.
         \\
+        \\--disable-subframes
+        \\                Skip loading <iframe> elements. The HTML parser registers them
+        \\                in the DOM but no child frame, document fetch, or
+        \\                Page.frameAttached / Runtime.executionContextCreated events are
+        \\                produced. Useful for pages that load many analytics / pixel
+        \\                iframes where each subframe navigation invalidates driver-side
+        \\                executionContextIds (lightpanda-io/browser#2400). On the CDP
+        \\                serve path, drivers can also toggle this per-session via the
+        \\                LP.setSubframeLoading method.
+        \\                Defaults to false.
+        \\
         \\--block-private-networks
         \\                Blocks HTTP requests to private/internal IP addresses
         \\                after DNS resolution. Useful for sandboxing, multi-tenant
diff --git a/src/browser/Session.zig b/src/browser/Session.zig
index 09e4716a2..eb0a8b79b 100644
--- a/src/browser/Session.zig
+++ b/src/browser/Session.zig
@@ -105,6 +105,8 @@ pub fn init(self: *Session, browser: *Browser, notification: *Notification) !voi
         .notification = notification,
         .fc_identity_pool = .init(allocator),
         .cookie_jar = storage.Cookie.Jar.init(allocator),
+        // CLI default; LP.setSubframeLoading can flip this per-session.
+        .subframe_loading_enabled = !browser.app.config.disableSubframes(),
     };
 }
 

From cdfabf7953c1ac1f3f12b70dea8482c836833a69 Mon Sep 17 00:00:00 2001
From: Karl Seguin <k@openmymind.io>
Date: Tue, 12 May 2026 12:56:33 +0800
Subject: [PATCH 3/3] Minor tweaks

Remove repeating description/comment of flag.

Change CDP lp command to be a general configuration endpoint.
---
 src/Config.zig          | 11 ++---------
 src/browser/Frame.zig   |  6 +-----
 src/browser/Session.zig | 12 ++----------
 src/cdp/domains/lp.zig  | 25 +++++--------------------
 4 files changed, 10 insertions(+), 44 deletions(-)

diff --git a/src/Config.zig b/src/Config.zig
index 3bf453422..df6d44f92 100644
--- a/src/Config.zig
+++ b/src/Config.zig
@@ -214,17 +214,10 @@ pub fn obeyRobots(self: *const Config) bool {
     };
 }
 
-// When true, the HTML parser silently skips loading <iframe> elements:
-// no child frame is created, no document fetch, no Page.frameAttached /
-// Page.frameNavigated / Runtime.executionContextCreated events emitted.
-// Useful for pages that load large numbers of analytics / pixel iframes
-// where each subframe navigation invalidates the driver's cached
-// executionContextIds (#2400). The CDP method LP.setSubframeLoading
-// can override this at runtime per-session.
 pub fn disableSubframes(self: *const Config) bool {
     return switch (self.mode) {
         inline .serve, .fetch, .mcp => |opts| opts.disable_subframes,
-        else => false,
+        else => unreachable,
     };
 }
 
@@ -523,7 +516,7 @@ pub fn printUsageAndExit(self: *const Config, success: bool) void {
         \\                iframes where each subframe navigation invalidates driver-side
         \\                executionContextIds (lightpanda-io/browser#2400). On the CDP
         \\                serve path, drivers can also toggle this per-session via the
-        \\                LP.setSubframeLoading method.
+        \\                LP.configureLoading method.
         \\                Defaults to false.
         \\
         \\--block-private-networks
diff --git a/src/browser/Frame.zig b/src/browser/Frame.zig
index 79b70d882..0628eaa20 100644
--- a/src/browser/Frame.zig
+++ b/src/browser/Frame.zig
@@ -1277,11 +1277,7 @@ pub fn iframeAddedCallback(self: *Frame, iframe: *IFrame) !void {
         return;
     }
     if (!self._session.subframe_loading_enabled) {
-        // The CDP driver opted out of subframe loading via
-        // LP.setSubframeLoading. Mark the iframe as "executed" so the
-        // parser doesn't keep handing it back to us, but skip the child
-        // frame creation / navigation / notification entirely — no child
-        // Frame, no Page.frameAttached, no Runtime.executionContextCreated.
+        // configured not to load frames
         iframe._executed = true;
         return;
     }
diff --git a/src/browser/Session.zig b/src/browser/Session.zig
index eb0a8b79b..1349ae1ea 100644
--- a/src/browser/Session.zig
+++ b/src/browser/Session.zig
@@ -76,15 +76,7 @@ _pending: ?*Page = null,
 frame_id_gen: u32 = 0,
 loader_id_gen: u32 = 0,
 
-// When false, the HTML parser silently skips loading <iframe> elements
-// (no child frame is created, no document fetch, no Page.frameAttached /
-// Page.frameNavigated / Runtime.executionContextCreated events emitted).
-// Lets CDP drivers opt out of subframe processing for pages that load
-// large numbers of analytics / pixel iframes — useful as a workaround
-// for #2400 (child-iframe navigation churns the main frame's
-// executionContextId because IsolatedWorld is shared and CONTEXT_GROUP_ID
-// is per-BrowserContext rather than per-frame). Toggled via
-// LP.setSubframeLoading from CDP.
+// configuration (or CDP command) to disable iframe loading
 subframe_loading_enabled: bool = true,
 
 pub fn init(self: *Session, browser: *Browser, notification: *Notification) !void {
@@ -105,7 +97,7 @@ pub fn init(self: *Session, browser: *Browser, notification: *Notification) !voi
         .notification = notification,
         .fc_identity_pool = .init(allocator),
         .cookie_jar = storage.Cookie.Jar.init(allocator),
-        // CLI default; LP.setSubframeLoading can flip this per-session.
+        // CLI default; LP.configureLoading can flip this per-session.
         .subframe_loading_enabled = !browser.app.config.disableSubframes(),
     };
 }
diff --git a/src/cdp/domains/lp.zig b/src/cdp/domains/lp.zig
index b3666a67b..471c984c7 100644
--- a/src/cdp/domains/lp.zig
+++ b/src/cdp/domains/lp.zig
@@ -42,7 +42,7 @@ pub fn processMessage(cmd: *CDP.Command) !void {
         scrollNode,
         waitForSelector,
         handleJavaScriptDialog,
-        setSubframeLoading,
+        configureLoading,
     }, cmd.input.action) orelse return error.UnknownMethod;
 
     switch (action) {
@@ -57,32 +57,17 @@ pub fn processMessage(cmd: *CDP.Command) !void {
         .scrollNode => return scrollNode(cmd),
         .waitForSelector => return waitForSelector(cmd),
         .handleJavaScriptDialog => return handleJavaScriptDialog(cmd),
-        .setSubframeLoading => return setSubframeLoading(cmd),
+        .configureLoading => return configureLoading(cmd),
     }
 }
 
-// LP.setSubframeLoading { enabled: bool }
-//
-// When called with enabled=false, the HTML parser silently skips loading
-// <iframe> elements: no child Frame is created, no document fetch, and
-// no Page.frameAttached / Page.frameNavigated / Runtime.executionContextCreated
-// events are emitted for the would-be subframe. Useful as an opt-in
-// workaround for pages that load large numbers of analytics / pixel
-// iframes (e.g. shopify storefronts) where each subframe navigation
-// re-registers the main frame's V8 contexts under the child's frameId
-// and invalidates the driver's cached executionContextIds (#2400).
-//
-// Default: enabled=true (current behaviour). Setting enabled=true again
-// re-enables loading for any iframes added to the DOM after the call;
-// already-skipped iframes stay skipped (the parser marks them as
-// _executed when bypassed).
-fn setSubframeLoading(cmd: *CDP.Command) !void {
+fn configureLoading(cmd: *CDP.Command) !void {
     const params = (try cmd.params(struct {
-        enabled: bool,
+        subFrame: bool = true,
     })) orelse return error.InvalidParams;
 
     const bc = cmd.browser_context orelse return error.NoBrowserContext;
-    bc.session.subframe_loading_enabled = params.enabled;
+    bc.session.subframe_loading_enabled = params.subFrame;
     return cmd.sendResult(null, .{});
 }