@pokit/tabs-opentui 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pokit/tabs-opentui",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "OpenTUI-based tab renderer for pok CLI applications",
   "keywords": [
     "cli",
@@ -26,9 +26,8 @@
   "bugs": {
     "url": "https://github.com/notation-dev/openpok/issues"
   },
-  "main": "./src/index.ts",
-  "module": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -39,7 +38,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
@@ -53,12 +53,12 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/react": "^19.2.0",
-    "@pokit/core": "0.0.1",
-    "@pokit/tabs-core": "0.0.1"
+    "@pokit/core": "0.0.2",
+    "@pokit/tabs-core": "0.0.2"
   },
   "peerDependencies": {
-    "@pokit/core": "0.0.1",
-    "@pokit/tabs-core": "0.0.1"
+    "@pokit/core": "0.0.2",
+    "@pokit/tabs-core": "0.0.2"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/adapter.tsx

@@ -0,0 +1,244 @@
+/**
+ * OpenTUI-based Tabs Adapter
+ *
+ * Implements the TabsAdapter interface using OpenTUI (React for CLI).
+ * Also provides an event-driven adapter that renders based on EventBus events.
+ */
+
+import * as React from 'react';
+import { createCliRenderer } from '@opentui/core';
+import { createRoot } from '@opentui/react';
+import type { TabsAdapter, TabSpec, TabsOptions, EventBus } from '@pokit/core';
+import { TabsApp } from './tabs-app.js';
+import { EventDrivenApp } from './event-driven-app.js';
+import { TabsErrorBoundary, restoreTerminal } from './error-boundary.js';
+
+/**
+ * Create a tabs adapter using OpenTUI
+ */
+export function createTabsAdapter(): TabsAdapter {
+  return {
+    async run(items: TabSpec[], options: TabsOptions): Promise<void> {
+      if (!process.stdout.isTTY) {
+        throw new Error('Tabbed view requires stdout to be a TTY');
+      }
+
+      if (!process.stdin.isTTY) {
+        throw new Error('Tabbed view requires stdin to be a TTY for keyboard input');
+      }
+
+      if (items.length === 0) {
+        return;
+      }
+
+      // Ensure stdin is not paused - previous CLI operations (prompts, spinners)
+      // may have left it in a paused state
+      if (process.stdin.isPaused()) {
+        process.stdin.resume();
+      }
+
+      // Enable raw mode before OpenTUI starts - this ensures stdin is ready
+      // to receive escape sequence responses for capability detection
+      process.stdin.setRawMode(true);
+
+      // Let OpenTUI handle alternate screen via its config
+      const renderer = await createCliRenderer({
+        exitOnCtrlC: false,
+        useAlternateScreen: true,
+        useMouse: true, // Enable mouse for scroll wheel support
+        useKittyKeyboard: {}, // Enable Kitty keyboard protocol for better key handling
+      });
+
+      // Disable stdout interception to prevent output mangling with scrolling
+      renderer.disableStdoutInterception();
+
+      const root = createRoot(renderer);
+
+      // Start the render loop explicitly
+      renderer.start();
+
+      return new Promise<void>((resolve) => {
+        let resolved = false;
+
+        // Cleanup function to restore terminal and resolve
+        const cleanup = () => {
+          if (resolved) return;
+          resolved = true;
+
+          // Remove signal handlers
+          process.removeListener('SIGTERM', handleSignal);
+          process.removeListener('SIGQUIT', handleSignal);
+          process.removeListener('uncaughtException', handleUncaughtException);
+
+          try {
+            root.unmount();
+            renderer.destroy();
+          } catch {
+            // Ignore errors during cleanup
+          }
+
+          restoreTerminal();
+          resolve();
+        };
+
+        // Signal handler for graceful shutdown
+        const handleSignal = () => {
+          cleanup();
+          process.exit(0);
+        };
+
+        // Handle uncaught exceptions
+        const handleUncaughtException = (error: Error) => {
+          restoreTerminal();
+          console.error('\n[TabsUI] Uncaught exception:', error);
+          cleanup();
+          process.exit(1);
+        };
+
+        // Register signal handlers
+        process.on('SIGTERM', handleSignal);
+        process.on('SIGQUIT', handleSignal);
+        process.on('uncaughtException', handleUncaughtException);
+
+        // Handle fatal errors from error boundary
+        const handleFatalError = () => {
+          cleanup();
+        };
+
+        const handleExit = () => {
+          cleanup();
+        };
+
+        // Use React.createElement to bypass OpenTUI's JSX type constraints for class components
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        root.render(
+          React.createElement(
+            TabsErrorBoundary,
+            { onFatalError: handleFatalError },
+            React.createElement(TabsApp, { items, options, onExit: handleExit })
+          ) as any
+        );
+      });
+    },
+  };
+}
+
+export type EventAdapterOptions = {
+  onExit?: (code: number) => void;
+};
+
+/**
+ * Create an event-driven adapter that renders based on EventBus events.
+ * This adapter builds a state tree from events and renders it using OpenTUI.
+ *
+ * @param bus - The EventBus to listen to
+ * @param options - Options for the adapter
+ * @returns Object with unmount function to stop the adapter
+ */
+export function createEventAdapter(
+  bus: EventBus,
+  options: EventAdapterOptions = {}
+): { unmount: () => void } {
+  if (!process.stdout.isTTY) {
+    throw new Error('Event-driven tabs view requires stdout to be a TTY');
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new Error('Event-driven tabs view requires stdin to be a TTY for keyboard input');
+  }
+
+  let root: ReturnType<typeof createRoot> | null = null;
+  let renderer: Awaited<ReturnType<typeof createCliRenderer>> | null = null;
+  let isCleanedUp = false;
+
+  // Cleanup function to restore terminal
+  const cleanup = () => {
+    if (isCleanedUp) return;
+    isCleanedUp = true;
+
+    // Remove signal handlers
+    process.removeListener('SIGTERM', handleSignal);
+    process.removeListener('SIGQUIT', handleSignal);
+    process.removeListener('uncaughtException', handleUncaughtException);
+
+    try {
+      root?.unmount();
+      renderer?.destroy();
+    } catch {
+      // Ignore errors during cleanup
+    }
+
+    restoreTerminal();
+  };
+
+  // Signal handler for graceful shutdown
+  const handleSignal = () => {
+    cleanup();
+    process.exit(0);
+  };
+
+  // Handle uncaught exceptions
+  const handleUncaughtException = (error: Error) => {
+    restoreTerminal();
+    console.error('\n[TabsUI] Uncaught exception:', error);
+    cleanup();
+    process.exit(1);
+  };
+
+  // Register signal handlers
+  process.on('SIGTERM', handleSignal);
+  process.on('SIGQUIT', handleSignal);
+  process.on('uncaughtException', handleUncaughtException);
+
+  const init = async () => {
+    // Let OpenTUI handle alternate screen and raw mode via its config
+    renderer = await createCliRenderer({
+      exitOnCtrlC: false,
+      useAlternateScreen: true,
+      useMouse: false,
+      useKittyKeyboard: {}, // Enable Kitty keyboard protocol for better key handling
+    });
+
+    // Check if cleanup was requested during async init
+    if (isCleanedUp) {
+      renderer.destroy();
+      return;
+    }
+
+    // Disable stdout interception to prevent output mangling with scrolling
+    renderer.disableStdoutInterception();
+    root = createRoot(renderer);
+
+    // Start the render loop explicitly
+    renderer.start();
+
+    const handleExit = (code: number) => {
+      cleanup();
+      options.onExit?.(code);
+    };
+
+    // Handle fatal errors from error boundary
+    const handleFatalError = () => {
+      cleanup();
+    };
+
+    // Use React.createElement to bypass OpenTUI's JSX type constraints for class components
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    root.render(
+      React.createElement(
+        TabsErrorBoundary,
+        { onFatalError: handleFatalError },
+        React.createElement(EventDrivenApp, { bus, onExit: handleExit })
+      ) as any
+    );
+  };
+
+  init().catch((error) => {
+    console.error('Failed to initialize event adapter:', error);
+    restoreTerminal();
+  });
+
+  return {
+    unmount: cleanup,
+  };
+}

package/src/error-boundary.tsx

@@ -0,0 +1,95 @@
+/**
+ * Error Boundary for Tabs UI (OpenTUI)
+ *
+ * Catches React errors and ensures terminal state is restored before displaying error.
+ * This prevents the terminal from being left in a corrupted state (alternate screen,
+ * hidden cursor, raw mode) when React rendering crashes.
+ */
+
+import * as React from 'react';
+
+export type ErrorBoundaryProps = {
+  children?: React.ReactNode;
+  onFatalError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+};
+
+type ErrorBoundaryState = {
+  hasError: boolean;
+  error: Error | null;
+};
+
+/**
+ * Restore terminal to a clean state.
+ * Called on errors and signal handlers to ensure terminal isn't left corrupted.
+ */
+export function restoreTerminal(): void {
+  // Exit alternate screen buffer
+  process.stdout.write('\x1b[?1049l');
+  // Show cursor (in case it was hidden)
+  process.stdout.write('\x1b[?25h');
+  // Reset all attributes (colors, styles)
+  process.stdout.write('\x1b[0m');
+
+  // Try to restore raw mode if stdin is a TTY
+  if (process.stdin.isTTY && process.stdin.isRaw) {
+    try {
+      process.stdin.setRawMode(false);
+    } catch {
+      // Ignore errors - stdin may already be closed
+    }
+  }
+}
+
+/**
+ * Internal React Error Boundary class that ensures terminal cleanup on crashes.
+ * For OpenTUI, we use a simple fallback since OpenTUI components may not
+ * render correctly after an error.
+ */
+class ErrorBoundaryClass extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+    // Restore terminal state immediately
+    restoreTerminal();
+
+    // Log error details for debugging
+    console.error('\n[TabsUI] Fatal error caught by error boundary:');
+    console.error(error);
+    if (errorInfo.componentStack) {
+      console.error('\nComponent stack:', errorInfo.componentStack);
+    }
+
+    // Notify parent if callback provided
+    this.props.onFatalError?.(error, errorInfo);
+  }
+
+  render(): React.ReactNode {
+    if (this.state.hasError) {
+      // For OpenTUI, render a simple box with the error message
+      // The terminal should already be restored at this point
+      return (
+        <box flexDirection="column" padding={1}>
+          <text fg="#FF0000">TabsUI encountered a fatal error</text>
+          <text fg="#888888">{this.state.error?.message ?? 'Unknown error'}</text>
+          <text fg="#666666">Press Ctrl+C to exit</text>
+        </box>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+/**
+ * Export the error boundary class.
+ * Note: When using in JSX with OpenTUI, you may need to use React.createElement directly
+ * due to OpenTUI's JSX type constraints.
+ */
+export const TabsErrorBoundary = ErrorBoundaryClass;

package/src/event-driven-app.tsx

@@ -0,0 +1,237 @@
+/**
+ * Event-Driven CLI App for OpenTUI
+ *
+ * A React component that renders CLI state based on EventBus events.
+ * Supports different layouts (tabs, parallel, sequence) based on group layout hints.
+ */
+
+import { useState, useCallback } from 'react';
+import { useKeyboard, useTerminalDimensions } from '@opentui/react';
+import type { KeyEvent } from '@opentui/core';
+import type { EventBus } from '@pokit/core';
+import type { ActivityNode } from '@pokit/tabs-core';
+import { findTabsGroup, getTabsGroupActivities } from '@pokit/tabs-core';
+import { useEventBus } from './use-event-bus.js';
+
+type EventDrivenAppProps = {
+  bus: EventBus;
+  onExit: (code: number) => void;
+};
+
+function getStatusIndicator({
+  status,
+  isActive,
+}: {
+  status: ActivityNode['status'];
+  isActive?: boolean;
+}) {
+  switch (status) {
+    case 'running':
+      return { color: isActive ? '#00FFFF' : '#008B8B', icon: '\u25CF' };
+    case 'success':
+      return { color: isActive ? '#00FF00' : '#008000', icon: '\u2713' };
+    case 'failure':
+      return { color: isActive ? '#FF0000' : '#8B0000', icon: '\u2717' };
+  }
+}
+
+function ActivityTabBar({
+  activities,
+  activeIndex,
+}: {
+  activities: ActivityNode[];
+  activeIndex: number;
+}) {
+  return (
+    <box flexDirection="row" gap={1} flexWrap="wrap">
+      {activities.map((activity, i) => {
+        const isActive = i === activeIndex;
+        const { color, icon } = getStatusIndicator({
+          status: activity.status,
+          isActive,
+        });
+        return (
+          <box key={activity.id} flexDirection="row">
+            <text fg={color}> {icon} </text>
+            <box style={isActive ? { backgroundColor: '#444' } : {}}>
+              <text fg={isActive ? '#FFF' : '#888'}>
+                {' '}
+                {activity.label} ({i + 1}){' '}
+              </text>
+            </box>
+          </box>
+        );
+      })}
+    </box>
+  );
+}
+
+function ActivityView({ activity, viewHeight }: { activity: ActivityNode; viewHeight: number }) {
+  const logs = activity.logs.slice(-viewHeight);
+
+  return (
+    <box flexDirection="column" height={viewHeight} overflow="hidden">
+      {activity.message && <text fg="#00FFFF">{activity.message}</text>}
+      {activity.progress !== undefined && <text fg="#FFFF00">Progress: {activity.progress}%</text>}
+      {logs.map((log, i) => {
+        let color: string | undefined;
+        switch (log.level) {
+          case 'error':
+            color = '#FF0000';
+            break;
+          case 'warn':
+            color = '#FFFF00';
+            break;
+          case 'success':
+            color = '#00FF00';
+            break;
+          case 'info':
+            color = '#0000FF';
+            break;
+          default:
+            color = undefined;
+        }
+        return (
+          <text key={i} fg={color}>
+            {log.message}
+          </text>
+        );
+      })}
+      {Array.from({
+        length: Math.max(
+          0,
+          viewHeight -
+            logs.length -
+            (activity.message ? 1 : 0) -
+            (activity.progress !== undefined ? 1 : 0)
+        ),
+      }).map((_, i) => (
+        <text key={`empty-${i}`}> </text>
+      ))}
+    </box>
+  );
+}
+
+function StatusBar({
+  activityCount,
+  quitConfirmPending,
+}: {
+  activityCount: number;
+  quitConfirmPending: boolean;
+}) {
+  if (quitConfirmPending) {
+    return (
+      <box>
+        <box style={{ backgroundColor: '#FFFF00' }}>
+          <text fg="#000000"> Press q again to quit, any other key to cancel </text>
+        </box>
+      </box>
+    );
+  }
+
+  return (
+    <box>
+      <text fg="#666666">[Tab/1-{activityCount}] switch | [q]uit</text>
+    </box>
+  );
+}
+
+export function EventDrivenApp({ bus, onExit }: EventDrivenAppProps): React.ReactNode {
+  const state = useEventBus(bus);
+  const { height: rows } = useTerminalDimensions();
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [quitConfirmPending, setQuitConfirmPending] = useState(false);
+
+  const terminalHeight = rows ?? 24;
+  const viewHeight = Math.max(5, terminalHeight - 6);
+
+  const tabsGroup = findTabsGroup(state);
+  const activities = tabsGroup
+    ? getTabsGroupActivities(state, tabsGroup.id)
+    : Array.from(state.activities.values());
+
+  const activeActivity = activities[activeIndex];
+
+  const switchTab = useCallback(
+    (newIndex: number) => {
+      if (newIndex >= 0 && newIndex < activities.length) {
+        setActiveIndex(newIndex);
+      }
+    },
+    [activities.length]
+  );
+
+  const handleQuitRequest = useCallback(() => {
+    setQuitConfirmPending((prev) => !prev);
+  }, []);
+
+  const handleQuit = useCallback(() => {
+    onExit(state.exitCode ?? 0);
+  }, [onExit, state.exitCode]);
+
+  useKeyboard((event: KeyEvent) => {
+    const { name, ctrl, shift } = event;
+
+    if (quitConfirmPending) {
+      if (name === 'q') {
+        handleQuit();
+      } else {
+        handleQuitRequest();
+      }
+      return;
+    }
+
+    if (name === 'q') {
+      handleQuitRequest();
+      return;
+    }
+
+    if (name === 'c' && ctrl) {
+      handleQuit();
+      return;
+    }
+
+    const num = parseInt(name, 10);
+    if (num >= 1 && num <= activities.length) {
+      switchTab(num - 1);
+      return;
+    }
+
+    if (name === 'tab' && shift) {
+      switchTab((activeIndex - 1 + activities.length) % activities.length);
+      return;
+    }
+    if (name === 'tab') {
+      switchTab((activeIndex + 1) % activities.length);
+      return;
+    }
+  });
+
+  if (activities.length === 0) {
+    return (
+      <box flexDirection="column" padding={1}>
+        <text>Waiting for activities...</text>
+        {state.appName && (
+          <text fg="#666666">
+            {state.appName}
+            {state.version ? ` v${state.version}` : ''}
+          </text>
+        )}
+      </box>
+    );
+  }
+
+  if (!activeActivity) {
+    return <text>No active activity</text>;
+  }
+
+  return (
+    <box flexDirection="column" padding={1}>
+      <ActivityTabBar activities={activities} activeIndex={activeIndex} />
+      <box border={['top', 'bottom']} borderStyle="single" borderColor="#666666">
+        <ActivityView activity={activeActivity} viewHeight={viewHeight} />
+      </box>
+      <StatusBar activityCount={activities.length} quitConfirmPending={quitConfirmPending} />
+    </box>
+  );
+}

package/src/help-overlay.tsx

@@ -0,0 +1,49 @@
+/**
+ * Help Overlay for OpenTUI
+ *
+ * Displays keyboard shortcuts in a modal overlay.
+ */
+
+import { HELP_CONTENT } from '@pokit/tabs-core';
+
+export type HelpOverlayProps = {
+  onClose: () => void;
+};
+
+export function HelpOverlay(_props: HelpOverlayProps): React.ReactNode {
+  return (
+    <box
+      flexDirection="column"
+      border={['top', 'bottom', 'left', 'right']}
+      borderStyle="single"
+      borderColor="#0000FF"
+      padding={1}
+    >
+      <box justifyContent="center" marginBottom={1}>
+        <text fg="#FFFFFF">Keyboard Help</text>
+      </box>
+
+      {HELP_CONTENT.map((group, i) => (
+        <box
+          key={group.title}
+          flexDirection="column"
+          marginBottom={i < HELP_CONTENT.length - 1 ? 1 : 0}
+        >
+          <text fg="#00FFFF">{group.title}</text>
+          {group.shortcuts.map(({ key, description }) => (
+            <box key={key} flexDirection="row">
+              <box width={16}>
+                <text fg="#FFFF00">{key}</text>
+              </box>
+              <text>{description}</text>
+            </box>
+          ))}
+        </box>
+      ))}
+
+      <box marginTop={1} justifyContent="center">
+        <text fg="#666666">Press ? or Escape to close</text>
+      </box>
+    </box>
+  );
+}

package/src/tabbed-view.tsx

@@ -0,0 +1,306 @@
+/**
+ * Tabbed View Components for OpenTUI
+ *
+ * UI components for the tabbed terminal interface using OpenTUI primitives.
+ */
+
+import { useKeyboard, useTerminalDimensions } from '@opentui/react';
+import type { KeyEvent, ScrollBoxRenderable } from '@opentui/core';
+import type { TabProcess } from '@pokit/tabs-core';
+import {
+  useTabsState,
+  useKeyboardCallbackRefs,
+  processKeyEvent,
+  executeKeyboardAction,
+  type NormalizedKeyEvent,
+  type KeyboardCallbacks,
+} from '@pokit/tabs-core';
+import { HelpOverlay } from './help-overlay.js';
+
+type TabbedViewProps = {
+  tabs: TabProcess[];
+  activeIndex: number;
+  onActiveIndexChange: (index: number) => void;
+  onQuit: () => void;
+  onQuitRequest: () => void;
+  onRestart: (index: number) => void;
+  onKill: (index: number) => void;
+  quitConfirmPending: boolean;
+  focusMode: boolean;
+  onEnterFocusMode: () => void;
+  onExitFocusMode: () => void;
+  onSendInput: (data: string) => void;
+  scrollRef?: (ref: ScrollBoxRenderable | null) => void;
+  helpVisible: boolean;
+  onToggleHelp: () => void;
+  onCloseHelp: () => void;
+};
+
+function getStatusIndicator({
+  status,
+  isActive,
+}: {
+  status: TabProcess['status'];
+  isActive?: boolean;
+}) {
+  switch (status) {
+    case 'running':
+      return { color: isActive ? '#00FFFF' : '#008B8B', icon: '\u25CF' };
+    case 'done':
+      return { color: isActive ? '#00FF00' : '#008000', icon: '\u2713' };
+    case 'error':
+      return { color: isActive ? '#FF0000' : '#8B0000', icon: '\u2717' };
+    case 'stopped':
+      return { color: isActive ? '#FFFF00' : '#808000', icon: '\u25A0' };
+  }
+}
+
+function TabBar({
+  tabs,
+  activeIndex,
+  focusMode,
+}: {
+  tabs: TabProcess[];
+  activeIndex: number;
+  focusMode: boolean;
+}) {
+  return (
+    <box flexDirection="row" gap={1} flexWrap="wrap">
+      {tabs.map((tab, i) => {
+        const isActive = i === activeIndex;
+        const { color, icon } = getStatusIndicator({
+          status: tab.status,
+          isActive,
+        });
+        return (
+          <box key={tab.id} flexDirection="row">
+            <text fg={color}> {icon} </text>
+            <box style={isActive ? { backgroundColor: '#444' } : {}}>
+              <text fg={isActive ? '#FFF' : '#888'}>
+                {' '}
+                {tab.label} ({i + 1}){' '}
+              </text>
+            </box>
+          </box>
+        );
+      })}
+      {focusMode && (
+        <box style={{ backgroundColor: '#FFFF00' }}>
+          <text fg="#000000"> INPUT MODE </text>
+        </box>
+      )}
+    </box>
+  );
+}
+
+function OutputView({
+  lines,
+  viewHeight,
+  isActive,
+  scrollRef,
+}: {
+  lines: string[];
+  viewHeight: number;
+  isActive: boolean;
+  scrollRef?: (ref: ScrollBoxRenderable | null) => void;
+}) {
+  return (
+    <scrollbox
+      ref={scrollRef}
+      height={viewHeight}
+      scrollY={true}
+      focused={isActive}
+      viewportCulling={false}
+    >
+      {lines.map((line, i) => (
+        <text key={i}>{line || ' '}</text>
+      ))}
+    </scrollbox>
+  );
+}
+
+function StatusBar({
+  tabCount,
+  quitConfirmPending,
+  focusMode,
+  showHelpHint,
+}: {
+  tabCount: number;
+  quitConfirmPending: boolean;
+  focusMode: boolean;
+  showHelpHint: boolean;
+}) {
+  if (quitConfirmPending) {
+    return (
+      <box>
+        <box style={{ backgroundColor: '#FFFF00' }}>
+          <text fg="#000000"> Press q again to quit, any other key to cancel </text>
+        </box>
+      </box>
+    );
+  }
+
+  if (focusMode) {
+    return (
+      <box flexDirection="row">
+        <box style={{ backgroundColor: '#00FFFF' }}>
+          <text fg="#000000"> INPUT MODE </text>
+        </box>
+        <text fg="#666666"> Press Esc to exit input mode</text>
+      </box>
+    );
+  }
+
+  return (
+    <box>
+      <text fg="#666666">
+        [{'\u2191\u2193'}] scroll | [Tab/1-{tabCount}] switch | [i]nput | [r]estart | [k]ill |
+        [q]uit{showHelpHint && ' | Press ? for help'}
+      </text>
+    </box>
+  );
+}
+
+/**
+ * Normalize OpenTUI's KeyEvent to the shared NormalizedKeyEvent format.
+ */
+function normalizeOpenTUIKeyEvent(event: KeyEvent): NormalizedKeyEvent {
+  const { name, ctrl, shift, meta, sequence } = event;
+
+  // Map OpenTUI key names to normalized names
+  let normalizedName: string | undefined;
+  if (name === 'escape') normalizedName = 'escape';
+  else if (name === 'return') normalizedName = 'return';
+  else if (name === 'tab') normalizedName = 'tab';
+  else if (name === 'backspace') normalizedName = 'backspace';
+  else if (name === 'delete') normalizedName = 'delete';
+  else if (name === 'up') normalizedName = 'up';
+  else if (name === 'down') normalizedName = 'down';
+  else if (name === 'left') normalizedName = 'left';
+  else if (name === 'right') normalizedName = 'right';
+  else if (name === 'pageup') normalizedName = 'pageup';
+  else if (name === 'pagedown') normalizedName = 'pagedown';
+  else normalizedName = name;
+
+  return {
+    char: sequence || undefined,
+    name: normalizedName,
+    ctrl,
+    shift,
+    meta,
+  };
+}
+
+export function TabbedView({
+  tabs,
+  activeIndex,
+  onActiveIndexChange,
+  onQuit,
+  onQuitRequest,
+  onRestart,
+  onKill,
+  quitConfirmPending,
+  focusMode,
+  onEnterFocusMode,
+  onExitFocusMode,
+  onSendInput,
+  scrollRef,
+  helpVisible,
+  onToggleHelp,
+  onCloseHelp,
+}: TabbedViewProps): React.ReactNode {
+  const { height: rows } = useTerminalDimensions();
+
+  const terminalHeight = rows ?? 24;
+  const viewHeight = Math.max(5, terminalHeight - 6);
+
+  // Use shared tabs state hook
+  // Note: OpenTUI's scrollbox handles scrolling natively, so we don't use scrollBy here
+  const { showHelpHint, switchTab, nextTab, prevTab, scrollBy } = useTabsState({
+    tabs,
+    activeIndex,
+    onActiveIndexChange,
+    viewHeight,
+  });
+
+  // Use shared callback refs hook
+  const callbacks: KeyboardCallbacks = {
+    onQuit,
+    onQuitRequest,
+    onRestart,
+    onKill,
+    onEnterFocusMode,
+    onExitFocusMode,
+    onSendInput,
+    onToggleHelp,
+    onCloseHelp,
+  };
+  const callbackRefs = useKeyboardCallbackRefs(callbacks);
+
+  useKeyboard((event: KeyEvent) => {
+    const normalizedEvent = normalizeOpenTUIKeyEvent(event);
+    const action = processKeyEvent(
+      normalizedEvent,
+      {
+        helpVisible,
+        focusMode,
+        quitConfirmPending,
+        activeIndex,
+        tabCount: tabs.length,
+      },
+      viewHeight
+    );
+
+    // For OpenTUI, we skip scroll actions since native scrollbox handles them
+    if (action.type === 'scroll') {
+      // OpenTUI's scrollbox handles up/down/pageup/pagedown natively
+      return;
+    }
+
+    executeKeyboardAction(action, callbackRefs, scrollBy, switchTab, nextTab, prevTab);
+  });
+
+  const activeTab = tabs[activeIndex];
+  if (!activeTab) {
+    return <text>No tabs available</text>;
+  }
+
+  return (
+    <box flexDirection="column" padding={1}>
+      <TabBar tabs={tabs} activeIndex={activeIndex} focusMode={focusMode} />
+      <box
+        border={['top', 'bottom']}
+        borderStyle="single"
+        borderColor="#666666"
+        height={viewHeight + 2}
+      >
+        <OutputView
+          lines={activeTab.output}
+          viewHeight={viewHeight}
+          isActive={true}
+          scrollRef={scrollRef}
+        />
+      </box>
+      <StatusBar
+        tabCount={tabs.length}
+        quitConfirmPending={quitConfirmPending}
+        focusMode={focusMode}
+        showHelpHint={showHelpHint}
+      />
+
+      {/* Help overlay - rendered on top */}
+      {helpVisible && (
+        <box
+          position="absolute"
+          flexDirection="column"
+          alignItems="center"
+          justifyContent="center"
+          width="100%"
+          height="100%"
+        >
+          <HelpOverlay onClose={onCloseHelp} />
+        </box>
+      )}
+    </box>
+  );
+}

package/src/tabs-app.tsx

@@ -0,0 +1,391 @@
+/**
+ * Tabs App for OpenTUI
+ *
+ * Wires ProcessManager from core to React state.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { spawn, type ChildProcess } from 'node:child_process';
+import stripAnsi from 'strip-ansi';
+import { TabbedView } from './tabbed-view.js';
+import {
+  OutputBuffer,
+  MAX_OUTPUT_LINES,
+  MAX_LINE_LENGTH,
+  BUFFER_WARNING_THRESHOLD,
+} from '@pokit/tabs-core';
+import type { TabSpec, TabProcess } from '@pokit/tabs-core';
+import type { TabsOptions } from '@pokit/core';
+import type { ScrollBoxRenderable } from '@opentui/core';
+
+const OUTPUT_BATCH_MS = 16;
+/** How many pixels from bottom to consider "near bottom" for auto-scroll */
+const NEAR_BOTTOM_THRESHOLD = 50;
+/** Delay before scrolling to allow React to render new content */
+const SCROLL_DELAY_MS = 50;
+
+type TabsAppProps = {
+  items: TabSpec[];
+  options: TabsOptions;
+  onExit: (code: number) => void;
+};
+
+/** Temporary buffer for batching incoming output before flushing to state */
+type BatchBuffer = {
+  lines: string[];
+};
+
+export function TabsApp({ items, options, onExit }: TabsAppProps): React.ReactNode {
+  // Ring buffers for storing all output per tab (with O(1) operations)
+  const ringBuffersRef = useRef<Map<string, OutputBuffer>>(new Map());
+
+  // Initialize ring buffers for each tab
+  const getOrCreateRingBuffer = useCallback((tabId: string): OutputBuffer => {
+    let buffer = ringBuffersRef.current.get(tabId);
+    if (!buffer) {
+      buffer = new OutputBuffer({
+        maxLines: MAX_OUTPUT_LINES,
+        maxLineLength: MAX_LINE_LENGTH,
+        warnAtPercentage: BUFFER_WARNING_THRESHOLD,
+        tabId,
+        // Optional: could add onPressure callback here for UI feedback
+      });
+      ringBuffersRef.current.set(tabId, buffer);
+    }
+    return buffer;
+  }, []);
+
+  const [tabs, setTabs] = useState<TabProcess[]>(() =>
+    items.map((item, i) => ({
+      id: `tab-${i}`,
+      label: item.label,
+      exec: item.exec,
+      output: [],
+      status: 'running' as const,
+    }))
+  );
+  const [quitConfirmPending, setQuitConfirmPending] = useState(false);
+  const [focusMode, setFocusMode] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [helpVisible, setHelpVisible] = useState(false);
+  const processesRef = useRef<(ChildProcess | null)[]>([]);
+  const batchBuffersRef = useRef<Map<number, BatchBuffer>>(new Map());
+  const flushScheduledRef = useRef(false);
+  const scrollBoxRef = useRef<ScrollBoxRenderable | null>(null);
+
+  /**
+   * Check if the scrollbox is near the bottom.
+   * Returns true if within NEAR_BOTTOM_THRESHOLD pixels of bottom, or if content fits in viewport.
+   */
+  const checkIfNearBottom = useCallback((): boolean => {
+    const scroll = scrollBoxRef.current;
+    if (!scroll) return true;
+
+    const maxScrollTop = Math.max(0, scroll.scrollHeight - scroll.viewport.height);
+    if (maxScrollTop <= 0) return true; // Content fits in viewport
+
+    const distanceFromBottom = maxScrollTop - scroll.scrollTop;
+    return distanceFromBottom <= NEAR_BOTTOM_THRESHOLD;
+  }, []);
+
+  /**
+   * Scroll to bottom immediately (synchronous). Used for tab switches to avoid visible snap.
+   */
+  const scrollToBottomImmediate = useCallback(() => {
+    const scroll = scrollBoxRef.current;
+    if (scroll) {
+      scroll.scrollTo(scroll.scrollHeight);
+    }
+  }, []);
+
+  /**
+   * Scroll to bottom with delay. Called after content updates to let React render first.
+   */
+  const scrollToBottom = useCallback(() => {
+    setTimeout(() => {
+      scrollToBottomImmediate();
+    }, SCROLL_DELAY_MS);
+  }, [scrollToBottomImmediate]);
+
+  const handleScrollRef = useCallback(
+    (ref: ScrollBoxRenderable | null) => {
+      scrollBoxRef.current = ref;
+      // Initial scroll to bottom when ref is set - immediate to avoid snap
+      if (ref) {
+        scrollToBottomImmediate();
+      }
+    },
+    [scrollToBottomImmediate]
+  );
+
+  const flushOutput = useCallback(() => {
+    flushScheduledRef.current = false;
+
+    const buffersSnapshot = batchBuffersRef.current;
+    batchBuffersRef.current = new Map();
+
+    if (buffersSnapshot.size === 0) return;
+
+    const updates: Array<{ index: number; lines: string[] }> = [];
+    for (const [index, buffer] of buffersSnapshot.entries()) {
+      if (buffer.lines.length > 0) {
+        updates.push({ index, lines: buffer.lines });
+      }
+    }
+
+    if (updates.length === 0) return;
+
+    // Check if near bottom BEFORE updating state (while old content is rendered)
+    const wasNearBottom = checkIfNearBottom();
+
+    setTabs((prev) => {
+      const next = [...prev];
+      for (const { index, lines } of updates) {
+        const tab = next[index];
+        if (!tab) continue;
+
+        // Push to ring buffer and get output with dropped indicator
+        const ringBuffer = getOrCreateRingBuffer(tab.id);
+        ringBuffer.push(...lines);
+        next[index] = { ...tab, output: ringBuffer.toArray() };
+      }
+      return next;
+    });
+
+    // If we were near bottom, scroll to bottom after content updates
+    if (wasNearBottom) {
+      scrollToBottom();
+    }
+  }, [checkIfNearBottom, scrollToBottom, getOrCreateRingBuffer]);
+
+  const scheduleFlush = useCallback(() => {
+    if (flushScheduledRef.current) return;
+    flushScheduledRef.current = true;
+    setTimeout(flushOutput, OUTPUT_BATCH_MS);
+  }, [flushOutput]);
+
+  const appendOutput = useCallback(
+    (index: number, data: Buffer) => {
+      const rawText = data.toString('utf-8');
+      // Strip ALL ANSI sequences to prevent rendering artifacts
+      // We lose colors but gain reliable scrolling
+      const text = stripAnsi(rawText)
+        // Also convert lone carriage returns to newlines (progress bars)
+        .replace(/\r(?!\n)/g, '\n');
+      const lines = text.split(/\r?\n/).filter((line, idx, arr) => {
+        return line || idx < arr.length - 1;
+      });
+
+      if (lines.length === 0) return;
+
+      let buffer = batchBuffersRef.current.get(index);
+      if (!buffer) {
+        buffer = { lines: [] };
+        batchBuffersRef.current.set(index, buffer);
+      }
+      buffer.lines.push(...lines);
+
+      scheduleFlush();
+    },
+    [scheduleFlush]
+  );
+
+  const spawnProcess = useCallback(
+    (index: number): ChildProcess | null => {
+      const item = items[index];
+      if (!item) return null;
+
+      const proc = spawn('sh', ['-c', item.exec], {
+        cwd: options.cwd,
+        env: {
+          ...options.env,
+          FORCE_COLOR: '1',
+        } as NodeJS.ProcessEnv,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+
+      const handleData = (data: Buffer) => appendOutput(index, data);
+
+      proc.stdout?.on('data', handleData);
+      proc.stderr?.on('data', handleData);
+
+      proc.on('close', (code) => {
+        flushOutput();
+        setTabs((prev) => {
+          const next = [...prev];
+          const tab = next[index];
+          if (!tab) return prev;
+          next[index] = {
+            ...tab,
+            status: code === 0 ? 'done' : 'error',
+            exitCode: code ?? undefined,
+          };
+          return next;
+        });
+      });
+
+      proc.on('error', (err) => {
+        setTabs((prev) => {
+          const next = [...prev];
+          const tab = next[index];
+          if (!tab) return prev;
+          next[index] = {
+            ...tab,
+            status: 'error',
+            output: [...tab.output, `Error: ${err.message}`],
+          };
+          return next;
+        });
+      });
+
+      return proc;
+    },
+    [items, options.cwd, options.env, appendOutput, flushOutput]
+  );
+
+  useEffect(() => {
+    const procs = items.map((_, i) => spawnProcess(i));
+    processesRef.current = procs;
+
+    return () => {
+      for (const proc of processesRef.current) {
+        if (proc && !proc.killed) {
+          proc.kill('SIGTERM');
+        }
+      }
+    };
+  }, [items, spawnProcess]);
+
+  const killAll = useCallback(() => {
+    for (const proc of processesRef.current) {
+      if (proc && !proc.killed) {
+        proc.kill('SIGTERM');
+      }
+    }
+  }, []);
+
+  const handleRestart = useCallback(
+    (index: number) => {
+      const existingProc = processesRef.current[index];
+      if (existingProc && !existingProc.killed) {
+        existingProc.kill('SIGTERM');
+      }
+
+      // Clear both batch buffer and ring buffer
+      batchBuffersRef.current.delete(index);
+      const tabId = `tab-${index}`;
+      ringBuffersRef.current.get(tabId)?.clear();
+
+      setTabs((prev) => {
+        const next = [...prev];
+        const tab = next[index];
+        if (!tab) return prev;
+        next[index] = {
+          ...tab,
+          output: ['Restarting...', ''],
+          status: 'running',
+          exitCode: undefined,
+        };
+        return next;
+      });
+
+      // Scroll to bottom after restart since output is cleared
+      scrollToBottom();
+
+      setTimeout(() => {
+        const newProc = spawnProcess(index);
+        processesRef.current[index] = newProc;
+      }, 100);
+    },
+    [spawnProcess, scrollToBottom]
+  );
+
+  const handleKill = useCallback((index: number) => {
+    const proc = processesRef.current[index];
+    if (proc && !proc.killed) {
+      proc.kill('SIGTERM');
+    }
+
+    setTabs((prev) => {
+      const next = [...prev];
+      const tab = next[index];
+      if (!tab) return prev;
+      if (tab.status !== 'running') return prev;
+      next[index] = {
+        ...tab,
+        status: 'stopped',
+        output: [...tab.output, '', 'Stopped'],
+      };
+      return next;
+    });
+  }, []);
+
+  const handleQuitRequest = useCallback(() => {
+    setQuitConfirmPending((prev) => !prev);
+  }, []);
+
+  const handleQuit = useCallback(() => {
+    killAll();
+    onExit(0);
+  }, [killAll, onExit]);
+
+  const handleEnterFocusMode = useCallback(() => {
+    const proc = processesRef.current[activeIndex];
+    if (proc && !proc.killed && proc.stdin) {
+      setFocusMode(true);
+    }
+  }, [activeIndex]);
+
+  const handleExitFocusMode = useCallback(() => {
+    setFocusMode(false);
+  }, []);
+
+  const handleSendInput = useCallback(
+    (data: string) => {
+      const proc = processesRef.current[activeIndex];
+      if (proc && !proc.killed && proc.stdin) {
+        proc.stdin.write(data);
+      }
+    },
+    [activeIndex]
+  );
+
+  const handleActiveIndexChange = useCallback(
+    (index: number) => {
+      setActiveIndex(index);
+      setFocusMode(false);
+      // Scroll to bottom when switching tabs
+      scrollToBottom();
+    },
+    [scrollToBottom]
+  );
+
+  const handleToggleHelp = useCallback(() => {
+    setHelpVisible((prev) => !prev);
+  }, []);
+
+  const handleCloseHelp = useCallback(() => {
+    setHelpVisible(false);
+  }, []);
+
+  return (
+    <TabbedView
+      tabs={tabs}
+      activeIndex={activeIndex}
+      onActiveIndexChange={handleActiveIndexChange}
+      onQuit={handleQuit}
+      onQuitRequest={handleQuitRequest}
+      onRestart={handleRestart}
+      onKill={handleKill}
+      quitConfirmPending={quitConfirmPending}
+      focusMode={focusMode}
+      onEnterFocusMode={handleEnterFocusMode}
+      onExitFocusMode={handleExitFocusMode}
+      onSendInput={handleSendInput}
+      scrollRef={handleScrollRef}
+      helpVisible={helpVisible}
+      onToggleHelp={handleToggleHelp}
+      onCloseHelp={handleCloseHelp}
+    />
+  );
+}

package/src/use-event-bus.ts

@@ -0,0 +1,28 @@
+/**
+ * React Hook for EventBus
+ *
+ * Provides a hook to subscribe to EventBus events and manage state.
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import type { EventBus, CLIEvent } from '@pokit/core';
+import type { EventDrivenState } from '@pokit/tabs-core';
+import { createInitialState, reducer } from '@pokit/tabs-core';
+
+/**
+ * Hook to subscribe to EventBus and manage state
+ */
+export function useEventBus(bus: EventBus): EventDrivenState {
+  const [state, setState] = useState<EventDrivenState>(createInitialState);
+
+  const handleEvent = useCallback((event: CLIEvent) => {
+    setState((prevState) => reducer(prevState, event));
+  }, []);
+
+  useEffect(() => {
+    const unsubscribe = bus.on(handleEvent);
+    return unsubscribe;
+  }, [bus, handleEvent]);
+
+  return state;
+}