Merge pull request #113 from royalapplications/agent/ghostty-latest-api-integration

Update Ghostty integration to latest libghostty-vt API

Author: wieslawsoltes

.github/workflows/ci.yml

@@ -142,7 +142,7 @@ jobs:
 
   native-build-macos:
     name: Native Build (macOS)
-    # Zig 0.15.2 fails to link the build runner on macos-26-arm64.
+    # Pin macOS 15 for reproducible SDK compatibility with the native artifacts.
     runs-on: macos-15
     strategy:
       matrix:
@@ -156,16 +156,16 @@ jobs:
       - name: Setup Zig
         uses: mlugg/setup-zig@v2
         with:
-          version: 0.15.2
+          version: 0.16.0
           cache-key: ${{ matrix.arch }}
 
       - name: Build libghostty-vt
         working-directory: external/ghostty
         run: |
           if [ "${{ matrix.arch }}" = "arm64" ]; then
-            zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-xcframework=false -Demit-macos-app=false
+            zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-lib-vt=true -Demit-xcframework=false -Demit-macos-app=false
           else
-            zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-xcframework=false -Demit-macos-app=false -Dtarget=x86_64-macos
+            zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-lib-vt=true -Demit-xcframework=false -Demit-macos-app=false -Dtarget=x86_64-macos
           fi
 
       - name: Build ghostty-renderer-capi
@@ -251,7 +251,7 @@ jobs:
       - name: Setup Zig
         uses: mlugg/setup-zig@v2
         with:
-          version: 0.15.2
+          version: 0.16.0
           cache-key: ${{ matrix.arch }}
 
       - name: Build libghostty-vt
@@ -265,6 +265,7 @@ jobs:
             build
             -Doptimize=ReleaseFast
             -Dapp-runtime=none
+            -Demit-lib-vt=true
             -Dtarget=${{ matrix.zig-target }}
             -Dsimd=false
           )
@@ -328,26 +329,30 @@ jobs:
       - name: Setup Zig
         uses: mlugg/setup-zig@v2
         with:
-          version: 0.15.2
+          version: 0.16.0
           cache-key: ${{ matrix.arch }}
 
       - name: Build libghostty-vt
         working-directory: external/ghostty
         shell: bash
         run: |
           target=""
+          simd=""
           if [ "${{ matrix.arch }}" = "arm64" ]; then
-            target="-Dtarget=aarch64-windows"
+            target="-Dtarget=aarch64-windows-gnu"
+            # Zig 0.16.0's Windows ARM64 stdlib stack-trace code fails to
+            # compile when Ghostty's vendored SIMD archive is enabled.
+            simd="-Dsimd=false"
           fi
-          zig build -Doptimize=ReleaseFast -Dapp-runtime=none ${target}
+          zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-lib-vt=true ${target} ${simd}
 
       - name: Build ghostty-renderer-capi
         working-directory: native/ghostty-renderer-capi
         shell: bash
         run: |
           target=""
           if [ "${{ matrix.arch }}" = "arm64" ]; then
-            target="-Dtarget=aarch64-windows"
+            target="-Dtarget=aarch64-windows-gnu"
           fi
           zig build -Doptimize=ReleaseFast ${target}
 

.github/workflows/release.yml

@@ -23,7 +23,7 @@ jobs:
 
   native-macos:
     name: Native (macOS ${{ matrix.arch }})
-    # Zig 0.15.2 fails to link the build runner on macos-26-arm64.
+    # Pin macOS 15 for reproducible SDK compatibility with the native artifacts.
     runs-on: macos-15
     strategy:
       matrix:
@@ -37,15 +37,15 @@ jobs:
       - name: Setup Zig
         uses: mlugg/setup-zig@v2
         with:
-          version: 0.15.2
+          version: 0.16.0
 
       - name: Build libghostty-vt
         working-directory: external/ghostty
         run: |
           if [ "${{ matrix.arch }}" = "arm64" ]; then
-            zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-xcframework=false -Demit-macos-app=false
+            zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-lib-vt=true -Demit-xcframework=false -Demit-macos-app=false
           else
-            zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-xcframework=false -Demit-macos-app=false -Dtarget=x86_64-macos
+            zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-lib-vt=true -Demit-xcframework=false -Demit-macos-app=false -Dtarget=x86_64-macos
           fi
 
       - name: Build ghostty-renderer-capi
@@ -129,7 +129,7 @@ jobs:
       - name: Setup Zig
         uses: mlugg/setup-zig@v2
         with:
-          version: 0.15.2
+          version: 0.16.0
 
       - name: Build libghostty-vt
         working-directory: external/ghostty
@@ -142,6 +142,7 @@ jobs:
             build
             -Doptimize=ReleaseFast
             -Dapp-runtime=none
+            -Demit-lib-vt=true
             -Dtarget=${{ matrix.zig-target }}
             -Dsimd=false
           )
@@ -203,7 +204,7 @@ jobs:
       - name: Setup Zig
         uses: mlugg/setup-zig@v2
         with:
-          version: 0.15.2
+          version: 0.16.0
 
       - name: Build libghostty-vt
         working-directory: external/ghostty
@@ -212,7 +213,10 @@ jobs:
           cpu=""
           simd=""
           if [ "${{ matrix.arch }}" = "arm64" ]; then
-            target="-Dtarget=aarch64-windows-msvc"
+            target="-Dtarget=aarch64-windows-gnu"
+            # Zig 0.16.0's Windows ARM64 stdlib stack-trace code fails to
+            # compile when Ghostty's vendored SIMD archive is enabled.
+            simd="-Dsimd=false"
           else
             # Keep win-x64 release artifacts on a true baseline x64 CPU model.
             # x86_64-windows-msvc alone still allows LLVM/third-party SIMD code
@@ -223,15 +227,15 @@ jobs:
             cpu="-Dcpu=x86_64-vzeroupper"
             simd="-Dsimd=false"
           fi
-          zig build -Doptimize=ReleaseFast -Dapp-runtime=none ${target} ${cpu} ${simd}
+          zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-lib-vt=true ${target} ${cpu} ${simd}
 
       - name: Build ghostty-renderer-capi
         working-directory: native/ghostty-renderer-capi
         shell: bash
         run: |
           cpu=""
           if [ "${{ matrix.arch }}" = "arm64" ]; then
-            target="-Dtarget=aarch64-windows-msvc"
+            target="-Dtarget=aarch64-windows-gnu"
           else
             target="-Dtarget=x86_64-windows-msvc"
             cpu="-Dcpu=x86_64-vzeroupper"

Directory.Build.props

@@ -8,8 +8,8 @@
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
     <AnalysisLevel>latest</AnalysisLevel>
-    <VersionPrefix>0.4.1</VersionPrefix>
-    <VersionSuffix></VersionSuffix>
+    <VersionPrefix>0.5.0</VersionPrefix>
+    <VersionSuffix>preview.1</VersionSuffix>
     <RoyalTerminalEnablePretextTextPipeline Condition="'$(RoyalTerminalEnablePretextTextPipeline)' == ''">true</RoyalTerminalEnablePretextTextPipeline>
     <DefineConstants Condition="'$(RoyalTerminalEnablePretextTextPipeline)' == 'true'">$(DefineConstants);ROYALTERMINAL_PRETEXT_TEXT_PIPELINE</DefineConstants>
   </PropertyGroup>

README.md

@@ -1157,7 +1157,7 @@ Build directly:
 
 ```bash
 cd external/ghostty
-zig build -Doptimize=ReleaseFast -Dapp-runtime=none
+zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-lib-vt=true
 ```
 
 For distributable Windows x64 artifacts, build a scalar compatibility DLL with
@@ -1167,7 +1167,7 @@ older CPUs, constrained VMs, and Windows ARM64 x64 emulation:
 ```powershell
 .\scripts\build-native.ps1 -Arch x64 -Release
 # or, from external/ghostty:
-zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Dtarget=x86_64-windows-msvc -Dcpu=x86_64-vzeroupper -Dsimd=false
+zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-lib-vt=true -Dtarget=x86_64-windows-msvc -Dcpu=x86_64-vzeroupper -Dsimd=false
 ```
 
 CI verifies the Windows x64 native artifacts with `scripts/verify-windows-x64-no-avx.ps1`.
@@ -1281,7 +1281,7 @@ RoyalTerminal/
 ### Prerequisites
 
 - .NET 10 SDK
-- Zig 0.15.2+
+- Zig 0.16.0
 - Ghostty submodule:
 
 ```bash

docs/articles/build-test-release.md

@@ -11,7 +11,7 @@ RoyalTerminal combines managed .NET packages with native artifacts. A successful
 Minimum toolchain:
 
 - .NET 10 SDK
-- Zig 0.15.2 or newer
+- Zig 0.16.0
 - initialized git submodules for native builds
 
 Common optional requirements:

docs/articles/ghostty-integration.md

@@ -46,6 +46,11 @@ If you want Ghostty behavior inside RoyalTerminal, you usually begin with the ma
 | `GhosttyMouseEvent` | Mutable mouse event payload. |
 | `GhosttyPaste` | Static helper for paste encoding. |
 | `GhosttySelection` | Managed selection value used by formatters and helpers. |
+| `GhosttySelectionGesture` | Owned state machine for native text-selection gestures. |
+| `GhosttySelectionGestureEvent` | Reusable selection pointer/click event. |
+| `GhosttyTrackedGridReference` | Owned reference that follows a cell through scroll, pruning, and reflow. |
+| `GhosttyColorUtilities` | Native-backed color parsing, palettes, color math, X11 names, and color-scheme reports. |
+| `GhosttyUnicode` | Ghostty-exact codepoint and grapheme width helpers. |
 | `GhosttyKittyGraphics` | Managed helper for Kitty graphics extraction. |
 | `GhosttyKittyGraphicsImage` | Managed Kitty image snapshot. |
 | `GhosttyKittyGraphicsPlacementIterator` | Managed iterator over Kitty placements. |
@@ -59,10 +64,30 @@ If you want Ghostty behavior inside RoyalTerminal, you usually begin with the ma
 
 These are the types used by RoyalTerminal itself when it wants native VT behavior without forcing consumers to work directly against raw pointers and C structs.
 
+## Engine-neutral effects and Unicode
+
+Hosts that can use either VT engine should query the terminal contracts instead
+of depending directly on Ghostty types:
+
+| Contract | Capability |
+| --- | --- |
+| `ITerminalEffectSource` | Clipboard writes, desktop notifications, progress reports, and working-directory changes. |
+| `ITerminalUnicodeWidthProvider` | Codepoint width and first-grapheme width using the active engine's rules. |
+
+`GhosttyVtProcessor` implements these contracts with the normalized
+libghostty callbacks and Ghostty Unicode tables. `BasicVtProcessor` implements
+the same contracts with managed OSC parsing and RoyalTerminal Unicode tables.
+The effect callbacks are policy boundaries: applications still decide whether
+clipboard writes and desktop notifications are allowed.
+
 ## The raw VT mirror is also public
 
 Under those wrappers, `GhosttyVtNative` exposes the Ghostty VT ABI directly. This is not the right layer for most applications, but it is the right layer for advanced interop, diagnostics, or custom wrappers.
 
+At the current Ghostty revision, `TerminalNew` takes `columns` and `rows`
+directly. Configure the returned terminal through `TerminalSet`; the former
+`GhosttyTerminalOptions` constructor struct no longer exists.
+
 ### Root VT exports
 
 `GhosttyVtNative`, `GhosttyResult`, `GhosttyVtKeyAction`, `GhosttyVtKey`, `GhosttyVtMods`, `GhosttyOscCommandType`, `GhosttyOscCommandData`, `GhosttySgrAttributeTag`, `GhosttySgrUnderline`, `GhosttySgrUnknown`, `GhosttySgrAttributeValue`, `GhosttySgrAttribute`, `GhosttyColorRgb`
@@ -85,15 +110,15 @@ Under those wrappers, `GhosttyVtNative` exposes the Ghostty VT ABI directly. Thi
 
 ### Render-state exports
 
-`GhosttyRenderStateDirty`, `GhosttyRenderStateCursorVisualStyle`, `GhosttyRenderStateData`, `GhosttyRenderStateOption`, `GhosttyRenderStateRowData`, `GhosttyRenderStateRowOption`, `GhosttyRenderStateRowCellsData`, `GhosttyRenderStateColors`
+`GhosttyRenderStateDirty`, `GhosttyRenderStateCursorVisualStyle`, `GhosttyRenderStateData`, `GhosttyRenderStateOption`, `GhosttyRenderStateRowData`, `GhosttyRenderStateRowOption`, `GhosttyRenderStateRowCellsData`, `GhosttyRenderStateColors`, `GhosttyRenderStateRowSelection`, `GhosttyBuffer`
 
 ### Screen exports
 
 `GhosttyStyleColorTag`, `GhosttyStyleColorValue`, `GhosttyStyleColor`, `GhosttyStyle`, `GhosttyGridRef`, `GhosttyCellContentTag`, `GhosttyCellWide`, `GhosttyCellSemanticContent`, `GhosttyCellData`, `GhosttyRowSemanticPrompt`, `GhosttyRowData`
 
 ### Selection, system, and terminal exports
 
-`GhosttySelectionRange`, `GhosttyAllocatorVtable`, `GhosttyAllocator`, `GhosttySysImage`, `GhosttySysDecodePngCallback`, `GhosttySysOption`, `GhosttyTerminalOptions`, `GhosttyTerminalScrollViewportTag`, `GhosttyTerminalScrollViewportValue`, `GhosttyTerminalScrollViewport`, `GhosttyTerminalScreen`, `GhosttyTerminalScrollbar`, `GhosttyTerminalBellCallback`, `GhosttyTerminalWritePtyCallback`, `GhosttyTerminalTitleChangedCallback`, `GhosttyTerminalEnquiryCallback`, `GhosttyTerminalXtversionCallback`, `GhosttyTerminalSizeCallback`, `GhosttyTerminalColorSchemeCallback`, `GhosttyTerminalDeviceAttributesCallback`, `GhosttyTerminalOption`, `GhosttyTerminalData`
+`GhosttySelectionRange`, `GhosttySelectionOrder`, `GhosttySelectionAdjust`, `GhosttySelectionGestureBehavior`, `GhosttySelectionGestureBehaviors`, `GhosttySelectionGestureGeometry`, `GhosttySelectionGestureAutoscroll`, `GhosttySelectionGestureData`, `GhosttySelectionGestureEventType`, `GhosttySelectionGestureEventOption`, `GhosttyAllocatorVtable`, `GhosttyAllocator`, `GhosttySysImage`, `GhosttySysDecodePngCallback`, `GhosttySysOption`, `GhosttyTerminalScrollViewportTag`, `GhosttyTerminalScrollViewportValue`, `GhosttyTerminalScrollViewport`, `GhosttyTerminalCompressionMode`, `GhosttyTerminalCompressionResult`, `GhosttyTerminalScreen`, `GhosttyTerminalScrollbar`, `GhosttyTerminalBellCallback`, `GhosttyTerminalWritePtyCallback`, `GhosttyTerminalTitleChangedCallback`, `GhosttyTerminalEnquiryCallback`, `GhosttyTerminalXtversionCallback`, `GhosttyTerminalSizeCallback`, `GhosttyTerminalColorSchemeCallback`, `GhosttyTerminalDeviceAttributesCallback`, `GhosttyTerminalPwdChangedCallback`, `GhosttyTerminalClipboardWriteCallback`, `GhosttyTerminalDesktopNotificationCallback`, `GhosttyTerminalProgressReportCallback`, `GhosttyTerminalOption`, `GhosttyTerminalData`
 
 ## Runtime enums, structs, and callbacks
 

docs/articles/windows-x64-native-compatibility.md

@@ -70,7 +70,7 @@ Build the Windows x64 native artifacts:
 Direct Ghostty build from `external/ghostty`:
 
 ```powershell
-zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Dtarget=x86_64-windows-msvc -Dcpu=x86_64-vzeroupper -Dsimd=false
+zig build -Doptimize=ReleaseFast -Dapp-runtime=none -Demit-lib-vt=true -Dtarget=x86_64-windows-msvc -Dcpu=x86_64-vzeroupper -Dsimd=false
 ```
 
 Verify a DLL with disassembly:

external/ghostty

@@ -8,10 +8,10 @@ const std = @import("std");
 
 fn linkAppleObjc(step: *std.Build.Step.Compile) void {
     // Add common SDK library locations so cross-target macOS builds can resolve libobjc.
-    step.addLibraryPath(.{ .cwd_relative = "/usr/lib" });
-    step.addLibraryPath(.{ .cwd_relative = "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib" });
-    step.addLibraryPath(.{ .cwd_relative = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/lib" });
-    step.linkSystemLibrary("objc");
+    step.root_module.addLibraryPath(.{ .cwd_relative = "/usr/lib" });
+    step.root_module.addLibraryPath(.{ .cwd_relative = "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib" });
+    step.root_module.addLibraryPath(.{ .cwd_relative = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/lib" });
+    step.root_module.linkSystemLibrary("objc", .{});
 }
 
 pub fn build(b: *std.Build) void {
@@ -30,10 +30,10 @@ pub fn build(b: *std.Build) void {
             .root_source_file = b.path("src/main.zig"),
             .target = target,
             .optimize = optimize,
+            .link_libc = true,
         }),
         .version = .{ .major = 0, .minor = 1, .patch = 0 },
     });
-    lib.linkLibC();
 
     if (target.result.os.tag == .macos) {
         linkAppleObjc(lib);
@@ -49,9 +49,9 @@ pub fn build(b: *std.Build) void {
             .root_source_file = b.path("src/main.zig"),
             .target = target,
             .optimize = optimize,
+            .link_libc = true,
         }),
     });
-    static_lib.linkLibC();
 
     if (target.result.os.tag == .macos) {
         linkAppleObjc(static_lib);
@@ -65,9 +65,9 @@ pub fn build(b: *std.Build) void {
             .root_source_file = b.path("src/main.zig"),
             .target = target,
             .optimize = optimize,
+            .link_libc = true,
         }),
     });
-    tests.linkLibC();
 
     if (target.result.os.tag == .macos) {
         linkAppleObjc(tests);
@@ -82,16 +82,16 @@ pub fn build(b: *std.Build) void {
             .root_source_file = b.path("samples/metal_texture_smoke.zig"),
             .target = target,
             .optimize = optimize,
+            .link_libc = true,
             .imports = &.{
                 .{ .name = "renderer_capi", .module = renderer_module },
             },
         }),
     });
-    sample.linkLibC();
 
     if (target.result.os.tag == .macos) {
         linkAppleObjc(sample);
-        sample.linkFramework("Metal");
+        sample.root_module.linkFramework("Metal", .{});
     }
 
     const sample_install = b.addInstallArtifact(sample, .{});

native/ghostty-renderer-capi/build.zig

@@ -3,5 +3,5 @@
     .version = "0.1.5",
     .paths = .{""},
     .fingerprint = 0x227859aca4c0de44,
-    .minimum_zig_version = "0.15.2",
+    .minimum_zig_version = "0.16.0",
 }