@rezi-ui/core 0.1.0-alpha.6 → 0.1.0-alpha.63

package/dist/app/createApp.js

@@ -22,219 +22,134 @@
  * @see docs/guide/lifecycle-and-updates.md
  */
 import { ZrUiError } from "../abi.js";
-import { FRAME_ACCEPTED_ACK_MARKER, } from "../backend.js";
-import { createManagerState, getMode, registerBindings, registerModes, routeKeyEvent, setMode, } from "../keybindings/index.js";
-import { PERF_ENABLED, perfMarkEnd, perfMarkStart, perfNow, perfRecord } from "../perf/perf.js";
-import { parseEventBatchV1 } from "../protocol/zrev_v1.js";
+import { BACKEND_FPS_CAP_MARKER, BACKEND_MAX_EVENT_BYTES_MARKER, } from "../backend.js";
+import { describeThrown } from "../debug/describeThrown.js";
+import { createManagerState, getBindings, getMode, getPendingChord, setMode, } from "../keybindings/index.js";
+import { PERF_ENABLED, perfMarkStart } from "../perf/perf.js";
+import { createRouterIntegration } from "../router/integration.js";
+import { DEFAULT_TERMINAL_PROFILE } from "../terminalProfile.js";
 import { defaultTheme } from "../theme/defaultTheme.js";
-import { coerceToLegacyTheme } from "../theme/interop.js";
+import { compileTheme } from "../theme/theme.js";
+import { createRuntimeBreadcrumbHelpers, } from "./createApp/breadcrumbs.js";
+import { loadTerminalProfile, readBackendDrawlistVersionMarker, readBackendPositiveIntMarker, requirePositiveInt, resolveAppConfig as resolveAppConfigImpl, } from "./createApp/config.js";
+import { DIRTY_LAYOUT, DIRTY_RENDER, DIRTY_VIEW, createDirtyTracker, } from "./createApp/dirtyPlan.js";
+import { createEventLoop } from "./createApp/eventLoop.js";
+import { createFocusDispatcher } from "./createApp/focusDispatcher.js";
+import { createAppGuards } from "./createApp/guards.js";
+import { computeKeybindingsEnabled, createAppKeybindingHelpers } from "./createApp/keybindings.js";
+import { createRenderLoop } from "./createApp/renderLoop.js";
+import { createRunSignalController, readProcessLike } from "./createApp/runSignals.js";
 import { RawRenderer } from "./rawRenderer.js";
 import { AppStateMachine } from "./stateMachine.js";
 import { TurnScheduler } from "./turnScheduler.js";
 import { UpdateQueue } from "./updateQueue.js";
-import { WidgetRenderer, } from "./widgetRenderer.js";
-/** Default configuration values. */
-const DEFAULT_CONFIG = Object.freeze({
-    fpsCap: 60,
-    maxEventBytes: 1 << 20 /* 1 MiB */,
-    maxDrawlistBytes: 2 << 20 /* 2 MiB */,
-    useV2Cursor: false,
-    drawlistValidateParams: true,
-    drawlistReuseOutputBuffer: true,
-    drawlistEncodedStringCacheCap: 1024,
-    maxFramesInFlight: 1,
-    internal_onRender: undefined,
-    internal_onLayout: undefined,
-});
-const SYNC_FRAME_ACK_MARKER = "__reziSyncFrameAck";
+import { WidgetRenderer } from "./widgetRenderer.js";
+export const APP_INTERNAL_REQUEST_VIEW_LAYOUT_MARKER = "__reziRequestViewLayout";
+export const APP_INTERNAL_SET_RUNTIME_BREADCRUMB_HOOKS_MARKER = "__reziSetRuntimeBreadcrumbHooks";
 function invalidProps(detail) {
     throw new ZrUiError("ZRUI_INVALID_PROPS", detail);
 }
-function requirePositiveInt(name, v) {
-    if (!Number.isInteger(v) || v <= 0)
-        invalidProps(`${name} must be a positive integer`);
-    return v;
-}
-function requireNonNegativeInt(name, v) {
-    if (!Number.isInteger(v) || v < 0)
-        invalidProps(`${name} must be a non-negative integer`);
-    return v;
-}
-function isSyncFrameAck(p) {
-    return (typeof p === "object" &&
-        p !== null &&
-        p[SYNC_FRAME_ACK_MARKER] === true);
-}
-function getAcceptedFrameAck(p) {
-    if (typeof p !== "object" || p === null)
-        return null;
-    const marker = p[FRAME_ACCEPTED_ACK_MARKER];
-    if (typeof marker !== "object" || marker === null)
-        return null;
-    if (typeof marker.then !== "function")
-        return null;
-    return marker;
-}
-/** Apply defaults to user-provided config, validating all values. */
 export function resolveAppConfig(config) {
-    if (!config)
-        return DEFAULT_CONFIG;
-    const fpsCap = config.fpsCap === undefined
-        ? DEFAULT_CONFIG.fpsCap
-        : requirePositiveInt("fpsCap", config.fpsCap);
-    const maxEventBytes = config.maxEventBytes === undefined
-        ? DEFAULT_CONFIG.maxEventBytes
-        : requirePositiveInt("maxEventBytes", config.maxEventBytes);
-    const maxDrawlistBytes = config.maxDrawlistBytes === undefined
-        ? DEFAULT_CONFIG.maxDrawlistBytes
-        : requirePositiveInt("maxDrawlistBytes", config.maxDrawlistBytes);
-    const useV2Cursor = config.useV2Cursor === true;
-    const drawlistValidateParams = config.drawlistValidateParams === undefined
-        ? DEFAULT_CONFIG.drawlistValidateParams
-        : config.drawlistValidateParams !== false;
-    const drawlistReuseOutputBuffer = config.drawlistReuseOutputBuffer === undefined
-        ? DEFAULT_CONFIG.drawlistReuseOutputBuffer
-        : config.drawlistReuseOutputBuffer === true;
-    const drawlistEncodedStringCacheCap = config.drawlistEncodedStringCacheCap === undefined
-        ? DEFAULT_CONFIG.drawlistEncodedStringCacheCap
-        : requireNonNegativeInt("drawlistEncodedStringCacheCap", config.drawlistEncodedStringCacheCap);
-    const maxFramesInFlight = config.maxFramesInFlight === undefined
-        ? DEFAULT_CONFIG.maxFramesInFlight
-        : Math.min(4, Math.max(1, requirePositiveInt("maxFramesInFlight", config.maxFramesInFlight)));
-    const internal_onRender = typeof config.internal_onRender === "function" ? config.internal_onRender : undefined;
-    const internal_onLayout = typeof config.internal_onLayout === "function" ? config.internal_onLayout : undefined;
-    return Object.freeze({
-        fpsCap,
-        maxEventBytes,
-        maxDrawlistBytes,
-        useV2Cursor,
-        drawlistValidateParams,
-        drawlistReuseOutputBuffer,
-        drawlistEncodedStringCacheCap,
-        maxFramesInFlight,
-        internal_onRender,
-        internal_onLayout,
-    });
-}
-function describeThrown(v) {
-    if (v instanceof Error)
-        return `${v.name}: ${v.message}`;
-    return String(v);
-}
-/**
- * Convert a text codepoint to a key code for keybinding matching.
- * Letters are normalized to uppercase (A-Z = 65-90).
- * Returns null if codepoint is not matchable.
- */
-function codepointToKeyCode(codepoint) {
-    // Lowercase letters -> uppercase
-    if (codepoint >= 97 && codepoint <= 122) {
-        return codepoint - 32; // 'a' (97) -> 'A' (65)
-    }
-    // Uppercase letters
-    if (codepoint >= 65 && codepoint <= 90) {
-        return codepoint;
-    }
-    // Digits and printable ASCII
-    if (codepoint >= 32 && codepoint <= 126) {
-        return codepoint;
-    }
-    return null;
+    return resolveAppConfigImpl(config);
 }
-/**
- * Create a Rezi application instance.
- *
- * @typeParam S - Application state type
- * @param opts.backend - Runtime backend (e.g., createNodeBackend())
- * @param opts.initialState - Initial application state
- * @param opts.config - Optional configuration overrides
- * @returns App instance with view/draw, update, start/stop/dispose methods
- *
- * @example
- * ```ts
- * const app = createApp({
- *   backend: createNodeBackend(),
- *   initialState: { count: 0 },
- * });
- *
- * app.view((state) => ui.text(`Count: ${state.count}`));
- * await app.start();
- * ```
- */
 export function createApp(opts) {
     const backend = opts.backend;
     const config = resolveAppConfig(opts.config);
-    let theme = coerceToLegacyTheme(opts.theme ?? defaultTheme);
+    const backendDrawlistVersion = readBackendDrawlistVersionMarker(backend);
+    if (backendDrawlistVersion !== null && backendDrawlistVersion !== 1) {
+        invalidProps(`backend drawlistVersion=${String(backendDrawlistVersion)} is invalid. Fix: set backend drawlist version marker to 1.`);
+    }
+    const backendMaxEventBytes = readBackendPositiveIntMarker(backend, BACKEND_MAX_EVENT_BYTES_MARKER);
+    if (backendMaxEventBytes !== null && backendMaxEventBytes !== config.maxEventBytes) {
+        invalidProps(`config.maxEventBytes=${String(config.maxEventBytes)} must match backend maxEventBytes=${String(backendMaxEventBytes)}. Fix: align maxEventBytes between app config and backend, or prefer createNodeApp({ config }) for Node/Bun apps to keep them aligned automatically.`);
+    }
+    const backendFpsCap = readBackendPositiveIntMarker(backend, BACKEND_FPS_CAP_MARKER);
+    if (backendFpsCap !== null && backendFpsCap !== config.fpsCap) {
+        invalidProps(`config.fpsCap=${String(config.fpsCap)} must match backend fpsCap=${String(backendFpsCap)}. Fix: align fpsCap between app config and backend, or prefer createNodeApp({ config }) for Node/Bun apps to keep them aligned automatically.`);
+    }
+    let theme = compileTheme(opts.theme ?? defaultTheme.definition);
+    let themeTransition = null;
+    let terminalProfile = DEFAULT_TERMINAL_PROFILE;
     const sm = new AppStateMachine();
+    const routes = opts.routes;
+    if (routes !== undefined && routes.length === 0) {
+        invalidProps("routes must contain at least one route");
+    }
+    if (routes === undefined && opts.initialRoute !== undefined) {
+        invalidProps("initialRoute requires routes");
+    }
+    if (routes !== undefined && opts.initialRoute === undefined) {
+        invalidProps("initialRoute is required when routes are provided");
+    }
+    if (opts.routeHistoryMaxDepth !== undefined) {
+        requirePositiveInt("routeHistoryMaxDepth", opts.routeHistoryMaxDepth);
+    }
     let mode = null;
     let drawFn = null;
     let viewFn = null;
-    let committedState = opts.initialState;
+    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 DIRTY_RENDER = 1 << 0;
-    const DIRTY_LAYOUT = 1 << 1;
-    const DIRTY_VIEW = 1 << 2;
-    let dirtyFlags = 0;
-    let dirtyRenderVersion = 0;
-    let dirtyLayoutVersion = 0;
-    let dirtyViewVersion = 0;
+    const dirtyTracker = createDirtyTracker();
+    const spinnerTickMinIntervalMs = Math.max(1, Math.floor(1000 / Math.min(config.fpsCap, 8)));
     let framesInFlight = 0;
     let interactiveBudget = 0;
+    let lastSpinnerRenderTickMs = Number.NEGATIVE_INFINITY;
+    let lastObservedSpinnerTickEventMs = Number.NEGATIVE_INFINITY;
+    let lastSpinnerRenderPerfMs = Number.NEGATIVE_INFINITY;
     let viewport = null;
     const timeUnwrap = { epochMs: 0, lastRawMs: null };
     let inRender = false;
     let inCommit = false;
     let inEventHandlerDepth = 0;
     let lifecycleBusy = null;
+    let backendStarted = false;
+    let lifecycleGeneration = 0;
     let pollToken = 0;
+    let settleActiveRun = null;
+    let renderRequestQueuedForCurrentTurn = false;
     let userCommitScheduled = false;
-    // Perf tracking: submit time for backend_ack calculation
-    let submitFrameStartMs = null;
-    // Perf tracking: schedule_wait measures time from render request to render start
     let scheduleWaitStartMs = null;
-    const scheduler = new TurnScheduler((items) => processTurn(items));
-    function snapshotDirtyVersions() {
-        return {
-            render: dirtyRenderVersion,
-            layout: dirtyLayoutVersion,
-            view: dirtyViewVersion,
-        };
-    }
-    function clearConsumedDirtyFlags(consumedFlags, snapshot) {
-        let clearMask = 0;
-        if ((consumedFlags & DIRTY_RENDER) !== 0 && dirtyRenderVersion === snapshot.render) {
-            clearMask |= DIRTY_RENDER;
-        }
-        if ((consumedFlags & DIRTY_LAYOUT) !== 0 && dirtyLayoutVersion === snapshot.layout) {
-            clearMask |= DIRTY_LAYOUT;
-        }
-        if ((consumedFlags & DIRTY_VIEW) !== 0 && dirtyViewVersion === snapshot.view) {
-            clearMask |= DIRTY_VIEW;
-        }
-        dirtyFlags &= ~clearMask;
-    }
+    const baseInternalOnRender = config.internal_onRender;
+    const baseInternalOnLayout = config.internal_onLayout;
+    let inspectorInternalOnRender;
+    let inspectorInternalOnLayout;
+    let runtimeBreadcrumbsEnabled = baseInternalOnRender !== undefined || baseInternalOnLayout !== undefined;
+    let keybindingState = createManagerState();
+    let keybindingsEnabled = false;
+    let breadcrumbLastEventKind = null;
+    let breadcrumbLastConsumptionPath = null;
+    let breadcrumbLastAction = null;
+    let breadcrumbEventTracked = false;
+    let deferredInlineFatal = null;
+    let processTurnImpl = () => undefined;
+    let tryRenderOnceImpl = () => undefined;
+    const scheduler = new TurnScheduler((items) => processTurnImpl(items));
+    const enqueueWorkItem = (item) => {
+        scheduler.enqueue(item);
+    };
     function markDirty(flags, schedule = true) {
-        // Track when dirty flags are first set for schedule_wait measurement.
-        // This captures time from "render needed" to "render started".
-        const wasDirty = dirtyFlags !== 0;
-        dirtyFlags |= flags;
-        if ((flags & DIRTY_RENDER) !== 0)
-            dirtyRenderVersion++;
-        if ((flags & DIRTY_LAYOUT) !== 0)
-            dirtyLayoutVersion++;
-        if ((flags & DIRTY_VIEW) !== 0)
-            dirtyViewVersion++;
-        if (PERF_ENABLED && !wasDirty && dirtyFlags !== 0 && scheduleWaitStartMs === null) {
+        const { wasDirty, flags: nextFlags } = dirtyTracker.markDirty(flags);
+        if (PERF_ENABLED && !wasDirty && nextFlags !== 0 && scheduleWaitStartMs === null) {
             scheduleWaitStartMs = perfMarkStart("schedule_wait");
         }
         if (!schedule)
             return;
         if (sm.state !== "Running")
             return;
-        if (scheduler.isScheduled || scheduler.isExecuting)
+        if (scheduler.isExecuting) {
+            if (!renderRequestQueuedForCurrentTurn) {
+                renderRequestQueuedForCurrentTurn = true;
+                enqueueWorkItem({ kind: "renderRequest" });
+            }
+            return;
+        }
+        if (scheduler.isScheduled)
             return;
-        scheduler.enqueue({ kind: "renderRequest" });
+        enqueueWorkItem({ kind: "renderRequest" });
     }
     function requestRenderFromRenderer() {
         markDirty(DIRTY_RENDER);
@@ -242,88 +157,22 @@ export function createApp(opts) {
     function requestViewFromRenderer() {
         markDirty(DIRTY_VIEW);
     }
-    const rawRenderer = new RawRenderer({
-        backend,
-        maxDrawlistBytes: config.maxDrawlistBytes,
-        ...(opts.config?.drawlistValidateParams === undefined
-            ? {}
-            : { drawlistValidateParams: opts.config.drawlistValidateParams }),
-        drawlistReuseOutputBuffer: config.drawlistReuseOutputBuffer,
-        drawlistEncodedStringCacheCap: config.drawlistEncodedStringCacheCap,
+    const guards = createAppGuards({
+        getEventHandlerDepth: () => inEventHandlerDepth,
+        getLifecycleBusy: () => lifecycleBusy,
+        getRuntimeState: () => sm.state,
+        isInCommit: () => inCommit,
+        isInRender: () => inRender,
     });
-    const widgetRenderer = new WidgetRenderer({
-        backend,
-        maxDrawlistBytes: config.maxDrawlistBytes,
-        useV2Cursor: config.useV2Cursor,
-        ...(opts.config?.drawlistValidateParams === undefined
-            ? {}
-            : { drawlistValidateParams: opts.config.drawlistValidateParams }),
-        drawlistReuseOutputBuffer: config.drawlistReuseOutputBuffer,
-        drawlistEncodedStringCacheCap: config.drawlistEncodedStringCacheCap,
-        requestRender: requestRenderFromRenderer,
-        requestView: requestViewFromRenderer,
-    });
-    /* --- Keybinding State --- */
-    let keybindingState = createManagerState();
-    let keybindingsEnabled = false;
-    function computeKeybindingsEnabled(state) {
-        for (const m of state.modes.values()) {
-            if (m.bindings.length > 0)
-                return true;
-        }
-        return false;
-    }
-    function throwCode(code, detail) {
-        throw new ZrUiError(code, detail);
-    }
-    function assertOperational(method) {
-        const st = sm.state;
-        if (st === "Disposed" || st === "Faulted") {
-            throwCode("ZRUI_INVALID_STATE", `${method}: app is ${st}`);
-        }
-    }
-    function assertNotReentrant(method) {
-        if (inCommit || inRender || inEventHandlerDepth > 0) {
-            throwCode("ZRUI_REENTRANT_CALL", `${method}: re-entrant call`);
-        }
-    }
     function enqueueFatal(code, detail) {
-        scheduler.enqueue({ kind: "fatal", code, detail });
-    }
-    function fatalNowOrEnqueue(code, detail) {
-        if (scheduler.isExecuting) {
-            doFatal(code, detail);
-            return;
-        }
-        enqueueFatal(code, detail);
-    }
-    function emit(ev) {
-        const snapshot = [];
-        for (const slot of handlers) {
-            if (slot.active.value)
-                snapshot.push(slot.fn);
-        }
-        inEventHandlerDepth++;
-        try {
-            for (const fn of snapshot) {
-                try {
-                    fn(ev);
-                }
-                catch (e) {
-                    // Treat handler exceptions as fatal, but defer out of the handler stack.
-                    enqueueFatal("ZRUI_USER_CODE_THROW", `onEvent handler threw: ${describeThrown(e)}`);
-                    return;
-                }
-            }
-        }
-        finally {
-            inEventHandlerDepth--;
-        }
+        enqueueWorkItem({ kind: "fatal", code, detail });
     }
     function doFatal(code, detail) {
         if (sm.state !== "Running")
             return;
-        // 1) emit fatal to handlers (registration order, best-effort)
+        lifecycleBusy = null;
+        lifecycleGeneration++;
+        backendStarted = false;
         const fatalEv = { kind: "fatal", code, detail };
         const snapshot = [];
         for (const slot of handlers) {
@@ -338,16 +187,13 @@ export function createApp(opts) {
                 // ignore
             }
         }
-        // 2) transition to Faulted
         try {
             sm.toFaulted();
         }
         catch {
             // ignore
         }
-        // Stop polling immediately.
         pollToken++;
-        // 3) backend stop/dispose best-effort (stop then dispose)
         try {
             void backend
                 .stop()
@@ -359,6 +205,7 @@ export function createApp(opts) {
                 catch {
                     // ignore
                 }
+                settleActiveRun?.();
             });
         }
         catch {
@@ -368,550 +215,645 @@ export function createApp(opts) {
             catch {
                 // ignore
             }
+            settleActiveRun?.();
         }
     }
-    function releaseOnce(batch) {
-        let released = false;
-        return () => {
-            if (released)
-                return;
-            released = true;
-            try {
-                batch.release();
-            }
-            catch {
-                // ignore
-            }
-        };
-    }
-    function processEventBatch(batch) {
-        const release = releaseOnce(batch);
-        const parseToken = perfMarkStart("event_parse");
-        const parsed = parseEventBatchV1(batch.bytes, {
-            maxTotalSize: config.maxEventBytes,
-            timeUnwrap,
-        });
-        perfMarkEnd("event_parse", parseToken);
-        if (!parsed.ok) {
-            release();
-            fatalNowOrEnqueue("ZRUI_PROTOCOL_ERROR", `${parsed.error.code}: ${parsed.error.detail}`);
+    function flushDeferredInlineFatal() {
+        if (deferredInlineFatal === null || inEventHandlerDepth !== 0)
             return;
-        }
-        const engineTruncated = (parsed.value.flags & 1) !== 0;
-        const droppedBatches = batch.droppedBatches;
-        try {
-            if (engineTruncated || droppedBatches > 0) {
-                emit({ kind: "overrun", engineTruncated, droppedBatches });
-                if (sm.state !== "Running")
-                    return;
-            }
-            for (const ev of parsed.value.events) {
-                // Input-priority / preemption: when an interactive input event arrives,
-                // allow a short urgent burst even if a previous frame is still
-                // in-flight. This keeps interactive latency resilient to transport/ack
-                // jitter while older frames are still coalesced downstream (latest-wins)
-                // in the backend/worker.
-                if (ev.kind === "key" || ev.kind === "text" || ev.kind === "paste" || ev.kind === "mouse") {
-                    interactiveBudget = 2;
-                }
-                emit({ kind: "engine", event: ev });
-                if (sm.state !== "Running")
-                    return;
-                if (ev.kind === "resize") {
-                    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 (ev.kind === "tick" && mode === "widget") {
-                    // Tick events drive render-only animation frames (e.g., Spinner).
-                    markDirty(DIRTY_RENDER);
-                }
-                const isWidgetRoutableEvent = ev.kind === "key" || ev.kind === "text" || ev.kind === "paste" || ev.kind === "mouse";
-                if (mode === "widget" && isWidgetRoutableEvent) {
-                    if (keybindingsEnabled) {
-                        // Route key events through keybinding system first
-                        if (ev.kind === "key") {
-                            const bypass = widgetRenderer.shouldBypassKeybindings(ev);
-                            if (!bypass) {
-                                const keyCtx = Object.freeze({
-                                    state: committedState,
-                                    update: app.update,
-                                    focusedId: widgetRenderer.getFocusedId(),
-                                });
-                                const keyResult = routeKeyEvent(keybindingState, ev, keyCtx);
-                                keybindingState = keyResult.nextState;
-                                if (keyResult.consumed)
-                                    continue; // Skip default widget routing
-                            }
-                        }
-                        // Also route text events through keybinding system for single-character bindings
-                        if (ev.kind === "text") {
-                            const keyCode = codepointToKeyCode(ev.codepoint);
-                            if (keyCode !== null) {
-                                // Create a synthetic key event for keybinding matching
-                                const syntheticKeyEvent = {
-                                    kind: "key",
-                                    action: "down",
-                                    key: keyCode,
-                                    mods: 0, // Text events have no modifiers
-                                    timeMs: ev.timeMs,
-                                };
-                                const keyCtx = Object.freeze({
-                                    state: committedState,
-                                    update: app.update,
-                                    focusedId: widgetRenderer.getFocusedId(),
-                                });
-                                const keyResult = routeKeyEvent(keybindingState, syntheticKeyEvent, keyCtx);
-                                keybindingState = keyResult.nextState;
-                                if (keyResult.consumed)
-                                    continue; // Skip default widget routing
-                            }
-                        }
-                    }
-                    let routed;
-                    try {
-                        routed = widgetRenderer.routeEngineEvent(ev);
-                    }
-                    catch (e) {
-                        enqueueFatal("ZRUI_USER_CODE_THROW", `widget routing threw: ${describeThrown(e)}`);
-                        return;
-                    }
-                    if (routed.needsRender)
-                        markDirty(DIRTY_RENDER);
-                    if (routed.action) {
-                        emit({ kind: "action", ...routed.action });
-                        if (sm.state !== "Running")
-                            return;
-                    }
-                }
+        const fatal = deferredInlineFatal;
+        deferredInlineFatal = null;
+        doFatal(fatal.code, fatal.detail);
+    }
+    function fatalNowOrEnqueue(code, detail) {
+        const canFailFastInline = scheduler.isExecuting && !inRender && !inCommit;
+        if (canFailFastInline && inEventHandlerDepth > 0) {
+            if (deferredInlineFatal === null) {
+                deferredInlineFatal = Object.freeze({ code, detail });
             }
+            return;
         }
-        finally {
-            release();
+        if (canFailFastInline) {
+            doFatal(code, detail);
+            return;
         }
+        enqueueFatal(code, detail);
     }
-    function commitUpdates() {
-        const drained = updates.drain();
-        if (drained.length === 0)
+    function cleanupStartedBackendAfterAbort() {
+        if (!backendStarted)
             return;
-        const commitToken = perfMarkStart("commit");
-        inCommit = true;
+        backendStarted = false;
         try {
-            let next = committedState;
-            for (const u of drained) {
-                if (typeof u === "function") {
-                    next = u(next);
+            void backend
+                .stop()
+                .catch(() => undefined)
+                .finally(() => {
+                try {
+                    backend.dispose();
                 }
-                else {
-                    next = u;
+                catch {
+                    // ignore
                 }
+            });
+        }
+        catch {
+            try {
+                backend.dispose();
             }
-            if (next !== committedState) {
-                committedState = next;
-                markDirty(DIRTY_VIEW, false);
+            catch {
+                // ignore
             }
         }
-        catch (e) {
-            fatalNowOrEnqueue("ZRUI_USER_CODE_THROW", `state updater threw: ${describeThrown(e)}`);
-        }
-        finally {
-            inCommit = false;
-            perfMarkEnd("commit", commitToken);
-        }
     }
-    function scheduleFrameSettlement(p, submitStart, submitEnd) {
-        if (isSyncFrameAck(p)) {
-            if (PERF_ENABLED && submitStart !== null) {
-                const ackNow = perfNow();
-                perfRecord("backend_ack", ackNow - submitStart);
-                if (submitEnd !== null) {
-                    perfRecord("frame_build", submitEnd - submitStart);
-                    perfRecord("worker_roundtrip", ackNow - submitEnd);
-                }
-            }
-            framesInFlight = Math.max(0, framesInFlight - 1);
-            return;
-        }
-        const acceptedAck = getAcceptedFrameAck(p);
-        const ackPromise = acceptedAck ?? p;
-        void ackPromise.then(() => {
-            if (PERF_ENABLED && submitStart !== null) {
-                const ackNow = perfNow();
-                // backend_ack: total time from frame build start to backend ack.
-                // Equals frame_build + worker_roundtrip (kept for backward compat).
-                perfRecord("backend_ack", ackNow - submitStart);
-                if (submitEnd !== null) {
-                    // frame_build: synchronous TS pipeline (view/commit/layout/render/build).
-                    perfRecord("frame_build", submitEnd - submitStart);
-                    // worker_roundtrip: async transport from requestFrame to backend ack.
-                    perfRecord("worker_roundtrip", ackNow - submitEnd);
-                }
+    const rawRenderer = new RawRenderer({
+        backend,
+        maxDrawlistBytes: config.maxDrawlistBytes,
+        ...(opts.config?.drawlistValidateParams === undefined
+            ? {}
+            : { drawlistValidateParams: opts.config.drawlistValidateParams }),
+        drawlistReuseOutputBuffer: config.drawlistReuseOutputBuffer,
+        drawlistEncodedStringCacheCap: config.drawlistEncodedStringCacheCap,
+    });
+    const widgetRenderer = new WidgetRenderer({
+        backend,
+        maxDrawlistBytes: config.maxDrawlistBytes,
+        rootPadding: config.rootPadding,
+        breakpointThresholds: config.breakpointThresholds,
+        terminalProfile,
+        ...(opts.config?.drawlistValidateParams === undefined
+            ? {}
+            : { drawlistValidateParams: opts.config.drawlistValidateParams }),
+        drawlistReuseOutputBuffer: config.drawlistReuseOutputBuffer,
+        drawlistEncodedStringCacheCap: config.drawlistEncodedStringCacheCap,
+        requestRender: requestRenderFromRenderer,
+        requestView: requestViewFromRenderer,
+        onUserCodeError: (detail) => fatalNowOrEnqueue("ZRUI_USER_CODE_THROW", detail),
+        collectRuntimeBreadcrumbs: runtimeBreadcrumbsEnabled,
+    });
+    const focusDispatcher = createFocusDispatcher({
+        getFocusedId: () => widgetRenderer.getFocusedId(),
+        getFocusInfo: () => widgetRenderer.getCurrentFocusInfo(),
+        initialFocusedId: widgetRenderer.getFocusedId(),
+        onHandlerError: (error) => {
+            fatalNowOrEnqueue("ZRUI_USER_CODE_THROW", `onFocusChange handler threw: ${describeThrown(error)}`);
+        },
+    });
+    let routeStateUpdater = null;
+    let routerIntegration = null;
+    if (routes !== undefined) {
+        mode = "widget";
+        viewFn = (state) => {
+            if (!routerIntegration || !routeStateUpdater) {
+                throw new ZrUiError("ZRUI_INVALID_STATE", "router integration is not initialized");
             }
-            scheduler.enqueue({ kind: "frameDone" });
-        }, (err) => scheduler.enqueue({ kind: "frameError", error: err }));
-        if (acceptedAck !== null) {
-            void p.then(() => { }, (err) => scheduler.enqueue({
-                kind: "fatal",
-                code: "ZRUI_BACKEND_ERROR",
-                detail: `requestFrame completion rejected after accepted ack: ${describeThrown(err)}`,
-            }));
-        }
+            return routerIntegration.renderCurrentScreen(state, routeStateUpdater);
+        };
     }
-    function emitInternalRenderMetrics(renderTime) {
-        if (config.internal_onRender === undefined)
-            return true;
-        try {
-            config.internal_onRender({ renderTime: Math.max(0, renderTime) });
-            return true;
-        }
-        catch (e) {
-            fatalNowOrEnqueue("ZRUI_USER_CODE_THROW", `onRender callback threw: ${describeThrown(e)}`);
-            return false;
-        }
+    const applyKeybindingState = (nextState) => {
+        keybindingState = nextState;
+        keybindingsEnabled = computeKeybindingsEnabled(keybindingState);
+    };
+    const keybindingHelpers = createAppKeybindingHelpers({
+        getState: () => keybindingState,
+        markDirty: (flags) => markDirty(flags),
+        setState: applyKeybindingState,
+        throwCode: guards.throwCode,
+    });
+    const runtimeBreadcrumbHelpers = createRuntimeBreadcrumbHelpers({
+        getBaseInternalOnLayout: () => baseInternalOnLayout,
+        getBaseInternalOnRender: () => baseInternalOnRender,
+        getInspectorInternalOnLayout: () => inspectorInternalOnLayout,
+        getInspectorInternalOnRender: () => inspectorInternalOnRender,
+        getLastAction: () => breadcrumbLastAction,
+        getLastConsumptionPath: () => breadcrumbLastConsumptionPath,
+        getLastEventKind: () => breadcrumbLastEventKind,
+        getWidgetRuntimeBreadcrumbSnapshot: () => widgetRenderer.getRuntimeBreadcrumbSnapshot(),
+        isEnabled: () => runtimeBreadcrumbsEnabled,
+        isEventTracked: () => breadcrumbEventTracked,
+        setEnabled: (enabled) => {
+            runtimeBreadcrumbsEnabled = enabled;
+        },
+        setEventTracked: (tracked) => {
+            breadcrumbEventTracked = tracked;
+        },
+        setInspectorInternalOnLayout: (callback) => {
+            inspectorInternalOnLayout = callback;
+        },
+        setInspectorInternalOnRender: (callback) => {
+            inspectorInternalOnRender = callback;
+        },
+        setLastAction: (action) => {
+            breadcrumbLastAction = action;
+        },
+        setLastConsumptionPath: (path) => {
+            breadcrumbLastConsumptionPath = path;
+        },
+        setLastEventKind: (kind) => {
+            breadcrumbLastEventKind = kind;
+        },
+        setWidgetRuntimeBreadcrumbCaptureEnabled: (enabled) => {
+            widgetRenderer.setRuntimeBreadcrumbCaptureEnabled(enabled);
+        },
+    });
+    function retryTopLevelViewError() {
+        topLevelViewError = null;
+        markDirty(DIRTY_VIEW | DIRTY_LAYOUT);
     }
-    function emitInternalLayoutSnapshot() {
-        if (config.internal_onLayout === undefined)
-            return true;
+    function quitFromTopLevelViewError() {
+        let stopPromise;
         try {
-            config.internal_onLayout({ idRects: widgetRenderer.getRectByIdIndex() });
-            return true;
-        }
-        catch (e) {
-            fatalNowOrEnqueue("ZRUI_USER_CODE_THROW", `onLayout callback threw: ${describeThrown(e)}`);
-            return false;
+            stopPromise = app.stop();
         }
-    }
-    function tryRenderOnce() {
-        if (sm.state !== "Running")
-            return;
-        // During stop(), we may still receive a few late event batches, but we must not
-        // submit new frames (backend may be tearing down).
-        if (lifecycleBusy === "stop")
-            return;
-        if (dirtyFlags === 0)
-            return;
-        const maxInFlight = config.maxFramesInFlight + (interactiveBudget > 0 ? 1 : 0);
-        if (framesInFlight >= maxInFlight)
-            return;
-        if (mode === null)
-            return;
-        // Record schedule_wait: time from render request to render start
-        if (PERF_ENABLED && scheduleWaitStartMs !== null) {
-            perfMarkEnd("schedule_wait", scheduleWaitStartMs);
-            scheduleWaitStartMs = null;
-        }
-        const dirtyVersionStart = snapshotDirtyVersions();
-        const snapshot = committedState;
-        const hooks = {
-            enterRender: () => {
-                inRender = true;
-            },
-            exitRender: () => {
-                inRender = false;
-            },
-        };
-        if (mode === "raw") {
-            const df = drawFn;
-            if (!df)
-                return;
-            const renderStart = perfNow();
-            const submitToken = perfMarkStart("submit_frame");
-            const res = rawRenderer.submitFrame(df, hooks);
-            perfMarkEnd("submit_frame", submitToken);
-            if (!res.ok) {
-                fatalNowOrEnqueue(res.code, res.detail);
-                return;
+        catch {
+            try {
+                app.dispose();
             }
-            if (!emitInternalRenderMetrics(perfNow() - renderStart))
-                return;
-            submitFrameStartMs = PERF_ENABLED ? submitToken : null;
-            const buildEndMs = PERF_ENABLED ? perfNow() : null;
-            framesInFlight++;
-            if (interactiveBudget > 0)
-                interactiveBudget--;
-            scheduleFrameSettlement(res.inFlight, submitFrameStartMs, buildEndMs);
-            clearConsumedDirtyFlags(DIRTY_RENDER | DIRTY_LAYOUT | DIRTY_VIEW, dirtyVersionStart);
-            return;
-        }
-        const vf = viewFn;
-        if (!vf)
-            return;
-        if (!viewport)
-            return;
-        if ((dirtyFlags & (DIRTY_VIEW | DIRTY_LAYOUT | DIRTY_RENDER)) === 0)
-            return;
-        // Compute render plan from dirty flags. Render-only turns (e.g., focus change)
-        // skip view/commit/layout. Layout-only turns (e.g., resize without state change)
-        // skip view/commit. Commit turns now rely on WidgetRenderer layout signatures
-        // to decide whether relayout is required, instead of forcing layout by default.
-        // First-frame/bootstrap safety is handled inside submitFrame(): it falls back
-        // to full pipeline when committedRoot or layoutTree is null.
-        const pendingDirtyFlags = dirtyFlags;
-        const plan = {
-            commit: (pendingDirtyFlags & DIRTY_VIEW) !== 0,
-            layout: (pendingDirtyFlags & DIRTY_LAYOUT) !== 0,
-            // Keep interactive frames on the absolute fast path (no layout signature walk).
-            // Background commit turns can afford the signature check to avoid unnecessary relayout.
-            checkLayoutStability: (pendingDirtyFlags & DIRTY_LAYOUT) === 0 &&
-                interactiveBudget === 0 &&
-                (pendingDirtyFlags & DIRTY_VIEW) !== 0,
-        };
-        const renderStart = perfNow();
-        const submitToken = perfMarkStart("submit_frame");
-        const res = widgetRenderer.submitFrame(vf, snapshot, viewport, theme, hooks, plan);
-        perfMarkEnd("submit_frame", submitToken);
-        if (!res.ok) {
-            fatalNowOrEnqueue(res.code, res.detail);
-            return;
-        }
-        if (!emitInternalRenderMetrics(perfNow() - renderStart))
-            return;
-        if (!emitInternalLayoutSnapshot())
-            return;
-        submitFrameStartMs = PERF_ENABLED ? submitToken : null;
-        const buildEndMs = PERF_ENABLED ? perfNow() : null;
-        framesInFlight++;
-        if (interactiveBudget > 0)
-            interactiveBudget--;
-        scheduleFrameSettlement(res.inFlight, submitFrameStartMs, buildEndMs);
-        let consumedDirtyFlags = DIRTY_RENDER;
-        if (plan.layout)
-            consumedDirtyFlags |= DIRTY_LAYOUT;
-        if (plan.commit)
-            consumedDirtyFlags |= DIRTY_VIEW;
-        clearConsumedDirtyFlags(consumedDirtyFlags, dirtyVersionStart);
-    }
-    function drainIgnored(items) {
-        for (const it of items) {
-            if (it.kind === "eventBatch") {
-                try {
-                    it.batch.release();
-                }
-                catch {
-                    // ignore
-                }
+            catch {
+                // ignore
             }
-        }
-    }
-    function processTurn(items) {
-        const st = sm.state;
-        if (st === "Disposed" || st === "Faulted") {
-            drainIgnored(items);
             return;
         }
-        let sawKick = false;
-        for (const item of items) {
-            if (sm.state === "Faulted" || sm.state === "Disposed") {
-                drainIgnored(items);
-                return;
+        void stopPromise.finally(() => {
+            try {
+                app.dispose();
             }
-            switch (item.kind) {
-                case "fatal": {
-                    doFatal(item.code, item.detail);
-                    drainIgnored(items);
-                    return;
-                }
-                case "eventBatch": {
-                    if (sm.state !== "Running") {
-                        try {
-                            item.batch.release();
-                        }
-                        catch {
-                            // ignore
-                        }
-                        break;
-                    }
-                    processEventBatch(item.batch);
-                    if (sm.state !== "Running") {
-                        drainIgnored(items);
-                        return;
-                    }
-                    commitUpdates();
-                    break;
-                }
-                case "userCommit": {
-                    userCommitScheduled = false;
-                    if (sm.state === "Running")
-                        commitUpdates();
-                    break;
-                }
-                case "kick": {
-                    sawKick = true;
-                    break;
-                }
-                case "renderRequest": {
-                    break;
-                }
-                case "frameDone": {
-                    framesInFlight = Math.max(0, framesInFlight - 1);
-                    break;
-                }
-                case "frameError": {
-                    framesInFlight = Math.max(0, framesInFlight - 1);
-                    // If we are intentionally stopping, treat requestFrame rejections as
-                    // part of shutdown (not a fatal backend error).
-                    if (lifecycleBusy === "stop")
-                        break;
-                    doFatal("ZRUI_BACKEND_ERROR", `requestFrame rejected: ${describeThrown(item.error)}`);
-                    break;
-                }
+            catch {
+                // ignore
             }
+        });
+    }
+    function stopFromUnhandledQuitEvent() {
+        let stopPromise;
+        try {
+            stopPromise = app.stop();
         }
-        if (sm.state !== "Running")
+        catch (error) {
+            if (lifecycleBusy === "stop")
+                return;
+            fatalNowOrEnqueue("ZRUI_BACKEND_ERROR", `stop threw after unhandled quit input: ${describeThrown(error)}`);
             return;
-        if (sawKick)
-            commitUpdates();
-        tryRenderOnce();
+        }
+        void stopPromise.catch((error) => {
+            fatalNowOrEnqueue("ZRUI_BACKEND_ERROR", `stop rejected after unhandled quit input: ${describeThrown(error)}`);
+        });
     }
-    async function pollLoop(token) {
-        while (sm.state === "Running" && token === pollToken) {
-            let batch;
-            try {
-                batch = await backend.pollEvents();
-            }
-            catch (e) {
-                if (sm.state === "Running" && token === pollToken) {
-                    enqueueFatal("ZRUI_BACKEND_ERROR", `pollEvents rejected: ${describeThrown(e)}`);
-                }
-                return;
-            }
-            if (token !== pollToken || sm.state !== "Running") {
+    if (routes !== undefined) {
+        routerIntegration = createRouterIntegration({
+            routes,
+            initialRoute: opts.initialRoute,
+            ...(opts.routeHistoryMaxDepth === undefined
+                ? {}
+                : { maxHistoryDepth: opts.routeHistoryMaxDepth }),
+            getState: () => committedState,
+            requestRouteRender: () => markDirty(DIRTY_VIEW | DIRTY_LAYOUT),
+            captureFocusSnapshot: () => widgetRenderer.captureFocusSnapshot(),
+            restoreFocusSnapshot: (snapshot) => widgetRenderer.restoreFocusSnapshot(snapshot),
+            assertCanMutate: guards.assertRouterMutationAllowed,
+        });
+    }
+    function emit(ev) {
+        const snapshot = [];
+        for (const slot of handlers) {
+            if (slot.active.value)
+                snapshot.push(slot.fn);
+        }
+        inEventHandlerDepth++;
+        try {
+            for (const fn of snapshot) {
                 try {
-                    batch.release();
+                    fn(ev);
                 }
-                catch {
-                    // ignore
+                catch (error) {
+                    fatalNowOrEnqueue("ZRUI_USER_CODE_THROW", `onEvent handler threw: ${describeThrown(error)}`);
+                    return false;
                 }
-                return;
             }
-            scheduler.enqueue({ kind: "eventBatch", batch });
         }
+        finally {
+            inEventHandlerDepth--;
+            flushDeferredInlineFatal();
+        }
+        return true;
+    }
+    function emitFocusChangeIfNeeded() {
+        return focusDispatcher.emitIfChanged();
     }
+    const renderLoop = createRenderLoop({
+        buildRuntimeBreadcrumbSnapshot: runtimeBreadcrumbHelpers.buildRuntimeBreadcrumbSnapshot,
+        config,
+        dirtyTracker,
+        emitFocusChangeIfNeeded,
+        enqueueWorkItem,
+        fatalNowOrEnqueue,
+        getBaseInternalOnLayout: () => baseInternalOnLayout,
+        getBaseInternalOnRender: () => baseInternalOnRender,
+        getCommittedState: () => committedState,
+        getDebugLayoutEnabled: () => debugLayoutEnabled,
+        getDrawFn: () => drawFn,
+        getFramesInFlight: () => framesInFlight,
+        getInspectorInternalOnLayout: () => inspectorInternalOnLayout,
+        getInspectorInternalOnRender: () => inspectorInternalOnRender,
+        getInteractiveBudget: () => interactiveBudget,
+        getLifecycleBusy: () => lifecycleBusy,
+        getMode: () => mode,
+        getRenderRequestQueuedForCurrentTurn: () => renderRequestQueuedForCurrentTurn,
+        getScheduleWaitStartMs: () => scheduleWaitStartMs,
+        getTheme: () => theme,
+        getThemeTransition: () => themeTransition,
+        getTopLevelViewError: () => topLevelViewError,
+        getViewFn: () => viewFn,
+        getViewport: () => viewport,
+        isRunning: () => sm.state === "Running",
+        markDirty,
+        rawRenderer,
+        setFramesInFlight: (next) => {
+            framesInFlight = next;
+        },
+        setInRender: (next) => {
+            inRender = next;
+        },
+        setInteractiveBudget: (next) => {
+            interactiveBudget = next;
+        },
+        setRenderRequestQueuedForCurrentTurn: (next) => {
+            renderRequestQueuedForCurrentTurn = next;
+        },
+        setScheduleWaitStartMs: (next) => {
+            scheduleWaitStartMs = next;
+        },
+        setTheme: (next) => {
+            theme = next;
+        },
+        setThemeTransition: (next) => {
+            themeTransition = next;
+        },
+        setTopLevelViewError: (next) => {
+            topLevelViewError = next;
+        },
+        widgetRenderer,
+    });
+    tryRenderOnceImpl = renderLoop.tryRenderOnce;
+    const eventLoop = createEventLoop({
+        backend,
+        config,
+        doFatal,
+        emit,
+        emitFocusChangeIfNeeded,
+        enqueueWorkItem,
+        fatalNowOrEnqueue,
+        getAppUpdate: () => app.update,
+        getCommittedState: () => committedState,
+        getFramesInFlight: () => framesInFlight,
+        getInteractiveBudget: () => interactiveBudget,
+        getKeybindingState: () => keybindingState,
+        getKeybindingsEnabled: () => keybindingsEnabled,
+        getLastObservedSpinnerTickEventMs: () => lastObservedSpinnerTickEventMs,
+        getLastSpinnerRenderPerfMs: () => lastSpinnerRenderPerfMs,
+        getLastSpinnerRenderTickMs: () => lastSpinnerRenderTickMs,
+        getLifecycleBusy: () => lifecycleBusy,
+        getMode: () => mode,
+        getPollToken: () => pollToken,
+        getRenderRequestQueuedForCurrentTurn: () => renderRequestQueuedForCurrentTurn,
+        getRuntimeState: () => sm.state,
+        getTopLevelViewError: () => topLevelViewError,
+        getViewport: () => viewport,
+        keybindingHelpers,
+        markDirty,
+        noteBreadcrumbAction: runtimeBreadcrumbHelpers.noteBreadcrumbAction,
+        noteBreadcrumbConsumptionPath: runtimeBreadcrumbHelpers.noteBreadcrumbConsumptionPath,
+        noteBreadcrumbEvent: runtimeBreadcrumbHelpers.noteBreadcrumbEvent,
+        quitFromTopLevelViewError,
+        retryTopLevelViewError,
+        setCommittedState: (next) => {
+            committedState = next;
+        },
+        setFramesInFlight: (next) => {
+            framesInFlight = next;
+        },
+        setInCommit: (next) => {
+            inCommit = next;
+        },
+        setInteractiveBudget: (next) => {
+            interactiveBudget = next;
+        },
+        setKeybindingState: applyKeybindingState,
+        setLastObservedSpinnerTickEventMs: (next) => {
+            lastObservedSpinnerTickEventMs = next;
+        },
+        setLastSpinnerRenderPerfMs: (next) => {
+            lastSpinnerRenderPerfMs = next;
+        },
+        setLastSpinnerRenderTickMs: (next) => {
+            lastSpinnerRenderTickMs = next;
+        },
+        setRenderRequestQueuedForCurrentTurn: (next) => {
+            renderRequestQueuedForCurrentTurn = next;
+        },
+        setUserCommitScheduled: (next) => {
+            userCommitScheduled = next;
+        },
+        setViewport: (next) => {
+            viewport = next;
+        },
+        spinnerTickMinIntervalMs,
+        stopFromUnhandledQuitEvent,
+        timeUnwrap,
+        tryRenderOnce: () => tryRenderOnceImpl(),
+        updates,
+        widgetRenderer,
+    });
+    processTurnImpl = eventLoop.processTurn;
     const app = {
         view(fn) {
-            assertOperational("view");
+            guards.assertOperational("view");
+            guards.assertLifecycleIdle("view");
             sm.assertOneOf(["Created", "Stopped"], "view: must be Created or Stopped");
-            assertNotReentrant("view");
+            guards.assertNotReentrant("view");
+            if (routes !== undefined) {
+                guards.throwCode("ZRUI_MODE_CONFLICT", "view: routes are configured in createApp(); screen rendering is managed by router");
+            }
             if (mode === "raw")
-                throwCode("ZRUI_MODE_CONFLICT", "view: draw mode already selected");
+                guards.throwCode("ZRUI_MODE_CONFLICT", "view: draw mode already selected");
             mode = "widget";
             viewFn = fn;
         },
+        replaceView(fn) {
+            guards.assertOperational("replaceView");
+            guards.assertLifecycleIdle("replaceView");
+            guards.assertNotReentrant("replaceView");
+            if (routes !== undefined) {
+                guards.throwCode("ZRUI_MODE_CONFLICT", "replaceView: routes are configured in createApp(); screen rendering is managed by router");
+            }
+            if (mode === "raw") {
+                guards.throwCode("ZRUI_MODE_CONFLICT", "replaceView: draw mode already selected");
+            }
+            if (mode === null)
+                mode = "widget";
+            viewFn = fn;
+            topLevelViewError = null;
+            if (sm.state === "Running") {
+                widgetRenderer.forceFullRenderNextFrame();
+                markDirty(DIRTY_VIEW);
+            }
+        },
+        replaceRoutes(nextRoutes) {
+            guards.assertOperational("replaceRoutes");
+            guards.assertLifecycleIdle("replaceRoutes");
+            guards.assertNotReentrant("replaceRoutes");
+            const activeRouterIntegration = routerIntegration;
+            if (activeRouterIntegration === null || routes === undefined) {
+                throw new ZrUiError("ZRUI_MODE_CONFLICT", "replaceRoutes: app was created without routes; use replaceView for view-mode apps");
+            }
+            if (mode === "raw") {
+                guards.throwCode("ZRUI_MODE_CONFLICT", "replaceRoutes: draw mode already selected");
+            }
+            const nextRouteKeybindings = activeRouterIntegration.replaceRoutes(nextRoutes);
+            keybindingHelpers.replaceRouteBindings(nextRouteKeybindings);
+            topLevelViewError = null;
+            if (sm.state === "Running") {
+                widgetRenderer.forceFullRenderNextFrame();
+                markDirty(DIRTY_VIEW);
+            }
+        },
         draw(fn) {
-            assertOperational("draw");
+            guards.assertOperational("draw");
+            guards.assertLifecycleIdle("draw");
             sm.assertOneOf(["Created", "Stopped"], "draw: must be Created or Stopped");
-            assertNotReentrant("draw");
+            guards.assertNotReentrant("draw");
             if (mode === "widget")
-                throwCode("ZRUI_MODE_CONFLICT", "draw: view mode already selected");
+                guards.throwCode("ZRUI_MODE_CONFLICT", "draw: view mode already selected");
             mode = "raw";
             drawFn = fn;
         },
         onEvent(handler) {
-            assertOperational("onEvent");
+            guards.assertOperational("onEvent");
             if (inCommit || inRender)
-                throwCode("ZRUI_REENTRANT_CALL", "onEvent: re-entrant call");
+                guards.throwCode("ZRUI_REENTRANT_CALL", "onEvent: re-entrant call");
             const active = { value: true };
             handlers.push({ fn: handler, active });
             return () => {
                 active.value = false;
             };
         },
+        onFocusChange(handler) {
+            guards.assertOperational("onFocusChange");
+            if (inCommit || inRender) {
+                guards.throwCode("ZRUI_REENTRANT_CALL", "onFocusChange: re-entrant call");
+            }
+            return focusDispatcher.register(handler);
+        },
         update(updater) {
-            assertOperational("update");
+            guards.assertOperational("update");
+            guards.assertLifecycleIdle("update");
             if (inCommit)
-                throwCode("ZRUI_REENTRANT_CALL", "update: called during commit");
-            if (inRender)
-                throwCode("ZRUI_UPDATE_DURING_RENDER", "update: called during render");
+                guards.throwCode("ZRUI_REENTRANT_CALL", "update: called during commit");
+            if (inRender) {
+                guards.throwCode("ZRUI_UPDATE_DURING_RENDER", guards.updateDuringRenderDetail("update"));
+            }
             updates.enqueue(updater);
             if (sm.state === "Running" && inEventHandlerDepth === 0 && !userCommitScheduled) {
                 userCommitScheduled = true;
-                scheduler.enqueue({ kind: "userCommit" });
+                enqueueWorkItem({ kind: "userCommit" });
             }
         },
         setTheme(next) {
-            assertOperational("setTheme");
+            guards.assertOperational("setTheme");
+            guards.assertLifecycleIdle("setTheme");
             if (inCommit)
-                throwCode("ZRUI_REENTRANT_CALL", "setTheme: called during commit");
-            if (inRender)
-                throwCode("ZRUI_UPDATE_DURING_RENDER", "setTheme: called during render");
-            theme = coerceToLegacyTheme(next);
-            requestRenderFromRenderer();
+                guards.throwCode("ZRUI_REENTRANT_CALL", "setTheme: called during commit");
+            if (inRender) {
+                guards.throwCode("ZRUI_UPDATE_DURING_RENDER", guards.updateDuringRenderDetail("setTheme"));
+            }
+            const nextTheme = compileTheme(next);
+            if (nextTheme === themeTransition?.to)
+                return;
+            if (nextTheme === theme) {
+                themeTransition = null;
+                return;
+            }
+            renderLoop.beginThemeTransition(nextTheme);
+            requestViewFromRenderer();
+        },
+        debugLayout(enabled) {
+            guards.assertOperational("debugLayout");
+            guards.assertLifecycleIdle("debugLayout");
+            if (mode === "raw") {
+                guards.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");
-            if (lifecycleBusy)
-                throwCode("ZRUI_INVALID_STATE", "start: lifecycle operation already in flight");
+            guards.assertOperational("start");
+            guards.assertNotReentrant("start");
             sm.assertOneOf(["Created", "Stopped"], "start: must be Created or Stopped");
             if (mode === null)
-                throwCode("ZRUI_NO_RENDER_MODE", "start: no render mode selected");
+                guards.throwCode("ZRUI_NO_RENDER_MODE", "start: no render mode selected");
             lifecycleBusy = "start";
-            let p;
+            const startGeneration = ++lifecycleGeneration;
+            let promise = null;
             try {
-                p = backend.start();
+                promise = backend.start();
             }
-            catch (e) {
-                lifecycleBusy = null;
-                throwCode("ZRUI_BACKEND_ERROR", `backend.start threw: ${describeThrown(e)}`);
+            catch (error) {
+                if (lifecycleGeneration === startGeneration)
+                    lifecycleBusy = null;
+                guards.throwCode("ZRUI_BACKEND_ERROR", `backend.start threw: ${describeThrown(error)}`);
             }
-            return p.then(() => {
-                lifecycleBusy = null;
-                sm.toRunning();
-                markDirty(DIRTY_VIEW, false);
-                pollToken++;
-                void pollLoop(pollToken);
-                scheduler.enqueue({ kind: "kick" });
-            }, (e) => {
+            if (promise === null)
+                throw new Error("start: backend.start did not return a promise");
+            return promise.then(async () => {
+                try {
+                    backendStarted = true;
+                    if (lifecycleGeneration !== startGeneration) {
+                        cleanupStartedBackendAfterAbort();
+                        return;
+                    }
+                    topLevelViewError = null;
+                    const loadedTerminalProfile = await loadTerminalProfile(backend);
+                    if (lifecycleGeneration !== startGeneration) {
+                        cleanupStartedBackendAfterAbort();
+                        return;
+                    }
+                    terminalProfile = loadedTerminalProfile;
+                    widgetRenderer.setTerminalProfile(terminalProfile);
+                    sm.toRunning();
+                    markDirty(DIRTY_VIEW, false);
+                    pollToken++;
+                    void eventLoop.pollLoop(pollToken);
+                    enqueueWorkItem({ kind: "kick" });
+                }
+                finally {
+                    if (lifecycleGeneration === startGeneration && lifecycleBusy === "start") {
+                        lifecycleBusy = null;
+                    }
+                }
+            }, (error) => {
+                if (lifecycleGeneration !== startGeneration)
+                    return;
                 lifecycleBusy = null;
-                throw new ZrUiError("ZRUI_BACKEND_ERROR", `backend.start rejected: ${describeThrown(e)}`);
+                throw new ZrUiError("ZRUI_BACKEND_ERROR", `backend.start rejected: ${describeThrown(error)}`);
+            });
+        },
+        run() {
+            guards.assertOperational("run");
+            guards.assertNotReentrant("run");
+            sm.assertOneOf(["Created", "Stopped"], "run: must be Created or Stopped");
+            if (mode === null)
+                guards.throwCode("ZRUI_NO_RENDER_MODE", "run: no render mode selected");
+            const proc = readProcessLike();
+            let runSettle = null;
+            const runController = createRunSignalController({
+                onDetached: () => {
+                    if (runSettle !== null && settleActiveRun === runSettle) {
+                        settleActiveRun = null;
+                    }
+                },
+                onSignal: async () => {
+                    try {
+                        if (sm.state === "Running")
+                            await app.stop();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    try {
+                        app.dispose();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    try {
+                        proc?.exit?.(0);
+                    }
+                    catch {
+                        // ignore
+                    }
+                },
+                processLike: proc,
+            });
+            runSettle = runController.settle;
+            settleActiveRun = runController.settle;
+            let startPromise;
+            try {
+                startPromise = app.start();
+            }
+            catch (error) {
+                runController.detach();
+                throw error;
+            }
+            return startPromise.then(() => {
+                if (!runController.canRegisterSignals) {
+                    runController.settle();
+                }
+                return runController.promise;
+            }, (error) => {
+                runController.detach();
+                throw error;
             });
         },
         stop() {
-            assertOperational("stop");
-            assertNotReentrant("stop");
-            if (lifecycleBusy)
-                throwCode("ZRUI_INVALID_STATE", "stop: lifecycle operation already in flight");
+            guards.assertOperational("stop");
+            guards.assertNotReentrant("stop");
             sm.assertOneOf(["Running"], "stop: must be Running");
             lifecycleBusy = "stop";
-            // Stop polling immediately so in-flight pollEvents rejections from backend.stop()
-            // are treated as part of shutdown (not a fatal backend error).
+            const stopGeneration = ++lifecycleGeneration;
             pollToken++;
-            // Clear any in-flight frames so a shutdown doesn't strand the app in a state
-            // where a future start() cannot submit frames.
             framesInFlight = 0;
-            let p;
+            let promise = null;
             try {
-                p = backend.stop();
+                promise = backend.stop();
             }
-            catch (e) {
-                lifecycleBusy = null;
-                throwCode("ZRUI_BACKEND_ERROR", `backend.stop threw: ${describeThrown(e)}`);
+            catch (error) {
+                if (lifecycleGeneration === stopGeneration)
+                    lifecycleBusy = null;
+                guards.throwCode("ZRUI_BACKEND_ERROR", `backend.stop threw: ${describeThrown(error)}`);
             }
-            return p.then(() => {
-                lifecycleBusy = null;
-                sm.toStopped();
-            }, (e) => {
+            if (promise === null)
+                throw new Error("stop: backend.stop did not return a promise");
+            return promise.then(() => {
+                try {
+                    if (lifecycleGeneration !== stopGeneration)
+                        return;
+                    backendStarted = false;
+                    themeTransition = null;
+                    sm.toStopped();
+                    settleActiveRun?.();
+                }
+                finally {
+                    if (lifecycleGeneration === stopGeneration && lifecycleBusy === "stop") {
+                        lifecycleBusy = null;
+                    }
+                }
+            }, (error) => {
+                if (lifecycleGeneration !== stopGeneration)
+                    return;
                 lifecycleBusy = null;
-                throw new ZrUiError("ZRUI_BACKEND_ERROR", `backend.stop rejected: ${describeThrown(e)}`);
+                throw new ZrUiError("ZRUI_BACKEND_ERROR", `backend.stop rejected: ${describeThrown(error)}`);
             });
         },
         dispose() {
             if (inCommit || inRender || inEventHandlerDepth > 0) {
-                throwCode("ZRUI_REENTRANT_CALL", "dispose: re-entrant call");
+                guards.throwCode("ZRUI_REENTRANT_CALL", "dispose: re-entrant call");
             }
             const st0 = sm.state;
             if (st0 === "Disposed")
                 return;
+            lifecycleGeneration++;
+            lifecycleBusy = null;
             pollToken++;
+            themeTransition = null;
             try {
                 sm.dispose();
             }
             catch {
                 // ignore
             }
-            if (st0 === "Running") {
+            if (st0 === "Running" || backendStarted) {
                 try {
                     void backend.stop().catch(() => undefined);
                 }
@@ -919,32 +861,71 @@ export function createApp(opts) {
                     // ignore
                 }
             }
+            backendStarted = false;
             try {
                 backend.dispose();
             }
             catch {
                 // ignore
             }
+            settleActiveRun?.();
         },
-        /* --- Keybinding API --- */
         keys(bindings) {
-            assertOperational("keys");
-            keybindingState = registerBindings(keybindingState, bindings).state;
-            keybindingsEnabled = computeKeybindingsEnabled(keybindingState);
+            guards.assertKeybindingMutationAllowed("keys");
+            guards.assertLifecycleIdle("keys");
+            keybindingHelpers.registerAppBindings(bindings);
         },
         modes(modes) {
-            assertOperational("modes");
-            keybindingState = registerModes(keybindingState, modes).state;
-            keybindingsEnabled = computeKeybindingsEnabled(keybindingState);
+            guards.assertKeybindingMutationAllowed("modes");
+            guards.assertLifecycleIdle("modes");
+            keybindingHelpers.registerAppModes(modes);
         },
         setMode(modeName) {
-            assertOperational("setMode");
-            keybindingState = setMode(keybindingState, modeName);
+            guards.assertKeybindingMutationAllowed("setMode");
+            guards.assertLifecycleIdle("setMode");
+            applyKeybindingState(setMode(keybindingState, modeName));
         },
         getMode() {
             return getMode(keybindingState);
         },
+        getBindings(mode) {
+            return getBindings(keybindingState, mode);
+        },
+        get pendingChord() {
+            return getPendingChord(keybindingState);
+        },
+        getTerminalProfile() {
+            return terminalProfile;
+        },
+        measureElement(id) {
+            if (mode !== "widget")
+                return null;
+            return widgetRenderer.getRectByIdIndex().get(id) ?? null;
+        },
+        ...(routerIntegration ? { router: routerIntegration.router } : {}),
     };
+    routeStateUpdater = app.update;
+    if (routerIntegration) {
+        keybindingHelpers.replaceRouteBindings(routerIntegration.routeKeybindings);
+    }
+    Object.defineProperty(app, APP_INTERNAL_REQUEST_VIEW_LAYOUT_MARKER, {
+        value: () => {
+            if (sm.state !== "Running")
+                return;
+            markDirty(DIRTY_VIEW | DIRTY_LAYOUT);
+        },
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    Object.defineProperty(app, APP_INTERNAL_SET_RUNTIME_BREADCRUMB_HOOKS_MARKER, {
+        value: (hooks) => {
+            runtimeBreadcrumbHelpers.setInspectorHooks(hooks);
+        },
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
     return app;
 }
 //# sourceMappingURL=createApp.js.map