jestronaut 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# Jestronaut 🚀
+
+An interactive terminal dashboard for Jest — navigate live test results, suites, and failure stack traces without leaving your terminal.
+
+![License](https://img.shields.io/badge/license-MIT-blue)
+![Jest](https://img.shields.io/badge/jest-%3E%3D27-orange)
+![Node](https://img.shields.io/badge/node-%3E%3D16-green)
+
+## Features
+
+- Live dashboard updates as tests run
+- Animated spinner showing which suites are in progress
+- Pass / Fail / Skip counters + progress bar
+- Navigable test results panel with keyboard controls
+- Navigable suites panel — open any suite to see its full breakdown
+- Failure detail overlay with expected/received diff and stack trace
+- Navigate between failed tests inside a suite with `j/k`
+
+## Install
+
+```bash
+npm install --save-dev jestronaut
+```
+
+## Setup
+
+Add to your `jest.config.js`:
+
+```js
+module.exports = {
+  reporters: ['jestronaut'],
+};
+```
+
+## Run
+
+Instead of `jest`, use:
+
+```bash
+npx jestronaut
+```
+
+Or add to your `package.json` scripts:
+
+```json
+"scripts": {
+  "test": "jestronaut"
+}
+```
+
+All Jest CLI flags work as normal:
+
+```bash
+npx jestronaut --testPathPattern=auth
+npx jestronaut --watch
+```
+
+## Keyboard Controls
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Switch focus between Test Results and Suites panels |
+| `j` / `↓` | Move cursor down |
+| `k` / `↑` | Move cursor up |
+| `Enter` | Open failure detail (on a failed test) or suite detail (on a suite) |
+| `Esc` | Close overlay / go back |
+| `q` / `Ctrl+C` | Quit |
+
+### Inside Suite Detail
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Navigate between failed tests only |
+| `Enter` | Open failure detail for selected test |
+| `Esc` | Back to dashboard |
+
+### Inside Failure Detail
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Scroll |
+| `Esc` | Back |
+
+## Example
+
+The `example/` directory contains a sample Jest project with multiple test suites and intentional failures to demonstrate the dashboard.
+
+```bash
+cd example
+npm install
+npm test
+```
+
+## Requirements
+
+- Node >= 16
+- Jest >= 27
+
+## License
+
+MIT

package/bin/jestronaut.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict';
+
+// Intercept stdout/stderr before Jest loads anything so its early
+// output ("Determining test suites...") doesn't bleed into the TUI.
+const realStdout = process.stdout.write.bind(process.stdout);
+const realStderr = process.stderr.write.bind(process.stderr);
+
+const SUPPRESS = [
+  'Determining test suites',
+  'localstorage-file',
+  'ExperimentalWarning',
+  'trace-warnings',
+  'Jest did not exit',
+  'detectOpenHandles',
+  'asynchronous operations',
+];
+
+function shouldSuppress(chunk) {
+  const s = chunk.toString();
+  return SUPPRESS.some(kw => s.includes(kw));
+}
+
+process.stdout.write = (chunk, enc, cb) => {
+  if (!shouldSuppress(chunk)) return realStdout(chunk, enc, cb);
+  if (typeof enc === 'function') enc(); else if (typeof cb === 'function') cb();
+  return true;
+};
+
+process.stderr.write = (chunk, enc, cb) => {
+  if (!shouldSuppress(chunk)) return realStderr(chunk, enc, cb);
+  if (typeof enc === 'function') enc(); else if (typeof cb === 'function') cb();
+  return true;
+};
+
+// Clear terminal before handing off to Jest
+realStdout('\x1b[2J\x1b[H');
+
+// Forward all CLI args so flags like --testPathPattern, --watch etc. still work
+const { run } = require('jest');
+run();

package/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./lib/reporter');

package/lib/constants.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const SPINNER = ['|', '/', '-', '\\'];
+
+module.exports = { SPINNER };

package/lib/reporter.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const { createState } = require('./state');
+const { createScreen } = require('./ui/screen');
+const { updateHeader } = require('./ui/panels/header');
+const { updateStats } = require('./ui/panels/stats');
+const { updateProgress } = require('./ui/panels/progress');
+const { updateFooter } = require('./ui/panels/footer');
+
+class DashboardReporter {
+  constructor(globalConfig) {
+    this._globalConfig = globalConfig;
+    this._state = createState();
+    const { screen, widgets, renderAll, refreshOpenSuiteDetail } = createScreen(this._state);
+    this._screen = screen;
+    this._widgets = widgets;
+    this._renderAll = renderAll;
+    this._refreshOpenSuiteDetail = refreshOpenSuiteDetail;
+  }
+
+  onRunStart(results) {
+    const s = this._state;
+    s.stats.suites = results.numTotalTestSuites;
+    s.stats.expectedTotal = results.numTotalTests || 0;
+    s.stats.startTime = Date.now();
+    this._renderAll();
+  }
+
+  onTestFileStart(test) {
+    this._state.suites[test.path] = {
+      passed: 0, failed: 0, done: false,
+      startTime: Date.now(), endTime: null,
+      running: new Set(), tests: [],
+    };
+    this._state.suiteOrder.push(test.path);
+    this._renderAll();
+  }
+
+  onTestCaseStart(test, info) {
+    const suite = this._state.suites[test.path];
+    if (suite && info) suite.running.add(info.fullName || info.title);
+  }
+
+  onTestCaseResult(test, r) {
+    const s = this._state;
+    const suite = s.suites[test.path] || {
+      passed: 0, failed: 0, done: false,
+      startTime: Date.now(), running: new Set(), tests: [],
+    };
+
+    s.stats.total++;
+    if (suite.running) suite.running.delete(r.fullName || r.title);
+
+    suite.tests.push({
+      title: r.title,
+      status: r.status,
+      duration: r.duration,
+      messages: r.failureMessages || [],
+    });
+
+    let icon, textColor;
+
+    if (r.status === 'passed') {
+      s.stats.passed++;
+      suite.passed++;
+      icon = '{green-fg}PASS{/green-fg}';
+      textColor = 'white-fg';
+      s.resultMeta.push({ status: 'passed', failureIndex: -1 });
+    } else if (r.status === 'failed') {
+      s.stats.failed++;
+      suite.failed++;
+      icon = '{red-fg}FAIL{/red-fg}';
+      textColor = 'red-fg';
+      const failureIndex = s.failures.length;
+      s.failures.push({
+        title: r.title,
+        suiteName: r.ancestorTitles.join(' > '),
+        messages: r.failureMessages || [],
+        duration: r.duration,
+      });
+      s.resultMeta.push({ status: 'failed', failureIndex });
+    } else {
+      s.stats.skipped++;
+      icon = '{yellow-fg}SKIP{/yellow-fg}';
+      textColor = 'yellow-fg';
+      s.resultMeta.push({ status: r.status, failureIndex: -1 });
+    }
+
+    s.suites[test.path] = suite;
+
+    const ms = r.duration != null ? ` {grey-fg}(${r.duration}ms){/grey-fg}` : '';
+    const ancestor = r.ancestorTitles.join(' > ');
+    const prefix = ancestor ? `{grey-fg}${ancestor} >{/grey-fg} ` : '';
+    const hint = r.status === 'failed' ? ' {cyan-fg}[Enter]{/cyan-fg}' : '';
+    s.resultLines.push(`[${icon}] ${prefix}{${textColor}}${r.title}{/${textColor}}${ms}${hint}`);
+
+    this._refreshOpenSuiteDetail();
+    this._renderAll();
+  }
+
+  onTestFileResult(test) {
+    const suite = this._state.suites[test.path];
+    if (suite) {
+      suite.done = true;
+      suite.endTime = Date.now();
+      suite.running = new Set();
+      this._state.stats.suitesCompleted++;
+    }
+    this._refreshOpenSuiteDetail();
+    this._renderAll();
+  }
+
+  onRunComplete(_, results) {
+    const s = this._state;
+    if (s._ticker) { clearInterval(s._ticker); s._ticker = null; }
+
+    const elapsed = ((Date.now() - s.stats.startTime) / 1000).toFixed(2);
+    const ok = results.numFailedTests === 0;
+
+    updateHeader(this._widgets.header, ok);
+    this._widgets.header.setContent(
+      `{center}{bold} ${ok ? 'ALL TESTS PASSED' : 'SOME TESTS FAILED'} — ${elapsed}s {/bold}{/center}`
+    );
+
+    s.stats.expectedTotal = s.stats.total;
+    updateStats(this._widgets.stats, s.stats);
+    updateProgress(this._widgets.progress, s.stats, this._screen.width);
+    updateFooter(this._widgets.footer, s);
+    this._renderAll();
+  }
+}
+
+module.exports = DashboardReporter;

package/lib/state.js

@@ -0,0 +1,51 @@
+'use strict';
+
+// Central mutable state shared across all UI modules.
+// All modules receive a reference to this object and read/write it directly.
+
+function createState() {
+  return {
+    // run-level stats
+    stats: {
+      passed: 0,
+      failed: 0,
+      skipped: 0,
+      total: 0,
+      expectedTotal: 0,
+      suites: 0,
+      suitesCompleted: 0,
+      startTime: Date.now(),
+    },
+
+    // suite data keyed by file path
+    suites: {},
+    suiteOrder: [],
+
+    // flat list of all test results for the results panel
+    resultLines: [],  // display strings
+    resultMeta: [],   // { status, failureIndex }
+
+    // all failure objects for detail view
+    failures: [],     // { title, suiteName, messages, duration }
+
+    // panel focus
+    focus: 'results', // 'results' | 'suites'
+    resultCursor: -1,
+    suiteCursor: 0,
+
+    // suite detail overlay
+    suiteDetailOpen: false,
+    suiteDetailPath: null,
+    suiteDetailLines: [],
+    suiteDetailMeta: [],
+    suiteDetailCursor: 0,
+
+    // test detail overlay
+    testDetailOpen: false,
+
+    // animation
+    spinFrame: 0,
+  };
+}
+
+module.exports = { createState };

package/lib/ui/keys.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const suiteDetailOverlay = require('./overlays/suiteDetail');
+const { openTestDetail } = require('./overlays/testDetail');
+
+function bindKeys(screen, widgets, state, render) {
+  screen.key(['q', 'C-c'], () => {
+    render.destroy();
+    process.exit(0);
+  });
+
+  screen.key(['tab'], () => {
+    if (state.suiteDetailOpen || state.testDetailOpen) return;
+    state.focus = state.focus === 'results' ? 'suites' : 'results';
+    render.all();
+  });
+
+  screen.key(['up', 'k'], () => {
+    if (state.testDetailOpen) {
+      widgets.testDetail.scroll(-1); screen.render(); return;
+    }
+    if (state.suiteDetailOpen) {
+      suiteDetailOverlay.moveCursor(state, -1);
+      suiteDetailOverlay.refreshSuiteDetail(widgets.suiteDetail, state);
+      screen.render(); return;
+    }
+    if (state.focus === 'results') {
+      if (state.resultLines.length === 0) return;
+      state.resultCursor = state.resultCursor <= 0
+        ? state.resultLines.length - 1
+        : state.resultCursor - 1;
+    } else {
+      if (state.suiteOrder.length === 0) return;
+      state.suiteCursor = state.suiteCursor <= 0
+        ? state.suiteOrder.length - 1
+        : state.suiteCursor - 1;
+    }
+    render.all();
+  });
+
+  screen.key(['down', 'j'], () => {
+    if (state.testDetailOpen) {
+      widgets.testDetail.scroll(1); screen.render(); return;
+    }
+    if (state.suiteDetailOpen) {
+      suiteDetailOverlay.moveCursor(state, 1);
+      suiteDetailOverlay.refreshSuiteDetail(widgets.suiteDetail, state);
+      screen.render(); return;
+    }
+    if (state.focus === 'results') {
+      if (state.resultLines.length === 0) return;
+      state.resultCursor = state.resultCursor >= state.resultLines.length - 1
+        ? 0
+        : state.resultCursor + 1;
+    } else {
+      if (state.suiteOrder.length === 0) return;
+      state.suiteCursor = state.suiteCursor >= state.suiteOrder.length - 1
+        ? 0
+        : state.suiteCursor + 1;
+    }
+    render.all();
+  });
+
+  screen.key(['enter'], () => {
+    if (state.testDetailOpen) return;
+
+    if (state.suiteDetailOpen) {
+      const meta = state.suiteDetailMeta[state.suiteDetailCursor];
+      if (meta && meta.type === 'test' && meta.failureObj) {
+        state.testDetailOpen = true;
+        openTestDetail(widgets.testDetail, meta.failureObj, state.stats);
+        screen.render();
+      }
+      return;
+    }
+
+    if (state.focus === 'results') {
+      if (state.resultCursor < 0 || state.resultCursor >= state.resultMeta.length) return;
+      const meta = state.resultMeta[state.resultCursor];
+      if (meta.status !== 'failed') return;
+      state.testDetailOpen = true;
+      openTestDetail(widgets.testDetail, state.failures[meta.failureIndex], state.stats);
+      screen.render();
+    } else {
+      if (state.suiteOrder.length === 0) return;
+      const path = state.suiteOrder[state.suiteCursor];
+      if (!path) return;
+      _openSuiteDetail(widgets, state, path);
+      screen.render();
+    }
+  });
+
+  screen.key(['escape'], () => {
+    if (state.testDetailOpen) {
+      state.testDetailOpen = false;
+      widgets.testDetail.hide();
+      screen.render();
+      return;
+    }
+    if (state.suiteDetailOpen) {
+      state.suiteDetailOpen = false;
+      state.suiteDetailPath = null;
+      state.suiteDetailLines = [];
+      state.suiteDetailMeta = [];
+      widgets.suiteDetail.hide();
+      screen.render();
+    }
+  });
+}
+
+function _openSuiteDetail(widgets, state, path) {
+  const result = suiteDetailOverlay.buildSuiteDetailLines(state.suites[path], path);
+  state.suiteDetailOpen = true;
+  state.suiteDetailPath = path;
+  state.suiteDetailLines = result.lines;
+  state.suiteDetailMeta = result.meta;
+  state.suiteDetailCursor = result.meta.findIndex(m => m.type === 'test' && m.failureObj);
+  if (state.suiteDetailCursor < 0) state.suiteDetailCursor = 0;
+  widgets.suiteDetail.setLabel(result.label);
+  widgets.suiteDetail.style.border.fg = result.hasFailed ? 'red' : 'green';
+  widgets.suiteDetail.show();
+  suiteDetailOverlay.refreshSuiteDetail(widgets.suiteDetail, state);
+}
+
+// Called when a suite receives new results while suite detail is open
+function refreshOpenSuiteDetail(widgets, state) {
+  if (!state.suiteDetailOpen || !state.suiteDetailPath) return;
+  const result = suiteDetailOverlay.buildSuiteDetailLines(
+    state.suites[state.suiteDetailPath],
+    state.suiteDetailPath
+  );
+  state.suiteDetailLines = result.lines;
+  state.suiteDetailMeta = result.meta;
+  widgets.suiteDetail.setLabel(result.label);
+  widgets.suiteDetail.style.border.fg = result.hasFailed ? 'red' : 'green';
+  suiteDetailOverlay.refreshSuiteDetail(widgets.suiteDetail, state);
+}
+
+module.exports = { bindKeys, refreshOpenSuiteDetail };

package/lib/ui/overlays/suiteDetail.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const blessed = require('blessed');
+
+function createSuiteDetail(screen) {
+  const widget = blessed.list({
+    top: '3%', left: '3%', width: '94%', height: '94%',
+    label: ' Suite Detail ',
+    border: { type: 'line' },
+    tags: true, scrollable: true, alwaysScroll: true,
+    keys: false, mouse: false,
+    scrollbar: { ch: '|', style: { fg: 'magenta' } },
+    style: {
+      border: { fg: 'magenta' }, label: { fg: 'magenta', bold: true },
+      bg: '#08080a', item: { fg: 'white' },
+    },
+    padding: { left: 2, right: 2, top: 1, bottom: 1 },
+    hidden: true,
+  });
+  screen.append(widget);
+  return widget;
+}
+
+function buildSuiteDetailLines(suiteData, path) {
+  const s = suiteData;
+  const name = path.split('/').pop().replace(/\.test\.[jt]sx?$/, '');
+  const totalTests = (s.tests || []).length;
+  const duration = s.endTime && s.startTime
+    ? ((s.endTime - s.startTime) / 1000).toFixed(2) + 's'
+    : 'running...';
+  const status = !s.done ? 'RUNNING' : s.failed > 0 ? 'FAILED' : 'PASSED';
+  const statusColor = !s.done ? 'yellow' : s.failed > 0 ? 'red' : 'green';
+  const passRate = totalTests > 0 ? Math.round((s.passed / totalTests) * 100) : 0;
+
+  const lines = [];
+  const meta = [];
+
+  const add = (text, m = { type: 'other' }) => { lines.push(text); meta.push(m); };
+
+  add(`{${statusColor}-fg}{bold}Suite: ${name}  [${status}]{/bold}{/${statusColor}-fg}`);
+  add('');
+  add(`{yellow-fg}File     :{/yellow-fg}  {grey-fg}${path}{/grey-fg}`);
+  add(`{yellow-fg}Duration :{/yellow-fg}  ${duration}`);
+  add(`{yellow-fg}Pass rate:{/yellow-fg}  {${statusColor}-fg}${passRate}%{/${statusColor}-fg}`);
+  add(`{yellow-fg}Tests    :{/yellow-fg}  ${totalTests} total  {green-fg}${s.passed} passed{/green-fg}  {red-fg}${s.failed} failed{/red-fg}`);
+  add(`{yellow-fg}Slowest  :{/yellow-fg}  ${_slowest(s.tests || [])}`);
+  add(`{yellow-fg}Fastest  :{/yellow-fg}  ${_fastest(s.tests || [])}`);
+  add('');
+  add(`{cyan-fg}── Test Results (${totalTests}) ─────────────────────────────────────────────{/cyan-fg}`);
+  add('');
+
+  const tests = s.tests || [];
+  if (tests.length === 0) {
+    add('  {grey-fg}(no results yet){/grey-fg}');
+  } else {
+    tests.forEach(t => {
+      if (t.status === 'passed') {
+        add(
+          `  {green-fg}PASS{/green-fg}  {white-fg}${t.title}{/white-fg}  {grey-fg}(${t.duration != null ? t.duration + 'ms' : '?'}){/grey-fg}`,
+          { type: 'test', failureObj: null }
+        );
+      } else if (t.status === 'failed') {
+        add(
+          `  {red-fg}FAIL{/red-fg}  {red-fg}${t.title}{/red-fg}  {grey-fg}(${t.duration != null ? t.duration + 'ms' : '?'}){/grey-fg}  {cyan-fg}[Enter]{/cyan-fg}`,
+          {
+            type: 'test',
+            failureObj: { title: t.title, suiteName: name, messages: t.messages || [], duration: t.duration },
+          }
+        );
+      } else {
+        add(
+          `  {yellow-fg}SKIP{/yellow-fg}  {grey-fg}${t.title}{/grey-fg}`,
+          { type: 'test', failureObj: null }
+        );
+      }
+    });
+  }
+
+  add('');
+  add('{grey-fg}  [j/k] navigate failed tests   [Enter] open failure   [Esc] back{/grey-fg}');
+
+  return { lines, meta, name, hasFailed: s.failed > 0, label: ` Suite: ${name}  [${s.passed}p ${s.failed}f] ` };
+}
+
+function refreshSuiteDetail(widget, state) {
+  const items = state.suiteDetailLines.map((line, i) => {
+    const m = state.suiteDetailMeta[i];
+    const isFailed = m && m.type === 'test' && m.failureObj;
+    if (i === state.suiteDetailCursor && isFailed) {
+      return `{#3a0a0a-bg}> ${line.trimStart()}{/#3a0a0a-bg}`;
+    }
+    return line;
+  });
+  widget.setItems(items);
+  widget.scrollTo(state.suiteDetailCursor);
+}
+
+function moveCursor(state, dir) {
+  const meta = state.suiteDetailMeta;
+  if (meta.length === 0) return;
+  const failIndices = meta
+    .map((m, i) => (m.type === 'test' && m.failureObj) ? i : -1)
+    .filter(i => i >= 0);
+  if (failIndices.length === 0) return;
+  const pos = failIndices.indexOf(state.suiteDetailCursor);
+  if (dir > 0) {
+    state.suiteDetailCursor = pos < failIndices.length - 1 ? failIndices[pos + 1] : failIndices[0];
+  } else {
+    state.suiteDetailCursor = pos > 0 ? failIndices[pos - 1] : failIndices[failIndices.length - 1];
+  }
+}
+
+function _slowest(tests) {
+  const t = tests.filter(t => t.duration != null).sort((a, b) => b.duration - a.duration)[0];
+  return t ? `{white-fg}${t.title}{/white-fg} {grey-fg}(${t.duration}ms){/grey-fg}` : 'N/A';
+}
+
+function _fastest(tests) {
+  const t = tests.filter(t => t.duration != null).sort((a, b) => a.duration - b.duration)[0];
+  return t ? `{white-fg}${t.title}{/white-fg} {grey-fg}(${t.duration}ms){/grey-fg}` : 'N/A';
+}
+
+module.exports = { createSuiteDetail, buildSuiteDetailLines, refreshSuiteDetail, moveCursor };

package/lib/ui/overlays/testDetail.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const blessed = require('blessed');
+
+function createTestDetail(screen) {
+  const widget = blessed.box({
+    top: '8%', left: '8%', width: '84%', height: '84%',
+    label: ' Test Failure Detail ',
+    border: { type: 'line' },
+    tags: true, scrollable: true, alwaysScroll: true,
+    keys: true, vi: true,
+    scrollbar: { ch: '|', style: { fg: 'red' } },
+    style: {
+      border: { fg: 'red' }, label: { fg: 'red', bold: true },
+      bg: '#0d0000', fg: 'white',
+    },
+    padding: { left: 2, right: 2, top: 1, bottom: 1 },
+    hidden: true,
+  });
+  screen.append(widget);
+  return widget;
+}
+
+function openTestDetail(widget, failure, stats) {
+  const rawMsg = (failure.messages || []).join('\n');
+  const expectedMatch = rawMsg.match(/Expected[:\s]+(.+)/);
+  const receivedMatch = rawMsg.match(/Received[:\s]+(.+)/);
+  const stackLines = rawMsg.split('\n')
+    .filter(l => l.trim().startsWith('at '))
+    .map(l => l.trim());
+
+  const lines = [
+    `{red-fg}{bold}FAILED: ${failure.suiteName} > ${failure.title}{/bold}{/red-fg}`,
+    '',
+    `{yellow-fg}Suite   :{/yellow-fg}  ${failure.suiteName}`,
+    `{yellow-fg}Test    :{/yellow-fg}  ${failure.title}`,
+    `{yellow-fg}Duration:{/yellow-fg}  ${failure.duration != null ? failure.duration + 'ms' : 'N/A'}`,
+    '',
+    '{cyan-fg}── Error Message ──────────────────────────────────────────────────{/cyan-fg}',
+    '',
+  ];
+
+  if (expectedMatch) lines.push(`  {green-fg}Expected:{/green-fg}  ${expectedMatch[1].trim()}`);
+  if (receivedMatch) lines.push(`  {red-fg}Received:{/red-fg}  ${receivedMatch[1].trim()}`);
+
+  lines.push('');
+  rawMsg.split('\n').slice(0, 15).forEach(l =>
+    lines.push(`  ${l.replace(/\{/g, '(').replace(/\}/g, ')')}`)
+  );
+
+  lines.push(
+    '',
+    '{cyan-fg}── Stack Trace ─────────────────────────────────────────────────────{/cyan-fg}',
+    '',
+  );
+
+  if (stackLines.length > 0) {
+    const firstUser = stackLines.findIndex(l => !l.includes('node_modules'));
+    stackLines.forEach((l, i) => {
+      if (i === firstUser) lines.push(`  {yellow-fg}> ${l}{/yellow-fg}`);
+      else lines.push(`  {grey-fg}${l}{/grey-fg}`);
+    });
+  } else {
+    lines.push('  {grey-fg}(no stack trace){/grey-fg}');
+  }
+
+  lines.push(
+    '',
+    '{cyan-fg}── Run Metrics ─────────────────────────────────────────────────────{/cyan-fg}',
+    '',
+    `  {white-fg}Passed  :{/white-fg}  {green-fg}${stats.passed}{/green-fg}`,
+    `  {white-fg}Failed  :{/white-fg}  {red-fg}${stats.failed}{/red-fg}`,
+    `  {white-fg}Skipped :{/white-fg}  {yellow-fg}${stats.skipped}{/yellow-fg}`,
+    `  {white-fg}Elapsed :{/white-fg}  ${((Date.now() - stats.startTime) / 1000).toFixed(1)}s`,
+    '',
+    '{grey-fg}  [Esc] back   [j/k] scroll{/grey-fg}',
+  );
+
+  widget.setLabel(` Test Failure: ${failure.title} `);
+  widget.setContent(lines.join('\n'));
+  widget.scrollTo(0);
+  widget.show();
+}
+
+module.exports = { createTestDetail, openTestDetail };

package/lib/ui/panels/footer.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const blessed = require('blessed');
+const { SPINNER } = require('../../constants');
+
+function createFooter(screen) {
+  const widget = blessed.box({
+    bottom: 0, left: 0, width: '100%', height: 3,
+    tags: true,
+    style: { fg: 'white', bg: '#111133' },
+  });
+  screen.append(widget);
+  return widget;
+}
+
+function updateFooter(widget, state) {
+  const elapsed = ((Date.now() - state.stats.startTime) / 1000).toFixed(1);
+  const suiteStr = `${state.stats.suitesCompleted}/${state.stats.suites} suites`;
+  const spin = SPINNER[state.spinFrame];
+  const running = Object.values(state.suites).filter(s => !s.done).length;
+  const runningStr = running > 0 ? ` {yellow-fg}${spin} ${running} running{/yellow-fg}  |` : '';
+  const hint = _getHint(state);
+
+  widget.setContent(
+    `{center}{grey-fg} Time: ${elapsed}s  |${runningStr}  ${suiteStr}  |  ${hint}  |  [q] quit {/grey-fg}{/center}`
+  );
+}
+
+function _getHint(state) {
+  if (state.testDetailOpen) {
+    return '{cyan-fg}[Esc]{/cyan-fg} close  |  {cyan-fg}[j/k]{/cyan-fg} scroll';
+  }
+  if (state.suiteDetailOpen) {
+    return '{cyan-fg}[j/k]{/cyan-fg} navigate failed tests  |  {cyan-fg}[Enter]{/cyan-fg} open failure  |  {cyan-fg}[Esc]{/cyan-fg} back';
+  }
+  if (state.focus === 'results') {
+    return '{cyan-fg}[Tab]{/cyan-fg} switch panel  |  {cyan-fg}[Enter]{/cyan-fg} open failure';
+  }
+  return '{cyan-fg}[Tab]{/cyan-fg} switch panel  |  {cyan-fg}[Enter]{/cyan-fg} open suite';
+}
+
+module.exports = { createFooter, updateFooter };

package/lib/ui/panels/header.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const blessed = require('blessed');
+
+function createHeader(screen) {
+  const widget = blessed.box({
+    top: 0, left: 0, width: '100%', height: 3,
+    content: '{center}{bold} JEST TEST DASHBOARD {/bold}{/center}',
+    tags: true,
+    style: { fg: 'white', bg: 'blue', bold: true },
+  });
+  screen.append(widget);
+  return widget;
+}
+
+function updateHeader(widget, ok) {
+  widget.style.bg = ok ? 'green' : 'red';
+  widget.setContent(
+    `{center}{bold} ${ok ? 'ALL TESTS PASSED' : 'SOME TESTS FAILED'} {/bold}{/center}`
+  );
+}
+
+module.exports = { createHeader, updateHeader };

package/lib/ui/panels/progress.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const blessed = require('blessed');
+
+function createProgress(screen) {
+  const widget = blessed.box({
+    top: 5, left: 0, width: '100%', height: 2,
+    tags: true,
+    style: { fg: 'white', bg: '#111133' },
+  });
+  screen.append(widget);
+  return widget;
+}
+
+function updateProgress(widget, stats, screenWidth) {
+  const done = stats.passed + stats.failed + stats.skipped;
+  const total = stats.expectedTotal || done || 1;
+  const pct = Math.min(100, Math.round((done / total) * 100));
+  const bar = _buildBar(pct, screenWidth, stats.failed > 0);
+  widget.setContent(` Progress: ${bar} ${pct}%`);
+}
+
+function _buildBar(pct, screenWidth, hasFailed) {
+  const w = Math.max(20, (screenWidth || 80) - 20);
+  const filled = Math.round((pct / 100) * w);
+  const bar = '#'.repeat(filled) + '-'.repeat(w - filled);
+  const color = hasFailed ? 'red' : 'green';
+  return `{${color}-fg}${bar}{/${color}-fg}`;
+}
+
+module.exports = { createProgress, updateProgress };

package/lib/ui/panels/results.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const blessed = require('blessed');
+
+function createResults(screen) {
+  const widget = blessed.list({
+    top: 7, left: 0, width: '65%', bottom: 3,
+    label: ' Test Results ',
+    border: { type: 'line' },
+    tags: true, scrollable: true, alwaysScroll: true,
+    keys: false, mouse: false,
+    scrollbar: { ch: '|', style: { fg: 'cyan' } },
+    style: {
+      border: { fg: 'cyan' }, label: { fg: 'cyan', bold: true },
+      bg: '#0a0a1a', item: { fg: 'white' },
+    },
+    padding: { left: 1, right: 1 },
+  });
+  screen.append(widget);
+  return widget;
+}
+
+function refreshResults(widget, state) {
+  const items = state.resultLines.map((line, i) => {
+    if (state.focus === 'results' && i === state.resultCursor) {
+      return `{#1a1a4a-bg}${line}{/#1a1a4a-bg}`;
+    }
+    return line;
+  });
+  widget.setItems(items);
+  if (state.focus === 'results' && state.resultCursor >= 0) {
+    widget.scrollTo(state.resultCursor);
+  }
+}
+
+function updateBorder(widget, focused) {
+  widget.style.border.fg = focused ? 'white' : 'cyan';
+  widget.setLabel(focused ? ' Test Results [FOCUSED] ' : ' Test Results ');
+}
+
+module.exports = { createResults, refreshResults, updateBorder };

package/lib/ui/panels/stats.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const blessed = require('blessed');
+
+function createStats(screen) {
+  const widget = blessed.box({
+    top: 3, left: 0, width: '100%', height: 2,
+    tags: true,
+    style: { fg: 'white', bg: '#111133' },
+  });
+  screen.append(widget);
+  return widget;
+}
+
+function updateStats(widget, stats) {
+  const { passed, failed, skipped, total } = stats;
+  widget.setContent(
+    '{center}' +
+    `{green-fg}{bold}  PASSED: ${passed}  {/bold}{/green-fg}` +
+    `{red-fg}{bold}  FAILED: ${failed}  {/bold}{/red-fg}` +
+    `{yellow-fg}{bold}  SKIPPED: ${skipped}  {/bold}{/yellow-fg}` +
+    `{white-fg}  TOTAL: ${total}  {/white-fg}` +
+    '{/center}'
+  );
+}
+
+module.exports = { createStats, updateStats };

package/lib/ui/panels/suites.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const blessed = require('blessed');
+const { SPINNER } = require('../../constants');
+
+function createSuites(screen) {
+  const widget = blessed.list({
+    top: 7, right: 0, width: '35%', bottom: 3,
+    label: ' Suites ',
+    border: { type: 'line' },
+    tags: true, scrollable: true, alwaysScroll: true,
+    keys: false, mouse: false,
+    scrollbar: { ch: '|', style: { fg: 'magenta' } },
+    style: {
+      border: { fg: 'magenta' }, label: { fg: 'magenta', bold: true },
+      bg: '#0a0a1a', item: { fg: 'white' },
+    },
+    padding: { left: 1, right: 1 },
+  });
+  screen.append(widget);
+  return widget;
+}
+
+function updateSuites(widget, state) {
+  const spin = SPINNER[state.spinFrame];
+  const items = state.suiteOrder.map((path, i) => {
+    const s = state.suites[path];
+    const name = path.split('/').pop().replace(/\.test\.[jt]sx?$/, '');
+    const elapsed = s.startTime ? ` ${((Date.now() - s.startTime) / 1000).toFixed(1)}s` : '';
+
+    let icon, detail;
+    if (s.done) {
+      icon = s.failed > 0 ? '{red-fg}FAIL{/red-fg}' : '{green-fg}PASS{/green-fg}';
+      detail = ` {grey-fg}[${s.passed}p ${s.failed}f]{/grey-fg}`;
+    } else {
+      icon = `{yellow-fg}${spin}{/yellow-fg}`;
+      detail = `{grey-fg}${elapsed} [${s.passed}p ${s.failed}f]{/grey-fg}`;
+    }
+
+    const runningLines = s.running && s.running.size > 0
+      ? '\n' + [...s.running].map(t => `  {cyan-fg}> ${t}{/cyan-fg}`).join('\n')
+      : '';
+
+    const isCursor = state.focus === 'suites' && i === state.suiteCursor;
+    const bg = isCursor ? '{#1a0a3a-bg}' : '';
+    const bgEnd = isCursor ? '{/#1a0a3a-bg}' : '';
+    const hint = isCursor ? ' {cyan-fg}[Enter]{/cyan-fg}' : '';
+
+    return `${bg}${icon} {white-fg}${name}{/white-fg}${detail}${hint}${bgEnd}${runningLines}`;
+  });
+
+  widget.setItems(items.length ? items : ['{grey-fg}waiting...{/grey-fg}']);
+  if (state.focus === 'suites' && state.suiteCursor >= 0) {
+    widget.scrollTo(state.suiteCursor);
+  }
+}
+
+function updateBorder(widget, focused) {
+  widget.style.border.fg = focused ? 'white' : 'magenta';
+  widget.setLabel(focused ? ' Suites [FOCUSED] ' : ' Suites ');
+}
+
+module.exports = { createSuites, updateSuites, updateBorder };

package/lib/ui/screen.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const blessed = require('blessed');
+const { SPINNER } = require('../constants');
+const { createHeader, updateHeader } = require('./panels/header');
+const { createStats, updateStats } = require('./panels/stats');
+const { createProgress, updateProgress } = require('./panels/progress');
+const { createResults, refreshResults, updateBorder: updateResultsBorder } = require('./panels/results');
+const { createSuites, updateSuites, updateBorder: updateSuitesBorder } = require('./panels/suites');
+const { createFooter, updateFooter } = require('./panels/footer');
+const { createSuiteDetail } = require('./overlays/suiteDetail');
+const { createTestDetail } = require('./overlays/testDetail');
+const { bindKeys, refreshOpenSuiteDetail } = require('./keys');
+
+function createScreen(state) {
+  const screen = blessed.screen({
+    smartCSR: true,
+    title: 'Jest Dashboard',
+    fullUnicode: false,
+    warnings: false,
+    terminal: 'xterm-256color',
+  });
+
+  const widgets = {
+    header:      createHeader(screen),
+    stats:       createStats(screen),
+    progress:    createProgress(screen),
+    results:     createResults(screen),
+    suites:      createSuites(screen),
+    footer:      createFooter(screen),
+    suiteDetail: createSuiteDetail(screen),
+    testDetail:  createTestDetail(screen),
+  };
+
+  // render helpers passed to key bindings
+  const render = {
+    all: () => renderAll(screen, widgets, state),
+    destroy: () => {
+      if (state._ticker) clearInterval(state._ticker);
+      screen.destroy();
+    },
+  };
+
+  bindKeys(screen, widgets, state, render);
+
+  // animation ticker
+  state._ticker = setInterval(() => {
+    state.spinFrame = (state.spinFrame + 1) % SPINNER.length;
+    updateSuites(widgets.suites, state);
+    updateFooter(widgets.footer, state);
+    screen.render();
+  }, 120);
+
+  renderAll(screen, widgets, state);
+
+  return { screen, widgets, renderAll: () => renderAll(screen, widgets, state), refreshOpenSuiteDetail: () => refreshOpenSuiteDetail(widgets, state) };
+}
+
+function renderAll(screen, widgets, state) {
+  updateStats(widgets.stats, state.stats);
+  updateProgress(widgets.progress, state.stats, screen.width);
+  updateSuites(widgets.suites, state);
+  updateFooter(widgets.footer, state);
+  _updateBorders(widgets, state);
+  refreshResults(widgets.results, state);
+  screen.render();
+}
+
+function _updateBorders(widgets, state) {
+  updateResultsBorder(widgets.results, state.focus === 'results');
+  updateSuitesBorder(widgets.suites, state.focus === 'suites');
+}
+
+module.exports = { createScreen };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "jestronaut",
+  "version": "0.1.0",
+  "description": "An interactive terminal dashboard UI for Jest — navigate live test results, suites, and failure details without leaving your terminal",
+  "main": "index.js",
+  "bin": {
+    "jestronaut": "bin/jestronaut.js"
+  },
+  "keywords": [
+    "jest",
+    "reporter",
+    "dashboard",
+    "tui",
+    "terminal",
+    "blessed",
+    "jestronaut"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "blessed": "^0.1.81"
+  },
+  "peerDependencies": {
+    "jest": ">=27"
+  }
+}