Core Engine & Terminal Probing

The `tuix.core.core` package manages process-level runtime lifecycle, execution loops, thread synchronization, and scene caching. The `tuix.core.tuix` package provides terminal probing, capability detection, Unicode grapheme cell measurement, and runtime terminal configuration.

Core Engine Lifecycle

Function	Description	Purpose & Return
core.tuix_core_init() -> int	Initializes the native engine, registry, and memory pools.	Must be called before creating scenes or builders. Returns TUIX_RC_OK (0).
core.tuix_core_shutdown() -> int	Shuts down the native engine and cleans up registry resources.	Call during application exit after stopping listeners.
core.tuix_core_loop_run() -> None	Executes one complete frame iteration: input routing, layout resolution, builder updates, compositing, and delta rendering.	Core execution step in synchronous application loops.
core.tuix_core_pipeline_tick(scene_name: bytes) -> int	Runs a single pipeline tick for a specific scene.	Allows custom orchestrators to tick individual scenes without running the full global loop.
core.tuix_core_lock() -> None	Acquires the global native engine mutex.	Guarantees thread safety when mutating scene trees or objects from background worker threads.
core.tuix_core_unlock() -> None	Releases the global native engine mutex.	Releases mutex after thread mutations.
core.tuix_cache_scenes() -> None	Snapshots active scenes to native cache.	Saves scene state before modal scene swaps.
core.tuix_restore_scenes() -> None	Restores scenes from native cache.	Restores previous scene hierarchy.
core.tuix_core_time_now_us() -> int	Returns high-resolution monotonic time in microseconds.	Used for precise frame timing, profiling, and animations.
core.tuix_core_loop_get_stats() -> dict	Returns a detailed dictionary of performance metrics from the last frame execution.	Includes frame_counter, batch_commit_ms, buffer_ms, composite_ms, total_ms, traversal_cache_hit, traversal_cache_miss, etc.
core.tuix_mouse_capture_start(uid: int) -> None	Starts exclusive mouse event capture for a specific widget UID.	Directs pointer events exclusively to the capturing widget during dragging.
core.tuix_mouse_capture_stop(uid: int) -> None	Ends exclusive mouse event capture for a specific widget UID.	Releases capture so normal hitmap routing resumes.
core.tuix_mouse_capture_get_uid() -> int	Returns UID of widget currently capturing mouse events, or 0.	Queries active capture state.

Terminal Probing & Configuration (tuix.core.tuix)

The `tuix.core.tuix` package interacts directly with the terminal emulator to probe supported features (wide character widths, emoji rendering, RGB truecolor, cursor position queries, and ASCII fallback policies).

Function	Description	Purpose
tuix.tuix_terminal_prepare() -> int	Prepares terminal for raw mode, enables alternate screen buffer, and disables echo.	Initializes terminal environment before starting UI loop.
tuix.tuix_terminal_probe() -> int	Sends probe escape sequences to detect terminal dimensions, cursor responsiveness, and Unicode capabilities.	Dynamically tunes rendering strategies to terminal capabilities.
tuix.tuix_terminal_select_policy() -> int	Selects rendering and symbol fallback policy based on probe results.	Ensures wide/emoji characters don't corrupt terminal layout.
tuix.tuix_terminal_get_info() -> dict	Returns dictionary with detected terminal emulator information, encoding, and probe flags.	Diagnostic querying for capabilities and environment.
tuix.tuix_terminal_config_set_probe_mode(mode: int)	Configures terminal probing mode (e.g. strict, fast, or disabled).	Controls probing overhead during startup.
tuix.tuix_terminal_config_set_ascii_fallback(enabled: bool)	Forces ASCII character fallback for box-drawing and borders if terminal lacks Unicode support.	Guarantees readable display on legacy terminals.
tuix.tuix_terminal_restore() -> None	Restores original terminal state, cursor visibility, and exits alternate screen buffer.	Must be executed on application exit.

Unicode & Codepoint Probing

Function	Description
tuix.tuix_codepoint_cell_width(cp: int) -> int	Returns the terminal cell column width (0, 1, or 2) for a given Unicode codepoint.
tuix.tuix_text_cell_count(s: bytes) -> int	Calculates total visible cell width of a UTF-8 encoded string.
tuix.tuix_codepoint_is_box(cp: int) -> int	Returns non-zero if codepoint is a box-drawing character.
tuix.tuix_codepoint_is_wide(cp: int) -> int	Returns non-zero if codepoint occupies 2 terminal cells (East Asian Wide / Fullwidth).
tuix.tuix_codepoint_is_emoji(cp: int) -> int	Returns non-zero if codepoint is an emoji glyph.
tuix.tuix_codepoint_is_combining(cp: int) -> int	Returns non-zero if codepoint is a zero-width combining mark or diacritic.

Standard Application Boot Sequence

from tuix.core import core, scene, content_builder, input, tuix

# 1. Prepare terminal & probe environment
tuix.tuix_terminal_prepare()
tuix.tuix_terminal_probe()

# 2. Initialize core engine & builders
core.tuix_core_init()
content_builder.tuix_builder_register_standard()

# 3. Setup scenes & input
scene.tuix_scene_init(b'Main')
scene.tuix_scene_select(b'Main')
input.tuix_input_start()

# 4. Main loop execution
while running:
    core.tuix_core_loop_run()

# 5. Clean teardown
input.tuix_input_stop()
core.tuix_core_shutdown()
tuix.tuix_terminal_restore()