@vizejs/fresco 0.717.0 → 0.719.0

package/dist/{app-B9yJzz5S.mjs → app-C_wFlWSV.mjs}

@@ -1,5 +1,5 @@
 import { format } from "node:util";
-import { computed, createRenderer, defineComponent, h, inject, isRef, onUnmounted, ref, shallowRef, watch } from "vue";
+import { computed, createRenderer, defineComponent, h, inject, isRef, nextTick, onUnmounted, provide, ref, shallowRef, watch } from "vue";
 //#region src/renderPayload.ts
 const displays = ["flex", "none"];
 const positions = [
@@ -89,6 +89,11 @@ function numberValue(value) {
 function booleanValue(value) {
 	return typeof value === "boolean" ? value : void 0;
 }
+function stringLines(value) {
+	if (!Array.isArray(value)) return void 0;
+	const lines = value.filter((line) => typeof line === "string");
+	return lines.length > 0 ? lines : void 0;
+}
 function enabledValue(value) {
 	return value === true ? true : void 0;
 }
@@ -199,6 +204,15 @@ function frescoNodeToRenderNode(node) {
 		}
 		return renderNode;
 	}
+	if (node.type === "raw") {
+		const renderNode = {
+			...common,
+			nodeType: "raw"
+		};
+		const lines = stringLines(node.props.lines);
+		if (lines) renderNode.lines = lines;
+		return renderNode;
+	}
 	const renderNode = {
 		...common,
 		nodeType: "input"
@@ -207,12 +221,16 @@ function frescoNodeToRenderNode(node) {
 	const placeholder = stringValue$1(node.props.placeholder);
 	const focused = booleanValue(firstValue(node.props, "focused", "focus"));
 	const cursor = numberValue(node.props.cursor);
+	const selectionStart = numberValue(firstValue(node.props, "selectionStart", "selection_start"));
+	const selectionEnd = numberValue(firstValue(node.props, "selectionEnd", "selection_end"));
 	const mask = booleanValue(node.props.mask);
 	const maskChar = stringValue$1(firstValue(node.props, "maskChar", "mask_char", "mask-char"));
 	if (value !== void 0) renderNode.value = value;
 	if (placeholder !== void 0) renderNode.placeholder = placeholder;
 	if (focused !== void 0) renderNode.focused = focused;
 	if (cursor !== void 0) renderNode.cursor = cursor;
+	if (selectionStart !== void 0) renderNode.selectionStart = selectionStart;
+	if (selectionEnd !== void 0) renderNode.selectionEnd = selectionEnd;
 	if (mask !== void 0) renderNode.mask = mask;
 	if (maskChar !== void 0) renderNode.maskChar = maskChar;
 	return renderNode;
@@ -371,6 +389,7 @@ function useApp() {
 * useFocus - Focus management composable
 */
 const FOCUS_KEY = Symbol("fresco-focus");
+const FOCUS_PARENT_KEY = Symbol("fresco-focus-parent");
 function activeFocusables(focusables) {
 	return focusables.filter((focusable) => focusable.isActive);
 }
@@ -382,38 +401,76 @@ function createFocusManager() {
 	const activeId = computed(() => focusedId.value ?? void 0);
 	const focusables = ref([]);
 	const focusableIds = computed(() => activeFocusables(focusables.value).map(({ id }) => id));
+	const trapStack = ref([]);
+	const activeTrapId = computed(() => trapStack.value.at(-1));
 	const isEnabled = ref(true);
-	const focus = (id) => {
-		const target = focusables.value.find((focusable) => focusable.id === id);
-		if (isEnabled.value && target?.isActive) focusedId.value = id;
+	const findFocusable = (id) => focusables.value.find((focusable) => focusable.id === id);
+	const isWithin = (id, rootId) => {
+		let currentId = id;
+		const visited = /* @__PURE__ */ new Set();
+		while (currentId !== null) {
+			if (currentId === rootId) return true;
+			if (visited.has(currentId)) return false;
+			visited.add(currentId);
+			currentId = findFocusable(currentId)?.parentId ?? null;
+		}
+		return false;
 	};
-	const focusNext = () => {
-		const active = activeFocusables(focusables.value);
-		if (!isEnabled.value || active.length === 0) return;
-		const currentIndex = focusedId.value !== null ? focusables.value.findIndex((focusable) => focusable.id === focusedId.value) : -1;
-		focusedId.value = focusables.value.slice(currentIndex + 1).find((focusable) => focusable.isActive)?.id ?? active[0]?.id ?? null;
+	const allowedByActiveTrap = (id) => {
+		const trapId = activeTrapId.value;
+		return trapId === void 0 || isWithin(id, trapId);
 	};
-	const focusPrevious = () => {
-		const active = activeFocusables(focusables.value);
+	const scopedFocusables = () => activeFocusables(focusables.value).filter(({ id }) => allowedByActiveTrap(id));
+	const delegatedTarget = (target) => {
+		let current = target;
+		const visited = /* @__PURE__ */ new Set();
+		while (current.delegateFocusTo !== null && !visited.has(current.id)) {
+			visited.add(current.id);
+			const delegated = findFocusable(current.delegateFocusTo);
+			if (!delegated?.isActive || !isWithin(delegated.id, current.id) || !allowedByActiveTrap(delegated.id)) break;
+			current = delegated;
+		}
+		return current;
+	};
+	const focus = (id) => {
+		const target = findFocusable(id);
+		if (isEnabled.value && target?.isActive && allowedByActiveTrap(id)) focusedId.value = delegatedTarget(target).id;
+	};
+	const moveFocus = (offset) => {
+		const active = scopedFocusables();
 		if (!isEnabled.value || active.length === 0) return;
-		const currentIndex = focusedId.value !== null ? focusables.value.findIndex((focusable) => focusable.id === focusedId.value) : focusables.value.length;
-		focusedId.value = focusables.value.slice(0, currentIndex < 0 ? 0 : currentIndex).findLast((focusable) => focusable.isActive)?.id ?? active.at(-1)?.id ?? null;
+		const currentIndex = active.findIndex((focusable) => focusable.id === focusedId.value);
+		for (let distance = 1; distance <= active.length; distance += 1) {
+			const candidate = active[currentIndex === -1 ? offset === 1 ? distance - 1 : active.length - distance : (currentIndex + offset * distance + active.length * 2) % active.length];
+			if (!candidate) continue;
+			const resolved = delegatedTarget(candidate);
+			if (resolved.id !== focusedId.value || active.length === 1) {
+				focusedId.value = resolved.id;
+				return;
+			}
+		}
 	};
+	const focusNext = () => moveFocus(1);
+	const focusPrevious = () => moveFocus(-1);
 	const register = (id, options = {}) => {
 		const existing = focusables.value.find((focusable) => focusable.id === id);
 		if (existing) {
 			existing.isActive = options.isActive ?? existing.isActive;
 			if ("parentId" in options) existing.parentId = options.parentId ?? null;
+			if ("delegateFocusTo" in options) existing.delegateFocusTo = options.delegateFocusTo ?? null;
 		} else focusables.value.push({
 			id,
 			isActive: options.isActive ?? true,
-			parentId: options.parentId ?? null
+			parentId: options.parentId ?? null,
+			delegateFocusTo: options.delegateFocusTo ?? null
 		});
 		if (options.autoFocus && focusedId.value === null && options.isActive !== false) focus(id);
 	};
 	const unregister = (id) => {
 		const index = focusables.value.findIndex((focusable) => focusable.id === id);
 		if (index !== -1) {
+			const trapIndex = trapStack.value.indexOf(id);
+			if (trapIndex !== -1) trapStack.value.splice(trapIndex);
 			focusables.value.splice(index, 1);
 			if (focusedId.value === id) focusedId.value = null;
 		}
@@ -422,12 +479,33 @@ function createFocusManager() {
 		const focusable = focusables.value.find((item) => item.id === id);
 		if (!focusable) return;
 		focusable.isActive = isActive;
+		if (!isActive) {
+			const trapIndex = trapStack.value.indexOf(id);
+			if (trapIndex !== -1) trapStack.value.splice(trapIndex);
+		}
 		if (!isActive && focusedId.value === id) focusedId.value = null;
 	};
 	const setParent = (id, parentId) => {
-		const focusable = focusables.value.find((item) => item.id === id);
+		const focusable = findFocusable(id);
 		if (!focusable) return;
 		focusable.parentId = parentId ?? null;
+		if (focusedId.value !== null && !allowedByActiveTrap(focusedId.value)) focusedId.value = null;
+	};
+	const setDelegate = (id, delegateFocusTo) => {
+		const focusable = findFocusable(id);
+		if (focusable) focusable.delegateFocusTo = delegateFocusTo ?? null;
+	};
+	const trapFocus = (id) => {
+		if (!findFocusable(id)?.isActive || !allowedByActiveTrap(id)) return;
+		if (activeTrapId.value !== id) trapStack.value.push(id);
+		if (focusedId.value === null || !isWithin(focusedId.value, id)) focus(id);
+	};
+	const releaseFocusTrap = (id) => {
+		const index = trapStack.value.indexOf(id);
+		if (index === -1) return;
+		trapStack.value.splice(index);
+		const remaining = activeTrapId.value;
+		if (remaining !== void 0 && focusedId.value !== null && !isWithin(focusedId.value, remaining)) focus(remaining);
 	};
 	const hasFocusedDescendant = (id) => {
 		let currentId = focusedId.value;
@@ -436,7 +514,7 @@ function createFocusManager() {
 		while (true) {
 			if (visited.has(currentId)) return false;
 			visited.add(currentId);
-			const parentId = focusables.value.find((focusable) => focusable.id === currentId)?.parentId ?? null;
+			const parentId = findFocusable(currentId)?.parentId ?? null;
 			if (parentId === null) return false;
 			if (parentId === id) return true;
 			currentId = parentId;
@@ -453,6 +531,7 @@ function createFocusManager() {
 		focusedId,
 		activeId,
 		focusableIds,
+		activeTrapId,
 		isEnabled,
 		enableFocus,
 		disableFocus,
@@ -463,23 +542,35 @@ function createFocusManager() {
 		unregister,
 		setActive,
 		setParent,
+		setDelegate,
+		trapFocus,
+		releaseFocusTrap,
 		hasFocusedDescendant
 	};
 }
+/** Make an owning focus target the default parent for nested useFocus calls. */
+function provideFocusScope(parentId) {
+	provide(FOCUS_PARENT_KEY, parentId);
+}
 /**
 * Use focus management
 */
 function useFocus(options = {}) {
-	const { autoFocus = false, id = `focus-${Math.random().toString(36).slice(2)}`, isActive: isActiveOption = true, parentId: parentIdOption = null } = options;
+	const inheritedParentId = inject(FOCUS_PARENT_KEY, null);
+	const { autoFocus = false, id = `focus-${Math.random().toString(36).slice(2)}`, isActive: isActiveOption = true, delegateFocusTo: delegateFocusToOption = null, trapFocus: trapFocusOption = false } = options;
+	const parentIdOption = "parentId" in options ? options.parentId ?? null : inheritedParentId;
 	const manager = inject(FOCUS_KEY, null);
 	const localFocused = ref(autoFocus);
 	const active = isRef(isActiveOption) ? isActiveOption : ref(isActiveOption);
 	const parentId = isRef(parentIdOption) ? parentIdOption : ref(parentIdOption);
+	const delegateFocusTo = isRef(delegateFocusToOption) ? delegateFocusToOption : ref(delegateFocusToOption);
+	const trapsFocus = isRef(trapFocusOption) ? trapFocusOption : ref(trapFocusOption);
 	const isFocused = computed(() => {
 		if (manager) return manager.isEnabled.value && manager.focusedId.value === id;
 		return active.value && localFocused.value;
 	});
 	const hasFocusedDescendant = computed(() => manager ? manager.hasFocusedDescendant(id) : false);
+	const isFocusTrapActive = computed(() => manager?.activeTrapId.value === id);
 	const focus = (targetId = id) => {
 		if (manager) manager.focus(targetId);
 		else if (targetId === id) localFocused.value = true;
@@ -493,16 +584,27 @@ function useFocus(options = {}) {
 		manager.register(id, {
 			isActive: active.value,
 			autoFocus,
-			parentId: parentId.value
+			parentId: parentId.value,
+			delegateFocusTo: delegateFocusTo.value
 		});
+		if (trapsFocus.value) manager.trapFocus(id);
 		watch(active, (enabled) => {
 			manager.setActive(id, enabled);
+			if (enabled && trapsFocus.value) manager.trapFocus(id);
 			if (enabled && autoFocus && !manager.focusedId.value) manager.focus(id);
 		}, { immediate: false });
 		watch(parentId, (nextParentId) => {
 			manager.setParent(id, nextParentId);
 		}, { immediate: false });
+		watch(delegateFocusTo, (nextDelegate) => {
+			manager.setDelegate(id, nextDelegate);
+		}, { immediate: false });
+		watch(trapsFocus, (trapped) => {
+			if (trapped) manager.trapFocus(id);
+			else manager.releaseFocusTrap(id);
+		}, { immediate: false });
 		onUnmounted(() => {
+			manager.releaseFocusTrap(id);
 			manager.unregister(id);
 		});
 	}
@@ -510,6 +612,7 @@ function useFocus(options = {}) {
 		id,
 		isFocused,
 		hasFocusedDescendant,
+		isFocusTrapActive,
 		focus,
 		blur
 	};
@@ -521,6 +624,7 @@ function useFocusManager() {
 	const manager = inject(FOCUS_KEY, null);
 	if (!manager) {
 		const empty = ref([]);
+		const activeId = ref(void 0);
 		return {
 			enableFocus: () => {},
 			disableFocus: () => {},
@@ -528,8 +632,12 @@ function useFocusManager() {
 			focusPrevious: () => {},
 			focus: (_id) => {},
 			hasFocusedDescendant: (_id) => false,
-			activeId: ref(void 0),
-			focusableIds: empty
+			trapFocus: (_id) => {},
+			releaseFocusTrap: (_id) => {},
+			setDelegate: (_id, _delegateFocusTo) => {},
+			activeId,
+			focusableIds: empty,
+			activeTrapId: activeId
 		};
 	}
 	return {
@@ -539,8 +647,12 @@ function useFocusManager() {
 		focusPrevious: manager.focusPrevious,
 		focus: manager.focus,
 		hasFocusedDescendant: manager.hasFocusedDescendant,
+		trapFocus: manager.trapFocus,
+		releaseFocusTrap: manager.releaseFocusTrap,
+		setDelegate: manager.setDelegate,
 		activeId: manager.activeId,
-		focusableIds: manager.focusableIds
+		focusableIds: manager.focusableIds,
+		activeTrapId: manager.activeTrapId
 	};
 }
 //#endregion
@@ -674,6 +786,10 @@ let lastRenderLayouts = [];
 function updateLastRenderLayouts(layouts) {
 	lastRenderLayouts = layouts;
 }
+/** Read the complete layout snapshot produced by the latest native frame. */
+function getLastRenderLayouts() {
+	return lastRenderLayouts;
+}
 /** Look up the latest native layout for an element or component public instance. */
 function getLastRenderLayout(node) {
 	const id = node?.id ?? node?.$el?.id;
@@ -689,6 +805,21 @@ function measureElement(node) {
 	};
 }
 //#endregion
+//#region src/mouseRouting.ts
+/** Hit-test one normalized mouse packet and route it through the host tree. */
+function routeMouseInput(renderer, root, event, layouts) {
+	const target = renderer.hitTest(root, event.x, event.y, layouts);
+	if (target) renderer.dispatchInput(target.id, event);
+}
+/** Route first, then publish the packet even when a routed handler throws. */
+function routeAndPublishMouseInput(renderer, root, event, layouts, sink) {
+	try {
+		if (root) routeMouseInput(renderer, root, event, layouts);
+	} finally {
+		sink.value = event;
+	}
+}
+//#endregion
 //#region src/nativeInput.ts
 /** Accept only key event phases supported by the public Fresco protocol. */
 function normalizeKeyEventType(value) {
@@ -719,6 +850,92 @@ function normalizeMouseEvent(event) {
 		} : void 0
 	};
 }
+/** Normalize one native input packet into the public Fresco event protocol. */
+function normalizeInputEvent(event) {
+	switch (event.eventType) {
+		case "resize": return {
+			type: "resize",
+			width: event.width ?? 0,
+			height: event.height ?? 0
+		};
+		case "paste": return {
+			type: "paste",
+			text: event.text ?? ""
+		};
+		case "mouse": return normalizeMouseEvent(event);
+		case "focus": return {
+			type: "focus",
+			focused: event.key === "gained"
+		};
+		case "compositionstart":
+		case "compositionupdate":
+		case "compositionend": return {
+			type: event.eventType,
+			text: event.text ?? "",
+			cursor: event.cursor ?? 0
+		};
+		case "key": {
+			const modifiers = event.modifiers ?? {};
+			return {
+				type: "key",
+				key: event.key ?? void 0,
+				char: event.char ?? void 0,
+				ctrl: modifiers.ctrl ?? false,
+				alt: modifiers.alt ?? false,
+				shift: modifiers.shift ?? false,
+				meta: modifiers.meta ?? false,
+				super: modifiers.super ?? false,
+				hyper: modifiers.hyper ?? false,
+				capsLock: modifiers.capsLock ?? false,
+				numLock: modifiers.numLock ?? false,
+				eventType: normalizeKeyEventType(event.keyEventType)
+			};
+		}
+		default: return;
+	}
+}
+//#endregion
+//#region src/hitTesting.ts
+function clipsOverflow(value) {
+	return value === "hidden" || value === "scroll";
+}
+function clipsDescendants(node) {
+	const style = normalizeFrescoStyle(node.props.style);
+	return clipsOverflow(style?.overflow ?? style?.overflowX ?? style?.overflowY);
+}
+function containsPoint(layout, clip, x, y) {
+	return x >= layout.x && x < layout.x + layout.width && y >= layout.y && y < layout.y + layout.height && x >= clip.left && x < clip.right && y >= clip.top && y < clip.bottom;
+}
+/** Return the deepest topmost live host node under one native-layout coordinate. */
+function hitTest(nodes, root, x, y, layouts) {
+	if (!Number.isFinite(x) || !Number.isFinite(y)) return void 0;
+	const byId = new Map(layouts.map((layout) => [layout.id, layout]));
+	const unbounded = {
+		left: Number.NEGATIVE_INFINITY,
+		top: Number.NEGATIVE_INFINITY,
+		right: Number.POSITIVE_INFINITY,
+		bottom: Number.POSITIVE_INFINITY
+	};
+	const visit = (node, ancestorClip) => {
+		const layout = byId.get(node.id);
+		const clips = clipsDescendants(node);
+		const childClip = layout ? {
+			left: clips ? Math.max(ancestorClip.left, layout.x) : ancestorClip.left,
+			top: clips ? Math.max(ancestorClip.top, layout.y) : ancestorClip.top,
+			right: clips ? Math.min(ancestorClip.right, layout.x + layout.width) : ancestorClip.right,
+			bottom: clips ? Math.min(ancestorClip.bottom, layout.y + layout.height) : ancestorClip.bottom
+		} : ancestorClip;
+		for (let index = node.children.length - 1; index >= 0; index -= 1) {
+			const child = node.children[index];
+			if (!child) continue;
+			const target = visit(child, childClip);
+			if (target) return target;
+		}
+		if (!layout || !nodes.has(node.id)) return void 0;
+		return containsPoint(layout, ancestorClip, x, y) ? node : void 0;
+	};
+	return visit(root, unbounded);
+}
 //#endregion
 //#region src/renderer.ts
 /**
@@ -891,6 +1108,9 @@ function mapElementType(type) {
 		case "span": return "text";
 		case "input":
 		case "textinput": return "input";
+		case "raw":
+		case "framebuffer":
+		case "frame-buffer": return "raw";
 		default: return "box";
 	}
 }
@@ -926,6 +1146,13 @@ function createRenderer$1(options = {}) {
 			tree.onMutation();
 			return true;
 		},
+		/**
+		* Return the deepest topmost node under one native-layout coordinate.
+		* Hidden and scroll overflow constrain descendant targeting on each axis.
+		*/
+		hitTest(root, x, y, layouts) {
+			return hitTest(tree.nodes, root, x, y, layouts);
+		},
 		/** Route normalized input through capture, target, and bubble handlers. */
 		dispatchInput(targetId, input) {
 			const target = tree.nodes.get(targetId);
@@ -1037,6 +1264,43 @@ function isStaticItemNode(node) {
 	return node.props.internal_static_item === true || node.props.internalStaticItem === true;
 }
 //#endregion
+//#region src/terminalLifecycle.ts
+const CI_ENVIRONMENT_KEYS = [
+	"CI",
+	"CONTINUOUS_INTEGRATION",
+	"BUILD_NUMBER",
+	"RUN_ID"
+];
+function isTruthyEnvironmentValue(value) {
+	if (!value) return false;
+	return ![
+		"0",
+		"false",
+		"no"
+	].includes(value.toLowerCase());
+}
+function isCiEnvironment(env = process.env) {
+	return CI_ENVIRONMENT_KEYS.some((key) => isTruthyEnvironmentValue(env[key]));
+}
+/** Resolve whether an application can own the interactive terminal lifecycle. */
+function detectInteractiveMode(interactive, stdout) {
+	return interactive ?? (stdout.isTTY === true && !isCiEnvironment());
+}
+/** Initialize the native terminal modes required by an interactive application. */
+function initializeTerminal(native, options) {
+	if (typeof native.initTerminalWithOptions === "function") native.initTerminalWithOptions({
+		alternateScreen: options.alternateScreen,
+		bracketedPaste: true,
+		hideCursor: true,
+		mouse: options.mouse,
+		rawMode: true
+	});
+	else if (options.mouse) native.initTerminalWithMouse();
+	else native.initTerminal();
+	native.enableIme?.();
+	native.initLayout();
+}
+//#endregion
 //#region src/app.ts
 /**
 * Fresco App - Application instance management
@@ -1196,33 +1460,12 @@ function updateAppSize(context, width, height) {
 	context.width.value = width;
 	context.height.value = height;
 }
-const CI_ENVIRONMENT_KEYS = [
-	"CI",
-	"CONTINUOUS_INTEGRATION",
-	"BUILD_NUMBER",
-	"RUN_ID"
-];
-function isTruthyEnvironmentValue(value) {
-	if (!value) return false;
-	return ![
-		"0",
-		"false",
-		"no"
-	].includes(value.toLowerCase());
-}
-function isCiEnvironment(env = process.env) {
-	return CI_ENVIRONMENT_KEYS.some((key) => isTruthyEnvironmentValue(env[key]));
-}
-function detectInteractiveMode(options) {
-	const stdout = options.stdout ?? process.stdout;
-	return options.interactive ?? (stdout.isTTY === true && !isCiEnvironment());
-}
 /**
 * Create a Fresco TUI app
 */
 function createApp(rootComponent, options = {}) {
 	const { mouse = false, exitOnCtrlC = true, onError } = options;
-	const interactive = detectInteractiveMode(options);
+	const interactive = detectInteractiveMode(options.interactive, options.stdout ?? process.stdout);
 	const screenReaderEnabled = ref(options.isScreenReaderEnabled ?? isScreenReaderEnabledByDefault());
 	const frameDelay = Math.max(1, Math.floor(1e3 / Math.max(1, options.maxFps ?? 30)));
 	let streamsContext;
@@ -1244,6 +1487,8 @@ function createApp(rootComponent, options = {}) {
 	let vueApp = null;
 	let rootElement = null;
 	let mounted = false;
+	let pendingMount = null;
+	let hasMountedSuccessfully = false;
 	let running = false;
 	let needsRender = true;
 	let appContext = null;
@@ -1255,6 +1500,8 @@ function createApp(rootComponent, options = {}) {
 	const renderedStaticItems = /* @__PURE__ */ new Map();
 	let cursorPosition;
 	let hasCursorOverride = false;
+	let instance;
+	const pluginInstallers = [];
 	let exitSettled = false;
 	let resolveExit = null;
 	let rejectExit = null;
@@ -1262,26 +1509,38 @@ function createApp(rootComponent, options = {}) {
 		resolveExit = resolve;
 		rejectExit = reject;
 	});
-	const { createApp: createVueApp } = createRenderer$1(() => {
-		needsRender = true;
+	const renderer = createRenderer$1({
+		lifecycle: options.devtools?.lifecycle,
+		onMutation() {
+			needsRender = true;
+		}
 	});
-	async function mount() {
-		if (mounted) return;
+	function publishRenderMetrics(root, layouts, start) {
+		if (!options.devtools && !options.onRender) return;
+		const metrics = {
+			renderTime: performance.now() - start,
+			nodeCount: treeToRenderNodes(root).length,
+			layoutCount: layouts.length
+		};
+		options.devtools?.recordRender(root, layouts, metrics);
+		options.onRender?.(metrics);
+	}
+	function mount() {
+		if (mounted) return Promise.resolve();
+		if (pendingMount) return pendingMount;
+		pendingMount = Promise.resolve().then(performMount).finally(() => {
+			pendingMount = null;
+		});
+		return pendingMount;
+	}
+	async function performMount() {
+		const app = renderer.createApp(componentFromRoot(rootComponent));
+		for (const install of pluginInstallers) install(app);
 		const n = interactive ? await loadNative() : null;
-		if (n) {
-			if (typeof n.initTerminalWithOptions === "function") n.initTerminalWithOptions({
-				alternateScreen: options.alternateScreen === true,
-				bracketedPaste: true,
-				hideCursor: true,
-				mouse,
-				rawMode: true
-			});
-			else if (mouse) n.initTerminalWithMouse();
-			else n.initTerminal();
-			n.enableIme?.();
-			n.initLayout();
-		}
-		const app = createVueApp(componentFromRoot(rootComponent));
+		if (n) initializeTerminal(n, {
+			alternateScreen: options.alternateScreen === true,
+			mouse
+		});
 		const info = n?.getTerminalInfo() ?? {
 			width: streamsContext.stdout.columns ?? 80,
 			height: streamsContext.stdout.rows ?? 24
@@ -1289,9 +1548,7 @@ function createApp(rootComponent, options = {}) {
 		appContext = createAppContext({
 			width: info.width,
 			height: info.height,
-			exit: (value) => {
-				unmount(value);
-			},
+			exit: (value) => void unmount(value),
 			render,
 			clear,
 			waitUntilRenderFlush,
@@ -1317,10 +1574,18 @@ function createApp(rootComponent, options = {}) {
 		}
 		vueApp = app;
 		mounted = true;
+		hasMountedSuccessfully = true;
 		running = true;
 		needsRender = true;
 		eventLoop();
 	}
+	function use(plugin, ...pluginOptions) {
+		if (pendingMount || hasMountedSuccessfully) throw new Error("Fresco plugins must be installed before the first successful mount");
+		pluginInstallers.push((app) => {
+			app.use(plugin, ...pluginOptions);
+		});
+		return instance;
+	}
 	async function unmount(errorOrResult) {
 		if (!mounted) return;
 		running = false;
@@ -1357,7 +1622,11 @@ function createApp(rootComponent, options = {}) {
 		return exitPromise;
 	}
 	async function waitUntilRenderFlush() {
-		return Promise.resolve();
+		if (pendingMount) await pendingMount;
+		await nextTick();
+		if (!needsRender) return;
+		needsRender = false;
+		render();
 	}
 	function clear() {
 		if (!mounted) return;
@@ -1426,7 +1695,7 @@ function createApp(rootComponent, options = {}) {
 			if (!interactive) {
 				staticOutput = appendOutput(staticOutput, captureStaticOutput(rootElement, renderedStaticItems));
 				nonInteractiveOutput = renderPlainOutput(rootElement, staticOutput);
-				options.onRender?.({ renderTime: performance.now() - start });
+				publishRenderMetrics(rootElement, [], start);
 				return;
 			}
 			if (!native) return;
@@ -1436,10 +1705,11 @@ function createApp(rootComponent, options = {}) {
 			if (renderNodes.length > 0) {
 				if (options.debug) streamsContext.stderr.write(`${JSON.stringify(renderNodes, null, 2)}\n`);
 				native.renderTree(renderNodes);
-				if ("getLastRenderLayouts" in native) updateLastRenderLayouts(native.getLastRenderLayouts());
+				const layouts = "getLastRenderLayouts" in native ? native.getLastRenderLayouts() : [];
+				updateLastRenderLayouts(layouts);
 				applyCursorOverride();
 				native.flushTerminal();
-				options.onRender?.({ renderTime: performance.now() - start });
+				publishRenderMetrics(rootElement, layouts, start);
 			}
 		} catch (error) {
 			if (onError) onError(error);
@@ -1450,58 +1720,31 @@ function createApp(rootComponent, options = {}) {
 		return (await loadNative()).getTerminalInfo();
 	}
 	function dispatchEvent(event) {
-		if (event.eventType === "resize") {
-			const resizeEvent = {
-				type: "resize",
-				width: event.width ?? 0,
-				height: event.height ?? 0
-			};
-			lastResizeEvent.value = resizeEvent;
-			updateAppSize(appContext, resizeEvent.width, resizeEvent.height);
-			return;
-		}
-		if (event.eventType === "paste") {
-			lastPasteEvent.value = {
-				type: "paste",
-				text: event.text ?? ""
-			};
-			return;
-		}
-		if (event.eventType === "mouse") {
-			lastMouseEvent.value = normalizeMouseEvent(event);
-			return;
-		}
-		if (event.eventType === "focus") {
-			lastFocusEvent.value = {
-				type: "focus",
-				focused: event.key === "gained"
-			};
-			return;
-		}
-		if (event.eventType === "compositionstart" || event.eventType === "compositionupdate" || event.eventType === "compositionend") {
-			lastCompositionEvent.value = {
-				type: event.eventType,
-				text: event.text ?? "",
-				cursor: event.cursor ?? 0
-			};
-			return;
-		}
-		if (event.eventType === "key") {
-			const modifiers = event.modifiers ?? {};
-			lastKeyEvent.value = {
-				type: "key",
-				key: event.key ?? void 0,
-				char: event.char ?? void 0,
-				ctrl: modifiers.ctrl ?? false,
-				alt: modifiers.alt ?? false,
-				shift: modifiers.shift ?? false,
-				meta: modifiers.meta ?? false,
-				super: modifiers.super ?? false,
-				hyper: modifiers.hyper ?? false,
-				capsLock: modifiers.capsLock ?? false,
-				numLock: modifiers.numLock ?? false,
-				eventType: normalizeKeyEventType(event.keyEventType)
-			};
+		const normalized = normalizeInputEvent(event);
+		if (!normalized) return;
+		options.devtools?.recordInput(normalized);
+		switch (normalized.type) {
+			case "resize":
+				lastResizeEvent.value = normalized;
+				updateAppSize(appContext, normalized.width, normalized.height);
+				break;
+			case "paste":
+				lastPasteEvent.value = normalized;
+				break;
+			case "mouse":
+				routeAndPublishMouseInput(renderer, rootElement, normalized, getLastRenderLayouts(), lastMouseEvent);
+				break;
+			case "focus":
+				lastFocusEvent.value = normalized;
+				break;
+			case "compositionstart":
+			case "compositionupdate":
+			case "compositionend":
+				lastCompositionEvent.value = normalized;
+				break;
+			case "key":
+				lastKeyEvent.value = normalized;
+				break;
 		}
 	}
 	async function eventLoop() {
@@ -1538,7 +1781,8 @@ function createApp(rootComponent, options = {}) {
 			await new Promise((resolve) => setTimeout(resolve, frameDelay));
 		}
 	}
-	return {
+	instance = {
+		use,
 		mount,
 		unmount,
 		waitUntilExit,
@@ -1547,6 +1791,7 @@ function createApp(rootComponent, options = {}) {
 		clear,
 		getTerminalInfo
 	};
+	return instance;
 }
 /**
 * Ink-compatible helper that mounts immediately.
@@ -1609,6 +1854,6 @@ function renderToString(root, options = {}) {
 	return output;
 }
 //#endregion
-export { APP_KEY as A, useStdin as C, createFocusManager as D, FOCUS_KEY as E, useApp as M, SCREEN_READER_KEY as N, useFocus as O, isScreenReaderEnabledByDefault as P, useStderr as S, useStreamsContext as T, CURSOR_KEY as _, lastMouseEvent as a, STREAMS_KEY as b, render as c, isStaticNode as d, createRenderer$1 as f, updateLastRenderLayouts as g, measureElement as h, lastKeyEvent as i, createAppContext as j, useFocusManager as k, renderToString as l, getLastRenderLayout as m, lastCompositionEvent as n, lastPasteEvent as o, treeToRenderNodes as p, lastFocusEvent as r, lastResizeEvent as s, createApp as t, isStaticItemNode as u, createCursorContext as v, useStdout as w, createStreamsContext as x, useCursor as y };
+export { useFocusManager as A, useStdin as C, createFocusManager as D, FOCUS_KEY as E, isScreenReaderEnabledByDefault as F, createAppContext as M, useApp as N, provideFocusScope as O, SCREEN_READER_KEY as P, useStderr as S, useStreamsContext as T, CURSOR_KEY as _, lastMouseEvent as a, STREAMS_KEY as b, render as c, isStaticNode as d, createRenderer$1 as f, updateLastRenderLayouts as g, measureElement as h, lastKeyEvent as i, APP_KEY as j, useFocus as k, renderToString as l, getLastRenderLayout as m, lastCompositionEvent as n, lastPasteEvent as o, treeToRenderNodes as p, lastFocusEvent as r, lastResizeEvent as s, createApp as t, isStaticItemNode as u, createCursorContext as v, useStdout as w, createStreamsContext as x, useCursor as y };
 
-//# sourceMappingURL=app-B9yJzz5S.mjs.map
+//# sourceMappingURL=app-C_wFlWSV.mjs.map