fix: address PR #417 review feedback

RtlZeroMemory · claude · RtlZeroMemory · commit 89f361798b56 · 2026-06-11T17:29:40.000+04:00
- core: printAbove/setInlineRows gain lifecycle-idle and in-commit/
  in-render re-entrancy guards (mirroring update())
- node: setInlineRows derives the runtime baseline from the START-resolved
  config (width policy settles during start), stripping Node-transport keys
  (fpsCap/maxEventBytes/frameTransport) so engine_set_config strict
  validation cannot reject the resend; commitScrollback validates rows
  client-side on both paths
- tests: guaranteed backend teardown via try/finally in all bodies
- example: inlineRows updates commit only after setInlineRows resolves

Re-verified in tmux: 4 printAbove checkpoints, live +/- resize, no stderr.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/examples/inline-status/src/index.ts b/examples/inline-status/src/index.ts
@@ -77,12 +77,22 @@ app.keys({
   "ctrl+c": () => void app.stop(),
   /* Grow/shrink the live region at runtime; layout follows the resize. */
   "shift+=": () => {
-    inlineRows = Math.min(16, inlineRows + 1);
-    void app.setInlineRows(inlineRows).catch(() => {});
+    const nextRows = Math.min(16, inlineRows + 1);
+    void app.setInlineRows(nextRows).then(
+      () => {
+        inlineRows = nextRows;
+      },
+      () => {},
+    );
   },
   "-": () => {
-    inlineRows = Math.max(5, inlineRows - 1);
-    void app.setInlineRows(inlineRows).catch(() => {});
+    const nextRows = Math.max(5, inlineRows - 1);
+    void app.setInlineRows(nextRows).then(
+      () => {
+        inlineRows = nextRows;
+      },
+      () => {},
+    );
   },
 });
 
diff --git a/packages/core/src/app/createApp.ts b/packages/core/src/app/createApp.ts
@@ -1018,6 +1018,14 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
 
     async printAbove(view: VNode, printOpts?: Readonly<{ rows?: number }>): Promise<void> {
       guards.assertOperational("printAbove");
+      guards.assertLifecycleIdle("printAbove");
+      if (inCommit) guards.throwCode("ZRUI_REENTRANT_CALL", "printAbove: called during commit");
+      if (inRender) {
+        guards.throwCode(
+          "ZRUI_UPDATE_DURING_RENDER",
+          guards.updateDuringRenderDetail("printAbove"),
+        );
+      }
       sm.assertOneOf(["Running"], "printAbove: app must be running");
       const commitFn = backend.commitScrollback?.bind(backend);
       if (commitFn === undefined) {
@@ -1038,6 +1046,14 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
 
     async setInlineRows(rows: number): Promise<void> {
       guards.assertOperational("setInlineRows");
+      guards.assertLifecycleIdle("setInlineRows");
+      if (inCommit) guards.throwCode("ZRUI_REENTRANT_CALL", "setInlineRows: called during commit");
+      if (inRender) {
+        guards.throwCode(
+          "ZRUI_UPDATE_DURING_RENDER",
+          guards.updateDuringRenderDetail("setInlineRows"),
+        );
+      }
       sm.assertOneOf(["Running"], "setInlineRows: app must be running");
       const setFn = backend.setInlineRows?.bind(backend);
       if (setFn === undefined) {
diff --git a/packages/node/src/__tests__/scrollback_commit.test.ts b/packages/node/src/__tests__/scrollback_commit.test.ts
@@ -37,10 +37,13 @@ for (const executionMode of ["worker", "inline"] as const) {
       nativeShimModule: SHIM,
     });
     await backend.start();
-    assert.ok(backend.commitScrollback !== undefined);
-    await backend.commitScrollback(makeClearDrawlist(), 2);
-    await backend.stop();
-    backend.dispose();
+    try {
+      assert.ok(backend.commitScrollback !== undefined);
+      await backend.commitScrollback(makeClearDrawlist(), 2);
+    } finally {
+      await backend.stop();
+      backend.dispose();
+    }
   });
 
   test(`scrollback: ${executionMode} path surfaces engine rejection`, async () => {
@@ -49,15 +52,18 @@ for (const executionMode of ["worker", "inline"] as const) {
       nativeShimModule: SHIM,
     });
     await backend.start();
-    await assert.rejects(
-      backend.commitScrollback?.(makeClearDrawlist(), 99) ?? Promise.reject(new Error("missing")),
-      (err: unknown) =>
-        err instanceof ZrUiError &&
-        err.code === "ZRUI_BACKEND_ERROR" &&
-        err.message.includes("engine_commit_scrollback failed"),
-    );
-    await backend.stop();
-    backend.dispose();
+    try {
+      await assert.rejects(
+        backend.commitScrollback?.(makeClearDrawlist(), 99) ?? Promise.reject(new Error("missing")),
+        (err: unknown) =>
+          err instanceof ZrUiError &&
+          err.code === "ZRUI_BACKEND_ERROR" &&
+          err.message.includes("engine_commit_scrollback failed"),
+      );
+    } finally {
+      await backend.stop();
+      backend.dispose();
+    }
   });
 
   test(`scrollback: ${executionMode} path accepts runtime inline rows`, async () => {
@@ -66,13 +72,16 @@ for (const executionMode of ["worker", "inline"] as const) {
       nativeShimModule: SHIM,
     });
     await backend.start();
-    assert.ok(backend.setInlineRows !== undefined);
-    /* The strict shim only accepts inlineRows=5 with plat.screenMode=1, so a
-       resolving call proves the runtime payload reached the engine intact. */
-    await backend.setInlineRows(5);
-    await backend.commitScrollback?.(makeClearDrawlist(), 1);
-    await backend.stop();
-    backend.dispose();
+    try {
+      assert.ok(backend.setInlineRows !== undefined);
+      /* The strict shim only accepts inlineRows=5 with plat.screenMode=1, so a
+         resolving call proves the runtime payload reached the engine intact. */
+      await backend.setInlineRows(5);
+      await backend.commitScrollback?.(makeClearDrawlist(), 1);
+    } finally {
+      await backend.stop();
+      backend.dispose();
+    }
   });
 
   test(`scrollback: ${executionMode} path validates inline rows client-side`, async () => {
@@ -81,12 +90,15 @@ for (const executionMode of ["worker", "inline"] as const) {
       nativeShimModule: SHIM,
     });
     await backend.start();
-    await assert.rejects(
-      backend.setInlineRows?.(0) ?? Promise.reject(new Error("missing")),
-      (err: unknown) => err instanceof ZrUiError && err.code === "ZRUI_INVALID_PROPS",
-    );
-    await backend.stop();
-    backend.dispose();
+    try {
+      await assert.rejects(
+        backend.setInlineRows?.(0) ?? Promise.reject(new Error("missing")),
+        (err: unknown) => err instanceof ZrUiError && err.code === "ZRUI_INVALID_PROPS",
+      );
+    } finally {
+      await backend.stop();
+      backend.dispose();
+    }
   });
 }
 
@@ -96,16 +108,19 @@ test("scrollback: alt-mode backend rejects commit and rows APIs", async () => {
     nativeShimModule: SHIM,
   });
   await backend.start();
-  await assert.rejects(
-    backend.commitScrollback?.(makeClearDrawlist(), 1) ?? Promise.reject(new Error("missing")),
-    (err: unknown) =>
-      err instanceof ZrUiError && err.message.includes('requires screen.mode "inline"'),
-  );
-  await assert.rejects(
-    backend.setInlineRows?.(5) ?? Promise.reject(new Error("missing")),
-    (err: unknown) =>
-      err instanceof ZrUiError && err.message.includes('requires screen.mode "inline"'),
-  );
-  await backend.stop();
-  backend.dispose();
+  try {
+    await assert.rejects(
+      backend.commitScrollback?.(makeClearDrawlist(), 1) ?? Promise.reject(new Error("missing")),
+      (err: unknown) =>
+        err instanceof ZrUiError && err.message.includes('requires screen.mode "inline"'),
+    );
+    await assert.rejects(
+      backend.setInlineRows?.(5) ?? Promise.reject(new Error("missing")),
+      (err: unknown) =>
+        err instanceof ZrUiError && err.message.includes('requires screen.mode "inline"'),
+    );
+  } finally {
+    await backend.stop();
+    backend.dispose();
+  }
 });
diff --git a/packages/node/src/backend/backendSharedConfig.ts b/packages/node/src/backend/backendSharedConfig.ts
@@ -127,6 +127,10 @@ const RUNTIME_STRIPPED_KEYS: readonly string[] = [
   "requested_drawlist_version",
   "requestedEventBatchVersion",
   "requested_event_batch_version",
+  /* Node-transport keys (worker init only; unknown to engine_set_config). */
+  "fpsCap",
+  "maxEventBytes",
+  "frameTransport",
 ];
 
 /**
@@ -160,12 +164,12 @@ export function isInlineScreenNativeConfig(
   return mode === NATIVE_SCREEN_MODE_INLINE;
 }
 
-/** Validate a runtime inline viewport height request. */
-export function validateInlineRowsOrThrow(rows: number): void {
+/** Validate a rows argument for inline screen-mode APIs. */
+export function validateInlineRowsOrThrow(rows: number, label = "rows"): void {
   if (!Number.isInteger(rows) || rows < 1 || rows > INLINE_ROWS_MAX) {
     throw new ZrUiError(
       "ZRUI_INVALID_PROPS",
-      `setInlineRows: rows must be an integer in [1, ${String(INLINE_ROWS_MAX)}]`,
+      `${label} must be an integer in [1, ${String(INLINE_ROWS_MAX)}]`,
     );
   }
 }
diff --git a/packages/node/src/backend/nodeBackend.ts b/packages/node/src/backend/nodeBackend.ts
@@ -204,10 +204,6 @@ export function createNodeBackendInternal(opts: NodeBackendInternalOpts = {}): N
   };
   let initConfigResolved: EngineCreateConfig | null = null;
   const isInlineScreen = isInlineScreenNativeConfig(nativeConfig);
-  const runtimeConfigBase = deriveRuntimeConfigBase({
-    ...nativeConfig,
-    targetFps: nativeTargetFps,
-  });
 
   let worker: Worker | null = null;
   let disposed = false;
@@ -888,6 +884,7 @@ export function createNodeBackendInternal(opts: NodeBackendInternalOpts = {}): N
       if (!isInlineScreen) {
         throw new ZrUiError("ZRUI_BACKEND_ERROR", 'commitScrollback requires screen.mode "inline"');
       }
+      validateInlineRowsOrThrow(rows, "commitScrollback: rows");
       const buf = new ArrayBuffer(drawlist.byteLength);
       copyInto(buf, drawlist);
       const d = deferred<void>();
@@ -904,8 +901,13 @@ export function createNodeBackendInternal(opts: NodeBackendInternalOpts = {}): N
       if (!isInlineScreen) {
         throw new ZrUiError("ZRUI_BACKEND_ERROR", 'setInlineRows requires screen.mode "inline"');
       }
-      validateInlineRowsOrThrow(rows);
-      send({ type: "setConfig", config: { ...runtimeConfigBase, inlineRows: rows } });
+      validateInlineRowsOrThrow(rows, "setInlineRows: rows");
+      if (initConfigResolved === null) {
+        throw new Error("NodeBackend: not started");
+      }
+      /* Resend the resolved create surface (width policy settles at start). */
+      const runtimeBase = deriveRuntimeConfigBase(initConfigResolved);
+      send({ type: "setConfig", config: { ...runtimeBase, inlineRows: rows } });
     },
 
     async getCaps(): Promise<TerminalCaps> {
diff --git a/packages/node/src/backend/nodeBackendInline.ts b/packages/node/src/backend/nodeBackendInline.ts
@@ -239,10 +239,6 @@ export function createNodeBackendInlineInternal(opts: NodeBackendInternalOpts =
   );
   const nativeTargetFps = resolveTargetFps(fpsCap, nativeConfig);
   const isInlineScreen = isInlineScreenNativeConfig(nativeConfig);
-  const runtimeConfigBase = deriveRuntimeConfigBase({
-    ...nativeConfig,
-    targetFps: nativeTargetFps,
-  });
 
   const initConfigBase = {
     ...nativeConfig,
@@ -793,6 +789,7 @@ export function createNodeBackendInlineInternal(opts: NodeBackendInternalOpts =
       if (!isInlineScreen) {
         throw new ZrUiError("ZRUI_BACKEND_ERROR", 'commitScrollback requires screen.mode "inline"');
       }
+      validateInlineRowsOrThrow(rows, "commitScrollback: rows");
       const commit = native.engineCommitScrollback;
       if (commit === undefined) {
         throw new ZrUiError(
@@ -818,8 +815,13 @@ export function createNodeBackendInlineInternal(opts: NodeBackendInternalOpts =
       if (!isInlineScreen) {
         throw new ZrUiError("ZRUI_BACKEND_ERROR", 'setInlineRows requires screen.mode "inline"');
       }
-      validateInlineRowsOrThrow(rows);
-      const rc = native.engineSetConfig(engineId, { ...runtimeConfigBase, inlineRows: rows });
+      validateInlineRowsOrThrow(rows, "setInlineRows: rows");
+      if (initConfigResolved === null) {
+        throw new Error("NodeBackend(inline): not started");
+      }
+      /* Resend the resolved create surface (width policy settles at start). */
+      const runtimeBase = deriveRuntimeConfigBase(initConfigResolved);
+      const rc = native.engineSetConfig(engineId, { ...runtimeBase, inlineRows: rows });
       if (rc < 0) {
         throw new ZrUiError("ZRUI_BACKEND_ERROR", `engine_set_config failed: code=${String(rc)}`);
       }
