# Developing winghostty

This fork is Windows-only. The native app target is Win32, the default build
is `winghostty.exe`, and the retained secondary deliverable is `libghostty-vt`.

If you plan to change code here, read [CONTRIBUTING.md](CONTRIBUTING.md) first.

## Build And Test

Use the standard Zig workflow from the repository root:

| Command | Description |
| --- | --- |
| `zig build` | Build the Win32 app and bundled resources |
| `zig build -Demit-exe=true` | Force-install `zig-out/bin/winghostty.exe` |
| `zig build test` | Run the full Zig test suite |
| `zig build test -Dtest-filter=win32` | Run Win32-focused tests |
| `zig build test -Dtest-filter=scroll` | Run scroll/input regression tests |
| `zig build test -Dtest-filter=keybind` | Run keybinding/default-behavior tests |
| `zig build -Demit-lib-vt` | Build the retained `libghostty-vt` library |

For normal development, prefer the narrowest verification that covers your
change, then run `zig build` before you finish.

## Toolchain

This fork requires a **Zig 0.15.x release with patch ≥ 2**. The check is
enforced at compile time in `src/build/zig.zig::requireZig`: any 0.14.x,
0.16.x, or 0.15.0 / 0.15.1 toolchain will fail with a `@compileError` before
user code runs; 0.15.2 and any later 0.15 patch will compile. CI uses
0.15.2 exactly. If you have multiple Zig versions installed locally,
verify the one on your `PATH` before debugging build issues.

If Zig fails before compilation because the dependency cache is empty or cannot
be hydrated automatically for Windows builds, seed it first from the repo root:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/fetch-zig-deps.ps1
```

The repo also ships `scripts/dev-windows.ps1` and `scripts/dev-windows.cmd`
to open a Windows-native shell with the expected Visual Studio and Zig cache
environment already configured.

For manual app validation on Windows, use
`powershell -ExecutionPolicy Bypass -File scripts/interactive-win11.ps1`.
This launches the worktree executable with repo-local runtime state under
`.sandbox/win11/<worktree-id>/` instead of global `%LOCALAPPDATA%\winghostty`.
Pass `-Rebuild` when you need a fresh executable after source edits. Use
`-ResetState` for clean first-run repros and `-OpenShell` to open a shell with
the same sandbox environment.

For a mechanical smoke check that the launched app can start its initial
terminal under the same sandboxed env, run
`powershell -ExecutionPolicy Bypass -File test/windows/interactive-win11-smoke.ps1`.

## Runtime Notes

- The application runtime is Win32.
- The renderer backend is OpenGL on Windows.
- The repo still retains `libghostty-vt` for Zig and C consumers.
- Cross-platform app packaging, GTK, and macOS app workflows have been removed
  from this fork and should not be reintroduced.

## Project Layout (quick map)

- `src/apprt/win32.zig` — Win32 application runtime entry point (~13.7k
  LOC, single file; extractions in progress, see commit `a759eb6`).
- `src/apprt/win32_theme.zig` — theme tokens, DWM integration, accent
  helpers, HC handling (extracted from `win32.zig` in `a759eb6`).
- `src/update/github_releases.zig` — notify-only GitHub Releases updater.
- `src/renderer/OpenGL.zig` — WGL + OpenGL 4.3 renderer backend.
- `src/config/Config.zig` — single source of config options and defaults.
- `dist/windows/` — Inno Setup script, icon, manifest, RC file.
- `scripts/` — Windows packaging, dep-cache bootstrap, dev-shell helpers.

Upstream-derived areas intentionally left alone in day-to-day fork work
include `src/terminal/`, `src/font/`, `src/input/`, `src/termio/`,
`src/shell-integration/`, `src/crash/`, and `libghostty-vt` surfaces.

## Logging

Logging to `stderr` is always available. Debug builds also emit additional
diagnostic output.

Win32-specific local traces used during bring-up may also write to
`winghostty-win32.log` in the current working directory.

## Formatting

- Zig: `zig fmt .`
- Other docs/resources: `prettier -w .`

## Manual Validation

If your change touches input, rendering, or chrome behavior, manually verify:

1. Wheel mouse scrolling in a long buffer.
2. Precision touchpad scrolling, if available.
3. Fast sustained scrolling for flicker, title churn, or dropped repaint.
4. Keybindings affected by the change.
5. Launch `scripts/interactive-win11.ps1 -Rebuild`; add `-ResetState` when
   validating first-run behavior.

## Scope Guard

This fork is not trying to preserve the upstream macOS/GTK app surface.
When Windows-native behavior conflicts with upstream cross-platform behavior,
prefer the Windows-native result.