GUI

GUI
Source snapshot: 9b4f8a3 (2026-09-23); retained QMail clone, including M7.
Working = implemented in this snapshot, not a new runtime/test certification.
Partial = an identified implementation/exposure gap; obsolete = retained compatibility only.
Entry points and static functions are selected navigation anchors; full lexical index: function-index.txt.
Used by / Tests list selected source references (including callback registration), not a proven dynamic call graph.
Tests were inspected, not executed; use tools/test.ps1 with isolated scratch data.
Old paths come from docs/path-map.txt; absent mappings denote additions after the move.

Application startup

Purpose: Parse desktop launch arguments and initialize the SDL/in-process application.
Files: src/app/main.c src/app/startup.c
Old paths: vendor/gui-3/src/app/main.c -> src/app/main.c src/host/startup.c -> src/app/startup.c
Public header: include/qmail/startup.h
Entry points: src/app/main.c:254 :: main() src/app/startup.c:42 :: qmail_startup_file_exists()
Important static functions: src/app/main.c:38 :: inproc_live_new_mail() src/app/main.c:47 :: print_version() src/app/startup.c:23 :: join_path() src/app/startup.c:37 :: ensure_directory()
Owns: Desktop process entry and startup policy.
Used by: src/app/desktop_api.c
Side effects: Updates UI state, allocates/renders resources and delegates user operations to desktop services; host calls can use OS/filesystem/process APIs.
Tests: tests/unit/desktop_api_test.c tests/unit/migration_test.c tests/unit/startup_test.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: working; Old Win32 chrome fallback was left in the archive, not a retained component.

Desktop API, service and SDK

Purpose: Provide typed desktop operations over the retained service/SDK layer and declare feature readiness.
Files: src/app/desktop_api.c src/app/desktop_api_more.c src/app/feature_catalog.c src/mail/service/qmail_service.c src/mail/sdk/qmail_sdk.c src/mail/sdk/qmail_sdk_transport.c
Old paths: src/desktop_api/desktop_api.c -> src/app/desktop_api.c src/desktop_api/desktop_api_more.c -> src/app/desktop_api_more.c src/desktop_api/feature_catalog.c -> src/app/feature_catalog.c vendor/core/src/qmail_service/qmail_service.c -> src/mail/service/qmail_service.c vendor/core/src/qmail_sdk/qmail_sdk.c -> src/mail/sdk/qmail_sdk.c vendor/core/src/qmail_sdk/qmail_sdk_transport.c -> src/mail/sdk/qmail_sdk_transport.c
Public header: include/qmail/desktop_api.h include/qmail/feature_catalog.h include/qmail_sdk/qmail_sdk.h include/qmail_service/qmail_service.h
Entry points: src/app/desktop_api.c:1737 :: qmail_desktop_api_send_email() src/mail/service/qmail_service.c:2544 :: qmail_svc_send_email() src/mail/sdk/qmail_sdk.c:2910 :: qmail_sdk_create() src/app/feature_catalog.c:9 :: qmail_desktop_feature_catalog() src/app/desktop_api.c:282 :: qmail_desktop_api_identity_lock() src/app/desktop_api_more.c:104 :: qmail_desktop_api_search_messages() src/mail/service/qmail_service.c:272 :: qmail_svc_messages_list() src/mail/sdk/qmail_sdk.c:2905 :: qmail_sdk_abi_version()
Important static functions: src/app/desktop_api.c:335 :: change_pw_file_read() src/app/desktop_api.c:358 :: change_pw_file_write() src/mail/service/qmail_service.c:255 :: qmail_svc_parse_email_id() src/mail/service/qmail_service.c:395 :: qmail_svc_parse_email_id_for_delete() src/mail/sdk/qmail_sdk.c:539 :: parse_envelope() src/mail/sdk/qmail_sdk.c:579 :: parse_params() src/app/desktop_api_more.c:37 :: clear_error() src/app/desktop_api_more.c:45 :: fail()
Owns: Desktop operation contract and feature readiness; domain rules remain in their groups.
Used by: src/app/client.c src/app/client_inproc.c src/app/main.c
Side effects: Updates UI state, allocates/renders resources and delegates user operations to desktop services; host calls can use OS/filesystem/process APIs.
Tests: tests/live/attachment_download_probe.c tests/live/contacts_probe.c tests/live/draft_probe.c tests/live/drd_profile_probe.c tests/live/get_message_probe.c tests/live/large_send_live_probe.c tests/live/mail_action_probe.c tests/live/object_transfer_probe.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: working

Client binding and JSON boundary

Purpose: Bind GUI client operations to desktop APIs, decode results and provide fake data for tests.
Files: src/app/client_inproc.c src/app/client.c src/gui/client/client.c src/gui/client/ops.c src/gui/client/ops_table.inc src/gui/client/load.c src/gui/client/servers.c src/gui/client/decode.c src/gui/client/decode_contacts.c src/gui/client/decode_drd.c src/gui/client/decode_setup.c src/gui/client/decode_transfer.c src/gui/client/decode_wallet.c src/gui/client/fake.c
Old paths: src/gui/client_inproc.c -> src/app/client_inproc.c src/gui/client.c -> src/app/client.c vendor/gui-3/src/client/client.c -> src/gui/client/client.c vendor/gui-3/src/client/ops.c -> src/gui/client/ops.c vendor/gui-3/src/client/ops_table.inc -> src/gui/client/ops_table.inc vendor/gui-3/src/client/load.c -> src/gui/client/load.c vendor/gui-3/src/client/servers.c -> src/gui/client/servers.c vendor/gui-3/src/client/decode.c -> src/gui/client/decode.c vendor/gui-3/src/client/decode_contacts.c -> src/gui/client/decode_contacts.c vendor/gui-3/src/client/decode_drd.c -> src/gui/client/decode_drd.c vendor/gui-3/src/client/decode_setup.c -> src/gui/client/decode_setup.c vendor/gui-3/src/client/decode_transfer.c -> src/gui/client/decode_transfer.c vendor/gui-3/src/client/decode_wallet.c -> src/gui/client/decode_wallet.c vendor/gui-3/src/client/fake.c -> src/gui/client/fake.c
Public header: include/qgui/client.h include/qmail/gui_client.h include/qmail/gui_inproc.h
Entry points: src/app/client_inproc.c:1822 :: qgui_client_inproc_init() src/gui/client/load.c:1042 :: qgui_client_load() src/app/client_inproc.c:1811 :: qgui_client_inproc_set_setup_progress() src/app/client.c:16 :: qmail_gui_client_attach() src/gui/client/client.c:73 :: qgui_client_stub_init() src/gui/client/ops.c:13 :: qgui_op_count() src/gui/client/load.c:112 :: qgui_client_send_with_progress() src/gui/client/servers.c:4 :: qgui_client_server_request() src/gui/client/decode.c:122 :: qgui_decode_time_label() src/gui/client/decode_contacts.c:47 :: qgui_client_decode_contacts() src/gui/client/decode_drd.c:54 :: qgui_client_base64url_encode() src/gui/client/decode_setup.c:48 :: qgui_client_decode_disclaimer()
Important static functions: src/app/client_inproc.c:659 :: inproc_download_attachment() src/app/client_inproc.c:781 :: inproc_save_draft() src/app/client.c:6 :: invalid() src/gui/client/load.c:22 :: load_rows_query() src/gui/client/load.c:54 :: load_rows() src/gui/client/fake.c:560 :: fake_task_status() src/gui/client/fake.c:574 :: fake_save_draft() src/gui/client/client.c:3 :: stub_health()
Owns: GUI operation table and in-process mapping.
Used by: src/app/main.c src/gui/server_adapter.c src/gui/client/client_rest.c src/gui/client/rest.c src/gui/host/jobs.c src/gui/logic/fake_state.c src/gui/logic/reduce.c
Side effects: Updates UI state, allocates/renders resources and delegates user operations to desktop services; host calls can use OS/filesystem/process APIs.
Tests: tests/gui/avatar_render_test.cpp tests/gui/server_gui_test.c tests/gui/test_headers.c tests/legacy/test_rest_live.c tests/unit/gui_client_test.c tests/unit/send_progress_test.c tests/unit/server_adapter_test.c tests/gui/client/test_decode.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: working

Reducer and view model

Purpose: Reduce events into application state and derive visible rows, menus and filters.
Files: src/gui/logic/address.c src/gui/logic/fake_state.c src/gui/logic/load.c src/gui/logic/menus.c src/gui/logic/query_defs.c src/gui/logic/reduce.c src/gui/logic/servers.c src/gui/logic/sounds.c src/gui/logic/state.c src/gui/logic/text_field.c src/gui/logic/viewmodel.c
Old paths: vendor/gui-3/src/logic/address.c -> src/gui/logic/address.c vendor/gui-3/src/logic/fake_state.c -> src/gui/logic/fake_state.c vendor/gui-3/src/logic/load.c -> src/gui/logic/load.c vendor/gui-3/src/logic/menus.c -> src/gui/logic/menus.c vendor/gui-3/src/logic/query_defs.c -> src/gui/logic/query_defs.c vendor/gui-3/src/logic/reduce.c -> src/gui/logic/reduce.c vendor/gui-3/src/logic/servers.c -> src/gui/logic/servers.c vendor/gui-3/src/logic/sounds.c -> src/gui/logic/sounds.c vendor/gui-3/src/logic/state.c -> src/gui/logic/state.c vendor/gui-3/src/logic/text_field.c -> src/gui/logic/text_field.c vendor/gui-3/src/logic/viewmodel.c -> src/gui/logic/viewmodel.c
Public header: include/qgui/client.h include/qgui/servers.h include/qgui/state.h include/qgui/types.h include/qgui/viewmodel.h
Entry points: src/gui/logic/reduce.c:4789 :: qgui_reduce() src/gui/logic/viewmodel.c:130 :: qgui_viewmodel_build() src/gui/logic/address.c:69 :: qgui_parse_address() src/gui/logic/fake_state.c:6 :: qgui_state_seed_from_client() src/gui/logic/load.c:81 :: qgui_state_apply_load() src/gui/logic/menus.c:101 :: qgui_menu_count() src/gui/logic/query_defs.c:42 :: qgui_chip_count() src/gui/logic/reduce.c:1783 :: qgui_row_picked() src/gui/logic/servers.c:6 :: qgui_servers_parse_uint() src/gui/logic/sounds.c:21 :: qgui_sound_count() src/gui/logic/state.c:6 :: qgui_mailbox_init() src/gui/logic/text_field.c:40 :: qgui_text_field_init()
Important static functions: src/gui/logic/address.c:46 :: parse_groups() src/gui/logic/reduce.c:567 :: selected_message() src/gui/logic/reduce.c:579 :: begin_pending_attachment_download() src/gui/logic/servers.c:59 :: capture_saved() src/gui/logic/address.c:19 :: word_to_code() src/gui/logic/load.c:11 :: apply_health() src/gui/logic/load.c:48 :: apply_rows() src/gui/logic/servers.c:19 :: field_set()
Owns: AppState transitions, query definitions and view model.
Used by: src/app/main.c src/gui/client/decode_contacts.c src/gui/client/decode_drd.c src/gui/client/fake.c src/gui/client/load.c src/gui/host/jobs.c src/gui/host/loop.c src/gui/host/titlebar.c
Side effects: Mutates application state and derives view data; host/client operations remain behind callbacks.
Tests: tests/gui/avatar_render_test.cpp tests/gui/server_gui_test.c tests/gui/test_headers.c tests/gui/theme_switch_test.c tests/unit/server_adapter_test.c tests/update/update_ux_test.c tests/gui/layout/test_columns.c tests/gui/layout/test_editor.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: working

Clay layout and vector icons

Purpose: Build screen structure, edit text and map hit targets; render UI icons from vector paths.
Files: src/gui/layout/layout.c src/gui/layout/widgets.c src/gui/layout/panes.c src/gui/layout/setup.c src/gui/layout/editor.c src/gui/layout/server_panes.c src/gui/layout/hits.c src/gui/layout/strings.c src/gui/layout/icons.h src/gui/render/icon_paths.h
Old paths: vendor/gui-3/src/layout/layout.c -> src/gui/layout/layout.c vendor/gui-3/src/layout/widgets.c -> src/gui/layout/widgets.c vendor/gui-3/src/layout/panes.c -> src/gui/layout/panes.c vendor/gui-3/src/layout/setup.c -> src/gui/layout/setup.c vendor/gui-3/src/layout/editor.c -> src/gui/layout/editor.c vendor/gui-3/src/layout/server_panes.c -> src/gui/layout/server_panes.c vendor/gui-3/src/layout/hits.c -> src/gui/layout/hits.c vendor/gui-3/src/layout/strings.c -> src/gui/layout/strings.c vendor/gui-3/src/layout/icons.h -> src/gui/layout/icons.h
Public header: include/qgui/layout.h
Entry points: src/gui/layout/layout.c:125 :: qgui_layout_create() src/gui/layout/widgets.c:226 :: qgui_layout_scrollbar_bounds() src/gui/layout/hits.c:365 :: qgui_layout_set_pointer()
Important static functions: src/gui/layout/widgets.c:366 :: status_label_c() src/gui/layout/widgets.c:402 :: status_label() src/gui/layout/server_panes.c:68 :: status_dot() src/gui/layout/server_panes.c:121 :: status_label() src/gui/layout/layout.c:14 :: qgui_clay_trace() src/gui/layout/layout.c:39 :: qgui_clay_error() src/gui/layout/panes.c:30 :: pane_header_begin() src/gui/layout/panes.c:35 :: small_button()
Owns: Screen layout, hit regions and icon geometry.
Used by: src/gui/host/loop.c
Side effects: Allocates layout state, emits draw/hit commands and updates editor state.
Tests: tests/gui/avatar_render_test.cpp tests/gui/server_gui_test.c tests/gui/layout/test_columns.c tests/gui/layout/test_editor.c tests/gui/layout/test_hits.c tests/gui/logic/test_virtual_list.c tests/gui/render/test_cbdf_pane.c tests/gui/render/test_frame_nonblank.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: working

SDL renderer

Purpose: Render Clay commands, text, avatars and theme textures through SDL.
Files: src/gui/render/render.cpp
Old paths: vendor/gui-3/src/render/render.cpp -> src/gui/render/render.cpp
Public header: include/qgui/host.h include/qgui/render.h
Entry points: src/gui/render/render.cpp:741 :: qgui_renderer_create() src/gui/render/render.cpp:897 :: qgui_renderer_destroy() src/gui/render/render.cpp:118 :: qgui_embedded_asset_bytes()
Important static functions: src/gui/render/render.cpp:126 :: resolve_family() src/gui/render/render.cpp:136 :: resolve_family_face()
Owns: GUI drawing backend and asset lookup; font locator owns font choice.
Used by: src/gui/host/host_ops.c src/gui/host/loop.c src/gui/host/titlebar.c src/gui/layout/layout.c src/gui/layout/widgets.c
Side effects: Allocates GPU/SDL/text resources, loads assets and emits drawing commands.
Tests: tests/gui/avatar_render_test.cpp tests/gui/server_gui_test.c tests/gui/layout/test_columns.c tests/gui/layout/test_editor.c tests/gui/layout/test_hits.c tests/gui/render/test_cbdf_pane.c tests/gui/render/test_font_fallback.c tests/gui/render/test_frame_nonblank.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: working

Desktop host

Purpose: Run event/work queues, settings, dialogs, clipboard, sound, logging and window chrome.
Files: src/gui/host/loop.c src/gui/host/host_ops.c src/gui/host/jobs.c src/gui/host/audio.c src/gui/host/log.c src/gui/host/titlebar.c
Old paths: vendor/gui-3/src/host/desktop/loop.c -> src/gui/host/loop.c vendor/gui-3/src/host/desktop/host_ops.c -> src/gui/host/host_ops.c vendor/gui-3/src/host/desktop/jobs.c -> src/gui/host/jobs.c vendor/gui-3/src/host/desktop/audio.c -> src/gui/host/audio.c vendor/gui-3/src/host/desktop/log.c -> src/gui/host/log.c vendor/gui-3/src/host/desktop/titlebar.c -> src/gui/host/titlebar.c
Public header: include/qgui/desktop.h include/qgui/host.h include/qmail/update_progress.h
Entry points: src/gui/host/loop.c:146 :: qgui_host_poll() src/gui/host/host_ops.c:87 :: qgui_host_stub_ops() src/gui/host/jobs.c:17 :: qgui_jobs_set_update_monitor() src/gui/host/audio.c:91 :: qgui_audio_probe() src/gui/host/log.c:27 :: qgui_log_open() src/gui/host/titlebar.c:30 :: qgui_titlebar_colorref()
Important static functions: src/gui/host/host_ops.c:199 :: desktop_downloads_dir() src/gui/host/loop.c:20 :: files_picked_cb() src/gui/host/loop.c:53 :: console_ctrl() src/gui/host/host_ops.c:14 :: stub_clipboard_set() src/gui/host/jobs.c:64 :: worker() src/gui/host/jobs.c:72 :: worker_body() src/gui/host/audio.c:44 :: embedded_sound_id() src/gui/host/audio.c:55 :: embedded_sound_open()
Owns: Desktop OS integration and settings key/value persistence.
Used by: src/app/main.c src/gui/host/core_proc.c src/gui/host/upgrade.c
Side effects: Updates UI state, allocates/renders resources and delegates user operations to desktop services; host calls can use OS/filesystem/process APIs.
Tests: tests/gui/avatar_render_test.cpp tests/gui/server_gui_test.c tests/gui/test_headers.c tests/gui/window_zoom_test.c tests/unit/embedded_sound_test.c tests/gui/host/test_p11_host.c tests/gui/host/test_p12_host.c tests/gui/layout/test_columns.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: working

Server discovery adapter

Purpose: Map DRD server discovery into the GUI server settings view.
Files: src/gui/server_adapter.c
Old paths: No changed-path mapping for these files.
Public header: include/qmail/gui_server_adapter.h
Entry points: src/gui/server_adapter.c:244 :: qmail_gui_server_request()
Important static functions: src/gui/server_adapter.c:19 :: parse_id() src/gui/server_adapter.c:13 :: failure()
Owns: GUI discovery result adaptation.
Used by: src/app/client_inproc.c
Side effects: Updates UI state, allocates/renders resources and delegates user operations to desktop services; host calls can use OS/filesystem/process APIs.
Tests: tests/unit/server_adapter_test.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: working

Common utilities

Purpose: Provide GUI strings, arena allocation and time helpers.
Files: src/gui/common/arena.c src/gui/common/str.c src/gui/common/time.c
Old paths: vendor/gui-3/src/common/arena.c -> src/gui/common/arena.c vendor/gui-3/src/common/str.c -> src/gui/common/str.c vendor/gui-3/src/common/time.c -> src/gui/common/time.c
Public header: include/qgui/types.h
Entry points: src/gui/common/arena.c:11 :: qgui_arena_create() src/gui/common/str.c:5 :: qgui_str_set() src/gui/common/time.c:11 :: qgui_sleep_ms()
Important static functions: None identified by lexical inspection; C++ methods and script helpers are outside the C static index.
Owns: GUI common utility implementations.
Used by: src/app/client_inproc.c src/app/main.c src/gui/server_adapter.c src/gui/client/client_rest.c src/gui/client/decode.c src/gui/client/decode_contacts.c src/gui/client/decode_drd.c src/gui/client/decode_setup.c
Side effects: Allocates arenas, writes string buffers and can sleep the calling thread.
Tests: tests/gui/server_gui_test.c tests/legacy/test_rest_live.c tests/gui/client/test_decode.c tests/gui/client/test_download.c tests/gui/host/test_p12_host.c tests/gui/layout/test_columns.c tests/gui/layout/test_editor.c tests/gui/logic/test_load.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: working

Legacy REST adapters

Purpose: Retain compatibility transport/process adapters for the frozen REST surface.
Files: src/gui/client/rest.c src/gui/client/client_rest.c src/gui/host/core_proc.c src/gui/host/sse.c
Old paths: vendor/gui-3/src/client/rest.c -> src/gui/client/rest.c vendor/gui-3/src/client/client_rest.c -> src/gui/client/client_rest.c vendor/gui-3/src/host/desktop/core_proc.c -> src/gui/host/core_proc.c vendor/gui-3/src/host/desktop/sse.c -> src/gui/host/sse.c
Public header: include/qgui/client.h include/qgui/desktop.h include/qgui/host.h
Entry points: src/gui/client/rest.c:613 :: qgui_transport_rest_last_status() src/gui/client/client_rest.c:1482 :: qgui_client_rest_last_error() src/gui/host/core_proc.c:53 :: qgui_core_read_port_file() src/gui/host/sse.c:248 :: qgui_sse_start()
Important static functions: src/gui/client/rest.c:392 :: rest_download_winhttp() src/gui/client/rest.c:551 :: rest_download() src/gui/client/client_rest.c:350 :: rest_save_draft_text() src/gui/client/client_rest.c:386 :: rest_update_status() src/gui/host/core_proc.c:28 :: read_port_file() src/gui/host/sse.c:200 :: sse_thread() src/gui/host/core_proc.c:61 :: make_token() src/gui/host/sse.c:59 :: post()
Owns: Legacy adapter implementation only.
Used by: src/app/main.c src/gui/client/load.c src/gui/host/loop.c src/gui/host/upgrade.c
Side effects: Updates UI state, allocates/renders resources and delegates user operations to desktop services; host calls can use OS/filesystem/process APIs.
Tests: tests/legacy/test_rest_live.c tests/gui/client/test_download.c tests/gui/client/test_ops.c tests/gui/host/test_p11_host.c
Platforms: Windows; POSIX branches/dependencies where present. Linux/macOS runtime unverified in M13.
Status: obsolete; Not the shipping in-process path; REST routes are frozen by M7.5. Presence in the source tree is not a supported core.exe deployment.