@iowarp/clio-coder 0.3.1 → 0.3.2

package/src/interactive/interactive-shell.ts

@@ -1,13 +1,25 @@
-import type { Component, Terminal } from "../engine/tui.js";
-import { ProcessTerminal, TUI } from "../engine/tui.js";
-import { createRenderTrace, type RenderTrace, renderTracePath, traceTerminalWrites } from "./render-trace.js";
+import type { Component, Terminal, TuiMode, TuiRenderObserver } from "../engine/tui.js";
+import { InstrumentedTuiAltScreen, InstrumentedTuiMainScreen, ProcessTerminal, type TUI } from "../engine/tui.js";
+import {
+	createRenderTrace,
+	type RenderTrace,
+	renderTracePath,
+	traceComponentRenders,
+	traceProcessStdout,
+} from "./render-trace.js";
+import type { StdoutBackpressureGate } from "./stdout-backpressure.js";
+import { installStdoutBackpressureGate } from "./stdout-backpressure.js";
 
 export interface InteractiveShellTui {
+	readonly mode?: TuiMode;
 	addChild(component: Component): void;
+	removeChild?(component: Component): void;
+	setLayoutRoot?(component: Component | undefined): void;
 	setFocus(component: Component): void;
 	start(): void;
 	stop(): void;
 	requestRender(): void;
+	renderNow?(force?: boolean): void;
 }
 
 export interface InteractiveShellInterval {
@@ -22,6 +34,8 @@ export interface InteractiveShellDeps<
 	createTui: (terminal: TTerminal) => TTui;
 	scheduleInterval?: (callback: () => void, intervalMs: number) => InteractiveShellInterval;
 	clearScheduledInterval?: (handle: InteractiveShellInterval) => void;
+	prepareRoot?: (root: Component) => void;
+	onStop?: () => void | Promise<void>;
 }
 
 export interface InteractiveShell<
@@ -34,6 +48,16 @@ export interface InteractiveShell<
 	anchor(): Promise<number>;
 	releaseAnchor(): void;
 	stop(): void;
+	/** Issue the latest model frame and wait a finite bound for stdout drain. */
+	commitCurrentFrame(timeoutMs?: number): Promise<number | null>;
+	/** True after this process has observed stdout saturation at least once. */
+	hasObservedBackpressure(): boolean;
+	/** Enable admission control only while presentation pacing is actually active. */
+	setStreamPacingActive(active: boolean): void;
+	/** Await asynchronous teardown work started by stop(), including trace-file settlement. */
+	settle(): Promise<void>;
+	/** Resolve after the next render transaction that reaches terminal commit. */
+	nextCommittedFrame(): Promise<number | null>;
 	complete(code: number): void;
 }
 
@@ -62,6 +86,8 @@ export function createInteractiveShell<TTerminal extends Terminal, TTui extends
 	let resolveRun: ((code: number) => void) | null = null;
 	let run: Promise<number> | null = null;
 	let completedCode: number | null = null;
+	let stopped = false;
+	let stopSettlement: Promise<void> | null = null;
 
 	return {
 		terminal,
@@ -69,7 +95,9 @@ export function createInteractiveShell<TTerminal extends Terminal, TTui extends
 		mount(root, focus): void {
 			if (mounted) return;
 			mounted = true;
+			deps.prepareRoot?.(root);
 			tui.addChild(root);
+			if (tui.mode === "fullscreen") tui.setLayoutRoot?.(root);
 			tui.setFocus(focus);
 			tui.start();
 		},
@@ -90,12 +118,37 @@ export function createInteractiveShell<TTerminal extends Terminal, TTui extends
 			keepAlive = null;
 		},
 		stop(): void {
+			if (stopped) return;
+			stopped = true;
 			try {
 				tui.stop();
 			} catch {
 				// TUI may already be stopped by a closed input stream.
+			} finally {
+				try {
+					stopSettlement = Promise.resolve(deps.onStop?.()).then(() => undefined);
+				} catch {
+					// Teardown is best effort, like a terminal that already closed.
+					stopSettlement = Promise.resolve();
+				}
 			}
 		},
+		async commitCurrentFrame(): Promise<number | null> {
+			if (!tui.renderNow) {
+				tui.requestRender();
+				return null;
+			}
+			tui.renderNow(false);
+			return null;
+		},
+		hasObservedBackpressure: () => false,
+		setStreamPacingActive: () => {},
+		settle(): Promise<void> {
+			return stopSettlement ?? Promise.resolve();
+		},
+		nextCommittedFrame(): Promise<number | null> {
+			return Promise.resolve(null);
+		},
 		complete(code): void {
 			if (completedCode !== null) return;
 			completedCode = code;
@@ -115,20 +168,221 @@ export function getActiveRenderTrace(): RenderTrace | null {
 	return activeRenderTrace;
 }
 
+/**
+ * Wait for ordinary admission, but never let a missing drain erase the final
+ * model state. After the finite pre-render bound, exactly one caller-supplied
+ * final frame is still issued; a post-render drain wait is likewise bounded.
+ */
+export async function settleLatestInteractiveFrame(
+	gate: Pick<StdoutBackpressureGate, "whenWritable"> | null,
+	timeoutMs: number,
+	renderFrame: () => Promise<number>,
+): Promise<number> {
+	const writableBeforeRender = gate ? await gate.whenWritable(timeoutMs) : true;
+	const frameId = await renderFrame();
+	if (writableBeforeRender && gate) await gate.whenWritable(timeoutMs);
+	return frameId;
+}
+
 /** Production factories stay here so the composition root does not own them. */
-export function createProcessInteractiveShell(): InteractiveShell<ProcessTerminal, TUI> {
+export function createProcessInteractiveShell(
+	options: {
+		tuiMode?: TuiMode;
+		onFirstFrameCommit?: (frameId: number) => void;
+		streamPacingActive?: boolean;
+		/** Construction fault seams for process-global rollback contracts. */
+		testing?: {
+			createTerminal?: () => ProcessTerminal;
+			createTui?: (terminal: ProcessTerminal) => TUI;
+		};
+	} = {},
+): InteractiveShell<ProcessTerminal, TUI> {
 	const tracePath = renderTracePath();
+	let restoreStdout: (() => void) | null = null;
+	let restoreFirstFrameStdout: (() => void) | null = null;
+	let restoreRoot: (() => void) | null = null;
+	let backpressure: StdoutBackpressureGate | null = null;
+	let observedBackpressure = false;
 	if (tracePath) {
-		activeRenderTrace = createRenderTrace(tracePath);
-		const trace = activeRenderTrace;
-		process.once("exit", () => trace.close());
-	}
+		let candidate: RenderTrace | null = null;
+		try {
+			candidate = createRenderTrace(tracePath);
+			restoreStdout = traceProcessStdout(candidate);
+			activeRenderTrace = candidate;
+		} catch {
+			// A diagnostics path must never prevent the interactive application from starting.
+			restoreStdout?.();
+			restoreStdout = null;
+			void candidate?.close().catch(() => {});
+			activeRenderTrace = null;
+		}
+	} else activeRenderTrace = null;
 	const trace = activeRenderTrace;
-	return createInteractiveShell({
-		createTerminal: () => {
-			const terminal = new ProcessTerminal();
-			return trace ? traceTerminalWrites(terminal, trace) : terminal;
+	if (trace && options.onFirstFrameCommit) trace.onFirstFrameCommit(options.onFirstFrameCommit);
+	let firstFrameDelivered = false;
+	let firstFrameSeq = 0;
+	let firstFrameActive = false;
+	let firstFrameWrote = false;
+	if (!trace && options.onFirstFrameCommit) {
+		const stdout = process.stdout;
+		const original = stdout.write;
+		const wrapped = function (this: typeof stdout, ...args: unknown[]): boolean {
+			const returned = Reflect.apply(original, this, args) as boolean;
+			if (firstFrameActive) firstFrameWrote = true;
+			return returned;
+		} as typeof stdout.write;
+		stdout.write = wrapped;
+		restoreFirstFrameStdout = () => {
+			if (stdout.write === wrapped) stdout.write = original;
+		};
+	}
+	const firstFrameOnlyObserver: TuiRenderObserver = {
+		isEnabled: () => !firstFrameDelivered,
+		beginFrame: () => {
+			firstFrameSeq += 1;
+			firstFrameActive = true;
+			firstFrameWrote = false;
+			return firstFrameSeq;
+		},
+		endFrame: (frame) => {
+			firstFrameActive = false;
+			if (firstFrameDelivered || !firstFrameWrote) return;
+			firstFrameDelivered = true;
+			options.onFirstFrameCommit?.(frame as number);
+			restoreFirstFrameStdout?.();
+			restoreFirstFrameStdout = null;
+		},
+		beginPhase: () => null,
+		endPhase: () => {},
+	};
+	const primaryObserver = trace ?? (options.onFirstFrameCommit ? firstFrameOnlyObserver : null);
+	let committedFrameSequence = 0;
+	const frameWaiters: Array<{ resolve: (frameId: number) => void }> = [];
+	const renderObserver: TuiRenderObserver = {
+		isEnabled: () => frameWaiters.length > 0 || (primaryObserver !== null && (primaryObserver.isEnabled?.() ?? true)),
+		beginFrame: (fields) => ({
+			primary: primaryObserver?.beginFrame(fields),
+			primaryActive: primaryObserver !== null && (primaryObserver.isEnabled?.() ?? true),
+			frameId: ++committedFrameSequence,
+		}),
+		endFrame: (token) => {
+			const frame = token as { primary: unknown; primaryActive: boolean; frameId: number };
+			if (frame.primaryActive) primaryObserver?.endFrame(frame.primary);
+			for (const waiter of frameWaiters.splice(0)) waiter.resolve(frame.frameId);
+		},
+		beginPhase: (token, phase) => {
+			const frame = token as { primary: unknown; primaryActive: boolean };
+			return frame.primaryActive ? primaryObserver?.beginPhase(frame.primary, phase) : null;
 		},
-		createTui: (terminal) => new TUI(terminal),
-	});
+		endPhase: (token, phase, phaseToken) => {
+			const frame = token as { primary: unknown; primaryActive: boolean };
+			if (frame.primaryActive) primaryObserver?.endPhase(frame.primary, phase, phaseToken);
+		},
+	};
+	const renderAdmission = {
+		get blocked() {
+			return backpressure?.blocked ?? false;
+		},
+		onWritable(listener: () => void) {
+			if (backpressure) return backpressure.onWritable(listener);
+			queueMicrotask(listener);
+			return () => {};
+		},
+	};
+	const setStreamPacingActive = (active: boolean): void => {
+		if (active) {
+			backpressure ??= installStdoutBackpressureGate();
+			return;
+		}
+		if (!backpressure) return;
+		observedBackpressure ||= backpressure.observed;
+		backpressure.restore();
+		backpressure = null;
+	};
+	let instrumentationCleanupStarted = false;
+	let instrumentationCleanupPromise: Promise<void> = Promise.resolve();
+	const cleanupInstrumentation = (): Promise<void> => {
+		if (instrumentationCleanupStarted) return instrumentationCleanupPromise;
+		instrumentationCleanupStarted = true;
+		const errors: unknown[] = [];
+		const attempt = (operation: () => void): void => {
+			try {
+				operation();
+			} catch (error) {
+				errors.push(error);
+			}
+		};
+		attempt(() => setStreamPacingActive(false));
+		attempt(() => restoreRoot?.());
+		restoreRoot = null;
+		attempt(() => restoreStdout?.());
+		restoreStdout = null;
+		attempt(() => restoreFirstFrameStdout?.());
+		restoreFirstFrameStdout = null;
+		if (activeRenderTrace === trace) activeRenderTrace = null;
+		instrumentationCleanupPromise = (async () => {
+			if (trace) {
+				try {
+					await trace.close();
+				} catch (error) {
+					errors.push(error);
+				}
+			}
+			if (errors.length > 0) throw new AggregateError(errors, "interactive shell instrumentation cleanup failed");
+		})();
+		return instrumentationCleanupPromise;
+	};
+	let shell: InteractiveShell<ProcessTerminal, TUI>;
+	try {
+		setStreamPacingActive(options.streamPacingActive === true);
+		shell = createInteractiveShell({
+			createTerminal: options.testing?.createTerminal ?? (() => new ProcessTerminal()),
+			createTui: (terminal) =>
+				options.testing?.createTui?.(terminal) ??
+				(options.tuiMode === "fullscreen"
+					? new InstrumentedTuiAltScreen(terminal, renderObserver, undefined, undefined, undefined, renderAdmission)
+					: new InstrumentedTuiMainScreen(terminal, renderObserver, undefined, undefined, renderAdmission)),
+			prepareRoot: (root) => {
+				if (trace) restoreRoot = traceComponentRenders(root, trace);
+			},
+			onStop: cleanupInstrumentation,
+		});
+	} catch (error) {
+		void cleanupInstrumentation().catch(() => {});
+		throw error;
+	}
+	return {
+		...shell,
+		nextCommittedFrame(): Promise<number | null> {
+			return new Promise<number>((resolve) => {
+				frameWaiters.push({ resolve });
+			});
+		},
+		async commitCurrentFrame(timeoutMs = 30_000): Promise<number | null> {
+			return await settleLatestInteractiveFrame(backpressure, timeoutMs, async () => {
+				const tui = shell.tui as TUI & { renderNow(force?: boolean): void };
+				const waiter: { resolve: (frameId: number) => void } = { resolve: () => {} };
+				const frame = new Promise<number>((resolve) => {
+					waiter.resolve = resolve;
+					frameWaiters.push(waiter);
+				});
+				try {
+					// Even when the writable never drains, issue exactly one bounded
+					// final frame. Preserve the renderer's cursor/history state: forcing
+					// a reset here makes TuiMainScreen repaint from the current physical
+					// column and can concatenate the full frame onto the footer. A direct
+					// differential render is still synchronous and commits every newest
+					// component mutation without reopening ordinary frame production.
+					tui.renderNow(false);
+				} catch (error) {
+					const index = frameWaiters.indexOf(waiter);
+					if (index >= 0) frameWaiters.splice(index, 1);
+					throw error;
+				}
+				return await frame;
+			});
+		},
+		hasObservedBackpressure: () => observedBackpressure || backpressure?.observed === true,
+		setStreamPacingActive,
+	};
 }