Skip to content

Gemma 4 26B-A4B inference in ~2 GB of RAM on any M-series MacBook

50.4 KB
Raw Blame
import AppKit
import Foundation

@MainActor
public final class InstructionTranscriptDocumentController {
    public enum Mutation: Equatable {
        case none
        case rebuilt
        case appended
        /// The open block was re-rendered in place. The completed blocks above
        /// it did not move, so the reader keeps their position.
        case tailReplaced
        case finalized
    }

    /// The stretch of the document this update rewrote, in the coordinates the
    /// document had *before* it. Everything below `previous.location` is the
    /// same text it was, which is what lets a selection there keep its exact
    /// indices instead of being clamped onto different characters.
    public struct ReplacedRange: Equatable {
        public let previous: NSRange
        public let length: Int

        public init(previous: NSRange, length: Int) {
            self.previous = previous
            self.length = length
        }

        /// The part of `previous` that actually changed.
        ///
        /// A tail re-render rewrites the same sentence with a few characters
        /// added, and reporting the whole tail as replaced collapsed every
        /// selection inside it — including one over text that had not moved.
        /// Trimming the common prefix and suffix leaves only what differs;
        /// nil when the two are the same text.
        public static func differing(
            previous: NSRange,
            old: NSString,
            new: NSString
        ) -> ReplacedRange? {
            let shorter = min(old.length, new.length)
            var prefix = 0
            while prefix < shorter, old.character(at: prefix) == new.character(at: prefix) {
                prefix += 1
            }
            guard prefix < old.length || prefix < new.length else { return nil }
            var suffix = 0
            while suffix < shorter - prefix,
                  old.character(at: old.length - 1 - suffix)
                    == new.character(at: new.length - 1 - suffix) {
                suffix += 1
            }

            // Neither boundary may land inside a composed character sequence,
            // or the replacement writes half a character.
            var start = prefix
            if start > 0, start < old.length {
                start = min(start, old.rangeOfComposedCharacterSequence(at: start).location)
            }
            if start > 0, start < new.length {
                start = min(start, new.rangeOfComposedCharacterSequence(at: start).location)
            }
            var oldEnd = max(start, old.length - suffix)
            var newEnd = max(start, new.length - suffix)
            if oldEnd > start, oldEnd < old.length {
                let sequence = old.rangeOfComposedCharacterSequence(at: oldEnd)
                if sequence.location < oldEnd { oldEnd = sequence.upperBound }
            }
            if newEnd > start, newEnd < new.length {
                let sequence = new.rangeOfComposedCharacterSequence(at: newEnd)
                if sequence.location < newEnd { newEnd = sequence.upperBound }
            }
            // The two ends move together or the suffixes they leave behind
            // stop matching.
            let kept = min(old.length - oldEnd, new.length - newEnd)
            return ReplacedRange(
                previous: NSRange(
                    location: previous.location + start,
                    length: old.length - kept - start),
                length: new.length - kept - start)
        }
    }

    public struct UpdateResult {
        public let mutation: Mutation
        public let assistantRange: NSRange
        public let replaced: ReplacedRange?

        public init(
            mutation: Mutation,
            assistantRange: NSRange,
            replaced: ReplacedRange? = nil
        ) {
            self.mutation = mutation
            self.assistantRange = assistantRange
            self.replaced = replaced
        }
    }

    public private(set) var prompt = ""
    public private(set) var promptPrefixIdentifier = ""
    public private(set) var response = ""
    public private(set) var isFinalized = false
    public private(set) var showsPrefillPlaceholder = false
    public private(set) var assistantRange = NSRange(location: 0, length: 0)
    /// Length of the completed turns above the live one. Everything below this
    /// offset is drawn once and never looked at again — which is the whole
    /// point: a chat that re-rendered its history on every token would make
    /// TextKit lay out the entire conversation per tick.
    public private(set) var frozenLength = 0
    /// Where each finished turn sits in the document, and the answer it holds.
    ///
    /// One floating copy button over a transcript of several turns reads as
    /// belonging to the first one. Knowing which turn a click landed in is what
    /// lets the menu offer that turn's answer instead of guessing.
    private var sealedTurns: [(range: NSRange, answer: String)] = []
    private var prefillPlaceholderRange: NSRange?
    private var prefillDotCount = 0

    private var renderer: any TranscriptBlockRendering
    public private(set) var typography: ConversationTypography
    private let environment: [String: String]
    private let progressiveRendering: Bool
    private var progressive = ProgressiveState()

    public init(
        renderer: (any TranscriptBlockRendering)? = nil,
        typography: ConversationTypography = .init(),
        environment: [String: String] = ProcessInfo.processInfo.environment
    ) {
        self.typography = typography
        self.environment = environment
        self.renderer = renderer ?? ResponseMarkdownRenderer(
            typography: typography, environment: environment)
        progressiveRendering = environment["TURBO_FIELDFARE_PROGRESSIVE_RENDER"] != "0"
    }

    /// The part of the assistant range that is still being written. Only this
    /// range is rewritten while an answer streams; in the raw streaming mode
    /// the whole answer is unrendered and the two ranges are the same.
    public var tailRange: NSRange {
        NSRange(
            location: assistantRange.location + progressive.prefixLength,
            length: max(0, assistantRange.length - progressive.prefixLength))
    }

    public static func clampedRanges(
        _ ranges: [NSRange],
        toLength length: Int
    ) -> [NSRange] {
        ranges.map { range in
            let location = min(max(range.location, 0), length)
            let available = max(0, length - location)
            return NSRange(location: location, length: min(max(range.length, 0), available))
        }
    }

    /// Where a selection lands after part of the document was rewritten.
    ///
    /// Clamping the old ranges onto the new length kept their lengths and so
    /// kept selecting *something* — whatever now sits at those indices. When
    /// the open tail is redrawn on a streaming tick that is different text,
    /// so a selection that reached into the tail loses the part that no longer
    /// exists and keeps the part above it, which has not moved.
    public static func adjustedRanges(
        _ ranges: [NSRange],
        replacing replaced: NSRange,
        newLength: Int
    ) -> [NSRange] {
        let end = replaced.location + newLength
        let delta = newLength - replaced.length
        return ranges.map { range in
            guard range.upperBound > replaced.location else { return range }
            // Below the rewrite the characters are the same ones, just moved.
            // Collapsing them too dropped a selection over a heading the
            // finalize pass never touched.
            guard range.location < replaced.upperBound else {
                return NSRange(location: range.location + delta, length: range.length)
            }
            guard range.location < replaced.location else {
                return NSRange(location: min(range.location, end), length: 0)
            }
            return NSRange(
                location: range.location,
                length: replaced.location - range.location)
        }
    }

    public static func shouldScrollToBottom(
        wasAtBottom: Bool,
        mutation: Mutation
    ) -> Bool {
        wasAtBottom
    }

    public static func shouldRunPrefillAnimation(
        response: String,
        isTerminal: Bool,
        requested: Bool
    ) -> Bool {
        requested && response.isEmpty && !isTerminal
    }

    /// Whether `response` starts with the exact bytes of `previous`.
    /// `hasPrefix` compares by canonical equivalence, so a decomposed prefix
    /// that arrives recomposed passes it while the UTF-8 offsets the delta is
    /// cut at no longer line up, and the append writes the wrong characters
    /// onto a document drawn from different ones.
    private static func extendsExactly(_ response: String, _ previous: String) -> Bool {
        let count = previous.utf8.count
        guard count > 0 else { return true }
        guard response.utf8.count >= count else { return false }
        // Through contiguous storage, not an element-wise walk of two UTF8
        // views: this runs on every streaming tick, and iterating one costs a
        // measurable fraction of the tick by the end of a long answer.
        return Self.withUTF8(response) { response in
            Self.withUTF8(previous) { previous in
                guard let left = response.baseAddress, let right = previous.baseAddress else {
                    return response.prefix(count).elementsEqual(previous)
                }
                return memcmp(left, right, count) == 0
            }
        }
    }

    private static func withUTF8<R>(
        _ text: String,
        _ body: (UnsafeBufferPointer<UInt8>) -> R
    ) -> R {
        if let result = text.utf8.withContiguousStorageIfAvailable(body) { return result }
        var copy = text
        return copy.withUTF8 { body($0) }
    }

    /// The text `response` adds on top of `previous`, or nil when the two do
    /// not share a Character-aligned UTF-8 prefix and the document must be
    /// rebuilt instead. Grapheme-based `count`/`dropFirst` walk the whole
    /// response on every streaming tick, which is quadratic across a
    /// generation; UTF-8 offsets are constant time on native strings.
    private static func appendedSuffix(of response: String, after previous: String) -> String? {
        let previousBytes = previous.utf8.count
        guard response.utf8.count > previousBytes else { return nil }
        let boundary = response.utf8.index(
            response.utf8.startIndex,
            offsetBy: previousBytes)
        guard let start = boundary.samePosition(in: response) else { return nil }
        return String(response[start...])
    }

    @discardableResult
    public func synchronize(
        storage: NSMutableAttributedString,
        prompt: String,
        response: String,
        isTerminal: Bool,
        showsPrefillPlaceholder: Bool = false,
        promptPrefix: NSAttributedString = NSAttributedString(),
        promptPrefixIdentifier: String = ""
    ) -> UpdateResult {
        let responseChanged = response != self.response
        let displaysPrefillPlaceholder = Self.shouldRunPrefillAnimation(
            response: response,
            isTerminal: isTerminal,
            requested: showsPrefillPlaceholder)
        var needsRebuild = prompt != self.prompt
            || promptPrefixIdentifier != self.promptPrefixIdentifier
            || !Self.extendsExactly(response, self.response)
            || (isFinalized && !isTerminal)
            || displaysPrefillPlaceholder != self.showsPrefillPlaceholder
        var appendedDelta: String?
        if !needsRebuild, response.utf8.count > self.response.utf8.count {
            // The progressive scanner consumes UTF-8 offsets itself. Requiring
            // a Character boundary here rebuilt a fence when CR and LF arrived
            // separately, losing its identity despite an exact byte append.
            appendedDelta = progressiveRendering ? "" : Self.appendedSuffix(of: response, after: self.response)
            needsRebuild = appendedDelta == nil
        }

        var mutation: Mutation = .none
        var replaced: ReplacedRange?
        // In progressive mode a terminal response is closed block by block, so
        // the tick that carries it is an ordinary extension. The raw mode is
        // replaced wholesale below and has nothing to gain from writing the
        // delta first.
        // `frozenLength`, not zero: with completed turns above it the live turn
        // is empty at `storage.length == frozenLength`, and comparing against
        // zero meant the first tick of turn two never drew its prompt.
        if needsRebuild
            || storage.length == frozenLength
                && (!prompt.isEmpty || promptPrefix.length > 0
                    || !response.isEmpty || displaysPrefillPlaceholder) {
            rebuild(
                storage: storage,
                prompt: prompt,
                promptPrefix: promptPrefix,
                response: response,
                showsPrefillPlaceholder: displaysPrefillPlaceholder,
                closingTail: isTerminal)
            mutation = .rebuilt
        } else if let delta = appendedDelta {
            if progressiveRendering {
                let update = extendProgressiveRender(
                    storage: storage,
                    response: response,
                    closingTail: isTerminal)
                mutation = update.mutation
                replaced = update.replaced
            } else if !isTerminal {
                mutation = appendRaw(delta, to: storage)
            }
        }

        self.prompt = prompt
        self.promptPrefixIdentifier = promptPrefixIdentifier
        self.response = response
        self.showsPrefillPlaceholder = displaysPrefillPlaceholder

        if isTerminal && (!isFinalized || responseChanged) {
            if progressiveRendering {
                // Finalize closes the open block and leaves everything above it
                // exactly as it was drawn. Re-rendering the whole answer put it
                // back through message-wide gates the streaming pass applies
                // per block — an unclosed fence anywhere, a table in a list, a
                // block-level HTML tag — so an answer that streamed styled
                // flipped to raw source the moment it finished.
                if let update = closeTail(storage: storage, response: response) {
                    replaced = update
                }
            } else {
                let rendered = renderer.render(response, typesetsMath: true).attributedString
                replaced = ReplacedRange(previous: assistantRange, length: rendered.length)
                storage.replaceCharacters(in: assistantRange, with: rendered)
                assistantRange.length = rendered.length
                progressive.reset()
            }
            isFinalized = true
            mutation = .finalized
        } else if !isTerminal {
            isFinalized = false
        }

        return UpdateResult(
            mutation: mutation,
            assistantRange: assistantRange,
            replaced: replaced)
    }

    @discardableResult
    public func advancePrefillAnimation(
        storage: NSMutableAttributedString
    ) -> Bool {
        guard showsPrefillPlaceholder, var range = prefillPlaceholderRange else {
            return false
        }
        prefillDotCount = (prefillDotCount + 1) % 4
        let replacement = NSAttributedString(
            string: Self.prefillPlaceholder(dotCount: prefillDotCount),
            attributes: prefillPlaceholderAttributes())
        storage.replaceCharacters(in: range, with: replacement)
        range.length = replacement.length
        prefillPlaceholderRange = range
        return true
    }

    private func appendRaw(
        _ delta: String,
        to storage: NSMutableAttributedString
    ) -> Mutation {
        storage.append(NSAttributedString(
            string: delta,
            attributes: responseAttributes()))
        assistantRange.length += (delta as NSString).length
        return .appended
    }

    private func rebuild(
        storage: NSMutableAttributedString,
        prompt: String,
        promptPrefix: NSAttributedString,
        response: String,
        showsPrefillPlaceholder: Bool,
        closingTail: Bool
    ) {
        let document = NSMutableAttributedString()
        if !prompt.isEmpty || promptPrefix.length > 0 {
            document.append(NSAttributedString(
                string: "You\n",
                attributes: userLabelAttributes()))
            if promptPrefix.length > 0 {
                document.append(promptPrefix)
                if !prompt.isEmpty {
                    document.append(NSAttributedString(
                        string: "\n\n",
                        attributes: promptAttributes()))
                }
            }
            if !prompt.isEmpty {
                document.append(NSAttributedString(
                    string: prompt,
                    attributes: promptAttributes()))
            }
            document.append(NSAttributedString(
                string: "\n\n",
                attributes: promptAttributes()))
        }
        // Recovery can clear the live turn while leaving completed history.
        if !prompt.isEmpty || promptPrefix.length > 0
            || !response.isEmpty || showsPrefillPlaceholder {
            document.append(NSAttributedString(
                string: "Answer\n",
                attributes: assistantLabelAttributes()))
        }
        assistantRange = NSRange(location: document.length, length: 0)
        let assistant = progressiveRendering
            ? progressiveRender(response, closingTail: closingTail)
            : NSAttributedString(string: response, attributes: responseAttributes())
        document.append(assistant)
        assistantRange.length = assistant.length
        prefillDotCount = 0
        prefillPlaceholderRange = nil
        if showsPrefillPlaceholder {
            let placeholder = NSAttributedString(
                string: Self.prefillPlaceholder(dotCount: prefillDotCount),
                attributes: prefillPlaceholderAttributes())
            prefillPlaceholderRange = NSRange(
                location: document.length,
                length: placeholder.length)
            document.append(placeholder)
        }
        // Only the live turn is replaced. `setAttributedString` would take the
        // completed turns with it, and rebuilding is the common path — every
        // prompt change and every non-extending response goes through here.
        if frozenLength == 0 {
            storage.setAttributedString(document)
        } else {
            storage.replaceCharacters(
                in: NSRange(location: frozenLength,
                            length: storage.length - frozenLength),
                with: document)
            assistantRange.location += frozenLength
            if prefillPlaceholderRange != nil {
                prefillPlaceholderRange?.location += frozenLength
            }
        }
        isFinalized = false
    }

    /// Freezes the live turn into the history above it and starts an empty one.
    ///
    /// Called when a turn is committed. The drawn turn is left exactly as it
    /// is: sealing is bookkeeping, not a re-render, so a finished answer never
    /// changes appearance after the fact.
    public func sealTurn(storage: NSMutableAttributedString) {
        guard storage.length > frozenLength else { return }
        let start = frozenLength
        let answer = response
        storage.append(NSAttributedString(
            string: "\n\n", attributes: promptAttributes()))
        frozenLength = storage.length
        sealedTurns.append((
            range: NSRange(location: start, length: frozenLength - start),
            answer: answer))
        prompt = ""
        promptPrefixIdentifier = ""
        response = ""
        isFinalized = false
        showsPrefillPlaceholder = false
        assistantRange = NSRange(location: frozenLength, length: 0)
        prefillPlaceholderRange = nil
        prefillDotCount = 0
        progressive.reset()
    }

    /// The answer of the turn containing `index`, or nil if the index is not in
    /// a turn that has one. The live turn is included: it is the one a reader is
    /// most likely to want, and it is not sealed until the next run starts.
    public func answer(at index: Int) -> String? {
        for turn in sealedTurns where NSLocationInRange(index, turn.range) {
            return turn.answer.isEmpty ? nil : turn.answer
        }
        guard index >= frozenLength, !response.isEmpty else { return nil }
        return response
    }

    /// Marks where the model's context begins.
    ///
    /// Everything above this line is on screen but no longer in the KV — a
    /// reload or an unload took it. Saying so is the difference between a
    /// transcript the user can trust and one that quietly implies the model
    /// remembers what it cannot.
    public func appendContextBreak(storage: NSMutableAttributedString, text: String) {
        guard storage.length == frozenLength else { return }
        storage.append(NSAttributedString(
            string: "\(text)\n\n", attributes: contextBreakAttributes()))
        frozenLength = storage.length
        assistantRange = NSRange(location: frozenLength, length: 0)
    }

    /// Empties the transcript, history included. New chat, not a new turn.
    public func resetTranscript(storage: NSMutableAttributedString) {
        storage.setAttributedString(NSAttributedString())
        frozenLength = 0
        sealedTurns.removeAll()
        prompt = ""
        promptPrefixIdentifier = ""
        response = ""
        isFinalized = false
        showsPrefillPlaceholder = false
        assistantRange = NSRange(location: 0, length: 0)
        prefillPlaceholderRange = nil
        prefillDotCount = 0
        progressive.reset()
    }

    // MARK: - Progressive rendering

    /// What the transcript shows while an answer is still arriving: every
    /// completed block already styled, and the block being written re-rendered
    /// from an auto-closed copy of itself. Finalize closes that last block the
    /// same way, so nothing above it is ever looked at twice.
    ///
    /// The cost of rendering block by block is that a block cannot see the
    /// rest of the answer: a `[label][ref]` whose definition sits in a later
    /// block keeps its brackets. Resolving it per tick is the quadratic shape
    /// the timing gate forbids, and resolving it only at finalize would
    /// reintroduce the flip this pass removed.
    private struct ProgressiveState {
        var split = ResponseBlockSplitter.Split()
        /// Completed blocks that are already drawn.
        var renderedBlocks = 0
        /// NSString length of those blocks and the separators between them,
        /// including the separator that precedes the open tail.
        var prefixLength = 0
        /// UTF-8 offset of the open block the drawn tail was made from.
        var tailStart: Int?
        var fence: FenceTail?
        var codeStyle: (bodyStart: Int, attributes: [NSAttributedString.Key: Any])?
        var nestedCodes: (start: Int, blocks: [TranscriptCodeBlock])?
        /// Rendered blocks keyed by position and text. Position is part of the
        /// key because two identical tables must not share one `NSTextTable`,
        /// which TextKit would draw as a single merged table.
        var cache: [BlockKey: NSAttributedString] = [:]

        mutating func reset() {
            split = ResponseBlockSplitter.Split()
            renderedBlocks = 0
            prefixLength = 0
            tailStart = nil
            fence = nil
            codeStyle = nil
            nestedCodes = nil
        }
    }

    private struct BlockKey: Hashable {
        let start: Int
        let text: String
    }

    /// A fenced block that is still arriving. It is drawn directly rather than
    /// through the markdown pass because it is the one block with no size
    /// bound: re-parsing a 10 KB listing on each of the ~1,200 ticks it takes
    /// to stream is quadratic, while appending the bytes that arrived is not.
    private struct FenceTail {
        let attributes: [NSAttributedString.Key: Any]
        let bodyStart: Int
        var bodyEnd: Int
        var filter: CodeBodyFilter
        /// The drawn tail ends with a newline this controller added because the
        /// body has none of its own yet; the next delta replaces it.
        var synthetic: Bool
    }

    /// Turns raw fenced-body bytes into what the markdown parser would have
    /// produced: CRLF and a lone CR become LF, and the opening fence's own
    /// indentation comes off every line. Deltas arrive one at a time, so the CR
    /// that ends one and the LF that starts the next still collapse into a
    /// single line break.
    private struct CodeBodyFilter {
        let indent: Int
        private var pendingCarriageReturn = false
        /// Columns of the current line consumed while the opening fence's own
        /// indentation comes off. A tab is four columns wide, so one that
        /// reaches past the fence's indent keeps the columns it owns beyond
        /// it: dropping the whole tab lost the listing's indentation until the
        /// answer finalized and the markdown pass drew it properly.
        private var column = 0
        private var stripping: Bool
        private(set) var endsWithNewline = true

        init(indent: Int) {
            self.indent = indent
            stripping = indent > 0
        }

        /// Scalars, not characters: Swift reads CRLF as one `Character`, so a
        /// character loop would carry the carriage return straight through into
        /// the transcript.
        mutating func append(_ raw: String) -> String {
            var output = String.UnicodeScalarView()
            output.reserveCapacity(raw.unicodeScalars.count)
            for scalar in raw.unicodeScalars {
                if scalar == "\n" {
                    if pendingCarriageReturn {
                        pendingCarriageReturn = false
                        continue
                    }
                    output.append("\n")
                    startLine()
                    endsWithNewline = true
                    continue
                }
                pendingCarriageReturn = false
                if scalar == "\r" {
                    pendingCarriageReturn = true
                    output.append("\n")
                    startLine()
                    endsWithNewline = true
                    continue
                }
                if stripping, scalar == " " {
                    column += 1
                    stripping = column < indent
                    continue
                }
                if stripping, scalar == "\t" {
                    let reached = column + 4 - column % 4
                    column = reached
                    stripping = false
                    if reached > indent {
                        for _ in 0..<(reached - indent) { output.append(" ") }
                        endsWithNewline = false
                    }
                    continue
                }
                stripping = false
                endsWithNewline = false
                output.append(scalar)
            }
            return String(output)
        }

        private mutating func startLine() {
            column = 0
            stripping = indent > 0
        }
    }

    private func progressiveRender(
        _ response: String,
        closingTail: Bool
    ) -> NSAttributedString {
        progressive.reset()
        let split = ResponseBlockSplitter.split(response)
        progressive.split = split
        let content = NSMutableAttributedString()
        var trailing = 0
        for block in split.completed {
            // With the separator the incremental path writes. Without it a
            // rebuild mid-answer — an image thumbnail landing and changing the
            // prompt prefix — glued every completed block to the one above it
            // and left the answer that way until finalize.
            append(
                block,
                of: response,
                to: content,
                trailing: &trailing,
                isFirst: content.length == 0)
        }
        progressive.renderedBlocks = split.completed.count
        if let open = split.open {
            content.append(separator(trailingNewlines: trailing, isFirst: content.length == 0))
            progressive.prefixLength = content.length
            if closingTail {
                // A terminal rebuild draws the last block finished. Rendering it
                // as a tail and then re-rendering the whole answer cost N+2
                // passes over an answer that was already on screen.
                progressive.tailStart = open.start
                progressive.fence = nil
                content.append(renderedBlock(open, of: response))
            } else {
                content.append(renderTail(open, of: response))
            }
        } else {
            progressive.prefixLength = content.length
        }
        return content
    }

    private struct ProgressiveUpdate {
        let mutation: Mutation
        var replaced: ReplacedRange?
    }

    private func extendProgressiveRender(
        storage: NSMutableAttributedString,
        response: String,
        closingTail: Bool
    ) -> ProgressiveUpdate {
        let split = ResponseBlockSplitter.split(response, resuming: progressive.split)
        progressive.split = split

        if !closingTail,
           split.completed.count == progressive.renderedBlocks,
           let open = split.open,
           open.start == progressive.tailStart,
           let fence = open.fence,
           let drawn = progressive.fence,
           fence.bodyStart == drawn.bodyStart {
            return growFence(fence, storage: storage, response: response)
        }

        var replacedTail = false
        let drawnTail = tailRange
        let drawnTailText = (storage.string as NSString).substring(with: NSRange(
            location: min(drawnTail.location, storage.length),
            length: min(drawnTail.length, max(0, storage.length - drawnTail.location)))) as NSString
        if progressive.tailStart != nil {
            if let promoted = split.completed[safe: progressive.renderedBlocks],
               promoted.start == progressive.tailStart,
               keepsDrawnBytes(promoted) {
                // The tail was a fenced block drawn from exactly this body; its
                // closing line adds nothing to the render, so the bytes stay
                // where they are and only the boundary moves.
                progressive.prefixLength += drawnTail.length
                progressive.renderedBlocks += 1
            } else if drawnTail.length > 0 {
                storage.deleteCharacters(in: drawnTail)
                assistantRange.length = progressive.prefixLength
                replacedTail = true
            }
            progressive.tailStart = nil
            progressive.fence = nil
        }

        let addition = NSMutableAttributedString()
        var trailing = trailingNewlines(in: storage)
        while progressive.renderedBlocks < split.completed.count {
            let block = split.completed[progressive.renderedBlocks]
            append(
                block,
                of: response,
                to: addition,
                trailing: &trailing,
                isFirst: assistantRange.length == 0 && addition.length == 0)
            progressive.renderedBlocks += 1
        }
        if let open = split.open {
            addition.append(separator(
                trailingNewlines: trailing,
                isFirst: assistantRange.length == 0 && addition.length == 0))
            progressive.prefixLength = assistantRange.length + addition.length
            if closingTail {
                progressive.tailStart = open.start
                progressive.fence = nil
                addition.append(renderedBlock(open, of: response))
            } else {
                addition.append(renderTail(open, of: response))
            }
        } else {
            progressive.prefixLength = assistantRange.length + addition.length
        }
        guard addition.length > 0 else {
            guard replacedTail else { return ProgressiveUpdate(mutation: .none) }
            return ProgressiveUpdate(
                mutation: .tailReplaced,
                replaced: ReplacedRange(previous: drawnTail, length: 0))
        }
        storage.replaceCharacters(
            in: NSRange(location: assistantRange.upperBound, length: 0),
            with: addition)
        assistantRange.length += addition.length
        guard replacedTail else { return ProgressiveUpdate(mutation: .appended) }
        return ProgressiveUpdate(
            mutation: .tailReplaced,
            replaced: ReplacedRange.differing(
                previous: drawnTail,
                old: drawnTailText,
                new: addition.string as NSString)
                ?? ReplacedRange(previous: drawnTail, length: addition.length))
    }

    /// Closes the block that was still being written, in place.
    ///
    /// The blocks above it are the ones already drawn: nothing above the open
    /// block is looked at again, so a message-wide gate cannot turn a styled
    /// answer back into raw source at the moment it finishes.
    private func closeTail(
        storage: NSMutableAttributedString,
        response: String
    ) -> ReplacedRange? {
        let update = extendProgressiveRender(
            storage: storage,
            response: response,
            closingTail: true)
        return update.replaced
    }

    /// Appends one completed block and remembers how many newlines it left
    /// behind, so the next separator matches what a whole-document render puts
    /// between the same two blocks.
    private func append(
        _ block: ResponseBlockSplitter.Block,
        of response: String,
        to content: NSMutableAttributedString,
        trailing: inout Int,
        isFirst: Bool
    ) {
        let rendered = renderedBlock(block, of: response)
        // A block that draws nothing — an empty fence — takes no separator
        // with it either, or the gap around it is written twice.
        guard rendered.length > 0 else { return }
        let separator = self.separator(trailingNewlines: trailing, isFirst: isFirst)
        content.append(separator)
        content.append(rendered)
        // The separator's own newlines count too. Seeding with the previous
        // block's count instead left a fence whose body is one blank line with
        // an extra paragraph gap under it that the whole render does not have.
        trailing = min(2, Self.trailingNewlines(
            rendered.string,
            seed: trailing + separator.length))
    }

    private func separator(trailingNewlines: Int, isFirst: Bool) -> NSAttributedString {
        guard !isFirst else { return NSAttributedString() }
        return renderer.blockSeparator(trailingNewlines: trailingNewlines)
    }

    private func codeAttributes(for fence: ResponseBlockSplitter.Fence) -> [NSAttributedString.Key: Any] {
        if let style = progressive.codeStyle, style.bodyStart == fence.bodyStart { return style.attributes }
        let attributes = renderer.streamingCodeAttributes()
        progressive.codeStyle = (fence.bodyStart, attributes)
        return attributes
    }

    private func preservingCodeIdentity(_ rendered: NSAttributedString, blockStart: Int) -> NSAttributedString {
        // Lists and quotes are reparsed as their tail grows. Reuse identities
        // by code order within that same block so a focused button survives.
        let previous = progressive.nestedCodes?.start == blockStart ? progressive.nestedCodes?.blocks ?? [] : []
        var blocks: [TranscriptCodeBlock] = []
        var replacement: NSMutableAttributedString?
        rendered.enumerateAttribute(.transcriptCodeBlock, in: NSRange(location: 0, length: rendered.length)) { value, range, _ in
            guard let fresh = value as? TranscriptCodeBlock else { return }
            let stable = previous[safe: blocks.count] ?? fresh
            stable.syntheticTerminator = fresh.syntheticTerminator
            blocks.append(stable)
            if stable !== fresh {
                if replacement == nil { replacement = NSMutableAttributedString(attributedString: rendered) }
                replacement?.addAttribute(.transcriptCodeBlock, value: stable, range: range)
            }
        }
        progressive.nestedCodes = (blockStart, blocks)
        return replacement ?? rendered
    }

    private func blockSource(_ block: ResponseBlockSplitter.Block, in response: String) -> String {
        var text = ResponseBlockSplitter.text(block.utf8Range, in: response)
        // Splitter ranges omit line terminators. Markdown needs that last real
        // newline to distinguish indented code from a synthetic paragraph end.
        guard block.kind == .indentedCode || block.kind == .list || block.kind == .quote else { return text }
        let suffix = ResponseBlockSplitter.text(block.end..<min(block.end + 2, response.utf8.count), in: response)
        if suffix.hasPrefix("\r\n") { text += "\r\n" }
        else if suffix.hasPrefix("\n") { text += "\n" }
        else if suffix.hasPrefix("\r") { text += "\r" }
        return text
    }

    private func renderedBlock(
        _ block: ResponseBlockSplitter.Block,
        of response: String
    ) -> NSAttributedString {
        // Empty body included: a fence with nothing in it renders nothing.
        // Sending it to the markdown pass instead produced an empty document,
        // which the renderer turns into raw fallback, so a rebuild mid-answer
        // put "```" back on screen where the streamed render had drawn nothing.
        if let fence = block.fence {
            return code(fence, of: response, attributes: codeAttributes(for: fence)).text
        }
        let text = blockSource(block, in: response)
        let key = BlockKey(start: block.start, text: text)
        if let cached = progressive.cache[key] { return cached }
        let rendered = preservingCodeIdentity(
            renderer.render(text, typesetsMath: true).attributedString, blockStart: block.start)
        // A session cannot grow this without bound; block renders are already
        // held by the storage, and dropping the whole table beats ageing it.
        if progressive.cache.count >= 512 { progressive.cache.removeAll(keepingCapacity: true) }
        // Code runs carry mutable occurrence identities and TextKit cells.
        // Reusing them across turns or resets resurrects obsolete controls.
        var containsCode = false
        rendered.enumerateAttribute(.transcriptCodeBlock, in: NSRange(location: 0, length: rendered.length)) { value, _, stop in
            if value != nil { containsCode = true; stop.pointee = true }
        }
        if !containsCode { progressive.cache[key] = rendered }
        return rendered
    }

    /// The open block, styled. Math stays as source here: a half-typed equation
    /// cannot typeset, so asking per tick only produces a failed parse and a
    /// log line, and the block is typeset once when it completes.
    private func renderTail(
        _ block: ResponseBlockSplitter.Block,
        of response: String
    ) -> NSAttributedString {
        progressive.tailStart = block.start
        if let fence = block.fence {
            let drawn = code(
                fence,
                of: response,
                attributes: codeAttributes(for: fence))
            progressive.fence = drawn.state
            return drawn.text
        }
        progressive.fence = nil
        let text = blockSource(block, in: response)
        let closed = TailAutoClose.close(text, typesetsMath: false)
        let rendered = renderer.render(closed, typesetsMath: false).attributedString
        if !TranscriptCodeBlock.endsWithLineBreak(text), closed.hasPrefix(text + "\n"), rendered.length > 0,
           let block = rendered.attribute(.transcriptCodeBlock, at: rendered.length - 1, effectiveRange: nil) as? TranscriptCodeBlock {
            block.syntheticTerminator = true
        }
        return preservingCodeIdentity(rendered, blockStart: block.start)
    }

    private func code(
        _ fence: ResponseBlockSplitter.Fence,
        of response: String,
        attributes: [NSAttributedString.Key: Any]
    ) -> (text: NSAttributedString, state: FenceTail) {
        var filter = CodeBodyFilter(indent: fence.indent)
        var body = filter.append(ResponseBlockSplitter.text(
            fence.bodyStart..<fence.bodyEnd,
            in: response))
        // Every code line is a paragraph; the last one needs its terminator or
        // the container closes mid-line.
        let synthetic = !filter.endsWithNewline
        if synthetic { body.append("\n") }
        (attributes[.transcriptCodeBlock] as? TranscriptCodeBlock)?.syntheticTerminator = synthetic
        return (
            NSAttributedString(string: body, attributes: attributes),
            FenceTail(
                attributes: attributes,
                bodyStart: fence.bodyStart,
                bodyEnd: fence.bodyEnd,
                filter: filter,
                synthetic: synthetic))
    }

    private func growFence(
        _ fence: ResponseBlockSplitter.Fence,
        storage: NSMutableAttributedString,
        response: String
    ) -> ProgressiveUpdate {
        guard var drawn = progressive.fence else { return ProgressiveUpdate(mutation: .none) }
        guard fence.bodyEnd >= drawn.bodyEnd else {
            // A closing fence line took bytes back out of the body. Redrawing
            // costs one pass over a block that is about to stop growing.
            let redrawn = code(fence, of: response, attributes: drawn.attributes)
            progressive.fence = redrawn.state
            let previous = tailRange
            let before = (storage.string as NSString).substring(with: previous) as NSString
            storage.replaceCharacters(in: previous, with: redrawn.text)
            assistantRange.length = progressive.prefixLength + redrawn.text.length
            return ProgressiveUpdate(
                mutation: .tailReplaced,
                replaced: ReplacedRange.differing(
                    previous: previous,
                    old: before,
                    new: redrawn.text.string as NSString)
                    ?? ReplacedRange(previous: previous, length: redrawn.text.length))
        }
        let raw = ResponseBlockSplitter.text(drawn.bodyEnd..<fence.bodyEnd, in: response)
        guard !raw.isEmpty else { return ProgressiveUpdate(mutation: .none) }
        var delta = drawn.filter.append(raw)
        let synthetic = !drawn.filter.endsWithNewline
        if synthetic { delta.append("\n") }
        // The newline that goes away is the one the previous tick added, not
        // the one this tick is about to.
        let removal = NSRange(
            location: assistantRange.upperBound - (drawn.synthetic ? 1 : 0),
            length: drawn.synthetic ? 1 : 0)
        drawn.bodyEnd = fence.bodyEnd
        drawn.synthetic = synthetic
        (drawn.attributes[.transcriptCodeBlock] as? TranscriptCodeBlock)?.syntheticTerminator = synthetic
        progressive.fence = drawn
        guard !delta.isEmpty || removal.length > 0 else {
            return ProgressiveUpdate(mutation: .none)
        }
        storage.replaceCharacters(
            in: removal,
            with: NSAttributedString(string: delta, attributes: drawn.attributes))
        assistantRange.length += (delta as NSString).length - removal.length
        return ProgressiveUpdate(mutation: .appended)
    }

    /// True when the drawn tail is already exactly what this newly completed
    /// block renders to, so its bytes can stay in place.
    private func keepsDrawnBytes(_ block: ResponseBlockSplitter.Block) -> Bool {
        guard let fence = block.fence, let drawn = progressive.fence else { return false }
        return fence.bodyStart == drawn.bodyStart && fence.bodyEnd == drawn.bodyEnd
    }

    private func trailingNewlines(in storage: NSMutableAttributedString) -> Int {
        guard assistantRange.length > 0 else { return 0 }
        let text = storage.string as NSString
        var count = 0
        var index = min(assistantRange.upperBound, text.length) - 1
        while index >= assistantRange.location, count < 2,
              text.character(at: index) == 10 {
            count += 1
            index -= 1
        }
        return count
    }

    private static func trailingNewlines(_ text: String, seed: Int) -> Int {
        var count = 0
        for character in text.reversed() {
            guard character == "\n" else { return count }
            count += 1
        }
        return count + seed
    }

    private func userLabelAttributes() -> [NSAttributedString.Key: Any] {
        labelAttributes(color: .secondaryLabelColor)
    }

    private func assistantLabelAttributes() -> [NSAttributedString.Key: Any] {
        labelAttributes(color: TurboFieldfareMacTheme.accentNSColor)
    }

    private func labelAttributes(
        color: NSColor
    ) -> [NSAttributedString.Key: Any] {
        let style = NSMutableParagraphStyle()
        style.paragraphSpacing = typography.scaled(5)
        return [
            .font: NSFont.systemFont(
                ofSize: typography.labelSize,
                weight: .semibold),
            .foregroundColor: color,
            .paragraphStyle: style,
        ]
    }

    private func contextBreakAttributes() -> [NSAttributedString.Key: Any] {
        let style = NSMutableParagraphStyle()
        style.alignment = .center
        style.paragraphSpacingBefore = typography.scaled(8)
        style.paragraphSpacing = typography.scaled(8)
        return [
            .font: NSFont.systemFont(
                ofSize: typography.labelSize, weight: .regular),
            .foregroundColor: NSColor.tertiaryLabelColor,
            .paragraphStyle: style,
        ]
    }

    private func promptAttributes() -> [NSAttributedString.Key: Any] {
        let style = NSMutableParagraphStyle()
        style.lineSpacing = typography.scaled(3)
        return [
            .font: typography.bodyFont,
            .foregroundColor: NSColor.secondaryLabelColor,
            .paragraphStyle: style,
        ]
    }

    private func responseAttributes() -> [NSAttributedString.Key: Any] {
        let style = NSMutableParagraphStyle()
        style.lineSpacing = typography.scaled(3)
        style.paragraphSpacing = typography.scaled(6)
        return [
            .font: typography.bodyFont,
            .foregroundColor: NSColor.labelColor,
            .paragraphStyle: style,
        ]
    }

    private func prefillPlaceholderAttributes() -> [NSAttributedString.Key: Any] {
        var attributes = responseAttributes()
        attributes[.foregroundColor] = NSColor.secondaryLabelColor
        return attributes
    }

    private static func prefillPlaceholder(dotCount: Int) -> String {
        "Processing your prompt" + String(repeating: ".", count: dotCount)
    }
}

extension Array {
    fileprivate subscript(safe index: Int) -> Element? {
        indices.contains(index) ? self[index] : nil
    }
}


extension InstructionTranscriptDocumentController {
    /// Replays the current presentation once, without inventing a new run or
    /// finalizing its open block. Ordinary token updates retain their caches.
    @discardableResult
    public func refreshTypography(
        _ typography: ConversationTypography,
        storage: NSMutableAttributedString,
        planner: inout TranscriptSyncPlanner,
        input: TranscriptSyncPlanner.Input,
        promptPrefix: NSAttributedString,
        renderer: (any TranscriptBlockRendering)? = nil,
        drawPair: (Int) -> Void
    ) -> UpdateResult {
        guard typography != self.typography else {
            return UpdateResult(mutation: .none, assistantRange: assistantRange)
        }
        let old = storage.string as NSString
        let currentPrompt = prompt
        let currentResponse = response
        let prefixIdentifier = promptPrefixIdentifier
        let terminal = isFinalized
        let placeholder = showsPrefillPlaceholder
        let dots = prefillDotCount
        self.typography = typography
        self.renderer = renderer ?? ResponseMarkdownRenderer(
            typography: typography, environment: environment)
        // resetTranscript deliberately retains this cache for ordinary replay.
        // At a new size, every cached attributed run is stale.
        progressive = ProgressiveState()
        planner = TranscriptSyncPlanner()
        storage.beginEditing()
        defer { storage.endEditing() }
        synchronizeHistory(storage: storage, planner: &planner, input: input,
                           drawPair: drawPair)
        synchronize(storage: storage, prompt: currentPrompt, response: currentResponse,
                    isTerminal: terminal, showsPrefillPlaceholder: placeholder,
                    promptPrefix: promptPrefix, promptPrefixIdentifier: prefixIdentifier)
        if placeholder {
            for _ in 0..<dots { advancePrefillAnimation(storage: storage) }
        }
        return UpdateResult(
            mutation: .rebuilt, assistantRange: assistantRange,
            replaced: ReplacedRange.differing(
                previous: NSRange(location: 0, length: old.length),
                old: old, new: storage.string as NSString))
    }

    /// Execute history updates as one storage edit before the new live turn.
    /// The view supplies cached image prefixes without moving image loading here.
    @discardableResult
    public func synchronizeHistory(
        storage: NSMutableAttributedString,
        planner: inout TranscriptSyncPlanner,
        input: TranscriptSyncPlanner.Input,
        drawPair: (Int) -> Void
    ) -> [TranscriptSyncStep] {
        let steps = planner.plan(input)
        guard !steps.isEmpty else { return steps }
        storage.beginEditing()
        defer { storage.endEditing() }
        for step in steps {
            switch step {
            case .reset:
                resetTranscript(storage: storage)
            case .sealDrawnTurn:
                let before = frozenLength
                sealTurn(storage: storage)
                if frozenLength == before {
                    planner.sealFoundNothingToFreeze(historyCount: input.historyCount)
                }
            case .drawPair(let index):
                drawPair(index)
                sealTurn(storage: storage)
            case .appendContextBreak:
                let before = frozenLength
                appendContextBreak(storage: storage,
                    text: "Earlier turns are no longer in the model's context")
                if frozenLength != before { planner.markContextBreakDrawn() }
            }
        }
        return steps
    }
}