Update with revised specs from Docs/semantic-prompt-design.md

Author: migueldeicaza

Docs/semantic-prompt-design.md

@@ -2636,9 +2636,25 @@ extension TerminalView {
     /**
      * Sends the specified slice of byte arrays to the program running under the terminal emulator
      * - Parameter data: the slice of an array to send to the client
+     *
+     * Thread contract (F.4): this runs the OSC 133 submission heuristic
+     * (`terminal.registerUserInput`) synchronously, mutating terminal state, so
+     * it MUST be called on the same thread that drives `terminal.feed` — the
+     * main thread for a `TerminalView`. Do not call it from a background I/O
+     * thread while feeding the terminal from another; doing so races the
+     * scanner against the parser and can leave the buffer armed after a
+     * submission (the injection direction). A host that needs a different
+     * threading model must marshal input onto the view's thread itself. The
+     * debug precondition below catches violations early.
      */
     public func send(data: ArraySlice<UInt8>)
     {
+        #if DEBUG
+        // Catch a host that violates the same-thread contract. Uses
+        // `Thread.isMainThread` rather than `dispatchPrecondition(.onQueue:)`,
+        // which is unreliable under Swift Concurrency's main-actor executor.
+        assert(Thread.isMainThread, "TerminalView.send(data:) must be called on the main thread")
+        #endif
         recordUserInput()
         ensureCaretIsVisible ()
         #if os(iOS) || os(visionOS)
@@ -2648,7 +2664,8 @@ extension TerminalView {
             TerminalView.textInputLogCounter += 1
         }
         #endif
-        terminalDelegate?.send (source: self, data: data)
+        terminal.registerUserInput(data)
+        terminalDelegate?.send(source: self, data: data)
     }
 
     /**

Sources/SwiftTerm/Apple/AppleTerminalView.swift

@@ -27,10 +27,32 @@ public final class BufferLine: CustomDebugStringConvertible {
     /// BiDi state for the paragraph that contains this row.
     public internal(set) var bidiState: BidiPresentationState { didSet { bump() } }
     var renderMode: RenderLineMode = .single { didSet { bump() } }
-    /// Semantic prompt classification for this row. Cell-level roles live in
-    /// `CharData.semanticContent`; this distinguishes primary and continuation
-    /// prompt rows even when they are currently blank.
-    public private(set) var semanticPromptKind: SemanticPromptKind? { didSet { bump() } }
+    /// Shell-authored OSC 133 marks on this line, at most one per kind.
+    /// A line can carry both a left prompt and a right prompt mark.
+    private(set) var semanticMarks: [SemanticMark] = [] { didSet { bump() } }
+    /// The prompt-group epoch of a line created by a hard line feed inside a
+    /// prompt group: the active group ID at stamp time, or nil for a line that
+    /// is not a hard continuation. Together with `isWrapped` this is what makes
+    /// a row derivable as a continuation, and the group ID is what keeps an old
+    /// group's stranded rows from joining a new prompt (R1/R5). Exactly one
+    /// function assigns it: `Terminal.finishSemanticLineAdvance`.
+    ///
+    /// It is structural, not content: cell erasure (EL/ED) never touches it.
+    /// Derivation-only metadata, not drawn, so it bumps the render generation
+    /// only on an actual change.
+    var semanticHardContinuationGroup: UInt64? = nil {
+        didSet { if semanticHardContinuationGroup != oldValue { bump() } }
+    }
+    /// Weak link to the owning buffer, used only so `copyFrom` can ask which
+    /// of two colliding same-kind marks is the live origin. Lines that never
+    /// carry marks (bare templates) leave this nil.
+    weak var owningBuffer: Buffer?
+    /// Bumped each time this line object is reused for different content
+    /// (recycle, reset). A deferred pointer click captures this alongside the
+    /// line identity; a mismatch at fire time means the object was recycled
+    /// into a new row and the click must be dropped — identity alone cannot
+    /// tell, because `CircularList.recycle` keeps the object in the array.
+    private(set) var recycleGeneration: UInt64 = 0
     private var data: UnsafeMutableBufferPointer<CharData>
     private var dataSize: Int
 
@@ -56,7 +78,6 @@ public final class BufferLine: CustomDebugStringConvertible {
         data = buf
         dataSize = cols
         self.isWrapped = isWrapped
-        semanticPromptKind = nil
         self.bidiState = bidiState
     }
 
@@ -66,7 +87,11 @@ public final class BufferLine: CustomDebugStringConvertible {
         isWrapped = other.isWrapped
         bidiState = other.bidiState
         renderMode = other.renderMode
-        semanticPromptKind = other.semanticPromptKind
+        semanticMarks = other.semanticMarks
+        semanticHardContinuationGroup = other.semanticHardContinuationGroup
+        // owningBuffer is NOT inherited: a clone is stamped with its real
+        // owner when it is attached to a buffer (B.3). Inheriting it from a
+        // cross-buffer template leaks the wrong owner.
         images = other.images
         let otherSize = other.dataSize
         let buf = UnsafeMutableBufferPointer<CharData>.allocate(capacity: otherSize)
@@ -128,13 +153,22 @@ public final class BufferLine: CustomDebugStringConvertible {
         return Int (data [index].width)
     }
 
+    /// Erases the cell contents. Marks are line-level metadata and survive
+    /// this: destruction of a recycled line goes through `destroySemanticState`.
     func clear(with attribute: Attribute) {
         let empty = CharData(attribute: attribute)
         data.update(repeating: empty)
-        semanticPromptKind = nil
         images = nil
+        recycleGeneration &+= 1
         bump()
     }
+
+    /// Removes the semantic prompt metadata. Called only when the line
+    /// itself is destroyed (recycled for reuse), never by cell mutations.
+    func destroySemanticState() {
+        semanticMarks.removeAll(keepingCapacity: true)
+        semanticHardContinuationGroup = nil
+    }
     /// Test whether contains any chars.
     public func hasContent (index: Int) -> Bool {
         data [index].code != 0 || data [index].attribute != CharData.defaultAttr;
@@ -171,6 +205,7 @@ public final class BufferLine: CustomDebugStringConvertible {
                 data [i] = fillData
             }
         }
+        marksShift(from: pos, by: n, rightMargin: rightMargin)
         bump()
     }
 
@@ -191,10 +226,51 @@ public final class BufferLine: CustomDebugStringConvertible {
                 data [i] = fillData
             }
         }
+        marksShift(from: pos, by: -n, rightMargin: rightMargin)
         bump()
     }
 
-    /// Replaces the cells in the start to end range with the specified fill data
+    /// Shifts mark columns with their cells when ICH inserts or DCH deletes
+    /// cells at `pos` inside the margin. Marks are never removed here: a mark
+    /// whose cell was deleted lands on `pos`, one pushed past the margin
+    /// stays on the margin.
+    func marksShift(from pos: Int, by delta: Int, rightMargin: Int) {
+        guard delta != 0, !semanticMarks.isEmpty else { return }
+        semanticMarks = semanticMarks.map { mark in
+            guard mark.column >= pos, mark.column <= rightMargin else { return mark }
+            var result = mark
+            result.column = min(max(mark.column + delta, pos), rightMargin)
+            return result
+        }
+    }
+
+    /// Clamps every mark column into the line's content width, for shrinking
+    /// resizes. A zero-width line can hold no marks.
+    func marksClampTo(width: Int) {
+        guard !semanticMarks.isEmpty else { return }
+        if width <= 0 {
+            semanticMarks.removeAll(keepingCapacity: true)
+            return
+        }
+        semanticMarks = semanticMarks.map { mark in
+            var result = mark
+            result.column = min(max(mark.column, 0), width - 1)
+            return result
+        }
+    }
+
+    /// Stores a shell-authored mark. Setting a mark of a kind the line
+    /// already carries replaces that mark: readline redisplay re-emits `A`
+    /// on the same row on every repaint.
+    func setSemanticMark(kind: SemanticPromptKind, column: Int, group: UInt64) {
+        semanticMarks.removeAll { $0.kind == kind }
+        semanticMarks.append(SemanticMark(kind: kind, column: column, group: group))
+        semanticMarks.sort { $0.column < $1.column }
+    }
+
+    /// Replaces the cells in the start to end range with the specified fill data.
+    /// Cell erasure never touches the continuation epoch (R1: structural, not
+    /// content).
     public func replaceCells (start: Int, end: Int, fillData : CharData)
     {
         let length = dataSize
@@ -259,6 +335,7 @@ public final class BufferLine: CustomDebugStringConvertible {
                 data = UnsafeMutableBufferPointer<CharData>.allocate(capacity: 0)
                 dataSize = 0
             }
+            marksClampTo(width: cols)
         }
     }
 
@@ -305,15 +382,12 @@ public final class BufferLine: CustomDebugStringConvertible {
         }
         dataSize = srcSize
         isWrapped = line.isWrapped
-        semanticPromptKind = line.semanticPromptKind
+        semanticMarks = line.semanticMarks
+        semanticHardContinuationGroup = line.semanticHardContinuationGroup
         bidiState = line.bidiState
         bump()
     }
 
-    func setSemanticPromptKind(_ kind: SemanticPromptKind?) {
-        semanticPromptKind = kind
-    }
-
     /// Returns the trimmed length in terms of cells used from the BufferLine
     ///
     public func getTrimmedLength () -> Int
@@ -334,6 +408,8 @@ public final class BufferLine: CustomDebugStringConvertible {
     ///  - len: the number of elements to copy
     public func copyFrom (_ src: BufferLine, srcCol: Int, dstCol: Int, len: Int)
     {
+        let movesSemanticHardContinuation = srcCol == 0 && dstCol == 0 && len >= count
+        let movedSemanticHardContinuationGroup = src.semanticHardContinuationGroup
         if src === self && srcCol > dstCol {
             // Overlapping forward copy: go left-to-right (already safe)
             for i in 0..<len {
@@ -349,6 +425,71 @@ public final class BufferLine: CustomDebugStringConvertible {
                 data[dstCol + i] = src.data[srcCol + i]
             }
         }
+        // Marks travel with their cells. The margin-scroll paths and reflow
+        // shuffle cell ranges between line objects through this call, and a
+        // mark's row is wherever its cells went: this moves marks, it never
+        // authors them. Marks outside the copied range stay where they are.
+        let moved = src.semanticMarks.filter { $0.column >= srcCol && $0.column < srcCol + len }
+        // Snapshot the live origin before the marks move, so a same-kind
+        // collision can be resolved by liveness rather than position. Skipped
+        // entirely on the common no-marks scroll row (E.5).
+        let origin = moved.isEmpty ? nil : owningBuffer?.rawSemanticOrigin()
+        if src === self {
+            semanticMarks.removeAll {
+                ($0.column >= srcCol && $0.column < srcCol + len) ||
+                ($0.column >= dstCol && $0.column < dstCol + len)
+            }
+        } else {
+            src.semanticMarks.removeAll { $0.column >= srcCol && $0.column < srcCol + len }
+            semanticMarks.removeAll { $0.column >= dstCol && $0.column < dstCol + len }
+        }
+        if !moved.isEmpty {
+            var originMovedHere = false
+            for mark in moved {
+                let newColumn = mark.column - srcCol + dstCol
+                let movedIsOrigin = origin.map {
+                    $0.line === src && $0.kind == mark.kind && $0.column == mark.column
+                } ?? false
+                if let idx = semanticMarks.firstIndex(where: { $0.kind == mark.kind }) {
+                    // A same-kind mark outside the copied destination range did
+                    // not move. The live origin always wins the collision: if
+                    // the origin is the mark that moved here, it displaces the
+                    // stationary one; otherwise the stationary mark is kept
+                    // (it is the origin, or — absent origin info — the
+                    // conservative choice) and the moved duplicate is dropped.
+                    let stationaryIsOrigin = origin.map {
+                        $0.line === self && $0.kind == mark.kind && $0.column == semanticMarks[idx].column
+                    } ?? false
+                    if movedIsOrigin && !stationaryIsOrigin {
+                        semanticMarks.remove(at: idx)
+                        semanticMarks.append(SemanticMark(kind: mark.kind, column: newColumn,
+                                                          group: mark.group))
+                        originMovedHere = true
+                    }
+                } else {
+                    semanticMarks.append(SemanticMark(kind: mark.kind, column: newColumn,
+                                                      group: mark.group))
+                    if movedIsOrigin {
+                        originMovedHere = true
+                    }
+                }
+            }
+            semanticMarks.sort { $0.column < $1.column }
+            if originMovedHere, src !== self {
+                // The origin's cells now live on this line; follow them so
+                // the getter binds to this object instead of relying on the
+                // rebind heuristic.
+                owningBuffer?.reassignSemanticOrigin(to: self)
+            }
+        }
+        // A full-width copy moves the continuation epoch with the content; a
+        // narrow-margin copy leaves it (R1: dead clicks over injection).
+        if movesSemanticHardContinuation {
+            semanticHardContinuationGroup = movedSemanticHardContinuationGroup
+            if src !== self {
+                src.semanticHardContinuationGroup = nil
+            }
+        }
         bump()
     }
 

Sources/SwiftTerm/Buffer.swift

@@ -292,17 +292,49 @@ public struct CharData: CustomDebugStringConvertible {
     // semantic metadata does not increase the size of a terminal cell.
     private var semanticContentCode: UInt8
 
+    // The single source of truth for the cell-storage encoding of a
+    // SemanticContent. Both directions switch exhaustively over this enum, so
+    // a new SemanticContent (or SemanticPromptKind) case fails to compile
+    // until it is mapped in both — it can never silently decode to `.none`.
+    private enum SemanticContentCode: UInt8 {
+        case none = 0
+        case promptInitial = 1
+        case promptRight = 2
+        case promptContinuation = 3
+        case promptSecondary = 4
+        case input = 5
+        case output = 6
+
+        var content: SemanticContent {
+            switch self {
+            case .none: return .none
+            case .promptInitial: return .prompt(.initial)
+            case .promptRight: return .prompt(.right)
+            case .promptContinuation: return .prompt(.continuation)
+            case .promptSecondary: return .prompt(.secondary)
+            case .input: return .input
+            case .output: return .output
+            }
+        }
+
+        init(_ content: SemanticContent) {
+            switch content {
+            case .none: self = .none
+            case .prompt(.initial): self = .promptInitial
+            case .prompt(.right): self = .promptRight
+            case .prompt(.continuation): self = .promptContinuation
+            case .prompt(.secondary): self = .promptSecondary
+            case .input: self = .input
+            case .output: self = .output
+            }
+        }
+    }
+
     /// The OSC 133 role assigned to this cell, if any.
     public var semanticContent: SemanticContent {
-        switch semanticContentCode {
-        case 1: return .prompt(.initial)
-        case 2: return .prompt(.right)
-        case 3: return .prompt(.continuation)
-        case 4: return .prompt(.secondary)
-        case 5: return .input
-        case 6: return .output
-        default: return .none
-        }
+        // An out-of-range byte can only come from corrupt storage; decode it
+        // as `.none` rather than trapping.
+        (SemanticContentCode(rawValue: semanticContentCode) ?? .none).content
     }
 
     /// The color and character attributes for the cell
@@ -345,15 +377,7 @@ public struct CharData: CustomDebugStringConvertible {
     }
 
     mutating func setSemanticContent(_ content: SemanticContent) {
-        switch content {
-        case .none: semanticContentCode = 0
-        case .prompt(.initial): semanticContentCode = 1
-        case .prompt(.right): semanticContentCode = 2
-        case .prompt(.continuation): semanticContentCode = 3
-        case .prompt(.secondary): semanticContentCode = 4
-        case .input: semanticContentCode = 5
-        case .output: semanticContentCode = 6
-        }
+        semanticContentCode = SemanticContentCode(content).rawValue
     }
 
     public func getPayload () -> Any?