perf: layout stability signatures, content-keyed render packets, and hot-path fixes (#226)

Five-part performance audit targeting the submit/render pipeline:

1. beginFrame slot reclamation — reclaim READY→DONE SAB slots so the
   native backend can reuse them without growing the ring buffer.

2. Content-based render packet keying — replace identity (WeakMap) packet
   cache with FNV-1a content hashing so structurally-identical frames
   reuse cached packets.  Adds a hashTextProps fast path for text/richText
   nodes (6 visual props) to avoid generic Object.keys iteration.

3. Clip sentinel push — replace O(n) splice with O(1) push for clip
   open/close sentinels in the container render path.

4. Layout stability signatures — FNV-1a hash over each subtree's
   layout-affecting props; skip relayout when signature is unchanged.
   Text width is treated as paint-only (even inside row/grid parents)
   to avoid O(frames) relayout in scrolling lists.

5. Benchmark instrumentation — per-scenario perf-counter snapshots,
   execution-mode override env var, and bench-full-compare script.

PTY results (vs pre-audit baseline):
  virtual-list  1.03 ms → 649 µs  (−37 %)
  table           450 µs → 462 µs  (flat)
  frame-fill d=1  457 µs → 456 µs  (flat)
  fps-stream     1.11 ms → 1.07 ms (−4 %)

Author: RtlZeroMemory

package.json

@@ -46,7 +46,10 @@
     "bench": "node --expose-gc packages/bench/dist/run.js",
     "bench:report": "node --expose-gc packages/bench/dist/run.js --markdown",
     "bench:ci": "node scripts/run-bench-ci.mjs",
-    "bench:ci:compare": "node scripts/bench-ci-compare.mjs"
+    "bench:ci:compare": "node scripts/bench-ci-compare.mjs",
+    "bench:full:compare": "node scripts/bench-full-compare.mjs",
+    "bench:terminal:rigorous": "node --expose-gc packages/bench/dist/run.js --suite terminal --io pty --replicates 7 --discard-first-replicate --shuffle-framework-order --shuffle-seed local-terminal-rigorous --cpu-affinity 0-7 --env-check strict",
+    "bench:all:rigorous": "node --expose-gc packages/bench/dist/run.js --suite all --io pty --replicates 7 --discard-first-replicate --shuffle-framework-order --shuffle-seed local-all-rigorous --cpu-affinity 0-7 --env-check strict"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",

packages/bench/src/io.ts

@@ -119,10 +119,16 @@ export async function createBenchBackend(): Promise<BenchFrameBackend> {
   }
 
   const NodeBackend = await import("@rezi-ui/node");
+  const executionModeEnv = (
+    process.env as Readonly<{ REZI_BENCH_REZI_EXECUTION_MODE?: string }>
+  ).REZI_BENCH_REZI_EXECUTION_MODE;
+  const executionMode = executionModeEnv === "worker" ? "worker" : "inline";
   const inner = NodeBackend.createNodeBackend({
     // PTY mode already runs in a dedicated process, so prefer inline execution
     // here for stability (avoids nested worker-thread ownership + transport).
-    executionMode: "inline",
+    // Diagnostic override:
+    //   REZI_BENCH_REZI_EXECUTION_MODE=worker
+    executionMode,
     fpsCap: 60,
     nativeConfig: {
       // Include output backpressure (when supported) for a closer-to-real measurement.

packages/bench/src/reziProfile.ts

@@ -0,0 +1,66 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type { BenchMetrics, ScenarioConfig } from "./types.js";
+
+type CorePerfModule = Readonly<{
+  perfReset?: () => void;
+  perfSnapshot?: () => unknown;
+}>;
+
+function readEnv(name: string): string | null {
+  const value = process.env[name];
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function envFlag(name: string): boolean {
+  const value = readEnv(name);
+  if (value === null) return false;
+  const norm = value.toLowerCase();
+  return norm === "1" || norm === "true" || norm === "yes" || norm === "on";
+}
+
+const PROFILE_ENABLED = envFlag("REZI_BENCH_REZI_PROFILE");
+const PROFILE_LOG_PATH = readEnv("REZI_BENCH_REZI_PROFILE_LOG");
+
+export function resetReziPerfSnapshot(core: CorePerfModule): void {
+  if (!PROFILE_ENABLED) return;
+  core.perfReset?.();
+}
+
+export function emitReziPerfSnapshot(
+  core: CorePerfModule,
+  scenario: string,
+  params: Record<string, number | string>,
+  config: ScenarioConfig,
+  metrics: BenchMetrics,
+): void {
+  if (!PROFILE_ENABLED) return;
+  if (!PROFILE_LOG_PATH) return;
+  const snapshot = core.perfSnapshot?.();
+  if (snapshot === undefined) return;
+
+  try {
+    mkdirSync(dirname(PROFILE_LOG_PATH), { recursive: true });
+    appendFileSync(
+      PROFILE_LOG_PATH,
+      `${JSON.stringify({
+        ts: new Date().toISOString(),
+        pid: process.pid,
+        scenario,
+        params,
+        config,
+        timingMeanMs: metrics.timing.mean,
+        timingP95Ms: metrics.timing.p95,
+        bytesProduced: metrics.bytesProduced,
+        framesProduced: metrics.framesProduced,
+        perfSnapshot: snapshot,
+      })}\n`,
+      "utf8",
+    );
+  } catch {
+    // Profiling is optional and must never affect benchmark execution.
+  }
+}
+

packages/bench/src/scenarios/construction.ts

@@ -12,6 +12,7 @@
 import { BenchBackend, MeasuringStream, NullReadable } from "../backends.js";
 import { runOpenTuiScenario } from "../frameworks/opentui.js";
 import { benchAsync, benchSync, tryGc } from "../measure.js";
+import { emitReziPerfSnapshot, resetReziPerfSnapshot } from "../reziProfile.js";
 import type { BenchMetrics, Framework, Scenario, ScenarioConfig } from "../types.js";
 import {
   buildBlessedTree,
@@ -21,7 +22,8 @@ import {
 } from "./treeBuilders.js";
 
 async function runRezi(config: ScenarioConfig, n: number): Promise<BenchMetrics> {
-  const { createApp } = await import("@rezi-ui/core");
+  const core = await import("@rezi-ui/core");
+  const { createApp } = core;
   // Viewport must be large enough to fit all items — prevents viewport
   // clipping from giving Rezi an unfair advantage over frameworks that
   // render the full list regardless of viewport size.
@@ -48,6 +50,7 @@ async function runRezi(config: ScenarioConfig, n: number): Promise<BenchMetrics>
 
     const frameBase = backend.frameCount;
     const bytesBase = backend.totalFrameBytes;
+    resetReziPerfSnapshot(core);
 
     const metrics = await benchAsync(
       async (i) => {
@@ -61,6 +64,7 @@ async function runRezi(config: ScenarioConfig, n: number): Promise<BenchMetrics>
 
     metrics.framesProduced = backend.frameCount - frameBase;
     metrics.bytesProduced = backend.totalFrameBytes - bytesBase;
+    emitReziPerfSnapshot(core, "tree-construction", { items: n }, config, metrics);
     return metrics;
   } finally {
     await app.stop();

packages/bench/src/scenarios/content-update.ts

@@ -18,6 +18,7 @@ import { type VNode, ui } from "@rezi-ui/core";
 import { BenchBackend, MeasuringStream, NullReadable } from "../backends.js";
 import { runOpenTuiScenario } from "../frameworks/opentui.js";
 import { benchAsync, benchSync, tryGc } from "../measure.js";
+import { emitReziPerfSnapshot, resetReziPerfSnapshot } from "../reziProfile.js";
 import type { BenchMetrics, Framework, Scenario, ScenarioConfig } from "../types.js";
 
 const LIST_SIZE = 500;
@@ -112,7 +113,8 @@ function termkitListTree(
 // ── Runners ─────────────────────────────────────────────────────────
 
 async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
-  const { createApp } = await import("@rezi-ui/core");
+  const core = await import("@rezi-ui/core");
+  const { createApp } = core;
   // Match the viewport height to other frameworks (540 rows for 500-item list)
   // so Rezi renders ALL rows, not just the visible 40.
   const backend = new BenchBackend(120, 540);
@@ -138,6 +140,7 @@ async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
 
     const frameBase = backend.frameCount;
     const bytesBase = backend.totalFrameBytes;
+    resetReziPerfSnapshot(core);
 
     const metrics = await benchAsync(
       async (i) => {
@@ -151,6 +154,7 @@ async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
 
     metrics.framesProduced = backend.frameCount - frameBase;
     metrics.bytesProduced = backend.totalFrameBytes - bytesBase;
+    emitReziPerfSnapshot(core, "content-update", {}, config, metrics);
     return metrics;
   } finally {
     await app.stop();

packages/bench/src/scenarios/memory.ts

@@ -16,6 +16,7 @@ import { NullReadable } from "../backends.js";
 import { runOpenTuiScenario } from "../frameworks/opentui.js";
 import { createBenchBackend, createInkStdout } from "../io.js";
 import { computeStats, diffCpu, peakMemory, takeCpu, takeMemory, tryGc } from "../measure.js";
+import { emitReziPerfSnapshot, resetReziPerfSnapshot } from "../reziProfile.js";
 import type {
   BenchMetrics,
   Framework,
@@ -121,7 +122,8 @@ function analyzeMemory(samples: NodeMemorySnapshot[]): MemoryProfile {
 // ── Runners ─────────────────────────────────────────────────────────
 
 async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
-  const { createApp } = await import("@rezi-ui/core");
+  const core = await import("@rezi-ui/core");
+  const { createApp } = core;
   const backend = await createBenchBackend();
 
   type State = { iteration: number };
@@ -150,6 +152,7 @@ async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
     const frameBase = backend.frameCount;
     const bytesBase = backend.totalFrameBytes;
 
+    resetReziPerfSnapshot(core);
     tryGc();
     const memBefore = takeMemory();
     const cpuBefore = takeCpu();
@@ -177,7 +180,7 @@ async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
 
     const prof = analyzeMemory(memorySamples);
 
-    return {
+    const metrics: BenchMetrics = {
       timing: computeStats(timingSamples),
       memBefore,
       memAfter,
@@ -195,6 +198,8 @@ async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
       bytesProduced: backend.totalFrameBytes - bytesBase,
       ptyBytesObserved: null,
     };
+    emitReziPerfSnapshot(core, "memory-profile", {}, config, metrics);
+    return metrics;
   } finally {
     await app.stop();
     app.dispose();

packages/bench/src/scenarios/scrollStress.ts

@@ -12,6 +12,7 @@ import { NullReadable } from "../backends.js";
 import { runOpenTuiScenario } from "../frameworks/opentui.js";
 import { createBenchBackend, createInkStdout } from "../io.js";
 import { benchAsync, tryGc } from "../measure.js";
+import { emitReziPerfSnapshot, resetReziPerfSnapshot } from "../reziProfile.js";
 import type { BenchMetrics, Framework, Scenario, ScenarioConfig } from "../types.js";
 
 function reziTree(items: number, active: number, tick: number): VNode {
@@ -66,7 +67,8 @@ function reactTree(
 }
 
 async function runRezi(config: ScenarioConfig, items: number): Promise<BenchMetrics> {
-  const { createApp } = await import("@rezi-ui/core");
+  const core = await import("@rezi-ui/core");
+  const { createApp } = core;
   const backend = await createBenchBackend();
 
   type State = { active: number; tick: number };
@@ -86,6 +88,7 @@ async function runRezi(config: ScenarioConfig, items: number): Promise<BenchMetr
 
     const frameBase = backend.frameCount;
     const bytesBase = backend.totalFrameBytes;
+    resetReziPerfSnapshot(core);
 
     const metrics = await benchAsync(
       async () => {
@@ -99,6 +102,7 @@ async function runRezi(config: ScenarioConfig, items: number): Promise<BenchMetr
 
     metrics.framesProduced = backend.frameCount - frameBase;
     metrics.bytesProduced = backend.totalFrameBytes - bytesBase;
+    emitReziPerfSnapshot(core, "scroll-stress", { items }, config, metrics);
     return metrics;
   } finally {
     await app.stop();

packages/bench/src/scenarios/startup.ts

@@ -18,6 +18,7 @@
 import { BenchBackend, MeasuringStream, NullReadable } from "../backends.js";
 import { runOpenTuiScenario } from "../frameworks/opentui.js";
 import { computeStats, diffCpu, peakMemory, takeCpu, takeMemory, tryGc } from "../measure.js";
+import { emitReziPerfSnapshot, resetReziPerfSnapshot } from "../reziProfile.js";
 import type {
   BenchMetrics,
   Framework,
@@ -35,7 +36,8 @@ import {
 const TREE_SIZE = 50;
 
 async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
-  const { createApp } = await import("@rezi-ui/core");
+  const core = await import("@rezi-ui/core");
+  const { createApp } = core;
 
   const samples: number[] = [];
 
@@ -51,6 +53,7 @@ async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
     app.dispose();
   }
 
+  resetReziPerfSnapshot(core);
   tryGc();
   const memBefore = takeMemory();
   const cpuBefore = takeCpu();
@@ -83,7 +86,7 @@ async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
   const memAfter = takeMemory();
   memMax = peakMemory(memMax, memAfter);
 
-  return {
+  const metrics: BenchMetrics = {
     timing: computeStats(samples),
     memBefore,
     memAfter,
@@ -101,6 +104,8 @@ async function runRezi(config: ScenarioConfig): Promise<BenchMetrics> {
     bytesProduced: totalBytes,
     ptyBytesObserved: null,
   };
+  emitReziPerfSnapshot(core, "startup", {}, config, metrics);
+  return metrics;
 }
 
 async function runInkCompat(config: ScenarioConfig): Promise<BenchMetrics> {
@@ -313,7 +318,7 @@ async function runBlessed(config: ScenarioConfig): Promise<BenchMetrics> {
   const samples: number[] = [];
 
   for (let w = 0; w < config.warmup; w++) {
-    const ctx = createBlessedContext(120, 60);
+    const ctx = createBlessedContext(120, 40);
     buildBlessedTree(ctx.blessed, ctx.screen, TREE_SIZE, w);
     ctx.screen.render();
     ctx.flush();
@@ -328,7 +333,7 @@ async function runBlessed(config: ScenarioConfig): Promise<BenchMetrics> {
   let totalBytes = 0;
 
   for (let i = 0; i < config.iterations; i++) {
-    const ctx = createBlessedContext(120, 60);
+    const ctx = createBlessedContext(120, 40);
 
     const ts = performance.now();
     buildBlessedTree(ctx.blessed, ctx.screen, TREE_SIZE, i);

packages/bench/src/scenarios/terminalStrictBench.ts

@@ -5,6 +5,7 @@ import { runOpenTuiScenario } from "../frameworks/opentui.js";
 import { runRatatuiScenario } from "../frameworks/ratatui.js";
 import { createBenchBackend, createInkStdout } from "../io.js";
 import { benchAsync } from "../measure.js";
+import { emitReziPerfSnapshot, resetReziPerfSnapshot } from "../reziProfile.js";
 import type { BenchMetrics, ScenarioConfig } from "../types.js";
 import {
   type StrictSections,
@@ -143,7 +144,8 @@ async function runRezi(
   params: Record<string, number | string>,
   variant: StrictVariant,
 ): Promise<BenchMetrics> {
-  const { createApp } = await import("@rezi-ui/core");
+  const core = await import("@rezi-ui/core");
+  const { createApp } = core;
   const backend = await createBenchBackend();
 
   type State = { tick: number };
@@ -163,6 +165,7 @@ async function runRezi(
 
     const frameBase = backend.frameCount;
     const bytesBase = backend.totalFrameBytes;
+    resetReziPerfSnapshot(core);
 
     const metrics = await benchAsync(
       async () => {
@@ -176,6 +179,13 @@ async function runRezi(
 
     metrics.framesProduced = backend.frameCount - frameBase;
     metrics.bytesProduced = backend.totalFrameBytes - bytesBase;
+    emitReziPerfSnapshot(
+      core,
+      variant === "navigation" ? "terminal-strict-ui-navigation" : "terminal-strict-ui",
+      params,
+      config,
+      metrics,
+    );
     return metrics;
   } finally {
     await app.stop();

packages/bench/src/scenarios/terminalVirtualList.ts

@@ -13,6 +13,7 @@ import { runOpenTuiScenario } from "../frameworks/opentui.js";
 import { runRatatuiScenario } from "../frameworks/ratatui.js";
 import { createBenchBackend, createInkStdout } from "../io.js";
 import { benchAsync, tryGc } from "../measure.js";
+import { emitReziPerfSnapshot, resetReziPerfSnapshot } from "../reziProfile.js";
 import type { BenchMetrics, Framework, Scenario, ScenarioConfig } from "../types.js";
 
 type BlessedElement = Readonly<{ setContent: (s: string) => void }>;
@@ -99,7 +100,8 @@ async function runRezi(
   totalItems: number,
   viewport: number,
 ): Promise<BenchMetrics> {
-  const { createApp } = await import("@rezi-ui/core");
+  const core = await import("@rezi-ui/core");
+  const { createApp } = core;
   const backend = await createBenchBackend();
 
   type State = { offset: number; tick: number };
@@ -119,6 +121,7 @@ async function runRezi(
 
     const frameBase = backend.frameCount;
     const bytesBase = backend.totalFrameBytes;
+    resetReziPerfSnapshot(core);
 
     const metrics = await benchAsync(
       async () => {
@@ -132,6 +135,7 @@ async function runRezi(
 
     metrics.framesProduced = backend.frameCount - frameBase;
     metrics.bytesProduced = backend.totalFrameBytes - bytesBase;
+    emitReziPerfSnapshot(core, "terminal-virtual-list", { items: totalItems, viewport }, config, metrics);
     return metrics;
   } finally {
     await app.stop();