@swiftbrowser/native 0.19.0 → 0.21.0

package/swift/Packages/SwiftBrowserDSP/Sources/SwiftBrowserDSPCore/Program.swift

@@ -6,6 +6,10 @@ import Foundation
 /// voice; `block` runs once per block of up to 128 frames and `sample` once
 /// per frame, each a flat list of instructions: an opcode, a destination
 /// register, the opcode's operands and, for a stateful builtin, its instance.
+/// A voice may have a right side (`outputRight`), and the `master` stage
+/// runs after the voices (in lane 0). The machine runs `sample` and `master`
+/// a chunk of frames at a time, all but their `serial` parts (word offsets),
+/// which touch state and run frame by frame (block processing).
 public struct DSPProgram: Sendable, Equatable {
     public struct Parameter: Sendable, Equatable {
         public let name: String
@@ -19,30 +23,109 @@ public struct DSPProgram: Sendable, Equatable {
         public let name: String
         public let register: Int
         public let initial: Float
+        /// The master stage's: reset when the program loads and on `reset`, not when a voice starts.
+        public var master = false
+    }
+
+    /// A wavetable: its frames, each the amplitudes of its sine harmonics from the fundamental up, and with
+    /// `cosines` (one list a frame, each as long as its frame's) their cosine parts.
+    public struct Table: Sendable, Equatable {
+        public let name: String
+        public let frames: [[Float]]
+        public var cosines: [[Float]]? = nil
+    }
+
+    /// A drawn curve: values at evenly spaced points from x = 0 to x = 1.
+    public struct Shape: Sendable, Equatable {
+        public let name: String
+        public let points: [Float]
+    }
+
+    /// Audio: mono, `rate` samples a second.
+    public struct Sample: Sendable, Equatable {
+        public let name: String
+        public let rate: Double
+        public let data: [Float]
+    }
+
+    /// The master stage: the voices' sum goes into `inputs` (left, right) each frame, `code` runs in lane 0, and
+    /// `outputs` is the program's output. Its notes are the newest one's (registers 7 … 10), and its envelopes start
+    /// over at every note.
+    public struct Master: Sendable, Equatable {
+        public let code: [Int32]
+        /// The part of `code` that runs frame by frame, in words.
+        public let serial: Range<Int>?
+        public let inputs: [Int]
+        public let outputs: [Int]
+    }
+
+    /// One voice playing the newest held note: `mono` starts its envelopes over at each note, `legato` only when
+    /// no other note was held.
+    public enum Mode: String, Sendable, Equatable {
+        case mono, legato
     }
 
     public let voices: Int
+    /// Absent, polyphonic.
+    public let mode: Mode?
     public let registers: Int
     public let constants: [(register: Int, value: Float)]
     public let parameters: [Parameter]
     public let state: [State]
     public let instances: [DSPBuiltin]
+    public let tables: [Table]
+    public let shapes: [Shape]
+    public let samples: [Sample]
+    /// `modsum`'s route lists: a source's register, then its amount's, pair after pair.
+    public let routes: [[Int]]
+    /// Envelopes with curves (program.ts `curves`): an `adsr` instance and its attack, decay and release exponents.
+    public let curves: [Curve]
     public let block: [Int32]
     public let sample: [Int32]
+    /// The part of `sample` that runs frame by frame, in words.
+    public let serial: Range<Int>?
+    /// The voice's left side, or both with no `outputRight`.
     public let output: Int
+    public let outputRight: Int?
+    public let master: Master?
 
     public static func == (a: DSPProgram, b: DSPProgram) -> Bool {
-        a.voices == b.voices && a.registers == b.registers && a.constants.map(\.register) == b.constants.map(\.register)
+        a.voices == b.voices && a.mode == b.mode && a.registers == b.registers && a.constants.map(\.register) == b.constants.map(\.register)
             && a.constants.map(\.value) == b.constants.map(\.value) && a.parameters == b.parameters && a.state == b.state
-            && a.instances == b.instances && a.block == b.block && a.sample == b.sample && a.output == b.output
+            && a.instances == b.instances && a.tables == b.tables && a.shapes == b.shapes && a.samples == b.samples && a.routes == b.routes && a.curves == b.curves
+            && a.block == b.block && a.sample == b.sample && a.serial == b.serial && a.output == b.output && a.outputRight == b.outputRight && a.master == b.master
     }
 
     public static let format = "swiftbrowser-dsp"
+    /// The format's version: the machine runs only its own.
     public static let version = 1
     public static let lanes = 16
     public static let blockFrames = 128
-    /// The machine's own registers: `sampleRate`, then a voice's `freq`, `gate`, `velocity` and `note`.
-    public static let machineRegisters = 5
+    /// The machine's own registers: `sampleRate`, a voice's `freq`, `gate`, `velocity` and `note`, then the
+    /// transport's `tempo` and `beat`.
+    public static let machineRegisters = 11
+    /// Samples a wavetable frame has, at each of its band-limited levels (program.ts `TABLE_FRAME`, `TABLE_LEVELS`).
+    public static let tableFrame = 2048
+    public static let tableLevels = 10
+    /// The most harmonics a frame gives, and frames a program's tables have between them.
+    public static let tableHarmonics = 512
+    public static let tableFramesMax = 256
+    /// The bounds of an envelope curve's exponents (program.ts `CURVE_MIN`, `CURVE_MAX`).
+    public static let curveRange: ClosedRange<Float> = 1.0 / 16 ... 16
+
+    /// An envelope's curves: the exponents its attack, decay and release are bent by (1 as without).
+    public struct Curve: Equatable, Sendable {
+        public let instance: Int
+        public let attack: Float
+        public let decay: Float
+        public let release: Float
+    }
+    /// The longest a delay may be, in seconds.
+    public static let delaySecondsMax: Float = 2
+    /// Points a shape has, and its shapes between them; samples a program's samples have between them.
+    public static let shapePointsMax = 4096
+    public static let shapesPointsMax = 65_536
+    public static let samplesMax = 8_000_000
 
     /// The program the JSON describes, checked: every register, operand and instance in range.
     public init(json: String) throws {
@@ -64,8 +147,16 @@ public struct DSPProgram: Sendable, Equatable {
     public init(object: Any) throws {
         guard let root = object as? [String: Any] else { throw DSPProgramError("not an object") }
         guard root["format"] as? String == Self.format else { throw DSPProgramError("format is not \(Self.format)") }
-        guard Self.int(root["version"]) == Self.version else { throw DSPProgramError("version is not \(Self.version)") }
+        guard Self.int(root["version"]) == Self.version else {
+            throw DSPProgramError("version \(root["version"].map { "\($0)" } ?? "none") is not \(Self.version)")
+        }
         guard let voices = Self.int(root["voices"]), (1...Self.lanes).contains(voices) else { throw DSPProgramError("voices must be 1 … \(Self.lanes)") }
+        var mode: Mode?
+        if let value = root["mode"] {
+            guard let name = value as? String, let parsed = Mode(rawValue: name) else { throw DSPProgramError("mode is not mono or legato") }
+            guard voices == 1 else { throw DSPProgramError("a mono or legato program has 1 voice") }
+            mode = parsed
+        }
         guard let registers = Self.int(root["registers"]), (Self.machineRegisters...65_536).contains(registers) else { throw DSPProgramError("registers out of range") }
         func register(_ value: Any?, _ what: String) throws -> Int {
             guard let r = Self.int(value), r >= 0, r < registers else { throw DSPProgramError("\(what): register out of range") }
@@ -101,40 +192,201 @@ public struct DSPProgram: Sendable, Equatable {
         guard let state = root["state"] as? [[String: Any]] else { throw DSPProgramError("state missing") }
         let parsedState = try state.map { s -> State in
             let name = s["name"] as? String ?? "state"
-            return State(name: name, register: try register(s["register"], "state \(name)"), initial: try number(s["initial"], "state \(name)'s initial value"))
+            return State(
+                name: name, register: try register(s["register"], "state \(name)"), initial: try number(s["initial"], "state \(name)'s initial value"),
+                master: s["master"] as? Bool ?? false
+            )
         }
         let output = try register(root["output"], "output")
-        func code(_ key: String) throws -> [Int32] {
+        let outputRight = try root["outputRight"].map { try register($0, "outputRight") }
+        var masterParts: (inputs: [Int], outputs: [Int])?
+        if root["master"] != nil {
+            guard let inputs = root["masterInputs"] as? [Any], inputs.count == 2 else { throw DSPProgramError("master needs masterInputs [left, right]") }
+            guard let outputs = root["masterOutput"] as? [Any], outputs.count == 2 else { throw DSPProgramError("master needs masterOutput [left, right]") }
+            masterParts = (try inputs.map { try register($0, "master") }, try outputs.map { try register($0, "master") })
+        }
+        var parsedShapes: [Shape] = []
+        if let shapes = root["shapes"] {
+            guard let list = shapes as? [[String: Any]] else { throw DSPProgramError("shapes must be an array") }
+            var points = 0
+            for shape in list {
+                guard let name = shape["name"] as? String, let values = shape["points"] as? [Any], (2...Self.shapePointsMax).contains(values.count) else {
+                    throw DSPProgramError("a shape is { name, points }, 2 … \(Self.shapePointsMax) numbers")
+                }
+                let parsed = try values.map { value in
+                    let point = try number(value, "shape \(name)'s point")
+                    guard point.isFinite else { throw DSPProgramError("shape \(name): a point is not finite") }
+                    return point
+                }
+                points += parsed.count
+                parsedShapes.append(Shape(name: name, points: parsed))
+            }
+            guard points <= Self.shapesPointsMax else { throw DSPProgramError("the shapes have more than \(Self.shapesPointsMax) points between them") }
+        }
+        var parsedSamples: [Sample] = []
+        if let samples = root["samples"] {
+            guard let list = samples as? [[String: Any]] else { throw DSPProgramError("samples must be an array") }
+            var total = 0
+            for sample in list {
+                guard let name = sample["name"] as? String, let text = sample["data"] as? String, let rate = (sample["rate"] as? NSNumber)?.doubleValue,
+                      rate >= 1000, rate <= 384_000
+                else { throw DSPProgramError("a sample is { name, rate, data }") }
+                // Base64 of 32-bit little-endian floats; at least two.
+                guard let bytes = Data(base64Encoded: text), bytes.count % 4 == 0, bytes.count >= 8 else {
+                    throw DSPProgramError("sample \(name)'s data is not base64 of at least 2 32-bit floats")
+                }
+                total += bytes.count / 4
+                guard total <= Self.samplesMax else { throw DSPProgramError("the samples have more than \(Self.samplesMax) samples between them") }
+                let data = bytes.withUnsafeBytes { raw in
+                    (0..<(bytes.count / 4)).map { Float(bitPattern: UInt32(littleEndian: raw.loadUnaligned(fromByteOffset: $0 * 4, as: UInt32.self))) }
+                }
+                parsedSamples.append(Sample(name: name, rate: rate, data: data))
+            }
+        }
+        var parsedTables: [Table] = []
+        if let tables = root["tables"] {
+            guard let list = tables as? [[String: Any]] else { throw DSPProgramError("tables must be an array") }
+            var frameCount = 0
+            for table in list {
+                guard let name = table["name"] as? String, let frames = table["frames"] as? [[Any]], !frames.isEmpty else { throw DSPProgramError("a table is { name, frames }") }
+                let parsedFrames = try frames.map { frame -> [Float] in
+                    guard !frame.isEmpty, frame.count <= Self.tableHarmonics else { throw DSPProgramError("table \(name): a frame is 1 … \(Self.tableHarmonics) harmonic amplitudes") }
+                    return try frame.map { value in
+                        let amplitude = try number(value, "table \(name)'s amplitude")
+                        guard amplitude.isFinite else { throw DSPProgramError("table \(name): an amplitude is not finite") }
+                        return amplitude
+                    }
+                }
+                var parsedCosines: [[Float]]?
+                if let cosines = table["cosines"] {
+                    guard let lists = cosines as? [[Any]], lists.count == parsedFrames.count else { throw DSPProgramError("table \(name): cosines are one list a frame") }
+                    parsedCosines = try lists.enumerated().map { f, list in
+                        guard list.count == parsedFrames[f].count else { throw DSPProgramError("table \(name): a frame's cosines are as many numbers as its sines") }
+                        return try list.map { value in
+                            let amplitude = try number(value, "table \(name)'s cosine")
+                            guard amplitude.isFinite else { throw DSPProgramError("table \(name): a cosine is not finite") }
+                            return amplitude
+                        }
+                    }
+                }
+                frameCount += parsedFrames.count
+                parsedTables.append(Table(name: name, frames: parsedFrames, cosines: parsedCosines))
+            }
+            guard frameCount <= Self.tableFramesMax else { throw DSPProgramError("the tables have more than \(Self.tableFramesMax) frames between them") }
+        }
+        var parsedRoutes: [[Int]] = []
+        if let routes = root["routes"] {
+            guard let lists = routes as? [[Any]] else { throw DSPProgramError("routes must be an array of lists") }
+            parsedRoutes = try lists.map { list in
+                guard list.count % 2 == 0 else { throw DSPProgramError("a route list is source and amount registers, pair after pair") }
+                let registers = try list.map { try register($0, "route") }
+                // An amount is a parameter, the same in every lane: the machine tests it once for all of them.
+                for k in stride(from: 1, to: registers.count, by: 2) where !parsedParameters.contains(where: { $0.register == registers[k] }) {
+                    throw DSPProgramError("route amount register \(registers[k]) is not a parameter")
+                }
+                return registers
+            }
+        }
+        var parsedCurves: [Curve] = []
+        if let curves = root["curves"] {
+            guard let entries = curves as? [[Any]] else { throw DSPProgramError("curves must be an array") }
+            parsedCurves = try entries.map { entry in
+                guard entry.count == 4, let instance = Self.int(entry[0]), instances.indices.contains(instance), instances[instance] == .adsr else {
+                    throw DSPProgramError("a curve is [instance, attack, decay, release] for an adsr")
+                }
+                let exponents = try entry.dropFirst().map { try number($0, "curve") }
+                guard exponents.allSatisfy({ Self.curveRange.contains($0) }) else { throw DSPProgramError("a curve's exponents are 1/16 … 16") }
+                return Curve(instance: instance, attack: exponents[0], decay: exponents[1], release: exponents[2])
+            }
+        }
+        let constantValues = Dictionary(parsedConstants.map { ($0.register, $0.value) }, uniquingKeysWith: { _, last in last })
+        let stateRegisters = Set(parsedState.map(\.register))
+        for r in [output, outputRight].compactMap({ $0 }) + (masterParts?.outputs ?? []) where stateRegisters.contains(r) {
+            throw DSPProgramError("output register \(r) is state")
+        }
+        func serial(_ key: String) throws -> Range<Int>? {
+            guard let value = root[key] else { return nil }
+            guard let pair = value as? [Any], pair.count == 2, let from = Self.int(pair[0]), let to = Self.int(pair[1]), from >= 0, from <= to else {
+                throw DSPProgramError("\(key) is not [from, to)")
+            }
+            return from..<to
+        }
+        func code(_ key: String, serial: Range<Int>?) throws -> [Int32] {
             guard let words = root[key] as? [Any] else { throw DSPProgramError("\(key) must be an array") }
             let code = try words.map { word -> Int32 in
                 guard let n = Self.int(word), n >= Int(Int32.min), n <= Int(Int32.max) else { throw DSPProgramError("\(key): a word is not a whole number") }
                 return Int32(n)
             }
+            if let serial, serial.upperBound > code.count { throw DSPProgramError("\(key)'s serial part is not [from, to) within it") }
+            var boundaries = 0
             var pc = 0
             while pc < code.count {
+                if let serial { boundaries += (pc == serial.lowerBound ? 1 : 0) + (pc == serial.upperBound ? 1 : 0) }
                 guard let op = DSPOpcode(rawValue: code[pc]) else { throw DSPProgramError("\(key): unknown opcode \(code[pc]) at \(pc)") }
                 let length = 2 + op.arity + (op.builtin == nil ? 0 : 1)
                 guard pc + length <= code.count else { throw DSPProgramError("\(key): \(op) at \(pc) is cut off") }
                 for i in 1..<(2 + op.arity) { _ = try register(Int(code[pc + i]), "\(key) \(op) at \(pc)") }
+                // State is a voice's value, not a frame's: only the part that runs frame by frame reads or writes it.
+                let inSerial = serial?.contains(pc) ?? false
+                if !inSerial && (1..<(2 + op.arity)).contains(where: { stateRegisters.contains(Int(code[pc + $0])) }) {
+                    throw DSPProgramError("\(key): \(op) at \(pc) reads or writes state outside the serial part")
+                }
                 if let builtin = op.builtin {
                     let instance = Int(code[pc + length - 1])
                     guard instances.indices.contains(instance), instances[instance] == builtin else {
                         throw DSPProgramError("\(key): \(op) at \(pc) names instance \(instance), not a \(builtin)")
                     }
                 }
+                // What sizes memory comes from a constant register.
+                if op == .wavetable || op == .tableread || op == .shape || op == .play || op == .loop || op == .grains {
+                    let (count, what) = op == .wavetable || op == .tableread ? (parsedTables.count, "a table") : op == .shape ? (parsedShapes.count, "a shape") : (parsedSamples.count, "a sample")
+                    guard let index = constantValues[Int(code[pc + 2])], index.rounded() == index, index >= 0, index < Float(count) else {
+                        throw DSPProgramError("\(key): \(op) at \(pc) does not name \(what)")
+                    }
+                } else if op == .modsum {
+                    guard let index = constantValues[Int(code[pc + 2])], index.rounded() == index, index >= 0, index < Float(parsedRoutes.count) else {
+                        throw DSPProgramError("\(key): modsum at \(pc) does not name a route list")
+                    }
+                    // It sums into its destination route by route, so the destination is none of the registers it reads.
+                    guard !parsedRoutes[Int(index)].contains(Int(code[pc + 1])) else {
+                        throw DSPProgramError("\(key): modsum at \(pc) writes a register its routes read")
+                    }
+                    guard inSerial || !parsedRoutes[Int(index)].contains(where: { stateRegisters.contains($0) }) else {
+                        throw DSPProgramError("\(key): modsum at \(pc) reads state outside the serial part")
+                    }
+                } else if let longestAt = op.longest {
+                    guard let longest = constantValues[Int(code[pc + 1 + longestAt])], longest > 0, longest <= Self.delaySecondsMax else {
+                        throw DSPProgramError("\(key): \(op) at \(pc)'s longest time is not a constant up to \(Self.delaySecondsMax) s")
+                    }
+                }
                 pc += length
             }
+            if let serial {
+                boundaries += (pc == serial.lowerBound ? 1 : 0) + (pc == serial.upperBound ? 1 : 0)
+                guard boundaries == 2 else { throw DSPProgramError("\(key)'s serial part does not fall between instructions") }
+            }
             return code
         }
         self.voices = voices
+        self.mode = mode
         self.registers = registers
         self.constants = parsedConstants
         self.parameters = parsedParameters
         self.state = parsedState
         self.instances = instances
-        self.block = try code("block")
-        self.sample = try code("sample")
+        self.tables = parsedTables
+        self.shapes = parsedShapes
+        self.samples = parsedSamples
+        self.routes = parsedRoutes
+        self.curves = parsedCurves
+        self.block = try code("block", serial: nil)
+        let sampleSerial = try serial("serial")
+        self.serial = sampleSerial
+        self.sample = try code("sample", serial: sampleSerial)
         self.output = output
+        self.outputRight = outputRight
+        let masterSerial = try serial("masterSerial")
+        self.master = try masterParts.map { Master(code: try code("master", serial: masterSerial), serial: masterSerial, inputs: $0.inputs, outputs: $0.outputs) }
     }
 
     private static func int(_ value: Any?) -> Int? {
@@ -152,13 +404,26 @@ public struct DSPProgramError: Error, CustomStringConvertible, Equatable {
 
 /// The stateful builtins, by the name a program's `instances` gives them.
 public enum DSPBuiltin: String, Sendable, CaseIterable {
-    case phasor, sine, saw, square, triangle, noise, adsr, lowpass, highpass, bandpass
+    case phasor, sine, saw, square, triangle, noise, adsr, lowpass, highpass, bandpass, wavetable, delay, play, grains, smooth, hold
+    case onepole, dcblock, comb, allpass, tableread, loop
 
-    /// Words of state per lane (program.ts BUILTIN_STATE).
+    /// Words of state per lane (program.ts BUILTIN_STATE): a delay's, a comb's and an all-pass's samples are a
+    /// buffer of their own.
     var words: Int {
         switch self {
-        case .phasor, .sine, .saw, .square, .triangle, .noise: 1
-        case .adsr, .lowpass, .highpass, .bandpass: 8
+        case .phasor, .sine, .saw, .square, .triangle, .noise, .delay, .allpass: 1
+        case .hold, .dcblock, .comb: 2
+        // A table read's frequency last seen and the level it reads at that frequency.
+        case .tableread: 2
+        // A one-pole's place, then the cutoff last seen and its coefficient.
+        case .onepole: 3
+        // A wavetable's phase, then the frequency last seen and the level it reads at that frequency.
+        case .play, .loop, .smooth, .wavetable: 3
+        // An envelope's stage, level, trigger and gate before, its decay and release times and coefficients, then
+        // (with curves) what it put out last and where its release started.
+        case .adsr: 10
+        case .lowpass, .highpass, .bandpass: 8
+        case .grains: 2 + 4 * 8
         }
     }
 }
@@ -167,22 +432,52 @@ public enum DSPBuiltin: String, Sendable, CaseIterable {
 public enum DSPOpcode: Int32, Sendable, CaseIterable {
     case mov = 0, add, sub, mul, div, mod, neg, min, max, abs, floor, ceil, round, sqrt, sin, cos, tan, exp, log, pow, tanh
     case lt = 21, le, gt, ge, eq, ne, and, or, not, select, clamp, mix, wrap, sign, atan
-    case phasor = 40, sine, saw, square, triangle, noise, adsr, lowpass, highpass, bandpass
+    case phasor = 40, sine, saw, square, triangle, noise, adsr, lowpass, highpass, bandpass, wavetable, delay, shape, play, grains, smooth, hold, modsum
+    /// The superinstructions the compiler fuses: a × b + c and (a + b) × c.
+    case madd = 58, amul
+    /// The rest of Math, and softclip.
+    case log2 = 60, log10, exp2, trunc, asin, acos, atan2, sinh, cosh, cbrt, hypot, expm1, log1p, softclip
+    case onepole = 74, dcblock, comb, allpass, tableread, loop
 
     /// Operands after the destination.
     public var arity: Int {
         switch self {
         case .noise: 0
+        case .modsum: 1
         case .mov, .neg, .abs, .floor, .ceil, .round, .sqrt, .sin, .cos, .tan, .exp, .log, .tanh, .not, .wrap, .sign, .atan,
-             .phasor, .sine, .saw, .triangle: 1
-        case .select, .clamp, .mix, .lowpass, .highpass, .bandpass: 3
-        case .adsr: 5
+             .phasor, .sine, .saw, .triangle, .log2, .log10, .exp2, .trunc, .asin, .acos, .sinh, .cosh, .cbrt, .expm1, .log1p,
+             .softclip, .dcblock: 1
+        case .select, .clamp, .mix, .lowpass, .highpass, .bandpass, .wavetable, .delay, .play, .loop, .madd, .amul: 3
+        case .allpass, .tableread: 4
+        case .adsr, .grains, .comb: 5
         default: 2
         }
     }
 
-    /// The builtin whose state it keeps, for a stateful one.
+    /// The builtin whose state it keeps, for a stateful one (`shape` keeps none).
     public var builtin: DSPBuiltin? {
-        rawValue >= 40 ? DSPBuiltin.allCases[Int(rawValue) - 40] : nil
+        switch self {
+        case .play: .play
+        case .grains: .grains
+        case .smooth: .smooth
+        case .hold: .hold
+        case .onepole: .onepole
+        case .dcblock: .dcblock
+        case .comb: .comb
+        case .allpass: .allpass
+        case .tableread: .tableread
+        case .loop: .loop
+        default: rawValue >= 40 && rawValue <= 51 ? DSPBuiltin.allCases[Int(rawValue) - 40] : nil
+        }
+    }
+
+    /// A delay line's operand (after the destination) that names its longest time: a delay's, a comb's, an all-pass's.
+    public var longest: Int? {
+        switch self {
+        case .delay: 3
+        case .comb: 5
+        case .allpass: 4
+        default: nil
+        }
     }
 }

package/swift/Packages/SwiftBrowserShader/Package.swift

@@ -0,0 +1,31 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+// SwiftBrowserShader: the native side of @swiftbrowser/shader. A shader
+// written in the shader language and compiled by the package's TypeScript
+// compiler draws here in an `MTKView`, its Metal compiled when a view first
+// draws it; JavaScript gives it as a `ShaderView`. A package of its own, so
+// only an app that draws with shaders links it; it installs itself as the
+// `SwiftBrowserShader.view` registered view (`SwiftBrowserShader.install()`).
+//
+// SwiftBrowserShaderCore is the view's props alone (the shader's layout, its
+// uniforms packed as the draw reads them, its textures), with no Apple
+// framework, so it builds and tests on Linux too.
+let package = Package(
+    name: "SwiftBrowserShader",
+    platforms: [.iOS(.v17), .macOS(.v14)],
+    products: [
+        .library(name: "SwiftBrowserShader", targets: ["SwiftBrowserShader"]),
+        .library(name: "SwiftBrowserShaderCore", targets: ["SwiftBrowserShaderCore"]),
+    ],
+    dependencies: [
+        .package(path: "../.."),
+    ],
+    targets: [
+        .target(name: "SwiftBrowserShaderCore", dependencies: [.product(name: "SwiftBrowserProtocol", package: "swift")]),
+        .target(
+            name: "SwiftBrowserShader",
+            dependencies: ["SwiftBrowserShaderCore", .product(name: "SwiftBrowserNative", package: "swift")]
+        ),
+    ]
+)

package/swift/Packages/SwiftBrowserShader/README.md

@@ -0,0 +1,45 @@
+# SwiftBrowserShader
+
+The native side of [@swiftbrowser/shader](../../../packages/shader): a
+shader written in the shader language, compiled by the package's TypeScript
+compiler to the Metal Shading Language (beside GLSL and JavaScript for a
+page), drawn by an `MTKView` over a `ShaderView`'s box. The JavaScript only
+sends the shader, its uniforms and its textures; nothing per pixel runs
+there.
+
+It is a package of its own, as SwiftBrowserDSP is, so only an app that
+draws with shaders links it. @swiftbrowser/native ships it beside the core
+(`node_modules/@swiftbrowser/native/swift/Packages/SwiftBrowserShader`; it
+depends on `SwiftBrowserNative` at `../..`, here and there). Link it into
+the app's Xcode project with `npx swiftbrowser native add shader` (or
+`native init --with shader`) and install it at launch:
+
+```swift
+import SwiftBrowserShader
+
+init() {
+    SwiftBrowserShader.install()
+}
+```
+
+That registers `ShaderView`'s view (`SwiftBrowserShader.view`) with
+SwiftBrowserNative's `ViewRegistry`. Without it, a `ShaderView` shows its
+name, as any registered view nothing registered does.
+
+- **SwiftBrowserShaderCore** is the view's props alone: the shader's layout
+  (`ShaderLayout`, every uniform inside the floats a draw reads), its
+  textures, and the floats packed as the JavaScript packs them on a page
+  (`packedUniforms`). No Apple framework, so it builds and tests on Linux.
+- **SwiftBrowserShader** is the view: `ShaderRenderer` compiles a shader's
+  Metal when a view first draws it (`makeLibrary(source:)`, kept for every
+  view that draws the same source), uploads its textures as `r32Float`, and
+  draws one triangle over the view with the uniforms in a fragment buffer.
+  The `MTKView` draws when its props or its size change, or every display
+  frame when the view is `animated`. A shader its device does not compile
+  draws nothing and sends the compiler's message to `onError`, once.
+
+The tests (`swift test`) read @swiftbrowser/shader's render fixtures
+(packages/shader/test/fixtures/render.json) and, on a Mac, compile each
+case's Metal, draw it into a texture and hold its pixels to the ones the
+package's JavaScript backend drew (printed as `[shader render]`), as the
+page's tests hold WebGL2's.

package/swift/Packages/SwiftBrowserShader/Sources/SwiftBrowserShader/ShaderRenderer.swift

@@ -0,0 +1,103 @@
+#if canImport(Metal)
+import Metal
+@_exported import SwiftBrowserShaderCore
+
+/// What draws a shader with Metal: its pipeline (the library compiled once
+/// for a source, kept for every view that draws it), its textures, and a
+/// draw into a render pass. `ShaderView`'s `MTKView` draws through it, and
+/// the tests draw into a texture of their own.
+@MainActor
+public final class ShaderRenderer {
+    public let device: MTLDevice
+    public let pixelFormat: MTLPixelFormat
+    private var pipeline: MTLRenderPipelineState?
+    private var source = ""
+    private var textures: [MTLTexture] = []
+    private var uploaded: [ShaderTextureData?] = []
+    /// A texture of one zero for a slot the view was given nothing for: a draw reads every slot it declares.
+    private lazy var blank: MTLTexture? = Self.texture(device: device, width: 1, height: 1, data: [0])
+
+    /// Pipelines by source and pixel format, for every view: a library compiles in tens of milliseconds.
+    private static var pipelines: [String: MTLRenderPipelineState] = [:]
+
+    public init(device: MTLDevice, pixelFormat: MTLPixelFormat = .bgra8Unorm) {
+        self.device = device
+        self.pixelFormat = pixelFormat
+    }
+
+    public enum Failure: Error, CustomStringConvertible {
+        case compile(String)
+        case missing(String)
+
+        public var description: String {
+            switch self {
+            case .compile(let message): return message
+            case .missing(let name): return "the library has no function \(name)"
+            }
+        }
+    }
+
+    /// Makes ready to draw `props`: its pipeline compiled (or found) and its textures uploaded when they changed.
+    /// Throws the compiler's message when its Metal does not compile.
+    public func prepare(_ props: ShaderProps) throws {
+        guard let shader = props.shader else {
+            pipeline = nil
+            return
+        }
+        if shader.msl != source {
+            source = shader.msl
+            pipeline = nil
+            pipeline = try Self.pipeline(device: device, source: shader.msl, pixelFormat: pixelFormat)
+        }
+        if props.textures != uploaded || textures.count != shader.textures.count {
+            uploaded = props.textures
+            textures = shader.textures.indices.compactMap { slot in
+                let data = slot < props.textures.count ? props.textures[slot] : nil
+                return data.flatMap { Self.texture(device: device, width: $0.width, height: $0.height, data: $0.data) } ?? blank
+            }
+        }
+    }
+
+    /// Draws into `encoder`'s pass (which `prepare` made ready), the view `width` × `height` points at `scale` pixels
+    /// a point, `time` seconds in.
+    public func draw(_ props: ShaderProps, into encoder: MTLRenderCommandEncoder, width: Double, height: Double, scale: Double, time: Double) {
+        guard let pipeline, let shader = props.shader, textures.count == shader.textures.count else { return }
+        var floats = props.packedUniforms(width: width, height: height, scale: scale, time: time)
+        encoder.setRenderPipelineState(pipeline)
+        encoder.setFragmentBytes(&floats, length: MemoryLayout<Float>.stride * floats.count, index: 0)
+        for (slot, texture) in textures.enumerated() { encoder.setFragmentTexture(texture, index: slot) }
+        encoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3)
+    }
+
+    static func pipeline(device: MTLDevice, source: String, pixelFormat: MTLPixelFormat) throws -> MTLRenderPipelineState {
+        let key = "\(pixelFormat.rawValue)\n\(source)"
+        if let found = pipelines[key] { return found }
+        let library: MTLLibrary
+        do {
+            library = try device.makeLibrary(source: source, options: nil)
+        } catch {
+            throw Failure.compile(String(describing: error))
+        }
+        guard let vertex = library.makeFunction(name: "sb_vertex") else { throw Failure.missing("sb_vertex") }
+        guard let fragment = library.makeFunction(name: "sb_fragment") else { throw Failure.missing("sb_fragment") }
+        let descriptor = MTLRenderPipelineDescriptor()
+        descriptor.vertexFunction = vertex
+        descriptor.fragmentFunction = fragment
+        descriptor.colorAttachments[0].pixelFormat = pixelFormat
+        let made = try device.makeRenderPipelineState(descriptor: descriptor)
+        pipelines[key] = made
+        return made
+    }
+
+    /// A texture of one float a texel, read with `read` (no filtering: the shader's `sample` interpolates).
+    static func texture(device: MTLDevice, width: Int, height: Int, data: [Float]) -> MTLTexture? {
+        let descriptor = MTLTextureDescriptor.texture2DDescriptor(pixelFormat: .r32Float, width: width, height: height, mipmapped: false)
+        descriptor.usage = .shaderRead
+        guard let texture = device.makeTexture(descriptor: descriptor), data.count >= width * height else { return nil }
+        data.withUnsafeBytes { bytes in
+            texture.replace(region: MTLRegionMake2D(0, 0, width, height), mipmapLevel: 0, withBytes: bytes.baseAddress!, bytesPerRow: width * MemoryLayout<Float>.stride)
+        }
+        return texture
+    }
+}
+#endif