@swiftbrowser/swift 0.0.0-stage → 0.2.0

package/Sources/SwiftUI/Runtime/Executor.swift

@@ -0,0 +1,85 @@
+@_spi(ExperimentalCustomExecutors) @_spi(ExperimentalScheduling) import _Concurrency
+
+/// A host-driven cooperative executor. Jobs created by `Task`, `.task` and
+/// sleeps queue here until the host calls `sb_run_jobs`; delays become
+/// timers against a clock the host sets (real time in the browser, a
+/// virtual clock in headless mode). See docs/ops-protocol.md (Phase 4).
+final class _HostExecutor: MainExecutor, SchedulingExecutor, TaskExecutor, @unchecked Sendable {
+    static let shared = _HostExecutor()
+
+    private var queue: [UnownedJob] = []
+    private var timers: [(deadlineNs: UInt64, job: UnownedJob)] = []
+    /// The executor's clock in nanoseconds; origin is arbitrary.
+    var nowNs: UInt64 = 0
+
+    func enqueue(_ job: consuming ExecutorJob) {
+        queue.append(UnownedJob(job))
+    }
+
+    func run() throws {}
+    func stop() {}
+    func checkIsolated() {}
+    func isIsolatingCurrentContext() -> Bool? { true }
+
+    func enqueue<C: Clock>(_ job: consuming ExecutorJob, after delay: C.Duration, tolerance: C.Duration?, clock: C) {
+        timers.append((nowNs + nanoseconds(of: delay), UnownedJob(job)))
+    }
+
+    func enqueue<C: Clock>(_ job: consuming ExecutorJob, at instant: C.Instant, tolerance: C.Duration?, clock: C) {
+        let delay = clock.now.duration(to: instant)
+        timers.append((nowNs + nanoseconds(of: delay), UnownedJob(job)))
+    }
+
+    /// Delays are rounded so timers stay aligned and headless runs are
+    /// deterministic.
+    private func nanoseconds<D: DurationProtocol>(of duration: D) -> UInt64 {
+        guard let duration = duration as? Duration else { return 0 }
+        let (seconds, attoseconds) = duration.components
+        let ns = Double(max(0, seconds)) * 1e9 + Double(max(0, attoseconds)) / 1e9
+        // 10 ms granularity: the WASI clock is coarse, and `Task.sleep(for:)`
+        // computes an absolute instant from it before we see the delay.
+        return UInt64((ns / 1e7).rounded() * 1e7)
+    }
+
+    /// Runs every queued job and every due timer, repeatedly, until the
+    /// queue is empty. Returns nanoseconds until the next timer, or -1.
+    func runJobs() -> Int64 {
+        var ran = 0
+        repeat {
+            ran = 0
+            while !queue.isEmpty {
+                let job = queue.removeFirst()
+                job.runSynchronously(on: asUnownedSerialExecutor())
+                ran += 1
+            }
+            timers.sort { $0.deadlineNs < $1.deadlineNs }
+            while let first = timers.first, first.deadlineNs <= nowNs {
+                timers.removeFirst()
+                queue.append(first.job)
+                ran += 1
+            }
+        } while ran > 0
+        guard let next = timers.first else { return -1 }
+        return Int64(next.deadlineNs - nowNs)
+    }
+
+    var hasTimers: Bool { !timers.isEmpty }
+    /// Whether jobs are waiting to run now (enqueued since the last `runJobs`).
+    var hasQueuedJobs: Bool { !queue.isEmpty }
+}
+
+enum _HostExecutorFactory: ExecutorFactory {
+    static var mainExecutor: any MainExecutor { _HostExecutor.shared }
+    static var defaultExecutor: any TaskExecutor { _HostExecutor.shared }
+}
+
+nonisolated(unsafe) private var executorInstalled = false
+
+/// Installs the host-driven executor. Must run before any task is created;
+/// `App.main()` calls it. Native test processes must not install it, since
+/// the test runner drives the main actor itself.
+public func _installHostExecutor() {
+    guard !executorInstalled else { return }
+    executorInstalled = true
+    _createExecutors(factory: _HostExecutorFactory.self)
+}

package/Sources/SwiftUI/Runtime/Exports.swift

@@ -0,0 +1,101 @@
+// C-ABI entry points for the browser renderer. See docs/ops-protocol.md.
+// Wasm is single-threaded, so the main actor is the only executor.
+
+@_cdecl("sb_event")
+public func _sb_event(_ id: Int32) {
+    MainActor.assumeIsolated {
+        _Runtime.shared.dispatch(tap: Int(id))
+    }
+}
+
+@_cdecl("sb_ops_ptr")
+public func _sb_ops_ptr() -> Int32 {
+    MainActor.assumeIsolated { _BufferedHost.shared.pointer }
+}
+
+@_cdecl("sb_ops_len")
+public func _sb_ops_len() -> Int32 {
+    MainActor.assumeIsolated { _BufferedHost.shared.length }
+}
+
+@_cdecl("sb_ops_clear")
+public func _sb_ops_clear() {
+    MainActor.assumeIsolated { _BufferedHost.shared.clear() }
+}
+
+/// The number of byte buffers beside the pending ops (`{"$bytes": n}` values).
+@_cdecl("sb_bytes_count")
+public func _sb_bytes_count() -> Int32 {
+    MainActor.assumeIsolated { Int32(_BufferedHost.shared.bytes.count) }
+}
+
+/// Where the pending ops' `n`th byte buffer starts in linear memory.
+@_cdecl("sb_bytes_ptr")
+public func _sb_bytes_ptr(_ index: Int32) -> Int32 {
+    MainActor.assumeIsolated {
+        let items = _BufferedHost.shared.bytes
+        guard items.indices.contains(Int(index)) else { return 0 }
+        return Int32(Int(bitPattern: items[Int(index)].baseAddress))
+    }
+}
+
+/// The length of the pending ops' `n`th byte buffer.
+@_cdecl("sb_bytes_len")
+public func _sb_bytes_len(_ index: Int32) -> Int32 {
+    MainActor.assumeIsolated {
+        let items = _BufferedHost.shared.bytes
+        guard items.indices.contains(Int(index)) else { return 0 }
+        return Int32(items[Int(index)].count)
+    }
+}
+
+/// Takes a buffer from `sb_alloc` that the renderer filled with bytes for
+/// the next event, and answers the `n` the event names them by (`{"$bytes": n}`).
+@_cdecl("sb_bytes")
+public func _sb_bytes(_ pointer: Int32, _ length: Int32) -> Int32 {
+    guard let base = UnsafeMutablePointer<UInt8>(bitPattern: Int(pointer)) else { return 0 }
+    let bytes = Array(UnsafeBufferPointer(start: base, count: Int(length)))
+    base.deallocate()
+    return MainActor.assumeIsolated { Int32(_BytesInbox.shared.add(bytes)) }
+}
+
+/// Allocates a buffer the renderer fills before calling `sb_event_json`.
+@_cdecl("sb_alloc")
+public func _sb_alloc(_ length: Int32) -> Int32 {
+    let pointer = UnsafeMutablePointer<UInt8>.allocate(capacity: Int(max(length, 1)))
+    return Int32(Int(bitPattern: pointer))
+}
+
+/// Delivers one UTF-8 JSON event written into a buffer from `sb_alloc`.
+@_cdecl("sb_event_json")
+public func _sb_event_json(_ pointer: Int32, _ length: Int32) {
+    guard let base = UnsafeMutablePointer<UInt8>(bitPattern: Int(pointer)) else { return }
+    let text = String(decoding: UnsafeBufferPointer(start: base, count: Int(length)), as: UTF8.self)
+    base.deallocate()
+    MainActor.assumeIsolated {
+        guard let event = try? _JSON.parse(text) else {
+            print("[SwiftUI] ignoring malformed event: \(text)")
+            return
+        }
+        _Runtime.shared.dispatch(event: _BytesInbox.shared.resolve(event))
+    }
+}
+
+@_cdecl("sb_state_ptr")
+public func _sb_state_ptr() -> Int32 {
+    MainActor.assumeIsolated {
+        _StateBuffer.shared.refresh(with: _Runtime.shared.snapshot())
+        return _StateBuffer.shared.pointer
+    }
+}
+
+@_cdecl("sb_state_len")
+public func _sb_state_len() -> Int32 {
+    MainActor.assumeIsolated { _StateBuffer.shared.length }
+}
+
+/// Drives Swift concurrency: see `_Runtime.runJobs(nowMilliseconds:)`.
+@_cdecl("sb_run_jobs")
+public func _sb_run_jobs(_ nowMilliseconds: Double) -> Double {
+    MainActor.assumeIsolated { _Runtime.shared.runJobs(nowMilliseconds: nowMilliseconds) }
+}

package/Sources/SwiftUI/Runtime/ImageSource.swift

@@ -0,0 +1,310 @@
+import Foundation
+
+// Bitmaps (`UIImage`, `CGImage`, Core Image's `CIImage`) never hold decoded
+// pixels in Swift. Each is a recipe: a source (an encoded file's bytes, or a
+// small pixel buffer a generator made) plus the Core Image steps applied to
+// it, in order. The page decodes the source and runs the steps when it draws
+// the image (Web/src/bitmaps.ts, docs/ops-protocol.md, "Bitmaps and Core
+// Image"). Swift only needs sizes, which it reads from the file's header, so
+// `UIImage(data:)` stays synchronous as on iOS while the browser decodes
+// asynchronously.
+
+/// What an encoded image's header says: its media type and its pixel size,
+/// with the EXIF (JPEG) or `irot` (HEIF) rotation applied, as browsers draw it.
+public struct _ImageHeader: Equatable, Sendable {
+    public let mime: String
+    public let width: Int
+    public let height: Int
+
+    public init(mime: String, width: Int, height: Int) {
+        self.mime = mime
+        self.width = width
+        self.height = height
+    }
+
+    /// The header of a PNG, JPEG, GIF, WebP, BMP, HEIC or AVIF file; nil for
+    /// anything else, or a header too short or malformed to give a size.
+    public static func parse(_ bytes: [UInt8]) -> _ImageHeader? {
+        let reader = _ByteReader(bytes)
+        let parsed = parsePNG(reader) ?? parseJPEG(reader) ?? parseGIF(reader) ?? parseWebP(reader)
+            ?? parseBMP(reader) ?? parseHEIF(reader)
+        guard let parsed, parsed.width > 0, parsed.height > 0 else { return nil }
+        return parsed
+    }
+
+    private static func parsePNG(_ r: _ByteReader) -> _ImageHeader? {
+        guard r.matches([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A], at: 0), r.matches(Array("IHDR".utf8), at: 12),
+              let width = r.u32be(16), let height = r.u32be(20) else { return nil }
+        return _ImageHeader(mime: "image/png", width: Int(width), height: Int(height))
+    }
+
+    private static func parseGIF(_ r: _ByteReader) -> _ImageHeader? {
+        guard r.matches(Array("GIF87a".utf8), at: 0) || r.matches(Array("GIF89a".utf8), at: 0),
+              let width = r.u16le(6), let height = r.u16le(8) else { return nil }
+        return _ImageHeader(mime: "image/gif", width: Int(width), height: Int(height))
+    }
+
+    private static func parseBMP(_ r: _ByteReader) -> _ImageHeader? {
+        guard r.matches(Array("BM".utf8), at: 0), let width = r.u32le(18), let height = r.u32le(22) else { return nil }
+        // The height is negative for a top-down bitmap.
+        return _ImageHeader(mime: "image/bmp", width: Int(Int32(bitPattern: width).magnitude), height: Int(Int32(bitPattern: height).magnitude))
+    }
+
+    private static func parseWebP(_ r: _ByteReader) -> _ImageHeader? {
+        guard r.matches(Array("RIFF".utf8), at: 0), r.matches(Array("WEBP".utf8), at: 8) else { return nil }
+        if r.matches(Array("VP8 ".utf8), at: 12) {
+            // Lossy: a key frame's start code, then 14-bit width and height.
+            guard r.matches([0x9D, 0x01, 0x2A], at: 23), let width = r.u16le(26), let height = r.u16le(28) else { return nil }
+            return _ImageHeader(mime: "image/webp", width: Int(width & 0x3FFF), height: Int(height & 0x3FFF))
+        }
+        if r.matches(Array("VP8L".utf8), at: 12) {
+            // Lossless: a signature byte, then width - 1 and height - 1 in 14 bits each.
+            guard r.byte(20) == 0x2F, let b0 = r.byte(21), let b1 = r.byte(22), let b2 = r.byte(23), let b3 = r.byte(24) else { return nil }
+            let width = 1 + (Int(b0) | (Int(b1 & 0x3F) << 8))
+            let height = 1 + ((Int(b1) >> 6) | (Int(b2) << 2) | (Int(b3 & 0x0F) << 10))
+            return _ImageHeader(mime: "image/webp", width: width, height: height)
+        }
+        if r.matches(Array("VP8X".utf8), at: 12) {
+            // Extended: the canvas size, minus one, in 24 bits each.
+            guard let width = r.u24le(24), let height = r.u24le(27) else { return nil }
+            return _ImageHeader(mime: "image/webp", width: Int(width) + 1, height: Int(height) + 1)
+        }
+        return nil
+    }
+
+    private static func parseJPEG(_ r: _ByteReader) -> _ImageHeader? {
+        guard r.matches([0xFF, 0xD8], at: 0) else { return nil }
+        var index = 2
+        var orientation = 1
+        while index + 4 <= r.count {
+            guard r.byte(index) == 0xFF, let marker = r.byte(index + 1) else { return nil }
+            if marker == 0xFF { index += 1; continue } // fill byte
+            index += 2
+            // Markers without a length: TEM, RSTn, SOI.
+            if marker == 0x01 || (0xD0...0xD8).contains(marker) { continue }
+            // End of image or start of scan before any frame header: no size.
+            if marker == 0xD9 || marker == 0xDA { return nil }
+            guard let length = r.u16be(index), length >= 2 else { return nil }
+            if marker == 0xE1, let value = exifOrientation(r, segment: index + 2, length: Int(length) - 2) {
+                orientation = value
+            }
+            // SOF0...SOF15, except DHT (C4), JPG (C8) and DAC (CC).
+            if (0xC0...0xCF).contains(marker), marker != 0xC4, marker != 0xC8, marker != 0xCC {
+                guard let height = r.u16be(index + 3), let width = r.u16be(index + 5) else { return nil }
+                // Orientations 5 to 8 turn the picture a quarter: browsers draw it (and
+                // UIImage reports it) with width and height swapped.
+                let turned = orientation >= 5 && orientation <= 8
+                return _ImageHeader(mime: "image/jpeg", width: Int(turned ? height : width), height: Int(turned ? width : height))
+            }
+            index += Int(length)
+        }
+        return nil
+    }
+
+    /// The orientation tag (0x0112) of an APP1 Exif segment's first IFD.
+    private static func exifOrientation(_ r: _ByteReader, segment: Int, length: Int) -> Int? {
+        guard length > 14, r.matches(Array("Exif".utf8) + [0, 0], at: segment) else { return nil }
+        let tiff = segment + 6
+        let little: Bool
+        if r.matches(Array("II".utf8), at: tiff) { little = true }
+        else if r.matches(Array("MM".utf8), at: tiff) { little = false }
+        else { return nil }
+        let u16 = { (at: Int) in little ? r.u16le(at) : r.u16be(at) }
+        let u32 = { (at: Int) in little ? r.u32le(at) : r.u32be(at) }
+        guard let ifd = u32(tiff + 4), let count = u16(tiff + Int(ifd)) else { return nil }
+        for entry in 0..<Int(count) {
+            let at = tiff + Int(ifd) + 2 + entry * 12
+            guard at + 12 <= segment + length, let tag = u16(at) else { return nil }
+            if tag == 0x0112, let value = u16(at + 8) { return Int(value) }
+        }
+        return nil
+    }
+
+    /// HEIC and AVIF (ISO base media files): the largest `ispe` (image spatial
+    /// extent) property is the primary image's size; an `irot` of a quarter
+    /// or three quarters swaps it.
+    private static func parseHEIF(_ r: _ByteReader) -> _ImageHeader? {
+        guard r.matches(Array("ftyp".utf8), at: 4), let boxSize = r.u32be(0) else { return nil }
+        let brands = Set(stride(from: 8, to: min(Int(boxSize), r.count) - 3, by: 4).compactMap { at -> String? in
+            guard at != 12, let bytes = r.slice(at, 4) else { return nil } // 12: the minor version
+            return String(decoding: bytes, as: UTF8.self)
+        })
+        let isAVIF = !brands.isDisjoint(with: ["avif", "avis"])
+        guard isAVIF || !brands.isDisjoint(with: ["heic", "heix", "hevc", "hevx", "heim", "heis", "mif1", "msf1"]) else { return nil }
+        var best: (width: Int, height: Int)?
+        var turned = false
+        let ispe = Array("ispe".utf8), irot = Array("irot".utf8)
+        // The `meta` box is near the start; the image data comes after it.
+        let limit = min(r.count, 1 << 20)
+        var at = 4
+        while at + 5 <= limit {
+            if r.matches(ispe, at: at), let width = r.u32be(at + 8), let height = r.u32be(at + 12) {
+                if Int(width) * Int(height) > (best.map { $0.width * $0.height } ?? 0) { best = (Int(width), Int(height)) }
+                at += 16
+                continue
+            }
+            if r.matches(irot, at: at), let angle = r.byte(at + 4) { turned = (angle & 0x03) % 2 == 1 }
+            at += 1
+        }
+        guard let best else { return nil }
+        return _ImageHeader(mime: isAVIF ? "image/avif" : "image/heic",
+                            width: turned ? best.height : best.width, height: turned ? best.width : best.height)
+    }
+}
+
+/// Bounds-checked reads from a byte array; every read past the end is nil.
+struct _ByteReader {
+    let bytes: [UInt8]
+    init(_ bytes: [UInt8]) { self.bytes = bytes }
+
+    var count: Int { bytes.count }
+    func byte(_ at: Int) -> UInt8? { at >= 0 && at < bytes.count ? bytes[at] : nil }
+    func slice(_ at: Int, _ length: Int) -> ArraySlice<UInt8>? {
+        at >= 0 && length >= 0 && at + length <= bytes.count ? bytes[at..<(at + length)] : nil
+    }
+    func matches(_ pattern: [UInt8], at: Int) -> Bool { slice(at, pattern.count).map { $0.elementsEqual(pattern) } ?? false }
+    func u16be(_ at: Int) -> UInt16? { slice(at, 2).map { UInt16($0[at]) << 8 | UInt16($0[at + 1]) } }
+    func u16le(_ at: Int) -> UInt16? { slice(at, 2).map { UInt16($0[at + 1]) << 8 | UInt16($0[at]) } }
+    func u24le(_ at: Int) -> UInt32? { slice(at, 3).map { UInt32($0[at + 2]) << 16 | UInt32($0[at + 1]) << 8 | UInt32($0[at]) } }
+    func u32be(_ at: Int) -> UInt32? {
+        slice(at, 4).map { UInt32($0[at]) << 24 | UInt32($0[at + 1]) << 16 | UInt32($0[at + 2]) << 8 | UInt32($0[at + 3]) }
+    }
+    func u32le(_ at: Int) -> UInt32? {
+        slice(at, 4).map { UInt32($0[at + 3]) << 24 | UInt32($0[at + 2]) << 16 | UInt32($0[at + 1]) << 8 | UInt32($0[at]) }
+    }
+}
+
+/// Where a bitmap's pixels come from: an encoded image file, or a pixel
+/// buffer (one gray or four RGBA bytes per pixel, rows from the top). The
+/// page receives it once, in an `imagedata` op, under its `key` (a hash of
+/// the content, so the same bytes are sent once however many images use them).
+public final class _ImageSource: Equatable, @unchecked Sendable {
+    public enum PixelFormat: String, Sendable {
+        case gray, rgba
+    }
+
+    enum Payload {
+        case encoded([UInt8], mime: String)
+        case pixels([UInt8], PixelFormat)
+    }
+
+    public let key: String
+    /// The size in pixels, as the page draws it (orientation applied).
+    public let width: Int
+    public let height: Int
+    let payload: Payload
+
+    /// An encoded image file; nil when its header is not one the page can draw.
+    public init?(encoded bytes: [UInt8]) {
+        guard let header = _ImageHeader.parse(bytes) else { return nil }
+        key = "f" + _fnv1a(bytes)
+        width = header.width
+        height = header.height
+        payload = .encoded(bytes, mime: header.mime)
+    }
+
+    /// A pixel buffer: `width * height` bytes for `.gray`, four times that
+    /// (straight, not premultiplied, alpha) for `.rgba`.
+    public init(pixels: [UInt8], width: Int, height: Int, format: PixelFormat) {
+        precondition(pixels.count == width * height * (format == .gray ? 1 : 4), "pixel buffer size does not match \(width)×\(height) \(format)")
+        key = "p" + _fnv1a(pixels + Array("\(width)x\(height)\(format.rawValue)".utf8))
+        self.width = width
+        self.height = height
+        payload = .pixels(pixels, format)
+    }
+
+    public static func == (lhs: _ImageSource, rhs: _ImageSource) -> Bool { lhs.key == rhs.key }
+
+    /// The media type of an encoded source; nil for pixels.
+    public var mime: String? {
+        if case .encoded(_, let mime) = payload { return mime }
+        return nil
+    }
+
+    /// The `imagedata` op's fields.
+    var json: _JSON {
+        var fields: [String: _JSON] = ["key": .string(key), "width": .number(Double(width)), "height": .number(Double(height))]
+        switch payload {
+        case .encoded(let bytes, let mime):
+            fields["mime"] = .string(mime)
+            fields["data"] = .bytes(bytes)
+        case .pixels(let bytes, let format):
+            fields["format"] = .string(format.rawValue)
+            fields["pixels"] = .bytes(bytes)
+        }
+        return .object(fields)
+    }
+}
+
+/// A bitmap as the page will draw it: its source and the Core Image steps
+/// applied to it. `extent` is Core Image's: in source pixels, origin at the
+/// bottom left, possibly infinite (`clampedToExtent()`). A `CGImage`'s
+/// recipe ends at its own pixel grid: its extent is `(0, 0, width, height)`.
+public struct _ImageRecipe: Equatable, Sendable {
+    /// Nil for an empty image (`UIImage()`, `CIImage.empty()`).
+    public let source: _ImageSource?
+    /// Each step is an object whose `op` names it (docs/ops-protocol.md).
+    public let steps: [_JSON]
+    public let extent: CGRect
+    /// The frame of an animated source (a GIF) the steps start from, whole as
+    /// the file's earlier frames leave the canvas; nil for the file as it is
+    /// (its first frame).
+    public let frame: Int?
+
+    public init(source: _ImageSource?, steps: [_JSON] = [], extent: CGRect, frame: Int? = nil) {
+        self.source = source
+        self.steps = steps
+        self.extent = extent
+        self.frame = frame
+    }
+
+    /// The source on its own: extent `(0, 0, width, height)`.
+    public init(source: _ImageSource, frame: Int? = nil) {
+        self.init(source: source, extent: CGRect(x: 0, y: 0, width: Double(source.width), height: Double(source.height)), frame: frame)
+    }
+
+    public static let empty = _ImageRecipe(source: nil, extent: .null)
+
+    /// This recipe followed by `step`, which gives the image `extent`.
+    public func adding(_ step: _JSON, extent: CGRect) -> _ImageRecipe {
+        _ImageRecipe(source: source, steps: steps + [step], extent: extent, frame: frame)
+    }
+
+    /// The image inside `rect` (Core Image coordinates) as a bitmap of its own,
+    /// `(0, 0, width, height)` in pixels: clear where the image does not reach
+    /// (`CIContext.createCGImage(_:from:)`). Nil for an infinite or empty rect.
+    public func rendered(in rect: CGRect) -> _ImageRecipe? {
+        guard !rect.isInfinite, !rect.isNull else { return nil }
+        let box = rect.integral
+        guard box.width >= 1, box.height >= 1 else { return nil }
+        let step: _JSON = .object(["op": .string("render"), "x": .number(box.minX), "y": .number(box.minY),
+                                   "width": .number(box.width), "height": .number(box.height)])
+        return adding(step, extent: CGRect(x: 0, y: 0, width: box.width, height: box.height))
+    }
+
+    /// The `bitmap` prop of an `image` element: the source's key, the frame
+    /// of an animated one, and the steps; `width` / `height` are the result's
+    /// size in pixels.
+    var json: _JSON {
+        let finite = !extent.isNull && !extent.isInfinite
+        var fields: [String: _JSON] = [
+            "source": source.map { .string($0.key) } ?? .null,
+            "steps": .array(steps),
+            "width": .number(finite ? extent.width : 0),
+            "height": .number(finite ? extent.height : 0),
+        ]
+        if let frame { fields["frame"] = .number(Double(frame)) }
+        return .object(fields)
+    }
+}
+
+/// FNV-1a, 64 bits, as 16 hex digits: content keys for image sources.
+func _fnv1a(_ bytes: [UInt8]) -> String {
+    var hash: UInt64 = 0xCBF2_9CE4_8422_2325
+    for byte in bytes {
+        hash ^= UInt64(byte)
+        hash = hash &* 0x0000_0100_0000_01B3
+    }
+    let hex = String(hash, radix: 16)
+    return String(repeating: "0", count: 16 - hex.count) + hex
+}

package/Sources/SwiftUI/Runtime/JSON.swift

@@ -0,0 +1,143 @@
+/// A minimal JSON value. The shim avoids Foundation (see Geometry.swift), so it
+/// carries its own serializer. Object keys serialize in sorted order so the
+/// output is byte-stable for snapshot tests.
+public enum _JSON: Equatable, Sendable {
+    case null
+    case bool(Bool)
+    case number(Double)
+    case string(String)
+    case array([_JSON])
+    case object([String: _JSON])
+    /// Raw bytes: a fetched body, an image file. Serialized as a base64
+    /// string, except into the browser's ops buffer, where they pass through
+    /// linear memory as `{"$bytes": n}` (docs/ops-protocol.md, "Bytes").
+    case bytes([UInt8])
+
+    public var serialized: String {
+        var out = ""
+        write(into: &out, outbox: nil)
+        return out
+    }
+
+    /// Serialized with `.bytes` values moved to `outbox`, each written as `{"$bytes": n}`.
+    func serialized(outbox: _BytesOutbox) -> String {
+        var out = ""
+        write(into: &out, outbox: outbox)
+        return out
+    }
+
+    private func write(into out: inout String, outbox: _BytesOutbox?) {
+        switch self {
+        case .null:
+            out += "null"
+        case .bool(let value):
+            out += value ? "true" : "false"
+        case .number(let value):
+            if value.isFinite, value == value.rounded(), abs(value) < 1e15 {
+                out += String(Int64(value))
+            } else if value.isFinite {
+                out += "\(value)"
+            } else {
+                out += "null"
+            }
+        case .string(let value):
+            _JSON.writeString(value, into: &out)
+        case .array(let items):
+            out += "["
+            for (index, item) in items.enumerated() {
+                if index > 0 { out += "," }
+                item.write(into: &out, outbox: outbox)
+            }
+            out += "]"
+        case .object(let members):
+            out += "{"
+            for (index, key) in members.keys.sorted().enumerated() {
+                if index > 0 { out += "," }
+                _JSON.writeString(key, into: &out)
+                out += ":"
+                members[key]!.write(into: &out, outbox: outbox)
+            }
+            out += "}"
+        case .bytes(let bytes):
+            if let outbox {
+                out += "{\"$bytes\":\(outbox.add(bytes))}"
+            } else {
+                out += "\""
+                out += _base64(bytes)
+                out += "\""
+            }
+        }
+    }
+
+    private static func writeString(_ value: String, into out: inout String) {
+        out += "\""
+        for scalar in value.unicodeScalars {
+            switch scalar {
+            case "\"": out += "\\\""
+            case "\\": out += "\\\\"
+            case "\n": out += "\\n"
+            case "\r": out += "\\r"
+            case "\t": out += "\\t"
+            case _ where scalar.value < 0x20:
+                let hex = String(scalar.value, radix: 16)
+                out += "\\u" + String(repeating: "0", count: 4 - hex.count) + hex
+            default:
+                out.unicodeScalars.append(scalar)
+            }
+        }
+        out += "\""
+    }
+}
+
+/// Bytes on their way to the page beside the ops buffer (`sb_bytes_*`
+/// exports): the `n` of each `{"$bytes": n}` in the ops is an index here.
+final class _BytesOutbox {
+    private(set) var items: [UnsafeMutableBufferPointer<UInt8>] = []
+
+    func add(_ bytes: [UInt8]) -> Int {
+        let buffer = UnsafeMutableBufferPointer<UInt8>.allocate(capacity: max(bytes.count, 1))
+        _ = buffer.initialize(from: bytes)
+        items.append(UnsafeMutableBufferPointer(rebasing: buffer[0..<bytes.count]))
+        return items.count - 1
+    }
+
+    func removeAll() {
+        for item in items { item.deallocate() }
+        items.removeAll()
+    }
+}
+
+/// Bytes the page put in linear memory for the next `sb_event_json` (the
+/// `sb_bytes` export), by the `n` of the event's `{"$bytes": n}` values.
+@MainActor
+final class _BytesInbox {
+    static let shared = _BytesInbox()
+    private var items: [Int: [UInt8]] = [:]
+    private var nextID = 1
+
+    func add(_ bytes: [UInt8]) -> Int {
+        let id = nextID
+        nextID += 1
+        items[id] = bytes
+        return id
+    }
+
+    /// `event` with each `{"$bytes": n}` replaced by its bytes; whatever it did not name is dropped.
+    func resolve(_ event: _JSON) -> _JSON {
+        guard !items.isEmpty else { return event }
+        defer { items.removeAll() }
+        return replace(event)
+    }
+
+    private func replace(_ value: _JSON) -> _JSON {
+        switch value {
+        case .object(let members):
+            if members.count == 1, case .number(let n)? = members["$bytes"], let bytes = items[Int(n)] { return .bytes(bytes) }
+            return .object(members.mapValues(replace))
+        case .array(let items):
+            return .array(items.map(replace))
+        default:
+            return value
+        }
+    }
+}