Fix OSC 8 print-time hyperlink attribution (closes #635)

Author: migueldeicaza

Sources/SwiftTerm/Buffer.swift

@@ -1577,11 +1577,17 @@ public final class Buffer {
 
     /// Bulk-inserts ASCII characters (all width-1, non-combining).
     /// Returns number of bytes consumed. Returns 0 if insert mode is active.
-    func insertAsciiRun(_ bytes: ArraySlice<UInt8>, attribute: Attribute) -> Int {
+    func insertAsciiRun(
+        _ bytes: ArraySlice<UInt8>,
+        attribute: Attribute,
+        resolvePayload: () -> TinyAtom?
+    ) -> Int {
         guard !insertMode else { return 0 }
         let right = marginMode ? _marginRight : _cols - 1
         var consumed = 0
         var idx = bytes.startIndex
+        var payload: TinyAtom?
+        var didResolvePayload = false
 
         while idx < bytes.endIndex {
             if _x > right {
@@ -1599,9 +1605,16 @@ public final class Buffer {
             let available = right - _x + 1
             let runLen = min(available, bytes.endIndex - idx)
             let row = _lines[_y + _yBase]
+            if !didResolvePayload {
+                payload = resolvePayload()
+                didResolvePayload = true
+            }
             for i in 0..<runLen {
                 var cell = CharData(attribute: attribute, code: Int32(bytes[idx + i]), size: 1)
                 cell.setSemanticContent(semanticContent)   // buffer's own classification (D.1)
+                if let payload {
+                    cell.setPayload(atom: payload)
+                }
                 row[_x + i] = cell
             }
             _x += runLen
@@ -1611,7 +1624,7 @@ public final class Buffer {
         return consumed
     }
 
-    func insertCharacter(_ charData: CharData) {
+    func insertCharacter(_ charData: CharData, resolvePayload: () -> TinyAtom?) {
         // D.1: stamp the OSC 133 role once, here at the insertion funnel, from
         // the buffer's own classification. No caller can forget to stamp, and
         // during ordinary output `semanticContent` is `.none` (a no-op).
@@ -1673,6 +1686,7 @@ public final class Buffer {
         if _x >= _cols {
             _x = _cols-1
         }
+        charData.setPayload(atom: resolvePayload() ?? TinyAtom.empty)
         bufferRow[_x] = charData
         _x += 1
 
@@ -1682,6 +1696,7 @@ public final class Buffer {
         if chWidth > 1 {
             var wideEmpty = CharData(attribute: curAttr, scalar: UnicodeScalar(0)!, size: 0)
             wideEmpty.setSemanticContent(charData.semanticContent)
+            wideEmpty.setPayload(atom: charData.payload)
             chWidth -= 1
             while chWidth != 0 && _x < _cols {
                 bufferRow [_x] = wideEmpty

Sources/SwiftTerm/Terminal.swift

@@ -984,7 +984,7 @@ open class Terminal {
         xtermTitleSetHex = false
         xtermTitleQueryHex = false
 
-        hyperLinkTracking = nil
+        activeHyperlink = nil
         cursorBlink = false
         hostCurrentDirectory = nil
         lineFeedMode = options.convertEol
@@ -1309,7 +1309,11 @@ open class Terminal {
             }
             if allAscii {
                 updateRange(borrowing: buffer, buffer.y)
-                let consumed = buffer.insertAsciiRun(data, attribute: curAttr)
+                let consumed = buffer.insertAsciiRun(
+                    data,
+                    attribute: curAttr,
+                    resolvePayload: { self.resolveActiveHyperlink() }
+                )
                 if consumed == data.count {
                     updateRange(borrowing: buffer, buffer.y)
                     return
@@ -1345,7 +1349,7 @@ open class Terminal {
                         // Every single mapping in the charset only takes one slot
                         chWidth = 1
                         let charData = makeCharData (attribute: curAttr, char: ch, size: Int8 (chWidth))
-                        buffer.insertCharacter(charData)
+                        insertCharacter(charData)
                         continue
                     }
                 }
@@ -1354,7 +1358,7 @@ open class Terminal {
                 chWidth = UnicodeUtil.columnWidth(rune: rune)
                 if chWidth > 0 {
                     let charData = makeCharData (attribute: curAttr, scalar: rune, size: Int8 (chWidth))
-                    buffer.insertCharacter(charData)
+                    insertCharacter(charData)
                 }
                 continue
             } else if readingBuffer.bytesLeft() >= (n-1) {
@@ -1383,7 +1387,7 @@ open class Terminal {
                     chWidth = UnicodeUtil.columnWidth(rune: rune)
                     if chWidth > 0 {
                         let charData = makeCharData (attribute: curAttr, scalar: rune, size: Int8 (chWidth))
-                        buffer.insertCharacter(charData)
+                        insertCharacter(charData)
                     }
                     continue
                 }
@@ -1498,6 +1502,7 @@ open class Terminal {
                                     let nextX = lastx + 1
                                     var empty = makeCharData (attribute: cd.attribute, code: 0, size: 0)
                                     empty.setSemanticContent(cd.semanticContent)
+                                    empty.setPayload(atom: cd.payload)
                                     existingLine [nextX] = empty
                                     buffer.x += 1
                                 } else {
@@ -1513,6 +1518,7 @@ open class Terminal {
                                 updateCharData(&cd, char: newCh, size: 2)
                                 var empty = makeCharData(attribute: cd.attribute, code: 0, size: 0)
                                 empty.setSemanticContent(cd.semanticContent)
+                                empty.setPayload(atom: cd.payload)
                                 existingLine [lastx + 1] = empty
                                 buffer.x += 1
                             } else {
@@ -1537,7 +1543,7 @@ open class Terminal {
             //    emitChar (ch)
             //}
             let charData = makeCharData (attribute: curAttr, char: ch, size: Int8 (chWidth))
-            buffer.insertCharacter(charData)
+            insertCharacter(charData)
         }
         updateRange(borrowing: buffer, buffer.y)
         readingBuffer.done ()
@@ -1612,9 +1618,10 @@ open class Terminal {
     // Inserts the specified character with the computed width into the next cell, following
     // the rules for wrapping around, scrolling and overflow expected in the terminal.
     func insertCharacter (_ charData: CharData) {
-        // TODO, make this a direct call. no need to pproxy here
         buffer.insertCharacter(
-            charData)
+            charData,
+            resolvePayload: { self.resolveActiveHyperlink() }
+        )
     }
 
 //    func insertCharacter2(_ charData: CharData) {
@@ -2601,9 +2608,35 @@ open class Terminal {
         }
     }
 
-    var hyperLinkTracking: (start: Position, payload: String)? = nil
+    private enum ActiveHyperlink {
+        case pending(String)
+        case resolved(TinyAtom)
+        case unavailable
+    }
+
+    private var activeHyperlink: ActiveHyperlink? = nil
     private var payloadCodes = Set<UInt16>()
 
+    private func resolveActiveHyperlink() -> TinyAtom? {
+        guard let activeHyperlink else {
+            return nil
+        }
+
+        switch activeHyperlink {
+        case .pending(let payload):
+            guard let atom = makePayload(value: payload) else {
+                self.activeHyperlink = .unavailable
+                return nil
+            }
+            self.activeHyperlink = .resolved(atom)
+            return atom
+        case .resolved(let atom):
+            return atom
+        case .unavailable:
+            return nil
+        }
+    }
+
     /// Creates a payload atom whose lifetime is managed by this terminal.
     ///
     /// ``garbageCollectPayload()`` releases the atom after it is no longer present in
@@ -2619,35 +2652,11 @@ open class Terminal {
 
     func oscHyperlink (_ data: ArraySlice<UInt8>)
     {
-        let buffer = self.buffer
         if data.count == 1 && data [data.startIndex] == UInt8 (ascii: ";") {
-            // We only had the terminator, so we can close ";"
-            if let hlt = hyperLinkTracking {
-                let str = hlt.payload
-                if let urlToken = makePayload(value: str) {
-                    //print ("Setting the text from \(hlt.start) to \(buffer.x) on line \(buffer.y+buffer.yBase) to \(str)")
-                    
-                    // Between the time the flag was set, and now `y` might have changed negatively,
-                    // in that case, we do not flag any sequence as a hyperlink
-                    if hlt.start.row <= buffer.y+buffer.yBase {
-                        for y in hlt.start.row...(buffer.y+buffer.yBase) {
-                            let line = buffer.lines [y]
-                            let startCol = y == hlt.start.row ? min (hlt.start.col, cols-1) : 0
-                            let endCol = y == buffer.y ? min (buffer.x, cols-1) : (marginMode ? buffer.marginRight : cols-1)
-                            if endCol > startCol {
-                                for x in startCol...endCol {
-                                    var cd = line [x]
-                                    cd.setPayload(atom: urlToken)
-                                    line [x] = cd
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-            hyperLinkTracking = nil
+            activeHyperlink = nil
         } else {
-            hyperLinkTracking = (start: Position(col: buffer.x, row: buffer.y+buffer.yBase), payload: String (bytes:data, encoding: .ascii) ?? "")
+            let payload = String(bytes: data, encoding: .ascii) ?? ""
+            activeHyperlink = .pending(payload)
         }
     }
 
@@ -4592,7 +4601,7 @@ open class Terminal {
         charset = nil
         setgLevel (0)
         conformance = .vt500
-        hyperLinkTracking = nil
+        activeHyperlink = nil
         lineFeedMode = options.convertEol
         resetAllColors()
         tdel?.showCursor(source: self)
@@ -6281,6 +6290,9 @@ open class Terminal {
 
         // check all atoms used in both buffers
         var used = Set<UInt16>()
+        if let activeHyperlink, case .resolved(let atom) = activeHyperlink {
+            used.insert(atom.code)
+        }
         for buffer in [normalBuffer, altBuffer] {
             // TODO use a better system than this ugly nest
             for line in buffer.lines.getArray() {

Tests/SwiftTermTests/OscTests.swift

@@ -11,6 +11,17 @@ import Testing
 @testable import SwiftTerm
 
 final class SwiftTermOsc {
+    private func explicitLink(_ terminal: Terminal, row: Int, col: Int) -> String? {
+        terminal.link(
+            at: .buffer(Position(col: col, row: row)),
+            mode: .explicitOnly
+        )
+    }
+
+    private func payload(_ terminal: Terminal, row: Int, col: Int) -> String? {
+        terminal.getCharData(col: col, row: row)?.getPayload() as? String
+    }
+
     private func promptKinds(_ terminal: Terminal, at row: Int) -> [SemanticPromptKind] {
         terminal.semanticPromptMarks(at: row).map(\.kind)
     }
@@ -191,6 +202,85 @@ final class SwiftTermOsc {
         // Verification depends on how SwiftTerm exposes hyperlink data
     }
 
+    @Test func testOscHyperlinkMarksOnlyPrintedCellsAcrossCursorJump() {
+        let terminal = Terminal(
+            delegate: TitleDelegate(),
+            options: TerminalOptions(cols: 8, rows: 4, scrollback: 0)
+        )
+        let escape = "\u{1b}"
+        let stringTerminator = "\(escape)\\"
+
+        terminal.feed(text: "\(escape)[H")
+        terminal.feed(text: "\(escape)]8;;https://example.com\(stringTerminator)")
+        terminal.feed(text: "AB")
+
+        #expect(explicitLink(terminal, row: 0, col: 0) == "https://example.com")
+        #expect(explicitLink(terminal, row: 0, col: 1) == "https://example.com")
+
+        terminal.feed(text: "\(escape)[3;1H")
+        terminal.feed(text: "\(escape)]8;;\(stringTerminator)")
+
+        for col in 2..<terminal.cols {
+            #expect(explicitLink(terminal, row: 0, col: col) == nil)
+        }
+        for col in 0..<terminal.cols {
+            #expect(explicitLink(terminal, row: 1, col: col) == nil)
+        }
+        #expect(explicitLink(terminal, row: 2, col: 0) == nil)
+
+        terminal.feed(text: "C")
+        #expect(explicitLink(terminal, row: 2, col: 0) == nil)
+    }
+
+    @Test func testOscHyperlinkMarksWideCharacterContinuationCell() {
+        let terminal = Terminal(
+            delegate: TitleDelegate(),
+            options: TerminalOptions(cols: 4, rows: 2, scrollback: 0)
+        )
+        let escape = "\u{1b}"
+        let stringTerminator = "\(escape)\\"
+
+        terminal.feed(text: "\(escape)]8;;https://example.com\(stringTerminator)")
+        terminal.feed(text: "界")
+        terminal.feed(text: "\(escape)]8;;\(stringTerminator)")
+
+        #expect(payload(terminal, row: 0, col: 0) == ";https://example.com")
+        #expect(payload(terminal, row: 0, col: 1) == ";https://example.com")
+        #expect(payload(terminal, row: 0, col: 2) == nil)
+    }
+
+    @Test func testOscPendingHyperlinkSurvivesPayloadCollection() {
+        let terminal = Terminal(
+            delegate: TitleDelegate(),
+            options: TerminalOptions(cols: 4, rows: 2, scrollback: 0)
+        )
+        let escape = "\u{1b}"
+        let stringTerminator = "\(escape)\\"
+
+        terminal.feed(text: "\(escape)]8;;https://example.com\(stringTerminator)")
+        terminal.garbageCollectPayload()
+        terminal.feed(text: "A")
+        terminal.feed(text: "\(escape)]8;;\(stringTerminator)")
+
+        #expect(explicitLink(terminal, row: 0, col: 0) == "https://example.com")
+    }
+
+    @Test func testOscHyperlinkUsesLastPendingPayload() {
+        let terminal = Terminal(
+            delegate: TitleDelegate(),
+            options: TerminalOptions(cols: 4, rows: 2, scrollback: 0)
+        )
+        let escape = "\u{1b}"
+        let stringTerminator = "\(escape)\\"
+
+        terminal.feed(text: "\(escape)]8;;https://first.example\(stringTerminator)")
+        terminal.feed(text: "\(escape)]8;;https://second.example\(stringTerminator)")
+        terminal.feed(text: "A")
+        terminal.feed(text: "\(escape)]8;;\(stringTerminator)")
+
+        #expect(explicitLink(terminal, row: 0, col: 0) == "https://second.example")
+    }
+
     /// Test OSC 8 hyperlinks with ID parameter
     /// From Ghostty: hyperlink with id
     @Test func testOscHyperlinkWithId() {