@swiftbrowser/native 0.19.0 → 0.23.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 the parts that touch state, which it
+/// schedules to run frame by frame when it loads them (block processing).
 public struct DSPProgram: Sendable, Equatable {
     public struct Parameter: Sendable, Equatable {
         public let name: String
@@ -19,30 +23,146 @@ 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]
+        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?
+    /// The voicing as parameters (program.ts `voicing`, their indices), read at each note: how many voices play
+    /// (rounded, 1 … `voices`), and the mode (rounded: 0 as many, 1 mono, 2 legato) in place of `mode`.
+    public let voicingVoices: Int?
+    public let voicingMode: Int?
     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 voice's left side, or both with no `outputRight`.
     public let output: Int
+    public let outputRight: Int?
+    public let master: Master?
+    /// Gated regions (program.ts `groups`): each one's parameter, the region it is inside (-1 none) and its results.
+    public let groups: [Gate]
+    /// Each instruction's region in `sample` and `master` (-1 none).
+    public let sampleGates: [Int32]?
+    public let masterGates: [Int32]?
+    /// Choices (program.ts `choices`): each a register read as one of its options, the one its parameter names.
+    public let choices: [Choice]
+
+    /// A choice: `register`, which no instruction writes, read as `options[round(parameter's set value × scale)]`
+    /// (clamped). What no choice picks, nor anything else needs, the machine does not run.
+    public struct Choice: Sendable, Equatable {
+        public let parameter: Int
+        public let register: Int
+        public let options: [Int]
+        /// What the parameter's value is multiplied by before it is rounded to an option.
+        public var scale: Double = 1
+    }
+
+    /// The most options a choice has.
+    public static let choiceOptionsMax = 256
+
+    /// A region: it runs while `parameter` (its index) is set above 0.5 and the region around it runs.
+    public struct Gate: Sendable, Equatable {
+        public let parameter: Int
+        public let parent: Int
+        public let outputs: [Output]
+    }
+
+    /// A region's result: a register no instruction writes, read as `on` while the region runs and `off` while not.
+    public struct Output: Sendable, Equatable {
+        public let register: Int
+        public let on: Int
+        public let off: Int
+    }
 
     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.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
+        /// The registers its exponents are read from, each frame (held to 1/16 … 16).
+        public let attack: Int
+        public let decay: Int
+        public let release: Int
+    }
+    /// 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 most registers a route list has (128 routes): a machine keeps room for a list this long.
+    public static let routesMax = 256
 
     /// The program the JSON describes, checked: every register, operand and instance in range.
     public init(json: String) throws {
@@ -64,8 +184,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,9 +229,120 @@ 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")
+        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") }
+                guard list.count <= Self.routesMax else { throw DSPProgramError("a route list has more than \(Self.routesMax) registers") }
+                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 register($0, "curve") }
+                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")
+        }
+        /// Every register an instruction writes.
+        var written = Set<Int>()
         func code(_ key: String) 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
@@ -116,25 +355,134 @@ public struct DSPProgram: Sendable, Equatable {
                 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)") }
+                written.insert(Int(code[pc + 1]))
                 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")
+                    }
+                } 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
             }
             return code
         }
         self.voices = voices
+        self.mode = mode
         self.registers = registers
         self.constants = parsedConstants
         self.parameters = parsedParameters
         self.state = parsedState
         self.instances = instances
+        self.tables = parsedTables
+        self.shapes = parsedShapes
+        self.samples = parsedSamples
+        self.routes = parsedRoutes
+        self.curves = parsedCurves
         self.block = try code("block")
         self.sample = try code("sample")
         self.output = output
+        self.outputRight = outputRight
+        self.master = try masterParts.map { Master(code: try code("master"), inputs: $0.inputs, outputs: $0.outputs) }
+        // Gated regions: each one's parameter one of the program's, the region around it an earlier one, and its
+        // results registers no instruction writes and nothing else names (no output, state, parameter, constant, route
+        // or another result), each read as a register while on and one while off, neither of them state (one value a
+        // voice, not one a frame).
+        var named = Set([output, outputRight].compactMap { $0 } + (masterParts?.inputs ?? []) + (masterParts?.outputs ?? []) + parsedRoutes.flatMap { $0 })
+        named.formUnion(stateRegisters)
+        named.formUnion(parsedParameters.map(\.register))
+        named.formUnion(parsedConstants.map(\.register))
+        named.formUnion(parsedCurves.flatMap { [$0.attack, $0.decay, $0.release] })
+        var results = Set<Int>()
+        var parsedGroups: [Gate] = []
+        for (index, item) in (root["groups"] as? [Any] ?? []).enumerated() {
+            guard let group = item as? [String: Any], let parameter = Self.int(group["parameter"]), parsedParameters.indices.contains(parameter) else {
+                throw DSPProgramError("groups[\(index)] does not name a parameter")
+            }
+            guard let parent = Self.int(group["parent"]), parent >= -1, parent < index else { throw DSPProgramError("groups[\(index)]'s parent is not an earlier region") }
+            guard let list = group["outputs"] as? [Any] else { throw DSPProgramError("groups[\(index)]'s outputs must be an array") }
+            let outputs = try list.map { entry -> Output in
+                guard let triple = entry as? [Any], triple.count == 3 else { throw DSPProgramError("groups[\(index)]: a result is [register, on, off]") }
+                let (r, on, off) = (try register(triple[0], "groups[\(index)]"), try register(triple[1], "groups[\(index)]"), try register(triple[2], "groups[\(index)]"))
+                guard r >= Self.machineRegisters, !written.contains(r), !named.contains(r), !results.contains(r) else {
+                    throw DSPProgramError("groups[\(index)]: result register \(r) is written or named elsewhere")
+                }
+                guard !stateRegisters.contains(on), !stateRegisters.contains(off) else { throw DSPProgramError("groups[\(index)]: result register \(r) reads as state") }
+                results.insert(r)
+                return Output(register: r, on: on, off: off)
+            }
+            parsedGroups.append(Gate(parameter: parameter, parent: parent, outputs: outputs))
+        }
+        self.groups = parsedGroups
+        // Choices: each one's parameter one of the program's, its register one nothing else writes or names (nor a
+        // region's result, nor another choice), its options 1 … choiceOptionsMax registers, none of them state.
+        let voicing = root["voicing"] as? [String: Any] ?? [:]
+        for key in voicing.keys {
+            guard ["voices", "mode"].contains(key), let index = Self.int(voicing[key]), parsedParameters.indices.contains(index) else {
+                throw DSPProgramError("voicing.\(key) does not name a parameter")
+            }
+        }
+        self.voicingVoices = Self.int(voicing["voices"])
+        self.voicingMode = Self.int(voicing["mode"])
+        self.choices = try (root["choices"] as? [Any] ?? []).enumerated().map { index, item in
+            guard let choice = item as? [String: Any], let parameter = Self.int(choice["parameter"]), parsedParameters.indices.contains(parameter) else {
+                throw DSPProgramError("choices[\(index)] does not name a parameter")
+            }
+            var scale = 1.0
+            if let value = choice["scale"] {
+                guard let number = value as? NSNumber, !(value is Bool), number.doubleValue.isFinite, number.doubleValue > 0 else {
+                    throw DSPProgramError("choices[\(index)]'s scale is not a number above 0")
+                }
+                scale = number.doubleValue
+            }
+            let r = try register(choice["register"], "choices[\(index)]")
+            guard r >= Self.machineRegisters, !written.contains(r), !named.contains(r), !results.contains(r) else {
+                throw DSPProgramError("choices[\(index)]: register \(r) is written or named elsewhere")
+            }
+            results.insert(r)
+            guard let list = choice["options"] as? [Any], (1...Self.choiceOptionsMax).contains(list.count) else {
+                throw DSPProgramError("choices[\(index)] has 1 … \(Self.choiceOptionsMax) options")
+            }
+            let options = try list.map { try register($0, "choices[\(index)]") }
+            guard !options.contains(where: stateRegisters.contains) else { throw DSPProgramError("choices[\(index)]: an option is state") }
+            return Choice(parameter: parameter, register: r, options: options, scale: scale)
+        }
+        /// One region (or -1) per instruction of `code`.
+        func regions(_ key: String, _ code: [Int32]?) throws -> [Int32]? {
+            guard let value = root[key] else { return nil }
+            guard let list = value as? [Any], let code else { throw DSPProgramError("\(key) must be an array") }
+            var count = 0
+            var pc = 0
+            while pc < code.count, let op = DSPOpcode(rawValue: code[pc]) {
+                count += 1
+                pc += 2 + op.arity + (op.builtin == nil ? 0 : 1)
+            }
+            guard list.count == count else { throw DSPProgramError("\(key) has \(list.count) entries for \(count) instructions") }
+            return try list.map { item in
+                guard let g = Self.int(item), g >= -1, g < parsedGroups.count else { throw DSPProgramError("\(key): a region is out of range") }
+                return Int32(g)
+            }
+        }
+        self.sampleGates = try regions("sampleGates", sample)
+        self.masterGates = try regions("masterGates", master?.code)
     }
 
     private static func int(_ value: Any?) -> Int? {
@@ -152,13 +500,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 +528,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.