ispbills-icli 8.6.6 → 8.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ispbills-icli",
-  "version": "8.6.6",
+  "version": "8.6.8",
   "description": "iCli — IspBills AI network engineer in your terminal",
   "keywords": [
     "ispbills",

package/src/tui/app.js

@@ -1,6 +1,6 @@
 // Root Ink application. Renders an INLINE chat UI (GitHub Copilot CLI style).
 import { html, useState, useEffect, useRef, useCallback } from './dom.js';
-import { Box, Text, Static, useStdout, useApp, useInput } from 'ink';
+import { Box, Text, useStdout, useApp, useInput } from 'ink';
 import { C, glyphs, midDot, dash } from './theme.js';
 import {
   Banner, TabBar, FollowupChips, UserMessage, AssistantMessage, StatusLines, Reasoning,
@@ -230,6 +230,78 @@ function itemPreview(it) {
   return JSON.stringify(it);
 }
 
+// Approximate the number of terminal rows an item occupies. Used purely for
+// viewport slicing — Ink clips any overflow, so this only needs to be close.
+function wrappedLines(text, width) {
+  const w = Math.max(1, width);
+  return String(text || '')
+    .split('\n')
+    .reduce((n, line) => n + Math.max(1, Math.ceil(line.length / w)), 0);
+}
+
+function itemHeight(it, cols = 80) {
+  const w = Math.max(1, cols - 4); // paddingX + body inset
+  switch (it.type) {
+    case 'user':
+      return 3 + wrappedLines(it.text, w); // sep + speaker + margin + body
+    case 'assistant':
+      return 3 + wrappedLines(it.text, Math.min(w, 96));
+    case 'shell':
+      return 4 + wrappedLines(it.output || '(no output)', w) + 1;
+    case 'plan':
+      return 4 + (it.reply?.steps?.length || 0);
+    case 'connect':
+      return 5;
+    case 'activity':
+      return 1 + (it.status?.length || 0);
+    case 'notice':
+      return 1 + wrappedLines(it.text, w);
+    case 'info':
+    case 'error':
+    case 'system':
+      return 2 + wrappedLines(it.text, w);
+    case 'help':
+      return 44;
+    default:
+      return 2 + wrappedLines(it.text, w);
+  }
+}
+
+// Given the full items array, choose the subset visible in a viewport that is
+// `avail` rows tall, scrolled up from the bottom by `scrollOffset` rows.
+// scrollOffset === 0 pins to the newest content at the bottom.
+function selectViewport(items, cols, avail, scrollOffset) {
+  const heights = items.map((it) => itemHeight(it, cols));
+  const total = heights.reduce((a, b) => a + b, 0);
+  const maxOffset = Math.max(0, total - avail);
+  const clamped = Math.max(0, Math.min(scrollOffset, maxOffset));
+  const windowBottom = total - clamped;      // exclusive row from top
+  const windowTop = windowBottom - avail;    // inclusive row from top
+  const visible = [];
+  let aboveCount = 0;
+  let y = 0;
+  for (let i = 0; i < items.length; i++) {
+    const h = heights[i];
+    const top = y;
+    const bottom = y + h;
+    if (bottom <= windowTop) aboveCount++;
+    else if (top < windowBottom) visible.push(items[i]);
+    y = bottom;
+  }
+  return { visible, aboveCount, hasAbove: windowTop > 0, maxOffset, clamped };
+}
+
+function liveAreaHeight(live, cols = 80, showReasoning = false) {
+  if (!live) return 0;
+  const w = Math.max(1, cols - 4);
+  let h = 2; // thinking line + margin
+  if (live.text) h += 3 + wrappedLines(live.text, Math.min(w, 96));
+  if (live.reasoning) h += showReasoning ? 2 + wrappedLines(live.reasoning, w) : 1;
+  if (live.reply?.steps) h += 3 + live.reply.steps.length;
+  if (live.status?.length) h += 1 + live.status.length;
+  return h;
+}
+
 function useTerminalSize() {
   const { stdout } = useStdout();
   const [size, setSize] = useState({ cols: stdout?.columns || 80, rows: stdout?.rows || 24 });
@@ -261,6 +333,10 @@ export function App({ cfg, display = {}, onExternal, onExit, initialQuestion, sh
   const { cols, rows } = useTerminalSize();
   const colsRef = useRef(cols);
   useEffect(() => { colsRef.current = cols; }, [cols]);
+  // Fixed-height viewport: total rows minus chrome (tabbar + spacing + chips +
+  // composer + footer). Everything else scrolls inside this region.
+  const viewportRows = Math.max(3, rows - 6);
+  const scrollPage = Math.max(4, viewportRows - 2);
 
   const [items, setItems] = useState(() => renderConversationItems(initialMessages, cols));
   const [live, setLive] = useState(null);
@@ -275,6 +351,7 @@ export function App({ cfg, display = {}, onExternal, onExit, initialQuestion, sh
   const [startedAt, setStartedAt] = useState(0);
   const [choice, setChoice] = useState(null);
   const [clearEpoch, setClearEpoch] = useState(0);
+  const [scrollOffset, setScrollOffset] = useState(0);
   const [composerClearToken, setComposerClearToken] = useState(0);
   const [composerText, setComposerText] = useState('');
   const [composerPreset, setComposerPreset] = useState({ token: 0, text: '' });
@@ -301,6 +378,7 @@ export function App({ cfg, display = {}, onExternal, onExit, initialQuestion, sh
   const activeTurns = useRef(0);
   const dismissTimers = useRef(new Map());
   const dispatchSubmitRef = useRef(null);
+  const maxScrollRef = useRef(0);
   const sessionIdRef = useRef(initialSession?.id || Date.now().toString(36));
   const sessionCreatedAtRef = useRef(initialSession?.createdAt || new Date().toISOString());
   const sessionNameRef = useRef(initialSession?.name || sessionAutoName(initialMessages));
@@ -327,6 +405,7 @@ export function App({ cfg, display = {}, onExternal, onExit, initialQuestion, sh
   const push = useCallback((item) => {
     const next = { id: nextId(), cols: colsRef.current, ts: item.ts ?? Date.now(), ...item };
     setItems((xs) => [...xs, next]);
+    setScrollOffset(0); // auto-pin to bottom on new content
     return next;
   }, []);
 
@@ -347,6 +426,9 @@ export function App({ cfg, display = {}, onExternal, onExit, initialQuestion, sh
     }
   }, [items, removeItem]);
 
+  // Pin the viewport to the newest content whenever a turn begins streaming.
+  useEffect(() => { if (startedAt) setScrollOffset(0); }, [startedAt]);
+
   const pushNotice = useCallback((text, color = C.gray, autoDismiss = false, type = null) => {
     const resolvedType = type || (color === C.red || color === C.error ? 'error' : 'info');
     push({ type: resolvedType, text, color, autoDismiss });
@@ -359,6 +441,7 @@ export function App({ cfg, display = {}, onExternal, onExit, initialQuestion, sh
     setItems([]);
     setExpandedItems(null);
     setSearch(null);
+    setScrollOffset(0);
     setClearEpoch((n) => n + 1);
   }, []);
 
@@ -367,6 +450,7 @@ export function App({ cfg, display = {}, onExternal, onExit, initialQuestion, sh
     setItems(renderConversationItems(messages, colsRef.current));
     setExpandedItems(null);
     setSearch(null);
+    setScrollOffset(0);
     setClearEpoch((n) => n + 1);
   }, []);
 
@@ -1685,6 +1769,14 @@ export function App({ cfg, display = {}, onExternal, onExit, initialQuestion, sh
       return;
     }
     if (key.ctrl && input === 'd') { doExit(); return; }
+    if (key.pageUp && !choice && !search && !sessionPicker && !diffState) {
+      setScrollOffset((n) => Math.min(maxScrollRef.current, n + scrollPage));
+      return;
+    }
+    if (key.pageDown && !choice && !search && !sessionPicker && !diffState) {
+      setScrollOffset((n) => Math.max(0, n - scrollPage));
+      return;
+    }
     if (key.escape && busy) { abortRef.current?.abort(); return; }
     if (key.escape && shellMode && !composerText.trim()) { setShellMode(false); pushNotice('Exited shell mode.', C.muted, true); return; }
     if (key.escape && expandedItems) { setExpandedItems(null); return; }
@@ -1812,81 +1904,93 @@ export function App({ cfg, display = {}, onExternal, onExit, initialQuestion, sh
     : streamerMode
     ? ''
     : [modelLabel, tokenLabel].filter(Boolean).join(midDot());
-  const compact = cols < 60;
   const composerMode = shellMode ? 'shell' : mode;
-  const staticItems = showBanner
-    ? [{ type: 'banner', id: `banner-${clearEpoch}`, cols }, ...items]
-    : items;
 
-  return html`
-    <${Box} flexDirection="column" width=${cols}>
-      <${Static} key=${clearEpoch} items=${staticItems}>
-        ${(it) => it.type === 'banner'
-          ? html`<${Box} key=${it.id} flexDirection="column" alignItems="center" width=${cols}>
-              <${Banner} cfg=${cfg} model=${model} width=${cols} compact=${compact} streamerMode=${streamerMode} />
+  // ── Viewport slicing ───────────────────────────────────────────────────────
+  // Reserve room for the live streaming area, then pick the items that fit in
+  // the remaining rows, scrolled up from the bottom by scrollOffset.
+  const liveH = liveAreaHeight(live, cols, showReasoning);
+  const availRows = Math.max(1, viewportRows - liveH);
+  const { visible: visibleItems, aboveCount, hasAbove } = selectViewport(items, cols, availRows, scrollOffset);
+  const totalRows = items.reduce((n, it) => n + itemHeight(it, cols), 0);
+  maxScrollRef.current = Math.max(0, totalRows - availRows);
+  const showEmptyBanner = items.length === 0 && !live;
+  const diffHeight = Math.max(8, viewportRows - 1);
+
+  const liveArea = live
+    ? html`<${Box} flexDirection="column">
+        ${live.text ? html`<${AssistantMessage} text=${live.text} cols=${cols} ts=${startedAt || Date.now()} streaming=${true} />` : null}
+        ${live.reasoning ? html`<${Reasoning} text=${live.reasoning} show=${showReasoning} />` : null}
+        ${live.reply?.steps ? html`<${Plan} reply=${live.reply} live=${true} />` : null}
+        <${StatusLines} lines=${live.status} busy=${busy} />
+        <${Thinking} label=${live.reply ? 'Planning' : live.text ? 'Responding' : 'Working'} startedAt=${startedAt} />
+      <//>`
+    : null;
+
+  const scrollIndicator = hasAbove
+    ? html`<${Box} paddingX=${1}>
+        <${Text} color=${C.muted} dimColor>${glyphs.up} ${aboveCount} message${aboveCount === 1 ? '' : 's'} above ${midDot()} PgUp/PgDn to scroll<//>
+      <//>`
+    : null;
+
+  const timelineContent = diffState
+    ? html`<${Box} flexDirection="column">
+        <${DiffViewer}
+          diff=${diffState.lines}
+          sel=${diffState.sel}
+          staged=${diffState.staged}
+          whitespace=${diffState.whitespace}
+          cols=${cols}
+          height=${diffHeight}
+          commentCount=${Object.keys(diffState.comments || {}).length}
+        />
+        ${diffState.commentInput
+          ? html`<${Choice}
+              title=${`Tell Copilot what stands out about ${diffState.commentInput.file}:${diffState.commentInput.lineNumber || '?'}`}
+              note=${diffState.commentInput.content}
+              sel=${0}
+              allowText=${true}
+              text=${diffState.commentInput.text}
+              focusText=${true}
+              options=${[]}
+            />`
+          : null}
+      <//>`
+    : expandedItems
+    ? html`<${Box} flexDirection="column">
+        <${Notice} text=${`${glyphs.expand} ${expandedItems.kind}`} color=${C.muted} />
+        ${expandedItems.items.map((it) => renderItem(it))}
+      <//>`
+    : tabPanel
+    ? html`<${Box} flexDirection="column" paddingX=${1} paddingY=${1}>
+        <${Text} color=${C.brand} bold>${tabPanel.title} — Quick Commands<//>\n
+        ${tabPanel.commands.map((c, i) =>
+          html`<${Box} key=${i}>
+            <${Text} color=${C.slash}>${c.cmd.padEnd(24)}<//>
+            <${Text} color=${C.muted}>${c.desc}<//>
+          <//>`)}
+        \n<${Text} color=${C.muted}>${tabPanel.hint} · Press Enter to return to Session · Press c to start a #reference<//>
+      <//>`
+    : html`<${Box} flexDirection="column">
+        ${showEmptyBanner
+          ? html`<${Box} flexDirection="column" alignItems="center" width=${cols}>
+              <${Banner} cfg=${cfg} model=${model} width=${cols} compact=${true} streamerMode=${streamerMode} />
             <//>`
-          : renderItem(it)}
-      <//>
-
-      ${live
-        ? html`<${Box} flexDirection="column">
-            ${live.text ? html`<${AssistantMessage} text=${live.text} cols=${cols} ts=${startedAt || Date.now()} streaming=${true} />` : null}
-            ${live.reasoning ? html`<${Reasoning} text=${live.reasoning} show=${showReasoning} />` : null}
-            ${live.reply?.steps ? html`<${Plan} reply=${live.reply} live=${true} />` : null}
-            <${StatusLines} lines=${live.status} busy=${busy} />
-            <${Thinking} label=${live.reply ? 'Planning' : live.text ? 'Responding' : 'Working'} startedAt=${startedAt} />
-          <//>`
-        : null}
-
-      ${expandedItems
-        ? html`<${Box} flexDirection="column">
-            <${Notice} text=${`${glyphs.expand} ${expandedItems.kind}`} color=${C.muted} />
-            ${expandedItems.items.map((it) => renderItem(it))}
-          <//>`
-        : null}
+          : null}
+        ${scrollIndicator}
+        ${visibleItems.map((it) => renderItem(it))}
+        ${liveArea}
+      <//>`;
 
-      ${search ? html`<${SearchOverlay} query=${search.query} matches=${searchMatches} active=${search.active} cols=${cols} />` : null}
+  return html`
+    <${Box} flexDirection="column" width=${cols} height=${rows}>
+      <${TabBar} active=${activeTab} cols=${cols} mode=${composerMode} />
 
-      ${diffState
-        ? html`<${Box} flexDirection="column">
-            <${DiffViewer}
-              diff=${diffState.lines}
-              sel=${diffState.sel}
-              staged=${diffState.staged}
-              whitespace=${diffState.whitespace}
-              cols=${cols}
-              height=${Math.max(8, rows - 14)}
-              commentCount=${Object.keys(diffState.comments || {}).length}
-            />
-            ${diffState.commentInput
-              ? html`<${Choice}
-                  title=${`Tell Copilot what stands out about ${diffState.commentInput.file}:${diffState.commentInput.lineNumber || '?'}`}
-                  note=${diffState.commentInput.content}
-                  sel=${0}
-                  allowText=${true}
-                  text=${diffState.commentInput.text}
-                  focusText=${true}
-                  options=${[]}
-                />`
-              : null}
-          <//>`
-        : null}
-
-      <${Box} marginTop=${1}>
-        <${TabBar} active=${activeTab} cols=${cols} mode=${composerMode} />
+      <${Box} flexDirection="column" flexGrow=${1} overflow="hidden">
+        ${timelineContent}
       <//>
 
-      ${tabPanel && !diffState
-        ? html`<${Box} flexDirection="column" paddingX=${1} paddingY=${1}>
-            <${Text} color=${C.brand} bold>${tabPanel.title} — Quick Commands<//>\n
-            ${tabPanel.commands.map((c, i) =>
-              html`<${Box} key=${i}>
-                <${Text} color=${C.slash}>${c.cmd.padEnd(24)}<//>
-                <${Text} color=${C.muted}>${c.desc}<//>
-              <//>`)}
-            \n<${Text} color=${C.muted}>${tabPanel.hint} · Press Enter to return to Session · Press c to start a #reference<//>
-          <//>`
-        : null}
+      ${search ? html`<${SearchOverlay} query=${search.query} matches=${searchMatches} active=${search.active} cols=${cols} />` : null}
 
       ${!busy && chips.length ? html`<${FollowupChips} chips=${chips} active=${activeChip} />` : null}
 

package/src/tui/components.js

@@ -191,28 +191,37 @@ export function Banner({ cfg = {}, model, width = 80, compact = false, streamerM
       ${wide
         ? html`<${Box} flexDirection="column" alignItems="center" width=${width}>
             ${LOGO.map((l, i) => html`<${Text} key=${'l' + i} color=${C.accent} bold>${l}<//>`)}
-            <${Text} color=${C.muted}>iCopilot ${dash()} IspBills network engineer in your terminal<//>
           <//>`
-        : html`<${Text} color=${C.accent} bold>iCopilot ${html`<${Text} color=${C.muted}>${dash()} IspBills AI terminal<//>`}<//>`}
-      <${Box} marginTop=${1}>
+        : html`<${Text} color=${C.accent} bold>◈ iCopilot ${html`<${Text} color=${C.muted}>${dash()} IspBills AI terminal<//>`}<//>` }
+
+      ${wide ? html`<${Text} color=${C.separator}>${'─'.repeat(Math.max(1, width))}<//>\n` : null}
+
+      <${Box} marginTop=${wide ? 0 : 1} justifyContent="center">
+        <${Text} color=${C.accent} bold>◈ iCopilot<//>
+        <${Text} color=${C.muted}>  ${dash()}  IspBills network engineer in your terminal<//>
+      <//>
+
+      ${wide ? html`<${Text} color=${C.separator}>${'─'.repeat(Math.max(1, width))}<//>\n` : null}
+
+      ${meta.length ? html`<${Box} marginTop=${1} justifyContent="center">
         ${meta.map(([label, val], i) => html`
           <${Box} key=${'m' + i}>
             ${i > 0 ? html`<${Text} color=${C.muted}>${midDot()}<//>` : null}
             <${Text} color=${C.muted}>${label} <//>
             <${Text} color=${label === 'model' ? C.accent : C.brand}>${val}<//>
           <//>`)}
+      <//>` : null}
+
+      ${cfg.url ? html`<${Box} justifyContent="center"><${Text} color=${C.muted}>${cfg.url}<//><//>` : null}
+
+      <${Box} flexDirection="column" marginTop=${1} alignItems="center" width=${width}>
+        <${Box} paddingX=${2} flexDirection="column">
+          <${Text} color=${C.muted} dimColor>  ${' @ '}${html`<${Text} color=${C.accent}>@<//>`} mention files · ${html`<${Text} color=${C.accent}>/<//>`} commands · ${html`<${Text} color=${C.accent}>?<//>`} help · ${html`<${Text} color=${C.accent}>!<//>` } shell<//>
+        <//>
       <//>
-      ${cfg.url ? html`<${Text} color=${C.muted}>${cfg.url}<//>` : null}
-
-      <${Box} flexDirection="column" marginTop=${1} paddingX=${2} alignSelf="flex-start">
-        <${Text} color=${C.muted} bold>Quick start:<//>\n
-        <${Text} color=${C.muted}>  <${Text} color=${C.accent}>@<//>  mention files or devices<//>
-        <${Text} color=${C.muted}>  <${Text} color=${C.accent}>/<//>  slash commands<//>
-        <${Text} color=${C.muted}>  <${Text} color=${C.accent}>?<//>  quick help overlay<//>
-        <${Text} color=${C.muted}>  <${Text} color=${C.accent}>!<//>  run shell command<//>
-      <//>
+
       ${!isAuth
-        ? html`<${Box} marginTop=${1}>
+        ? html`<${Box} marginTop=${1} justifyContent="center">
             <${Text} color=${C.warning}>⚠ Not authenticated — run <//>
             <${Text} color=${C.slash} bold>/login<//>
             <${Text} color=${C.warning}> to connect.<//><//>` 

package/src/tui/composer.js

@@ -347,7 +347,7 @@ export function Composer({
       return;
     }
     if (key.pageUp || key.pageDown) {
-      onNotice?.('Use terminal scrollback to view history.', C.muted);
+      // Viewport scrolling is handled by the app-level input handler.
       return;
     }
     if (key.ctrl && input === 'r') {
@@ -517,7 +517,7 @@ export function Composer({
               <${Text} color=${C.muted} italic> ${ghostHint}<//>
             <//>`
           : html`<${Box} flexGrow=${1}>
-              <${Text}>${before}<//><${Text} inverse>${at}<//><${Text}>${after}<//><${Text} color=${C.muted}>${ghost}<//>
+              <${Text}>${before}<//><${Text} inverse>${at}<//><${Text}>${after}<//><${Text} color=${C.muted} italic>${ghost}<//>
             <//>`}
       <//>
 

package/src/tui/run.js

@@ -1,42 +1,105 @@
-// Ink render entrypoint. Runs the TUI INLINE in the normal terminal buffer.
+// Ink render entrypoint. Runs the TUI in a full-screen ALT-SCREEN viewport.
 import { html } from './dom.js';
 import { render } from 'ink';
 import { App } from './app.js';
 import { saveConfig } from '../config.js';
 
+// ── Alt-screen management ────────────────────────────────────────────────────
+// Switch to the alternate terminal buffer so the TUI owns the full viewport and
+// nothing leaks into the user's native scrollback. Must run BEFORE Ink renders.
+let altScreenActive = false;
+
+function enterAltScreen() {
+  if (altScreenActive || !process.stdout.isTTY) return;
+  process.stdout.write('\x1b[?1049h\x1b[2J\x1b[H'); // enter alt-screen, clear, home
+  altScreenActive = true;
+}
+
+function exitAltScreen() {
+  if (!altScreenActive) return;
+  try { process.stdout.write('\x1b[?1049l'); } catch {}
+  altScreenActive = false;
+}
+
+// iCopilot wordmark in block letters
 const LOGO = [
-  '██╗ ██████╗ ██████╗ ██████╗ ██╗██╗      ██████╗ ████████╗',
-  '██║██╔════╝██╔═══██╗██╔══██╗██║██║     ██╔═══██╗╚══██╔══╝',
-  '██║██║     ██║   ██║██████╔╝██║██║     ██║   ██║   ██║   ',
-  '██║██║     ██║   ██║██╔═══╝ ██║██║     ██║   ██║   ██║   ',
-  '██║╚██████╗╚██████╔╝██║     ██║███████╗╚██████╔╝   ██║   ',
-  '╚═╝ ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝ ╚═════╝    ╚═╝   ',
+  ' ██╗ ██████╗ ██████╗ ██████╗ ██╗██╗      ██████╗ ████████╗',
+  ' ██║██╔════╝██╔═══██╗██╔══██╗██║██║     ██╔═══██╗╚══██╔══╝',
+  ' ██║██║     ██║   ██║██████╔╝██║██║     ██║   ██║   ██║   ',
+  ' ██║██║     ██║   ██║██╔═══╝ ██║██║     ██║   ██║   ██║   ',
+  ' ██║╚██████╗╚██████╔╝██║     ██║███████╗╚██████╔╝   ██║   ',
+  ' ╚═╝ ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝ ╚═════╝    ╚═╝   ',
+];
+
+// ANSI gradient: dim purple → bright purple → bright blue → bright cyan
+const FRAMES = [
+  LOGO.map((l) => `\x1b[2;35m${l}\x1b[0m`),           // dim magenta
+  LOGO.map((l) => `\x1b[1;35m${l}\x1b[0m`),           // bold magenta
+  LOGO.map((l, i) => i < 3 ? `\x1b[1;35m${l}\x1b[0m` : `\x1b[1;34m${l}\x1b[0m`), // split
+  LOGO.map((l) => `\x1b[1;34m${l}\x1b[0m`),           // bold blue
+  LOGO.map((l, i) => i < 3 ? `\x1b[1;34m${l}\x1b[0m` : `\x1b[1;36m${l}\x1b[0m`), // split
+  LOGO.map((l) => `\x1b[1;36m${l}\x1b[0m`),           // bold cyan
+  LOGO.map((l) => `\x1b[1;35m${l}\x1b[0m`),           // back to bold magenta
 ];
-const COLORS = ['35', '95', '94', '96', '97'];
 
 async function animateSplash(cfg = {}) {
   if (!process.stdout.isTTY) return;
-  for (let frame = 0; frame < COLORS.length; frame++) {
-    const color = COLORS[frame];
-    const lines = LOGO.map((line, idx) => `\x1b[${Math.min(frame + idx + 1, 5) > 3 ? '1' : '2'};${color}m${line}\x1b[0m`).join('\n');
-    process.stdout.write(lines + '\n');
-    await new Promise((resolve) => setTimeout(resolve, 110));
-    if (frame !== COLORS.length - 1) process.stdout.write(`\x1b[${LOGO.length}A`);
+  const cols = process.stdout.columns || 80;
+  const logoW = LOGO[0].length;
+  const pad = ' '.repeat(Math.max(0, Math.floor((cols - logoW) / 2)));
+
+  // Phase 1: reveal lines one-by-one dim
+  for (let i = 0; i < LOGO.length; i++) {
+    process.stdout.write(`${pad}\x1b[2;35m${LOGO[i]}\x1b[0m\n`);
+    await new Promise((r) => setTimeout(r, 55));
+  }
+
+  // Phase 2: colour-cycle animation
+  for (let fi = 1; fi < FRAMES.length; fi++) {
+    process.stdout.write(`\x1b[${LOGO.length}A`);
+    for (const line of FRAMES[fi]) {
+      process.stdout.write(`${pad}${line}\n`);
+    }
+    await new Promise((r) => setTimeout(r, 90));
   }
-  // §3: welcome text, quick-start tips and a visible /login instruction.
-  const DIM = '\x1b[2m';
-  const ACCENT = '\x1b[38;5;141m';
-  const WARN = '\x1b[38;5;179m';
-  const R = '\x1b[0m';
-  process.stdout.write(`\n  ${ACCENT}iCopilot${R} ${DIM}— IspBills network engineer in your terminal${R}\n\n`);
-  process.stdout.write(`  ${DIM}Quick start:${R}\n`);
-  process.stdout.write(`    ${ACCENT}@${R}${DIM}  mention files or devices${R}\n`);
-  process.stdout.write(`    ${ACCENT}/${R}${DIM}  slash commands${R}\n`);
-  process.stdout.write(`    ${ACCENT}?${R}${DIM}  quick help overlay${R}\n`);
-  process.stdout.write(`    ${ACCENT}!${R}${DIM}  run a shell command${R}\n`);
+
+  // Welcome section — centered
+  const DIM  = '\x1b[2m';
+  const BOLD = '\x1b[1m';
+  const ACC  = '\x1b[38;5;141m'; // #A371F7 purple
+  const BLU  = '\x1b[38;5;75m';  // #58A6FF blue
+  const WARN = '\x1b[38;5;179m'; // #D29922 amber
+  const SEP  = '\x1b[38;5;237m'; // #30363D separator
+  const R    = '\x1b[0m';
+
+  const hr = `${SEP}${'─'.repeat(cols)}${R}`;
+  const subtitle = `${ACC}◈ iCopilot${R}  ${DIM}IspBills network engineer in your terminal${R}`;
+  const subtitleLen = 10 + 2 + 46; // approx visual length
+  const subPad = ' '.repeat(Math.max(0, Math.floor((cols - subtitleLen) / 2)));
+
+  process.stdout.write(`\n${hr}\n`);
+  process.stdout.write(`${subPad}${subtitle}\n`);
+  process.stdout.write(`${hr}\n\n`);
+
+  // Quick-start tips in a two-column grid, centered
+  const tips = [
+    [`${ACC}@${R}`, 'mention files, devices, ONUs'],
+    [`${ACC}/${R}`, 'slash commands & autocomplete'],
+    [`${ACC}?${R}`, 'quick help overlay'],
+    [`${ACC}!${R}`, 'run shell command directly'],
+    [`${BLU}Shift+Tab${R}`, 'cycle Ask → Plan → Autopilot'],
+    [`${BLU}Ctrl+T${R}`,    'toggle reasoning display'],
+  ];
+  const tipW = 42;
+  const tipPad = ' '.repeat(Math.max(0, Math.floor((cols - tipW) / 2)));
+  process.stdout.write(`${tipPad}${DIM}Quick start:${R}\n`);
+  for (const [key, desc] of tips) {
+    process.stdout.write(`${tipPad}  ${BOLD}${key}${R}  ${DIM}${desc}${R}\n`);
+  }
+
   const isAuth = Boolean(cfg?.user?.name || cfg?.user?.email || cfg?.apiKey || cfg?._token);
   if (!isAuth) {
-    process.stdout.write(`\n  ${WARN}⚠ Not authenticated — run ${R}${ACCENT}/login${R}${WARN} to connect.${R}\n`);
+    process.stdout.write(`\n${tipPad}${WARN}⚠ Not authenticated${R}  ${DIM}run${R} ${ACC}/login${R} ${DIM}to connect${R}\n`);
   }
   process.stdout.write('\n');
 }
@@ -47,6 +110,14 @@ export async function runTui(cfg, opts = {}) {
   const seen = Boolean(cfg?.tui?.bannerSeen);
   const showAnimation = banner || !seen;
 
+  // Enter the alternate screen buffer before anything renders, and make sure we
+  // always restore the primary buffer no matter how the process ends.
+  enterAltScreen();
+  process.on('exit', exitAltScreen);
+  const onSignal = (sig) => { exitAltScreen(); process.exit(sig === 'SIGINT' ? 130 : 0); };
+  process.on('SIGINT', () => onSignal('SIGINT'));
+  process.on('SIGTERM', () => onSignal('SIGTERM'));
+
   if (showAnimation) {
     await animateSplash(cfg);
     cfg.tui = { ...(cfg.tui || {}), bannerSeen: true };
@@ -66,6 +137,10 @@ export async function runTui(cfg, opts = {}) {
     { exitOnCtrlC: false },
   );
 
-  await instance.waitUntilExit();
+  try {
+    await instance.waitUntilExit();
+  } finally {
+    exitAltScreen();
+  }
   return externalAction;
 }