@pokit/tabs-ink 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pokit/tabs-ink",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Ink-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"
@@ -51,12 +51,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.3",
+    "@pokit/tabs-core": "0.0.3"
   },
   "peerDependencies": {
-    "@pokit/core": "0.0.1",
-    "@pokit/tabs-core": "0.0.1"
+    "@pokit/core": "0.0.3",
+    "@pokit/tabs-core": "0.0.3"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/adapter.tsx

@@ -0,0 +1,223 @@
+/**
+ * Ink-based Tabs Adapter
+ *
+ * Implements the TabsAdapter interface using Ink (React for CLI).
+ * Also provides an event-driven adapter that renders based on EventBus events.
+ */
+import { render, type RenderOptions } from 'ink';
+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 Ink
+ */
+export function createTabsAdapter(): TabsAdapter {
+  return {
+    async run(items: TabSpec[], options: TabsOptions): Promise<void> {
+      // Check stdout TTY
+      if (!process.stdout.isTTY) {
+        throw new Error('Tabbed view requires stdout to be a TTY');
+      }
+
+      // Check stdin TTY - required for keyboard input
+      if (!process.stdin.isTTY) {
+        throw new Error('Tabbed view requires stdin to be a TTY for keyboard input');
+      }
+
+      // Empty items - nothing to do
+      if (items.length === 0) {
+        return;
+      }
+
+      // Switch to alternate screen buffer (like vim/less)
+      // This preserves the main terminal content and provides a clean canvas
+      process.stdout.write('\x1b[?1049h\x1b[H');
+
+      // 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 Ink starts - Ink's internal ref counting may be
+      // out of sync if previous CLI operations (clack prompts/spinners) didn't
+      // properly balance their setRawMode calls
+      process.stdin.setRawMode(true);
+
+      return new Promise<void>((resolve) => {
+        let resolved = false;
+        let unmount: (() => void) | null = null;
+        let clear: (() => void) | null = null;
+
+        // 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 {
+            clear?.();
+            unmount?.();
+          } 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 result = render(
+          <TabsErrorBoundary onFatalError={handleFatalError}>
+            <TabsApp
+              items={items}
+              options={options}
+              onExit={() => {
+                cleanup();
+              }}
+            />
+          </TabsErrorBoundary>,
+          {
+            exitOnCtrlC: false, // We handle quit ourselves
+            incrementalRendering: true, // Only update changed lines to reduce flicker
+          } as RenderOptions
+        );
+
+        unmount = result.unmount;
+        clear = result.clear;
+
+        // Also resolve when ink exits naturally
+        result.waitUntilExit().then(() => {
+          if (!resolved) {
+            cleanup();
+          }
+        });
+      });
+    },
+  };
+}
+
+// =============================================================================
+// Event-Driven Adapter
+// =============================================================================
+
+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 Ink.
+ *
+ * @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');
+  }
+
+  process.stdout.write('\x1b[?1049h\x1b[H');
+
+  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 {
+      clear();
+      unmount();
+    } 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 handleExit = (code: number) => {
+    cleanup();
+    options.onExit?.(code);
+  };
+
+  // Handle fatal errors from error boundary
+  const handleFatalError = () => {
+    cleanup();
+  };
+
+  const { unmount, clear } = render(
+    <TabsErrorBoundary onFatalError={handleFatalError}>
+      <EventDrivenApp bus={bus} onExit={handleExit} />
+    </TabsErrorBoundary>,
+    {
+      exitOnCtrlC: false,
+      incrementalRendering: true,
+    } as RenderOptions
+  );
+
+  return {
+    unmount: cleanup,
+  };
+}

package/src/error-boundary.tsx

@@ -0,0 +1,90 @@
+/**
+ * Error Boundary for Tabs UI
+ *
+ * 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 { Component, type ReactNode, type ErrorInfo } from 'react';
+import { Text, Box } from 'ink';
+
+export type ErrorBoundaryProps = {
+  children: ReactNode;
+  onFatalError?: (error: Error, errorInfo: 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
+    }
+  }
+}
+
+/**
+ * React Error Boundary that ensures terminal cleanup on crashes.
+ */
+export class TabsErrorBoundary extends 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: 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(): ReactNode {
+    if (this.state.hasError) {
+      // Show minimal error message - terminal should already be restored
+      return (
+        <Box flexDirection="column" padding={1}>
+          <Text color="red" bold>
+            TabsUI encountered a fatal error
+          </Text>
+          <Text color="gray">{this.state.error?.message ?? 'Unknown error'}</Text>
+          <Text color="gray" dimColor>
+            Press Ctrl+C to exit
+          </Text>
+        </Box>
+      );
+    }
+
+    return this.props.children;
+  }
+}

package/src/event-driven-app.tsx

@@ -0,0 +1,249 @@
+/**
+ * Event-Driven CLI App
+ *
+ * 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 { Box, Text, useInput, useStdout } from 'ink';
+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,
+  inverse,
+}: {
+  status: ActivityNode['status'];
+  inverse?: boolean;
+}) {
+  switch (status) {
+    case 'running':
+      return { color: inverse ? 'cyanBright' : 'cyan', icon: '●' };
+    case 'success':
+      return { color: inverse ? 'greenBright' : 'green', icon: '✓' };
+    case 'failure':
+      return { color: inverse ? 'redBright' : 'red', icon: '✗' };
+  }
+}
+
+function ActivityTabBar({
+  activities,
+  activeIndex,
+}: {
+  activities: ActivityNode[];
+  activeIndex: number;
+}) {
+  return (
+    <Box gap={1} flexWrap="wrap">
+      {activities.map((activity, i) => {
+        const isActive = i === activeIndex;
+        const { color, icon } = getStatusIndicator({
+          status: activity.status,
+          inverse: isActive,
+        });
+        return (
+          <Box key={activity.id}>
+            <Text inverse={isActive} color={color}>
+              {' '}
+              {icon}{' '}
+            </Text>
+            <Text inverse={isActive}> {activity.label}</Text>
+            <Text inverse={isActive}>
+              {' ('}
+              {i + 1}
+              {') '}
+            </Text>
+          </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 color="cyan">{activity.message}</Text>}
+      {activity.progress !== undefined && (
+        <Text color="yellow">Progress: {activity.progress}%</Text>
+      )}
+      {logs.map((log, i) => {
+        let color: string | undefined;
+        switch (log.level) {
+          case 'error':
+            color = 'red';
+            break;
+          case 'warn':
+            color = 'yellow';
+            break;
+          case 'success':
+            color = 'green';
+            break;
+          case 'info':
+            color = 'blue';
+            break;
+          default:
+            color = undefined;
+        }
+        return (
+          <Text key={i} color={color} wrap="truncate">
+            {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>
+        <Text backgroundColor="yellow" color="black">
+          {' '}
+          Press q again to quit, any other key to cancel{' '}
+        </Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box>
+      <Text dimColor>[Tab/1-{activityCount}] switch | [q]uit</Text>
+    </Box>
+  );
+}
+
+export function EventDrivenApp({ bus, onExit }: EventDrivenAppProps) {
+  const state = useEventBus(bus);
+  const { stdout } = useStdout();
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [quitConfirmPending, setQuitConfirmPending] = useState(false);
+
+  const terminalHeight = stdout?.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]);
+
+  useInput(
+    (input, key) => {
+      if (quitConfirmPending) {
+        if (input === 'q') {
+          handleQuit();
+        } else {
+          handleQuitRequest();
+        }
+        return;
+      }
+
+      if (input === 'q') {
+        handleQuitRequest();
+        return;
+      }
+
+      if (input === 'c' && key.ctrl) {
+        handleQuit();
+        return;
+      }
+
+      const num = parseInt(input, 10);
+      if (num >= 1 && num <= activities.length) {
+        switchTab(num - 1);
+        return;
+      }
+
+      if (key.tab && key.shift) {
+        switchTab((activeIndex - 1 + activities.length) % activities.length);
+        return;
+      }
+      if (key.tab) {
+        switchTab((activeIndex + 1) % activities.length);
+        return;
+      }
+    },
+    { isActive: true }
+  );
+
+  if (activities.length === 0) {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Text>Waiting for activities...</Text>
+        {state.appName && (
+          <Text dimColor>
+            {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
+        borderLeft={false}
+        borderRight={false}
+        borderStyle="single"
+        borderColor="gray"
+        paddingX={1}
+      >
+        <ActivityView activity={activeActivity} viewHeight={viewHeight} />
+      </Box>
+      <StatusBar activityCount={activities.length} quitConfirmPending={quitConfirmPending} />
+    </Box>
+  );
+}

package/src/help-overlay.tsx

@@ -0,0 +1,40 @@
+import { Box, Text } from 'ink';
+import { HELP_CONTENT } from '@pokit/tabs-core';
+
+export type HelpOverlayProps = {
+  onClose: () => void;
+};
+
+export function HelpOverlay(_props: HelpOverlayProps) {
+  return (
+    <Box flexDirection="column" borderStyle="single" borderColor="blue" paddingX={2} paddingY={1}>
+      <Box justifyContent="center" marginBottom={1}>
+        <Text bold>Keyboard Help</Text>
+      </Box>
+
+      {HELP_CONTENT.map((group, i) => (
+        <Box
+          key={group.title}
+          flexDirection="column"
+          marginBottom={i < HELP_CONTENT.length - 1 ? 1 : 0}
+        >
+          <Text bold color="cyan">
+            {group.title}
+          </Text>
+          {group.shortcuts.map(({ key, description }) => (
+            <Box key={key}>
+              <Box width={16}>
+                <Text color="yellow">{key}</Text>
+              </Box>
+              <Text>{description}</Text>
+            </Box>
+          ))}
+        </Box>
+      ))}
+
+      <Box marginTop={1} justifyContent="center">
+        <Text dimColor>Press ? or Escape to close</Text>
+      </Box>
+    </Box>
+  );
+}

package/src/tabbed-view.tsx

@@ -0,0 +1,347 @@
+import { Box, Text, useInput, useStdout } from 'ink';
+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;
+  helpVisible: boolean;
+  onToggleHelp: () => void;
+  onCloseHelp: () => void;
+};
+
+function getStatusIndicator({
+  status,
+  inverse,
+}: {
+  status: TabProcess['status'];
+  inverse?: boolean;
+}) {
+  switch (status) {
+    case 'running':
+      return { color: inverse ? 'cyanBright' : 'cyan', icon: '●' };
+    case 'done':
+      return { color: inverse ? 'greenBright' : 'green', icon: '✓' };
+    case 'error':
+      return { color: inverse ? 'redBright' : 'red', icon: '✗' };
+    case 'stopped':
+      return { color: inverse ? 'yellowBright' : 'yellow', icon: '■' };
+  }
+}
+
+function TabBar({
+  tabs,
+  activeIndex,
+  focusMode,
+}: {
+  tabs: TabProcess[];
+  activeIndex: number;
+  focusMode: boolean;
+}) {
+  return (
+    <Box gap={1} flexWrap="wrap">
+      {tabs.map((tab, i) => {
+        const isActive = i === activeIndex;
+        const { color, icon } = getStatusIndicator({
+          status: tab.status,
+          inverse: isActive,
+        });
+        return (
+          <Box key={tab.id}>
+            <Text inverse={isActive} color={color}>
+              {' '}
+              {icon}{' '}
+            </Text>
+            <Text inverse={isActive}> {tab.label}</Text>
+            <Text inverse={isActive}>
+              {' ('}
+              {i + 1}
+              {') '}
+            </Text>
+          </Box>
+        );
+      })}
+      {focusMode && (
+        <Text backgroundColor="yellow" color="black">
+          {' INPUT MODE '}
+        </Text>
+      )}
+    </Box>
+  );
+}
+
+function OutputView({
+  lines,
+  scrollOffset,
+  viewHeight,
+  canScrollUp,
+  canScrollDown,
+}: {
+  lines: string[];
+  scrollOffset: number;
+  viewHeight: number;
+  canScrollUp: boolean;
+  canScrollDown: boolean;
+}) {
+  const visibleLines = lines.slice(scrollOffset, scrollOffset + viewHeight);
+
+  return (
+    <Box flexDirection="column" height={viewHeight} overflow="hidden">
+      {visibleLines.map((line, i) => {
+        // Show scroll indicator on first two lines
+        let prefix = '  ';
+        if (i === 0 && canScrollUp) prefix = '↑ ';
+        else if (i === 1 && canScrollDown) prefix = '↓ ';
+
+        return (
+          <Text key={i} wrap="truncate" dimColor={i < 2 && prefix !== '  '}>
+            <Text dimColor>{prefix}</Text>
+            <Text>{line || ' '}</Text>
+          </Text>
+        );
+      })}
+      {/* Fill remaining space with empty lines */}
+      {Array.from({
+        length: Math.max(0, viewHeight - visibleLines.length),
+      }).map((_, i) => {
+        const lineIndex = visibleLines.length + i;
+        let prefix = '  ';
+        if (lineIndex === 0 && canScrollUp) prefix = '↑ ';
+        else if (lineIndex === 1 && canScrollDown) prefix = '↓ ';
+
+        return (
+          <Text key={`empty-${i}`}>
+            <Text dimColor>{prefix}</Text>
+            <Text> </Text>
+          </Text>
+        );
+      })}
+    </Box>
+  );
+}
+
+function StatusBar({
+  tabCount,
+  quitConfirmPending,
+  focusMode,
+  showHelpHint,
+}: {
+  tabCount: number;
+  quitConfirmPending: boolean;
+  focusMode: boolean;
+  showHelpHint: boolean;
+}) {
+  if (quitConfirmPending) {
+    return (
+      <Box>
+        <Text backgroundColor="yellow" color="black">
+          {' '}
+          Press q again to quit, any other key to cancel{' '}
+        </Text>
+      </Box>
+    );
+  }
+
+  if (focusMode) {
+    return (
+      <Box>
+        <Text backgroundColor="cyan" color="black">
+          {' '}
+          INPUT MODE{' '}
+        </Text>
+        <Text dimColor> Press Esc to exit input mode</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box>
+      <Text dimColor>
+        [↑↓] scroll | [Tab/1-{tabCount}] switch | [i]nput | [r]estart | [k]ill | [q]uit
+        {showHelpHint && ' | Press ? for help'}
+      </Text>
+    </Box>
+  );
+}
+
+/**
+ * Normalize Ink's useInput key event to the shared NormalizedKeyEvent format.
+ */
+function normalizeInkKeyEvent(
+  input: string,
+  key: {
+    upArrow: boolean;
+    downArrow: boolean;
+    leftArrow: boolean;
+    rightArrow: boolean;
+    return: boolean;
+    escape: boolean;
+    ctrl: boolean;
+    shift: boolean;
+    meta: boolean;
+    tab: boolean;
+    backspace: boolean;
+    delete: boolean;
+    pageUp: boolean;
+    pageDown: boolean;
+  }
+): NormalizedKeyEvent {
+  // Map Ink key properties to normalized key names
+  let name: string | undefined;
+  if (key.escape) name = 'escape';
+  else if (key.return) name = 'return';
+  else if (key.tab) name = 'tab';
+  else if (key.backspace) name = 'backspace';
+  else if (key.delete) name = 'delete';
+  else if (key.upArrow) name = 'up';
+  else if (key.downArrow) name = 'down';
+  else if (key.leftArrow) name = 'left';
+  else if (key.rightArrow) name = 'right';
+  else if (key.pageUp) name = 'pageup';
+  else if (key.pageDown) name = 'pagedown';
+
+  return {
+    char: input || undefined,
+    name,
+    ctrl: key.ctrl,
+    shift: key.shift,
+    meta: key.meta,
+  };
+}
+
+export function TabbedView({
+  tabs,
+  activeIndex,
+  onActiveIndexChange,
+  onQuit,
+  onQuitRequest,
+  onRestart,
+  onKill,
+  quitConfirmPending,
+  focusMode,
+  onEnterFocusMode,
+  onExitFocusMode,
+  onSendInput,
+  helpVisible,
+  onToggleHelp,
+  onCloseHelp,
+}: TabbedViewProps) {
+  const { stdout } = useStdout();
+
+  // Calculate view height based on terminal size
+  // Reserve space for: padding (2) + tab bar (1) + border (2) + status bar (1) = 6
+  const terminalHeight = stdout?.rows ?? 24;
+  const viewHeight = Math.max(5, terminalHeight - 6);
+
+  // Use shared tabs state hook
+  const {
+    showHelpHint,
+    activeScrollOffset,
+    canScrollUp,
+    canScrollDown,
+    scrollBy,
+    switchTab,
+    nextTab,
+    prevTab,
+  } = 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);
+
+  // Keyboard handling via useInput - always active
+  useInput((input, key) => {
+    const normalizedEvent = normalizeInkKeyEvent(input, key);
+    const action = processKeyEvent(
+      normalizedEvent,
+      {
+        helpVisible,
+        focusMode,
+        quitConfirmPending,
+        activeIndex,
+        tabCount: tabs.length,
+      },
+      viewHeight
+    );
+    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
+        borderLeft={false}
+        borderRight={false}
+        borderStyle="single"
+        borderColor="gray"
+        paddingX={1}
+      >
+        <OutputView
+          lines={activeTab.output}
+          scrollOffset={activeScrollOffset}
+          viewHeight={viewHeight}
+          canScrollUp={canScrollUp}
+          canScrollDown={canScrollDown}
+        />
+      </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,313 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { TabbedView } from './tabbed-view.js';
+import {
+  OutputBuffer,
+  MAX_OUTPUT_LINES,
+  MAX_LINE_LENGTH,
+  BUFFER_WARNING_THRESHOLD,
+} from '@pokit/tabs-core';
+import type { TabProcess } from './types.js';
+import type { TabSpec, TabsOptions } from '@pokit/core';
+
+const OUTPUT_BATCH_MS = 16;
+
+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) {
+  // 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 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;
+
+    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;
+    });
+  }, [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 text = data.toString('utf-8');
+      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;
+
+      // Use 'pipe' for stdin so we can send input in focus mode
+      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;
+      });
+
+      setTimeout(() => {
+        const newProc = spawnProcess(index);
+        processesRef.current[index] = newProc;
+      }, 100);
+    },
+    [spawnProcess]
+  );
+
+  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);
+    // Exit focus mode when switching tabs
+    setFocusMode(false);
+  }, []);
+
+  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}
+      helpVisible={helpVisible}
+      onToggleHelp={handleToggleHelp}
+      onCloseHelp={handleCloseHelp}
+    />
+  );
+}

package/src/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Types for tabs-ink
+ *
+ * Re-exports shared types from @pokit/tabs-core and defines implementation-specific types.
+ */
+
+import type { ChildProcess } from 'node:child_process';
+import type { TabProcess as BaseTabProcess } from '@pokit/tabs-core';
+
+// =============================================================================
+// Re-exports from @pokit/tabs-core
+// =============================================================================
+
+export type { TabStatus, ActivityNode, GroupNode, EventDrivenState } from '@pokit/tabs-core';
+
+export { MAX_OUTPUT_LINES } from '@pokit/tabs-core';
+
+// =============================================================================
+// Implementation-specific types for tabs-ink
+// =============================================================================
+
+/**
+ * Extended TabProcess with ChildProcess reference for process management.
+ * This extends the base TabProcess from tabs-core with Ink-specific fields.
+ */
+export type TabProcess = BaseTabProcess & {
+  /** Reference to the spawned child process (Ink-specific) */
+  process?: ChildProcess;
+};
+
+/**
+ * Props for the TabbedView component (UI-specific)
+ */
+export type TabbedViewProps = {
+  tabs: TabProcess[];
+  onQuit: () => void;
+  onQuitRequest: () => void;
+  quitConfirmPending: boolean;
+};

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;
+}