bleam 0.0.7 → 0.0.9

package/templates/native/ios/Bleam.xcodeproj/xcshareddata/xcschemes/Bleam.xcscheme

@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1130"
+   version = "1.3">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "13B07F861A680F5B00A75B9A"
+               BuildableName = "bleam.app"
+               BlueprintName = "bleam"
+               ReferencedContainer = "container:bleam.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "00E356ED1AD99517003FC87E"
+               BuildableName = "bleamTests.xctest"
+               BlueprintName = "bleamTests"
+               ReferencedContainer = "container:bleam.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "13B07F861A680F5B00A75B9A"
+            BuildableName = "bleam.app"
+            BlueprintName = "bleam"
+            ReferencedContainer = "container:bleam.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "13B07F861A680F5B00A75B9A"
+            BuildableName = "bleam.app"
+            BlueprintName = "bleam"
+            ReferencedContainer = "container:bleam.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

package/templates/native/ios/GenerationService/GenerationService.entitlements

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>group.dev.bleam.app</string>
+	</array>
+</dict>
+</plist>

package/templates/native/ios/GenerationService/ImageGenerationRunner.swift

@@ -0,0 +1,591 @@
+import CoreGraphics
+import Foundation
+import ImageIO
+import MLX
+import UniformTypeIdentifiers
+
+final class ImageGenerationRunner: @unchecked Sendable {
+  private let request: GenerationWorkerRequest
+  private let emit: @Sendable (GenerationWorkerEvent) -> Void
+  private var isCancelled = false
+
+  init(
+    request: GenerationWorkerRequest,
+    emit: @escaping @Sendable (GenerationWorkerEvent) -> Void
+  ) {
+    self.request = request
+    self.emit = emit
+  }
+
+  func cancel() {
+    isCancelled = true
+  }
+
+  func run(isCancelled externalCancellation: @escaping @Sendable () -> Bool) async throws {
+    let startedAt = Date()
+    let jobID = request.jobID.uuidString
+    Flux2Debug.setLogSink { [emit] level, message in
+      let logLevel: String
+      switch level {
+      case .verbose: logLevel = "debug"
+      case .info: logLevel = "info"
+      case .warning: logLevel = "warn"
+      case .error: logLevel = "error"
+      }
+      emit(.init(
+        type: .log,
+        message: message,
+        level: logLevel,
+        category: "flux2",
+        jobID: jobID
+      ))
+    }
+    logMemory("job start")
+    defer {
+      Flux2Debug.setLogSink(nil)
+      MLX.Memory.clearCache()
+      log("job elapsed=\(Self.formatDuration(Date().timeIntervalSince(startedAt)))")
+      logMemory("job end")
+    }
+
+    try validateRequest()
+    try FileManager.default.createDirectory(
+      at: URL(fileURLWithPath: request.stagingDirectoryPath, isDirectory: true),
+      withIntermediateDirectories: true
+    )
+    emit(.init(type: .ready, message: nil))
+
+    guard !shouldCancel(externalCancellation) else {
+      throw CancellationError()
+    }
+
+    let textEmbeddings: MLXArray = try timed("text encoder", stage: "encode") {
+      let embeddings: MLXArray = try { () throws -> MLXArray in
+        // The XPC service is the only place that may hold MLX generation
+        // models. Keep the text encoder scoped to this closure so its weights
+        // are gone before the Flux transformer stage starts.
+        let textEncoder = KleinTextEncoder(
+          modelPath: URL(fileURLWithPath: request.textEncoderPath, isDirectory: true)
+        )
+        return try textEncoder.encode(
+          inputIds: request.inputIds,
+          attentionMask: request.attentionMask
+        )
+      }()
+      MLX.Memory.clearCache()
+      logMemory("after text encoder release")
+      return embeddings
+    }
+
+    guard !shouldCancel(externalCancellation) else {
+      throw CancellationError()
+    }
+
+    let image = try timed("flux generation", stage: "denoise") {
+      let generationMode = try generationMode()
+      let outputWidth = request.outpaintWidth ?? request.width
+      let outputHeight = request.outpaintHeight ?? request.height
+      // First service version is deliberately memory-first: the runner releases
+      // text encoder, transformer, and VAE stages instead of keeping a warm
+      // pipeline. Add warm caching later only behind explicit idle trimming.
+      let runner = FluxImageRunner(paths: FluxImageRunnerPaths(
+        transformer: URL(fileURLWithPath: request.transformerPath, isDirectory: true),
+        vae: URL(fileURLWithPath: request.vaePath, isDirectory: true)
+      ))
+      var fluxStage = "denoise"
+      do {
+        return try runner.generate(
+          textEmbeddings: textEmbeddings,
+          height: outputHeight,
+          width: outputWidth,
+          steps: request.steps,
+          guidance: Float(request.guidance),
+          seed: request.seed.flatMap { $0 >= 0 ? UInt64($0) : nil },
+          mode: generationMode,
+          loras: loraConfigs(),
+          sigmas: request.sigmaSchedule?.map(Float.init),
+          onStage: { stage in fluxStage = stage },
+          onProgress: { [emit] currentStep, totalSteps in
+            emit(.init(type: .progress, currentStep: currentStep, totalSteps: totalSteps))
+          }
+        )
+      } catch {
+        throw GenerationWorkerFailure(message: error.localizedDescription, stage: fluxStage)
+      }
+    }
+
+    guard !shouldCancel(externalCancellation) else {
+      throw CancellationError()
+    }
+
+    let outputURL = try timed("png write", stage: "write") {
+      try Self.writePNG(image, directory: URL(
+        fileURLWithPath: request.stagingDirectoryPath,
+        isDirectory: true
+      ))
+    }
+
+    emit(.init(
+      type: .completed,
+      path: outputURL.path,
+      width: image.width,
+      height: image.height,
+      model: request.model,
+      metadata: GenerationWorkerMetadata(
+        model: request.model,
+        width: image.width,
+        height: image.height,
+        steps: request.steps,
+        guidance: request.guidance,
+        strength: request.strength,
+        seed: request.seed,
+        elapsedMs: Int(Date().timeIntervalSince(startedAt) * 1000),
+        appliedLoRAs: appliedLoRAs(),
+        sigmaSchedule: request.sigmaSchedule
+      )
+    ))
+  }
+
+  private func shouldCancel(_ externalCancellation: @escaping @Sendable () -> Bool) -> Bool {
+    Task.isCancelled || isCancelled || externalCancellation()
+  }
+
+  private func validateRequest() throws {
+    guard request.model == "flux2-klein-4b-8bit-abliterated" else {
+      throw GenerationWorkerFailure(message: "Unsupported image model: \(request.model)")
+    }
+    guard !request.prompt.isEmpty else {
+      throw GenerationWorkerFailure(message: "Expected prompt")
+    }
+    guard request.width > 0, request.height > 0, request.steps > 0, request.guidance > 0 else {
+      throw GenerationWorkerFailure(message: "Invalid generation options")
+    }
+    if let strength = request.strength, !(strength > 0 && strength <= 1) {
+      throw GenerationWorkerFailure(message: "Image strength must be greater than 0 and at most 1")
+    }
+    if let sigmas = request.sigmaSchedule {
+      guard !sigmas.isEmpty,
+        sigmas.enumerated().allSatisfy({ index, sigma in
+          sigma.isFinite && sigma > 0 && sigma <= 1 && (index == 0 || sigma < sigmas[index - 1])
+        })
+      else {
+        throw GenerationWorkerFailure(message: "sigmaSchedule must contain descending values greater than 0 and at most 1")
+      }
+      guard sigmas.count == request.steps else {
+        throw GenerationWorkerFailure(message: "sigmaSchedule count must match steps")
+      }
+    }
+    if let sourceImagePath = request.sourceImagePath, sourceImagePath.isEmpty {
+      throw GenerationWorkerFailure(message: "Source image path must not be empty")
+    }
+    if let maskImagePath = request.maskImagePath, maskImagePath.isEmpty {
+      throw GenerationWorkerFailure(message: "Mask image path must not be empty")
+    }
+    if request.maskImagePath != nil, request.sourceImagePath == nil {
+      throw GenerationWorkerFailure(message: "Mask image requires a source image")
+    }
+    if let maskMode = request.maskMode, maskMode != "paint" && maskMode != "preserve" {
+      throw GenerationWorkerFailure(message: "maskMode must be paint or preserve")
+    }
+    if request.outpaintWidth != nil || request.outpaintHeight != nil || request.outpaintSourceX != nil || request.outpaintSourceY != nil || request.outpaintSourceWidth != nil || request.outpaintSourceHeight != nil {
+      guard request.sourceImagePath != nil else {
+        throw GenerationWorkerFailure(message: "Outpaint requires a source image")
+      }
+      guard let width = request.outpaintWidth, width > 0, let height = request.outpaintHeight, height > 0 else {
+        throw GenerationWorkerFailure(message: "Outpaint requires positive width and height")
+      }
+      guard let sourceX = request.outpaintSourceX,
+        let sourceY = request.outpaintSourceY,
+        let sourceWidth = request.outpaintSourceWidth, sourceWidth > 0,
+        let sourceHeight = request.outpaintSourceHeight, sourceHeight > 0
+      else {
+        throw GenerationWorkerFailure(message: "Outpaint requires a valid source rect")
+      }
+      guard sourceX < width, sourceY < height, sourceX + sourceWidth > 0, sourceY + sourceHeight > 0 else {
+        throw GenerationWorkerFailure(message: "Outpaint source rect must intersect the canvas")
+      }
+      if request.outpaintAutoCrop != true,
+        (sourceX < 0 || sourceY < 0 || sourceX + sourceWidth > width || sourceY + sourceHeight > height)
+      {
+        throw GenerationWorkerFailure(message: "Outpaint source rect must fit within the canvas unless autoCrop is enabled")
+      }
+    }
+    if let resizeMode = request.resizeMode, !["stretch", "fit", "crop"].contains(resizeMode) {
+      throw GenerationWorkerFailure(message: "Resize mode must be stretch, fit, or crop")
+    }
+    if let maxInputLongSide = request.maxInputLongSide, maxInputLongSide != 0 && maxInputLongSide < 64 {
+      throw GenerationWorkerFailure(message: "maxInputLongSide must be 0 or at least 64")
+    }
+    guard request.referenceImagePaths.allSatisfy({ !$0.isEmpty }) else {
+      throw GenerationWorkerFailure(message: "Reference image paths must not be empty")
+    }
+    guard request.referenceImagePaths.count <= 3 else {
+      throw GenerationWorkerFailure(message: "Provide at most 3 reference images")
+    }
+    if let referenceInfluences = request.referenceInfluences, referenceInfluences.count != request.referenceImagePaths.count {
+      throw GenerationWorkerFailure(message: "referenceInfluences count must match reference image count")
+    }
+    if let referenceInfluences = request.referenceInfluences, !referenceInfluences.allSatisfy({ $0.isFinite && $0 >= 0 }) {
+      throw GenerationWorkerFailure(message: "referenceInfluences must be non-negative numbers")
+    }
+    guard request.loraPaths.allSatisfy({ !$0.isEmpty }) else {
+      throw GenerationWorkerFailure(message: "LoRA paths must not be empty")
+    }
+    if let loraScales = request.loraScales, loraScales.count != request.loraPaths.count {
+      throw GenerationWorkerFailure(message: "loraScales count must match LoRA path count")
+    }
+    if let loraScales = request.loraScales, !loraScales.allSatisfy({ $0.isFinite && $0 > 0 }) {
+      throw GenerationWorkerFailure(message: "loraScales must be positive numbers")
+    }
+    if let loraIds = request.loraIds, loraIds.count != request.loraPaths.count {
+      throw GenerationWorkerFailure(message: "loraIds count must match LoRA path count")
+    }
+    guard !request.inputIds.isEmpty, request.inputIds.count == request.attentionMask.count else {
+      throw GenerationWorkerFailure(message: "Invalid tokenized prompt")
+    }
+
+    let fileManager = FileManager.default
+    for path in [request.modelRoot, request.textEncoderPath, request.transformerPath, request.vaePath] {
+      var isDirectory: ObjCBool = false
+      guard fileManager.fileExists(atPath: path, isDirectory: &isDirectory), isDirectory.boolValue else {
+        throw GenerationWorkerFailure(message: "Missing model directory: \(path)")
+      }
+    }
+
+    for path in [request.sourceImagePath, request.maskImagePath].compactMap({ $0 }) + request.referenceImagePaths + request.loraPaths {
+      var isDirectory: ObjCBool = false
+      guard fileManager.fileExists(atPath: path, isDirectory: &isDirectory), !isDirectory.boolValue else {
+        throw GenerationWorkerFailure(message: "Missing input file: \(path)")
+      }
+    }
+
+    for path in request.loraPaths {
+      try Self.validateSafetensors(atPath: path)
+    }
+  }
+
+  private static func validateSafetensors(atPath path: String) throws {
+    let url = URL(fileURLWithPath: path)
+    let fileSize: UInt64
+    do {
+      let attributes = try FileManager.default.attributesOfItem(atPath: path)
+      fileSize = (attributes[.size] as? NSNumber)?.uint64Value ?? 0
+    } catch {
+      throw GenerationWorkerFailure(message: "Unable to inspect LoRA file: \(path)")
+    }
+
+    guard fileSize > 8 else {
+      throw GenerationWorkerFailure(message: "Invalid LoRA safetensors file (missing 8-byte header): \(path)")
+    }
+
+    do {
+      let handle = try FileHandle(forReadingFrom: url)
+      defer { try? handle.close() }
+
+      guard let prefix = try handle.read(upToCount: 8), prefix.count == 8 else {
+        throw GenerationWorkerFailure(message: "Invalid LoRA safetensors file (unable to read header): \(path)")
+      }
+      let headerLength = prefix.enumerated().reduce(UInt64(0)) { value, byte in
+        value | (UInt64(byte.element) << UInt64(byte.offset * 8))
+      }
+      guard headerLength > 0,
+        headerLength <= 100_000_000,
+        headerLength <= fileSize - 8,
+        headerLength <= UInt64(Int.max)
+      else {
+        throw GenerationWorkerFailure(message: "Invalid LoRA safetensors header length: \(path)")
+      }
+
+      guard let header = try handle.read(upToCount: Int(headerLength)),
+        header.count == Int(headerLength),
+        let object = try JSONSerialization.jsonObject(with: header) as? [String: Any]
+      else {
+        throw GenerationWorkerFailure(message: "Invalid LoRA safetensors header: \(path)")
+      }
+
+      let dataSize = fileSize - 8 - headerLength
+      var tensorCount = 0
+      for (key, value) in object where key != "__metadata__" {
+        guard let tensor = value as? [String: Any],
+          let offsets = tensor["data_offsets"] as? [NSNumber],
+          offsets.count == 2
+        else {
+          throw GenerationWorkerFailure(message: "Invalid LoRA tensor metadata for \(key): \(path)")
+        }
+        let start = offsets[0].uint64Value
+        let end = offsets[1].uint64Value
+        guard start <= end, end <= dataSize else {
+          throw GenerationWorkerFailure(message: "LoRA tensor data is truncated for \(key): \(path)")
+        }
+        tensorCount += 1
+      }
+      guard tensorCount > 0 else {
+        throw GenerationWorkerFailure(message: "LoRA safetensors file contains no tensors: \(path)")
+      }
+    } catch let failure as GenerationWorkerFailure {
+      throw failure
+    } catch {
+      throw GenerationWorkerFailure(message: "Invalid LoRA safetensors file: \(path) - \(error.localizedDescription)")
+    }
+  }
+
+  private func loraConfigs() -> [FluxLoRAConfig] {
+    request.loraPaths.enumerated().map { index, path in
+      FluxLoRAConfig(
+        id: request.loraIds?[safe: index],
+        path: path,
+        scale: Float(request.loraScales?[safe: index] ?? 1)
+      )
+    }
+  }
+
+  private func appliedLoRAs() -> [GenerationWorkerLoRA]? {
+    guard !request.loraPaths.isEmpty else { return nil }
+    return request.loraPaths.enumerated().map { index, path in
+      GenerationWorkerLoRA(
+        id: request.loraIds?[safe: index],
+        path: path,
+        scale: request.loraScales?[safe: index] ?? 1
+      )
+    }
+  }
+
+  private func generationMode() throws -> FluxImageGenerationMode {
+    let maxInputLongSide = request.maxInputLongSide.flatMap { $0 > 0 ? $0 : nil }
+    let sourceImage = try request.sourceImagePath.map { try Self.loadImage(path: $0, maxLongSide: maxInputLongSide) }
+    let maskImage = try request.maskImagePath.map { try Self.loadImage(path: $0, maxLongSide: maxInputLongSide) }
+    let loadedReferences = try request.referenceImagePaths.map { try Self.loadImage(path: $0, maxLongSide: maxInputLongSide) }
+    let targetWidth = request.outpaintWidth ?? request.width
+    let targetHeight = request.outpaintHeight ?? request.height
+    let resizeMode = request.resizeMode ?? "stretch"
+    let referenceImages = try loadedReferences.map {
+      try Self.resizeImage($0, width: targetWidth, height: targetHeight, mode: resizeMode)
+    }
+    let preparedSource: CGImage?
+    let preparedMask: CGImage?
+    if let sourceImage, request.outpaintWidth != nil || request.outpaintHeight != nil {
+      let prepared = try Self.outpaintImages(sourceImage: sourceImage, request: request)
+      preparedSource = prepared.source
+      preparedMask = prepared.mask
+      log("outpaint canvas=\(request.outpaintWidth ?? request.width)x\(request.outpaintHeight ?? request.height) sourceRect=\(request.outpaintSourceX ?? 0),\(request.outpaintSourceY ?? 0),\(request.outpaintSourceWidth ?? 0),\(request.outpaintSourceHeight ?? 0)")
+    } else {
+      preparedSource = try sourceImage.map {
+        try Self.resizeImage($0, width: targetWidth, height: targetHeight, mode: resizeMode)
+      }
+      preparedMask = try maskImage.map {
+        try Self.resizeImage($0, width: targetWidth, height: targetHeight, mode: "stretch", grayscale: true)
+      }
+    }
+
+    guard sourceImage != nil || !referenceImages.isEmpty else {
+      return .textToImage
+    }
+
+    log("generation mode=imageToImage source=\(preparedSource != nil) mask=\(preparedMask != nil) refs=\(referenceImages.count) strength=\(request.strength ?? 0.8)")
+
+    return .imageToImage(
+      sourceImage: preparedSource,
+      maskImage: preparedMask,
+      maskMode: request.maskMode == "preserve" ? .preserve : .paint,
+      referenceImages: referenceImages,
+      referenceInfluences: request.referenceInfluences?.map(Float.init),
+      strength: Float(request.strength ?? 0.8)
+    )
+  }
+
+  private static func loadImage(path: String, maxLongSide: Int?) throws -> CGImage {
+    let url = URL(fileURLWithPath: path)
+    guard let source = CGImageSourceCreateWithURL(url as CFURL, nil) else {
+      throw GenerationWorkerFailure(message: "Failed to load image: \(path)")
+    }
+    let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as? [CFString: Any]
+    let pixelWidth = properties?[kCGImagePropertyPixelWidth] as? Int ?? 1
+    let pixelHeight = properties?[kCGImagePropertyPixelHeight] as? Int ?? 1
+    let thumbnailMax = maxLongSide.map { min($0, max(pixelWidth, pixelHeight)) } ?? max(pixelWidth, pixelHeight)
+    let options: [CFString: Any] = [
+      kCGImageSourceCreateThumbnailFromImageAlways: true,
+      kCGImageSourceCreateThumbnailWithTransform: true,
+      kCGImageSourceThumbnailMaxPixelSize: max(1, thumbnailMax),
+    ]
+    guard let image = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
+      throw GenerationWorkerFailure(message: "Failed to decode image: \(path)")
+    }
+    return try resizeImage(image, width: image.width, height: image.height, mode: "stretch")
+  }
+
+  private static func resizeImage(
+    _ image: CGImage,
+    width: Int,
+    height: Int,
+    mode: String,
+    grayscale: Bool = false
+  ) throws -> CGImage {
+    let colorSpace = grayscale
+      ? CGColorSpaceCreateDeviceGray()
+      : (CGColorSpace(name: CGColorSpace.sRGB) ?? CGColorSpaceCreateDeviceRGB())
+    let bitmapInfo = grayscale
+      ? CGImageAlphaInfo.none.rawValue
+      : CGImageAlphaInfo.noneSkipLast.rawValue
+    guard let context = CGContext(
+      data: nil,
+      width: width,
+      height: height,
+      bitsPerComponent: 8,
+      bytesPerRow: 0,
+      space: colorSpace,
+      bitmapInfo: bitmapInfo
+    ) else {
+      throw GenerationWorkerFailure(message: "Failed to create normalized image canvas")
+    }
+    context.setFillColor(gray: 0, alpha: 1)
+    context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+    context.interpolationQuality = .high
+
+    let canvas = CGSize(width: width, height: height)
+    let source = CGSize(width: image.width, height: image.height)
+    let destination: CGRect
+    if mode == "stretch" {
+      destination = CGRect(origin: .zero, size: canvas)
+    } else {
+      let scale = mode == "fit"
+        ? min(canvas.width / source.width, canvas.height / source.height)
+        : max(canvas.width / source.width, canvas.height / source.height)
+      let size = CGSize(width: source.width * scale, height: source.height * scale)
+      destination = CGRect(
+        x: (canvas.width - size.width) / 2,
+        y: (canvas.height - size.height) / 2,
+        width: size.width,
+        height: size.height
+      )
+    }
+    context.draw(image, in: destination)
+    guard let result = context.makeImage() else {
+      throw GenerationWorkerFailure(message: "Failed to normalize image")
+    }
+    return result
+  }
+
+  private static func outpaintImages(sourceImage: CGImage, request: GenerationWorkerRequest) throws -> (source: CGImage, mask: CGImage) {
+    guard let width = request.outpaintWidth, let height = request.outpaintHeight else {
+      throw GenerationWorkerFailure(message: "Outpaint requires width and height")
+    }
+    guard let sourceX = request.outpaintSourceX,
+      let sourceY = request.outpaintSourceY,
+      let sourceWidth = request.outpaintSourceWidth,
+      let sourceHeight = request.outpaintSourceHeight
+    else {
+      throw GenerationWorkerFailure(message: "Outpaint requires a source rect")
+    }
+    guard sourceWidth > 0, sourceHeight > 0,
+      sourceX < width, sourceY < height, sourceX + sourceWidth > 0, sourceY + sourceHeight > 0
+    else {
+      throw GenerationWorkerFailure(message: "Outpaint source rect must intersect the canvas")
+    }
+
+    guard let sourceContext = CGContext(
+      data: nil,
+      width: width,
+      height: height,
+      bitsPerComponent: 8,
+      bytesPerRow: 0,
+      space: CGColorSpace(name: CGColorSpace.sRGB) ?? CGColorSpaceCreateDeviceRGB(),
+      bitmapInfo: CGImageAlphaInfo.noneSkipLast.rawValue
+    ) else {
+      throw GenerationWorkerFailure(message: "Failed to create outpaint source canvas")
+    }
+    sourceContext.setFillColor(CGColor(red: 0, green: 0, blue: 0, alpha: 1))
+    sourceContext.fill(CGRect(x: 0, y: 0, width: width, height: height))
+    sourceContext.interpolationQuality = .high
+    let sourceRect = CGRect(x: CGFloat(sourceX), y: CGFloat(sourceY), width: CGFloat(sourceWidth), height: CGFloat(sourceHeight))
+    sourceContext.draw(sourceImage, in: sourceRect)
+    guard let expandedSource = sourceContext.makeImage() else {
+      throw GenerationWorkerFailure(message: "Failed to create outpaint source image")
+    }
+
+    guard let maskContext = CGContext(
+      data: nil,
+      width: width,
+      height: height,
+      bitsPerComponent: 8,
+      bytesPerRow: 0,
+      space: CGColorSpaceCreateDeviceGray(),
+      bitmapInfo: CGImageAlphaInfo.none.rawValue
+    ) else {
+      throw GenerationWorkerFailure(message: "Failed to create outpaint mask canvas")
+    }
+    maskContext.setFillColor(gray: 1, alpha: 1)
+    maskContext.fill(CGRect(x: 0, y: 0, width: width, height: height))
+    maskContext.setFillColor(gray: 0, alpha: 1)
+    maskContext.fill(sourceRect)
+    guard let outpaintMask = maskContext.makeImage() else {
+      throw GenerationWorkerFailure(message: "Failed to create outpaint mask image")
+    }
+
+    return (expandedSource, outpaintMask)
+  }
+
+  private func timed<T>(_ label: String, stage: String, _ operation: () throws -> T) throws -> T {
+    logMemory("before \(label)")
+    let startedAt = Date()
+    do {
+      let value = try operation()
+      log("\(label) elapsed=\(Self.formatDuration(Date().timeIntervalSince(startedAt)))")
+      logMemory("after \(label)")
+      return value
+    } catch {
+      log("\(label) failed elapsed=\(Self.formatDuration(Date().timeIntervalSince(startedAt))) error=\(error.localizedDescription)")
+      logMemory("after failed \(label)")
+      if let failure = error as? GenerationWorkerFailure, failure.stage != nil {
+        throw failure
+      }
+      if error is CancellationError {
+        throw error
+      }
+      throw GenerationWorkerFailure(message: error.localizedDescription, stage: stage)
+    }
+  }
+
+  private static func writePNG(_ image: CGImage, directory: URL) throws -> URL {
+    do {
+      try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+    } catch {
+      throw GenerationWorkerFailure(message: "Failed to create output directory: \(directory.path) - \(error.localizedDescription)")
+    }
+
+    let outputURL = directory.appendingPathComponent("flux-\(UUID().uuidString).png")
+    guard let destination = CGImageDestinationCreateWithURL(outputURL as CFURL, UTType.png.identifier as CFString, 1, nil) else {
+      throw GenerationWorkerFailure(message: "Failed to create image destination: \(outputURL.path)")
+    }
+
+    CGImageDestinationAddImage(destination, image, nil)
+    guard CGImageDestinationFinalize(destination) else {
+      throw GenerationWorkerFailure(message: "Failed to write generated image: \(outputURL.path)")
+    }
+    return outputURL
+  }
+
+  private func logMemory(_ label: String) {
+    log("\(label) active=\(MLX.Memory.activeMemory / 1_048_576)MB cache=\(MLX.Memory.cacheMemory / 1_048_576)MB")
+  }
+
+  private func log(_ message: String) {
+    print("[GenerationService] \(request.jobID) \(message)")
+    emit(.init(type: .log, message: message, level: "info", category: "imagegen", jobID: request.jobID.uuidString))
+  }
+
+  private static func formatDuration(_ duration: TimeInterval) -> String {
+    if duration < 60 {
+      return String(format: "%.1fs", duration)
+    }
+
+    let minutes = Int(duration) / 60
+    let seconds = duration - Double(minutes * 60)
+    return String(format: "%dm %.1fs", minutes, seconds)
+  }
+}
+
+private extension Array {
+  subscript(safe index: Int) -> Element? {
+    indices.contains(index) ? self[index] : nil
+  }
+}