core: stabilize animation tick cadence and single-select table focus (#94)

* core: throttle spinner tick repaints and stabilize table single-selection focus

* core: apply biome formatting for lint CI

Author: RtlZeroMemory

packages/core/src/app/__tests__/interactivePriority.test.ts

@@ -1,4 +1,5 @@
 import { assert, test } from "@rezi-ui/testkit";
+import { ui } from "../../widgets/ui.js";
 import { createApp } from "../createApp.js";
 import { encodeZrevBatchV1, flushMicrotasks, makeBackendBatch } from "./helpers.js";
 import { StubBackend } from "./stubBackend.js";
@@ -87,3 +88,86 @@ test("raw mode tick does not force render when no state changed", async () => {
   await flushMicrotasks(5);
   assert.equal(backend.requestedFrames.length, 1);
 });
+
+test("widget mode tick does not force render when no spinner exists", async () => {
+  const backend = new StubBackend();
+  const app = createApp({ backend, initialState: 0 });
+
+  app.view(() => ui.text("static"));
+
+  await app.start();
+  backend.pushBatch(
+    makeBackendBatch({
+      bytes: encodeZrevBatchV1({
+        flags: 0,
+        events: [{ kind: "resize", timeMs: 1, cols: 80, rows: 24 }],
+      }),
+    }),
+  );
+  await flushMicrotasks(10);
+  assert.equal(backend.requestedFrames.length, 1);
+
+  backend.resolveNextFrame();
+  await flushMicrotasks(3);
+
+  const bytes = encodeZrevBatchV1({
+    flags: 0,
+    events: [{ kind: "tick", timeMs: 10 }],
+  });
+  backend.pushBatch(makeBackendBatch({ bytes }));
+
+  await flushMicrotasks(5);
+  assert.equal(backend.requestedFrames.length, 1);
+});
+
+test("widget mode spinner tick rendering is throttled", async () => {
+  const backend = new StubBackend();
+  const app = createApp({ backend, initialState: 0 });
+
+  app.view(() => ui.spinner({ variant: "line", label: "Loading" }));
+
+  await app.start();
+  backend.pushBatch(
+    makeBackendBatch({
+      bytes: encodeZrevBatchV1({
+        flags: 0,
+        events: [{ kind: "resize", timeMs: 1, cols: 80, rows: 24 }],
+      }),
+    }),
+  );
+  await flushMicrotasks(10);
+  assert.equal(backend.requestedFrames.length, 1);
+
+  backend.resolveNextFrame();
+  await flushMicrotasks(3);
+
+  backend.pushBatch(
+    makeBackendBatch({
+      bytes: encodeZrevBatchV1({
+        flags: 0,
+        events: [
+          { kind: "tick", timeMs: 10 },
+          { kind: "tick", timeMs: 20 },
+          { kind: "tick", timeMs: 30 },
+          { kind: "tick", timeMs: 40 },
+        ],
+      }),
+    }),
+  );
+  await flushMicrotasks(5);
+  assert.equal(backend.requestedFrames.length, 2);
+
+  backend.resolveNextFrame();
+  await flushMicrotasks(3);
+
+  backend.pushBatch(
+    makeBackendBatch({
+      bytes: encodeZrevBatchV1({
+        flags: 0,
+        events: [{ kind: "tick", timeMs: 200 }],
+      }),
+    }),
+  );
+  await flushMicrotasks(5);
+  assert.equal(backend.requestedFrames.length, 3);
+});

packages/core/src/app/__tests__/runtimeBreadcrumbs.test.ts

@@ -105,6 +105,8 @@ test("runtime breadcrumbs capture event path/action/focus/cursor deterministical
             presses++;
           },
         }),
+        // Keep an animated widget in-tree so tick events produce render snapshots.
+        ui.spinner({ variant: "dots", label: "" }),
       ],
     ),
   );
@@ -167,7 +169,7 @@ test("runtime breadcrumbs capture event path/action/focus/cursor deterministical
   assert.deepEqual(actionEvents, [{ id: "save", action: "press" }]);
   assert.equal(presses, 1);
 
-  await pushEvents(backend, [{ kind: "tick", timeMs: 6, dtMs: 16 }]);
+  await pushEvents(backend, [{ kind: "tick", timeMs: 200, dtMs: 16 }]);
   assert.equal(renderSnapshots.length, 4);
   const fourth = renderSnapshots[3];
   assert.ok(fourth);

packages/core/src/app/createApp.ts

@@ -369,13 +369,17 @@ export function createApp<S>(
   const DIRTY_RENDER = 1 << 0;
   const DIRTY_LAYOUT = 1 << 1;
   const DIRTY_VIEW = 1 << 2;
+  const spinnerTickMinIntervalMs = Math.max(1, Math.floor(1000 / Math.min(config.fpsCap, 8)));
 
   let dirtyFlags = 0;
   let dirtyRenderVersion = 0;
   let dirtyLayoutVersion = 0;
   let dirtyViewVersion = 0;
   let framesInFlight = 0;
   let interactiveBudget = 0;
+  let lastSpinnerRenderTickMs = Number.NEGATIVE_INFINITY;
+  let lastObservedSpinnerTickEventMs = Number.NEGATIVE_INFINITY;
+  let lastSpinnerRenderPerfMs = Number.NEGATIVE_INFINITY;
   let viewport: Readonly<{ cols: number; rows: number }> | null = null;
   const timeUnwrap: EventTimeUnwrapState = { epochMs: 0, lastRawMs: null };
 
@@ -722,8 +726,26 @@ export function createApp<S>(
           }
         }
         if (ev.kind === "tick" && mode === "widget") {
-          // Tick events drive render-only animation frames (e.g., Spinner).
-          markDirty(DIRTY_RENDER);
+          // Tick events drive render-only animation frames for animated widgets
+          // (currently spinner). Throttle to avoid repaint storms/flicker.
+          //
+          // Prefer backend tick timestamps when they advance, but fall back to
+          // local monotonic time for runtimes/terminals where tick time is
+          // constant or non-monotonic.
+          if (widgetRenderer.hasAnimatedWidgets()) {
+            const tickMs = ev.timeMs;
+            const perfMs = perfNow();
+            const eventClockAdvances = tickMs > lastObservedSpinnerTickEventMs;
+            if (eventClockAdvances) lastObservedSpinnerTickEventMs = tickMs;
+            const elapsedMs = eventClockAdvances
+              ? tickMs - lastSpinnerRenderTickMs
+              : perfMs - lastSpinnerRenderPerfMs;
+            if (elapsedMs >= spinnerTickMinIntervalMs) {
+              lastSpinnerRenderTickMs = tickMs;
+              lastSpinnerRenderPerfMs = perfMs;
+              markDirty(DIRTY_RENDER);
+            }
+          }
         }
 
         const isWidgetRoutableEvent =

packages/core/src/app/widgetRenderer.ts

@@ -504,6 +504,7 @@ export class WidgetRenderer<S> {
 
   // Tracks whether the currently committed tree needs routing rebuild traversals.
   private hadRoutingWidgets = false;
+  private hasAnimatedWidgetsInCommittedTree = false;
 
   /* --- Render Caches (avoid per-frame recompute) --- */
   private readonly tableRenderCacheById = new Map<string, TableRenderCache>();
@@ -639,6 +640,29 @@ export class WidgetRenderer<S> {
     }
   }
 
+  hasAnimatedWidgets(): boolean {
+    return this.hasAnimatedWidgetsInCommittedTree;
+  }
+
+  private recomputeAnimatedWidgetPresence(runtimeRoot: RuntimeInstance): void {
+    this._pooledRuntimeStack.length = 0;
+    this._pooledRuntimeStack.push(runtimeRoot);
+    while (this._pooledRuntimeStack.length > 0) {
+      const node = this._pooledRuntimeStack.pop();
+      if (!node) continue;
+      if (node.vnode.kind === "spinner") {
+        this.hasAnimatedWidgetsInCommittedTree = true;
+        this._pooledRuntimeStack.length = 0;
+        return;
+      }
+      for (let i = node.children.length - 1; i >= 0; i--) {
+        const child = node.children[i];
+        if (child) this._pooledRuntimeStack.push(child);
+      }
+    }
+    this.hasAnimatedWidgetsInCommittedTree = false;
+  }
+
   /**
    * Get the currently focused widget ID.
    *
@@ -2988,6 +3012,7 @@ export class WidgetRenderer<S> {
         }
         commitRes = commitRes0.value;
         this.committedRoot = commitRes.root;
+        this.recomputeAnimatedWidgetPresence(this.committedRoot);
 
         const damageToken = PERF_DETAIL_ENABLED ? perfMarkStart("damage_identity_diff") : 0;
         identityDamageFromCommit = this.computeIdentityDiffDamage(

packages/core/src/renderer/renderToDrawlist/widgets/collections.ts

@@ -411,13 +411,20 @@ export function renderCollectionWidget(
           }
         }
         const isFocusedRow = focusState.focusedId === props.id && i === tableState.focusedRowIndex;
+        const suppressFocusedStyle =
+          selectionMode === "single" && needsSelection && isFocusedRow && !isSelected;
+        const showFocusedStyle = isFocusedRow && !suppressFocusedStyle;
 
         const yRow = bodyY + i * safeRowHeight - effectiveScrollTop;
         if (yRow >= bodyY + bodyH) break;
         if (yRow + safeRowHeight <= bodyY) continue;
 
         const rowStripeBg = stripedRows ? ((i & 1) === 1 ? stripeOddBg : stripeEvenBg) : undefined;
-        const rowBg = isFocusedRow ? undefined : isSelected ? theme.colors.secondary : rowStripeBg;
+        const rowBg = showFocusedStyle
+          ? undefined
+          : isSelected
+            ? theme.colors.secondary
+            : rowStripeBg;
         if (rowBg) {
           builder.fillRect(innerX, yRow, innerW, safeRowHeight, { bg: rowBg });
         }
@@ -437,7 +444,7 @@ export function renderCollectionWidget(
                   ? rawValue
                   : String(rawValue);
 
-          const style = isFocusedRow ? { inverse: true } : rowBg ? { bg: rowBg } : undefined;
+          const style = showFocusedStyle ? { inverse: true } : rowBg ? { bg: rowBg } : undefined;
 
           if (col.render) {
             const cellVNode = col.render(rawValue, row, i);

packages/core/src/widgets/__tests__/renderer.regressions.test.ts

@@ -146,6 +146,7 @@ function renderBytes(
     virtualListStore?: VirtualListStateStore;
     tableStore?: TableStateStore;
     treeStore?: TreeStateStore;
+    focusedId?: string | null;
   }>,
 ): Uint8Array {
   const allocator = createInstanceIdAllocator(1);
@@ -169,7 +170,7 @@ function renderBytes(
     tree: committed.value.root,
     layout: layoutRes.value,
     viewport,
-    focusState: Object.freeze({ focusedId: null }),
+    focusState: Object.freeze({ focusedId: stores?.focusedId ?? null }),
     builder,
     virtualListStore: stores?.virtualListStore,
     tableStore: stores?.tableStore,
@@ -183,6 +184,7 @@ function renderBytes(
 
 describe("renderer regressions", () => {
   const noop = (..._args: readonly unknown[]) => undefined;
+  const ATTR_INVERSE = 1 << 3;
 
   test("box shadow renders shade glyphs when enabled", () => {
     const withShadow = parseInternedStrings(
@@ -252,6 +254,58 @@ describe("renderer regressions", () => {
     assert.equal(withFillCount > withoutFillCount, true);
   });
 
+  test("table single-selection suppresses focused inverse style when focused row is not selected", () => {
+    const tableStore = createTableStateStore();
+    tableStore.set("tbl-single-active", { focusedRowIndex: 1 });
+
+    const bytes = renderBytes(
+      ui.table({
+        id: "tbl-single-active",
+        columns: [{ key: "name", header: "Name", width: 10 }],
+        data: [
+          { id: "r0", name: "A" },
+          { id: "r1", name: "B" },
+        ],
+        getRowKey: (row) => row.id,
+        selectionMode: "single",
+        selection: ["r0"],
+        border: "none",
+      }),
+      { cols: 40, rows: 8 },
+      { tableStore, focusedId: "tbl-single-active" },
+    );
+
+    const styles = parseCommandStyles(bytes);
+    const hasInverse = styles.some((s) => (s.attrs & ATTR_INVERSE) !== 0);
+    assert.equal(hasInverse, false);
+  });
+
+  test("table keeps focused inverse style when focused row is selected", () => {
+    const tableStore = createTableStateStore();
+    tableStore.set("tbl-single-active-selected", { focusedRowIndex: 1 });
+
+    const bytes = renderBytes(
+      ui.table({
+        id: "tbl-single-active-selected",
+        columns: [{ key: "name", header: "Name", width: 10 }],
+        data: [
+          { id: "r0", name: "A" },
+          { id: "r1", name: "B" },
+        ],
+        getRowKey: (row) => row.id,
+        selectionMode: "single",
+        selection: ["r1"],
+        border: "none",
+      }),
+      { cols: 40, rows: 8 },
+      { tableStore, focusedId: "tbl-single-active-selected" },
+    );
+
+    const styles = parseCommandStyles(bytes);
+    const hasInverse = styles.some((s) => (s.attrs & ATTR_INVERSE) !== 0);
+    assert.equal(hasInverse, true);
+  });
+
   test("table column overflow policies render ellipsis, middle, and clip deterministically", () => {
     const strings = parseInternedStrings(
       renderBytes(