# CUI > Experimental portable C11 UI: immediate frame composition, persistent application models, themed components and independent host/renderer adapters. All 78 comparison entries remain in scope; gallery presence is not complete component parity. Use catalog.json for feature status and limitations. Public headers define the API; examples must state their tested host. Source revision: `4752885b8a8f8eec40d1c91964f1f57e4d8d37e1`. Build profile: `web-default-icons-regex`. [Exact input hashes and build metadata](./build-info.json). ## Choose a task - [Build a native application](./tasks/native-app.md): A focused reading set for this task. - [Handle interaction and asynchronous work](./tasks/events.md): A focused reading set for this task. - [Understand and repair layouts](./tasks/layout.md): A focused reading set for this task. - [Diagnose errors and missing output](./tasks/debugging.md): A focused reading set for this task. ## Getting started - [CUI](./markdown/README.md): An experimental C11 native UI framework: Clay layout, unstyled interaction primitives, themed controls, and independent renderer adapters. Embed it in an existing host or run the SDL3 workbench. No browser engine, JavaSc - [Build CUI applications with an AI agent](./markdown/docs/AI_AGENTS.md): Give an agent your application requirements and the repository's current API and tests. CUI is a portable C11 library with optional host/renderer adapters. The live gallery covers 78 entries, while the feature manifest s - [Build your first native CUI app](./markdown/docs/NATIVE_APP_STARTER.md): Download the [versioned alpha.4 starter kit](https://github.com/mattmezza/cui/releases/download/v0.1.0-alpha.4/cui-0.1.0-alpha.4-native-starter.tar.gz) from GitHub Releases. It includes the source, bundled fonts and exam - [Resizable visible-divider regression](./markdown/docs/RESIZABLE_DRAG_AUDIT.md): The reported failure reproduced on the actual HTTPS gallery revision `44819c1` at a 1920 × 1080 viewport. Normal desktop mouse and actual Chromium CDP touch contacts began on the visible divider. Both pane bounds stayed - [Start building with CUI](./markdown/docs/START_HERE.md): CUI composes a user interface in portable C11. Your application supplies state and calls components during a frame; CUI produces a draw list and a semantic tree. A renderer paints the list, and a host supplies window eve ## Guides - [Alert completed-dismiss observations](./markdown/docs/ALERT_EVENTS.md): Include `cui/cui_alert_events.h` and call `cui_alert_events` to observe the built-in Dismiss action. This additive native C facade calls the existing `cui_alert` once. Its original options, Button style, content/action s - [API and ownership](./markdown/docs/API.md): Public headers live in `include/cui/`; generated embeddable headers in `dist/`. - [Practical application recipes](./markdown/docs/APP_RECIPES.md): The runnable [mail fixture](../examples/native_bundle/mail.c) uses the same host as the two-file starter. Build it from the extracted native bundle: - [Attachment action observers](./markdown/docs/ATTACHMENT_EVENTS.md): Include `cui/cui_media_events.h` and call `cui_attachment_events` with the same arguments as `cui_attachment`, plus a borrowed `cui_attachment_handler`. It returns `control` (the legacy `cui_attachment_result`) and actua - [Avatar activation observation](./markdown/docs/AVATAR_EVENTS.md): `cui_avatar_events.h` adds an opt-in direct C observer to `cui_avatar_ex` behavior. It does not change legacy Avatar options/layouts or the aggregate bool API. `interactive` still enables BUTTON semantics and routing: su - [Native callback runners in language bindings](./markdown/docs/BINDING_NATIVE_RUN.md): Python `App.run()`, Go `App.Run(dt)`, Rust `App::run()` / `run_with(...)` and Node/TypeScript `App.run()` delegate to `cui_bridge_run`. The SDL callback loop owns event pumping and frame scheduling so native modal resizi - [Controlled boolean Base requests](./markdown/docs/BOOLEAN_EVENTS.md): `cui_boolean_events.h` adds `cui_base_switch_events` and `cui_base_toggle_events`. These portable C11 Base reducers draw nothing; submit one inside its same-ID layout box. Switch retains `CUI_ROLE_SWITCH`; Toggle retains - [Bridge notification snapshots (V1)](./markdown/docs/BRIDGE_NOTIFICATIONS.md): The additive C API `cui_bridge_poll_notification_v1` returns a versioned typed view of the **existing** notification queue. It does not register callbacks, change timing, add input routing, or turn applied bridge mutatio - [Manual queued notifications in Go and Rust](./markdown/docs/BRIDGE_NOTIFICATIONS_GO_RUST.md): `App.PollNotificationV1()` in Go and `App::poll_notification_v1()` in Rust drain one notification from the same native FIFO used by legacy polling and dispatch. They invoke no handlers. `Step`/`step` already leave that q - [Bridge value notification views (V1)](./markdown/docs/BRIDGE_VALUE_NOTIFICATIONS.md): The C-only `cui_bridge_poll_value_notification_v1` opts into scalar, plain-text and selected-handle views on the **existing shared notification queue**. It preserves the shipped V1 layout, ABI version, size/version queri - [Go owning value notifications](./markdown/docs/BRIDGE_VALUE_NOTIFICATIONS_GO.md): `(*App).PollValueNotificationV1() (ValueNotificationV1, bool, error)` is an additive, manual owning view over the existing FIFO. `PollNotificationV1`, its struct and enum, legacy `PollEvent`, `Dispatch`, `Step` and `Run` - [JavaScript and TypeScript owning value notifications](./markdown/docs/BRIDGE_VALUE_NOTIFICATIONS_JS.md): `App.poll_value_notification_v1(): ValueNotificationV1 | undefined` is an explicit, manual drain of the **same queue** used by `poll_notification_v1()`, legacy dispatch, `step()` and `run()`. It adds no listeners or sync - [Python owning bridge value notifications](./markdown/docs/BRIDGE_VALUE_NOTIFICATIONS_PYTHON.md): `App.poll_value_notifications_v1()` is an explicit manual drain of the [C value notification queue](BRIDGE_VALUE_NOTIFICATIONS.md). It yields frozen owning values without invoking callbacks. Existing `poll_notifications_ - [Rust owning value notifications](./markdown/docs/BRIDGE_VALUE_NOTIFICATIONS_RUST.md): `App::poll_value_notification_v1(&mut self) -> Result>` is a separate opt-in owning view over the existing queue. The original `NotificationV1` enum and `poll_notification_v1` method remain un - [Checkbox source contracts](./markdown/docs/CHECKBOX_BEHAVIOR.md): This audit uses GPUI Kit v0.7.1, commit `87d10ae5e1299d1be18670a37570c5402f952e34`, from the frozen checkout described in [upstream-baseline.md](upstream-baseline.md). It reads actual Base and Styled implementations and - [Combobox selection notifications](./markdown/docs/COMBOBOX_EVENTS.md): `cui_base_combobox_events` and `cui_combobox_events` add synchronous selection CHANGE observers to single-selection Combobox. Legacy APIs, query editing, Select, List/Menu and multi-selection retain their behavior. Share - [Command observers](./markdown/docs/COMMAND_EVENTS.md): Include `cui/cui_command_events.h`. The additive `cui_command_rebuild_events`, `cui_command_select_events`, `cui_command_move_events` and `cui_command_confirm_events` accept the existing arguments, an explicit nonzero me - [Shared component event metadata](./markdown/docs/COMPONENT_EVENTS.md): The additive `cui_component_events.h` utility supplies common metadata and a bounded text-copy helper. It does **not** change any existing component callback, result, state owner or dispatch timing. The [78-family covera - [ContextMenu command notifications](./markdown/docs/CONTEXT_MENU_EVENTS.md): `cui_base_context_menu_events` and `cui_context_menu_events` add synchronous per-command observation to the existing Base and Styled ContextMenu. They use the unchanged `cui_menu_command_handler`, payload and result from - [Button and Check event facades](./markdown/docs/CONTROL_EVENTS.md): `cui_control_events.h` and the Styled declarations in `cui_components.h` add typed synchronous event facades for Button and Checkbox/Check. Existing entry points keep their behavior. [Switch/Toggle facades](BOOLEAN_EVENT - [Core contract and limits](./markdown/docs/CORE.md): The core uses the pinned Clay implementation for sizing and draw generation. Public APIs contain C11 types only. Calls run on one UI thread; contexts may be interleaved, including open frames, because each layout operati - [Debug a native CUI app](./markdown/docs/DEBUGGING.md): Start with the smallest failing frame and check the installed revision's public headers. [Layout](LAYOUT_GUIDE.md) and [IDs/lifetimes](IDS_AND_LIFETIMES.md) explain the contracts most often involved. The feature manifest - [Disclosure applied transitions](./markdown/docs/DISCLOSURE_EVENTS.md): Include `cui/cui_disclosure_events.h`. `cui_base_collapsible_events` and `cui_collapsible_events` add a synchronous observer to the existing owned bool. They preserve the old return in `result.changed`; `change_count` co - [DropdownButton paired notifications](./markdown/docs/DROPDOWN_EVENTS.md): `cui_base_dropdown_button_events` and `cui_dropdown_button_events` add synchronous observers for the primary action and individual menu commands. They preserve the paired DropdownButton presentation and legacy aggregate - [Hover model-open observers](./markdown/docs/HOVER_EVENTS.md): Include `cui/cui_hover_events.h` for `cui_hover_update_events`. This additive pure Base adapter preserves `cui_hover_update` and all its parameters, state and timing. It observes actual model-open transitions for shared - [IDs and lifetimes](./markdown/docs/IDS_AND_LIFETIMES.md): The declarations and comments in `include/cui/cui.h` are authoritative. Layout, semantics and interaction share stable application identity across frames. Nonzero layout IDs must be unique within a frame; semantic IDs mu - [Frames, state and callbacks](./markdown/docs/IMMEDIATE_AND_STATE.md): CUI uses immediate frame composition with persistent application and context state. Call components inside `cui_begin_frame` / `cui_end_frame`; they submit this frame's layout, draw commands and semantics. Keep values an - [InputGroup addon and text observers](./markdown/docs/INPUT_GROUP_EVENTS.md): Include `cui/cui_form_events.h`. `cui_base_input_group_events` and `cui_input_group_events` mirror the legacy arguments plus a borrowed `cui_input_group_handler`, returning `cui_input_group_event_result`. `control` is th - [Frozen initial integration contract](./markdown/docs/INTERFACES.md): Core types in include/cui/cui.h; core implementation src/core/cui.c. Public C11, no Clay/platform types. All dimensions logical pixels. Width/height 0 fits contents, negative grows, positive fixed. Explicit begin/end ele - [Python, Go, Rust, Node JavaScript and TypeScript with CUI](./markdown/docs/LANGUAGE_BINDINGS.md): For installable local wheel, npm, Go module and Rust crate artifacts, see the [packaging guide](PACKAGING.md). Linux alpha packages are tested outside the checkout; registry publication and other platform packages remain - [Layout and custom content](./markdown/docs/LAYOUT_GUIDE.md): Use `include/cui/cui.h` as the exact field/signature authority. This guide is the canonical introduction; [Core](CORE.md) records advanced contracts. Dimensions are logical pixels. A box is a column unless `.row = true`. - [Letter spacing](./markdown/docs/LETTER_SPACING.md): Set `cui_text_style.letter_spacing` to a signed distance in logical pixels. A value of `2` adds two logical pixels between eligible visual shaping clusters; `-1` compresses them by one. Density scales the distance with t - [Linux live-resize evidence](./markdown/docs/LINUX_LIVE_RESIZE.md): The callback-driven SDL3 host is tested on Linux independently of macOS modal resize behavior. The automated test uses X11 on the private Xvfb display created by `scripts/test_local.py`. It does not connect to the mainta - [Typed List transitions](./markdown/docs/LIST_EVENTS.md): Include `cui/cui_list_events.h`. `cui_base_list_events` adds an explicit compound control ID to the old Base arguments; `cui_list_events` uses the Styled container ID. Both accept the existing `cui_selection_handler` and - [Native live resize and pointer motion](./markdown/docs/LIVE_RESIZE.md): Use `cui_sdl3_run(argc, argv, callbacks)` for native applications. Initialization creates the backend and Core context; the frame callback composes and presents one frame using freshly queried `cui_sdl3_size`; quit relea - [MenuTree command notifications](./markdown/docs/MENU_EVENTS.md): `cui_base_menu_tree_events` and `cui_menu_tree_events` add synchronous per-command ACTIVATE observers. They preserve Base/Styled MenuTree mutation, navigation and close behavior. Simple Menu, ContextMenu, Dropdown, Split - [MessageScroller exact offset and following-tail observers](./markdown/docs/MESSAGE_EVENTS.md): Include `cui/cui_message_events.h`. `cui_base_message_scroller_events` and `cui_message_scroller_events` append a borrowed `cui_message_scroller_handler` to the old arguments. Their result carries the exact old return in - [Multiline aggregate CHANGE observers](./markdown/docs/MULTILINE_EVENTS.md): Include `cui/cui_multiline_events.h` for `cui_base_textarea_events` and `cui_textarea_events`. Each mirrors its existing Textarea entrypoint, appends a `cui_component_text_handler`, and returns `cui_multiline_event_resul - [Aggregate NumberInput CHANGE observation](./markdown/docs/NUMBER_EVENTS.md): Include `cui/cui_number_events.h` and use `cui_base_number_input_events` or `cui_number_input_events` with the existing arguments plus a `cui_number_event_handler`. Both return the unchanged native `control` result and a - [Numeric selection CHANGE observers](./markdown/docs/NUMERIC_SELECTION_EVENTS.md): Include `cui/cui_numeric_selection_events.h`. Pagination's additive Base and Styled `_events` entrypoints accept `{change, user}` and return the original aggregate bool as `control`, plus actual synchronous `change_count - [OTP CHANGE observation](./markdown/docs/OTP_EVENTS.md): Include `cui/cui_otp_events.h`. `cui_base_otp_events` and `cui_otp_events` add a synchronous `{change, user}` observer to the existing Base/Styled signatures. Their result contains the unchanged legacy `control` plus act - [Install local alpha binding artifacts](./markdown/docs/PACKAGING.md): Current artifact examples use prepared alpha.2 versions (`0.1.0-alpha.3`, Python `0.1.0a3`). Metadata preparation is not publication or a final source freeze; see [RELEASING.md](RELEASING.md). Existing alpha.1 tags/asset - [Picker applied observers](./markdown/docs/PICKER_EVENTS.md): Include `cui/cui_picker_events.h` for additive applied date-selection observers: `cui_calendar_reduce_events`, `cui_base_calendar_events`, and `cui_calendar_events`. Each mirrors its legacy operation, appends `cui_date_s - [Platform evidence](./markdown/docs/PLATFORM_MATRIX.md): | Target | Status | Evidence and limits | |---|---|---| | Linux Xorg | tested partial | Native SDL_Renderer OpenGL, independent Sokol GLCORE and SDL_GPU Vulkan on Intel Graphics; actual frames/readbacks, pointer/key mode - [Responsive containers](./markdown/docs/RESPONSIVE_LAYOUT.md): Use `cui/cui_responsive.h` to make layout decisions from a container's current logical width. Named mobile-first breakpoints resemble familiar utility-class systems: BASE, SM (640), MD (768), LG (1024), XL (1280), and 2X - [Final-offset scroll observers](./markdown/docs/SCROLL_EVENTS.md): Include `cui/cui_scroll_events.h`. Drawing-free `cui_base_scrollable_events` / `cui_base_scrollable_finish_events` and Styled `cui_scrollable_begin_events` / `cui_scrollable_end_events` observe one final offset per pair. - [RadioGroup selection notifications](./markdown/docs/SELECTION_EVENTS.md): `cui_selection_events.h` and `cui_radio_group.h` add synchronous Base/Styled RadioGroup CHANGE observers. [Select observers](SELECT_EVENTS.md) have their own guide; [Combobox observers](COMBOBOX_EVENTS.md) preserve their - [Select selection notifications](./markdown/docs/SELECT_EVENTS.md): `cui_select_events` adds a synchronous post-mutation CHANGE observer to single-selection Styled Select. Existing `cui_select`, List, Menu, Combobox and multi-select APIs retain their behavior. Shared payloads come from [ - [Settings applied events](./markdown/docs/SETTINGS_EVENTS.md): Include `cui/cui_settings_events.h`. `cui_settings_events` preserves the existing Styled Settings operation and adds navigation and built-in value observers. `on_navigation` reports applied page/group selection, not an o - [Sidebar row activation events](./markdown/docs/SIDEBAR_EVENTS.md): This additive C slice provides Base and Styled **row activation notifications** and typed item expansion and collapse requests. Header/footer actions remain later slices. Legacy Sidebar callbacks, results, layouts and re - [Simple Menu command notifications](./markdown/docs/SIMPLE_MENU_EVENTS.md): `cui_menu_events` adds synchronous per-command notifications to Styled Simple Menu. It takes the same arguments as `cui_menu`, followed by a `cui_menu_command_handler`, and returns `cui_menu_command_result` from [MenuTre - [Controlled Slider events](./markdown/docs/SLIDER_EVENTS.md): Include `cui/cui_slider_events.h` for `cui_base_slider_events`. This additive, drawing-free facade uses the existing controlled double-precision Slider reducer. Submit it inside a box with the same ID. The legacy `cui_ba - [Spinner](./markdown/docs/SPINNER.md): Use `cui_spinner_ex` for the frozen source-style decorative loading icon. It paints the Loader SVG at 16 logical pixels in `theme.text` by default, rotating through one turn every 0.8 seconds with quadratic ease in/out. - [Styled double Slider](./markdown/docs/STYLED_SLIDER_EVENTS.md): Include `cui/cui_styled_slider_events.h` for `cui_slider_events`. This additive controlled Slider paints a horizontal bar and optional label, using the existing [Base double event reducer](SLIDER_EVENTS.md) exactly once. - [Retained completed-close observers](./markdown/docs/SURFACE_EVENTS.md): Include `cui/cui_surface_events.h` for additive Base and Styled surface facades. They observe completed closes; they do not control close acceptance or notify opening, destruction, dismissal attempts or vetoes. Existing - [DataTable transitions](./markdown/docs/TABLE_EVENTS.md): Include `cui/cui_table_events.h`. The additive `cui_table_reduce_events`, `cui_base_data_table_events` and `cui_data_table_events` take a `cui_table_event_handler` and return unchanged legacy `control`, validity/submissi - [Tabs aggregate selection observers](./markdown/docs/TABS_EVENTS.md): Include `cui/cui_tabs_events.h` for `cui_base_tabs_events` and `cui_tabs_events`. They add an optional applied selection CHANGE observer to existing Base/Styled Tabs, preserving the old APIs, options, bool results, input - [Gradient text](./markdown/docs/TEXT_GRADIENT.md): `cui_text_paragraph_painted` paints real glyph coverage with a continuous linear color field. One glyph can contain many colors. Wrapping, shaping, fallback, contextual line sources, alignment, carets and selection retai - [Base Input change and submit notifications](./markdown/docs/TEXT_INPUT_EVENTS.md): Include `cui/cui_text_input_events.h` for two additive Base-only APIs: `cui_base_input_events` submits the ordinary Input reducer and observes each event; `cui_base_input_reduce_event_events` observes one event for compo - [Styled Input observers](./markdown/docs/TEXT_INPUT_STYLED_EVENTS.md): `cui_input_events` accepts the same arguments as `cui_input_ex`, followed by a `cui_component_text_handler`, and returns `cui_input_event_result`. For example: - [Themes](./markdown/docs/THEME_GUIDE.md): A `cui_theme` C struct carries surface/background, text/muted, primary/on-primary, border/focus/destructive colors and typography/spacing/radius/control height. `cui_theme_light`, `dark`, `high_contrast`, and `terminal` - [TimeField applied change observers](./markdown/docs/TIME_FIELD_EVENTS.md): Include `cui/cui_picker_events.h`. Use `cui_base_time_field_events` for semantics without Styled paint, or `cui_time_field_events` for the complete Styled control. Both preserve the old operation and return `cui_picker_e - [Toolbar command activation](./markdown/docs/TOOLBAR_EVENTS.md): Include `cui/cui_toolbar_events.h` and call `cui_toolbar_command_events` in a custom Toolbar item renderer. Existing container and command entrypoints remain unchanged. For example, an application-owned adapter can hold - [Tree applied selection events](./markdown/docs/TREE_EVENTS.md): Include `cui/cui_tree_events.h`. `cui_tree_reduce_events`, `cui_base_tree_events` and `cui_tree_events` add synchronous selection observers to the corresponding legacy calls. They edit the same caller-owned selected key. - [Reusable typography tokens](./markdown/docs/TYPOGRAPHY_TOKENS.md): `cui_typography.h` is a header-only authoring convenience over existing Core text APIs. It gives applications three semantic roles without owning fonts, modifying the current theme or introducing new layout behavior. - [Decoded video frames and a portable timeline](./markdown/docs/VIDEO_GUIDE.md): `cui/cui_video.h` supplies a decoder-neutral timeline model and a real CPU RGBA8 surface using the existing bitmap draw path. There is **no built-in codec**, container reader, network transport, audio output, subtitle en - [Reusable VideoPlayer](./markdown/docs/VIDEO_PLAYER.md): Start with `cui_video_player_defaults()`: a 320×180 contained video surface, compact playback/skip/timeline controls, short `m:ss / m:ss` time and fullscreen. The seek row and icon buttons have 44-unit touch targets; art - [VirtualList final-offset observers](./markdown/docs/VIRTUAL_EVENTS.md): Include `cui/cui_virtual_events.h`. `cui_base_virtual_list_events` and `cui_virtual_list_draw_events` take the legacy arguments plus `cui_scroll_handler`. They execute the old operation exactly once and return its unchan - [Icon](./markdown/docs/ICON.md): Icon renders named, host-loaded or raw SVG as a monochrome antialiased mask through CUI's portable RGBA bitmap draw path. It is decorative by default: it contributes layout and paint without a focus stop or pointer targe - [CUI bridge v1: C ABI and Python builders](./markdown/bindings/bridge/docs/README.md): This slice exposes real CUI row, column, label, and Button components through a portable C11 shared-library ABI. Python retains a convenient widget tree; each `step()` submits that tree to Core and renders a frame. The b - [Native CUI for Node.js and TypeScript](./markdown/bindings/node/README.md): This binding creates a real CUI scene. The N-API addon calls the shared C bridge; CUI computes layout and queues input events. The SDL backend renders an actual native window. JavaScript owns callbacks and updates nodes ## API and status - [Complete documentation index](./docs-index.md): All guides, component references and historical reports. - [API symbol index](./api-index.json): Header-derived declarations and matching downloadable headers. - [Feature manifest](./catalog.json): All 78 entries and incomplete behavior. - [Full documentation bundle](./llms-full.txt): Current documentation and catalog data; historical reports are linked separately.