CustomElement Reactions

While this PR touches a lot of files, and isn't trivial, many of the changes
are either:
1 - removing guards added in previous PRs, e.g.
    #1969
    #2172
    #2313
    #2366

2 - Adding the `.ce_reactions = true` flag to various WebAPIs

CustomElements have callbacks, e.g. connectedCallback. Also, many WebAPI calls
are implemented as a series of mutations, e.g. appendChild = remove from current
+ append to new.

These two things interact in an important way: when should callbacks execute?
Before this PR, we were invoking callbacks at each individual step. This is
(a) technically wrong and (b) breaks a lot of assumptions (the reason the above
4 PRs were needed to fix bugs).

This PR adds a `_ce_reactions` queue to the frame. And, instead of invoking
callbacks, we "enqueue" the reaction. At various boundaries, a scope is created
the DOM manipulation is done, and then we pop the scope, invoking all queued
reactions.

Author: karlseguin

src/browser/CustomElementReactions.zig

@@ -0,0 +1,129 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+// Implements the spec's "custom element reactions" mechanism: callbacks
+// (connectedCallback, disconnectedCallback, adoptedCallback,
+// attributeChangedCallback) are enqueued during DOM mutation and invoked at
+// the outer algorithm boundary, not synchronously mid-mutation.
+//
+// The "stack of element queues" is collapsed to a single flat ArrayList plus
+// per-scope checkpoint indices: push() captures items.len, popAndInvoke()
+// drains items[checkpoint..] and truncates. Nested scopes work naturally —
+// inside a callback, a new scope captures its own checkpoint past the current
+// length, drains its own range, and the outer iteration continues from where
+// it left off.
+
+const std = @import("std");
+const lp = @import("lightpanda");
+
+const Frame = @import("Frame.zig");
+const Element = @import("webapi/Element.zig");
+const Document = @import("webapi/Document.zig");
+const Custom = @import("webapi/element/html/Custom.zig");
+
+const String = lp.String;
+const Allocator = std.mem.Allocator;
+
+const Self = @This();
+
+allocator: Allocator,
+queue: std.ArrayList(Reaction) = .empty,
+// Number of currently-open scopes (push() that hasn't been pop'd). Every
+// enqueue must happen inside a scope — that's the leak-detection invariant.
+// Checked in debug at enqueue time so leaks surface where the bug is, not
+// later at some unrelated boundary.
+active_scopes: u32 = 0,
+
+/// Open a new reactions scope. Returns a checkpoint to be passed to popAndInvoke.
+pub fn push(self: *Self) usize {
+    self.active_scopes += 1;
+    return self.queue.items.len;
+}
+
+/// Drain reactions queued at indices >= checkpoint, then truncate. Reactions
+/// enqueued within a nested scope drain at that scope's pop, before this loop
+/// sees them.
+pub fn popAndInvoke(self: *Self, checkpoint: usize, frame: *Frame) void {
+    for (self.queue.items[checkpoint..]) |reaction| {
+        Custom.fireReaction(reaction, frame);
+    }
+    self.queue.items.len = checkpoint;
+    self.active_scopes -= 1;
+}
+
+inline fn assertScopeActive(self: *const Self) void {
+    lp.assert(self.active_scopes > 0, "ce_reactions enqueue without active scope", .{});
+}
+
+pub fn enqueueConnected(self: *Self, element: *Element) !void {
+    self.assertScopeActive();
+    try self.queue.append(self.allocator, .{ .connected = element });
+}
+
+pub fn enqueueDisconnected(self: *Self, element: *Element) !void {
+    self.assertScopeActive();
+    try self.queue.append(self.allocator, .{ .disconnected = element });
+}
+
+pub fn enqueueAdopted(self: *Self, element: *Element, old_document: *Document, new_document: *Document) !void {
+    self.assertScopeActive();
+    try self.queue.append(self.allocator, .{ .adopted = .{
+        .element = element,
+        .old_document = old_document,
+        .new_document = new_document,
+    } });
+}
+
+pub fn enqueueAttributeChanged(
+    self: *Self,
+    element: *Element,
+    name: String,
+    old_value: ?String,
+    new_value: ?String,
+    namespace: ?String,
+) !void {
+    self.assertScopeActive();
+    try self.queue.append(self.allocator, .{ .attribute_changed = .{
+        .name = name,
+        .element = element,
+        .old_value = old_value,
+        .new_value = new_value,
+        .namespace = namespace,
+    } });
+}
+
+pub const Reaction = union(enum) {
+    connected: *Element,
+    disconnected: *Element,
+    adopted: Adopted,
+    attribute_changed: AttributeChanged,
+
+    pub const Adopted = struct {
+        element: *Element,
+        old_document: *Document,
+        new_document: *Document,
+    };
+
+    pub const AttributeChanged = struct {
+        element: *Element,
+        name: String,
+        old_value: ?String,
+        new_value: ?String,
+        namespace: ?String,
+    };
+};

src/browser/Frame.zig

@@ -32,6 +32,8 @@ const StyleManager = @import("StyleManager.zig");
 const Parser = @import("parser/Parser.zig");
 const h5e = @import("parser/html5ever.zig");
 
+const CustomElementReactions = @import("CustomElementReactions.zig");
+
 const URL = @import("URL.zig");
 const Blob = @import("webapi/Blob.zig");
 const Node = @import("webapi/Node.zig");
@@ -188,6 +190,12 @@ _upgrading_element: ?*Node = null,
 // List of custom elements that were created before their definition was registered
 _undefined_custom_elements: std.ArrayList(*Element.Html.Custom) = .{},
 
+// Pending custom-element reactions (connected/disconnected/adopted/attribute
+// changed). Reactions are enqueued during DOM mutation and drained at the
+// outer algorithm boundary — set up by the JS bridge for [CEReactions]
+// methods and by the parser pump on each yield.
+_ce_reactions: CustomElementReactions,
+
 // for heap allocations and managing WebAPI objects
 _factory: *Factory,
 
@@ -287,6 +295,7 @@ pub fn init(self: *Frame, frame_id: u32, page: *Page, parent: ?*Frame) !void {
         ._type = if (parent == null) .root else .frame,
         ._style_manager = undefined,
         ._script_manager = undefined,
+        ._ce_reactions = .{ .allocator = arena },
         ._event_manager = EventManager.init(arena, self),
     };
     self._to_load = &self._to_load_1;
@@ -1852,7 +1861,7 @@ pub fn adoptNodeTree(self: *Frame, node: *Node, old_owner: *Document, new_owner:
 
     // Per spec, adopted steps run on each element after its document is set.
     if (node.is(Element)) |el| {
-        Element.Html.Custom.invokeAdoptedCallbackOnElement(el, old_owner, new_owner, self);
+        Element.Html.Custom.enqueueAdoptedCallbackOnElement(el, old_owner, new_owner, self);
     }
 
     var it = node.childrenIterator();
@@ -2588,7 +2597,7 @@ pub fn createElementNS(self: *Frame, namespace: Element.Namespace, name: []const
                 if (element._attributes) |attributes| {
                     var it = attributes.iterator();
                     while (it.next()) |attr| {
-                        Element.Html.Custom.invokeAttributeChangedCallbackOnElement(
+                        Element.Html.Custom.enqueueAttributeChangedCallbackOnElement(
                             element,
                             attr._name,
                             null, // old_value is null for initial attributes
@@ -2981,7 +2990,7 @@ pub fn removeNode(self: *Frame, parent: *Node, child: *Node, opts: RemoveNodeOpt
             self.removeElementIdWithMaps(id_maps.?, id);
         }
 
-        Element.Html.Custom.invokeDisconnectedCallbackOnElement(el, self);
+        Element.Html.Custom.enqueueDisconnectedCallbackOnElement(el, self);
 
         // If a <style> element is being removed, remove its sheet from the list
         if (el.is(Element.Html.Style)) |style| {
@@ -3004,11 +3013,8 @@ pub fn appendAllChildren(self: *Frame, parent: *Node, target: *Node) !void {
     self.domChanged();
     const dest_connected = target.isConnected();
 
-    // Use firstChild() instead of iterator to handle cases where callbacks
-    // (like custom element connectedCallback) modify the parent during iteration.
-    // The iterator captures "next" pointers that can become stale.
-    while (parent.firstChild()) |child| {
-        // Check if child was connected BEFORE removing it from parent
+    var it = parent.childrenIterator();
+    while (it.next()) |child| {
         const child_was_connected = child.isConnected();
         self.removeNode(parent, child, .{ .will_be_reconnected = dest_connected });
         try self.appendNode(target, child, .{ .child_already_connected = child_was_connected });
@@ -3019,31 +3025,16 @@ pub fn insertAllChildrenBefore(self: *Frame, fragment: *Node, parent: *Node, ref
     self.domChanged();
     const dest_connected = parent.isConnected();
 
-    // Use firstChild() instead of iterator to handle cases where callbacks
-    // (like custom element connectedCallback) modify the fragment during iteration.
-    // The iterator captures "next" pointers that can become stale.
-    while (fragment.firstChild()) |child| {
-        // Check if child was connected BEFORE removing it from fragment
+    var it = fragment.childrenIterator();
+    while (it.next()) |child| {
         const child_was_connected = child.isConnected();
         self.removeNode(fragment, child, .{ .will_be_reconnected = dest_connected });
-        // A callback fired by a previous iteration's insert (e.g. a custom
-        // element's connectedCallback) may have detached ref_node from
-        // parent. In that case, fall back to append so the remaining
-        // children still land in `parent` in source order.
-        if (ref_node._parent == parent) {
-            try self.insertNodeRelative(
-                parent,
-                child,
-                .{ .before = ref_node },
-                .{ .child_already_connected = child_was_connected },
-            );
-        } else {
-            try self.appendNode(
-                parent,
-                child,
-                .{ .child_already_connected = child_was_connected },
-            );
-        }
+        try self.insertNodeRelative(
+            parent,
+            child,
+            .{ .before = ref_node },
+            .{ .child_already_connected = child_was_connected },
+        );
     }
 }
 
@@ -3167,7 +3158,7 @@ pub fn _insertNodeRelative(self: *Frame, comptime from_parser: bool, parent: *No
                 if (el.getAttributeSafe(comptime .wrap("id"))) |id| {
                     try self.addElementId(parent, el, id);
                 }
-                try Element.Html.Custom.invokeConnectedCallbackOnElement(true, el, self);
+                try Element.Html.Custom.enqueueConnectedCallbackOnElement(true, el, self);
             }
         }
         return;
@@ -3213,7 +3204,7 @@ pub fn _insertNodeRelative(self: *Frame, comptime from_parser: bool, parent: *No
         }
 
         if (should_invoke_connected) {
-            try Element.Html.Custom.invokeConnectedCallbackOnElement(false, el, self);
+            try Element.Html.Custom.enqueueConnectedCallbackOnElement(false, el, self);
         }
     }
 }
@@ -3223,7 +3214,7 @@ pub fn attributeChange(self: *Frame, element: *Element, name: String, value: Str
         log.err(.bug, "build.attributeChange", .{ .tag = element.getTag(), .name = name, .value = value, .err = err, .type = self._type, .url = self.url });
     };
 
-    Element.Html.Custom.invokeAttributeChangedCallbackOnElement(element, name, old_value, value, null, self);
+    Element.Html.Custom.enqueueAttributeChangedCallbackOnElement(element, name, old_value, value, null, self);
 
     var it: ?*std.DoublyLinkedList.Node = self._mutation_observers.first;
     while (it) |node| : (it = node.next) {
@@ -3249,7 +3240,7 @@ pub fn attributeRemove(self: *Frame, element: *Element, name: String, old_value:
         log.err(.bug, "build.attributeRemove", .{ .tag = element.getTag(), .name = name, .err = err, .type = self._type, .url = self.url });
     };
 
-    Element.Html.Custom.invokeAttributeChangedCallbackOnElement(element, name, old_value, null, null, self);
+    Element.Html.Custom.enqueueAttributeChangedCallbackOnElement(element, name, old_value, null, null, self);
 
     var it: ?*std.DoublyLinkedList.Node = self._mutation_observers.first;
     while (it) |node| : (it = node.next) {

src/browser/ScriptManagerBase.zig

@@ -749,6 +749,13 @@ pub const Script = struct {
         try_catch.init(local);
         defer try_catch.deinit();
 
+        // Custom-element reactions: the script body is a JS-execution
+        // boundary. Open a scope so any reactions it queues (or that were
+        // queued by the parser since the previous boundary) drain at the
+        // end of the script, before the parser resumes.
+        const ce_checkpoint = frame._ce_reactions.push();
+        defer frame._ce_reactions.popAndInvoke(ce_checkpoint, frame);
+
         const success = blk: {
             const content = self.source.content();
             switch (fe.kind) {

src/browser/js/Caller.zig

@@ -569,6 +569,7 @@ pub const Function = struct {
         null_as_undefined: bool = false,
         cache: ?Caching = null,
         embedded_receiver: bool = false,
+        ce_reactions: bool = false,
 
         // We support two ways to cache a value directly into a v8::Object. The
         // difference between the two is like the difference between a Map
@@ -621,6 +622,26 @@ pub const Function = struct {
         caller.initWithContext(ctx, v8_context);
         defer caller.deinit();
 
+        // [CEReactions] entry: open a reactions scope so any custom-element
+        // callbacks queued by DOM mutation inside `func` fire after it
+        // returns, never mid-algorithm.
+        var ce_checkpoint: usize = undefined;
+        const ce_frame: ?*Frame = if (comptime opts.ce_reactions) switch (ctx.global) {
+            .frame => |frame| frame,
+            .worker => null,
+        } else null;
+
+        if (comptime opts.ce_reactions) {
+            if (ce_frame) |frame| {
+                ce_checkpoint = frame._ce_reactions.push();
+            }
+        }
+        defer if (comptime opts.ce_reactions) {
+            if (ce_frame) |frame| {
+                frame._ce_reactions.popAndInvoke(ce_checkpoint, frame);
+            }
+        };
+
         const js_value = _call(T, &caller.local, info, func, opts) catch |err| {
             handleError(T, @TypeOf(func), &caller.local, err, info, .{
                 .dom_exception = opts.dom_exception,

src/browser/js/bridge.zig

@@ -130,6 +130,18 @@ pub const Constructor = struct {
                     }
                     defer caller.deinit();
 
+                    // Constructors are a JS-execution boundary, just like
+                    // [CEReactions] methods. Open a reactions scope so any
+                    // callbacks queued by the user's constructor body (or
+                    // by attribute_changed reactions queued before invocation)
+                    // drain at the constructor's exit, not later.
+                    const ce_frame: ?*Frame = switch (caller.local.ctx.global) {
+                        .frame => |frame| frame,
+                        .worker => null,
+                    };
+                    const ce_checkpoint: usize = if (ce_frame) |frame| frame._ce_reactions.push() else 0;
+                    defer if (ce_frame) |frame| frame._ce_reactions.popAndInvoke(ce_checkpoint, frame);
+
                     caller.constructor(T, func, handle.?, .{
                         .dom_exception = opts.dom_exception,
                         .new_target = opts.new_target,