Skip to content

Lightpanda: the headless browser designed for AI and automation

webapi: preload onload/onerror callback timing

Karl Seguince4c94a27d1a
diff --git a/src/browser/Frame.zig b/src/browser/Frame.zig
index a9a437f5e..de89a8eb5 100644
--- a/src/browser/Frame.zig
+++ b/src/browser/Frame.zig
@@ -152,13 +152,14 @@ _blob_urls: std.StringHashMapUnmanaged(*Blob) = .{},
// File objects (reference counted via their Blob proto); released at teardown.
_file_lists: std.ArrayList(*FileList) = .{},
-/// `load` events that'll be fired before window's `load` event.
+/// Element `load`/`error` events queued to fire on the next scheduler tick,
+/// and flushed before window's `load` event.
/// A call to `documentIsComplete` (which calls `_documentIsComplete`) resets it.
-/// Double-buffered so that dispatching load events (which may trigger JS that
+/// Double-buffered so that dispatching events (which may trigger JS that
/// creates new elements) doesn't invalidate the list while iterating.
-_to_load_1: std.ArrayList(*Element.Html) = .{},
-_to_load_2: std.ArrayList(*Element.Html) = .{},
-_to_load: *std.ArrayList(*Element.Html) = undefined,
+_queued_events_1: std.ArrayList(QueuedEvent) = .{},
+_queued_events_2: std.ArrayList(QueuedEvent) = .{},
+_queued_events: *std.ArrayList(QueuedEvent) = undefined,
_style_manager: StyleManager,
_script_manager: ScriptManager,
@@ -309,7 +310,7 @@ pub fn init(self: *Frame, frame_id: u32, page: *Page, parent: ?*Frame) !void {
._ce_reactions = .{ .allocator = arena },
._event_manager = EventManager.init(arena, self),
};
- self._to_load = &self._to_load_1;
+ self._queued_events = &self._queued_events_1;
self._http_owner.blob_urls = &self._blob_urls;
var screen: *Screen = undefined;
@@ -995,8 +996,8 @@ pub fn documentIsComplete(self: *Frame) void {
fn _documentIsComplete(self: *Frame) !void {
self.document._ready_state = .complete;
- // Run load events before window.load.
- try self.dispatchLoad();
+ // Run element load/error events before window.load.
+ try self.dispatchQueuedEvents();
// Dispatch window.load event.
const window_target = self.window.asEventTarget();
@@ -1677,16 +1678,27 @@ pub fn checkIntersections(self: *Frame) !void {
}
}
+pub const QueuedEvent = struct {
+ kind: Kind,
+ element: *Element.Html,
+
+ pub const Kind = enum { load, @"error" };
+};
+
pub fn queueLoad(self: *Frame, html: *Element.Html) !void {
- try self._to_load.append(self.arena, html);
- if (self._to_load.items.len == 1) {
+ try self.queueElementEvent(html, .load);
+}
+
+pub fn queueElementEvent(self: *Frame, element: *Element.Html, kind: QueuedEvent.Kind) !void {
+ try self._queued_events.append(self.arena, .{ .element = element, .kind = kind });
+ if (self._queued_events.items.len == 1) {
try self.js.scheduler.add(self, struct {
fn cleanup(ctx: *anyopaque) !?u32 {
const f: *Frame = @ptrCast(@alignCast(ctx));
- try f.dispatchLoad();
+ try f.dispatchQueuedEvents();
return null;
}
- }.cleanup, 0, .{ .name = "frame.dispatchLoad" });
+ }.cleanup, 0, .{ .name = "frame.dispatchQueuedEvents" });
}
}
@@ -1698,37 +1710,37 @@ pub fn queueLoad(self: *Frame, html: *Element.Html) !void {
const MAX_STYLESHEET_BYTES: usize = 2 * 1024 * 1024;
// start prefetching <link rel="preload" as="script" href=...>`
-pub fn preloadScriptHint(self: *Frame, href: []const u8) void {
+pub fn preloadScriptHint(self: *Frame, element: *Element.Html, href: []const u8) bool {
if (self.isGoingAway() or self._parse_mode == .fragment) {
- return;
+ return false;
}
- const arena = self.getArena(.small, "Frame.preloadScriptHint") catch return;
+ const arena = self.getArena(.small, "Frame.preloadScriptHint") catch return false;
defer self.releaseArena(arena);
- const resolved = URL.resolve(arena, self.base(), href, .{ .encoding = self.charset }) catch return;
+ const resolved = URL.resolve(arena, self.base(), href, .{ .encoding = self.charset }) catch return false;
if (!std.ascii.startsWithIgnoreCase(resolved, "http:") and !std.ascii.startsWithIgnoreCase(resolved, "https:")) {
// data:/blob: are synthesized locally — no round-trip to hide.
- return;
+ return false;
}
- self._script_manager.preloadScript(resolved) catch {};
+ return self._script_manager.preloadScript(element, resolved) catch false;
}
// start prefetching <link rel="modulepreload" href=...>
-pub fn preloadModuleHint(self: *Frame, href: []const u8) void {
+pub fn preloadModuleHint(self: *Frame, element: *Element.Html, href: []const u8) bool {
if (self.isGoingAway() or self._parse_mode == .fragment) {
- return;
+ return false;
}
// The url becomes the imported_modules key, which must outlive the fetch
// so it lives on the frame arena
- const resolved = URL.resolve(self.arena, self.base(), href, .{ .encoding = self.charset }) catch return;
+ const resolved = URL.resolve(self.arena, self.base(), href, .{ .encoding = self.charset }) catch return false;
if (!std.ascii.startsWithIgnoreCase(resolved, "http:") and !std.ascii.startsWithIgnoreCase(resolved, "https:")) {
// data:/blob: are synthesized locally — no round-trip to hide.
- return;
+ return false;
}
- self._script_manager.base.preloadModuleHint(resolved, self.url) catch {};
+ return self._script_manager.base.preloadModuleHint(element, resolved, self.url) catch false;
}
// Synchronously fetch and parse an external `<link rel=stylesheet>`.
@@ -1849,19 +1861,35 @@ fn fireElementEvent(self: *Frame, el: *Element, name: String) !void {
try self._event_manager.dispatch(el.asEventTarget(), event);
}
-fn dispatchLoad(self: *Frame) !void {
+fn dispatchQueuedEvents(self: *Frame) !void {
const has_dom_load_listener = self._event_manager.has_dom_load_listener;
// Swap buffers - new additions during dispatch go to the other buffer
- const to_process = self._to_load;
- self._to_load = if (self._to_load == &self._to_load_1)
- &self._to_load_2
+ const to_process = self._queued_events;
+ self._queued_events = if (self._queued_events == &self._queued_events_1)
+ &self._queued_events_2
else
- &self._to_load_1;
-
- for (to_process.items) |html_element| {
- if (has_dom_load_listener or html_element.hasAttributeFunction(.onload, self)) {
- try self.fireElementEvent(html_element.asElement(), comptime .wrap("load"));
+ &self._queued_events_1;
+
+ for (to_process.items) |queued| {
+ const html_element = queued.element;
+ const element = html_element.asElement();
+ switch (queued.kind) {
+ // hasAttributeFunction only sees handlers compiled via property
+ // access; a parsed `onload="..."` attribute is compiled lazily at
+ // dispatch (EventManager.getInlineHandler), so check it raw too.
+ .load => {
+ if (has_dom_load_listener or
+ html_element.hasAttributeFunction(.onload, self) or
+ element.getAttributeSafe(comptime .wrap("onload")) != null)
+ {
+ try self.fireElementEvent(element, comptime .wrap("load"));
+ }
+ },
+ .@"error" => {
+ // errors are rare; not worth a listener-presence check
+ try self.fireElementEvent(element, comptime .wrap("error"));
+ },
}
}
diff --git a/src/browser/ScriptManager.zig b/src/browser/ScriptManager.zig
index 769d57f45..157abf557 100644
--- a/src/browser/ScriptManager.zig
+++ b/src/browser/ScriptManager.zig
@@ -102,9 +102,11 @@ fn getHeaders(self: *ScriptManager) !HttpClient.Headers {
return self.base.getHeaders();
}
-pub fn preloadScript(self: *ScriptManager, url: []const u8) !void {
+// Returns true when a fetch was started: the link's load/error event fires
+// when the fetch settles. false (duplicate hint) = no event will fire.
+pub fn preloadScript(self: *ScriptManager, element: *Element.Html, url: []const u8) !bool {
if (self.preloaded_scripts.contains(url)) {
- return;
+ return false;
}
const frame = self.frame;
@@ -122,6 +124,7 @@ pub fn preloadScript(self: *ScriptManager, url: []const u8) !void {
.complete = false,
.source = .{ .remote = .{} },
.extra = .preload,
+ .hint_element = element,
};
try self.preloaded_scripts.putNoClobber(self.base.allocator, owned_url, .{ .state = .{ .loading = script } });
@@ -148,6 +151,7 @@ pub fn preloadScript(self: *ScriptManager, url: []const u8) !void {
.done_callback = PreloadedScript.doneCallback,
.error_callback = PreloadedScript.errorCallback,
});
+ return true;
}
fn waitForPreload(self: *ScriptManager, url: [:0]const u8) ?*Script {
@@ -439,6 +443,7 @@ const PreloadedScript = struct {
const self: *ScriptManager = @fieldParentPtr("base", script.manager);
self.preloaded_scripts.getPtr(script.url).?.state = .{ .done = script };
+ script.queueHintEvent(.load);
}
fn errorCallback(ctx: *anyopaque, err: anyerror) void {
@@ -451,6 +456,7 @@ const PreloadedScript = struct {
const self: *ScriptManager = @fieldParentPtr("base", script.manager);
_ = self.preloaded_scripts.remove(script.url);
+ script.queueHintEvent(.@"error");
script.deinit();
}
};
diff --git a/src/browser/ScriptManagerBase.zig b/src/browser/ScriptManagerBase.zig
index a1969501f..b998afb3e 100644
--- a/src/browser/ScriptManagerBase.zig
+++ b/src/browser/ScriptManagerBase.zig
@@ -218,7 +218,8 @@ pub fn resolveSpecifier(self: *ScriptManagerBase, arena: Allocator, base: [:0]co
}
const PreloadOpts = struct {
- hint: bool = false,
+ // set when the preload comes from a <link rel=modulepreload> hint
+ hint_element: ?*Element.Html = null,
};
pub fn preloadImport(self: *ScriptManagerBase, url: [:0]const u8, referrer: []const u8, opts: PreloadOpts) !void {
const gop = try self.imported_modules.getOrPut(self.allocator, url);
@@ -246,9 +247,10 @@ pub fn preloadImport(self: *ScriptManagerBase, url: [:0]const u8, referrer: []co
.complete = false,
.source = .{ .remote = .{} },
.extra = .import,
+ .hint_element = opts.hint_element,
};
- gop.value_ptr.* = .{ .state = .{ .loading = script }, .hint = opts.hint };
+ gop.value_ptr.* = .{ .state = .{ .loading = script }, .hint = opts.hint_element != null };
if (comptime IS_DEBUG) {
var ls: js.Local.Scope = undefined;
@@ -294,12 +296,14 @@ pub fn preloadImport(self: *ScriptManagerBase, url: [:0]const u8, referrer: []co
}
// <link rel=modulepreload href=...> — start fetching a module before import
-// resolution discovers it.
-pub fn preloadModuleHint(self: *ScriptManagerBase, url: [:0]const u8, referrer: []const u8) !void {
+// resolution discovers it. Returns false when no fetch was started (the
+// module is already fetched/fetching): no event will fire on the link.
+pub fn preloadModuleHint(self: *ScriptManagerBase, element: *Element.Html, url: [:0]const u8, referrer: []const u8) !bool {
if (self.imported_modules.contains(url)) {
- return;
+ return false;
}
- try self.preloadImport(url, referrer, .{ .hint = true });
+ try self.preloadImport(url, referrer, .{ .hint_element = element });
+ return true;
}
pub fn waitForImport(self: *ScriptManagerBase, url: [:0]const u8) !ModuleSource {
@@ -581,6 +585,12 @@ pub const Script = struct {
node: std.DoublyLinkedList.Node,
manager: *ScriptManagerBase,
+ // Set when this fetch was started by a <link rel=preload as=script> or
+ // <link rel=modulepreload> hint: the link element to fire load/error on
+ // once the fetch settles. Lives outside `extra` so adoption (e.g.
+ // getAsyncImport replacing .import with .import_async) can't lose it.
+ hint_element: ?*Element.Html = null,
+
// for debugging a rare production issue
header_callback_called: bool = false,
@@ -609,7 +619,8 @@ pub const Script = struct {
// (script_element, kind, *Frame); workers and dynamic JS imports use
// `.import` / `.import_async` and never reach the .frame arm.
pub const Extra = union(enum) {
- // Static module import — V8 resolution via imported_modules.
+ // Static module import — V8 resolution via imported_modules. Also
+ // <link rel=modulepreload> hints (see Script.hint_element).
import,
// Dynamic JS import() — resolved via ready_scripts callback.
import_async: ImportAsync,
@@ -758,6 +769,7 @@ pub const Script = struct {
},
.preload => unreachable, // preloads use ScriptManager.PreloadedScript.doneCallback
}
+ self.queueHintEvent(.load);
manager.evaluate();
}
@@ -801,6 +813,7 @@ pub const Script = struct {
.frame => self.executeCallback(comptime .wrap("error")),
.preload => unreachable, // preloads use ScriptManager.PreloadedScript.errorCallback
}
+ self.queueHintEvent(.@"error");
self.deinit();
manager.evaluate();
}
@@ -911,6 +924,8 @@ pub const Script = struct {
self.executeCallback(comptime .wrap("error"));
}
+ // Frame-only: fires load/error on the <script> element itself,
+ // synchronously. Hint <link> events go through queueHintEvent instead.
pub fn executeCallback(self: *const Script, typ: String) void {
const fe = self.extra.frame;
const frame = fe.frame;
@@ -931,6 +946,21 @@ pub const Script = struct {
});
};
}
+
+ // Fire the hint <link>'s load/error event, queued on the scheduler rather
+ // than dispatched inline: done/error callbacks run inside HTTP pumps
+ // (possibly mid sync-wait, or inside V8's module-resolve callback for
+ // imports), where dispatching user JS would be a novel re-entrancy point.
+ // Browsers queue these as tasks anyway. The queued entry holds only the
+ // element, so it stays valid even if the script is adopted/freed first.
+ pub fn queueHintEvent(self: *const Script, kind: Frame.QueuedEvent.Kind) void {
+ const element = self.hint_element orelse return;
+ // hints only originate from a <link> in a frame, never from a worker
+ const frame = self.manager.owner.frame;
+ frame.queueElementEvent(element, kind) catch |err| {
+ log.warn(.js, "script hint event", .{ .url = self.url, .kind = kind, .err = err });
+ };
+ }
};
pub const ImportAsync = struct {
diff --git a/src/browser/tests/element/html/script/modulepreload.html b/src/browser/tests/element/html/script/modulepreload.html
index 72b19892a..5ad1b4d21 100644
--- a/src/browser/tests/element/html/script/modulepreload.html
+++ b/src/browser/tests/element/html/script/modulepreload.html
@@ -9,33 +9,46 @@
exactly as if the hint never existed. Both halves of that handover run under
the leak detector here.
-->
-<link rel="modulepreload" href="modulepreload.js">
+<link rel="modulepreload" href="modulepreload.js" onload="window.hint_consumed_load = true">
<!--
A hinted module that nothing imports is fetched but never evaluated. It
lingers as a `.done` imported_modules entry until reset() frees it —
exercises the map cleanup under the leak detector — and it must not run on
- its own, nor delay the load event.
+ its own. Its fetch holds an async_scripts slot, so window.load waits for it:
+ the link's load event (queued at fetch completion) is deterministically
+ observable in testing.onload.
-->
-<link rel="modulepreload" href="modulepreload_unused.js">
+<link rel="modulepreload" href="modulepreload_unused.js" onload="window.hint_unused_load = true">
-<!-- A duplicate hint must not double-fetch or double-register a waiter. -->
-<link rel="modulepreload" href="modulepreload.js">
+<!--
+ A duplicate hint must not double-fetch or double-register a waiter. No fetch
+ starts for it, so its load event is the synthetic next-tick one.
+-->
+<link rel="modulepreload" href="modulepreload.js" onload="window.hint_dup_load = true">
+
+<!--
+ A hint whose fetch fails must fire error (not load) on the link. The fetch
+ settles before window.load (async_scripts gate), so this is deterministic.
+-->
+<link rel="modulepreload" href="modulepreload_does_not_exist.js"
+ onload="window.hint_404_load = true" onerror="window.hint_404_error = true">
<!--
The Vite pattern: a runtime-style hint immediately followed by a dynamic
- import(). The hint's load event is synthetic, so the import fires while the
- hint's fetch is still in flight — getAsyncImport adopts the loading Script
- (converts it to .import_async) instead of fetching the module a second time.
+ import(). The import fires while the hint's fetch is still in flight —
+ getAsyncImport adopts the loading Script (converts it to .import_async)
+ instead of fetching the module a second time. The link's load event must
+ survive that adoption: it lives on Script.hint_element, not in extra.
-->
-<link rel="modulepreload" href="modulepreload_dynamic.js">
+<link rel="modulepreload" href="modulepreload_dynamic.js" onload="window.hint_dynamic_load = true">
<script id="dynamic_adopt_loading">
window.dynamic_val = '';
import('./modulepreload_dynamic.js').then((m) => { window.dynamic_val = m.dval; });
testing.onload(() => testing.expectEqual('dynamic-preloaded', window.dynamic_val));
</script>
-<link rel="modulepreload" href="modulepreload_dynamic2.js">
+<link rel="modulepreload" href="modulepreload_dynamic2.js" onload="window.hint_dynamic2_load = true">
<script id="consume" type="module">
import { val } from "./modulepreload.js";
@@ -55,3 +68,16 @@
// A hint that nothing imports must never evaluate.
testing.expectEqual(undefined, window.modulepreload_unused_ran);
</script>
+
+<script id="link_events">
+ // Every hint link fires exactly one settle event before window.load.
+ testing.onload(() => {
+ testing.expectEqual(true, window.hint_consumed_load);
+ testing.expectEqual(true, window.hint_unused_load);
+ testing.expectEqual(true, window.hint_dup_load);
+ testing.expectEqual(true, window.hint_dynamic_load);
+ testing.expectEqual(true, window.hint_dynamic2_load);
+ testing.expectEqual(undefined, window.hint_404_load);
+ testing.expectEqual(true, window.hint_404_error);
+ });
+</script>
diff --git a/src/browser/tests/element/html/script/preload.html b/src/browser/tests/element/html/script/preload.html
index 26ea2a291..bad4c40a0 100644
--- a/src/browser/tests/element/html/script/preload.html
+++ b/src/browser/tests/element/html/script/preload.html
@@ -8,13 +8,21 @@
fresh syncRequest, then the consumed entry is freed by the caller. Both halves
of that ownership handover run under the leak detector here.
-->
-<link rel="preload" as="script" href="preload.js">
+<link rel="preload" as="script" href="preload.js" onload="window.preload_consumed_load = true">
+
+<!--
+ A duplicate hint: no fetch starts, so its load event is the synthetic
+ next-tick one.
+-->
+<link rel="preload" as="script" href="preload.js" onload="window.preload_dup_load = true">
<!--
A preload with no matching <script> is fetched but never executed. It lingers
as a `.done` (or still-loading) entry until reset() frees it — exercises
freePreloads / map cleanup under the leak detector — and it must not run on
- its own, nor delay the load event.
+ its own, nor delay the load event. No onload assertion: unlike module hints,
+ nothing gates window.load on this fetch, so its load event may fire after
+ testing.onload runs.
-->
<link rel="preload" as="script" href="preload_unused.js">
@@ -36,3 +44,13 @@
// A preload hint that nothing consumes must never execute.
testing.expectEqual(undefined, window.unused_preload_ran);
</script>
+
+<script id="link_events">
+ // The consumed preload's fetch completed (the blocking script above
+ // adopted its body), so its real load event fired; the duplicate's
+ // synthetic load fired next tick. Both before window.load.
+ testing.onload(() => {
+ testing.expectEqual(true, window.preload_consumed_load);
+ testing.expectEqual(true, window.preload_dup_load);
+ });
+</script>
diff --git a/src/browser/webapi/element/html/Link.zig b/src/browser/webapi/element/html/Link.zig
index 0e8e1d424..601d713e3 100644
--- a/src/browser/webapi/element/html/Link.zig
+++ b/src/browser/webapi/element/html/Link.zig
@@ -203,9 +203,7 @@ pub fn linkAddedCallback(self: *Link, frame: *Frame) !void {
const rel = element.getAttributeSafe(comptime .wrap("rel")) orelse return;
// Opt-in fetch for `rel="stylesheet"` — drives `frame.loadExternalStylesheet`,
- // which fires the load/error event itself. preload/modulepreload start a
- // background fetch (a hint, never evaluated on its own) and fire a
- // synthetic `load` event regardless of how the fetch goes.
+ // which fires the load/error event itself.
if (std.mem.eql(u8, rel, "stylesheet")) {
return frame.loadExternalStylesheet(self, href);
}
@@ -213,20 +211,27 @@ pub fn linkAddedCallback(self: *Link, frame: *Frame) !void {
if (std.mem.eql(u8, rel, "preload")) {
const as = element.getAttributeSafe(comptime .wrap("as")) orelse "";
if (std.ascii.eqlIgnoreCase(as, "script")) {
- frame.preloadScriptHint(href);
+ if (frame.preloadScriptHint(self._proto, href)) {
+ // load/error fires when the fetch settles
+ return;
+ }
}
- } else if (std.mem.eql(u8, rel, "modulepreload")) {
- // "as" default to script in this case
+ // synthetic load, fires next tick
+ return frame.queueLoad(self._proto);
+ }
+
+ if (std.mem.eql(u8, rel, "modulepreload")) {
+ // "as" defaults to script in this case
const as = element.getAttributeSafe(comptime .wrap("as")) orelse "";
if (as.len == 0 or std.ascii.eqlIgnoreCase(as, "script")) {
- frame.preloadModuleHint(href);
+ if (frame.preloadModuleHint(self._proto, href)) {
+ // load/error fires when the fetch settles
+ return;
+ }
}
- } else {
- // remaining rels (icon, canonical, ...): no fetch, no load event
- return;
+ // synthetic load, fires next tick
+ return frame.queueLoad(self._proto);
}
-
- try frame.queueLoad(self._proto);
}
pub const JsApi = struct {