magi-ai 0.1.0

package/dist/src/tui/index.js

@@ -0,0 +1,3 @@
+export { MagiTui } from './magi-tui.js';
+export { detectCapabilities, isTuiCapable, tuiCheckFailure } from './terminal-detect.js';
+export { getTuiProfile } from './layout.js';

package/dist/src/tui/keypress.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Stdin helpers for TUI keyboard handling.
+ */
+export type TuiKey = '1' | '2' | '3' | 'q' | 'escape' | 'other';
+/**
+ * Suppress stdin echo by setting raw mode and consuming all input.
+ * Returns a cleanup function to restore stdin to its original state.
+ * Prevents escape sequences (^[[B, ^[[A, etc.) from leaking to stdout.
+ */
+export declare function suppressStdin(onKey?: (key: TuiKey) => void): () => void;
+/**
+ * Wait for a single keypress from stdin.
+ * If stdin is not a TTY, falls back to a 3-second timeout.
+ */
+export declare function waitForKeypress(): Promise<void>;
+/**
+ * Parse a raw stdin Buffer into TuiKey events.
+ *
+ * Properly skips CSI (`\x1b[...`) and SS3 (`\x1bO.`) escape sequences
+ * so that arrow keys, function keys, and modifier combos are never
+ * misinterpreted as literal '1'/'2'/'3' or 'escape'.
+ *
+ * A bare `\x1b` (with no following `[` or `O`) is the real Escape key.
+ */
+export declare function normalizeKeys(chunk: Buffer): TuiKey[];

package/dist/src/tui/keypress.js

@@ -0,0 +1,95 @@
+/**
+ * Stdin helpers for TUI keyboard handling.
+ */
+/**
+ * Suppress stdin echo by setting raw mode and consuming all input.
+ * Returns a cleanup function to restore stdin to its original state.
+ * Prevents escape sequences (^[[B, ^[[A, etc.) from leaking to stdout.
+ */
+export function suppressStdin(onKey) {
+    if (!process.stdin.isTTY)
+        return () => { };
+    const wasRaw = process.stdin.isRaw;
+    const wasFlowing = process.stdin.readableFlowing;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    // Consume all input silently
+    const drain = (chunk) => {
+        if (!onKey)
+            return;
+        for (const key of normalizeKeys(chunk)) {
+            onKey(key);
+        }
+    };
+    process.stdin.on('data', drain);
+    return () => {
+        process.stdin.removeListener('data', drain);
+        process.stdin.setRawMode(wasRaw ?? false);
+        if (!wasFlowing)
+            process.stdin.pause();
+    };
+}
+/**
+ * Wait for a single keypress from stdin.
+ * If stdin is not a TTY, falls back to a 3-second timeout.
+ */
+export function waitForKeypress() {
+    if (!process.stdin.isTTY) {
+        return new Promise(resolve => setTimeout(resolve, 3000));
+    }
+    return new Promise(resolve => {
+        // stdin is already in raw mode from suppressStdin(), just listen for data
+        const handler = () => {
+            process.stdin.removeListener('data', handler);
+            resolve();
+        };
+        process.stdin.on('data', handler);
+    });
+}
+/**
+ * Parse a raw stdin Buffer into TuiKey events.
+ *
+ * Properly skips CSI (`\x1b[...`) and SS3 (`\x1bO.`) escape sequences
+ * so that arrow keys, function keys, and modifier combos are never
+ * misinterpreted as literal '1'/'2'/'3' or 'escape'.
+ *
+ * A bare `\x1b` (with no following `[` or `O`) is the real Escape key.
+ */
+export function normalizeKeys(chunk) {
+    const text = chunk.toString('utf8');
+    const keys = [];
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '\x1b') {
+            const next = text[i + 1];
+            if (next === '[') {
+                // CSI sequence: \x1b[ ... <final byte in @-~ range>
+                i += 2; // skip \x1b[
+                while (i < text.length && !(text[i] >= '@' && text[i] <= '~')) {
+                    i++;
+                }
+                if (i < text.length)
+                    i++; // skip final byte
+                continue;
+            }
+            if (next === 'O') {
+                // SS3 sequence: \x1bO + 1 char
+                i += 3;
+                continue;
+            }
+            // Bare ESC — real escape key press
+            keys.push('escape');
+            i++;
+            continue;
+        }
+        if (ch === '1' || ch === '2' || ch === '3' || ch === 'q') {
+            keys.push(ch);
+        }
+        else if (ch >= ' ') {
+            keys.push('other');
+        }
+        i++;
+    }
+    return keys;
+}

package/dist/src/tui/layout.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Inverted Y-shape layout geometry for the MAGI TUI.
+ *
+ * Layout structure:
+ *   [Header]           — top 5 rows
+ *   [Main area]        — BALTHASAR(top), MAGI node(center), CASPER(left), MELCHIOR(right)
+ *   [Activity log]     — 3 rows above status bar
+ *   [Status bar]       — bottom 2 rows
+ */
+export declare const HEADER_HEIGHT = 5;
+export declare const STATUS_BAR_HEIGHT = 2;
+export declare const ACTIVITY_LOG_LINES = 3;
+export declare const MAGI_NODE_WIDTH = 11;
+export declare const MAGI_NODE_HEIGHT = 3;
+export declare const VERDICT_STAMP_WIDTH = 14;
+export declare const VERDICT_STAMP_HEIGHT = 3;
+export declare const MIN_PANEL_WIDTH = 20;
+export declare const MIN_PANEL_HEIGHT = 5;
+export type TuiProfile = 'compact' | 'standard' | 'cinematic';
+export interface Rect {
+    readonly row: number;
+    readonly col: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface Connector {
+    readonly row: number;
+    readonly col: number;
+    readonly char: string;
+}
+export interface MagiLayout {
+    readonly profile: TuiProfile;
+    readonly header: Rect;
+    readonly verdictStamp: Rect;
+    readonly balthasarPanel: Rect;
+    readonly magiNode: Rect;
+    readonly casperPanel: Rect;
+    readonly melchiorPanel: Rect;
+    readonly connectors: Connector[];
+    readonly activityLog: Rect;
+    readonly statusBar: Rect;
+    readonly outerFrame: Rect;
+}
+export declare const BOX: {
+    readonly h: "─";
+    readonly v: "│";
+    readonly tl: "┌";
+    readonly tr: "┐";
+    readonly bl: "└";
+    readonly br: "┘";
+    readonly lT: "├";
+    readonly rT: "┤";
+    readonly tT: "┬";
+    readonly bT: "┴";
+    readonly x: "┼";
+};
+export declare const BOX_DOUBLE: {
+    readonly h: "═";
+    readonly v: "║";
+    readonly tl: "╔";
+    readonly tr: "╗";
+    readonly bl: "╚";
+    readonly br: "╝";
+};
+export declare const BOX_HEAVY: {
+    readonly h: "━";
+    readonly v: "┃";
+    readonly tl: "┏";
+    readonly tr: "┓";
+    readonly bl: "┗";
+    readonly br: "┛";
+};
+export declare function getTuiProfile(cols: number, rows: number): TuiProfile;
+export declare function calculateLayout(cols: number, rows: number): MagiLayout;

package/dist/src/tui/layout.js

@@ -0,0 +1,171 @@
+/**
+ * Inverted Y-shape layout geometry for the MAGI TUI.
+ *
+ * Layout structure:
+ *   [Header]           — top 5 rows
+ *   [Main area]        — BALTHASAR(top), MAGI node(center), CASPER(left), MELCHIOR(right)
+ *   [Activity log]     — 3 rows above status bar
+ *   [Status bar]       — bottom 2 rows
+ */
+// ── Constants ───────────────────────────────────────────────
+export const HEADER_HEIGHT = 5;
+export const STATUS_BAR_HEIGHT = 2;
+export const ACTIVITY_LOG_LINES = 3;
+export const MAGI_NODE_WIDTH = 11; // "┌─ MAGI ─┐"
+export const MAGI_NODE_HEIGHT = 3;
+export const VERDICT_STAMP_WIDTH = 14;
+export const VERDICT_STAMP_HEIGHT = 3;
+export const MIN_PANEL_WIDTH = 20;
+export const MIN_PANEL_HEIGHT = 5;
+// ── Box-drawing characters ──────────────────────────────────
+export const BOX = {
+    h: '─', v: '│',
+    tl: '┌', tr: '┐', bl: '└', br: '┘',
+    lT: '├', rT: '┤', tT: '┬', bT: '┴', x: '┼',
+};
+export const BOX_DOUBLE = {
+    h: '═', v: '║',
+    tl: '╔', tr: '╗', bl: '╚', br: '╝',
+};
+export const BOX_HEAVY = {
+    h: '━', v: '┃',
+    tl: '┏', tr: '┓', bl: '┗', br: '┛',
+};
+// ── Layout calculation ──────────────────────────────────────
+export function getTuiProfile(cols, rows) {
+    if (cols >= 140 && rows >= 40)
+        return 'cinematic';
+    if (cols >= 100 && rows >= 30)
+        return 'standard';
+    return 'compact';
+}
+export function calculateLayout(cols, rows) {
+    const profile = getTuiProfile(cols, rows);
+    const outerFrame = { row: 0, col: 0, width: cols, height: rows };
+    // Header: top rows
+    const header = { row: 0, col: 0, width: cols, height: HEADER_HEIGHT };
+    const verdictStamp = {
+        row: 1,
+        col: Math.max(2, cols - VERDICT_STAMP_WIDTH - 2),
+        width: Math.min(VERDICT_STAMP_WIDTH, Math.max(10, cols - 4)),
+        height: VERDICT_STAMP_HEIGHT,
+    };
+    // Status bar: bottom rows
+    const statusBar = {
+        row: rows - STATUS_BAR_HEIGHT,
+        col: 0,
+        width: cols,
+        height: STATUS_BAR_HEIGHT,
+    };
+    // Activity log: above status bar
+    const activityLog = {
+        row: rows - STATUS_BAR_HEIGHT - ACTIVITY_LOG_LINES,
+        col: 0,
+        width: cols,
+        height: ACTIVITY_LOG_LINES,
+    };
+    // Main area: between header and activity log.
+    // When terminal is too small, mainHeight may be 0 — panels will overlap
+    // but ScreenBuffer clips out-of-bounds writes so no crash occurs.
+    // A proper fix would enforce MIN_ROWS at the TUI entry point.
+    const mainTop = HEADER_HEIGHT;
+    const mainHeight = Math.max(0, activityLog.row - mainTop);
+    const mainCenter = Math.floor(cols / 2);
+    // --- BALTHASAR panel (top center) ---
+    const baltWidthFactor = profile === 'cinematic' ? 0.5 : profile === 'standard' ? 0.47 : 0.45;
+    const baltHeightFactor = profile === 'cinematic' ? 0.42 : profile === 'standard' ? 0.4 : 0.38;
+    const baltWidth = Math.min(Math.floor(cols * baltWidthFactor), cols - 4);
+    const baltHeight = Math.max(MIN_PANEL_HEIGHT, Math.floor(mainHeight * baltHeightFactor));
+    const baltCol = Math.floor((cols - baltWidth) / 2);
+    const balthasarPanel = {
+        row: mainTop,
+        col: baltCol,
+        width: baltWidth,
+        height: baltHeight,
+    };
+    // --- MAGI node (center junction) ---
+    const magiRow = mainTop + baltHeight;
+    const magiCol = mainCenter - Math.floor(MAGI_NODE_WIDTH / 2);
+    const magiNode = {
+        row: magiRow,
+        col: magiCol,
+        width: MAGI_NODE_WIDTH,
+        height: MAGI_NODE_HEIGHT,
+    };
+    // --- Bottom panels: CASPER (left) and MELCHIOR (right) ---
+    const bottomTop = magiRow + MAGI_NODE_HEIGHT;
+    const bottomHeight = Math.max(MIN_PANEL_HEIGHT, Math.max(0, activityLog.row - bottomTop));
+    const panelWidth = Math.max(MIN_PANEL_WIDTH, Math.floor((cols - (profile === 'compact' ? 6 : 8)) / 2));
+    const gap = cols - panelWidth * 2;
+    const leftCol = Math.floor(gap / 3);
+    const rightCol = leftCol + panelWidth + Math.floor(gap / 3);
+    const casperPanel = {
+        row: bottomTop,
+        col: leftCol,
+        width: panelWidth,
+        height: bottomHeight,
+    };
+    const melchiorPanel = {
+        row: bottomTop,
+        col: rightCol,
+        width: panelWidth,
+        height: bottomHeight,
+    };
+    // --- Connectors (Y-shape lines) ---
+    const connectors = buildConnectors(balthasarPanel, magiNode, casperPanel, melchiorPanel, mainCenter);
+    return {
+        profile,
+        header,
+        verdictStamp,
+        balthasarPanel,
+        magiNode,
+        casperPanel,
+        melchiorPanel,
+        connectors,
+        activityLog,
+        statusBar,
+        outerFrame,
+    };
+}
+function buildConnectors(balt, magi, casper, melchior, centerCol) {
+    const conns = [];
+    // ── BALTHASAR bottom → MAGI top (vertical trunk) ────────────
+    const baltBottomRow = balt.row + balt.height;
+    // Junction on BALTHASAR bottom border center
+    conns.push({ row: baltBottomRow - 1, col: centerCol, char: BOX.bT });
+    // Vertical lines between BALTHASAR bottom and MAGI top
+    for (let r = baltBottomRow; r < magi.row; r++) {
+        conns.push({ row: r, col: centerCol, char: BOX.v });
+    }
+    // Junction on MAGI top border center (connector enters MAGI from above)
+    conns.push({ row: magi.row, col: centerCol, char: BOX.tT });
+    // ── MAGI bottom → Y-split (trunk continues down) ───────────
+    const magiBottomBorder = magi.row + magi.height - 1;
+    const magiBottomRow = magi.row + magi.height;
+    // Junction on MAGI bottom border center (connector exits down)
+    conns.push({ row: magiBottomBorder, col: centerCol, char: BOX.bT });
+    // Vertical lines between MAGI bottom and bottom panels
+    for (let r = magiBottomRow; r < casper.row; r++) {
+        conns.push({ row: r, col: centerCol, char: BOX.v });
+    }
+    // ── Y-split into CASPER (left) and MELCHIOR (right) ─────────
+    const casperRight = casper.col + casper.width - 1;
+    const melchiorLeft = melchior.col;
+    const splitRow = casper.row;
+    // Horizontal branches at the split row (overwrite panel top borders)
+    // Left branch: center → CASPER's top-right
+    for (let c = casperRight + 1; c < centerCol; c++) {
+        conns.push({ row: splitRow, col: c, char: BOX.h });
+    }
+    // Junction at CASPER's top-right corner (┐ → ┤ to accept horizontal)
+    conns.push({ row: splitRow, col: casperRight, char: BOX.rT });
+    // Right branch: center → MELCHIOR's top-left
+    for (let c = centerCol + 1; c < melchiorLeft; c++) {
+        conns.push({ row: splitRow, col: c, char: BOX.h });
+    }
+    // Junction at MELCHIOR's top-left corner (┌ → ├ to accept horizontal)
+    conns.push({ row: splitRow, col: melchiorLeft, char: BOX.lT });
+    // Central split junction — ┼ (cross) because divider continues downward
+    conns.push({ row: splitRow, col: centerCol, char: BOX.x });
+    return conns;
+}

package/dist/src/tui/magi-tui.d.ts

@@ -0,0 +1,101 @@
+/**
+ * MagiTui — Main TUI class that orchestrates the Evangelion-themed interface.
+ *
+ * Subscribes to all 17 MagiEventBus events and drives:
+ *   Event → State update → Activity log → Animation → Render → ScreenBuffer → stdout
+ */
+import type { MagiEventBus } from '../engine/events.js';
+export interface MagiTuiOptions {
+    eventBus: MagiEventBus;
+    skipBoot?: boolean;
+    stream?: NodeJS.WritableStream;
+    soundEnabled?: boolean;
+}
+export declare class MagiTui {
+    private buf;
+    private layout;
+    private readonly panelRenderer;
+    private readonly headerRenderer;
+    private readonly statusBarRenderer;
+    private readonly activityLog;
+    private readonly animations;
+    private readonly stream;
+    private readonly eventBus;
+    private readonly skipBoot;
+    private readonly soundEnabled;
+    private unitStates;
+    private headerData;
+    private statusData;
+    private verdictStamp;
+    private elapsedTimer?;
+    private startTime;
+    private renderScheduled;
+    private disposed;
+    private backgroundFilled;
+    private completionPromise?;
+    private stdinCleanup?;
+    private deregisterCleanup?;
+    private dismissResolver?;
+    private tuiPhase;
+    private overlayUnit?;
+    private lastOverlayRect?;
+    private connectorPulseIndex;
+    private berserkFlashActive;
+    private syncRates;
+    private terminalFailure;
+    private boundListeners;
+    private resizeHandler?;
+    constructor(options: MagiTuiOptions);
+    /** Start the TUI: boot sequence → initial draw → event binding. */
+    start(): Promise<void>;
+    /** Clean up: stop animations, unbind events, restore terminal. */
+    dispose(): void;
+    /** Wait for completion animation + keypress before disposing. */
+    waitForDismiss(): Promise<void>;
+    private bindEvents;
+    private on;
+    private onDeliberationStart;
+    private onPhaseStart;
+    private onUnitStart;
+    private onUnitComplete;
+    private onUnitError;
+    private onPhaseSkipped;
+    private onPhaseComplete;
+    private onDeliberationComplete;
+    private onSyncRateUpdated;
+    private onBerserkWarning;
+    private onBiasDetected;
+    private onGospelMilestone;
+    private onUmbilicalStatusChanged;
+    private onDummyPlugActivated;
+    private onDummyPlugRecovery;
+    private onCipherDiscovered;
+    private onMemoryDriftWarning;
+    private onMemoryConsolidated;
+    private onBerserkActivated;
+    /** Shared berserk flash logic — overlay approach (FIX-03 + FIX-06). */
+    private startBerserkFlash;
+    private onBerserkDeactivated;
+    private onInstrumentalityTriggered;
+    private onFusionComplete;
+    private onLCLContamination;
+    private onLCLPurified;
+    private scheduleRender;
+    private render;
+    private buildPanelContent;
+    private buildMagiNodeContent;
+    private handleResize;
+    private startElapsedTimer;
+    private stopElapsedTimer;
+    private getOrCreateUnit;
+    private getTerminalFailure;
+    private renderTerminalWarning;
+    private write;
+    private handleKeypress;
+    /** Resolve pending dismiss promise if in dismiss phase (FIX-02). */
+    private resolveDismiss;
+    private renderDetailOverlay;
+    private playSound;
+    private fillBackgroundRect;
+    private updateLiveActivityStatus;
+}