Handle native render backpressure and failures (#1163)

- Retry feed-backed skipped frames once the feed becomes idle.
- Coalesce render requests while waiting for feed readiness.
- Avoid automatic retries for native failures.
- Preserve paused, stopped, suspended, and continuous-rendering
behavior.
- Prevent split-footer failure retry loops and unresolved idle waits.

---------

Co-authored-by: Simon Klee <hello@simonklee.dk>

Author: kommander

packages/core/src/renderer.ts

@@ -955,6 +955,8 @@ export class CliRenderer extends EventEmitter implements RenderContext {
   private _detachFeed: (() => void) | null = null
   private _detachFeedError: (() => void) | null = null
   private feedIdleRenderScheduled = false
+  private ordinaryFrameWaitingForFeed = false
+  private ordinaryFrameWaitControlState: RendererControlState | null = null
 
   public get controlState(): RendererControlState {
     return this._controlState
@@ -1411,32 +1413,90 @@ export class CliRenderer extends EventEmitter implements RenderContext {
     this.feedIdleRenderScheduled = true
     feed.idle().then(() => {
       this.feedIdleRenderScheduled = false
-      if (this._isDestroyed) {
+      const ordinaryFrameWasWaiting = this.ordinaryFrameWaitingForFeed
+      const ordinaryFrameWaitControlState = this.ordinaryFrameWaitControlState
+      this.ordinaryFrameWaitingForFeed = false
+      this.ordinaryFrameWaitControlState = null
+      if (
+        this._isDestroyed ||
+        (ordinaryFrameWasWaiting &&
+          this._controlState !== ordinaryFrameWaitControlState &&
+          (this._controlState === RendererControlState.EXPLICIT_PAUSED ||
+            this._controlState === RendererControlState.EXPLICIT_STOPPED ||
+            this._controlState === RendererControlState.EXPLICIT_SUSPENDED))
+      ) {
         this.resolveIdleIfNeeded()
         return
       }
 
-      if (this._isRunning) {
-        if (!this.renderTimeout && !this.rendering) {
-          this.renderTimeout = this.clock.setTimeout(() => {
-            this.renderTimeout = null
-            this.loop()
-          }, 0)
-        }
-        return
-      }
-
-      this.requestRender()
+      this.scheduleRenderTimer()
       this.resolveIdleIfNeeded()
     })
   }
 
+  private handleNativeRenderRejection(status: number): "retryable-skip" | "failed" {
+    if (status === NATIVE_RENDER_STATUS_SKIPPED && this._feed) {
+      this.ordinaryFrameWaitingForFeed = true
+      this.ordinaryFrameWaitControlState = this._controlState
+      this.scheduleRenderAfterFeedIdle()
+      return "retryable-skip"
+    }
+
+    if (status === NATIVE_RENDER_STATUS_SKIPPED) {
+      console.error("[CliRenderer] Native frame render unexpectedly skipped without a feed")
+      return "failed"
+    }
+
+    return this.reportNativeRenderFailure()
+  }
+
+  private reportNativeRenderFailure(): "failed" {
+    console.error("[CliRenderer] Native frame render failed; waiting for the next render request to force repaint")
+    return "failed"
+  }
+
+  private scheduleRenderTimer(): void {
+    if (this.renderTimeout || this._isDestroyed || this._controlState === RendererControlState.EXPLICIT_SUSPENDED)
+      return
+
+    const now = this.normalizeClockTime(this.clock.now(), this.lastTime)
+    const elapsed = this.getElapsedMs(now, this.lastTime)
+    const delay = Math.max(this.minTargetFrameTime - elapsed, 0)
+    this.renderTimeout = this.clock.setTimeout(() => {
+      this.renderTimeout = null
+      this.loop()
+    }, delay)
+  }
+
+  private scheduleRenderAfterBackpressure(): void {
+    if (this._feed) {
+      this.scheduleRenderAfterFeedIdle()
+      return
+    }
+
+    this.scheduleRenderTimer()
+  }
+
   public requestRender() {
     if (this._controlState === RendererControlState.EXPLICIT_SUSPENDED) {
       return
     }
 
+    // A skipped feed-backed frame already owns the next scheduling attempt through
+    // feed.idle(). Coalesce normal invalidations into that retry so split-footer
+    // output and UI updates cannot start competing render passes while the feed is busy.
+    if (this.feedIdleRenderScheduled) {
+      return
+    }
+
     if (this._isRunning) {
+      if (!this.rendering && !this.renderTimeout && !this.ordinaryFrameWaitingForFeed) {
+        this.scheduleRenderTimer()
+      }
+      return
+    }
+
+    if (this.ordinaryFrameWaitingForFeed) {
       return
     }
 
@@ -2483,7 +2543,7 @@ export class CliRenderer extends EventEmitter implements RenderContext {
   private flushPendingSplitCommits(
     forceFooterRepaint: boolean = false,
     drainAll: boolean = false,
-  ): "rendered" | "backpressured" {
+  ): "rendered" | "backpressured" | "failed" {
     // Drain only a bounded prefix so one JS render pass maps to one native frame.
     // Remaining commits are intentionally left queued and rendered on subsequent
     // ticks to avoid giant multi-thousand-cell frames that can flicker.
@@ -2492,6 +2552,7 @@ export class CliRenderer extends EventEmitter implements RenderContext {
     const lastCommitIndex = commits.length - 1
     let acceptedCommits = 0
     let nativeBackpressured = false
+    let nativeFailed = false
 
     for (const [index, commit] of commits.entries()) {
       // Force repaint only on the last commit in a frame. Repainting after every
@@ -2521,7 +2582,7 @@ export class CliRenderer extends EventEmitter implements RenderContext {
       }
 
       if (nativeResult.status === NATIVE_RENDER_STATUS_FAILED) {
-        nativeBackpressured = true
+        nativeFailed = true
         break
       }
 
@@ -2535,6 +2596,10 @@ export class CliRenderer extends EventEmitter implements RenderContext {
       this.externalOutputQueue.drop(acceptedCommits)
     }
 
+    if (nativeFailed) {
+      return this.reportNativeRenderFailure()
+    }
+
     if (nativeBackpressured) {
       this.scheduleRenderAfterFeedIdle()
       return "backpressured"
@@ -2546,10 +2611,13 @@ export class CliRenderer extends EventEmitter implements RenderContext {
         this.getSplitPinnedRenderOffset(),
         forceFooterRepaint,
       )
-      if (nativeResult.status === NATIVE_RENDER_STATUS_SKIPPED || nativeResult.status === NATIVE_RENDER_STATUS_FAILED) {
+      if (nativeResult.status === NATIVE_RENDER_STATUS_SKIPPED) {
         this.scheduleRenderAfterFeedIdle()
         return "backpressured"
       }
+      if (nativeResult.status === NATIVE_RENDER_STATUS_FAILED) {
+        return this.reportNativeRenderFailure()
+      }
       this.renderOffset = nativeResult.renderOffset
     }
 
@@ -4290,6 +4358,11 @@ export class CliRenderer extends EventEmitter implements RenderContext {
     this.lastFpsTime = this.lastTime
     this.currentFps = 0
 
+    // Starting continuous mode must not bypass an existing feed-idle retry. Keep
+    // _isRunning true, but let the idle callback schedule the first loop once the
+    // feed is ready; a successful frame will then resume the normal cadence.
+    if (this.feedIdleRenderScheduled) return
+
     this.loop()
   }
 
@@ -4394,7 +4467,7 @@ export class CliRenderer extends EventEmitter implements RenderContext {
             this.clock.clearTimeout(this.renderTimeout!)
             this.renderTimeout = null
           }
-        } else if (nativeStatus === "skipped") {
+        } else if (nativeStatus === "blocked") {
           const overallFrameTime = performance.now() - overallStart
 
           if (this._isRunning || this.immediateRerenderRequested) {
@@ -4409,7 +4482,12 @@ export class CliRenderer extends EventEmitter implements RenderContext {
             this.clock.clearTimeout(this.renderTimeout!)
             this.renderTimeout = null
           }
-        } else {
+        } else if (nativeStatus === "backpressured") {
+          this.scheduleRenderAfterBackpressure()
+        } else if (nativeStatus === "retryable-skip") {
+          this.immediateRerenderRequested = false
+          this.renderTimeout = null
+        } else if (nativeStatus === "failed") {
           this.immediateRerenderRequested = false
           this.renderTimeout = null
         }
@@ -4428,7 +4506,7 @@ export class CliRenderer extends EventEmitter implements RenderContext {
     this.loop()
   }
 
-  private renderNative(): "rendered" | "backpressured" | "skipped" {
+  private renderNative(): "rendered" | "retryable-skip" | "failed" | "blocked" | "backpressured" {
     if (this.renderingNative) {
       console.error("Rendering called concurrently")
       throw new Error("Rendering called concurrently")
@@ -4438,7 +4516,7 @@ export class CliRenderer extends EventEmitter implements RenderContext {
 
     try {
       if (this.isSplitCursorSeedFrameBlocked()) {
-        return "skipped"
+        return "blocked"
       }
 
       if (this._splitHeight > 0 && this._externalOutputMode === "capture-stdout") {
@@ -4453,6 +4531,9 @@ export class CliRenderer extends EventEmitter implements RenderContext {
         if (status === "backpressured") {
           return "backpressured"
         }
+        if (status === "failed") {
+          return "failed"
+        }
         this.forceFullRepaintRequested = false
         this.pendingSplitFooterTransition = null
         return "rendered"
@@ -4461,8 +4542,7 @@ export class CliRenderer extends EventEmitter implements RenderContext {
       const force = this.forceFullRepaintRequested
       const nativeStatus = this.lib.render(this.rendererPtr, force)
       if (nativeStatus === NATIVE_RENDER_STATUS_SKIPPED || nativeStatus === NATIVE_RENDER_STATUS_FAILED) {
-        this.scheduleRenderAfterFeedIdle()
-        return "backpressured"
+        return this.handleNativeRenderRejection(nativeStatus)
       }
 
       this.forceFullRepaintRequested = false