Lightpanda: the headless browser designed for AI and automation
webapi: structuredClone for host (aka Zig) objects
Karl Seguina750a6942dac
diff --git a/src/browser/js/Value.zig b/src/browser/js/Value.zigindex c777a87e7..c9d4fb5e3 100644--- a/src/browser/js/Value.zig+++ b/src/browser/js/Value.zig@@ -20,8 +20,10 @@ const std = @import("std");const lp = @import("lightpanda");const js = @import("js.zig");+const TaggedOpaque = @import("TaggedOpaque.zig");const v8 = js.v8;+const bridge = js.bridge;const IS_DEBUG = @import("builtin").mode == .Debug;@@ -324,8 +326,9 @@ pub fn jsonStringify(self: Value, jws: anytype) !void {jws.endWriteRaw();}-// Throws a DataCloneError for host objects (Blob, File, etc.) that cannot be serialized.-// Does not support transferables which require additional delegate callbacks.+// Clones host objects listed in cloneable_types; throws a DataCloneError for+// any other. Does not support transferables which require additional delegate+// callbacks.pub fn structuredClone(self: Value) !Value {return self.structuredCloneTo(self.local);}@@ -333,75 +336,283 @@ pub fn structuredClone(self: Value) !Value {// Clone a value to a different context (within the same isolate).// Used for cross-context messaging (e.g., Worker <-> Page).pub fn structuredCloneTo(self: Value, target: *const js.Local) !Value {- const source_context = self.local.handle;- const target_context = target.handle;- const v8_isolate = target.isolate.handle;-- const SerializerDelegate = struct {- // Called when V8 encounters a host object it doesn't know how to serialize.- // Returns false to indicate the object cannot be cloned, and throws a DataCloneError.- // V8 asserts has_exception() after this returns false, so we must throw here.- fn writeHostObject(_: ?*anyopaque, isolate: ?*v8.Isolate, _: ?*const v8.Object) callconv(.c) v8.MaybeBool {- const iso = isolate orelse return .{ .has_value = true, .value = false };- const message = v8.v8__String__NewFromUtf8(iso, "The object cannot be cloned.", v8.kNormal, -1);- const error_value = v8.v8__Exception__Error(message) orelse return .{ .has_value = true, .value = false };- _ = v8.v8__Isolate__ThrowException(iso, error_value);- return .{ .has_value = true, .value = false };+ const serialized = try self.serialize();+ defer serialized.deinit();+ return deserialize(target, serialized.bytes());+}++// A structured-serialized value: a V8-owned byte buffer. Caller must free it+// and must dupe the bytes if they want it to outlive the current local scope.+pub const Serialized = struct {+ data: [*c]u8,+ size: usize,++ pub fn bytes(self: Serialized) []const u8 {+ return self.data[0..self.size];+ }++ pub fn deinit(self: Serialized) void {+ v8.v8__ValueSerializer__FreeBuffer(self.data);+ }+};++// Serialize `self` into a V8-owned buffer. The caller must call deinit on the+// result. Raises a JS exception (DataCloneError) for unserializable values.+pub fn serialize(self: Value) !Serialized {+ var delegate_ctx = CloneDelegate.SerializeContext{+ .local = self.local,+ .serializer = undefined,+ };+ const serializer = v8.v8__ValueSerializer__New(self.local.isolate.handle, &.{+ .data = &delegate_ctx,+ .get_shared_array_buffer_id = CloneDelegate.getSharedArrayBufferId,+ .write_host_object = CloneDelegate.writeHostObject,+ .throw_data_clone_error = CloneDelegate.throwDataCloneError,+ }) orelse return error.JsException;+ defer v8.v8__ValueSerializer__DELETE(serializer);+ // the delegate callbacks only fire during WriteValue, after this is set+ delegate_ctx.serializer = serializer;++ var write_result: v8.MaybeBool = undefined;+ v8.v8__ValueSerializer__WriteHeader(serializer);+ v8.v8__ValueSerializer__WriteValue(serializer, self.local.handle, self.handle, &write_result);+ if (!write_result.has_value or !write_result.value) {+ return error.JsException;+ }++ var size: usize = undefined;+ const data = v8.v8__ValueSerializer__Release(serializer, &size) orelse return error.JsException;+ return .{ .data = data, .size = size };+}++// Deserialize a structured-serialized buffer (from `serialize`) into a value in+// `local`'s context. A malformed buffer surfaces as error.JsException.+pub fn deserialize(local: *const js.Local, bytes: []const u8) !Value {+ var delegate_ctx = CloneDelegate.DeserializeContext{+ .local = local,+ .deserializer = undefined,+ };+ const deserializer = v8.v8__ValueDeserializer__New(local.isolate.handle, bytes.ptr, bytes.len, &.{+ .data = &delegate_ctx,+ .read_host_object = CloneDelegate.readHostObject,+ }) orelse return error.JsException;+ defer v8.v8__ValueDeserializer__DELETE(deserializer);+ delegate_ctx.deserializer = deserializer;++ var read_header_result: v8.MaybeBool = undefined;+ v8.v8__ValueDeserializer__ReadHeader(deserializer, local.handle, &read_header_result);+ if (!read_header_result.has_value or !read_header_result.value) {+ return error.JsException;+ }++ const handle = v8.v8__ValueDeserializer__ReadValue(deserializer, local.handle) orelse return error.JsException;+ return .{ .local = local, .handle = handle };+}++// Host object types that support structured cloning via structuredSerialize /+// structuredDeserialize hooks. The serialized payload tags each host object+// with its position in this list; buffers never outlive the process, so the+// order only has to be consistent within a build.+const cloneable_types = .{+ @import("../webapi/Blob.zig"),+ @import("../webapi/File.zig"),+ @import("../webapi/FileList.zig"),+ @import("../webapi/ImageData.zig"),+};++// Passed to a type's structuredSerialize hook to write its payload into the+// V8 serialization buffer.+pub const StructuredWriter = struct {+ local: *const js.Local,+ serializer: *v8.ValueSerializer,++ pub fn writeUint32(self: *const StructuredWriter, value: u32) void {+ v8.v8__ValueSerializer__WriteUint32(self.serializer, value);+ }++ pub fn writeUint64(self: *const StructuredWriter, value: u64) void {+ v8.v8__ValueSerializer__WriteUint64(self.serializer, value);+ }++ pub fn writeBytes(self: *const StructuredWriter, bytes: []const u8) void {+ v8.v8__ValueSerializer__WriteUint32(self.serializer, @intCast(bytes.len));+ if (bytes.len > 0) {+ v8.v8__ValueSerializer__WriteRawBytes(self.serializer, bytes.ptr, bytes.len);}+ }+};- // Called by V8 to report serialization errors. The exception should already be thrown.- fn throwDataCloneError(_: ?*anyopaque, _: ?*const v8.String) callconv(.c) void {}-- // Called when V8 encounters a SharedArrayBuffer. We don't support sharing them across- // contexts, so throw a DataCloneError and return false. V8's WriteJSArrayBuffer calls- // RETURN_VALUE_IF_EXCEPTION after this, so throwing prevents the fatal FromJust call.- fn getSharedArrayBufferId(_: ?*anyopaque, isolate: ?*v8.Isolate, _: ?*const v8.SharedArrayBuffer, _: ?*u32) callconv(.c) bool {- const iso = isolate orelse return false;- const message = v8.v8__String__NewFromUtf8(iso, "SharedArrayBuffer cannot be cloned.", v8.kNormal, -1);- const error_value = v8.v8__Exception__Error(message) orelse return false;- _ = v8.v8__Isolate__ThrowException(iso, error_value);- return false;+// Passed to a type's structuredDeserialize hook to read back the payload its+// structuredSerialize hook wrote.+pub const StructuredReader = struct {+ local: *const js.Local,+ deserializer: *v8.ValueDeserializer,++ pub fn readUint32(self: *const StructuredReader) !u32 {+ var out: u32 = undefined;+ if (!v8.v8__ValueDeserializer__ReadUint32(self.deserializer, &out)) {+ return error.DataClone;}- };+ return out;+ }- const size, const data = blk: {- const serializer = v8.v8__ValueSerializer__New(v8_isolate, &.{- .data = null,- .get_shared_array_buffer_id = SerializerDelegate.getSharedArrayBufferId,- .write_host_object = SerializerDelegate.writeHostObject,- .throw_data_clone_error = SerializerDelegate.throwDataCloneError,- }) orelse return error.JsException;-- defer v8.v8__ValueSerializer__DELETE(serializer);-- var write_result: v8.MaybeBool = undefined;- v8.v8__ValueSerializer__WriteHeader(serializer);- v8.v8__ValueSerializer__WriteValue(serializer, source_context, self.handle, &write_result);- if (!write_result.has_value or !write_result.value) {- return error.JsException;+ pub fn readUint64(self: *const StructuredReader) !u64 {+ var out: u64 = undefined;+ if (!v8.v8__ValueDeserializer__ReadUint64(self.deserializer, &out)) {+ return error.DataClone;}+ return out;+ }- var size: usize = undefined;- const data = v8.v8__ValueSerializer__Release(serializer, &size) orelse return error.JsException;- break :blk .{ size, data };+ // The returned slice points into the serialization buffer; dupe anything+ // that must outlive deserialization.+ pub fn readBytes(self: *const StructuredReader) ![]const u8 {+ const len = try self.readUint32();+ if (len == 0) {+ return "";+ }+ var ptr: ?*const anyopaque = null;+ if (!v8.v8__ValueDeserializer__ReadRawBytes(self.deserializer, len, &ptr)) {+ return error.DataClone;+ }+ return @as([*]const u8, @ptrCast(ptr.?))[0..len];+ }+};++const CloneDelegate = struct {+ const SerializeContext = struct {+ local: *const js.Local,+ serializer: *v8.ValueSerializer,};- defer v8.v8__ValueSerializer__FreeBuffer(data);+ const DeserializeContext = struct {+ local: *const js.Local,+ deserializer: *v8.ValueDeserializer,+ };++ // Called when V8 encounters an object with embedder fields, i.e. one of+ // our wrapped Zig instances. Serialize it if its type (or a prototype)+ // is in cloneable_types, otherwise throw a DataCloneError. V8 asserts+ // has_exception() after a false return, so we must throw here.+ fn writeHostObject(data: ?*anyopaque, _: ?*v8.Isolate, object: ?*const v8.Object) callconv(.c) v8.MaybeBool {+ const ctx: *SerializeContext = @ptrCast(@alignCast(data.?));++ blk: {+ const obj = object orelse break :blk;+ if (v8.v8__Object__InternalFieldCount(obj) == 0) {+ break :blk;+ }+ const tao_ptr = v8.v8__Object__GetAlignedPointerFromInternalField(obj, 0) orelse break :blk;+ const tao: *TaggedOpaque = @ptrCast(@alignCast(tao_ptr));- const cloned_handle = blk: {- const deserializer = v8.v8__ValueDeserializer__New(v8_isolate, data, size, null) orelse return error.JsException;- defer v8.v8__ValueDeserializer__DELETE(deserializer);+ const prototype_chain = tao.prototype_chain[0..tao.prototype_len];+ if (writeCloneable(ctx, prototype_chain[0].index, tao.value)) |result| {+ return result;+ }- var read_header_result: v8.MaybeBool = undefined;- v8.v8__ValueDeserializer__ReadHeader(deserializer, target_context, &read_header_result);- if (!read_header_result.has_value or !read_header_result.value) {- return error.JsException;+ // Walk up the prototype chain so a subtype serializes as its+ // closest cloneable supertype (mirrors TaggedOpaque.fromJS).+ var ptr = @intFromPtr(tao.value);+ for (prototype_chain[1..]) |proto| {+ ptr += proto.offset;+ const proto_ptr: **anyopaque = @ptrFromInt(ptr);+ if (writeCloneable(ctx, proto.index, proto_ptr.*)) |result| {+ return result;+ }+ ptr = @intFromPtr(proto_ptr.*);+ }}- break :blk v8.v8__ValueDeserializer__ReadValue(deserializer, target_context) orelse return error.JsException;- };- return .{ .local = target, .handle = cloned_handle };-}+ throwDataCloneException(ctx.local, null);+ return .{ .has_value = true, .value = false };+ }++ fn writeCloneable(+ ctx: *SerializeContext,+ type_index: bridge.JsApiLookup.BackingInt,+ value_ptr: *anyopaque,+ ) ?v8.MaybeBool {+ inline for (cloneable_types, 0..) |T, tag| {+ if (type_index == bridge.JsApiLookup.getId(T.JsApi)) {+ v8.v8__ValueSerializer__WriteUint32(ctx.serializer, tag);+ var writer = StructuredWriter{ .local = ctx.local, .serializer = ctx.serializer };+ const instance: *const T = @ptrCast(@alignCast(value_ptr));+ instance.structuredSerialize(&writer) catch {+ throwDataCloneException(ctx.local, null);+ return .{ .has_value = true, .value = false };+ };+ return .{ .has_value = true, .value = true };+ }+ }+ return null;+ }++ // Called by V8 to read back what writeHostObject wrote. Returning null+ // aborts deserialization, so we throw first to surface a proper error.+ fn readHostObject(data: ?*anyopaque, _: ?*v8.Isolate) callconv(.c) ?*const v8.Object {+ const ctx: *DeserializeContext = @ptrCast(@alignCast(data.?));+ const local = ctx.local;++ var tag: u32 = undefined;+ if (v8.v8__ValueDeserializer__ReadUint32(ctx.deserializer, &tag)) {+ var reader = StructuredReader{ .local = local, .deserializer = ctx.deserializer };+ inline for (cloneable_types, 0..) |T, i| {+ if (tag == i) {+ return readCloneable(T, &reader) orelse {+ throwDataCloneException(local, null);+ return null;+ };+ }+ }+ }++ throwDataCloneException(local, null);+ return null;+ }++ fn readCloneable(comptime T: type, reader: *StructuredReader) ?*const v8.Object {+ const local = reader.local;+ const instance = T.structuredDeserialize(reader, local.ctx.page) catch return null;+ const js_obj = local.mapZigInstanceToJs(null, instance) catch return null;+ return js_obj.handle;+ }++ // Called by V8 when a built-in can't be serialized (e.g. an out-of-bounds+ // TypedArray). The delegate is responsible for actually throwing.+ fn throwDataCloneError(data: ?*anyopaque, message: ?*const v8.String) callconv(.c) void {+ const ctx: *SerializeContext = @ptrCast(@alignCast(data.?));+ const local = ctx.local;+ const msg: ?[]const u8 = blk: {+ const handle = message orelse break :blk null;+ const str = js.String{ .local = local, .handle = handle };+ // the exception can outlive this call; dupe onto the context arena+ break :blk str.toSliceWithAlloc(local.ctx.arena) catch null;+ };+ throwDataCloneException(local, msg);+ }++ // Called when V8 encounters a SharedArrayBuffer. We don't support sharing+ // them across contexts, so throw a DataCloneError and return false. V8's+ // WriteJSArrayBuffer calls RETURN_VALUE_IF_EXCEPTION after this, so+ // throwing prevents the fatal FromJust call.+ fn getSharedArrayBufferId(data: ?*anyopaque, _: ?*v8.Isolate, _: ?*const v8.SharedArrayBuffer, _: ?*u32) callconv(.c) bool {+ const ctx: *SerializeContext = @ptrCast(@alignCast(data.?));+ throwDataCloneException(ctx.local, "SharedArrayBuffer cannot be cloned");+ return false;+ }++ fn throwDataCloneException(local: *const js.Local, message: ?[]const u8) void {+ const DOMException = @import("../webapi/DOMException.zig");+ const isolate = local.isolate;+ const js_value = local.zigValueToJs(DOMException.init(message, "DataCloneError"), .{}) catch {+ const str = v8.v8__String__NewFromUtf8(isolate.handle, "The object can not be cloned", v8.kNormal, -1);+ const error_value = v8.v8__Exception__Error(str) orelse return;+ _ = v8.v8__Isolate__ThrowException(isolate.handle, error_value);+ return;+ };+ _ = isolate.throwException(js_value.handle);+ }+};pub fn persist(self: Value) !Global {return self._persist(true);diff --git a/src/browser/js/js.zig b/src/browser/js/js.zigindex 3095d20b3..cbbba7cbb 100644--- a/src/browser/js/js.zig+++ b/src/browser/js/js.zig@@ -43,6 +43,8 @@ pub const Isolate = @import("Isolate.zig");pub const HandleScope = @import("HandleScope.zig");pub const Value = @import("Value.zig");+pub const StructuredWriter = Value.StructuredWriter;+pub const StructuredReader = Value.StructuredReader;pub const Array = @import("Array.zig");pub const String = @import("String.zig");pub const Object = @import("Object.zig");@@ -178,6 +180,22 @@ pub fn ArrayBufferRef(comptime kind: ArrayType) type {return .{ .handle = global };}++ // Direct view into the typed array's backing memory.+ pub fn slice(self: *const Self) []BackingInt {+ const view: *const v8.ArrayBufferView = @ptrCast(self.handle);+ const byte_len = v8.v8__ArrayBufferView__ByteLength(view);+ if (byte_len == 0) {+ return @constCast(&[_]BackingInt{});+ }+ const byte_offset = v8.v8__ArrayBufferView__ByteOffset(view);+ const array_buffer = v8.v8__ArrayBufferView__Buffer(view).?;+ const backing_store_ptr = v8.v8__ArrayBuffer__GetBackingStore(array_buffer);+ const backing_store = v8.std__shared_ptr__v8__BackingStore__get(&backing_store_ptr).?;+ const data = v8.v8__BackingStore__Data(backing_store).?;+ const base = @as([*]u8, @ptrCast(data)) + byte_offset;+ return @as([*]BackingInt, @ptrCast(@alignCast(base)))[0 .. byte_len / @sizeOf(BackingInt)];+ }};}diff --git a/src/browser/webapi/Blob.zig b/src/browser/webapi/Blob.zigindex 2d4916db7..4b7dfbfda 100644--- a/src/browser/webapi/Blob.zig+++ b/src/browser/webapi/Blob.zig@@ -96,7 +96,8 @@ pub fn init(parts_: ?[]const js.Value, opts_: ?InitOptions, page: *Page) !*Blob/// Creates a new Blob from raw byte slices (for internal Zig use).pub fn initFromBytes(data: []const u8, content_type: []const u8, page: *Page) !*Blob {- const arena = try page.getArena(.large, "Blob");+ // + 256 because the arena might also be used by File+ const arena = try page.getArena(data.len + content_type.len + 256, "Blob");errdefer page.releaseArena(arena);const mime = try Mime.serialize(arena, content_type);@@ -124,6 +125,30 @@ pub fn acquireRef(self: *Blob) void {self._rc.acquire();}+pub fn structuredSerialize(self: *const Blob, writer: *js.StructuredWriter) !void {+ writer.writeBytes(self._mime);+ writer.writeBytes(self._slice);+}++pub fn structuredDeserialize(reader: *js.StructuredReader, page: *Page) !*Blob {+ const mime = try reader.readBytes();+ const data = try reader.readBytes();++ const arena = try page.getArena(data.len + mime.len + 256, "Blob.clone");+ errdefer page.releaseArena(arena);++ const self = try arena.create(Blob);+ self.* = .{+ ._rc = .{},+ ._arena = arena,+ ._type = .generic,+ ._slice = try arena.dupe(u8, data),+ // the serialized mime is already in normalized form; copy it verbatim+ ._mime = try arena.dupe(u8, mime),+ };+ return self;+}+const largest_vector = @max(std.simd.suggestVectorLength(u8) orelse 1, 8);/// Array of possible vector sizes for the current arch in decrementing order./// We may move this to some file for SIMD helpers in the future.diff --git a/src/browser/webapi/File.zig b/src/browser/webapi/File.zigindex b71fcb90b..ae00f11c7 100644--- a/src/browser/webapi/File.zig+++ b/src/browser/webapi/File.zig@@ -72,6 +72,29 @@ pub fn acquireRef(self: *File) void {self._proto.acquireRef();}+pub fn structuredSerialize(self: *const File, writer: *js.StructuredWriter) !void {+ try self._proto.structuredSerialize(writer);+ writer.writeBytes(self._name);+ writer.writeUint64(@bitCast(self._last_modified));+}++pub fn structuredDeserialize(reader: *js.StructuredReader, page: *Page) !*File {+ const blob = try Blob.structuredDeserialize(reader, page);+ errdefer blob.deinit(page);++ const name = try reader.readBytes();+ const last_modified = try reader.readUint64();++ const file = try blob._arena.create(File);+ file.* = .{+ ._proto = blob,+ ._name = try blob._arena.dupe(u8, name),+ ._last_modified = @bitCast(last_modified),+ };+ blob._type = .{ .file = file };+ return file;+}+pub fn getName(self: *const File) []const u8 {return self._name;}diff --git a/src/browser/webapi/FileList.zig b/src/browser/webapi/FileList.zigindex c139155ab..e85166c04 100644--- a/src/browser/webapi/FileList.zig+++ b/src/browser/webapi/FileList.zig@@ -1,4 +1,23 @@+// Copyright (C) 2023-2026 Lightpanda (Selecy SAS)+//+// Francis Bouvier <[email protected]>+// Pierre Tachoire <[email protected]>+//+// 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/>.+const js = @import("../js/js.zig");+const Page = @import("../Page.zig");const File = @import("File.zig");@@ -24,6 +43,22 @@ pub fn item(self: *const FileList, index: u32) ?*File {return self._files[index];}+pub fn structuredSerialize(self: *const FileList, writer: *js.StructuredWriter) !void {+ writer.writeUint32(@intCast(self._files.len));+ for (self._files) |file| {+ try file.structuredSerialize(writer);+ }+}++pub fn structuredDeserialize(reader: *js.StructuredReader, page: *Page) !FileList {+ const count = try reader.readUint32();+ const files = try reader.local.ctx.arena.alloc(*File, count);+ for (files) |*file| {+ file.* = try File.structuredDeserialize(reader, page);+ }+ return .{ ._files = files };+}+pub fn iterator(self: *FileList, exec: *const js.Execution) !*Iterator {return Iterator.init(.{.index = 0,diff --git a/src/browser/webapi/ImageData.zig b/src/browser/webapi/ImageData.zigindex 333630e86..1bf39f714 100644--- a/src/browser/webapi/ImageData.zig+++ b/src/browser/webapi/ImageData.zig@@ -20,6 +20,7 @@ const std = @import("std");const lp = @import("lightpanda");const js = @import("../js/js.zig");+const Page = @import("../Page.zig");const String = lp.String;const Execution = js.Execution;@@ -84,6 +85,27 @@ pub fn init(});}+pub fn structuredSerialize(self: *const ImageData, writer: *js.StructuredWriter) !void {+ writer.writeUint32(self._width);+ writer.writeUint32(self._height);+ writer.writeBytes(self._data.local(writer.local).slice());+}++pub fn structuredDeserialize(reader: *js.StructuredReader, page: *Page) !*ImageData {+ const width = try reader.readUint32();+ const height = try reader.readUint32();+ const bytes = try reader.readBytes();++ const data = reader.local.createTypedArray(.uint8_clamped, bytes.len);+ @memcpy(data.slice(), bytes);++ return page.factory.create(ImageData{+ ._width = width,+ ._height = height,+ ._data = try data.persist(),+ });+}+pub fn getWidth(self: *const ImageData) u32 {return self._width;}diff --git a/src/browser/webapi/Window.zig b/src/browser/webapi/Window.zigindex 7a488fac7..c1616f5b0 100644--- a/src/browser/webapi/Window.zig+++ b/src/browser/webapi/Window.zig@@ -705,7 +705,8 @@ pub fn atob(_: *const Window, input: base64.BinInput, frame: *Frame) !js.String.}pub fn structuredClone(_: *const Window, value: js.Value) !js.Value {- return value.structuredClone();+ // the serializer already threw (e.g. a DataCloneError); keep it+ return value.structuredClone() catch error.TryCatchRethrow;}pub fn getFrame(self: *Window, idx: usize) !?*Window {