Merge pull request #190 from RtlZeroMemory/codex/remove-v1-cursor

refactor(cursor): remove v1 cursor paths and make native cursor default

Author: RtlZeroMemory

CHANGELOG.md

@@ -18,6 +18,7 @@ The format is based on Keep a Changelog and the project follows Semantic Version
 
 ### Features
 
+- **cursor/protocol**: Removed cursor v1/v2 toggle flags (`useV2Cursor`, `useDrawlistV2`); native cursor protocol is now the default runtime path and backend drawlist version `1` is rejected.
 - **runtime**: Widget protocol registry centralizes widget capability detection.
 - **events**: Extended `RoutedAction` union (`toggle`, `select`, `rowPress`, `change`, `activate`, `scroll`) now surfaces through `UiEvent`.
 - **overlays**: Unified overlay system; dropdowns and toasts register in `LayerRegistry`.

docs/backend/engine-config.md

@@ -27,7 +27,6 @@ type AppConfig = Readonly<{
   fpsCap?: number;
   maxEventBytes?: number;
   maxDrawlistBytes?: number;
-  useV2Cursor?: boolean;
   drawlistValidateParams?: boolean;
   drawlistReuseOutputBuffer?: boolean;
   drawlistEncodedStringCacheCap?: number;
@@ -87,35 +86,6 @@ config: {
 }
 ```
 
-### useV2Cursor
-
-| Detail   | Value |
-|----------|-------|
-| Type     | `boolean` |
-| Default  | `false` |
-
-Enables the v2 cursor protocol, which adds a `SET_CURSOR` command to the
-drawlist. When enabled, the native engine can set the terminal cursor position
-and shape directly, which is required for proper cursor rendering in `Input`
-widgets.
-
-Both the app config and the backend must agree on this setting. If you set
-`useV2Cursor: true` in the app config, the backend must also be created with
-drawlist v2+ support, or the runtime will throw a validation error.
-
-The default Node/Bun backend supports cursor v2 (drawlist v5 by default). You
-only need to change backend configuration if you intentionally force an older
-drawlist version.
-
-```typescript
-import { createNodeApp } from "@rezi-ui/node";
-
-const app = createNodeApp({
-  initialState: {},
-  config: { useV2Cursor: true },
-});
-```
-
 ### drawlistValidateParams
 
 | Detail   | Value |
@@ -207,7 +177,6 @@ config: {
 | `fpsCap`                        | `60`          |
 | `maxEventBytes`                 | `1048576` (1 MiB) |
 | `maxDrawlistBytes`              | `2097152` (2 MiB) |
-| `useV2Cursor`                   | `false`       |
 | `drawlistValidateParams`        | `true` (app runtime default) |
 | `drawlistReuseOutputBuffer`     | `true`        |
 | `drawlistEncodedStringCacheCap` | `1024`        |

docs/backend/node.md

@@ -17,15 +17,13 @@ const app = createNodeApp({
     executionMode: "auto",
     fpsCap: 60,
     maxEventBytes: 1 << 20,
-    useV2Cursor: false,
   },
 });
 ```
 
 `createNodeApp` is the recommended path because it keeps core/backend config
 knobs aligned:
 
-- `useV2Cursor` and drawlist v2 are paired automatically.
 - `maxEventBytes` is applied to both app parsing and backend transport buffers.
 - `fpsCap` is the single scheduling knob.
 - `executionMode: "auto"` resolves to inline when `fpsCap <= 30`, worker otherwise.

docs/getting-started/quickstart.md

@@ -106,7 +106,7 @@ const app = createNodeApp<State>({ initialState: { count: 0 } });
 
 - `createNodeApp<State>` creates a typed application instance with a compatible Node/Bun backend
 - `initialState` provides the starting application state
-- An optional `config` object controls runtime knobs (`fpsCap`, `maxEventBytes`, `useV2Cursor`)
+- An optional `config` object controls runtime knobs (`fpsCap`, `maxEventBytes`, `maxDrawlistBytes`)
 
 ### Defining the View
 

docs/guide/debugging.md

@@ -69,7 +69,7 @@ const app = createAppWithInspectorOverlay({
 
 Overlay sections include:
 - Focus summary (`focusedId`, active zone, active trap)
-- Cursor target summary (position, shape, blink intent when cursor v2 is active)
+- Cursor target summary (position, shape, blink intent)
 - Damage + frame summary (`mode`, rect/cell counts, commit/layout/incremental state)
 - Frame timing rows (`drawlistBytes`, `diffBytesEmitted`, `usDrawlist`, `usDiff`, `usWrite`)
 - Event routing breadcrumbs (last event kind, keybindings vs widget routing path, last action)

docs/guide/lifecycle-and-updates.md

@@ -14,7 +14,7 @@ type State = { count: number };
 
 const app = createNodeApp<State>({
   initialState: { count: 0 },
-  config: { fpsCap: 60, maxEventBytes: 1 << 20, useV2Cursor: false },
+  config: { fpsCap: 30, maxEventBytes: 1 << 20 },
 });
 
 app.view((state) => ui.text(`Count: ${state.count}`));

docs/guide/record-replay.md

@@ -35,7 +35,7 @@ Top-level required fields:
 | `maxDrawlistBytes` | `number` (non-negative integer) |
 | `maxFrames` | `number` (non-negative integer) |
 | `fpsCap` | `number` (positive integer) |
-| `cursorProtocolVersion` | `1 \| 2` |
+| `cursorProtocolVersion` | `2` |
 
 ### `capsSnapshot`
 
@@ -44,7 +44,7 @@ Top-level required fields:
 | `terminalCaps` | `TerminalCaps \| null` |
 | `backendCaps.maxEventBytes` | `number` (non-negative integer) |
 | `backendCaps.fpsCap` | `number` (positive integer) |
-| `backendCaps.cursorProtocolVersion` | `1 \| 2` |
+| `backendCaps.cursorProtocolVersion` | `2` |
 
 ### `timingModel`
 

docs/packages/node.md

@@ -40,15 +40,13 @@ const app = createNodeApp({
     executionMode: "auto",
     fpsCap: 60,
     maxEventBytes: 1 << 20,
-    useV2Cursor: false,
   },
 });
 ```
 
 `createNodeApp` is the default path because it keeps core/backend config in
 lockstep:
 
-- `useV2Cursor` <-> drawlist v2
 - app/backend `maxEventBytes`
 - app/backend `fpsCap`
 

docs/protocol/cursor-v2.md

@@ -0,0 +1,79 @@
+# Cursor Protocol
+
+Rezi uses the **SET_CURSOR** command to control the terminal cursor position,
+visibility, shape, and blink state from the TypeScript renderer.
+
+## SET_CURSOR command
+
+**Opcode:** 7 (`OP_SET_CURSOR`)
+
+**Total size:** 20 bytes (8-byte command header + 12-byte payload)
+
+### Payload layout
+
+| Offset | Size | Type | Field | Description |
+|--------|------|------|-------|-------------|
+| 8 | 4 | `i32` | `x` | 0-based cell column; `-1` = leave unchanged |
+| 12 | 4 | `i32` | `y` | 0-based cell row; `-1` = leave unchanged |
+| 16 | 1 | `u8` | `shape` | Cursor shape constant |
+| 17 | 1 | `u8` | `visible` | `1` = show, `0` = hide |
+| 18 | 1 | `u8` | `blink` | `1` = blinking, `0` = steady |
+| 19 | 1 | `u8` | `reserved0` | Must be `0` |
+
+The command is 20 bytes total, which is 4-byte aligned (no padding needed).
+
+### Special values
+
+- **x = -1 or y = -1:** The engine leaves that coordinate unchanged from the previous frame.
+- **visible = 0:** Hides the cursor until a later command sets `visible = 1`.
+
+## Cursor shape constants
+
+The `shape` field accepts the following values, defined in `packages/core/src/abi.ts`:
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `ZR_CURSOR_SHAPE_BLOCK` | `0` | Block cursor (full cell) |
+| `ZR_CURSOR_SHAPE_UNDERLINE` | `1` | Underline cursor (bottom of cell) |
+| `ZR_CURSOR_SHAPE_BAR` | `2` | Bar cursor (left edge of cell) |
+
+The TypeScript type is:
+
+```typescript
+export type CursorShape = 0 | 1 | 2;
+```
+
+!!! note
+    If the terminal does not support cursor shaping, the engine ignores `shape`
+    and uses the terminal default cursor appearance.
+
+## Runtime behavior
+
+- The widget renderer resolves cursor targets from focused inputs/editors and
+  emits `SET_CURSOR` when visible.
+- If no widget requests a cursor, the renderer emits a hide cursor command.
+- Node/Bun defaults to drawlist v5, so cursor protocol support is available by
+  default.
+
+## Default cursor shapes
+
+The framework provides context-specific defaults in `CURSOR_DEFAULTS`:
+
+| Context | Shape | Blink | Use case |
+|---------|-------|-------|----------|
+| `input` | `2` (BAR) | `true` | Text input fields |
+| `selection` | `0` (BLOCK) | `true` | Selection-mode cursors |
+| `staticUnderline` | `1` (UNDERLINE) | `false` | Non-blinking indicator |
+
+```typescript
+import { CURSOR_DEFAULTS } from "@rezi-ui/core";
+
+// CURSOR_DEFAULTS.input       => { shape: 2, blink: true }
+// CURSOR_DEFAULTS.selection   => { shape: 0, blink: true }
+// CURSOR_DEFAULTS.staticUnderline => { shape: 1, blink: false }
+```
+
+## See also
+
+- [Drawlists (ZRDL)](zrdl.md) -- full ZRDL format reference
+- [Versioning](versioning.md) -- protocol and ABI version table