Merge pull request #238 from RtlZeroMemory/fix/233-default-q-quit

fix(core): stop app on unhandled q and ctrl+c

Author: RtlZeroMemory

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on Keep a Changelog and the project follows Semantic Version
 
 ### Bug Fixes
 
+- **core/runtime**: Unhandled top-level `q`/`Q` and `Ctrl+C` inputs now stop the app by default, while preserving explicit keybinding handlers.
 - **native/detect**: Startup terminal probing now exits after a short DA1 drain window instead of waiting the full 500ms budget when XTVERSION never responds, reducing first-render delay on VTE-like terminals.
 - **core/constraints**: Constraint input signatures now include all required runtime dependencies, preventing stale cache reuse when unconstrained referenced widget geometry changes.
 - **core/layout**: Constraint resolution now performs bounded in-frame settle passes for deeper parent-dependent chains, eliminating first-frame/resize layout jump artifacts in nested constraint trees.

packages/core/src/__tests__/stress/fuzz.random-events.test.ts

@@ -18,10 +18,17 @@ import {
   ZR_KEY_RIGHT,
   ZR_KEY_TAB,
   ZR_KEY_UP,
+  ZR_MOD_ALT,
+  ZR_MOD_CTRL,
+  ZR_MOD_META,
 } from "../../keybindings/keyCodes.js";
 import { ui } from "../../widgets/ui.js";
 
 const ITERATIONS = 1024;
+const KEY_C = 67;
+const KEY_Q = 81;
+const TEXT_Q = 81;
+const TEXT_LOWER_Q = 113;
 
 const LETTER_KEYS = Object.freeze(Array.from({ length: 26 }, (_unused, idx) => 65 + idx));
 const DIGIT_KEYS = Object.freeze(Array.from({ length: 10 }, (_unused, idx) => 48 + idx));
@@ -276,6 +283,23 @@ function randomMods(rng: Rng): number {
   return rng.u32() & 0x0f;
 }
 
+function isDefaultQuitKeyEvent(
+  key: number,
+  mods: number,
+  action: "down" | "up" | "repeat",
+): boolean {
+  if (action !== "down") return false;
+  if (key === KEY_Q) {
+    return (mods & (ZR_MOD_CTRL | ZR_MOD_ALT | ZR_MOD_META)) === 0;
+  }
+  if (key === KEY_C) {
+    const hasCtrl = (mods & ZR_MOD_CTRL) !== 0;
+    const hasAltOrMeta = (mods & (ZR_MOD_ALT | ZR_MOD_META)) !== 0;
+    return hasCtrl && !hasAltOrMeta;
+  }
+  return false;
+}
+
 function randomKeyCode(rng: Rng, profile: EventProfile): number {
   if (profile.interactiveKeyBias && chance(rng, 65)) {
     return pick(rng, NAV_KEYS);
@@ -307,11 +331,17 @@ function generateKeyEvent(rng: Rng, stream: StreamState, profile: EventProfile):
     }
   }
 
+  let mods = randomMods(rng);
+  // Keep fuzz deterministic while avoiding global default quit hotkeys.
+  if (isDefaultQuitKeyEvent(key, mods, action)) {
+    mods |= ZR_MOD_ALT;
+  }
+
   return {
     kind: "key",
     timeMs: nextTime(stream, rng),
     key,
-    mods: randomMods(rng),
+    mods,
     action,
   };
 }
@@ -376,10 +406,14 @@ function generateMouseEvent(
 }
 
 function generateTextEvent(rng: Rng, stream: StreamState): EncodedInputEvent {
+  let codepoint = 32 + (rng.u32() % 95);
+  if (codepoint === TEXT_Q || codepoint === TEXT_LOWER_Q) {
+    codepoint = (codepoint === TEXT_Q ? TEXT_Q + 1 : TEXT_LOWER_Q - 1) >>> 0;
+  }
   return {
     kind: "text",
     timeMs: nextTime(stream, rng),
-    codepoint: 32 + (rng.u32() % 95),
+    codepoint,
   };
 }
 

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

@@ -1,6 +1,7 @@
 import { assert, test } from "@rezi-ui/testkit";
 import { parseInternedStrings } from "../../__tests__/drawlistDecode.js";
 import { defineWidget, ui } from "../../index.js";
+import { ZR_MOD_CTRL, ZR_MOD_SHIFT } from "../../keybindings/keyCodes.js";
 import { createApp } from "../createApp.js";
 import { encodeZrevBatchV1, flushMicrotasks, makeBackendBatch } from "./helpers.js";
 import { StubBackend } from "./stubBackend.js";
@@ -161,6 +162,132 @@ test("top-level view error screen handles Q by stopping and disposing the app",
   assert.equal(backend.disposeCalls >= 1, true);
 });
 
+test("unhandled q text event stops app by default", async () => {
+  const backend = new StubBackend();
+  const app = createApp({ backend, initialState: {} });
+
+  app.view(() => ui.text("hello"));
+
+  await app.start();
+  await emitResize(backend, 1);
+  await settleNextFrame(backend);
+
+  await pushEvents(backend, [{ kind: "text", timeMs: 3, codepoint: 113 }]);
+  await flushMicrotasks(30);
+
+  assert.equal(backend.stopCalls >= 1, true);
+  assert.equal(backend.disposeCalls, 0);
+});
+
+test("unhandled ctrl+c key/text events stop app by default", async () => {
+  const backend = new StubBackend();
+  const app = createApp({ backend, initialState: {} });
+
+  app.view(() => ui.text("hello"));
+
+  await app.start();
+  await emitResize(backend, 1);
+  await settleNextFrame(backend);
+
+  await pushEvents(backend, [
+    { kind: "key", timeMs: 3, key: 67, mods: ZR_MOD_CTRL, action: "down" },
+  ]);
+  await flushMicrotasks(30);
+
+  assert.equal(backend.stopCalls >= 1, true);
+
+  await app.start();
+  await emitResize(backend, 5);
+  await settleNextFrame(backend);
+
+  await pushEvents(backend, [{ kind: "text", timeMs: 6, codepoint: 3 }]);
+  await flushMicrotasks(30);
+
+  assert.equal(backend.stopCalls >= 2, true);
+});
+
+test("handled ctrl+c copy in input does not trigger default quit", async () => {
+  const backend = new StubBackend();
+  const app = createApp({ backend, initialState: {} });
+
+  app.view(() =>
+    ui.input({
+      id: "inp",
+      value: "hello world",
+    }),
+  );
+
+  await app.start();
+  await emitResize(backend, 1);
+  await settleNextFrame(backend);
+
+  await pushEvents(backend, [
+    { kind: "key", timeMs: 2, key: 3, mods: 0, action: "down" }, // Tab -> focus input
+    { kind: "key", timeMs: 3, key: 22, mods: ZR_MOD_SHIFT | ZR_MOD_CTRL, action: "down" }, // Shift+Ctrl+Left
+    { kind: "key", timeMs: 4, key: 67, mods: ZR_MOD_CTRL, action: "down" }, // Ctrl+C
+  ]);
+
+  assert.equal(backend.stopCalls, 0);
+  assert.equal(backend.disposeCalls, 0);
+});
+
+test("unhandled quit emits fatal when stop throws synchronously", async () => {
+  class ThrowingStopBackend extends StubBackend {
+    override stop(): Promise<void> {
+      this.stopCalls++;
+      this.callLog.push("stop");
+      throw new Error("sync-stop-fail");
+    }
+  }
+
+  const backend = new ThrowingStopBackend();
+  const app = createApp({ backend, initialState: {} });
+  const fatals: string[] = [];
+
+  app.view(() => ui.text("hello"));
+  app.onEvent((ev) => {
+    if (ev.kind === "fatal") fatals.push(`${ev.code}:${ev.detail}`);
+  });
+
+  await app.start();
+  await emitResize(backend, 1);
+  await settleNextFrame(backend);
+
+  await pushEvents(backend, [{ kind: "text", timeMs: 3, codepoint: 113 }]);
+  await flushMicrotasks(30);
+
+  assert.equal(fatals.length >= 1, true);
+  assert.equal(
+    fatals[0]?.startsWith("ZRUI_BACKEND_ERROR:stop threw after unhandled quit input:"),
+    true,
+  );
+  assert.equal(backend.disposeCalls, 1);
+  assert.equal(backend.stopCalls >= 2, true);
+});
+
+test("custom q keybinding overrides default unhandled quit behavior", async () => {
+  const backend = new StubBackend();
+  const app = createApp({ backend, initialState: {} });
+  let keybindingHits = 0;
+
+  app.view(() => ui.text("hello"));
+  app.keys({
+    q: () => {
+      keybindingHits++;
+    },
+  });
+
+  await app.start();
+  await emitResize(backend, 1);
+  await settleNextFrame(backend);
+
+  await pushEvents(backend, [{ kind: "text", timeMs: 3, codepoint: 113 }]);
+  await flushMicrotasks(30);
+
+  assert.equal(keybindingHits, 1);
+  assert.equal(backend.stopCalls, 0);
+});
+
 test("app.run() wires SIGINT/SIGTERM/SIGHUP and performs graceful shutdown", async () => {
   const backend = new StubBackend();
   const app = createApp({ backend, initialState: 0 });

packages/core/src/app/createApp.ts

@@ -366,6 +366,10 @@ type TopLevelViewError = Readonly<{
 
 const KEY_Q = 81;
 const KEY_R = 82;
+const KEY_C = 67;
+const KEY_LOWER_Q = 113;
+const KEY_LOWER_R = 114;
+const CTRL_C_CODEPOINT = 3;
 
 function captureTopLevelViewError(value: unknown): TopLevelViewError {
   if (value instanceof Error) {
@@ -420,7 +424,7 @@ function isTopLevelRetryEvent(ev: ZrevEvent): boolean {
     return ev.action === "down" && isUnmodifiedLetterKey(ev.mods) && ev.key === KEY_R;
   }
   if (ev.kind === "text") {
-    return ev.codepoint === KEY_R || ev.codepoint === 114;
+    return ev.codepoint === KEY_R || ev.codepoint === KEY_LOWER_R;
   }
   return false;
 }
@@ -430,11 +434,27 @@ function isTopLevelQuitEvent(ev: ZrevEvent): boolean {
     return ev.action === "down" && isUnmodifiedLetterKey(ev.mods) && ev.key === KEY_Q;
   }
   if (ev.kind === "text") {
-    return ev.codepoint === KEY_Q || ev.codepoint === 113;
+    return ev.codepoint === KEY_Q || ev.codepoint === KEY_LOWER_Q;
   }
   return false;
 }
 
+function isUnmodifiedTextQuitEvent(ev: ZrevEvent): boolean {
+  if (ev.kind !== "text") return false;
+  return (
+    ev.codepoint === KEY_Q || ev.codepoint === KEY_LOWER_Q || ev.codepoint === CTRL_C_CODEPOINT
+  );
+}
+
+function isUnhandledCtrlCKeyEvent(ev: ZrevEvent): boolean {
+  if (ev.kind !== "key") return false;
+  if (ev.action !== "down") return false;
+  if (ev.key !== KEY_C) return false;
+  const hasCtrl = (ev.mods & ZR_MOD_CTRL) !== 0;
+  if (!hasCtrl) return false;
+  return (ev.mods & (ZR_MOD_ALT | ZR_MOD_META)) === 0;
+}
+
 type ProcessLike = Readonly<{
   on?: ((event: string, handler: (...args: unknown[]) => void) => unknown) | undefined;
   off?: ((event: string, handler: (...args: unknown[]) => void) => unknown) | undefined;
@@ -940,6 +960,27 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
     });
   }
 
+  function stopFromUnhandledQuitEvent(): void {
+    let stopPromise: Promise<void>;
+    try {
+      stopPromise = app.stop();
+    } catch (e: unknown) {
+      // Late events can race while a stop is already in-flight; avoid double-fatal.
+      if (lifecycleBusy === "stop") return;
+      enqueueFatal(
+        "ZRUI_BACKEND_ERROR",
+        `stop threw after unhandled quit input: ${describeThrown(e)}`,
+      );
+      return;
+    }
+    void stopPromise.catch((e: unknown) => {
+      enqueueFatal(
+        "ZRUI_BACKEND_ERROR",
+        `stop rejected after unhandled quit input: ${describeThrown(e)}`,
+      );
+    });
+  }
+
   function buildRuntimeBreadcrumbSnapshot(renderTimeMs: number): RuntimeBreadcrumbSnapshot | null {
     if (!runtimeBreadcrumbsEnabled) return null;
     const widgetSnapshot = widgetRenderer.getRuntimeBreadcrumbSnapshot();
@@ -1310,6 +1351,15 @@ export function createApp<S>(opts: CreateAppStateOptions<S> | CreateAppRoutesOnl
             emit({ kind: "action", ...routed.action });
             if (sm.state !== "Running") return;
           }
+          if (
+            routed.action === undefined &&
+            !routed.needsRender &&
+            routed.consumed !== true &&
+            (isUnmodifiedTextQuitEvent(ev) || isUnhandledCtrlCKeyEvent(ev))
+          ) {
+            noteBreadcrumbConsumptionPath("widgetRouting");
+            stopFromUnhandledQuitEvent();
+          }
         }
       }
     } finally {

packages/core/src/app/widgetRenderer.ts

@@ -406,6 +406,7 @@ export type WidgetRenderPlan = Readonly<{
 export type WidgetRoutingOutcome = Readonly<{
   needsRender: boolean;
   action?: RoutedAction;
+  consumed?: boolean;
 }>;
 
 /**
@@ -509,6 +510,10 @@ const EMPTY_CONSTRAINT_BREADCRUMBS: RuntimeBreadcrumbConstraintsSummary = Object
 });
 const ROUTE_RENDER: WidgetRoutingOutcome = Object.freeze({ needsRender: true });
 const ROUTE_NO_RENDER: WidgetRoutingOutcome = Object.freeze({ needsRender: false });
+const ROUTE_NO_RENDER_CONSUMED: WidgetRoutingOutcome = Object.freeze({
+  needsRender: false,
+  consumed: true,
+});
 const ZERO_RECT: Rect = Object.freeze({ x: 0, y: 0, w: 0, h: 0 });
 const INCREMENTAL_DAMAGE_AREA_FRACTION = 0.45;
 const DEFAULT_POSITION_TRANSITION_DURATION_MS = 180;
@@ -1896,7 +1901,7 @@ export class WidgetRenderer<S> {
     if (event.kind === "key" && event.action === "down") {
       const shortcutResult = this.routeOverlayShortcut(event);
       if (shortcutResult === "matched") return ROUTE_RENDER;
-      if (shortcutResult === "pending") return ROUTE_NO_RENDER;
+      if (shortcutResult === "pending") return ROUTE_NO_RENDER_CONSUMED;
 
       const topLayerId =
         this.layerStack.length > 0 ? (this.layerStack[this.layerStack.length - 1] ?? null) : null;
@@ -2042,12 +2047,12 @@ export class WidgetRenderer<S> {
 
           if (isCut && editor.readOnly !== true) {
             const cut = selection ? deleteRange(editor.lines, selection) : null;
-            if (!cut) return ROUTE_NO_RENDER;
+            if (!cut) return ROUTE_NO_RENDER_CONSUMED;
             editor.onSelectionChange(null);
             editor.onChange(cut.lines, cut.cursor);
             return ROUTE_RENDER;
           }
-          return ROUTE_NO_RENDER;
+          return ROUTE_NO_RENDER_CONSUMED;
         }
 
         const rect = this.rectById.get(editor.id) ?? null;

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

@@ -17,6 +17,7 @@ import type { InputMeta } from "../../runtime/widgetMeta.js";
 export type InputEditingRoutingOutcome = Readonly<{
   needsRender: boolean;
   action?: RoutedAction;
+  consumed?: boolean;
 }>;
 
 type RouteInputEditingEventContext = Readonly<{
@@ -32,7 +33,10 @@ type RouteInputEditingEventContext = Readonly<{
 }>;
 
 const ROUTE_RENDER: InputEditingRoutingOutcome = Object.freeze({ needsRender: true });
-const ROUTE_NO_RENDER: InputEditingRoutingOutcome = Object.freeze({ needsRender: false });
+const ROUTE_NO_RENDER_CONSUMED: InputEditingRoutingOutcome = Object.freeze({
+  needsRender: false,
+  consumed: true,
+});
 
 function invokeOnInputSafely(
   meta: InputMeta,
@@ -180,7 +184,7 @@ export function routeInputEditingEvent(
             return Object.freeze({ needsRender: true, action });
           }
         }
-        return ROUTE_NO_RENDER;
+        return ROUTE_NO_RENDER_CONSUMED;
       }
     }
 
@@ -203,7 +207,7 @@ export function routeInputEditingEvent(
         });
         return Object.freeze({ needsRender: true, action });
       }
-      return ROUTE_NO_RENDER;
+      return ROUTE_NO_RENDER_CONSUMED;
     }
   }