fix(cursor): address PR review follow-up issues

Author: RtlZeroMemory

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 },
+  config: { fpsCap: 30, maxEventBytes: 1 << 20 },
 });
 
 app.view((state) => ui.text(`Count: ${state.count}`));

docs/protocol/versioning.md

@@ -122,7 +122,7 @@ Both the builder and the engine perform version checks:
 
 1. The builder writes the correct magic and version into the header at build time.
 2. The version is determined by the selected builder version.
-3. `createApp()` validates backend drawlist version markers and requires version `>= 2`.
+3. `createApp()` validates the backend `drawlistVersion` and requires version `>= 2`.
 
 **Engine side (C):**
 

packages/core/src/app/rawRenderer.ts

@@ -57,7 +57,7 @@ export class RawRenderer {
     opts: Readonly<{
       backend: RuntimeBackend;
       builder?: DrawlistBuilderV1;
-      drawlistVersion?: 1 | 2 | 3 | 4 | 5;
+      drawlistVersion?: 2 | 3 | 4 | 5;
       maxDrawlistBytes?: number;
       drawlistValidateParams?: boolean;
       drawlistReuseOutputBuffer?: boolean;
@@ -82,6 +82,18 @@ export class RawRenderer {
       return;
     }
     const drawlistVersion = opts.drawlistVersion ?? 2;
+    if (
+      drawlistVersion !== 2 &&
+      drawlistVersion !== 3 &&
+      drawlistVersion !== 4 &&
+      drawlistVersion !== 5
+    ) {
+      throw new Error(
+        `drawlistVersion ${String(
+          drawlistVersion,
+        )} is no longer supported; use drawlistVersion 2, 3, 4, or 5.`,
+      );
+    }
     if (drawlistVersion >= 3) {
       this.builder = createDrawlistBuilderV3({
         ...builderOpts,

packages/core/src/app/widgetRenderer.ts

@@ -825,7 +825,7 @@ export class WidgetRenderer<S> {
     opts: Readonly<{
       backend: RuntimeBackend;
       builder?: DrawlistBuilderV1 | DrawlistBuilderV2 | DrawlistBuilderV3;
-      drawlistVersion?: 1 | 2 | 3 | 4 | 5;
+      drawlistVersion?: 2 | 3 | 4 | 5;
       maxDrawlistBytes?: number;
       drawlistValidateParams?: boolean;
       drawlistReuseOutputBuffer?: boolean;
@@ -882,6 +882,18 @@ export class WidgetRenderer<S> {
       return;
     }
     const drawlistVersion = opts.drawlistVersion ?? 2;
+    if (
+      drawlistVersion !== 2 &&
+      drawlistVersion !== 3 &&
+      drawlistVersion !== 4 &&
+      drawlistVersion !== 5
+    ) {
+      throw new Error(
+        `drawlistVersion ${String(
+          drawlistVersion,
+        )} is no longer supported; use drawlistVersion 2, 3, 4, or 5.`,
+      );
+    }
     if (drawlistVersion >= 3) {
       this.builder = createDrawlistBuilderV3({
         ...builderOpts,

packages/core/src/app/widgetRenderer/cursorBreadcrumbs.ts

@@ -277,64 +277,26 @@ export function emitIncrementalCursor(
       cursorInfo,
     );
 
-  if (!cursorInfo || !isCursorBuilder(ctx.builder)) {
-    return ctx.collectRuntimeBreadcrumbs ? resolveSummary() : null;
-  }
-
-  const focusedId = ctx.focusedId;
-  if (!focusedId) {
-    ctx.builder.hideCursor();
-    return ctx.collectRuntimeBreadcrumbs ? resolveSummary() : null;
-  }
+  const summary = resolveSummary();
 
-  const input = ctx.inputById.get(focusedId);
-  if (!input || input.disabled) {
-    ctx.builder.hideCursor();
-    return ctx.collectRuntimeBreadcrumbs ? resolveSummary() : null;
+  if (!cursorInfo || !isCursorBuilder(ctx.builder)) {
+    return ctx.collectRuntimeBreadcrumbs ? summary : null;
   }
 
-  const rect = ctx.pooledRectByInstanceId.get(input.instanceId);
-  if (!rect || rect.w <= 1 || rect.h <= 0) {
+  if (!summary || !summary.visible) {
     ctx.builder.hideCursor();
-    return ctx.collectRuntimeBreadcrumbs ? resolveSummary() : null;
-  }
-
-  const graphemeOffset = ctx.inputCursorByInstanceId.get(input.instanceId) ?? input.value.length;
-  let cursorX = 0;
-  let cursorY = rect.y;
-  if (input.multiline) {
-    const contentW = Math.max(1, rect.w - 2);
-    const resolved = resolveInputMultilineCursor(
-      input.value,
-      graphemeOffset,
-      contentW,
-      input.wordWrap,
-    );
-    const maxStartVisual = Math.max(0, resolved.totalVisualLines - rect.h);
-    const startVisual = Math.max(0, Math.min(maxStartVisual, resolved.visualLine - rect.h + 1));
-    const localY = resolved.visualLine - startVisual;
-    if (localY < 0 || localY >= rect.h) {
-      ctx.builder.hideCursor();
-      return ctx.collectRuntimeBreadcrumbs ? resolveSummary() : null;
-    }
-    cursorX = Math.max(0, Math.min(Math.max(0, rect.w - 2), resolved.visualX));
-    cursorY = rect.y + localY;
-  } else {
-    cursorX = Math.max(
-      0,
-      Math.min(Math.max(0, rect.w - 2), measureTextCells(input.value.slice(0, graphemeOffset))),
-    );
+    return ctx.collectRuntimeBreadcrumbs ? summary : null;
   }
 
   ctx.builder.setCursor({
-    x: rect.x + 1 + cursorX,
-    y: cursorY,
-    shape: cursorInfo.shape,
+    x: summary.x,
+    y: summary.y,
+    shape: summary.shape,
     visible: true,
-    blink: cursorInfo.blink,
+    blink: summary.blink,
   });
 
-  return ctx.collectRuntimeBreadcrumbs ? resolveSummary() : null;
+  return ctx.collectRuntimeBreadcrumbs ? summary : null;
 }
 
 export function updateRuntimeBreadcrumbSnapshot(

packages/core/src/terminalCaps.ts

@@ -92,8 +92,7 @@ export const DEFAULT_TERMINAL_CAPS: TerminalCaps = Object.freeze({
  * @param caps - Terminal capabilities
  * @returns true if SET_CURSOR commands will work
  */
-export function supportsCursorProtocol(caps: TerminalCaps): boolean {
-  // The engine may support cursor visibility even without shape support
+export function supportsCursorProtocol(_caps: TerminalCaps): boolean {
   return true;
 }
 

packages/node/src/repro/recorder.ts

@@ -38,7 +38,6 @@ export type ReproRecorderBounds = Readonly<{
 export type ReproRecorderBackendCapsOverrides = Readonly<{
   maxEventBytes?: number;
   fpsCap?: number;
-  cursorProtocolVersion?: 2;
 }>;
 
 export type CreateReproRecorderOptions = Readonly<{