@clarkarch/opentui-fork-linux-arm64 0.8.1-fork.2 → 0.8.4-fork.2

package/opentui.h

@@ -0,0 +1,3918 @@
+#ifndef OPENTUI_H
+#define OPENTUI_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Experimental context and session ABI, version 2. This header does not stabilize the
+ * library's legacy renderer, Yoga, or other FFI exports. Use matching headers
+ * and artifacts. The restricted scene surface supports roots, boxes, plain text,
+ * sliders, standard arrows, editor views, and images. */
+#define OT_CONTEXT_ABI_VERSION UINT32_C(2)
+
+typedef int32_t ot_status;
+#define OT_OK INT32_C(0)
+#define OT_INVALID_ARGUMENT (-INT32_C(1))
+#define OT_UNSUPPORTED_VERSION (-INT32_C(2))
+#define OT_OUT_OF_MEMORY (-INT32_C(3))
+#define OT_WRONG_THREAD (-INT32_C(4))
+#define OT_INTERNAL_ERROR (-INT32_C(5))
+#define OT_CONTEXT_BUSY (-INT32_C(6))
+#define OT_WRONG_CONTEXT (-INT32_C(7))
+#define OT_WRONG_KIND (-INT32_C(8))
+#define OT_STALE_HANDLE (-INT32_C(9))
+#define OT_WRONG_SESSION (-INT32_C(10))
+#define OT_OUTPUT_BACKPRESSURE (-INT32_C(11))
+#define OT_SESSION_CLOSED (-INT32_C(12))
+#define OT_OUTPUT_BUSY (-INT32_C(13))
+#define OT_STALE_OUTPUT (-INT32_C(14))
+#define OT_OUTPUT_FAILED (-INT32_C(15))
+#define OT_OBJECT_LIMIT (-INT32_C(16))
+#define OT_RENDERER_ATTACHED (-INT32_C(17))
+#define OT_RENDERER_NOT_ATTACHED (-INT32_C(18))
+#define OT_INVALID_PHASE (-INT32_C(19))
+#define OT_CONTROL_PACKET_LIMIT (-INT32_C(20))
+#define OT_LEASE_LIMIT (-INT32_C(21))
+#define OT_LEASE_BYTES_LIMIT (-INT32_C(22))
+#define OT_STALE_LEASE (-INT32_C(23))
+#define OT_UNSUPPORTED_RESOURCE (-INT32_C(24))
+#define OT_STALE_FRAME (-INT32_C(25))
+#define OT_LAYOUT_LIMIT (-INT32_C(26))
+#define OT_FRAME_BUSY (-INT32_C(27))
+#define OT_FRAME_REQUEST_LIMIT (-INT32_C(28))
+#define OT_IMAGE_UNSUPPORTED_FORMAT (-INT32_C(40))
+#define OT_IMAGE_UNSUPPORTED_COLOR_SPACE (-INT32_C(41))
+#define OT_IMAGE_MALFORMED_DATA (-INT32_C(42))
+#define OT_IMAGE_DIMENSION_LIMIT (-INT32_C(43))
+#define OT_IMAGE_MEMORY_LIMIT (-INT32_C(44))
+#define OT_IMAGE_OUTPUT_TOO_SMALL (-INT32_C(45))
+#define OT_IMAGE_UNSUPPORTED_FEATURE (-INT32_C(46))
+#define OT_IMAGE_BUSY (-INT32_C(47))
+#define OT_VIDEO_FAILED (-INT32_C(60))
+#define OT_AUDIO_DECODE_FAILED (-INT32_C(61))
+#define OT_AUDIO_DEVICE_FAILED (-INT32_C(62))
+
+/* A context owns its native resources and I/O storage. Only its creating OS
+ * thread may call its functions, including error queries and destruction.
+ * Separate contexts may run on separate threads. Do not race a call with
+ * destruction. A successful destroy invalidates every copy of the pointer;
+ * stale, forged, and already-destroyed pointers are caller errors.
+ * Callbacks run synchronously on the owner thread and must return normally.
+ * A C++ exception, longjmp, or thread exit through native frames skips native
+ * cleanup and is undefined behavior. */
+typedef struct ot_context ot_context;
+
+/* Context-qualified identity. A destroyed slot cannot identify its replacement.
+ * Numeric IDs belong to one native image and its load lifetime; independent
+ * images can issue equal IDs. Do not reuse handles or tickets across images
+ * or after unloading.
+ * Copying this value does not retain the object. An all-zero handle is invalid. */
+typedef struct ot_handle {
+    uint64_t context_id;
+    uint32_t slot;
+    uint32_t generation;
+} ot_handle;
+
+#define OT_SCENE_ROOT UINT32_C(0)
+#define OT_SCENE_BOX UINT32_C(1)
+#define OT_SCENE_TEXT UINT32_C(2)
+#define OT_SCENE_SLIDER UINT32_C(3)
+#define OT_SCENE_ARROW UINT32_C(4)
+#define OT_SCENE_EDITOR UINT32_C(5)
+#define OT_SCENE_CUSTOM UINT32_C(6)
+#define OT_SCENE_TEXT_VIEW UINT32_C(7)
+#define OT_SCENE_IMAGE UINT32_C(8)
+#define OT_SCENE_VIDEO UINT32_C(9)
+#define OT_SCENE_WRAP_NONE UINT32_C(0)
+#define OT_SCENE_WRAP_CHAR UINT32_C(1)
+#define OT_SCENE_WRAP_WORD UINT32_C(2)
+#define OT_SCENE_ALIGN_LEFT UINT32_C(0)
+#define OT_SCENE_ALIGN_CENTER UINT32_C(1)
+#define OT_SCENE_ALIGN_RIGHT UINT32_C(2)
+
+/* Layout property groups and kinds. ENUM/FLOAT require edge=OT_EDGE_NONE and
+ * unit=OT_UNIT_UNDEFINED. VALUE uses an edge for MARGIN/PADDING/POSITION and a
+ * gutter for GAP; other kinds ignore edge. DIMENSION requires OT_EDGE_NONE.
+ * BORDER is read-only, uses OT_STYLE_BORDER_WIDTH, and reads an OT_EDGE_* border width.
+ * Read dimensions through VALUE WIDTH/HEIGHT or DIMENSION WIDTH/HEIGHT.
+ * Numeric lengths use terminal display cells; percent uses 0..100 for 0..100%.
+ * UNDEFINED ignores value. AUTO ignores value and is supported only by width,
+ * height, flex basis, margin, and position. NaN clears a numeric value; infinity
+ * rejects. ENUM values must be nonnegative integers from the named family.
+ * Scene layout requires box geometry; Yoga's display:contents is unsupported. */
+#define OT_STYLE_ENUM UINT32_C(0)
+#define OT_STYLE_FLOAT UINT32_C(1)
+#define OT_STYLE_VALUE UINT32_C(2)
+#define OT_STYLE_BORDER UINT32_C(3)
+#define OT_STYLE_DIMENSION UINT32_C(4)
+#define OT_STYLE_BORDER_WIDTH UINT32_C(0)
+#define OT_STYLE_FLAGS_NONE UINT32_C(0)
+#define OT_STYLE_DISABLE_FLEX_SHRINK UINT32_C(1)
+#define OT_STYLE_CONTENT UINT32_C(2)
+#define OT_STYLE_ENUM_DIRECTION UINT32_C(0)
+#define OT_STYLE_ENUM_FLEX_DIRECTION UINT32_C(1)
+#define OT_STYLE_ENUM_JUSTIFY_CONTENT UINT32_C(2)
+#define OT_STYLE_ENUM_ALIGN_CONTENT UINT32_C(3)
+#define OT_STYLE_ENUM_ALIGN_ITEMS UINT32_C(4)
+#define OT_STYLE_ENUM_ALIGN_SELF UINT32_C(5)
+#define OT_STYLE_ENUM_POSITION_TYPE UINT32_C(6)
+#define OT_STYLE_ENUM_FLEX_WRAP UINT32_C(7)
+#define OT_STYLE_ENUM_OVERFLOW UINT32_C(8)
+#define OT_STYLE_ENUM_DISPLAY UINT32_C(9)
+#define OT_STYLE_ENUM_BOX_SIZING UINT32_C(10)
+/* Scene layout only: LIST stacks in-flow children top to bottom without flex. */
+#define OT_STYLE_ENUM_LAYOUT_MODE UINT32_C(11)
+#define OT_STYLE_FLOAT_FLEX UINT32_C(0)
+#define OT_STYLE_FLOAT_FLEX_GROW UINT32_C(1)
+#define OT_STYLE_FLOAT_FLEX_SHRINK UINT32_C(2)
+#define OT_STYLE_FLOAT_ASPECT_RATIO UINT32_C(3)
+#define OT_STYLE_VALUE_WIDTH UINT32_C(0)
+#define OT_STYLE_VALUE_HEIGHT UINT32_C(1)
+#define OT_STYLE_VALUE_MIN_WIDTH UINT32_C(2)
+#define OT_STYLE_VALUE_MIN_HEIGHT UINT32_C(3)
+#define OT_STYLE_VALUE_MAX_WIDTH UINT32_C(4)
+#define OT_STYLE_VALUE_MAX_HEIGHT UINT32_C(5)
+#define OT_STYLE_VALUE_FLEX_BASIS UINT32_C(6)
+#define OT_STYLE_VALUE_MARGIN UINT32_C(7)
+#define OT_STYLE_VALUE_PADDING UINT32_C(8)
+#define OT_STYLE_VALUE_POSITION UINT32_C(9)
+#define OT_STYLE_VALUE_GAP UINT32_C(10)
+#define OT_DIMENSION_WIDTH UINT32_C(0)
+#define OT_DIMENSION_HEIGHT UINT32_C(1)
+#define OT_UNIT_UNDEFINED UINT32_C(0)
+#define OT_UNIT_POINT UINT32_C(1)
+#define OT_UNIT_PERCENT UINT32_C(2)
+#define OT_UNIT_AUTO UINT32_C(3)
+#define OT_EDGE_NONE UINT32_C(0)
+#define OT_EDGE_LEFT UINT32_C(0)
+#define OT_EDGE_TOP UINT32_C(1)
+#define OT_EDGE_RIGHT UINT32_C(2)
+#define OT_EDGE_BOTTOM UINT32_C(3)
+#define OT_EDGE_START UINT32_C(4)
+#define OT_EDGE_END UINT32_C(5)
+#define OT_EDGE_HORIZONTAL UINT32_C(6)
+#define OT_EDGE_VERTICAL UINT32_C(7)
+#define OT_EDGE_ALL UINT32_C(8)
+#define OT_GUTTER_COLUMN UINT32_C(0)
+#define OT_GUTTER_ROW UINT32_C(1)
+#define OT_GUTTER_ALL UINT32_C(2)
+#define OT_DIRECTION_INHERIT UINT32_C(0)
+#define OT_DIRECTION_LTR UINT32_C(1)
+#define OT_DIRECTION_RTL UINT32_C(2)
+#define OT_FLEX_DIRECTION_COLUMN UINT32_C(0)
+#define OT_FLEX_DIRECTION_COLUMN_REVERSE UINT32_C(1)
+#define OT_FLEX_DIRECTION_ROW UINT32_C(2)
+#define OT_FLEX_DIRECTION_ROW_REVERSE UINT32_C(3)
+#define OT_JUSTIFY_FLEX_START UINT32_C(0)
+#define OT_JUSTIFY_CENTER UINT32_C(1)
+#define OT_JUSTIFY_FLEX_END UINT32_C(2)
+#define OT_JUSTIFY_SPACE_BETWEEN UINT32_C(3)
+#define OT_JUSTIFY_SPACE_AROUND UINT32_C(4)
+#define OT_JUSTIFY_SPACE_EVENLY UINT32_C(5)
+#define OT_ALIGN_AUTO UINT32_C(0)
+#define OT_ALIGN_FLEX_START UINT32_C(1)
+#define OT_ALIGN_CENTER UINT32_C(2)
+#define OT_ALIGN_FLEX_END UINT32_C(3)
+#define OT_ALIGN_STRETCH UINT32_C(4)
+#define OT_ALIGN_BASELINE UINT32_C(5)
+#define OT_ALIGN_SPACE_BETWEEN UINT32_C(6)
+#define OT_ALIGN_SPACE_AROUND UINT32_C(7)
+#define OT_ALIGN_SPACE_EVENLY UINT32_C(8)
+#define OT_POSITION_STATIC UINT32_C(0)
+#define OT_POSITION_RELATIVE UINT32_C(1)
+#define OT_POSITION_ABSOLUTE UINT32_C(2)
+#define OT_FLEX_WRAP_NONE UINT32_C(0)
+#define OT_FLEX_WRAP_WRAP UINT32_C(1)
+#define OT_FLEX_WRAP_REVERSE UINT32_C(2)
+#define OT_OVERFLOW_VISIBLE UINT32_C(0)
+#define OT_OVERFLOW_HIDDEN UINT32_C(1)
+#define OT_OVERFLOW_SCROLL UINT32_C(2)
+#define OT_DISPLAY_FLEX UINT32_C(0)
+#define OT_DISPLAY_NONE UINT32_C(1)
+#define OT_BOX_SIZING_BORDER_BOX UINT32_C(0)
+#define OT_BOX_SIZING_CONTENT_BOX UINT32_C(1)
+#define OT_LAYOUT_MODE_FLEX UINT32_C(0)
+#define OT_LAYOUT_MODE_LIST UINT32_C(1)
+/* Yoga values for the standalone Yoga bindings only; scene styles reject
+ * DISPLAY_CONTENTS (OT_STYLE_ENUM_DISPLAY_MAX). */
+#define OT_DISPLAY_CONTENTS UINT32_C(2)
+#define OT_YOGA_ERRATA_NONE UINT32_C(0)
+#define OT_YOGA_ERRATA_STRETCH_FLEX_BASIS UINT32_C(1)
+#define OT_YOGA_ERRATA_ABSOLUTE_POSITION_WITHOUT_INSETS_EXCLUDES_PADDING UINT32_C(2)
+#define OT_YOGA_ERRATA_ABSOLUTE_PERCENT_AGAINST_INNER_SIZE UINT32_C(4)
+#define OT_YOGA_ERRATA_ALL UINT32_C(2147483647)
+#define OT_YOGA_ERRATA_CLASSIC UINT32_C(2147483646)
+#define OT_YOGA_EXPERIMENTAL_FEATURE_WEB_FLEX_BASIS UINT32_C(0)
+#define OT_YOGA_LOG_LEVEL_ERROR UINT32_C(0)
+#define OT_YOGA_LOG_LEVEL_WARN UINT32_C(1)
+#define OT_YOGA_LOG_LEVEL_INFO UINT32_C(2)
+#define OT_YOGA_LOG_LEVEL_DEBUG UINT32_C(3)
+#define OT_YOGA_LOG_LEVEL_VERBOSE UINT32_C(4)
+#define OT_YOGA_LOG_LEVEL_FATAL UINT32_C(5)
+#define OT_YOGA_NODE_TYPE_DEFAULT UINT32_C(0)
+#define OT_YOGA_NODE_TYPE_TEXT UINT32_C(1)
+/* Inclusive enum limits also drive generated host validation. */
+#define OT_STYLE_ENUM_DIRECTION_MAX OT_DIRECTION_RTL
+#define OT_STYLE_ENUM_FLEX_DIRECTION_MAX OT_FLEX_DIRECTION_ROW_REVERSE
+#define OT_STYLE_ENUM_JUSTIFY_CONTENT_MAX OT_JUSTIFY_SPACE_EVENLY
+#define OT_STYLE_ENUM_ALIGN_CONTENT_MAX OT_ALIGN_SPACE_EVENLY
+#define OT_STYLE_ENUM_ALIGN_ITEMS_MAX OT_ALIGN_SPACE_EVENLY
+#define OT_STYLE_ENUM_ALIGN_SELF_MAX OT_ALIGN_SPACE_EVENLY
+#define OT_STYLE_ENUM_POSITION_TYPE_MAX OT_POSITION_ABSOLUTE
+#define OT_STYLE_ENUM_FLEX_WRAP_MAX OT_FLEX_WRAP_REVERSE
+#define OT_STYLE_ENUM_OVERFLOW_MAX OT_OVERFLOW_SCROLL
+#define OT_STYLE_ENUM_DISPLAY_MAX OT_DISPLAY_NONE
+#define OT_STYLE_ENUM_BOX_SIZING_MAX OT_BOX_SIZING_CONTENT_BOX
+#define OT_STYLE_ENUM_LAYOUT_MODE_MAX OT_LAYOUT_MODE_LIST
+#define OT_MEASURE_UNDEFINED UINT32_C(0)
+#define OT_MEASURE_EXACTLY UINT32_C(1)
+#define OT_MEASURE_AT_MOST UINT32_C(2)
+#define OT_LAYOUT_PUBLIC UINT32_C(0)
+#define OT_LAYOUT_YOGA UINT32_C(1)
+#define OT_LAYOUT_PAINT UINT32_C(2)
+#define OT_LAYOUT_CONTENT UINT32_C(3)
+
+/* Border masks are paint bits, not OT_EDGE_* layout selectors. */
+#define OT_BORDER_NONE UINT32_C(0)
+#define OT_BORDER_LEFT UINT32_C(1)
+#define OT_BORDER_BOTTOM UINT32_C(2)
+#define OT_BORDER_RIGHT UINT32_C(4)
+#define OT_BORDER_TOP UINT32_C(8)
+#define OT_BORDER_ALL UINT32_C(15)
+#define OT_BORDER_SINGLE UINT32_C(0)
+#define OT_BORDER_DOUBLE UINT32_C(1)
+#define OT_BORDER_ROUNDED UINT32_C(2)
+#define OT_BORDER_HEAVY UINT32_C(3)
+
+/* Color words store RGBA bytes in their low eight bits, not 16-bit channels.
+ * The high bytes store metadata: word[0] has the palette slot, word[1] has the
+ * intent, and word[2..3] have zero high bytes. RGB and DEFAULT require slot=0.
+ * INDEXED requires a slot in 0..255. RGB snapshots supply fallback/blending
+ * colors for INDEXED and DEFAULT. Alpha is 0..255 for every intent.
+ * For example, {255, 0, 0, 255} is opaque red; {255, 0, 0, 0} is transparent.
+ * Indexed red at slot 1: {255 | (1 << OT_COLOR_META_SHIFT),
+ * OT_COLOR_INDEXED << OT_COLOR_META_SHIFT, 0, 255}.
+ * Default white: {255, 255 | (OT_COLOR_DEFAULT << OT_COLOR_META_SHIFT), 255, 255}.
+ * Float color outputs such as cursor state instead use normalized 0..1 channels. */
+#define OT_COLOR_RGB UINT32_C(0)
+#define OT_COLOR_INDEXED UINT32_C(1)
+#define OT_COLOR_DEFAULT UINT32_C(2)
+#define OT_COLOR_CHANNEL_MASK UINT32_C(255)
+#define OT_COLOR_META_SHIFT UINT32_C(8)
+/* The RGB snapshot of each palette slot, as 0xRRGGBB: slots 0..15 are ANSI_n;
+ * slots 16..231 are a 6x6x6 cube whose channel level n is 0 for n=0 and
+ * CUBE_BASE + CUBE_STEP * n otherwise; slots 232..255 are a gray ramp of
+ * GRAY_BASE + GRAY_STEP * (slot - 232). */
+#define OT_COLOR_ANSI_0 UINT32_C(0x000000)
+#define OT_COLOR_ANSI_1 UINT32_C(0x800000)
+#define OT_COLOR_ANSI_2 UINT32_C(0x008000)
+#define OT_COLOR_ANSI_3 UINT32_C(0x808000)
+#define OT_COLOR_ANSI_4 UINT32_C(0x000080)
+#define OT_COLOR_ANSI_5 UINT32_C(0x800080)
+#define OT_COLOR_ANSI_6 UINT32_C(0x008080)
+#define OT_COLOR_ANSI_7 UINT32_C(0xC0C0C0)
+#define OT_COLOR_ANSI_8 UINT32_C(0x808080)
+#define OT_COLOR_ANSI_9 UINT32_C(0xFF0000)
+#define OT_COLOR_ANSI_10 UINT32_C(0x00FF00)
+#define OT_COLOR_ANSI_11 UINT32_C(0xFFFF00)
+#define OT_COLOR_ANSI_12 UINT32_C(0x0000FF)
+#define OT_COLOR_ANSI_13 UINT32_C(0xFF00FF)
+#define OT_COLOR_ANSI_14 UINT32_C(0x00FFFF)
+#define OT_COLOR_ANSI_15 UINT32_C(0xFFFFFF)
+#define OT_COLOR_CUBE_BASE UINT32_C(55)
+#define OT_COLOR_CUBE_STEP UINT32_C(40)
+#define OT_COLOR_GRAY_BASE UINT32_C(8)
+#define OT_COLOR_GRAY_STEP UINT32_C(10)
+
+/* Text attribute words: bits 0..7 are the ATTR flags. Where a call or plane
+ * carries a link, bits 8..31 hold its link ID: (attributes >> LINK_SHIFT) & LINK_MASK. */
+#define OT_ATTR_BOLD UINT32_C(1)
+#define OT_ATTR_DIM UINT32_C(2)
+#define OT_ATTR_ITALIC UINT32_C(4)
+#define OT_ATTR_UNDERLINE UINT32_C(8)
+#define OT_ATTR_BLINK UINT32_C(16)
+#define OT_ATTR_INVERSE UINT32_C(32)
+#define OT_ATTR_HIDDEN UINT32_C(64)
+#define OT_ATTR_STRIKETHROUGH UINT32_C(128)
+#define OT_ATTR_BASE_MASK UINT32_C(255)
+#define OT_ATTR_LINK_SHIFT UINT32_C(8)
+#define OT_ATTR_LINK_MASK UINT32_C(0xFFFFFF)
+
+/* Complete slider options. orientation is horizontal=0 or vertical=1. Colors
+ * retain terminal color intent. All numbers and derived thumb arithmetic must be finite.
+ * Values are not clamped: zero and inverted ranges retain the legacy full thumb. A track
+ * longer than the i32 cell range uses that range.
+ * reserved must be zero. New sliders default to horizontal, min=0, max=100,
+ * value=0, viewport_size=10, foreground=#9a9ea3, background=#252527 (both opaque). */
+typedef struct ot_scene_slider_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t orientation;
+    uint32_t reserved;
+    double min;
+    double max;
+    double value;
+    double viewport_size;
+    uint16_t foreground[4];
+    uint16_t background[4];
+} ot_scene_slider_options;
+
+/* Copied virtual half-cell size and start, not terminal-cell coordinates. */
+typedef struct ot_scene_slider_thumb {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    double size;
+    double start;
+} ot_scene_slider_thumb;
+
+/* direction is up=0, down=1, left=2, right=3, using U+25B2/U+25BC/U+25C0/U+25B6.
+ * Only attributes bits 0..7 are accepted. Colors retain terminal color intent.
+ * New arrows default to up, white/transparent, and zero attributes. */
+typedef struct ot_scene_arrow_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t direction;
+    uint32_t attributes;
+    uint16_t foreground[4];
+    uint16_t background[4];
+} ot_scene_arrow_options;
+
+/* Complete text options, not a patch. Colors retain terminal color intent;
+ * attributes accepts only bits 0..7. truncate is 0 or 1. Offsets are display
+ * columns/virtual rows, at most INT32_MAX. Viewport size comes from native layout.
+ * New text nodes default to white/transparent, zero attributes/offsets, word wrap,
+ * left alignment, and no truncation. No custom providers or raw handles. */
+typedef struct ot_scene_text_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint16_t foreground[4];
+    uint16_t background[4];
+    uint32_t attributes;
+    uint32_t wrap_mode;
+    uint32_t truncate;
+    uint32_t first_line_offset;
+    /* Logical positions are retained; native view coordinates truncate to cells. */
+    double scroll_x;
+    double scroll_y;
+    uint32_t tab_indicator; /* Unicode scalar, or zero to hide the indicator. */
+    uint32_t tab_color_set; /* 0 or 1; absent tab color must be zero. */
+    uint16_t tab_color[4];
+    uint32_t text_align; /* OT_SCENE_ALIGN_*: left=0, center=1, right=2. */
+} ot_scene_text_options;
+
+#define OT_SCENE_TEXT_SELECTION_RESET UINT32_C(0)
+#define OT_SCENE_TEXT_SELECTION_SET UINT32_C(1)
+#define OT_SCENE_TEXT_SELECTION_UPDATE UINT32_C(2)
+#define OT_SCENE_TEXT_SELECTION_CELL UINT32_C(0)
+#define OT_SCENE_TEXT_SELECTION_WORD UINT32_C(1)
+#define OT_SCENE_TEXT_SELECTION_LINE UINT32_C(2)
+#define OT_SCENE_TEXT_SELECTION_BACKGROUND UINT32_C(1)
+#define OT_SCENE_TEXT_SELECTION_FOREGROUND UINT32_C(2)
+
+typedef struct ot_scene_text_selection_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t operation;
+    uint32_t behavior;
+    int32_t anchor_x;
+    int32_t anchor_y;
+    int32_t focus_x;
+    int32_t focus_y;
+    uint32_t flags;
+    uint32_t reserved;
+    uint16_t background[4];
+    uint16_t foreground[4];
+} ot_scene_text_selection_options;
+
+#define OT_SCENE_TEXT_FOREGROUND UINT32_C(1)
+#define OT_SCENE_TEXT_BACKGROUND UINT32_C(2)
+#define OT_SCENE_TEXT_LINK UINT32_C(4)
+
+typedef struct ot_styled_text_chunk {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t byte_count;
+    uint32_t flags;
+    uint16_t foreground[4];
+    uint16_t background[4];
+    uint32_t attributes;
+    uint32_t reserved;
+    uint32_t link_offset;
+    uint32_t link_byte_count;
+} ot_styled_text_chunk;
+
+/* Copied text metadata. text_length sums unwrapped line widths in display columns,
+ * with expanded tabs and no line separators. It is not a byte/code-point count
+ * or the final document selection offset: selection offsets count each line
+ * separator as one position. width_cols_max is the longest unwrapped line.
+ * reserved is zero. */
+typedef struct ot_scene_text_info {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t byte_count;
+    uint32_t text_length; /* Sum of unwrapped display-column widths, excluding line separators. */
+    uint32_t line_count;
+    uint32_t virtual_line_count;
+    uint32_t width_cols_max;
+    uint32_t reserved;
+} ot_scene_text_info;
+
+typedef struct ot_scene_text_line {
+    uint32_t start_cols;
+    uint32_t width_cols;
+    uint32_t source_line;
+    uint32_t wrap_index;
+} ot_scene_text_line;
+
+typedef struct ot_scene_paint_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    int32_t z_index;
+    float opacity;
+    double translate_x;
+    double translate_y;
+    uint32_t border_sides;
+    uint32_t should_fill;
+    uint16_t background[4];
+    uint16_t border_color[4];
+    uint32_t border_style;
+    uint32_t focusable;
+    uint16_t focused_border_color[4];
+    uint32_t reserved;
+} ot_scene_paint_options;
+
+#define OT_SCENE_MUTATIONS_MAX UINT32_C(4096)
+
+/* Complete Box details. Flags: 1 = title color, 2 = custom border characters.
+ * Titles are copied single-row UTF-8; each is bounded by OT_BUFFER_TEXT_BYTES_MAX.
+ * Alignments are left=0, center=1, right=2. Custom scalars occupy one display cell.
+ * Absent color/characters and reserved fields must be zero. */
+typedef struct ot_scene_box_details {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t title_alignment;
+    uint32_t bottom_title_alignment;
+    uint32_t flags;
+    uint32_t reserved;
+    uint16_t title_color[4];
+    uint32_t border_characters[11];
+} ot_scene_box_details;
+
+typedef struct ot_scene_style_value {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t unit;
+    float value;
+} ot_scene_style_value;
+
+typedef struct ot_scene_layout {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    float left;
+    float top;
+    float right;
+    float bottom;
+    float width;
+    float height;
+    double screen_x;
+    double screen_y;
+} ot_scene_layout;
+
+#define OT_SCENE_FULL_PATH_FORCED UINT32_C(1)
+#define OT_SCENE_FULL_PATH_SCREEN UINT32_C(2)
+#define OT_SCENE_FULL_PATH_IMAGES UINT32_C(4)
+#define OT_SCENE_FULL_PATH_TAINTED UINT32_C(8)
+#define OT_SCENE_FULL_PATH_UNRETAINED UINT32_C(16)
+#define OT_SCENE_FULL_PATH_OPTIONS UINT32_C(32)
+#define OT_SCENE_FULL_PATH_NON_LOCAL UINT32_C(64)
+
+/* Fields from work_frame_id on count the work of the last presented scene
+ * frame: preparation, paint, and encoding. They are deterministic work
+ * counts, not times, and their values may change between versions as the
+ * renderer does less work. The three hit_cells fields are zero: paint records
+ * one hit rectangle per member, and a hit test walks them. Cancelled, failed, and skipped frames,
+ * non-scene renders, and snapshot-only split renders leave them unchanged.
+ * work_frame_id is the frame_id of the counted frame, or zero before the first.
+ * full_path_reasons holds OT_SCENE_FULL_PATH_* bits: FORCED (debug flag),
+ * SCREEN (forced, invalidated, or palette-changed encode), IMAGES (image
+ * placements present), TAINTED (the next buffer was written outside scene
+ * paint), UNRETAINED (no presented scene frame to compare with: the first
+ * frame, a resize, or the frame after a failed, cancelled, or unpresented
+ * frame), OPTIONS (background, use_mouse, excluded_hit_num, or
+ * preserve_unwritten changed), NON_LOCAL (a recording clears or color-matrixes
+ * the frame). IMAGES also counts recorded image draws. Otherwise, without a
+ * reason, a frame repaints only when a painted member's inputs changed, its
+ * recording included: it clears and repaints only bands around the damage_rows
+ * rows they cover (runs one row apart merge, and a sixteenth band takes every
+ * later run, so a band can include undamaged rows), and the encoder diffs only
+ * the damage_rows rows; an unchanged frame has damage_rows 0 and paints nothing. After a current-buffer session lease the
+ * encoder diffs every row, without repainting. */
+typedef struct ot_scene_stats {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    double last_frame_time;
+    double average_frame_time;
+    double render_time;
+    double stdout_write_time;
+    uint64_t frame_count;
+    uint32_t cells_updated;
+    uint32_t average_cells_updated;
+    uint32_t render_time_valid;
+    uint32_t stdout_write_time_valid;
+    uint64_t work_frame_id;
+    uint64_t candidate_visits;
+    uint64_t paint_visits;
+    uint64_t view_preparations;
+    uint64_t geometry_reads;
+    uint64_t yoga_solves;
+    uint64_t feedback_operations;
+    uint64_t visibility_steps;
+    uint64_t viewport_child_refreshes;
+    uint64_t overlap_tests;
+    uint64_t members_painted;
+    uint64_t member_cells;
+    uint64_t cells_cleared;
+    uint64_t hit_cells_written;
+    uint64_t hit_cells_cleared;
+    uint64_t hit_cells_compared;
+    uint64_t rows_compared;
+    uint64_t rows_diffed;
+    uint32_t full_path_reasons;
+    uint32_t host_requests;
+    uint32_t layout_rounds;
+    uint32_t damage_rows;
+} ot_scene_stats;
+
+/* Cursor styles of the session cursor, the scene cursor state and editors. */
+#define OT_CURSOR_STYLE_BLOCK UINT32_C(0)
+#define OT_CURSOR_STYLE_LINE UINT32_C(1)
+#define OT_CURSOR_STYLE_UNDERLINE UINT32_C(2)
+#define OT_CURSOR_STYLE_DEFAULT UINT32_C(3)
+typedef struct ot_scene_cursor_state {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t x;
+    uint32_t y;
+    uint32_t visible;
+    uint32_t style;
+    uint32_t blinking;
+    uint32_t reserved;
+    float r;
+    float g;
+    float b;
+    float a;
+} ot_scene_cursor_state;
+
+#define OT_SCENE_HOOK_UPDATE UINT32_C(1)
+#define OT_SCENE_HOOK_RESIZE UINT32_C(2)
+#define OT_SCENE_HOOK_LAYOUT_CHANGED UINT32_C(4)
+#define OT_SCENE_HOOK_RENDER_BEFORE UINT32_C(8)
+#define OT_SCENE_HOOK_RENDER_AFTER UINT32_C(16)
+#define OT_SCENE_HOOK_RENDER_SELF UINT32_C(32)
+#define OT_SCENE_HOOK_IDLE_UPDATE UINT32_C(64)
+#define OT_SCENE_HOOK_SCROLL UINT32_C(128)
+#define OT_SCENE_FRAME_DONE UINT32_C(0)
+#define OT_SCENE_FRAME_UPDATE UINT32_C(1)
+#define OT_SCENE_FRAME_RESIZE UINT32_C(2)
+#define OT_SCENE_FRAME_LAYOUT_CHANGED UINT32_C(3)
+#define OT_SCENE_FRAME_RECORD UINT32_C(4)
+#define OT_SCENE_FRAME_SCROLL UINT32_C(5)
+
+typedef struct ot_scene_hooks {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t flags;
+    uint32_t reserved;
+    uint64_t generation;
+    double initial_width;
+    double initial_height;
+} ot_scene_hooks;
+
+typedef struct ot_scene_frame_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint16_t background[4];
+    uint32_t use_mouse;
+    uint32_t excluded_hit_num;
+    uint32_t max_layout_rounds;
+    uint32_t max_host_requests;
+    uint32_t preserve_unwritten; /* 0 clears to spaces; 1 clears untouched snapshot cells to codepoint zero. */
+} ot_scene_frame_options;
+
+typedef struct ot_scene_frame_request {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    ot_handle session;
+    ot_handle root;
+    ot_handle node;
+    uint64_t frame_id;
+    uint64_t request_id;
+    uint64_t layout_epoch;
+    uint64_t hook_generation;
+    uint32_t kind;
+    uint32_t num;
+    uint32_t width;
+    uint32_t height;
+    uint32_t reserved[2];
+} ot_scene_frame_request;
+
+#define OT_SCENE_GEOMETRY_PAINT UINT32_C(1)
+#define OT_SCENE_GEOMETRY_PUBLIC UINT32_C(2)
+typedef struct ot_scene_frame_geometry {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t flags;
+    uint32_t reserved;
+    ot_scene_layout paint;
+    ot_scene_layout public_layout;
+} ot_scene_frame_geometry;
+
+/* One node whose paint hooks a RECORD request asks the host to record, in paint
+ * order. hooks holds the RENDER_BEFORE, RENDER_SELF, and RENDER_AFTER bits to
+ * record. paint is the prepared geometry native code paints at, clamped like
+ * OT_LAYOUT_PAINT; clip and opacity
+ * are the inherited paint state. flags has OT_SCENE_GEOMETRY_PAINT and, when the
+ * public observation succeeded, OT_SCENE_GEOMETRY_PUBLIC. */
+typedef struct ot_scene_paint_slot {
+    ot_handle node;
+    uint64_t hook_generation;
+    uint32_t num;
+    uint32_t hooks;
+    int32_t clip_x;
+    int32_t clip_y;
+    uint32_t clip_width;
+    uint32_t clip_height;
+    float opacity;
+    uint32_t flags;
+    ot_scene_layout paint;
+    ot_scene_layout public_layout;
+} ot_scene_paint_slot;
+
+/* All phase records require exact size/version and zero reserved fields. Hook
+ * generations are nonzero and must increase on every change. Initial dimensions
+ * seed the resize baseline on the node's first publication. Later subscriptions use
+ * completed dimensions. Only the root accepts LAYOUT_CHANGED.
+ * IDLE_UPDATE uses up the node's update for a frame without a host request or callback.
+ * It does not count as a host hook and cannot be combined with UPDATE.
+ * Non-root nodes accept RENDER_BEFORE, RENDER_SELF, and RENDER_AFTER.
+ * Root paint flags are rejected.
+ * Rejected registrations leave hook flags, generation, and resize baselines unchanged.
+ * No custom measurement or native-to-host callbacks are installed. */
+ot_status ot_scene_set_hooks(ot_context *, const ot_handle *node, const ot_scene_hooks *);
+/* NULL previous starts an attempt. Otherwise acknowledge the exact returned
+ * request, including all identities and dimensions. Invalid replies consume
+ * nothing. One ordered request is outstanding; hooks run between native calls.
+ * Paint options are copied on each accepted step; max_layout_rounds and
+ * max_host_requests stay positive and fixed for the attempt. Yoga completes before host work. Filtered
+ * text viewports advance only when refreshed or painted, not during candidate layout.
+ * UPDATE runs at most once per node per attempt; getter refresh
+ * and resize ordering preserve the mounted and newly placed node contracts.
+ * LAYOUT_CHANGED follows an actual Yoga solve, before updates. Layout/preparation
+ * limits fail before paint. Failure cancels the attempt without presenting
+ * partial cells or rolling back mutations.
+ *
+ * When preparation finishes and a visible node has paint hooks, the step returns
+ * one RECORD request instead of painting. It names the root and counts as one host
+ * request. Read its slots with ot_scene_frame_get_paint_slots, run every slot's
+ * hooks in slot order, and acknowledge the RECORD ticket with the recording: one
+ * byte stream of ot_scene_record_* records (see ot_scene_record_header). Native
+ * code then paints the whole frame in one pass and returns DONE. At each slot,
+ * it plays RENDER_BEFORE, then RENDER_SELF in place of the node's native body,
+ * then native editor cursor maintenance, then RENDER_AFTER, before the node's
+ * children. A slot without a recorded phase draws nothing for that phase. An
+ * IMAGE or VIDEO node with a backing buffer from ot_scene_set_image or ot_scene_set_video plays its phases into
+ * that buffer, in buffer coordinates, after native code clears it and before
+ * composing it.
+ * recording must be NULL with zero length for every other acknowledgement.
+ *
+ * Hooks run before painting starts. Membership, geometry, clipping, and opacity
+ * stay as prepared for the RECORD request; later paint values stay live.
+ * Destroyed slot nodes and destroyed paint members are skipped with their
+ * recordings and hits. New nodes wait for the next frame. Layout mutations mark
+ * the next frame dirty. During RECORD, render, resize, setup, and suspend reject
+ * with OT_FRAME_BUSY, and the ticket grants no buffer access.
+ *
+ * DONE names a retained painted draft, not presentation or a preparation attempt.
+ * Native code retains its membership, destination, and storage identity. DONE
+ * does not acquire a buffer lease automatically. Acquire qualified access below
+ * only when needed, and explicitly commit or cancel the draft before another frame.
+ * During preparation, render, resize, buffer draw, buffer borrowing, setup, and
+ * suspend reject with OT_FRAME_BUSY. Close, cancellation, root destruction, and
+ * owner teardown invalidate preparation attempts.
+ * After DONE, destroying nodes or the root leaves painted cells and capture intact
+ * without repainting. Commit, frame or Session cancellation, and owner teardown
+ * still end draft access.
+ *
+ * Preparation and painting never yield: each step runs until it returns a host
+ * request, DONE, or an error.
+ *
+ * Geometry observations are produced after phase publication.
+ * Geometry is not ticket authority and must not be echoed in acknowledgements.
+ * Each flag marks a valid snapshot; absent snapshots are zeroed, including for
+ * RECORD and DONE. Observation failures do not fail the step: a caller
+ * needing that observation must use the checked layout query.
+ * Accepted mutations may invalidate these snapshots before the next step.
+ * out_geometry requires exact size/version and zero reserved before advancement.
+ * All buffers are borrowed only for this call. previous may alias out_request;
+ * the two output records must be distinct. */
+ot_status ot_scene_frame_step_with_geometry(ot_context *, const ot_handle *session,
+    const ot_scene_frame_request *previous, const ot_scene_frame_options *,
+    const uint8_t *recording, uint32_t recording_length,
+    ot_scene_frame_request *out_request, ot_scene_frame_geometry *out_geometry);
+/* Copy the slots of the exact pending RECORD request. out_count receives the total
+ * slot count; min(capacity, total) slots are written in paint order. NULL out_slots
+ * requires zero capacity. Recording refers to slots by their index. */
+ot_status ot_scene_frame_get_paint_slots(ot_context *, const ot_handle *session,
+    const ot_scene_frame_request *record_request, ot_scene_paint_slot *out_slots,
+    uint32_t capacity, uint32_t *out_count);
+/* Cancel preparation or a retained painted draft. A stale frame ID rejects without
+ * cancelling the active frame. Cancellation immediately revokes qualified access
+ * and submission; pending hits cannot publish. Release every acquired scope even
+ * when validation returns OT_STALE_LEASE. Scratch NEXT bytes intentionally remain
+ * readable through an ordinary storage lease afterward for error inspection;
+ * cancellation does not guarantee zeroed cells. */
+ot_status ot_scene_frame_cancel(ot_context *, const ot_handle *session, uint64_t frame_id);
+
+/* A root creates one Session scene. Other nodes may remain detached. Nonzero public
+ * numbers are immutable; native hit tokens do not recycle. Node handles use the
+ * Context table. */
+ot_status ot_scene_create_node(ot_context *, const ot_handle *session, uint32_t kind,
+    uint32_t num, ot_handle *out_node);
+/* Individual destruction detaches surviving children. Session destruction frees
+ * all associated nodes, including detached nodes. NULL parent means detach.
+ * A failed layout solve, such as Yoga running out of memory, leaves the tree failed:
+ * frames, Yoga layout queries, and style, paint, and text setters return
+ * OT_INTERNAL_ERROR until its nodes are destroyed. Destroy, detach, blur, clearing a measure provider, and selection
+ * RESET still succeed. */
+ot_status ot_scene_destroy_node(ot_context *, const ot_handle *node);
+ot_status ot_scene_move_node(ot_context *, const ot_handle *node, const ot_handle *parent, uint32_t index);
+/* Detaches every child of node, as moving each to NULL from first to last would, in
+ * time linear in the child count. On error no child is detached. */
+ot_status ot_scene_clear_children(ot_context *, const ot_handle *node);
+/* Synchronous owner-thread measurement on leaves. The callback is borrowed until
+ * replacement, unset, node destruction, or Context destruction. NULL clears the
+ * single provider slot; it does not restore built-in measurement. Each set or clear
+ * invalidates the cached measurement. The result is two floats (width, height),
+ * initialized to NaN, valid only during the callback. A NaN, negative, or larger
+ * than INT32_MAX dimension measures as 0 and queues a Yoga warning diagnostic.
+ * Only scene style/layout/text/provider queries may reenter; mutations may not. */
+typedef void (*ot_scene_measure_callback)(uint64_t context_id, uint32_t slot, uint32_t generation,
+    float width, uint32_t width_mode, float height, uint32_t height_mode, float *out_size);
+ot_status ot_scene_set_measure(ot_context *, const ot_handle *node, ot_scene_measure_callback);
+ot_status ot_scene_has_measure(ot_context *, const ot_handle *node, uint32_t *out_enabled);
+/* out_reached is 1 when a frame's hooks reach the node: it is attached under the root, it and
+ * its ancestors are shown, and each culling ancestor selects its branch at the current offsets
+ * and child count from the latest layout (a child moved since then has no position, and is
+ * not selected). A node they do not reach gets no hook calls. */
+ot_status ot_scene_reaches_hooks(ot_context *, const ot_handle *node, uint32_t *out_reached);
+/* out_painted is 1 when the last frame that finished paint painted the node, or the presented
+ * frame once a later one is cancelled; 0 for the root and before any frame. */
+ot_status ot_scene_painted(ot_context *, const ot_handle *node, uint32_t *out_painted);
+ot_status ot_scene_mark_dirty(ot_context *, const ot_handle *node);
+/* Use OT_STYLE_* groups/kinds, OT_EDGE_* (or OT_GUTTER_* for GAP), and OT_UNIT_*.
+ * Only OT_STYLE_DIMENSION accepts OT_STYLE_DISABLE_FLEX_SHRINK, which disables
+ * flex shrink atomically with the dimension update. OT_STYLE_CONTENT writes the
+ * content layout node of a scroll node (see ot_scene_set_scroll) instead of the
+ * node, and rejects DISPLAY; PADDING on a scroll node requires it. Other flags must be zero.
+ * Finite MARGIN, PADDING, POSITION, and GAP values beyond ±1e30 are stored as ±1e30, so
+ * get_style reads the stored value; Yoga clamps resolved percentages the same way. */
+ot_status ot_scene_set_style(ot_context *, const ot_handle *node, uint32_t group,
+    uint32_t kind, uint32_t edge, uint32_t unit, float value, uint32_t flags);
+ot_status ot_scene_get_style(ot_context *, const ot_handle *node, uint32_t group,
+    uint32_t kind, uint32_t edge, ot_scene_style_value *out_value);
+/* Exact size/version and zero reserved. Borders use L=1 B=2 R=4 T=8;
+ * styles are single=0 double=1 rounded=2 heavy=3. Colors retain terminal color intent.
+ * focusable is 0 or 1. New nodes default to 0 and focused color {0,170,255,255}.
+ * Translations must be finite with a magnitude of at most FLT_MAX.
+ * Border layout widths and paint properties publish together on acceptance. */
+ot_status ot_scene_set_paint(ot_context *, const ot_handle *node, const ot_scene_paint_options *);
+/* --- Staged scene properties ---
+ * One borrowed byte stream, one mutation admission. Records apply in stream order;
+ * each record publishes atomically, including border appearance and Yoga widths.
+ * The first rejected record stops the call. out_applied counts complete accepted
+ * RECORDS, not bytes; the rejected record and suffix remain unapplied. No rollback.
+ * Admission/null/byte-limit failures consume zero. The record limit stops before
+ * record OT_SCENE_MUTATIONS_MAX + 1, preserving the accepted prefix.
+ *
+ * Each record starts with this 24-byte header. Values use native byte order and
+ * follow in increasing field-bit order, tightly packed, with zero padding to an
+ * 8-byte record size. Payload values may be unaligned. size_bytes must equal the
+ * size implied by fields. Unknown/empty masks and nonzero padding are rejected.
+ * Unselected visual fields retain accepted native values. RESET_BORDER_CHARACTERS
+ * carries no payload, requires BORDER_STYLE, and clears custom border characters
+ * after successful border-width publication.
+ *
+ * STYLE must be the sole bit and carries ot_scene_style_property (40 bytes total).
+ * Visual records are 32..88 bytes; a color/scalar costs 32 and all fields cost 88.
+ * NULL input requires zero bytes. out_applied is required, initialized even on
+ * failed Context admission, and must not alias input. Input is borrowed only for
+ * this call. The ABI requires matching headers and artifacts. */
+#define OT_SCENE_PROPERTY_Z_INDEX UINT32_C(1)
+#define OT_SCENE_PROPERTY_OPACITY UINT32_C(2)
+#define OT_SCENE_PROPERTY_TRANSLATE_X UINT32_C(4)
+#define OT_SCENE_PROPERTY_TRANSLATE_Y UINT32_C(8)
+#define OT_SCENE_PROPERTY_BORDER UINT32_C(16)
+#define OT_SCENE_PROPERTY_SHOULD_FILL UINT32_C(32)
+#define OT_SCENE_PROPERTY_BACKGROUND UINT32_C(64)
+#define OT_SCENE_PROPERTY_BORDER_COLOR UINT32_C(128)
+#define OT_SCENE_PROPERTY_BORDER_STYLE UINT32_C(256)
+#define OT_SCENE_PROPERTY_FOCUSABLE UINT32_C(512)
+#define OT_SCENE_PROPERTY_FOCUSED_BORDER_COLOR UINT32_C(1024)
+#define OT_SCENE_PROPERTY_STYLE UINT32_C(2048)
+#define OT_SCENE_PROPERTY_RESET_BORDER_CHARACTERS UINT32_C(4096)
+#define OT_SCENE_PROPERTY_RECORD_MAX UINT32_C(88)
+#define OT_SCENE_PROPERTY_BYTES_MAX (OT_SCENE_MUTATIONS_MAX * OT_SCENE_PROPERTY_RECORD_MAX)
+
+/* Field types, in bit order: int32_t, float, double, double, uint32_t,
+ * uint32_t, uint16_t[4], uint16_t[4], uint32_t, uint32_t, uint16_t[4].
+ * Field value rules match ot_scene_set_paint. */
+typedef struct ot_scene_property_update {
+    ot_handle node;
+    uint32_t fields;
+    uint32_t size_bytes;
+} ot_scene_property_update;
+
+typedef struct ot_scene_style_property {
+    uint8_t group;
+    uint8_t kind;
+    uint8_t edge;
+    uint8_t unit;
+    uint32_t flags;
+    float value;
+    uint32_t reserved;
+} ot_scene_style_property;
+
+ot_status ot_scene_flush(ot_context *,
+    const uint8_t *updates, uint32_t byte_count, uint32_t *out_applied);
+/* Retains a Context-owned buffer for a surface node. NULL clears the binding.
+ * Replacement retains the new buffer before releasing the previous binding. */
+ot_status ot_scene_set_surface(ot_context *, const ot_handle *node, const ot_handle *buffer);
+/* tfm fork: bind only BOX nodes. When on != 0 this node's TRANSLUCENT box fill
+ * keeps the image placements it covers and dims them (their reservation cells
+ * survive; uncovered placements and opaque fills are unchanged), instead of
+ * deleting them — the modal scrim overlay. Default 0 keeps the historical
+ * behavior. */
+ot_status ot_scene_set_fill_dims_images(ot_context *, const ot_handle *node, uint32_t on);
+ot_status ot_scene_set_box_details(ot_context *, const ot_handle *node, const ot_scene_box_details *,
+    const uint8_t *title, uint32_t title_bytes, const uint8_t *bottom_title, uint32_t bottom_title_bytes);
+/* A box may filter its direct children against a root/box in the same Session.
+ * The viewport handle is copied, not pinned. NULL disables filtering. A destroyed
+ * viewport fails frame preparation until rebound or disabled. Every direct child
+ * whose layout, text, view, or hooks changed refreshes before selection,
+ * including hidden/culled children; hidden nodes do not update or resize. Fewer than 16 total children bypass overlap filtering.
+ * Bounds use the full viewport, not its border-inset paint clip. Row/reverse-row
+ * use horizontal overlap; column/reverse-column use vertical overlap. Primary
+ * overlap is strict, cross-axis touching is included, and padding is zero.
+ * A scroll node rejects a viewport with OT_INVALID_ARGUMENT; as another node's
+ * viewport it bounds by its full box. */
+ot_status ot_scene_set_viewport(ot_context *, const ot_handle *node, const ot_handle *viewport);
+
+/* --- Scroll nodes ---
+ * ot_scene_set_scroll makes a box with no children a scroll node. It owns two
+ * hidden layout nodes: a viewport node, the box's only layout child (column,
+ * grow 1, overflow hidden, the viewport padding), and a content node inside it
+ * (align-self flex-start, shrink 0, min width and height 100%, and max 100% on
+ * an axis that does not scroll). The box's scene children lay out in the
+ * content node, and the box's own padding holds the gutters of visible inset
+ * bars. After each layout solve, max = max(0, content - viewport inner) on a
+ * scrolling axis (0 otherwise); if max, the content size, or the viewport
+ * changed, a stuck view moves to its follow edge; the offset clamps to
+ * [0, max] in whole cells. Children compose at the box origin
+ * plus the viewport and content origins minus the offset, clip to the viewport
+ * rect, and with culling filter against it like ot_scene_set_viewport. Auto
+ * bars show while max > 0; a box toggles its bars at most twice per frame,
+ * after which a bar may still appear but not hide. Bars paint after the box's
+ * children and hit the box. Options are complete and copied. A later call
+ * updates options; a changed follow recomputes stuck. stuck starts true and
+ * changes only on explicit scrolls (ot_scene_scroll_to, ot_scene_scroll_request),
+ * follow changes, and the solves that apply a request or an anchor: it is true
+ * when the offset reached the follow edge or max on that axis is at most 1.
+ * Rejection preserves accepted state. */
+#define OT_SCENE_SCROLL_X UINT32_C(1)
+#define OT_SCENE_SCROLL_Y UINT32_C(2)
+#define OT_SCENE_SCROLL_FOLLOW_NONE UINT32_C(0)
+#define OT_SCENE_SCROLL_FOLLOW_TOP UINT32_C(1)
+#define OT_SCENE_SCROLL_FOLLOW_BOTTOM UINT32_C(2)
+#define OT_SCENE_SCROLL_FOLLOW_LEFT UINT32_C(3)
+#define OT_SCENE_SCROLL_FOLLOW_RIGHT UINT32_C(4)
+#define OT_SCENE_SCROLL_FILL_WRAPPER UINT32_C(1)
+#define OT_SCENE_SCROLL_FILL_VIEWPORT UINT32_C(2)
+#define OT_SCENE_SCROLL_FILL_CONTENT UINT32_C(4)
+#define OT_SCENE_SCROLL_BAR_AUTO UINT32_C(0)
+#define OT_SCENE_SCROLL_BAR_ALWAYS UINT32_C(1)
+#define OT_SCENE_SCROLL_BAR_NEVER UINT32_C(2)
+#define OT_SCENE_SCROLL_BAR_INSET UINT32_C(0)
+#define OT_SCENE_SCROLL_BAR_OVERLAY UINT32_C(1)
+#define OT_SCENE_SCROLL_RELATIVE_X UINT32_C(1)
+#define OT_SCENE_SCROLL_RELATIVE_Y UINT32_C(2)
+#define OT_SCENE_SCROLL_REAPPLY UINT32_C(4)
+#define OT_SCENE_SCROLL_REQUEST_INTO_VIEW UINT32_C(0)
+#define OT_SCENE_SCROLL_REQUEST_ANCHOR UINT32_C(1)
+#define OT_SCENE_SCROLL_REQUEST_LAYOUT UINT32_C(2)
+#define OT_SCENE_SCROLL_ALIGN_NEAREST UINT32_C(0)
+#define OT_SCENE_SCROLL_ALIGN_START UINT32_C(1)
+#define OT_SCENE_SCROLL_ALIGN_END UINT32_C(2)
+
+/* thickness is 1..255 cells and gap 0..255 cells (between content and track);
+ * an inset bar's gutter is gap + thickness, an overlay bar takes none. arrows
+ * is 0 or 1. Track colors retain terminal color intent. reserved must be zero. */
+typedef struct ot_scene_scroll_bar_options {
+    uint32_t policy;
+    uint32_t placement;
+    uint32_t thickness;
+    uint32_t gap;
+    uint32_t arrows;
+    uint32_t reserved;
+    uint16_t track_foreground[4];
+    uint16_t track_background[4];
+} ot_scene_scroll_bar_options;
+
+#define OT_SCENE_SCROLL_PADDING_MAX UINT32_C(65535)
+/* axes holds OT_SCENE_SCROLL_X/Y. culling is 0 or 1. padding is the viewport
+ * padding in whole cells, left, top, right, bottom, each 0..PADDING_MAX. fills selects
+ * which of the wrapper (box inner rect minus the vertical gutter), viewport, and
+ * content (moving with the offset) backgrounds paint, in that order, before the
+ * children. bars[0] is the horizontal bar, bars[1] the vertical bar. */
+typedef struct ot_scene_scroll_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t axes;
+    uint32_t follow;
+    uint32_t culling;
+    uint32_t fills;
+    float padding[4];
+    uint16_t wrapper_background[4];
+    uint16_t viewport_background[4];
+    uint16_t content_background[4];
+    ot_scene_scroll_bar_options bars[2];
+} ot_scene_scroll_options;
+
+/* Rects are x, y, width, height in cells. track, arrows, and viewport are screen
+ * cells of the last prepared frame; content is local to the node. thumb_start
+ * and thumb_size are half cells along the track, as ot_scene_slider_thumb. */
+typedef struct ot_scene_scroll_bar_state {
+    uint32_t visible;
+    uint32_t reserved;
+    double track[4];
+    double start_arrow[4];
+    double end_arrow[4];
+    double thumb_start;
+    double thumb_size;
+} ot_scene_scroll_bar_state;
+
+/* generation changes with every change of the other fields. changes holds the
+ * OT_SCENE_SCROLL_CHANGED_* bits that differed from the last report when the last
+ * SCROLL request was issued. Setting OT_SCENE_HOOK_SCROLL on a node that did not
+ * have it makes the current state the last report. */
+#define OT_SCENE_SCROLL_CHANGED_OFFSET_X UINT32_C(1)
+#define OT_SCENE_SCROLL_CHANGED_OFFSET_Y UINT32_C(2)
+#define OT_SCENE_SCROLL_CHANGED_CONTENT UINT32_C(4)
+#define OT_SCENE_SCROLL_CHANGED_VIEWPORT UINT32_C(8)
+/* Set on the request that delivers an OT_SCENE_SCROLL_REQUEST_LAYOUT callback. */
+#define OT_SCENE_SCROLL_CHANGED_LAYOUT UINT32_C(16)
+typedef struct ot_scene_scroll_state {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t stuck;
+    uint32_t changes;
+    uint64_t generation;
+    double offset[2];
+    double max[2];
+    double content[4];
+    double viewport[4];
+    ot_scene_scroll_bar_state bars[2];
+} ot_scene_scroll_state;
+
+ot_status ot_scene_set_scroll(ot_context *, const ot_handle *node, const ot_scene_scroll_options *);
+/* axis is 0 (horizontal bar) or 1 (vertical bar); end is 0 (start) or 1 (end).
+ * Options and text follow ot_scene_set_arrow; direction must be zero and the
+ * axis and end choose the glyph unless text is given. */
+ot_status ot_scene_set_scroll_arrow(ot_context *, const ot_handle *node, uint32_t axis, uint32_t end,
+    const ot_scene_arrow_options *, const uint8_t *text, uint32_t byte_count);
+/* An explicit scroll. Without RELATIVE_X/Y the values are absolute offsets; a
+ * relative delta of 0 keeps an axis. Values round to whole cells and clamp to
+ * the limits of the last solve; ±Infinity clamp, NaN returns
+ * OT_INVALID_ARGUMENT. It recomputes stuck, moves a held anchor's row with the
+ * offset, marks the offset (not the sizes) as reported to the host, and copies
+ * the new state to out_state unless it is NULL. During a frame attempt the next
+ * round prepares at the new offset.
+ * With REAPPLY each axis it sets also keeps its target, and every solve of the
+ * next frame (the current one during an attempt, or a later one if that frame
+ * is cancelled) moves the offset to the target again, clamped to the new limits,
+ * and recomputes stuck. A relative delta adds to a pending target. A target of
+ * +Infinity, or one at or past a positive max of a laid-out node, is the end:
+ * it lands at the new max and releases a held anchor. A following view that the
+ * scroll left stuck where it asked keeps no target on the follow axis. A later
+ * scroll without REAPPLY drops pending targets. */
+ot_status ot_scene_scroll_to(ot_context *, const ot_handle *node, double x, double y, uint32_t flags,
+    ot_scene_scroll_state *out_state);
+/* Requests about a node in the scroll node's subtree, read from the last solve
+ * (OT_INVALID_ARGUMENT for a node outside it):
+ * - INTO_VIEW scrolls now so the target's rect is inside the viewport inset by
+ *   inset cells (align NEAREST moves the least, as a browser does; START puts its
+ *   start at the inset edge; END its end), and again after each solve of the next
+ *   frame, as a REAPPLY scroll does; it replaces pending targets. A target that
+ *   was never laid out scrolls only after its first solve.
+ * - ANCHOR holds the target's position in the viewport: after each solve the
+ *   offset moves with the target, clamped, and stuck is recomputed; while held,
+ *   the anchor decides the offset over sticky follow and pending requests. A
+ *   target that was never laid out holds the place its first solve gives it. An
+ *   explicit scroll moves the held row. A NULL target releases it; so does
+ *   destroying the target or moving it out of the subtree. align and inset are 0.
+ * - LAYOUT asks for one SCROLL request (OT_SCENE_SCROLL_CHANGED_LAYOUT in
+ *   changes) in the next frame, after its layout settles and before it paints,
+ *   while OT_SCENE_HOOK_SCROLL is set and the node is visible. target is NULL,
+ *   align and inset are 0.
+ * out_state follows ot_scene_scroll_to. */
+ot_status ot_scene_scroll_request(ot_context *, const ot_handle *node, uint32_t kind, const ot_handle *target,
+    uint32_t align, uint32_t inset, ot_scene_scroll_state *out_state);
+/* Pure: it never changes what an OT_SCENE_FRAME_SCROLL request reports. With
+ * OT_SCENE_HOOK_SCROLL (scroll nodes only) a frame returns one SCROLL request,
+ * after the node's refresh and before paint, when the offset differs from the last
+ * reported or written offset, or the content or viewport size from the last
+ * reported size. */
+ot_status ot_scene_get_scroll(ot_context *, const ot_handle *node, ot_scene_scroll_state *out_state);
+/* focused is 0 or 1. Stores one accepted target without host focus/input policy.
+ * Focusable boxes on its current ancestor path use focused_border_color. Zero
+ * clears only a matching target and remains valid after Session cancellation. */
+ot_status ot_scene_set_focus(ot_context *, const ot_handle *node, uint32_t focused);
+/* Exact size/version and zero reserved where present. Rejection preserves accepted
+ * options and query output. Slider/arrow paint is separate from common node paint;
+ * borders are unsupported. No custom arrow strings or native-to-host paint calls. */
+ot_status ot_scene_set_slider(ot_context *, const ot_handle *node, const ot_scene_slider_options *);
+/* Custom text is copied and bounded by OT_BUFFER_TEXT_BYTES_MAX. NULL selects the standard direction glyph. */
+ot_status ot_scene_set_arrow(ot_context *, const ot_handle *node, const ot_scene_arrow_options *, const uint8_t *text, uint32_t byte_count);
+/* Uses current observed wrapper dimensions without running Yoga. Before the first
+ * observed layout, dimensions come from ot_scene_set_hooks initial_width/height
+ * (flags may be zero), or default to zero. Later style changes do not change this
+ * constructor baseline. Painting uses completed geometry, not this projection. */
+ot_status ot_scene_get_slider_thumb(ot_context *, const ot_handle *node, ot_scene_slider_thumb *out_thumb);
+/* Text nodes own their buffer/view and native measure target. Replacements copy
+ * UTF-8 and preserve content on rejection. Length is bounded by u32 line/column
+ * counts, accounting for tab expansion, not the offscreen drawing call budget.
+ * C0/C1/DEL controls other than tab, CR, and LF are accepted and returned by
+ * queries; painting gives them no cells and never writes them to the terminal.
+ * Line endings normalize to LF in queries. bytes may be NULL only for zero length. Options require exact
+ * size/version; borders and child nodes are not supported on text. */
+ot_status ot_scene_set_text(ot_context *, const ot_handle *node, const uint8_t *bytes, uint32_t byte_count);
+/* Copies a complete styled replacement. Every chunk requires exact size/version,
+ * positive UTF-8 byte_count, and zero reserved. Chunk lengths sum to byte_count.
+ * Only FOREGROUND/BACKGROUND/LINK flags and attributes bits 0..7 are accepted. Present
+ * colors retain terminal color intent; absent colors inherit the node defaults.
+ * Chunk widths retain legacy independently measured display-column ranges.
+ * All bytes, styles, and listener storage are prepared before publication.
+ * Rejection preserves accepted content and resources. No style handles.
+ * Each array may be NULL only when its count is zero. link_offset and
+ * link_byte_count select bytes in urls; without LINK both must be zero. URLs are
+ * copied, not normalized. Empty URLs, URLs over 512 bytes,
+ * URLs that are not UTF-8 or hold a C0, DEL or C1 control, and chunks with zero
+ * independently measured width produce no link; their text stays. Oversized
+ * URLs are not truncated. URLs and their references are prepared before publication;
+ * rejection preserves accepted text, styles, and links. urls may be NULL only
+ * when url_byte_count is zero. Link IDs stay local to the owning Context. */
+ot_status ot_scene_set_styled_text(ot_context *, const ot_handle *node,
+    const uint8_t *bytes, uint32_t byte_count, const ot_styled_text_chunk *chunks, uint32_t chunk_count,
+    const uint8_t *urls, uint32_t url_byte_count);
+ot_status ot_scene_set_text_options(ot_context *, const ot_handle *node, const ot_scene_text_options *);
+/* Select through the owned Text view. Coordinates are local display cells/virtual
+ * rows, with signed offscreen positions clamped by the view. Coordinates plus
+ * viewport scroll offsets must fit int32_t. UPDATE retains an
+ * existing document anchor across scrolling, or acts as SET without an anchor.
+ * Exact size/version, zero reserved, and only BACKGROUND/FOREGROUND flags are
+ * accepted. Present colors retain terminal color intent; absent color arrays must be zero.
+ * out_changed is the view's 0/1 change result. Failure preserves selection and
+ * out_changed. RESET needs no allocation and is allowed after Session cancellation.
+ * Mutation is forbidden during measurement callbacks, including RESET. */
+ot_status ot_scene_set_text_selection(ot_context *, const ot_handle *node,
+    const ot_scene_text_selection_options *, uint32_t *out_changed);
+/* Packed display-column offsets: start in the high 32 bits, exclusive end in the
+ * low 32 bits. UINT64_MAX means absent or zero-width selection. */
+ot_status ot_scene_get_text_selection(ot_context *, const ot_handle *node, uint64_t *out_packed);
+/* Zero capacity reports the exact selected UTF-8 byte count;
+ * absent/zero-width selection reports zero. A copy requires at least
+ * that count and returns the selected byte count, without a terminating
+ * NUL. Insufficient capacity rejects before writing bytes or out_count. bytes may
+ * be NULL only for zero capacity. These reads follow the text getter rules. */
+ot_status ot_scene_get_selected_text(ot_context *, const ot_handle *node,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+/* Copied queries retain no native memory. Zero capacity reports the exact count;
+ * otherwise insufficient text capacity rejects without writing either output. bytes
+ * and lines may be NULL only for zero capacity. Text has no terminating NUL.
+ * Lines copies virtual lines [first_line, first_line + capacity), clipped to the
+ * count of all virtual lines, not only visible ones, which out_count reports. Info
+ * requires exact size/version. Queries never perform Yoga layout or resize the viewport. */
+ot_status ot_scene_get_text(ot_context *, const ot_handle *node, uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+ot_status ot_scene_get_text_info(ot_context *, const ot_handle *node, ot_scene_text_info *out_info);
+ot_status ot_scene_get_text_lines(ot_context *, const ot_handle *node, uint32_t first_line,
+    ot_scene_text_line *lines, uint32_t capacity, uint32_t *out_count);
+/* The byte offset, in the UTF-8 last set on the text node, where the grapheme the latest
+ * finished frame drew at screen cell (x, y) starts. UINT32_MAX when that frame did not
+ * paint the node, when its text or view options changed since, and when the cell lies
+ * outside the node's painted cells or shows no whole grapheme: padding, a truncation
+ * ellipsis, a wide grapheme an edge cuts, zero opacity, or a RENDER_SELF hook's body
+ * in place of the text. A failed paint attempt leaves the answers of the frame before
+ * it, except for nodes it drew. It never lays text out, and does not check
+ * what covers the cell; ot_scene_hit_test does. Follows the text getter rules. */
+ot_status ot_scene_get_text_byte_at(ot_context *, const ot_handle *node, int32_t x, int32_t y, uint32_t *out_byte);
+/* OT_LAYOUT_PUBLIC copies local cell geometry from the node's latest preparation refresh.
+ * Below a child that its filtering parent's latest selection culled, which no refresh
+ * reaches, it copies the latest solved geometry instead, if Yoga has laid the node out since
+ * it was created or moved. During host phases, mounted nodes retain their preceding projection until that
+ * refresh; newly placed children refresh before their own update. screen_x/y
+ * combine that geometry with current accepted ancestor relationships
+ * and translations immediately, without running layout. OT_LAYOUT_YOGA instead
+ * copies the six actual Yoga computed values, including zero dimensions, and
+ * sets screen_x/y to zero. OT_LAYOUT_PAINT copies where the latest paint list painted the
+ * node, or where a frame being prepared places it, including screen_x/y, with each axis
+ * that leaves the signed 32-bit cell range clamped to the whole cells it paints within 2^22
+ * of the origin, at least one unless zero; PUBLIC and YOGA keep the unclamped values.
+ * PUBLIC raises a zero width or height to one cell; PAINT keeps it, and a node with a zero
+ * dimension paints and hits no cell. During a RECORD request, mutations do not change those
+ * coordinates. A node that list did not paint (hidden, culled, or detached), and every node
+ * after a solve or after a change between frames that drops the list, until the next list
+ * paints it, reads its latest solved geometry composed with current translations and
+ * offsets; zeros if Yoga has not laid it out since it was created or moved. While a host
+ * request is pending, such a node's first read holds. OT_LAYOUT_CONTENT is PAINT without a
+ * text node's padding, its content edges rounded as Yoga rounds the node's own edges (no
+ * padding reads the box): the cells its text view fills, which paint, wrapping, text byte
+ * hits, selection and body draws use. Other nodes read PAINT.
+ * These reads do not run layout. Other selectors reject without changing output.
+ * A scroll node's children report YOGA values local to its content node, and their
+ * screen_x/y compose through the viewport and content origins and the offset. */
+ot_status ot_scene_get_layout(ot_context *, const ot_handle *node, uint32_t observation, ot_scene_layout *out_layout);
+/* Paint a hook-free scene and retain its DONE draft in out_frame. Commit it with
+ * ot_scene_frame_commit, or cancel it before painting again. Frame-qualified
+ * effects and capture may run before commit. Initialize out_frame's exact
+ * size/version and zero reserved fields; rejection leaves it unchanged.
+ * No output or hit publication occurs until commit and output completion.
+ * Pending presentation rejects painting; accepted scene mutations remain valid.
+ * excluded_hit_num is the captured node's public number, or zero. It excludes
+ * only that node from this frame's hits, not its painting or descendants.
+ * Uses the same phase engine, but rejects registered hooks before layout with
+ * OT_UNSUPPORTED_RESOURCE. Use ot_scene_frame_step_with_geometry for host hooks. */
+ot_status ot_scene_paint(ot_context *, const ot_handle *session, const uint16_t background[4], uint32_t use_mouse, uint32_t excluded_hit_num, ot_scene_frame_request *out_frame);
+ot_status ot_scene_hit_test(ot_context *, const ot_handle *session, int32_t x, int32_t y, uint32_t *out_num);
+/* ot_scene_hit_test as if the node with public number excluded_num painted no hits (zero
+ * excludes none). Its descendants still hit. A drag looks up targets through its source. */
+ot_status ot_scene_hit_test_excluding(ot_context *, const ot_handle *session, int32_t x, int32_t y, uint32_t excluded_num, uint32_t *out_num);
+ot_status ot_scene_get_stats(ot_context *, const ot_handle *session, ot_scene_stats *out_stats);
+#define OT_SCENE_DEBUG_FULL_FRAME UINT32_C(1)
+#define OT_SCENE_DEBUG_VERIFY UINT32_C(2)
+/* Diagnostic switches for tests. FULL_FRAME rebuilds each frame's preparation
+ * and paint lists instead of reusing the last frame's, and every later shortcut
+ * that skips frame work also tests it; Yoga still solves only a dirty tree, and
+ * geometry is read only for nodes laid out since the last solve. Output is
+ * unchanged; only the work counts in ot_scene_stats differ, and frames report
+ * OT_SCENE_FULL_PATH_FORCED. A closed or cancelled Session returns
+ * OT_SESSION_CLOSED, a failed one OT_OUTPUT_FAILED, other bits
+ * OT_INVALID_ARGUMENT, a Session without a scene OT_INVALID_PHASE, and an active
+ * frame attempt, draft, or frame lease OT_FRAME_BUSY. Rejection keeps the flags.
+ * Flags persist for the Session. VERIFY checks frames that retained paint skips
+ * or repaints partly: next must still hold the presented frame, a partly
+ * repainted frame's other rows must match it, and a full repaint into a
+ * scratch buffer must match the cells and hits of a skipped or partly
+ * repainted frame. A mismatch fails the frame step
+ * with OT_INTERNAL_ERROR; VERIFY changes no other state or count. */
+ot_status ot_scene_set_debug_flags(ot_context *, const ot_handle *session, uint32_t flags);
+/* Copied renderer cursor state. style is an OT_CURSOR_STYLE_* value.
+ * Colors use normalized float channels. Output requires exact size/version. */
+ot_status ot_scene_get_cursor_state(ot_context *, const ot_handle *session, ot_scene_cursor_state *out_state);
+
+/* chunk_size, span_capacity, and max_bytes are explicit and positive. max_bytes
+ * is a multiple of chunk_size and must fit at most UINT32_MAX chunks. It bounds
+ * allocated feed chunks and outstanding payload bytes. span_capacity includes
+ * queued and copied output awaiting completion. All chunks are allocated at creation.
+ * control_capacity is zero for no reservation. A positive value reserves bytes
+ * inside max_bytes, rounded up to whole chunks, with one span slot per chunk.
+ * Ordinary writes cannot use this capacity. The reservation must leave at least
+ * one ordinary chunk and one ordinary span slot. Terminal setup requires at least
+ * OT_SESSION_CONTROL_PACKET_BYTES of rounded control storage. reserved is zero. */
+typedef struct ot_session_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t chunk_size;
+    uint32_t span_capacity;
+    uint64_t max_bytes;
+    uint32_t control_capacity;
+    uint32_t reserved;
+} ot_session_options;
+
+/* Output bytes are copied into caller-owned storage. Complete this exact ticket
+ * only after its bytes reach the transport, not when a write merely queues them.
+ * At most one ticket is pending per session. reserved is always zero. */
+typedef struct ot_output_ticket {
+    ot_handle session;
+    uint64_t request_id;
+    uint32_t byte_count;
+    uint32_t reserved;
+} ot_output_ticket;
+
+#define OT_SESSION_OPEN UINT32_C(0)
+#define OT_SESSION_CLOSING UINT32_C(1)
+#define OT_SESSION_CLOSED_STATE UINT32_C(2)
+#define OT_SESSION_FAILED UINT32_C(3)
+#define OT_SESSION_CANCELLED_STATE UINT32_C(4)
+
+/* Attach without terminal setup or output. Dimensions are positive terminal
+ * cells and obey the Context's render_cells_max. remote is 0 or 1; remote
+ * terminals do not inherit the local terminal environment. reserved is zero. */
+typedef struct ot_session_renderer_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t width;
+    uint32_t height;
+    uint32_t remote;
+    uint32_t reserved;
+} ot_session_renderer_options;
+
+#define OT_SESSION_REMOTE_AUTO UINT32_C(0)
+#define OT_SESSION_REMOTE_LOCAL UINT32_C(1)
+#define OT_SESSION_REMOTE_REMOTE UINT32_C(2)
+#define OT_SESSION_ENV_ENTRIES_MAX UINT32_C(256)
+#define OT_SESSION_ENV_BYTES_MAX UINT32_C(65536)
+
+/* Additive attachment with initialization-only copied host environment. For each
+ * of entry_count entries, the payload holds the little-endian u32 key and value
+ * byte lengths, then the key bytes and the value bytes. Keys and values are
+ * UTF-8 without NUL; keys are nonempty and exclude '='. byte_count includes the
+ * eight length bytes per entry. Duplicate keys use the last value. Empty payload opts out.
+ * Auto detects remote sessions but ignores forwarded host hints when remote;
+ * explicit local/remote modes apply all supplied hints. No process env is read.
+ * reserved is zero. Payload and options are borrowed only for the call. */
+typedef struct ot_session_renderer_env_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t width;
+    uint32_t height;
+    uint32_t remote_mode;
+    uint32_t entry_count;
+    uint32_t byte_count;
+    uint32_t reserved;
+} ot_session_renderer_env_options;
+
+#define OT_RENDER_PRESENTED UINT32_C(0)
+#define OT_RENDER_PENDING UINT32_C(1)
+#define OT_RENDER_SKIPPED UINT32_C(2)
+#define OT_RENDER_FAILED UINT32_C(3)
+
+typedef struct ot_split_snapshot {
+    ot_handle buffer;
+    uint32_t row_columns;
+    uint32_t flags; /* 1 = start on new line, 2 = trailing newline. */
+} ot_split_snapshot;
+
+/* command: reset=0, sync=1, output-offset=2, render-offset=3, transition=4,
+ * clear-transition=5. Reset uses seed rows/pinned offset; sync and offset commands
+ * use argument 0. Transition uses mode (viewport-scroll=1, clear=2), source top,
+ * source height, target top, target height, scroll rows. Unused arguments are zero.
+ * Until a split frame applies it or clear-transition drops it, a pending transition
+ * makes ordinary frames, setup, and resume return OT_OUTPUT_BUSY. Controls, clipboard
+ * writes, and notifications do not move the cursor and do not wait for it. */
+typedef struct ot_split_control {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t command;
+    uint32_t arguments[6];
+} ot_split_control;
+
+/* Copy a checked painted draft into a Context buffer without presenting it. */
+ot_status ot_scene_frame_copy_buffer(ot_context *, const ot_handle *session,
+    const ot_scene_frame_request *, const ot_handle *target);
+/* Solve an idle scene's existing root without frame preparation, hooks, or painting.
+ * Custom Yoga measurement providers may run. Read computed dimensions with raw_yoga=1. */
+ot_status ot_scene_measure_layout(ot_context *, const ot_handle *session, const ot_handle *root);
+#define OT_SPLIT_SNAPSHOTS_MAX UINT32_C(64)
+/* At most SPLIT_SNAPSHOTS_MAX snapshots; Context identities are checked before native bounded copies.
+ * A null frame submits snapshots only, without painting or publishing the footer draft.
+ * After suspension completes, null-frame snapshots remain permitted without reactivating
+ * terminal modes; their output packet leaves the cursor restored. Non-null frames and
+ * submissions during terminal transitions retain the ordinary rendering restrictions.
+ * force is 0/1. OT_OK writes out_status, including SKIPPED and FAILED.
+ * With a frame, all statuses consume the draft under ot_scene_frame_commit's rules.
+ * Without a frame, PENDING may describe an earlier submission; no new snapshots
+ * were accepted in that case. Admission errors preserve a live draft for retry. */
+ot_status ot_session_render_split(ot_context *, const ot_handle *session, const ot_scene_frame_request *,
+    const ot_split_snapshot *, uint32_t count, uint32_t pinned_render_offset, uint32_t force,
+    uint32_t *out_status);
+ot_status ot_session_split_control(ot_context *, const ot_handle *session, const ot_split_control *, uint32_t *out_offset);
+/* Screen mode, dimensions, and copied trailing output are admitted together.
+ * The screen packet plus trailing output must fit within 4096 bytes. */
+ot_status ot_session_set_screen(ot_context *, const ot_handle *session, uint32_t alternate, uint32_t width, uint32_t height,
+    const uint8_t *trailing_output, uint32_t byte_count);
+ot_status ot_session_sync_detached(ot_context *, const ot_handle *session, const ot_handle *parent);
+
+/* Initialize struct_size and abi_version. The remaining fields are output-only.
+ * frame_count counts complete presentations, not queued frames. frame_pending
+ * is 0 or 1. image_uploads_pending counts presented Kitty and Sixel placements
+ * whose image a later frame still sends: uploads that did not fit one frame
+ * wait, and one larger than a frame draws as blocks next. Submit another frame
+ * while it is nonzero. A frame whose output without image uploads is larger than
+ * the write limit returns FAILED: dropped_frame_bytes is then its size (saturated),
+ * and dropped_frames counts each dropped content once. A frame that wrote only some
+ * cells is counted once its full repaint fails too. The same content returns
+ * FAILED again, with its size, without encoding until it changes; any other result
+ * sets dropped_frame_bytes to 0. This copied record borrows no renderer or framebuffer
+ * storage. */
+typedef struct ot_session_renderer_state {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t width;
+    uint32_t height;
+    uint64_t frame_count;
+    uint32_t frame_pending;
+    uint32_t image_uploads_pending;
+    uint32_t dropped_frames;
+    uint32_t dropped_frame_bytes;
+} ot_session_renderer_state;
+
+#define OT_SESSION_BUFFER_CURRENT UINT32_C(0)
+#define OT_SESSION_BUFFER_NEXT UINT32_C(1)
+
+#define OT_WIDTH_METHOD_WCWIDTH UINT32_C(0)
+#define OT_WIDTH_METHOD_UNICODE UINT32_C(1)
+#define OT_WIDTH_METHOD_NO_ZWJ UINT32_C(2)
+#define OT_WIDTH_METHOD_UNICODE_WIDE UINT32_C(3)
+#define OT_BUFFER_RESPECT_ALPHA UINT32_C(1)
+
+/* Context-owned offscreen storage, independent of any Session. Dimensions are
+ * positive, at most INT32_MAX, and width * height obeys render_cells_max.
+ * width_method is one of OT_WIDTH_METHOD_*. flags is zero or
+ * OT_BUFFER_RESPECT_ALPHA; all other bits are rejected. */
+typedef struct ot_buffer_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t width;
+    uint32_t height;
+    uint32_t width_method;
+    uint32_t flags;
+} ot_buffer_options;
+
+/* Copied records belong to a live Unicode resource. character is not a portable
+ * scalar: pooled values may only be drawn through their owning Context resource. */
+typedef struct ot_unicode_char {
+    uint32_t width;
+    uint32_t character;
+} ot_unicode_char;
+
+/* Encodes one record per drawn glyph. Controls produce no record. A tab, or a
+ * grapheme over the native 128-byte limit or 16 cells, produces one width-1
+ * space per cell. */
+ot_status ot_unicode_create(ot_context *, const uint8_t *bytes, uint32_t byte_count,
+    uint32_t width_method, ot_handle *out_unicode);
+ot_status ot_unicode_destroy(ot_context *, const ot_handle *unicode);
+/* Zero capacity reports the count; insufficient capacity preserves both outputs. */
+ot_status ot_unicode_get(ot_context *, const ot_handle *unicode, ot_unicode_char *characters,
+    uint32_t capacity, uint32_t *out_count);
+ot_status ot_buffer_draw_unicode(ot_context *, const ot_handle *target,
+    const ot_scene_frame_request *frame, const ot_handle *unicode, uint32_t index,
+    int32_t x, int32_t y, const uint16_t foreground[4], const uint16_t background[4], uint32_t attributes);
+
+typedef struct ot_embedded_terminal_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t cols;
+    uint32_t rows;
+    uint32_t max_scrollback;
+    /* Cell pixel geometry of the host terminal. Kitty image placements are
+     * sized in pixels, so the terminal needs it to place them. Zero falls back
+     * to a nominal 8x16 cell. */
+    uint32_t cell_width_px;
+    uint32_t cell_height_px;
+    uint32_t reserved;
+} ot_embedded_terminal_options;
+
+typedef struct ot_embedded_terminal_cursor {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t x;
+    uint32_t y;
+    uint32_t has_value;
+    uint32_t visible;
+    uint32_t blinking;
+    uint32_t wide_tail;
+    uint32_t style;
+    uint32_t color_has_value;
+    uint32_t color_r;
+    uint32_t color_g;
+    uint32_t color_b;
+    uint32_t reserved;
+} ot_embedded_terminal_cursor;
+/* The emulator's cursor styles for style above; not the OT_CURSOR_STYLE_* order. */
+#define OT_EMBEDDED_TERMINAL_CURSOR_BAR UINT32_C(0)
+#define OT_EMBEDDED_TERMINAL_CURSOR_BLOCK UINT32_C(1)
+#define OT_EMBEDDED_TERMINAL_CURSOR_UNDERLINE UINT32_C(2)
+#define OT_EMBEDDED_TERMINAL_CURSOR_BLOCK_HOLLOW UINT32_C(3)
+
+/* The active screen's viewport, in rows. offset is the distance from the live
+ * screen (0 there; total - visible at the top of history). total includes the
+ * visible rows; the alternate screen has no history. Output, resizes, scrollback
+ * clears, and screen switches move the viewport too; read it after each. */
+typedef struct ot_embedded_terminal_scrollbar {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t offset;
+    uint32_t total;
+    uint32_t visible;
+    uint32_t reserved;
+} ot_embedded_terminal_scrollbar;
+
+typedef struct ot_embedded_terminal_key {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t action;
+    uint32_t composing;
+    uint32_t mods;
+    uint32_t consumed_mods;
+    uint32_t unshifted_codepoint;
+    uint32_t reserved;
+} ot_embedded_terminal_key;
+
+typedef struct ot_embedded_terminal_mouse {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t action;
+    int32_t button;
+    uint32_t mods;
+    uint32_t any_button_pressed;
+    float x;
+    float y;
+} ot_embedded_terminal_mouse;
+
+/* mods and consumed_mods use the emulator's bits, not OT_INPUT_MOD_*. It has no
+ * Hyper or Meta: hosts send Kitty Meta as ALT. button is BUTTON_NONE for motion
+ * without a pressed button. */
+#define OT_EMBEDDED_TERMINAL_MOD_SHIFT UINT32_C(1)
+#define OT_EMBEDDED_TERMINAL_MOD_CTRL UINT32_C(2)
+#define OT_EMBEDDED_TERMINAL_MOD_ALT UINT32_C(4)
+#define OT_EMBEDDED_TERMINAL_MOD_SUPER UINT32_C(8)
+#define OT_EMBEDDED_TERMINAL_MOD_CAPS_LOCK UINT32_C(16)
+#define OT_EMBEDDED_TERMINAL_MOD_NUM_LOCK UINT32_C(32)
+#define OT_EMBEDDED_TERMINAL_KEY_RELEASE UINT32_C(0)
+#define OT_EMBEDDED_TERMINAL_KEY_PRESS UINT32_C(1)
+#define OT_EMBEDDED_TERMINAL_KEY_REPEAT UINT32_C(2)
+#define OT_EMBEDDED_TERMINAL_MOUSE_PRESS UINT32_C(0)
+#define OT_EMBEDDED_TERMINAL_MOUSE_RELEASE UINT32_C(1)
+#define OT_EMBEDDED_TERMINAL_MOUSE_MOTION UINT32_C(2)
+#define OT_EMBEDDED_TERMINAL_BUTTON_NONE INT32_C(-1)
+#define OT_EMBEDDED_TERMINAL_BUTTON_UNKNOWN INT32_C(0)
+#define OT_EMBEDDED_TERMINAL_BUTTON_LEFT INT32_C(1)
+#define OT_EMBEDDED_TERMINAL_BUTTON_RIGHT INT32_C(2)
+#define OT_EMBEDDED_TERMINAL_BUTTON_MIDDLE INT32_C(3)
+#define OT_EMBEDDED_TERMINAL_BUTTON_FOUR INT32_C(4)
+#define OT_EMBEDDED_TERMINAL_BUTTON_FIVE INT32_C(5)
+#define OT_EMBEDDED_TERMINAL_BUTTON_SIX INT32_C(6)
+#define OT_EMBEDDED_TERMINAL_BUTTON_SEVEN INT32_C(7)
+
+/* All option records require exact size/version and zero reserved fields.
+ * Booleans are 0/1. Input and output buffers are borrowed only during the call.
+ * Columns and rows are positive u16 values within the Context cell budget.
+ * Write, key-name, key-text, and paste inputs are each limited to INPUT_BYTES_MAX. */
+#define OT_EMBEDDED_TERMINAL_INPUT_BYTES_MAX UINT32_C(1048576)
+ot_status ot_embedded_terminal_create(ot_context *, const ot_embedded_terminal_options *, ot_handle *out_terminal);
+ot_status ot_embedded_terminal_destroy(ot_context *, const ot_handle *terminal);
+ot_status ot_embedded_terminal_write(ot_context *, const ot_handle *terminal, const uint8_t *bytes, uint32_t byte_count);
+ot_status ot_embedded_terminal_resize(ot_context *, const ot_handle *terminal, uint32_t cols, uint32_t rows);
+/* Cell pixel geometry of the host terminal. Zero keeps the current value. */
+ot_status ot_embedded_terminal_set_cell_size(ot_context *, const ot_handle *terminal, uint32_t cell_width_px, uint32_t cell_height_px);
+#define OT_EMBEDDED_TERMINAL_INVALIDATE UINT32_C(0)
+#define OT_EMBEDDED_TERMINAL_SCROLL UINT32_C(1)
+#define OT_EMBEDDED_TERMINAL_CLEAR_SELECTION UINT32_C(2)
+#define OT_EMBEDDED_TERMINAL_SET_TRANSPARENT_BACKGROUND UINT32_C(3)
+/* argument is a signed row delta for SCROLL, zero otherwise. */
+ot_status ot_embedded_terminal_command(ot_context *, const ot_handle *terminal, uint32_t command, int32_t argument);
+ot_status ot_embedded_terminal_set_selection(ot_context *, const ot_handle *terminal,
+    uint32_t start_x, uint32_t start_y, uint32_t end_x, uint32_t end_y);
+/* Selected text and encode calls accept zero capacity to query exact byte counts.
+ * Insufficient nonzero capacity preserves output bytes/count and mouse state.
+ * No returned buffer includes a terminating NUL. */
+ot_status ot_embedded_terminal_get_selected_text(ot_context *, const ot_handle *terminal,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+ot_status ot_embedded_terminal_compose(ot_context *, const ot_handle *terminal, const ot_handle *target,
+    const ot_scene_frame_request *frame, int32_t x, int32_t y);
+ot_status ot_embedded_terminal_cursor_get(ot_context *, const ot_handle *terminal, ot_embedded_terminal_cursor *out_cursor);
+ot_status ot_embedded_terminal_scrollbar_get(ot_context *, const ot_handle *terminal, ot_embedded_terminal_scrollbar *out_scrollbar);
+ot_status ot_embedded_terminal_encode_key(ot_context *, const ot_handle *terminal, const ot_embedded_terminal_key *,
+    const uint8_t *key, uint32_t key_count, const uint8_t *text, uint32_t text_count,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+ot_status ot_embedded_terminal_encode_mouse(ot_context *, const ot_handle *terminal, const ot_embedded_terminal_mouse *,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+ot_status ot_embedded_terminal_encode_paste(ot_context *, const ot_handle *terminal,
+    const uint8_t *input, uint32_t input_count, uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+ot_status ot_embedded_terminal_encode_focus(ot_context *, const ot_handle *terminal,
+    uint32_t focused, uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+#define OT_EMBEDDED_TERMINAL_RESPONSE_BYTES_MAX UINT32_C(1048576)
+/* Drains at most capacity bytes, not a sizing query. Response overflow returns
+ * OT_OUTPUT_BACKPRESSURE once without consuming the retained RESPONSE_BYTES_MAX prefix. */
+ot_status ot_embedded_terminal_drain_responses(ot_context *, const ot_handle *terminal,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+
+/* Context-owned editor resources use checked handles, never legacy pointers.
+ * Options require exact size/version and zero reserved. width_method uses
+ * OT_WIDTH_METHOD_*. Creation failures leave output handles unchanged. */
+typedef struct ot_edit_buffer_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t width_method;
+    uint32_t reserved;
+} ot_edit_buffer_options;
+
+/* Initialize size/version and zero remaining fields. Other fields are copied output.
+ * Cursor row is a zero-based document line; col and offset count display columns,
+ * not UTF-8 bytes or code points. can_undo and can_redo are 0 or 1.
+ * tab_width is the even display-cell width in [2, 254].
+ * content_epoch is an invalidation token, not a count of user edits. */
+typedef struct ot_edit_buffer_info {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint64_t content_epoch;
+    uint32_t byte_count;
+    uint32_t line_count;
+    uint32_t cursor_row;
+    uint32_t cursor_col;
+    uint32_t cursor_offset;
+    uint32_t can_undo;
+    uint32_t can_redo;
+    uint32_t tab_width;
+} ot_edit_buffer_info;
+
+#define OT_EDIT_CURSOR_CHANGED UINT32_C(1)
+#define OT_EDIT_CONTENT_CHANGED UINT32_C(2)
+#define OT_EDIT_HISTORY_CURSOR_CHANGED UINT32_C(4)
+
+/* Mouse pointer shapes, named after CSS cursor values. */
+#define OT_MOUSE_POINTER_AUTO UINT32_C(0)
+#define OT_MOUSE_POINTER_DEFAULT UINT32_C(1)
+#define OT_MOUSE_POINTER_NONE UINT32_C(2)
+#define OT_MOUSE_POINTER_CONTEXT_MENU UINT32_C(3)
+#define OT_MOUSE_POINTER_HELP UINT32_C(4)
+#define OT_MOUSE_POINTER_POINTER UINT32_C(5)
+#define OT_MOUSE_POINTER_PROGRESS UINT32_C(6)
+#define OT_MOUSE_POINTER_WAIT UINT32_C(7)
+#define OT_MOUSE_POINTER_CELL UINT32_C(8)
+#define OT_MOUSE_POINTER_CROSSHAIR UINT32_C(9)
+#define OT_MOUSE_POINTER_TEXT UINT32_C(10)
+#define OT_MOUSE_POINTER_VERTICAL_TEXT UINT32_C(11)
+#define OT_MOUSE_POINTER_ALIAS UINT32_C(12)
+#define OT_MOUSE_POINTER_COPY UINT32_C(13)
+#define OT_MOUSE_POINTER_MOVE UINT32_C(14)
+#define OT_MOUSE_POINTER_NO_DROP UINT32_C(15)
+#define OT_MOUSE_POINTER_NOT_ALLOWED UINT32_C(16)
+#define OT_MOUSE_POINTER_GRAB UINT32_C(17)
+#define OT_MOUSE_POINTER_GRABBING UINT32_C(18)
+#define OT_MOUSE_POINTER_ALL_SCROLL UINT32_C(19)
+#define OT_MOUSE_POINTER_COL_RESIZE UINT32_C(20)
+#define OT_MOUSE_POINTER_ROW_RESIZE UINT32_C(21)
+#define OT_MOUSE_POINTER_N_RESIZE UINT32_C(22)
+#define OT_MOUSE_POINTER_E_RESIZE UINT32_C(23)
+#define OT_MOUSE_POINTER_S_RESIZE UINT32_C(24)
+#define OT_MOUSE_POINTER_W_RESIZE UINT32_C(25)
+#define OT_MOUSE_POINTER_NE_RESIZE UINT32_C(26)
+#define OT_MOUSE_POINTER_NW_RESIZE UINT32_C(27)
+#define OT_MOUSE_POINTER_SE_RESIZE UINT32_C(28)
+#define OT_MOUSE_POINTER_SW_RESIZE UINT32_C(29)
+#define OT_MOUSE_POINTER_EW_RESIZE UINT32_C(30)
+#define OT_MOUSE_POINTER_NS_RESIZE UINT32_C(31)
+#define OT_MOUSE_POINTER_NESW_RESIZE UINT32_C(32)
+#define OT_MOUSE_POINTER_NWSE_RESIZE UINT32_C(33)
+#define OT_MOUSE_POINTER_ZOOM_IN UINT32_C(34)
+#define OT_MOUSE_POINTER_ZOOM_OUT UINT32_C(35)
+#define OT_MOUSE_POINTER_MAX OT_MOUSE_POINTER_ZOOM_OUT
+/* Editor options only: leave the current mouse pointer unchanged. */
+#define OT_MOUSE_POINTER_UNCHANGED UINT32_C(0xFFFFFFFF)
+
+/* Complete cursor options, not a patch. Exact size/version and zero reserved.
+ * show_cursor and blinking are 0 or 1. style is an OT_CURSOR_STYLE_* value.
+ * color retains packed intent for capture; cursor output uses its RGB snapshot.
+ * mouse_pointer is an OT_MOUSE_POINTER_* shape or OT_MOUSE_POINTER_UNCHANGED. */
+typedef struct ot_scene_editor_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t show_cursor;
+    uint32_t style;
+    uint32_t blinking;
+    uint32_t reserved;
+    uint16_t color[4];
+    uint32_t mouse_pointer;
+    uint32_t reserved2;
+} ot_scene_editor_options;
+
+ot_status ot_edit_buffer_create(ot_context *, const ot_edit_buffer_options *, ot_handle *out_edit_buffer);
+/* Destroying an edit buffer also destroys its views and unbinds their scene nodes.
+ * Destroying a view alone leaves its edit buffer alive. */
+ot_status ot_edit_buffer_destroy(ot_context *, const ot_handle *edit_buffer);
+/* Initial viewport dimensions are display cells, from zero through INT32_MAX. */
+ot_status ot_editor_view_create(ot_context *, const ot_handle *edit_buffer,
+    uint32_t width, uint32_t height, ot_handle *out_view);
+ot_status ot_editor_view_destroy(ot_context *, const ot_handle *view);
+/* Creates an empty style table. Destroying it clears attached native references. */
+ot_status ot_syntax_style_create(ot_context *, ot_handle *out_style);
+ot_status ot_syntax_style_destroy(ot_context *, const ot_handle *style);
+/* NULL clears the binding. A non-NULL style must belong to this Context. */
+ot_status ot_edit_buffer_set_syntax_style(ot_context *, const ot_handle *edit_buffer, const ot_handle *style);
+/* Copy UTF-8 bytes into owned storage; bytes may be NULL only for zero length.
+ * Editors keep C0, DEL, and C1 controls and show them as notation: ^@..^_ and ^?
+ * in two cells, <80>..<9f> in four. Tab, CR, and LF keep their meaning. Queries
+ * normalize line endings to LF. preserve_history is 0 (clear history) or 1 (create an undo point).
+ * Replacement resets the cursor to the origin; insertion uses the primary cursor.
+ * No input memory remains borrowed after return. */
+ot_status ot_edit_buffer_set_text(ot_context *, const ot_handle *edit_buffer,
+    const uint8_t *bytes, uint32_t byte_count, uint32_t preserve_history);
+ot_status ot_edit_buffer_insert_text(ot_context *, const ot_handle *edit_buffer,
+    const uint8_t *bytes, uint32_t byte_count);
+/* Zero-based document rows and display columns. Deletion orders its endpoints and
+ * excludes the end; equal endpoints do nothing. Cursor setting clamps to the text. */
+ot_status ot_edit_buffer_delete_range(ot_context *, const ot_handle *edit_buffer,
+    uint32_t start_row, uint32_t start_col, uint32_t end_row, uint32_t end_col);
+ot_status ot_edit_buffer_set_cursor(ot_context *, const ot_handle *edit_buffer, uint32_t row, uint32_t col);
+/* Zero capacity reports the exact UTF-8 byte count. Otherwise capacity must fit
+ * all bytes; undersized calls preserve both outputs. No terminating NUL is added.
+ * bytes may be NULL only for zero capacity. Copied outputs borrow no native memory.
+ * These getters and the view getter allow readonly measurement-callback reentry,
+ * but not reentry from an edit notification during a mutation. */
+ot_status ot_edit_buffer_get_text(ot_context *, const ot_handle *edit_buffer,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+ot_status ot_edit_buffer_get_info(ot_context *, const ot_handle *edit_buffer, ot_edit_buffer_info *out_info);
+/* width is a display-cell tab stop. Native code rounds it up to an even value in [2, 254]. */
+ot_status ot_edit_buffer_set_tab_width(ot_context *, const ot_handle *edit_buffer, uint32_t width);
+
+/* Editor transport records require exact size/version. Unknown selectors and
+ * unused nonzero arguments reject. Mutations reject callback reentry and validate
+ * every native measure dependency. Invalidation never reinstalls an unset provider.
+ * All coordinates and offsets count display cells, never UTF-8 bytes. */
+#define OT_EDIT_DELETE_FORWARD UINT32_C(0)
+#define OT_EDIT_BACKSPACE UINT32_C(1)
+#define OT_EDIT_NEW_LINE UINT32_C(2)
+#define OT_EDIT_DELETE_LINE UINT32_C(3)
+#define OT_EDIT_MOVE_LEFT UINT32_C(4)
+#define OT_EDIT_MOVE_RIGHT UINT32_C(5)
+#define OT_EDIT_MOVE_UP UINT32_C(6)
+#define OT_EDIT_MOVE_DOWN UINT32_C(7)
+#define OT_EDIT_GOTO_LINE UINT32_C(8)
+#define OT_EDIT_CURSOR_OFFSET UINT32_C(9)
+#define OT_EDIT_CLEAR UINT32_C(10)
+#define OT_EDIT_CLEAR_HISTORY UINT32_C(11)
+#define OT_EDIT_DEBUG_ROPE UINT32_C(12)
+/* argument is a line/offset for GOTO_LINE/CURSOR_OFFSET, zero otherwise. */
+ot_status ot_edit_buffer_command(ot_context *, const ot_handle *, uint32_t command, uint32_t argument);
+/* redo is 0/1. Capacity must be at least 64, the native cursor-metadata bound,
+ * before history is changed. No history returns zero bytes. */
+ot_status ot_edit_buffer_history(ot_context *, const ot_handle *, uint32_t redo,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+
+#define OT_EDIT_POSITION_CURSOR UINT32_C(0)
+#define OT_EDIT_POSITION_NEXT_WORD UINT32_C(1)
+#define OT_EDIT_POSITION_PREV_WORD UINT32_C(2)
+#define OT_EDIT_POSITION_EOL UINT32_C(3)
+#define OT_EDIT_POSITION_OFFSET UINT32_C(4)
+#define OT_EDIT_POSITION_COORDS UINT32_C(5)
+#define OT_EDIT_POSITION_LINE_START UINT32_C(6)
+#define OT_EDIT_POSITION_END UINT32_C(7)
+#define OT_EDIT_POSITION_PREV_CHAR UINT32_C(8)
+typedef struct ot_edit_position {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t valid;
+    uint32_t row;
+    uint32_t col;
+    uint32_t offset;
+} ot_edit_position;
+/* a is offset, row, or line for OFFSET, COORDS, LINE_START; b is col for COORDS.
+ * Other inputs are zero. Invalid positions return valid=0 and zero coordinates.
+ * END is the text's end, PREV_CHAR where MOVE_LEFT would go; no query moves the cursor. */
+ot_status ot_edit_buffer_get_position(ot_context *, const ot_handle *, uint32_t query,
+    uint32_t a, uint32_t b, ot_edit_position *out_position);
+/* by_coords=0 uses start_col/end_col as offsets and requires zero rows;
+ * by_coords=1 uses all coordinates. Offsets and columns are display cells, not
+ * UTF-8 bytes. Zero capacity returns the exact selected UTF-8 byte count;
+ * nonzero capacity must fit that count. Short copies preserve both outputs.
+ * Grapheme boundaries follow the text range rules below. */
+ot_status ot_edit_buffer_get_range(ot_context *, const ot_handle *, uint32_t by_coords,
+    uint32_t start_row, uint32_t start_col, uint32_t end_row, uint32_t end_col,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+/* Lays UTF-8 bytes out as set_text would, without storing them, and reports the offset at
+ * their end: display cells under the buffer's width method, tab width, and control notation,
+ * plus one per line break (LF, CR, or CRLF). bytes may be NULL only for zero length; the
+ * byte limit and UTF-8 validation of set_text apply. Failures preserve out_width. */
+ot_status ot_edit_buffer_measure_text(ot_context *, const ot_handle *edit_buffer,
+    const uint8_t *bytes, uint32_t byte_count, uint32_t *out_width);
+/* Measures as ot_edit_buffer_measure_text does on an edit buffer with this width method and
+ * tab width, without a buffer. tab_width rounds as in ot_edit_buffer_set_tab_width, so 0
+ * gives the tab width of a new edit buffer; a tab_width over 255 fails. */
+ot_status ot_edit_measure_text(ot_context *, const uint8_t *bytes, uint32_t byte_count,
+    uint32_t width_method, uint32_t tab_width, uint32_t *out_width);
+
+#define OT_EDITOR_STYLE_FOREGROUND UINT32_C(1)
+#define OT_EDITOR_STYLE_BACKGROUND UINT32_C(2)
+#define OT_EDITOR_STYLE_ATTRIBUTES UINT32_C(4)
+/* Syntax styles only, with OT_EDITOR_STYLE_ATTRIBUTES: attributes bits 16..23 say which of bits
+ * 0..7 the style supplies. */
+#define OT_EDITOR_STYLE_ATTRIBUTE_MASK UINT32_C(8)
+typedef struct ot_editor_style {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t flags;
+    uint32_t attributes;
+    uint16_t foreground[4];
+    uint16_t background[4];
+} ot_editor_style;
+/* mask selects fields to update. flags identifies present (non-null) values.
+ * Absent fields are zero; colors retain terminal color intent, attributes bits 0..7.
+ * Reset uses mask=7 and flags=0. */
+ot_status ot_edit_buffer_set_defaults(ot_context *, const ot_handle *, uint32_t mask, const ot_editor_style *);
+/* Names are copied UTF-8; registering an existing name replaces its definition.
+ * Empty names are valid; name may be NULL only when byte_count is zero. Ids are
+ * below OT_STYLE_RUN_FLAG. A group set composes its names in order: each later name
+ * replaces fg, bg, and the attribute bits it supplies. Without
+ * OT_EDITOR_STYLE_ATTRIBUTE_MASK, a style with OT_EDITOR_STYLE_ATTRIBUTES supplies all
+ * eight bits and one without supplies none. Set bits 0..7 outside the supplied bits fail. */
+ot_status ot_syntax_style_register(ot_context *, const ot_handle *, const uint8_t *name,
+    uint32_t byte_count, const ot_editor_style *, uint32_t *out_id);
+/* Unknown names return id=0. Names are borrowed only for the query. */
+ot_status ot_syntax_style_resolve(ot_context *, const ot_handle *, const uint8_t *name,
+    uint32_t byte_count, uint32_t *out_id);
+ot_status ot_syntax_style_get_count(ot_context *, const ot_handle *, uint32_t *out_count);
+
+#define OT_EDIT_HIGHLIGHT_ADD_LINE UINT32_C(0)
+#define OT_EDIT_HIGHLIGHT_ADD_RANGE UINT32_C(1)
+#define OT_EDIT_HIGHLIGHT_REMOVE_REF UINT32_C(2)
+#define OT_EDIT_HIGHLIGHT_CLEAR_LINE UINT32_C(3)
+#define OT_EDIT_HIGHLIGHT_CLEAR_ALL UINT32_C(4)
+/* Highlight style ids with this bit name a text buffer's styled-text styles; styled
+ * text interns them by value in the buffer and never writes the attached SyntaxStyle.
+ * get_highlights reports them; equal styles share one id, unstyled text has id 0. */
+#define OT_STYLE_RUN_FLAG UINT32_C(0x80000000)
+typedef struct ot_edit_highlight {
+    uint32_t start;
+    uint32_t end;
+    uint32_t style_id;
+    uint32_t priority;
+    uint32_t ref;
+} ot_edit_highlight;
+/* highlight is required only for ADD operations. argument is line for ADD_LINE/
+ * CLEAR_LINE, ref for REMOVE_REF, zero otherwise. priority<=255, ref<=65535, and
+ * style_id has no OT_STYLE_RUN_FLAG.
+ * start/end are display columns: within line argument for ADD_LINE; for ADD_RANGE,
+ * document offsets that skip line breaks, unlike cursor, selection, and get_range
+ * offsets, which count one cell per line break. In "ab\ncd", range 3..4 is "d". */
+ot_status ot_edit_buffer_highlight(ot_context *, const ot_handle *, uint32_t operation,
+    uint32_t argument, const ot_edit_highlight *highlight);
+/* Copies the highlights on line in ADD_LINE columns; a range gives one record per line
+ * where it covers a column. Zero capacity reports the count; otherwise all records
+ * must fit, and undersized calls preserve both outputs. */
+ot_status ot_edit_buffer_get_highlights(ot_context *, const ot_handle *, uint32_t line,
+    ot_edit_highlight *highlights, uint32_t capacity, uint32_t *out_count);
+
+/* Interns an ordered list of SyntaxStyle names as a group set. names is a pool of UTF-8
+ * names; name_end_bytes[i] is the exclusive end of name i, and the last end is
+ * name_byte_count. Equal lists give equal ids on this Context, whatever style a buffer binds;
+ * ids are never freed. Paint composes the names against the buffer's bound style, later names
+ * winning, and a missing name falls back to its first dotted component. Names must be
+ * nonempty. More than OT_GROUP_SET_NAME_COUNT_MAX names, a name over
+ * OT_GROUP_SET_NAME_BYTE_COUNT_MAX bytes, or a new set past 4,096 sets or 64 KiB of names fails
+ * with OT_OBJECT_LIMIT. Failures preserve out_group_set. */
+#define OT_GROUP_SET_NAME_COUNT_MAX UINT32_C(16)
+#define OT_GROUP_SET_NAME_BYTE_COUNT_MAX UINT32_C(64)
+ot_status ot_context_group_set(ot_context *, const uint8_t *names, uint32_t name_byte_count,
+    const uint32_t *name_end_bytes, uint32_t name_count, uint32_t *out_group_set);
+
+typedef struct ot_highlight_run {
+    uint32_t start_byte;
+    uint32_t end_byte;
+    uint32_t group_set; /* id from ot_context_group_set */
+} ot_highlight_run;
+/* Replaces layer layer_id of the buffer inside [start_byte, end_byte), start_byte <= end_byte,
+ * with runs, in UTF-8 bytes of the text as get_text returns it (one byte per line break);
+ * runs may be NULL only when run_count is zero. Runs are nonempty,
+ * sorted, non-overlapping, inside the range and inside the text, and start and end on code
+ * point boundaries; so must range edges inside the text. A range end past the text reaches
+ * its end. Runs that cross the range edges keep their outside parts. One transaction: a
+ * rejection leaves the layer unchanged. Runs move with edits: they shift, a run grows when
+ * text is inserted strictly inside it, and deleted bytes clip them. set_text, clear, undo,
+ * redo and the CLEAR_ALL highlight operation empty every layer; REMOVE_REF and CLEAR_LINE
+ * leave layers alone. Layers paint at priority 0: above highlights of priority 0, below
+ * higher priorities; where layers overlap, the higher layer_id wins. A run without a link
+ * whose group set supplies no field (fg, bg or attribute bit) paints as if absent. At most 4 nonempty
+ * layers per buffer: a fifth fails with OT_OBJECT_LIMIT, and a layer left empty is dropped. */
+ot_status ot_edit_buffer_set_layer(ot_context *, const ot_handle *, uint32_t layer_id,
+    uint32_t start_byte, uint32_t end_byte, const ot_highlight_run *runs, uint32_t run_count);
+
+/* A streamed Markdown document (CommonMark 0.31.2 with GFM tables, strikethrough, task lists and
+ * extended autolinks), parsed incrementally. Blocks have preorder indices, which are their ids;
+ * a removal is always a suffix. Complete lines parse exactly; the bytes after the last line
+ * ending are laid out provisionally, held while their kind can still change. Limits: source
+ * 64 MiB, 1,048,576 blocks, 4,096 link definitions, 32 levels of nesting, hook filter 256
+ * bytes, 32 emphasis runs waiting for a closer (past it the oldest is text and never matches).
+ * A rejected call changes nothing: the document, its bound nodes and its pending
+ * changes stay as they were. An accepted call writes its bound nodes after its change; a node
+ * write that runs out of memory leaves that node behind until a later call writes it whole. */
+#define OT_MD_CONCEAL UINT32_C(1)    /* hide markers; off, a leaf shows its source, styled */
+#define OT_MD_HYPERLINKS UINT32_C(2) /* the terminal shows links; off, a label that is not its
+                                        URL is followed by " (url)" */
+#define OT_MD_MATH UINT32_C(4)       /* $…$, \(…\) inline math; $$ and \[ blocks (code, MATH) */
+#define OT_MD_HOOK UINT32_C(8)       /* prose leaves whose source holds a filter substring latch
+                                        HOOKED: the host writes them */
+typedef struct ot_markdown_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t flags;             /* OT_MD_* */
+    uint32_t source_byte_limit; /* 0 = 64 MiB; may only lower it */
+    ot_handle syntax_style;     /* style the bound nodes and read_leaf resolve with; zero = none */
+    uint32_t hook_filter_byte_count; /* <= OT_MD_HOOK_FILTER_BYTE_COUNT_MAX */
+    uint32_t reserved;
+    /* At most 16 NUL-separated substrings, each 1..64 bytes, in the first
+     * hook_filter_byte_count bytes; none with OT_MD_HOOK = every prose leaf is hooked. */
+    uint8_t hook_filter[256];
+} ot_markdown_options;
+#define OT_MD_HOOK_FILTER_BYTE_COUNT_MAX UINT32_C(256)
+typedef struct ot_markdown_result {
+    uint32_t changed_block_count;       /* blocks read_changes lists now */
+    uint32_t committed_top_level_count; /* leading top-level blocks that are final */
+    uint32_t removed_from_index;        /* blocks at this index and after were removed since
+                                           the last read; UINT32_MAX = none */
+} ot_markdown_result;
+/* The doc keeps a copy of the filter. syntax_style must name a live style. */
+ot_status ot_markdown_create(ot_context *, const ot_markdown_options *, ot_handle *out_doc);
+/* Bound nodes keep their last text. */
+ot_status ot_markdown_destroy(ot_context *, const ot_handle *doc);
+/* Conceal, hyperlink, math, hook and limit changes parse the source again: blocks equal to the
+ * old ones keep their indices, bound nodes whose leaf output changed are written again (the
+ * listed ones the host writes), and the blocks after the first difference are removed. A style
+ * change binds the bound nodes to the new style without a rewrite. A finished doc stays
+ * finished. */
+ot_status ot_markdown_set_options(ot_context *, const ot_handle *doc, const ot_markdown_options *,
+    ot_markdown_result *out);
+/* bytes is valid UTF-8 and may be NULL only when byte_count is zero. After finish, an append is
+ * a fresh parse of the whole source and the bytes. */
+ot_status ot_markdown_append(ot_context *, const ot_handle *doc, const uint8_t *bytes,
+    uint32_t byte_count, ot_markdown_result *out);
+/* A fresh parse of bytes; leading blocks equal to the old ones keep their indices unreported. */
+ot_status ot_markdown_set(ot_context *, const ot_handle *doc, const uint8_t *bytes,
+    uint32_t byte_count, ot_markdown_result *out);
+/* Ends the document: the pending line is complete and every block closes. A fence or math
+ * block without its closer stays without OT_MD_BLOCK_CLOSED. */
+ot_status ot_markdown_finish(ot_context *, const ot_handle *doc, ot_markdown_result *out);
+/* The source, borrowed until the next mutating call on doc or its destruction. */
+ot_status ot_markdown_get_source(ot_context *, const ot_handle *doc, const uint8_t **out_bytes,
+    uint32_t *out_byte_count);
+
+#define OT_MD_PARAGRAPH UINT32_C(0)
+#define OT_MD_HEADING UINT32_C(1)
+#define OT_MD_CODE UINT32_C(2)       /* fenced, indented, or display math (OT_MD_BLOCK_MATH) */
+#define OT_MD_HTML UINT32_C(3)       /* shown as its source text */
+#define OT_MD_RULE UINT32_C(4)
+#define OT_MD_TABLE UINT32_C(5)
+#define OT_MD_TABLE_ROW UINT32_C(6)
+#define OT_MD_TABLE_CELL UINT32_C(7) /* a row's source cells only; shorter rows have fewer */
+#define OT_MD_QUOTE UINT32_C(8)
+#define OT_MD_LIST UINT32_C(9)
+#define OT_MD_ITEM UINT32_C(10)
+#define OT_MD_BLOCK_CLOSED UINT32_C(1)       /* a fence's or math block's closer arrived */
+#define OT_MD_BLOCK_SETEXT UINT32_C(2)
+#define OT_MD_BLOCK_ORDERED UINT32_C(4)
+#define OT_MD_BLOCK_TIGHT UINT32_C(8)        /* set when the list closes */
+#define OT_MD_BLOCK_TASK UINT32_C(16)
+#define OT_MD_BLOCK_CHECKED UINT32_C(32)
+#define OT_MD_BLOCK_BLANK_AFTER UINT32_C(64) /* a blank line separates the item from the next */
+#define OT_MD_BLOCK_FENCED UINT32_C(128)
+#define OT_MD_BLOCK_HOOKED UINT32_C(256)
+#define OT_MD_BLOCK_MATH UINT32_C(512)       /* display math: a code block of the language math */
+#define OT_MD_BLOCK_HEADER UINT32_C(1024)    /* a table's header row */
+#define OT_MD_BLOCK_OPEN UINT32_C(2048)      /* later lines may still extend the block */
+typedef struct ot_markdown_block {
+    uint32_t index;           /* preorder index = block id */
+    uint32_t parent_index;    /* UINT32_MAX at top level */
+    uint16_t kind;            /* OT_MD_PARAGRAPH .. OT_MD_ITEM */
+    uint16_t flags;           /* OT_MD_BLOCK_* */
+    uint32_t source_start_byte;
+    uint32_t source_end_byte;
+    uint32_t info_start_byte; /* a fence's info string; empty otherwise */
+    uint32_t info_end_byte;
+    uint32_t number;          /* heading level, list start, table column count, cell column */
+} ot_markdown_block;
+/* Lists every block changed since the last successful read, in document order, and clears the
+ * pending changes and removed_from_index. A zero or short capacity reports the count and
+ * acknowledges nothing. blocks may be NULL only when block_capacity is zero. */
+ot_status ot_markdown_read_changes(ot_context *, const ot_handle *doc, ot_markdown_block *blocks,
+    uint32_t block_capacity, uint32_t *out_block_count);
+#define OT_MD_SPAN_CODE UINT32_C(1)
+#define OT_MD_SPAN_MATH UINT32_C(2)
+/* The parser's output for a leaf (paragraph, heading, code, HTML block or table cell), never a
+ * host's: its display bytes, styled chunks resolved through the doc's style (links point into
+ * urls, as ot_scene_set_styled_text takes them), and, when spans is not NULL, one OT_MD_SPAN_*
+ * word per chunk. All capacities zero report the three counts; otherwise each must hold its
+ * count, and an undersized call writes nothing. A pointer may be NULL only with zero capacity. */
+/* A paragraph's, heading's or table cell's inline source: its content with container markers
+ * and leading whitespace removed, lines joined by '\n', trailing whitespace and leading link
+ * definitions dropped, a cell's escaped pipes unescaped (what an inline hook gets as the
+ * block's source). Zero capacity reports the count; a short one writes nothing. */
+ot_status ot_markdown_read_source(ot_context *, const ot_handle *doc, uint32_t block_index,
+    uint8_t *bytes, uint32_t byte_capacity, uint32_t *out_byte_count);
+ot_status ot_markdown_read_leaf(ot_context *, const ot_handle *doc, uint32_t block_index,
+    uint8_t *bytes, uint32_t byte_capacity, uint32_t *out_byte_count,
+    ot_styled_text_chunk *chunks, uint32_t *spans, uint32_t chunk_capacity, uint32_t *out_chunk_count,
+    uint8_t *urls, uint32_t url_byte_capacity, uint32_t *out_url_byte_count);
+/* Binds a scene text node to a paragraph or heading: the node draws with the doc's style, and
+ * while the leaf is not hooked and the doc conceals and shows hyperlinks, the doc writes the
+ * leaf's display and Markdown runs to it now and on every change. A removal of the block
+ * unbinds it; a destroyed node is skipped. A node the host writes (the doc does not) is never
+ * written by another call: when a call makes the doc write such a leaf, it unbinds the node and
+ * lists the leaf, and binding the node again hands it over. */
+ot_status ot_markdown_bind(ot_context *, const ot_handle *doc, uint32_t block_index,
+    const ot_handle *text_node);
+
+typedef struct ot_editor_viewport {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t x;
+    uint32_t y;
+    uint32_t width;
+    uint32_t height;
+} ot_editor_viewport;
+/* size_only and move_cursor are 0/1. size_only requires zero x/y and move_cursor.
+ * Viewports and their coordinate sums must fit INT32_MAX. */
+ot_status ot_editor_view_set_viewport(ot_context *, const ot_handle *, const ot_editor_viewport *,
+    uint32_t size_only, uint32_t move_cursor);
+/* Cursor changes (edits and moves) do not lay out text; they make a scroll to the cursor
+ * due. The viewport read and the other editor view calls apply a due scroll first, so the
+ * viewport read can lay out text and return OT_OUT_OF_MEMORY, but only while a scroll is due. */
+ot_status ot_editor_view_get_viewport(ot_context *, const ot_handle *, ot_editor_viewport *out_viewport);
+ot_status ot_editor_view_set_scroll_margin(ot_context *, const ot_handle *, float margin);
+#define OT_EDITOR_MOVE_UP UINT32_C(0)
+#define OT_EDITOR_MOVE_DOWN UINT32_C(1)
+#define OT_EDITOR_GOTO_LINE_END UINT32_C(2)
+#define OT_EDITOR_DELETE_SELECTION UINT32_C(3)
+#define OT_EDITOR_CURSOR_OFFSET UINT32_C(4)
+#define OT_EDITOR_WRAP_MODE UINT32_C(5)
+#define OT_EDITOR_TAB_INDICATOR UINT32_C(6)
+/* argument is offset, OT_SCENE_WRAP_*, or Unicode scalar (0 disables) for the
+ * last three commands, and zero otherwise. */
+ot_status ot_editor_view_command(ot_context *, const ot_handle *, uint32_t command, uint32_t argument);
+/* Atomic selected delete-then-insert using native editor history and event order.
+ * Without a selection inserts at the primary cursor. Input bytes are copied. */
+/* out_steps reports committed history steps: 1 = deletion, 2 = insertion. */
+ot_status ot_editor_view_replace_selection(ot_context *, const ot_handle *, const uint8_t *bytes,
+    uint32_t byte_count, uint32_t *out_steps);
+/* NULL clears the tab color. */
+ot_status ot_editor_view_set_tab_color(ot_context *, const ot_handle *, const uint16_t color[4]);
+
+#define OT_EDITOR_SELECT_SET UINT32_C(0)
+#define OT_EDITOR_SELECT_UPDATE UINT32_C(1)
+#define OT_EDITOR_SELECT_RESET UINT32_C(2)
+#define OT_EDITOR_SELECT_LOCAL UINT32_C(3)
+#define OT_EDITOR_SELECT_LOCAL_UPDATE UINT32_C(4)
+#define OT_EDITOR_SELECT_LOCAL_RESET UINT32_C(5)
+#define OT_EDITOR_SELECT_CELL UINT32_C(6)
+#define OT_EDITOR_SELECT_OCCUPANCY UINT32_C(7)
+#define OT_EDITOR_SELECT_INCLUSIVE UINT32_C(8)
+#define OT_EDITOR_SELECT_COLORS UINT32_C(9)
+/* SET/UPDATE use flattened document display-column offsets (start/end), with an
+ * exclusive end and one position per line separator. LOCAL/LOCAL_UPDATE use viewport-local display cells (x) and
+ * virtual rows (y). Scene text selection always uses that local coordinate space.
+ * These aliases name the coordinate space as well as the operation. */
+#define OT_SELECT_DOCUMENT_SET OT_EDITOR_SELECT_SET
+#define OT_SELECT_DOCUMENT_UPDATE OT_EDITOR_SELECT_UPDATE
+#define OT_SELECT_DOCUMENT_RESET OT_EDITOR_SELECT_RESET
+#define OT_SELECT_VIEWPORT_SET OT_EDITOR_SELECT_LOCAL
+#define OT_SELECT_VIEWPORT_UPDATE OT_EDITOR_SELECT_LOCAL_UPDATE
+#define OT_SELECT_VIEWPORT_RESET OT_EDITOR_SELECT_LOCAL_RESET
+#define OT_SELECTION_CELL UINT32_C(0)
+#define OT_SELECTION_WORD UINT32_C(1)
+#define OT_SELECTION_LINE UINT32_C(2)
+#define OT_SELECTION_OCCUPANCY_CELL UINT32_C(0)
+#define OT_SELECTION_OCCUPANCY_BOUNDARY UINT32_C(1)
+typedef struct ot_editor_selection {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t operation;
+    uint32_t behavior;
+    uint32_t start;
+    uint32_t end;
+    int32_t anchor_x;
+    int32_t anchor_y;
+    int32_t focus_x;
+    int32_t focus_y;
+    uint32_t update_cursor;
+    uint32_t follow_cursor;
+    uint32_t flags;
+    uint32_t reserved;
+    uint16_t foreground[4];
+    uint16_t background[4];
+} ot_editor_selection;
+/* flags uses FOREGROUND/BACKGROUND; behavior is OT_SELECTION_CELL/WORD/LINE for local
+ * operations, or OT_SELECTION_OCCUPANCY_* for OCCUPANCY. Unused fields are zero.
+ * out_changed is meaningful for LOCAL/LOCAL_UPDATE/CELL, otherwise zero. */
+ot_status ot_editor_view_select(ot_context *, const ot_handle *, const ot_editor_selection *, uint32_t *out_changed);
+typedef struct ot_editor_view_info {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t virtual_line_count;
+    uint32_t total_virtual_line_count;
+    uint32_t selection_present;
+    uint32_t selection_start;
+    uint32_t selection_end;
+    uint32_t selection_occupancy;
+} ot_editor_view_info;
+/* follow_cursor is 0/1. Zero preserves the viewport during observational queries, apart
+ * from a scroll that an earlier cursor change made due; one retains editor render-preparation
+ * behavior for visible line-count queries. */
+ot_status ot_editor_view_get_info(ot_context *, const ot_handle *, uint32_t follow_cursor, ot_editor_view_info *out_info);
+/* Reads selection without preparing lines or following the cursor. Reuses the
+ * info record with both line counts zero; absent or zero-width selections report
+ * selection_present=0 and zero offsets. */
+ot_status ot_editor_view_get_selection(ot_context *, const ot_handle *, ot_editor_view_info *out_info);
+/* Exact selected UTF-8 byte query/copy, as for ot_scene_get_selected_text.
+ * Does not prepare lines or follow the cursor. */
+ot_status ot_editor_view_get_selected_text(ot_context *, const ot_handle *,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+#define OT_EDITOR_POSITION_CURSOR UINT32_C(0)
+#define OT_EDITOR_POSITION_NEXT_WORD UINT32_C(1)
+#define OT_EDITOR_POSITION_PREV_WORD UINT32_C(2)
+#define OT_EDITOR_POSITION_EOL UINT32_C(3)
+#define OT_EDITOR_POSITION_VISUAL_SOL UINT32_C(4)
+#define OT_EDITOR_POSITION_VISUAL_EOL UINT32_C(5)
+typedef struct ot_editor_position {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t visual_row;
+    uint32_t visual_col;
+    uint32_t logical_row;
+    uint32_t logical_col;
+    uint32_t offset;
+} ot_editor_position;
+ot_status ot_editor_view_get_position(ot_context *, const ot_handle *, uint32_t query, ot_editor_position *out_position);
+typedef struct ot_editor_measure {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t line_count;
+    uint32_t width_cols_max;
+} ot_editor_measure;
+/* Both modes copy wrapped rows. logical=0 first scrolls the viewport to the cursor, as
+ * ot_editor_view_get_info does with follow_cursor=1, then copies the viewport's rows,
+ * numbered from its first visible row; width_cols_max is the widest of them. logical=1
+ * copies every row of the document; width_cols_max is the widest unwrapped line. While
+ * the placeholder shows, both modes copy its rows.
+ * Zero capacity reports the count; otherwise all records must fit. */
+ot_status ot_editor_view_get_lines(ot_context *, const ot_handle *, uint32_t logical,
+    ot_scene_text_line *lines, uint32_t capacity, ot_editor_measure *out_info);
+ot_status ot_editor_view_measure(ot_context *, const ot_handle *, uint32_t width, uint32_t height, ot_editor_measure *out_info);
+/* Copies owned placeholder text and styles; zero chunks clears the placeholder.
+ * Uses the same chunk validation as ot_scene_set_styled_text, but LINK,
+ * link_offset, and link_byte_count must be zero. */
+ot_status ot_editor_view_set_placeholder(ot_context *, const ot_handle *, const uint8_t *bytes,
+    uint32_t byte_count, const ot_styled_text_chunk *chunks, uint32_t chunk_count);
+/* One synchronous owner-thread observer per Context, borrowed until replacement,
+ * NULL clearing, or Context destruction. event is one OT_EDIT_* value, not a mask.
+ * The identity names the edit buffer in this native image. Queue host work before
+ * returning: mutations, callback replacement, drains, and destruction reject
+ * reentry with OT_CONTEXT_BUSY. */
+typedef void (*ot_edit_event_callback)(uint64_t context_id, uint32_t slot, uint32_t generation, uint32_t event);
+ot_status ot_context_set_edit_event_callback(ot_context *, ot_edit_event_callback);
+/* Bind only OT_SCENE_EDITOR nodes. A view binds at most one node at a time.
+ * NULL unbinds. Binding retains no host memory and does not transfer ownership.
+ * Session/node destruction unbinds without destroying the view or edit buffer. */
+ot_status ot_scene_set_editor_view(ot_context *, const ot_handle *node, const ot_handle *view);
+ot_status ot_scene_set_editor_options(ot_context *, const ot_handle *node, const ot_scene_editor_options *);
+
+#define OT_IMAGE_FIT UINT32_C(0)
+#define OT_IMAGE_COVER UINT32_C(1)
+#define OT_IMAGE_FILL UINT32_C(2)
+#define OT_IMAGE_PROTOCOL_AUTO UINT32_C(0)
+#define OT_IMAGE_PROTOCOL_KITTY UINT32_C(1)
+#define OT_IMAGE_PROTOCOL_SIXEL UINT32_C(2)
+#define OT_IMAGE_PROTOCOL_BLOCKS UINT32_C(3)
+#define OT_IMAGE_DRAW_SOURCE_WIDTH UINT32_C(1)
+#define OT_IMAGE_DRAW_SOURCE_HEIGHT UINT32_C(2)
+/* tfm fork: read opacity_override (0..1) instead of the inherited render-tree
+ * opacity. Without the flag the field is ignored, so a zeroed struct inherits. */
+#define OT_IMAGE_DRAW_OPACITY_OVERRIDE UINT32_C(4)
+/* Keep the source's aspect inside the pixel box: the protocol writers
+ * letterbox the image (centered, transparent margins) instead of stretching it
+ * to the box. Without the flag the source is stretched to the box. */
+#define OT_IMAGE_DRAW_PRESERVE_ASPECT UINT32_C(8)
+
+ot_status ot_image_destroy(ot_context *, const ot_handle *image);
+
+#define OT_IMAGE_ENCODED_BYTES_MAX UINT32_C(67108864)
+/* Image resources use Context allocation, I/O and handle capacity. Encoded inputs
+ * are limited to ENCODED_BYTES_MAX; dimensions to 16384 per axis and 25000000 pixels.
+ * Inputs are copied during creation. Failed operations leave outputs unchanged.
+ * Transform/clone/retain return independently releasable handles. Clone copies
+ * pixels and encoded data; retain shares immutable storage within one Context.
+ * Nodes and buffers retain storage after ot_image_destroy releases the public handle.
+ * Only update_pixels mutates an existing image; retained storage returns OT_IMAGE_BUSY.
+ * Successful updates assign fresh render-cache identities. */
+typedef struct ot_image_info {
+    uint32_t width, height, source_width, source_height;
+    uint32_t format, color_status, orientation, has_alpha;
+} ot_image_info;
+#define OT_IMAGE_FORMAT_UNKNOWN UINT32_C(0)
+#define OT_IMAGE_FORMAT_PNG UINT32_C(1)
+#define OT_IMAGE_FORMAT_RGBA UINT32_C(2)
+#define OT_IMAGE_FORMAT_JPEG UINT32_C(3)
+#define OT_IMAGE_FORMAT_WEBP UINT32_C(4)
+#define OT_IMAGE_FORMAT_GIF UINT32_C(5)
+#define OT_IMAGE_ASSUMED_SRGB UINT32_C(0)
+#define OT_IMAGE_EXPLICIT_SRGB UINT32_C(1)
+#define OT_IMAGE_RGBA8 UINT32_C(0)
+#define OT_IMAGE_BGRA8 UINT32_C(1)
+#define OT_IMAGE_ALPHA_STRAIGHT UINT32_C(0)
+#define OT_IMAGE_ALPHA_OPAQUE UINT32_C(1)
+#define OT_IMAGE_FILTER_DEFAULT UINT32_C(0)
+#define OT_IMAGE_FILTER_AREA UINT32_C(1)
+#define OT_IMAGE_FILTER_TRIANGLE UINT32_C(2)
+#define OT_IMAGE_FILTER_CUBIC_BSPLINE UINT32_C(3)
+#define OT_IMAGE_FILTER_CATMULL_ROM UINT32_C(4)
+#define OT_IMAGE_FILTER_MITCHELL UINT32_C(5)
+#define OT_IMAGE_FILTER_NEAREST UINT32_C(6)
+#define OT_IMAGE_ROTATE_90 UINT32_C(0)
+#define OT_IMAGE_ROTATE_180 UINT32_C(1)
+#define OT_IMAGE_ROTATE_270 UINT32_C(2)
+#define OT_IMAGE_FLIP UINT32_C(3)
+#define OT_IMAGE_FLOP UINT32_C(4)
+#define OT_IMAGE_BLEND_SOURCE_OVER UINT32_C(0)
+#define OT_IMAGE_BLEND_SOURCE UINT32_C(1)
+#define OT_IMAGE_BLEND_DESTINATION_OVER UINT32_C(2)
+ot_status ot_image_inspect(ot_context *, const uint8_t *bytes, uint64_t byte_count, ot_image_info *out_info);
+ot_status ot_image_decode(ot_context *, const uint8_t *bytes, uint64_t byte_count, ot_handle *out_image);
+ot_status ot_image_create_pixels(ot_context *, const uint8_t *pixels, uint64_t byte_count,
+    uint32_t width, uint32_t height, uint32_t stride, uint32_t format, uint32_t alpha, ot_handle *out_image);
+ot_status ot_image_update_pixels(ot_context *, const ot_handle *image, const uint8_t *pixels,
+    uint64_t byte_count, uint32_t stride, uint32_t format, uint32_t alpha);
+ot_status ot_image_clone(ot_context *destination, ot_context *source, const ot_handle *image, ot_handle *out_image);
+ot_status ot_image_retain(ot_context *, const ot_handle *image, ot_handle *out_image);
+ot_status ot_image_get_info(ot_context *, const ot_handle *image, ot_image_info *out_info);
+ot_status ot_image_resize(ot_context *, const ot_handle *image, uint32_t width, uint32_t height,
+    uint32_t filter, ot_handle *out_image);
+ot_status ot_image_extract(ot_context *, const ot_handle *image, uint32_t left, uint32_t top,
+    uint32_t width, uint32_t height, ot_handle *out_image);
+ot_status ot_image_extend(ot_context *, const ot_handle *image, uint32_t top, uint32_t right,
+    uint32_t bottom, uint32_t left, const uint8_t *background_rgba, ot_handle *out_image);
+ot_status ot_image_transform(ot_context *, const ot_handle *image, uint32_t operation, ot_handle *out_image);
+ot_status ot_image_composite(ot_context *, const ot_handle *base, const ot_handle *overlay,
+    int32_t left, int32_t top, uint32_t blend, uint8_t opacity, ot_handle *out_image);
+ot_status ot_image_copy_pixels(ot_context *, const ot_handle *image, uint8_t *destination,
+    uint64_t byte_count, uint32_t stride, uint32_t format);
+/* Zero capacity reports the exact PNG byte count and ensures its cached encoding.
+ * A short nonempty destination returns OT_IMAGE_OUTPUT_TOO_SMALL without writing. */
+ot_status ot_image_copy_png(ot_context *, const ot_handle *image, uint8_t *destination,
+    uint64_t capacity, uint64_t *out_byte_count);
+/* Transfer requires exclusive storage. Success consumes image and returns a mutable
+ * pixel lease; the old handle becomes stale. Leases share Context lease count/byte
+ * limits and prevent Context destruction until release. Admission needs one free
+ * handle slot; lease bytes include pixels and their native image header. Pixels
+ * are packed straight sRGB RGBA8. No image operation accepts the lease. All aliases
+ * expire on release. */
+typedef struct ot_image_pixels {
+    ot_handle lease;
+    uint64_t pixels;
+    uint64_t byte_count;
+} ot_image_pixels;
+ot_status ot_image_take_pixels(ot_context *, const ot_handle *image, ot_image_pixels *out_pixels);
+ot_status ot_image_pixels_release(ot_context *, const ot_handle *lease);
+/* Bind only IMAGE nodes. NULL image clears the binding. Nodes and drawn placements
+ * retain their image independently of the imported handle. Optional buffer names
+ * Context-owned backing storage for buffered Image drawing, not a legacy buffer.
+ * fit and protocol use OT_IMAGE_*; mutations reject measurement-callback reentry.
+ * opacity_override is a tfm fork addition: a negative value (including NaN)
+ * inherits the render-tree opacity; 0..1 replaces it for this node's placements
+ * so an image can stay opaque (or scale independently) under a node-opacity dim. */
+ot_status ot_scene_set_image(ot_context *, const ot_handle *node, const ot_handle *image,
+    uint32_t fit, uint32_t protocol, const ot_handle *buffer, float opacity_override);
+/* Sets the region of the source, in source pixels, that an IMAGE or VIDEO node shows; fit
+ * applies to the region. All four zero show the whole source; otherwise width and height
+ * are positive. A region that does not lie inside the source shows the whole source. A VIDEO
+ * node scales and copies only the region of each frame. Setting the image or video keeps it. */
+ot_status ot_scene_set_crop(ot_context *, const ot_handle *node, uint32_t left, uint32_t top,
+    uint32_t width, uint32_t height);
+
+/* A VIDEO node owns one decoder and player. Decoded frames stay native: each paint
+ * of the node draws the current frame as the IMAGE node does, from a small set of
+ * images that the decoder refreshes in place while no buffer retains them. Audio
+ * plays from a native thread; paints and ot_video_get_state advance the clock and
+ * end or loop playback, so an unpainted node keeps time. Hosts keep frames painting
+ * while playback runs, for example with a live renderable. ot_scene_set_video sets fit and buffer as ot_scene_set_image does;
+ * frames draw with OT_IMAGE_PROTOCOL_AUTO.
+ * ot_video_open replaces the player; a zero path_length closes it, and path may then
+ * be NULL. Audio plays through a private audio engine and is the media clock while it
+ * plays. A decode worker thread starts when the node first needs a frame; an audio
+ * thread starts on the first play of a source with audio and makes every audio engine
+ * call. Failed opens, seeks, and decodes return OT_VIDEO_FAILED; ot_video_get_error
+ * copies the detail. After a failure, ot_video_play and ot_video_seek retry; other
+ * controls still apply and succeed. A paused seek decodes its frame once the node has
+ * painted, so decode failures return from the seek. Audio failures leave playback running silently on the wall clock. Control and
+ * state calls on a node without an open player return OT_INVALID_PHASE.
+ * With OT_VIDEO_OPEN_NO_AUDIO, the only accepted flag, ot_video_open creates no audio engine: playback opens no
+ * audio device and follows the wall clock, and has_audio still reports the file's audio track.
+ * In ot_video_info, zero duration_us or fps_num means unknown. */
+#define OT_VIDEO_OPEN_NO_AUDIO UINT32_C(1)
+typedef struct ot_video_info {
+    int64_t duration_us;
+    uint32_t width, height, fps_num, fps_den, has_audio, reserved;
+} ot_video_info;
+/* BUFFERING: playing, and the audio clock waits for queued audio. AUDIO: playing, and
+ * audio output drives the media clock. Without either, playback follows the wall clock. */
+#define OT_VIDEO_PLAYING UINT32_C(1)
+#define OT_VIDEO_ENDED UINT32_C(2)
+#define OT_VIDEO_BUFFERING UINT32_C(4)
+#define OT_VIDEO_AUDIO UINT32_C(8)
+#define OT_VIDEO_HAS_FRAME UINT32_C(16)
+#define OT_VIDEO_ERROR UINT32_C(32)
+typedef struct ot_video_state {
+    int64_t current_time_us;
+    int64_t frame_pts_us;
+    /* quality_tier: 0 is full decode size; each higher tier decodes Kitty output smaller to keep up. */
+    uint32_t flags, quality_tier;
+} ot_video_state;
+ot_status ot_scene_set_video(ot_context *, const ot_handle *node, uint32_t fit, const ot_handle *buffer);
+ot_status ot_video_open(ot_context *, const ot_handle *node, const uint8_t *path, uint32_t path_length,
+    uint32_t flags, ot_video_info *out_info);
+ot_status ot_video_play(ot_context *, const ot_handle *node);
+ot_status ot_video_pause(ot_context *, const ot_handle *node);
+ot_status ot_video_seek(ot_context *, const ot_handle *node, int64_t time_us);
+ot_status ot_video_set_loop(ot_context *, const ot_handle *node, uint32_t loop);
+ot_status ot_video_set_muted(ot_context *, const ot_handle *node, uint32_t muted);
+ot_status ot_video_set_volume(ot_context *, const ot_handle *node, float volume);
+/* Positive offsets show frames earlier relative to the media clock. Offsets beyond
+ * +-60 s return OT_INVALID_ARGUMENT. */
+ot_status ot_video_set_av_sync_offset(ot_context *, const ot_handle *node, int64_t offset_us);
+/* Frames present at the lower of fps and the source frame rate. fps is 1 to 120; default 30. */
+ot_status ot_video_set_max_fps(ot_context *, const ot_handle *node, uint32_t fps);
+ot_status ot_video_get_state(ot_context *, const ot_handle *node, ot_video_state *out_state);
+/* Copies the detail of the last failure, empty without one. Zero capacity reports the
+ * exact byte count; otherwise insufficient capacity rejects without writing bytes or
+ * out_count. bytes may be NULL only for zero capacity. No terminating NUL is added. */
+ot_status ot_video_get_error(ot_context *, const ot_handle *node, uint8_t *bytes, uint32_t capacity,
+    uint32_t *out_count);
+
+/* An audio engine decodes sounds into Context memory and mixes up to 32 voices at
+ * 48 kHz. ot_audio_create opens no device. ot_audio_start opens the default playback
+ * device, whose thread then mixes; that thread never calls the host, and writes silence
+ * while another call holds the engine. With OT_AUDIO_START_NO_DEVICE, the only accepted
+ * flag, the engine mixes only when ot_audio_mix asks, and nothing opens a device; while
+ * a device plays, it returns OT_INVALID_PHASE, so stop first to change modes.
+ * ot_audio_stop silences the engine and releases its device; ot_audio_start resumes.
+ * ot_audio_destroy and Context destruction stop the device, then free every sound.
+ * ot_audio_load copies and decodes WAV, MP3 or FLAC bytes. Sound IDs are nonzero and
+ * stay valid until the engine is destroyed. Voice IDs are nonzero; a voice ends when
+ * its sound ends or is stopped, and its ID never names a later voice. An ID that names
+ * no sound or playing voice, including 0, returns OT_STALE_HANDLE.
+ * volume is a gain from 0 to 4, 1 unchanged; others return OT_INVALID_ARGUMENT.
+ * More than 32 playing voices return OT_OBJECT_LIMIT. */
+#define OT_AUDIO_START_NO_DEVICE UINT32_C(1)
+ot_status ot_audio_create(ot_context *, ot_handle *out_engine);
+ot_status ot_audio_destroy(ot_context *, const ot_handle *engine);
+ot_status ot_audio_start(ot_context *, const ot_handle *engine, uint32_t flags);
+ot_status ot_audio_stop(ot_context *, const ot_handle *engine);
+ot_status ot_audio_load(ot_context *, const ot_handle *engine, const uint8_t *bytes, uint64_t byte_count,
+    uint32_t *out_sound);
+ot_status ot_audio_play(ot_context *, const ot_handle *engine, uint32_t sound, float volume, uint32_t *out_voice);
+ot_status ot_audio_stop_voice(ot_context *, const ot_handle *engine, uint32_t voice);
+ot_status ot_audio_set_volume(ot_context *, const ot_handle *engine, float volume);
+/* Writes frame_count frames of channels (1 or 2) interleaved samples: the mix after
+ * OT_AUDIO_START_NO_DEVICE, silence while stopped. Returns OT_INVALID_PHASE while a
+ * device plays. */
+ot_status ot_audio_mix(ot_context *, const ot_handle *engine, float *samples, uint32_t frame_count,
+    uint32_t channels);
+
+/* x/y and width/height count terminal cells. pixel_* and source_* count image
+ * pixels. Absent source extents and reserved fields must be zero. Exact size and
+ * version are required. Only the two SOURCE_* flags plus
+ * OT_IMAGE_DRAW_OPACITY_OVERRIDE and OT_IMAGE_DRAW_PRESERVE_ASPECT (tfm fork)
+ * are accepted. opacity_override is read only with that flag and must be 0..1
+ * (absent source extents inherit). */
+typedef struct ot_image_draw_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t flags;
+    uint32_t protocol;
+    int32_t x;
+    int32_t y;
+    uint32_t width;
+    uint32_t height;
+    uint32_t pixel_width;
+    uint32_t pixel_height;
+    uint32_t source_x;
+    uint32_t source_y;
+    uint32_t source_width;
+    uint32_t source_height;
+    float opacity_override;
+    uint32_t reserved[1];
+} ot_image_draw_options;
+
+/* Offscreen buffers require NULL frame; Session drawing requires its current
+ * frame ticket. out_drawn is 0 for empty/clipped draws and 1 for accepted drawing.
+ * Invalid options preserve both target cells and out_drawn. */
+ot_status ot_buffer_draw_image(ot_context *, const ot_handle *target, const ot_scene_frame_request *frame,
+    const ot_handle *image, const ot_image_draw_options *, uint32_t *out_drawn);
+/* Store terminal cell and pixel dimensions for native Image fit calculations.
+ * All four values are positive, or all zero to clear the resolution. */
+ot_status ot_session_set_image_resolution(ot_context *, const ot_handle *session,
+    uint32_t terminal_width, uint32_t terminal_height, uint32_t pixel_width, uint32_t pixel_height);
+
+/* Kitty image transport is renderer state, not a terminal control packet.
+ * requested is 0=raw, 1=zlib, 2=file. effective is 0=raw, 1=zlib, 2=png, 3=file.
+ * file_state is 0=disabled, 1=probing, 2=ready, 3=unsupported, 4=timeout,
+ * 5=io-error, 6=cancelled. fallback is 0=none, 1=not-ready, 2=unavailable,
+ * 3=budget, 4=busy, 5=preparation, 6=compression. pending_bytes fits u32.
+ * Set, poll, cancel, and reply require an attached renderer and may run in any
+ * open phase so resume can consume probe replies before JS restores control.
+ * File probes emit only while the terminal is active and not suspended. A probe
+ * that ordinary output cannot admit is not started: file_state stays disabled
+ * until a later set or start call after output drains. */
+typedef struct ot_session_kitty_image_transport {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t requested;
+    uint32_t effective;
+    uint32_t file_state;
+    uint32_t fallback;
+    uint32_t pending_files;
+    uint32_t pending_bytes;
+} ot_session_kitty_image_transport;
+
+ot_status ot_session_set_kitty_image_transport(ot_context *, const ot_handle *session, uint32_t mode);
+ot_status ot_session_get_kitty_image_transport(
+    ot_context *,
+    const ot_handle *session,
+    ot_session_kitty_image_transport *out_status);
+/* now_ns shares the Session pump clock. Earlier samples return OT_INVALID_ARGUMENT
+ * before changing leases or consuming retry notifications. Equal samples are valid.
+ * Each pump or poll visits at most eight files, even while output is pending.
+ * The first observation after creation arms a five-second lease deadline,
+ * saturating at UINT64_MAX. Expiry cancels file transport; it is not an ACK.
+ * Poll regularly while files may be pending, including after changing modes.
+ * Poll does not advance terminal lifecycle or deliver output. */
+ot_status ot_session_poll_kitty_image_transport(ot_context *, const ot_handle *session,
+    uint64_t now_ns, uint32_t *out_retry);
+ot_status ot_session_cancel_kitty_image_transport(ot_context *, const ot_handle *session, uint32_t failed);
+/* out_result is 0=ignored, 1=consumed, 2=consumed and images should retransmit. */
+ot_status ot_session_process_kitty_image_reply(
+    ot_context *,
+    const ot_handle *session,
+    const uint8_t *bytes,
+    uint32_t byte_count,
+    uint32_t *out_result);
+ot_status ot_session_start_kitty_file_probe(ot_context *, const ot_handle *session);
+
+/* Shared text buffers own copied bytes, styles and links. Destroying a buffer
+ * destroys its dependent views; destroying a node only unbinds its view.
+ * Existing editor style, highlight, viewport, selection and measurement records
+ * retain their ABI1 layouts. Text selection rejects cursor-only flags. */
+typedef struct ot_text_buffer_info {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint64_t content_epoch;
+    uint32_t byte_count;
+    uint32_t text_length; /* Sum of unwrapped display-column widths, excluding line separators. */
+    uint32_t line_count;
+    uint32_t highlight_count;
+    uint32_t tab_width;
+    uint32_t reserved;
+} ot_text_buffer_info;
+
+#define OT_TEXT_VIEW_WRAP_WIDTH UINT32_C(0)
+#define OT_TEXT_VIEW_WRAP_MODE UINT32_C(1)
+#define OT_TEXT_VIEW_FIRST_LINE_OFFSET UINT32_C(2)
+#define OT_TEXT_VIEW_TAB_INDICATOR UINT32_C(3)
+#define OT_TEXT_VIEW_TRUNCATE UINT32_C(4)
+#define OT_TEXT_VIEW_TEXT_ALIGN UINT32_C(5)
+
+ot_status ot_text_buffer_create(ot_context *, const ot_edit_buffer_options *, ot_handle *out_buffer);
+ot_status ot_text_buffer_destroy(ot_context *, const ot_handle *);
+ot_status ot_text_buffer_view_create(ot_context *, const ot_handle *buffer, ot_handle *out_view);
+ot_status ot_text_buffer_view_destroy(ot_context *, const ot_handle *);
+ot_status ot_text_buffer_set_text(ot_context *, const ot_handle *, const uint8_t *, uint32_t byte_count);
+ot_status ot_text_buffer_append(ot_context *, const ot_handle *, const uint8_t *, uint32_t byte_count);
+ot_status ot_text_buffer_clear(ot_context *, const ot_handle *, uint32_t reset);
+/* Empty chunks register no style or link. Unlike direct scene text, chunk_count can
+ * exceed byte_count. clear without reset keeps styled highlights but drops their links. */
+ot_status ot_text_buffer_set_styled_text(ot_context *, const ot_handle *, const uint8_t *, uint32_t byte_count,
+    const ot_styled_text_chunk *, uint32_t chunk_count, const uint8_t *urls, uint32_t url_byte_count);
+/* Atomic replacement of buffer-owned styled text. Every buffer appears once and
+ * view must be its dependent view.
+ * Success resets selection on each named view, retaining defaults and geometry.
+ * Failure leaves every buffer, view and output unchanged. Inputs are borrowed
+ * only for the call. Output has count entries; NULL spans require zero count.
+ * These aggregate limits bound synchronous preparation and temporary storage. */
+#define OT_TEXT_REPLACEMENT_COUNT_MAX UINT32_C(256)
+#define OT_TEXT_REPLACEMENT_CHUNKS_MAX UINT32_C(4096)
+#define OT_TEXT_REPLACEMENT_BYTES_MAX UINT32_C(4194304)
+#define OT_TEXT_REPLACEMENT_URL_BYTES_MAX UINT32_C(1048576)
+typedef struct ot_text_buffer_replacement {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    ot_handle buffer;
+    ot_handle view;
+    uint32_t byte_offset;
+    uint32_t byte_count;
+    uint32_t chunk_offset;
+    uint32_t chunk_count;
+} ot_text_buffer_replacement;
+typedef struct ot_text_buffer_replacement_info {
+    uint32_t text_length; /* Sum of unwrapped display-column widths, as in ot_text_buffer_info. */
+    uint32_t byte_count;
+} ot_text_buffer_replacement_info;
+ot_status ot_text_buffer_replace_styled_batch(ot_context *, const ot_text_buffer_replacement *, uint32_t count,
+    const uint8_t *bytes, uint32_t byte_count, const ot_styled_text_chunk *, uint32_t chunk_count,
+    const uint8_t *urls, uint32_t url_byte_count, ot_text_buffer_replacement_info *out);
+ot_status ot_text_buffer_set_syntax_style(ot_context *, const ot_handle *, const ot_handle *style);
+ot_status ot_text_buffer_get_info(ot_context *, const ot_handle *, ot_text_buffer_info *);
+/* Zero capacity reports the exact UTF-8 byte count. Nonzero capacity must fit
+ * that count; no terminating NUL is copied. Outputs are unchanged on rejection. */
+ot_status ot_text_buffer_get_text(ot_context *, const ot_handle *, uint8_t *, uint32_t capacity, uint32_t *out_count);
+/* Same exact byte query/copy convention. start/end are display-column offsets,
+ * including one cell per LF. start snaps backward to the containing grapheme;
+ * exclusive end snaps forward to include a partially selected grapheme. Empty, reversed, and
+ * out-of-document ranges return zero. End is clamped to the document length. */
+ot_status ot_text_buffer_get_range(ot_context *, const ot_handle *, uint32_t start, uint32_t end,
+    uint8_t *, uint32_t capacity, uint32_t *out_count);
+ot_status ot_text_buffer_set_defaults(ot_context *, const ot_handle *, uint32_t mask, const ot_editor_style *);
+ot_status ot_text_buffer_set_tab_width(ot_context *, const ot_handle *, uint32_t width);
+/* Same operations, units, and copy rules as ot_edit_buffer_highlight and
+ * ot_edit_buffer_get_highlights. Styled text is stored as highlights with ref 0 and
+ * priority 1: get_highlights returns them, and REMOVE_REF 0 and CLEAR_* remove them. */
+ot_status ot_text_buffer_highlight(ot_context *, const ot_handle *, uint32_t operation,
+    uint32_t argument, const ot_edit_highlight *);
+ot_status ot_text_buffer_get_highlights(ot_context *, const ot_handle *, uint32_t line,
+    ot_edit_highlight *, uint32_t capacity, uint32_t *out_count);
+ot_status ot_text_buffer_view_set_viewport(ot_context *, const ot_handle *, const ot_editor_viewport *, uint32_t size_only);
+ot_status ot_text_buffer_view_command(ot_context *, const ot_handle *, uint32_t command, uint32_t argument);
+ot_status ot_text_buffer_view_set_tab_color(ot_context *, const ot_handle *, const uint16_t color[4]);
+ot_status ot_text_buffer_view_select(ot_context *, const ot_handle *, const ot_editor_selection *, uint32_t *out_changed);
+ot_status ot_text_buffer_view_get_info(ot_context *, const ot_handle *, ot_editor_view_info *);
+/* Exact selected UTF-8 byte query/copy, as for ot_scene_get_selected_text.
+ * Does not prepare lines or change the viewport. */
+ot_status ot_text_buffer_view_get_selected_text(ot_context *, const ot_handle *, uint8_t *, uint32_t capacity, uint32_t *out_count);
+/* Rows and width_cols_max as for ot_editor_view_get_lines, but a text view has no
+ * cursor to follow or placeholder, and until a viewport is set, logical=0 matches
+ * logical=1. Copies rows [first_line, first_line + capacity) clipped to the row count,
+ * which out reports. A caller receives min(capacity, line_count - first_line) rows,
+ * or none when first_line >= line_count; zero capacity only reports the count. */
+ot_status ot_text_buffer_view_get_lines(ot_context *, const ot_handle *, uint32_t logical, uint32_t first_line,
+    ot_scene_text_line *, uint32_t capacity, ot_editor_measure *);
+ot_status ot_text_buffer_view_measure(ot_context *, const ot_handle *, uint32_t width, uint32_t height, ot_editor_measure *);
+ot_status ot_scene_set_text_view(ot_context *, const ot_handle *node, const ot_handle *view);
+/* Only gates built-in painting, not layout, viewport preparation or hit membership. */
+ot_status ot_scene_set_text_view_paint(ot_context *, const ot_handle *node, uint32_t enabled);
+/* NULL frame selects an owned offscreen buffer. A frame requires the exact active
+ * custom paint destination. The source view must belong to this Context. */
+ot_status ot_buffer_draw_text_view(ot_context *, const ot_handle *target, const ot_scene_frame_request *,
+    const ot_handle *view, int32_t x, int32_t y);
+/* Same destination rules as ot_buffer_draw_text_view. Paints synchronously with
+ * the destination's current clipping and opacity, without publishing cursor state.
+ * The scene-body source is a Text, Box, Slider or Arrow scene node, drawn as its
+ * built-in painting would draw it at x, y with the node's paint size and the
+ * current focus. */
+ot_status ot_buffer_draw_editor_view(ot_context *, const ot_handle *target, const ot_scene_frame_request *,
+    const ot_handle *view, int32_t x, int32_t y);
+ot_status ot_buffer_draw_scene_body(ot_context *, const ot_handle *target, const ot_scene_frame_request *,
+    const ot_handle *node, int32_t x, int32_t y);
+
+#define OT_BUFFER_TEXT_BYTES_MAX UINT32_C(65536)
+
+#define OT_BUFFER_DRAW_CLEAR UINT32_C(0)
+#define OT_BUFFER_DRAW_FILL UINT32_C(1)
+#define OT_BUFFER_DRAW_TEXT UINT32_C(2)
+#define OT_BUFFER_DRAW_CELL UINT32_C(3)
+#define OT_BUFFER_DRAW_CELL_BLEND UINT32_C(4)
+#define OT_BUFFER_DRAW_CHAR UINT32_C(5)
+#define OT_BUFFER_DRAW_BOX UINT32_C(6)
+#define OT_BUFFER_DRAW_COMPOSE UINT32_C(7)
+#define OT_BUFFER_DRAW_RESPECT_ALPHA UINT32_C(8)
+#define OT_BUFFER_DRAW_HAS_BACKGROUND UINT32_C(1)
+#define OT_BUFFER_DRAW_HAS_SOURCE_WIDTH UINT32_C(2)
+#define OT_BUFFER_DRAW_HAS_SOURCE_HEIGHT UINT32_C(4)
+#define OT_BUFFER_DRAW_FIT_ELLIPSIS UINT32_C(16)
+
+#define OT_BUFFER_STACK_DEPTH_MAX UINT32_C(256)
+#define OT_BUFFER_STACK_GET_OPACITY UINT32_C(0)
+#define OT_BUFFER_STACK_PUSH_SCISSOR UINT32_C(1)
+#define OT_BUFFER_STACK_POP_SCISSOR UINT32_C(2)
+#define OT_BUFFER_STACK_CLEAR_SCISSORS UINT32_C(3)
+#define OT_BUFFER_STACK_PUSH_OPACITY UINT32_C(4)
+#define OT_BUFFER_STACK_POP_OPACITY UINT32_C(5)
+#define OT_BUFFER_STACK_CLEAR_OPACITY UINT32_C(6)
+
+/* Pass the header of the record matching operation to ot_buffer_draw.
+ * struct_size is sizeof(the complete record), not sizeof(this header).
+ * CLEAR/FILL/TEXT/BOX/COMPOSE use their named records below; CELL, CELL_BLEND,
+ * and CHAR share ot_buffer_draw_cell; RESPECT_ALPHA uses ot_buffer_draw_alpha.
+ * flags is zero except for TEXT (HAS_BACKGROUND, FIT_ELLIPSIS) and COMPOSE
+ * (HAS_SOURCE_WIDTH and HAS_SOURCE_HEIGHT). Without HAS_BACKGROUND, text
+ * uses the background at each glyph or tab start. A nonzero TEXT max_width
+ * stops the text before the first glyph that would end more than max_width
+ * cells right of x; a tab clips cell by cell. FIT_ELLIPSIS needs max_width
+ * and applies only to text wider than max_width: it keeps the glyphs that
+ * leave room for U+2026 and draws U+2026 right after them. A TEXT record of
+ * offsetof(ot_buffer_draw_text_record, max_width) bytes has no limit.
+ * Omitted source extents use the remaining source dimensions; an explicit
+ * zero extent draws nothing.
+ * Positions are signed cells. FILL and TEXT draw only their cells inside the
+ * target; TEXT skips a wide glyph that starts left of column 0. CELL, CELL_BLEND,
+ * and CHAR at a position outside the target draw nothing.
+ * All records and byte spans are borrowed only for the call. */
+typedef struct ot_buffer_draw_header {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t operation;
+    uint32_t flags;
+} ot_buffer_draw_header;
+
+typedef struct ot_buffer_draw_clear {
+    ot_buffer_draw_header header;
+    uint16_t background[4];
+} ot_buffer_draw_clear;
+
+typedef struct ot_buffer_draw_fill {
+    ot_buffer_draw_header header;
+    int32_t x;
+    int32_t y;
+    uint32_t width;
+    uint32_t height;
+    uint16_t background[4];
+} ot_buffer_draw_fill;
+
+typedef struct ot_buffer_draw_text_record {
+    ot_buffer_draw_header header;
+    int32_t x;
+    int32_t y;
+    uint32_t attributes;
+    uint16_t foreground[4];
+    uint16_t background[4];
+    uint32_t max_width;
+} ot_buffer_draw_text_record;
+
+typedef struct ot_buffer_draw_cell {
+    ot_buffer_draw_header header;
+    int32_t x;
+    int32_t y;
+    uint32_t character;
+    uint32_t attributes;
+    uint16_t foreground[4];
+    uint16_t background[4];
+} ot_buffer_draw_cell;
+
+typedef struct ot_buffer_draw_box {
+    ot_buffer_draw_header header;
+    int32_t x;
+    int32_t y;
+    uint32_t width;
+    uint32_t height;
+    uint32_t packed_options;
+    uint16_t foreground[4];
+    uint16_t background[4];
+    uint16_t title_color[4];
+    uint32_t border_chars[11];
+} ot_buffer_draw_box;
+
+typedef struct ot_buffer_draw_compose {
+    ot_buffer_draw_header header;
+    int32_t x;
+    int32_t y;
+    uint32_t source_x;
+    uint32_t source_y;
+    uint32_t source_width;
+    uint32_t source_height;
+} ot_buffer_draw_compose;
+
+typedef struct ot_buffer_draw_alpha {
+    ot_buffer_draw_header header;
+    /* Zero or one. Valid only for an owned-buffer target. */
+    uint32_t enabled;
+} ot_buffer_draw_alpha;
+
+#define OT_BUFFER_GRID_INNER UINT32_C(1)
+#define OT_BUFFER_GRID_OUTER UINT32_C(2)
+
+typedef struct ot_buffer_grid_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t flags;
+    uint32_t reserved;
+    uint16_t foreground[4];
+    uint16_t background[4];
+    uint32_t border_chars[11];
+} ot_buffer_grid_options;
+
+/* Initialize struct_size, abi_version, and zero reserved before acquisition.
+ * All other fields are output-only. The record has an exact 80-byte layout on
+ * supported 64-bit targets. Addresses are native-endian uint64_t values; convert
+ * through uintptr_t, for example (uint32_t *)(uintptr_t)record.char_ptr.
+ * char_ptr and attributes_ptr each address width * height uint32_t elements.
+ * fg_ptr and bg_ptr each address width * height * 4 uint16_t RGBA components.
+ * Literal RGBA channels use 0..255; high bytes carry native color metadata.
+ * This retains storage, not a frozen frame. Rendering can change cells without
+ * changing generation. CURRENT is the encoder's comparison buffer, which can
+ * change before output admission or presentation; it is not a last-presented
+ * snapshot. NEXT is drawing storage and rendering clears it after encoding.
+ * Raw planes must not add, replace, or remove pooled grapheme/link IDs. Use
+ * ot_buffer_draw TEXT for checked plain UTF-8 on an owned offscreen buffer.
+ * Styled-text/editor resources, hyperlinks, and images need separate checked APIs. */
+typedef struct ot_buffer_lease_snapshot {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    ot_handle lease;
+    uint32_t width;
+    uint32_t height;
+    uint64_t generation;
+    uint64_t char_ptr;
+    uint64_t fg_ptr;
+    uint64_t bg_ptr;
+    uint64_t attributes_ptr;
+    uint64_t reserved;
+} ot_buffer_lease_snapshot;
+
+/* Bits 31..30 of a char plane element (KIND_MASK) select its kind: 00 is a
+ * Unicode scalar; IMAGE, GRAPHEME (a pooled grapheme's first cell) and
+ * CONTINUATION (a later cell of a wide glyph) carry native payloads. */
+#define OT_CELL_CHAR_KIND_MASK UINT32_C(0xC0000000)
+#define OT_CELL_CHAR_IMAGE UINT32_C(0x40000000)
+#define OT_CELL_CHAR_GRAPHEME UINT32_C(0x80000000)
+#define OT_CELL_CHAR_CONTINUATION UINT32_C(0xC0000000)
+
+/* Acquire local frame access for the exact retained DONE record. which is
+ * OT_SESSION_BUFFER_CURRENT or NEXT. Both require this qualified operation while
+ * a draft is live; ordinary Session draw, render, and borrowing cannot bypass it.
+ * The frame and snapshot require exact size/version and zero reserved fields.
+ * Rejection leaves out_snapshot unchanged and acquires no lease. Native code
+ * validates frame membership, destination, and storage identity; copied or forged
+ * record fields do not replace that validation. Existing lease limits, raw-plane
+ * restrictions, validation, capture, and release operations apply.
+ * Release all qualified scopes before commit or a new frame, including stale ones.
+ * An accepted size-changing resize replaces and requalifies draft storage natively
+ * without repainting. Old scopes return OT_STALE_LEASE; later acquisitions use the
+ * new size with the same request record. Setup before the first accepted frame and
+ * suspend retain existing scopes, but new acquisitions and commit return
+ * OT_INVALID_PHASE outside a rendering phase. */
+ot_status ot_scene_frame_acquire_buffer_lease(ot_context *, const ot_handle *session,
+    const ot_scene_frame_request *frame_request, uint32_t which, ot_buffer_lease_snapshot *out_snapshot);
+
+/* Submit the exact retained DONE record through ordered Session output. force is
+ * 0 or 1; out_status uses OT_RENDER_* and the existing Session output admission
+ * and publication rules. Only output completion publishes frame_count and pending
+ * hits. No qualified scope may remain, or commit returns OT_FRAME_BUSY. The frame
+ * requires exact size/version and zero reserved fields. Rejection leaves out_status
+ * unchanged and preserves a live draft for retry after the admission error is
+ * resolved. OT_OK consumes the draft for EVERY out_status:
+ * PRESENTED: output accepted and presentation complete, including no-byte frames.
+ * PENDING: this draft accepted; output completion is still pending.
+ * SKIPPED: output pressure; paint a new draft after queued output drains.
+ * FAILED: the frame is larger than the empty output queue, or encoding or
+ * allocation failed; no output was accepted.
+ * In particular, OT_OK with OT_RENDER_FAILED is not an ot_status error.
+ * A consumed, cancelled, foreign, or altered frame cannot submit again. */
+ot_status ot_scene_frame_commit(ot_context *, const ot_handle *session,
+    const ot_scene_frame_request *frame_request, uint32_t force, uint32_t *out_status);
+
+#define OT_SESSION_CONTROL_PACKET_BYTES UINT32_C(4096)
+#define OT_TERMINAL_ALTERNATE_SCREEN UINT32_C(1)
+#define OT_TERMINAL_MOUSE UINT32_C(2)
+#define OT_TERMINAL_MOUSE_MOVEMENT UINT32_C(4)
+#define OT_TERMINAL_CLEAR_ON_CLOSE UINT32_C(8)
+#define OT_TERMINAL_REPLY_SENTINEL UINT32_C(16)
+#define OT_TERMINAL_SYNC_ALWAYS UINT32_C(32)
+#define OT_TERMINAL_SYNC_NEVER UINT32_C(64)
+#define OT_TERMINAL_HOST_MULTIPLEXER UINT32_C(128)
+
+/* flags is a combination of the eight OT_TERMINAL_* option bits above. Other bits
+ * must be zero. REPLY_SENTINEL ends the startup query packet with DA1 (CSI c),
+ * also inside tmux, and sends no other DA1; the host waits for its reply instead
+ * of a timer. A DA1 reply then also ends the startup cursor-report probes.
+ * Frames that paint are wrapped in synchronized output (DEC mode 2026) unless the terminal
+ * is remote and, once its replies passed the 2026 query (a width-probe report
+ * or DA1), either did not report the mode or HOST_MULTIPLEXER is set: the host
+ * runs inside tmux, screen or Zellij between the app and the link.
+ * SYNC_ALWAYS or SYNC_NEVER (not both) forces the wrapper on or off. kitty_keyboard_flags accepts OT_KITTY_KEYBOARD_* bits, or zero to
+ * disable Kitty keyboard. clear-on-close also controls surface clearing on suspend. It
+ * clears only a surface that setup or resume claimed: a close before their mode
+ * packet leaves visible shell output in place. */
+typedef struct ot_session_terminal_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t flags;
+    uint32_t kitty_keyboard_flags;
+} ot_session_terminal_options;
+
+/* Kitty keyboard protocol progressive-enhancement flags. */
+#define OT_KITTY_KEYBOARD_DISAMBIGUATE UINT32_C(1)
+#define OT_KITTY_KEYBOARD_EVENT_TYPES UINT32_C(2)
+#define OT_KITTY_KEYBOARD_ALTERNATE_KEYS UINT32_C(4)
+#define OT_KITTY_KEYBOARD_ALL_KEYS_AS_ESCAPES UINT32_C(8)
+#define OT_KITTY_KEYBOARD_REPORT_TEXT UINT32_C(16)
+#define OT_KITTY_KEYBOARD_ALL (OT_KITTY_KEYBOARD_DISAMBIGUATE | OT_KITTY_KEYBOARD_EVENT_TYPES | \
+    OT_KITTY_KEYBOARD_ALTERNATE_KEYS | OT_KITTY_KEYBOARD_ALL_KEYS_AS_ESCAPES | OT_KITTY_KEYBOARD_REPORT_TEXT)
+
+#define OT_CONTROL_CAPABILITY_RESPONSE UINT32_C(1)
+#define OT_CONTROL_TITLE UINT32_C(2)
+#define OT_CONTROL_MOUSE UINT32_C(3)
+#define OT_CONTROL_KITTY_KEYBOARD_FLAGS UINT32_C(4)
+#define OT_CONTROL_RESTORE_MODES UINT32_C(5)
+#define OT_CONTROL_QUERY_PIXEL_RESOLUTION UINT32_C(6)
+#define OT_CONTROL_QUERY_THEME_COLORS UINT32_C(7)
+#define OT_CONTROL_CURSOR UINT32_C(8)
+#define OT_CONTROL_RESET_BACKGROUND UINT32_C(9)
+#define OT_CONTROL_PALETTE_QUERY UINT32_C(10)
+#define OT_CONTROL_PROGRAM_STATUS UINT32_C(11)
+#define OT_CONTROL_END_REPLY_SENTINEL UINT32_C(12)
+
+/* argument is 0/1/2 (disabled/drag/motion) for MOUSE, 0..31 for Kitty flags,
+ * 0/1 for QUERY_PIXEL_RESOLUTION, QUERY_THEME_COLORS and PALETTE_QUERY (1 appends
+ * the DA1 sentinel, after the validated palette queries in the same packet; a
+ * tmux-wrapped query's replies trail tmux's own DA1, so it takes 0), and zero
+ * otherwise. CAPABILITY_RESPONSE, TITLE, CURSOR, PALETTE_QUERY, and
+ * PROGRAM_STATUS accept payload bytes. reserved must be zero. END_REPLY_SENTINEL,
+ * accepted in every open phase, turns REPLY_SENTINEL off for good once a DA1
+ * reply never came: later Kitty keyboard pushes send no CSI ? u query. */
+typedef struct ot_session_control_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t kind;
+    uint32_t argument;
+    uint32_t reserved;
+} ot_session_control_options;
+
+#define OT_CURSOR_POSITION UINT32_C(1)
+#define OT_CURSOR_STYLE UINT32_C(2)
+#define OT_CURSOR_BLINKING UINT32_C(4)
+#define OT_CURSOR_COLOR UINT32_C(8)
+#define OT_CURSOR_MOUSE_POINTER UINT32_C(16)
+
+/* CURSOR payload is exactly one copied ot_session_cursor_update, with native
+ * byte order and no alignment requirement. fields selects updated properties;
+ * other bits must be zero. x/y clamp to 1 and must not exceed 65536. visible and
+ * blinking are 0/1. style is an OT_CURSOR_STYLE_* value. mouse_pointer
+ * is an OT_MOUSE_POINTER_* shape. Color uses the packed RGBA lanes. Unselected
+ * fields must be zero. */
+typedef struct ot_session_cursor_update {
+    uint32_t fields;
+    int32_t x;
+    int32_t y;
+    uint8_t visible;
+    uint8_t style;
+    uint8_t blinking;
+    uint8_t mouse_pointer;
+    uint16_t color[4];
+} ot_session_cursor_update;
+
+#define OT_PROGRAM_STATE_IDLE UINT32_C(1)
+#define OT_PROGRAM_STATE_WORKING UINT32_C(2)
+#define OT_PROGRAM_STATE_DONE UINT32_C(3)
+#define OT_PROGRAM_STATE_BLOCKED UINT32_C(4)
+#define OT_PROGRAM_STATE_ERROR UINT32_C(5)
+#define OT_PROGRAM_STATE_CLEAR UINT32_C(6)
+
+#define OT_PROGRAM_KIND_PERMISSION UINT32_C(1)
+#define OT_PROGRAM_KIND_QUESTION UINT32_C(2)
+#define OT_PROGRAM_KIND_AUTH UINT32_C(3)
+
+#define OT_PROGRAM_STATUS_PROGRESS UINT32_C(1)
+
+/* PROGRAM_STATUS payload is one copied ot_session_program_status, with native
+ * byte order and no alignment requirement, followed by exactly id_len, app_len,
+ * title_len, and message_len bytes in that order. It writes one OSC 7501
+ * Program Status Protocol report. A zero length omits that key; an empty id
+ * addresses the root record. kind is zero or an OT_PROGRAM_KIND_* value and
+ * requires BLOCKED. fields selects progress, 0..100, which requires WORKING or
+ * BLOCKED; unselected progress must be zero. CLEAR accepts only an id.
+ * id is at most 8 '/'-separated segments of 1..32 [A-Za-z0-9_.+-] bytes and 128
+ * bytes in total. app is at most 32 [A-Za-z0-9_.+-] bytes. title (at most 192
+ * bytes) and message (at most 2048 bytes) are UTF-8 without C0, DEL, or C1
+ * controls; output encodes them as base64. Output is never multiplexer-wrapped. */
+typedef struct ot_session_program_status {
+    uint32_t state;
+    uint32_t kind;
+    uint32_t fields;
+    uint32_t progress;
+    uint32_t id_len;
+    uint32_t app_len;
+    uint32_t title_len;
+    uint32_t message_len;
+} ot_session_program_status;
+
+#define OT_CAP_KITTY_KEYBOARD UINT32_C(1)
+#define OT_CAP_KITTY_GRAPHICS UINT32_C(2)
+#define OT_CAP_RGB UINT32_C(4)
+#define OT_CAP_ANSI256 UINT32_C(8)
+#define OT_CAP_SGR_PIXELS UINT32_C(16)
+#define OT_CAP_COLOR_SCHEME_UPDATES UINT32_C(32)
+#define OT_CAP_EXPLICIT_WIDTH UINT32_C(64)
+#define OT_CAP_SCALED_TEXT UINT32_C(128)
+#define OT_CAP_SIXEL UINT32_C(256)
+#define OT_CAP_FOCUS_TRACKING UINT32_C(512)
+#define OT_CAP_SYNC UINT32_C(1024)
+#define OT_CAP_BRACKETED_PASTE UINT32_C(2048)
+#define OT_CAP_HYPERLINKS UINT32_C(4096)
+#define OT_CAP_OSC52 UINT32_C(8192)
+#define OT_CAP_NOTIFICATIONS UINT32_C(16384)
+#define OT_CAP_EXPLICIT_CURSOR_POSITIONING UINT32_C(32768)
+#define OT_CAP_REMOTE UINT32_C(65536)
+#define OT_CAP_PROGRAM_STATUS UINT32_C(131072)
+
+/* Initialize struct_size and abi_version. All other fields are copied output.
+ * width_method is 0=wcwidth, 1=unicode, 2=no_zwj, 3=unicode_wide.
+ * multiplexer is 0=none, 1=tmux, 2=zellij, 3=screen, 4=unknown.
+ * image_protocol is 0=auto, 1=kitty, 2=sixel, 3=blocks.
+ * osc52_support is 0=unknown, 1=supported, 2=unsupported.
+ * kitty_keyboard_flags is accepted intent, not confirmation of enabled modes.
+ * String lengths count bytes, not NUL terminators. Unused bytes and reserved
+ * are zero. No native memory is borrowed; failure leaves the record unchanged. */
+typedef struct ot_session_capabilities {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t flags;
+    uint32_t width_method;
+    uint32_t multiplexer;
+    uint32_t image_protocol;
+    uint32_t osc52_support;
+    uint32_t kitty_keyboard_flags;
+    uint32_t term_name_len;
+    uint32_t term_version_len;
+    uint32_t term_from_xtversion;
+    uint32_t reserved;
+    uint8_t term_name[64];
+    uint8_t term_version[32];
+} ot_session_capabilities;
+
+#define OT_TERMINAL_UNINITIALIZED UINT32_C(0)
+#define OT_TERMINAL_SETTING_UP UINT32_C(1)
+#define OT_TERMINAL_ACTIVE UINT32_C(2)
+#define OT_TERMINAL_SUSPENDING UINT32_C(3)
+#define OT_TERMINAL_SUSPENDED UINT32_C(4)
+#define OT_TERMINAL_RESUMING UINT32_C(5)
+#define OT_TERMINAL_CLOSING UINT32_C(6)
+#define OT_TERMINAL_RESTORED UINT32_C(7)
+#define OT_TERMINAL_FAILED UINT32_C(8)
+#define OT_TERMINAL_CANCELLED UINT32_C(9)
+
+#define OT_PUMP_IDLE UINT32_C(0)
+#define OT_PUMP_AGAIN UINT32_C(1)
+#define OT_PUMP_OUTPUT_PENDING UINT32_C(2)
+#define OT_PUMP_WAIT_UNTIL UINT32_C(3)
+#define OT_PUMP_CLOSED UINT32_C(4)
+
+/* ot_session_post_stdout states. */
+#define OT_STDOUT_IDLE UINT32_C(0)
+#define OT_STDOUT_IN_FLIGHT UINT32_C(1)
+
+/* Initialize struct_size and abi_version. status, reserved, and deadline_ns are
+ * output-only. deadline_ns is nonzero only for OT_PUMP_WAIT_UNTIL. No memory is
+ * borrowed. A rejected call leaves the entire output record unchanged. */
+typedef struct ot_session_pump_result {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t status;
+    uint32_t reserved;
+    uint64_t deadline_ns;
+} ot_session_pump_result;
+
+#define OT_INPUT_KEY UINT32_C(1)
+#define OT_INPUT_MOUSE UINT32_C(2)
+#define OT_INPUT_PASTE UINT32_C(3)
+#define OT_INPUT_FOCUS UINT32_C(4)
+#define OT_INPUT_REPLY UINT32_C(5)
+
+#define OT_INPUT_KEY_PRESS UINT32_C(1)
+#define OT_INPUT_KEY_REPEAT UINT32_C(2)
+#define OT_INPUT_KEY_RELEASE UINT32_C(3)
+#define OT_INPUT_MOUSE_DOWN UINT32_C(1)
+#define OT_INPUT_MOUSE_UP UINT32_C(2)
+#define OT_INPUT_MOUSE_MOVE UINT32_C(3)
+#define OT_INPUT_MOUSE_DRAG UINT32_C(4)
+#define OT_INPUT_MOUSE_SCROLL UINT32_C(5)
+#define OT_INPUT_MOUSE_BUTTON_NONE UINT32_C(255)
+#define OT_INPUT_FOCUS_OUT UINT32_C(0)
+#define OT_INPUT_FOCUS_IN UINT32_C(1)
+
+/* Modifier bits use Kitty's layout: the wire modifier parameter minus one. Mouse
+ * events report only Shift, Alt, and Ctrl. */
+#define OT_INPUT_MOD_SHIFT UINT32_C(1)
+#define OT_INPUT_MOD_ALT UINT32_C(2)
+#define OT_INPUT_MOD_CTRL UINT32_C(4)
+#define OT_INPUT_MOD_SUPER UINT32_C(8)
+#define OT_INPUT_MOD_HYPER UINT32_C(16)
+#define OT_INPUT_MOD_META UINT32_C(32)
+#define OT_INPUT_MOD_CAPS_LOCK UINT32_C(64)
+#define OT_INPUT_MOD_NUM_LOCK UINT32_C(128)
+
+#define OT_INPUT_KEY_KITTY UINT32_C(1)
+#define OT_INPUT_KEY_TEXT_TRUNCATED UINT32_C(2)
+#define OT_INPUT_KEY_TYPED UINT32_C(4)
+#define OT_INPUT_PASTE_START UINT32_C(1)
+#define OT_INPUT_PASTE_END UINT32_C(2)
+#define OT_INPUT_REPLY_FRAGMENT UINT32_C(1)
+#define OT_INPUT_REPLY_CURSOR_POSITION UINT32_C(2)
+
+#define OT_INPUT_REPLY_CSI UINT32_C(1)
+#define OT_INPUT_REPLY_SS3 UINT32_C(2)
+#define OT_INPUT_REPLY_OSC UINT32_C(3)
+#define OT_INPUT_REPLY_DCS UINT32_C(4)
+#define OT_INPUT_REPLY_APC UINT32_C(5)
+
+/* Key codes are Unicode scalars; functional keys use the Kitty keyboard protocol
+ * assignments. Escape, Enter, Tab, and Backspace are 27, 13, 9, and 127. A key
+ * typed from the private-use area shares the Kitty range: OT_INPUT_KEY_TYPED
+ * marks a code that is a printable character the terminal sent as text or as
+ * xterm's CSI 27 ; mods ; code ~, never a functional key. Code 0 is a text-only
+ * key (input method output). */
+#define OT_INPUT_KEY_ESCAPE UINT32_C(27)
+#define OT_INPUT_KEY_ENTER UINT32_C(13)
+#define OT_INPUT_KEY_TAB UINT32_C(9)
+#define OT_INPUT_KEY_BACKSPACE UINT32_C(127)
+#define OT_INPUT_KEY_INSERT UINT32_C(57348)
+#define OT_INPUT_KEY_DELETE UINT32_C(57349)
+#define OT_INPUT_KEY_LEFT UINT32_C(57350)
+#define OT_INPUT_KEY_RIGHT UINT32_C(57351)
+#define OT_INPUT_KEY_UP UINT32_C(57352)
+#define OT_INPUT_KEY_DOWN UINT32_C(57353)
+#define OT_INPUT_KEY_PAGE_UP UINT32_C(57354)
+#define OT_INPUT_KEY_PAGE_DOWN UINT32_C(57355)
+#define OT_INPUT_KEY_HOME UINT32_C(57356)
+#define OT_INPUT_KEY_END UINT32_C(57357)
+#define OT_INPUT_KEY_CAPS_LOCK UINT32_C(57358)
+#define OT_INPUT_KEY_SCROLL_LOCK UINT32_C(57359)
+#define OT_INPUT_KEY_NUM_LOCK UINT32_C(57360)
+#define OT_INPUT_KEY_PRINT_SCREEN UINT32_C(57361)
+#define OT_INPUT_KEY_PAUSE UINT32_C(57362)
+#define OT_INPUT_KEY_MENU UINT32_C(57363)
+#define OT_INPUT_KEY_F1 UINT32_C(57364) /* F(n) is 57363 + n, n in 1..35 */
+#define OT_INPUT_KEY_F35 UINT32_C(57398)
+#define OT_INPUT_KEY_KP_0 UINT32_C(57399) /* KP(n) is 57399 + n, n in 0..9 */
+#define OT_INPUT_KEY_KP_9 UINT32_C(57408)
+#define OT_INPUT_KEY_KP_DECIMAL UINT32_C(57409)
+#define OT_INPUT_KEY_KP_DIVIDE UINT32_C(57410)
+#define OT_INPUT_KEY_KP_MULTIPLY UINT32_C(57411)
+#define OT_INPUT_KEY_KP_SUBTRACT UINT32_C(57412)
+#define OT_INPUT_KEY_KP_ADD UINT32_C(57413)
+#define OT_INPUT_KEY_KP_ENTER UINT32_C(57414)
+#define OT_INPUT_KEY_KP_EQUAL UINT32_C(57415)
+#define OT_INPUT_KEY_KP_SEPARATOR UINT32_C(57416)
+#define OT_INPUT_KEY_KP_LEFT UINT32_C(57417)
+#define OT_INPUT_KEY_KP_RIGHT UINT32_C(57418)
+#define OT_INPUT_KEY_KP_UP UINT32_C(57419)
+#define OT_INPUT_KEY_KP_DOWN UINT32_C(57420)
+#define OT_INPUT_KEY_KP_PAGE_UP UINT32_C(57421)
+#define OT_INPUT_KEY_KP_PAGE_DOWN UINT32_C(57422)
+#define OT_INPUT_KEY_KP_HOME UINT32_C(57423)
+#define OT_INPUT_KEY_KP_END UINT32_C(57424)
+#define OT_INPUT_KEY_KP_INSERT UINT32_C(57425)
+#define OT_INPUT_KEY_KP_DELETE UINT32_C(57426)
+#define OT_INPUT_KEY_KP_BEGIN UINT32_C(57427)
+#define OT_INPUT_KEY_MEDIA_PLAY UINT32_C(57428)
+#define OT_INPUT_KEY_MEDIA_PAUSE UINT32_C(57429)
+#define OT_INPUT_KEY_MEDIA_PLAY_PAUSE UINT32_C(57430)
+#define OT_INPUT_KEY_MEDIA_REVERSE UINT32_C(57431)
+#define OT_INPUT_KEY_MEDIA_STOP UINT32_C(57432)
+#define OT_INPUT_KEY_MEDIA_FAST_FORWARD UINT32_C(57433)
+#define OT_INPUT_KEY_MEDIA_REWIND UINT32_C(57434)
+#define OT_INPUT_KEY_MEDIA_TRACK_NEXT UINT32_C(57435)
+#define OT_INPUT_KEY_MEDIA_TRACK_PREVIOUS UINT32_C(57436)
+#define OT_INPUT_KEY_MEDIA_RECORD UINT32_C(57437)
+#define OT_INPUT_KEY_LOWER_VOLUME UINT32_C(57438)
+#define OT_INPUT_KEY_RAISE_VOLUME UINT32_C(57439)
+#define OT_INPUT_KEY_MUTE_VOLUME UINT32_C(57440)
+#define OT_INPUT_KEY_LEFT_SHIFT UINT32_C(57441)
+#define OT_INPUT_KEY_LEFT_CONTROL UINT32_C(57442)
+#define OT_INPUT_KEY_LEFT_ALT UINT32_C(57443)
+#define OT_INPUT_KEY_LEFT_SUPER UINT32_C(57444)
+#define OT_INPUT_KEY_LEFT_HYPER UINT32_C(57445)
+#define OT_INPUT_KEY_LEFT_META UINT32_C(57446)
+#define OT_INPUT_KEY_RIGHT_SHIFT UINT32_C(57447)
+#define OT_INPUT_KEY_RIGHT_CONTROL UINT32_C(57448)
+#define OT_INPUT_KEY_RIGHT_ALT UINT32_C(57449)
+#define OT_INPUT_KEY_RIGHT_SUPER UINT32_C(57450)
+#define OT_INPUT_KEY_RIGHT_HYPER UINT32_C(57451)
+#define OT_INPUT_KEY_RIGHT_META UINT32_C(57452)
+#define OT_INPUT_KEY_ISO_LEVEL3_SHIFT UINT32_C(57453)
+#define OT_INPUT_KEY_ISO_LEVEL5_SHIFT UINT32_C(57454)
+
+#define OT_INPUT_EXPECT_REPLIES UINT32_C(1)
+#define OT_INPUT_EXPECT_KITTY_KEYBOARD UINT32_C(2)
+#define OT_INPUT_EXPECT_CURSOR_POSITION UINT32_C(4)
+#define OT_INPUT_EXPECT_SENTINEL UINT32_C(8)
+#define OT_INPUT_EXPECT_ESCAPE_PREFIX UINT32_C(16)
+
+#define OT_INPUT_EVENTS_MIN UINT32_C(4)
+#define OT_INPUT_PAYLOAD_BYTES_MIN UINT32_C(4384)
+#define OT_INPUT_TIMEOUT_NS UINT64_C(20000000)
+
+/* One parsed input event. raw and text are byte spans into the payload buffer of
+ * the same call. kind selects the meaning of action, code, x, and y:
+ * KEY: action is OT_INPUT_KEY_PRESS/REPEAT/RELEASE, code a key code, base_code a
+ * nonzero base-layout scalar when the terminal reports one, text what an editor
+ * inserts. MOUSE: action is OT_INPUT_MOUSE_*, code a button (0..2, 8+, or NONE)
+ * or a scroll direction (0 up, 1 down, 2 left, 3 right), x and y a zero-based
+ * cell. PASTE: text is one chunk of pasted bytes and raw is empty. FOCUS: action
+ * is OT_INPUT_FOCUS_IN/OUT. REPLY: code is an OT_INPUT_REPLY_* protocol and raw
+ * the wire bytes. flags hold the kind's OT_INPUT_* flags. */
+typedef struct ot_input_event {
+    uint8_t kind;
+    uint8_t action;
+    uint8_t modifiers;
+    uint8_t flags;
+    uint32_t code;
+    uint32_t base_code;
+    uint16_t x;
+    uint16_t y;
+    uint32_t raw_offset;
+    uint32_t raw_len;
+    uint32_t text_offset;
+    uint32_t text_len;
+} ot_input_event;
+
+/* Initialize struct_size and abi_version. The remaining fields are output-only.
+ * consumed is the number of input bytes parsed; call again with the rest when it
+ * is less than byte_count. A call can consume nothing after it reported events.
+ * deadline_ns is nonzero when a partial unit waits for the timeout: call feed
+ * with zero bytes at or after it. discarded is a saturating lifetime count of
+ * overlong units dropped. */
+typedef struct ot_input_drain {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t consumed;
+    uint32_t count;
+    uint32_t payload_len;
+    uint32_t discarded;
+    uint64_t deadline_ns;
+} ot_input_drain;
+
+/* Zero-initialize, then set struct_size to sizeof(ot_context_options) and
+ * abi_version to OT_CONTEXT_ABI_VERSION. Version 2 requires the exact size,
+ * zero flags, zero reserved fields, and positive resource limits.
+ * object_capacity is the initial count of native object slots, not bytes. A full
+ * table doubles, up to 4194304 slots or object_capacity, whichever is larger;
+ * past that, creation returns OT_OBJECT_LIMIT. render_cells_max bounds each
+ * renderer's width * height in terminal cells, not bytes or total context
+ * memory. Neither limit uses a default when zero.
+ * Allocator and I/O injection are available only through the direct Zig API. */
+typedef struct ot_context_options {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t flags;
+    uint32_t object_capacity;
+    uint32_t render_cells_max;
+    uint32_t reserved[3];
+} ot_context_options;
+
+/* Initialize struct_size and abi_version before querying. The library writes
+ * status and clears reserved on success. This record contains no borrowed
+ * memory and remains valid after context destruction. */
+typedef struct ot_context_error {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    ot_status status;
+    uint32_t reserved;
+} ot_context_error;
+
+#define OT_DIAGNOSTIC_MESSAGE_BYTES UINT32_C(4096)
+#define OT_DIAGNOSTIC_TRUNCATED UINT32_C(1)
+#define OT_DIAGNOSTIC_QUEUE_MAX UINT32_C(64)
+
+/* Copied diagnostic record. level is 0 (error), 1 (warning), 2 (info), or
+ * 3 (debug). message_len counts bytes, not a terminating NUL. Unused message
+ * bytes and reserved are zero. Truncation can split a UTF-8 sequence. */
+typedef struct ot_diagnostic {
+    uint32_t level;
+    uint32_t message_len;
+    uint32_t flags;
+    uint32_t reserved;
+    uint8_t message[OT_DIAGNOSTIC_MESSAGE_BYTES];
+} ot_diagnostic;
+
+/* Initialize struct_size and abi_version before each drain. dropped is a
+ * saturating lifetime total. Draining does not reset it. */
+typedef struct ot_diagnostic_drain {
+    uint32_t struct_size;
+    uint32_t abi_version;
+    uint32_t count;
+    uint32_t remaining;
+    uint64_t dropped;
+} ot_diagnostic_drain;
+
+uint32_t ot_context_abi_version(void);
+
+/* Create a context without setting up a terminal or starting worker threads.
+ * Both pointers must be non-NULL and correctly aligned. Options are borrowed
+ * only for this call. The function checks options before native allocation
+ * and sets *out_context to NULL on every failure when out_context is non-NULL.
+ * Creation failures have no context-local error record; use the return status.
+ * OT_OUT_OF_MEMORY includes Yoga configuration allocation failure. Yoga C++
+ * allocations use separate failure-injection tests, not Zig allocators.
+ * Destroy a successful result with ot_context_destroy, never free(). */
+ot_status ot_context_create(const ot_context_options *options, ot_context **out_context);
+
+/* Destroy a live context on its owner thread. NULL returns OT_INVALID_ARGUMENT.
+ * OT_WRONG_THREAD leaves the context alive and does not change its error.
+ * An active operation, teardown, or unreleased checked storage lease returns and
+ * records OT_CONTEXT_BUSY without releasing the context or its I/O storage. */
+ot_status ot_context_destroy(ot_context *context);
+
+/* Copy this context's most recent owner-thread error, initially OT_OK.
+ * Successful queries do not clear it. Invalid query arguments update it.
+ * The output requires the exact version-1 size and version; its status and
+ * reserved fields are output-only. On failure, the output remains unchanged.
+ * NULL contexts and wrong-thread calls return a status without changing any
+ * context-local state. The caller owns the output for the entire call. */
+ot_status ot_context_get_last_error(ot_context *context, ot_context_error *out_error);
+
+/* Copy up to capacity records in arrival order without allocation or callbacks.
+ * Version 2 C contexts hold at most OT_DIAGNOSTIC_QUEUE_MAX records and drop newest on overflow.
+ * records may be NULL only when capacity is zero. A zero-capacity drain reports
+ * queue pressure without removing records. out_drain must have the exact size
+ * and version. The caller owns both outputs for the call. Outputs and queued
+ * records remain unchanged on failure. Active operations return OT_CONTEXT_BUSY.
+ * Copied records remain valid after context destruction. */
+ot_status ot_context_drain_diagnostics(
+    ot_context *context,
+    ot_diagnostic *records,
+    uint32_t capacity,
+    ot_diagnostic_drain *out_drain);
+
+/* Copy a live interned hyperlink URL. Zero capacity reports the byte count.
+ * Nonzero capacity must fit that count; out_count is the copied byte count.
+ * bytes may be NULL only when capacity is zero. URLs are at most 512 bytes.
+ * Unknown or retired IDs return OT_INVALID_ARGUMENT. Outputs are unchanged on
+ * rejection. Owner-thread and busy-operation rules apply. */
+ot_status ot_context_get_link_url(ot_context *context, uint32_t link_id,
+    uint8_t *bytes, uint32_t capacity, uint32_t *out_count);
+
+/* Options require the exact size and version. Failure leaves out_buffer unchanged.
+ * The Context owns the buffer and its pools.
+ * These functions obey the Context owner-thread and busy-operation rules. */
+ot_status ot_buffer_create(
+    ot_context *context,
+    const ot_buffer_options *options,
+    ot_handle *out_buffer);
+ot_status ot_buffer_destroy(ot_context *context, const ot_handle *buffer);
+
+/* Rejected resize preserves dimensions and cells. Size-changing resize or
+ * destruction retires leased storage, which stays allocated until release. */
+ot_status ot_buffer_resize(
+    ot_context *context,
+    const ot_handle *buffer,
+    uint32_t width,
+    uint32_t height);
+
+/* Draw into an owned buffer, or a Session's next buffer with the exact retained
+ * DONE ticket. frame must be NULL for an owned buffer and non-NULL
+ * for a Session. source is a same-Context buffer for COMPOSE only.
+ * text is used only for TEXT or the BOX top title; bottom_title is BOX-only.
+ * Other operations require zero byte counts for unused spans.
+ * CLEAR fills spaces, zero attributes, and white foreground using the record
+ * background. FILL clips to the destination; zero-sized or offscreen rectangles
+ * are no-ops. Neither replaces storage or invalidates leases. TEXT draws only its
+ * cells inside the target and skips a glyph that starts left of column 0.
+ * Text/title byte counts are bounded by OT_BUFFER_TEXT_BYTES_MAX; invalid UTF-8
+ * returns OT_INVALID_ARGUMENT. C0/C1/DEL controls occupy no cells. A tab (two
+ * cells) and a grapheme over the native 128-byte limit or 16 cells draw as
+ * spaces of their width. CELL, CELL_BLEND, and CHAR write a space for a control character.
+ * Image-bearing targets return OT_UNSUPPORTED_RESOURCE.
+ * Raw resource IDs are rejected. Rejection preserves cells except that any Box
+ * title drawing failure may partially modify the destination; callers must
+ * cancel the frame or discard the offscreen draft. No native framebuffer
+ * pointer is accepted. */
+ot_status ot_buffer_draw(ot_context *context, const ot_handle *target,
+    const ot_scene_frame_request *frame, const ot_buffer_draw_header *options,
+    const ot_handle *source, const uint8_t *text, uint32_t text_len,
+    const uint8_t *bottom_title, uint32_t bottom_title_len);
+
+/* Checked drawing stacks use the same target/frame authority as ot_buffer_draw.
+ * Pushes intersect clips or multiply opacity using the native buffer rules.
+ * At most OT_BUFFER_STACK_DEPTH_MAX custom entries per stack are permitted;
+ * exceeding this limit returns OT_OBJECT_LIMIT without changing either stack.
+ * Clip sizes and signed endpoints must fit int32_t; empty clips are valid.
+ * Opacity must be finite and is clamped to [0, 1]. Pass it as a one-float
+ * buffer so host FFI can keep the portable integer/buffer calling convention.
+ * Only PUSH operations use their corresponding rectangle/opacity arguments.
+ * Pop on an empty custom stack is a no-op. Custom frame stacks reset on commit
+ * or frame cancellation; owned buffer stacks persist until explicitly
+ * popped/cleared or destroyed. out_opacity is required and receives the
+ * effective opacity on success only. */
+ot_status ot_buffer_stack(ot_context *context, const ot_handle *target,
+    const ot_scene_frame_request *frame, uint32_t operation,
+    int32_t x, int32_t y, uint32_t width, uint32_t height,
+    const float *opacity, float *out_opacity);
+
+/* Draw a grid with the same target/frame authority as ot_buffer_draw. Counts are
+ * offset-array lengths, not cell counts. Arrays must be strictly increasing,
+ * with at most render_cells_max + 1 entries each; fewer than two is a no-op.
+ * NULL arrays require zero length. Glyphs must be single-cell Unicode scalars
+ * or zero. Colors use packed RGBA with canonical color intent. Input is borrowed only for this
+ * call. Invalid input preserves the destination. Image-bearing targets reject. */
+ot_status ot_buffer_draw_grid(ot_context *context, const ot_handle *target,
+    const ot_scene_frame_request *frame, const ot_buffer_grid_options *options,
+    const int32_t *columns, uint32_t column_count,
+    const int32_t *rows, uint32_t row_count);
+
+/* Pixel drawing uses the same target/frame authority as ot_buffer_draw. Input
+ * spans are borrowed for this call only and must not overlap destination planes.
+ * NULL input requires zero length. Images reject; clipping, opacity, and pooled
+ * cell replacement use the native buffer rules. Rejection preserves cells.
+ * Packed cells are 48 native-endian bytes: bg[4] f32, fg[4] f32, character u32,
+ * and 12 padding bytes. Input may be unaligned and must contain complete cells,
+ * at least width * height. Visible color samples must be finite; finite channels
+ * are clamped to 0..1. Invalid/non-cell characters use the existing block fallback.
+ * Supersampling uses format 0=BGRA, 1=RGBA, and a nonzero stride divisible by 4.
+ * Input must contain whole rows. Row padding is input; destination width clips it.
+ * Missing neighbors at odd source edges are transparent.
+ * Packed and supersampled positions are signed cells; a negative position clips
+ * the source cells left of or above the destination.
+ * Grayscale sample_count counts floats, not bytes; width * height must fit u32
+ * and the supplied span. Visible samples must be finite. supersampled is 0 or 1;
+ * 2x grayscale ignores an incomplete final sample row/column. Optional colors
+ * contain packed RGBA with canonical color intent. Preflight work is destination-bounded. */
+ot_status ot_buffer_draw_packed(ot_context *, const ot_handle *, const ot_scene_frame_request *,
+    const uint8_t *data, uint32_t byte_count, int32_t x, int32_t y, uint32_t width, uint32_t height);
+ot_status ot_buffer_draw_supersample(ot_context *, const ot_handle *, const ot_scene_frame_request *,
+    const uint8_t *data, uint32_t byte_count, int32_t x, int32_t y, uint32_t format, uint32_t stride);
+ot_status ot_buffer_draw_grayscale(ot_context *, const ot_handle *, const ot_scene_frame_request *,
+    const float *data, uint32_t sample_count, int32_t x, int32_t y, uint32_t width, uint32_t height,
+    const uint16_t *foreground, const uint16_t *background, uint32_t supersampled);
+
+/* Color matrices borrow 16 floats and optional (x, y, weight) triples for this
+ * call. NULL mask selects uniform application and requires zero mask_count;
+ * a non-NULL empty mask selects no cells. Counts are floats, not bytes; incomplete
+ * triples are ignored. Matrix/global strength must be finite. channel is 1=FG,
+ * 2=BG, 3=both. Mask triples are bounded by render_cells_max; invalid coordinates
+ * and non-finite effective cell strengths are skipped. Effects retain whole-buffer
+ * semantics without applying scissor/opacity again. Target/frame authority is the
+ * same as ot_buffer_draw, including no-ops. Inputs are not retained. */
+ot_status ot_buffer_color_matrix(ot_context *, const ot_handle *, const ot_scene_frame_request *,
+    const float *matrix, uint32_t matrix_count, const float *mask, uint32_t mask_count,
+    const float *strength, uint32_t channel);
+
+/* A paint recording acknowledges a RECORD request. It is one byte stream of
+ * records. The stream must be 8-byte aligned and at most OT_SCENE_RECORD_BYTES_MAX
+ * bytes. Every record starts with ot_scene_record_header; size counts the whole
+ * record, including its trailing variable data, rounded up to a multiple of 8.
+ * Native code ignores padding bytes. Reserved fields must be zero.
+ *
+ * A SLOT record starts the commands for one phase of one slot. Slots and phases
+ * must appear in increasing order, at most once, and only for phases set in the
+ * slot's hooks. Every other record belongs to the latest SLOT record. The stream
+ * is validated before painting; an invalid stream fails the step and cancels the
+ * attempt without presenting cells.
+ *
+ * Commands draw into the Session's next buffer with the same rules as the named
+ * operations, inside the slot's clip and opacity. STACK entries apply above that
+ * scene-owned entry and reset between phases. Exceptions: a DRAW with
+ * OT_BUFFER_DRAW_CLEAR and COLOR_MATRIX act on the whole buffer, like their named
+ * operations, and ignore the clip and opacity. CLEAR overwrites every cell and
+ * removes the image placements that earlier slots painted. Native code plays each
+ * command when it paints the slot, so a command that names a buffer, view, image,
+ * node, or Unicode handle reads that resource then, not when it was recorded. A
+ * command whose resource was destroyed before playback draws nothing. Other
+ * invalid commands fail the step without presenting cells. */
+#define OT_SCENE_RECORD_BYTES_MAX UINT32_C(67108864)
+#define OT_SCENE_RECORD_PHASE_BEFORE UINT32_C(0)
+#define OT_SCENE_RECORD_PHASE_SELF UINT32_C(1)
+#define OT_SCENE_RECORD_PHASE_AFTER UINT32_C(2)
+#define OT_SCENE_RECORD_SLOT UINT32_C(0)
+#define OT_SCENE_RECORD_DRAW UINT32_C(1)
+#define OT_SCENE_RECORD_STACK UINT32_C(2)
+#define OT_SCENE_RECORD_GRID UINT32_C(3)
+#define OT_SCENE_RECORD_PACKED UINT32_C(4)
+#define OT_SCENE_RECORD_SUPERSAMPLE UINT32_C(5)
+#define OT_SCENE_RECORD_GRAYSCALE UINT32_C(6)
+#define OT_SCENE_RECORD_COLOR_MATRIX UINT32_C(7)
+#define OT_SCENE_RECORD_TEXT_VIEW UINT32_C(8)
+#define OT_SCENE_RECORD_EDITOR_VIEW UINT32_C(9)
+#define OT_SCENE_RECORD_SCENE_BODY UINT32_C(10)
+#define OT_SCENE_RECORD_IMAGE UINT32_C(11)
+#define OT_SCENE_RECORD_UNICODE UINT32_C(12)
+#define OT_SCENE_RECORD_GRAYSCALE_FOREGROUND UINT32_C(1)
+#define OT_SCENE_RECORD_GRAYSCALE_BACKGROUND UINT32_C(2)
+#define OT_SCENE_RECORD_GRAYSCALE_SUPERSAMPLED UINT32_C(4)
+
+typedef struct ot_scene_record_header {
+    uint32_t size;
+    uint32_t operation;
+} ot_scene_record_header;
+
+typedef struct ot_scene_record_slot {
+    ot_scene_record_header header;
+    uint32_t slot;
+    uint32_t phase;
+} ot_scene_record_slot;
+
+/* Followed by one complete ot_buffer_draw_* record, then text_length text bytes
+ * and bottom_length bottom-title bytes, as for ot_buffer_draw. source names the
+ * COMPOSE source and must be zero otherwise. RESPECT_ALPHA rejects. */
+typedef struct ot_scene_record_draw {
+    ot_scene_record_header header;
+    ot_handle source;
+    uint32_t text_length;
+    uint32_t bottom_length;
+} ot_scene_record_draw;
+
+/* As for ot_buffer_stack. */
+typedef struct ot_scene_record_stack {
+    ot_scene_record_header header;
+    uint32_t operation;
+    int32_t x;
+    int32_t y;
+    uint32_t width;
+    uint32_t height;
+    float opacity;
+} ot_scene_record_stack;
+
+/* Followed by column_count and then row_count int32_t offsets, as for
+ * ot_buffer_draw_grid. */
+typedef struct ot_scene_record_grid {
+    ot_scene_record_header header;
+    ot_buffer_grid_options options;
+    uint32_t column_count;
+    uint32_t row_count;
+} ot_scene_record_grid;
+
+/* Followed by byte_count bytes, as for ot_buffer_draw_packed. */
+typedef struct ot_scene_record_packed {
+    ot_scene_record_header header;
+    int32_t x;
+    int32_t y;
+    uint32_t width;
+    uint32_t height;
+    uint32_t byte_count;
+    uint32_t reserved;
+} ot_scene_record_packed;
+
+/* Followed by byte_count bytes, as for ot_buffer_draw_supersample. */
+typedef struct ot_scene_record_supersample {
+    ot_scene_record_header header;
+    int32_t x;
+    int32_t y;
+    uint32_t format;
+    uint32_t stride;
+    uint32_t byte_count;
+    uint32_t reserved;
+} ot_scene_record_supersample;
+
+/* Followed by sample_count floats, as for ot_buffer_draw_grayscale. flags
+ * selects the optional colors and supersampling. */
+typedef struct ot_scene_record_grayscale {
+    ot_scene_record_header header;
+    int32_t x;
+    int32_t y;
+    uint32_t width;
+    uint32_t height;
+    uint32_t flags;
+    uint32_t sample_count;
+    uint16_t foreground[4];
+    uint16_t background[4];
+} ot_scene_record_grayscale;
+
+/* Followed by mask_count floats, as for ot_buffer_color_matrix. has_mask 0
+ * selects uniform application and requires zero mask_count. */
+typedef struct ot_scene_record_color_matrix {
+    ot_scene_record_header header;
+    float matrix[16];
+    float strength;
+    uint32_t channel;
+    uint32_t has_mask;
+    uint32_t mask_count;
+} ot_scene_record_color_matrix;
+
+/* TEXT_VIEW, EDITOR_VIEW, and SCENE_BODY draw a text-buffer view, an editor
+ * view, or a scene node's body, as for their ot_buffer_draw_* operations. */
+typedef struct ot_scene_record_view {
+    ot_scene_record_header header;
+    ot_handle source;
+    int32_t x;
+    int32_t y;
+} ot_scene_record_view;
+
+/* As for ot_buffer_draw_image. */
+typedef struct ot_scene_record_image {
+    ot_scene_record_header header;
+    ot_handle image;
+    ot_image_draw_options options;
+} ot_scene_record_image;
+
+/* As for ot_buffer_draw_unicode. */
+typedef struct ot_scene_record_unicode {
+    ot_scene_record_header header;
+    ot_handle unicode;
+    uint32_t index;
+    int32_t x;
+    int32_t y;
+    uint32_t attributes;
+    uint16_t foreground[4];
+    uint16_t background[4];
+} ot_scene_record_unicode;
+
+/* Retain one offscreen storage generation under the same limits and raw-plane
+ * restrictions as Session leases. The snapshot requires exact size/version and
+ * zero reserved. Rejection leaves it unchanged and acquires no lease. */
+ot_status ot_buffer_acquire_lease(
+    ot_context *context,
+    const ot_handle *buffer,
+    ot_buffer_lease_snapshot *out_snapshot);
+
+/* Create only the transport. No renderer, terminal modes, or worker starts.
+ * Options require the exact size and OT_CONTEXT_ABI_VERSION. A failed call leaves
+ * out_session unchanged. All session functions obey the context thread rule. */
+ot_status ot_session_create(
+    ot_context *context,
+    const ot_session_options *options,
+    ot_handle *out_session);
+
+/* Attach once. A rejected call preserves the Session and its queued output.
+ * The renderer uses its Context's pools. */
+ot_status ot_session_attach_renderer(
+    ot_context *context,
+    const ot_handle *session,
+    const ot_session_renderer_options *options);
+ot_status ot_session_attach_renderer_with_env(
+    ot_context *context,
+    const ot_handle *session,
+    const ot_session_renderer_env_options *options,
+    const uint8_t *environment);
+
+/* Submit at most one frame. force is 0 or 1. OT_RENDER_PENDING also means that
+ * an earlier accepted frame is still pending; no second frame was accepted.
+ * SKIPPED and FAILED accept no output and require an explicit new submission.
+ * Only output completion publishes frame_count. A frame submitted here has no
+ * scene hits: after it, ot_scene_hit_test returns 0 until a scene frame presents.
+ * A live scene preparation or painted draft returns OT_FRAME_BUSY; submit a
+ * painted draft with ot_scene_frame_commit instead.
+ * On an error return, out_result remains unchanged. */
+ot_status ot_session_render(
+    ot_context *context,
+    const ot_handle *session,
+    uint32_t force,
+    uint32_t *out_result);
+
+/* A frame whose presentation is pending returns OT_OUTPUT_BUSY. Queued raw and
+ * control output does not prevent resize and stays ahead of the next frame.
+ * Rejection preserves accepted dimensions. Scene preparation returns
+ * OT_FRAME_BUSY. A painted draft allows resize under the storage
+ * requalification rules of ot_scene_frame_acquire_buffer_lease. */
+ot_status ot_session_resize_renderer(
+    ot_context *context,
+    const ot_handle *session,
+    uint32_t width,
+    uint32_t height);
+
+/* Copy the full offscreen source into the Session's next framebuffer, clipped
+ * at signed cell coordinates. Both handles must belong to this Context.
+ * Pending presentation and non-rendering phases reject drawing. Images in the
+ * source or destination return OT_UNSUPPORTED_RESOURCE. Rejection preserves
+ * cells and output; success retains no source borrow and emits no output. */
+ot_status ot_session_draw_buffer(
+    ot_context *context,
+    const ot_handle *session,
+    const ot_handle *source,
+    int32_t x,
+    int32_t y);
+
+/* Same resource and coordinate rules as ot_session_draw_buffer, but authorized
+ * by a retained DONE draft. No source borrow
+ * survives return; pending presentation and stale tickets reject drawing. */
+ot_status ot_scene_frame_draw_buffer(ot_context *context, const ot_handle *session,
+    const ot_scene_frame_request *frame_request, const ot_handle *source, int32_t x, int32_t y);
+
+/* Diagnostics require an open Session and attached renderer, not terminal setup
+ * or an idle frame. They emit no terminal output. enabled is 0 or 1; corner is
+ * 0 top-left, 1 top-right, 2 bottom-left, or 3 bottom-right. Times must be finite
+ * and nonnegative. Memory byte counts use the renderer's existing u32 range.
+ * Hit-grid dumping writes, per cell, the last digit of the presented hit token
+ * (or '.') with best-effort file I/O through Context I/O, to
+ * hitgrid_<timestamp>.txt in the working directory. */
+ot_status ot_session_set_debug_overlay(ot_context *, const ot_handle *session, uint32_t enabled, uint32_t corner);
+ot_status ot_session_update_stats(ot_context *, const ot_handle *session, double overall_ms, uint32_t fps, double callback_ms);
+ot_status ot_session_update_memory_stats(ot_context *, const ot_handle *session, uint32_t heap_used, uint32_t heap_total, uint32_t array_buffers);
+ot_status ot_session_dump_hit_grid(ot_context *, const ot_handle *session);
+
+/* The record requires the exact size and version. Failure preserves it. */
+ot_status ot_session_get_renderer_state(
+    ot_context *context,
+    const ot_handle *session,
+    ot_session_renderer_state *out_state);
+
+/* Retain one Session-owned framebuffer storage generation without creating a
+ * renderer or buffer owner. which is OT_SESSION_BUFFER_CURRENT or NEXT.
+ * Acquisition requires a rendering phase and no pending presentation. Finish
+ * drawing before submitting a frame; an ordinary storage lease does not block
+ * rendering. A live scene preparation or painted draft returns OT_FRAME_BUSY;
+ * use ot_scene_frame_acquire_buffer_lease for painted-frame access.
+ * The output requires the exact size/version and zero reserved. Rejection leaves
+ * it unchanged and acquires no lease. Leases take object slots; C contexts
+ * allow at most 4096 leases and 64 MiB of distinct leased storage, including
+ * retired arrays and tracker capacity. Shared Context pools are not in that charge.
+ * Release every accepted lease, even after Session resize or destruction. */
+ot_status ot_session_acquire_buffer_lease(
+    ot_context *context,
+    const ot_handle *session,
+    uint32_t which,
+    ot_buffer_lease_snapshot *out_snapshot);
+
+/* Read the link id stored in one current-framebuffer cell. Does not retain
+ * storage and does not require an idle frame. Encode syncs those cells before
+ * presentation is pending, so the read stays valid while output drains.
+ * Negative or out-of-range coordinates write 0 and succeed. out_link_id is
+ * required; rejection leaves it unchanged. */
+ot_status ot_session_get_link_id(
+    ot_context *context,
+    const ot_handle *session,
+    int32_t x,
+    int32_t y,
+    uint32_t *out_link_id);
+
+/* Ordinary leases check storage lifetime, not contents or Session phase. Qualified
+ * leases also check retained painted-frame membership, destination, and storage
+ * identity. Buffer replacement, destruction, or frame cancellation makes affected
+ * leases return OT_STALE_LEASE. Arrays remain allocated until release, but stale
+ * qualified access is revoked.
+ * Duplicate release or a reused lease slot returns OT_STALE_HANDLE. All calls obey the Context
+ * owner-thread rule. Keep the Context and native image alive until release.
+ * Copies of the record do not retain storage. Release cannot revoke saved raw
+ * addresses: callers must not use them after release. */
+ot_status ot_buffer_lease_validate(ot_context *context, const ot_handle *lease);
+ot_status ot_buffer_lease_release(ot_context *context, const ot_handle *lease);
+
+/* Resolve text through the leased storage's own grapheme pool. Keep one lease
+ * across sizing and writing. add_line_breaks is 0 or 1. An undersized output
+ * returns OT_INVALID_ARGUMENT and may contain a partial prefix; out_written
+ * remains unchanged on error. Stale or released leases reject both operations.
+ * Optional cell_lengths receives one UTF-8 byte length per cell, excluding row
+ * separators. Continuations have length zero. Set it to NULL with cell_capacity
+ * zero when lengths are not needed; otherwise reserve at least width * height. */
+ot_status ot_buffer_lease_get_real_char_size(
+    ot_context *context, const ot_handle *lease,
+    uint32_t add_line_breaks, uint32_t *out_size);
+ot_status ot_buffer_lease_write_resolved_chars(
+    ot_context *context, const ot_handle *lease,
+    uint8_t *bytes, uint32_t capacity,
+    uint32_t add_line_breaks, uint8_t *cell_lengths, uint32_t cell_capacity,
+    uint32_t *out_written);
+
+/* Accept a terminal lifecycle request; pump performs output and timed work.
+ * Setup requires an attached renderer and sufficient reserved control storage,
+ * and must precede the first accepted frame. Earlier raw output is allowed.
+ * It does not wait for capability replies. Ordinary writes and rendering are
+ * rejected during transitions. Suspended sessions allow raw writes and null-frame
+ * split snapshots, not ordinary frames.
+ * Resume reuses the accepted setup options without repeating detection. */
+ot_status ot_session_setup_terminal(
+    ot_context *context,
+    const ot_handle *session,
+    const ot_session_terminal_options *options);
+ot_status ot_session_suspend(ot_context *context, const ot_handle *session);
+ot_status ot_session_resume(ot_context *context, const ot_handle *session);
+ot_status ot_session_get_terminal_state(ot_context *context, const ot_handle *session, uint32_t *out_phase);
+
+/* Accept capability replies during setup after pump publishes the initial query
+ * packet, even before output completion. Also accept replies during resume.
+ * CURSOR updates synchronous intent in any open phase; only a subsequent accepted
+ * frame emits it. Other controls require an active terminal. Capability payloads
+ * contain complete supported 7-bit CSI/DCS/OSC/APC replies, not stream fragments,
+ * at most 4096 bytes.
+ * Titles are UTF-8 without C0, DEL, or C1 controls, at most 4091 bytes.
+ * Program status reports do not depend on detected support; terminals ignore
+ * OSC 7501 they do not implement. OT_CAP_PROGRAM_STATUS reports a query reply.
+ * All output uses ordinary capacity and stays behind earlier raw/frame bytes,
+ * including copied tickets. Setup enables detected features after screen selection.
+ * Admission failure changes neither terminal state nor accepted output.
+ * Zero Kitty flags disable; other flags apply when support is detected. Mouse
+ * and Kitty intent survive suspend/resume. bytes may be NULL only for zero length. */
+ot_status ot_session_control(
+    ot_context *context,
+    const ot_handle *session,
+    const ot_session_control_options *options,
+    const uint8_t *bytes,
+    uint32_t byte_count);
+ot_status ot_session_get_capabilities(
+    ot_context *context,
+    const ot_handle *session,
+    ot_session_capabilities *out_capabilities);
+
+/* Write or clear terminal clipboard selection 0..3 (clipboard/primary/select/secondary).
+ * Empty bytes clear the selection. Requires an active terminal. Uses ordinary output
+ * capacity behind earlier raw/frame bytes. Unsupported capability or rejected output
+ * returns out_written=0 without accepting bytes. Payloads retain the terminal's u32 byte limit.
+ * bytes may be NULL only for zero length; all input is consumed during this call. */
+ot_status ot_session_clipboard(
+    ot_context *context,
+    const ot_handle *session,
+    uint32_t target,
+    const uint8_t *bytes,
+    uint32_t byte_count,
+    uint32_t *out_written);
+
+/* Palette queries are bounded, validated OSC query packets admitted through
+ * ot_session_control. Palette publication copies up to 256 literal RGBA colors;
+ * every channel must be 0..255. All operations require an active terminal. */
+ot_status ot_session_set_palette_state(ot_context *, const ot_handle *,
+    const uint16_t *palette, uint32_t color_count, const uint16_t *foreground,
+    const uint16_t *background, uint32_t epoch);
+
+/* Notifications reuse terminal protocol selection and ordinary output capacity.
+ * Unsupported capability, text that is not UTF-8, or rejected output returns
+ * out_written=0; C0, DEL, and C1 controls in the text become spaces. Message and
+ * optional title are consumed only during this call; NULL requires zero length. */
+ot_status ot_session_notification(ot_context *, const ot_handle *,
+    const uint8_t *message, uint32_t message_len, const uint8_t *title,
+    uint32_t title_len, uint32_t *out_written);
+
+/* Run bounded owner-thread work without sleeping or sampling a clock.
+ * now_ns must be monotonic across accepted pumps and Kitty polls; equal samples
+ * are valid. work_budget must be positive;
+ * one unit visits one image entry, emits at most OT_SESSION_CONTROL_PACKET_BYTES,
+ * or advances one lifecycle step. AGAIN needs another turn, OUTPUT_PENDING needs
+ * output completion, and WAIT_UNTIL needs a clock turn at deadline_ns. Cursor
+ * delays start at the first pump observing completed restoration output.
+ * The first wait requires time range for both cursor waits. Later retry times
+ * must leave room for the final wait. Exhausted clock range returns
+ * OT_INVALID_ARGUMENT; a host with no valid later time must cancel explicitly.
+ * Each accepted pump also visits at most eight Kitty file leases and can unlink
+ * expired files through Context I/O, even while terminal output is pending.
+ * WAIT_UNTIL describes lifecycle waits; Kitty expiry still requires regular polls.
+ * No second frame is accepted or implicitly retried by this operation. */
+ot_status ot_session_pump(
+    ot_context *context,
+    const ot_handle *session,
+    uint64_t now_ns,
+    uint32_t work_budget,
+    ot_session_pump_result *out_result);
+
+/* Parse terminal input into events written to caller-owned records and payload.
+ * bytes may be NULL only when byte_count is zero; zero bytes only resolves the
+ * timeout. now_ns is a host monotonic clock in nanoseconds that must not go
+ * backwards across feeds; it is independent of the pump clock. capacity must be
+ * at least OT_INPUT_EVENTS_MIN and payload_capacity at least
+ * OT_INPUT_PAYLOAD_BYTES_MIN; the call consumes input until either runs low and
+ * reports consumed. A bracketed paste arrives as one or more PASTE records from
+ * START to END; a start marker cut by the timeout waits for a feed that begins with its
+ * rest and more bytes. Records and payload are borrowed for the call and never retained.
+ * bytes, records, payload, and out_drain must not overlap.
+ * Accepted in any open session state; closing, closed, failed, and cancelled
+ * sessions reject. A rejected call leaves out_drain, the records, and parser
+ * state unchanged. No allocation, no I/O. */
+ot_status ot_session_input_feed(
+    ot_context *context,
+    const ot_handle *session,
+    const uint8_t *bytes,
+    uint32_t byte_count,
+    uint64_t now_ns,
+    ot_input_event *records,
+    uint32_t capacity,
+    uint8_t *payload,
+    uint32_t payload_capacity,
+    ot_input_drain *out_drain);
+
+/* flags is a combination of OT_INPUT_EXPECT_* bits; other bits must be zero.
+ * Set REPLIES while any query is outstanding, including the capability queries
+ * that setup publishes. It keeps a partial CSI reply waiting past the timeout.
+ * CURSOR_POSITION, which implies REPLIES, marks a cursor position request: it
+ * makes a complete CSI 1 ; N R (N >= 2) a CURSOR_POSITION reply instead of a
+ * modified F3 key. KITTY_KEYBOARD keeps a partial Kitty key waiting and makes
+ * CSI R and CSI 1 ; N R replies, since the Kitty protocol sends F3 as CSI 13 ~;
+ * a session with a renderer applies its terminal's negotiated state instead.
+ * SENTINEL, which implies REPLIES, means that a DA1 reply (CSI ? ... c) ends the
+ * outstanding queries; clear it when that reply arrives. While it is set, a
+ * partial reply waits without a deadline: an OSC, DCS, or APC string that begins
+ * like one (OSC and a digit, DCS and > or a digit, APC and G), a bare CSI, OSC,
+ * DCS, or APC introducer, and a CSI of digits. A held string continues only
+ * while it matches a reply prefix, and a CSI that timed out completes only as a
+ * reply; another byte ends either one and is typed. A lone Escape still times
+ * out, and a reply that follows it is not typed; if what follows that Escape is
+ * cut before it matches a reply, its introducer is typed. KEEP_REPLY also keeps such a CSI.
+ * ESCAPE_PREFIX, which implies KITTY_KEYBOARD, means the terminal confirmed
+ * Kitty disambiguate or report-all keys, so no unit has a deadline. A raw ESC and the byte after it in the same
+ * feed are Alt and that key as without the flag; a raw ESC that ends a feed is the Escape key at once. If the next
+ * feed, however late, begins with [ and a byte that begins a CSI such a terminal sends (a digit, ?, >, <, or one of
+ * ABCDEFHIOPQS), the CSI is kept whole and is never a key; _G begins a Kitty graphics reply, kept whole once that
+ * feed matches its key= prefix and typed otherwise; other bytes are typed. With SENTINEL, an OSC, DCS, or APC
+ * introducer or a lone [ after that Escape is recovered as after a timeout until SENTINEL is cleared.
+ * A session with a renderer sets it itself once the terminal answers the CSI ? u
+ * query that follows its current push (only with OT_TERMINAL_REPLY_SENTINEL).
+ * Changing flags emits nothing; the next feed resolves a unit that may no longer wait. */
+ot_status ot_session_input_expect(ot_context *context, const ot_handle *session, uint32_t flags);
+
+#define OT_INPUT_RESET_KEEP_REPLY UINT32_C(1)
+
+/* Drop any partial unit and mouse button state. Expectations are kept. flags is
+ * 0 or OT_INPUT_RESET_KEEP_REPLY. Call with KEEP_REPLY after feeding the input
+ * drained on resume: then a partial CSI unit that may begin a reply survives
+ * while REPLIES is set, and waits for its rest without a deadline. */
+ot_status ot_session_input_reset(ot_context *context, const ot_handle *session, uint32_t flags);
+
+/* Maximum ordinary atomic write in an empty queue, excluding control reservations
+ * and bounded by both chunk storage and span slots, at most UINT32_MAX bytes.
+ * This is not current free capacity; pending output can still reject a smaller
+ * write. Failure leaves out_bytes unchanged. */
+ot_status ot_session_get_write_limit(ot_context *context, const ot_handle *session, uint64_t *out_bytes);
+
+/* Copy the complete write or reject it without changing accepted output.
+ * bytes may be NULL only when byte_count is zero. Queued and unacknowledged
+ * bytes share the finite limits. The caller retains no native memory borrow. */
+ot_status ot_session_write(
+    ot_context *context,
+    const ot_handle *session,
+    const uint8_t *bytes,
+    uint32_t byte_count);
+
+/* Copy at most capacity bytes in write order. bytes may be NULL only for zero
+ * capacity. A successful empty read returns a zero byte_count and request_id.
+ * Failure leaves both outputs unchanged. The next read requires completion of
+ * the previous ticket. Copied bytes remain valid after cancellation/destruction. */
+ot_status ot_session_read_output(
+    ot_context *context,
+    const ot_handle *session,
+    uint8_t *bytes,
+    uint32_t capacity,
+    ot_output_ticket *out_ticket);
+
+/* Borrow the next queued span for one synchronous writer call, at most max_bytes
+ * (which must be positive). The callback returns the delivered prefix length,
+ * zero for backpressure, or -1 for failure. It must not retain bytes, report
+ * buffered-but-unwritten bytes as delivered, or reenter mutating Context calls.
+ * No callback or user_data is retained. A pending copy ticket returns OT_OUTPUT_BUSY.
+ * Partial writes keep the remaining bytes queued. Failure or an invalid count
+ * stops transport with OT_OUTPUT_FAILED; bytes are never replayed. Successful
+ * writes publish frame presentation at the same endpoint as complete_output.
+ * out_written is zero for an empty/closed queue or backpressure, and is unchanged
+ * on error. A nonempty writer call can block only as long as its writer does. */
+typedef int64_t (*ot_output_write_callback)(void *user_data, const uint8_t *bytes, uint32_t byte_count);
+ot_status ot_session_drain_output(
+    ot_context *context,
+    const ot_handle *session,
+    uint32_t max_bytes,
+    uint32_t *out_written,
+    void *user_data,
+    ot_output_write_callback writer);
+
+/* Deliver directly to process stdout through Context I/O, without a host byte
+ * buffer or completion ticket. Same completion/failure rules as drain_output.
+ * max_bytes must be at least four for a complete UTF-8 scalar on Windows consoles;
+ * console writes preserve the code page and may span queue chunk boundaries.
+ * An overlapped or unrecognized Windows byte handle returns OT_UNSUPPORTED_RESOURCE
+ * before consuming output; use the host writer for that handle. An incomplete
+ * console scalar followed by a byte that cannot continue it, with no room for more
+ * input, or while new writes are disabled, returns OT_INVALID_ARGUMENT with its
+ * bytes retained for another delivery method.
+ * Nonblocking stdout pressure returns zero; retry on a later turn. A blocking
+ * stdout can block this call. This operation neither closes nor reconfigures stdout. */
+ot_status ot_session_drain_stdout(
+    ot_context *context,
+    const ot_handle *session,
+    uint32_t max_bytes,
+    uint32_t *out_written);
+
+/* Write process stdout from a native thread that the Session owns, so this call
+ * never waits in write(2) on a slow terminal.
+ * wait=0: if the running copy has ended, complete its bytes as complete_output
+ *   would; then, when max_bytes is positive and output is queued, copy the next
+ *   prefix (at most max_bytes and 64 KiB) to the thread and start it. max_bytes
+ *   zero only collects.
+ * wait=1 (process exit only): never starts a copy. Waits for the running copy
+ *   without a limit and completes it. A copy the thread has not picked up within
+ *   100 ms is taken back unwritten, stays queued for drain_stdout, and the thread
+ *   is stopped. With no copy running, or no thread: OT_OK and OT_STDOUT_IDLE.
+ * out_written is the bytes this call completed; out_state is OT_STDOUT_IN_FLIGHT
+ * when a copy is still running on return, else OT_STDOUT_IDLE. A failed write
+ * returns OT_OUTPUT_FAILED and stops the transport without replay; outputs are
+ * then unchanged. wait above 1 or a null output: OT_INVALID_ARGUMENT. A pending
+ * read_output ticket: OT_OUTPUT_BUSY. Before consuming output, wait=0 returns
+ * OT_UNSUPPORTED_RESOURCE when stdout is not a terminal, on platforms without the
+ * writer (it runs on Linux and macOS), or when the thread cannot start: use
+ * drain_stdout.
+ * While a copy is posted, read_output, drain_output and drain_stdout return
+ * OT_OUTPUT_BUSY and complete_output returns OT_STALE_OUTPUT for any ticket.
+ * Cancel and destroy never wait for a running copy. The thread calls nothing
+ * back and keeps the library loaded until process exit. */
+ot_status ot_session_post_stdout(
+    ot_context *context,
+    const ot_handle *session,
+    uint32_t max_bytes,
+    uint32_t wait,
+    uint32_t *out_state,
+    uint32_t *out_written);
+
+/* success must be 0 or 1. Failure stops the transport without replaying bytes.
+ * Wrong-session, stale, altered, and repeated tickets do not consume output. */
+ot_status ot_session_complete_output(
+    ot_context *context,
+    const ot_handle *session,
+    const ot_output_ticket *ticket,
+    uint32_t success);
+
+/* Stop new writes. Queued output and terminal restoration must finish before
+ * the session becomes closed. Terminal-managed sessions require continued pumping.
+ * cancel explicitly discards pending output after transport disconnection.
+ * Neither operation waits or sleeps. */
+ot_status ot_session_close(ot_context *context, const ot_handle *session);
+/* A close past its deadline: begin closing if needed, then discard the output
+ * queued before the close, except the copy an outstanding ticket or stdout
+ * copy holds. Only that copy and terminal restoration remain; once restoration
+ * output is queued, this discards nothing. Continue pumping as after close. */
+ot_status ot_session_drop_output(ot_context *context, const ot_handle *session);
+/* Process-exit fallback: stop admission and visit one restoration work unit
+ * without cursor-settle waits. Returns OT_PUMP_AGAIN, OT_PUMP_OUTPUT_PENDING, or
+ * OT_PUMP_CLOSED. The host must still deliver and complete output in order.
+ * Never acknowledges or replays pending copies, and rejects failed transports.
+ * Normal asynchronous shutdown must use close and pump instead. */
+ot_status ot_session_pump_exit(ot_context *context, const ot_handle *session, uint32_t *out_status);
+/* Process-wide and best effort: discard input that the terminal queued on process stdin
+ * and the host has not read (tcflush TCIFLUSH, or FlushConsoleInputBuffer on Windows).
+ * Call it after restoration disables mouse reporting, so the shell does not receive
+ * stale reports. A no-op when stdin is not a terminal. Always returns OT_OK. */
+ot_status ot_terminal_flush_input(void);
+ot_status ot_session_cancel(ot_context *context, const ot_handle *session);
+ot_status ot_session_get_state(ot_context *context, const ot_handle *session, uint32_t *out_state);
+
+/* Pending output or an unrestored terminal prevents destruction unless cancelled.
+ * Context destruction follows the same rule. Successful destruction invalidates
+ * the session handle and all its tickets, but not caller-owned output copies. */
+ot_status ot_session_destroy(ot_context *context, const ot_handle *session);
+
+/* Host clipboard service owned by a Context. Distinct from ot_session_clipboard,
+ * which writes terminal OSC selection bytes. These calls return domain-specific
+ * uint8 codes, not ot_status. Create returns 0 or -1. The service is the Context's
+ * sole clipboard_service object: a second create returns -1 while one exists, even
+ * one shutting down. ot_context_destroy begins the service's shutdown and returns
+ * OT_CONTEXT_BUSY until it is ready. wayland_seat may be NULL only when its length
+ * is zero. Request, text, and result bytes are borrowed for the call. */
+#define OT_CLIPBOARD_OPERATION_PENDING UINT32_C(0)
+#define OT_CLIPBOARD_OPERATION_READ UINT32_C(1)
+#define OT_CLIPBOARD_OPERATION_EMPTY UINT32_C(2)
+#define OT_CLIPBOARD_OPERATION_WRITTEN UINT32_C(3)
+#define OT_CLIPBOARD_OPERATION_CLEARED UINT32_C(4)
+#define OT_CLIPBOARD_OPERATION_UNSUPPORTED UINT32_C(5)
+#define OT_CLIPBOARD_OPERATION_CANCELLED UINT32_C(6)
+#define OT_CLIPBOARD_OPERATION_TIMED_OUT UINT32_C(7)
+#define OT_CLIPBOARD_OPERATION_LIMIT_EXCEEDED UINT32_C(8)
+#define OT_CLIPBOARD_OPERATION_FAILED UINT32_C(9)
+#define OT_CLIPBOARD_OPERATION_INVALID_HANDLE UINT32_C(10)
+#define OT_CLIPBOARD_START_OK UINT32_C(0)
+#define OT_CLIPBOARD_START_INVALID_SERVICE UINT32_C(1)
+#define OT_CLIPBOARD_START_SHUTTING_DOWN UINT32_C(2)
+#define OT_CLIPBOARD_START_LIMIT_EXCEEDED UINT32_C(3)
+#define OT_CLIPBOARD_START_INVALID_ARGUMENT UINT32_C(4)
+#define OT_CLIPBOARD_START_OUT_OF_MEMORY UINT32_C(5)
+#define OT_CLIPBOARD_CANCEL_REQUESTED UINT32_C(0)
+#define OT_CLIPBOARD_CANCEL_ALREADY_TERMINAL UINT32_C(1)
+#define OT_CLIPBOARD_CANCEL_INVALID_HANDLE UINT32_C(2)
+#define OT_CLIPBOARD_COPY_OK UINT32_C(0)
+#define OT_CLIPBOARD_COPY_BUFFER_TOO_SMALL UINT32_C(1)
+#define OT_CLIPBOARD_COPY_INVALID_HANDLE UINT32_C(2)
+#define OT_CLIPBOARD_COPY_INVALID_STATE UINT32_C(3)
+#define OT_CLIPBOARD_COPY_INVALID_ARGUMENT UINT32_C(4)
+#define OT_CLIPBOARD_DESTROY_DESTROYED UINT32_C(0)
+#define OT_CLIPBOARD_DESTROY_NOT_READY UINT32_C(1)
+#define OT_CLIPBOARD_DESTROY_INVALID_HANDLE UINT32_C(2)
+#define OT_CLIPBOARD_SHUTDOWN_PENDING UINT32_C(0)
+#define OT_CLIPBOARD_SHUTDOWN_READY UINT32_C(1)
+#define OT_CLIPBOARD_SHUTDOWN_INVALID_HANDLE UINT32_C(2)
+
+int32_t ot_clipboard_service_create(
+    ot_context *context,
+    uint32_t max_operations,
+    uint32_t max_provider_transfers,
+    const uint8_t *wayland_seat,
+    uint32_t wayland_seat_length);
+uint8_t ot_clipboard_service_begin_shutdown(ot_context *context);
+uint8_t ot_clipboard_service_poll_shutdown(ot_context *context);
+uint8_t ot_clipboard_service_destroy(ot_context *context);
+uint8_t ot_clipboard_service_drain(ot_context *context);
+uint8_t ot_clipboard_read_operation_start(
+    ot_context *context,
+    const uint8_t *request, uint32_t request_length,
+    uint8_t selection,
+    uint32_t max_bytes, uint32_t max_image_pixels, uint32_t max_conversion_bytes,
+    uint32_t timeout_ms,
+    ot_handle *out_operation);
+uint8_t ot_clipboard_write_operation_start(
+    ot_context *context,
+    const uint8_t *text, uint32_t text_length,
+    uint8_t selection, uint32_t timeout_ms,
+    ot_handle *out_operation);
+uint8_t ot_clipboard_clear_operation_start(
+    ot_context *context,
+    uint8_t selection, uint32_t timeout_ms,
+    ot_handle *out_operation);
+uint8_t ot_clipboard_operation_poll(ot_context *context, const ot_handle *operation);
+uint8_t ot_clipboard_operation_cancel(ot_context *context, const ot_handle *operation);
+uint8_t ot_clipboard_operation_result_mime_length(
+    ot_context *context, const ot_handle *operation, uint32_t *out_length);
+uint8_t ot_clipboard_operation_result_mime_copy(
+    ot_context *context, const ot_handle *operation, uint8_t *out_bytes, uint32_t capacity);
+uint8_t ot_clipboard_operation_result_data_length(
+    ot_context *context, const ot_handle *operation, uint32_t *out_length);
+uint8_t ot_clipboard_operation_result_data_copy(
+    ot_context *context, const ot_handle *operation, uint8_t *out_bytes, uint32_t capacity);
+uint8_t ot_clipboard_operation_result_error_code(
+    ot_context *context, const ot_handle *operation, uint32_t *out_error_code);
+uint8_t ot_clipboard_operation_result_diagnostic_length(
+    ot_context *context, const ot_handle *operation, uint32_t *out_length);
+uint8_t ot_clipboard_operation_result_diagnostic_copy(
+    ot_context *context, const ot_handle *operation, uint8_t *out_bytes, uint32_t capacity);
+uint8_t ot_clipboard_operation_destroy(ot_context *context, const ot_handle *operation);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif