From c957ac449003e08c38cdfcc519ce8fe21fadacb0 Mon Sep 17 00:00:00 2001
From: Alex-Wengg <hanweng9@gmail.com>
Date: Sun, 11 Oct 2026 18:33:56 -0400
Subject: [PATCH 1/6] feat(unlimited-ocr): Core ML runtime + one-pass PDF
 reader demo

UnlimitedOcrManager runs Baidu Unlimited-OCR (3B MoE) on Core ML: page encoder (fp16) + 8-bit
stateful decoder bundle (prefill/decode functions per prefix-capacity bucket, 128-slot ring
for generated tokens), upstream's multi-page prompt and 35-gram no-repeat ban on the host.

- UnlimitedOcrCheck: CLI parity tool; with the reference pixels it reproduces upstream's fp32
  output token for token (paper page 4, 865 tokens).
- UnlimitedOcrDemo: drop a PDF, every page is read in one generation; the page thumbnails
  highlight the layout block being written while the markdown streams in.
---
 Package.swift                                 |   2 +
 .../UnlimitedOcr/UnlimitedOcrDocument.swift   |  93 ++++
 .../UnlimitedOcr/UnlimitedOcrManager.swift    | 418 ++++++++++++++++++
 .../UnlimitedOcrPagePreprocessor.swift        |  78 ++++
 .../UnlimitedOcrTokenDecoder.swift            |  63 +++
 .../UnlimitedOcr/UnlimitedOcrTypes.swift      |  82 ++++
 .../UnlimitedOcrCheck/UnlimitedOcrCheck.swift | 111 +++++
 Sources/UnlimitedOcrDemo/ContentView.swift    | 209 +++++++++
 Sources/UnlimitedOcrDemo/ReaderModel.swift    | 126 ++++++
 .../UnlimitedOcrDemoApp.swift                 |  36 ++
 10 files changed, 1218 insertions(+)
 create mode 100644 Sources/FluidUse/UnlimitedOcr/UnlimitedOcrDocument.swift
 create mode 100644 Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
 create mode 100644 Sources/FluidUse/UnlimitedOcr/UnlimitedOcrPagePreprocessor.swift
 create mode 100644 Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTokenDecoder.swift
 create mode 100644 Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTypes.swift
 create mode 100644 Sources/UnlimitedOcrCheck/UnlimitedOcrCheck.swift
 create mode 100644 Sources/UnlimitedOcrDemo/ContentView.swift
 create mode 100644 Sources/UnlimitedOcrDemo/ReaderModel.swift
 create mode 100644 Sources/UnlimitedOcrDemo/UnlimitedOcrDemoApp.swift

diff --git a/Package.swift b/Package.swift
index 90b883c..e7d844b 100644
--- a/Package.swift
+++ b/Package.swift
@@ -67,6 +67,8 @@ let package = Package(
         .executableTarget(name: "ImageSortDemo", dependencies: ["ImageSort"], exclude: ["README.md"]),
         .executableTarget(name: "KevCheck", dependencies: ["FluidUse"]),
         .executableTarget(name: "ClefVisionCheck", dependencies: ["FluidUse"]),
+        .executableTarget(name: "UnlimitedOcrCheck", dependencies: ["FluidUse"]),
+        .executableTarget(name: "UnlimitedOcrDemo", dependencies: ["FluidUse"]),
         .executableTarget(name: "ClefFlashDemo", dependencies: ["FluidUse"], exclude: ["README.md", "demo.sh", "bars.py"]),
         .executableTarget(name: "ClefTextCheck", dependencies: ["FluidUse"]),
         .executableTarget(name: "ClefCompareDemo", dependencies: ["FluidUse"], exclude: ["README.md", "demo.sh"]),
diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrDocument.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrDocument.swift
new file mode 100644
index 0000000..6d58a8f
--- /dev/null
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrDocument.swift
@@ -0,0 +1,93 @@
+import CoreGraphics
+import Foundation
+
+/// Parsed model output: `<PAGE>` sections of `<|det|>label [x1, y1, x2, y2]<|/det|>content` blocks. Boxes are in
+/// upstream's 0...999 page coordinates (top-left origin). Parsing is tolerant of a partially streamed tail.
+public struct UnlimitedOcrDocument: Sendable {
+    public struct Block: Sendable, Identifiable {
+        public let id: Int
+        public let label: String
+        /// Normalized 0...1 rectangles (top-left origin); usually one.
+        public let boxes: [CGRect]
+        public let content: String
+    }
+
+    public struct Page: Sendable, Identifiable {
+        public let id: Int
+        public let blocks: [Block]
+    }
+
+    public let pages: [Page]
+
+    public init(parsing text: String) {
+        var pages: [Page] = []
+        var sections = text.components(separatedBy: "<PAGE>")
+        if sections.first?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == true { sections.removeFirst() }
+        var blockID = 0
+        for (pageIndex, section) in sections.enumerated() {
+            var blocks: [Block] = []
+            let parts = section.components(separatedBy: "<|det|>")
+            for part in parts.dropFirst() {
+                let pieces = part.components(separatedBy: "<|/det|>")
+                let header = pieces[0]
+                let content = pieces.count > 1 ? pieces[1...].joined(separator: "") : ""
+                let label =
+                    header.split(separator: "[", maxSplits: 1).first.map {
+                        $0.trimmingCharacters(in: .whitespaces)
+                    } ?? ""
+                blocks.append(
+                    Block(
+                        id: blockID, label: label, boxes: Self.boxes(in: header),
+                        content: content.trimmingCharacters(in: .whitespacesAndNewlines)))
+                blockID += 1
+            }
+            if blocks.isEmpty, !section.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                blocks.append(
+                    Block(
+                        id: blockID, label: "text", boxes: [],
+                        content: section.trimmingCharacters(in: .whitespacesAndNewlines)))
+                blockID += 1
+            }
+            pages.append(Page(id: pageIndex, blocks: blocks))
+        }
+        self.pages = pages
+    }
+
+    /// Every complete `[x1, y1, x2, y2]` group in a det header, normalized.
+    static func boxes(in header: String) -> [CGRect] {
+        var rects: [CGRect] = []
+        var numbers: [Double] = []
+        var current = ""
+        var inside = false
+        for character in header {
+            switch character {
+            case "[":
+                inside = true
+                numbers = []
+                current = ""
+            case "]":
+                if let value = Double(current) { numbers.append(value) }
+                if inside, numbers.count == 4 {
+                    rects.append(
+                        CGRect(
+                            x: numbers[0] / 999, y: numbers[1] / 999, width: (numbers[2] - numbers[0]) / 999,
+                            height: (numbers[3] - numbers[1]) / 999))
+                }
+                inside = false
+                current = ""
+            case ",":
+                if let value = Double(current.trimmingCharacters(in: .whitespaces)) { numbers.append(value) }
+                current = ""
+            default:
+                if inside { current.append(character) }
+            }
+        }
+        return rects
+    }
+
+    /// Plain markdown: layout markup removed, pages separated by a rule.
+    public var markdown: String {
+        pages.map { page in page.blocks.map(\.content).filter { !$0.isEmpty }.joined(separator: "\n\n") }
+            .joined(separator: "\n\n---\n\n")
+    }
+}
diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
new file mode 100644
index 0000000..efb2aca
--- /dev/null
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
@@ -0,0 +1,418 @@
+import CoreML
+import Foundation
+
+/// Baidu Unlimited-OCR (3B MoE, ~0.5B active) on Core ML: several document pages in, structured markdown out, in one
+/// generation (upstream's "Multi page parsing." mode).
+///
+/// - Page encoder (SAM-B + CLIP-L + projector, fp16, GPU): one 1024 x 1024 page -> 273 embeddings.
+/// - Decoder bundle (8-bit, GPU): per prefix-capacity bucket P a `prefill_P` (128 tokens per call) and a `decode_P`
+///   (1 token) function sharing weights. The K/V cache is Core ML state: P prefix slots + a 128-slot ring for
+///   generated tokens (upstream's R-SWA keeps the whole prefix plus the last 128 generated tokens).
+/// - Host: embeddings, RoPE, masks, ring slots and upstream's 35-gram no-repeat ban.
+///
+/// An actor: Core ML's synchronous `prediction` is not thread-safe.
+@available(macOS 15.0, iOS 18.0, *)
+public actor UnlimitedOcrManager {
+    private struct Bucket {
+        let capacity: Int
+        let prefill: MLModel
+        let decode: MLModel
+    }
+
+    let config: UnlimitedOcrConfig
+    private let directory: URL
+    private let computeUnits: MLComputeUnits
+    private let encoder: MLModel
+    private let embeddings: Data  // fp16 [vocab, hidden]
+    private let tokenDecoder: UnlimitedOcrTokenDecoder
+    private var buckets: [Int: Bucket] = [:]
+
+    /// Largest document, in pages, the bundle's biggest capacity bucket holds.
+    public nonisolated let maxPages: Int
+
+    public static func load(
+        from directory: URL, computeUnits: MLComputeUnits = .cpuAndGPU
+    ) async throws
+        -> UnlimitedOcrManager
+    {
+        let config = try JSONDecoder().decode(
+            UnlimitedOcrConfig.self, from: Data(contentsOf: directory.appendingPathComponent("config.json")))
+        let embeddings = try Data(
+            contentsOf: directory.appendingPathComponent("embeddings.f16"), options: .alwaysMapped)
+        guard embeddings.count == config.vocabSize * config.hiddenSize * 2 else {
+            throw UnlimitedOcrError.invalidAsset("embeddings.f16 size")
+        }
+        let tokenDecoder = try UnlimitedOcrTokenDecoder(
+            tokenizerJsonURL: directory.appendingPathComponent("tokenizer.json"),
+            skipping: [config.bosId, config.eosId])
+        let encoder = try await compiledModel(
+            directory: directory, package: config.encoder, functionName: nil, computeUnits: computeUnits)
+        return UnlimitedOcrManager(
+            config: config, directory: directory, computeUnits: computeUnits, encoder: encoder,
+            embeddings: embeddings, tokenDecoder: tokenDecoder)
+    }
+
+    private init(
+        config: UnlimitedOcrConfig, directory: URL, computeUnits: MLComputeUnits, encoder: MLModel, embeddings: Data,
+        tokenDecoder: UnlimitedOcrTokenDecoder
+    ) {
+        self.config = config
+        self.directory = directory
+        self.computeUnits = computeUnits
+        self.encoder = encoder
+        self.embeddings = embeddings
+        self.tokenDecoder = tokenDecoder
+        let largest = config.capacities.max() ?? 0
+        maxPages = max(0, (largest - 1 - (config.promptSuffixIds["multi"]?.count ?? 0)) / config.pageTokens)
+    }
+
+    /// Compiles a package once into `compiled/` and loads it (optionally one function of a multifunction package).
+    private static func compiledModel(
+        directory: URL, package: String, functionName: String?, computeUnits: MLComputeUnits
+    ) async throws -> MLModel {
+        let source = directory.appendingPathComponent(package)
+        let compiledDir = directory.appendingPathComponent("compiled")
+        try FileManager.default.createDirectory(at: compiledDir, withIntermediateDirectories: true)
+        let target = compiledDir.appendingPathComponent(source.deletingPathExtension().lastPathComponent + ".mlmodelc")
+        if !FileManager.default.fileExists(atPath: target.path) {
+            let temporary = try await MLModel.compileModel(at: source)
+            try FileManager.default.moveItem(at: temporary, to: target)
+        }
+        let configuration = MLModelConfiguration()
+        configuration.computeUnits = computeUnits
+        configuration.functionName = functionName
+        return try await MLModel.load(contentsOf: target, configuration: configuration)
+    }
+
+    /// Smallest capacity bucket that holds a prefix of `tokens` tokens (prefill runs in whole chunks).
+    func capacity(forPrefix tokens: Int) -> Int? {
+        let padded = (tokens + config.chunk - 1) / config.chunk * config.chunk
+        return config.capacities.sorted().first { $0 >= padded }
+    }
+
+    /// Loads the decoder functions for the buckets these page counts need (default: all) and runs one prediction
+    /// through each model, so the first real read does not pay Core ML's lazy GPU setup.
+    public func warm(pages: [Int]? = nil) async throws {
+        let counts = pages ?? Array(1...max(1, maxPages))
+        let blank = UnlimitedOcrPage(
+            pixels: [Float](
+                repeating: 0, count: 3 * UnlimitedOcrPagePreprocessor.size * UnlimitedOcrPagePreprocessor.size))
+        _ = try encode(blank)
+        var warmed = Set<Int>()
+        for count in counts {
+            guard let capacity = capacity(forPrefix: prefixLength(pages: count, prompt: "multi")),
+                warmed.insert(capacity).inserted
+            else { continue }
+            let bucket = try await bucket(capacity)
+            let slots = capacity + config.ring
+            for (model, c) in [(bucket.prefill, config.chunk), (bucket.decode, 1)] {
+                let x = try MLMultiArray(shape: [1, c as NSNumber, config.hiddenSize as NSNumber], dataType: .float16)
+                let mask = try MLMultiArray(shape: [1, 1, c as NSNumber, (slots + c) as NSNumber], dataType: .float16)
+                let writeIdx = try MLMultiArray(shape: [c as NSNumber], dataType: .int32)
+                let outIndex = try MLMultiArray(shape: [1], dataType: .int32)
+                for i in 0..<c { writeIdx.dataPointer.assumingMemoryBound(to: Int32.self)[i] = Int32(i) }
+                outIndex.dataPointer.assumingMemoryBound(to: Int32.self)[0] = 0
+                _ = try step(
+                    model, state: model.makeState(), x: x, positions: 0..<c, mask: mask, writeIdx: writeIdx,
+                    outIndex: outIndex)
+            }
+        }
+    }
+
+    private func bucket(_ capacity: Int) async throws -> Bucket {
+        if let bucket = buckets[capacity] { return bucket }
+        let prefill = try await Self.compiledModel(
+            directory: directory, package: config.decoder, functionName: "prefill_P\(capacity)",
+            computeUnits: computeUnits)
+        let decode = try await Self.compiledModel(
+            directory: directory, package: config.decoder, functionName: "decode_P\(capacity)",
+            computeUnits: computeUnits)
+        let bucket = Bucket(capacity: capacity, prefill: prefill, decode: decode)
+        buckets[capacity] = bucket
+        return bucket
+    }
+
+    func prefixLength(pages: Int, prompt: String) -> Int {
+        1 + pages * config.pageTokens + (config.promptSuffixIds[prompt]?.count ?? 0)
+    }
+
+    /// Reads `pages` (from `UnlimitedOcrPagePreprocessor`) as one document. With one page the "single" prompt
+    /// (`document parsing.`) can be used; the default multi-page prompt marks each page with `<PAGE>`.
+    public nonisolated func read(
+        pages: [UnlimitedOcrPage], prompt: String = "multi", maxNewTokens: Int? = nil
+    ) -> AsyncThrowingStream<UnlimitedOcrEvent, Error> {
+        AsyncThrowingStream { continuation in
+            let task = Task {
+                do {
+                    try await self.run(
+                        pages: pages, prompt: prompt, maxNewTokens: maxNewTokens,
+                        emit: { continuation.yield($0) })
+                    continuation.finish()
+                } catch {
+                    continuation.finish(throwing: error)
+                }
+            }
+            continuation.onTermination = { _ in task.cancel() }
+        }
+    }
+
+    // MARK: - Generation
+
+    private func run(
+        pages: [UnlimitedOcrPage], prompt: String, maxNewTokens: Int?, emit: @Sendable (UnlimitedOcrEvent) -> Void
+    ) async throws {
+        guard !pages.isEmpty else { throw UnlimitedOcrError.invalidInput("no pages") }
+        guard let suffix = config.promptSuffixIds[prompt] else {
+            throw UnlimitedOcrError.invalidInput("unknown prompt \(prompt)")
+        }
+        let hidden = config.hiddenSize
+        let n = prefixLength(pages: pages.count, prompt: prompt)
+        guard let capacity = capacity(forPrefix: n) else {
+            throw UnlimitedOcrError.invalidInput(
+                "\(pages.count) pages need \(n) prefix slots; bundle holds \(maxPages) pages")
+        }
+        let bucket = try await bucket(capacity)
+
+        // Prefix: BOS, the page embeddings, the prompt text.
+        var promptIDs = [config.bosId]
+        var prefix = [Float16](repeating: 0, count: n * hidden)
+        copyEmbedding(config.bosId, into: &prefix, row: 0)
+        let encodeStart = Date()
+        for (index, page) in pages.enumerated() {
+            let pageStart = Date()
+            let embeds = try encode(page)
+            try copyRows(embeds, rows: config.pageTokens, into: &prefix, startRow: 1 + index * config.pageTokens)
+            promptIDs += Array(repeating: config.imageTokenId, count: config.pageTokens)
+            emit(.pageEncoded(index: index, milliseconds: Date().timeIntervalSince(pageStart) * 1000))
+            try Task.checkCancellation()
+        }
+        let encodeMs = Date().timeIntervalSince(encodeStart) * 1000
+        for (i, id) in suffix.enumerated() { copyEmbedding(id, into: &prefix, row: n - suffix.count + i) }
+        promptIDs += suffix
+
+        // Prefill in chunks, then hand the cache to the decode function's state.
+        let slots = capacity + config.ring
+        let chunk = config.chunk
+        let prefillStart = Date()
+        let prefillState = bucket.prefill.makeState()
+        var top: (values: [Float], ids: [Int]) = ([], [])
+        let x = try MLMultiArray(shape: [1, chunk as NSNumber, hidden as NSNumber], dataType: .float16)
+        let mask = try MLMultiArray(shape: [1, 1, chunk as NSNumber, (slots + chunk) as NSNumber], dataType: .float16)
+        let writeIdx = try MLMultiArray(shape: [chunk as NSNumber], dataType: .int32)
+        let outIndex = try MLMultiArray(shape: [1], dataType: .int32)
+        for start in stride(from: 0, to: n, by: chunk) {
+            let rows = min(chunk, n - start)
+            let xp = x.dataPointer.assumingMemoryBound(to: Float16.self)
+            prefix.withUnsafeBufferPointer { src in
+                xp.update(from: src.baseAddress! + start * hidden, count: rows * hidden)
+            }
+            (xp + rows * hidden).update(repeating: 0, count: (chunk - rows) * hidden)
+            let mp = mask.dataPointer.assumingMemoryBound(to: Float16.self)
+            let width = slots + chunk
+            for i in 0..<chunk {
+                let row = mp + i * width
+                row.update(repeating: -1e4, count: width)
+                row.update(repeating: 0, count: start)  // earlier chunks
+                (row + slots).update(repeating: 0, count: i + 1)  // causal within the chunk
+            }
+            let wp = writeIdx.dataPointer.assumingMemoryBound(to: Int32.self)
+            for i in 0..<chunk { wp[i] = Int32(start + i) }
+            outIndex.dataPointer.assumingMemoryBound(to: Int32.self)[0] = Int32(rows - 1)
+            top = try step(
+                bucket.prefill, state: prefillState, x: x, positions: start..<(start + chunk), mask: mask,
+                writeIdx: writeIdx, outIndex: outIndex)
+            try Task.checkCancellation()
+        }
+        let decodeState = bucket.decode.makeState()
+        try copyState(from: prefillState, to: decodeState)
+        let prefillMs = Date().timeIntervalSince(prefillStart) * 1000
+        emit(.prefilled(tokens: n, capacity: capacity, milliseconds: prefillMs))
+
+        // Decode: token t goes to ring slot P + t % W; the mask shows the prefix, the previous W - 1 tokens and itself.
+        var tokens = tokenDecoder
+        let x1 = try MLMultiArray(shape: [1, 1, hidden as NSNumber], dataType: .float16)
+        let mask1 = try MLMultiArray(shape: [1, 1, 1, (slots + 1) as NSNumber], dataType: .float16)
+        let m1 = mask1.dataPointer.assumingMemoryBound(to: Float16.self)
+        m1.update(repeating: -1e4, count: slots + 1)
+        m1.update(repeating: 0, count: n)
+        m1[slots] = 0
+        let write1 = try MLMultiArray(shape: [1], dataType: .int32)
+        let out0 = try MLMultiArray(shape: [1], dataType: .int32)
+        out0.dataPointer.assumingMemoryBound(to: Int32.self)[0] = 0
+        var sequence = promptIDs
+        var limit = config.maxLength - n
+        if let maxNewTokens { limit = min(limit, maxNewTokens) }
+        var produced = 0
+        var stoppedAtEOS = false
+        let decodeStart = Date()
+        for t in 0..<limit {
+            let banned = bannedTokens(sequence)
+            guard let token = zip(top.values, top.ids).first(where: { !banned.contains($0.1) })?.1 else {
+                throw UnlimitedOcrError.prediction("every top-k candidate is banned at step \(t)")
+            }
+            sequence.append(token)
+            produced += 1
+            let text = tokens.append(token)
+            if !text.isEmpty { emit(.text(text)) }
+            if token == config.eosId {
+                stoppedAtEOS = true
+                break
+            }
+            if t == limit - 1 { break }
+            try Task.checkCancellation()
+            let slot = capacity + t % config.ring
+            if t > 0 { m1[capacity + (t - 1) % config.ring] = 0 }
+            m1[slot] = -1e4
+            write1.dataPointer.assumingMemoryBound(to: Int32.self)[0] = Int32(slot)
+            let xp = x1.dataPointer.assumingMemoryBound(to: Float16.self)
+            embeddings.withUnsafeBytes { raw in
+                let table = raw.bindMemory(to: Float16.self)
+                xp.update(from: table.baseAddress! + token * hidden, count: hidden)
+            }
+            top = try step(
+                bucket.decode, state: decodeState, x: x1, positions: (n + t)..<(n + t + 1), mask: mask1,
+                writeIdx: write1, outIndex: out0)
+        }
+        emit(
+            .finished(
+                UnlimitedOcrStats(
+                    pages: pages.count, promptTokens: n, outputTokens: produced, encodeMilliseconds: encodeMs,
+                    prefillMilliseconds: prefillMs, decodeMilliseconds: Date().timeIntervalSince(decodeStart) * 1000,
+                    stoppedAtEOS: stoppedAtEOS)))
+    }
+
+    /// Page encoder call (synchronous: the async overload would send non-Sendable Core ML values off the actor).
+    private func encode(_ page: UnlimitedOcrPage) throws -> MLMultiArray {
+        let side = UnlimitedOcrPagePreprocessor.size as NSNumber
+        let pixels = try MLMultiArray(shape: [1, 3, side, side], dataType: .float32)
+        page.pixels.withUnsafeBufferPointer {
+            pixels.dataPointer.assumingMemoryBound(to: Float.self).update(from: $0.baseAddress!, count: $0.count)
+        }
+        let output = try encoder.prediction(
+            from: MLDictionaryFeatureProvider(dictionary: ["pixels": MLFeatureValue(multiArray: pixels)]))
+        guard let embeds = output.featureValue(for: "page_embeds")?.multiArrayValue else {
+            throw UnlimitedOcrError.prediction("page encoder returned no page_embeds")
+        }
+        return embeds
+    }
+
+    /// One decoder call; returns the merged top-k over both vocab halves, best first.
+    private func step(
+        _ model: MLModel, state: MLState, x: MLMultiArray, positions: Range<Int>, mask: MLMultiArray,
+        writeIdx: MLMultiArray, outIndex: MLMultiArray
+    ) throws -> (values: [Float], ids: [Int]) {
+        let (cos, sin) = try rope(positions)
+        let inputs = try MLDictionaryFeatureProvider(dictionary: [
+            "x": MLFeatureValue(multiArray: x), "cos": MLFeatureValue(multiArray: cos),
+            "sin": MLFeatureValue(multiArray: sin), "mask": MLFeatureValue(multiArray: mask),
+            "write_idx": MLFeatureValue(multiArray: writeIdx), "out_index": MLFeatureValue(multiArray: outIndex),
+        ])
+        let output = try model.prediction(from: inputs, using: state)
+        guard let values = output.featureValue(for: "top_values")?.multiArrayValue,
+            let ids = output.featureValue(for: "top_ids")?.multiArrayValue
+        else { throw UnlimitedOcrError.prediction("decoder returned no top-k") }
+        var merged: [(Float, Int)] = []
+        let k = values.shape[1].intValue
+        for half in 0..<2 {
+            for j in 0..<k {
+                let value = values[[half as NSNumber, j as NSNumber]].floatValue
+                let id = ids[[half as NSNumber, j as NSNumber]].intValue + half * config.vocabHalf
+                merged.append((value, id))
+            }
+        }
+        merged.sort { $0.0 > $1.0 }
+        return (merged.map(\.0), merged.map(\.1))
+    }
+
+    private func rope(_ positions: Range<Int>) throws -> (MLMultiArray, MLMultiArray) {
+        let dim = config.headDim
+        let half = dim / 2
+        let count = positions.count as NSNumber
+        let cos = try MLMultiArray(shape: [count, dim as NSNumber], dataType: .float16)
+        let sin = try MLMultiArray(shape: [count, dim as NSNumber], dataType: .float16)
+        let c = cos.dataPointer.assumingMemoryBound(to: Float16.self)
+        let s = sin.dataPointer.assumingMemoryBound(to: Float16.self)
+        for (row, position) in positions.enumerated() {
+            for i in 0..<half {
+                let angle = Double(position) / pow(config.ropeTheta, Double(2 * i) / Double(dim))
+                c[row * dim + i] = Float16(Foundation.cos(angle))
+                c[row * dim + half + i] = Float16(Foundation.cos(angle))
+                s[row * dim + i] = Float16(Foundation.sin(angle))
+                s[row * dim + half + i] = Float16(Foundation.sin(angle))
+            }
+        }
+        return (cos, sin)
+    }
+
+    /// Upstream `SlidingWindowNoRepeatNgramProcessor`: ban the token that would repeat a 35-gram seen in the last
+    /// 1,024 tokens (prompt included).
+    private func bannedTokens(_ sequence: [Int]) -> Set<Int> {
+        let size = config.ngramSize
+        guard sequence.count >= size else { return [] }
+        let start = max(0, sequence.count - config.ngramWindow)
+        let end = sequence.count - size + 1
+        guard end > start else { return [] }
+        let prefixStart = sequence.count - (size - 1)
+        var banned = Set<Int>()
+        for i in start..<end where sequence[i] == sequence[prefixStart] {
+            var same = true
+            for j in 1..<(size - 1) where sequence[i + j] != sequence[prefixStart + j] {
+                same = false
+                break
+            }
+            if same { banned.insert(sequence[i + size - 1]) }
+        }
+        return banned
+    }
+
+    private func copyEmbedding(_ id: Int, into prefix: inout [Float16], row: Int) {
+        let hidden = config.hiddenSize
+        embeddings.withUnsafeBytes { raw in
+            let table = raw.bindMemory(to: Float16.self)
+            prefix.withUnsafeMutableBufferPointer { dst in
+                (dst.baseAddress! + row * hidden).update(from: table.baseAddress! + id * hidden, count: hidden)
+            }
+        }
+    }
+
+    private func copyRows(_ array: MLMultiArray, rows: Int, into prefix: inout [Float16], startRow: Int) throws {
+        let hidden = config.hiddenSize
+        guard array.shape.count == 2, array.shape[0].intValue == rows, array.shape[1].intValue == hidden else {
+            throw UnlimitedOcrError.prediction("page_embeds shape \(array.shape)")
+        }
+        let rowStride = array.strides[0].intValue
+        let colStride = array.strides[1].intValue
+        prefix.withUnsafeMutableBufferPointer { dst in
+            let base = dst.baseAddress! + startRow * hidden
+            switch array.dataType {
+            case .float32:
+                let src = array.dataPointer.assumingMemoryBound(to: Float.self)
+                for r in 0..<rows {
+                    for c in 0..<hidden { base[r * hidden + c] = Float16(src[r * rowStride + c * colStride]) }
+                }
+            case .float16:
+                let src = array.dataPointer.assumingMemoryBound(to: Float16.self)
+                for r in 0..<rows { for c in 0..<hidden { base[r * hidden + c] = src[r * rowStride + c * colStride] } }
+            default:
+                break
+            }
+        }
+    }
+
+    private func copyState(from source: MLState, to target: MLState) throws {
+        for name in ["k_cache", "v_cache"] {
+            var mismatch: String?
+            source.withMultiArray(for: name) { src in
+                target.withMultiArray(for: name) { dst in
+                    guard src.shape == dst.shape, src.strides == dst.strides, src.dataType == dst.dataType else {
+                        mismatch = "\(name): \(src.shape) vs \(dst.shape)"
+                        return
+                    }
+                    let bytes = src.count * (src.dataType == .float16 ? 2 : 4)
+                    dst.dataPointer.copyMemory(from: src.dataPointer, byteCount: bytes)
+                }
+            }
+            if let mismatch { throw UnlimitedOcrError.prediction("state copy \(mismatch)") }
+        }
+    }
+}
diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrPagePreprocessor.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrPagePreprocessor.swift
new file mode 100644
index 0000000..759ca59
--- /dev/null
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrPagePreprocessor.swift
@@ -0,0 +1,78 @@
+import CoreGraphics
+import Foundation
+import PDFKit
+
+/// One preprocessed page: planar RGB in [-1, 1], 3 x 1024 x 1024.
+public struct UnlimitedOcrPage: Sendable {
+    public let pixels: [Float]
+
+    public init(pixels: [Float]) {
+        self.pixels = pixels
+    }
+}
+
+/// Upstream's base-mode page view: aspect-fit into a 1024 x 1024 square padded with mid-gray (`ImageOps.pad`, color
+/// 127), RGB normalized to [-1, 1], planar [3, 1024, 1024]. PDF pages are rasterized straight to the target
+/// size (vector rendering instead of upstream's 300 dpi PNG + bicubic downscale).
+public enum UnlimitedOcrPagePreprocessor {
+    public static let size = 1024
+
+    public static func page(from image: CGImage) throws -> UnlimitedOcrPage {
+        let fit = fitRect(width: Double(image.width), height: Double(image.height))
+        return try render { context in
+            context.interpolationQuality = .high
+            context.draw(image, in: fit)
+        }
+    }
+
+    public static func page(from page: PDFPage) throws -> UnlimitedOcrPage {
+        let box = page.bounds(for: .mediaBox)
+        let rotation = ((page.rotation % 360) + 360) % 360
+        let quarterTurn = rotation == 90 || rotation == 270
+        let fit = fitRect(
+            width: quarterTurn ? box.height : box.width, height: quarterTurn ? box.width : box.height)
+        return try render { context in
+            context.setFillColor(CGColor(gray: 1, alpha: 1))
+            context.fill(fit)
+            context.translateBy(x: fit.midX, y: fit.midY)
+            context.rotate(by: -CGFloat(rotation) * .pi / 180)
+            let scale = quarterTurn ? fit.width / box.height : fit.width / box.width
+            context.scaleBy(x: scale, y: scale)
+            context.translateBy(x: -box.midX, y: -box.midY)
+            if let cgPage = page.pageRef { context.drawPDFPage(cgPage) }
+        }
+    }
+
+    /// Centered aspect-fit rectangle inside the square, in pixels.
+    static func fitRect(width: Double, height: Double) -> CGRect {
+        let scale = min(Double(size) / width, Double(size) / height)
+        let w = (width * scale).rounded()
+        let h = (height * scale).rounded()
+        return CGRect(
+            x: ((Double(size) - w) / 2).rounded(.down), y: ((Double(size) - h) / 2).rounded(.down), width: w, height: h)
+    }
+
+    private static func render(_ draw: (CGContext) -> Void) throws -> UnlimitedOcrPage {
+        let n = size
+        var rgba = [UInt8](repeating: 127, count: n * n * 4)
+        try rgba.withUnsafeMutableBytes { buffer in
+            guard
+                let context = CGContext(
+                    data: buffer.baseAddress, width: n, height: n, bitsPerComponent: 8, bytesPerRow: n * 4,
+                    space: CGColorSpace(name: CGColorSpace.sRGB)!,
+                    bitmapInfo: CGImageAlphaInfo.noneSkipLast.rawValue)
+            else { throw UnlimitedOcrError.invalidInput("could not create a \(n)x\(n) bitmap") }
+            context.setFillColor(CGColor(gray: 127.0 / 255.0, alpha: 1))
+            context.fill(CGRect(x: 0, y: 0, width: n, height: n))
+            draw(context)
+        }
+        let plane = n * n
+        var out = [Float](repeating: 0, count: 3 * plane)
+        for i in 0..<plane {
+            out[i] = Float(rgba[i * 4]) / 127.5 - 1
+            out[plane + i] = Float(rgba[i * 4 + 1]) / 127.5 - 1
+            out[2 * plane + i] = Float(rgba[i * 4 + 2]) / 127.5 - 1
+        }
+        return UnlimitedOcrPage(pixels: out)
+    }
+}
diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTokenDecoder.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTokenDecoder.swift
new file mode 100644
index 0000000..8a8dfc6
--- /dev/null
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTokenDecoder.swift
@@ -0,0 +1,63 @@
+import Foundation
+
+/// Streaming byte-level BPE decoder for the Unlimited-OCR `tokenizer.json`. Unlike `QwenBPETokenizer.decode`, it
+/// keeps added tokens such as `<|det|>` (the layout markup) and drops only BOS / EOS. Bytes are buffered until they
+/// form complete UTF-8, so multi-byte characters split across tokens come out whole.
+public struct UnlimitedOcrTokenDecoder: Sendable {
+    private let pieces: [Int: [UInt8]]
+    private let skipped: Set<Int>
+    private var pending: [UInt8] = []
+
+    public init(tokenizerJsonURL: URL, skipping skipped: Set<Int>) throws {
+        let data = try Data(contentsOf: tokenizerJsonURL)
+        guard let root = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+            let model = root["model"] as? [String: Any], let vocab = model["vocab"] as? [String: Int],
+            let added = root["added_tokens"] as? [[String: Any]]
+        else { throw UnlimitedOcrError.invalidAsset("tokenizer.json is not a byte-level BPE tokenizer") }
+        var byteForScalar: [UInt32: UInt8] = [:]
+        for (byte, scalar) in Self.bytesToUnicode().enumerated() { byteForScalar[scalar] = UInt8(byte) }
+        var pieces = [Int: [UInt8]](minimumCapacity: vocab.count + added.count)
+        for (token, id) in vocab {
+            pieces[id] = token.unicodeScalars.compactMap { byteForScalar[$0.value] }
+        }
+        for entry in added {
+            guard let content = entry["content"] as? String, let id = entry["id"] as? Int else { continue }
+            pieces[id] = Array(content.utf8)
+        }
+        self.pieces = pieces
+        self.skipped = skipped
+    }
+
+    /// Text completed by `id`; may be empty while a multi-byte character is still incomplete.
+    public mutating func append(_ id: Int) -> String {
+        guard !skipped.contains(id), let bytes = pieces[id] else { return "" }
+        pending += bytes
+        var end = pending.count
+        // Hold back a trailing incomplete UTF-8 sequence (at most 3 bytes).
+        for back in 1...min(3, pending.count) {
+            let byte = pending[pending.count - back]
+            if byte & 0xC0 == 0x80 { continue }  // continuation byte
+            let length = byte >= 0xF0 ? 4 : byte >= 0xE0 ? 3 : byte >= 0xC0 ? 2 : 1
+            if length > back { end = pending.count - back }
+            break
+        }
+        let text = String(decoding: pending[..<end], as: UTF8.self)
+        pending.removeFirst(end)
+        return text
+    }
+
+    /// GPT-2's reversible byte -> printable code point table.
+    private static func bytesToUnicode() -> [UInt32] {
+        var bytes = Array(33...126) + Array(161...172) + Array(174...255)
+        var codes = bytes
+        var extra = 0
+        for byte in 0..<256 where !bytes.contains(byte) {
+            bytes.append(byte)
+            codes.append(256 + extra)
+            extra += 1
+        }
+        var table = [UInt32](repeating: 0, count: 256)
+        for (byte, code) in zip(bytes, codes) { table[byte] = UInt32(code) }
+        return table
+    }
+}
diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTypes.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTypes.swift
new file mode 100644
index 0000000..818dd59
--- /dev/null
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTypes.swift
@@ -0,0 +1,82 @@
+import Foundation
+
+public enum UnlimitedOcrError: Error, LocalizedError, Sendable {
+    case invalidAsset(String)
+    case invalidInput(String)
+    case prediction(String)
+
+    public var errorDescription: String? {
+        switch self {
+        case .invalidAsset(let reason): "Invalid Unlimited-OCR asset: \(reason)"
+        case .invalidInput(let reason): "Invalid Unlimited-OCR input: \(reason)"
+        case .prediction(let reason): "Unlimited-OCR prediction failed: \(reason)"
+        }
+    }
+}
+
+/// `config.json` of the Core ML bundle (written by model-lab `unlimited-ocr-coreml/conversion/export_assets.py`).
+struct UnlimitedOcrConfig: Decodable, Sendable {
+    let hiddenSize: Int
+    let headDim: Int
+    let layers: Int
+    let vocabSize: Int
+    let vocabHalf: Int
+    let ropeTheta: Double
+    let ring: Int
+    let chunk: Int
+    let capacities: [Int]
+    let pageTokens: Int
+    let imageSize: Int
+    let bosId: Int
+    let eosId: Int
+    let imageTokenId: Int
+    let promptSuffixIds: [String: [Int]]
+    let ngramSize: Int
+    let ngramWindow: Int
+    let maxLength: Int
+    let decoder: String
+    let encoder: String
+
+    enum CodingKeys: String, CodingKey {
+        case hiddenSize = "hidden_size"
+        case headDim = "head_dim"
+        case layers
+        case vocabSize = "vocab_size"
+        case vocabHalf = "vocab_half"
+        case ropeTheta = "rope_theta"
+        case ring, chunk, capacities
+        case pageTokens = "page_tokens"
+        case imageSize = "image_size"
+        case bosId = "bos_id"
+        case eosId = "eos_id"
+        case imageTokenId = "image_token_id"
+        case promptSuffixIds = "prompt_suffix_ids"
+        case ngramSize = "ngram_size"
+        case ngramWindow = "ngram_window"
+        case maxLength = "max_length"
+        case decoder, encoder
+    }
+}
+
+/// Progress of one `UnlimitedOcrManager.read` call.
+public enum UnlimitedOcrEvent: Sendable {
+    /// Page `index` (0-based) went through the vision encoder.
+    case pageEncoded(index: Int, milliseconds: Double)
+    /// The whole document (all page tokens + prompt) is in the decoder's cache.
+    case prefilled(tokens: Int, capacity: Int, milliseconds: Double)
+    /// Newly decoded text (raw model output, including `<PAGE>` and `<|det|>` layout markup).
+    case text(String)
+    case finished(UnlimitedOcrStats)
+}
+
+public struct UnlimitedOcrStats: Sendable {
+    public let pages: Int
+    public let promptTokens: Int
+    public let outputTokens: Int
+    public let encodeMilliseconds: Double
+    public let prefillMilliseconds: Double
+    public let decodeMilliseconds: Double
+    public let stoppedAtEOS: Bool
+
+    public var millisecondsPerToken: Double { decodeMilliseconds / Double(max(1, outputTokens)) }
+}
diff --git a/Sources/UnlimitedOcrCheck/UnlimitedOcrCheck.swift b/Sources/UnlimitedOcrCheck/UnlimitedOcrCheck.swift
new file mode 100644
index 0000000..8746036
--- /dev/null
+++ b/Sources/UnlimitedOcrCheck/UnlimitedOcrCheck.swift
@@ -0,0 +1,111 @@
+import CoreGraphics
+import FluidUse
+import Foundation
+import ImageIO
+import PDFKit
+
+// Runs UnlimitedOcrManager on page images or a PDF and optionally diffs against a reference output.md.
+//   UnlimitedOcrCheck <bundle dir> <page.png ... | doc.pdf> [--ref output.md] [--max-new N] [--first-page K --pages N]
+@main
+struct UnlimitedOcrCheck {
+    static func option(_ name: String, _ args: inout [String]) -> String? {
+        guard let i = args.firstIndex(of: name), i + 1 < args.count else { return nil }
+        let value = args[i + 1]
+        args.removeSubrange(i...(i + 1))
+        return value
+    }
+
+    /// Reference pixels from tools/ref_generate.py (`pixels.npy`, float32 [N, 3, 1024, 1024]) for exact parity.
+    static func loadNpyPages(_ path: String) throws -> [UnlimitedOcrPage] {
+        let data = try Data(contentsOf: URL(fileURLWithPath: path))
+        let headerLength = Int(data[8]) | Int(data[9]) << 8
+        let body = data.dropFirst(10 + headerLength)
+        let plane = 3 * UnlimitedOcrPagePreprocessor.size * UnlimitedOcrPagePreprocessor.size
+        let floats = body.withUnsafeBytes { Array($0.bindMemory(to: Float.self)) }
+        return stride(from: 0, to: floats.count, by: plane).map {
+            UnlimitedOcrPage(pixels: Array(floats[$0..<($0 + plane)]))
+        }
+    }
+
+    static func main() async throws {
+        setvbuf(stdout, nil, _IOLBF, 0)
+        var args = Array(CommandLine.arguments.dropFirst())
+        let refPath = option("--ref", &args)
+        let outPath = option("--out", &args)
+        let npyPath = option("--npy", &args)
+        let maxNew = option("--max-new", &args).flatMap(Int.init)
+        let firstPage = option("--first-page", &args).flatMap(Int.init) ?? 1
+        let pageCount = option("--pages", &args).flatMap(Int.init)
+        guard #available(macOS 15.0, *) else {
+            print("UnlimitedOcrCheck needs macOS 15 (Core ML state)")
+            exit(1)
+        }
+        if npyPath != nil { args.append("-") }
+        guard args.count >= 2 else {
+            print("usage: UnlimitedOcrCheck <bundle dir> <page.png ... | doc.pdf> [--ref output.md] [--max-new N]")
+            exit(2)
+        }
+        let bundle = URL(fileURLWithPath: args[0])
+        let inputs = args.dropFirst().map { URL(fileURLWithPath: $0) }
+
+        var pixels: [UnlimitedOcrPage] = []
+        if let npyPath {
+            pixels = try loadNpyPages(npyPath)
+        }
+        for url in inputs where url.lastPathComponent != "-" {
+            if url.pathExtension.lowercased() == "pdf" {
+                guard let document = PDFDocument(url: url) else { fatalError("cannot open \(url.path)") }
+                let last = min(document.pageCount, firstPage - 1 + (pageCount ?? document.pageCount))
+                for index in (firstPage - 1)..<last {
+                    pixels.append(try UnlimitedOcrPagePreprocessor.page(from: document.page(at: index)!))
+                }
+            } else {
+                guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
+                    let image = CGImageSourceCreateImageAtIndex(source, 0, nil)
+                else { fatalError("cannot read \(url.path)") }
+                pixels.append(try UnlimitedOcrPagePreprocessor.page(from: image))
+            }
+        }
+
+        let loadStart = Date()
+        let manager = try await UnlimitedOcrManager.load(from: bundle)
+        try await manager.warm(pages: [pixels.count])
+        print(String(format: "loaded in %.1f s, %d page(s)", Date().timeIntervalSince(loadStart), pixels.count))
+
+        var text = ""
+        for try await event in manager.read(pages: pixels, maxNewTokens: maxNew) {
+            switch event {
+            case .pageEncoded(let index, let ms):
+                print(String(format: "page %d encoded in %.0f ms", index + 1, ms))
+            case .prefilled(let tokens, let capacity, let ms):
+                print(String(format: "prefill %d tokens (bucket %d) in %.0f ms", tokens, capacity, ms))
+            case .text(let delta):
+                text += delta
+            case .finished(let stats):
+                print(
+                    String(
+                        format: "%d tokens in %.1f s (%.1f ms/token), EOS %@", stats.outputTokens,
+                        stats.decodeMilliseconds / 1000, stats.millisecondsPerToken, stats.stoppedAtEOS ? "yes" : "no"))
+            }
+        }
+        if let outPath { try text.write(toFile: outPath, atomically: true, encoding: .utf8) }
+        print("----- output (first 600 chars) -----")
+        print(String(text.prefix(600)))
+        if let refPath {
+            let ref = try String(contentsOfFile: refPath, encoding: .utf8)
+            let got = text.trimmingCharacters(in: .whitespacesAndNewlines)
+            // tools/ref_generate.py decodes the EOS token into output.md; the manager skips it.
+            let want = ref.replacingOccurrences(of: "<｜end▁of▁sentence｜>", with: "")
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            let common = zip(got, want).prefix { $0 == $1 }.count
+            print("----- vs reference -----")
+            print(
+                "identical: \(got == want) · common prefix \(common) of \(want.count) reference chars (got \(got.count))"
+            )
+            if got != want {
+                print("ref: …\(want.dropFirst(max(0, common - 40)).prefix(120))")
+                print("got: …\(got.dropFirst(max(0, common - 40)).prefix(120))")
+            }
+        }
+    }
+}
diff --git a/Sources/UnlimitedOcrDemo/ContentView.swift b/Sources/UnlimitedOcrDemo/ContentView.swift
new file mode 100644
index 0000000..53fa957
--- /dev/null
+++ b/Sources/UnlimitedOcrDemo/ContentView.swift
@@ -0,0 +1,209 @@
+import AppKit
+import FluidUse
+import SwiftUI
+import UniformTypeIdentifiers
+
+@available(macOS 15.0, *)
+struct ContentView: View {
+    @EnvironmentObject var model: ReaderModel
+    @State private var dropTargeted = false
+
+    var body: some View {
+        VStack(spacing: 0) {
+            header
+            Divider()
+            HStack(spacing: 0) {
+                pagesColumn
+                    .frame(width: 420)
+                    .background(Color(nsColor: .underPageBackgroundColor))
+                Divider()
+                outputColumn
+            }
+        }
+        .onDrop(of: [.fileURL], isTargeted: $dropTargeted) { providers in
+            guard let provider = providers.first else { return false }
+            _ = provider.loadObject(ofClass: URL.self) { url, _ in
+                guard let url, url.pathExtension.lowercased() == "pdf" else { return }
+                Task { @MainActor in model.open(url) }
+            }
+            return true
+        }
+        .overlay {
+            if dropTargeted {
+                RoundedRectangle(cornerRadius: 12).stroke(Color.accentColor, lineWidth: 4).padding(6)
+            }
+        }
+    }
+
+    private var header: some View {
+        HStack(alignment: .center, spacing: 16) {
+            VStack(alignment: .leading, spacing: 2) {
+                Text("A whole PDF, read in one pass — on this Mac")
+                    .font(.system(size: 22, weight: .semibold))
+                Text("Baidu Unlimited-OCR · 3B MoE on Core ML · offline")
+                    .font(.system(size: 13))
+                    .foregroundStyle(.secondary)
+            }
+            Spacer()
+            statusView
+            Button("Open PDF…") { openPanel() }
+                .disabled(model.phase == .loading)
+        }
+        .padding(.horizontal, 20)
+        .padding(.vertical, 12)
+    }
+
+    private var statusView: some View {
+        HStack(spacing: 18) {
+            metric(value: "\(model.pageImages.count)", label: "pages")
+            metric(value: "\(model.outputTokens)", label: "tokens")
+            metric(value: String(format: "%.0f", model.tokensPerSecond), label: "tokens / s")
+            metric(value: String(format: "%.1f s", model.elapsed), label: phaseLabel)
+        }
+    }
+
+    private var phaseLabel: String {
+        switch model.phase {
+        case .loading: "loading model"
+        case .ready: "drop a PDF"
+        case .encoding: "looking at pages"
+        case .prefilling: "reading pages in"
+        case .reading: "writing"
+        case .done: "done"
+        case .failed: "error"
+        }
+    }
+
+    private func metric(value: String, label: String) -> some View {
+        VStack(alignment: .trailing, spacing: 0) {
+            Text(value).font(.system(size: 20, weight: .semibold, design: .rounded)).monospacedDigit()
+            Text(label).font(.system(size: 11)).foregroundStyle(.secondary)
+        }
+        .frame(minWidth: 70, alignment: .trailing)
+    }
+
+    // MARK: Pages with layout boxes
+
+    private var currentPage: Int { max(0, model.document.pages.count - 1) }
+
+    private var pagesColumn: some View {
+        ScrollViewReader { proxy in
+            ScrollView {
+                LazyVStack(spacing: 14) {
+                    ForEach(Array(model.pageImages.enumerated()), id: \.offset) { index, image in
+                        pageView(index: index, image: image).id(index)
+                    }
+                }
+                .padding(14)
+            }
+            .onChange(of: model.document.pages.count) { _, count in
+                withAnimation(.easeInOut(duration: 0.4)) { proxy.scrollTo(max(0, count - 1), anchor: .top) }
+            }
+        }
+    }
+
+    private func pageView(index: Int, image: NSImage) -> some View {
+        let blocks = index < model.document.pages.count ? model.document.pages[index].blocks : []
+        let reading = model.phase == .reading && index == currentPage
+        return Image(nsImage: image)
+            .resizable()
+            .aspectRatio(contentMode: .fit)
+            .overlay {
+                GeometryReader { geo in
+                    ForEach(Array(blocks.enumerated()), id: \.element.id) { i, block in
+                        let isCurrent = reading && i == blocks.count - 1
+                        ForEach(Array(block.boxes.enumerated()), id: \.offset) { _, box in
+                            Rectangle()
+                                .fill(isCurrent ? Color.accentColor.opacity(0.18) : Color.green.opacity(0.06))
+                                .overlay(
+                                    Rectangle().stroke(
+                                        isCurrent ? Color.accentColor : Color.green.opacity(0.5),
+                                        lineWidth: isCurrent ? 2.5 : 1)
+                                )
+                                .frame(width: box.width * geo.size.width, height: box.height * geo.size.height)
+                                .position(x: box.midX * geo.size.width, y: box.midY * geo.size.height)
+                        }
+                    }
+                }
+            }
+            .shadow(radius: 2)
+            .opacity(index <= currentPage || model.phase != .reading ? 1 : 0.55)
+    }
+
+    // MARK: Markdown output
+
+    private var outputColumn: some View {
+        ScrollViewReader { proxy in
+            ScrollView {
+                VStack(alignment: .leading, spacing: 10) {
+                    if model.pageImages.isEmpty {
+                        placeholder
+                    }
+                    ForEach(model.document.pages) { page in
+                        HStack {
+                            Text("Page \(page.id + 1)").font(.system(size: 12, weight: .semibold)).foregroundStyle(
+                                .secondary)
+                            VStack { Divider() }
+                        }
+                        .padding(.top, page.id == 0 ? 0 : 12)
+                        ForEach(page.blocks) { block in
+                            blockView(block)
+                        }
+                    }
+                    Color.clear.frame(height: 1).id("bottom")
+                }
+                .padding(24)
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .textSelection(.enabled)
+            }
+            .onChange(of: model.outputTokens) { _, _ in
+                if model.phase == .reading { proxy.scrollTo("bottom", anchor: .bottom) }
+            }
+        }
+    }
+
+    private var placeholder: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            switch model.phase {
+            case .loading:
+                ProgressView().controlSize(.small)
+                Text("Loading the model…").foregroundStyle(.secondary)
+            case .failed(let message):
+                Text(message).foregroundStyle(.red)
+            default:
+                Text("Drop a PDF here (up to \(model.maxPages) pages per read).").foregroundStyle(.secondary)
+            }
+        }
+        .font(.system(size: 15))
+        .padding(.top, 40)
+    }
+
+    @ViewBuilder
+    private func blockView(_ block: UnlimitedOcrDocument.Block) -> some View {
+        switch block.label {
+        case "title":
+            Text(block.content).font(.system(size: 20, weight: .bold))
+        case "sub_title":
+            Text(block.content).font(.system(size: 16, weight: .semibold))
+        case "table", "equation", "code", "formula":
+            Text(block.content)
+                .font(.system(size: 12, design: .monospaced))
+                .padding(8)
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .background(RoundedRectangle(cornerRadius: 6).fill(Color.secondary.opacity(0.08)))
+        case "image", "figure":
+            Label("figure", systemImage: "photo").font(.system(size: 12)).foregroundStyle(.secondary)
+        case "image_caption", "table_caption", "footnote", "page_footer", "page_header", "header", "footer":
+            Text(block.content).font(.system(size: 12)).foregroundStyle(.secondary)
+        default:
+            Text(block.content).font(.system(size: 14)).lineSpacing(2)
+        }
+    }
+
+    private func openPanel() {
+        let panel = NSOpenPanel()
+        panel.allowedContentTypes = [.pdf]
+        panel.allowsMultipleSelection = false
+        if panel.runModal() == .OK, let url = panel.url { model.open(url) }
+    }
+}
diff --git a/Sources/UnlimitedOcrDemo/ReaderModel.swift b/Sources/UnlimitedOcrDemo/ReaderModel.swift
new file mode 100644
index 0000000..d99b8ce
--- /dev/null
+++ b/Sources/UnlimitedOcrDemo/ReaderModel.swift
@@ -0,0 +1,126 @@
+import AppKit
+import FluidUse
+import Foundation
+import PDFKit
+
+/// Drives one read: PDF -> page tensors -> UnlimitedOcrManager stream -> parsed document for the UI.
+@available(macOS 15.0, *)
+@MainActor
+final class ReaderModel: ObservableObject {
+    enum Phase: Equatable {
+        case loading, ready
+        case encoding(Int)
+        case prefilling, reading, done
+        case failed(String)
+    }
+
+    @Published var phase: Phase = .loading
+    @Published var pageImages: [NSImage] = []
+    @Published var document = UnlimitedOcrDocument(parsing: "")
+    @Published var title = ""
+    @Published var outputTokens = 0
+    @Published var tokensPerSecond = 0.0
+    @Published var elapsed = 0.0
+    @Published var maxPages = 0
+
+    private var manager: UnlimitedOcrManager?
+    private var readTask: Task<Void, Never>?
+    private var text = ""
+
+    static var bundleURL: URL {
+        if let path = ProcessInfo.processInfo.environment["UNLIMITED_OCR_BUNDLE"], !path.isEmpty {
+            return URL(fileURLWithPath: path)
+        }
+        return FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(
+            "Documents/unlimited-ocr-work/bundle")
+    }
+
+    func start() async {
+        do {
+            let started = Date()
+            let manager = try await UnlimitedOcrManager.load(from: Self.bundleURL)
+            try await manager.warm()
+            self.manager = manager
+            maxPages = manager.maxPages
+            print(
+                String(
+                    format: "[unlimited-ocr] loaded in %.1f s, up to %d pages per read",
+                    Date().timeIntervalSince(started), maxPages))
+            phase = .ready
+            if let path = ProcessInfo.processInfo.environment["UNLIMITED_OCR_PDF"], !path.isEmpty {
+                open(URL(fileURLWithPath: path))
+            }
+        } catch {
+            phase = .failed(error.localizedDescription)
+        }
+    }
+
+    func open(_ url: URL) {
+        guard let manager, let pdf = PDFDocument(url: url) else {
+            phase = .failed("Could not open \(url.lastPathComponent)")
+            return
+        }
+        readTask?.cancel()
+        let count = min(pdf.pageCount, maxPages)
+        title = url.deletingPathExtension().lastPathComponent
+        pageImages = (0..<count).compactMap {
+            pdf.page(at: $0)?.thumbnail(of: NSSize(width: 900, height: 1200), for: .mediaBox)
+        }
+        text = ""
+        document = UnlimitedOcrDocument(parsing: "")
+        outputTokens = 0
+        tokensPerSecond = 0
+        elapsed = 0
+        let pdfPages = (0..<count).compactMap { pdf.page(at: $0) }
+        readTask = Task { [weak self] in
+            await self?.read(pdfPages, with: manager)
+        }
+    }
+
+    private func read(_ pdfPages: [PDFPage], with manager: UnlimitedOcrManager) async {
+        let started = Date()
+        do {
+            phase = .encoding(pdfPages.count)
+            let pages = try pdfPages.map { try UnlimitedOcrPagePreprocessor.page(from: $0) }
+            var decodeStart: Date?
+            var lastParse = Date.distantPast
+            for try await event in manager.read(pages: pages) {
+                switch event {
+                case .pageEncoded(let index, _):
+                    phase = index + 1 == pdfPages.count ? .prefilling : .encoding(pdfPages.count)
+                case .prefilled(let tokens, _, _):
+                    print(
+                        String(
+                            format: "[unlimited-ocr] %d pages encoded + prefilled (%d tokens) in %.2f s",
+                            pdfPages.count, tokens, Date().timeIntervalSince(started)))
+                    phase = .reading
+                    decodeStart = Date()
+                case .text(let delta):
+                    text += delta
+                    outputTokens += 1
+                    if Date().timeIntervalSince(lastParse) > 0.05 {
+                        document = UnlimitedOcrDocument(parsing: text)
+                        lastParse = Date()
+                    }
+                    if let decodeStart {
+                        tokensPerSecond = Double(outputTokens) / max(0.001, Date().timeIntervalSince(decodeStart))
+                    }
+                    elapsed = Date().timeIntervalSince(started)
+                case .finished(let stats):
+                    document = UnlimitedOcrDocument(parsing: text)
+                    outputTokens = stats.outputTokens
+                    tokensPerSecond = 1000 / stats.millisecondsPerToken
+                    elapsed = Date().timeIntervalSince(started)
+                    phase = .done
+                    print(
+                        String(
+                            format: "[unlimited-ocr] %d pages -> %d tokens in %.1f s (%.1f tok/s)",
+                            stats.pages, stats.outputTokens, elapsed, tokensPerSecond))
+                }
+            }
+        } catch is CancellationError {
+        } catch {
+            phase = .failed(error.localizedDescription)
+        }
+    }
+}
diff --git a/Sources/UnlimitedOcrDemo/UnlimitedOcrDemoApp.swift b/Sources/UnlimitedOcrDemo/UnlimitedOcrDemoApp.swift
new file mode 100644
index 0000000..2d1dc59
--- /dev/null
+++ b/Sources/UnlimitedOcrDemo/UnlimitedOcrDemoApp.swift
@@ -0,0 +1,36 @@
+import AppKit
+import SwiftUI
+
+@main
+struct UnlimitedOcrDemoApp: App {
+    init() {
+        setvbuf(stdout, nil, _IOLBF, 0)
+        // Bare SwiftPM executables start as background processes; make this one a regular windowed app.
+        NSApplication.shared.setActivationPolicy(.regular)
+        NSApplication.shared.activate(ignoringOtherApps: true)
+    }
+
+    var body: some Scene {
+        WindowGroup("Unlimited-OCR — on this Mac") {
+            if #available(macOS 15.0, *) {
+                RootView()
+            } else {
+                Text("Unlimited-OCR needs macOS 15 (Core ML state).").padding(40)
+            }
+        }
+        .defaultSize(width: 1320, height: 860)
+        .windowResizability(.contentMinSize)
+    }
+}
+
+@available(macOS 15.0, *)
+struct RootView: View {
+    @StateObject private var model = ReaderModel()
+
+    var body: some View {
+        ContentView()
+            .environmentObject(model)
+            .frame(minWidth: 1000, minHeight: 640)
+            .task { await model.start() }
+    }
+}

From 627585859f57abf0f4d2748cc6e8eb16e17d7f09 Mon Sep 17 00:00:00 2001
From: Alex-Wengg <hanweng9@gmail.com>
Date: Sun, 11 Oct 2026 18:47:01 -0400
Subject: [PATCH 2/6] fix(unlimited-ocr): parse the last box coordinate
 (leading space before ])

---
 Sources/FluidUse/UnlimitedOcr/UnlimitedOcrDocument.swift | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrDocument.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrDocument.swift
index 6d58a8f..e10e8ca 100644
--- a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrDocument.swift
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrDocument.swift
@@ -66,7 +66,7 @@ public struct UnlimitedOcrDocument: Sendable {
                 numbers = []
                 current = ""
             case "]":
-                if let value = Double(current) { numbers.append(value) }
+                if let value = Double(current.trimmingCharacters(in: .whitespaces)) { numbers.append(value) }
                 if inside, numbers.count == 4 {
                     rects.append(
                         CGRect(

From 8d98af7ef9cab2a2f84c32fa90b23e40edb7b3bc Mon Sep 17 00:00:00 2001
From: Alex-Wengg <hanweng9@gmail.com>
Date: Sun, 11 Oct 2026 21:01:02 -0400
Subject: [PATCH 3/6] feat(unlimited-ocr): Hub model store, Start/Pause
 controls, tests

- UnlimitedOcrModelStore: pinned, checksummed download of FluidInference/unlimited-ocr-coreml.
- Demo: opening a PDF only loads its pages; Start (Return) reads them, Pause/Resume (Space)
  holds generation between tokens. The pause flag is a lock, not actor state: the decode loop
  holds the actor without suspending, so an actor-isolated pause() only ran after the read.
- Warm-up zeroes its inputs and keeps each state alive for the call (the app intermittently
  hit an MPSGraph `shape.count = 0 != strides.count = 2` assert with uninitialized inputs).
- UnlimitedOcrCheck: `hub` bundle argument, --warm-all, --out.
- Unit tests: output/box parsing, page fit, capacity buckets, pinned assets.
---
 Package.swift                                 |  2 +-
 README.md                                     | 21 ++++
 .../UnlimitedOcr/UnlimitedOcrManager.swift    | 48 ++++++----
 .../UnlimitedOcr/UnlimitedOcrModelStore.swift | 84 ++++++++++++++++
 .../UnlimitedOcr/UnlimitedOcrTypes.swift      | 22 +++++
 .../UnlimitedOcrCheck/UnlimitedOcrCheck.swift | 18 +++-
 Sources/UnlimitedOcrDemo/ContentView.swift    | 33 +++++--
 Sources/UnlimitedOcrDemo/README.md            | 19 ++++
 Sources/UnlimitedOcrDemo/ReaderModel.swift    | 96 ++++++++++++++-----
 .../UnlimitedOcrDemoApp.swift                 |  2 +-
 Tests/FluidUseTests/UnlimitedOcrTests.swift   | 84 ++++++++++++++++
 11 files changed, 377 insertions(+), 52 deletions(-)
 create mode 100644 Sources/FluidUse/UnlimitedOcr/UnlimitedOcrModelStore.swift
 create mode 100644 Sources/UnlimitedOcrDemo/README.md
 create mode 100644 Tests/FluidUseTests/UnlimitedOcrTests.swift

diff --git a/Package.swift b/Package.swift
index e7d844b..c2f283d 100644
--- a/Package.swift
+++ b/Package.swift
@@ -68,7 +68,7 @@ let package = Package(
         .executableTarget(name: "KevCheck", dependencies: ["FluidUse"]),
         .executableTarget(name: "ClefVisionCheck", dependencies: ["FluidUse"]),
         .executableTarget(name: "UnlimitedOcrCheck", dependencies: ["FluidUse"]),
-        .executableTarget(name: "UnlimitedOcrDemo", dependencies: ["FluidUse"]),
+        .executableTarget(name: "UnlimitedOcrDemo", dependencies: ["FluidUse"], exclude: ["README.md"]),
         .executableTarget(name: "ClefFlashDemo", dependencies: ["FluidUse"], exclude: ["README.md", "demo.sh", "bars.py"]),
         .executableTarget(name: "ClefTextCheck", dependencies: ["FluidUse"]),
         .executableTarget(name: "ClefCompareDemo", dependencies: ["FluidUse"], exclude: ["README.md", "demo.sh"]),
diff --git a/README.md b/README.md
index bb34ddb..9404c21 100644
--- a/README.md
+++ b/README.md
@@ -332,6 +332,27 @@ print(draft.reply, draft.timing.totalSeconds)                           // "Cong
 `Sources/ShortReplyDemo/demo.sh --x` launches it with a macmon + log terminal
 ([Sources/ShortReplyDemo](Sources/ShortReplyDemo/README.md)).
 
+## Document OCR (multi-page)
+
+`UnlimitedOcrManager` runs Baidu's [Unlimited-OCR](https://huggingface.co/FluidInference/unlimited-ocr-coreml)
+(DeepSeek-OCR architecture, 3B MoE / ~0.5B active, MIT) on the GPU through Core ML: up to 8 document pages go in as
+one prompt and the whole document comes out of a single generation as markdown with layout boxes. Its R-SWA cache
+(full prefix + a ring of the last 128 generated tokens) is Core ML state, so speed stays flat over a long read. The
+pinned, checksummed bundle (~3.8 GB) downloads from the Hub on first use (macOS 15 / iOS 18).
+
+```swift
+let ocr = try await UnlimitedOcrManager.load(from: try await UnlimitedOcrModelStore.ensure())
+let pages = try (0..<min(pdf.pageCount, ocr.maxPages)).map { try UnlimitedOcrPagePreprocessor.page(from: pdf.page(at: $0)!) }
+var text = ""
+for try await event in ocr.read(pages: pages) { if case .text(let delta) = event { text += delta } }
+print(UnlimitedOcrDocument(parsing: text).markdown)
+```
+
+Token-for-token identical to upstream's fp32 `generate` on Baidu's paper (865 tokens for one page, 2,461 for three
+pages in one pass). On an M5 Pro: ~100 ms per page to encode, ~21 ms per output token; the first 8 pages of the paper
+(6,727 tokens) take 160 s. `UnlimitedOcrDemo` reads a dropped PDF and highlights the block being written on each
+page ([Sources/UnlimitedOcrDemo](Sources/UnlimitedOcrDemo/README.md)).
+
 ## Demo
 
 ```bash
diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
index efb2aca..40aed60 100644
--- a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
@@ -1,5 +1,6 @@
 import CoreML
 import Foundation
+import os
 
 /// Baidu Unlimited-OCR (3B MoE, ~0.5B active) on Core ML: several document pages in, structured markdown out, in one
 /// generation (upstream's "Multi page parsing." mode).
@@ -26,6 +27,9 @@ public actor UnlimitedOcrManager {
     private let embeddings: Data  // fp16 [vocab, hidden]
     private let tokenDecoder: UnlimitedOcrTokenDecoder
     private var buckets: [Int: Bucket] = [:]
+    /// Read by the generation loop every token; a lock rather than actor state because the loop holds the actor
+    /// without suspending, so an actor-isolated `pause()` would only run after the read ends.
+    private nonisolated let pauseFlag = OSAllocatedUnfairLock(initialState: false)
 
     /// Largest document, in pages, the bundle's biggest capacity bucket holds.
     public nonisolated let maxPages: Int
@@ -62,8 +66,7 @@ public actor UnlimitedOcrManager {
         self.encoder = encoder
         self.embeddings = embeddings
         self.tokenDecoder = tokenDecoder
-        let largest = config.capacities.max() ?? 0
-        maxPages = max(0, (largest - 1 - (config.promptSuffixIds["multi"]?.count ?? 0)) / config.pageTokens)
+        maxPages = config.maxPages
     }
 
     /// Compiles a package once into `compiled/` and loads it (optionally one function of a multifunction package).
@@ -84,12 +87,6 @@ public actor UnlimitedOcrManager {
         return try await MLModel.load(contentsOf: target, configuration: configuration)
     }
 
-    /// Smallest capacity bucket that holds a prefix of `tokens` tokens (prefill runs in whole chunks).
-    func capacity(forPrefix tokens: Int) -> Int? {
-        let padded = (tokens + config.chunk - 1) / config.chunk * config.chunk
-        return config.capacities.sorted().first { $0 >= padded }
-    }
-
     /// Loads the decoder functions for the buckets these page counts need (default: all) and runs one prediction
     /// through each model, so the first real read does not pay Core ML's lazy GPU setup.
     public func warm(pages: [Int]? = nil) async throws {
@@ -100,7 +97,7 @@ public actor UnlimitedOcrManager {
         _ = try encode(blank)
         var warmed = Set<Int>()
         for count in counts {
-            guard let capacity = capacity(forPrefix: prefixLength(pages: count, prompt: "multi")),
+            guard let capacity = config.capacity(forPrefix: config.prefixLength(pages: count, prompt: "multi")),
                 warmed.insert(capacity).inserted
             else { continue }
             let bucket = try await bucket(capacity)
@@ -110,11 +107,15 @@ public actor UnlimitedOcrManager {
                 let mask = try MLMultiArray(shape: [1, 1, c as NSNumber, (slots + c) as NSNumber], dataType: .float16)
                 let writeIdx = try MLMultiArray(shape: [c as NSNumber], dataType: .int32)
                 let outIndex = try MLMultiArray(shape: [1], dataType: .int32)
+                // MLMultiArray memory is not initialized.
+                x.dataPointer.initializeMemory(as: UInt8.self, repeating: 0, count: x.count * 2)
+                mask.dataPointer.initializeMemory(as: UInt8.self, repeating: 0, count: mask.count * 2)
                 for i in 0..<c { writeIdx.dataPointer.assumingMemoryBound(to: Int32.self)[i] = Int32(i) }
                 outIndex.dataPointer.assumingMemoryBound(to: Int32.self)[0] = 0
+                let state = model.makeState()
                 _ = try step(
-                    model, state: model.makeState(), x: x, positions: 0..<c, mask: mask, writeIdx: writeIdx,
-                    outIndex: outIndex)
+                    model, state: state, x: x, positions: 0..<c, mask: mask, writeIdx: writeIdx, outIndex: outIndex)
+                withExtendedLifetime(state) {}
             }
         }
     }
@@ -132,10 +133,6 @@ public actor UnlimitedOcrManager {
         return bucket
     }
 
-    func prefixLength(pages: Int, prompt: String) -> Int {
-        1 + pages * config.pageTokens + (config.promptSuffixIds[prompt]?.count ?? 0)
-    }
-
     /// Reads `pages` (from `UnlimitedOcrPagePreprocessor`) as one document. With one page the "single" prompt
     /// (`document parsing.`) can be used; the default multi-page prompt marks each page with `<PAGE>`.
     public nonisolated func read(
@@ -156,18 +153,26 @@ public actor UnlimitedOcrManager {
         }
     }
 
+    /// Holds a running read between tokens until `resume()`; the K/V state and position are kept.
+    public nonisolated func pause() { pauseFlag.withLock { $0 = true } }
+
+    public nonisolated func resume() { pauseFlag.withLock { $0 = false } }
+
+    public nonisolated var isPaused: Bool { pauseFlag.withLock { $0 } }
+
     // MARK: - Generation
 
     private func run(
         pages: [UnlimitedOcrPage], prompt: String, maxNewTokens: Int?, emit: @Sendable (UnlimitedOcrEvent) -> Void
     ) async throws {
         guard !pages.isEmpty else { throw UnlimitedOcrError.invalidInput("no pages") }
+        resume()
         guard let suffix = config.promptSuffixIds[prompt] else {
             throw UnlimitedOcrError.invalidInput("unknown prompt \(prompt)")
         }
         let hidden = config.hiddenSize
-        let n = prefixLength(pages: pages.count, prompt: prompt)
-        guard let capacity = capacity(forPrefix: n) else {
+        let n = config.prefixLength(pages: pages.count, prompt: prompt)
+        guard let capacity = config.capacity(forPrefix: n) else {
             throw UnlimitedOcrError.invalidInput(
                 "\(pages.count) pages need \(n) prefix slots; bundle holds \(maxPages) pages")
         }
@@ -244,6 +249,7 @@ public actor UnlimitedOcrManager {
         if let maxNewTokens { limit = min(limit, maxNewTokens) }
         var produced = 0
         var stoppedAtEOS = false
+        var pausedSeconds = 0.0
         let decodeStart = Date()
         for t in 0..<limit {
             let banned = bannedTokens(sequence)
@@ -260,6 +266,11 @@ public actor UnlimitedOcrManager {
             }
             if t == limit - 1 { break }
             try Task.checkCancellation()
+            if isPaused {
+                let pauseStart = Date()
+                while isPaused { try await Task.sleep(nanoseconds: 50_000_000) }
+                pausedSeconds += Date().timeIntervalSince(pauseStart)
+            }
             let slot = capacity + t % config.ring
             if t > 0 { m1[capacity + (t - 1) % config.ring] = 0 }
             m1[slot] = -1e4
@@ -277,7 +288,8 @@ public actor UnlimitedOcrManager {
             .finished(
                 UnlimitedOcrStats(
                     pages: pages.count, promptTokens: n, outputTokens: produced, encodeMilliseconds: encodeMs,
-                    prefillMilliseconds: prefillMs, decodeMilliseconds: Date().timeIntervalSince(decodeStart) * 1000,
+                    prefillMilliseconds: prefillMs,
+                    decodeMilliseconds: (Date().timeIntervalSince(decodeStart) - pausedSeconds) * 1000,
                     stoppedAtEOS: stoppedAtEOS)))
     }
 
diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrModelStore.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrModelStore.swift
new file mode 100644
index 0000000..49f7194
--- /dev/null
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrModelStore.swift
@@ -0,0 +1,84 @@
+import Foundation
+
+/// Downloads the pinned Unlimited-OCR Core ML bundle (FluidInference/unlimited-ocr-coreml): page encoder (fp16),
+/// 8-bit multi-page decoder, embedding table, tokenizer and config, as `UnlimitedOcrManager.load(from:)` expects.
+/// About 3.8 GB; files are checksummed once per pinned revision.
+public enum UnlimitedOcrModelStore {
+    public typealias Progress = @Sendable (_ file: String, _ bytes: Int64) -> Void
+
+    struct Asset {
+        let path: String
+        let sha256: String
+    }
+
+    public static let repository = "FluidInference/unlimited-ocr-coreml"
+    public static let revision = "9921f1f46054870446009ddc3ebd01f23bec0027"
+    static let assets: [Asset] = [
+        Asset(path: "config.json", sha256: "210d30d4698482e1672cbbb83846d88b5ca2b67333a3fbbbefa056663080945b"),
+        Asset(path: "embeddings.f16", sha256: "5d1df8b73bdff79c672f53ddc000451158cd16cd04ed143a1c0054b30ca03455"),
+        Asset(path: "LICENSE", sha256: "d985048c6d69429d685fdbe7557340aa0897c0fd8dc038299b148b9c75dc3383"),
+        Asset(path: "tokenizer.json", sha256: "a02f8fd5228c90256bb4f6554c34a579d48f909e5beb232dc4afad870b55a8b4"),
+        Asset(
+            path: "UnlimitedOcrDecoder.mlpackage/Data/com.apple.CoreML/model.mlmodel",
+            sha256: "bbd94029b3343cf3e5fa79d73feffd49f299fa6f445d30c51ef65df4905d37e0"),
+        Asset(
+            path: "UnlimitedOcrDecoder.mlpackage/Data/com.apple.CoreML/weights/weight.bin",
+            sha256: "9dca216cc86a99767f5837c2b17e132c96001ec21006c12eae45830fbebc468e"),
+        Asset(
+            path: "UnlimitedOcrDecoder.mlpackage/Manifest.json",
+            sha256: "d972e5852f362d203d94eb3df0d2e124a7803c39045c162f94183e76d6cfeefe"),
+        Asset(
+            path: "UnlimitedOcrPageEncoder.mlpackage/Data/com.apple.CoreML/model.mlmodel",
+            sha256: "7dcce3bed4dcf35e3dde7bd2510aa7cbc7b1bd3ca8eff93d859d11456005fc9d"),
+        Asset(
+            path: "UnlimitedOcrPageEncoder.mlpackage/Data/com.apple.CoreML/weights/weight.bin",
+            sha256: "767a77ddc86f6721dfe1e46fbb44c1e624429dfc3920682e49f68734189e40f9"),
+        Asset(
+            path: "UnlimitedOcrPageEncoder.mlpackage/Manifest.json",
+            sha256: "614ed2ad82f254936583de24a8001d440c39b00828f81343791f9eaa42913d1a"),
+    ]
+
+    /// Ensure the bundle exists in the FluidUse cache and return its directory.
+    public static func ensure(cacheDirectory: URL? = nil, progress: Progress? = nil) async throws -> URL {
+        let root = cacheDirectory ?? LayaModelStore.defaultCacheDirectory()
+        let directory = root.appendingPathComponent("unlimited-ocr-coreml", isDirectory: true)
+        let manager = FileManager.default
+        let verified = directory.appendingPathComponent(".verified-\(revision)")
+        if manager.fileExists(atPath: verified.path),
+            assets.allSatisfy({ manager.fileExists(atPath: directory.appendingPathComponent($0.path).path) })
+        {
+            return directory
+        }
+        try manager.createDirectory(at: directory, withIntermediateDirectories: true)
+        for asset in assets {
+            try Task.checkCancellation()
+            let destination = directory.appendingPathComponent(asset.path)
+            if manager.fileExists(atPath: destination.path),
+                try ClefVisionModelStore.checksum(of: destination) == asset.sha256
+            {
+                continue
+            }
+            try manager.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)
+            progress?(asset.path, 0)
+            let escaped = asset.path.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? asset.path
+            guard let url = URL(string: "https://huggingface.co/\(repository)/resolve/\(revision)/\(escaped)") else {
+                throw UnlimitedOcrError.download("bad URL for \(asset.path)")
+            }
+            let (temporary, response) = try await URLSession.shared.download(from: url)
+            defer { try? manager.removeItem(at: temporary) }
+            guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
+                throw UnlimitedOcrError.download(
+                    "HTTP \((response as? HTTPURLResponse)?.statusCode ?? -1) for \(asset.path)")
+            }
+            guard try ClefVisionModelStore.checksum(of: temporary) == asset.sha256 else {
+                throw UnlimitedOcrError.download("checksum mismatch for \(asset.path)")
+            }
+            if manager.fileExists(atPath: destination.path) { try manager.removeItem(at: destination) }
+            try manager.moveItem(at: temporary, to: destination)
+            progress?(
+                asset.path, Int64((try? manager.attributesOfItem(atPath: destination.path)[.size] as? Int64) ?? 0))
+        }
+        manager.createFile(atPath: verified.path, contents: nil)
+        return directory
+    }
+}
diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTypes.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTypes.swift
index 818dd59..7596390 100644
--- a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTypes.swift
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrTypes.swift
@@ -4,12 +4,14 @@ public enum UnlimitedOcrError: Error, LocalizedError, Sendable {
     case invalidAsset(String)
     case invalidInput(String)
     case prediction(String)
+    case download(String)
 
     public var errorDescription: String? {
         switch self {
         case .invalidAsset(let reason): "Invalid Unlimited-OCR asset: \(reason)"
         case .invalidInput(let reason): "Invalid Unlimited-OCR input: \(reason)"
         case .prediction(let reason): "Unlimited-OCR prediction failed: \(reason)"
+        case .download(let reason): "Unlimited-OCR download failed: \(reason)"
         }
     }
 }
@@ -58,6 +60,26 @@ struct UnlimitedOcrConfig: Decodable, Sendable {
     }
 }
 
+extension UnlimitedOcrConfig {
+    /// BOS + 273 tokens per page + the prompt text.
+    func prefixLength(pages: Int, prompt: String) -> Int {
+        1 + pages * pageTokens + (promptSuffixIds[prompt]?.count ?? 0)
+    }
+
+    /// Smallest capacity bucket that holds a prefix of `tokens` tokens (prefill runs in whole chunks).
+    func capacity(forPrefix tokens: Int) -> Int? {
+        let padded = (tokens + chunk - 1) / chunk * chunk
+        return capacities.sorted().first { $0 >= padded }
+    }
+
+    /// Most pages one read can take with the multi-page prompt.
+    var maxPages: Int {
+        var pages = 0
+        while capacity(forPrefix: prefixLength(pages: pages + 1, prompt: "multi")) != nil { pages += 1 }
+        return pages
+    }
+}
+
 /// Progress of one `UnlimitedOcrManager.read` call.
 public enum UnlimitedOcrEvent: Sendable {
     /// Page `index` (0-based) went through the vision encoder.
diff --git a/Sources/UnlimitedOcrCheck/UnlimitedOcrCheck.swift b/Sources/UnlimitedOcrCheck/UnlimitedOcrCheck.swift
index 8746036..8d1dd4a 100644
--- a/Sources/UnlimitedOcrCheck/UnlimitedOcrCheck.swift
+++ b/Sources/UnlimitedOcrCheck/UnlimitedOcrCheck.swift
@@ -5,7 +5,8 @@ import ImageIO
 import PDFKit
 
 // Runs UnlimitedOcrManager on page images or a PDF and optionally diffs against a reference output.md.
-//   UnlimitedOcrCheck <bundle dir> <page.png ... | doc.pdf> [--ref output.md] [--max-new N] [--first-page K --pages N]
+//   UnlimitedOcrCheck <bundle dir | hub> <page.png ... | doc.pdf> [--ref output.md] [--out text.md] [--max-new N]
+//       [--first-page K --pages N] [--npy pixels.npy] [--cache dir]
 @main
 struct UnlimitedOcrCheck {
     static func option(_ name: String, _ args: inout [String]) -> String? {
@@ -33,6 +34,9 @@ struct UnlimitedOcrCheck {
         let refPath = option("--ref", &args)
         let outPath = option("--out", &args)
         let npyPath = option("--npy", &args)
+        let cachePath = option("--cache", &args)
+        let warmAll = args.contains("--warm-all")
+        args.removeAll { $0 == "--warm-all" }
         let maxNew = option("--max-new", &args).flatMap(Int.init)
         let firstPage = option("--first-page", &args).flatMap(Int.init) ?? 1
         let pageCount = option("--pages", &args).flatMap(Int.init)
@@ -42,10 +46,16 @@ struct UnlimitedOcrCheck {
         }
         if npyPath != nil { args.append("-") }
         guard args.count >= 2 else {
-            print("usage: UnlimitedOcrCheck <bundle dir> <page.png ... | doc.pdf> [--ref output.md] [--max-new N]")
+            print(
+                "usage: UnlimitedOcrCheck <bundle dir | hub> <page.png ... | doc.pdf> [--ref output.md] [--out text.md]"
+            )
             exit(2)
         }
-        let bundle = URL(fileURLWithPath: args[0])
+        // "hub" downloads the pinned bundle (into --cache <dir> or the FluidUse cache).
+        let bundle =
+            args[0] == "hub"
+            ? try await UnlimitedOcrModelStore.ensure(cacheDirectory: cachePath.map { URL(fileURLWithPath: $0) })
+            : URL(fileURLWithPath: args[0])
         let inputs = args.dropFirst().map { URL(fileURLWithPath: $0) }
 
         var pixels: [UnlimitedOcrPage] = []
@@ -69,7 +79,7 @@ struct UnlimitedOcrCheck {
 
         let loadStart = Date()
         let manager = try await UnlimitedOcrManager.load(from: bundle)
-        try await manager.warm(pages: [pixels.count])
+        try await manager.warm(pages: warmAll ? nil : [pixels.count])
         print(String(format: "loaded in %.1f s, %d page(s)", Date().timeIntervalSince(loadStart), pixels.count))
 
         var text = ""
diff --git a/Sources/UnlimitedOcrDemo/ContentView.swift b/Sources/UnlimitedOcrDemo/ContentView.swift
index 53fa957..93d3da8 100644
--- a/Sources/UnlimitedOcrDemo/ContentView.swift
+++ b/Sources/UnlimitedOcrDemo/ContentView.swift
@@ -46,8 +46,19 @@ struct ContentView: View {
             }
             Spacer()
             statusView
-            Button("Open PDF…") { openPanel() }
-                .disabled(model.phase == .loading)
+            HStack(spacing: 8) {
+                Button("Open PDF…") { openPanel() }
+                    .disabled(model.phase == .loading || model.canPause)
+                Button(model.phase == .done ? "Restart" : "Start") { model.start() }
+                    .keyboardShortcut(.return, modifiers: [])
+                    .disabled(!model.canStart)
+                Button(model.phase == .paused ? "Resume" : "Pause") { model.togglePause() }
+                    .keyboardShortcut(.space, modifiers: [])
+                    .disabled(!model.canPause)
+                    .frame(minWidth: 76)
+            }
+            .controlSize(.large)
+            .focusable(false)
         }
         .padding(.horizontal, 20)
         .padding(.vertical, 12)
@@ -66,9 +77,11 @@ struct ContentView: View {
         switch model.phase {
         case .loading: "loading model"
         case .ready: "drop a PDF"
+        case .loaded: "press Start"
         case .encoding: "looking at pages"
         case .prefilling: "reading pages in"
         case .reading: "writing"
+        case .paused: "paused"
         case .done: "done"
         case .failed: "error"
         }
@@ -104,7 +117,7 @@ struct ContentView: View {
 
     private func pageView(index: Int, image: NSImage) -> some View {
         let blocks = index < model.document.pages.count ? model.document.pages[index].blocks : []
-        let reading = model.phase == .reading && index == currentPage
+        let reading = (model.phase == .reading || model.phase == .paused) && index == currentPage
         return Image(nsImage: image)
             .resizable()
             .aspectRatio(contentMode: .fit)
@@ -127,7 +140,7 @@ struct ContentView: View {
                 }
             }
             .shadow(radius: 2)
-            .opacity(index <= currentPage || model.phase != .reading ? 1 : 0.55)
+            .opacity(index <= currentPage || !model.canPause ? 1 : 0.55)
     }
 
     // MARK: Markdown output
@@ -136,7 +149,7 @@ struct ContentView: View {
         ScrollViewReader { proxy in
             ScrollView {
                 VStack(alignment: .leading, spacing: 10) {
-                    if model.pageImages.isEmpty {
+                    if model.document.pages.isEmpty {
                         placeholder
                     }
                     ForEach(model.document.pages) { page in
@@ -167,9 +180,17 @@ struct ContentView: View {
             switch model.phase {
             case .loading:
                 ProgressView().controlSize(.small)
-                Text("Loading the model…").foregroundStyle(.secondary)
+                Text(model.status).foregroundStyle(.secondary)
             case .failed(let message):
                 Text(message).foregroundStyle(.red)
+            case .loaded:
+                Text(
+                    "Press Start to read \(model.pageImages.count) page\(model.pageImages.count == 1 ? "" : "s") in one pass."
+                )
+                .foregroundStyle(.secondary)
+            case .encoding, .prefilling:
+                ProgressView().controlSize(.small)
+                Text("Taking in all \(model.pageImages.count) pages…").foregroundStyle(.secondary)
             default:
                 Text("Drop a PDF here (up to \(model.maxPages) pages per read).").foregroundStyle(.secondary)
             }
diff --git a/Sources/UnlimitedOcrDemo/README.md b/Sources/UnlimitedOcrDemo/README.md
new file mode 100644
index 0000000..f697fd8
--- /dev/null
+++ b/Sources/UnlimitedOcrDemo/README.md
@@ -0,0 +1,19 @@
+# UnlimitedOcrDemo
+
+Drop a PDF: its pages (up to 8) are read by Baidu Unlimited-OCR in **one generation**, on this Mac, offline. The
+page thumbnails highlight the layout block being written while the markdown streams in.
+
+```bash
+swift run -c release UnlimitedOcrDemo
+UNLIMITED_OCR_PDF=paper.pdf swift run -c release UnlimitedOcrDemo   # open a PDF at launch
+```
+
+The pinned bundle ([FluidInference/unlimited-ocr-coreml](https://huggingface.co/FluidInference/unlimited-ocr-coreml),
+~3.8 GB) downloads on first launch; `UNLIMITED_OCR_BUNDLE=<dir>` uses a local one. The first launch also compiles
+the packages (about a minute), later launches load in ~12 s.
+
+On an M5 Pro the first 8 pages of Baidu's paper (6,727 tokens) take 160 s at 43 tokens/s, with a 1.9 GB footprint
+plus 2.7 GB of memory-mapped decoder weights.
+
+`UnlimitedOcrCheck <bundle dir> <page.png … | doc.pdf> [--ref output.md]` runs the same pipeline from the command
+line; with `--npy pixels.npy` (reference pixels) it reproduces upstream's fp32 output token for token.
diff --git a/Sources/UnlimitedOcrDemo/ReaderModel.swift b/Sources/UnlimitedOcrDemo/ReaderModel.swift
index d99b8ce..a8bc5e5 100644
--- a/Sources/UnlimitedOcrDemo/ReaderModel.swift
+++ b/Sources/UnlimitedOcrDemo/ReaderModel.swift
@@ -3,14 +3,15 @@ import FluidUse
 import Foundation
 import PDFKit
 
-/// Drives one read: PDF -> page tensors -> UnlimitedOcrManager stream -> parsed document for the UI.
+/// Drives one read: PDF -> page tensors -> UnlimitedOcrManager stream -> parsed document for the UI. Opening a PDF
+/// only loads its pages; `start()` reads them, `togglePause()` holds / continues the generation.
 @available(macOS 15.0, *)
 @MainActor
 final class ReaderModel: ObservableObject {
     enum Phase: Equatable {
-        case loading, ready
+        case loading, ready, loaded
         case encoding(Int)
-        case prefilling, reading, done
+        case prefilling, reading, paused, done
         case failed(String)
     }
 
@@ -22,23 +23,37 @@ final class ReaderModel: ObservableObject {
     @Published var tokensPerSecond = 0.0
     @Published var elapsed = 0.0
     @Published var maxPages = 0
+    @Published var status = "Loading the model…"
 
     private var manager: UnlimitedOcrManager?
     private var readTask: Task<Void, Never>?
+    private var pdfPages: [PDFPage] = []
     private var text = ""
+    private var pausedAt: Date?
+    private var pausedTotal = 0.0
 
-    static var bundleURL: URL {
-        if let path = ProcessInfo.processInfo.environment["UNLIMITED_OCR_BUNDLE"], !path.isEmpty {
-            return URL(fileURLWithPath: path)
+    var canStart: Bool {
+        switch phase {
+        case .loaded, .done: return !pdfPages.isEmpty
+        case .failed: return manager != nil && !pdfPages.isEmpty
+        default: return false
         }
-        return FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(
-            "Documents/unlimited-ocr-work/bundle")
     }
 
-    func start() async {
+    var canPause: Bool { phase == .reading || phase == .paused }
+
+    func boot() async {
         do {
             let started = Date()
-            let manager = try await UnlimitedOcrManager.load(from: Self.bundleURL)
+            let directory: URL
+            if let path = ProcessInfo.processInfo.environment["UNLIMITED_OCR_BUNDLE"], !path.isEmpty {
+                directory = URL(fileURLWithPath: path)
+            } else {
+                status = "Downloading Unlimited-OCR Core ML (\(UnlimitedOcrModelStore.repository), ~3.8 GB)…"
+                directory = try await UnlimitedOcrModelStore.ensure()
+            }
+            status = "Loading the model (first launch compiles it, about a minute)…"
+            let manager = try await UnlimitedOcrManager.load(from: directory)
             try await manager.warm()
             self.manager = manager
             maxPages = manager.maxPages
@@ -55,26 +70,62 @@ final class ReaderModel: ObservableObject {
         }
     }
 
+    /// Loads the PDF's pages (up to `maxPages`) without reading them.
     func open(_ url: URL) {
-        guard let manager, let pdf = PDFDocument(url: url) else {
+        guard manager != nil, let pdf = PDFDocument(url: url) else {
             phase = .failed("Could not open \(url.lastPathComponent)")
             return
         }
-        readTask?.cancel()
+        stop()
         let count = min(pdf.pageCount, maxPages)
         title = url.deletingPathExtension().lastPathComponent
-        pageImages = (0..<count).compactMap {
-            pdf.page(at: $0)?.thumbnail(of: NSSize(width: 900, height: 1200), for: .mediaBox)
+        pdfPages = (0..<count).compactMap { pdf.page(at: $0) }
+        pageImages = pdfPages.map { $0.thumbnail(of: NSSize(width: 900, height: 1200), for: .mediaBox) }
+        reset()
+        phase = .loaded
+    }
+
+    /// Reads the loaded pages from the beginning.
+    func start() {
+        guard let manager, canStart else { return }
+        stop()
+        reset()
+        let pages = pdfPages
+        readTask = Task { [weak self] in
+            await self?.read(pages, with: manager)
+        }
+    }
+
+    func togglePause() {
+        guard let manager else { return }
+        if phase == .reading {
+            phase = .paused
+            pausedAt = Date()
+            manager.pause()
+            print("[unlimited-ocr] paused at \(outputTokens) tokens")
+        } else if phase == .paused {
+            if let pausedAt { pausedTotal += Date().timeIntervalSince(pausedAt) }
+            pausedAt = nil
+            phase = .reading
+            manager.resume()
+            print("[unlimited-ocr] resumed")
         }
+    }
+
+    private func stop() {
+        readTask?.cancel()
+        readTask = nil
+        if let manager { manager.resume() }
+    }
+
+    private func reset() {
         text = ""
         document = UnlimitedOcrDocument(parsing: "")
         outputTokens = 0
         tokensPerSecond = 0
         elapsed = 0
-        let pdfPages = (0..<count).compactMap { pdf.page(at: $0) }
-        readTask = Task { [weak self] in
-            await self?.read(pdfPages, with: manager)
-        }
+        pausedAt = nil
+        pausedTotal = 0
     }
 
     private func read(_ pdfPages: [PDFPage], with manager: UnlimitedOcrManager) async {
@@ -93,7 +144,7 @@ final class ReaderModel: ObservableObject {
                         String(
                             format: "[unlimited-ocr] %d pages encoded + prefilled (%d tokens) in %.2f s",
                             pdfPages.count, tokens, Date().timeIntervalSince(started)))
-                    phase = .reading
+                    if phase != .paused { phase = .reading }
                     decodeStart = Date()
                 case .text(let delta):
                     text += delta
@@ -103,14 +154,15 @@ final class ReaderModel: ObservableObject {
                         lastParse = Date()
                     }
                     if let decodeStart {
-                        tokensPerSecond = Double(outputTokens) / max(0.001, Date().timeIntervalSince(decodeStart))
+                        let active = Date().timeIntervalSince(decodeStart) - pausedTotal
+                        tokensPerSecond = Double(outputTokens) / max(0.001, active)
                     }
-                    elapsed = Date().timeIntervalSince(started)
+                    elapsed = Date().timeIntervalSince(started) - pausedTotal
                 case .finished(let stats):
                     document = UnlimitedOcrDocument(parsing: text)
                     outputTokens = stats.outputTokens
                     tokensPerSecond = 1000 / stats.millisecondsPerToken
-                    elapsed = Date().timeIntervalSince(started)
+                    elapsed = Date().timeIntervalSince(started) - pausedTotal
                     phase = .done
                     print(
                         String(
diff --git a/Sources/UnlimitedOcrDemo/UnlimitedOcrDemoApp.swift b/Sources/UnlimitedOcrDemo/UnlimitedOcrDemoApp.swift
index 2d1dc59..0d5cef6 100644
--- a/Sources/UnlimitedOcrDemo/UnlimitedOcrDemoApp.swift
+++ b/Sources/UnlimitedOcrDemo/UnlimitedOcrDemoApp.swift
@@ -31,6 +31,6 @@ struct RootView: View {
         ContentView()
             .environmentObject(model)
             .frame(minWidth: 1000, minHeight: 640)
-            .task { await model.start() }
+            .task { await model.boot() }
     }
 }
diff --git a/Tests/FluidUseTests/UnlimitedOcrTests.swift b/Tests/FluidUseTests/UnlimitedOcrTests.swift
new file mode 100644
index 0000000..2b7a81b
--- /dev/null
+++ b/Tests/FluidUseTests/UnlimitedOcrTests.swift
@@ -0,0 +1,84 @@
+import XCTest
+
+@testable import FluidUse
+
+/// Unlimited-OCR host pieces that need no model: output parsing, page geometry, bucket math and the pinned assets.
+final class UnlimitedOcrTests: XCTestCase {
+    /// Start of the model's own output for page 4 of Baidu's paper (fp32 reference run).
+    static let output = """
+        <PAGE><|det|>title [115, 100, 293, 116]<|/det|>2. Related Works
+        <|det|>title [114, 133, 383, 149]<|/det|>2.1. Pipeline-based Framework
+        <|det|>text [113, 159, 886, 370]<|/det|>Traditional OCR models, particularly those designed for document parsing
+        <PAGE><|det|>sub_title [100, 50, 400, 60]<|/det|>3.1. Next
+        <|det|>text [100, 70, 900
+        """
+
+    func testParsesPagesBlocksAndBoxes() {
+        let document = UnlimitedOcrDocument(parsing: Self.output)
+        XCTAssertEqual(document.pages.count, 2)
+        let first = document.pages[0].blocks
+        XCTAssertEqual(first.map(\.label), ["title", "title", "text"])
+        XCTAssertEqual(first[0].content, "2. Related Works")
+        XCTAssertEqual(first[0].boxes.count, 1)
+        let box = first[0].boxes[0]
+        XCTAssertEqual(box.minX, 115.0 / 999, accuracy: 1e-9)
+        XCTAssertEqual(box.minY, 100.0 / 999, accuracy: 1e-9)
+        XCTAssertEqual(box.maxX, 293.0 / 999, accuracy: 1e-9)
+        XCTAssertEqual(box.maxY, 116.0 / 999, accuracy: 1e-9)
+    }
+
+    func testStreamingTailHasNoBoxUntilComplete() {
+        let blocks = UnlimitedOcrDocument(parsing: Self.output).pages[1].blocks
+        XCTAssertEqual(blocks.map(\.label), ["sub_title", "text"])
+        XCTAssertTrue(blocks[1].boxes.isEmpty)
+        XCTAssertEqual(blocks[1].content, "")
+    }
+
+    func testMarkdownDropsLayoutMarkup() {
+        let markdown = UnlimitedOcrDocument(parsing: Self.output).markdown
+        XCTAssertFalse(markdown.contains("<|det|>"))
+        XCTAssertFalse(markdown.contains("<PAGE>"))
+        XCTAssertTrue(markdown.hasPrefix("2. Related Works\n\n2.1. Pipeline-based Framework"))
+        XCTAssertTrue(markdown.contains("\n\n---\n\n3.1. Next"))
+    }
+
+    func testFitRectCentersAnA4Page() {
+        let rect = UnlimitedOcrPagePreprocessor.fitRect(width: 595, height: 842)
+        XCTAssertEqual(rect.height, 1024)
+        XCTAssertEqual(rect.width, (595.0 * 1024 / 842).rounded())
+        XCTAssertEqual(rect.minX, ((1024 - rect.width) / 2).rounded(.down))
+        XCTAssertEqual(rect.minY, 0)
+    }
+
+    func testBucketsHoldOneTwoFourAndEightPages() throws {
+        let json = """
+            {"hidden_size": 1280, "head_dim": 128, "layers": 12, "vocab_size": 129280, "vocab_half": 64640,
+             "rope_theta": 10000.0, "ring": 128, "chunk": 128, "capacities": [384, 640, 1152, 2304],
+             "page_tokens": 273, "image_size": 1024, "bos_id": 0, "eos_id": 1, "image_token_id": 128815,
+             "prompt_suffix_ids": {"multi": [37460, 4366, 76466, 16], "single": [34030, 76466, 16]},
+             "ngram_size": 35, "ngram_window": 1024, "max_length": 32768,
+             "decoder": "UnlimitedOcrDecoder.mlpackage", "encoder": "UnlimitedOcrPageEncoder.mlpackage"}
+            """
+        let config = try JSONDecoder().decode(UnlimitedOcrConfig.self, from: Data(json.utf8))
+        XCTAssertEqual(config.prefixLength(pages: 1, prompt: "multi"), 278)
+        XCTAssertEqual(config.prefixLength(pages: 3, prompt: "multi"), 824)
+        let buckets = (1...8).map { config.capacity(forPrefix: config.prefixLength(pages: $0, prompt: "multi")) }
+        XCTAssertEqual(buckets, [384, 640, 1152, 1152, 2304, 2304, 2304, 2304])
+        XCTAssertNil(config.capacity(forPrefix: config.prefixLength(pages: 9, prompt: "multi")))
+        XCTAssertEqual(config.maxPages, 8)
+    }
+
+    func testModelStorePinsEveryBundleFile() {
+        let paths = UnlimitedOcrModelStore.assets.map(\.path)
+        XCTAssertEqual(Set(paths).count, paths.count)
+        for required in [
+            "config.json", "embeddings.f16", "tokenizer.json",
+            "UnlimitedOcrDecoder.mlpackage/Data/com.apple.CoreML/weights/weight.bin",
+            "UnlimitedOcrPageEncoder.mlpackage/Data/com.apple.CoreML/weights/weight.bin",
+        ] {
+            XCTAssertTrue(paths.contains(required), required)
+        }
+        XCTAssertTrue(UnlimitedOcrModelStore.assets.allSatisfy { $0.sha256.count == 64 })
+        XCTAssertEqual(UnlimitedOcrModelStore.revision.count, 40)
+    }
+}

From b0defc2cfc49518814f44e9c2f7c738277a87b50 Mon Sep 17 00:00:00 2001
From: Alex-Wengg <hanweng9@gmail.com>
Date: Sun, 11 Oct 2026 22:10:46 -0400
Subject: [PATCH 4/6] feat(unlimited-ocr): pin bundle revision 51046f08 (leaner
 decoder graph, same weights)

---
 Sources/FluidUse/UnlimitedOcr/UnlimitedOcrModelStore.swift | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrModelStore.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrModelStore.swift
index 49f7194..6a8aebc 100644
--- a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrModelStore.swift
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrModelStore.swift
@@ -12,7 +12,7 @@ public enum UnlimitedOcrModelStore {
     }
 
     public static let repository = "FluidInference/unlimited-ocr-coreml"
-    public static let revision = "9921f1f46054870446009ddc3ebd01f23bec0027"
+    public static let revision = "51046f081ace85b77c8287ad7b56d504b91eb3d2"
     static let assets: [Asset] = [
         Asset(path: "config.json", sha256: "210d30d4698482e1672cbbb83846d88b5ca2b67333a3fbbbefa056663080945b"),
         Asset(path: "embeddings.f16", sha256: "5d1df8b73bdff79c672f53ddc000451158cd16cd04ed143a1c0054b30ca03455"),
@@ -20,13 +20,13 @@ public enum UnlimitedOcrModelStore {
         Asset(path: "tokenizer.json", sha256: "a02f8fd5228c90256bb4f6554c34a579d48f909e5beb232dc4afad870b55a8b4"),
         Asset(
             path: "UnlimitedOcrDecoder.mlpackage/Data/com.apple.CoreML/model.mlmodel",
-            sha256: "bbd94029b3343cf3e5fa79d73feffd49f299fa6f445d30c51ef65df4905d37e0"),
+            sha256: "4a339171fbfd8ca84a1de4d39de77d53538feb7e4bb9759d3fb92b3d0ee20ee2"),
         Asset(
             path: "UnlimitedOcrDecoder.mlpackage/Data/com.apple.CoreML/weights/weight.bin",
             sha256: "9dca216cc86a99767f5837c2b17e132c96001ec21006c12eae45830fbebc468e"),
         Asset(
             path: "UnlimitedOcrDecoder.mlpackage/Manifest.json",
-            sha256: "d972e5852f362d203d94eb3df0d2e124a7803c39045c162f94183e76d6cfeefe"),
+            sha256: "b0086733d3888c7cb881628e6a60d227a6f1c63f09c86db7ed21eb633e5dd3de"),
         Asset(
             path: "UnlimitedOcrPageEncoder.mlpackage/Data/com.apple.CoreML/model.mlmodel",
             sha256: "7dcce3bed4dcf35e3dde7bd2510aa7cbc7b1bd3ca8eff93d859d11456005fc9d"),

From 600589ee21413c252ee2220da241eeb3f3921432 Mon Sep 17 00:00:00 2001
From: Alex-Wengg <hanweng9@gmail.com>
Date: Sun, 11 Oct 2026 22:15:16 -0400
Subject: [PATCH 5/6] fix(unlimited-ocr): demo prepares only the decoder size
 the open PDF needs (launch 177 s -> 15 s)

---
 .../UnlimitedOcr/UnlimitedOcrManager.swift    |  2 +-
 Sources/UnlimitedOcrDemo/ContentView.swift    |  4 +++
 Sources/UnlimitedOcrDemo/ReaderModel.swift    | 26 ++++++++++++++++---
 3 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
index 40aed60..0e5950a 100644
--- a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
@@ -90,7 +90,7 @@ public actor UnlimitedOcrManager {
     /// Loads the decoder functions for the buckets these page counts need (default: all) and runs one prediction
     /// through each model, so the first real read does not pay Core ML's lazy GPU setup.
     public func warm(pages: [Int]? = nil) async throws {
-        let counts = pages ?? Array(1...max(1, maxPages))
+        let counts = pages ?? Array(1...max(1, maxPages))  // [] warms the page encoder only
         let blank = UnlimitedOcrPage(
             pixels: [Float](
                 repeating: 0, count: 3 * UnlimitedOcrPagePreprocessor.size * UnlimitedOcrPagePreprocessor.size))
diff --git a/Sources/UnlimitedOcrDemo/ContentView.swift b/Sources/UnlimitedOcrDemo/ContentView.swift
index 93d3da8..2104180 100644
--- a/Sources/UnlimitedOcrDemo/ContentView.swift
+++ b/Sources/UnlimitedOcrDemo/ContentView.swift
@@ -77,6 +77,7 @@ struct ContentView: View {
         switch model.phase {
         case .loading: "loading model"
         case .ready: "drop a PDF"
+        case .preparing: "preparing"
         case .loaded: "press Start"
         case .encoding: "looking at pages"
         case .prefilling: "reading pages in"
@@ -183,6 +184,9 @@ struct ContentView: View {
                 Text(model.status).foregroundStyle(.secondary)
             case .failed(let message):
                 Text(message).foregroundStyle(.red)
+            case .preparing:
+                ProgressView().controlSize(.small)
+                Text(model.status).foregroundStyle(.secondary)
             case .loaded:
                 Text(
                     "Press Start to read \(model.pageImages.count) page\(model.pageImages.count == 1 ? "" : "s") in one pass."
diff --git a/Sources/UnlimitedOcrDemo/ReaderModel.swift b/Sources/UnlimitedOcrDemo/ReaderModel.swift
index a8bc5e5..1b5bc69 100644
--- a/Sources/UnlimitedOcrDemo/ReaderModel.swift
+++ b/Sources/UnlimitedOcrDemo/ReaderModel.swift
@@ -9,7 +9,7 @@ import PDFKit
 @MainActor
 final class ReaderModel: ObservableObject {
     enum Phase: Equatable {
-        case loading, ready, loaded
+        case loading, ready, preparing, loaded
         case encoding(Int)
         case prefilling, reading, paused, done
         case failed(String)
@@ -27,6 +27,7 @@ final class ReaderModel: ObservableObject {
 
     private var manager: UnlimitedOcrManager?
     private var readTask: Task<Void, Never>?
+    private var prepareTask: Task<Void, Never>?
     private var pdfPages: [PDFPage] = []
     private var text = ""
     private var pausedAt: Date?
@@ -53,8 +54,10 @@ final class ReaderModel: ObservableObject {
                 directory = try await UnlimitedOcrModelStore.ensure()
             }
             status = "Loading the model (first launch compiles it, about a minute)…"
+            // Only the page encoder here; the decoder size for a document is prepared when it is opened
+            // (compiling every size up front took minutes).
             let manager = try await UnlimitedOcrManager.load(from: directory)
-            try await manager.warm()
+            try await manager.warm(pages: [])
             self.manager = manager
             maxPages = manager.maxPages
             print(
@@ -82,7 +85,23 @@ final class ReaderModel: ObservableObject {
         pdfPages = (0..<count).compactMap { pdf.page(at: $0) }
         pageImages = pdfPages.map { $0.thumbnail(of: NSSize(width: 900, height: 1200), for: .mediaBox) }
         reset()
-        phase = .loaded
+        guard let manager else { return }
+        phase = .preparing
+        status = "Preparing the model for \(count) page\(count == 1 ? "" : "s")…"
+        let started = Date()
+        prepareTask = Task { [weak self] in
+            do {
+                try await manager.warm(pages: [count])
+                guard let self, !Task.isCancelled else { return }
+                print(
+                    String(
+                        format: "[unlimited-ocr] ready for %d pages in %.1f s", count, Date().timeIntervalSince(started)
+                    ))
+                self.phase = .loaded
+            } catch {
+                self?.phase = .failed(error.localizedDescription)
+            }
+        }
     }
 
     /// Reads the loaded pages from the beginning.
@@ -113,6 +132,7 @@ final class ReaderModel: ObservableObject {
     }
 
     private func stop() {
+        prepareTask?.cancel()
         readTask?.cancel()
         readTask = nil
         if let manager { manager.resume() }

From 93f0584e8e88ac7cd149a0be86d4f267d6f8ac95 Mon Sep 17 00:00:00 2001
From: Alex-Wengg <hanweng9@gmail.com>
Date: Mon, 12 Oct 2026 17:25:13 -0400
Subject: [PATCH 6/6] fix(unlimited-ocr): @preconcurrency import CoreML for the
 CI Swift toolchain

CI's compiler rejects sending the non-Sendable MLModel returned by the
nonisolated compiledModel(...) into the actor (UnlimitedOcrManager.swift:125, 128).
Same import as the other managers (Laya, GLiClass, Kev, Verdict, GLiNER2).
---
 Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
index 0e5950a..23c62d3 100644
--- a/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
+++ b/Sources/FluidUse/UnlimitedOcr/UnlimitedOcrManager.swift
@@ -1,4 +1,4 @@
-import CoreML
+@preconcurrency import CoreML
 import Foundation
 import os