@swiftbrowser/swift 0.1.0 → 0.2.0

package/Sources/SwiftUI/Localization/PluralRules.swift

@@ -0,0 +1,127 @@
+// CLDR's cardinal plural rules, which pick a `.stringsdict` plural case
+// (`zero`, `one`, `two`, `few`, `many`, `other`) for a count in a language.
+// The operands follow CLDR: `n` the absolute value, `i` its integer digits,
+// `v` whether it has visible fraction digits (a `Double` with a fractional
+// part; the browser cannot tell `1.0` from `1`).
+
+import Foundation
+
+enum _PluralRules {
+    static func category(for value: Double, language tag: String) -> String {
+        let n = abs(value)
+        let i = n.rounded(.towardZero)
+        let fractional = n != i
+        let integer = Int64(clamping: Int(exactly: i) ?? Int.max)
+        let i10 = integer % 10
+        let i100 = integer % 100
+        let language = tag.replacingOccurrences(of: "_", with: "-").lowercased().split(separator: "-").first.map(String.init) ?? ""
+        let millions = !fractional && integer != 0 && integer % 1_000_000 == 0
+
+        switch language {
+        // No plural forms.
+        case "ja", "zh", "ko", "th", "vi", "id", "ms", "my", "lo", "km", "yue", "jv", "su":
+            return "other"
+        case "fr":
+            if !fractional && (integer == 0 || integer == 1) { return "one" }
+            if fractional && i < 2 { return "one" }
+            return millions ? "many" : "other"
+        case "pt":
+            if tag.lowercased().hasPrefix("pt-pt") {
+                if !fractional && integer == 1 { return "one" }
+                return millions ? "many" : "other"
+            }
+            if i < 2 { return "one" }
+            return millions ? "many" : "other"
+        case "es", "it", "ca":
+            if !fractional && integer == 1 { return "one" }
+            return millions ? "many" : "other"
+        case "ru", "uk", "be":
+            if fractional { return "other" }
+            if i10 == 1 && i100 != 11 { return "one" }
+            if (2...4).contains(i10) && !(12...14).contains(i100) { return "few" }
+            return "many"
+        case "pl":
+            if fractional { return "other" }
+            if integer == 1 { return "one" }
+            if (2...4).contains(i10) && !(12...14).contains(i100) { return "few" }
+            return "many"
+        case "cs", "sk":
+            if fractional { return "many" }
+            if integer == 1 { return "one" }
+            if (2...4).contains(integer) { return "few" }
+            return "other"
+        case "hr", "sr", "bs", "sh":
+            if fractional { return "other" }
+            if i10 == 1 && i100 != 11 { return "one" }
+            if (2...4).contains(i10) && !(12...14).contains(i100) { return "few" }
+            return "other"
+        case "lt":
+            if fractional { return "many" }
+            if i10 == 1 && !(11...19).contains(i100) { return "one" }
+            if (2...9).contains(i10) && !(11...19).contains(i100) { return "few" }
+            return "other"
+        case "lv":
+            if fractional { return "other" }
+            if i10 == 0 || (11...19).contains(i100) { return "zero" }
+            if i10 == 1 && i100 != 11 { return "one" }
+            return "other"
+        case "ro", "mo":
+            if !fractional && integer == 1 { return "one" }
+            if fractional || integer == 0 || (2...19).contains(i100) { return "few" }
+            return "other"
+        case "sl":
+            if fractional { return "few" }
+            if i100 == 1 { return "one" }
+            if i100 == 2 { return "two" }
+            if i100 == 3 || i100 == 4 { return "few" }
+            return "other"
+        case "ar":
+            if fractional { return "other" }
+            if integer == 0 { return "zero" }
+            if integer == 1 { return "one" }
+            if integer == 2 { return "two" }
+            if (3...10).contains(i100) { return "few" }
+            if (11...99).contains(i100) { return "many" }
+            return "other"
+        case "he", "iw":
+            if !fractional && integer == 1 { return "one" }
+            if !fractional && integer == 2 { return "two" }
+            return "other"
+        case "ga":
+            if fractional { return "other" }
+            switch integer {
+            case 1: return "one"
+            case 2: return "two"
+            case 3...6: return "few"
+            case 7...10: return "many"
+            default: return "other"
+            }
+        case "cy":
+            if fractional { return "other" }
+            switch integer {
+            case 0: return "zero"
+            case 1: return "one"
+            case 2: return "two"
+            case 3: return "few"
+            case 6: return "many"
+            default: return "other"
+            }
+        case "da":
+            if n == 1 || (fractional && (i == 0 || i == 1)) { return "one" }
+            return "other"
+        case "is":
+            if !fractional && i10 == 1 && i100 != 11 { return "one" }
+            return "other"
+        case "mk":
+            if !fractional && i10 == 1 && i100 != 11 { return "one" }
+            return "other"
+        case "hi", "bn", "gu", "kn", "mr", "fa", "zu", "am":
+            if i == 0 || n == 1 { return "one" }
+            return "other"
+        default:
+            // English and most languages: one for exactly 1.
+            if !fractional && integer == 1 { return "one" }
+            return "other"
+        }
+    }
+}

package/Sources/SwiftUI/Runtime/Executor.swift

@@ -64,6 +64,8 @@ final class _HostExecutor: MainExecutor, SchedulingExecutor, TaskExecutor, @unch
     }
 
     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 {

package/Sources/SwiftUI/Runtime/Exports.swift

@@ -23,6 +23,42 @@ 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 {
@@ -41,7 +77,7 @@ public func _sb_event_json(_ pointer: Int32, _ length: Int32) {
             print("[SwiftUI] ignoring malformed event: \(text)")
             return
         }
-        _Runtime.shared.dispatch(event: event)
+        _Runtime.shared.dispatch(event: _BytesInbox.shared.resolve(event))
     }
 }
 

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

@@ -8,14 +8,25 @@ public enum _JSON: Equatable, Sendable {
     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)
+        write(into: &out, outbox: nil)
         return out
     }
 
-    private func write(into out: inout String) {
+    /// 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"
@@ -35,7 +46,7 @@ public enum _JSON: Equatable, Sendable {
             out += "["
             for (index, item) in items.enumerated() {
                 if index > 0 { out += "," }
-                item.write(into: &out)
+                item.write(into: &out, outbox: outbox)
             }
             out += "]"
         case .object(let members):
@@ -44,9 +55,17 @@ public enum _JSON: Equatable, Sendable {
                 if index > 0 { out += "," }
                 _JSON.writeString(key, into: &out)
                 out += ":"
-                members[key]!.write(into: &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 += "\""
+            }
         }
     }
 
@@ -69,3 +88,56 @@ public enum _JSON: Equatable, Sendable {
         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
+        }
+    }
+}