ghostty-rs/docs/rewrite/notes/ghostty-inspector.md

# ghostty-inspector (agent I1): terminal inspector

Ports `ZIG/src/inspector/*` (Inspector, widgets/{key,page,pagelist,renderer,screen,style,surface,terminal,termio}, units),
the GTK classes `imgui_widget`, `inspector_widget`, `inspector_window` (+ their `.blp`), and the core Surface hooks.

## Stack
`dear-imgui-rs` 0.19 (Dear ImGui 1.92.9b docking branch, builds fine with rustc 1.99) + `dear-imgui-glow` 0.19 (glow 0.18, the
same glow as the renderer). imgui-rs 0.12 was not used: it has no safe docking/DockBuilder and an old ImGui. The safe API of
`dear-imgui-rs` is strict (it panics on API misuse, e.g. table phases, dockspace ordering), which the headless test below exercises.

## Layout
* `crates/ghostty-inspector` (`unsafe_code = "deny"`)
  * `inspector.rs`: `Inspector` (`mouse`, `gui`), `setup(ctx, scale)`, `Shared` (= `Mutex<Inspector>` newtype implementing
    `ghostty_renderer::state::InspectorHook`).
  * `widgets/*.rs`: 1:1 with the Zig widget files (`surface.rs` has the dockspace + Surface info + `SurfaceInfo` input struct).
  * `keys.rs`: `tag_name` (Zig `@tagName` from `Debug`), `imgui_key` (Zig `Key.imguiKey`).
  * `dock.rs`: the ONLY `unsafe` module (`#![allow(unsafe_code)]`, all SAFETY-commented): `DockBuilder` (node create/split/dock),
    `SetNextWindowSize`, `SetNextItemAllowOverlap`, and a raw `Begin`/`End` scope (`begin_window`) so that widgets still run when
    `Begin` returned false, like Zig's `Begin` + `defer End`.
* `ghostty-renderer::state`: `State.overlay_features` replaced by `State.inspector: Option<Arc<dyn InspectorHook>>` (Zig
  `inspector: ?*Inspector`); `generic.rs` reads `overlay_features()` from it each frame. The trait breaks the crate cycle.
* `ghostty-termio`: `Output::process_output` goes into Zig's "slow mode" while an inspector is set (`record_pty_read` per byte, then
  `process_byte`).
* `ghostty-core` (`surface/inspector.rs`): `activate_inspector` / `deactivate_inspector` (render-state pointer + renderer and IO
  `Inspector(bool)` messages), `render_inspector(ui)` (locks terminal then inspector, fills `SurfaceInfo`, wakes the renderer),
  key event recording in `keyboard.rs` (event created after key remapping, `binding` set in the consumed branch, `pty` copied in
  `encode_key`, recorded + `queue_render` when done, only if the inspector is still active), mouse recording in
  `mouse.rs` (cursor pos, `queue_render` on buttons). The `inspector` binding action already forwarded `RtAction::Inspector`.
* `ghostty-apprt` `CoreSurface`: new `render_inspector(&Ui)` next to `activate/deactivate_inspector`.
* `ghostty-apprt-gtk`: `class/{imgui_widget,inspector_widget,inspector_window}.rs`, `resources/ui/1.5/{imgui-widget,inspector-widget,
  inspector-window}.blp` (verbatim from Zig), `Surface::control_inspector` (toggle/show/hide, weak ref to the window) and
  `redraw_inspector`, `Window::toggle_inspector` (`win.toggle-inspector`, ctrl+shift+i). Unsafe only for `glow::Context::from_loader_function`
  (epoxy loader) and the GL read-back of the debug screenshot, both `#[allow(unsafe_code)]` + SAFETY.

## GTK input/rendering (imgui_widget)
GLArea + `IMMulticontext` as in Zig: focus/key/click/motion/scroll/IM-commit controllers feed `Io` (modifier keys as LeftShift/Ctrl/Alt/Super
events, keyval -> `imgui_key`), 30 FPS tick callback, two ImGui frames per GL render (first one only `end_frame`), then clear + draw.
Zig clears with `0x28/0xFF` which is integer 0, so the background is black; kept.

## Debug / verification
`GHOSTTY_DEBUG_INPUT_SCRIPT` got `inspector-screenshot <png>`, `inspector-click <x> <y>`, `inspector-scroll <x> <y> <dy>`
(`debug_input.rs`). Inspector frames are rendered synchronously for these steps because the compositor does not send frame
callbacks to an off-screen window (without this the screenshot lags one event behind). Run:
`GSETTINGS_BACKEND=memory GHOSTTY_DEBUG_INPUT_SCRIPT=script.txt timeout 25 ./target/debug/ghostty -e sh` with
`key ctrl+shift+i`, `wait 2500`, `inspector-click 126 11`, `inspector-screenshot /abs/x.png`, ...
Verified in the real app on Wayland (screenshots viewed): all tabs (Terminal with screens/Misc/Layout/Mouse/Color/Modes tables, Surface,
Keyboard event table with pty encoding, Terminal IO VT log, Renderer overlays, ImGui demo), screen pop-out window with Info/Cell/PageList
docking (cell picking resolves the cell at (0,0)), detach of a header into a docked window, toggle open/close/reopen, closing a surface
and a tab while its inspector is open (no warnings, core deactivates in the surface's `dispose`).

## Tests
* ghostty-inspector: 15 unit tests (Zig has none for this package): label/pty/utf8 formatting, ring bound, hsv/key colour, text filter
  (ImGuiTextFilter semantics), OSC/CSI/ESC/Execute encodings and event recording through a real `Stream`, features toggle, snake_case,
  imgui key map, mouse button labels, plus `draws_frames_headless`: draws 8 frames of the whole inspector headlessly (all windows, pop-out
  screen window, palette window, detached headers, selected VT event) to catch misuse of the strict imgui API.
* ghostty-core `tests/e2e_inspector.rs`: 4 tests (key events with pty data + binding, VT events from a real child, overlay features
  reach the render state, activate/deactivate semantics).
* apprt-gtk `debug_input` parse test extended.
Skipped: none (Zig package has no tests).

## Deviations
* Font size is `16 * scale_factor` (Zig hardcodes `16 * 2` with a TODO). The imgui style is scaled by the change of the factor
  (a `Style` cannot be re-created from Rust like Zig's `ImGuiStyle_ImGuiStyle`).
* `GhosttyImguiWidget` virtual methods (`setup`/`render`) are hooks installed with `ImguiWidget::set_hooks` (gtk-rs class-struct
  boilerplate avoided); the widget hierarchy `InspectorWidget -> ImguiWidget -> AdwBin` is real.
* The inspector widget keeps an `Rc<dyn CoreSurface>` and the GTK Surface destroys its inspector window in `dispose` (Zig used a
  GObject weak notify to call `deactivateInspector` while the core surface is alive).
* DockBuilder splits requested by the pop-out headers (`DetachableHeader`, `detachable_header`) are queued and applied after all windows
  of the frame ended (`dock::flush_splits`): doing the split while the parent window is being built re-parents its dock node and trips
  Dear ImGui's "Must call EndChild() and not End()" assertion. The popped-out window therefore docks one frame later.
* Popups: the VT filter popup uses a Rust port of `ImGuiTextFilter` (`TextFilter`, same Build/PassFilter semantics) because the safe wrapper's
  type holds a raw pointer (not `Send`) and the inspector is shared with the IO thread.
* VT events: `Parser.Action.format` for DCS/APC is approximated (`parser.Parser.Action{ .dcs_hook = ... }`); the OSC metadata for
  `color_operation.requests` / `kitty_color_protocol.list` print the Zig container type name; metadata keeps insertion order (Zig hash map order).
  `vt_raw` only sees parser-driven actions (CSI/ESC/OSC/DCS/APC), exactly like Zig: printable text and C0 controls in the ground state
  are dispatched straight to the handler, so they never appear in the log.
* The recorded cursor is a `CursorSnapshot` (displayed fields only) instead of a copy of the whole cursor struct.
* Added accessors in ghostty-terminal: `Page::string_used_bytes` / `string_capacity_bytes`, `PageList::viewport_pin_handle`.
* ImGui demo window is shown when `debug_assertions` (Zig: `builtin.mode == .Debug`); the workspace release profile keeps debug assertions,
  so it is also shown there.

## Known gaps
* No unit tests can drive real GTK events; clicks/scroll are only covered by the debug replay.
* Fractional scale factors are rounded by GTK's integer `scale_factor`.