@dvai-bridge/ios-llama-core 4.0.0

package/ios/Sources/DVAILlamaCoreObjC/include/LlamaCppBridge.h

@@ -0,0 +1,101 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Objective-C++ bridge to llama.cpp. Wraps the C API for use from Swift via the
+/// `DVAICapacitorLlamaObjC` module. Owns the `llama_model` and `llama_context`
+/// for the lifetime of a load/unload cycle.
+@interface LlamaCppBridge : NSObject
+
+@property (nonatomic, readonly, getter=isLoaded) BOOL loaded;
+@property (nonatomic, readonly, copy, nullable) NSString *currentModelPath;
+
+- (instancetype)init;
+
+- (BOOL)loadModelAtPath:(NSString *)path
+             mmprojPath:(nullable NSString *)mmprojPath
+              gpuLayers:(int)gpuLayers
+            contextSize:(int)contextSize
+                threads:(int)threads
+          embeddingMode:(BOOL)embeddingMode
+                  error:(NSError **)error;
+
+- (void)unload;
+
+- (NSString *)versionString;
+
+/// Greedy-sample `maxTokens` tokens from the loaded model for the given prompt.
+/// `temperature` and `topP` are accepted but currently ignored — this entry point
+/// uses a deterministic greedy sampler for Task 30. Future work (Task 36) will
+/// honour temperature/top-p via additional sampler-chain stages.
+- (nullable NSString *)completePrompt:(NSString *)prompt
+                            maxTokens:(int)maxTokens
+                          temperature:(float)temperature
+                                 topP:(float)topP
+                                error:(NSError **)error;
+
+/// Compute an embedding vector for the given text. Requires the model to have
+/// been loaded with `embeddingMode:YES`; otherwise the returned values are
+/// undefined / not meaningful (the handler layer is responsible for the 400
+/// short-circuit before we get here). Returns the per-dimension floats (length
+/// == llama_n_embd(model)) wrapped as `NSNumber` doubles.
+- (nullable NSArray<NSNumber *> *)embedding:(NSString *)text
+                                      error:(NSError **)error;
+
+/// Whether a multimodal projector (mmproj) has been loaded for this bridge.
+@property (nonatomic, readonly, getter=isMmprojLoaded) BOOL mmprojLoaded;
+
+/// Load a multimodal projector (mmproj). The main model must already be
+/// loaded — the projector is always paired with a text model. Phase 2A Pass 2
+/// wires the real `mtmd_init_from_file()` call.
+///
+/// `useGPU` controls `mtmd_context_params.use_gpu`. Pass `YES` for production
+/// (Metal-accelerated CLIP / vision-encoder pass on real iPhone). Pass `NO`
+/// in environments where Metal allocation can't accommodate the projector's
+/// position-embedding tensor — most commonly the iOS Simulator, where
+/// `_xpc_shmem_create_with_prot` aborts on tensors >~ 60 MiB. The bridge
+/// uses YES by default. Returns NO on failure (with `error` populated).
+- (BOOL)loadMmprojAtPath:(NSString *)mmprojPath
+                  useGPU:(BOOL)useGPU
+                   error:(NSError **)error;
+
+/// Convenience wrapper that defaults `useGPU:YES`. Most callers want this.
+- (BOOL)loadMmprojAtPath:(NSString *)mmprojPath
+                   error:(NSError **)error;
+
+/// Unload the multimodal projector. Safe to call when nothing is loaded
+/// (idempotent). Frees the underlying mtmd_context.
+- (void)unloadMmproj;
+
+/// Apply a chat template via `llama_chat_apply_template`. If `templateOverride`
+/// is nil/empty, the model's bundled `tokenizer.chat_template` (via
+/// `llama_model_chat_template`) is used. `messages` is an array of
+/// `@{ @"role": @"...", @"content": @"..." }` dicts. Returns the rendered
+/// prompt string with role markers; multimodal callers should pre-populate
+/// `<__media__>` markers in the content fields where image/audio bytes will
+/// splice in.
+- (nullable NSString *)applyChatTemplate:(nullable NSString *)templateOverride
+                                messages:(NSArray<NSDictionary<NSString *, NSString *> *> *)messages
+                            addAssistant:(BOOL)addAssistant
+                                   error:(NSError **)error;
+
+/// Multimodal completion. `prompt` must contain N `<__media__>` markers
+/// matching the count of `media`. Bytes are auto-detected as image or audio
+/// via `mtmd_helper_bitmap_init_from_buf` (magic bytes); the caller must
+/// supply media in declaration order (i.e. the same order the markers
+/// appear in `prompt`). Returns the generated text. Throws on tokenization
+/// / eval / decode failures.
+- (nullable NSString *)completeMultimodalPrompt:(NSString *)prompt
+                                          media:(NSArray<NSData *> *)mediaInOrder
+                                      maxTokens:(int)maxTokens
+                                    temperature:(float)temperature
+                                           topP:(float)topP
+                                          error:(NSError **)error;
+
+/// Returns YES if the loaded model declares an audio encoder (via
+/// `mtmd_support_audio()`). Always NO when no mmproj is loaded.
+- (BOOL)hasAudioEncoder;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Tests/DVAILlamaCoreTests/AudioDecoderTest.swift

@@ -0,0 +1,46 @@
+import XCTest
+@testable import DVAILlamaCore
+
+final class AudioDecoderTest: XCTestCase {
+    func testPCM16PassThrough() async throws {
+        let pcm = try Data(contentsOf: audioFixtureURL("pcm16-1s-16khz-mono.bin"))
+        let result = try await AudioDecoder.decode(data: pcm, format: .pcm16)
+        XCTAssertEqual(result.count, pcm.count)
+    }
+
+    func testWavToPCM() async throws {
+        let wav = try Data(contentsOf: audioFixtureURL("wav-1s-16khz-mono.wav"))
+        let result = try await AudioDecoder.decode(data: wav, format: .wav)
+        // 1s @ 16kHz mono PCM16 = 32000 bytes (allow ±5%).
+        XCTAssertGreaterThan(result.count, 30000)
+        XCTAssertLessThan(result.count, 34000)
+    }
+
+    func testM4AToPCM() async throws {
+        let m4a = try Data(contentsOf: audioFixtureURL("m4a-1s.m4a"))
+        let result = try await AudioDecoder.decode(data: m4a, format: .m4a)
+        // M4A AAC 1s decodes to ~32000 bytes; AAC priming may shave a few hundred samples.
+        XCTAssertGreaterThan(result.count, 25000)
+        XCTAssertLessThan(result.count, 36000)
+    }
+
+    /// Walks up from this test source file until it finds the repo-root
+    /// `fixtures/` directory. We don't bundle the fixtures into the SwiftPM
+    /// test target's resources because they're shared with Android and Node
+    /// tests.
+    private func fixturesURL() -> URL {
+        var dir = URL(fileURLWithPath: #file).deletingLastPathComponent()
+        while !FileManager.default.fileExists(atPath: dir.appendingPathComponent("fixtures").path) {
+            let parent = dir.deletingLastPathComponent()
+            if parent.path == dir.path {
+                fatalError("fixtures dir not found walking up from \(#file)")
+            }
+            dir = parent
+        }
+        return dir.appendingPathComponent("fixtures")
+    }
+
+    private func audioFixtureURL(_ name: String) -> URL {
+        fixturesURL().appendingPathComponent("audio").appendingPathComponent(name)
+    }
+}

package/ios/Tests/DVAILlamaCoreTests/ContentPartsTranslatorTest.swift

@@ -0,0 +1,361 @@
+import XCTest
+@testable import DVAILlamaCore
+
+final class ContentPartsTranslatorTest: XCTestCase {
+    // MARK: - Mocks
+
+    /// Image decoder that returns canned bytes per URL. Records every call so
+    /// tests can assert which URLs were passed in and in what order.
+    final class MockImageDecoder: ImageDecoderProtocol {
+        var responses: [String: Data] = [:]
+        var calls: [String] = []
+        func resolve(url: String) async throws -> Data {
+            calls.append(url)
+            if let bytes = responses[url] { return bytes }
+            return Data([0xDE, 0xAD, 0xBE, 0xEF])
+        }
+    }
+
+    /// Audio-decoder closure factory. Records each call's `(bytesIn, format)`
+    /// and returns canned PCM bytes.
+    final class AudioRecorder {
+        var calls: [(Data, AudioFormat)] = []
+        var pcmOut: Data = Data([0x11, 0x22, 0x33, 0x44])
+        func make() -> (Data, AudioFormat) async throws -> Data {
+            { [unowned self] data, format in
+                self.calls.append((data, format))
+                return self.pcmOut
+            }
+        }
+    }
+
+    // MARK: - Fixture loader
+
+    /// Loads `transport-fixtures.json` from the repo-root `fixtures/` dir.
+    /// For `CHAT_REQUEST_AUDIO_PCM16` the `data` field carries the literal
+    /// `"<replaced-by-loader>"` placeholder; we substitute the base64 of the
+    /// PCM16 fixture file before returning.
+    private func loadFixture(_ key: String) throws -> [String: Any] {
+        let url = fixturesURL().appendingPathComponent("transport-fixtures.json")
+        let data = try Data(contentsOf: url)
+        guard var root = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+              var fixture = root[key] as? [String: Any] else {
+            XCTFail("fixture \(key) missing or not an object")
+            return [:]
+        }
+        if key == "CHAT_REQUEST_AUDIO_PCM16" {
+            let pcmURL = fixturesURL().appendingPathComponent("audio").appendingPathComponent("pcm16-1s-16khz-mono.bin")
+            let pcmBytes = try Data(contentsOf: pcmURL)
+            let b64 = pcmBytes.base64EncodedString()
+            // Mutate messages[0].content[0].input_audio.data
+            if var messages = fixture["messages"] as? [[String: Any]],
+               var msg0 = messages.first,
+               var parts = msg0["content"] as? [[String: Any]],
+               var part0 = parts.first,
+               var audio = part0["input_audio"] as? [String: Any] {
+                audio["data"] = b64
+                part0["input_audio"] = audio
+                parts[0] = part0
+                msg0["content"] = parts
+                messages[0] = msg0
+                fixture["messages"] = messages
+                root[key] = fixture
+            } else {
+                XCTFail("CHAT_REQUEST_AUDIO_PCM16 fixture shape unexpected")
+            }
+        }
+        return fixture
+    }
+
+    private func messages(from fixture: [String: Any]) -> [[String: Any]] {
+        (fixture["messages"] as? [[String: Any]]) ?? []
+    }
+
+    private func fixturesURL() -> URL {
+        var dir = URL(fileURLWithPath: #file).deletingLastPathComponent()
+        while !FileManager.default.fileExists(atPath: dir.appendingPathComponent("fixtures").path) {
+            let parent = dir.deletingLastPathComponent()
+            if parent.path == dir.path {
+                fatalError("fixtures dir not found walking up from \(#file)")
+            }
+            dir = parent
+        }
+        return dir.appendingPathComponent("fixtures")
+    }
+
+    // MARK: - Happy paths (driven by transport-fixtures.json)
+
+    /// `CHAT_REQUEST_TEXT` — the legacy string-content shape produces a prompt
+    /// with the user text and no media collateral.
+    func testTextOnlyMessage() async throws {
+        let fixture = try loadFixture("CHAT_REQUEST_TEXT")
+        let translator = ContentPartsTranslator(mmprojLoaded: false, modelHasAudioEncoder: false)
+        let result = try await translator.translate(messages: messages(from: fixture))
+        XCTAssertEqual(result.prompt, "hi")
+        XCTAssertTrue(result.media.isEmpty)
+        XCTAssertEqual(result.messagesWithMarkers.count, 1)
+        XCTAssertEqual(result.messagesWithMarkers[0].role, "user")
+        XCTAssertEqual(result.messagesWithMarkers[0].content, "hi")
+    }
+
+    /// `CHAT_REQUEST_IMAGE` — text + data-URL image. The image part should be
+    /// resolved via the (mocked) ImageDecoder and the bytes appended to
+    /// `media`. The rendered content for that message has a single
+    /// `<__media__>` marker substituted in place of the image part.
+    func testTextPlusImage() async throws {
+        let fixture = try loadFixture("CHAT_REQUEST_IMAGE")
+        let mock = MockImageDecoder()
+        let cannedPng = Data([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x99])
+        // Prefix-match any data: URL by snapping it after we observe it; here
+        // we just set a default in `responses` keyed off the actual URL once
+        // we know it from the fixture.
+        let urlFromFixture: String = {
+            let parts = (((fixture["messages"] as? [[String: Any]])?[0])?["content"] as? [[String: Any]]) ?? []
+            return ((parts.first(where: { ($0["type"] as? String) == "image_url" })?["image_url"] as? [String: Any])?["url"] as? String) ?? ""
+        }()
+        mock.responses[urlFromFixture] = cannedPng
+
+        let translator = ContentPartsTranslator(
+            mmprojLoaded: true,
+            modelHasAudioEncoder: false,
+            imageDecoder: mock
+        )
+        let result = try await translator.translate(messages: messages(from: fixture))
+        XCTAssertEqual(result.prompt, "What is in this image?")
+        XCTAssertEqual(result.media.count, 1)
+        XCTAssertEqual(result.media[0], cannedPng)
+        XCTAssertEqual(mock.calls, [urlFromFixture])
+        // Marker count in rendered content == media count.
+        let markerCount = result.messagesWithMarkers
+            .map { $0.content.components(separatedBy: MTMD_MEDIA_MARKER).count - 1 }
+            .reduce(0, +)
+        XCTAssertEqual(markerCount, 1)
+    }
+
+    /// `CHAT_REQUEST_AUDIO_PCM16` — base64-encoded audio + text. The base64
+    /// payload is decoded and the **raw bytes** land in `media` unchanged;
+    /// mtmd does its own format detection downstream via miniaudio, so the
+    /// translator no longer routes audio through `AudioDecoder`. The
+    /// `audioDecoder` collaborator is wired up but should not be invoked.
+    func testAudioPCM16PlusText() async throws {
+        let fixture = try loadFixture("CHAT_REQUEST_AUDIO_PCM16")
+        let recorder = AudioRecorder()
+        let translator = ContentPartsTranslator(
+            mmprojLoaded: false,
+            modelHasAudioEncoder: true,
+            audioDecoder: recorder.make()
+        )
+        let result = try await translator.translate(messages: messages(from: fixture))
+        XCTAssertEqual(result.prompt, "Transcribe this.")
+        XCTAssertEqual(result.media.count, 1)
+        // `media[0]` should be the raw base64-decoded bytes (i.e. the
+        // contents of the PCM fixture file as-is) — NOT the canned
+        // `recorder.pcmOut`, because the translator no longer routes audio
+        // through the decoder closure.
+        let pcmFile = try Data(contentsOf: fixturesURL().appendingPathComponent("audio").appendingPathComponent("pcm16-1s-16khz-mono.bin"))
+        XCTAssertEqual(result.media[0], pcmFile)
+        XCTAssertEqual(recorder.calls.count, 0, "audioDecoder must not be called on the production path; mtmd handles decode itself")
+        let markerCount = result.messagesWithMarkers
+            .map { $0.content.components(separatedBy: MTMD_MEDIA_MARKER).count - 1 }
+            .reduce(0, +)
+        XCTAssertEqual(markerCount, 1)
+    }
+
+    /// Interleaved `[text, image, text, audio, text]` → media list preserves
+    /// declaration order (image first, then audio); rendered content has
+    /// exactly two `<__media__>` markers in the right positions. After the
+    /// audio-path fix, `media[1]` is the raw base64-decoded audio bytes
+    /// (mtmd handles format detection downstream); the audio-decoder
+    /// collaborator must not be invoked.
+    func testInterleavedTextImageAudio() async throws {
+        let imageMock = MockImageDecoder()
+        let imageBytes = Data([0xAA, 0xBB, 0xCC])
+        imageMock.responses["data:image/png;base64,AAAA"] = imageBytes
+        let audioRecorder = AudioRecorder()
+        audioRecorder.pcmOut = Data([0x55, 0x66, 0x77])
+        let translator = ContentPartsTranslator(
+            mmprojLoaded: true,
+            modelHasAudioEncoder: true,
+            imageDecoder: imageMock,
+            audioDecoder: audioRecorder.make()
+        )
+        let messages: [[String: Any]] = [[
+            "role": "user",
+            "content": [
+                ["type": "text", "text": "before"],
+                ["type": "image_url", "image_url": ["url": "data:image/png;base64,AAAA"]] as [String: Any],
+                ["type": "text", "text": "between"],
+                ["type": "input_audio", "input_audio": ["data": "AAAA", "format": "pcm16"]] as [String: Any],
+                ["type": "text", "text": "after"],
+            ],
+        ]]
+        let result = try await translator.translate(messages: messages)
+        XCTAssertEqual(result.media.count, 2)
+        XCTAssertEqual(result.media[0], imageBytes, "image must come first in declaration order")
+        // `"AAAA"` base64-decoded is three zero bytes — that's what mtmd sees.
+        XCTAssertEqual(result.media[1], Data([0x00, 0x00, 0x00]), "audio bytes are the raw base64-decoded payload")
+        XCTAssertEqual(audioRecorder.calls.count, 0, "audioDecoder must not be invoked on the production path")
+        XCTAssertEqual(result.messagesWithMarkers.count, 1)
+        let content = result.messagesWithMarkers[0].content
+        let markerCount = content.components(separatedBy: MTMD_MEDIA_MARKER).count - 1
+        XCTAssertEqual(markerCount, 2)
+        // First marker should appear after "before" and before "between";
+        // second after "between" and before "after".
+        let firstMarker = content.range(of: MTMD_MEDIA_MARKER)!
+        let secondMarker = content.range(of: MTMD_MEDIA_MARKER, range: firstMarker.upperBound..<content.endIndex)!
+        let beforeRange = content.range(of: "before")!
+        let betweenRange = content.range(of: "between")!
+        let afterRange = content.range(of: "after")!
+        XCTAssertLessThan(beforeRange.upperBound, firstMarker.lowerBound)
+        XCTAssertLessThan(firstMarker.upperBound, betweenRange.lowerBound)
+        XCTAssertLessThan(betweenRange.upperBound, secondMarker.lowerBound)
+        XCTAssertLessThan(secondMarker.upperBound, afterRange.lowerBound)
+    }
+
+    // MARK: - Negative paths
+
+    /// Image part with `mmprojLoaded == false` → `noMmprojForImage`. The
+    /// translator must throw before even consulting the image decoder.
+    func testImageWithoutMmprojThrows() async {
+        let messages: [[String: Any]] = [[
+            "role": "user",
+            "content": [
+                ["type": "image_url", "image_url": ["url": "data:image/png;base64,AAAA"]]
+            ],
+        ]]
+        let mock = MockImageDecoder()
+        let translator = ContentPartsTranslator(
+            mmprojLoaded: false,
+            modelHasAudioEncoder: false,
+            imageDecoder: mock
+        )
+        do {
+            _ = try await translator.translate(messages: messages)
+            XCTFail("expected noMmprojForImage")
+        } catch TranslatorError.noMmprojForImage {
+            XCTAssertTrue(mock.calls.isEmpty, "translator should not invoke decoder when mmproj is missing")
+        } catch {
+            XCTFail("unexpected error: \(error)")
+        }
+    }
+
+    /// Audio part with `modelHasAudioEncoder == false` → `audioWithoutAudioEncoder`.
+    func testAudioWithoutEncoderThrows() async {
+        let messages: [[String: Any]] = [[
+            "role": "user",
+            "content": [
+                ["type": "input_audio", "input_audio": ["data": "AAAA", "format": "pcm16"]]
+            ],
+        ]]
+        let translator = ContentPartsTranslator(mmprojLoaded: false, modelHasAudioEncoder: false)
+        do {
+            _ = try await translator.translate(messages: messages)
+            XCTFail("expected audioWithoutAudioEncoder")
+        } catch TranslatorError.audioWithoutAudioEncoder {
+            // expected
+        } catch {
+            XCTFail("unexpected error: \(error)")
+        }
+    }
+
+    /// Unsupported audio format (e.g. `vorbis`) → `unsupportedAudioFormat`
+    /// with the offending format echoed back and the supported list filled in.
+    func testUnsupportedAudioFormatThrows() async {
+        let messages: [[String: Any]] = [[
+            "role": "user",
+            "content": [
+                ["type": "input_audio", "input_audio": ["data": "AAAA", "format": "vorbis"]]
+            ],
+        ]]
+        let translator = ContentPartsTranslator(mmprojLoaded: false, modelHasAudioEncoder: true)
+        do {
+            _ = try await translator.translate(messages: messages)
+            XCTFail("expected unsupportedAudioFormat")
+        } catch let TranslatorError.unsupportedAudioFormat(fmt, supported) {
+            XCTAssertEqual(fmt, "vorbis")
+            XCTAssertEqual(supported, ContentPartsTranslator.supportedAudioFormats)
+            XCTAssertTrue(supported.contains("flac"), "iOS supported list should include flac")
+        } catch {
+            XCTFail("unexpected error: \(error)")
+        }
+    }
+
+    /// Unknown content part type → `malformedRequest` with the offending type
+    /// echoed in the message.
+    func testUnknownContentPartTypeThrows() async {
+        let messages: [[String: Any]] = [[
+            "role": "user",
+            "content": [
+                ["type": "video_url", "video_url": ["url": "https://example.com/v.mp4"]]
+            ],
+        ]]
+        let translator = ContentPartsTranslator(mmprojLoaded: true, modelHasAudioEncoder: true)
+        do {
+            _ = try await translator.translate(messages: messages)
+            XCTFail("expected malformedRequest")
+        } catch let TranslatorError.malformedRequest(reason) {
+            XCTAssertTrue(reason.contains("video_url"), "expected reason to mention offending type, got: \(reason)")
+        } catch {
+            XCTFail("unexpected error: \(error)")
+        }
+    }
+
+    /// Empty `input_audio.data` → `malformedRequest`. The audio decoder must
+    /// not be invoked — this is a request-shape error caught before decode.
+    func testEmptyAudioDataThrowsMalformedRequest() async {
+        let translator = ContentPartsTranslator(
+            mmprojLoaded: false,
+            modelHasAudioEncoder: true,
+            imageDecoder: MockImageDecoder(),
+            audioDecoder: { _, _ in
+                XCTFail("audio decoder should not be invoked for empty data")
+                return Data()
+            }
+        )
+        let messages: [[String: Any]] = [[
+            "role": "user",
+            "content": [[
+                "type": "input_audio",
+                "input_audio": ["data": "", "format": "pcm16"]
+            ]]
+        ]]
+        do {
+            _ = try await translator.translate(messages: messages)
+            XCTFail("Expected throw")
+        } catch TranslatorError.malformedRequest {
+            // OK
+        } catch {
+            XCTFail("Unexpected: \(error)")
+        }
+    }
+
+    /// Malformed base64 in `input_audio.data` → `malformedRequest` (not
+    /// `audioDecodeFailed`). The audio decoder never runs — this is a
+    /// pre-decode request-shape error.
+    func testMalformedBase64ThrowsMalformedRequest() async {
+        let translator = ContentPartsTranslator(
+            mmprojLoaded: false,
+            modelHasAudioEncoder: true,
+            imageDecoder: MockImageDecoder(),
+            audioDecoder: { _, _ in
+                XCTFail("audio decoder should not be invoked for invalid base64")
+                return Data()
+            }
+        )
+        let messages: [[String: Any]] = [[
+            "role": "user",
+            "content": [[
+                "type": "input_audio",
+                "input_audio": ["data": "!!!not-valid-base64!!!", "format": "pcm16"]
+            ]]
+        ]]
+        do {
+            _ = try await translator.translate(messages: messages)
+            XCTFail("Expected throw")
+        } catch TranslatorError.malformedRequest {
+            // OK
+        } catch {
+            XCTFail("Unexpected: \(error)")
+        }
+    }
+}

package/ios/Tests/DVAILlamaCoreTests/ImageDecoderTest.swift

@@ -0,0 +1,139 @@
+import XCTest
+@testable import DVAILlamaCore
+
+final class ImageDecoderTest: XCTestCase {
+    /// `data:image/png;base64,...` round-trips to bytes whose first 8 bytes
+    /// are the canonical PNG magic header.
+    func testDataURLBase64() async throws {
+        let url = try String(contentsOf: imageFixtureURL("tiny-test-base64.txt"), encoding: .utf8)
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        let bytes = try await ImageDecoder.resolve(url: url)
+        XCTAssertEqual(
+            Array(bytes.prefix(8)),
+            [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A],
+            "expected PNG magic header"
+        )
+    }
+
+    /// `file://` URLs return the raw bytes off disk.
+    func testFileURL() async throws {
+        let pngURL = imageFixtureURL("tiny-test.png")
+        let result = try await ImageDecoder.resolve(url: pngURL.absoluteString)
+        let raw = try Data(contentsOf: pngURL)
+        XCTAssertEqual(result, raw)
+    }
+
+    /// Unsupported schemes throw `invalidScheme`.
+    func testInvalidScheme() async {
+        do {
+            _ = try await ImageDecoder.resolve(url: "ftp://example.com/x.png")
+            XCTFail("Expected throw")
+        } catch ImageSourceError.invalidScheme {
+            // expected
+        } catch {
+            XCTFail("Unexpected error type: \(error)")
+        }
+    }
+
+    /// `data:` URL with no comma → `malformedDataURL`.
+    func testMalformedDataURL() async {
+        do {
+            _ = try await ImageDecoder.resolve(url: "data:image/png;base64")
+            XCTFail("Expected throw")
+        } catch ImageSourceError.malformedDataURL {
+            // expected
+        } catch {
+            XCTFail("Unexpected error type: \(error)")
+        }
+    }
+
+    /// `https://` URL fetches response body bytes verbatim. Mocked at the
+    /// URLSession layer via `URLProtocol.registerClass` so no real network
+    /// is touched.
+    func testHTTPSFetchesBytes() async throws {
+        let payload = try Data(contentsOf: imageFixtureURL("tiny-test.png"))
+        URLProtocol.registerClass(MockURLProtocol.self)
+        defer {
+            URLProtocol.unregisterClass(MockURLProtocol.self)
+            MockURLProtocol.handler = nil
+        }
+        MockURLProtocol.handler = { request in
+            let response = HTTPURLResponse(
+                url: request.url!,
+                statusCode: 200,
+                httpVersion: "HTTP/1.1",
+                headerFields: nil
+            )!
+            return (response, payload)
+        }
+
+        let bytes = try await ImageDecoder.resolve(url: "https://example.invalid/img.png")
+        XCTAssertEqual(bytes, payload)
+    }
+
+    /// HTTP non-2xx → `ImageSourceError.httpError(status:)` carrying the code.
+    func testHTTPErrorThrowsHttpError() async {
+        URLProtocol.registerClass(MockURLProtocol.self)
+        defer {
+            URLProtocol.unregisterClass(MockURLProtocol.self)
+            MockURLProtocol.handler = nil
+        }
+        MockURLProtocol.handler = { request in
+            let response = HTTPURLResponse(
+                url: request.url!,
+                statusCode: 404,
+                httpVersion: "HTTP/1.1",
+                headerFields: nil
+            )!
+            return (response, Data())
+        }
+
+        do {
+            _ = try await ImageDecoder.resolve(url: "https://example.invalid/missing.png")
+            XCTFail("Expected throw")
+        } catch ImageSourceError.httpError(let status) {
+            XCTAssertEqual(status, 404)
+        } catch {
+            XCTFail("Unexpected error type: \(error)")
+        }
+    }
+
+    /// Walks up from this test source file until it finds the repo-root
+    /// `fixtures/` directory — same pattern as `AudioDecoderTest`.
+    private func imageFixtureURL(_ name: String) -> URL {
+        var dir = URL(fileURLWithPath: #file).deletingLastPathComponent()
+        while !FileManager.default.fileExists(atPath: dir.appendingPathComponent("fixtures").path) {
+            let parent = dir.deletingLastPathComponent()
+            if parent.path == dir.path {
+                fatalError("fixtures dir not found walking up from \(#file)")
+            }
+            dir = parent
+        }
+        return dir.appendingPathComponent("fixtures").appendingPathComponent("images").appendingPathComponent(name)
+    }
+}
+
+/// In-process `URLProtocol` stub that intercepts every URLSession request
+/// and dispatches it to a per-test handler. Registered globally via
+/// `URLProtocol.registerClass`, which `URLSession.shared` consults — so the
+/// production code under test (which uses `URLSession.shared`) is exercised
+/// without any actual network I/O.
+private final class MockURLProtocol: URLProtocol {
+    static var handler: ((URLRequest) -> (HTTPURLResponse, Data))?
+
+    override class func canInit(with request: URLRequest) -> Bool { true }
+    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+
+    override func startLoading() {
+        guard let handler = MockURLProtocol.handler else {
+            client?.urlProtocol(self, didFailWithError: NSError(domain: "MockURLProtocol", code: -1))
+            return
+        }
+        let (response, data) = handler(request)
+        client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
+        client?.urlProtocol(self, didLoad: data)
+        client?.urlProtocolDidFinishLoading(self)
+    }
+
+    override func stopLoading() {}
+}