Sources/FaceMaker/AppModel.swift

Swift source for Making faces, 798 lines. Raw file

import AppKit
import CoreImage
import SwiftUI

/// Whether a model's grid is anchored on a seed (a reproducible random draw)
/// or an explicit 512-d latent vector the user can edit / drop in.
enum BaseMode: String, Hashable, Sendable {
    case seed
    case vector
}

/// One generated face in the grid.
struct FaceSlot: Identifiable {
    var id: Int
    var image: NSImage?
    var pngData: Data?
    var seed: UInt64?
    /// The exact 512-d latent (z) that produced this face — carried so the
    /// grid can offer "Use Vector" and the viewer "View Vector".
    var vector: [Float]?
    /// The W+ latent (18×512) when this face came from encoder inversion.
    var wplus: [Float]?
    var failure: String?
    /// The ranged sliders' values for this face, like "Smile 1.23", shown in place of the seed.
    var labels: [String] = []

    init(id: Int, image: NSImage? = nil, pngData: Data? = nil,
         seed: UInt64? = nil, vector: [Float]? = nil, wplus: [Float]? = nil,
         failure: String? = nil) {
        self.id = id
        self.image = image
        self.pngData = pngData
        self.seed = seed
        self.vector = vector
        self.wplus = wplus
        self.failure = failure
    }
}

/// App state. Almost everything is stored *per model* (keyed by model id) so
/// switching models restores that model's own seed, vector, radius, slider
/// values, and ranges. Generation runs on `FaceLocalEngine` (bundled ONNX,
/// CPU); this model builds each face's latent + edits and republishes results.
@MainActor
@Observable
final class AppModel {
    let models = LocalFaceModel.all.sorted { $0.speedRank < $1.speedRank }

    var selectedModelID: String {
        didSet {
            if oldValue != selectedModelID {
                if strategy == .encoder && !supportsEncoder { strategy = .quick }
                bumpGeneration(); persist()
            }
        }
    }
    var faceCount: Int = 8 {
        didSet { if oldValue != faceCount { bumpGeneration(); persist() } }
    }

    // Per-slider state (slider ids are already unique per model).
    /// Slider id → value ("start" of a range). Absent means neutral.
    var sliderValues: [String: Double] = [:] { didSet { bumpGeneration(); persist() } }
    /// Optional group id → enabled. Absent means off.
    var enabledGroups: [String: Bool] = [:] { didSet { bumpGeneration(); persist() } }
    /// Slider id → range on. When on, faces after the first sample a random
    /// value between the start value and `rangeEnd`.
    var rangeEnabled: [String: Bool] = [:] { didSet { bumpGeneration(); persist() } }
    /// Slider id → the far end of the range.
    var rangeEnd: [String: Double] = [:] { didSet { bumpGeneration(); persist() } }

    // Per-model scalars. Mutated only through the computed accessors below,
    // which bump generation + persist — so no didSet here.
    var modeByModel: [String: String] = [:]
    var seedTextByModel: [String: String] = [:]
    var radiusByModel: [String: Double] = [:]
    /// Truncation ψ for W+ radius neighbours (1 = none). Lower pulls them
    /// toward the average face — more realistic/sharper, less extreme.
    var realismByModel: [String: Double] = [:]
    /// Whether W+ radius neighbours use one coherent W-direction across layers
    /// (face-like variation) vs independent per-dimension noise.
    var coherentByModel: [String: Bool] = [:]
    var vectorByModel: [String: [Float]] = [:]
    /// Encoder-inversion W+ latent (18×512) per model. When set, it takes
    /// precedence over the z vector as the base for generation.
    var wplusByModel: [String: [Float]] = [:]
    /// Variation salt for vector mode — bumped by Regenerate to re-roll the
    /// radius sampling and range randomness (seed mode uses the seed itself).
    var saltByModel: [String: UInt64] = [:]

    var slots: [FaceSlot] = []
    var notice: String?
    /// How long the last full grid took to generate, shown under it. The
    /// model is loaded before the clock starts, so it's the faces alone.
    var timing: String?

    /// Transient status shown while a dropped image is matched to a vector.
    var finderStatus: String?
    /// True while the slow refinement is running (shows the Stop button).
    var isSearching = false
    /// The matching strategy chosen in the drop dropdown.
    var strategy: FindStrategy = .quick {
        didSet { if oldValue != strategy { persist() } }
    }
    private var isFinding = false
    private var findTask: Task<Void, Never>?

    /// Bank size for nearest-neighbour search. Matches the precomputed banks
    /// shipped in the bundle, so a drop just loads + searches (no runtime
    /// build) for the models that have one.
    static let bankTarget = 200

    /// Incremented on every control change; the view's `.task(id:)` restarts.
    private(set) var generation = 0

    var selectedModel: LocalFaceModel {
        LocalFaceModel.find(selectedModelID) ?? models[0]
    }

    /// Guards persistence during the initial load.
    private var loaded = false

    init() {
        let defaults = UserDefaults.standard
        self.selectedModelID = defaults.string(forKey: Keys.model)
            .flatMap { LocalFaceModel.find($0) != nil ? $0 : nil }
            ?? LocalFaceModel.fastest.id
        if let count = defaults.object(forKey: Keys.faceCount) as? Int {
            self.faceCount = min(100, max(4, count))
        }
        sliderValues = Self.decode(defaults, Keys.sliders) ?? [:]
        enabledGroups = Self.decode(defaults, Keys.groups) ?? [:]
        rangeEnabled = Self.decode(defaults, Keys.rangeOn) ?? [:]
        rangeEnd = Self.decode(defaults, Keys.rangeEnd) ?? [:]
        modeByModel = Self.decode(defaults, Keys.mode) ?? [:]
        seedTextByModel = Self.decode(defaults, Keys.seed) ?? [:]
        radiusByModel = Self.decode(defaults, Keys.radius) ?? [:]
        realismByModel = Self.decode(defaults, Keys.realism) ?? [:]
        coherentByModel = Self.decode(defaults, Keys.coherent) ?? [:]
        vectorByModel = Self.decode(defaults, Keys.vector) ?? [:]
        wplusByModel = Self.decode(defaults, Keys.wplus) ?? [:]
        saltByModel = Self.decode(defaults, Keys.salt) ?? [:]
        if let raw = defaults.string(forKey: Keys.strategy),
           let saved = FindStrategy(rawValue: raw) {
            self.strategy = saved
        }
        loaded = true
    }

    private enum Keys {
        static let model = "facemaker.model"
        static let faceCount = "facemaker.faceCount"
        static let sliders = "facemaker.sliders"
        static let groups = "facemaker.groups"
        static let rangeOn = "facemaker.rangeOn"
        static let rangeEnd = "facemaker.rangeEnd"
        static let mode = "facemaker.mode"
        static let seed = "facemaker.seedByModel"
        static let radius = "facemaker.radius"
        static let realism = "facemaker.realism"
        static let coherent = "facemaker.coherent"
        static let vector = "facemaker.vector"
        static let wplus = "facemaker.wplus"
        static let salt = "facemaker.salt"
        static let strategy = "facemaker.strategy"
    }

    private static func decode<T: Decodable>(_ defaults: UserDefaults, _ key: String) -> T? {
        guard let data = defaults.data(forKey: key) else { return nil }
        return try? JSONDecoder().decode(T.self, from: data)
    }

    private func persist() {
        guard loaded else { return }
        let defaults = UserDefaults.standard
        defaults.set(selectedModelID, forKey: Keys.model)
        defaults.set(faceCount, forKey: Keys.faceCount)
        defaults.set(try? JSONEncoder().encode(sliderValues), forKey: Keys.sliders)
        defaults.set(try? JSONEncoder().encode(enabledGroups), forKey: Keys.groups)
        defaults.set(try? JSONEncoder().encode(rangeEnabled), forKey: Keys.rangeOn)
        defaults.set(try? JSONEncoder().encode(rangeEnd), forKey: Keys.rangeEnd)
        defaults.set(try? JSONEncoder().encode(modeByModel), forKey: Keys.mode)
        defaults.set(try? JSONEncoder().encode(seedTextByModel), forKey: Keys.seed)
        defaults.set(try? JSONEncoder().encode(radiusByModel), forKey: Keys.radius)
        defaults.set(try? JSONEncoder().encode(realismByModel), forKey: Keys.realism)
        defaults.set(try? JSONEncoder().encode(coherentByModel), forKey: Keys.coherent)
        defaults.set(try? JSONEncoder().encode(vectorByModel), forKey: Keys.vector)
        defaults.set(try? JSONEncoder().encode(wplusByModel), forKey: Keys.wplus)
        defaults.set(try? JSONEncoder().encode(saltByModel), forKey: Keys.salt)
        defaults.set(strategy.rawValue, forKey: Keys.strategy)
    }

    private func bumpGeneration() {
        notice = nil
        generation += 1
    }

    // MARK: - Per-model accessors (current model)

    var mode: BaseMode {
        get { BaseMode(rawValue: modeByModel[selectedModelID] ?? "") ?? .seed }
        set {
            modeByModel[selectedModelID] = newValue.rawValue
            if newValue == .vector { ensureVector() }
            if newValue == .seed { wplusByModel[selectedModelID] = nil }
            bumpGeneration(); persist()
        }
    }

    var seedText: String {
        get { seedTextByModel[selectedModelID] ?? "" }
        set { seedTextByModel[selectedModelID] = newValue; bumpGeneration(); persist() }
    }

    var radius: Double {
        //  0.3 gives faces that are clearly related but not all the same
        get { radiusByModel[selectedModelID] ?? 0.3 }
        set { radiusByModel[selectedModelID] = newValue; bumpGeneration(); persist() }
    }

    var realism: Double {
        get { realismByModel[selectedModelID] ?? 0.7 }
        set { realismByModel[selectedModelID] = newValue; bumpGeneration(); persist() }
    }

    var coherentPerturb: Bool {
        get { coherentByModel[selectedModelID] ?? true }
        set { coherentByModel[selectedModelID] = newValue; bumpGeneration(); persist() }
    }

    /// The average W+ (bundled), for truncation. Loaded once.
    @ObservationIgnored private var wAvgCache: [Float]?
    private func wAvg() -> [Float]? {
        if let wAvgCache { return wAvgCache }
        guard let dir = try? FaceLocalEngine.bundledDirectory() else { return nil }
        let url = dir.appendingPathComponent("stylegan2-ffhq-wavg.f32")
        guard let data = try? Data(contentsOf: url), data.count == 18 * 512 * 4 else { return nil }
        var values = [Float](repeating: 0, count: 18 * 512)
        _ = values.withUnsafeMutableBytes { data.copyBytes(to: $0) }
        wAvgCache = values
        return values
    }

    /// The editable 512-d vector for this model. Falls back to a deterministic
    /// latent until one is materialized (see `ensureVector`).
    var vector: [Float] {
        get {
            vectorByModel[selectedModelID]
                ?? FaceLocalEngine.gaussianLatent(seed: parsedSeed() ?? 0xF00D_CAFE, count: 512)
        }
        set {
            vectorByModel[selectedModelID] = newValue
            wplusByModel[selectedModelID] = nil  // editing z leaves W+ behind
            bumpGeneration(); persist()
        }
    }

    /// Re-derive the vector from the current seed (editor's "From seed").
    func resetVectorToSeed() {
        vectorByModel[selectedModelID] =
            FaceLocalEngine.gaussianLatent(seed: seedBase(), count: 512)
        wplusByModel[selectedModelID] = nil
        bumpGeneration(); persist()
    }

    // MARK: - Drop an image → find vector

    /// Every bundled generator can be searched by nearest-neighbour, so all
    /// models support the drop.
    var supportsFinder: Bool { true }

    /// The matching strategies available for the current model. Encoder
    /// inversion only appears for the StyleGAN2-FFHQ checkpoint it matches.
    var availableStrategies: [FindStrategy] {
        supportsEncoder ? [.quick, .search, .encoder] : [.quick, .search]
    }

    /// Stop an in-progress refinement, keeping the best latent found so far.
    func stopSearch() { findTask?.cancel() }

    /// Match a dropped photo to this model's closest latent and adopt it as
    /// the vector. `quick` is the instant bank match; `search` then refines
    /// live until the user stops.
    func findVector(from image: CIImage) {
        guard supportsFinder, !isFinding else { return }
        isFinding = true
        finderStatus = "Reading dropped face…"
        let model = selectedModel
        let strategy = self.strategy
        findTask = Task { @MainActor in
            defer { isFinding = false; isSearching = false }
            guard let directory = try? FaceLocalEngine.bundledDirectory() else {
                finderStatus = "Face models are missing from the app bundle."
                return
            }
            do {
                // Encoder inversion: one-shot high-fidelity reconstruction.
                if strategy == .encoder {
                    finderStatus = "Encoding dropped face…"
                    guard let wplus = try await FaceInversion.shared.encodeWPlus(
                        image, directory: directory) else {
                        finderStatus = "No face was found in the dropped image."
                        try? await Task.sleep(for: .seconds(2))
                        if finderStatus?.hasPrefix("No face") == true { finderStatus = nil }
                        return
                    }
                    useWPlus(wplus)
                    finderStatus = "Reconstructed."
                    try? await Task.sleep(for: .seconds(2))
                    if finderStatus == "Reconstructed." { finderStatus = nil }
                    return
                }

                // 1) Embed the dropped face.
                guard let query = try await FaceInversion.shared.embedDropped(
                    image, directory: directory) else {
                    finderStatus = "No face was found in the dropped image."
                    try? await Task.sleep(for: .seconds(2))
                    if finderStatus?.hasPrefix("No face") == true { finderStatus = nil }
                    return
                }

                // 2) Instant nearest match from the bundled bank.
                let seed = try await FaceInversion.shared.nearest(
                    to: query, model: model, directory: directory,
                    target: Self.bankTarget,
                    progress: { done, total in
                        Task { @MainActor in
                            self.finderStatus = "Building search index… \(done)/\(total)"
                        }
                    })
                useVector(seed)

                guard strategy == .search else {
                    finderStatus = "Matched to the nearest face."
                    try? await Task.sleep(for: .seconds(2))
                    if finderStatus == "Matched to the nearest face." { finderStatus = nil }
                    return
                }

                // 3) Live refinement until the user hits Stop. The face
                // updates each step so you can stop when it's close enough.
                isSearching = true
                finderStatus = "Refining…"
                let refined = try await FaceInversion.shared.refine(
                    query: query, start: seed, model: model, directory: directory,
                    iterations: 1000, lambda: 6,
                    progress: { step, _, sim, best in
                        Task { @MainActor in
                            self.useVector(best)
                            self.finderStatus = String(
                                format: "Refining · step %d · distance %.3f",
                                step, max(0, 1 - sim))
                        }
                    })
                useVector(refined)
                isSearching = false
                finderStatus = "Stopped refining."
                try? await Task.sleep(for: .seconds(2))
                if finderStatus == "Stopped refining." { finderStatus = nil }
            } catch let error as LocalizedError {
                finderStatus = error.errorDescription
            } catch {
                finderStatus = "Could not read the dropped image."
            }
        }
    }

    /// Adopt a face's exact latent and switch to vector mode (grid "Use
    /// Vector").
    func useVector(_ vector: [Float]) {
        guard vector.count == 512 else { return }
        vectorByModel[selectedModelID] = vector
        wplusByModel[selectedModelID] = nil
        modeByModel[selectedModelID] = BaseMode.vector.rawValue
        bumpGeneration(); persist()
    }

    /// Adopt an encoder-inversion W+ latent (18×512) as the base and switch to
    /// vector mode.
    func useWPlus(_ wplus: [Float]) {
        guard wplus.count == 18 * 512, supportsEncoder else { return }
        wplusByModel[selectedModelID] = wplus
        modeByModel[selectedModelID] = BaseMode.vector.rawValue
        bumpGeneration(); persist()
    }

    /// Encoder inversion is only valid for the exact StyleGAN2-FFHQ checkpoint
    /// the e4e encoder was trained against.
    var supportsEncoder: Bool { selectedModelID == "local/stylegan2-ffhq" }

    /// Load a latent made elsewhere, for example by projecting a photo with
    /// PyTorch: a JSON with a `data` array of 9216 floats (W+) or 512 floats (z).
    func importLatent(from url: URL) {
        guard let data = try? Data(contentsOf: url),
              let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
              let raw = object["data"] as? [Any]
        else {
            notice = "Could not read the latent file."
            return
        }
        let floats = raw.compactMap { ($0 as? NSNumber)?.floatValue }
        if floats.count == 18 * 512 {
            guard supportsEncoder else {
                notice = "That W+ latent is for StyleGAN2 FFHQ — select that model first."
                return
            }
            useWPlus(floats)
        } else if floats.count == 512 {
            useVector(floats)
        } else {
            notice = "Unexpected latent size (\(floats.count))."
        }
    }

    /// The latent the grid starts from in vector mode: the W+ from a photo
    /// when there is one, otherwise the 512-number vector.
    var baseLatent: [Float] { activeWPlus() ?? vector }

    /// The active W+ base, if encoder inversion is in effect for this model.
    private func activeWPlus() -> [Float]? {
        guard mode == .vector, supportsEncoder else { return nil }
        return wplusByModel[selectedModelID]
    }

    /// Materialize a concrete vector (and a concrete seed) the first time a
    /// model enters vector mode, so the base face is stable.
    private func ensureVector() {
        let id = selectedModelID
        if vectorByModel[id] != nil { return }
        let seed: UInt64
        if let parsed = parsedSeed() {
            seed = parsed
        } else {
            seed = UInt64.random(in: 1...UInt64.max)
            seedTextByModel[id] = String(seed)
        }
        vectorByModel[id] = FaceLocalEngine.gaussianLatent(seed: seed, count: 512)
    }

    // MARK: - Regenerate

    /// Regenerate with a fresh roll. In seed mode that means a brand-new base
    /// seed (written into the seed box); in vector mode a new variation salt
    /// (the vector itself is kept — only the neighbours re-roll).
    func forceRegenerate() {
        if mode == .seed {
            seedText = String(UInt64.random(in: 0...UInt64.max))
        } else {
            saltByModel[selectedModelID] = UInt64.random(in: 1...UInt64.max)
            bumpGeneration(); persist()
        }
    }

    /// Loads a saved face's exact recipe into the controls (viewer "Use
    /// Image"): seed mode, its seed, its slider values.
    func applyRecipe(
        modelID: String, seed: UInt64,
        sliders: [String: Double], groups: [String: Bool]
    ) {
        if LocalFaceModel.find(modelID) != nil { selectedModelID = modelID }
        sliderValues = sliders
        enabledGroups = groups
        modeByModel[selectedModelID] = BaseMode.seed.rawValue
        seedTextByModel[selectedModelID] = String(seed)
        bumpGeneration(); persist()
    }

    // MARK: - Generation

    /// Regenerates the whole grid. Face 0 is always the base (the seed or the
    /// vector, with each slider at its start value); later faces vary the seed
    /// / sample the radius / draw ranged sliders.
    func regenerate() async {
        let model = selectedModel
        let count = max(4, min(faceCount, 100))
        let currentMode = mode
        let base = seedBase()
        let vseed = variationSeed()
        let vec = vector
        let rad = radius
        let wplusBase = activeWPlus()
        //  With a slider's Range on, every face is the same face, so only the ranged values change
        let sameFace = hasActiveRange

        slots = (0..<count).map { FaceSlot(id: $0) }
        timing = nil

        let directory: URL
        do {
            directory = try FaceLocalEngine.bundledDirectory()
            try await FaceLocalEngine.shared.preload(model: model, directory: directory)
        } catch {
            notice = "Face models are missing from the app bundle."
            return
        }
        let started = ContinuousClock.now

        for index in 0..<count {
            if Task.isCancelled { return }
            let edits = editsForFace(index, vseed: vseed, model: model)
            let faceIndex = sameFace ? 0 : index
            var result: FaceSlot
            if let wplusBase {
                let w = wplusForFace(faceIndex, base: wplusBase, vseed: vseed, radius: rad)
                result = await generateOneWPlus(
                    model: model, directory: directory, wplus: w, edits: edits)
            } else {
                let (z, seedLabel) = latentForFace(
                    faceIndex, mode: currentMode, base: base, vseed: vseed,
                    vec: vec, radius: rad)
                result = await generateOne(
                    model: model, directory: directory,
                    latent: z, edits: edits, seed: seedLabel)
            }
            result.id = index
            result.labels = rangeLabels(edits, model: model)
            if Task.isCancelled { return }
            guard index < slots.count else { return }
            slots[index] = result
        }
        let elapsed = started.duration(to: .now)
        let seconds = Double(elapsed.components.seconds) + Double(elapsed.components.attoseconds) / 1e18
        timing = String(format: "%d faces in %.1f s, %.2f s each", count, seconds, seconds / Double(count))
    }

    /// W+ neighbours: the base itself for face 0, else a small perturbation.
    private func wplusForFace(
        _ index: Int, base: [Float], vseed: UInt64, radius: Double
    ) -> [Float] {
        if index == 0 || radius <= 0 { return base }
        return perturb(base, seed: mix(vseed, index, 0xE4E), radius: radius * 0.5)
    }

    private func generateOneWPlus(
        model: LocalFaceModel, directory: URL, wplus: [Float], edits: [String: Float]
    ) async -> FaceSlot {
        do {
            let png = try await FaceLocalEngine.shared.png(
                model: model, directory: directory, wplus: wplus, edits: edits)
            return FaceSlot(
                id: 0, image: NSImage(data: png), pngData: png, wplus: wplus)
        } catch {
            return FaceSlot(
                id: 0, wplus: wplus,
                failure: (error as? LocalizedError)?.errorDescription ?? "Failed")
        }
    }

    /// Re-rolls a single slot with a fresh neighbour.
    func reroll(_ index: Int) {
        guard index < slots.count else { return }
        let model = selectedModel
        let currentMode = mode
        let vec = vector
        let rad = radius
        let wplusBase = activeWPlus()
        let random = UInt64.random(in: 1...UInt64.max)
        slots[index] = FaceSlot(id: index)
        Task {
            guard let directory = try? FaceLocalEngine.bundledDirectory() else { return }
            let edits = editsForFace(0, vseed: 0, model: model)
            if let wplusBase {
                let w = perturb(wplusBase, seed: random, radius: max(rad, 0.2) * 0.5)
                var result = await generateOneWPlus(
                    model: model, directory: directory, wplus: w, edits: edits)
                result.id = index
                guard index < slots.count, slots[index].image == nil else { return }
                slots[index] = result
                return
            }
            let z: [Float]
            let seedLabel: UInt64?
            switch currentMode {
            case .seed:
                z = FaceLocalEngine.gaussianLatent(seed: random, count: 512)
                seedLabel = random
            case .vector:
                z = perturb(vec, seed: random, radius: max(rad, 0.2))
                seedLabel = nil
            }
            var result = await generateOne(
                model: model, directory: directory,
                latent: z, edits: edits, seed: seedLabel)
            result.id = index
            guard index < slots.count, slots[index].image == nil else { return }
            slots[index] = result
        }
    }

    private func latentForFace(
        _ index: Int, mode: BaseMode, base: UInt64, vseed: UInt64,
        vec: [Float], radius: Double
    ) -> (z: [Float], seed: UInt64?) {
        switch mode {
        case .seed:
            //  The seed, then the seeds after it, one face each
            let seed = base &+ UInt64(index)
            return (FaceLocalEngine.gaussianLatent(seed: seed, count: 512), seed)
        case .vector:
            if index == 0 || radius <= 0 { return (vec, nil) }
            return (perturb(vec, seed: mix(vseed, index, 0xFACE), radius: radius), nil)
        }
    }

    private func perturb(_ base: [Float], seed: UInt64, radius: Double) -> [Float] {
        let scale = Float(radius)

        // W+ neighbour: optional coherent (broadcast) noise, then truncate
        // toward the average face by ψ to keep it realistic and sharp.
        if base.count == 18 * 512 {
            let noise: [Float]
            if coherentPerturb {
                let dir = FaceLocalEngine.gaussianLatent(seed: seed, count: 512)
                var n = [Float]()
                n.reserveCapacity(18 * 512)
                for _ in 0..<18 { n.append(contentsOf: dir) }
                noise = n
            } else {
                noise = FaceLocalEngine.gaussianLatent(seed: seed, count: base.count)
            }
            var out = base
            for k in 0..<out.count { out[k] += scale * noise[k] }
            let psi = Float(realism)
            if psi < 0.999, let mean = wAvg(), mean.count == out.count {
                for k in 0..<out.count { out[k] = mean[k] + psi * (out[k] - mean[k]) }
            }
            return out
        }

        // z neighbour: unchanged (the mapping network keeps it on-manifold).
        let noise = FaceLocalEngine.gaussianLatent(seed: seed, count: base.count)
        var z = base
        for k in 0..<min(z.count, noise.count) { z[k] += scale * noise[k] }
        return z
    }

    /// Per-face slider edits: start value for face 0, or a random draw within
    /// [start, rangeEnd] for later faces when that slider's range is on.
    /// The sliders whose Range is on and spans something, in the current model's enabled groups.
    private func rangedSliders(_ model: LocalFaceModel) -> [FaceSlider] {
        model.controls
            .filter { !$0.optional || enabledGroups[$0.id] == true }
            .flatMap(\.sliders)
            .filter { slider in
                guard rangeEnabled[slider.id] == true else { return false }
                let start = sliderValues[slider.id] ?? slider.neutral
                return (rangeEnd[slider.id] ?? start) != start
            }
    }

    /// True when any slider's Range is on, so the grid shows one face with different values.
    var hasActiveRange: Bool { !rangedSliders(selectedModel).isEmpty }

    /// "Smile 1.23" for each ranged slider, shown on the face in place of its seed.
    private func rangeLabels(_ edits: [String: Float], model: LocalFaceModel) -> [String] {
        rangedSliders(model).compactMap { slider in
            edits[slider.id].map { String(format: "%@ %.2f", slider.name, $0) }
        }
    }

    private func editsForFace(
        _ index: Int, vseed: UInt64, model: LocalFaceModel
    ) -> [String: Float] {
        var edits: [String: Float] = [:]
        var parameter = 0
        for group in model.controls {
            if group.optional && enabledGroups[group.id] != true { continue }
            for slider in group.sliders {
                parameter += 1
                let start = sliderValues[slider.id] ?? slider.neutral
                var value = start
                if index > 0, rangeEnabled[slider.id] == true {
                    let end = rangeEnd[slider.id] ?? start
                    let lo = min(start, end), hi = max(start, end)
                    if hi > lo {
                        value = lo + (hi - lo) * rand01(vseed, index, parameter)
                    }
                }
                edits[slider.id] = Float(value)
            }
        }
        return edits
    }

    private func generateOne(
        model: LocalFaceModel, directory: URL,
        latent: [Float], edits: [String: Float], seed: UInt64?
    ) async -> FaceSlot {
        do {
            let png = try await FaceLocalEngine.shared.png(
                model: model, directory: directory, latent: latent, edits: edits)
            return FaceSlot(
                id: 0, image: NSImage(data: png), pngData: png,
                seed: seed, vector: latent)
        } catch {
            return FaceSlot(
                id: 0, seed: seed, vector: latent,
                failure: (error as? LocalizedError)?.errorDescription ?? "Failed")
        }
    }

    // MARK: - Edits / display helpers

    func value(for slider: FaceSlider) -> Double {
        sliderValues[slider.id] ?? slider.neutral
    }

    func rangeEndValue(for slider: FaceSlider) -> Double {
        rangeEnd[slider.id] ?? (sliderValues[slider.id] ?? slider.neutral)
    }

    func isRangeOn(_ slider: FaceSlider) -> Bool {
        rangeEnabled[slider.id] ?? false
    }

    func isGroupEnabled(_ group: FaceControlGroup) -> Bool {
        group.optional ? (enabledGroups[group.id] ?? false) : true
    }

    private func currentEdits(for model: LocalFaceModel) -> [String: Float] {
        editsForFace(0, vseed: 0, model: model)
    }

    /// The full recipe for the current base settings, as labelled rows.
    func recipeDetails() -> [(label: String, value: String)] {
        var rows: [(String, String)] = [("Model", selectedModel.name)]
        for group in selectedModel.controls {
            let enabled = isGroupEnabled(group)
            if group.optional && !enabled { continue }
            var groupHadChange = false
            for slider in group.sliders {
                let value = sliderValues[slider.id] ?? slider.neutral
                if abs(value - slider.neutral) > 0.0001 {
                    rows.append((slider.name, FaceNumbers.display(value)))
                    groupHadChange = true
                }
            }
            if group.optional && !groupHadChange {
                rows.append((group.name, "on (defaults)"))
            }
        }
        return rows
    }

    func activeEditBrief() -> String {
        let edits = currentEdits(for: selectedModel)
        let named = selectedModel.sliders.compactMap { slider -> (String, Double)? in
            guard let value = edits[slider.id], abs(value - Float(slider.neutral)) > 0.001
            else { return nil }
            return (slider.name, Double(value))
        }
        return FacePrompt.localBrief(named)
    }

    // MARK: - Seed / RNG

    private func parsedSeed() -> UInt64? {
        UInt64(seedText.trimmingCharacters(in: .whitespaces))
    }

    private func seedBase() -> UInt64 {
        parsedSeed() ?? UInt64.random(in: 1...UInt64.max)
    }

    private func variationSeed() -> UInt64 {
        mode == .seed ? seedBase() : (saltByModel[selectedModelID] ?? 0x5EED_5A17)
    }

    private func rand01(_ a: UInt64, _ b: Int, _ c: Int) -> Double {
        var rng = SeedRNG(state: mixState(a, b, c))
        _ = rng.next()
        return Double(rng.next() >> 11) / Double(1 << 53)
    }

    private func mix(_ a: UInt64, _ b: Int, _ c: Int) -> UInt64 {
        var rng = SeedRNG(state: mixState(a, b, c))
        return rng.next()
    }

    private func mixState(_ a: UInt64, _ b: Int, _ c: Int) -> UInt64 {
        let state = a
            ^ (UInt64(bitPattern: Int64(b)) &* 0x9E37_79B9_7F4A_7C15)
            ^ (UInt64(bitPattern: Int64(c)) &* 0xD1B5_4A32_D192_ED03)
        return state == 0 ? 1 : state
    }
}

private struct SeedRNG: RandomNumberGenerator {
    var state: UInt64
    mutating func next() -> UInt64 {
        state &+= 0x9E37_79B9_7F4A_7C15
        var mixed = state
        mixed = (mixed ^ (mixed >> 30)) &* 0xBF58_476D_1CE4_E5B9
        mixed = (mixed ^ (mixed >> 27)) &* 0x94D0_49BB_1331_11EB
        return mixed ^ (mixed >> 31)
    }
}