@rezi-ui/core 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/app/createApp.d.ts

@@ -23,6 +23,7 @@
  */
 import { type RuntimeBackend } from "../backend.js";
 import type { App, AppConfig, AppLayoutSnapshot, AppRenderMetrics } from "../index.js";
+import { type ResponsiveBreakpointThresholds } from "../layout/responsive.js";
 import type { RouteDefinition } from "../router/types.js";
 import type { Theme } from "../theme/theme.js";
 import type { ThemeDefinition } from "../theme/tokens.js";
@@ -31,6 +32,8 @@ type ResolvedAppConfig = Readonly<{
     fpsCap: number;
     maxEventBytes: number;
     maxDrawlistBytes: number;
+    rootPadding: number;
+    breakpointThresholds: ResponsiveBreakpointThresholds;
     useV2Cursor: boolean;
     drawlistValidateParams: boolean;
     drawlistReuseOutputBuffer: boolean;

package/dist/app/createApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createApp.d.ts","sourceRoot":"","sources":["../../src/app/createApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EACV,GAAG,EACH,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAIjB,MAAM,aAAa,CAAC;AAoBrB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQ1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAoB1D,oDAAoD;AACpD,KAAK,iBAAiB,GAAG,QAAQ,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,sBAAsB,EAAE,OAAO,CAAC;IAChC,yBAAyB,EAAE,OAAO,CAAC;IACnC,6BAA6B,EAAE,MAAM,CAAC;IACtC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACtE,iBAAiB,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACzE,CAAC,CAAC;AAwBH,eAAO,MAAM,uCAAuC,4BAA4B,CAAC;AACjF,eAAO,MAAM,gDAAgD,oCAAoC,CAAC;AAyGlG,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,iBAAiB,CAmDjF;AAoDD,KAAK,oBAAoB,GAAG,QAAQ,CAAC;IACnC,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,GAAG,eAAe,CAAC;CACjC,CAAC,CAAC;AAEH,KAAK,qBAAqB,CAAC,CAAC,IAAI,oBAAoB,GAClD,QAAQ,CAAC;IACP,YAAY,EAAE,CAAC,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC,CAAC;AAEL,KAAK,0BAA0B,GAAG,oBAAoB,GACpD,QAAQ,CAAC;IACP,MAAM,EAAE,SAAS,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACrC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC,CAAC;AAEL;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,0BAA0B,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AACxF,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"createApp.d.ts","sourceRoot":"","sources":["../../src/app/createApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EACV,GAAG,EACH,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAKjB,MAAM,aAAa,CAAC;AAmBrB,OAAO,EACL,KAAK,8BAA8B,EAEpC,MAAM,yBAAyB,CAAC;AAMjC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQ1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAsB1D,oDAAoD;AACpD,KAAK,iBAAiB,GAAG,QAAQ,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB,EAAE,8BAA8B,CAAC;IACrD,WAAW,EAAE,OAAO,CAAC;IACrB,sBAAsB,EAAE,OAAO,CAAC;IAChC,yBAAyB,EAAE,OAAO,CAAC;IACnC,6BAA6B,EAAE,MAAM,CAAC;IACtC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACtE,iBAAiB,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACzE,CAAC,CAAC;AA0BH,eAAO,MAAM,uCAAuC,4BAA4B,CAAC;AACjF,eAAO,MAAM,gDAAgD,oCAAoC,CAAC;AAgIlG,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,iBAAiB,CA0DjF;AAuKD,KAAK,oBAAoB,GAAG,QAAQ,CAAC;IACnC,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,GAAG,eAAe,CAAC;CACjC,CAAC,CAAC;AAEH,KAAK,qBAAqB,CAAC,CAAC,IAAI,oBAAoB,GAClD,QAAQ,CAAC;IACP,YAAY,EAAE,CAAC,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC,CAAC;AAEL,KAAK,0BAA0B,GAAG,oBAAoB,GACpD,QAAQ,CAAC;IACP,MAAM,EAAE,SAAS,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACrC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC,CAAC;AAEL;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,0BAA0B,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AACxF,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC"}

package/dist/app/createApp.js

@@ -23,13 +23,16 @@
  */
 import { ZrUiError } from "../abi.js";
 import { BACKEND_DRAWLIST_V2_MARKER, BACKEND_DRAWLIST_VERSION_MARKER, BACKEND_FPS_CAP_MARKER, BACKEND_MAX_EVENT_BYTES_MARKER, FRAME_ACCEPTED_ACK_MARKER, } from "../backend.js";
-import { createManagerState, getMode, registerBindings, registerModes, resetChordState, routeKeyEvent, setMode, } from "../keybindings/index.js";
+import { createManagerState, getBindings, getMode, getPendingChord, registerBindings, registerModes, resetChordState, routeKeyEvent, setMode, } from "../keybindings/index.js";
+import { ZR_MOD_ALT, ZR_MOD_CTRL, ZR_MOD_META } from "../keybindings/keyCodes.js";
+import { normalizeBreakpointThresholds, } from "../layout/responsive.js";
 import { PERF_ENABLED, perfMarkEnd, perfMarkStart, perfNow, perfRecord } from "../perf/perf.js";
 import { parseEventBatchV1 } from "../protocol/zrev_v1.js";
 import { createRouterIntegration } from "../router/integration.js";
 import { DEFAULT_TERMINAL_PROFILE, terminalProfileFromCaps, } from "../terminalProfile.js";
 import { defaultTheme } from "../theme/defaultTheme.js";
 import { coerceToLegacyTheme } from "../theme/interop.js";
+import { ui } from "../widgets/ui.js";
 import { RawRenderer } from "./rawRenderer.js";
 import { isRuntimeBreadcrumbEventKind, mergeRuntimeBreadcrumbSnapshot, toRuntimeBreadcrumbAction, } from "./runtimeBreadcrumbs.js";
 import { AppStateMachine } from "./stateMachine.js";
@@ -41,6 +44,8 @@ const DEFAULT_CONFIG = Object.freeze({
     fpsCap: 60,
     maxEventBytes: 1 << 20 /* 1 MiB */,
     maxDrawlistBytes: 2 << 20 /* 2 MiB */,
+    rootPadding: 0,
+    breakpointThresholds: normalizeBreakpointThresholds(undefined),
     useV2Cursor: false,
     drawlistValidateParams: true,
     drawlistReuseOutputBuffer: true,
@@ -134,6 +139,27 @@ async function loadTerminalProfile(backend) {
         return DEFAULT_TERMINAL_PROFILE;
     }
 }
+function buildLayoutDebugOverlay(rectById) {
+    if (rectById.size === 0)
+        return null;
+    const rows = [...rectById.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .slice(0, 18)
+        .map(([id, rect]) => ui.text(`${id}  ${String(rect.x)},${String(rect.y)}  ${String(rect.w)}x${String(rect.h)}`));
+    const panel = ui.box({ border: "single", title: `Layout (${String(rectById.size)})`, p: 1 }, [
+        ui.column({ gap: 0 }, rows),
+    ]);
+    return ui.layer({
+        id: "rezi.layout.debug.overlay",
+        zIndex: 2_000_000_000,
+        modal: false,
+        backdrop: "none",
+        closeOnEscape: false,
+        content: ui.column({ width: "100%", height: "100%", justify: "end", p: 1 }, [
+            ui.row({ width: "100%", justify: "start" }, [panel]),
+        ]),
+    });
+}
 /** Apply defaults to user-provided config, validating all values. */
 export function resolveAppConfig(config) {
     if (!config)
@@ -147,6 +173,10 @@ export function resolveAppConfig(config) {
     const maxDrawlistBytes = config.maxDrawlistBytes === undefined
         ? DEFAULT_CONFIG.maxDrawlistBytes
         : requirePositiveInt("maxDrawlistBytes", config.maxDrawlistBytes);
+    const rootPadding = config.rootPadding === undefined
+        ? DEFAULT_CONFIG.rootPadding
+        : requireNonNegativeInt("rootPadding", config.rootPadding);
+    const breakpointThresholds = normalizeBreakpointThresholds(config.breakpoints);
     const useV2Cursor = config.useV2Cursor === true;
     const drawlistValidateParams = config.drawlistValidateParams === undefined
         ? DEFAULT_CONFIG.drawlistValidateParams
@@ -166,6 +196,8 @@ export function resolveAppConfig(config) {
         fpsCap,
         maxEventBytes,
         maxDrawlistBytes,
+        rootPadding,
+        breakpointThresholds,
         useV2Cursor,
         drawlistValidateParams,
         drawlistReuseOutputBuffer,
@@ -180,6 +212,83 @@ function describeThrown(v) {
         return `${v.name}: ${v.message}`;
     return String(v);
 }
+const KEY_Q = 81;
+const KEY_R = 82;
+function captureTopLevelViewError(value) {
+    if (value instanceof Error) {
+        return Object.freeze({
+            code: "ZRUI_USER_CODE_THROW",
+            detail: `${value.name}: ${value.message}`,
+            message: value.message,
+            ...(typeof value.stack === "string" && value.stack.length > 0 ? { stack: value.stack } : {}),
+        });
+    }
+    const detail = String(value);
+    return Object.freeze({
+        code: "ZRUI_USER_CODE_THROW",
+        detail,
+        message: detail,
+    });
+}
+function buildTopLevelViewErrorScreen(error) {
+    const lines = [`Code: ${error.code}`, `Message: ${error.message}`];
+    if (error.stack === undefined || error.stack.length === 0) {
+        lines.push(`Detail: ${error.detail}`);
+    }
+    return ui.column({ width: "100%", height: "100%", justify: "center", align: "center", p: 1 }, [
+        ui.box({
+            width: "100%",
+            height: "100%",
+            border: "single",
+            title: "Runtime Error",
+            p: 1,
+        }, [
+            ui.errorDisplay(lines.join("\n"), {
+                title: "Top-level view() threw",
+                ...(error.stack === undefined || error.stack.length === 0
+                    ? {}
+                    : { stack: error.stack, showStack: true }),
+            }),
+            ui.callout("Press R to retry, Q to quit", { variant: "warning" }),
+        ]),
+    ]);
+}
+function isUnmodifiedLetterKey(mods) {
+    return (mods & (ZR_MOD_CTRL | ZR_MOD_ALT | ZR_MOD_META)) === 0;
+}
+function isTopLevelRetryEvent(ev) {
+    if (ev.kind === "key") {
+        return ev.action === "down" && isUnmodifiedLetterKey(ev.mods) && ev.key === KEY_R;
+    }
+    if (ev.kind === "text") {
+        return ev.codepoint === KEY_R || ev.codepoint === 114;
+    }
+    return false;
+}
+function isTopLevelQuitEvent(ev) {
+    if (ev.kind === "key") {
+        return ev.action === "down" && isUnmodifiedLetterKey(ev.mods) && ev.key === KEY_Q;
+    }
+    if (ev.kind === "text") {
+        return ev.codepoint === KEY_Q || ev.codepoint === 113;
+    }
+    return false;
+}
+function readProcessLike() {
+    const processRef = globalThis.process;
+    if (!processRef || typeof processRef !== "object")
+        return null;
+    return processRef;
+}
+function removeSignalHandler(proc, signal, handler) {
+    if (typeof proc.off === "function") {
+        proc.off(signal, handler);
+        return;
+    }
+    if (typeof proc.removeListener === "function") {
+        proc.removeListener(signal, handler);
+    }
+}
 /**
  * Convert a text codepoint to a key code for keybinding matching.
  * Letters are normalized to uppercase (A-Z = 65-90).
@@ -240,10 +349,14 @@ export function createApp(opts) {
     let mode = null;
     let drawFn = null;
     let viewFn = null;
+    let topLevelViewError = null;
+    let debugLayoutEnabled = false;
     const hasInitialState = "initialState" in opts;
     let committedState = hasInitialState ? opts.initialState : Object.freeze({});
     const updates = new UpdateQueue();
     const handlers = [];
+    const focusHandlers = [];
+    let lastEmittedFocusId = null;
     const DIRTY_RENDER = 1 << 0;
     const DIRTY_LAYOUT = 1 << 1;
     const DIRTY_VIEW = 1 << 2;
@@ -264,6 +377,7 @@ export function createApp(opts) {
     let inEventHandlerDepth = 0;
     let lifecycleBusy = null;
     let pollToken = 0;
+    let settleActiveRun = null;
     let userCommitScheduled = false;
     // Perf tracking: submit time for backend_ack calculation
     let submitFrameStartMs = null;
@@ -337,6 +451,8 @@ export function createApp(opts) {
         backend,
         drawlistVersion,
         maxDrawlistBytes: config.maxDrawlistBytes,
+        rootPadding: config.rootPadding,
+        breakpointThresholds: config.breakpointThresholds,
         terminalProfile,
         useV2Cursor: config.useV2Cursor,
         ...(opts.config?.drawlistValidateParams === undefined
@@ -348,6 +464,7 @@ export function createApp(opts) {
         requestView: requestViewFromRenderer,
         collectRuntimeBreadcrumbs: runtimeBreadcrumbsEnabled,
     });
+    lastEmittedFocusId = widgetRenderer.getFocusedId();
     let routeStateUpdater = null;
     let routerIntegration = null;
     if (routes !== undefined) {
@@ -390,9 +507,13 @@ export function createApp(opts) {
         return false;
     }
     function applyRoutedKeybindingState(routeInputState, routeNextState) {
+        const previousChordState = keybindingState.chordState;
         // If handlers did not mutate keybinding state, take the routed state directly.
         if (keybindingState === routeInputState) {
             keybindingState = routeNextState;
+            if (keybindingState.chordState !== previousChordState) {
+                markDirty(DIRTY_VIEW);
+            }
             return;
         }
         // Preserve handler-triggered mode changes (for example app.setMode() in a binding).
@@ -405,6 +526,9 @@ export function createApp(opts) {
             ...keybindingState,
             chordState: routeNextState.chordState,
         });
+        if (keybindingState.chordState !== previousChordState) {
+            markDirty(DIRTY_VIEW);
+        }
     }
     function noteBreadcrumbEvent(kind) {
         breadcrumbEventTracked = false;
@@ -430,6 +554,33 @@ export function createApp(opts) {
             return;
         breadcrumbLastAction = toRuntimeBreadcrumbAction(action);
     }
+    function retryTopLevelViewError() {
+        topLevelViewError = null;
+        markDirty(DIRTY_VIEW | DIRTY_LAYOUT);
+    }
+    function quitFromTopLevelViewError() {
+        let stopPromise;
+        try {
+            stopPromise = app.stop();
+        }
+        catch {
+            try {
+                app.dispose();
+            }
+            catch {
+                // ignore
+            }
+            return;
+        }
+        void stopPromise.finally(() => {
+            try {
+                app.dispose();
+            }
+            catch {
+                // ignore
+            }
+        });
+    }
     function buildRuntimeBreadcrumbSnapshot(renderTimeMs) {
         if (!runtimeBreadcrumbsEnabled)
             return null;
@@ -476,6 +627,7 @@ export function createApp(opts) {
             ...(opts.routeHistoryMaxDepth === undefined
                 ? {}
                 : { maxHistoryDepth: opts.routeHistoryMaxDepth }),
+            getState: () => committedState,
             // Route transitions can swap the entire screen tree; force both commit
             // and layout so id->rect indexes and focus metadata stay in sync.
             requestRouteRender: () => markDirty(DIRTY_VIEW | DIRTY_LAYOUT),
@@ -507,6 +659,28 @@ export function createApp(opts) {
             inEventHandlerDepth--;
         }
     }
+    function emitFocusChangeIfNeeded() {
+        const focusedId = widgetRenderer.getFocusedId();
+        if (focusedId === lastEmittedFocusId)
+            return true;
+        lastEmittedFocusId = focusedId;
+        const info = widgetRenderer.getCurrentFocusInfo();
+        const snapshot = [];
+        for (const slot of focusHandlers) {
+            if (slot.active.value)
+                snapshot.push(slot.fn);
+        }
+        for (const fn of snapshot) {
+            try {
+                fn(info);
+            }
+            catch (e) {
+                enqueueFatal("ZRUI_USER_CODE_THROW", `onFocusChange handler threw: ${describeThrown(e)}`);
+                return false;
+            }
+        }
+        return true;
+    }
     function doFatal(code, detail) {
         if (sm.state !== "Running")
             return;
@@ -546,6 +720,7 @@ export function createApp(opts) {
                 catch {
                     // ignore
                 }
+                settleActiveRun?.();
             });
         }
         catch {
@@ -555,6 +730,7 @@ export function createApp(opts) {
             catch {
                 // ignore
             }
+            settleActiveRun?.();
         }
     }
     function releaseOnce(batch) {
@@ -609,7 +785,13 @@ export function createApp(opts) {
                     const prev = viewport;
                     if (prev === null || prev.cols !== ev.cols || prev.rows !== ev.rows) {
                         viewport = Object.freeze({ cols: ev.cols, rows: ev.rows });
-                        markDirty(DIRTY_LAYOUT);
+                        if (widgetRenderer.hasViewportAwareComposites()) {
+                            widgetRenderer.invalidateCompositeWidgets();
+                            markDirty(DIRTY_LAYOUT | DIRTY_VIEW);
+                        }
+                        else {
+                            markDirty(DIRTY_LAYOUT);
+                        }
                     }
                 }
                 if (ev.kind === "tick" && mode === "widget") {
@@ -635,6 +817,25 @@ export function createApp(opts) {
                         }
                     }
                 }
+                if (mode === "widget" && topLevelViewError !== null) {
+                    if (isTopLevelRetryEvent(ev)) {
+                        noteBreadcrumbConsumptionPath("widgetRouting");
+                        retryTopLevelViewError();
+                        continue;
+                    }
+                    if (isTopLevelQuitEvent(ev)) {
+                        noteBreadcrumbConsumptionPath("widgetRouting");
+                        quitFromTopLevelViewError();
+                        continue;
+                    }
+                    if (ev.kind === "key" ||
+                        ev.kind === "text" ||
+                        ev.kind === "paste" ||
+                        ev.kind === "mouse") {
+                        noteBreadcrumbConsumptionPath("widgetRouting");
+                        continue;
+                    }
+                }
                 const isWidgetRoutableEvent = ev.kind === "key" || ev.kind === "text" || ev.kind === "paste" || ev.kind === "mouse";
                 if (mode === "widget" && isWidgetRoutableEvent) {
                     if (keybindingsEnabled) {
@@ -708,6 +909,8 @@ export function createApp(opts) {
                         enqueueFatal("ZRUI_USER_CODE_THROW", `widget routing threw: ${describeThrown(e)}`);
                         return;
                     }
+                    if (!emitFocusChangeIfNeeded())
+                        return;
                     if (routed.needsRender)
                         markDirty(DIRTY_RENDER);
                     if (routed.action) {
@@ -914,14 +1117,37 @@ export function createApp(opts) {
             // newly-committed tree against stale layout nodes until the next resize.
             checkLayoutStability: (pendingDirtyFlags & DIRTY_LAYOUT) === 0 && (pendingDirtyFlags & DIRTY_VIEW) !== 0,
         };
+        const resilientView = (state) => {
+            if (topLevelViewError !== null) {
+                return buildTopLevelViewErrorScreen(topLevelViewError);
+            }
+            try {
+                return vf(state);
+            }
+            catch (e) {
+                topLevelViewError = captureTopLevelViewError(e);
+                return buildTopLevelViewErrorScreen(topLevelViewError);
+            }
+        };
         const renderStart = perfNow();
         const submitToken = perfMarkStart("submit_frame");
-        const res = widgetRenderer.submitFrame(vf, snapshot, viewport, theme, hooks, plan);
+        const frameView = debugLayoutEnabled
+            ? (state) => {
+                const root = resilientView(state);
+                const overlay = buildLayoutDebugOverlay(widgetRenderer.getRectByIdIndex());
+                if (!overlay)
+                    return root;
+                return ui.layers([root, overlay]);
+            }
+            : resilientView;
+        const res = widgetRenderer.submitFrame(frameView, snapshot, viewport, theme, hooks, plan);
         perfMarkEnd("submit_frame", submitToken);
         if (!res.ok) {
             fatalNowOrEnqueue(res.code, res.detail);
             return;
         }
+        if (!emitFocusChangeIfNeeded())
+            return;
         const renderTime = perfNow() - renderStart;
         const runtimeBreadcrumbs = buildRuntimeBreadcrumbSnapshot(Math.max(0, renderTime));
         if (!emitInternalRenderMetrics(renderTime, runtimeBreadcrumbs))
@@ -1079,6 +1305,17 @@ export function createApp(opts) {
                 active.value = false;
             };
         },
+        onFocusChange(handler) {
+            assertOperational("onFocusChange");
+            if (inCommit || inRender) {
+                throwCode("ZRUI_REENTRANT_CALL", "onFocusChange: re-entrant call");
+            }
+            const active = { value: true };
+            focusHandlers.push({ fn: handler, active });
+            return () => {
+                active.value = false;
+            };
+        },
         update(updater) {
             assertOperational("update");
             if (inCommit)
@@ -1103,6 +1340,18 @@ export function createApp(opts) {
             theme = nextTheme;
             requestRenderFromRenderer();
         },
+        debugLayout(enabled) {
+            assertOperational("debugLayout");
+            if (mode === "raw") {
+                throwCode("ZRUI_MODE_CONFLICT", "debugLayout: not available in draw mode");
+            }
+            const next = enabled === undefined ? !debugLayoutEnabled : enabled === true;
+            if (next === debugLayoutEnabled)
+                return debugLayoutEnabled;
+            debugLayoutEnabled = next;
+            requestViewFromRenderer();
+            return debugLayoutEnabled;
+        },
         start() {
             assertOperational("start");
             assertNotReentrant("start");
@@ -1122,6 +1371,7 @@ export function createApp(opts) {
             }
             return p.then(async () => {
                 lifecycleBusy = null;
+                topLevelViewError = null;
                 terminalProfile = await loadTerminalProfile(backend);
                 widgetRenderer.setTerminalProfile(terminalProfile);
                 sm.toRunning();
@@ -1134,6 +1384,91 @@ export function createApp(opts) {
                 throw new ZrUiError("ZRUI_BACKEND_ERROR", `backend.start rejected: ${describeThrown(e)}`);
             });
         },
+        run() {
+            assertOperational("run");
+            assertNotReentrant("run");
+            if (lifecycleBusy)
+                throwCode("ZRUI_INVALID_STATE", "run: lifecycle operation already in flight");
+            sm.assertOneOf(["Created", "Stopped"], "run: must be Created or Stopped");
+            if (mode === null)
+                throwCode("ZRUI_NO_RENDER_MODE", "run: no render mode selected");
+            const proc = readProcessLike();
+            const addSignalHandler = proc !== null && typeof proc.on === "function" ? proc.on.bind(proc) : null;
+            const canRegisterSignals = addSignalHandler !== null;
+            const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+            const handlers = [];
+            let runSettled = false;
+            let resolveRun;
+            const runPromise = new Promise((resolve) => {
+                resolveRun = resolve;
+            });
+            const cleanupSignalHandlers = () => {
+                if (!proc)
+                    return;
+                for (const entry of handlers) {
+                    removeSignalHandler(proc, entry.signal, entry.handler);
+                }
+                handlers.length = 0;
+            };
+            const settleRun = () => {
+                if (runSettled)
+                    return;
+                runSettled = true;
+                cleanupSignalHandlers();
+                if (settleActiveRun === settleRun)
+                    settleActiveRun = null;
+                resolveRun();
+            };
+            const onSignal = () => {
+                if (runSettled)
+                    return;
+                runSettled = true;
+                cleanupSignalHandlers();
+                if (settleActiveRun === settleRun)
+                    settleActiveRun = null;
+                void (async () => {
+                    try {
+                        if (sm.state === "Running")
+                            await app.stop();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    try {
+                        app.dispose();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    try {
+                        proc?.exit?.(0);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    resolveRun();
+                })();
+            };
+            if (canRegisterSignals) {
+                for (const signal of signals) {
+                    const handler = () => onSignal();
+                    handlers.push(Object.freeze({ signal, handler }));
+                    addSignalHandler(signal, handler);
+                }
+            }
+            settleActiveRun = settleRun;
+            return app.start().then(() => {
+                if (!canRegisterSignals) {
+                    settleRun();
+                }
+                return runPromise;
+            }, (e) => {
+                cleanupSignalHandlers();
+                if (settleActiveRun === settleRun)
+                    settleActiveRun = null;
+                throw e;
+            });
+        },
         stop() {
             assertOperational("stop");
             assertNotReentrant("stop");
@@ -1158,6 +1493,7 @@ export function createApp(opts) {
             return p.then(() => {
                 lifecycleBusy = null;
                 sm.toStopped();
+                settleActiveRun?.();
             }, (e) => {
                 lifecycleBusy = null;
                 throw new ZrUiError("ZRUI_BACKEND_ERROR", `backend.stop rejected: ${describeThrown(e)}`);
@@ -1191,6 +1527,7 @@ export function createApp(opts) {
             catch {
                 // ignore
             }
+            settleActiveRun?.();
         },
         /* --- Keybinding API --- */
         keys(bindings) {
@@ -1210,6 +1547,12 @@ export function createApp(opts) {
         getMode() {
             return getMode(keybindingState);
         },
+        getBindings(mode) {
+            return getBindings(keybindingState, mode);
+        },
+        get pendingChord() {
+            return getPendingChord(keybindingState);
+        },
         getTerminalProfile() {
             return terminalProfile;
         },