@lynx-js/lynx-library-headers 0.0.1-alpha.4

package/include/lynx/platform/embedder/public/capi/lynx_update_meta_capi.h

@@ -0,0 +1,33 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_UPDATE_META_CAPI_H_
+#define PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_UPDATE_META_CAPI_H_
+
+#include "lynx_export.h"
+#include "lynx_template_bundle_capi.h"
+#include "lynx_template_data_capi.h"
+
+LYNX_EXTERN_C_BEGIN
+
+// LynxUpdateMeta is the metadata structure used by LynxView to update template
+// data. It will serve as the input parameter for UpdateData. Users can specify
+// various parameters required for the update through LynxUpdateMeta, such as
+// template data and globalProps, among others.
+typedef struct lynx_update_meta_t lynx_update_meta_t;
+
+LYNX_CAPI_EXPORT lynx_update_meta_t* lynx_update_meta_create();
+// The content of the data to update the template.
+LYNX_CAPI_EXPORT void lynx_update_meta_set_update_data(
+    lynx_update_meta_t*, lynx_template_data_t* data);
+
+// The globalProps content for updating the template;
+LYNX_CAPI_EXPORT void lynx_update_meta_set_global_props(
+    lynx_update_meta_t*, lynx_template_data_t* data);
+
+// Release the update meta.
+LYNX_CAPI_EXPORT void lynx_update_meta_release(lynx_update_meta_t*);
+
+LYNX_EXTERN_C_END
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_UPDATE_META_CAPI_H_

package/include/lynx/platform/embedder/public/capi/lynx_view_builder_capi.h

@@ -0,0 +1,113 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VIEW_BUILDER_CAPI_H_
+#define PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VIEW_BUILDER_CAPI_H_
+
+#include "lynx_export.h"
+#include "lynx_extension_module_types_capi.h"
+#include "lynx_generic_resource_fetcher_capi.h"
+#include "lynx_group_capi.h"
+#include "lynx_native_module_capi.h"
+#include "lynx_native_view_capi.h"
+#include "lynx_windowless_renderer_capi.h"
+
+LYNX_EXTERN_C_BEGIN
+
+typedef void* NativeWindow;
+
+typedef struct lynx_view_builder_t lynx_view_builder_t;
+LYNX_CAPI_EXPORT lynx_view_builder_t* lynx_view_builder_create();
+
+// Sets the screen size and pixel ratio for the LynxView being built. This
+// function allows you to specify the screen size and pixel ratio of the device
+// for the LynxView that is being constructed using the provided builder. The
+// screen size affects the layout and rendering of the LynxView, and the pixel
+// ratio is used to adjust the rendering quality of high - DPI displays.
+LYNX_CAPI_EXPORT void lynx_view_builder_set_screen_size(
+    lynx_view_builder_t*, const float& width, const float& height,
+    const float& pixel_ratio);
+
+// Set the initial position and size of the LynxView. This function allows you
+// to specify the initial position and dimensions of the LynxView being built
+// using the provided builder. The position is defined by the `x` and `y`
+// coordinates, and the size is defined by the `width` and `height` parameters.
+LYNX_CAPI_EXPORT void lynx_view_builder_set_frame(lynx_view_builder_t*,
+                                                  const float& x,
+                                                  const float& y,
+                                                  const float& width,
+                                                  const float& height);
+
+// Sets the font scaling ratio for the LynxView being built. This function
+// allows you to specify a scaling factor for the font size within the LynxView.
+// The text size in the LynxView will be multiplied by this scaling ratio. For
+// example, a value of 1.5 will increase the text size by 50%, while 0.8 will
+// reduce it by 20%.
+LYNX_CAPI_EXPORT void lynx_view_builder_set_font_scale(lynx_view_builder_t*,
+                                                       const float& scale);
+
+// Sets the ICU data path for the LynxView being built. This function allows you
+// to specify the path to the ICU (International Components for Unicode) data
+// file that the LynxView will use for Unicode-related operations such as text
+// processing, collation, and formatting. The ICU data is essential for proper
+// handling of international text and multilingual support in the LynxView.
+LYNX_CAPI_EXPORT void lynx_view_builder_set_icu_data_path(
+    lynx_view_builder_t*, const char* icu_data_path);
+
+// Sets the fixed WebView2 runtime path for the LynxView being built. Windows
+// WebView native views first try the system WebView2 runtime, then retry with
+// this fixed runtime path if the system runtime is unavailable or fails.
+LYNX_CAPI_EXPORT void lynx_view_builder_set_webview2_fixed_runtime_path(
+    lynx_view_builder_t*, const char* webview2_fixed_runtime_path);
+
+// Associates a Lynx group with the LynxView being built. This function allows
+// you to assign a specific Lynx group to the LynxView that is currently under
+// construction using the provided builder. The Lynx group can contain shared
+// resources, configurations, or state that the LynxView may utilize. By
+// associating a Lynx group, the LynxView can inherit and interact with the
+// group's context, which can be useful for managing resources and coordinating
+// behavior across multiple views.
+LYNX_CAPI_EXPORT void lynx_view_builder_set_lynx_group(lynx_view_builder_t*,
+                                                       lynx_group_t* group);
+
+// Sets the parent window for the Lynx view being built. This function assigns a
+// parent native window to the Lynx view that is being constructed using the
+// provided builder. The parent window will contain the Lynx view, and the
+// view's position and behavior may be influenced by its parent.
+LYNX_CAPI_EXPORT void lynx_view_builder_set_parent(lynx_view_builder_t*,
+                                                   NativeWindow parent);
+
+// Sets the windowless renderer for the Lynx view being built. This function
+// assigns a windowless renderer to the Lynx view that is being constructed
+// using the provided builder. The windowless renderer is responsible for
+// rendering the Lynx view without a visible window, which can be useful for
+// offscreen rendering or headless scenarios.
+LYNX_CAPI_EXPORT void lynx_view_builder_set_windowless_renderer(
+    lynx_view_builder_t*, lynx_windowless_renderer_t*);
+
+// generic fetcher.
+LYNX_CAPI_EXPORT void lynx_view_builder_set_generic_resource_fetcher(
+    lynx_view_builder_t*, lynx_generic_resource_fetcher_t* fetcher);
+
+// Register instance-level native module, which have a higher priority than
+// global modules.
+LYNX_CAPI_EXPORT void lynx_view_builder_register_native_module(
+    lynx_view_builder_t* builder, const char* name, napi_module_creator creator,
+    void* opaque);
+
+// Register instance-level extension module, which have a higher priority than
+// global extension modules.
+LYNX_CAPI_EXPORT void lynx_view_builder_register_extension_module(
+    lynx_view_builder_t* builder, const char* name,
+    extension_module_creator creator, bool is_lazy_create, void* opaque);
+
+// Register instance-level view factory.
+LYNX_CAPI_EXPORT void lynx_view_builder_register_native_view(
+    lynx_view_builder_t* builder, const char* name,
+    lynx_native_view_creator creator, void* opaque);
+
+LYNX_CAPI_EXPORT void lynx_view_builder_release(lynx_view_builder_t* builder);
+
+LYNX_EXTERN_C_END
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VIEW_BUILDER_CAPI_H_

package/include/lynx/platform/embedder/public/capi/lynx_view_capi.h

@@ -0,0 +1,174 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VIEW_CAPI_H_
+#define PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VIEW_CAPI_H_
+
+#include "lynx_export.h"
+#include "lynx_load_meta_capi.h"
+#include "lynx_runtime_lifecycle_observer_capi.h"
+#include "lynx_update_meta_capi.h"
+#include "lynx_view_builder_capi.h"
+#include "lynx_view_client_capi.h"
+#include "lynx_vsync_monitor_capi.h"
+
+LYNX_EXTERN_C_BEGIN
+
+// LynxView is the main entry point for rendering and interacting with Lynx.
+// It provides methods for loading and rendering templates, updating data, and
+// sending events. Users should call lynx_view_release() to release the LynxView
+// when it is no longer needed.
+typedef struct lynx_view_t lynx_view_t;
+
+// Create lynx view with builder.
+LYNX_CAPI_EXPORT lynx_view_t* lynx_view_create(lynx_view_builder_t* builder,
+                                               void* user_data);
+LYNX_CAPI_EXPORT void* lynx_view_get_user_data(lynx_view_t*);
+
+// Get the fixed WebView2 runtime path configured by the builder. Returns an
+// empty string if no fixed runtime path was configured.
+LYNX_CAPI_EXPORT const char* lynx_view_get_webview2_fixed_runtime_path(
+    lynx_view_t*);
+
+// Register lifecycle event observer for LynxView. The client passed in is the
+// structure implemented by user and registered to the LynxView instance is used
+// to obtain the callbacks of each process in the LynxView lifecycle.
+LYNX_CAPI_EXPORT void lynx_view_add_client(lynx_view_t*,
+                                           lynx_view_client_t* client);
+LYNX_CAPI_EXPORT void lynx_view_remove_client(lynx_view_t*,
+                                              lynx_view_client_t* client);
+
+// Register a runtime lifecycle observer for the LynxView.
+// This function allows you to associate a runtime lifecycle observer with a
+// specific LynxView instance. The observer will be notified of various runtime
+// lifecycle events, such as runtime attachment, and detachment. This can be
+// useful for monitoring and responding to changes in the runtime state.
+LYNX_CAPI_EXPORT void lynx_view_register_runtime_lifecycle_observer(
+    lynx_view_t*, lynx_runtime_lifecycle_observer_t*);
+
+// Using LynxLoadMeta to render LynxView, it is the main entrance for the client
+// to load Lynx templates.
+LYNX_CAPI_EXPORT void lynx_view_load_template(lynx_view_t*,
+                                              lynx_load_meta_t* data);
+
+// Using LynxUpdateMeta to update LynxView, it is the main entrance for the
+// client to update template data.
+LYNX_CAPI_EXPORT void lynx_view_update_data(lynx_view_t*,
+                                            lynx_update_meta_t* data);
+
+// Reload the template of the LynxView with the given data. This function
+// reloads the template of the specified LynxView using the provided template
+// data and global properties. It can be used when you need to refresh the view
+// with updated data or different template configurations.
+LYNX_CAPI_EXPORT void lynx_view_reload_template(
+    lynx_view_t*, lynx_template_data_t* data,
+    lynx_template_data_t* global_props);
+
+// Send global events to the front end through the client, and the front end can
+// listen to the event through GlobalEventEmitter.
+LYNX_CAPI_EXPORT void lynx_view_send_global_event(lynx_view_t*,
+                                                  const char* name,
+                                                  const char* json);
+
+// Update the screen metrics of the LynxView. This function allows you to modify
+// the screen-related properties of an existing LynxView, including the screen
+// width, height, and pixel ratio.
+LYNX_CAPI_EXPORT void lynx_view_update_screen_metrics(lynx_view_t*,
+                                                      const float& width,
+                                                      const float& height,
+                                                      const float& pixel_ratio);
+
+// Updates the position and size of the LynxView. This function allows you to
+// change the position and dimensions of an existing LynxView. The position is
+// defined by the `x` and `y` coordinates of the top-left corner of the view,
+// and the size is defined by the `width` and `height` parameters.
+LYNX_CAPI_EXPORT void lynx_view_set_frame(lynx_view_t*, const float& x,
+                                          const float& y, const float& width,
+                                          const float& height);
+
+// Changing the font scaling ratio in client settings will automatically change
+// the text size.
+LYNX_CAPI_EXPORT void lynx_view_set_font_scale(lynx_view_t*,
+                                               const float& font_scale);
+
+// Set the parent window of the LynxView.
+LYNX_CAPI_EXPORT void lynx_view_set_parent(lynx_view_t*, NativeWindow parent);
+
+// Get the native window of the LynxView.
+LYNX_CAPI_EXPORT NativeWindow lynx_view_get_native_window(lynx_view_t*);
+
+// Get the generic resource fetcher of the LynxView. This function increases the
+// reference count of the returned fetcher. The caller assumes ownership and is
+// responsible for calling `lynx_generic_resource_fetcher_release` to release
+// it when no longer needed.
+LYNX_CAPI_EXPORT lynx_generic_resource_fetcher_t*
+lynx_view_get_generic_resource_fetcher(lynx_view_t*);
+
+// Instruct the LynxView to enter the foreground state. This function should be
+// called when the LynxView becomes visible or active again after being in the
+// background. It may trigger necessary operations such as resuming animations,
+// reloading resources, or updating the UI.
+LYNX_CAPI_EXPORT void lynx_view_enter_foreground(lynx_view_t*);
+
+// Instruct the LynxView to enter the background state. This function should be
+// called when the LynxView is about to become hidden or inactive, such as when
+// the app is sent to the background. It may trigger operations like pausing
+// animations, releasing resources, or saving the current state to ensure
+// efficient resource usage and a smooth transition when the view returns to the
+// foreground.
+LYNX_CAPI_EXPORT void lynx_view_enter_background(lynx_view_t*);
+
+// Send bubble event to lynx view. This function is only used by test bench to
+// replay the bubble event.
+LYNX_CAPI_EXPORT void lynx_view_inject_bubble_event(lynx_view_t*,
+                                                    const char* params);
+// Register instance-level view factory.
+LYNX_CAPI_EXPORT void lynx_view_register_native_view(
+    lynx_view_t*, const char* name, lynx_native_view_creator creator,
+    void* opaque);
+
+// Register Input Method Editor (IME) handler for the LynxView.
+// When registering IME (handler != NULL), the provided handler will be invoked
+// to handle keyboard events. When releasing IME (handler == NULL), the IME
+// will be hidden and no further keyboard events will be sent.
+LYNX_CAPI_EXPORT void lynx_view_register_ime_handler(lynx_view_t* view,
+                                                     void* handler,
+                                                     void* opaque);
+
+// Set a custom vsync monitor to request a synchronous vsync signal
+LYNX_CAPI_EXPORT void lynx_view_set_custom_vsync_monitor(
+    lynx_view_t*, lynx_vsync_monitor_t* monitor);
+
+// Users should call lynx_view_release() to release the LynxView when it is no
+// longer needed.
+LYNX_CAPI_EXPORT void lynx_view_release(lynx_view_t* view);
+
+// Callback type for event simulation (devtool).
+typedef void (*lynx_emulate_touch_fn)(void* context, const char* event_type,
+                                      int x, int y, const char* button,
+                                      float delta_x, float delta_y,
+                                      int modifiers, int click_count);
+
+// Set event simulation proxy for devtool. The callback will be invoked to
+// emulate touch/mouse events. Pass NULL callback to clear the proxy.
+LYNX_CAPI_EXPORT void lynx_view_set_event_simulation_proxy(
+    lynx_view_t* view, lynx_emulate_touch_fn callback, void* context);
+
+LYNX_CAPI_EXPORT void lynx_view_send_touch_event(lynx_view_t* view,
+                                                 const char* name, int32_t id,
+                                                 float x, float y,
+                                                 float client_x, float client_y,
+                                                 float page_x, float page_y);
+
+LYNX_CAPI_EXPORT int lynx_view_get_node_for_location(lynx_view_t* view, int x,
+                                                     int y);
+
+LYNX_CAPI_EXPORT void lynx_view_emulate_mouse_event(lynx_view_t* view,
+                                                    const char* event_name,
+                                                    float x, float y,
+                                                    float delta_x,
+                                                    float delta_y);
+
+LYNX_EXTERN_C_END
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VIEW_CAPI_H_

package/include/lynx/platform/embedder/public/capi/lynx_view_client_capi.h

@@ -0,0 +1,81 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VIEW_CLIENT_CAPI_H_
+#define PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VIEW_CLIENT_CAPI_H_
+
+#include <stdint.h>
+
+#include "lynx_export.h"
+
+LYNX_EXTERN_C_BEGIN
+
+// The LynxViewClient implemented by the client and registered to the LynxView
+// instance is used to obtain the callbacks of each process in the LynxView
+// lifecycle.
+typedef struct lynx_view_client_t lynx_view_client_t;
+
+// Callbacks of LynxViewClient
+// Page starts preparing to load.
+typedef void (*on_page_start)(lynx_view_client_t* client, const char* url);
+// Page loaded successfully.
+typedef void (*on_load_success)(lynx_view_client_t* client);
+// First screen layout completed.
+typedef void (*on_first_screen)(lynx_view_client_t* client);
+// Page update callback.
+typedef void (*on_page_updated)(lynx_view_client_t* client);
+// Data update callback.
+typedef void (*on_data_updated)(lynx_view_client_t* client);
+// Callback after the page is destroyed.
+typedef void (*on_destroy)(lynx_view_client_t* client);
+// JS environment preparation completed.
+// Note: The callback is in an asynchronous thread.
+typedef void (*on_runtime_ready)(lynx_view_client_t* client);
+// Error received.
+typedef void (*on_received_error)(lynx_view_client_t* client, int error_code,
+                                  const char* message);
+typedef void (*on_timing_setup)(lynx_view_client_t* client,
+                                const char* timing_info);
+typedef void (*on_timing_update)(lynx_view_client_t* client,
+                                 const char* timing_info,
+                                 const char* update_timing,
+                                 const char* update_flag);
+typedef void (*on_enter_foreground)(lynx_view_client_t* client);
+typedef void (*on_enter_background)(lynx_view_client_t* client);
+typedef void (*on_frame_timing)(lynx_view_client_t* client,
+                                int64_t frame_start_time_in_ns,
+                                int64_t frame_finish_time_in_ns);
+
+LYNX_CAPI_EXPORT lynx_view_client_t* lynx_view_client_create(void* user_data);
+LYNX_CAPI_EXPORT void* lynx_view_client_get_user_data(lynx_view_client_t*);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_page_start(lynx_view_client_t*,
+                                                          on_page_start f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_load_success(lynx_view_client_t*,
+                                                            on_load_success f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_first_screen(lynx_view_client_t*,
+                                                            on_first_screen f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_page_updated(lynx_view_client_t*,
+                                                            on_page_updated f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_data_updated(lynx_view_client_t*,
+                                                            on_data_updated f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_destroy(lynx_view_client_t*,
+                                                       on_destroy f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_runtime_ready(
+    lynx_view_client_t*, on_runtime_ready f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_received_error(
+    lynx_view_client_t*, on_received_error f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_timing_setup(lynx_view_client_t*,
+                                                            on_timing_setup f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_timing_update(
+    lynx_view_client_t*, on_timing_update f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_enter_foreground(
+    lynx_view_client_t*, on_enter_foreground f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_enter_background(
+    lynx_view_client_t*, on_enter_background f);
+LYNX_CAPI_EXPORT void lynx_view_client_bind_on_frame_timing(lynx_view_client_t*,
+                                                            on_frame_timing f);
+LYNX_CAPI_EXPORT void lynx_view_client_release(lynx_view_client_t*);
+
+LYNX_EXTERN_C_END
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VIEW_CLIENT_CAPI_H_

package/include/lynx/platform/embedder/public/capi/lynx_vsync_monitor_capi.h

@@ -0,0 +1,38 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+#ifndef PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VSYNC_MONITOR_CAPI_H_
+#define PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VSYNC_MONITOR_CAPI_H_
+
+#include <stdint.h>
+
+#include "lynx_export.h"
+
+LYNX_EXTERN_C_BEGIN
+
+typedef struct lynx_vsync_monitor_t lynx_vsync_monitor_t;
+
+typedef void (*lynx_vsync_monitor_on_vsync_callback)(void* user_data, int64_t,
+                                                     int64_t);
+typedef void (*lynx_vsync_monitor_request_vsync)(
+    lynx_vsync_monitor_t*, lynx_vsync_monitor_on_vsync_callback callback,
+    void* user_data);
+
+// Creates a lynx_vsync_monitor_t instance with a finalizer. It associates
+// the provided user data with the monitor, which can be retrieved later using
+// `lynx_vsync_monitor_get_user_data`. The finalizer function will be called
+// when the monitor is released.
+LYNX_CAPI_EXPORT lynx_vsync_monitor_t* lynx_vsync_monitor_create_with_finalizer(
+    void* user_data, void (*finalizer)(lynx_vsync_monitor_t*, void*));
+
+LYNX_CAPI_EXPORT void* lynx_vsync_monitor_get_user_data(lynx_vsync_monitor_t*);
+
+// Binds a request_vsync function to lynx_vsync_monitor_t. This function is used
+// to synchronize a Vsync signal.
+LYNX_CAPI_EXPORT void lynx_vsync_monitor_bind_request_vsync_func(
+    lynx_vsync_monitor_t*, lynx_vsync_monitor_request_vsync func);
+
+LYNX_EXTERN_C_END
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_VSYNC_MONITOR_CAPI_H_

package/include/lynx/platform/embedder/public/capi/lynx_windowless_renderer_capi.h

@@ -0,0 +1,213 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+#ifndef PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_WINDOWLESS_RENDERER_CAPI_H_
+#define PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_WINDOWLESS_RENDERER_CAPI_H_
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "lynx_export.h"
+#include "lynx_types.h"
+
+LYNX_EXTERN_C_BEGIN
+
+/* ----- Global UI Task Runner Configuration ----- */
+// These APIs provide a way to inject a host-provided task runner for Lynx's
+// global UI thread. This is useful when embedding Lynx in a windowless mode
+// where the host wants to control the UI thread execution.
+//
+// These functions are process-global and should be called only once, before
+// any windowless renderer is created. After the first windowless renderer is
+// initialized, subsequent calls will have no effect.
+
+// Callback function type for checking if the current thread is the UI thread.
+// Should return true if the calling thread is the UI thread where tasks should
+// be executed.
+typedef bool (*lynx_windowless_ui_task_runner_runs_on_current_thread_callback)(
+    void* user_data);
+
+// Callback function type for posting a task to the UI thread.
+// The target_time_nanos is the absolute time (in nanoseconds since epoch)
+// when the task should be executed.
+typedef void (*lynx_windowless_ui_task_runner_post_task_callback)(
+    lynx_task_t task, uint64_t target_time_nanos, void* user_data);
+
+// Configuration structure for the global UI task runner.
+// This structure must be zero-initialized before use.
+typedef struct lynx_windowless_ui_task_runner_config_t {
+  // The size of this struct. Must be set to
+  // sizeof(lynx_windowless_ui_task_runner_config_t).
+  size_t struct_size;
+  // User data pointer that will be passed to the callbacks.
+  void* user_data;
+  // Callback to check if current thread is UI thread.
+  lynx_windowless_ui_task_runner_runs_on_current_thread_callback
+      runs_on_current_thread_callback;
+  // Callback to post a task to the UI thread.
+  lynx_windowless_ui_task_runner_post_task_callback post_task_callback;
+} lynx_windowless_ui_task_runner_config_t;
+
+// Configures the global UI task runner for windowless mode.
+// This function must be called before creating any windowless renderer.
+// Returns true if the configuration was successfully set, false if it was
+// already set or UIThread has already been initialized.
+LYNX_CAPI_EXPORT bool lynx_windowless_set_global_ui_task_runner(
+    const lynx_windowless_ui_task_runner_config_t* config);
+
+// Runs a UI task that was posted via the global UI task runner.
+// This function should be called by the host on the UI thread.
+// Returns true if the task was found and executed successfully.
+LYNX_CAPI_EXPORT bool lynx_windowless_run_ui_task(lynx_task_t task);
+
+/* ----- End of Global UI Task Runner Configuration ----- */
+
+// The type of the windowless renderer.
+typedef enum lynx_windowless_renderer_type_e {
+  // The software renderer type that renders content on CPU.
+  kRendererTypeSoftware = 0,
+  // The GL renderer type that renders content with host OpenGL context.
+  // Unlike kRendererTypeGLDirect, this renderer type will be running as a
+  // bitmap uploader, underneath will render view using a SharedImageSink and
+  // readback GPU memory to a CPU bitmap. It may be SLOW for large views, but
+  // all components will work well.
+  kRendererTypeGL,
+  // The GL renderer type that renders content with host OpenGL context.
+  // This renderer type will be running directly on the host OpenGL context, it
+  // can speed normal UI rendering, but components using external textures like
+  // video or canvas maybe NOT work.
+  kRendererTypeGLDirect,
+  // The accelerated renderer type that uses shared texture.
+  kRendererTypeAccelerated,
+} lynx_windowless_renderer_type_e;
+
+// Forward declaration of the windowless renderer structure.
+// This is an opaque type that represents the internal implementation
+// of the windowless renderer. Users should not directly access its
+// fields but instead use the provided API functions to interact with it.
+typedef struct lynx_windowless_renderer_t lynx_windowless_renderer_t;
+
+// Creates a new windowless handler instance.
+// This function is the entry point for initializing a windowless handler
+// with the specified type and optional user data. The finalizer function
+// will be called when the renderer is released.
+LYNX_CAPI_EXPORT lynx_windowless_renderer_t*
+lynx_windowless_renderer_create_with_finalizer(
+    lynx_windowless_renderer_type_e type, void* user_data,
+    void (*finalizer)(lynx_windowless_renderer_t*, void*));
+
+LYNX_CAPI_EXPORT void* lynx_windowless_renderer_get_user_data(
+    lynx_windowless_renderer_t*);
+
+/* ----- Callbacks for GL renderer type ----- */
+// The callback function type for making the current context. Returns true if
+// the context is made successfully.
+typedef bool (*on_gl_make_current)(lynx_windowless_renderer_t*);
+// The callback function type for clearing the current context. Returns true if
+// the context is cleared successfully.
+typedef bool (*on_gl_clear_current)(lynx_windowless_renderer_t*);
+// The callback function type for presenting the rendered content. The return
+// value indicates success of the present call.
+typedef bool (*on_gl_present)(lynx_windowless_renderer_t*);
+// The callback function type for creating a framebuffer object. Returns the
+// framebuffer object if the creation is successful.
+typedef uint32_t (*on_gl_create_fbo)(lynx_windowless_renderer_t*, int w, int h);
+// The callback function type for resolving the GL procedure. Returns the
+// procedure address if the resolution is successful.
+typedef void* (*on_gl_proc_resolver)(lynx_windowless_renderer_t*, const char*);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_on_gl_make_current(
+    lynx_windowless_renderer_t*, on_gl_make_current);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_on_gl_clear_current(
+    lynx_windowless_renderer_t*, on_gl_clear_current);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_on_gl_present(
+    lynx_windowless_renderer_t*, on_gl_present);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_on_gl_create_fbo(
+    lynx_windowless_renderer_t*, on_gl_create_fbo);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_on_gl_proc_resolver(
+    lynx_windowless_renderer_t*, on_gl_proc_resolver);
+/* ----- Callbacks for GL renderer type ----- */
+
+/* ----- Callbacks for Software renderer type ----- */
+// The callback function type for presenting the rendered content when the
+// renderer is in software mode. The return value indicates success of the
+// present call.
+typedef bool (*on_software_present)(lynx_windowless_renderer_t*,
+                                    const void* allocation, size_t row_bytes,
+                                    size_t height);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_on_software_present(
+    lynx_windowless_renderer_t*, on_software_present);
+/* ----- Callbacks for Software renderer type ----- */
+
+/* ----- Callbacks for accelerated renderer type ----- */
+typedef bool (*on_accelerated_present)(lynx_windowless_renderer_t*);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_on_accelerated_present(
+    lynx_windowless_renderer_t*, on_accelerated_present);
+
+// Gets the accelerated paint info of the windowless renderer. The accelerated
+// paint info used for presenting on screen is generally obtained by calling
+// from the host's render thread. Returns true if the call is successful, false
+// otherwise.
+LYNX_CAPI_EXPORT bool lynx_windowless_renderer_get_accelerated_paint_info(
+    lynx_windowless_renderer_t*, lynx_accelerated_paint_info_t* paint_info);
+/* ----- Callbacks for accelerated renderer type ----- */
+
+// The callback function type for posting a task to the main thread.
+// The task is a function pointer that will be executed on the main thread.
+// The interval_nanoseconds is the time interval in nanoseconds at which the
+// task should be executed.
+typedef void (*on_post_task)(lynx_windowless_renderer_t*, lynx_task_t task,
+                             uint64_t interval_nanoseconds);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_on_post_task(
+    lynx_windowless_renderer_t*, on_post_task);
+
+// Runs a task on the main thread.
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_run_task(
+    lynx_windowless_renderer_t*, lynx_task_t task);
+
+// Sends a pointer event to the windowless renderer.
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_send_pointer_event(
+    lynx_windowless_renderer_t*, lynx_pointer_event_t* event);
+// Sends a key event to the windowless renderer.
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_send_key_event(
+    lynx_windowless_renderer_t*, lynx_key_event_t* event);
+
+/* ----- Callbacks for platform function ----- */
+typedef const char* (*get_clipboard_data)(lynx_windowless_renderer_t*);
+typedef void (*set_clipboard_data)(lynx_windowless_renderer_t*,
+                                   const char* data);
+typedef void (*activate_system_cursor)(lynx_windowless_renderer_t*,
+                                       lynx_cursor_type_e type,
+                                       const char* path);
+typedef void (*show_text_input)(lynx_windowless_renderer_t*, bool show);
+typedef void (*update_caret_position)(lynx_windowless_renderer_t*, float x,
+                                      float y, float width, float height);
+typedef void (*set_cursor_position)(lynx_windowless_renderer_t*, int position);
+typedef void (*set_marked_text_rect)(lynx_windowless_renderer_t*, float x,
+                                     float y, float width, float height);
+typedef void (*set_editable_transform)(lynx_windowless_renderer_t*,
+                                       const float transform_matrix[16]);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_get_clipboard_data(
+    lynx_windowless_renderer_t*, get_clipboard_data);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_set_clipboard_data(
+    lynx_windowless_renderer_t*, set_clipboard_data);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_activate_system_cursor(
+    lynx_windowless_renderer_t*, activate_system_cursor);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_show_text_input(
+    lynx_windowless_renderer_t*, show_text_input);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_update_caret_position(
+    lynx_windowless_renderer_t*, update_caret_position);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_set_cursor_position(
+    lynx_windowless_renderer_t*, set_cursor_position);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_set_marked_text_rect(
+    lynx_windowless_renderer_t*, set_marked_text_rect);
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_bind_set_editable_transform(
+    lynx_windowless_renderer_t*, set_editable_transform);
+/* ----- Callbacks for platform function ----- */
+
+LYNX_CAPI_EXPORT void lynx_windowless_renderer_release(
+    lynx_windowless_renderer_t*);
+
+LYNX_EXTERN_C_END
+
+#endif  // PLATFORM_EMBEDDER_PUBLIC_CAPI_LYNX_WINDOWLESS_RENDERER_CAPI_H_