@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/ui/layout/ScrollViewport.js

@@ -0,0 +1,222 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { Box, measureElement, useStdout } from 'ink';
+import { createScrollbarController } from '../scrollbar-controller.js';
+import { ViewportGeometryContext } from './viewport-geometry.js';
+import { applyScrollTimes } from './scroll.js';
+import { reduceFollow, shouldArmResume } from './follow-state.js';
+import { thumbRange } from './scroll-indicator.js';
+import { ScrollIndicator } from './ScrollIndicator.js';
+import { buildDocumentLayout } from './document-layout.js';
+/**
+ * Whether `element` lies fully inside `clip`. A missing element (not mounted) or
+ * clip reports `true`, so a caller that consumes the answer must first know the
+ * element is actually mounted. Rows are one line tall, so "partially visible"
+ * cannot occur for the run status row.
+ */
+function elementVisible(element, clip) {
+    if (!element || !clip)
+        return true;
+    let top = 0;
+    let current = element;
+    while (current && current !== clip) {
+        top += current.yogaNode?.getComputedTop() ?? 0;
+        current = current.parentNode;
+    }
+    return current === clip && top >= 0 &&
+        top + measureElement(element).height <= measureElement(clip).height;
+}
+/** One offset for messages, padding and panels; hidden trees keep their local state. */
+export function ScrollViewport(props) {
+    const { stdout } = useStdout();
+    const { active = true, hold = false, resumeMs = 0, scrollbar } = props;
+    const cols = props.cols ?? stdout?.columns ?? 80;
+    const clipRef = useRef(null);
+    const bodyRef = useRef(null);
+    const footerRef = useRef(null);
+    const [{ metrics, offset }, setGeometry] = useState({
+        metrics: { viewport: 0, content: 0, padding: 0, footer: 0 }, offset: 0,
+    });
+    const pendingMetrics = useRef(metrics);
+    const geometryScheduled = useRef(false);
+    const mounted = useRef(true);
+    const [dragging, setDragging] = useState(false);
+    const offsetRef = useRef(0);
+    const baseline = useRef(null);
+    const latest = useRef({ active, hold, resumeMs, metrics, scrollbar });
+    latest.current = { active, hold, resumeMs, metrics, scrollbar };
+    const pausedLines = useRef(0);
+    const resumeTimer = useRef(null);
+    const lastIntent = useRef(props.intent?.nonce);
+    const lastPin = useRef(props.pinToBottomNonce);
+    const lastReset = useRef(props.resetKey);
+    const lastVisible = useRef();
+    const lastActivityVisible = useRef();
+    const previousActive = useRef(active);
+    const geometryRevision = useRef(0);
+    const geometryBounds = useRef('');
+    const lastGeometryKey = useRef(props.geometryKey);
+    const clearResume = useCallback(() => {
+        if (resumeTimer.current)
+            clearTimeout(resumeTimer.current);
+        resumeTimer.current = null;
+    }, []);
+    const publishGeometry = useCallback(() => {
+        if (geometryScheduled.current)
+            return;
+        geometryScheduled.current = true;
+        queueMicrotask(() => {
+            geometryScheduled.current = false;
+            if (!mounted.current)
+                return;
+            const nextMetrics = pendingMetrics.current;
+            const nextOffset = offsetRef.current;
+            setGeometry((previous) => previous.offset === nextOffset &&
+                Object.keys(nextMetrics).every((key) => previous.metrics[key] ===
+                    nextMetrics[key])
+                ? previous : { metrics: nextMetrics, offset: nextOffset });
+        });
+    }, []);
+    const publishOffset = useCallback((next) => {
+        offsetRef.current = next;
+        if (next === 0)
+            pausedLines.current = 0;
+        publishGeometry();
+    }, [publishGeometry]);
+    const isHeld = useCallback(() => latest.current.hold ||
+        !!latest.current.scrollbar?.controller?.isCaptured(), []);
+    const armResume = useCallback(() => {
+        clearResume();
+        const current = latest.current;
+        if (!current.active || !shouldArmResume({ resumeMs: current.resumeMs,
+            offset: offsetRef.current, newLinesWhilePaused: pausedLines.current, hold: isHeld() }))
+            return;
+        resumeTimer.current = setTimeout(() => {
+            resumeTimer.current = null;
+            if (latest.current.active && !isHeld())
+                publishOffset(0);
+        }, current.resumeMs);
+        resumeTimer.current.unref?.();
+    }, [clearResume, isHeld, publishOffset]);
+    useLayoutEffect(() => {
+        if (!scrollbar)
+            return;
+        const controller = createScrollbarController({
+            getGeometry: () => scrollbar.geometry,
+            isEnabled: () => latest.current.active && scrollbar.frameReady && scrollbar.isEnabled(),
+            setOffset: (next) => { publishOffset(next); armResume(); },
+            page: (kind) => {
+                publishOffset(applyScrollTimes({ offset: offsetRef.current }, kind, latest.current.metrics, 1).offset);
+            },
+            onStart: () => { clearResume(); scrollbar.onStart?.(); },
+            onHold: (held) => { setDragging(held); armResume(); },
+        });
+        scrollbar.controller = controller;
+        return () => {
+            controller.dispose();
+            scrollbar.controller = null;
+            scrollbar.geometry = null;
+            scrollbar.invalidate();
+        };
+    }, [scrollbar, publishOffset, armResume, clearResume]);
+    useEffect(() => clearResume, [clearResume]);
+    useLayoutEffect(() => {
+        mounted.current = true;
+        return () => { mounted.current = false; };
+    }, []);
+    useEffect(() => { armResume(); }, [hold, resumeMs, armResume]);
+    useLayoutEffect(() => {
+        if (lastGeometryKey.current !== props.geometryKey) {
+            props.onGeometryChange?.();
+            scrollbar?.controller?.cancel();
+            scrollbar?.invalidate();
+            geometryRevision.current++;
+            lastGeometryKey.current = props.geometryKey;
+        }
+        const reset = lastReset.current !== props.resetKey;
+        lastReset.current = props.resetKey;
+        const pin = lastPin.current !== props.pinToBottomNonce;
+        lastPin.current = props.pinToBottomNonce;
+        const intent = lastIntent.current !== props.intent?.nonce ? props.intent : undefined;
+        lastIntent.current = props.intent?.nonce;
+        if (reset) {
+            baseline.current = null;
+            pausedLines.current = 0;
+            publishOffset(0);
+            scrollbar?.controller?.cancel();
+        }
+        if (!active) {
+            clearResume();
+            scrollbar?.invalidate();
+            if (scrollbar)
+                scrollbar.geometry = null;
+            previousActive.current = false;
+            return;
+        }
+        const viewport = clipRef.current ? measureElement(clipRef.current).height : 0;
+        const body = bodyRef.current ? measureElement(bodyRef.current).height : 0;
+        const footer = footerRef.current ? measureElement(footerRef.current).height : 0;
+        const layout = buildDocumentLayout({ viewportRows: viewport, bodyRows: body, footerRows: footer });
+        const padding = props.footer === undefined ? 0 : layout.paddingRows;
+        const content = body + footer + padding;
+        const tail = props.tailRowsRef?.current.rows ?? 0;
+        const old = baseline.current;
+        const reflow = !old || old.cols !== cols || old.viewport !== viewport;
+        const tailDelta = reflow ? 0 : tail - old.tail;
+        const footerDelta = reflow ? 0 : footer - old.footer;
+        const paddingDelta = !old || reflow || props.footer === undefined ? 0 :
+            Math.max(0, viewport - old.body - old.footer - tailDelta - footerDelta) - old.padding;
+        const nextMetrics = { viewport, content, padding, footer };
+        latest.current.metrics = nextMetrics;
+        // Markdown estimates may take more than 50 measurements to converge in a
+        // tall viewport. Publishing during the layout commit recursively mounts
+        // another window before the height store's microtask can finish. Coalesce
+        // geometry with that store outside the commit; keep measuring every frame.
+        // Offset clamps must join the same publication: at the top, each corrected
+        // estimate shrinks the overflow and would otherwise recurse via setOffset.
+        pendingMetrics.current = nextMetrics;
+        publishGeometry();
+        const followed = reduceFollow({ offset: offsetRef.current,
+            overflowLines: Math.max(0, content - viewport), tailDelta,
+            layoutTailDelta: footerDelta + paddingDelta, hold: isHeld(),
+            newLinesWhilePaused: pausedLines.current });
+        pausedLines.current = followed.newLinesWhilePaused;
+        let next = pin || reset ? 0 : followed.offset;
+        if (!pin && intent)
+            next = applyScrollTimes({ offset: next }, intent.kind, nextMetrics, intent.repeat ?? 1).offset;
+        publishOffset(next);
+        baseline.current = { viewport, content, body, footer, padding, cols, tail };
+        if (tailDelta !== 0 || pin || intent || !previousActive.current)
+            armResume();
+        previousActive.current = true;
+        const bounds = `${cols}:${stdout?.columns}:${stdout?.rows}:${viewport}`;
+        if (bounds !== geometryBounds.current) {
+            geometryBounds.current = bounds;
+            geometryRevision.current++;
+            scrollbar?.invalidate();
+        }
+        if (scrollbar) {
+            scrollbar.geometry = { trackTop: 2, trackCol: stdout?.columns ?? cols,
+                trackRows: viewport, contentRows: content, offset: next,
+                thumb: thumbRange(viewport, content, next, true), revision: geometryRevision.current };
+            scrollbar.onGeometry?.();
+        }
+        const visible = elementVisible(props.composerRef?.current ?? null, clipRef.current);
+        if (lastVisible.current !== visible) {
+            lastVisible.current = visible;
+            props.onComposerVisibilityChange?.(visible);
+        }
+        const activityVisible = elementVisible(props.activityRef?.current ?? null, clipRef.current);
+        if (lastActivityVisible.current !== activityVisible) {
+            lastActivityVisible.current = activityVisible;
+            props.onActivityVisibilityChange?.(activityVisible);
+        }
+    });
+    const shiftUp = Math.max(0, metrics.content - metrics.viewport - offset);
+    useEffect(() => { props.onScrolledLinesChange?.(offset); }, [offset, props.onScrolledLinesChange]);
+    useEffect(() => { if (active)
+        props.onViewportShiftChange?.(shiftUp); }, [active, shiftUp, props.onViewportShiftChange]);
+    const geometry = useMemo(() => ({ viewportRows: metrics.viewport, offset,
+        contentRows: metrics.content, trailingContentRows: metrics.padding + metrics.footer }), [metrics, offset]);
+    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsxs(Box, { display: active ? 'flex' : 'none', flexDirection: "row", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: [_jsx(Box, { ref: clipRef, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: _jsxs(Box, { flexDirection: "column", flexShrink: 0, marginTop: -shiftUp, children: [_jsx(ViewportGeometryContext.Provider, { value: geometry, children: _jsx(Box, { ref: bodyRef, flexDirection: "column", flexShrink: 0, children: props.children }) }), _jsx(Box, { height: metrics.padding, flexShrink: 0 }), _jsx(Box, { ref: footerRef, flexDirection: "column", flexShrink: 0, children: props.footer })] }) }), props.rail, props.showScrollIndicator && _jsx(ScrollIndicator, { rows: metrics.viewport, thumb: thumbRange(metrics.viewport, metrics.content, offset, true), dragging: dragging, theme: props.theme, caps: props.caps })] }), _jsx(Box, { display: active ? 'none' : 'flex', flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: props.overlay ?? null })] }));
+}

package/dist/ui/layout/agents-board.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The Agents board's row model — pure projection, no Ink (tui-subagent-panel §4.4 / §7).
+ *
+ * WHY A PURE MODULE AND NOT JSX. The board's whole value is that it shows EVERY fact
+ * about every child, and the two things that can go wrong with that are both
+ * properties of a list: a row wider than the overlay (which silently desynchronises
+ * `OverlayFrame`'s position indicator) and a row count that grows without a bound.
+ * Both are assertable here, against plain strings, without a terminal - which is the
+ * same reason `layout/team-panel.ts` and `layout/budget.ts` are separate modules.
+ *
+ * LIVE-ONLY RULE (§4.4.2, RV-P0-2). The board has two sources with DIFFERENT fields:
+ * a live `TeamSnapshot` (has `messageCount`, `startedAt`, the activity prose and the
+ * timeline) and a settled `kind: 'team'` entry (has `durationMs` and the runs, and
+ * nothing else - `agent/reducer.ts`'s entry member carries no `messageCount` and no
+ * `startedAt`). A section whose source is missing is OMITTED, never filled with a
+ * zero: `mail 0` would be a lie, and an empty section title tells the reader nothing.
+ * The one section that survives both sources is `result` (`summary` / `error` is
+ * never stripped), which is precisely the fact a user opens the board to find.
+ *
+ * ASCII ONLY: `src/ui/**` is inside `glyphs.test.ts`'s static scan, so every symbol
+ * (the ellipsis, the separator, the cursor) arrives through `glyphs`.
+ */
+import type { Entry } from '../../model/agent/reducer.js';
+import type { SubagentRun, TeamSnapshot } from '../../model/team/types.js';
+import type { Glyphs } from '../glyphs.js';
+export type BoardRowKind = 'summary' | 'blank' | 'section' | 'child' | 'field' | 'event' | 'hint';
+/** Which palette slot a row draws with. Mapped to `Theme` one level up, in the component. */
+export type BoardTone = 'accent' | 'primary' | 'muted' | 'warn' | 'error' | 'done' | 'hint';
+export interface BoardRow {
+    /** React key: stable and unique (`kind:subject:index`). */
+    key: string;
+    kind: BoardRowKind;
+    /** One already-folded line, safe to hand to `<Text wrap="truncate">`. */
+    text: string;
+    tone: BoardTone;
+    selected?: boolean;
+}
+export interface BoardSource {
+    dispatchId: string;
+    active: boolean;
+    /**
+     * When the dispatch started. **A settled `team` entry has no such field**
+     * (`agent/reducer.ts`'s entry member), so it is optional: with no `startedAt` the
+     * summary shows `durationMs` alone rather than inventing an absolute instant.
+     */
+    startedAt?: number;
+    endedAt?: number;
+    requested: number;
+    runs: readonly SubagentRun[];
+    /**
+     * Team-mail count. Live snapshots carry it; a settled entry does **not** - absent
+     * means the clause is omitted rather than rendered as `mail 0` (RV-P0-2).
+     */
+    messageCount?: number;
+    /** A settled entry's own total (`teamEnd` writes it). */
+    durationMs?: number;
+}
+/**
+ * The board's single source shape, resolved in ONE place.
+ *
+ * PRIORITY: live snapshot > (the component's frozen copy) > the most recent settled
+ * entry. This function answers the first and the third; the frozen copy belongs to
+ * the component because it only exists while a dispatch is being read (§4.4.5).
+ */
+export declare function resolveBoardSource(input: {
+    team: TeamSnapshot | null;
+    entries: readonly Entry[];
+}): BoardSource | null;
+/**
+ * The child the board is showing, resolved from its LABEL every frame (D-8).
+ *
+ * Labels are the only stable handle: `panel-rows.ts` re-sorts the roster by phase, so
+ * an index would silently jump to a different child the moment one of them settles.
+ * Fallback order is "the first running child, else the first child", which is the
+ * one a reader opening the board mid-dispatch wants.
+ */
+export declare function resolveSelection(runs: readonly SubagentRun[], label: string | null): SubagentRun | null;
+export interface AgentBoardInput {
+    source: BoardSource;
+    /** Overlay content width. */
+    cols: number;
+    now: number;
+    selectedLabel: string | null;
+    glyphs: Glyphs;
+    native: boolean;
+}
+/**
+ * The board's rows, in the order a reader wants them: what the dispatch did, then who
+ * is in it, then everything about the selected child, then its history.
+ *
+ * Bounded by `TEAM_LIMITS.boardMaxRows`, and the truncation is ANNOUNCED rather than
+ * silent - a list that stops mid-fact with no notice reads as a rendering bug.
+ */
+export declare function buildAgentBoardRows(input: AgentBoardInput): BoardRow[];
+/**
+ * The facts, in a FIXED order, and with the zero-valued ones ABSENT.
+ *
+ * `supervisor` / `retries` / `compactions` / `truncated` only appear when they carry a
+ * fact; a row reading `supervisor  0` teaches a reader nothing and pushes the section
+ * a row down for every child that was never touched.
+ */
+export declare function factPairs(run: SubagentRun, glyphs: Glyphs): [string, string][];