initial import

Author: compnerd

.gitattributes

@@ -0,0 +1,3 @@
+*.swift text eol=lf
+*.md text eol=lf
+*.txt text eol=lf

.gitignore

@@ -0,0 +1,16 @@
+# git ls-files --others --exclude-from=.git/info/exclude
+# Lines that start with '#' are comments.
+# For a project mostly in C, the following would be a good set of
+# exclude patterns (uncomment them if you want to use them):
+
+**/.DS_Store
+.*.sw[nop]
+*~
+
+/build/
+
+/package.resolved
+/Packages/
+.build/
+
+.vscode/

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Saleem Abdulrasool
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version:6.0
+
+import PackageDescription
+
+let _: Package =
+  .init(name: "Cursor",
+        platforms: [
+          .macOS(.v14),
+        ],
+        products: [
+          .executable(name: "VTDemo", targets: ["VTDemo"]),
+        ],
+        dependencies: [
+          .package(url: "https://github.com/compnerd/swift-platform-core.git", branch: "main"),
+        ],
+        targets: [
+          .target(name: "Geometry"),
+          .target(name: "Primitives"),
+          .target(name: "VirtualTerminal", dependencies: [
+            .target(name: "Geometry"),
+            .target(name: "Primitives"),
+            .product(name: "POSIXCore", package: "swift-platform-core", condition: .when(platforms: [.macOS, .linux])),
+            .product(name: "WindowsCore", package: "swift-platform-core", condition: .when(platforms: [.windows])),
+          ]),
+          .executableTarget(name: "VTDemo", dependencies: [
+            .target(name: "VirtualTerminal"),
+          ]),
+        ])

README.md

@@ -0,0 +1,102 @@
+# VirtualTerminal
+
+**Modern, high-performance terminal UI library for Swift**
+
+Build beautiful, fast command-line applications with native Swift. VirtualTerminal provides efficient rendering, cross-platform compatibility, and Swift 6 concurrency support—without the complexity of C bindings.
+
+## Why VirtualTerminal?
+
+### 🚀 **Built for Performance**
+- **Damage-based rendering**: Only redraw changed cells, not entire screens
+- **Intelligent cursor optimization**: Minimal escape sequences for movement
+- **Double buffering**: Smooth animations without screen tearing
+- **Output batching**: Batch multiple operations into fewer writes
+
+### 🛡️ **Swift-Native Design**
+- **Memory safety**: No unsafe pointers or C interop required
+- **Modern concurrency**: Built on Swift 6 actors and async/await
+- **Type safety**: Compile-time guarantees for colors, positions, and styles
+- **Zero dependencies**: Pure Swift implementation
+
+### 🌍 **True Cross-Platform**
+- **macOS, Linux, Windows**: Single codebase, platform-optimized internals
+- **Consistent APIs**: Write once, run everywhere
+- **Native input handling**: Platform-specific optimizations under the hood
+
+## Quick Example
+
+```swift
+import VirtualTerminal
+
+// Create a high-performance terminal renderer
+let renderer = try await VTRenderer(mode: .raw)
+
+// Render at 60 FPS with automatic optimization
+try await renderer.rendering(fps: 60) { buffer in
+    buffer.write("Hello, World!", 
+                 at: VTPosition(row: 1, column: 1),
+                 style: VTStyle(foreground: .green, attributes: [.bold]))
+}
+
+// Handle input events with modern Swift concurrency
+for await event in renderer.terminal.input {
+    switch event {
+    case .key(let key) where key.character == "q":
+        return  // Clean exit
+    case .resize(let size):
+        renderer.resize(to: size)
+    default:
+        break
+    }
+}
+```
+
+## Core Features
+
+### Efficient Rendering
+- **Damage detection**: Only update changed regions
+- **Style optimization**: Minimize escape sequence overhead  
+- **Cursor movement**: Intelligent positioning algorithms
+- **Unicode support**: Proper width calculation for CJK, emoji, and symbols
+
+### Modern Input Handling
+```swift
+// AsyncSequence-based input processing
+for await event in terminal.input {
+    switch event {
+    case .key(let key):
+        handleKeyPress(key)
+    case .mouse(let mouse):
+        handleMouseEvent(mouse)
+    case .resize(let size):
+        handleResize(size)
+    }
+}
+```
+
+### Rich Styling
+```swift
+let style = VTStyle(foreground: .rgb(red: 255, green: 100, blue: 50),
+                    background: .ansi(.blue),
+                    attributes: [.bold, .italic])
+buffer.write("Styled text", at: position, style: style)
+```
+
+## Installation
+
+Add to your `Package.swift`:
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/compnerd/VirtualTerminal.git", branch: "main")
+],
+targets: [
+    .target(name: "YourCLI", dependencies: ["VirtualTerminal"])
+]
+```
+
+## Requirements
+
+- **Swift 6.0+**
+- **macOS 14+**, **Linux**, or **Windows 10+**  
+- Terminal with basic ANSI support (any modern terminal)

Sources/Geometry/Point.swift

@@ -0,0 +1,73 @@
+// Copyright © 2025 Saleem Abdulrasool <compnerd@compnerd.org>
+// SPDX-License-Identifier: BSD-3-Clause
+
+@frozen
+public struct Point {
+  public let x: Int
+  public let y: Int
+
+  public init(x: Int, y: Int) {
+    self.x = x
+    self.y = y
+  }
+}
+
+extension Point: AdditiveArithmetic {
+  public static var zero: Point {
+    Point(x: 0, y: 0)
+  }
+
+  public static func + (_ lhs: Point, _ rhs: Point) -> Point {
+    Point(x: lhs.x + rhs.x, y: lhs.y + rhs.y)
+  }
+
+  public static func - (_ lhs: Point, _ rhs: Point) -> Point {
+    Point(x: lhs.x - rhs.x, y: lhs.y - rhs.y)
+  }
+}
+
+extension Point: Codable { }
+
+extension Point: CustomStringConvertible {
+  public var description: String {
+    "(\(x), \(y))"
+  }
+}
+
+extension Point: Equatable { }
+
+extension Point: Hashable { }
+
+extension Point: Sendable { }
+
+extension Point {
+  public static func * (_ point: Point, _ scalar: Int) -> Point {
+    Point(x: point.x * scalar, y: point.y * scalar)
+  }
+}
+
+extension Point {
+  public static func / (_ point: Point, _ scalar: Int) -> Point {
+    return Point(x: point.x / scalar, y: point.y / scalar)
+  }
+}
+
+extension Point {
+  public func distance(to point: Point) -> Double {
+    let dx = self.x - point.x
+    let dy = self.y - point.y
+    return Double(dx * dx + dy * dy).squareRoot()
+  }
+}
+
+extension Point {
+  public var magnitude: Double {
+    distance(to: .zero)
+  }
+}
+
+extension Point {
+  public func midpoint(to point: Point) -> Point {
+    return Point(x: (self.x + point.x) / 2, y: (self.y + point.y) / 2)
+  }
+}

Sources/Geometry/Rect.swift

@@ -0,0 +1,107 @@
+// Copyright © 2025 Saleem Abdulrasool <compnerd@compnerd.org>
+// SPDX-License-Identifier: BSD-3-Clause
+
+@frozen
+public struct Rect {
+  public let origin: Point
+  public let size: Size
+
+  public init(origin: Point, size: Size) {
+    self.origin = origin
+    self.size = size
+  }
+}
+
+extension Rect: AdditiveArithmetic {
+  public static var zero: Rect {
+    Rect(origin: .zero, size: .zero)
+  }
+
+  public static func + (_ lhs: Rect, _ rhs: Rect) -> Rect {
+    Rect(origin: lhs.origin + rhs.origin, size: lhs.size + rhs.size)
+  }
+
+  public static func - (_ lhs: Rect, _ rhs: Rect) -> Rect {
+    Rect(origin: lhs.origin - rhs.origin, size: lhs.size - rhs.size)
+  }
+}
+
+extension Rect: Codable { }
+
+extension Rect: CustomStringConvertible {
+  public var description: String {
+    "{\(origin), \(size)}"
+  }
+}
+
+extension Rect: Equatable { }
+
+extension Rect: Hashable { }
+
+extension Rect: Sendable { }
+
+extension Rect {
+  public var isEmpty: Bool {
+    size.width <= 0 || size.height <= 0
+  }
+}
+
+extension Rect {
+  public var center: Point {
+    Point(x: origin.x + size.width / 2, y: origin.y + size.height / 2)
+  }
+}
+
+extension Rect {
+  public func contains(_ point: Point) -> Bool {
+    return point.x >= origin.x && point.x < (origin.x + size.width) &&
+           point.y >= origin.y && point.y < (origin.y + size.height)
+  }
+
+  public func contains(_ rect: Rect) -> Bool {
+    return rect.origin.x >= origin.x &&
+           (rect.origin.x + rect.size.width) <= (origin.x + size.width) &&
+           rect.origin.y >= origin.y &&
+           (rect.origin.y + rect.size.height) <= (origin.y + size.height)
+  }
+}
+
+extension Rect {
+  public func intersects(_ rect: Rect) -> Bool {
+    return (origin.x + size.width) > rect.origin.x &&
+           origin.x < (rect.origin.x + rect.size.width) &&
+           (origin.y + size.height) > rect.origin.y &&
+           origin.y < (rect.origin.y + rect.size.height)
+  }
+}
+
+extension Rect {
+  public func union(_ rect: Rect) -> Rect {
+    let x = (min: min(origin.x, rect.origin.x), 
+             max: max(origin.x + size.width, rect.origin.x + rect.size.width))
+    let y = (min: min(origin.y, rect.origin.y),
+             max: max(origin.y + size.height, rect.origin.y + rect.size.height))
+
+    return Rect(origin: Point(x: x.min, y: y.min),
+                size: Size(width: x.max - x.min, height: y.max - y.min))
+  }
+}
+
+extension Rect {
+  public func intersection(with rect: Rect) -> Rect? {
+    let x = (min: max(origin.x, rect.origin.x),
+             max: min(origin.x + size.width, rect.origin.x + rect.size.width))
+    let y = (min: max(origin.y, rect.origin.y),
+             max: min(origin.y + size.height, rect.origin.y + rect.size.height))
+
+    guard x.min < x.max, y.min < y.max else { return nil }
+    return Rect(origin: Point(x: x.min, y: y.min),
+                size: Size(width: x.max - x.min, height: y.max - y.min))
+  }
+}
+
+extension Rect {
+  public func offset(by point: Point) -> Rect {
+    return Rect(origin: origin + point, size: size)
+  }
+}