@visual-z/xeno 0.2.0 → 0.3.0

package/src/tui/ui/screen.ts

@@ -0,0 +1,421 @@
+/**
+ * The whole view, assembled (docs/tasks/refactor-tui-dock-layout.md).
+ *
+ *   ┌ top bar (topbar tier) ───────────────────────────┐┌ sidebar ┐
+ *   │ greeting (empty session, no draft)               ││ (≥ 110  │
+ *   │ transcript (bottom-sticky)          ↓ 3 new      ││  cols)  │
+ *   │ completion · queue · attachments · widgets       ││         │
+ *   │ ╭─ transient: activity / dialog title ───────╮   ││         │
+ *   │ │ › draft, or the open dialog                │   ││         │
+ *   │ ╰─ model · thinking ──────────── ctx ~12% ───╯   ││         │
+ *   └──────────────────────────────────────────────────┘└─────────┘
+ *
+ * The input box is the one fixed point: its bottom edge is always the last
+ * row and it only grows upward. Status has exactly one place per width tier
+ * (layout.ts). Chrome is drawn by Canvas renderables, so the activity clock
+ * repaints cells without touching layout.
+ *
+ * One screen owns the renderer's tree, the dialog host and the editor; the
+ * app controller feeds it data and handles keys.
+ */
+import { BoxRenderable, type CliRenderer } from "@opentui/core";
+import { Canvas } from "./canvas.ts";
+import type { UiColors } from "./colors.ts";
+import { Composer, draftMaxLines } from "./composer.ts";
+import { DialogHost } from "./dialog.ts";
+import { clipSegs, edgeLine, segsWidth, type Label, type Seg } from "./edge.ts";
+import type { Bindings } from "./keys.ts";
+import { screenLayout, type ScreenLayout } from "./layout.ts";
+import { greetingLines, mascotFrame, MASCOT_FRAME_MS, MASCOT_FRAMES, type Greeting } from "./mascot.ts";
+import { MessageList, type MessageFeatures } from "./messages.ts";
+import { Motion } from "./motion.ts";
+import { contextLabel, sidebarLines, topbarRow, type Line, type StatusModel } from "./status.ts";
+import { DEFAULT_CELL, stripImageRows } from "./image-size.ts";
+import { Pictures, type PictureSource } from "./pictures.ts";
+import type { ImageView, ViewItem } from "./items.ts";
+
+export interface DockState {
+  /** Model display name. */
+  readonly model: string;
+  readonly thinking: string;
+  readonly busy: boolean;
+  /** What the running turn is doing: "thinking", "streaming", "running command"… */
+  readonly activity: string;
+}
+
+type Tone = "info" | "success" | "warning" | "error";
+
+/** Braille spinner, ten frames. */
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+/** Spinner cadence: Codex and the research recommendation both use about 100 ms. */
+const ACTIVITY_MS = 100;
+/**
+ * After this long without a stream event the spinner slows to IDLE_ACTIVITY_MS:
+ * a turn waiting on a slow tool still shows it is alive, at a fifth of the
+ * wakeups (OpenCode #42306 measured a full core spent on a fast spinner).
+ */
+const QUIET_AFTER_MS = 2000;
+const IDLE_ACTIVITY_MS = 500;
+/** How long a transient message stays on the box edge. Assumed. */
+const TOAST_MS = 2500;
+/** Rows the transcript keeps even when the box grows (a picker never hides everything above it). Assumed. */
+const MIN_TRANSCRIPT_ROWS = 3;
+/** Completion rows above the box at most. Assumed. */
+const COMPLETION_ROWS = 6;
+/** Below this height the greeting would crowd the transcript; it stays hidden. Assumed. */
+const GREETING_MIN_ROWS = 14;
+
+export class Screen {
+  readonly renderer: CliRenderer;
+  readonly messages: MessageList;
+  readonly composer: Composer;
+  readonly dialogs: DialogHost;
+  private colors: UiColors;
+  private readonly topbar: Canvas;
+  private readonly greeting: Canvas;
+  private readonly pill: Canvas;
+  private readonly above: BoxRenderable;
+  private readonly completion: Canvas;
+  private readonly queueRows: Canvas;
+  private readonly widgetRows: Canvas;
+  private readonly dock: BoxRenderable;
+  private readonly body: BoxRenderable;
+  private readonly topEdge: Canvas;
+  private readonly bottomEdge: Canvas;
+  private readonly sidebar: BoxRenderable;
+  private readonly sidebarRows: Canvas;
+  private shape: ScreenLayout;
+  private sidebarWanted = true;
+  private status: StatusModel | undefined;
+  private dockState: DockState = { model: "", thinking: "", busy: false, activity: "" };
+  private home: Greeting | undefined;
+  private greetingPlayed = false;
+  private greetingFrame = MASCOT_FRAMES;
+  private readonly entrance = new Motion();
+  private readonly activity = new Motion();
+  private spin = 0;
+  private busySince = 0;
+  private lastEvent = 0;
+  private activityMs = ACTIVITY_MS;
+  private animations = true;
+  private focused = true;
+  private toastText: { text: string; tone: Tone } | undefined;
+  private toastTimer: ReturnType<typeof setTimeout> | undefined;
+  private queue: readonly string[] = [];
+  private attachmentImages: readonly ImageView[] = [];
+  private attachmentsKey = "";
+  private picturesSource: PictureSource = { mode: "chip", protocol: "blocks", cell: DEFAULT_CELL, widthCells: 60, load: async () => null };
+  private readonly attachments: BoxRenderable;
+  private widgets: readonly string[] = [];
+  private unread = 0;
+  private readonly glyph = () => this.activity.running ? SPINNER[this.spin % SPINNER.length]! : "●";
+
+  constructor(renderer: CliRenderer, colors: UiColors, bindings: () => Bindings, features: MessageFeatures = {}) {
+    this.renderer = renderer;
+    this.colors = colors;
+    renderer.setBackgroundColor(colors.background);
+    this.shape = screenLayout(renderer.width, renderer.height, true);
+    const root = new BoxRenderable(renderer, { id: "root", flexDirection: "column", width: "100%", height: "100%" });
+    this.topbar = new Canvas(renderer, { id: "topbar", height: 1, flexShrink: 0, marginLeft: 1, marginRight: 1, colors });
+    const middle = new BoxRenderable(renderer, { id: "middle", flexDirection: "row", flexGrow: 1, flexShrink: 1 });
+    const main = new BoxRenderable(renderer, { id: "main", flexDirection: "column", flexGrow: 1, flexShrink: 1 });
+    this.greeting = new Canvas(renderer, { id: "greeting", height: 3, flexShrink: 0, marginTop: 1, marginLeft: 3, marginBottom: 1, colors });
+    const area = new BoxRenderable(renderer, { id: "messages-area", flexDirection: "column", flexGrow: 1, flexShrink: 1 });
+    this.messages = new MessageList(renderer, colors, features, this.glyph);
+    area.add(this.messages.scroll);
+    this.pill = new Canvas(renderer, { id: "pill", position: "absolute", zIndex: 40, visible: false, height: 1, width: 1, bottom: 0, right: 3, colors });
+    area.add(this.pill);
+    this.above = new BoxRenderable(renderer, { id: "above-dock", flexDirection: "column", flexShrink: 0, marginLeft: 3, marginRight: 3 });
+    this.completion = new Canvas(renderer, { id: "completion", visible: false, height: 1, flexShrink: 0, colors });
+    this.queueRows = new Canvas(renderer, { id: "queue", visible: false, height: 1, flexShrink: 0, colors });
+    this.widgetRows = new Canvas(renderer, { id: "widgets", visible: false, height: 1, flexShrink: 0, colors });
+    this.attachments = new BoxRenderable(renderer, { id: "attachments", flexDirection: "column", flexShrink: 0, visible: false });
+    this.above.add(this.widgetRows); this.above.add(this.attachments); this.above.add(this.queueRows); this.above.add(this.completion);
+    this.dock = new BoxRenderable(renderer, { id: "dock", flexDirection: "column", flexShrink: 0, marginLeft: 1, marginRight: 1 });
+    this.topEdge = new Canvas(renderer, { id: "dock-top", height: 1, flexShrink: 0, colors, glyph: this.glyph });
+    this.body = new BoxRenderable(renderer, { id: "dock-body", flexDirection: "column", flexShrink: 0, border: ["left", "right"], borderStyle: "rounded", borderColor: colors.edge, paddingLeft: 1, paddingRight: 1 });
+    const slot = new BoxRenderable(renderer, { id: "dialog", flexDirection: "column", flexShrink: 0, visible: false });
+    this.composer = new Composer(renderer, colors);
+    this.body.add(slot); this.body.add(this.composer.row);
+    this.bottomEdge = new Canvas(renderer, { id: "dock-bottom", height: 1, flexShrink: 0, colors });
+    this.dock.add(this.topEdge); this.dock.add(this.body); this.dock.add(this.bottomEdge);
+    main.add(this.greeting); main.add(area); main.add(this.above); main.add(this.dock);
+    this.sidebar = new BoxRenderable(renderer, { id: "sidebar", flexShrink: 0, border: ["left"], borderColor: colors.line, paddingLeft: 1, paddingRight: 1, paddingTop: 1, flexDirection: "column" });
+    this.sidebarRows = new Canvas(renderer, { id: "sidebar-rows", flexGrow: 1, colors });
+    this.sidebar.add(this.sidebarRows);
+    middle.add(main); middle.add(this.sidebar);
+    root.add(this.topbar); root.add(middle);
+    renderer.root.add(root);
+    this.dialogs = new DialogHost(renderer, colors, bindings, slot, () => this.dialogRows(), this.glyph);
+    this.dialogs.onOpened = () => { this.composer.setCompletion(undefined); this.composer.area.blur(); this.composer.row.visible = false; this.paintAttachments(); this.layout(); };
+    this.dialogs.onClosed = () => { this.composer.row.visible = true; this.paintAttachments(); this.layout(); this.composer.focus(); };
+    this.dialogs.onChrome = () => { this.paintEdges(); this.syncActivity(); };
+    this.composer.onResize = () => this.paintAbove();
+    this.composer.onOverflow = () => this.paintEdges();
+    this.composer.onChange = () => this.paintGreeting();
+    this.messages.onUnread = count => { this.unread = count; this.paintPill(); };
+    renderer.on("resize", () => this.layout());
+    renderer.on("blur", () => { this.focused = false; this.finishEntrance(); });
+    renderer.on("focus", () => { this.focused = true; });
+    this.layout();
+    this.composer.focus();
+  }
+
+  get width(): number { return this.renderer.width; }
+  get tier(): ScreenLayout["tier"] { return this.shape.tier; }
+  get sidebarVisible(): boolean { return this.shape.tier === "sidebar"; }
+  /** An empty session (the greeting may still be hidden by a draft). */
+  get homeVisible(): boolean { return this.home !== undefined; }
+  get greetingVisible(): boolean { return this.greeting.visible; }
+  get animating(): boolean { return this.activity.running || this.entrance.running; }
+  /** Live timers owned by the view: none while idle (DoD 9). */
+  get timers(): number { return (this.activity.running ? 1 : 0) + (this.entrance.running ? 1 : 0) + (this.toastTimer ? 1 : 0); }
+  /** Plain text of the box edges and status surfaces (tests). */
+  get chrome(): { top: string; bottom: string; topbar: string; sidebar: string; greeting: string; completion: string } {
+    return { top: this.topEdge.text, bottom: this.bottomEdge.text, topbar: this.topbar.visible ? this.topbar.text : "", sidebar: this.sidebar.visible ? this.sidebarRows.text : "",
+      greeting: this.greeting.visible ? this.greeting.text : "", completion: this.completion.visible ? this.completion.text : "" };
+  }
+  /** The box's outer rows, for layout tests. */
+  get dockBox(): BoxRenderable { return this.dock; }
+
+  // -------------------------------------------------------------- appearance
+  setColors(colors: UiColors): void {
+    this.colors = colors;
+    this.renderer.setBackgroundColor(colors.background);
+    for (const canvas of [this.topbar, this.greeting, this.pill, this.completion, this.queueRows, this.widgetRows, this.topEdge, this.bottomEdge, this.sidebarRows]) canvas.setColors(colors);
+    this.sidebar.borderColor = colors.line;
+    this.messages.setColors(colors);
+    this.composer.setColors(colors);
+    this.dialogs.setColors(colors);
+    this.paintEdges();
+  }
+
+  setAnimations(enabled: boolean): void {
+    if (enabled === this.animations) return;
+    this.animations = enabled;
+    if (!enabled) this.finishEntrance();
+    this.syncActivity();
+  }
+
+  toggleSidebar(): void { this.sidebarWanted = !this.sidebarWanted; this.layout(); }
+
+  // ------------------------------------------------------------------ layout
+  private layout(): void {
+    const w = this.renderer.width, h = this.renderer.height;
+    this.shape = screenLayout(w, h, this.sidebarWanted);
+    this.topbar.visible = this.shape.topbar;
+    this.sidebar.visible = this.shape.tier === "sidebar";
+    if (this.sidebar.visible) this.sidebar.width = this.shape.sidebarWidth;
+    // The draft may grow while the transcript keeps its minimum and the box keeps its edges.
+    this.composer.setMaxLines(Math.min(draftMaxLines(h), h - (this.shape.topbar ? 1 : 0) - 2 - MIN_TRANSCRIPT_ROWS - this.aboveRows()));
+    this.dialogs.layout();
+    this.paintStatus();
+    this.paintEdges();
+    this.paintAbove();
+    this.paintGreeting();
+    this.renderer.requestRender();
+  }
+
+  /** Rows a dialog may use inside the box. */
+  private dialogRows(): number {
+    return Math.max(1, this.renderer.height - (this.shape.topbar ? 1 : 0) - 2 - MIN_TRANSCRIPT_ROWS);
+  }
+
+  private aboveRows(): number {
+    return (this.completion.visible ? this.completion.height as number : 0) + (this.queueRows.visible ? this.queueRows.height as number : 0) + (this.widgetRows.visible ? this.widgetRows.height as number : 0)
+      + (this.attachments.visible ? this.attachments.height : 0);
+  }
+
+  // ------------------------------------------------------------------ status
+  setStatus(model: StatusModel): void { this.status = model; this.paintStatus(); this.paintEdges(); }
+
+  private paintStatus(): void {
+    const model = this.status;
+    if (!model) return;
+    if (this.topbar.visible) this.topbar.setRows([topbarRow(model, Math.max(1, this.renderer.width - 2))]);
+    if (this.sidebar.visible) {
+      const width = Math.max(1, this.shape.sidebarWidth - 3);
+      this.sidebarRows.setRows(sidebarLines(model, width, Math.max(0, this.renderer.height - 1)));
+    }
+  }
+
+  // -------------------------------------------------------------------- dock
+  setDock(state: DockState): void {
+    const wasBusy = this.dockState.busy;
+    this.dockState = state;
+    if (state.busy && !wasBusy) this.busySince = Date.now();
+    this.syncActivity();
+    this.paintEdges();
+  }
+
+  toast(text: string, tone: Tone = "info"): void {
+    this.toastText = { text, tone };
+    clearTimeout(this.toastTimer);
+    this.toastTimer = setTimeout(() => { this.toastTimer = undefined; this.toastText = undefined; this.paintEdges(); }, TOAST_MS);
+    this.toastTimer.unref?.();
+    this.paintEdges();
+  }
+
+  private paintEdges(): void {
+    const width = Math.max(2, this.renderer.width - (this.shape.tier === "sidebar" ? this.shape.sidebarWidth : 0) - 2);
+    const d = this.dockState, dialog = this.dialogs.open;
+    const role = this.dialogs.tone === "warning" ? "warning" : d.busy && !dialog ? "accent" : "edge";
+    this.body.borderColor = role === "warning" ? this.colors.warning : role === "accent" ? this.colors.accent : this.colors.edge;
+    const right: Label[] = [];
+    if (this.toastText) {
+      const tone = this.toastText.tone;
+      right.push({ segs: [{ text: this.toastText.text, role: tone === "error" ? "error" : tone === "warning" ? "warning" : tone === "success" ? "success" : "text" }], priority: 1, min: 12 });
+    }
+    let left: Label[] = [];
+    if (dialog) {
+      left = [{ segs: [{ text: this.dialogs.title, role: "text", bold: true }], priority: 0, min: 8 }];
+      if (this.dialogs.edgeHint) right.push({ segs: [{ text: this.dialogs.edgeHint, role: "muted" }], priority: 3, min: 10 });
+    } else if (d.busy) {
+      const seconds = Math.max(0, Math.floor((Date.now() - this.busySince) / 1000));
+      left = [{ segs: [{ text: "●", role: "accent", spin: true }, { text: ` ${d.activity}`, role: "muted" }, { text: ` ${seconds}s`, role: "muted" }], priority: 0, min: 1, shrink: 1 }];
+      right.push({ segs: [{ text: "esc interrupt", role: "muted" }], priority: 4 });
+    } else {
+      // A draft taller than the box says what scrolled out of view (fix-tui-composer-growth DoD 4).
+      const { above, below } = this.composer.overflow;
+      if (above) left = [{ segs: [{ text: `↑ ${above} more`, role: "muted" }], priority: 1 }];
+      if (below && !this.toastText) right.push({ segs: [{ text: `↓ ${below} more`, role: "muted" }], priority: 2 });
+    }
+    this.topEdge.setRows([edgeLine({ width, corners: ["╭", "╮"], role, left, right })]);
+    const bottomLeft: Label[] = d.model ? [
+      { segs: [{ text: d.model, role: "text", bold: true }], priority: 0, min: 8 },
+      ...(d.thinking ? [{ segs: [{ text: d.thinking, role: "muted" as const }], priority: 2 }] : []),
+    ] : [];
+    const context = this.shape.tier !== "sidebar" && this.status ? contextLabel(this.status) : undefined;
+    this.bottomEdge.setRows([edgeLine({ width, corners: ["╰", "╯"], role, left: bottomLeft, right: context ? [context] : [] })]);
+  }
+
+  /** A stream event arrived (delta, tool progress, shell output): the spinner returns to full speed. */
+  markActivity(): void {
+    this.lastEvent = Date.now();
+    if (this.activity.running && this.activityMs !== ACTIVITY_MS) this.startClock(ACTIVITY_MS);
+  }
+
+  /** The clock runs only while something on screen shows the activity glyph. */
+  private syncActivity(): void {
+    const wanted = this.animations && (this.dockState.busy || this.dialogs.animated);
+    if (wanted && !this.activity.running) { this.lastEvent = Date.now(); this.startClock(ACTIVITY_MS); }
+    else if (!wanted && this.activity.running) { this.activity.stop(); this.paintEdges(); }
+  }
+
+  private startClock(intervalMs: number): void {
+    this.activityMs = intervalMs;
+    const base = this.spin;
+    this.activity.start(frame => {
+      this.spin = base + frame;
+      if (this.activityMs === ACTIVITY_MS && Date.now() - this.lastEvent > QUIET_AFTER_MS) { this.startClock(IDLE_ACTIVITY_MS); return; }
+      this.paintEdges();
+      this.renderer.requestRender();
+    }, undefined, intervalMs);
+  }
+
+  /** The spinner's current interval (tests). */
+  get activityInterval(): number { return this.activity.running ? this.activityMs : 0; }
+
+  // ------------------------------------------------------------ above the box
+  setQueue(lines: readonly string[]): void { this.queue = lines; this.paintAbove(); }
+
+  /** How pictures are drawn; the transcript and the attachment strip both follow it (feat-tui-inline-images). */
+  setPictures(source: PictureSource): void {
+    this.picturesSource = source;
+    this.messages.setPictures(source);
+    this.attachmentsKey = "";
+    this.paintAttachments();
+  }
+
+  /** The image next to the draft cursor; its identity and sendability remain in the editor. */
+  setAttachments(images: readonly ImageView[]): void { this.attachmentImages = images; this.paintAttachments(); }
+
+  private paintAttachments(): void {
+    const images = this.dialogs.open ? [] : this.attachmentImages;
+    const key = images.map(image => image.sha256).join(",") + `|${this.renderer.width}x${this.renderer.height}`;
+    if (key === this.attachmentsKey) return;
+    this.attachmentsKey = key;
+    for (const child of this.attachments.getChildren()) { this.attachments.remove(child); child.destroyRecursively(); }
+    this.attachments.visible = images.length > 0;
+    if (images.length) {
+      const source = this.picturesSource;
+      const width = Math.max(10, this.renderer.width - (this.shape.tier === "sidebar" ? this.shape.sidebarWidth : 0) - 6);
+      this.attachments.add(new Pictures(this.renderer, this.colors, images, source, { maxCols: width, maxRows: stripImageRows(this.renderer.height) }));
+    }
+    this.renderer.requestRender();
+  }
+  setWidgets(lines: readonly string[]): void { this.widgets = lines; this.paintAbove(); }
+
+  private paintAbove(): void {
+    const width = Math.max(1, this.renderer.width - (this.shape.tier === "sidebar" ? this.shape.sidebarWidth : 0) - 6);
+    const set = (canvas: Canvas, rows: readonly Line[]) => {
+      canvas.visible = rows.length > 0;
+      if (rows.length) { canvas.height = rows.length; canvas.setRows(rows.map(row => clipSegs(row, width))); }
+    };
+    set(this.widgetRows, this.widgets.map(text => [{ text, role: "muted" }]));
+    set(this.queueRows, this.queue.map(text => [{ text: "↳ ", role: "muted" }, { text, role: "text" }]));
+    const view = this.composer.completionView;
+    let rows: Line[] = [];
+    if (view && !this.dialogs.open) {
+      const limit = Math.max(1, Math.min(COMPLETION_ROWS, this.renderer.height - (this.shape.topbar ? 1 : 0) - 2 - (this.composer.rows || 1) - MIN_TRANSCRIPT_ROWS - this.widgets.length - this.queue.length));
+      const start = Math.max(0, Math.min(view.selected - Math.floor(limit / 2), view.items.length - limit));
+      const shown = view.items.slice(start, start + limit);
+      const labelWidth = Math.min(24, Math.max(...shown.map(item => segsWidth([{ text: item.label, role: "text" }]))) + 2);
+      rows = shown.map((item, k) => {
+        const selected = start + k === view.selected;
+        const pad = Math.max(1, labelWidth - segsWidth([{ text: item.label, role: "text" }]));
+        return [{ text: selected ? "▸ " : "  ", role: "accent", bold: true }, { text: item.label, role: "text", bold: selected },
+          ...(item.description ? [{ text: " ".repeat(pad), role: "text" as const }, { text: item.description, role: "muted" as const }] : [])] as Seg[];
+      });
+    }
+    set(this.completion, rows);
+    this.renderer.requestRender();
+  }
+
+  // ---------------------------------------------------------------- greeting
+  setGreeting(state: Greeting | undefined): void {
+    this.home = state;
+    this.paintGreeting();
+  }
+
+  private paintGreeting(): void {
+    const show = this.home !== undefined && !this.composer.text && !this.dialogs.open && this.renderer.height >= GREETING_MIN_ROWS;
+    this.greeting.visible = show;
+    if (!show) { if (this.entrance.running) this.finishEntrance(); return; }
+    // The entrance plays once per screen, when the greeting first shows on a focused terminal.
+    if (!this.greetingPlayed && this.animations && this.focused) {
+      this.greetingPlayed = true;
+      this.entrance.start(frame => { this.greetingFrame = frame; this.drawGreeting(); }, MASCOT_FRAMES - 1, MASCOT_FRAME_MS);
+    }
+    this.greetingPlayed = true;
+    this.drawGreeting();
+  }
+
+  private drawGreeting(): void {
+    if (!this.home) return;
+    const width = Math.max(1, this.renderer.width - (this.shape.tier === "sidebar" ? this.shape.sidebarWidth : 0) - 4);
+    this.greeting.setRows(greetingLines(this.home, mascotFrame(this.greetingFrame)).map(row => clipSegs(row, width)));
+  }
+
+  private finishEntrance(): void {
+    this.entrance.stop();
+    this.greetingFrame = MASCOT_FRAMES;
+    this.drawGreeting();
+  }
+
+  // ------------------------------------------------------------- transcript
+  setItems(items: readonly ViewItem[]): void { this.messages.update(items); }
+
+  private paintPill(): void {
+    this.pill.visible = this.unread > 0;
+    const text = ` ↓ ${this.unread} new `;
+    this.pill.width = segsWidth([{ text, role: "text" }]);
+    this.pill.setRows([[{ text, role: "accent", bold: true }]]);
+  }
+
+  dispose(): void {
+    clearTimeout(this.toastTimer); this.toastTimer = undefined;
+    this.activity.stop(); this.entrance.stop();
+    this.dialogs.dispose();
+  }
+}