# terminal_probe

URL: /kida/api/utils/terminal_probe/
Section: utils
Description: Terminal character width probing for Kida template engine.

Probes the actual terminal to determine how wide ambiguous-width Unicode
characters render. This gives pixel-accurate width measurement for the
user's specific terminal + font combination.

The probe works by:
1. Saving cursor position
2. Writing a test character
3. Querying cursor position via ANSI DSR (Device Status Report)
4. Measuring how many columns the cursor advanced

Thread-Safety:
    Probe functions are not thread-safe (they manipulate terminal state).
    Call once during Environment init, then use the cached result.

---

> For a complete page index, fetch /kida/llms.txt.

Open LLM text
(/kida/api/utils/terminal_probe/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fterminal_probe%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fterminal_probe%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fterminal_probe%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Fterminal_probe%2Findex.txt)

Module

#
`utils.terminal_probe`

Terminal character width probing for Kida template engine.

Probes the actual terminal to determine how wide ambiguous-width Unicode
characters render. This gives pixel-accurate width measurement for the
user's specific terminal + font combination.

The probe works by:

- Saving cursor position

- Writing a test character

- Querying cursor position via ANSI DSR (Device Status Report)

- Measuring how many columns the cursor advanced

Thread-Safety:
Probe functions are not thread-safe (they manipulate terminal state).
Call once during Environment init, then use the cached result.

2Functions

## Functions

`probe_ambiguous_width`

1

`int | None`

▼

Probe the terminal to determine the rendered width of ambiguous characters.

Wr…

`def probe_ambiguous_width(timeout: float = 0.1) -> int | None`

Probe the terminal to determine the rendered width of ambiguous characters.

Writes a known ambiguous-width character and measures cursor movement
using ANSI escape codes. Returns 1 or 2 on success, or`None`if
probing is not possible (non-TTY, non-Unix, timeout, etc.).

##### Parameters

Name
Type
Description

`timeout`
`float`

Maximum seconds to wait for terminal response.

Default:`0.1`

##### Returns

`int | None`

`_probe_tty`

4

`int | None`

▼

TTY-dependent probe internals. Requires a real terminal to exercise.

`def _probe_tty(select, termios, tty, timeout: float) -> int | None`

##### Parameters

Name
Type
Description

`select`
`—`

`termios`
`—`

`tty`
`—`

`timeout`
`float`

##### Returns

`int | None`