[MrMage]

This is the first in a series of PRs improving terminal accessibility on macOS, effectively splitting #10992 over multiple, smaller PRs. See #9930 and #9932 for motivation.

It introduces an AccessibilityContext type on the Zig side and uses it to back the existing accessibility APIs in SurfaceView. That in itself is not valuable yet (and in fact, the AccessibilityContext generation via PinMap is arguably more complex than the previous approach), but it's a necessary foundation for future improvements (again, see #10992 for what's to come). Large portions of the Accessibility API (including accessibilityVisibleCharacterRange()) will require us to build the PinMap anyway, and with this approach we can at least centralize that logic and data in one place.

However, this PR also provides some immediate value: it provides a proper implementation of accessibilityVisibleCharacterRange() and fixes two UTF-16 vs. UTF-8 mismatch issues in accessibilityNumberOfCharacters() and accessibilityLine(for:). It also introduces the inverse of that method, accessibilityRange(forLine:).

Also see #10992 for a small helper tool that one can use to probe the accessibility APIs for verification.

Zig core: AccessibilityContext (Screen.zig, Surface.zig)

A new AccessibilityContext struct holds the full terminal text (scrollback + active area) along with the byte offsets delimiting the visible viewport. It is built from a PinMap — the same mechanism used by selectionString — to accurately determine where the viewport sits within the full text. The PinMap is necessary because accessibilityVisibleCharacterRange() needs to report the viewport as a character range within the full text; the previous implementation had no way to do this and simply returned the range of the entire text. Without the PinMap, the alternatives would be fragile — fetching the viewport text separately and searching for it within the full text could match the wrong occurrence, and making two separate Zig calls leaves no reliable way to correlate their offsets. The PinMap maps every byte in the output text back to its terminal Pin, so we can precisely identify where the viewport starts and ends. The context owns its data (no Pins or page pointers) so it can be used after releasing the terminal mutex.

Swift: unified cache and AX method fixes (SurfaceView_AppKit.swift)

The two separate CachedValue<String> properties (cachedScreenContents, cachedVisibleContents) are replaced by a single CachedValue<ScreenTextInfo>. The ScreenTextInfo struct holds the full text and the viewport range as a Range<String.Index>. accessibilityVisibleCharacterRange() converts this range to NSRange only when needed.

Known limitations

accessibilityLine(for:) and accessibilityRange(forLine:) count \n-delimited lines, not visual screen rows. Soft-wrapped lines are treated as a single line. Accurate visual-line support requires the grid mapping infrastructure planned for a follow-up PR.

Outlook

Subsequent PRs will build on AccessibilityContext to add:

• Grid mapping tables (viewport_cells, grid_to_offset) for accessibilityFrame(for:) and accessibilityRange(for:) (bounds/position queries).
• A content_changed notification pipeline so VoiceOver stays in sync with terminal output without polling — gated on whether an accessibility client is actually connected, to avoid unnecessary work.
• (Maybe) Cursor offset tracking for accessibilityInsertionPointLineNumber() -- Depends on whether this is actually valuable, and/or whether we would need to change the semantics of accessibilityLine(for:) and accessibilityRange(forLine:) to refer to newlines as rendered rather than as line break characters.

[jcollie]

Ping :-)

Do not ping maintainers hoping to expedite review. It won't happen any faster, and just serves to annoy people - more than you think since many people receive "full feeds" of the activity on the Ghostty repo.