@swiftbrowser/native 0.18.3 → 0.21.0

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

@@ -0,0 +1,483 @@
+import Foundation
+
+/// A compiled DSP program: the JSON @swiftbrowser/dsp's compiler writes
+/// (packages/dsp/src/program.ts, which documents the format). The machine
+/// keeps a register file of `registers` registers of 16 lanes, a lane per
+/// 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
+        public let register: Int
+        public let defaultValue: Float
+        public let min: Float
+        public let max: Float
+    }
+
+    public struct State: 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.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.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`, 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 {
+        guard let data = json.data(using: .utf8) else { throw DSPProgramError("not UTF-8") }
+        try self.init(data: data)
+    }
+
+    public init(data: Data) throws {
+        let parsed: Any
+        do {
+            parsed = try JSONSerialization.jsonObject(with: data)
+        } catch {
+            throw DSPProgramError("not JSON (\(error.localizedDescription))")
+        }
+        try self.init(object: parsed)
+    }
+
+    /// From a decoded JSON object (`JSONSerialization`'s).
+    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 \(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") }
+            return r
+        }
+        func number(_ value: Any?, _ what: String) throws -> Float {
+            guard let n = (value as? NSNumber)?.doubleValue, n.isFinite || n.isInfinite else { throw DSPProgramError("\(what) must be a number") }
+            return Float(n)
+        }
+        guard let instanceNames = root["instances"] as? [String] else { throw DSPProgramError("instances must be an array of names") }
+        let instances = try instanceNames.map { name in
+            guard let builtin = DSPBuiltin(rawValue: name) else { throw DSPProgramError("unknown builtin \(name)") }
+            return builtin
+        }
+        guard let constants = root["constants"] as? [[Any]] else { throw DSPProgramError("constants missing") }
+        let parsedConstants: [(register: Int, value: Float)] = try constants.map { entry in
+            guard entry.count == 2 else { throw DSPProgramError("a constant is not [register, value]") }
+            return (try register(entry[0], "constant"), try number(entry[1], "a constant"))
+        }
+        guard let parameters = root["parameters"] as? [[String: Any]] else { throw DSPProgramError("parameters missing") }
+        let parsedParameters = try parameters.map { p -> Parameter in
+            guard let name = p["name"] as? String else { throw DSPProgramError("a parameter has no name") }
+            let parameter = Parameter(
+                name: name, register: try register(p["register"], "parameter \(name)"),
+                defaultValue: try number(p["default"], "parameter \(name)'s default"),
+                min: try number(p["min"], "parameter \(name)'s min"), max: try number(p["max"], "parameter \(name)'s max")
+            )
+            guard parameter.min <= parameter.max, [parameter.defaultValue, parameter.min, parameter.max].allSatisfy(\.isFinite) else {
+                throw DSPProgramError("parameter \(name): its range is not numbers from min to max")
+            }
+            return parameter
+        }
+        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"),
+                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") }
+                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.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? {
+        guard let number = value as? NSNumber else { return nil }
+        let double = number.doubleValue
+        guard double.rounded() == double, abs(double) < 1e12 else { return nil }
+        return Int(double)
+    }
+}
+
+public struct DSPProgramError: Error, CustomStringConvertible, Equatable {
+    public let description: String
+    public init(_ detail: String) { description = "invalidProgram: \(detail)" }
+}
+
+/// 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, wavetable, delay, play, grains, smooth, hold
+    case onepole, dcblock, comb, allpass, tableread, loop
+
+    /// 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, .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
+        }
+    }
+}
+
+/// The opcodes, v1: the numbers are the wire format (program.ts OPCODES).
+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, 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, .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 (`shape` keeps none).
+    public var builtin: DSPBuiltin? {
+        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/SwiftBrowserLocalModel/Package.swift

@@ -0,0 +1,35 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+// SwiftBrowserLocalModel: an open language model on the device, through
+// llama.cpp, for the `LanguageModelSession`s of a SwiftBrowser Native app
+// where Apple Intelligence cannot answer (an iPhone before the 15 Pro, Apple
+// Intelligence off, a system before iOS 26). A package of its own, so only an
+// app that adds it fetches, builds and links llama.cpp; it installs itself as
+// `LanguageModels.fallback` (SwiftBrowserNative, LanguageModelProvider.swift).
+//
+// llama.cpp is its release XCFramework, b10456: the newest whose release
+// carries the iOS Simulator beside devices and macOS (later ones ship devices
+// and macOS only). SwiftPM fetches it once (286 MB, tvOS and visionOS
+// included) and caches it; an iPhone app links about 6 MB of it.
+let package = Package(
+    name: "SwiftBrowserLocalModel",
+    platforms: [.iOS(.v17), .macOS(.v14)],
+    products: [
+        .library(name: "SwiftBrowserLocalModel", targets: ["SwiftBrowserLocalModel"]),
+    ],
+    dependencies: [
+        .package(path: "../.."),
+    ],
+    targets: [
+        .binaryTarget(
+            name: "llama",
+            url: "https://github.com/ggml-org/llama.cpp/releases/download/b10456/llama-b10456-xcframework.zip",
+            checksum: "0223bedd0a01232399d943dcb72bc227882bc90df98e29d7a92343531a88cc02"
+        ),
+        .target(
+            name: "SwiftBrowserLocalModel",
+            dependencies: [.product(name: "SwiftBrowserNative", package: "swift"), "llama"]
+        ),
+    ]
+)

package/swift/Packages/SwiftBrowserLocalModel/README.md

@@ -0,0 +1,66 @@
+# SwiftBrowserLocalModel
+
+An open language model on the device, run with
+[llama.cpp](https://github.com/ggml-org/llama.cpp), for a SwiftBrowser Native
+app's `LanguageModelSession`s where Apple Intelligence cannot answer: an
+iPhone before the 15 Pro, Apple Intelligence turned off, a system before
+iOS 26. Where Apple Intelligence answers, it still does.
+
+It is a package of its own so that only an app that adds it fetches, builds
+and links llama.cpp. @swiftbrowser/native ships it beside the core
+(`node_modules/@swiftbrowser/native/swift/Packages/SwiftBrowserLocalModel`;
+it depends on `SwiftBrowserNative` at `../..`, here and there). Link it into
+the app's Xcode project with
+
+```sh
+npx swiftbrowser native add local-model        # or native init --with local-model
+```
+
+and install a model at launch:
+
+```swift
+import SwiftBrowserLocalModel
+
+init() {
+    LocalLanguageModel.install([.llama3_2_1B, .qwen2_5_1_5B, .llama3_2_3B])
+}
+```
+
+With several, the first is the default and availability lists them as
+`models` for the viewer to choose from (`selectModel(id)`), the choice
+remembered across launches; each downloads on its own.
+
+On the JavaScript side, `useSystemLanguageModel()` reports `modelNotReady`
+with `download: { size, downloaded: false }` until the viewer asks for the
+model: show the size and call `SystemLanguageModel.default.download()` from
+a button. The download's `progress` follows, then `available`, and
+`LanguageModelSession` answers with it. `deleteDownload()` stops a download
+or takes the model off the device (the Showcase's Chat has both).
+
+- **Tools** a session is given are offered in its instructions, and a reply
+  that is just `{"tool": name, "arguments": {...}}` is run as a call, its
+  result handed back for the model to go on. Small models call tools less
+  reliably than Apple Intelligence does; Qwen 2.5 1.5B is the steadiest here.
+- **The models**: `.llama3_2_1B` (808 MB, fastest), `.qwen2_5_1_5B` (1.1 GB,
+  Apache 2.0, best with tools), `.llama3_2_3B` (2.0 GB, most capable; a phone
+  with 6 GB of memory runs it near its limit).
+- **The model** is a GGUF file, fetched when the app calls `download()`, kept
+  in Application Support's
+  `SwiftBrowserLocalModel` folder and excluded from backups. `.llama3_2_1B`
+  is Meta's Llama 3.2 1B Instruct at 4 bits (808 MB; Meta's Llama 3.2
+  Community License applies); any other is a `LocalLanguageModel.Model`
+  with its URL, size and context length. `allowsCellularAccess: false`
+  waits for Wi-Fi.
+- **Running it**: loaded once on the first prompt or `prewarm()`, on the GPU
+  with Metal, on a queue of its own. A session keeps its messages, formatted
+  with the model's chat template (ChatML for a model without one); the
+  context keeps the tokens of the last conversation, so a prompt that
+  continues it decodes only what is new. A conversation longer than the
+  context fails as `exceededContextWindowSize`.
+- **Size**: llama.cpp is its release XCFramework, b10456, the newest whose
+  release has the iOS Simulator beside devices and macOS. SwiftPM downloads
+  it once (286 MB, with tvOS and visionOS) and caches it; an iPhone app
+  links about 6 MB.
+
+The tests (`swift test`, macOS) run llama.cpp on the CPU with a 1.2 MB toy
+model they download.