macos.zig

// macOS host — drop-down terminal entry point.
//
// 진행 상태는 이슈 #108 참고.
//
//   M1 — host 골격 + fail-fast 메시지 (5a336db).
//   M2 — NSWindow + CAMetalLayer 빈 화면 + Cmd+Q (ae2328b).
//   M3 — borderless + dock rect + F1 글로벌 핫키 토글. (현재)
//   M3.5 — config.zig platform-leak 정리, NSAlert 기반 config 에러.
//   M4 — 모니터/DPI 변화 시 재적용.
//   M5 — POSIX PTY + ghostty-vt + CoreText/Metal 글리프.
//   M6 — 한글 IME.
//
// M3 의 검증 포인트 (옵션 D 핵심 가설):
//   F1 두 번 → 윈도우 hide/show 토글에서 잔상 / 깜박임 없음.
//   사용자 드래그 리사이즈는 borderless + non-resizable styleMask 로 OS 차단.
//   #75 가 6번 시도해도 못 풀던 \"드래그 중 잔상\" 시나리오를 원천 회피.

const std = @import("std");
const run_options = @import("../run_options.zig");
const build_options = @import("build_options");
const objc = @import("../macos_objc.zig");
const config = @import("../config.zig");
const ghostty = @import("ghostty-vt");
const display_width = @import("../font/display_width.zig");
const renderer_module = @import("../renderer.zig");
// macOS 전용 host — render present/합성 게이트(#255 Phase 2) free 함수 직접 접근.
const mac_renderer = @import("../renderer/macos.zig");
const ui_metrics = @import("../ui_metrics.zig");
const scrollbar = @import("../scrollbar.zig");
const terminal = @import("../terminal.zig");
const terminal_interaction = @import("../terminal_interaction.zig");
const tab_interaction = @import("../tab_interaction.zig");
const tab_layout = @import("../tab_layout.zig");
const tab_actions = @import("../tab_actions.zig");
const input_policy = @import("../input_policy.zig");
const session_core = @import("../session_core.zig");
const themes = @import("../themes.zig");
const dialog = @import("../dialog.zig");
const messages = @import("../messages.zig");
const command_menu = @import("../command_menu.zig");
const about = @import("../about.zig");
const log = @import("../log.zig");
const perf = @import("../perf.zig");
const instance_context = @import("../instance_context.zig");
const instances = @import("../instances.zig");

pub fn showPanic(msg: []const u8, addr: usize, _: ?*std.builtin.StackTrace) noreturn {
    log.appendLine("panic", "{s}  return_addr=0x{x}", .{ msg, addr });
    var buf: [512]u8 = undefined;
    const text = std.fmt.bufPrint(&buf, messages.panic_format, .{ msg, addr }) catch messages.panic_fallback_msg;
    dialog.showError(messages.crash_title, text);
    std.process.exit(1);
}

pub fn showFatalRunError(err: anyerror) void {
    log.appendLine("fatal", "run failed: {s}", .{@errorName(err)});
    var buf: [256]u8 = undefined;
    const text = messages.runFailureMessage(&buf, err);
    dialog.showError(messages.error_title, text);
}

// AppKit / Metal 상수.
const NSWindowStyleMaskBorderless: c_ulong = 0;
const NSWindowStyleMaskTitled: c_ulong = 1 << 0;
const NSWindowStyleMaskFullSizeContentView: c_ulong = 1 << 15;
const NSBackingStoreBuffered: c_ulong = 2;
// `Regular` (0) = Dock + Cmd+Tab + 메뉴바 등장 (일반 앱).
// `Accessory` (1) = Dock / Cmd+Tab 안 보임, 메뉴바도 우리 앱 메뉴 안 뜸. drop-down
//   터미널 정체성. Info.plist 의 LSUIElement = true 와 같은 효과지만 코드 레벨이라
//   LaunchServices 캐시 / 직접 실행 / open 실행 무관하게 즉시 적용된다.
const NSApplicationActivationPolicyAccessory: c_long = 1;
const MTLPixelFormatBGRA8Unorm: c_ulong = 80;
// `standardWindowButton:` 인덱스 — close=0, miniaturize=1, zoom=2.
const NSWindowCloseButton: c_long = 0;
const NSWindowMiniaturizeButton: c_long = 1;
const NSWindowZoomButton: c_long = 2;
// `setTitleVisibility:` 의 NSWindowTitleHidden = 1.
const NSWindowTitleHidden: c_long = 1;

// CGEventFlags modifier 마스크 (CGEventTypes.h). Carbon modifier (1<<8 등) 와
// 다른 비트 위치. 예: command = 1<<20.
const kCGEventFlagMaskCommand: u64 = 0x00100000;
const kCGEventFlagMaskShift: u64 = 0x00020000;
const kCGEventFlagMaskAlternate: u64 = 0x00080000; // = Option
const kCGEventFlagMaskControl: u64 = 0x00040000;
const kCGEventFlagsAllModifiers: u64 = kCGEventFlagMaskCommand | kCGEventFlagMaskShift | kCGEventFlagMaskAlternate | kCGEventFlagMaskControl;

const CGFloat = f64;
const NSRect = extern struct { origin: NSPoint, size: NSSize };
const NSPoint = extern struct { x: CGFloat, y: CGFloat };
const NSSize = extern struct { width: CGFloat, height: CGFloat };

// CGEventTap FFI (CoreGraphics).
//
// Apple DTS 권장 패턴: CGEventTapCreate 로 system-wide 키보드 이벤트 가로채기
// + CFRunLoopAddSource 로 NSApp 의 main run loop 에 통합. Carbon RegisterEvent
// HotKey 와 달리 Apple Developer 인증서 sign 없이도 동작 (단 \"Input Monitoring\"
// 권한 필요 — 사용자가 시스템 설정에서 활성화).
//
// 참고: ghostty Quick Terminal 의 GlobalEventTap.swift 도 같은 길.
const CGEventRef = ?*anyopaque;
const CFMachPortRef = ?*anyopaque;
const CFRunLoopSourceRef = ?*anyopaque;
const CFRunLoopRef = ?*anyopaque;
const CFStringRef = ?*anyopaque;

const CGEventTapLocation = c_int;
const CGEventTapPlacement = c_int;
const CGEventTapOptions = c_int;
const CGEventMask = u64;
const CGEventField = u32;
const CGEventType = c_int;

const kCGSessionEventTap: CGEventTapLocation = 1;
const kCGHeadInsertEventTap: CGEventTapPlacement = 0;
const kCGEventTapOptionDefault: CGEventTapOptions = 0;
const kCGEventKeyDown: CGEventType = 10;
// CGEventTap 이 OS 에 의해 자동 비활성화될 때 callback 으로 들어오는 special
// type (#146). callback 응답 timeout 또는 user input race 시 발생. -1 / -2 의
// signed 값이라 c_int (= CGEventType).
const kCGEventTapDisabledByTimeout: CGEventType = -2;
const kCGEventTapDisabledByUserInput: CGEventType = -1;
const kCGKeyboardEventKeycode: CGEventField = 9;

const CGEventTapCallBack = *const fn (
    proxy: ?*anyopaque,
    event_type: CGEventType,
    event: CGEventRef,
    userInfo: ?*anyopaque,
) callconv(.c) CGEventRef;

extern fn CGEventTapCreate(
    tap: CGEventTapLocation,
    place: CGEventTapPlacement,
    options: CGEventTapOptions,
    eventsOfInterest: CGEventMask,
    callback: CGEventTapCallBack,
    userInfo: ?*anyopaque,
) CFMachPortRef;

extern fn CGEventTapEnable(tap: CFMachPortRef, enable: bool) void;

extern fn CGEventGetIntegerValueField(event: CGEventRef, field: CGEventField) i64;
extern fn CGEventGetFlags(event: CGEventRef) u64;

extern fn CFMachPortCreateRunLoopSource(
    allocator: ?*anyopaque,
    port: CFMachPortRef,
    order: usize,
) CFRunLoopSourceRef;

extern fn CFRunLoopGetMain() CFRunLoopRef;
extern fn CFRunLoopAddSource(runloop: CFRunLoopRef, source: CFRunLoopSourceRef, mode: CFStringRef) void;
extern fn CFRunLoopRemoveSource(runloop: CFRunLoopRef, source: CFRunLoopSourceRef, mode: CFStringRef) void;
extern fn CFMachPortInvalidate(port: CFMachPortRef) void;

// GCD — 콜백 안에서 tap 자기 자신을 destroy 하기 위해 main run loop 의
// 다음 turn 으로 작업 deferral. `dispatch_get_main_queue()` 는 macOS 헤더에
// static inline 이라 link symbol 없음 — 실제 export 되는 `_dispatch_main_q`
// 글로벌 변수의 주소를 dispatch_queue_t 로 직접 사용 (Apple SDK 가 헤더에서
// 그렇게 풀어내는 것과 동일).
extern var _dispatch_main_q: anyopaque;
const dispatch_function_t = *const fn (?*anyopaque) callconv(.c) void;
extern fn dispatch_async_f(queue: *anyopaque, ctx: ?*anyopaque, work: dispatch_function_t) void;

// render 는 CADisplayLink (`NSWindow.displayLink(target:selector:)`, macOS 14+)
// 가 vsync 마다 main thread 에서 구동한다. 시스템이 합성 타이밍/재생률을 관리
// 하고, 창이 디스플레이에 없으면(hidden) AppKit 이 link 를 자동 suspend 해
// idle 시 render 0 — 옛 CFRunLoopTimer(60fps 무조건 fire)를 대체 (#255).

// kCFRunLoopCommonModes 는 CFString 상수 (Apple 의 CFRunLoop.h). NSString 과
// toll-free bridge 라 NSRunLoop addToRunLoop:forMode: 의 mode 로도 쓴다.
extern const kCFRunLoopCommonModes: CFStringRef;

// Input Monitoring 권한 (macOS 10.15+).
extern fn CGPreflightListenEventAccess() bool;
extern fn CGRequestListenEventAccess() bool;

// Accessibility (손쉬운 사용) 권한 — `kCGEventTapOptionDefault` (active tap)
// 으로 이벤트 변경 / 삼키기 시 macOS 가 추가로 요구. ListenOnly 면 Input
// Monitoring 만으로 충분하지만, 우리는 F1/Cmd+Q 를 다른 앱에 전달 안 되게
// consume 해야 하므로 active 가 필수.
extern fn AXIsProcessTrusted() bool;
extern "c" fn atexit(func: *const fn () callconv(.c) void) c_int;

/// `atexit` 핸들러 — Cmd+Q (NSApp `terminate:`) 가 defer 거치지 않고 `exit()`
/// 직행하므로 run() 의 `defer logStop` 이 안 불린다. `atexit` 는 `exit()`
/// 호출되면 동작하니 여기서 [exit] 라인 기록.
fn atExitLogStop() callconv(.c) void {
    log.logStop(build_options.version);
}

// NSApplication delegate — `applicationShouldTerminate:` 한 메서드만 구현.
// 모든 `terminate:` 호출 (Cmd+Q / 메뉴 / 마지막 탭 종료) 가 진입하기 전에
// macOS 가 이 hook 을 거치게 해 사용자에게 confirm 을 물음 (#116).
const NSTerminateCancel: c_long = 0;
const NSTerminateNow: c_long = 1;

/// 종료 직전 confirm. count == 0 (마지막 탭 PTY exit 후 자동 종료) 만 skip —
/// 이미 사용자 의도된 종료 path. 단일 탭 (count==1) 도 confirm — 사용자 정책.
fn applicationShouldTerminate(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) c_long {
    // #317 — programmatic `terminate:`도 confirm 전에 공통 shortcut 정책을
    // 적용한다. 메뉴 Cmd+Q는 tildazQuit:에서 먼저 적용하므로 여기서는 no-op이고,
    // Cancel 뒤 재시도도 첫 호출에서 pending 상태가 이미 비어 no-op이다.
    applyShortcutInputPolicy(.quit);
    const n = g_session.count();
    if (n == 0) return NSTerminateNow;
    var msg_buf: [256]u8 = undefined;
    const msg = dialog.quitConfirmMessage(&msg_buf, n) orelse return NSTerminateNow;
    return if (dialog.showConfirm(messages.quit_confirm_title, msg)) NSTerminateNow else NSTerminateCancel;
}

/// #195 — 다른 app 활성화 시 우리 NSWindow level 을 normal (0) 로 떨어뜨림.
/// 그 app 이 z-order 상 위로 올라오고, 우리는 *visible 유지* (drop-down 본분 —
/// hide 안 함, 다른 app 뒤에 보임). 다시 우리 app 활성화 (`DidBecomeActive`)
/// 시 popUpMenu (101) 로 복귀 — dock / menu bar 위에 우리가 다시 자리잡음.
///
/// IME 후보 panel (`lowerWindowForImePanel`) 경로와는 별개 — 그쪽은 우리 app
/// 활성 + IME 후보 표시 시 floating (3) 으로 잠깐 낮춤. `setPopupWindowLevel`
/// 호출 시 `g_ime_panel_window_lowered=false` 까지 한 번 reset — IME 가 다시
/// 후보 띄울 때 `lowerWindowForImePanel` 재호출.
fn applicationDidResignActive(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    if (!g_visible) return;
    const NSNormalWindowLevel: c_int = 0;
    setMainWindowLevel(NSNormalWindowLevel);
}

fn applicationDidBecomeActive(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    if (!g_visible) return;
    setPopupWindowLevel();
}

fn createNewInstance() void {
    if (@import("../instance_context.zig").requireWorkerIndex() == 0) {
        repositionWindow();
        showWindow();
        @import("../new_instance.zig").handle(g_gpa.allocator());
    } else {
        @import("../instance_request.zig").send() catch {};
    }
}

fn applicationShouldHandleReopen(_: objc.id, _: objc.SEL, _: objc.id, _: bool) callconv(.c) bool {
    createNewInstance();
    return false;
}

fn newInstanceNotification(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    if (@import("../instance_context.zig").requireWorkerIndex() == 0) createNewInstance();
}

fn hotkeyCaptureBeginNotification(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    @import("../hotkey_capture/macos.zig").setSuspended(true);
}

fn hotkeyCaptureEndNotification(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    @import("../hotkey_capture/macos.zig").setSuspended(false);
}

var g_app_delegate_class: ?objc.Class = null;
var g_app_delegate_instance: objc.id = null;
var g_new_instance_observer_registered = false;

fn installAppDelegate() !void {
    if (g_app_delegate_instance != null) return;
    const NSObject = objc.getClass("NSObject");
    const cls = objc.objc_allocateClassPair(NSObject, "TildazAppDelegate", 0) orelse
        return error.AppDelegateAllocFailed;
    // 시그니처: 반환 NSApplicationTerminateReply (NSUInteger 호환 c_long),
    //         self (id) + _cmd (SEL) + sender (NSApplication id).
    if (!objc.class_addMethod(cls, objc.sel("applicationShouldTerminate:"), @ptrCast(&applicationShouldTerminate), "Q@:@"))
        return error.AppDelegateAddMethodFailed;
    // #195 — focus loss / regain z-order toggle. visible 유지, level 만 조정.
    if (!objc.class_addMethod(cls, objc.sel("applicationDidResignActive:"), @ptrCast(&applicationDidResignActive), "v@:@"))
        return error.AppDelegateAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("applicationDidBecomeActive:"), @ptrCast(&applicationDidBecomeActive), "v@:@"))
        return error.AppDelegateAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("applicationShouldHandleReopen:hasVisibleWindows:"), @ptrCast(&applicationShouldHandleReopen), "B@:@B"))
        return error.AppDelegateAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("newInstanceNotification:"), @ptrCast(&newInstanceNotification), "v@:@"))
        return error.AppDelegateAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("hotkeyCaptureBeginNotification:"), @ptrCast(&hotkeyCaptureBeginNotification), "v@:@"))
        return error.AppDelegateAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("hotkeyCaptureEndNotification:"), @ptrCast(&hotkeyCaptureEndNotification), "v@:@"))
        return error.AppDelegateAddMethodFailed;
    objc.objc_registerClassPair(cls);
    g_app_delegate_class = cls;

    const alloc = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const init_obj = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    const inst = init_obj(alloc(cls, objc.sel("alloc")) orelse return error.AppDelegateInitFailed, objc.sel("init")) orelse
        return error.AppDelegateInitFailed;
    g_app_delegate_instance = inst;

    const setDelegate = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    setDelegate(g_app, objc.sel("setDelegate:"), inst);

    const Center = objc.getClass("NSDistributedNotificationCenter");
    const getCenter = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    if (getCenter(Center, objc.sel("defaultCenter"))) |center| {
        const addObserver = objc.objcSend(fn (objc.id, objc.SEL, objc.id, objc.SEL, objc.id, objc.id) callconv(.c) void);
        addObserver(
            center,
            objc.sel("addObserver:selector:name:object:"),
            inst,
            objc.sel("newInstanceNotification:"),
            objc.nsString(@import("../instance_request/macos.zig").notification_name),
            null,
        );
        g_new_instance_observer_registered = true;
        const capture = @import("../hotkey_capture/macos.zig");
        addObserver(center, objc.sel("addObserver:selector:name:object:"), inst, objc.sel("hotkeyCaptureBeginNotification:"), objc.nsString(capture.begin_notification_name), null);
        addObserver(center, objc.sel("addObserver:selector:name:object:"), inst, objc.sel("hotkeyCaptureEndNotification:"), objc.nsString(capture.end_notification_name), null);
    }
}

extern fn MTLCreateSystemDefaultDevice() objc.id;

// 글로벌 toggle 상태 — CGEventTap 콜백 (C 시그니처) 이 NSApp / window / config
// 에 접근하려면 어딘가 보관해야 함. M3 단계에서 host 가 한 인스턴스만 띄우므로
// 모듈 전역으로 충분. M5 이후 multi-window / multi-tab 으로 확장 시 userdata
// 포인터 패턴으로 옮길 예정.
var g_app: objc.id = null;
var g_window: objc.id = null;
var g_visible: bool = false;
var g_config: config.Config = .{};
var g_gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
/// 멀티탭 컬렉션 (#111 M11.1). 현재 단계는 데이터 모델만 도입 — 실제로는
/// 단일 탭만 생성. PTY / Terminal / Stream / 마우스 selection 은 모두 활성
/// 탭의 필드. host 코드는 `g_session.activeTab().?.{pty,terminal,...}` 로 access.
///
/// thread safety (M5.1 노트): UI thread 가 terminal 을 안 읽으므로 PTY read
/// thread 가 직접 stream parsing 해도 race 없음. 멀티탭 도입해도 활성 탭만
/// 렌더링 + 입력 받으니 동일 — 단 closeTab 은 read thread 가 살아 있을 때
/// 위험하므로 후속 milestone 에서 join 처리.
var g_session: session_core.SessionCore = undefined;

/// #382 — 측정용 실행 옵션. `run()` 이 받아 여기 저장하고, 아래 네 지점이 참조한다:
/// 전역 핫키 등록 · 창 표시 · 창 크기 (`dockRect`) · 첫 탭의 셸.
var g_run_opts: run_options.RunOptions = .{};
/// PTY 자식 종료 시 read thread 가 enqueue, main thread (renderFrameTick) 가
/// drain. session_core 의 tab_exit_fn 이 read thread context 에서 불리는데
/// 거기서 closeTabByPtr 직접 호출하면 self-join deadlock — read thread 가
/// 자기 자신을 join 하게 됨. Windows 의 PostMessage 패턴과 같은 의도이지만
/// CFRunLoop 우회 — 단순 mutex-protected queue 로 충분 (renderFrameTick 가
/// main thread 에서 매 frame drain).
var g_pending_close_buf: std.ArrayList(usize) = .{};
var g_pending_close_mutex: std.Thread.Mutex = .{};
/// #255 Phase 2 — visible-but-idle render skip. displayLink 가 vsync 마다 fire 해도
/// 변화 없으면 그릴 게 없다. 렌더 필요 = ① PTY 출력(drainOutputForRender 반환)
/// ② 로컬 UI 변화(키/마우스/창 — 이 플래그) ③ preedit/autoscroll(force_render).
/// 셋 다 아니고 화면 표시까지 확정(frameWasPresented)되면 그 frame 의 render 작업을
/// skip(GPU 안 씀) — displayLink 는 visible 동안 계속 돌아 다음 변화를 다음 frame 이
/// 즉시 잡는다. 입력 핸들러·renderFrameTick 모두 main thread 라 atomic 불필요.
/// init=true(첫 프레임). requestRender() 로 set, render 후 clear.
var g_needs_render: bool = true;

/// #376 — 직전 tick 의 blink 위상. 이 값이 **바뀌는 프레임에만** 렌더 게이트를
/// 연다. "화면에 blink 셀이 있다" 로 열면 매 vsync 그리게 돼 #255 의 절전이
/// 사라지지만, 위상 전환은 1초에 두 번뿐이라 추가 렌더가 초당 2프레임이다.
var g_last_blink_phase: bool = false;

/// #245 — drag-select auto-scroll (mac). 선택 드래그 중 포인터가 grid 위/아래 경계
/// 밖이면 방향(-1=위/older, +1=아래/newer, 0=비활성) + 마지막 drag px 저장. 60fps
/// 렌더 tick(renderFrameTick)이 이 동안 viewport 스크롤 + selection.update 재호출
/// → 포인터를 멈춰 둬도 연속 스크롤 + scrollback 까지 선택 연장. mouseUp 에서 0.
var g_sel_autoscroll_dir: i8 = 0;
var g_sel_autoscroll_next_ms: i64 = 0;
var g_last_drag_x: f32 = 0;
var g_last_drag_y: f32 = 0;

/// 윈도우 표시 모드 (#162). Windows `FullscreenMode` 와 동등 — cross-platform.
///   - .none: dock rect (config.dock_position / width / height / offset 기반)
///   - .monitor: NSScreen.frame 통째 = 메뉴바 + dock 까지 덮음 ("전체화면")
///   - .workarea: NSScreen.visibleFrame = 메뉴바 + dock 회피 ("풀스크린")
///
/// 토글 정책: 들어간 키로만 나옴 (self-symmetric). Cmd+Enter 로 .monitor 진입
/// 시 같은 키로만 dock 복귀, Shift+Cmd+Enter 는 no-op. 같은 패턴으로 .workarea.
/// `.monitor ↔ .workarea` 직접 transition 없음.
const FullscreenMode = enum { none, monitor, workarea };
var g_fullscreen_mode: FullscreenMode = .none;
/// 탭 drag-and-drop reorder state (#111 M11.6a). Windows `tab_interaction.DragState`
/// 그대로 사용 — cross-platform 모듈.
var g_drag: tab_interaction.DragState = .{};
/// 탭바 스크롤 오프셋 (픽셀, #117). 탭바 총 너비가 viewport 너비를 초과하면
/// 활성 탭이 보이도록 자동 이동. Windows `App.tab_scroll_x` 와 동일 정책 — 매
/// frame `renderFrameTick` 에서 `ensureActiveTabVisible` 가 갱신, drag 중에는
/// `tildazMouseDragged` 가 직접 갱신.
var g_tab_scroll_x_px: f32 = 0;
/// #268 2b — 탭바 컨트롤 버튼 (`<` `>` `×` `+`) 의 hover 대상. mouseMoved:
/// 마다 갱신, 변경 시에만 재렌더. 렌더러가 hover 배경 박스를 그림.
var g_tab_hover: tab_layout.Area = .none;
/// #329 command/shortcut menu 표시 상태.
var g_command_menu_open: bool = false;
var g_command_menu_hover: ?command_menu.Command = null;
/// #329 — 메뉴 keyboard focus (Up/Down/Home/End/Tab 이동, Enter/Space 실행).
var g_command_menu_focus: ?command_menu.Command = null;
/// #329 — 작은 viewport 에서 entry 단위 scroll 의 첫 표시 entry 인덱스.
var g_command_menu_first: usize = 0;
/// #334 — 메뉴 wheel delta 누적 (트랙패드 과민 방지 — 12pt 당 1 entry).
var g_command_menu_scroll_accum: f64 = 0;
/// 사용자가 `<` / `>` 화살표를 눌러 viewport 를 옮긴 상태 (#117). 이 동안
/// `ensureActiveTabVisible` skip — 활성 탭 가려져도 그대로 (Firefox).
/// 활성 탭 변경 / drag reorder 끝 / 새 탭 생성 시 false 로 리셋.
var g_tab_scroll_user_override: bool = false;
/// `tab_actions.Host` 인스턴스 — module-level state (g_session 등) 를 cross-
/// platform helper API 로 노출. 모든 콜백은 mac specific (NSPasteboard, NSApp
/// terminate). invalidate 는 noop — mac 60fps timer 가 자동 redraw.
var g_host: tab_actions.Host = .{
    .session = &g_session,
    .override_ptr = &g_tab_scroll_user_override,
    .invalidate = macHostInvalidate,
    .clipboard_copy = macHostClipboardCopy,
    .terminate = macHostTerminate,
};

fn macHostInvalidate(_: *tab_actions.Host) void {
    // mac 은 renderFrameTick 이 vsync 마다 자동 호출 — 즉시 redraw 트리거 불필요.
}

/// NSPasteboard.general → clearContents → setString:forType:NSPasteboardTypeString.
/// text 는 caller 가 비어있지 않음 보장 (`tab_actions.copyActiveSelection` 가
/// len==0 검사 후 호출).
fn macHostClipboardCopy(_: *tab_actions.Host, text: [:0]const u8) void {
    const NSPasteboard = objc.getClass("NSPasteboard");
    const get_general = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const pb = get_general(NSPasteboard, objc.sel("generalPasteboard"));
    if (pb == null) return;
    const clear = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_long);
    _ = clear(pb, objc.sel("clearContents"));

    // text 가 std.heap allocator 에서 온 non-null-terminated slice — NSString
    // 의 stringWithBytes:length:encoding: 사용 (UTF8 = 4).
    const NSString = objc.getClass("NSString");
    const stringWithBytes = objc.objcSend(fn (objc.Class, objc.SEL, [*]const u8, usize, c_ulong) callconv(.c) objc.id);
    const ns_text = stringWithBytes(NSString, objc.sel("stringWithBytes:length:encoding:"), text.ptr, text.len, NSUTF8StringEncoding);
    if (ns_text == null) return;

    const setString = objc.objcSend(fn (objc.id, objc.SEL, objc.id, objc.id) callconv(.c) bool);
    const ns_type = objc.nsString("public.utf8-plain-text"); // = NSPasteboardTypeString
    _ = setString(pb, objc.sel("setString:forType:"), ns_text, ns_type);
}

fn macHostTerminate(_: *tab_actions.Host) void {
    log.appendLine("tab", "last tab closed, terminating tildaz", .{});
    const terminate_sel = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    terminate_sel(g_app, objc.sel("terminate:"), null);
}
/// 새 탭 생성 시 재사용할 PTY 파라미터들. 첫 탭 init 시 채우고 그 후 변동 없음.
var g_shell_path: []const u8 = "";
var g_extra_env: [5]terminal.ExtraEnv = undefined;

// M5.3 — Metal 렌더러 + timer + cell metrics. cell_width/height 는 폰트의
// 'M' advance / ascent+descent+leading 으로 동적 측정 (Windows 와 동일 패턴).
var g_metal_layer: objc.id = null;
var g_renderer: ?renderer_module.RendererBackend = null;
/// CADisplayLink (NSWindow.displayLink) — vsync render driver. null = 미생성.
var g_display_link: objc.id = null;
// 터미널 영역 안쪽 padding — `ui_metrics.zig` 의 공통 상수. Windows /
// macOS 동일 값으로 시각적 일관성 유지. pixel 변환은 init 시 retina scale 곱.
const TERMINAL_PADDING_PT = ui_metrics.TERMINAL_PADDING_PT;
const TAB_BAR_HEIGHT_PT = ui_metrics.TAB_BAR_HEIGHT_PT;

/// 탭바가 현재 차지하는 픽셀 높이. 탭이 ≤ 1 개면 0 (자리 안 띄움) — 단일 탭
/// 사용자가 위쪽 빈 공간 거슬려 함 (#111 M11.4 사용자 보고).
/// 탭 ≥ 2 개로 전환 시 자리 등장 + 모든 탭 cols/rows 재계산은 호출처 책임
/// (`syncTerminalGeometry` 가 통합 처리).
fn tabBarHeightPx(scale: f32) i32 {
    if (g_session.count() < 2) return 0;
    return @intCast(ui_metrics.tabBarHeightPx(scale));
}

/// #329 — terminal grid y-offset과 분리된 scrollbar 전용 top inset. 단일
/// 탭에서도 항상-visible control strip 아래부터 track이 시작한다.
fn scrollbarTopInsetPx(scale: f32) i32 {
    return if (g_session.count() > 0) @intCast(ui_metrics.tabBarHeightPx(scale)) else 0;
}

/// 픽셀 단위 탭 너비 (DPI scale 적용). hit-test / drag / scroll 모두 같은 값.
fn tabWidthPx() f32 {
    if (g_renderer == null) return 0;
    return ui_metrics.scaledPxF(ui_metrics.TAB_WIDTH_PT, g_renderer.?.scale);
}

/// `tab_layout.Layout` alias — 본문 정의는 cross-platform 모듈 (#159 Phase 1).
const TabBarLayout = tab_layout.Layout;

/// `Inputs` 채워서 tab_layout.compute 호출. host 별로 g_renderer.scale /
/// g_session.count / g_tab_scroll_x_px 같은 글로벌을 인자로 변환만 함.
fn tabBarLayoutInputs() ?tab_layout.Inputs {
    if (g_renderer == null) return null;
    const r = &g_renderer.?;
    // #329 정책 변경 (2026-07-22) — count >= MAX_TABS 여도 `+` 는 자리를
    // 유지하고 비활성 색 + click noop. `[+][×][…]` 세 버튼이 항상 같은 자리.
    // 단축키 경로의 한도 dialog 는 그대로.
    const at_limit = g_session.count() >= session_core.MAX_TABS;
    return .{
        .viewport_w = @floatFromInt(r.vp_width),
        .tab_count = @intCast(g_session.count()),
        .tab_w = tabWidthPx(),
        .arrow_w = ui_metrics.scaledPxF(ui_metrics.TAB_ARROW_W_PT, r.scale),
        .plus_w = ui_metrics.scaledPxF(ui_metrics.TAB_PLUS_W_PT, r.scale),
        .plus_enabled = !at_limit,
        .close_w = ui_metrics.scaledPxF(ui_metrics.TAB_CLOSE_W_PT, r.scale),
        .more_w = ui_metrics.scaledPxF(ui_metrics.TAB_MORE_W_PT, r.scale),
        .scroll_x = g_tab_scroll_x_px,
    };
}

fn tabBarLayout() TabBarLayout {
    const inputs = tabBarLayoutInputs() orelse return .{
        .tab_area_x = 0,
        .tab_area_w = 0,
        .arrows_visible = false,
        .arrow_w = 0,
        .plus_w = 0,
        .plus_x = 0,
        .close_w = 0,
        .close_x = 0,
        .more_w = 0,
        .more_x = 0,
    };
    return tab_layout.compute(inputs);
}

/// 활성 탭이 viewport 안에 보이도록 `g_tab_scroll_x_px` 갱신 (#117 정책 b).
/// drag / 사용자 화살표 override 중에는 호출 안 함.
fn ensureActiveTabVisible() void {
    const inputs = tabBarLayoutInputs() orelse {
        g_tab_scroll_x_px = 0;
        return;
    };
    const layout = tab_layout.compute(inputs);
    g_tab_scroll_x_px = tab_layout.ensureActiveVisible(inputs, layout, @intCast(g_session.active_tab));
}

/// `<` / `>` 화살표 클릭 처리 (#117). viewport 한 step (= 1 탭 너비) 이동 +
/// user_override 활성. 양 끝 clamp.
fn scrollTabsByArrow(dir: tab_layout.ArrowDir) void {
    const inputs = tabBarLayoutInputs() orelse return;
    const layout = tab_layout.compute(inputs);
    if (tab_layout.scrollByArrow(inputs, layout, dir)) |sx| {
        g_tab_scroll_x_px = sx;
        g_tab_scroll_user_override = true;
    }
}

/// #352 — 터미널 격자 크기. 계산은 공통 `ui_metrics` 가 한다 (열 수 #350 / 행 수 #352).
///
/// **세 호출처의 9줄 복붙을 없애려고 둔 지역 helper 다.** `syncTerminalGeometry` ·
/// `syncGeometryAfterScreenChange` · 첫 탭 생성 세 곳이 `cell_w` / `cell_h` / `pad` /
/// `tab_bar` / `top_reserved` / `usable_h` / `sb_px` / `cols` / `rows` 를 똑같이 적어
/// 두고 있었고, 실질 입력은 `(vp_w, vp_h, scale)` 셋뿐이었다. Linux `Client.gridSize` ·
/// Windows `App.getTerminalGridSize` 와 같은 모양이 된다.
///
/// `cell_*` 는 `g_renderer` 에서 읽는다 — 세 호출처가 모두 renderer 가 있는 시점이고,
/// 같은 파일의 `tabBarHeightPx` 도 이미 `g_session` 전역을 읽는다 (탭 < 2 면 0, #127).
fn terminalGrid(vp_w: u32, vp_h: u32, scale: f32) struct { cols: u16, rows: u16 } {
    const font = &g_renderer.?.font;
    const pad: u32 = ui_metrics.scaledPx(u32, TERMINAL_PADDING_PT, scale);
    const sb_px: u32 = ui_metrics.scaledPx(u32, ui_metrics.SCROLLBAR_W_PT, scale);
    return .{
        .cols = ui_metrics.terminalCols(vp_w, pad, sb_px, font.cell_width_px),
        .rows = ui_metrics.terminalRows(vp_h, tabBarHeightPx(scale), pad, font.cell_height_px),
    };
}

/// 현재 viewport / cell 크기 + 탭 수에 따른 cols/rows 재계산 후 모든 탭의
/// terminal + pty 동기화. 탭 1↔2 전환 시 탭바 등장/사라짐으로 cell 영역이
/// 변하므로 호출 필요. screen change / 탭 추가 / 탭 닫기 모두 같은 함수 사용.
fn syncTerminalGeometry() void {
    if (g_renderer == null) return;
    if (g_session.count() == 0) return;

    const r = &g_renderer.?;
    const grid = terminalGrid(r.vp_width, r.vp_height, r.scale);
    const new_cols = grid.cols;
    const new_rows = grid.rows;

    for (g_session.tabs.items) |t| {
        if (new_cols == t.terminal.cols and new_rows == t.terminal.rows) continue;
        t.terminal.resize(g_gpa.allocator(), new_cols, new_rows) catch |err| {
            log.appendLine("geom", "terminal resize failed: {s}", .{@errorName(err)});
            continue;
        };
        t.backend.resize(new_cols, new_rows) catch |err| {
            log.appendLine("geom", "pty resize failed: {s}", .{@errorName(err)});
        };
    }
}

// NSWindow subclass — `canBecomeKeyWindow` 를 YES 로 override 해서 borderless
// styleMask 에서도 key window 가능하게. Default NSWindow 는 borderless 면
// canBecomeKey=NO 라 mainMenu Cmd+Q 등이 dispatch 안 됨. ghostty Quick Terminal
// 의 `class QuickTerminalWindow: NSPanel { override var canBecomeKey: Bool { true } }`
// 와 동일 효과.
fn tildazCanBecomeKey(_: objc.id, _: objc.SEL) callconv(.c) bool {
    return true;
}

fn tildazCanBecomeMain(_: objc.id, _: objc.SEL) callconv(.c) bool {
    return true;
}

fn registerTildazWindowClass() !objc.Class {
    const NSWindow = objc.getClass("NSWindow");
    const cls = objc.objc_allocateClassPair(NSWindow, "TildazWindow", 0) orelse
        return error.WindowSubclassAllocFailed;
    // Method signature: "B@:" = bool 반환, self (id) + _cmd (SEL) 만 인자.
    if (!objc.class_addMethod(cls, objc.sel("canBecomeKeyWindow"), @ptrCast(&tildazCanBecomeKey), "B@:"))
        return error.WindowSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("canBecomeMainWindow"), @ptrCast(&tildazCanBecomeMain), "B@:"))
        return error.WindowSubclassAddMethodFailed;
    objc.objc_registerClassPair(cls);
    return cls;
}

// TildazView = NSView subclass — keyDown / acceptsFirstResponder override.
// `acceptsFirstResponder` YES 안 하면 NSWindow 가 firstResponder 로 안 잡아
// 키 이벤트가 view 에 안 옴. keyDown: 에서 NSEvent.characters 추출 → PTY 로
// write. 특수 키 (화살표, F-key) 는 별도 escape sequence 매핑 필요 (M5.4b).
fn tildazAcceptsFirstResponder(_: objc.id, _: objc.SEL) callconv(.c) bool {
    return true;
}

/// #317 — AppKit은 Command key equivalent를 keyDown:보다 먼저 key window의
/// view hierarchy에 보낸다. terminal marked input이 Cmd+Q를 소비하기 전에 custom
/// NSTextInputClient인 이 view가 공통 입력 정책을 적용한다. terminal marked-input
/// 첫 event는 mainMenu가 매칭하지 않는 것이 실기로 확인됐으므로, 기존 macOS
/// main-queue deferral로 custom Quit selector를 다음 turn에 실행한다. 다른 key는
/// false로 기존 NSMenu routing을 유지한다.
fn tildazPerformKeyEquivalent(_: objc.id, _: objc.SEL, event: objc.id) callconv(.c) bool {
    if (event == null) return false;

    const get_flags = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_ulong);
    const flags = get_flags(event, objc.sel("modifierFlags"));
    const NSEventModifierFlagShift: c_ulong = 1 << 17;
    const NSEventModifierFlagControl: c_ulong = 1 << 18;
    const NSEventModifierFlagOption: c_ulong = 1 << 19;
    const NSEventModifierFlagCommand: c_ulong = 1 << 20;
    const relevant = NSEventModifierFlagShift |
        NSEventModifierFlagControl |
        NSEventModifierFlagOption |
        NSEventModifierFlagCommand;
    if (flags & relevant != NSEventModifierFlagCommand) return false;

    const get_kc = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_ushort);
    if (get_kc(event, objc.sel("keyCode")) != 0x0C) return false; // Q

    applyShortcutInputPolicy(.quit);
    dispatch_async_f(&_dispatch_main_q, null, tildazQuitTrampoline);
    return true;
}

const NSEventTypeKeyDown: c_long = 10;
const NSUTF8StringEncoding: usize = 4;

/// macOS hardware keyCode 별 xterm-compatible escape sequence. macOS 의
/// NSEvent.characters 는 화살표 / F-key 를 NSFunctionKey private codepoint
/// (U+F700~) 으로 보내는데 bash / vim / less 등은 표준 xterm escape sequence
/// 만 인식하므로 keyCode 직접 매핑이 필요.
fn keyCodeToEscape(keycode: c_ushort) ?[]const u8 {
    return switch (keycode) {
        // 화살표
        126 => "\x1b[A", // up
        125 => "\x1b[B", // down
        124 => "\x1b[C", // right
        123 => "\x1b[D", // left
        // 네비게이션
        115 => "\x1b[H", // home
        119 => "\x1b[F", // end
        116 => "\x1b[5~", // pgup
        121 => "\x1b[6~", // pgdn
        117 => "\x1b[3~", // forward delete
        114 => "\x1b[2~", // insert/help (외장 PC 키보드 — Apple 키보드엔 없음, #282 A7 parity)
        // F-keys
        122 => "\x1bOP", // F1 (CGEventTap 이 가로채니 사실 도달 안 함)
        120 => "\x1bOQ", // F2
        99 => "\x1bOR", // F3
        118 => "\x1bOS", // F4
        96 => "\x1b[15~", // F5
        97 => "\x1b[17~", // F6
        98 => "\x1b[18~", // F7
        100 => "\x1b[19~", // F8
        101 => "\x1b[20~", // F9
        109 => "\x1b[21~", // F10
        103 => "\x1b[23~", // F11
        111 => "\x1b[24~", // F12
        else => null,
    };
}

fn interpretSingleKeyEvent(self_view: objc.id, event: objc.id) void {
    const NSArray = objc.getClass("NSArray");
    const arrayWithObject = objc.objcSend(fn (objc.Class, objc.SEL, objc.id) callconv(.c) objc.id);
    const array = arrayWithObject(NSArray, objc.sel("arrayWithObject:"), event);
    const interpretKeyEvents = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    interpretKeyEvents(self_view, objc.sel("interpretKeyEvents:"), array);
}

/// #296 — 현재 입력 상태를 공통 입력 정책(input_policy)용으로.
fn macInputState() input_policy.State {
    return .{ .terminal_preedit_active = g_marked_len > 0 };
}

/// #317 — macOS의 모든 shortcut 진입점이 같은 pending 입력 정책을 적용한다.
/// `keyDown:` Cmd shortcut뿐 아니라 NSMenu selector, Cmd+Q의
/// `applicationShouldTerminate:`, F1 event tap도 이 helper를 action 전에 호출한다.
/// read-only copy/perf의 `.leave`와 상태변경 action의 `.commit` 구분은 오직
/// `input_policy.resolve`가 결정한다.
fn applyShortcutInputPolicy(shortcut: input_policy.Shortcut) void {
    const disposition = input_policy.resolve(.{ .shortcut = shortcut }, macInputState());
    switch (disposition.pending) {
        .leave => {},
        .commit => {
            if (g_window == null) return;
            const contentView_get = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
            const cv = contentView_get(g_window, objc.sel("contentView"));
            if (cv != null) commitPendingInput(cv);
        },
        // shortcut 정책에는 discard 가 없다. Ctrl+C interrupt의 discard는
        // tildazKeyDown의 별도 IME/SIGINT 순서가 담당한다.
        .discard => unreachable,
    }
}

/// #340 — paste semantic entry 의 pending 정책 적용. Cmd+V / 우클릭 공통 —
/// 예전엔 우클릭(tildazRightMouseDown)이 정책 없이 handlePaste 직행이라 터미널
/// 조합 중 우클릭 paste 가 'X하' 순서가 될 수 있었다 (#333 의 macOS 형제).
/// terminal preedit(.commit): 전체 commit (preedit → PTY flush) 후 payload 가
/// 이어져 '하X' (native textbox 동등).
fn applyPasteInputPolicy() void {
    const disposition = input_policy.resolve(.paste, macInputState());
    if (g_window == null) return;
    const contentView_get = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    const cv = contentView_get(g_window, objc.sel("contentView"));
    if (cv == null) return;
    switch (disposition.pending) {
        .leave => {},
        .commit => commitPendingInput(cv),
        // paste 정책에 discard 없음 (input_policy.resolve 참고).
        .discard => unreachable,
    }
}

/// #296 — macOS Cmd+keyCode 를 입력 정책 Shortcut 으로 분류. 인식 못한 조합은
/// null (→ mainMenu Cmd+Q 등). `tildazKeyDown` 의 dispatch switch 와 정확히 일치.
fn macCmdShortcut(kc: c_ushort, shift: bool) ?input_policy.Shortcut {
    if (kc == 8) return .copy_selection; // Cmd+C
    if (kc == 0x11 and !shift) return .new_tab; // Cmd+T
    if (kc == 0x0D and !shift) return .close_tab; // Cmd+W
    if (keycodeToTabIndex(kc) != null) return .switch_tab; // Cmd+1..9
    if (shift and kc == 0x21) return .prev_tab; // Shift+Cmd+[
    if (shift and kc == 0x1E) return .next_tab; // Shift+Cmd+]
    if (shift and kc == 0x0F) return .reset_terminal; // Shift+Cmd+R
    if (kc == 0x24) return .fullscreen; // Cmd+Enter / Shift+Cmd+Enter
    if (shift and kc == 0x6F) return .dump_perf; // Shift+Cmd+F12
    return null;
}

fn tildazKeyDown(self_view: objc.id, _: objc.SEL, event: objc.id) callconv(.c) void {
    requestRender(); // #255 Phase2 — 키 입력 → 렌더 (스크롤백/탭조작 등 출력 없는 변화 포함).
    const tab = g_session.activeTab() orelse return;
    if (event == null) return;

    // Cmd+C / Cmd+V 우선 — IME 와 무관하게 처리.
    const get_flags = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_ulong);
    const flags = get_flags(event, objc.sel("modifierFlags"));

    // #329 — command menu 가 열려 있으면: Cmd 단축키와 Ctrl 조합(Ctrl+C
    // interrupt — 2026-07-23 사용자 확정 (a): 메뉴 닫고 정상 실행)은 메뉴를
    // 닫고 아래 기존 경로로 진행, 그 외 모든 키는 메뉴 계층이 소비 (Esc 닫기
    // / 화살표·Tab 이동 / Enter·Space 실행 / 그 외 noop). Option 조합은 특수
    // 문자·한자 입력이라 소비 유지. PTY 로 새지 않음 — SPEC §5.3.
    if (g_command_menu_open) {
        const NSEventModifierFlagControl: c_ulong = 1 << 18;
        if ((flags & ((1 << 20) | NSEventModifierFlagControl)) != 0) {
            closeCommandMenu();
        } else {
            const get_menu_kc = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_ushort);
            const menu_kc = get_menu_kc(event, objc.sel("keyCode"));
            const menu_shift = (flags & (1 << 17)) != 0;
            handleCommandMenuKey(switch (menu_kc) {
                0x35 => .escape,
                0x7E => .up,
                0x7D => .down,
                0x73 => .home,
                0x77 => .end,
                0x30 => if (menu_shift) command_menu.MenuKey.shift_tab else .tab,
                0x24, 0x4C => .enter, // Return / KP Enter
                0x31 => .space,
                else => command_menu.MenuKey.other,
            });
            return;
        }
    }

    const NSEventModifierFlagCommand: c_ulong = 1 << 20;
    const cmd = (flags & NSEventModifierFlagCommand) != 0;
    if (cmd) {
        const get_kc = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_ushort);
        const kc = get_kc(event, objc.sel("keyCode"));
        const NSEventModifierFlagShift: c_ulong = 1 << 17;
        const shift = (flags & NSEventModifierFlagShift) != 0;

        // #296 — Cmd 단축키의 preedit commit 여부는 입력 정책(input_policy.
        // resolve) 한 곳에서 결정. copy(Cmd+C)/perf(Shift+Cmd+F12)는 read-only,
        // 터미널 preedit 은 자모 보존 위해 flush. 그 외 단축키는 commit 후 실행
        // (SPEC §4.1).
        //
        // #282 A3 / #340 — Cmd+V(paste): 조합을 먼저 확정하고 payload 를 잇는다.
        // pending 적용은 우클릭과 공통 helper(applyPasteInputPolicy) 한 곳.
        if (kc == 9) {
            applyPasteInputPolicy();
            handlePaste();
            return;
        }

        // Cmd+kc → 입력 정책 Shortcut 분류. 인식 못한 Cmd+key 는 mainMenu(Cmd+Q 등).
        const shortcut = macCmdShortcut(kc, shift) orelse return;
        applyShortcutInputPolicy(shortcut);
        switch (shortcut) {
            .copy_selection => handleCopy(), // Cmd+C (kc 8)
            .new_tab => handleNewTab(), // Cmd+T
            .close_tab => handleCloseActiveTab(), // Cmd+W
            .switch_tab => tab_actions.switchTab(&g_host, keycodeToTabIndex(kc).?), // Cmd+1..9
            .prev_tab => tab_actions.prevTab(&g_host), // Shift+Cmd+[
            .next_tab => tab_actions.nextTab(&g_host), // Shift+Cmd+]
            .reset_terminal => tab_actions.resetActive(&g_host), // Shift+Cmd+R (#162)
            .fullscreen => toggleFullscreenMode(if (shift) .workarea else .monitor), // Cmd/Shift+Cmd+Enter (#162)
            .dump_perf => perf.dumpAndReset("snapshot"), // Shift+Cmd+F12 (#160)
            else => {}, // macOS keyDown 이 안 내는 나머지(show_about/config/log/quit=mainMenu)
        }
        return;
    }

    const NSEventModifierFlagShift: c_ulong = 1 << 17;
    const NSEventModifierFlagOption: c_ulong = 1 << 19;
    const shift = (flags & NSEventModifierFlagShift) != 0;
    const option = (flags & NSEventModifierFlagOption) != 0;
    const get_keycode = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_ushort);
    const keycode = get_keycode(event, objc.sel("keyCode"));

    if (option and keycode == 0x24) {
        const had_marked_text = g_marked_len > 0 and g_preedit_len > 0;
        clearHanjaState();
        g_hanja_preedit_commit_requested = had_marked_text;
        defer g_hanja_preedit_commit_requested = false;

        if (!had_marked_text) _ = beginHanjaReconversionTarget();
        interpretSingleKeyEvent(self_view, event);

        if (had_marked_text and g_hanja_pending_commit_active) {
            g_hanja_reconversion_active = true;
            g_hanja_reconversion_range = g_hanja_pending_commit_range;
            g_hanja_reconversion_delete_count = g_hanja_pending_commit_delete_count;
            interpretSingleKeyEvent(self_view, event);
            if (!g_hanja_candidate_active) cancelHanjaState();
        }
        return;
    }

    // Ctrl+key (#121) — ASCII control char (예: Ctrl+C = 0x03 SIGINT).
    // Windows `WM_CHAR` 가 자동 변환하는 패턴을 macOS 는 직접. NSEvent 의
    // `characters` 가 modifier 적용된 char — Ctrl+C 누르면 characters="\x03".
    //
    // **IME 조합 중에도** Ctrl+key 는 그대로 PTY 로 보낸다 — shell 의 Ctrl+C
    // 는 "현재 입력 라인 버리기" 의도라 한글 조합도 같이 버리는 게 자연스러움.
    // IME 의 markedText 는 `discardMarkedText` 로 reset 한 후 PTY write.
    // (이전 분기는 g_marked_len==0 일 때만 했어서 한글 조합 중 Ctrl+C 가 IME
    // 의 interpretKeyEvents 로 흘러 SIGINT 안 갔음.)
    const NSEventModifierFlagControl: c_ulong = 1 << 18;
    const NSEventModifierFlagCommandKD: c_ulong = 1 << 20;
    const ctrl = (flags & NSEventModifierFlagControl) != 0;
    const cmd_too = (flags & NSEventModifierFlagCommandKD) != 0;

    // Cmd 가 같이 눌린 ctrl+cmd 조합은 macOS system shortcut (Ctrl+Cmd+Space =
    // Show Emoji & Symbols 등) 의 표식 — PTY 로 안 흘리고 mainMenu 의 menu
    // item keyEquivalent 로 라우팅 (#130). 일반 Ctrl+C (Cmd 없음) 는 그대로
    // PTY 직송.
    if (ctrl and !cmd_too) {
        const get_chars = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
        const chars = get_chars(event, objc.sel("characters"));
        if (chars != null) {
            const get_len = objc.objcSend(fn (objc.id, objc.SEL, usize) callconv(.c) usize);
            const len = get_len(chars, objc.sel("lengthOfBytesUsingEncoding:"), NSUTF8StringEncoding);
            if (len > 0) {
                const get_utf8 = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) [*:0]const u8);
                const cstr = get_utf8(chars, objc.sel("UTF8String"));
                const ctrl_c = (len == 1 and cstr[0] == 0x03);
                if (g_marked_len > 0) {
                    // Ctrl+C 는 line abort 의미라 preedit *discard*. 다른
                    // Ctrl+key (Ctrl+A/E/L/D 등) 은 *commit* — 입력 중인 자모
                    // 보존 후 Ctrl char 발신 (native textbox / iTerm2 동등).
                    if (!ctrl_c) {
                        tab.queueWrite(g_preedit_buf[0..g_preedit_len]);
                    }
                    const get_ic = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
                    const ic = get_ic(self_view, objc.sel("inputContext"));
                    if (ic != null) {
                        const discard = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) void);
                        discard(ic, objc.sel("discardMarkedText"));
                    }
                    g_marked_len = 0;
                    g_preedit_len = 0;
                    clearHanjaState();
                }
                // Ctrl+C (SIGINT) 만 큐 우회 + 큐 reset — paste 등으로 가득찬
                // write_queue 뒤에 enqueue 되면 셸이 SIGINT 늦게 받아 "Ctrl+C
                // 안 먹힌다" 로 보임.
                if (ctrl_c) {
                    tab.interruptWrite(cstr[0..len]);
                    // #242 — Ctrl+C 도 사용자 입력 → 맨 아래로(^C/새 prompt 보이게).
                    // interruptWrite 는 즉시 SIGINT 경로라 writeUserInput(queue) 대신
                    // scroll 만 별도.
                    tab.terminal.scrollViewport(.{ .bottom = {} });
                } else {
                    writeUserInput(tab, cstr[0..len]);
                }
                return;
            }
        }
    }

    // IME 가 조합 중이 아니면 화살표 / F-key / nav 는 직접 escape sequence
    // (성능 + 정확성). 조합 중이면 interpretKeyEvents 로 보내 IME 가 음절
    // commit 후 doCommandBySelector 로 우리에게 위임 — 우리 imeDoCommand 가
    // escape sequence write.
    if (g_marked_len == 0) {
        // Esc — emoji picker 가 떠 있으면 dismiss (#130 follow-up). modifier
        // 없는 단순 Esc 만 — Cmd / ctrl 은 위 분기에서 처리 끝 (cmd 는 mainMenu,
        // ctrl-only 는 PTY 직송). shift / option 도 없을 때만. picker 의 visibility
        // 는 `isEmojiPickerOpen()` 이 NSApp.orderedWindows 직접 query — boolean
        // 추적의 stale 문제 회피.
        if (keycode == 53 and !shift and (flags & NSEventModifierFlagOption) == 0 and isEmojiPickerOpen()) {
            const orderFront = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
            orderFront(g_app, objc.sel("orderFrontCharacterPalette:"), null);
            return;
        }

        // Shift+PgUp / Shift+PgDn — viewport scrollback. Windows
        // `session_core.scrollActive` 와 같은 *한 페이지 (visible rows)* 단위.
        // PTY 로 안 흘림.
        if (shift) {
            const rows: isize = @intCast(tab.terminal.rows);
            if (keycode == 116) { // kVK_PageUp — 위쪽 (older).
                tab.terminal.scrollViewport(.{ .delta = -rows });
                return;
            }
            if (keycode == 121) { // kVK_PageDown — 아래쪽 (newer).
                tab.terminal.scrollViewport(.{ .delta = rows });
                return;
            }
        }

        if (keyCodeToEscape(keycode)) |esc| {
            writeUserInput(tab, esc);
            return;
        }
    }

    // preedit 활성 + nav 키 (Home/End/Arrows/PgUp/PgDn 등) — interpretKeyEvents
    // 가 Home/End 같은 일부 키에 doCommandBySelector dispatch 안 하는 케이스
    // (IME 가 finalize 만 하고 selector 안 보냄). 직접 keyCode 검사 후 preedit
    // commit + escape 발신.
    if (g_marked_len > 0) {
        const get_keycode2 = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_ushort);
        const keycode2 = get_keycode2(event, objc.sel("keyCode"));
        if (keyCodeToEscape(keycode2)) |esc| {
            if (g_hanja_candidate_active) {
                interpretSingleKeyEvent(self_view, event);
                return;
            }
            commitPreeditToPty(self_view);
            writeUserInput(tab, esc);
            return;
        }
    }

    interpretSingleKeyEvent(self_view, event);
}

// IME (NSTextInputClient) 상태 — 조합 중 (preedit) 텍스트 buffer.
const NSRange = extern struct { location: usize, length: usize };
const CGRect = extern struct { x: f64, y: f64, w: f64, h: f64 };
const NSNotFound: usize = @as(usize, @intCast(std.math.maxInt(isize)));
var g_marked_len: usize = 0;
var g_marked_selected_range: NSRange = .{ .location = 0, .length = 0 };
var g_preedit_buf: [128]u8 = undefined;
var g_preedit_len: usize = 0;
var g_hanja_reconversion_active: bool = false;
var g_hanja_reconversion_range: NSRange = .{ .location = 0, .length = 0 };
var g_hanja_reconversion_delete_count: usize = 0;
var g_hanja_candidate_active: bool = false;
var g_hanja_candidate_range: NSRange = .{ .location = 0, .length = 0 };
var g_hanja_candidate_delete_count: usize = 0;
var g_hanja_preedit_commit_requested: bool = false;
var g_hanja_pending_commit_active: bool = false;
var g_hanja_pending_commit_buf: [128]u8 = undefined;
var g_hanja_pending_commit_len: usize = 0;
var g_hanja_pending_commit_range: NSRange = .{ .location = 0, .length = 0 };
var g_hanja_pending_commit_delete_count: usize = 0;
var g_ime_panel_window_lowered: bool = false;

const ImeRectPx = struct {
    x: f32,
    y: f32,
    w: f32,
    h: f32,
};

const ImeSnapshot = struct {
    text: std.ArrayList(u8) = .{},
    utf16_to_byte: std.ArrayList(usize) = .{},
    positions: std.ArrayList(ImeRectPx) = .{},
    selected: NSRange = .{ .location = 0, .length = 0 },

    fn deinit(self: *ImeSnapshot, allocator: std.mem.Allocator) void {
        self.text.deinit(allocator);
        self.utf16_to_byte.deinit(allocator);
        self.positions.deinit(allocator);
    }

    fn utf16Len(self: *const ImeSnapshot) usize {
        return if (self.utf16_to_byte.items.len == 0) 0 else self.utf16_to_byte.items.len - 1;
    }

    fn initPositions(self: *ImeSnapshot, allocator: std.mem.Allocator, initial: ImeRectPx) !void {
        try self.utf16_to_byte.append(allocator, 0);
        try self.positions.append(allocator, initial);
    }

    fn appendCodepoint(self: *ImeSnapshot, allocator: std.mem.Allocator, cp: u21, start: ImeRectPx, end: ImeRectPx) !void {
        var encoded: [4]u8 = undefined;
        const encoded_len = try std.unicode.utf8Encode(cp, &encoded);
        const byte_start = self.text.items.len;
        try self.text.appendSlice(allocator, encoded[0..encoded_len]);
        const byte_end = self.text.items.len;

        const units: usize = if (cp >= 0x10000) 2 else 1;
        for (0..units) |i| {
            const is_last = i + 1 == units;
            try self.utf16_to_byte.append(allocator, if (is_last) byte_end else byte_start);
            try self.positions.append(allocator, if (is_last) end else start);
        }
    }

    fn appendCluster(self: *ImeSnapshot, allocator: std.mem.Allocator, base: u21, extras: []const u21, start: ImeRectPx, end: ImeRectPx) !void {
        if (extras.len == 0) {
            try self.appendCodepoint(allocator, base, start, end);
            return;
        }
        try self.appendCodepoint(allocator, base, start, start);
        for (extras, 0..) |cp, i| {
            try self.appendCodepoint(allocator, cp, start, if (i + 1 == extras.len) end else start);
        }
    }

    fn clampRange(self: *const ImeSnapshot, proposed: NSRange) NSRange {
        const len = self.utf16Len();
        if (proposed.location == NSNotFound) return .{ .location = @min(self.selected.location, len), .length = 0 };
        const start = @min(proposed.location, len);
        const available = len - start;
        const wanted = if (proposed.length > available) available else proposed.length;
        return .{ .location = start, .length = wanted };
    }
};

fn isValidRange(range: NSRange) bool {
    return range.location != NSNotFound;
}

fn isReplacingRange(range: NSRange) bool {
    return isValidRange(range) and range.length > 0;
}

fn clearHanjaReconversionTarget() void {
    g_hanja_reconversion_active = false;
    g_hanja_reconversion_range = .{ .location = 0, .length = 0 };
    g_hanja_reconversion_delete_count = 0;
}

fn clearHanjaCandidateTarget() void {
    const was_active = g_hanja_candidate_active;
    g_hanja_candidate_active = false;
    g_hanja_candidate_range = .{ .location = 0, .length = 0 };
    g_hanja_candidate_delete_count = 0;
    if (was_active) restoreWindowLevelAfterImePanel();
}

fn clearHanjaPendingCommit() void {
    g_hanja_pending_commit_active = false;
    g_hanja_pending_commit_len = 0;
    g_hanja_pending_commit_range = .{ .location = 0, .length = 0 };
    g_hanja_pending_commit_delete_count = 0;
}

fn clearHanjaState() void {
    clearHanjaReconversionTarget();
    clearHanjaCandidateTarget();
    clearHanjaPendingCommit();
    restoreWindowLevelAfterImePanel();
}

fn cancelHanjaState() void {
    clearImeMarkedState();
    clearHanjaState();
}

fn setMainWindowLevel(level: c_int) void {
    if (g_window == null) return;
    const setLevel = objc.objcSend(fn (objc.id, objc.SEL, c_int) callconv(.c) void);
    setLevel(g_window, objc.sel("setLevel:"), level);
}

fn setPopupWindowLevel() void {
    const NSPopUpMenuWindowLevel: c_int = 101;
    setMainWindowLevel(NSPopUpMenuWindowLevel);
    g_ime_panel_window_lowered = false;
}

fn lowerWindowForImePanel() void {
    // Candidate panels sit below TildaZ's drop-down popup level. Lower only
    // while the IME asks for a candidate anchor rect, not when Option+Return
    // is merely pressed.
    const NSFloatingWindowLevel: c_int = 3;
    setMainWindowLevel(NSFloatingWindowLevel);
    g_ime_panel_window_lowered = true;
}

fn restoreWindowLevelAfterImePanel() void {
    if (!g_ime_panel_window_lowered) return;
    setPopupWindowLevel();
}

fn utf16LenOfUtf8Prefix(text: []const u8, byte_limit: usize) usize {
    var len: usize = 0;
    var iter = std.unicode.Utf8Iterator{ .bytes = text, .i = 0 };
    while (iter.i < byte_limit) {
        const before = iter.i;
        const cp = iter.nextCodepoint() orelse break;
        if (before >= byte_limit) break;
        len += if (cp >= 0x10000) 2 else 1;
        if (iter.i >= byte_limit) break;
    }
    return len;
}

fn isHangulSyllable(cp: u21) bool {
    return cp >= 0xAC00 and cp <= 0xD7A3;
}

fn isOnlyHangulSyllables(text: []const u8) bool {
    var saw = false;
    var iter = std.unicode.Utf8Iterator{ .bytes = text, .i = 0 };
    while (iter.nextCodepoint()) |cp| {
        if (!isHangulSyllable(cp)) return false;
        saw = true;
    }
    return saw;
}

fn hangulRunBeforeCursor(text: []const u8, cursor_utf16: usize) ?NSRange {
    var iter = std.unicode.Utf8Iterator{ .bytes = text, .i = 0 };
    var utf16_pos: usize = 0;
    var run_start: ?usize = null;
    var run_end: usize = 0;

    while (iter.nextCodepoint()) |cp| {
        const units: usize = if (cp >= 0x10000) 2 else 1;
        const start = utf16_pos;
        const end = start + units;
        if (end > cursor_utf16) break;

        if (isHangulSyllable(cp)) {
            if (run_start == null or start != run_end) run_start = start;
            run_end = end;
        } else {
            run_start = null;
            run_end = end;
        }
        utf16_pos = end;
    }

    const start = run_start orelse return null;
    if (run_end != cursor_utf16 or run_end <= start) return null;
    return .{ .location = start, .length = run_end - start };
}

test "hangul run before cursor selects contiguous syllables" {
    const text = "abc 한국";
    const cursor = utf16LenOfUtf8Prefix(text, text.len);
    const range = hangulRunBeforeCursor(text, cursor).?;
    try std.testing.expectEqual(@as(usize, 4), range.location);
    try std.testing.expectEqual(@as(usize, 2), range.length);
}

test "hangul run before cursor ignores non-hangul suffix" {
    const text = "가x";
    const cursor = utf16LenOfUtf8Prefix(text, text.len);
    try std.testing.expect(hangulRunBeforeCursor(text, cursor) == null);
}

fn storeHanjaPendingCommit(commit: []const u8, range_start: usize) bool {
    if (commit.len == 0 or commit.len > g_hanja_pending_commit_buf.len) return false;
    const range_len = utf16LenOfUtf8Prefix(commit, commit.len);
    if (range_len == 0) return false;
    @memcpy(g_hanja_pending_commit_buf[0..commit.len], commit);
    g_hanja_pending_commit_len = commit.len;
    g_hanja_pending_commit_range = .{ .location = range_start, .length = range_len };
    g_hanja_pending_commit_delete_count = utf8CodepointCount(commit);
    g_hanja_pending_commit_active = true;
    return true;
}

fn appendUtf8ToSnapshot(
    allocator: std.mem.Allocator,
    snap: *ImeSnapshot,
    text: []const u8,
    start_x: f32,
    y: f32,
    cw: f32,
    ch: f32,
) !f32 {
    var x = start_x;
    var iter = std.unicode.Utf8Iterator{ .bytes = text, .i = 0 };
    while (iter.nextCodepoint()) |cp| {
        const advance = @as(f32, @floatFromInt(display_width.codepointWidth(cp))) * cw;
        const start = ImeRectPx{ .x = x, .y = y, .w = @max(advance, cw), .h = ch };
        x += advance;
        const end = ImeRectPx{ .x = x, .y = y, .w = cw, .h = ch };
        try snap.appendCodepoint(allocator, cp, start, end);
    }
    return x;
}

fn appendPendingHanjaCommitToSnapshot(
    allocator: std.mem.Allocator,
    snap: *ImeSnapshot,
    start_x: f32,
    y: f32,
    cw: f32,
    ch: f32,
) !f32 {
    if (!g_hanja_pending_commit_active or g_hanja_pending_commit_len == 0) return start_x;
    return appendUtf8ToSnapshot(
        allocator,
        snap,
        g_hanja_pending_commit_buf[0..g_hanja_pending_commit_len],
        start_x,
        y,
        cw,
        ch,
    );
}

fn beginHanjaReconversionTarget() bool {
    var snap = buildImeSnapshot(g_gpa.allocator()) orelse return false;
    defer snap.deinit(g_gpa.allocator());

    const cursor = @min(snap.selected.location + snap.selected.length, snap.utf16Len());
    const range = hangulRunBeforeCursor(snap.text.items, cursor) orelse return false;
    g_hanja_reconversion_range = range;
    if (replacementByteRange(&snap, range)) |r| {
        g_hanja_reconversion_delete_count = utf8CodepointCount(snap.text.items[r.byte_start..r.byte_end]);
    } else {
        g_hanja_reconversion_delete_count = range.length;
    }
    g_hanja_reconversion_active = true;
    return true;
}

fn nsAttributedStringFromUtf8(text: []const u8) objc.id {
    const NSString = objc.getClass("NSString");
    const stringWithBytes = objc.objcSend(fn (objc.Class, objc.SEL, [*]const u8, usize, c_ulong) callconv(.c) objc.id);
    const empty: [1]u8 = .{0};
    const ptr = if (text.len > 0) text.ptr else empty[0..0].ptr;
    const ns_text = stringWithBytes(NSString, objc.sel("stringWithBytes:length:encoding:"), ptr, text.len, NSUTF8StringEncoding);
    if (ns_text == null) return null;

    const NSAttributedString = objc.getClass("NSAttributedString");
    const alloc = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const initWithString = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) objc.id);
    const obj = initWithString(alloc(NSAttributedString, objc.sel("alloc")) orelse return null, objc.sel("initWithString:"), ns_text);
    if (obj == null) return null;
    const autorelease = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    return autorelease(obj, objc.sel("autorelease"));
}

fn localTopDownPxToScreenRect(self_view: objc.id, rect: ImeRectPx) CGRect {
    if (g_renderer == null or self_view == null) return .{ .x = 0, .y = 0, .w = 0, .h = 0 };
    const scale = g_renderer.?.scale;
    const get_rect = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) NSRect);
    const bounds = get_rect(self_view, objc.sel("bounds"));
    const local = NSRect{
        .origin = .{
            .x = @as(f64, @floatCast(rect.x / scale)),
            .y = bounds.size.height - @as(f64, @floatCast((rect.y + rect.h) / scale)),
        },
        .size = .{
            .width = @as(f64, @floatCast(rect.w / scale)),
            .height = @as(f64, @floatCast(rect.h / scale)),
        },
    };

    const convertRect = objc.objcSend(fn (objc.id, objc.SEL, NSRect, objc.id) callconv(.c) NSRect);
    const window_rect = convertRect(self_view, objc.sel("convertRect:toView:"), local, @as(objc.id, null));
    const get_window = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    var window = get_window(self_view, objc.sel("window"));
    if (window == null) window = g_window;
    if (window == null) return .{ .x = 0, .y = 0, .w = 0, .h = 0 };

    const convertToScreen = objc.objcSend(fn (objc.id, objc.SEL, NSRect) callconv(.c) NSRect);
    const screen_rect = convertToScreen(window, objc.sel("convertRectToScreen:"), window_rect);
    return .{
        .x = screen_rect.origin.x,
        .y = screen_rect.origin.y,
        .w = screen_rect.size.width,
        .h = screen_rect.size.height,
    };
}

fn screenPointToLocalTopDownPx(self_view: objc.id, point: NSPoint) ?struct { x: f32, y: f32 } {
    if (g_renderer == null or self_view == null) return null;
    const get_window = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    var window = get_window(self_view, objc.sel("window"));
    if (window == null) window = g_window;
    if (window == null) return null;

    const convertFromScreen = objc.objcSend(fn (objc.id, objc.SEL, NSRect) callconv(.c) NSRect);
    const window_rect = convertFromScreen(window, objc.sel("convertRectFromScreen:"), .{
        .origin = point,
        .size = .{ .width = 0, .height = 0 },
    });
    const convertPoint = objc.objcSend(fn (objc.id, objc.SEL, NSPoint, objc.id) callconv(.c) NSPoint);
    const view_point = convertPoint(self_view, objc.sel("convertPoint:fromView:"), window_rect.origin, @as(objc.id, null));
    const get_rect = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) NSRect);
    const bounds = get_rect(self_view, objc.sel("bounds"));
    const scale = g_renderer.?.scale;
    return .{
        .x = @as(f32, @floatCast(view_point.x)) * scale,
        .y = @as(f32, @floatCast(bounds.size.height - view_point.y)) * scale,
    };
}

/// 활성 탭 cursor row 를 NSTextInputClient 용 snapshot 으로 채운다. 실패 시
/// `snap` 은 *부분 생성 상태* 로 남으므로 호출자(`buildImeSnapshot`)가 정리한다.
fn fillImeSnapshot(allocator: std.mem.Allocator, snap: *ImeSnapshot) !bool {
    if (g_renderer == null) return false;
    const tab = g_session.activeTab() orelse return false;
    var r = &g_renderer.?;
    try r.render_state.update(allocator, &tab.terminal);
    const vp = r.render_state.cursor.viewport orelse return false;

    const row_slice = r.render_state.row_data.slice();
    const all_cells = row_slice.items(.cells);
    if (vp.y >= all_cells.len) return false;
    const cells = all_cells[vp.y].slice();
    const raws = cells.items(.raw);
    const graphemes = cells.items(.grapheme);

    const cw: f32 = @floatFromInt(r.font.cell_width_px);
    const ch: f32 = @floatFromInt(r.font.cell_height_px);
    const pad_px: f32 = ui_metrics.scaledPxF(TERMINAL_PADDING_PT, r.scale);
    const tab_bar_px: f32 = @floatFromInt(tabBarHeightPx(r.scale));
    const row_y = pad_px + tab_bar_px + @as(f32, @floatFromInt(vp.y)) * ch;
    const cursor_col: usize = if (vp.wide_tail and vp.x > 0) vp.x - 1 else vp.x;

    var last_text_end: usize = 0;
    for (raws, 0..) |raw, x| {
        if (raw.hasText() and raw.wide != .spacer_tail and raw.wide != .spacer_head and raw.codepoint() != 0) {
            const width: usize = if (raw.wide == .wide) 2 else 1;
            last_text_end = @max(last_text_end, x + width);
        }
    }
    const limit = @min(@max(last_text_end, cursor_col), raws.len);

    snap.* = .{};
    try snap.initPositions(allocator, .{
        .x = pad_px,
        .y = row_y,
        .w = cw,
        .h = ch,
    });

    var selected_set = false;
    var pending_hanja_inserted = false;
    var x: usize = 0;
    while (x < limit) {
        if (!selected_set and cursor_col <= x) {
            snap.selected = .{ .location = snap.utf16Len(), .length = 0 };
            selected_set = true;
            const insert_x = pad_px + @as(f32, @floatFromInt(cursor_col)) * cw;
            _ = try appendPendingHanjaCommitToSnapshot(allocator, snap, insert_x, row_y, cw, ch);
            pending_hanja_inserted = true;
        }

        const raw = raws[x];
        const cell_x = pad_px + @as(f32, @floatFromInt(x)) * cw;
        if (raw.hasText() and raw.wide != .spacer_tail and raw.wide != .spacer_head and raw.codepoint() != 0) {
            const width_cells: usize = if (raw.wide == .wide) 2 else 1;
            const start = ImeRectPx{ .x = cell_x, .y = row_y, .w = @as(f32, @floatFromInt(width_cells)) * cw, .h = ch };
            const end = ImeRectPx{ .x = cell_x + @as(f32, @floatFromInt(width_cells)) * cw, .y = row_y, .w = cw, .h = ch };
            const extras = if (raw.hasGrapheme() and x < graphemes.len) graphemes[x] else &.{};
            try snap.appendCluster(allocator, raw.codepoint(), extras, start, end);
            x += width_cells;
            continue;
        }

        const start = ImeRectPx{ .x = cell_x, .y = row_y, .w = cw, .h = ch };
        const end = ImeRectPx{ .x = cell_x + cw, .y = row_y, .w = cw, .h = ch };
        try snap.appendCodepoint(allocator, ' ', start, end);
        x += 1;
    }

    if (!selected_set) {
        snap.selected = .{ .location = snap.utf16Len(), .length = 0 };
    }
    if (!pending_hanja_inserted) {
        const insert_x = pad_px + @as(f32, @floatFromInt(cursor_col)) * cw;
        _ = try appendPendingHanjaCommitToSnapshot(allocator, snap, insert_x, row_y, cw, ch);
    }
    return true;
}

/// NSTextInputClient 진입점들의 공용 snapshot 빌더. 실패하면 부분 생성물을
/// 정리하고 null.
///
/// `fillImeSnapshot` 과 분리된 채로 둔다 — 이 정리 계약을 한 함수로 합칠 수 없다.
/// `errdefer` 는 `error` 반환에만 걸리고 `return null` 에는 안 걸리므로, 합치면
/// 실패 경로마다 수동 deinit 을 흩뿌려야 하고 하나 빠지면 누수다. (#341 로 rename
/// snapshot 분기가 사라져 호출 대상이 하나뿐이지만, 그게 병합 근거는 아니다.)
fn buildImeSnapshot(allocator: std.mem.Allocator) ?ImeSnapshot {
    var snap = ImeSnapshot{};
    if (fillImeSnapshot(allocator, &snap) catch false) return snap;
    snap.deinit(allocator);
    return null;
}

fn markedRangeStart() usize {
    var snap = buildImeSnapshot(g_gpa.allocator()) orelse return 0;
    defer snap.deinit(g_gpa.allocator());
    return @min(snap.selected.location, snap.utf16Len());
}

fn clearImeMarkedState() void {
    g_marked_len = 0;
    g_marked_selected_range = .{ .location = 0, .length = 0 };
    g_preedit_len = 0;
}

fn replacementByteRange(snap: *const ImeSnapshot, replacement: NSRange) ?struct {
    range: NSRange,
    byte_start: usize,
    byte_end: usize,
} {
    if (replacement.location == NSNotFound) return null;
    const range = snap.clampRange(replacement);
    const byte_start = snap.utf16_to_byte.items[range.location];
    const byte_end = snap.utf16_to_byte.items[range.location + range.length];
    return .{
        .range = range,
        .byte_start = byte_start,
        .byte_end = @max(byte_start, byte_end),
    };
}

fn utf8CodepointCount(bytes: []const u8) usize {
    // #298 — 자체 Utf8Iterator 루프 → std. 입력은 내부 생성 valid UTF-8 이라
    // 실패 경로 없음(만약을 위해 byte 수 fallback — never-fail 계약 유지).
    return std.unicode.utf8CountCodepoints(bytes) catch bytes.len;
}

fn queueBackspaces(tab: anytype, count: usize) void {
    var remaining = count;
    const chunk = [_]u8{0x7f} ** 32;
    while (remaining > 0) {
        const n = @min(remaining, chunk.len);
        tab.queueWrite(chunk[0..n]);
        remaining -= n;
    }
}

/// #242 — 사용자 키 입력을 PTY 로 보내고 viewport 를 맨 아래로 (scroll-on-keystroke).
/// Linux/Windows 의 `session_core.queueInputToActive` 와 동등 — macOS parity
/// (SPEC §0). scroll-on-output(program 출력) / terminal 자동응답 write 와 구분해
/// *사용자 키 입력* 경로에서만 호출한다. macOS 60fps render timer 가 viewport
/// 변화를 다음 프레임에 반영하므로 별도 redraw 트리거 불필요(휠 스크롤과 동일).
fn writeUserInput(tab: anytype, bytes: []const u8) void {
    tab.queueWrite(bytes);
    tab.terminal.scrollViewport(.{ .bottom = {} });
}

/// NSAttributedString 이거나 NSString 인 input → NSString 추출.
fn imeStringFromInput(text: objc.id) objc.id {
    if (text == null) return text;
    const NSAttributedString = objc.getClass("NSAttributedString");
    const isKindOf = objc.objcSend(fn (objc.id, objc.SEL, objc.Class) callconv(.c) bool);
    if (isKindOf(text, objc.sel("isKindOfClass:"), NSAttributedString)) {
        const get_str = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
        return get_str(text, objc.sel("string"));
    }
    return text;
}

/// IME 가 글자 commit 시 호출 (한글 음절 완성, 일본어 conversion 확정 등).
/// PTY 로 write + preedit buffer clear.
fn imeInsertText(_: objc.id, _: objc.SEL, text: objc.id, replacement: NSRange) callconv(.c) void {
    requestRender(); // #255 Phase2
    const tab = g_session.activeTab() orelse return;
    const str = imeStringFromInput(text);
    if (str == null) {
        clearImeMarkedState();
        clearHanjaState();
        return;
    }
    const get_len = objc.objcSend(fn (objc.id, objc.SEL, usize) callconv(.c) usize);
    const len = get_len(str, objc.sel("lengthOfBytesUsingEncoding:"), NSUTF8StringEncoding);
    if (len == 0) {
        clearImeMarkedState();
        clearHanjaState();
        return;
    }
    const get_utf8 = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) [*:0]const u8);
    const cstr = get_utf8(str, objc.sel("UTF8String"));
    const commit = cstr[0..len];

    var snap = buildImeSnapshot(g_gpa.allocator());
    defer if (snap) |*s| s.deinit(g_gpa.allocator());
    const should_reconvert_committed_preedit = g_hanja_preedit_commit_requested and isOnlyHangulSyllables(commit);
    const pending_range_start = if (snap) |*s| @min(s.selected.location, s.utf16Len()) else 0;
    const candidate_delete_count = if (g_hanja_candidate_active) g_hanja_candidate_delete_count else 0;
    clearImeMarkedState();
    if (should_reconvert_committed_preedit) {
        _ = storeHanjaPendingCommit(commit, pending_range_start);
    }
    if (candidate_delete_count > 0) {
        queueBackspaces(tab, candidate_delete_count);
    } else if (snap) |*s| {
        if (replacementByteRange(s, replacement)) |r| {
            // 터미널은 arbitrary range edit API 가 없으므로, IME 가 보통 한자 변환
            // 시 보내는 "cursor 직전 텍스트 치환" 만 안전하게 backspace+insert 로
            // 구현한다. 그 외 range 는 기존 입력 보존을 위해 단순 insert 로 fallback.
            if (r.range.length > 0 and r.range.location + r.range.length == s.selected.location) {
                const delete_count = utf8CodepointCount(s.text.items[r.byte_start..r.byte_end]);
                queueBackspaces(tab, delete_count);
            }
        }
    }
    writeUserInput(tab, commit);
    if (!should_reconvert_committed_preedit) clearHanjaState();
}

/// NSResponder 의 1-arg insertText: (legacy). 일부 IME 가 이걸 호출.
fn imeInsertTextSimple(self_view: objc.id, sel_: objc.SEL, text: objc.id) callconv(.c) void {
    imeInsertText(self_view, sel_, text, .{ .location = NSNotFound, .length = 0 });
}

/// IME 조합 중 텍스트 — preedit buffer 에 저장. PTY 에는 안 보냄. metal
/// renderer 가 cursor 위치 위에 overlay (M6.2).
fn imeSetMarkedText(_: objc.id, _: objc.SEL, text: objc.id, selected_range: NSRange, replacement_range: NSRange) callconv(.c) void {
    requestRender(); // #255 Phase2 — preedit 변경 → 렌더.
    const reconversion_delete_count = g_hanja_reconversion_delete_count;
    clearHanjaReconversionTarget();
    const str = imeStringFromInput(text);
    if (str == null) {
        clearImeMarkedState();
        clearHanjaState();
        return;
    }
    const get_length = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) usize);
    g_marked_len = get_length(str, objc.sel("length"));
    g_marked_selected_range = selected_range;

    const get_len = objc.objcSend(fn (objc.id, objc.SEL, usize) callconv(.c) usize);
    const len = get_len(str, objc.sel("lengthOfBytesUsingEncoding:"), NSUTF8StringEncoding);
    if (len == 0) {
        clearImeMarkedState();
        clearHanjaState();
        return;
    }
    const get_utf8 = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) [*:0]const u8);
    const cstr = get_utf8(str, objc.sel("UTF8String"));
    const copy_len = @min(len, g_preedit_buf.len);
    @memcpy(g_preedit_buf[0..copy_len], cstr[0..copy_len]);
    g_preedit_len = copy_len;
    // #242 — preedit(조합 중)도 사용자 입력 → 맨 아래로(scroll-on-keystroke).
    // composition 은 cursor(맨 아래 live line)에 inline 표시되므로, 스크롤백 올린
    // 상태에서 조합 시작 시 안 내려가면 자기 조합이 안 보임. commit 은
    // imeInsertText 가 scroll.
    g_session.scrollActiveToBottom();
    if (isReplacingRange(replacement_range)) {
        g_hanja_candidate_active = true;
        g_hanja_candidate_range = replacement_range;
        g_hanja_candidate_delete_count = if (reconversion_delete_count > 0)
            reconversion_delete_count
        else
            replacement_range.length;
    }
}

fn imeUnmarkText(_: objc.id, _: objc.SEL) callconv(.c) void {
    if (g_hanja_candidate_active) {
        cancelHanjaState();
        return;
    }
    clearImeMarkedState();
    clearHanjaState();
}

fn imeHasMarkedText(_: objc.id, _: objc.SEL) callconv(.c) bool {
    return g_marked_len > 0;
}

fn imeMarkedRange(_: objc.id, _: objc.SEL) callconv(.c) NSRange {
    if (g_marked_len > 0 and g_hanja_candidate_active) {
        return .{ .location = g_hanja_candidate_range.location, .length = g_marked_len };
    }
    if (g_marked_len > 0) return .{ .location = markedRangeStart(), .length = g_marked_len };
    return .{ .location = NSNotFound, .length = 0 };
}

fn imeSelectedRange(_: objc.id, _: objc.SEL) callconv(.c) NSRange {
    var snap = buildImeSnapshot(g_gpa.allocator()) orelse return .{ .location = 0, .length = 0 };
    defer snap.deinit(g_gpa.allocator());
    const base = @min(snap.selected.location, snap.utf16Len());
    if (g_marked_len == 0 and g_hanja_reconversion_active) {
        return snap.clampRange(g_hanja_reconversion_range);
    }
    if (g_marked_len == 0) return .{ .location = base, .length = snap.selected.length };

    const marked_sel_loc = if (g_marked_selected_range.location == NSNotFound)
        g_marked_len
    else
        @min(g_marked_selected_range.location, g_marked_len);
    const remaining = g_marked_len - marked_sel_loc;
    const marked_sel_len = @min(g_marked_selected_range.length, remaining);
    if (g_hanja_candidate_active) {
        const range = snap.clampRange(g_hanja_candidate_range);
        return .{ .location = range.location + marked_sel_loc, .length = marked_sel_len };
    }
    return .{ .location = base + marked_sel_loc, .length = marked_sel_len };
}

fn imeValidAttributes(_: objc.id, _: objc.SEL) callconv(.c) objc.id {
    const NSArray = objc.getClass("NSArray");
    const array = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    return array(NSArray, objc.sel("array"));
}

fn imeAttrSubstring(_: objc.id, _: objc.SEL, proposed: NSRange, actual: ?*NSRange) callconv(.c) objc.id {
    var snap = buildImeSnapshot(g_gpa.allocator()) orelse {
        if (actual) |a| a.* = .{ .location = NSNotFound, .length = 0 };
        return null;
    };
    defer snap.deinit(g_gpa.allocator());

    const range = snap.clampRange(proposed);
    if (actual) |a| a.* = range;
    const byte_start = snap.utf16_to_byte.items[range.location];
    const byte_end = snap.utf16_to_byte.items[range.location + range.length];
    return nsAttributedStringFromUtf8(snap.text.items[byte_start..@max(byte_start, byte_end)]);
}

fn imeCharIndex(self_view: objc.id, _: objc.SEL, point: NSPoint) callconv(.c) usize {
    var snap = buildImeSnapshot(g_gpa.allocator()) orelse return NSNotFound;
    defer snap.deinit(g_gpa.allocator());
    const local = screenPointToLocalTopDownPx(self_view, point) orelse return NSNotFound;
    const len = snap.utf16Len();
    if (snap.positions.items.len == 0) return NSNotFound;
    if (len == 0) {
        const p = snap.positions.items[0];
        return if (local.y >= p.y and local.y <= p.y + p.h) 0 else NSNotFound;
    }

    var row_match: ?usize = null;
    for (0..len) |i| {
        const p = snap.positions.items[i];
        const next = snap.positions.items[i + 1];
        if (local.y < p.y or local.y > p.y + p.h) continue;
        row_match = i + 1;
        const mid = (p.x + next.x) * 0.5;
        if (local.x < mid) return i;
    }
    return row_match orelse NSNotFound;
}

fn imeFirstRect(self_view: objc.id, _: objc.SEL, proposed: NSRange, actual: ?*NSRange) callconv(.c) CGRect {
    var snap = buildImeSnapshot(g_gpa.allocator()) orelse {
        if (actual) |a| a.* = .{ .location = NSNotFound, .length = 0 };
        return .{ .x = 0, .y = 0, .w = 0, .h = 0 };
    };
    defer snap.deinit(g_gpa.allocator());

    const range = snap.clampRange(proposed);
    if (actual) |a| a.* = range;
    const idx = @min(range.location, snap.positions.items.len - 1);
    if (g_hanja_reconversion_active or g_hanja_candidate_active) lowerWindowForImePanel();
    return localTopDownPxToScreenRect(self_view, snap.positions.items[idx]);
}

/// IME 가 모르는 special key (Return, Backspace, Tab, 화살표 등) 을
/// interpretKeyEvents 가 selector 형태로 보냄. escape sequence 매핑.
fn imeDoCommand(_: objc.id, _: objc.SEL, cmd_sel: objc.SEL) callconv(.c) void {
    requestRender(); // #255 Phase2
    const tab = g_session.activeTab() orelse return;

    if (g_hanja_candidate_active and cmd_sel == objc.sel("cancelOperation:")) {
        cancelHanjaState();
        return;
    }

    const bytes: ?[]const u8 = if (cmd_sel == objc.sel("insertNewline:"))
        "\r"
    else if (cmd_sel == objc.sel("insertTab:"))
        "\t"
    else if (cmd_sel == objc.sel("insertBacktab:"))
        "\x1b[Z"
    else if (cmd_sel == objc.sel("deleteBackward:"))
        "\x7f"
    else if (cmd_sel == objc.sel("deleteForward:"))
        "\x1b[3~"
    else if (cmd_sel == objc.sel("cancelOperation:"))
        "\x1b"
    else if (cmd_sel == objc.sel("moveUp:"))
        "\x1b[A"
    else if (cmd_sel == objc.sel("moveDown:"))
        "\x1b[B"
    else if (cmd_sel == objc.sel("moveLeft:"))
        "\x1b[D"
    else if (cmd_sel == objc.sel("moveRight:"))
        "\x1b[C"
        // Home/End 키 (preedit 활성 → IME finalize 후 nav selector 로 dispatch).
        // Document/Line/Paragraph 셋 다 매핑 — 사용자 키보드 / 키바인딩에 따라 다른
        // selector 가 dispatch 될 수 있음.
    else if (cmd_sel == objc.sel("moveToBeginningOfDocument:"))
        "\x1b[H"
    else if (cmd_sel == objc.sel("moveToEndOfDocument:"))
        "\x1b[F"
    else if (cmd_sel == objc.sel("moveToBeginningOfLine:"))
        "\x1b[H"
    else if (cmd_sel == objc.sel("moveToEndOfLine:"))
        "\x1b[F"
    else if (cmd_sel == objc.sel("moveToBeginningOfParagraph:"))
        "\x1b[H"
    else if (cmd_sel == objc.sel("moveToEndOfParagraph:"))
        "\x1b[F"
    else
        null;
    if (bytes) |b| {
        writeUserInput(tab, b);
    }
}

/// 모니터 / DPI / dock auto-hide / 해상도 변경 시 호출. NSApplicationDidChange
/// ScreenParameters / NSWindowDidChangeScreen / NSWindowDidChangeBackingProperties
/// notification 모두 같은 handler. 윈도우 frame 재계산 + layer / drawable /
/// renderer / Terminal / PTY 의 cols/rows 재동기화.
fn tildazScreenChanged(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    syncGeometryAfterScreenChange();
}

fn syncGeometryAfterScreenChange() void {
    requestRender(); // #255 Phase2 — 리사이즈/모니터 변경 → 렌더.
    if (g_renderer == null) return;
    const tab = g_session.activeTab() orelse return;

    // 1. 새 visibleFrame 기준으로 윈도우 위치 / 크기 재설정.
    repositionWindow();

    // 2. contentView bounds + backingScaleFactor 다시 읽기 (DPI 변경 시 scale
    //    바뀜). layer.frame / contentsScale / drawableSize 갱신.
    const get_cv = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    const content_view = get_cv(g_window, objc.sel("contentView")) orelse return;
    const get_rect = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) NSRect);
    const cv_bounds = get_rect(content_view, objc.sel("bounds"));
    const get_double = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) f64);
    const scale_pt = get_double(g_window, objc.sel("backingScaleFactor"));

    const set_layer_frame = objc.objcSend(fn (objc.id, objc.SEL, NSRect) callconv(.c) void);
    set_layer_frame(g_metal_layer, objc.sel("setFrame:"), cv_bounds);
    const set_contents_scale = objc.objcSend(fn (objc.id, objc.SEL, f64) callconv(.c) void);
    set_contents_scale(g_metal_layer, objc.sel("setContentsScale:"), scale_pt);
    const set_drawable_size = objc.objcSend(fn (objc.id, objc.SEL, NSSize) callconv(.c) void);
    set_drawable_size(g_metal_layer, objc.sel("setDrawableSize:"), .{
        .width = cv_bounds.size.width * scale_pt,
        .height = cv_bounds.size.height * scale_pt,
    });

    // 3. Renderer viewport 갱신 + (#253) scale 이 실제로 바뀌었으면 폰트 cell
    //    재측정 + glyph atlas 재구성 + renderer scale 갱신. 다른 scale(DPI) 모니터로
    //    이동하면 cell/glyph/UI metric 이 init scale 에 고정돼 글자·탭바가 배율만큼
    //    틀어지므로(Windows rebuildFontForDpi / Linux applyScale 동등) 여기서 보정.
    //    같은 scale 이동은 viewport 만 바꾸면 됨(atlas 재생성 낭비 회피).
    const vp_w_px: u32 = @intFromFloat(cv_bounds.size.width * scale_pt);
    const vp_h_px: u32 = @intFromFloat(cv_bounds.size.height * scale_pt);
    if (@as(f32, @floatCast(scale_pt)) != g_renderer.?.scale) {
        g_renderer.?.applyScale(@floatCast(scale_pt)) catch |err| {
            log.appendLine("geom", "applyScale failed: {s} — skipping cell re-measure", .{@errorName(err)});
        };
    }
    g_renderer.?.resize(vp_w_px, vp_h_px);

    // 4. 새 viewport 에 맞춰 cols/rows 재계산. cell 크기 같으면 viewport 만
    //    변경. ghostty Terminal + PTY 도 같은 cols/rows 로 resize.
    const grid = terminalGrid(vp_w_px, vp_h_px, @floatCast(scale_pt));
    const new_cols = grid.cols;
    const new_rows = grid.rows;

    // 모든 탭의 terminal+pty 를 같이 resize 해야 해요 — 보이지 않는 탭의 grid
    // 도 같은 cols/rows 로 유지 (탭 전환 시 화면 깨짐 방지).
    const active_terminal = tab.terminal;
    if (new_cols != active_terminal.cols or new_rows != active_terminal.rows) {
        for (g_session.tabs.items) |t| {
            t.terminal.resize(g_gpa.allocator(), new_cols, new_rows) catch |err| {
                log.appendLine("geom", "terminal resize failed: {s}", .{@errorName(err)});
                continue;
            };
            t.backend.resize(new_cols, new_rows) catch |err| {
                log.appendLine("geom", "pty resize failed: {s}", .{@errorName(err)});
            };
        }
        log.appendLine("geom", "screen changed: vp={d}x{d}px scale={d:.2} cols={d} rows={d}", .{
            vp_w_px, vp_h_px, scale_pt, new_cols, new_rows,
        });
    }
}

/// NSEvent 위치 → 윈도우 좌상단 기준 pixel 좌표 (top-down). 탭바 / cell hit
/// test 에서 공용. 윈도우 밖이면 그대로 반환 (호출처가 음수 / 초과 처리).
fn eventToWindowPx(self_view: objc.id, event: objc.id) struct { x: f32, y: f32 } {
    const get_loc = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) NSPoint);
    const win_loc = get_loc(event, objc.sel("locationInWindow"));
    const convertPoint = objc.objcSend(fn (objc.id, objc.SEL, NSPoint, objc.id) callconv(.c) NSPoint);
    const view_loc = convertPoint(self_view, objc.sel("convertPoint:fromView:"), win_loc, @as(objc.id, null));

    const get_rect = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) NSRect);
    const cv_bounds = get_rect(self_view, objc.sel("bounds"));
    const view_h_pt = cv_bounds.size.height;
    const scale = if (g_renderer) |*r| r.scale else 1.0;

    return .{
        .x = @as(f32, @floatCast(view_loc.x)) * scale,
        .y = @as(f32, @floatCast(view_h_pt - view_loc.y)) * scale,
    };
}

/// NSEvent 의 window 좌표 (Y-up) → terminal grid cell 좌표.
/// `null` = window 밖 또는 padding 영역.
fn eventToCell(self_view: objc.id, event: objc.id) ?terminal_interaction.Cell {
    if (g_renderer == null) return null;
    const tab = g_session.activeTab() orelse return null;

    const xy = eventToWindowPx(self_view, event);
    const scale = g_renderer.?.scale;
    const cell_w_px = g_renderer.?.font.cell_width_px;
    const cell_h_px = g_renderer.?.font.cell_height_px;
    const pad_px: f32 = ui_metrics.scaledPxF(TERMINAL_PADDING_PT, scale);
    const tab_bar_px: f32 = @floatFromInt(tabBarHeightPx(scale));
    const cell_top_px = pad_px + tab_bar_px;

    // 탭바 영역 + padding 안쪽만 cell. 밖이면 null (탭바 클릭은 별도 dispatch).
    if (xy.x < pad_px or xy.y < cell_top_px) return null;
    const x_in: f32 = xy.x - pad_px;
    const y_in: f32 = xy.y - cell_top_px;

    const col_f = x_in / @as(f32, @floatFromInt(cell_w_px));
    const row_f = y_in / @as(f32, @floatFromInt(cell_h_px));
    if (col_f < 0 or row_f < 0) return null;

    const cols = tab.terminal.cols;
    const rows = tab.terminal.rows;
    const col: u16 = @intCast(@min(@as(u32, @intFromFloat(col_f)), @as(u32, cols) - 1));
    const row: u16 = @intCast(@min(@as(u32, @intFromFloat(row_f)), @as(u32, rows) - 1));
    return .{ .col = col, .row = row };
}

/// #245 — drag px → (clamp 된 선택 cell, 경계 방향). `eventToCell`(클릭용, 위/왼쪽
/// 경계 null)과 달리 경계 밖이어도 가장자리로 clamp + 위/아래 경계 dir 반환. event
/// 없이 px 만 받아 mouseDragged 와 렌더-타이머 tick 둘 다 호출.
fn cellAndDirFromPx(x: f32, y: f32) ?struct { cell: terminal_interaction.Cell, dir: i8 } {
    if (g_renderer == null) return null;
    const tab = g_session.activeTab() orelse return null;
    const scale = g_renderer.?.scale;
    const cell_w_px = g_renderer.?.font.cell_width_px;
    const cell_h_px = g_renderer.?.font.cell_height_px;
    const pad_px: f32 = ui_metrics.scaledPxF(TERMINAL_PADDING_PT, scale);
    const tab_bar_px: f32 = @floatFromInt(tabBarHeightPx(scale));
    const cell_top_px = pad_px + tab_bar_px;
    const col_i: i32 = @intFromFloat(@floor((x - pad_px) / @as(f32, @floatFromInt(cell_w_px))));
    const row_i: i32 = @intFromFloat(@floor((y - cell_top_px) / @as(f32, @floatFromInt(cell_h_px))));
    return .{
        .cell = terminal_interaction.clampCell(col_i, row_i, tab.terminal.cols, tab.terminal.rows),
        .dir = terminal_interaction.edgeScrollDir(row_i, tab.terminal.rows),
    };
}

/// #245 — drag-select auto-scroll tick (mac, renderFrameTick 에서 매 frame 호출).
/// 포인터가 grid 경계 밖(dir!=0)이고 선택 활성이면 40ms 마다 viewport 한 step
/// 스크롤 + 마지막 drag px(clamp cell)로 selection.update → 멈춰 있어도 연속.
/// 이번 frame 에 스크롤했으면 true 반환(force render).
fn maybeAutoScrollSelectionMac() bool {
    if (g_sel_autoscroll_dir == 0) return false;
    const tab = g_session.activeTab() orelse {
        g_sel_autoscroll_dir = 0;
        return false;
    };
    if (!tab.interaction.selection.active) {
        g_sel_autoscroll_dir = 0;
        return false;
    }
    const now = std.time.milliTimestamp();
    if (now < g_sel_autoscroll_next_ms) return false;
    const step: isize = 3;
    tab.terminal.scrollViewport(.{ .delta = if (g_sel_autoscroll_dir < 0) -step else step });
    if (cellAndDirFromPx(g_last_drag_x, g_last_drag_y)) |sc| {
        tab.interaction.selection.update(tab.terminal.screens.active, sc.cell);
    }
    g_sel_autoscroll_next_ms = now + 40;
    return true;
}

const TabBarArea = tab_layout.Area;

/// 탭바 영역 hit-area 분기 (#117). 화살표 / `+` / `x` 영역에서는 별도 처리,
/// tab_area 안에서는 `tabBarTabHitTest` 가 탭 인덱스 계산.
fn tabBarHitArea(px: f32, py: f32, layout: TabBarLayout) TabBarArea {
    if (g_renderer == null) return .none;
    const r = &g_renderer.?;
    const tab_bar_h: f32 = @floatFromInt(tabBarHeightPx(r.scale));
    return tab_layout.hitArea(px, py, tab_bar_h, layout);
}

fn singleControlHit(px: f32, py: f32) TabBarArea {
    if (g_renderer == null or g_session.count() != 1) return .none;
    const h: f32 = @floatFromInt(scrollbarTopInsetPx(g_renderer.?.scale));
    return switch (tab_layout.hitArea(px, py, h, tabBarLayout())) {
        .plus, .close, .more => |a| a,
        else => .none,
    };
}

/// #329 — 현재 viewport / scroll 기준의 menu View (renderer 와 같은 계산).
/// 호출 전 `g_renderer != null` 확인 필수.
fn commandMenuViewNow() command_menu.View {
    const r = &g_renderer.?;
    return command_menu.view(
        @as(f32, @floatFromInt(r.vp_width)) / r.scale,
        @as(f32, @floatFromInt(r.vp_height)) / r.scale,
        @floatFromInt(ui_metrics.TAB_BAR_HEIGHT_PT),
        g_command_menu_first,
    );
}

/// #329 — 메뉴 닫기 공통 지점. focus / scroll 까지 초기화해 다음 열기가
/// 항상 처음 상태에서 시작한다.
fn closeCommandMenu() void {
    g_command_menu_open = false;
    g_command_menu_hover = null;
    g_command_menu_focus = null;
    g_command_menu_first = 0;
    g_command_menu_scroll_accum = 0;
    invalidateCursorRects();
    requestRender();
}

fn commandMenuHit(px: f32, py: f32) ?command_menu.Command {
    if (!g_command_menu_open or g_renderer == null) return null;
    const scale = g_renderer.?.scale;
    return command_menu.hit(commandMenuViewNow(), px / scale, py / scale);
}

/// #329 — 메뉴가 열린 동안의 키 입력. 모든 키를 메뉴 계층이 소비한다
/// (native menu 동등) — PTY 로 보내지 않는다.
fn handleCommandMenuKey(menu_key: command_menu.MenuKey) void {
    switch (command_menu.onKey(menu_key, &g_command_menu_focus)) {
        .consumed => {
            // #334 — 키보드를 쓰는 순간 pointer hover 강조를 지운다. 마우스가
            // 항목 위에 머물러 있으면 hover 가 focus 를 덮어 키보드 이동이
            // 화면에 안 보였다 (사용자 시연 발견). 마우스를 다시 움직이면
            // hover 가 재적용되며 focus 도 동기화된다.
            g_command_menu_hover = null;
            if (g_command_menu_focus) |focused| {
                if (g_renderer != null) {
                    const r = &g_renderer.?;
                    g_command_menu_first = command_menu.ensureVisible(
                        @as(f32, @floatFromInt(r.vp_width)) / r.scale,
                        @as(f32, @floatFromInt(r.vp_height)) / r.scale,
                        @floatFromInt(ui_metrics.TAB_BAR_HEIGHT_PT),
                        g_command_menu_first,
                        focused,
                    );
                }
            }
            requestRender();
        },
        .close => closeCommandMenu(),
        .activate => |command| {
            // keyboard 실행도 outside click 과 동일 — pending 입력 commit 후.
            if (g_window != null) {
                const contentView_get = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
                const cv = contentView_get(g_window, objc.sel("contentView"));
                if (cv != null) commitPendingInput(cv);
            }
            executeCommandMenu(command);
        },
    }
}

fn executeCommandMenu(command: command_menu.Command) void {
    closeCommandMenu();
    switch (command) {
        .toggle_visibility => toggleWindow(),
        .new_tab => handleNewTab(),
        .close_active_tab => handleCloseActiveTab(),
        .copy_selection => handleCopy(),
        .paste => handlePaste(),
        // #334 — 메뉴는 상태 기준 토글: 어떤 모드든 전체화면이면 그 모드를
        // 해제, 아니면 monitor 진입. 키보드의 self-symmetric(들어간 키로만
        // 나옴) 정책은 그대로 — workarea 상태에서 메뉴가 no-op 이던 문제.
        .fullscreen => toggleFullscreenMode(if (g_fullscreen_mode != .none) g_fullscreen_mode else .monitor),
        .open_config => {
            const allocator = g_gpa.allocator();
            const path = @import("../paths.zig").configPath(allocator) catch return;
            defer allocator.free(path);
            @import("../system_open.zig").openInDefaultApp(allocator, path);
        },
        .keyboard_shortcuts => @import("../system_open.zig").openInDefaultApp(g_gpa.allocator(), messages.keyboard_shortcuts_url),
        .about => about.showAboutDialog(),
    }
    requestRender();
}

/// tab_area 안에서 px → 탭 인덱스. 호출자가 먼저 hit-area 가 `.tab_area` 인지
/// 검사. (#268 — per-tab close 제거로 인덱스만.)
fn tabBarTabHitTest(px: f32, layout: TabBarLayout) ?usize {
    if (g_renderer == null) return null;
    const r = &g_renderer.?;
    const tab_w_px = ui_metrics.scaledPxF(ui_metrics.TAB_WIDTH_PT, r.scale);
    return tab_layout.hitTab(
        px,
        layout,
        tab_w_px,
        g_tab_scroll_x_px,
        @intCast(g_session.count()),
    );
}

/// IME preedit (g_preedit_buf) 을 활성 탭 PTY 로 commit + IME 상태 클리어.
/// 호출 후 typing 계속 가능. render 요청은 하지 않는다 — 호출자가 뒤이어
/// 화면을 바꾸는 경우(escape 송신 등)가 있어 `commitPendingInput` 이 그걸 맡는다.
fn commitPreeditToPty(self_view: objc.id) void {
    if (g_preedit_len == 0) return;
    g_session.queueInputToActive(g_preedit_buf[0..g_preedit_len]);
    g_preedit_len = 0;
    g_marked_len = 0;
    clearHanjaState();
    const get_ic = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    const ic = get_ic(self_view, objc.sel("inputContext"));
    if (ic != null) {
        const discard = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) void);
        discard(ic, objc.sel("discardMarkedText"));
    }
}

/// 진행 중인 IME preedit 을 활성 탭 PTY 로 확정 + IME 상태 클리어. focus
/// 이탈 / 단축키 등 "지금 멈춰" 시점에 호출. native textbox / Win IME 동등
/// 동작 (cancel 아님).
/// (#164 follow-up — mac Cocoa markedText 는 click / 단축키 시 자동 cancel 안 함)
fn commitPendingInput(self_view: objc.id) void {
    commitPreeditToPty(self_view);
    // NSMenu selector / applicationShouldTerminate: 는 keyDown:/mouseDown: 을
    // 우회한다. 내부 marked state 만 지우고 render 를 요청하지 않으면
    // 마지막 보라색 preedit frame 이 화면에 남으므로, 상태 변경의 공통 지점에서
    // 반드시 다음 frame 을 요청한다 (#317).
    requestRender();
}

/// #193 — OS mouse cursor shape. NSView 의 `resetCursorRects` override. SPEC.md
/// §3.1: cell 영역 → I-beam, 그 외 → arrow.
/// NSView default coordinate (Y-up, bottom-left origin) 라 paint 좌표계 (Y-down)
/// 와 flip 변환.
///
/// resetCursorRects 자동 호출 경로: view bounds 변경 (`setFrame:`) / mouse 가
/// view 위로 들어옴 / `[window invalidateCursorRectsForView:]`. command menu
/// 열림/닫힘 시 명시 invalidate 필요 (`invalidateCursorRects`).
fn tildazResetCursorRects(self_view: objc.id, _: objc.SEL) callconv(.c) void {
    const get_rect = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) NSRect);
    const bounds = get_rect(self_view, objc.sel("bounds"));
    const w: f64 = bounds.size.width;
    const h: f64 = bounds.size.height;

    // PT (logical points) — bounds 자체 PT 단위라 scale 곱 불필요.
    const pad: f64 = @floatFromInt(TERMINAL_PADDING_PT);
    const sbw: f64 = @floatFromInt(ui_metrics.SCROLLBAR_W_PT);
    const tab_bar_h_pt: f64 = if (g_session.count() < 2) 0 else @floatFromInt(TAB_BAR_HEIGHT_PT);

    const NSCursor = objc.getClass("NSCursor");
    const get_ibeam = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const ibeam = get_ibeam(NSCursor, objc.sel("IBeamCursor"));
    if (ibeam == null) return;
    const arrow = get_ibeam(NSCursor, objc.sel("arrowCursor"));
    const add_rect = objc.objcSend(fn (objc.id, objc.SEL, NSRect, objc.id) callconv(.c) void);

    // cell 영역 (Y-up): x=[pad, w-pad-sbw], y=[pad, h-tab_bar_h-pad].
    const cell_w = w - 2.0 * pad - sbw;
    const cell_h = h - tab_bar_h_pt - 2.0 * pad;
    if (cell_w > 0 and cell_h > 0) {
        const cell_rect = NSRect{
            .origin = .{ .x = pad, .y = pad },
            .size = .{ .width = cell_w, .height = cell_h },
        };
        add_rect(self_view, objc.sel("addCursorRect:cursor:"), cell_rect, ibeam);
    }

    // 단일 탭 control strip과 열린 command menu는 terminal 위 overlay라 cell
    // I-beam rect와 겹친다. 뒤에 arrow rect를 추가해 버튼 의미를 우선한다.
    if (arrow != null and g_session.count() == 1) {
        const controls_w: f64 = @floatFromInt(ui_metrics.TAB_PLUS_W_PT + ui_metrics.TAB_CLOSE_W_PT + ui_metrics.TAB_MORE_W_PT);
        const controls = NSRect{
            .origin = .{ .x = @max(0, w - controls_w), .y = @max(0, h - @as(f64, @floatFromInt(TAB_BAR_HEIGHT_PT))) },
            .size = .{ .width = @min(w, controls_w), .height = @min(h, @as(f64, @floatFromInt(TAB_BAR_HEIGHT_PT))) },
        };
        add_rect(self_view, objc.sel("addCursorRect:cursor:"), controls, arrow);
    }
    if (arrow != null and g_command_menu_open and g_renderer != null) {
        const menu = commandMenuViewNow().rect;
        const menu_rect = NSRect{
            .origin = .{ .x = menu.x, .y = @max(0, h - @as(f64, menu.y + menu.h)) },
            .size = .{ .width = menu.w, .height = @min(h, @as(f64, menu.h)) },
        };
        add_rect(self_view, objc.sel("addCursorRect:cursor:"), menu_rect, arrow);
    }
}

/// #193 — cursor rect 재계산 (command menu 열림/닫힘 등 state 변화 직후).
/// mouse 안 움직여도 변경 적용.
fn invalidateCursorRects() void {
    if (g_window == null) return;
    const contentView_get = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    const cv = contentView_get(g_window, objc.sel("contentView"));
    if (cv == null) return;
    const invalidate = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    invalidate(g_window, objc.sel("invalidateCursorRectsForView:"), cv);
}

fn tildazMouseDown(self_view: objc.id, _: objc.SEL, event: objc.id) callconv(.c) void {
    requestRender(); // #255 Phase2 — 마우스 → 렌더 (선택/탭/스크롤바 등).
    if (event == null) return;
    const tab = g_session.activeTab() orelse return;

    // 어떤 클릭이든 진행 중 preedit / marked text 우선 commit — terminal
    // click 시 cell preedit 으로 옮겨가지 않게.
    commitPendingInput(self_view);

    if (g_command_menu_open) {
        const xy = eventToWindowPx(self_view, event);
        // #334 — 스크롤 표시 행 클릭 = 한 entry 스크롤, 메뉴 유지.
        if (g_renderer != null) {
            const menu_view = commandMenuViewNow();
            const s = g_renderer.?.scale;
            if (command_menu.hitScrollIndicator(menu_view, xy.x / s, xy.y / s)) |dir| {
                g_command_menu_first = command_menu.scrollStep(menu_view, dir == .down);
                requestRender();
                return;
            }
        }
        const hit = commandMenuHit(xy.x, xy.y);
        closeCommandMenu();
        if (hit) |command| executeCommandMenu(command);
        return;
    }

    if (g_session.count() == 1 and g_renderer != null) {
        const xy = eventToWindowPx(self_view, event);
        switch (singleControlHit(xy.x, xy.y)) {
            .plus => {
                tab.interaction.cancelPointerModes();
                handleNewTab();
                return;
            },
            .close => {
                tab.interaction.cancelPointerModes();
                handleCloseActiveTab();
                return;
            },
            .more => {
                tab.interaction.cancelPointerModes();
                g_command_menu_open = !g_command_menu_open;
                g_command_menu_hover = null;
                invalidateCursorRects();
                g_needs_render = true;
                return;
            },
            else => {},
        }
    }

    // 탭바 영역 클릭 (멀티탭 시) → 화살표 / + / × / 탭 전환 / drag-begin.
    // Windows (app_controller mouse_down) / Linux (handlePointerButton)
    // 와 동일하게 **탭바 분기가 스크롤바보다 먼저** (#268 — 우측 끝 × 버튼이
    // 스크롤바 x 밴드와 겹치므로 순서가 정답. 탭바 안 클릭은 여기서 전부
    // return 하고, .none (= 탭바 밖) 만 아래로 fallthrough).
    if (g_session.count() >= 2 and g_renderer != null) {
        const xy = eventToWindowPx(self_view, event);
        const layout = tabBarLayout();
        const hit_area = tabBarHitArea(xy.x, xy.y, layout);
        // 탭바 영역 (어떤 sub-area 든) 클릭 = 새 mode 시작 의도. 기존 활성
        // 탭의 진행 중 pointer mode (selection / scrollbar drag) cleanup —
        // Windows app_controller.zig:814 동등. β 정책에 따라 highlight 는 보존.
        if (hit_area != .none) {
            tab.interaction.cancelPointerModes();
        }
        switch (hit_area) {
            .left_arrow => {
                if (layout.left_enabled) scrollTabsByArrow(.left);
                return;
            },
            .right_arrow => {
                if (layout.right_enabled) scrollTabsByArrow(.right);
                return;
            },
            .plus => {
                // #329 — MAX_TABS 도달 시 비활성 `+` 클릭은 완전 noop (dialog
                // 없음 — 비활성 overflow 화살표와 같은 관례).
                if (layout.plus_enabled) handleNewTab();
                return;
            },
            // #268 — 우측 끝 `x` = 활성 탭 닫기 (per-tab close 대체).
            .close => {
                handleCloseActiveTab();
                return;
            },
            .more => {
                g_command_menu_open = !g_command_menu_open;
                g_command_menu_hover = null;
                invalidateCursorRects();
                g_needs_render = true;
                return;
            },
            .none => {
                // 탭바 영역 *밖* = 터미널 영역 (tab_layout.hitArea 의 `py >= tab_bar_h`
                // 케이스). 아래 cell selection / 더블클릭 분기로 fallthrough — return
                // 하면 멀티탭 상태에서 모든 터미널 클릭이 무시됨 (#172).
            },
            .tab_area => {
                if (tabBarTabHitTest(xy.x, layout)) |hit_index| {
                    const get_count = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_long);
                    const click_count = get_count(event, objc.sel("clickCount"));
                    // 더블클릭은 소비만 (rename 은 #341 로 제거 — Windows
                    // mouse_double_click noop 동등).
                    if (click_count >= 2) return;
                    // 본체 클릭 → 활성 전환 + drag-begin. DragState world 좌표.
                    _ = g_session.setActiveTab(hit_index);
                    g_tab_scroll_user_override = false;
                    const tab_w_int: c_int = ui_metrics.scaledPx(c_int, ui_metrics.TAB_WIDTH_PT, g_renderer.?.scale);
                    const world_x: f32 = (xy.x - layout.tab_area_x) + g_tab_scroll_x_px;
                    _ = g_drag.begin(@intFromFloat(world_x), tab_w_int, g_session.count());
                    return;
                }
                // tab_area 안인데 탭에는 안 맞음 (마지막 탭 우측 빈 공간 등). 무시.
                return;
            },
        }
    }
    // 스크롤바 영역 클릭 (#123) — Windows app_controller mouse_down 과 동일
    // 순서: 탭바 분기가 위에서 먼저 처리되므로 여기 도달한 클릭은 탭바 밖
    // (y ≥ tab_bar_h). cell selection 보다는 우선.
    if (g_renderer != null) {
        const xy = eventToWindowPx(self_view, event);
        const sbw_px: f32 = ui_metrics.scaledPxF(ui_metrics.SCROLLBAR_W_PT, g_renderer.?.scale);
        const vp_w_f: f32 = @floatFromInt(g_renderer.?.vp_width);
        if (xy.x >= vp_w_f - sbw_px) {
            // 새 scrollbar drag 시작 = 기존 selection drag 정리 (Windows
            // app_controller.zig 동등). selection.cancel 은 active flag
            // 만 리셋, screen 의 highlight 는 보존.
            tab.interaction.selection.cancel();
            g_drag.reset();
            tab.interaction.scrollbar.begin(scrollbarGrabAt(xy.y));
            scrollbarScrollToY(xy.y);
            return;
        }
    }

    const cell = eventToCell(self_view, event) orelse return;
    // double-click → word selection + 자동 copy (Windows `selectWordAt` 와 동등).
    const get_count = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_long);
    const click_count = get_count(event, objc.sel("clickCount"));
    if (click_count >= 2) {
        if (terminal_interaction.selectWord(tab.terminal.screens.active, cell)) {
            handleCopy();
        }
        tab.interaction.selection.cancel(); // word selection 자체 완료, drag 모드 X.
        return;
    }
    tab.interaction.selection.begin(tab.terminal.screens.active, cell);
}

fn tildazMouseDragged(self_view: objc.id, _: objc.SEL, event: objc.id) callconv(.c) void {
    requestRender(); // #255 Phase2
    if (event == null) return;
    const tab = g_session.activeTab() orelse return;

    // 스크롤바 drag (#123) — mouseDown 에서 begin 했으면 mouseDragged 마다
    // scrollToY 로 thumb 위치 동기화.
    if (tab.interaction.scrollbar.active) {
        const xy = eventToWindowPx(self_view, event);
        scrollbarScrollToY(xy.y);
        return;
    }

    // 탭 drag (#111 M11.6a) 가 활성이면 drag 만 처리 — cell selection 무관.
    if (g_drag.active) {
        const xy = eventToWindowPx(self_view, event);
        // #117 drag auto-scroll. mouse_x 가 *탭 영역* 의 좌/우 끝 가까이면 scroll
        // 한 step 이동. drag.move 에는 *갱신된* world 좌표 (= local + scroll).
        const layout = tabBarLayout();
        if (g_renderer) |*r| {
            const tab_w = tabWidthPx();
            const total = tab_w * @as(f32, @floatFromInt(g_session.count()));
            const vp = layout.tab_area_w;
            if (vp > 0 and total > vp) {
                const max_sx = total - vp;
                const edge: f32 = 32 * r.scale;
                const step: f32 = 16 * r.scale;
                const local_x = xy.x - layout.tab_area_x;
                if (local_x < edge and g_tab_scroll_x_px > 0) {
                    g_tab_scroll_x_px = @max(0, g_tab_scroll_x_px - step);
                } else if (local_x > vp - edge and g_tab_scroll_x_px < max_sx) {
                    g_tab_scroll_x_px = @min(max_sx, g_tab_scroll_x_px + step);
                }
            }
        }
        const world_x = (xy.x - layout.tab_area_x) + g_tab_scroll_x_px;
        _ = g_drag.move(@intFromFloat(world_x));
        return;
    }

    if (!tab.interaction.selection.active) return;
    // #245 — 경계 밖이어도 clamp cell 로 선택 연장 + 위/아래 경계면 auto-scroll arm.
    // 마지막 drag px 저장 (렌더-타이머 tick 이 멈춰 있어도 연속 스크롤에 사용).
    const xy = eventToWindowPx(self_view, event);
    g_last_drag_x = xy.x;
    g_last_drag_y = xy.y;
    if (cellAndDirFromPx(xy.x, xy.y)) |sc| {
        tab.interaction.selection.update(tab.terminal.screens.active, sc.cell);
        const prev = g_sel_autoscroll_dir;
        g_sel_autoscroll_dir = sc.dir;
        if (sc.dir != 0 and prev == 0) g_sel_autoscroll_next_ms = 0;
    }
}

fn tildazMouseUp(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    requestRender(); // #255 Phase2
    const tab = g_session.activeTab() orelse return;
    // #245 — 어떤 release 든 drag-select auto-scroll 해제 (선택 끝/취소).
    g_sel_autoscroll_dir = 0;

    // 스크롤바 drag 종료 (#123).
    if (tab.interaction.scrollbar.active) {
        tab.interaction.scrollbar.end();
        return;
    }

    // 탭 drag 완료 (#111 M11.6a). dragging 임계 (5px) 넘었으면 reorder.
    if (g_drag.active) {
        if (g_renderer) |*r| {
            const tab_w_int: c_int = ui_metrics.scaledPx(c_int, ui_metrics.TAB_WIDTH_PT, r.scale);
            if (g_drag.finish(tab_w_int, g_session.count())) |req| {
                _ = g_session.reorderTabs(req.from, req.to) catch |err| {
                    log.appendLine("tab", "reorder failed: {s}", .{@errorName(err)});
                };
                // drag reorder 끝 — 활성 탭 위치 변경, ensure 재가동 (#117).
                g_tab_scroll_user_override = false;
            }
        } else {
            g_drag.reset();
        }
        return;
    }

    // 셀 selection finish — Windows `selection.finish()` → `copyToClipboard`
    // 패턴 (#122). selection 변화 있었으면 자동 clipboard copy. Cmd+C 없이도
    // 드래그 후 즉시 paste 가능.
    if (tab.interaction.selection.finish()) {
        handleCopy();
    }
}

/// #268 2b — NSTrackingArea 의 mouseMoved:. 탭바 컨트롤 버튼 (`<` `>` `×`
/// `+`) 위에서만 hover, 탭 본체 / 탭바 밖은 .none. 변경 시에만 재렌더.
fn tildazMouseMoved(self_view: objc.id, _: objc.SEL, event: objc.id) callconv(.c) void {
    if (g_renderer == null) return;
    if (g_command_menu_open) {
        const xy = eventToWindowPx(self_view, event);
        const hover = commandMenuHit(xy.x, xy.y);
        if (hover != g_command_menu_hover or g_tab_hover != .none) {
            g_command_menu_hover = hover;
            // #329 — pointer 가 항목 위로 오면 keyboard focus 도 동기화 (표준
            // 메뉴 동작). 안 하면 마우스로 건너뛴 뒤 ↑↓ 가 옛 위치에서 출발.
            if (hover) |h| g_command_menu_focus = h;
            g_tab_hover = .none;
            requestRender();
        }
        return;
    }
    g_command_menu_hover = null;
    const new_hover: tab_layout.Area = blk: {
        const xy = eventToWindowPx(self_view, event);
        if (g_session.count() == 1) break :blk singleControlHit(xy.x, xy.y);
        if (g_session.count() < 2) break :blk .none;
        const layout = tabBarLayout();
        break :blk switch (tabBarHitArea(xy.x, xy.y, layout)) {
            // #329 — 비활성 `+` 는 hover 강조도 없음.
            .plus => if (layout.plus_enabled) tab_layout.Area.plus else .none,
            .left_arrow, .right_arrow, .close, .more => |a| a,
            .tab_area, .none => .none,
        };
    };
    if (new_hover != g_tab_hover) {
        g_tab_hover = new_hover;
        requestRender();
    }
}

/// #268 2b — 마우스가 view 밖으로 나가면 hover 해제 (안 하면 박스가 남음).
fn tildazMouseExited(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    if (g_tab_hover != .none) {
        g_tab_hover = .none;
        requestRender();
    }
    // #334 재감사 — 메뉴 항목 hover 도 창 이탈 시 해제 (keyboard focus 는
    // 유지 — 표준 메뉴의 마지막 selection 기억과 동일).
    if (g_command_menu_hover != null) {
        g_command_menu_hover = null;
        requestRender();
    }
}

/// 우클릭 paste (#119). cmd.exe console 표준 패턴 — Windows 의 WM_RBUTTONDOWN
/// (변경 후) 와 동일.
fn tildazRightMouseDown(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    // #329 — 열린 menu 는 pointer button 보다 우선: 우클릭은 메뉴만 닫고
    // paste 하지 않는다 (SPEC §5.3).
    if (g_command_menu_open) {
        closeCommandMenu();
        return;
    }
    // #340 — Cmd+V 와 같은 pending 정책 적용 (조합 확정 후 payload — '하X').
    applyPasteInputPolicy();
    handlePaste();
}

/// 현재 활성 탭의 scrollbar `Hit` (track + thumb geometry). 스크롤백이 없거나
/// thumb 여유가 없으면 null. 렌더러(`renderer/macos.zig`)와 같은 `scrollbar.hit`
/// 입력을 써서 그림 영역과 클릭 영역을 일치시킨다 (#259).
fn scrollbarHit() ?scrollbar.Hit {
    const tab = g_session.activeTab() orelse return null;
    if (g_renderer == null) return null;
    const r = &g_renderer.?;
    const sb = tab.terminal.screens.active.pages.scrollbar();
    return scrollbar.hit(
        sb.total,
        sb.len,
        sb.offset,
        @floatFromInt(r.vp_height),
        @floatFromInt(scrollbarTopInsetPx(r.scale)),
        ui_metrics.scaledPxF(TERMINAL_PADDING_PT, r.scale),
        ui_metrics.scaledPxF(ui_metrics.SCROLLBAR_MIN_THUMB_H_PT, r.scale),
    );
}

/// mouse-down 시 grab offset (#259). 스크롤바 없으면 0.
fn scrollbarGrabAt(mouse_y_px: f32) f64 {
    const h = scrollbarHit() orelse return 0;
    return h.grab(mouse_y_px);
}

/// 스크롤바 드래그 시 thumb 위치 따라 viewport scroll (#123). grab offset 은
/// down 때 `scrollbar.begin` 으로 저장된 값을 사용 — thumb 어디를 잡아도 그 지점이
/// 커서 아래 고정돼 따라온다 (#259, 이전엔 thumb 윗변이 커서로 점프).
/// `mouse_y_px` 는 윈도우 좌상 기준 top-down pixel.
fn scrollbarScrollToY(mouse_y_px: f32) void {
    const tab = g_session.activeTab() orelse return;
    const h = scrollbarHit() orelse return;
    const target_row = h.target(mouse_y_px, tab.interaction.scrollbar.grab_offset);
    const delta = @as(isize, @intCast(target_row)) - @as(isize, @intCast(h.offset));
    if (delta != 0) {
        tab.terminal.scrollViewport(.{ .delta = delta });
    }
}

/// macOS keycode (kVK_ANSI_*) 의 1..9 → 0-base 탭 인덱스. 1 → 0, 2 → 1 식.
/// 키보드 row 가 keycode 순서가 아니라 매핑이 비균일 (`0x12, 0x13, 0x14,
/// 0x15, 0x17, 0x16, 0x1A, 0x1C, 0x19`).
fn keycodeToTabIndex(kc: c_ushort) ?usize {
    return switch (kc) {
        0x12 => 0, // 1
        0x13 => 1, // 2
        0x14 => 2, // 3
        0x15 => 3, // 4
        0x17 => 4, // 5
        0x16 => 5, // 6
        0x1A => 6, // 7
        0x1C => 7, // 8
        0x19 => 8, // 9
        else => null,
    };
}

/// Cmd+W — 활성 탭을 즉시 정리. PTY 자식이 살아 있어도 deinit 의 SIGHUP +
/// fd close 로 정상 hangup 후 종료. 마지막 탭이 닫혔는지는 다음 frame 의
/// drainExitedTabs 가 검사 (closeTab 이 컬렉션에서 즉시 제거하므로 사실 이번
/// frame 끝에 count == 0 일 수 있음 — drainExitedTabs 의 빈 컬렉션 분기로
/// 통일).
fn handleCloseActiveTab() void {
    // closeActive helper 가 마지막 탭 → terminate, 그 외 → override clear +
    // invalidate. mac 의 사후 처리는 .changed 일 때 syncTerminalGeometry 만 —
    // 2 → 1 전환에서 탭바 사라져 cell 영역 늘어나는 케이스 대응 (#127).
    if (tab_actions.closeActive(&g_host) == .changed) syncTerminalGeometry();
}

/// Cmd+T — 활성 탭의 cols/rows 와 같은 크기로 새 탭 생성 후 syncTerminalGeometry
/// 가 1 → 2 전환 시 탭바 등장으로 줄어드는 cell 영역에 맞춰 모든 탭 resize.
fn handleNewTab() void {
    if (tab_actions.checkAtLimitAndDialog(&g_host)) return;
    // #248 — shell 이 런타임에 사라졌으면 (brew 업데이트 등) 조용히 죽는 대신 알림.
    if (!@import("../shell_validate.zig").checkForNewTab(g_gpa.allocator(), g_config.shell)) return;
    const active = g_session.activeTab() orelse return;
    g_session.createTab(active.terminal.cols, active.terminal.rows) catch |err| {
        log.appendLine("tab", "new tab failed: {s}", .{@errorName(err)});
        return;
    };
    syncTerminalGeometry();
    g_tab_scroll_user_override = false;
}

/// 마우스 휠 / 트랙패드 스크롤 → ghostty Terminal 의 viewport scroll. 양수
/// deltaY (콘텐츠가 아래로 = 손가락 위로) 면 scrollback 의 위쪽 (오래된 내용)
/// 보임. trackpad 의 작은 precise delta 도 그대로 1+ row 단위로 변환.
fn handleCopy() void {
    tab_actions.copyActiveSelection(&g_host, g_gpa.allocator());
}

fn handlePaste() void {
    const NSPasteboard = objc.getClass("NSPasteboard");
    const get_general = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const pb = get_general(NSPasteboard, objc.sel("generalPasteboard"));
    if (pb == null) return;

    const stringForType = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) objc.id);
    const ns_type = objc.nsString("public.utf8-plain-text");
    const ns_text = stringForType(pb, objc.sel("stringForType:"), ns_type);
    if (ns_text == null) return;

    const get_len = objc.objcSend(fn (objc.id, objc.SEL, usize) callconv(.c) usize);
    const len = get_len(ns_text, objc.sel("lengthOfBytesUsingEncoding:"), NSUTF8StringEncoding);
    if (len == 0) return;

    const get_utf8 = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) [*:0]const u8);
    const cstr = get_utf8(ns_text, objc.sel("UTF8String"));

    // PTY paste (bracketed paste + wrap 은 session.pasteToActive 가).
    tab_actions.routePaste(&g_host, cstr[0..len]);
}

fn tildazScrollWheel(_: objc.id, _: objc.SEL, event: objc.id) callconv(.c) void {
    requestRender(); // #255 Phase2 — 휠 스크롤 → 렌더 (viewport 변경, 출력 없음).
    const tab = g_session.activeTab() orelse return;
    if (event == null) return;

    const get_delta = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) f64);
    const delta_y = get_delta(event, objc.sel("scrollingDeltaY"));
    if (delta_y == 0) return;

    // #329 — 열린 menu 는 wheel 도 소비한다. 작은 viewport 에서 잘린 항목
    // 도달 경로 (entry 단위 scroll). terminal scrollback 으로 안 보냄.
    // #334 — delta 누적 + 나머지 보존: 이벤트당 1 entry 는 트랙패드(초당
    // 수십 개의 작은 delta)에서 과민했다 (재감사 발견). 12pt 당 1 entry 는
    // 시작값 — 시연 튜닝.
    if (g_command_menu_open) {
        if (g_renderer == null) return;
        const step_unit: f64 = 12.0;
        g_command_menu_scroll_accum += delta_y;
        var steps: i64 = @intFromFloat(@divTrunc(g_command_menu_scroll_accum, step_unit));
        g_command_menu_scroll_accum -= @as(f64, @floatFromInt(steps)) * step_unit;
        while (steps != 0) {
            const down = steps < 0; // deltaY 음수 = 아래로 스크롤
            const next = command_menu.scrollStep(commandMenuViewNow(), down);
            if (next == g_command_menu_first) break;
            g_command_menu_first = next;
            requestRender();
            steps += if (down) @as(i64, 1) else -1;
        }
        return;
    }

    // ceil/floor 로 작은 값도 1 line 으로. multiplier 1.0 이면 약간 느려서
    // 평소 trackpad 사용감 기준 multiplier ~2.
    const scaled = delta_y * 2.0;
    const lines: isize = if (scaled > 0)
        @as(isize, @intFromFloat(@ceil(scaled)))
    else
        @as(isize, @intFromFloat(@floor(scaled)));
    if (lines == 0) return;

    // delta 부호: 양수 deltaY (위로) → scrollback 위쪽 (older) = delta 음수
    // (ghostty `scrollViewport(.{.delta = -N})` 가 위쪽).
    tab.terminal.scrollViewport(.{ .delta = -lines });
}

fn registerTildazViewClass() !objc.Class {
    const NSView = objc.getClass("NSView");
    const cls = objc.objc_allocateClassPair(NSView, "TildazView", 0) orelse
        return error.ViewSubclassAllocFailed;
    if (!objc.class_addMethod(cls, objc.sel("acceptsFirstResponder"), @ptrCast(&tildazAcceptsFirstResponder), "B@:"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("performKeyEquivalent:"), @ptrCast(&tildazPerformKeyEquivalent), "B@:@"))
        return error.ViewSubclassAddMethodFailed;
    // "v@:@" = void 반환, self + _cmd + 한 인자 (NSEvent id).
    if (!objc.class_addMethod(cls, objc.sel("keyDown:"), @ptrCast(&tildazKeyDown), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("scrollWheel:"), @ptrCast(&tildazScrollWheel), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    // 마우스 selection (drag).
    if (!objc.class_addMethod(cls, objc.sel("mouseDown:"), @ptrCast(&tildazMouseDown), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("mouseDragged:"), @ptrCast(&tildazMouseDragged), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("mouseUp:"), @ptrCast(&tildazMouseUp), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    // 우클릭 paste (#119) — cmd.exe console 표준 패턴.
    if (!objc.class_addMethod(cls, objc.sel("rightMouseDown:"), @ptrCast(&tildazRightMouseDown), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    // #268 2b — 탭바 컨트롤 버튼 hover 추적. NSTrackingArea (아래 attach) 가
    // mouseMoved: / mouseExited: 를 보내준다.
    if (!objc.class_addMethod(cls, objc.sel("mouseMoved:"), @ptrCast(&tildazMouseMoved), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("mouseExited:"), @ptrCast(&tildazMouseExited), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    // #193 — OS mouse cursor shape. cell 영역 I-beam.
    if (!objc.class_addMethod(cls, objc.sel("resetCursorRects"), @ptrCast(&tildazResetCursorRects), "v@:"))
        return error.ViewSubclassAddMethodFailed;
    // 모니터 / DPI / dock auto-hide 등 screen parameter 변경 알림 handler.
    if (!objc.class_addMethod(cls, objc.sel("screenChanged:"), @ptrCast(&tildazScreenChanged), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    // CADisplayLink (#255) target — vsync 마다 render. 인자는 CADisplayLink id.
    if (!objc.class_addMethod(cls, objc.sel("displayLinkFire:"), @ptrCast(&displayLinkFire), "v@:@"))
        return error.ViewSubclassAddMethodFailed;

    // NSTextInputClient protocol — IME (한글 / 일본어 / 중국어). 등록한 13
    // 메서드는 ghostty / Terminal.app / 표준 NSView terminal 패턴. `NSRange`
    // = `{_NSRange=QQ}` (location, length 둘 다 unsigned long). `CGRect`
    // = `{CGRect={CGPoint=dd}{CGSize=dd}}`.
    if (!objc.class_addMethod(cls, objc.sel("insertText:replacementRange:"), @ptrCast(&imeInsertText), "v@:@{_NSRange=QQ}"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("insertText:"), @ptrCast(&imeInsertTextSimple), "v@:@"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("setMarkedText:selectedRange:replacementRange:"), @ptrCast(&imeSetMarkedText), "v@:@{_NSRange=QQ}{_NSRange=QQ}"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("unmarkText"), @ptrCast(&imeUnmarkText), "v@:"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("hasMarkedText"), @ptrCast(&imeHasMarkedText), "B@:"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("markedRange"), @ptrCast(&imeMarkedRange), "{_NSRange=QQ}@:"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("selectedRange"), @ptrCast(&imeSelectedRange), "{_NSRange=QQ}@:"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("validAttributesForMarkedText"), @ptrCast(&imeValidAttributes), "@@:"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("attributedSubstringForProposedRange:actualRange:"), @ptrCast(&imeAttrSubstring), "@@:{_NSRange=QQ}^{_NSRange=QQ}"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("characterIndexForPoint:"), @ptrCast(&imeCharIndex), "Q@:{CGPoint=dd}"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("firstRectForCharacterRange:actualRange:"), @ptrCast(&imeFirstRect), "{CGRect={CGPoint=dd}{CGSize=dd}}@:{_NSRange=QQ}^{_NSRange=QQ}"))
        return error.ViewSubclassAddMethodFailed;
    if (!objc.class_addMethod(cls, objc.sel("doCommandBySelector:"), @ptrCast(&imeDoCommand), "v@::"))
        return error.ViewSubclassAddMethodFailed;

    // protocol 채택 — 이거 안 하면 inputContext 가 view 를 NSTextInputClient
    // 로 인식 안 해서 interpretKeyEvents 가 routing 안 됨.
    if (objc.objc_getProtocol("NSTextInputClient")) |proto| {
        _ = objc.class_addProtocol(cls, proto);
    } else {
        log.appendLine("ime", "WARNING: NSTextInputClient protocol not found", .{});
    }

    objc.objc_registerClassPair(cls);
    return cls;
}

/// 첫 실행 시점에 disk config 에 명시할 shell path 결정.
///   - `$SHELL` env 가 있으면 그 값 (사용자 환경 그대로 보존).
///   - 없으면 `config.Defaults.shell` (= `/bin/bash`).
///
/// 반환 string 은 owned — `Config.load` 가 소유권 인수 (disk 정상 경로서 free,
/// fail 경로서 `Config.shell` 로 보관, #218). fallback 도 dupe 해 항상 owned.
/// (macOS 는 terminate 가 exit 직행이라 `Config.deinit` 미호출 — 그래도 load 의
/// disk 경로 free 가 owned 를 기대하므로 dupe 필요.)
fn resolveShell(allocator: std.mem.Allocator) []const u8 {
    if (std.process.getEnvVarOwned(allocator, "SHELL") catch null) |s| return s;
    return allocator.dupe(u8, config.Defaults.shell) catch config.Defaults.shell;
}

pub fn run(opts: run_options.RunOptions) !void {
    g_run_opts = opts;
    // 통합 로그 파일에 boot/exit 라인을 남긴다 (`log.zig`). macOS 는
    // `~/Library/Logs/tildaz_N.log` — Console.app 이 자동 인덱싱해 GUI 에서
    // 바로 열람 가능.
    log.logStart(build_options.version);
    // #197 — env TILDAZ_VERBOSE 면 protocol/timing/detail 로그까지 (기본은 lifecycle).
    log.setVerbose(std.process.hasEnvVarConstant("TILDAZ_VERBOSE"));
    // Cmd+Q (NSApp terminate:) 는 `exit()` 직행 — defer 안 불림. atexit 등록.
    _ = atexit(&atExitLogStop);

    // 0. NSApplication. config fatal이 긴 경로를 포함해도 osascript의 8192-byte
    //    bootstrap buffer로 떨어지지 않고 NSAlert + overflow scroll을 쓸 수 있도록
    //    config 읽기 전에 AppKit dialog backend부터 준비한다 (#316).
    const NSApplication = objc.getClass("NSApplication");
    const sharedApp = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    g_app = sharedApp(NSApplication, objc.sel("sharedApplication")) orelse return error.NSApplicationFailed;

    const setActivationPolicy = objc.objcSend(fn (objc.id, objc.SEL, c_long) callconv(.c) bool);
    _ = setActivationPolicy(g_app, objc.sel("setActivationPolicy:"), NSApplicationActivationPolicyAccessory);
    @import("../dialog/macos.zig").markNSAppReady();

    // 1. Config 읽기 — 잘못된 값 발견 시 config.zig 가 dialog.showFatal 로
    //    다이얼로그를 띄우고 즉시 종료 (Windows host 와 동일 정책).
    //
    // shell_resolved: 첫 실행 시 disk 에 명시될 shell path. `$SHELL` env 가
    // 있으면 사용자 환경값을 그대로, 없으면 `Defaults.shell` (= `/bin/bash`).
    // 이후 실행은 disk 의 명시값만 사용 — runtime fallback 분기 없음.
    const shell_resolved = resolveShell(g_gpa.allocator());
    g_config = config.Config.load(g_gpa.allocator(), shell_resolved);
    log.logConfigLoaded(g_config);

    // shell executable 이 실제 존재하고 실행 가능한지 검증. PTY 단계까지 가서
    // execve 실패하면 generic 에러로 끝나 사용자에게 어디 고쳐야 할지 안내 안
    // 됨 — config 로드 직후 fatal 로 종료. Windows host 와 같은 정책.
    @import("../shell_validate.zig").validateOrFatal(g_gpa.allocator(), g_config.shell);

    // macOS "Press and Hold" 기능 끔 — 영어 키 길게 눌러도 accent picker
    // (à á â) 안 뜨고 정상 key repeat 발생. 한글 자모는 IME 경로라 영향
    // 없지만, 영어/숫자/기호는 system 이 repeat 을 막아 *키 한 번* 만 들어옴.
    // ghostty / iTerm2 / Alacritty 모두 같은 방식 — 우리 앱 도메인의
    // NSUserDefaults 에 false 로 set.
    {
        const NSUserDefaults = objc.getClass("NSUserDefaults");
        const stdDefaults = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
        const defaults = stdDefaults(NSUserDefaults, objc.sel("standardUserDefaults"));
        if (defaults != null) {
            const setBoolForKey = objc.objcSend(fn (objc.id, objc.SEL, bool, objc.id) callconv(.c) void);
            setBoolForKey(defaults, objc.sel("setBool:forKey:"), false, objc.nsString("ApplePressAndHoldEnabled"));
        }
    }

    try buildMainMenu(g_app);

    // applicationShouldTerminate: hook (#116) — 다중 탭에서 Cmd+Q / 메뉴 Quit
    // 시 confirm 다이얼로그. NSApp.terminate 모든 path 를 한 곳에서 가로챔
    // (mainMenu 의 Quit + 마지막 탭 닫힘 자동 terminate). 마지막 탭 종료 후
    // 자동 호출되는 path (drainExitedTabs / handleCloseActiveTab /
    // handleTabBarClick) 는 count == 0 이라 자동 통과.
    try installAppDelegate();

    // 2. NSWindow (TildazWindow subclass) — borderless styleMask. Default
    //    NSWindow 가 borderless 일 때 `canBecomeKeyWindow == NO` 라서 mainMenu
    //    Cmd+Q 가 dispatch 안 되는 문제가 있는데, subclass 에서 그 method 를
    //    YES 로 override 해 우회. titlebar 자체가 없어 위쪽 32pt offset 도
    //    사라진다 (이게 위 padding 비대칭의 진짜 원인 — Titled mask 가 위쪽
    //    titlebar 영역의 layer drawing 을 시스템이 막던 것).
    const TildazWindow = try registerTildazWindowClass();
    const alloc = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const window_alloc = alloc(TildazWindow, objc.sel("alloc")) orelse return error.NSWindowAllocFailed;

    const initWindow = objc.objcSend(fn (objc.id, objc.SEL, NSRect, c_ulong, c_ulong, bool) callconv(.c) objc.id);
    // 초기 rect 는 placeholder — 곧이어 dock rect 로 덮어쓴다.
    const placeholder = NSRect{ .origin = .{ .x = 0, .y = 0 }, .size = .{ .width = 800, .height = 400 } };
    const style_mask = NSWindowStyleMaskBorderless;
    g_window = initWindow(
        window_alloc,
        objc.sel("initWithContentRect:styleMask:backing:defer:"),
        placeholder,
        style_mask,
        NSBackingStoreBuffered,
        false,
    ) orelse return error.NSWindowInitFailed;

    // 사용자 드래그 / 이동 OS 차단.
    const setMovable = objc.objcSend(fn (objc.id, objc.SEL, bool) callconv(.c) void);
    setMovable(g_window, objc.sel("setMovable:"), false);
    // Window level = popUpMenu (101) — dock + menu bar + 다른 앱 위에 표시.
    // floating(3) 은 dock 보다 낮아서 dock 이 우리 윈도우 좌측 (또는 dock
    // 위치) 일부를 가려 padding 비대칭으로 보임. ghostty QuickTerminal 도
    // 동일 이유로 popUpMenu 사용 (QuickTerminalController.swift:435 주석
    // "only popUpMenu and above do what we want").
    const NSPopUpMenuWindowLevel: c_int = 101;
    const setLevel = objc.objcSend(fn (objc.id, objc.SEL, c_int) callconv(.c) void);
    setLevel(g_window, objc.sel("setLevel:"), NSPopUpMenuWindowLevel);

    // dialog/macos 가 alert 띄울 때 우리 윈도우 level 을 잠깐 normal 로 낮추도록
    // 등록 (alert 가 popup 위에 표시되도록).
    @import("../dialog/macos.zig").setHostWindow(g_window);

    // 윈도우 자체를 opaque=NO + backgroundColor=clear 로 — borderless 라
    // titlebar 자체는 없지만 system 의 default window background (흰색) 가
    // 보일 수 있다. clear 로 하면 metal layer 가 윈도우 전체에 그대로 보임.
    const setOpaque = objc.objcSend(fn (objc.id, objc.SEL, bool) callconv(.c) void);
    setOpaque(g_window, objc.sel("setOpaque:"), false);
    const NSColor = objc.getClass("NSColor");
    const clearColor_get = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const clear_color = clearColor_get(NSColor, objc.sel("clearColor"));
    const setBackgroundColor = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    setBackgroundColor(g_window, objc.sel("setBackgroundColor:"), clear_color);

    // config.opacity (0..255) → NSWindow.alphaValue (0.0..1.0). Windows
    // tildaz 의 layered window alpha 와 동일 의미 — 윈도우 전체 (cell grid +
    // 탭바) 가 그 alpha 만큼 반투명. opacity = 255 (default) 면 alpha = 1.0
    // 완전 불투명.
    const alpha_value: f64 = @as(f64, @floatFromInt(g_config.opacity_alpha)) / 255.0;
    const setAlphaValue = objc.objcSend(fn (objc.id, objc.SEL, f64) callconv(.c) void);
    setAlphaValue(g_window, objc.sel("setAlphaValue:"), alpha_value);

    // 3. CAMetalLayer + Metal 렌더러. ghostty 의 layer-hosting 패턴 차용:
    //    `setLayer:` 를 먼저 호출하고 그 *다음* `setWantsLayer:YES` — 이러면
    //    NSView 가 우리 layer 를 직접 host (자동 backing layer 안 만들고).
    //
    //    contentView 를 TildazView 로 교체 — keyDown 받아 PTY 로 forwarding.
    //    default NSView 는 keyDown override 안 되어 키 입력 처리 불가. NSWindow
    //    의 default contentView 는 setContentView: 로 바꿀 수 있다.
    //
    //    참고 — 위쪽 32pt 패딩 비대칭의 진짜 원인은 **PTY non-login shell +
    //    `~/.hushlogin` → row 0 empty** 였고 `argv = {shell, "-l"}` 로 해결됨
    //    (`macos_pty.zig`). Borderless styleMask + safeAreaInsets workaround
    //    는 그 때 무관한 회피책이었어서 이번에 정리. Borderless 라 시스템 top
    //    inset 자체가 0 이라 `additionalSafeAreaInsets` 무력화 코드 불필요.
    const TildazView = try registerTildazViewClass();
    const view_alloc = alloc(TildazView, objc.sel("alloc")) orelse return error.ViewAllocFailed;
    const view_init = objc.objcSend(fn (objc.id, objc.SEL, NSRect) callconv(.c) objc.id);
    const tildaz_view = view_init(view_alloc, objc.sel("initWithFrame:"), placeholder) orelse
        return error.ViewInitFailed;
    const setContentView = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    setContentView(g_window, objc.sel("setContentView:"), tildaz_view);

    // #268 2b — mouseMoved: 수신용 NSTrackingArea. options:
    //   MouseEnteredAndExited(0x01) | MouseMoved(0x02) | ActiveAlways(0x80)
    //   | InVisibleRect(0x200) — InVisibleRect 라 rect 인자 무시 + view resize
    //   자동 추적 (updateTrackingAreas 재부착 불필요).
    {
        const NSTrackingArea = objc.getClass("NSTrackingArea");
        const ta_alloc = alloc(NSTrackingArea, objc.sel("alloc")) orelse return error.TrackingAreaAllocFailed;
        const ta_init = objc.objcSend(fn (objc.id, objc.SEL, NSRect, c_ulong, objc.id, objc.id) callconv(.c) objc.id);
        const tracking_area = ta_init(
            ta_alloc,
            objc.sel("initWithRect:options:owner:userInfo:"),
            placeholder,
            0x01 | 0x02 | 0x80 | 0x200,
            tildaz_view,
            null,
        ) orelse return error.TrackingAreaInitFailed;
        const addTA = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
        addTA(tildaz_view, objc.sel("addTrackingArea:"), tracking_area);
    }

    const contentView_get = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    const content_view = contentView_get(g_window, objc.sel("contentView")) orelse return error.ContentViewMissing;

    const CAMetalLayer = objc.getClass("CAMetalLayer");
    const init_obj = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    const layer_alloc = alloc(CAMetalLayer, objc.sel("alloc")) orelse return error.MetalLayerAllocFailed;
    const layer = init_obj(layer_alloc, objc.sel("init")) orelse return error.MetalLayerInitFailed;

    const device = MTLCreateSystemDefaultDevice() orelse return error.MetalDeviceMissing;

    const setLayer = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    setLayer(content_view, objc.sel("setLayer:"), layer);
    const setWantsLayer = objc.objcSend(fn (objc.id, objc.SEL, bool) callconv(.c) void);
    setWantsLayer(content_view, objc.sel("setWantsLayer:"), true);
    // layer 가 view bounds 를 넘으면 자르기 — drawable 이 view 보다 살짝
    // 커도 화면 밖으로 그려지지 않게 (ghostty Metal.zig 패턴).
    const setClipsToBounds = objc.objcSend(fn (objc.id, objc.SEL, bool) callconv(.c) void);
    setClipsToBounds(content_view, objc.sel("setClipsToBounds:"), true);
    g_metal_layer = layer;

    // 4. 첫 dock rect 적용 후 표시 (hidden_start 면 표시 생략 — 첫 hotkey 까지
    //    윈도우는 unmapped, F1 처음 눌렀을 때 첫 노출. Windows windows_host.run
    //    의 `if (!config.hidden_start) app.window.show();` 와 동등).
    repositionWindow();
    // 측정 모드는 `hidden_start` 를 무시한다 (#382) — 창이 숨겨져 있으면 렌더가
    // 일어나지 않아 측정이 무의미하다.
    if (!g_config.hidden_start or g_run_opts.isStressRun()) {
        showWindow();
    }

    // 4.5. screen parameter 변경 알림 등록 — 모니터 추가/제거, 해상도 변경,
    //      DPI 변경, dock auto-hide 토글 모두 syncGeometryAfterScreenChange
    //      한 곳에서 처리.
    {
        const NSNotificationCenter = objc.getClass("NSNotificationCenter");
        const get_center = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
        const center = get_center(NSNotificationCenter, objc.sel("defaultCenter"));
        if (center != null) {
            const notif_names = [_][:0]const u8{
                "NSApplicationDidChangeScreenParametersNotification",
                "NSWindowDidChangeScreenNotification",
                "NSWindowDidChangeBackingPropertiesNotification",
            };
            for (notif_names) |name| {
                const ns_name = objc.nsString(name);
                objc.msgSendVoid4(
                    center,
                    objc.sel("addObserver:selector:name:object:"),
                    tildaz_view,
                    objc.sel("screenChanged:"),
                    ns_name,
                    @as(objc.id, null),
                );
            }
        }
    }

    // layer geometry 동기화. additionalSafeAreaInsets 로 시스템 inset 무력화
    // 했으므로 layer 가 cv_bounds 전체 (titlebar 영역 포함) 를 그대로 사용.
    const get_rect = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) NSRect);
    // #382 — `-size` 가 있으면 renderer 초기화 뒤에 창을 격자에 맞추고 이 값을 다시 읽는다.
    var cv_bounds = get_rect(content_view, objc.sel("bounds"));
    const set_layer_frame = objc.objcSend(fn (objc.id, objc.SEL, NSRect) callconv(.c) void);
    set_layer_frame(layer, objc.sel("setFrame:"), cv_bounds);

    const backing_scale = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) f64);
    const scale_pt = backing_scale(g_window, objc.sel("backingScaleFactor"));
    const set_contents_scale = objc.objcSend(fn (objc.id, objc.SEL, f64) callconv(.c) void);
    set_contents_scale(layer, objc.sel("setContentsScale:"), scale_pt);
    const set_drawable_size = objc.objcSend(fn (objc.id, objc.SEL, NSSize) callconv(.c) void);
    set_drawable_size(layer, objc.sel("setDrawableSize:"), .{
        .width = cv_bounds.size.width * scale_pt,
        .height = cv_bounds.size.height * scale_pt,
    });

    // 5. CGEventTap 으로 이 worker config의 글로벌 hotkey 등록. Cmd+Q 는
    //    NSMenu 의 "Quit TildaZ" item 이 표준 dispatch (#153 — 글로벌 hook
    //    이었던 시절엔 다른 앱 frontmost 일 때도 가로챘음).
    //    Carbon RegisterEventHotKey 는 우리 환경 (macOS Tahoe + ad-hoc sign) 에서
    //    silently fail 하므로 Apple DTS 권장 modern API 인 CGEventTap 사용.
    //    Input Monitoring 권한 필요 — 사용자가 시스템 설정에서 활성화.
    // 측정 모드는 전역 핫키를 등록하지 않는다 (#382) — 평소 쓰는 TildaZ 와 F1 이
    // 겹쳐 두 프로세스가 같은 키에 반응한다.
    if (!g_run_opts.isStressRun()) try installEventTap();

    const allocator = g_gpa.allocator();

    // 6. Metal 렌더러 (font 측정 포함). terminal Font Spec 의 logical size와
    //    ratio로 cell_width/height 자동 계산 — Windows / Linux 와 동일 계약.
    //
    //    `TILDAZ_FONT` 환경변수로 config 보다 우선 — 빠르게 다른 폰트 시험.
    //    config.font.family 는 *glyph fallback chain* (codepoint 별로 chain 순회).
    const tildaz_font_env = std.process.getEnvVarOwned(allocator, "TILDAZ_FONT") catch null;
    defer if (tildaz_font_env) |s| allocator.free(s);
    var env_chain: [1][]const u8 = undefined;
    const font_family_slice: []const []const u8 = if (tildaz_font_env) |s| blk: {
        env_chain[0] = s;
        break :blk env_chain[0..1];
    } else g_config.font_families[0..g_config.font_family_count];

    // active terminal 에 background가 없는 예외에 쓸 renderer fallback.
    // 정상 frame은 terminal의 현재 값(OSC 11 포함)을 renderTabBar에 전달한다.
    const theme_bg: ?[3]u8 = if (g_config.theme) |t| .{ t.background.r, t.background.g, t.background.b } else null;
    g_renderer = renderer_module.RendererBackend.init(
        allocator,
        device,
        layer,
        font_family_slice,
        g_config.terminalFontSpec(),
        theme_bg,
        @floatCast(scale_pt),
    ) catch |err| switch (err) {
        // chain 모두 lookup 실패 — 시도한 폰트 list 명시 (Windows 의
        // `font_not_found_format` 와 같은 의도, multi-font 메시지).
        error.FontCreateFailed => {
            var buf: [1024]u8 = undefined;
            var fbs = std.io.fixedBufferStream(&buf);
            const w = fbs.writer();
            w.writeAll(messages.font_chain_all_failed_msg) catch {};
            for (font_family_slice) |fam| w.print("\n  - {s}", .{fam}) catch {};
            dialog.showFatal(messages.config_error_title, fbs.getWritten());
        },
        else => return err,
    };
    // #382 — renderer 가 생겨 셀 크기를 알므로 여기서 `-size` 를 적용한다. 창을 격자에
    // 맞추고 layer / drawable / bounds 를 새 크기로 되돌린다. 아래 `terminalGrid` 가 그
    // 창에서 격자를 다시 계산하므로, 요청한 셀 수가 그대로 나오는지 그 값으로 확인된다.
    if (g_run_opts.grid != null) {
        repositionWindow();
        cv_bounds = get_rect(content_view, objc.sel("bounds"));
        set_layer_frame(layer, objc.sel("setFrame:"), cv_bounds);
        set_drawable_size(layer, objc.sel("setDrawableSize:"), .{
            .width = cv_bounds.size.width * scale_pt,
            .height = cv_bounds.size.height * scale_pt,
        });
    }

    // viewport / cell metrics 모두 pixel 단위로 통일 — pt/px mixing 시 글리프
    // 가 cell 일부만 차지해 깨져 보이는 문제 회피 (#75 댓글 6 의 정정 패턴).
    const vp_w_px: u32 = @intFromFloat(cv_bounds.size.width * scale_pt);
    const vp_h_px: u32 = @intFromFloat(cv_bounds.size.height * scale_pt);
    g_renderer.?.resize(vp_w_px, vp_h_px);

    const cell_w_px: u32 = g_renderer.?.font.cell_width_px;
    const cell_h_px: u32 = g_renderer.?.font.cell_height_px;
    const pad_px: u32 = ui_metrics.scaledPx(u32, TERMINAL_PADDING_PT, @floatCast(scale_pt));
    log.appendLine("startup", "renderer init: vp={d}x{d}px scale={d:.2} cell={d}x{d}px pad={d}px font={s}", .{
        vp_w_px,
        vp_h_px,
        scale_pt,
        cell_w_px,
        cell_h_px,
        pad_px,
        g_renderer.?.font.font_family,
    });

    // 7. PTY + ghostty-vt Terminal (M5.0 + M5.1). cols/rows 는 (viewport −
    //    좌우 padding) ÷ cell. Windows app_controller 의 size − 2*pad 패턴.
    // shell path — disk 명시값 그대로. 첫 실행 시 host 의 `resolveShell` 이
    // `$SHELL` 또는 `Defaults.shell` 로 disk 에 적었고, 이후 실행은 그 값을
    // 그대로 읽음. 빈 문자열은 `shell_validate.validateOrFatal` 가 잡음.
    const shell_path: []const u8 = g_config.shell;

    const grid = terminalGrid(vp_w_px, vp_h_px, @floatCast(scale_pt));
    const term_cols = grid.cols;
    const term_rows = grid.rows;

    // 자식 셸 환경변수. macOS .app launch 시 부모 environ 에 없을 수 있어 명시
    // 설정. TERM = xterm-256color, LANG = en_US.UTF-8 (bash readline multi-byte
    // 활성화 — 안 하면 한글 byte 를 받아도 echo 안 함). COLORFGBG = TUI dark/
    // light 자동 판별 (Windows `host/windows.zig` 의 buildExtraEnv 와 동등).
    // SHELL = 우리가 spawn 한 셸 path (부모의 SHELL 과 어긋남 방지).
    const colorfgbg_value: []const u8 = if (g_config.theme) |t|
        themes.colorFgBg(t)
    else
        "15;0";
    g_shell_path = try allocator.dupe(u8, shell_path);
    g_extra_env = .{
        .{ .name = "TERM", .value = "xterm-256color" },
        .{ .name = "LANG", .value = "en_US.UTF-8" },
        .{ .name = "LC_CTYPE", .value = "en_US.UTF-8" },
        .{ .name = "COLORFGBG", .value = colorfgbg_value },
        .{ .name = "SHELL", .value = g_shell_path },
    };

    g_session = session_core.SessionCore.init(
        allocator,
        // `-e <실행파일>` 이면 셸 대신 그것을 띄운다 (#382). 인자는 넘길 수 없다 —
        // POSIX 는 PTY 자식의 argv 가 고정이다 (`terminal/posix/pty.zig`).
        g_run_opts.command orelse g_shell_path,
        g_config.max_scroll_lines,
        g_config.theme,
        &g_extra_env,
        onSessionTabExit,
        null,
    );

    try g_session.createTab(term_cols, term_rows);
    log.appendLine("startup", "initial tab created: shell={s} cols={d} rows={d} max_scroll_lines={d}", .{
        shell_path,
        term_cols,
        term_rows,
        g_config.max_scroll_lines,
    });

    // CADisplayLink (#255) — vsync render driver. `NSWindow.displayLink`
    // (macOS 14+) 가 contentView(tildaz_view)의 displayLinkFire: 를 매 vsync
    // main thread 에서 호출. CFRunLoopTimer(60fps 무조건 fire)와 달리 시스템이
    // 합성 타이밍/재생률을 관리하고, 창이 hidden 이면 AppKit 이 자동 suspend
    // 해 idle render 0. common modes 로 등록 — 리사이즈/모달 tracking 중에도 fire.
    {
        const display_link_for = objc.objcSend(fn (objc.id, objc.SEL, objc.id, objc.SEL) callconv(.c) objc.id);
        g_display_link = display_link_for(
            g_window,
            objc.sel("displayLinkWithTarget:selector:"),
            tildaz_view,
            objc.sel("displayLinkFire:"),
        );
        if (g_display_link == null) return error.DisplayLinkCreateFailed;

        const NSRunLoop = objc.getClass("NSRunLoop");
        const main_run_loop = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
        const run_loop = main_run_loop(NSRunLoop, objc.sel("mainRunLoop"));
        // mode: kCFRunLoopCommonModes (CFStringRef) ↔ NSRunLoopCommonModes (NSString)
        // toll-free bridge — 그대로 전달.
        const add_to_run_loop = objc.objcSend(fn (objc.id, objc.SEL, objc.id, CFStringRef) callconv(.c) void);
        add_to_run_loop(g_display_link, objc.sel("addToRunLoop:forMode:"), run_loop, kCFRunLoopCommonModes);
        log.appendLine("startup", "CADisplayLink installed (vsync render driver)", .{});
    }

    // 7. 이벤트 루프.
    // #304 — observer뿐 아니라 window, renderer, 첫 tab, display link까지 준비된
    // 시점이다. distributed notification center가 없으면 앱은 계속 실행하되
    // launcher가 요청을 보내지 않도록 unavailable을 기록한다.
    //
    // #382 — 측정 인스턴스는 기록하지 않는다. Windows 실기에서 확인된 문제인데
    // (`host/windows.zig` 의 같은 지점 주석) `instances.recordEndpointState` 가 공유
    // helper 라 세 host 에 똑같이 있었다 — 측정 인스턴스가 worker 와 같은 index 의
    // 상태를 자기 PID 로 덮으면, 측정이 끝난 뒤 사용자의 새 instance 요청이
    // `RequestEndpointReadyTimeout` 으로 실패한다.
    if (!g_run_opts.isStressRun()) try instances.recordEndpointState(
        allocator,
        instance_context.requireWorkerIndex(),
        if (g_new_instance_observer_registered) .ready else .unavailable,
    );
    log.appendLine("startup", "enter NSApp run loop", .{});
    const runApp = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) void);
    runApp(g_app, objc.sel("run"));
    log.appendLine("startup", "NSApp run loop exited", .{});
}

/// session_core 의 tab_exit_fn — read thread 에서 호출. read thread 안에서
/// closeTabByPtr 직접 호출하면 self-join deadlock (Tab.deinit 이 read_thread
/// .join 부름) → 글로벌 queue 에 enqueue 만 하고 main thread (renderFrameTick)
/// 가 매 frame 시작 시 drain. Windows 의 PostMessage 패턴과 동등 의도.
fn onSessionTabExit(tab_ptr: usize, _: ?*anyopaque) void {
    g_pending_close_mutex.lock();
    defer g_pending_close_mutex.unlock();
    g_pending_close_buf.append(g_gpa.allocator(), tab_ptr) catch {};
}

/// 매 프레임 시작 시 pending close queue drain. main thread 에서 호출되므로
/// closeTabByPtr → Tab.deinit → read_thread.join 이 deadlock 없이 진행.
/// `tab_actions.closeByPtr` 가 마지막 탭 → terminate 자동 호출 (#117 helper)
/// — 호출처는 .changed 만 분기.
fn drainExitedTabs() bool {
    g_pending_close_mutex.lock();
    const closes = g_pending_close_buf.toOwnedSlice(g_gpa.allocator()) catch &.{};
    g_pending_close_mutex.unlock();
    defer g_gpa.allocator().free(closes);

    var any_changed = false;
    for (closes) |ptr| switch (tab_actions.closeByPtr(&g_host, ptr) orelse continue) {
        .ended => {
            log.appendLine("tab", "last tab exited — terminating tildaz", .{});
            return true;
        },
        .changed => {
            // per-tab close 는 session_core 의 cross-platform "[tab] shell exited" 가 이미 기록.
            log.appendLineVerbose("pty", "tab ptr=0x{x} exited, closed", .{ptr});
            any_changed = true;
        },
    };

    // 2 → 1 전환 시 탭바 사라짐 → cell 영역 늘어남. 모든 탭 resize.
    if (any_changed) {
        syncTerminalGeometry();
        g_needs_render = true; // #255 Phase2 — 탭 닫힘 후 새 레이아웃 렌더 (idle 재pause 전).
    }
    return false;
}

/// CADisplayLink (#255) fire — vsync 마다 main thread 호출. ObjC method
/// signature: (self, _cmd, CADisplayLink*). 인자는 안 씀.
fn displayLinkFire(_: objc.id, _: objc.SEL, _: objc.id) callconv(.c) void {
    renderFrameTick();
}

/// #255 Phase 2 — "그릴 게 생겼다" 신호 (main thread 전용, 입력/창 핸들러가 호출).
/// displayLink 는 visible 동안 계속 vsync 로 돌고(규칙적 cadence → 깜빡임 없음 +
/// auto-scroll tick 유지), 이 플래그가 그 frame 에 *render 작업을 할지*만 가른다.
fn requestRender() void {
    g_needs_render = true;
}

/// render tick. 윈도우 hidden 이거나 renderer 미초기화면 skip. cell_w/h 는
/// font 가 측정한 pixel 단위 (Retina backing scale 이미 적용됨).
fn renderFrameTick() void {
    // Per-tab PTY exit 처리 — 마지막 탭이 정리되면 NSApp.terminate (이번 frame
    // 은 더 진행 안 함).
    if (drainExitedTabs()) return;

    // #160 — onrender(프레임 tick 전체) 계측. Windows app_controller 동등.
    const onrender_t0 = perf.now();
    defer perf.addTimed(&perf.onrender, onrender_t0);

    // #245 — drag-select auto-scroll tick (포인터가 grid 경계 밖에 머물면 연속).
    // 스크롤했으면 이번 frame 강제 렌더.
    const did_autoscroll = maybeAutoScrollSelectionMac();

    // #255 Phase 2 / #269 — 모든 탭 output ring을 공통 예산 안에서 drain + parse.
    // 반환값은 활성 탭 본문 또는 어느 탭이든 제목이 바뀌어 현재 화면 redraw가
    // 필요한지 나타낸다. 비활성 탭 본문만 바뀌면 parse하되 GPU render는 생략한다.
    const had_output = g_session.drainOutputForRender();
    // 렌더 게이트: ① PTY 출력 ② 로컬 UI 변화(g_needs_render) ③ preedit/autoscroll
    // ④ blink 위상 전환 (#376).
    const force_render = g_preedit_len > 0 or did_autoscroll;
    // #376 — 위상이 뒤집힌 **그 프레임에만**, 그리고 직전 프레임에 blink 셀이
    // 실제로 보였을 때만 연다. 둘을 함께 봐야 blink 이 없는 화면에서 공짜로
    // 초당 2프레임을 낭비하지 않는다.
    const blink_phase_now = ui_metrics.blinkFaintPhase(std.time.milliTimestamp());
    const blink_tick = blink_phase_now != g_last_blink_phase and
        (if (g_renderer) |r| r.saw_blink_cell else false);
    g_last_blink_phase = blink_phase_now;
    if (!had_output and !force_render and !g_needs_render and !blink_tick) {
        // 변화 없음(idle) → 비싼 render 작업(GPU encode/present) skip. displayLink
        // 는 계속 돌므로 다음 출력/입력은 다음 frame 이 즉시 잡는다(별도 wake 불필요).
        // 단 show 직후 화면 표시(합성)가 확정되기 *전* 이면 skip 하지 않고 정적
        // 내용이라도 계속 그려 합성 완료시킨다 — 합성 전 1프레임만 그리고 멈추면 빈
        // 화면(#252 의 근본). presentedTime(결정적 신호, 매직넘버 없음)으로 표시
        // 확정되면 그때부터 idle skip 시작.
        if (mac_renderer.frameWasPresented()) {
            perf.incExtra(&perf.onrender); // #255 — idle skip frame (render 안 함).
            return;
        }
        // 표시 미확정 → fall through 해 한 프레임 더 그림(present handler 재부착).
    } else {
        g_needs_render = false;
    }

    if (!g_visible) return;
    if (g_renderer == null) return;
    const tab = g_session.activeTab() orelse return;

    // #117 — 활성 탭이 viewport 에 보이도록 scroll 갱신. drag / 사용자 화살표
    // override 중에는 skip.
    if (!g_drag.active and !g_tab_scroll_user_override) ensureActiveTabVisible();
    const cell_w_px: i32 = @intCast(g_renderer.?.font.cell_width_px);
    const cell_h_px: i32 = @intCast(g_renderer.?.font.cell_height_px);
    const pad_px: i32 = ui_metrics.scaledPx(i32, TERMINAL_PADDING_PT, g_renderer.?.scale);
    const tab_bar_px = tabBarHeightPx(g_renderer.?.scale);

    // 탭 제목 stack-allocated slice. 매 프레임 만들지만 alloc 없음. session_core
    // .MAX_TABS = 32 한도와 일치 (cross-platform 동등, Windows 도 [32]).
    var titles_buf: [session_core.MAX_TABS][]const u8 = undefined;
    const tab_count = @min(g_session.count(), titles_buf.len);
    for (g_session.tabs.items[0..tab_count], 0..) |t, i| {
        titles_buf[i] = t.title[0..t.title_len];
    }
    const titles = titles_buf[0..tab_count];

    // IME preedit (`g_preedit_buf`) — cell grid 의 cursor 위치 inline overlay.
    const cell_preedit: []const u8 =
        if (g_preedit_len > 0 and !g_hanja_candidate_active)
            g_preedit_buf[0..g_preedit_len]
        else
            &.{};

    g_renderer.?.renderTabBar(
        titles,
        g_session.active_tab,
        tab.terminal.colors.background.get(),
        g_drag.view(),
        g_tab_scroll_x_px,
        tabBarLayout(),
        g_tab_hover,
    );
    var hotkey_hint_buf: [64]u8 = undefined;
    const hotkey_hint = config.hotkeyDisplay(&hotkey_hint_buf, g_config.hotkey);
    g_renderer.?.renderTerminal(
        &tab.terminal,
        cell_w_px,
        cell_h_px,
        tab_bar_px,
        scrollbarTopInsetPx(g_renderer.?.scale),
        pad_px,
        cell_preedit,
        .{
            .open = g_command_menu_open,
            .hover = g_command_menu_hover,
            .focused = g_command_menu_focus,
            .first_visible = g_command_menu_first,
            .fullscreen_workarea = g_fullscreen_mode == .workarea,
        },
        hotkey_hint,
    );

    // #255 — 이번 frame draw 중 *처음 본* glyph 는 atlas 에 추가되지만(getOrInsert →
    // dirty=true) GPU 업로드는 *다음* frame uploadAtlas 에서 일어난다(현재 upload 는
    // draw 前 순서). 그래서 그 glyph 는 이번 frame 엔 빈칸이고 다음 frame 에 채워진다
    // — Phase 1(60fps 무조건 render)은 자연 보정됐으나, idle skip 이 그 다음 frame 을
    // 없애면 처음 보는 문자(`"`,`(`,`N` 등)가 빈칸으로 남는다. atlas 가 아직 dirty 면
    // 한 frame 더 요청해 업로드+재draw 시킨다(빈칸은 1 frame, Phase 1 과 동일).
    if (g_renderer.?.atlas.dirty or g_renderer.?.tabAtlasDirty()) g_needs_render = true;
}

/// CGEventTap 생성 + run loop source 등록 + 활성화. 권한 없으면 사용자 안내 후
/// tap 없이 진행 (mainMenu Cmd+Q 는 동작).
fn installEventTap() !void {
    // active CGEventTap 은 두 권한이 모두 필요: Input Monitoring (preflight) +
    // Accessibility (이벤트 consume / 변조). 한쪽만 있으면 CGEventTapCreate 가
    // null 반환.
    const has_input = CGPreflightListenEventAccess();
    const has_ax = AXIsProcessTrusted();
    if (!has_input or !has_ax) {
        if (!has_input) _ = CGRequestListenEventAccess();
        // 다이얼로그로 사용자에게 안내 + 로그 한 줄. stdout 으로 안 찍어 — 사용자가
        // .app 으로 띄우면 stdout 안 보고 다이얼로그를 봐야 함.
        var hotkey_buf: [64]u8 = undefined;
        const hotkey = config.hotkeyDisplay(&hotkey_buf, g_config.hotkey);
        var msg_buf: [2048]u8 = undefined;
        const msg = std.fmt.bufPrint(
            &msg_buf,
            messages.macos_permission_required_format,
            .{
                hotkey,
                if (has_input) messages.permission_status_granted else messages.permission_status_missing,
                if (has_ax) messages.permission_status_granted else messages.permission_status_missing,
            },
        ) catch messages.macos_permission_required_fallback_msg;

        log.appendLine("perm", "missing — input_monitoring={s} accessibility={s}", .{
            if (has_input) "OK" else "missing",
            if (has_ax) "OK" else "missing",
        });
        // #249 — installEventTap 은 `[NSApp run]` *전* 에 호출된다. 이 시점에 곧장
        // showInfo 를 부르면 run loop 가 없어 활성화(activateIgnoringOtherApps)가
        // 적용 안 되고 alert 가 key window 가 못 돼 키보드를 못 받는다. 그래서
        // main queue 로 dispatch 해 run loop 시작 *후* 에 띄운다 — 그때는 앱이
        // active 가 돼 런타임 다이얼로그와 똑같이 key 를 얻는다 (실측 확인).
        g_perm_msg_len = @min(msg.len, g_perm_msg_buf.len);
        @memcpy(g_perm_msg_buf[0..g_perm_msg_len], msg[0..g_perm_msg_len]);
        dispatch_async_f(&_dispatch_main_q, null, showPermDialogTrampoline);
        return;
    }

    try createAndRegisterEventTap();
}

/// CGEventTapCreate + run loop source 등록 + Enable. Permission preflight 는
/// 호출자 (`installEventTap` 또는 recreate path) 가 책임. 실패 시 module-level
/// `g_event_tap` / `g_runloop_source` 는 null 인 채로 남음.
fn createAndRegisterEventTap() !void {
    const mask: u64 = @as(u64, 1) << @as(u6, @intCast(kCGEventKeyDown));
    g_event_tap = CGEventTapCreate(
        kCGSessionEventTap,
        kCGHeadInsertEventTap,
        kCGEventTapOptionDefault,
        mask,
        eventTapCallback,
        null,
    );
    if (g_event_tap == null) {
        log.appendLine("hotkey", "CGEventTapCreate failed — permissions may need to be renewed", .{});
        return error.TapCreateFailed;
    }

    g_runloop_source = CFMachPortCreateRunLoopSource(null, g_event_tap, 0);
    if (g_runloop_source == null) {
        CFMachPortInvalidate(g_event_tap);
        CFRelease(@ptrCast(g_event_tap));
        g_event_tap = null;
        return error.RunLoopSourceFailed;
    }

    CFRunLoopAddSource(CFRunLoopGetMain(), g_runloop_source, kCFRunLoopCommonModes);
    CGEventTapEnable(g_event_tap, true);
}

/// CGEventTapEnable(true) 만으로 안 살아나는 OS-invalidated tap 을 destroy
/// 후 새로 만들어 등록. 콜백 안에서 자기 자신을 invalidate 하면 안 되므로
/// `dispatch_async_f` 로 main run loop 다음 turn 에서 호출되도록 dispatch.
/// (#152)
fn recreateEventTap() void {
    if (g_runloop_source != null) {
        CFRunLoopRemoveSource(CFRunLoopGetMain(), g_runloop_source, kCFRunLoopCommonModes);
        CFRelease(@ptrCast(g_runloop_source));
        g_runloop_source = null;
    }
    if (g_event_tap != null) {
        CFMachPortInvalidate(g_event_tap);
        CFRelease(@ptrCast(g_event_tap));
        g_event_tap = null;
    }
    createAndRegisterEventTap() catch |err| {
        log.appendLine("hotkey", "recreateEventTap failed: {s}", .{@errorName(err)});
        return;
    };
    log.appendLine("hotkey", "CGEventTap recreated", .{});
}

/// `dispatch_async_f` 트램폴린 — context 무시하고 recreateEventTap 호출.
fn recreateEventTapTrampoline(_: ?*anyopaque) callconv(.c) void {
    recreateEventTap();
}

/// `dispatch_async_f` 트램폴린 — run loop 시작 후 권한 안내 다이얼로그 표시 (#249).
/// 인자를 못 받아 메시지는 module-level `g_perm_msg_buf` 에서 읽는다.
fn showPermDialogTrampoline(_: ?*anyopaque) callconv(.c) void {
    dialog.showInfo(messages.macos_permission_required_title, g_perm_msg_buf[0..g_perm_msg_len]);
    // dialog 가 닫히면서 key window 를 우리 윈도우로 안 돌려줄 수 있어 강제 복원.
    showWindow();
}

/// CGEventTap 콜백 — keycode + modifier 검사해서 config.hotkey 면
/// \"이벤트 삼킴\" (null 반환), 아니면 그대로 passthrough (event 반환). Cmd+Q 는
/// #153 에서 NSMenu 의 \"Quit TildaZ\" 로 위임 (active 상태에서만 dispatch).
///
/// macOS 가 tap 을 timeout / user-input race 로 자동 비활성화하면 special
/// event type 이 들어옴 (#146). 처리 안 하면 다시 활성화 안 되어 F1 hotkey
/// 영원히 안 옴 — 다른 앱으로 focus 갔다 돌아왔을 때 흔히 재현.
///
/// 1차 시도: `CGEventTapEnable(true)` 로 re-enable (단발 timeout 대부분 OK).
/// 짧은 시간 (REPEAT_WINDOW_MS) 안에 disable 이 반복되면 OS 가 tap 을 truly
/// invalidate 한 케이스 (#152) — `Enable(true)` 가 boolean 성공처럼 리턴해도
/// events 안 옴. tap 을 destroy + recreate 해야 살아남. 콜백 안에서 invalidate
/// 하면 안 되므로 main queue 로 dispatch.
fn eventTapCallback(
    _: ?*anyopaque,
    event_type: CGEventType,
    event: CGEventRef,
    _: ?*anyopaque,
) callconv(.c) CGEventRef {
    if (event_type == kCGEventTapDisabledByTimeout or event_type == kCGEventTapDisabledByUserInput) {
        const REPEAT_WINDOW_MS: i64 = 30_000;
        const now_ms = std.time.milliTimestamp();
        const recent = (now_ms - g_last_tap_disable_ms) < REPEAT_WINDOW_MS;
        g_last_tap_disable_ms = now_ms;
        if (recent) {
            log.appendLine("hotkey", "CGEventTap disabled (type={d}) — repeat within {d}s, scheduling recreate", .{ event_type, @divTrunc(REPEAT_WINDOW_MS, 1000) });
            dispatch_async_f(&_dispatch_main_q, null, recreateEventTapTrampoline);
        } else {
            log.appendLine("hotkey", "CGEventTap disabled (type={d}) — re-enabling", .{event_type});
            if (g_event_tap != null) CGEventTapEnable(g_event_tap, true);
        }
        return event;
    }
    const keycode_i64 = CGEventGetIntegerValueField(event, kCGKeyboardEventKeycode);
    const flags = CGEventGetFlags(event);
    const mods = flags & kCGEventFlagsAllModifiers;
    const keycode: u32 = @intCast(keycode_i64);

    // 단축키 입력 dialog 동안에는 기존 worker 의 hotkey 를 통과시켜 local
    // NSEvent monitor 가 실제 조합을 받게 한다.
    if (@import("../hotkey_capture/macos.zig").isSuspended()) return event;

    // 사용자 toggle hotkey (config.hotkey).
    if (keycode == g_config.hotkey.keycode and mods == g_config.hotkey.modifiers) {
        toggleWindow();
        return null;
    }

    // Cmd+Q 글로벌 가로채기는 #153 에서 제거. NSMenu 의 "Quit TildaZ"
    // (`terminate:` + keyEquivalent="q") 가 active 상태에서 표준 dispatch.
    // TildazWindow 가 `canBecomeKeyWindow` YES override 라 borderless 여도
    // mainMenu shortcut 정상 작동. 글로벌 hook 이 있던 시절엔 다른 앱이
    // frontmost 일 때 Cmd+Q 가 그 앱이 아니라 tildaz 종료 dialog 를 띄우는
    // 버그가 있었음.

    return event; // passthrough.
}

/// 현재 메인 스크린의 dock rect 를 `g_config` 의 `dock_position` / `width` /
/// `height` / `offset` 으로 계산해 윈도우에 적용. macOS 좌표계는
/// **bottom-up** — top dock 은 y = (usable max y) - h.
///
/// Dock 처리:
///   - `visibleFrame` 은 메뉴바 + (보이는) Dock 을 뺀 영역.
///   - Dock 자동 숨김 모드 (또는 좌/우/우측 dock) 면 visibleFrame.minY 가
///     frame.minY 와 거의 같아짐 (4pt 미만의 reserved sliver 제외). 그 경우
///     사용자가 \"화면 끝까지 와 줘\" 라고 지정했으므로 frame.minY 까지 사용.
///   - 메뉴바는 어떤 경우에도 회피해야 하므로 `frame.maxY - visibleFrame.maxY`
///     만큼 위쪽을 빼고 사용.
/// #240 — drop-down 이 뜰 스크린 = 마우스 커서가 있는 스크린 (drop-down 표준 UX,
/// SPEC §1 '표시 모니터'). `NSScreen.mainScreen` 은 키 윈도우/메뉴바 스크린이라 공식적으론
/// 커서 모니터가 아님 (Windows `MonitorFromPoint(GetCursorPos)` / Linux current_monitor 동등).
/// `NSEvent.mouseLocation`(global, NSScreen.frame 과 같은 좌표 공간)을 포함하는 NSScreen 을
/// 찾고, 없으면 mainScreen fallback. 경계는 half-open [origin, origin+size) — 두 모니터
/// 인접 경계에서 한쪽만 claim.
fn screenForCursor() objc.id {
    const NSScreen = objc.getClass("NSScreen");
    const NSEvent = objc.getClass("NSEvent");
    const mouseLoc = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) NSPoint);
    const cursor = mouseLoc(NSEvent, objc.sel("mouseLocation"));

    const getScreens = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const screens = getScreens(NSScreen, objc.sel("screens"));
    if (screens != null) {
        const countMsg = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) u64);
        const objAt = objc.objcSend(fn (objc.id, objc.SEL, u64) callconv(.c) objc.id);
        const getRect = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) NSRect);
        const n = countMsg(screens, objc.sel("count"));
        var i: u64 = 0;
        while (i < n) : (i += 1) {
            const s = objAt(screens, objc.sel("objectAtIndex:"), i) orelse continue;
            const f = getRect(s, objc.sel("frame"));
            if (cursor.x >= f.origin.x and cursor.x < f.origin.x + f.size.width and
                cursor.y >= f.origin.y and cursor.y < f.origin.y + f.size.height)
            {
                return s;
            }
        }
    }
    const mainScreen = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    return mainScreen(NSScreen, objc.sel("mainScreen"));
}

fn repositionWindow() void {
    const screen = screenForCursor() orelse return;

    // arm64 macOS 의 NSRect 반환은 일반 레지스터 ABI — stret variant 불필요.
    const getRectSel = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) NSRect);
    const visible = getRectSel(screen, objc.sel("visibleFrame"));
    const frame = getRectSel(screen, objc.sel("frame"));

    // Dock 이 화면 하단에 보이고 있는지 추정. 자동 숨김 모드는 4pt 정도의
    // \"reserved sliver\" 가 visibleFrame 에 남는 경우가 있어 임계값 10pt.
    const dock_bottom_height = visible.origin.y - frame.origin.y;
    const dock_visible_at_bottom = dock_bottom_height >= 10.0;

    // 사용 가능한 세로 영역 — 메뉴바는 항상 빼고, Dock 은 보일 때만 빼기.
    const usable_max_y = visible.origin.y + visible.size.height; // = frame.maxY - menubarH
    const usable_min_y = if (dock_visible_at_bottom) visible.origin.y else frame.origin.y;
    const usable_height = usable_max_y - usable_min_y;

    // 가로는 visibleFrame 그대로 — 좌/우 dock 의 경우 visibleFrame.width 가
    // 자동으로 줄어 있음.
    const sw = visible.size.width;
    const sx = visible.origin.x;

    const width_percent: f64 = @floatCast(g_config.width_percent);
    const height_percent: f64 = @floatCast(g_config.height_percent);
    const offset_percent: f64 = @floatCast(g_config.offset_percent);

    var w = sw * width_percent / 100.0;
    var h = usable_height * height_percent / 100.0;

    // #382 — `-size COLSxROWS` 는 config 의 퍼센트를 무시하고 **셀 개수**로 창을 만든다.
    // 셀 크기는 폰트 metrics 에서 나오므로 renderer 초기화 뒤에만 계산할 수 있다. 그
    // 전에 불린 호출은 퍼센트로 두고 (창이 잠깐 다른 크기로 뜬다), 초기화 직후 이 함수를
    // 다시 불러 맞춘다 — `run()` 의 renderer init 뒤 블록이 그 일을 한다.
    if (g_run_opts.grid) |want| {
        if (g_renderer) |r| {
            const backing = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) f64);
            const scale = backing(g_window, objc.sel("backingScaleFactor"));
            const scale_f: f32 = @floatCast(scale);
            const vp = ui_metrics.viewportForGrid(
                want.cols,
                want.rows,
                ui_metrics.scaledPx(i64, TERMINAL_PADDING_PT, scale_f),
                ui_metrics.scaledPx(i64, ui_metrics.SCROLLBAR_W_PT, scale_f),
                tabBarHeightPx(scale_f),
                r.font.cell_width_px,
                r.font.cell_height_px,
            );
            // viewport 는 physical px, 창 frame 은 logical pt 다.
            w = @as(f64, @floatFromInt(vp.w)) / scale;
            h = @as(f64, @floatFromInt(vp.h)) / scale;
        }
    }

    // dock_position 별로 x / y 결정. macOS 의 bottom-up 좌표계 주의.
    const x: f64 = switch (g_config.dock_position) {
        .left => sx,
        .right => sx + sw - w,
        .top, .bottom => sx + (sw - w) * offset_percent / 100.0,
    };
    const y: f64 = switch (g_config.dock_position) {
        .top => usable_max_y - h,
        .bottom => usable_min_y,
        .left, .right => usable_min_y + (usable_height - h) * offset_percent / 100.0,
    };

    // Fullscreen 모드별 rect 결정 (#162). dock 모드는 위에서 계산한 rect.
    const final_rect = switch (g_fullscreen_mode) {
        .none => NSRect{ .origin = .{ .x = x, .y = y }, .size = .{ .width = w, .height = h } },
        .monitor => frame, // 메뉴바 + dock 까지 덮음
        .workarea => visible, // 메뉴바 + dock 회피
    };
    const setFrameDisplay = objc.objcSend(fn (objc.id, objc.SEL, NSRect, bool) callconv(.c) void);
    setFrameDisplay(g_window, objc.sel("setFrame:display:"), final_rect, true);
}

/// 단축키 (Cmd+Enter / Shift+Cmd+Enter) 핸들러. self-symmetric 토글 — 들어간
/// 키로만 나옴 (Windows `Window.toggleFullscreenMode` 와 동등).
fn toggleFullscreenMode(target: FullscreenMode) void {
    requestRender(); // #255 Phase2 — 전체화면 토글 → 렌더.
    if (g_fullscreen_mode == target) {
        g_fullscreen_mode = .none;
    } else if (g_fullscreen_mode == .none) {
        g_fullscreen_mode = target;
    } else {
        return; // 다른 모드 → no-op
    }
    // 풀-패스 재동기화 — repositionWindow 만 부르면 window frame 만 변경되어
    // cell metric 그대로 → 글자만 늘어나 보임 (시연 회귀). syncGeometryAfter
    // ScreenChange 가 frame 변경 + drawable + renderer viewport + 각 탭의
    // ghostty Terminal / PTY winsize 까지 새 cols/rows 로 resize. 모니터 변경
    // path 와 같음.
    syncGeometryAfterScreenChange();
}

fn showWindow() void {
    mac_renderer.resetFramePresented(); // #255 Phase2 — hidden→visible 재합성: 표시 확정 리셋.
    requestRender();
    // popup level 복구 — emoji picker / dialog 같은 path 가 잠시 normal 로
    // 낮춘 후 다음 toggle 시 popup 으로 자동 복귀.
    const NSPopUpMenuWindowLevel: c_int = 101;
    const setLevel = objc.objcSend(fn (objc.id, objc.SEL, c_int) callconv(.c) void);
    setLevel(g_window, objc.sel("setLevel:"), NSPopUpMenuWindowLevel);

    const makeKeyAndOrderFront = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    makeKeyAndOrderFront(g_window, objc.sel("makeKeyAndOrderFront:"), null);

    const activate = objc.objcSend(fn (objc.id, objc.SEL, bool) callconv(.c) void);
    activate(g_app, objc.sel("activateIgnoringOtherApps:"), true);

    restoreContentViewFocus();
    g_visible = true;
}

/// contentView (TildazView) 를 firstResponder 로 강제. NSAlert.runModal 후
/// firstResponder 가 dialog OK 버튼에 잡혀 우리 view 로 안 돌아오는 케이스
/// 회피 — 권한 dialog 닫고 사용자가 마우스 클릭 안 해도 바로 타이핑 가능.
fn restoreContentViewFocus() void {
    const contentView_get = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);
    const cv = contentView_get(g_window, objc.sel("contentView"));
    if (cv != null) {
        const makeFirstResponder = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) bool);
        _ = makeFirstResponder(g_window, objc.sel("makeFirstResponder:"), cv);
    }
}

fn hideWindow() void {
    const orderOut = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    orderOut(g_window, objc.sel("orderOut:"), null);
    g_visible = false;
}

fn toggleWindow() void {
    if (g_visible) {
        // #175/#317 — F1 hide도 공통 shortcut 정책의 focus_loss = commit.
        applyShortcutInputPolicy(.toggle_visibility);
        // #329 — 열린 menu 는 hide 때 닫는다. 다음 show 에 남지 않게.
        if (g_command_menu_open) closeCommandMenu();
        // per-toggle — verbose (#197 Option B, 3 플랫폼 공통 category "toggle").
        log.appendLineVerbose("toggle", "hide", .{});
        hideWindow();
    } else {
        // 화면 / Dock 변화 대비해 매번 dock rect 재계산.
        log.appendLineVerbose("toggle", "show", .{});
        repositionWindow();
        showWindow();
    }
}

// CGEventTap 보관용 module-level 변수. CFRunLoopAddSource 후에도 OS 가 mach
// port 와 source 를 참조하므로 process 수명동안 살아 있어야 한다.
var g_event_tap: CFMachPortRef = null;
var g_runloop_source: CFRunLoopSourceRef = null;

// 마지막 tap-disable 이벤트의 wall-clock millis. 짧은 시간 안에 재발하면
// `CGEventTapEnable(true)` 만으로는 안 살아나는 케이스라 destroy + recreate
// path 로 escalate (#152).
var g_last_tap_disable_ms: i64 = 0;

// #249 — installEventTap 의 권한 안내 메시지를 run loop 시작 후 dispatch 로 띄우려
// 임시 보관. dispatch 트램폴린은 인자를 못 받아 module-level 에 둔다.
var g_perm_msg_buf: [2048]u8 = undefined;
var g_perm_msg_len: usize = 0;

/// `About TildaZ` menu item action. Selector 는 NSApplication 에 등록되어
/// responder chain 의 마지막 단계 (NSApp) 에서 항상 dispatch 된다 — 윈도우가
/// hide 상태여도 동작.
fn tildazShowAboutAction(self: objc.id, _sel: objc.SEL, sender: objc.id) callconv(.c) void {
    _ = self;
    _ = _sel;
    _ = sender;
    applyShortcutInputPolicy(.show_about);
    about.showAboutDialog();
}

/// Shift+Cmd+P — 현재 worker의 config_N.json 을 default editor 로 열기 (#128). About 와 같은
/// NSApplication-level selector 패턴.
fn tildazOpenConfigAction(self: objc.id, _sel: objc.SEL, sender: objc.id) callconv(.c) void {
    _ = self;
    _ = _sel;
    _ = sender;
    applyShortcutInputPolicy(.open_config);
    const allocator = g_gpa.allocator();
    const path = @import("../paths.zig").configPath(allocator) catch return;
    defer allocator.free(path);
    @import("../system_open.zig").openInDefaultApp(allocator, path);
}

/// Shift+Cmd+L — 현재 worker의 tildaz_N.log 를 default editor 로 열기 (#128).
fn tildazOpenLogAction(self: objc.id, _sel: objc.SEL, sender: objc.id) callconv(.c) void {
    _ = self;
    _ = _sel;
    _ = sender;
    applyShortcutInputPolicy(.open_log);
    const allocator = g_gpa.allocator();
    const path = log.filePath() orelse return;
    @import("../system_open.zig").openInDefaultApp(allocator, path);
}

/// Cmd+Q / Quit TildaZ menu action. 표준 `terminate:`를 menu item에 직접
/// 연결하면 applicationShouldTerminate: 안에서 commit한 뒤 원래 key event의
/// IME 후속 `insertText:`가 Cancel 복귀 시 terminal로 한 번 더 들어간다 (#317).
/// 다른 상태변경 menu action처럼 native action 진입 전에 공통 정책을 적용한 뒤
/// terminate:를 호출한다. delegate의 두 번째 적용은 pending이 비어 no-op이다.
fn requestApplicationQuit(sender: objc.id) void {
    const terminate = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    terminate(g_app, objc.sel("terminate:"), sender);
}

fn tildazQuitTrampoline(_: ?*anyopaque) callconv(.c) void {
    tildazQuitAction(g_app, objc.sel("tildazQuit:"), null);
}

fn tildazQuitAction(self: objc.id, _sel: objc.SEL, sender: objc.id) callconv(.c) void {
    _ = self;
    _ = _sel;
    applyShortcutInputPolicy(.quit);
    requestApplicationQuit(sender);
}

/// Ctrl+Cmd+Space — Show Emoji & Symbols picker (#130). 우리 popup-level
/// (101) 윈도우가 emoji panel 위에 가리는 문제 회피 위해 잠시 normal level
/// 로 낮춤. 다음 toggle (F1 / hotkey) 시 `showWindow` 가 popup 으로 복구.
///
/// 2026-07-13 실기 (macOS 26.5.2 + v0.6.1) 기준 picker 는 cursor-anchored
/// popover 로 뜨고 focus loss 에 자동 dismiss 됨 (SPEC.md §5.2). 과거엔
/// floating panel + no auto-dismiss 였음 — 원인 미확정 (SPEC.md 부록 B
/// 이력 노트). 아래 Esc dismiss 보강은 구 동작 환경 대비로 유지.
///
/// Esc 로 dismiss 가능 — `tildazKeyDown` 이 `isEmojiPickerOpen()` 으로 panel
/// 의 *실제 visibility* 를 매번 query (NSApp.orderedWindows 순회 + class name
/// 매칭) → picker 떠 있을 때 modifier 없는 Esc 면 다시 `orderFrontCharacterPalette:`
/// 호출 (toggle 닫힘). picker 가 외부 path 로 닫혀도 stale 안 됨 — boolean
/// 추적이 아닌 직접 query.
fn tildazShowEmojiAction(self: objc.id, _sel: objc.SEL, sender: objc.id) callconv(.c) void {
    _ = self;
    _ = _sel;
    _ = sender;
    const NSNormalWindowLevel: c_int = 0;
    const setLevel = objc.objcSend(fn (objc.id, objc.SEL, c_int) callconv(.c) void);
    setLevel(g_window, objc.sel("setLevel:"), NSNormalWindowLevel);
    const activate = objc.objcSend(fn (objc.id, objc.SEL, bool) callconv(.c) void);
    activate(g_app, objc.sel("activateIgnoringOtherApps:"), true);
    const orderFront = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    orderFront(g_app, objc.sel("orderFrontCharacterPalette:"), null);
}

// CoreGraphics window list — 모든 process 의 onscreen 윈도우 query (#130).
// emoji picker 는 별도 process (`com.apple.CharacterPaletteIM` 등 Apple Input
// Method bundle) 가 호스팅 → 우리 NSApp.orderedWindows 로는 안 보임.
const CGWindowListOption = u32;
const kCGWindowListOptionOnScreenOnly: CGWindowListOption = 1 << 0;
const kCGWindowListExcludeDesktopElements: CGWindowListOption = 1 << 4;
const kCGNullWindowID: u32 = 0;
extern fn CGWindowListCopyWindowInfo(option: CGWindowListOption, relativeToWindow: u32) objc.id;
extern fn CFRelease(cf: ?*anyopaque) void;
extern const kCGWindowOwnerPID: objc.id;

/// Show Emoji & Symbols panel 이 현재 떠 있는지 — `CGWindowListCopyWindowInfo`
/// 로 onscreen 윈도우 순회, 각 owner PID 를 NSRunningApplication 으로 풀어
/// `bundleIdentifier` 매칭. owner name 은 localized 라 (한글: "이모지 및 기호",
/// 영어: "Emoji & Symbols") bundle ID 로 식별 — locale-independent.
///
/// 매칭 prefix `com.apple.Character` — 현재 macOS 의 `com.apple.CharacterPaletteIM`
/// + 다른 Apple Character* 변형 (`CharacterPicker` / `CharacterViewer` 등 미래
/// 가능성) cover. 권한: `kCGWindowOwnerPID` 는 Screen Recording 권한 불필요.
///
/// 매 Esc keyDown 마다 호출 — CGWindowListCopyWindowInfo 자체는 fast (us 단위),
/// 보통 onscreen 윈도우 ~20 개라 iteration 부담 없음.
fn isEmojiPickerOpen() bool {
    const info = CGWindowListCopyWindowInfo(
        kCGWindowListOptionOnScreenOnly | kCGWindowListExcludeDesktopElements,
        kCGNullWindowID,
    );
    if (info == null) return false;
    defer CFRelease(@ptrCast(info));

    const get_count = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) usize);
    const obj_at = objc.objcSend(fn (objc.id, objc.SEL, usize) callconv(.c) objc.id);
    const dict_get = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) objc.id);
    const utf8 = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) ?[*:0]const u8);
    const get_int = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) c_int);
    const ra_for_pid = objc.objcSend(fn (objc.Class, objc.SEL, c_int) callconv(.c) objc.id);
    const ra_send = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);

    const NSRunningApplication = objc.getClass("NSRunningApplication");
    const count = get_count(info, objc.sel("count"));

    var i: usize = 0;
    while (i < count) : (i += 1) {
        const dict = obj_at(info, objc.sel("objectAtIndex:"), i);
        if (dict == null) continue;
        const pid_obj = dict_get(dict, objc.sel("objectForKey:"), kCGWindowOwnerPID);
        if (pid_obj == null) continue;
        const pid = get_int(pid_obj, objc.sel("intValue"));
        const ra = ra_for_pid(NSRunningApplication, objc.sel("runningApplicationWithProcessIdentifier:"), pid);
        if (ra == null) continue;
        const bid = ra_send(ra, objc.sel("bundleIdentifier"));
        if (bid == null) continue;
        const b_cstr = utf8(bid, objc.sel("UTF8String")) orelse continue;
        const b_slice = std.mem.span(b_cstr);
        if (std.mem.startsWith(u8, b_slice, "com.apple.Character")) return true;
    }
    return false;
}

fn buildMainMenu(app: objc.id) !void {
    const NSMenu = objc.getClass("NSMenu");
    const NSMenuItem = objc.getClass("NSMenuItem");
    const alloc = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const init_obj = objc.objcSend(fn (objc.id, objc.SEL) callconv(.c) objc.id);

    // About / Open Config / Open Log / Quit 핸들러를 NSApplication 인스턴스
    // 메서드로 등록. 윈도우 hide 상태라도 NSApp에서 dispatch.
    const NSApplication = objc.getClass("NSApplication");
    if (!objc.class_addMethod(NSApplication, objc.sel("tildazShowAbout:"), @ptrCast(&tildazShowAboutAction), "v@:@"))
        return error.AddAboutMethodFailed;
    if (!objc.class_addMethod(NSApplication, objc.sel("tildazOpenConfig:"), @ptrCast(&tildazOpenConfigAction), "v@:@"))
        return error.AddOpenConfigMethodFailed;
    if (!objc.class_addMethod(NSApplication, objc.sel("tildazOpenLog:"), @ptrCast(&tildazOpenLogAction), "v@:@"))
        return error.AddOpenLogMethodFailed;
    if (!objc.class_addMethod(NSApplication, objc.sel("tildazQuit:"), @ptrCast(&tildazQuitAction), "v@:@"))
        return error.AddQuitMethodFailed;
    if (!objc.class_addMethod(NSApplication, objc.sel("tildazShowEmoji:"), @ptrCast(&tildazShowEmojiAction), "v@:@"))
        return error.AddShowEmojiMethodFailed;

    const main_menu = init_obj(alloc(NSMenu, objc.sel("alloc")) orelse return error.MenuAllocFailed, objc.sel("init")) orelse return error.MenuInitFailed;

    const app_item = init_obj(alloc(NSMenuItem, objc.sel("alloc")) orelse return error.MenuItemAllocFailed, objc.sel("init")) orelse return error.MenuItemInitFailed;
    const addItem = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    addItem(main_menu, objc.sel("addItem:"), app_item);

    const app_menu = init_obj(alloc(NSMenu, objc.sel("alloc")) orelse return error.MenuAllocFailed, objc.sel("init")) orelse return error.MenuInitFailed;

    const initItem = objc.objcSend(fn (objc.id, objc.SEL, objc.id, objc.SEL, objc.id) callconv(.c) objc.id);

    const about_alloc = alloc(NSMenuItem, objc.sel("alloc")) orelse return error.MenuItemAllocFailed;
    // Shift+Cmd+I — macOS 표준 modifier (Cmd) + 다른 탭 단축키 (Cmd+T/W/숫자/[/])
    // 와 일관. Accessory mode 라 메뉴바 UI 는 안 보이지만 NSApp 의
    // `performKeyEquivalent:` 가 mainMenu 를 훑어 dispatch 하므로 키만으로
    // 동작 (Cmd+Q 와 같은 메커니즘).
    // shift modifier 가 있으면 keyEquivalent 는 lowercase 로 둠 (Apple HIG).
    const about_item = initItem(
        about_alloc,
        objc.sel("initWithTitle:action:keyEquivalent:"),
        objc.nsString(messages.about_title),
        objc.sel("tildazShowAbout:"),
        objc.nsString("i"),
    ) orelse return error.AboutItemInitFailed;
    const NSEventModifierFlagShift: c_ulong = 1 << 17;
    const NSEventModifierFlagCommand: c_ulong = 1 << 20;
    const setMask = objc.objcSend(fn (objc.id, objc.SEL, c_ulong) callconv(.c) void);
    setMask(about_item, objc.sel("setKeyEquivalentModifierMask:"), NSEventModifierFlagCommand | NSEventModifierFlagShift);
    addItem(app_menu, objc.sel("addItem:"), about_item);

    // Shift+Cmd+P — Open Config (#128). About 와 같은 NSApp-level dispatch.
    const config_alloc = alloc(NSMenuItem, objc.sel("alloc")) orelse return error.MenuItemAllocFailed;
    const config_item = initItem(
        config_alloc,
        objc.sel("initWithTitle:action:keyEquivalent:"),
        objc.nsString(messages.macos_menu_open_config_label),
        objc.sel("tildazOpenConfig:"),
        objc.nsString("p"),
    ) orelse return error.OpenConfigItemInitFailed;
    setMask(config_item, objc.sel("setKeyEquivalentModifierMask:"), NSEventModifierFlagCommand | NSEventModifierFlagShift);
    addItem(app_menu, objc.sel("addItem:"), config_item);

    // Shift+Cmd+L — Open Log (#128).
    const log_alloc = alloc(NSMenuItem, objc.sel("alloc")) orelse return error.MenuItemAllocFailed;
    const log_item = initItem(
        log_alloc,
        objc.sel("initWithTitle:action:keyEquivalent:"),
        objc.nsString(messages.macos_menu_open_log_label),
        objc.sel("tildazOpenLog:"),
        objc.nsString("l"),
    ) orelse return error.OpenLogItemInitFailed;
    setMask(log_item, objc.sel("setKeyEquivalentModifierMask:"), NSEventModifierFlagCommand | NSEventModifierFlagShift);
    addItem(app_menu, objc.sel("addItem:"), log_item);

    // separator
    const NSMenuItem_class = objc.getClass("NSMenuItem");
    const separatorItem = objc.objcSend(fn (objc.Class, objc.SEL) callconv(.c) objc.id);
    const sep = separatorItem(NSMenuItem_class, objc.sel("separatorItem")) orelse return error.SeparatorFailed;
    addItem(app_menu, objc.sel("addItem:"), sep);

    const item_alloc = alloc(NSMenuItem, objc.sel("alloc")) orelse return error.MenuItemAllocFailed;
    const quit_item = initItem(
        item_alloc,
        objc.sel("initWithTitle:action:keyEquivalent:"),
        objc.nsString(messages.macos_menu_quit_label),
        objc.sel("tildazQuit:"),
        objc.nsString("q"),
    ) orelse return error.QuitItemInitFailed;
    addItem(app_menu, objc.sel("addItem:"), quit_item);

    const setSubmenu = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    setSubmenu(app_item, objc.sel("setSubmenu:"), app_menu);

    // Edit menu — "Emoji & Symbols" menu item 으로 macOS 의 Show Emoji & Symbols
    // system shortcut (Apple default `Ctrl+Cmd+Space`) 라우팅. 이전 시도:
    // selector `orderFrontCharacterPalette:` (Apple 표준) + 빈 keyEquivalent
    // 로 *system 자동 매핑* 기대 — 동작 안 함. 그래서 explicit keyEquivalent
    // 로 hardcode + 우리 selector `tildazShowEmoji:` 로 라우팅 (popup-level
    // toggle 등 추가 처리). Terminal.app / ghostty 모두 비슷한 explicit menu
    // item 패턴.
    const edit_item = init_obj(alloc(NSMenuItem, objc.sel("alloc")) orelse return error.MenuItemAllocFailed, objc.sel("init")) orelse return error.MenuItemInitFailed;
    addItem(main_menu, objc.sel("addItem:"), edit_item);

    const edit_menu_init = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) objc.id);
    const edit_menu = edit_menu_init(alloc(NSMenu, objc.sel("alloc")) orelse return error.MenuAllocFailed, objc.sel("initWithTitle:"), objc.nsString(messages.macos_menu_edit_label)) orelse return error.MenuInitFailed;

    // Ctrl+Cmd+Space → tildazShowEmoji: — NSApp.sendEvent 단계에서 menu
    // shortcut 매칭 자동 라우팅 → 우리 view keyDown 까지 안 와서 PTY 안 흘림.
    // 사용자가 System Settings 에서 단축키를 다른 키로 변경한 경우 매칭 안 됨
    // (low-priority 한계, 우회: System Settings 에서 default 복구).
    const NSEventModifierFlagCtrl: c_ulong = 1 << 18;
    {
        const emoji_alloc = alloc(NSMenuItem, objc.sel("alloc")) orelse return error.MenuItemAllocFailed;
        const item = initItem(
            emoji_alloc,
            objc.sel("initWithTitle:action:keyEquivalent:"),
            objc.nsString(messages.macos_menu_emoji_symbols_label),
            objc.sel("tildazShowEmoji:"),
            objc.nsString(" "),
        ) orelse return error.EmojiItemInitFailed;
        setMask(item, objc.sel("setKeyEquivalentModifierMask:"), NSEventModifierFlagCtrl | NSEventModifierFlagCommand);
        addItem(edit_menu, objc.sel("addItem:"), item);
    }

    setSubmenu(edit_item, objc.sel("setSubmenu:"), edit_menu);

    const setMainMenu = objc.objcSend(fn (objc.id, objc.SEL, objc.id) callconv(.c) void);
    setMainMenu(app, objc.sel("setMainMenu:"), main_menu);
}