@haywoodmarx/agent-pager 0.1.0

package/dist/src/tui/app.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode } from "react";
+import { type TuiActionCatalogue } from "./actions.js";
+import type { TuiOperatorModel, TuiOperatorModelState } from "./model.js";
+import { type MessageViewsProps } from "./message-views.js";
+import { type TuiTheme } from "./theme.js";
+/** Explicit production presentation collaborators that do not belong to the operator model. */
+export type OperatorTuiProps = {
+    readonly model: TuiOperatorModel;
+    readonly theme: Readonly<TuiTheme>;
+    readonly body: MessageViewsProps["body"];
+    readonly copyFallback: MessageViewsProps["copyFallback"];
+    readonly commands: MessageViewsProps["commands"];
+    readonly onShutdown: () => void;
+    readonly colorEnabled?: boolean;
+    /** Everything the actions menu offers. */
+    readonly actions: TuiActionCatalogue;
+};
+/** Keys the tree pane advertises whatever its selection. */
+export declare const TREE_FOOTER_KEYS = "m menu  l log  ? help";
+/** Keys the portrait tree screen advertises whatever its selection. */
+export declare const PORTRAIT_TREE_FOOTER_KEYS = "m menu  l log  ? help  \u2191\u2193 move  \u2192 open";
+/**
+ * Reduce the shell-owned pane navigation without changing authoritative or component-local state.
+ * @param state - Current model state; an open overlay makes every key a no-op here.
+ * @param key - Key name as OpenTUI normalises it, such as `tab`, `right` or `return`.
+ * @param portrait - Whether the single-pane stack is in use, which makes the message log a focus stop.
+ * @returns The next view: the same object for a key navigation does not handle, and possibly a new object with
+ *   unchanged focus for a movement key that has nowhere to go.
+ */
+export declare function reduceOperatorTuiNavigation(state: TuiOperatorModelState, key: string, portrait: boolean): TuiOperatorModelState["view"];
+/**
+ * Compose the complete responsive operator surface over the renderer-independent model.
+ *
+ * Mounting starts the model and unmounting disposes it.
+ * @param properties - Model and presentation collaborators, and the action that ends the process.
+ * @returns Root element filling the terminal, bordered, with the wide or portrait layout chosen from its width.
+ */
+export declare function OperatorTui(properties: OperatorTuiProps): ReactNode;

package/dist/src/tui/app.js

@@ -0,0 +1,378 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "@opentui/react/jsx-runtime";
+import { useKeyboard, useTerminalDimensions } from "@opentui/react";
+import { useEffect, useMemo } from "react";
+import { OPERATOR_PROTOCOL_VERSION } from "../operator/protocol.js";
+import { AgentTree, AgentTreeOverlay, executeAgentTreeResult, reduceAgentTreeKey, selectTuiCollapsibleSelection, } from "./agent-tree.js";
+import { ActionRunOverlay, ActionsOverlay, reduceOperatorActionsKey, skillInstallTerminalSize, } from "./actions.js";
+import { Line, Overlay, PaneBar, Rule, VERTICAL_SCROLL_STYLE, useTuiModel } from "./chrome.js";
+import { AgentTrafficLog, MessageDetail, MessageOverlays, selectNewestTuiTraffic, stepTuiTrafficSelection, } from "./message-views.js";
+import { AGENT_TREE_COLUMNS, sidePaneWidths, MESSAGE_LOG_COLUMNS, PORTRAIT_BREAKPOINT_COLUMNS, agentColor, activeAgentCount, agentLogScope, brokerIndicator, COLLAPSED_LOG_ROWS, describeCommandOutcome, diagnosticColor, fitBarLeading, formatClock, formatDiagnostic, selectedMessage, selectMessageBodyRows, selectTuiTraffic, } from "./presentation.js";
+import { dimTuiTheme } from "./theme.js";
+/* eslint-enable jsdoc/require-jsdoc -- The collaborator declarations end here. */
+/** Rows the wide layout spends on fixed chrome rather than pane content. */
+const WIDE_PANE_CHROME_ROWS = 7;
+/** Rows the portrait layout spends on fixed chrome rather than pane content. */
+const PORTRAIT_PANE_CHROME_ROWS = 5;
+/** Keys the tree pane advertises whatever its selection. */
+export const TREE_FOOTER_KEYS = "m menu  l log  ? help";
+/** Keys the portrait tree screen advertises whatever its selection. */
+export const PORTRAIT_TREE_FOOTER_KEYS = "m menu  l log  ? help  ↑↓ move  → open";
+/** Keys the tree pane adds once a selection can answer them. */
+const AGENT_FOOTER_KEYS = "i details  p ping";
+/**
+ * Compose the tree footer for the current selection.
+ * @param state - Current projection and view state.
+ * @param base - Keys the pane advertises whatever is selected.
+ * @returns Footer text naming only the keys the selection can answer.
+ */
+function selectTreeFooterKeys(state, base) {
+    return state.view.selection?.kind === "agent" ? `${base}  ${AGENT_FOOTER_KEYS}` : base;
+}
+/** Keys the portrait traffic screen advertises in its navigation footer. */
+const PORTRAIT_TRAFFIC_FOOTER_KEYS = "← back  → open  f follow";
+/** Keys the portrait message screen advertises in its navigation footer. */
+const PORTRAIT_MESSAGE_FOOTER_KEYS = "← back  o full message";
+/**
+ * Report the character rows a pane gives its content at one terminal height.
+ * @param height - Current terminal rows.
+ * @param portrait - Whether the single-pane stack is in use.
+ * @param logRows - Rows the diagnostics log occupies beneath the panes.
+ * @returns Rows left for pane content.
+ */
+function selectPaneContentRows(height, portrait, logRows) {
+    return Math.max(0, height - (portrait ? PORTRAIT_PANE_CHROME_ROWS : WIDE_PANE_CHROME_ROWS) - logRows);
+}
+/**
+ * Report the character columns each pane occupies at one terminal width and the widths the operator dragged.
+ * @param width - Current terminal columns.
+ * @param portrait - Whether the single-pane stack is in use, where every pane takes the whole inner width.
+ * @param view - View state holding the dragged widths of the two side panes.
+ * @returns Columns each pane occupies, including its own one-column insets; the agent log takes what the side panes leave.
+ */
+function selectPaneWidths(width, portrait, view) {
+    const outer = Math.max(0, width - 2);
+    if (portrait)
+        return { tree: outer, agentLog: outer, messageLog: outer };
+    const shared = Math.max(0, outer - 2);
+    const { tree, messageLog } = sidePaneWidths({
+        tree: view.treeColumns,
+        treeFallback: AGENT_TREE_COLUMNS,
+        messageLog: view.messageLogColumns,
+        messageLogFallback: MESSAGE_LOG_COLUMNS,
+        available: shared,
+    });
+    return { tree, agentLog: Math.max(0, shared - tree - messageLog), messageLog };
+}
+/**
+ * Reduce the shell-owned pane navigation without changing authoritative or component-local state.
+ * @param state - Current model state; an open overlay makes every key a no-op here.
+ * @param key - Key name as OpenTUI normalises it, such as `tab`, `right` or `return`.
+ * @param portrait - Whether the single-pane stack is in use, which makes the message log a focus stop.
+ * @returns The next view: the same object for a key navigation does not handle, and possibly a new object with
+ *   unchanged focus for a movement key that has nowhere to go.
+ */
+export function reduceOperatorTuiNavigation(state, key, portrait) {
+    const view = state.view;
+    if (view.overlay.kind !== "none")
+        return view;
+    // An empty agent log has no row to select, so focus would land somewhere with nothing to act on.
+    const carriesTraffic = selectTuiTraffic(state).length > 0;
+    // The message log is a stack level in portrait; in the wide layout it is a detail pane whose one
+    // key reaches it from the agent log, so keyboard navigation never stops there. A click on the
+    // detail focuses it in either layout.
+    const message = selectedMessage(state);
+    const panes = [
+        "tree",
+        ...(carriesTraffic ? ["agent_log"] : []),
+        ...(portrait && carriesTraffic && message ? ["message_log"] : []),
+    ];
+    const current = panes.indexOf(view.focus);
+    const step = (delta) => ({
+        ...view,
+        focus: panes[Math.min(Math.max(Math.max(current, 0) + delta, 0), panes.length - 1)] ?? "tree",
+    });
+    if (key === "tab")
+        return { ...view, focus: panes[(Math.max(current, 0) + 1) % panes.length] ?? "tree" };
+    if (key === "right")
+        return step(1);
+    if (key === "left")
+        return step(-1);
+    if (key === "enter" || key === "return") {
+        if (view.focus === "message_log" && message)
+            return {
+                ...view,
+                overlay: { kind: "full_message", messageId: message.messageId },
+                overlayReturnFocus: view.focus,
+            };
+        if (selectTuiCollapsibleSelection(state) === null)
+            return step(1);
+    }
+    if (key === "escape" && portrait && view.focus === "message_log")
+        return { ...view, focus: "agent_log" };
+    if (key === "escape" && portrait && view.focus === "agent_log")
+        return { ...view, focus: "tree" };
+    return view;
+}
+/**
+ * Compose the complete responsive operator surface over the renderer-independent model.
+ *
+ * Mounting starts the model and unmounting disposes it.
+ * @param properties - Model and presentation collaborators, and the action that ends the process.
+ * @returns Root element filling the terminal, bordered, with the wide or portrait layout chosen from its width.
+ */
+export function OperatorTui(properties) {
+    const state = useTuiModel(properties.model);
+    const { width, height } = useTerminalDimensions();
+    const portrait = width < PORTRAIT_BREAKPOINT_COLUMNS;
+    const overlaid = state.view.overlay.kind !== "none";
+    const backdrop = useMemo(() => dimTuiTheme(properties.theme), [properties.theme]);
+    const theme = overlaid ? backdrop : properties.theme;
+    const colorEnabled = properties.colorEnabled ?? true;
+    const messageProperties = {
+        model: properties.model,
+        theme,
+        body: properties.body,
+        copyFallback: properties.copyFallback,
+        commands: properties.commands,
+    };
+    useEffect(() => {
+        void properties.model.start();
+        return () => {
+            properties.model.dispose();
+        };
+    }, [properties.model]);
+    useKeyboard((key) => {
+        const current = properties.model.state;
+        if (current.view.overlay.kind === "help" || current.view.overlay.kind === "log") {
+            // The key that opened the log closes it, so it reads as a toggle rather than a one-way door.
+            const closes = key.name === "escape" || (key.name === "l" && current.view.overlay.kind === "log");
+            if (closes)
+                properties.model.updateView((view) => ({ ...view, overlay: { kind: "none" } }));
+            return;
+        }
+        if (current.view.overlay.kind === "actions" || current.view.overlay.kind === "action_run") {
+            const result = reduceOperatorActionsKey(current, key.name, properties.actions);
+            if (result.view !== current.view)
+                properties.model.updateView(() => result.view);
+            const request = result.request;
+            switch (request.kind) {
+                case "none":
+                    break;
+                case "clear":
+                    properties.model.clearLocalRun();
+                    break;
+                case "cancel":
+                    properties.model.cancelLocalRun();
+                    break;
+                case "start":
+                    properties.model.startLocalRun(request.command.command, request.command.args, skillInstallTerminalSize(height));
+                    break;
+            }
+            return;
+        }
+        if (key.name === "m" && current.view.overlay.kind === "none") {
+            properties.model.updateView((view) => ({
+                ...view,
+                overlay: { kind: "actions" },
+                actionIndex: 0,
+                overlayReturnFocus: view.focus,
+            }));
+            return;
+        }
+        if (key.name === "q" && current.view.overlay.kind === "none")
+            properties.onShutdown();
+        if (key.name === "l" && current.view.overlay.kind === "none") {
+            properties.model.updateView((view) => ({ ...view, overlay: { kind: "log" }, overlayReturnFocus: view.focus }));
+            return;
+        }
+        if (key.name === "?" && current.view.overlay.kind === "none") {
+            properties.model.updateView((view) => ({
+                ...view,
+                overlay: { kind: "help" },
+                overlayReturnFocus: view.focus,
+            }));
+            return;
+        }
+        if (key.name === "up" || key.name === "down") {
+            stepFocus(properties.model, key.name, onCommand);
+            return;
+        }
+        const view = reduceOperatorTuiNavigation(current, key.name, portrait);
+        if (view !== current.view) {
+            properties.model.updateView(() => view);
+            if (view.focus === "agent_log" && current.view.focus !== "agent_log" && view.trafficId === null)
+                selectNewestTuiTraffic(properties.model);
+        }
+    });
+    const paneWidths = selectPaneWidths(width, portrait, state.view);
+    const bodyRows = selectMessageBodyRows(selectPaneContentRows(height, portrait, COLLAPSED_LOG_ROWS));
+    const onCommand = submitCommand(properties.model, properties.commands);
+    const tree = (_jsx(AgentTree, { model: properties.model, theme: theme, onCommand: onCommand, colorEnabled: colorEnabled, width: paneWidths.tree }));
+    const traffic = _jsx(AgentTrafficLog, { ...messageProperties, colorEnabled: colorEnabled, width: paneWidths.agentLog });
+    const detail = (_jsx(MessageDetail, { ...messageProperties, colorEnabled: colorEnabled, width: paneWidths.messageLog, bodyRows: bodyRows }));
+    return (_jsxs("box", { width: "100%", height: "100%", flexDirection: "column", border: true, borderStyle: "single", borderColor: theme.structure.rulesAndLabels, children: [portrait ? null : _jsx(StatusBar, { state: state, theme: theme }), portrait ? (_jsx(PortraitStack, { state: state, theme: theme, colorEnabled: colorEnabled, tree: tree, traffic: traffic, detail: detail, width: paneWidths.messageLog })) : (_jsxs("box", { flexGrow: 1, flexDirection: "row", children: [_jsx(Pane, { theme: theme, width: paneWidths.tree, footers: [
+                            _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: selectTreeFooterKeys(state, TREE_FOOTER_KEYS) }), right: null }, "keys"),
+                        ], children: tree }), _jsx(Divider, { theme: theme, headerJunction: "\u251C" }), _jsx(Pane, { theme: theme, flexible: true, header: _jsx(AgentLogHeader, { state: state, theme: theme, colorEnabled: colorEnabled, width: paneWidths.agentLog }), footers: [_jsx(FollowFooter, { state: state, theme: theme }, "follow")], children: traffic }), _jsx(Divider, { theme: theme, headerJunction: "\u253C" }), _jsx(Pane, { theme: theme, width: paneWidths.messageLog, header: _jsx(MessageLogHeader, { state: state, theme: theme, width: paneWidths.messageLog }), footers: [
+                            _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: selectedMessage(state) ? "o full message" : "" }), right: null }, "keys"),
+                        ], children: detail })] })), _jsx(DiagnosticsLog, { state: state, theme: theme, width: width }), portrait ? null : (_jsxs(_Fragment, { children: [_jsx(PaneGrabStrip, { left: paneWidths.tree, onDrag: (column) => {
+                            properties.model.resizePane("tree", Math.max(0, column - 1), paneWidths.messageLog);
+                        }, onSettle: () => {
+                            properties.model.commitPaneLayout();
+                        } }), _jsx(PaneGrabStrip, { left: paneWidths.tree + 1 + paneWidths.agentLog, onDrag: (column) => {
+                            properties.model.resizePane("message_log", Math.max(0, width - column - 2), paneWidths.tree);
+                        }, onSettle: () => {
+                            properties.model.commitPaneLayout();
+                        } })] })), _jsx(AgentTreeOverlay, { model: properties.model, theme: properties.theme, onCommand: onCommand, colorEnabled: colorEnabled }), _jsx(MessageOverlays, { ...messageProperties, theme: properties.theme, colorEnabled: colorEnabled }), state.view.overlay.kind === "actions" ? (_jsx(ActionsOverlay, { actionIndex: state.view.actionIndex, catalogue: properties.actions, theme: properties.theme, onSelect: (action) => {
+                    properties.model.updateView((view) => ({ ...view, overlay: { kind: "action_run", actionId: action.id } }));
+                } })) : null, state.view.overlay.kind === "action_run" ? (_jsx(ActionRunOverlay, { run: state.run, actionId: state.view.overlay.actionId, catalogue: properties.actions, terminalRows: height, copyFallback: properties.copyFallback, onInput: (bytes) => {
+                    properties.model.writeToLocalRun(bytes);
+                }, onResize: (columns, rows) => {
+                    properties.model.resizeLocalRun(columns, rows);
+                }, theme: properties.theme })) : null, state.view.overlay.kind === "help" ? _jsx(HelpOverlay, { theme: properties.theme }) : null, state.view.overlay.kind === "log" ? _jsx(DiagnosticsOverlay, { state: state, theme: properties.theme }) : null] }));
+}
+/** Marker leading a portrait screen's header, which returns to the screen above it. */
+const PORTRAIT_BACK_GLYPH = "◂ ";
+function PortraitStack({ state, theme, colorEnabled, tree, traffic, detail, width, }) {
+    if (state.view.focus === "agent_log") {
+        const scope = agentLogScope(state);
+        return (_jsx(Pane, { theme: theme, flexible: true, topRule: false, header: _jsx(PaneBar, { left: _jsxs("text", { fg: theme.structure.rulesAndLabels, children: ["◂ ", _jsx("span", { fg: scope.kind === "agent" && colorEnabled ? agentColor(scope.agentId, theme) : theme.structure.emphasis, children: scope.title })] }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: scope.detail }) }), footers: [
+                _jsx(FollowFooter, { state: state, theme: theme }, "follow"),
+                _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: PORTRAIT_TRAFFIC_FOOTER_KEYS }), right: null }, "keys"),
+            ], children: traffic }));
+    }
+    if (state.view.focus === "message_log") {
+        const message = selectedMessage(state);
+        const clock = message ? formatClock(message.acceptedAt) : "";
+        return (_jsx(Pane, { theme: theme, flexible: true, topRule: false, header: _jsx(PaneBar, { left: _jsxs("text", { fg: theme.structure.rulesAndLabels, children: [PORTRAIT_BACK_GLYPH, _jsx("span", { fg: theme.structure.emphasis, children: message ? fitBarLeading(message.messageId, width - PORTRAIT_BACK_GLYPH.length, clock) : "—" })] }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: clock }) }), footers: [
+                _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: PORTRAIT_MESSAGE_FOOTER_KEYS }), right: null }, "keys"),
+            ], children: detail }));
+    }
+    return (_jsx(Pane, { theme: theme, flexible: true, topRule: false, header: _jsx(PortraitStatusBar, { state: state, theme: theme }), footers: [
+            _jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: selectTreeFooterKeys(state, PORTRAIT_TREE_FOOTER_KEYS) }), right: null }, "keys"),
+        ], children: tree }));
+}
+function Pane({ theme, width, flexible = false, topRule = true, header, footers, children, }) {
+    return (_jsxs("box", { ...(width === undefined ? {} : { width }), ...(flexible ? { flexGrow: 1 } : {}), height: "100%", flexDirection: "column", ...(topRule
+            ? {
+                border: ["top", "bottom"],
+                borderStyle: "single",
+                borderColor: theme.structure.rulesAndLabels,
+            }
+            : { border: ["bottom"], borderStyle: "single", borderColor: theme.structure.rulesAndLabels }), children: [header === undefined ? null : (_jsxs(_Fragment, { children: [header, _jsx(Rule, { theme: theme })] })), _jsx("box", { flexGrow: 1, flexShrink: 1, overflow: "hidden", flexDirection: "column", children: children }), footers.map((footer, index) => (_jsxs("box", { flexDirection: "column", flexShrink: 0, children: [_jsx(Rule, { theme: theme }), footer] }, index)))] }));
+}
+function AgentLogHeader({ state, theme, colorEnabled, width, }) {
+    const scope = agentLogScope(state);
+    const titleColor = scope.kind === "agent" && colorEnabled ? agentColor(scope.agentId, theme) : theme.structure.emphasis;
+    return (_jsx(PaneBar, { left: _jsx("text", { fg: titleColor, children: fitBarLeading(scope.title, width, scope.detail) }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: scope.detail }) }));
+}
+function MessageLogHeader({ state, theme, width, }) {
+    const message = selectedMessage(state);
+    return (_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: message ? fitBarLeading(message.messageId, width) : "—" }), right: null }));
+}
+function FollowFooter({ state, theme }) {
+    return (_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "f follow" }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: state.view.followAgentLog ? "▼ following" : "▽ paused" }) }));
+}
+function StatusBar({ state, theme }) {
+    const broker = brokerIndicator(state.connection, theme);
+    return (_jsxs("box", { height: 1, flexShrink: 0, flexDirection: "row", paddingLeft: 1, paddingRight: 1, justifyContent: "space-between", children: [_jsx("text", { fg: theme.structure.emphasis, children: "pager" }), _jsx("box", { flexDirection: "row", children: _jsxs("text", { fg: theme.structure.rulesAndLabels, children: [_jsx("span", { fg: broker.color, children: broker.glyph }), " broker   ", `${String(state.unreadMessageIds.size)} unread   ${String(activeAgentCount(state))} agents`] }) })] }));
+}
+function PortraitStatusBar({ state, theme }) {
+    const broker = brokerIndicator(state.connection, theme);
+    return (_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: "pager" }), right: _jsxs("text", { fg: theme.structure.rulesAndLabels, children: [_jsx("span", { fg: broker.color, children: broker.glyph }), ` ${String(state.unreadMessageIds.size)} unread · ${String(activeAgentCount(state))} agents`] }) }));
+}
+const HELP_KEYS = [
+    ["↑↓", "move within the focused pane"],
+    ["←→", "move between panes"],
+    ["tab", "cycle panes"],
+    ["esc", "close an overlay, or go back"],
+    ["i", "agent identity"],
+    ["p", "ping the selected agent's inbox"],
+    ["a", "row actions"],
+    ["m", "operator actions"],
+    ["f", "follow the newest message"],
+    ["enter", "toggle a section, else go to the next pane"],
+    ["", "or, on the message pane, open the message"],
+    ["o", "open the full message"],
+    ["l", "open the diagnostics log"],
+    ["y", "copy raw, in the full message"],
+    ["q", "quit"],
+];
+function HelpOverlay({ theme }) {
+    return (_jsxs(Overlay, { theme: theme, width: 56, children: [_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: "keys" }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "esc" }) }), _jsx(Rule, { theme: theme }), _jsx("box", { flexDirection: "column", paddingLeft: 1, paddingRight: 1, children: HELP_KEYS.map(([key, description]) => (_jsx(Line, { children: _jsxs("text", { fg: theme.structure.bodyText, children: [_jsx("span", { fg: theme.structure.rulesAndLabels, children: key.padEnd(8) }), description] }) }, description))) })] }));
+}
+function stepFocus(model, direction, onCommand) {
+    const view = model.state.view;
+    if (view.overlay.kind !== "none")
+        return;
+    // The diagnostics pane is not focusable: it is read in the overlay the global key opens, so there
+    // is nothing below the last row to step into.
+    if (view.focus === "tree")
+        applyTreeStep(model, direction, onCommand);
+    else if (view.focus === "agent_log")
+        stepTuiTrafficSelection(model, direction);
+}
+function applyTreeStep(model, direction, onCommand) {
+    const before = model.state.view.selection;
+    const result = reduceAgentTreeKey(model.state, direction);
+    if (JSON.stringify(result.view.selection) === JSON.stringify(before))
+        return false;
+    executeAgentTreeResult(model, onCommand, result);
+    return true;
+}
+function DiagnosticsLog({ state, theme, width, }) {
+    const entries = state.diagnostics.slice(-COLLAPSED_LOG_ROWS);
+    return (_jsx("box", { flexDirection: "column", height: COLLAPSED_LOG_ROWS, flexShrink: 0, overflow: "hidden", paddingLeft: 1, paddingRight: 1, children: entries.length === 0 ? (_jsx(Line, { children: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "no diagnostics" }) })) : (entries.map((diagnostic, index) => (_jsx(Line, { children: _jsx("text", { fg: diagnosticColor(diagnostic.severity, theme), children: formatDiagnostic(diagnostic, width - 2) }) }, `${String(diagnostic.at)}-${String(index)}`)))) }));
+}
+function DiagnosticsOverlay({ state, theme }) {
+    return (_jsxs(Overlay, { theme: theme, width: DIAGNOSTICS_OVERLAY_COLUMNS, height: DIAGNOSTICS_OVERLAY_ROWS, children: [_jsx(PaneBar, { left: _jsx("text", { fg: theme.structure.emphasis, children: "log" }), right: _jsx("text", { fg: theme.structure.rulesAndLabels, children: "esc" }) }), _jsx(Rule, { theme: theme }), _jsx("scrollbox", { flexGrow: 1, focused: true, stickyScroll: true, stickyStart: "bottom", style: VERTICAL_SCROLL_STYLE, children: state.diagnostics.map((diagnostic, index) => (_jsx(Line, { children: _jsx("text", { fg: diagnosticColor(diagnostic.severity, theme), children: ` ${formatDiagnostic(diagnostic, DIAGNOSTICS_OVERLAY_COLUMNS - 3)}` }) }, `${String(diagnostic.at)}-${String(index)}`))) })] }));
+}
+const DIAGNOSTICS_OVERLAY_COLUMNS = 110;
+const DIAGNOSTICS_OVERLAY_ROWS = 24;
+/**
+ * Cover one pane rule with an invisible full-height strip that drags it.
+ *
+ * The rule sits inside the pane row and so cannot be grabbed level with the status bar above it. This
+ * strip spans the status bar and the pane row instead, stopping short of the window's own border and
+ * of the diagnostics log. It is declared after every pane because the hit grid is written in render
+ * order: an earlier sibling's cells are reclaimed by whatever draws over them.
+ * @param properties - Column the strip stands at, the drag handler given each pointer column, and the handler run when a drag ends.
+ * @returns One-column absolute box with no visible content, spanning the status bar and the pane row.
+ */
+function PaneGrabStrip({ left, onDrag, onSettle, }) {
+    return (_jsx("box", { position: "absolute", left: left, top: 0, bottom: COLLAPSED_LOG_ROWS, width: 1, onMouseDown: (event) => {
+            event.preventDefault();
+        }, onMouseDrag: (event) => {
+            onDrag(event.x);
+        }, onMouseDragEnd: () => {
+            onSettle();
+        } }));
+}
+function Divider({ theme, headerJunction }) {
+    // A bordered box would draw one character down its whole edge, overwriting each rule it crosses.
+    return (_jsxs("box", { width: 1, height: "100%", flexDirection: "column", children: [_jsx(DividerCell, { theme: theme, glyph: "\u252C" }), _jsx(DividerCell, { theme: theme, glyph: "\u2502" }), _jsx(DividerCell, { theme: theme, glyph: headerJunction }), _jsx("box", { flexGrow: 1, flexShrink: 1, border: ["left"], borderStyle: "single", borderColor: theme.structure.rulesAndLabels }), _jsx(DividerCell, { theme: theme, glyph: "\u253C" }), _jsx(DividerCell, { theme: theme, glyph: "\u2502" }), _jsx(DividerCell, { theme: theme, glyph: "\u2534" })] }));
+}
+function DividerCell({ theme, glyph }) {
+    return (_jsx("box", { height: 1, flexShrink: 0, children: _jsx("text", { fg: theme.structure.rulesAndLabels, children: glyph }) }));
+}
+function submitCommand(model, commands) {
+    return (command) => {
+        const report = (result) => {
+            const outcome = describeCommandOutcome(model.state, command, result);
+            model.reportDiagnostic(outcome.severity, "command", outcome.summary);
+        };
+        void model
+            .execute({
+            protocolVersion: OPERATOR_PROTOCOL_VERSION,
+            commandId: commands.commandId(),
+            issuedAt: commands.issuedAt(),
+            command,
+        })
+            .then((result) => {
+            report(result);
+            commands.observe(result);
+        }, () => {
+            report(null);
+        })
+            .catch(() => undefined);
+    };
+}

package/dist/src/tui/chrome.d.ts

@@ -0,0 +1,86 @@
+import { type ReactNode } from "react";
+import type { TuiOperatorModel, TuiOperatorModelState } from "./model.js";
+import type { TuiTheme } from "./theme.js";
+/**
+ * Subscribe a component to the model's immutable state.
+ * @param model - Renderer-independent state owner.
+ * @returns The current model state, re-rendering the caller on each transition.
+ */
+export declare function useTuiModel(model: TuiOperatorModel): TuiOperatorModelState;
+/**
+ * Options that let a ScrollBox measure the height it was actually given.
+ *
+ * Its viewport reserves a row for the horizontal scrollbar even while that bar is hidden, and its
+ * content is at least as tall as the ScrollBox. A vertical list that fits therefore reports exactly
+ * one row of overflow it does not have: the scrollbar draws, and a sticky-bottom list scrolls its
+ * first row out of sight. Hiding the horizontal scrollbar gives the row back. A headless-renderer
+ * test pins both the quirk and this workaround, and fails once the ScrollBox no longer has the quirk.
+ */
+export declare const VERTICAL_SCROLL_STYLE: Readonly<{
+    horizontalScrollbarOptions: Readonly<{
+        visible: false;
+    }>;
+}>;
+/**
+ * Columns a ScrollBox keeps for its vertical scrollbar, which it reserves whether or not the bar is
+ * drawn. Row content that must right-align against the pane edge has to subtract it.
+ */
+export declare const SCROLLBAR_RESERVED_COLUMNS = 1;
+/**
+ * Options for a ScrollBox holding text it word-wraps itself.
+ *
+ * Text wraps to the ScrollBox's full width while the vertical scrollbar draws over the last column,
+ * so a row that fills its width loses its final character under the bar. Padding the content by the
+ * scrollbar's columns wraps the text clear of it.
+ */
+export declare const WRAPPED_TEXT_SCROLL_STYLE: Readonly<{
+    contentOptions: Readonly<{
+        paddingRight: 1;
+    }>;
+    horizontalScrollbarOptions: Readonly<{
+        visible: false;
+    }>;
+}>;
+/**
+ * Draw one full-width horizontal rule occupying a single character row.
+ * @param properties - Semantic palette supplying the rule colour.
+ * @returns One rule row.
+ */
+export declare function Rule({ theme }: {
+    readonly theme: Readonly<TuiTheme>;
+}): ReactNode;
+/**
+ * Hold content to exactly one character row so stacked rows keep the grid.
+ * @param properties - Row content.
+ * @returns One fixed-height row.
+ */
+export declare function Line({ children }: {
+    readonly children?: ReactNode;
+}): ReactNode;
+/**
+ * Draw one header or footer row with its leading and trailing content pushed apart.
+ * @param properties - Row content for each edge; an absent edge keeps the row's height.
+ * @returns One inset bar row.
+ */
+export declare function PaneBar({ left, right }: {
+    readonly left: ReactNode;
+    readonly right: ReactNode;
+}): ReactNode;
+/**
+ * Report the columns an overlay occupies once it is fitted to the terminal.
+ * @param width - Columns the overlay asks for.
+ * @param terminalColumns - Columns the whole terminal has.
+ * @returns - Columns the overlay draws at, including its border.
+ */
+export declare function fitOverlayColumns(width: number, terminalColumns: number): number;
+/**
+ * Centre one bordered overlay over the panes it covers.
+ * @param properties - Palette, fixed overlay width, optional fixed height, and overlay content.
+ * @returns The overlay positioned at the terminal root.
+ */
+export declare function Overlay({ theme, width, height, children, }: {
+    readonly theme: Readonly<TuiTheme>;
+    readonly width: number;
+    readonly height?: number;
+    readonly children: ReactNode;
+}): ReactNode;

package/dist/src/tui/chrome.js

@@ -0,0 +1,85 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@opentui/react/jsx-runtime";
+import { useTerminalDimensions } from "@opentui/react";
+import { useSyncExternalStore } from "react";
+/**
+ * Subscribe a component to the model's immutable state.
+ * @param model - Renderer-independent state owner.
+ * @returns The current model state, re-rendering the caller on each transition.
+ */
+export function useTuiModel(model) {
+    return useSyncExternalStore(model.subscribe.bind(model), () => model.state, () => model.state);
+}
+/**
+ * Options that let a ScrollBox measure the height it was actually given.
+ *
+ * Its viewport reserves a row for the horizontal scrollbar even while that bar is hidden, and its
+ * content is at least as tall as the ScrollBox. A vertical list that fits therefore reports exactly
+ * one row of overflow it does not have: the scrollbar draws, and a sticky-bottom list scrolls its
+ * first row out of sight. Hiding the horizontal scrollbar gives the row back. A headless-renderer
+ * test pins both the quirk and this workaround, and fails once the ScrollBox no longer has the quirk.
+ */
+export const VERTICAL_SCROLL_STYLE = Object.freeze({
+    horizontalScrollbarOptions: Object.freeze({ visible: false }),
+});
+/**
+ * Columns a ScrollBox keeps for its vertical scrollbar, which it reserves whether or not the bar is
+ * drawn. Row content that must right-align against the pane edge has to subtract it.
+ */
+export const SCROLLBAR_RESERVED_COLUMNS = 1;
+/**
+ * Options for a ScrollBox holding text it word-wraps itself.
+ *
+ * Text wraps to the ScrollBox's full width while the vertical scrollbar draws over the last column,
+ * so a row that fills its width loses its final character under the bar. Padding the content by the
+ * scrollbar's columns wraps the text clear of it.
+ */
+export const WRAPPED_TEXT_SCROLL_STYLE = Object.freeze({
+    ...VERTICAL_SCROLL_STYLE,
+    contentOptions: Object.freeze({ paddingRight: SCROLLBAR_RESERVED_COLUMNS }),
+});
+/** Narrowest overlay that still reads as a panel rather than a fragment. */
+const MINIMUM_OVERLAY_COLUMNS = 20;
+/**
+ * Draw one full-width horizontal rule occupying a single character row.
+ * @param properties - Semantic palette supplying the rule colour.
+ * @returns One rule row.
+ */
+export function Rule({ theme }) {
+    return (_jsx("box", { height: 1, flexShrink: 0, border: ["top"], borderStyle: "single", borderColor: theme.structure.rulesAndLabels }));
+}
+/**
+ * Hold content to exactly one character row so stacked rows keep the grid.
+ * @param properties - Row content.
+ * @returns One fixed-height row.
+ */
+export function Line({ children }) {
+    return (_jsx("box", { height: 1, flexShrink: 0, children: children }));
+}
+/**
+ * Draw one header or footer row with its leading and trailing content pushed apart.
+ * @param properties - Row content for each edge; an absent edge keeps the row's height.
+ * @returns One inset bar row.
+ */
+export function PaneBar({ left, right }) {
+    return (_jsxs("box", { height: 1, flexShrink: 0, flexDirection: "row", paddingLeft: 1, paddingRight: 1, justifyContent: "space-between", children: [left ?? _jsx("text", { children: " " }), right ?? _jsx("text", { children: " " })] }));
+}
+/**
+ * Report the columns an overlay occupies once it is fitted to the terminal.
+ * @param width - Columns the overlay asks for.
+ * @param terminalColumns - Columns the whole terminal has.
+ * @returns - Columns the overlay draws at, including its border.
+ */
+export function fitOverlayColumns(width, terminalColumns) {
+    return Math.min(width, Math.max(MINIMUM_OVERLAY_COLUMNS, terminalColumns - 2));
+}
+/**
+ * Centre one bordered overlay over the panes it covers.
+ * @param properties - Palette, fixed overlay width, optional fixed height, and overlay content.
+ * @returns The overlay positioned at the terminal root.
+ */
+export function Overlay({ theme, width, height, children, }) {
+    const terminal = useTerminalDimensions();
+    const fitted = fitOverlayColumns(width, terminal.width);
+    const fittedHeight = height === undefined ? undefined : Math.min(height, Math.max(3, terminal.height - 2));
+    return (_jsx("box", { position: "absolute", left: 0, top: 0, width: "100%", height: "100%", justifyContent: "center", alignItems: "center", children: _jsx("box", { width: fitted, ...(fittedHeight === undefined ? {} : { height: fittedHeight }), border: true, borderStyle: "single", borderColor: theme.structure.rulesAndLabels, flexDirection: "column", backgroundColor: theme.structure.background, children: children }) }));
+}

package/dist/src/tui/client.d.ts

@@ -0,0 +1,41 @@
+import { type OperatorCommandEnvelope, type OperatorCommandResult, type OperatorCursor } from "../operator/protocol.js";
+import type { TuiRequest, TuiStreamObservation } from "./model.js";
+/** Owns one cancellable loopback NDJSON session and exposes only model-guarded stream callbacks. */
+export declare class TuiOperatorTcpClient {
+    #private;
+    private readonly url;
+    /**
+     * Construct a client for the published numeric loopback TCP endpoint. No connection opens until a fetch or open.
+     * @param url - Operator endpoint the broker published, naming a numeric loopback host and port.
+     */
+    constructor(url: string);
+    /**
+     * Open cold hydration and resolve exactly one authoritative snapshot.
+     * @returns Snapshot request; cancelling it resets the session, and a second fetch while one is pending rejects.
+     */
+    fetch(): TuiRequest<unknown>;
+    /**
+     * Attach the model-owned ordered callback, opening a resumed session when no socket is live.
+     *
+     * After hydration the session opened by `fetch` is already subscribed, and the cursor it was
+     * subscribed at is the one the caller now holds. Only a caller resuming without hydrating first
+     * reaches the connect below, and the cursor it supplies is what makes the server replay rather
+     * than transfer a whole snapshot.
+     * @param cursor - Position the caller already holds, or null when it holds no snapshot.
+     * @param receive - Receives each validated observation in stream order, including any buffered before this call.
+     * @param unavailable - Called once when the session fails; a failure recorded before this call is reported on the next microtask.
+     * @returns Cancellation callback for this stream generation.
+     */
+    open(cursor: OperatorCursor | null, receive: (observation: TuiStreamObservation) => void, unavailable: () => void): () => void;
+    /** Reset the current session. */
+    reconnect(): void;
+    /**
+     * Submit one correlated non-authoritative command.
+     * @param command - Validated command envelope, correlated with its result by `commandId`.
+     * @returns Command request; it rejects at once without a live session, while hydration is pending, when
+     * too many commands are pending, or for a duplicate `commandId`, and rejects later if the session resets.
+     */
+    execute(command: OperatorCommandEnvelope): TuiRequest<OperatorCommandResult>;
+    /** Release socket, input buffers, and all pending work exactly once. */
+    dispose(): void;
+}