feat(drawlist): add BLIT_RECT opcode with overlap-safe execution

docs/ABI_REFERENCE.md

@@ -80,11 +80,12 @@ Drawlist v1 and event batch v1 are specified by:
 - `docs/modules/DRAWLIST_FORMAT_AND_PARSER.md`
 - `docs/modules/EVENT_SYSTEM_AND_PACKED_EVENT_ABI.md`
 
-## Drawlist v1
+## Drawlist v1/v2
 
 Drawlist v1 includes the `SET_CURSOR` opcode (opcode 7). All v1 opcodes remain
-unchanged. The engine accepts only drawlists whose header version is
-`ZR_DRAWLIST_VERSION_V1`.
+unchanged. Drawlist v2 adds `ZR_DL_OP_BLIT_RECT` (opcode 14). The engine
+accepts drawlists whose header version is `ZR_DRAWLIST_VERSION_V1` or
+`ZR_DRAWLIST_VERSION_V2`.
 
 ```c
 typedef struct zr_dl_cmd_set_cursor_t {

docs/VERSION_PINS.md

@@ -21,8 +21,12 @@ Zireael is pre-alpha. ABI and wire-format details may change between releases.
 ## Drawlist
 
 - `ZR_DRAWLIST_VERSION_V1 = 1`
+- `ZR_DRAWLIST_VERSION_V2 = 2`
 
-Only drawlist v1 is supported.
+Supported drawlist versions are v1 and v2. `ZR_DL_OP_BLIT_RECT` is a v2
+opcode.
+Drawlist v1 remains the baseline protocol; v2 is additive and only adds
+`ZR_DL_OP_BLIT_RECT` (BLIT_RECT).
 
 ## Event Batch
 

docs/abi/c-abi-reference.md

@@ -18,17 +18,18 @@ Binary format headers:
 - `zr_drawlist.h` - drawlist structs/opcodes
 - `zr_event.h` - packed event batch structs/types
 
-Drawlist v1 adds:
+Drawlist protocol additions:
 
 - `ZR_DL_OP_DRAW_CANVAS` command payload (`zr_dl_cmd_draw_canvas_t`)
 - sub-cell selector enum (`zr_blitter_t`)
 - `ZR_DL_OP_DRAW_IMAGE` command payload (`zr_dl_cmd_draw_image_t`)
+- `ZR_DL_OP_BLIT_RECT` command payload (`zr_dl_cmd_blit_rect_t`, drawlist v2)
 - drawlist v1 image numeric fields in payload:
   - `format`: `0=RGBA`, `1=PNG`
   - `protocol`: `0=auto`, `1=kitty`, `2=sixel`, `3=iterm2`
   - `fit_mode`: `0=fill`, `1=contain`, `2=cover`
 
-Current drawlist version: `ZR_DRAWLIST_VERSION_V1`.
+Supported drawlist versions: `ZR_DRAWLIST_VERSION_V1`, `ZR_DRAWLIST_VERSION_V2`.
 
 ## Result Model
 
@@ -191,7 +192,8 @@ Notes:
 From `zr_engine_config_t` at create time:
 
 - `requested_engine_abi_*` must match pinned ABI macros.
-- `requested_drawlist_version` must be exactly `ZR_DRAWLIST_VERSION_V1`.
+- `requested_drawlist_version` must be `ZR_DRAWLIST_VERSION_V1` or `ZR_DRAWLIST_VERSION_V2`.
+  Use `ZR_DRAWLIST_VERSION_V2` when emitting `ZR_DL_OP_BLIT_RECT`.
 - `requested_event_batch_version` must match pinned event version.
 - `cap_force_flags` / `cap_suppress_flags` apply deterministic capability
   overrides (`suppress` wins over `force`).
@@ -205,7 +207,7 @@ zr_engine_config_t cfg = zr_engine_config_default();
 cfg.requested_engine_abi_major = ZR_ENGINE_ABI_MAJOR;
 cfg.requested_engine_abi_minor = ZR_ENGINE_ABI_MINOR;
 cfg.requested_engine_abi_patch = ZR_ENGINE_ABI_PATCH;
-cfg.requested_drawlist_version = ZR_DRAWLIST_VERSION_V1;
+cfg.requested_drawlist_version = ZR_DRAWLIST_VERSION_V2;
 cfg.requested_event_batch_version = ZR_EVENT_BATCH_VERSION_V1;
 
 zr_engine_t* e = NULL;

docs/abi/drawlist-format.md

@@ -1,14 +1,14 @@
-# Drawlist Format (ZRDL v1)
+# Drawlist Format (ZRDL v1/v2)
 
-ZRDL v1 is a 64-byte header plus a command stream. String/blob tables are no
-longer carried per frame.
+ZRDL v1 and v2 share the same 64-byte header layout plus a command stream.
+String/blob tables are no longer carried per frame.
 
 ## Header
 
 All header fields are little-endian `u32`.
 
 - `magic`: `0x4C44525A` (`ZRDL`)
-- `version`: `ZR_DRAWLIST_VERSION_V1` (`1`)
+- `version`: `ZR_DRAWLIST_VERSION_V1` (`1`) or `ZR_DRAWLIST_VERSION_V2` (`2`)
 - `header_size`: `64`
 - `total_size`: full buffer size
 - `cmd_offset`: offset to command stream (normally `64`)
@@ -49,6 +49,7 @@ Commands are 4-byte aligned.
 - `11` `ZR_DL_OP_FREE_STRING` (size `12`)
 - `12` `ZR_DL_OP_DEF_BLOB` (base size `16` + aligned bytes)
 - `13` `ZR_DL_OP_FREE_BLOB` (size `12`)
+- `14` `ZR_DL_OP_BLIT_RECT` (size `32`, **v2 only**)
 
 ## Persistent Resource Semantics
 

docs/abi/versioning.md

@@ -20,7 +20,7 @@ Current pins:
 - Library: v1.3.8
 - Lifecycle: alpha
 - Engine ABI: v1.2.0
-- Drawlist formats: v1
+- Drawlist formats: v1, v2
 - Event batch format: v1
 
 ## Compatibility Expectations
@@ -31,7 +31,7 @@ Negotiation rules (v1 line):
 
 - engine ABI request must match pinned ABI exactly
 - event batch version must match pinned event version exactly
-- drawlist request must match `ZR_DRAWLIST_VERSION_V1`
+- drawlist request must be `ZR_DRAWLIST_VERSION_V1` or `ZR_DRAWLIST_VERSION_V2`
 
 Unsupported requests fail with `ZR_ERR_UNSUPPORTED`.
 
@@ -49,6 +49,10 @@ Recent ABI-minor additions in `v1.2.0`:
 - extended `zr_terminal_caps_t` fields (`terminal_id`, cap flags/masks)
 - create/runtime capability override masks (`cap_force_flags`, `cap_suppress_flags`)
 
+Recent drawlist-format addition in `v2`:
+
+- `ZR_DL_OP_BLIT_RECT` opcode for overlap-safe cell rectangle copies
+
 Breaking examples:
 
 - changing existing struct field meaning without version gating

docs/user-guide/rendering-model.md

@@ -36,6 +36,9 @@ Drawlist v1 supports explicit cursor control (`ZR_DL_OP_SET_CURSOR`).
 - cursor state is part of terminal emission behavior
 - it does not mutate glyph content in framebuffer cells
 
+Drawlist v2 adds overlap-safe framebuffer rectangle copies
+(`ZR_DL_OP_BLIT_RECT`) to express scroll/move-style updates without redraw.
+
 ## Output Buffering and Flush
 
 - Output is assembled into an internal bounded buffer.

include/zr/zr_drawlist.h

@@ -1,5 +1,5 @@
 /*
-  include/zr/zr_drawlist.h — Drawlist ABI structs (v1).
+  include/zr/zr_drawlist.h — Drawlist ABI structs (v1/v2).
 
   Why: Defines the little-endian drawlist command stream used by wrappers to
   drive rendering through engine_submit_drawlist().
@@ -63,7 +63,8 @@ typedef enum zr_dl_opcode_t {
   ZR_DL_OP_DEF_STRING = 10,
   ZR_DL_OP_FREE_STRING = 11,
   ZR_DL_OP_DEF_BLOB = 12,
-  ZR_DL_OP_FREE_BLOB = 13
+  ZR_DL_OP_FREE_BLOB = 13,
+  ZR_DL_OP_BLIT_RECT = 14
 } zr_dl_opcode_t;
 
 /*
@@ -178,6 +179,15 @@ typedef struct zr_dl_cmd_push_clip_t {
   int32_t h;
 } zr_dl_cmd_push_clip_t;
 
+typedef struct zr_dl_cmd_blit_rect_t {
+  int32_t src_x;
+  int32_t src_y;
+  int32_t w;
+  int32_t h;
+  int32_t dst_x;
+  int32_t dst_y;
+} zr_dl_cmd_blit_rect_t;
+
 typedef struct zr_dl_cmd_draw_text_run_t {
   int32_t x;
   int32_t y;

include/zr/zr_version.h

@@ -14,8 +14,7 @@
 */
 #if defined(ZR_LIBRARY_VERSION_MAJOR) || defined(ZR_LIBRARY_VERSION_MINOR) || defined(ZR_LIBRARY_VERSION_PATCH) ||     \
     defined(ZR_ENGINE_ABI_MAJOR) || defined(ZR_ENGINE_ABI_MINOR) || defined(ZR_ENGINE_ABI_PATCH) ||                    \
-    defined(ZR_DRAWLIST_VERSION_V1) ||                                                                             \
-    defined(ZR_EVENT_BATCH_VERSION_V1)
+    defined(ZR_DRAWLIST_VERSION_V1) || defined(ZR_DRAWLIST_VERSION_V2) || defined(ZR_EVENT_BATCH_VERSION_V1)
 #error "Zireael version pins are locked; do not override ZR_*_VERSION_* macros."
 #endif
 
@@ -29,8 +28,9 @@
 #define ZR_ENGINE_ABI_MINOR (2u)
 #define ZR_ENGINE_ABI_PATCH (0u)
 
-/* Drawlist binary format version (current protocol baseline). */
+/* Drawlist binary format versions. */
 #define ZR_DRAWLIST_VERSION_V1 (1u)
+#define ZR_DRAWLIST_VERSION_V2 (2u)
 
 /* Packed event batch binary format versions. */
 #define ZR_EVENT_BATCH_VERSION_V1 (1u)

scripts/check_version_pins.py

@@ -49,6 +49,7 @@ def main() -> int:
     "ZR_ENGINE_ABI_MINOR",
     "ZR_ENGINE_ABI_PATCH",
     "ZR_DRAWLIST_VERSION_V1",
+    "ZR_DRAWLIST_VERSION_V2",
     "ZR_EVENT_BATCH_VERSION_V1",
   ]
 

src/core/zr_config.c

@@ -139,8 +139,12 @@ zr_result_t zr_engine_config_validate(const zr_engine_config_t* cfg) {
     return ZR_ERR_UNSUPPORTED;
   }
 
-  if (cfg->requested_drawlist_version != ZR_DRAWLIST_VERSION_V1 ||
-      cfg->requested_event_batch_version != ZR_EVENT_BATCH_VERSION_V1) {
+  if (cfg->requested_drawlist_version != ZR_DRAWLIST_VERSION_V1 &&
+      cfg->requested_drawlist_version != ZR_DRAWLIST_VERSION_V2) {
+    return ZR_ERR_UNSUPPORTED;
+  }
+
+  if (cfg->requested_event_batch_version != ZR_EVENT_BATCH_VERSION_V1) {
     return ZR_ERR_UNSUPPORTED;
   }