From ef669eeae7574335631d6897c07f60ce4015727c Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <m@mitchellh.com>
Date: Thu, 5 Mar 2026 20:46:52 -0800
Subject: [PATCH] macos: add AppleScript `split` command

Add a new `split` command to the AppleScript scripting dictionary that
splits a terminal in a given direction (right, left, down, up) and
returns the newly created terminal.

The command is exposed as:
  split terminal <terminal> direction <direction>

Also adds a `fourCharCode` String extension for converting four-character
ASCII strings to their FourCharCode (UInt32) representation.
---
 macos/Ghostty.sdef                            | 19 +++++
 macos/Ghostty.xcodeproj/project.pbxproj       |  3 +-
 .../AppleScript/ScriptSplitCommand.swift      | 74 +++++++++++++++++++
 ...iptTerminal.swift => ScriptTerminal.swift} |  5 +-
 .../Helpers/Extensions/String+Extension.swift |  9 +++
 5 files changed, 108 insertions(+), 2 deletions(-)
 create mode 100644 macos/Sources/Features/AppleScript/ScriptSplitCommand.swift
 rename macos/Sources/Features/AppleScript/{AppleScriptTerminal.swift => ScriptTerminal.swift} (90%)

diff --git a/macos/Ghostty.sdef b/macos/Ghostty.sdef
index 9ed37f764..962e1329a 100644
--- a/macos/Ghostty.sdef
+++ b/macos/Ghostty.sdef
@@ -8,6 +8,7 @@
       <responds-to command="perform action">
         <cocoa method="handlePerformActionScriptCommand:"/>
       </responds-to>
+
       <element type="terminal" access="r">
         <cocoa key="terminals"/>
       </element>
@@ -25,6 +26,24 @@
       <parameter name="on" code="GonT" type="terminal" description="Target terminal."/>
       <result type="boolean" description="True when the action was performed."/>
     </command>
+
+    <enumeration name="split direction" code="GSpD" description="Direction for a new split.">
+      <enumerator name="right" code="GSrt" description="Split to the right."/>
+      <enumerator name="left" code="GSlf" description="Split to the left."/>
+      <enumerator name="down" code="GSdn" description="Split downward."/>
+      <enumerator name="up" code="GSup" description="Split upward."/>
+    </enumeration>
+
+    <command name="split" code="GhstSplt" description="Split a terminal in the given direction.">
+      <cocoa class="GhosttyScriptSplitCommand"/>
+      <parameter name="terminal" code="GSpT" type="terminal" description="The terminal to split.">
+        <cocoa key="terminal"/>
+      </parameter>
+      <parameter name="direction" code="GSpd" type="split direction" description="The direction to split.">
+        <cocoa key="direction"/>
+      </parameter>
+      <result type="terminal" description="The newly created terminal."/>
+    </command>
   </suite>
 
   <!--
diff --git a/macos/Ghostty.xcodeproj/project.pbxproj b/macos/Ghostty.xcodeproj/project.pbxproj
index 867c52436..ce3f2edcc 100644
--- a/macos/Ghostty.xcodeproj/project.pbxproj
+++ b/macos/Ghostty.xcodeproj/project.pbxproj
@@ -137,7 +137,8 @@
 				"Features/App Intents/NewTerminalIntent.swift",
 				"Features/App Intents/QuickTerminalIntent.swift",
 				"Features/AppleScript/AppDelegate+AppleScript.swift",
-				Features/AppleScript/AppleScriptTerminal.swift,
+				Features/AppleScript/ScriptSplitCommand.swift,
+				Features/AppleScript/ScriptTerminal.swift,
 				Features/ClipboardConfirmation/ClipboardConfirmation.xib,
 				Features/ClipboardConfirmation/ClipboardConfirmationController.swift,
 				Features/ClipboardConfirmation/ClipboardConfirmationView.swift,
diff --git a/macos/Sources/Features/AppleScript/ScriptSplitCommand.swift b/macos/Sources/Features/AppleScript/ScriptSplitCommand.swift
new file mode 100644
index 000000000..6e90eda50
--- /dev/null
+++ b/macos/Sources/Features/AppleScript/ScriptSplitCommand.swift
@@ -0,0 +1,74 @@
+import AppKit
+
+/// Handler for the `split` AppleScript command defined in `Ghostty.sdef`.
+///
+/// Cocoa scripting instantiates this class because the command's `<cocoa>` element
+/// specifies `class="GhosttyScriptSplitCommand"`. The runtime calls
+/// `performDefaultImplementation()` to execute the command.
+@MainActor
+@objc(GhosttyScriptSplitCommand)
+final class ScriptSplitCommand: NSScriptCommand {
+    override func performDefaultImplementation() -> Any? {
+        guard let terminal = evaluatedArguments?["terminal"] as? ScriptTerminal else {
+            scriptErrorNumber = errAEParamMissed
+            scriptErrorString = "Missing terminal target."
+            return nil
+        }
+
+        guard let surfaceView = terminal.surfaceView else {
+            scriptErrorNumber = errAEEventFailed
+            scriptErrorString = "Terminal surface is no longer available."
+            return nil
+        }
+
+        guard let directionCode = evaluatedArguments?["direction"] as? UInt32,
+              let direction = ScriptSplitDirection(code: directionCode) else {
+            scriptErrorNumber = errAEParamMissed
+            scriptErrorString = "Missing or unknown split direction."
+            return nil
+        }
+
+        // Find the window controller that owns this surface.
+        guard let controller = surfaceView.window?.windowController as? BaseTerminalController else {
+            scriptErrorNumber = errAEEventFailed
+            scriptErrorString = "Terminal is not in a splittable window."
+            return nil
+        }
+
+        guard let newView = controller.newSplit(at: surfaceView, direction: direction.splitDirection) else {
+            scriptErrorNumber = errAEEventFailed
+            scriptErrorString = "Failed to create split."
+            return nil
+        }
+
+        return ScriptTerminal(surfaceView: newView)
+    }
+}
+
+/// Four-character codes matching the `split direction` enumeration in `Ghostty.sdef`.
+private enum ScriptSplitDirection {
+    case right
+    case left
+    case down
+    case up
+
+    init?(code: UInt32) {
+        switch code {
+        case "GSrt".fourCharCode: self = .right
+        case "GSlf".fourCharCode: self = .left
+        case "GSdn".fourCharCode: self = .down
+        case "GSup".fourCharCode: self = .up
+        default: return nil
+        }
+    }
+
+    var splitDirection: SplitTree<Ghostty.SurfaceView>.NewDirection {
+        switch self {
+        case .right: .right
+        case .left: .left
+        case .down: .down
+        case .up: .up
+        }
+    }
+}
+
diff --git a/macos/Sources/Features/AppleScript/AppleScriptTerminal.swift b/macos/Sources/Features/AppleScript/ScriptTerminal.swift
similarity index 90%
rename from macos/Sources/Features/AppleScript/AppleScriptTerminal.swift
rename to macos/Sources/Features/AppleScript/ScriptTerminal.swift
index 3f6603d0e..1e47aa7b6 100644
--- a/macos/Sources/Features/AppleScript/AppleScriptTerminal.swift
+++ b/macos/Sources/Features/AppleScript/ScriptTerminal.swift
@@ -17,7 +17,10 @@ import AppKit
 @MainActor
 @objc(GhosttyScriptTerminal)
 final class ScriptTerminal: NSObject {
-    private weak var surfaceView: Ghostty.SurfaceView?
+    /// Weak reference to the underlying surface. Package-visible so that
+    /// other AppleScript command handlers (e.g. `ScriptSplitCommand`) can
+    /// access the live surface without exposing it to ObjC/AppleScript.
+    weak var surfaceView: Ghostty.SurfaceView?
 
     init(surfaceView: Ghostty.SurfaceView) {
         self.surfaceView = surfaceView
diff --git a/macos/Sources/Helpers/Extensions/String+Extension.swift b/macos/Sources/Helpers/Extensions/String+Extension.swift
index e28877ca8..4fa61cd78 100644
--- a/macos/Sources/Helpers/Extensions/String+Extension.swift
+++ b/macos/Sources/Helpers/Extensions/String+Extension.swift
@@ -27,4 +27,13 @@ extension String {
     }
 #endif
 
+    /// Converts a four-character ASCII string to its `FourCharCode` (`UInt32`) value.
+    var fourCharCode: UInt32 {
+        assert(count <= 4, "FourCharCode string must be at most 4 characters")
+        var result: UInt32 = 0
+        for byte in utf8.prefix(4) {
+            result = (result << 8) | UInt32(byte)
+        }
+        return result
+    }
 }