Swap out the hash map backed by an arena with a fixed array.
Measurements from poop:
CPU Cycles: 173M → 171M (−1.2%)
Instructions: 519M → 517M (−0.5%)
Peak RSS: 11.9 → 11.8 MB
Cache misses: 356K → 312K (−12.4%)
Graphics commands prev. stored parsed control fields in a hash map
backed that used an arena.
This added hashing and allocation to every command even though protocol
keys are single ASCII letters.
Store letter keys in a fixed array with a presence bitmap and remove the
now-unnecessary arena. Unknown non-letter keys remain ignored and are
covered by a regression test.
#13319#13748
Normalize command-line file arguments as file URLs internally while
keeping the AppKit and FileManager string boundaries unchanged.
This handles relative paths, URL-sensitive characters, and trailing
directory separators consistently when matching duplicate open-file
events.
Fixes#13319
AppKit treats existing positional arguments as documents, causing paths
passed to a child command after -e to open an extra terminal surface.
We now process args ourselves during openFile callbacks to ignore file
paths after `-e`. There isn't a way to avoid this I can find because
AppKit processes argc/argv from the main entrypoint and that can't be
overridden.
Fixes#13319
AppKit treats existing positional arguments as documents, causing paths
passed to a child command after -e to open an extra terminal surface.
We now process args ourselves during openFile callbacks to ignore
file paths after `-e`. There isn't a way to avoid this I can find
because AppKit processes argc/argv from the main entrypoint and that
can't be overridden.
Fixes#10077
Clipboard read confirmations would immediately show a sheet which
grabbed focus. This could be used for a bunch of dumb reasons, including
DoS attacks. But, it also caused focus/sheet loops for programs that did
OSC52 on focus changes (which was seen via some Neovim configs!).
Now, if a surface is unfocused, we bell the surface and show the
confirmation request on next focus. If the surface is not focused or
another request comes in, we cancel the prior one.
This also fixes some memory management issues around clipboard requests
that were likely small leaks (didn't verify the old bug, but verified
the new code, and eyeballed the old).
To implement this, I decided to reorient the whole clipboard
confirmation thing around state on SurfaceView (which simplifies memory
management) and using Combine on BaseTerminalController to get notified.
Fixes#10077
Clipboard read confirmations would immediately show a sheet which
grabbed focus. This could be used for a bunch of dumb reasons, including
DoS attacks. But, it also caused focus/sheet loops for programs that did
OSC52 on focus changes (which was seen via some Neovim configs!).
Now, if a surface is unfocused, we bell the surface and show the confirmation
request on next focus. If the surface is not focused or another request
comes in, we cancel the prior one.
This also fixes some memory management issues around clipboard requests
that were likely small leaks (didn't verify the old bug, but verified
the new code, and eyeballed the old).
`needleSelection` was introduced in #12712 to select all texts when
syncing pasteboard, the crash happens most on macOS 15 in
`readPasteboardNeedle`. It seems that `objectWillChange` fires
differently there, and it's hard to reproduce on macOS 26/27. I think
guaranteeing from ourside is enough, I believe SwiftUI already as its
own when updating the binding.
**Confirmed with a simple example on macOS 15, it seems a SwiftUI
issue. So I changed the minimal macOS version for text selection to
macOS 26. I don't see an elegant way to fix it.**
<img width="1352" height="849" alt="image"
src="https://github.com/user-attachments/assets/1dfef3f5-ceaa-41dd-bb91-c23dbc5e4ad3"
/>
```swift
struct ContentView: View {
@State private var text = ""
@State private var selection: TextSelection?
var body: some View {
TextField("Search", text: $text, selection: $selection)
}
}
```
This adds some better handling of existing paths when editing
configuration files:
* If we've found an existing file we just skip any attempts to create
files/dirs, and just return the path.
* If the path (including file) does not exist, we check to see if the
directory exists first (possibly following symlinks). Directory creation
happens normally after this (note that any intermediary symlinks in this
process will still cause the process to fail, this is to prevent
infinite loops, as per the comments in
std.Io.Threaded.dirCreateDirPath).
This adds some better handling of existing paths when editing
configuration files:
* If we've found an existing file we just skip any attempts to create
files/dirs, and just return the path.
* If the path (including file) does not exist, we check to see if the
directory exists first (possibly following symlinks). Directory
creation happens normally after this (note that any intermediary
symlinks in this process will still cause the process to fail, this is
to prevent infinite loops, as per the comments in
std.Io.Threaded.dirCreateDirPath).
Fixes#13713.
`WeakRef(T)` offers `set` and `get`, so releasing one is spelled
`set(null)` — indistinguishable from an ordinary assignment. The
requirement that it *must* happen before the owning memory is freed
lives in a comment in `class/inspector_window.zig`, which is not where
somebody using the type is looking.
This adds `deinit`, forwarding to `g_weak_ref_clear` — the call GLib
documents for a `GWeakRef` that is going away — and switches the
dispose-time clears to it.
### What changed
- `weak_ref.zig`: new `deinit`, with the reasoning in its doc comment.
- `window.zig`, `split_tree.zig`, `application.zig`,
`command_palette.zig`: the four dispose-time clears now call `deinit`.
`set(null)` is unchanged and still valid. The clear in
`Application.handleReloadConfig` deliberately stays a `set(null)`: the
object is alive there and the reference is reused, so it is a logical
clear rather than teardown — which is the distinction the new name is
meant to make visible.
### Why it is worth a method
Zig has no destructors, so this enforces nothing; it is documentation
that happens to be executable. The concrete case is in #13713: I added a
`WeakRef(Window)` in a downstream branch, did not clear it, and closing
a window that had shown that dialog deadlocked the GTK main loop inside
`weak_ref_data_clear_list` locking freed memory. Every upstream call
site already gets this right — the point is only to put the rule where
the next person will see it.
### Testing
`zig build test` passes. `zig fmt --check` clean. Built and used on
Linux/GTK; the change is behaviourally identical to what was there,
since `g_weak_ref_clear` and `g_weak_ref_set(NULL)` both unregister.
---
**AI disclosure per `AI_POLICY.md`:** I investigated the underlying
incident with Claude Code and it drafted this change; I reviewed it.
This PR extends the `open_config` keybind action to allow editing the
Ghostty config in a new Ghostty window using the editor configured in
`$EDITOR` or `$VISUAL`.
In debug builds the DebugAllocator throws an error about leaked memory
when you close Ghostty, if you have global keybinds in your config with
a Wayland compositor that supports the vicinae-hotkey protocol. The
cause is the `Hotkeys.entries` array list never actually being freed.
Not really a problem because the list should be kept around until app
teardown anyway, but not getting an error every time would be nice (even
if you need a somewhat specific setup for this to even happen right
now).
To fix this free the array list memory in Hotkeys.deinit with
`ArrayList.clearAndFree`. As the existing comment on `deinit` already
mentions, we can't use `ArrayList.deinit` because it leaves the list in
an invalid state and `Hotkeys.clear` might still get called and use it.
This PR extends the `open_config` keybind action to allow editing the
Ghostty config in a new Ghostty window using the editor configured in
`$EDITOR` or `$VISUAL`.
A GWeakRef must be released before the memory holding it is freed: the
target keeps a pointer to the GWeakRef so it can clear it at finalize,
and if that memory is gone by then the target walks into whatever now
occupies it. inspector_window.zig already carries this warning, and
every call site follows it — but the rule lives in a comment in one
file, while the type itself offers only set and get, so releasing one
looks like an ordinary assignment.
Give it a name. deinit forwards to g_weak_ref_clear, which is the call
GLib documents for a GWeakRef that is going away, and the dispose-time
clears now use it. set(null) still works and is unchanged; the clear in
handleReloadConfig stays a set(null) because the object is still alive
there and the reference is reused.
Zig has no destructors so this enforces nothing. It puts the
requirement on the type someone is already looking at.
Its moniker has been `libghostty-internal` for *quite* a while now among
maintainers but that has never really been clarified for the public aside
from a couple comments on discussions. Judging by how many people still
try to vibe their way into making this work for their purposes, I think
we should clear this up once and for all.
Fixes#13719
The Kitty graphics protocol requires retransmitting data for a specific
image ID to delete the previous image and all of its placements.
Ghostty instead preserved the placement count and map when replacing
image data. Repeated `a=T` commands therefore added one anonymous
placement per frame and retained its tracked pin.
Spec:
https://sw.kovidgoyal.net/kitty/graphics-protocol/#display-images-on-screen
Fixes#13719
The Kitty graphics protocol requires retransmitting data for a
specific image ID to delete the previous image and all of its
placements.
Ghostty instead preserved the placement count and map when replacing image
data. Repeated `a=T` commands therefore added one anonymous placement per
frame and retained its tracked pin.
Spec: https://sw.kovidgoyal.net/kitty/graphics-protocol/#display-images-on-screen
Startup optimizations for macOS! Highlights:
* Process exec to visible window: **15% reduction, ~193ms to ~165ms.**
* Time to first rendered frame: **27% reduction, ~126ms to ~92ms.**
* Zig startup time goes from **20ms to ~5ms**, the remainder is
AppKit/Swift stuff.
> [!NOTE]
>
> "Time to first rendered frame?" I measured the time between global
init start to the first Metal callback saying that a frame was
completed/drawn. This is faster than when it is _presented_ because we
can create an IOSurfaceLayer and draw to it before AppKit finishes its
startup and shows the window. But, the good news is this means that when
the window is shown, the frame is already drawn!
See individual commits for speeds, but a summary below:
1. **Resolve Sentry directories on the init thread, not startup thread
(~3-4ms).** Sentry init already ran on a thread, but directory
resolution happened on the main thread first, and on macOS that calls
`NSFileManager URLForDirectory:` which is slow as shit.
2. **Initialize the TIS keymap lazily (~7ms).** The keymap is only
needed once keyboard events flow. If AppKit isn't warmed up, this is
SLOW. Defer setup until its needed.
3. **Warm up the font registry and Metal on background threads (~7ms+
off the first surface).** The first CoreText query initializes the
system font database (~7ms) and the first Metal device/queue/pipeline
use pays framework init and shader compilation costs. `App.create` now
spawns a detached warmup thread per subsystem so this overlaps config
load, AppKit launch, and window creation. First font grid init went from
~4.5ms to ~1.1ms, renderer init from ~6.8ms to ~1.5ms.
4. **Look up Apple Color Emoji by exact name.** We know exactly which
font we want, so skip the system-wide `CTFontCollection` matching
(~312us to ~13us).
5. **Cache unified logging loggers per scope.** We created and released
an `os_log_t` on every log call. I actually had a comment saying this is
slow but probably won't matter. Well, we log a lot on startup, and this
actually mattered.
## Warmup Threads
As a note, some of the biggest speedups are by using "warmup" threads.
These are one-time launched threads on system start that basically just
"touch" the relevant frameworks (CoreText/Metal). The initial touching
of these frameworks has a ton of cost associated with them (and they're
thread-safe), so we can shave off a bunch of time by just touching them
in the background.
This sets up a race between our own startup needing it and these warmup
threads, but in every case I measured, the warmup threads win.
## Linux
All the optimizations here focused really on slow macOS APIs. I plan on
measuring on Linux, but nothing here should slow it down.
**AI usage:** Fable was used for this one to find the issues, help
perform the measurements, and draft commit messages by splitting up my
work. I wrote the code, then edited the commit messages. This PR message
is fully hand-written.
windowDidLoad undoes macOS automatic window tabbing by inspecting
window.tabGroup. Accessing tabGroup on a fresh window materializes
AppKit's tab group machinery, which takes ~15-20ms and is on the
critical path of every window creation, including the first window at
app launch.
AppKit only auto-tabs a fresh window when the system tabbing
preference is "always": the tab bar "+" button goes through
newWindowForTab which we intercept and route through our own tab
logic, so it never auto-tabs. Guard the check on
NSWindow.userTabbingPreference == .always so everyone else skips the
tab group materialization entirely.
Measured on macOS (Apple Silicon) during app launch via the startup
timeline instrumentation:
windowDidLoad tab group check: 17.8ms -> ~0ms
main() -> window visible: median ~173ms -> ~165ms (n=7)
Measured on macOS (Apple Silicon) during app launch, via a startup
timeline instrumented across the Swift app and libghostty:
config apply, errors step: 35.5ms -> 0.1ms
main() -> first frame rendered: ~126ms -> ~93ms
main() -> window visible: ~193ms -> ~173ms
The embedded apprt App init created the keyboard layout keymap
eagerly, which requires talking to the text input system (TIS). The
first TIS call in a process is slow: 6.6ms measured inside
ghostty_app_new during app launch (up to ~30ms in a cold process).
The keymap is only used for keyboard layout queries (option-as-alt
detection, layout change reload), which happen once keyboard events
are flowing. By then AppKit has already warmed TIS and the call is
effectively free (~0.2us measured warm). So initialize the keymap
lazily on first use. If the layout changes before the keymap was ever
created, reload is a no-op since lazy init picks up the current
layout.
Measured on macOS (Apple Silicon) with local timing instrumentation
during app launch:
embedded app init before: ~6.7ms (keymap 6614us)
embedded app init after: ~60us (config clone only)
Extend the Metal portion of the startup warmup thread to also create
(and discard) a command queue and build (and discard) the shader
pipelines for both pixel formats we may use (which one is used
depends on the blending config). The first command queue for a device
and the first render pipeline state creations pay one-time driver
setup and shader compilation costs; once warm, the real creations
during surface initialization hit driver and OS caches.
Measured on macOS (Apple Silicon) with local timing instrumentation
during app launch, first surface renderer initialization:
queue creation: 717us -> 93us
pipeline builds: 1023us -> 347us
renderer init total: 2777us -> 1466us
The first Metal device query in a process (MTLCopyAllDevices) takes
multiple milliseconds; once the framework is warm, subsequent queries
are effectively free (measured ~15ms cold, ~1us warm in isolation).
This cost was paid during the first surface's renderer
initialization, on the critical path to the first window.
Measured on macOS (Apple Silicon) with local timing instrumentation
during app launch, first surface renderer initialization:
GraphicsAPI.init before: 4227us (device query ~3.5ms)
GraphicsAPI.init after: ~900us (device query 20-25us)
The first CoreText font query in a process initializes the system
font database, which takes multiple milliseconds (~7ms measured in an
isolated process; 2-4ms observed inside Ghostty startup). This cost
was previously paid during the first surface's font grid
initialization, on the critical path to the first window.
App.create can now spawn a background thread that performs the warmup.
The Apple Color Emoji fallback font was discovered with the generic
discovery path, which builds a CTFontCollection and runs system-wide
font matching. Since we know the exact font we want, we can look it
up directly with CTFontCreateWithName instead.
The logFn for macOS unified logging created and released an os_log_t
logger on every single log call. Loggers are now cached per log scope for
the process lifetime via an atomic pointer (a creation race wastes at most
one create).
Measured on macOS (Apple Silicon) with local timing instrumentation
during app launch, the version-info logging block in global.init:
before: 1070us-2629us
after: 858us-1319us
Sentry initialization already ran on a separate thread, but the cache
and state directory resolution happened on the main thread before
spawning it. On macOS the cache dir resolution calls NSFileManager
URLForDirectory:inDomain:appropriateForURL:create:error: which takes
multiple milliseconds and was the single largest cost in global.init.
All directory resolution now happens on the init thread.
before: 2967us-4018us
after: 30us-70us (env map snapshot + thread spawn)
global.init total drops from ~3.4-5.0ms to ~0.4-1.0ms.
This shrinks the binary size of libghostty-vt by **16% on aarch64 macOS
and 22% on x86_64 Linux**. It also shrinks the in-memory footprint by
~256KB per thread + ~20KB per app. All benchmarks remain the same, no
speedups or slowdowns.
Each commit message explains an individual tactic used, but to
summarize:
1. **No stack traces in release panic handlers (~160KB).** This requires
the Zig stack unwind and symbolication logic. I don't think this makes
sense in an embedded library because the embedder should handle this.
2. **An alternate `std.Io` implementation called `TinyIo` (~100KB to
200KB).** See later... since this is the big one.
3. **Disable recursive Parser.Action logging (~35KB).** We now only log
the top-level fields of a Parser.Action, which lowers the amount of
`std.fmt` codegen significantly.
All sizes above are aarch64 macOS and x86_64 Linux ReleaseFast
libghostty builds.
## TinyIo
I think the main complexity introduction here is our alternate `std.Io`
implementation `TinyIo`. This is an IO implementation that implements IO
operations we need through direct syscalls and does not support
concurrency or any other options like network, progress, etc.
Why? Because of the way `std.Io` works through vtable dispatch, the
linker and dead code removal can't prune ANY of the function pointers.
So our binary has full implementations of all the networking,
concurrency, etc. related code even though we don't use it.
This has a runtime effect too: even though we put `std.Io.Threaded` in
single-threaded mode, it still allocates ~256KB of TLS _per thread_, and
its raw struct state is ~18KB (versus 80 _bytes_ for `TinyIo`).
For future maintenance: I exhaustively implemented the vtable rather
than use the failing vtable from Zig stdlib so any Zig changes to add
new fields to this error so we can determine if we want to support it or
not.
Release libghostty-vt builds carefully avoid referencing
std.Options.debug_io because its default implementation is
std.Io.Threaded, and referencing that vtable keeps every operation
Threaded supports linked into the binary: roughly 110KB of unreachable
code. Nothing references it today, but any std.debug.print,
std.debug.lockStderr, or std.log default-handler call added to
release-reachable code would silently reintroduce all of it.
Declare std_options_debug_io in the root module so std uses our value
instead of constructing the Threaded default. Development builds
(Debug, ReleaseSafe, tests) forward the std default so std.debug.print
and friends work normally. ReleaseFast and ReleaseSmall builds declare
it as a @compileError: since std only analyzes the declaration lazily,
at the moment something references a debug Io code path, the error
fires exactly at the offending reference, turning a silent size
regression into a build failure with a message explaining the
alternatives.
Release binaries are byte-identical when the guard is not tripped.
Add a new Io implementation `TinyIo` that only supports the operations
we need and doesn't support concurrency. This shrinks the binary size
of libghostty by anywhere from ~100KB (macOS) to ~200KB (Linux) and
runtime memory requirements by over 256KB (the thread-local storage
`std.Io.Threaded` creates plus the 18KB threaded structure is gone).
`TinyIo` is POSIX-only: Windows keeps std.Io.Threaded, and on
freestanding targets (wasm) TinyIo degrades to std.Io.failing
behavior just like before.
It is also exported from the Zig module as `ghostty.TinyIo` so
Zig embedders can opt into the same size win when constructing
terminals.
The default Zig panic handler unwinds the stack and symbolicates it,
which drags in ~160KB worth of helper machinery. For an embedded library
this isn't great because the embedder's environment should be providing
this as long as libghostty is compiled with symbols or has a way to
symbolize.
Change ReleaseFast/ReleaseSmall libghostty-vt builds to use a custom
panic handler. Debug/ReleaseSafe keep the full Zig handlers.
This shrinks libghostty-vt on macOS by ~160KB (~9%).
This PR adds a `+new-tab` CLI action, useful for automation on GTK. This
mainly re-uses machinery added for the `+new-window`, but adds in a
unique surface ID for identifying surfaces for IPC purposes (and
eliminates use of raw pointers for callbacks from notifications).
Use the standard `~/Android/Sdk` capitalization for the Linux SDK
fallback.
This lets NDK discovery work when neither `ANDROID_NDK_HOME` nor an
`SDK` environment variable is set.
