@hypersocial/cli-games 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,695 @@
+import * as _xterm_xterm from '@xterm/xterm';
+import { Terminal } from '@xterm/xterm';
+import { PhosphorMode } from './themes.js';
+
+/**
+ * Shared utilities for games
+ *
+ * This module provides theme-aware utilities for games.
+ * The theme must be configured by the consuming application via setTheme().
+ */
+
+/**
+ * Set the current theme mode
+ * Call this from your app when the theme changes
+ */
+declare function setTheme(mode: PhosphorMode): void;
+/**
+ * Get the current theme mode
+ */
+declare function getTheme(): PhosphorMode;
+/**
+ * Check if a terminal is valid and can accept writes
+ */
+declare function isTerminalValid(terminal: Terminal | null | undefined): terminal is Terminal;
+/**
+ * Enter alternate screen buffer with state tracking.
+ * Safe to call multiple times - will log warning but not double-enter.
+ *
+ * @param terminal - The xterm terminal instance
+ * @param reason - Description of why we're entering (for debugging)
+ * @returns true if buffer was entered, false if already in buffer or terminal invalid
+ */
+declare function enterAlternateBuffer(terminal: Terminal, reason: string): boolean;
+/**
+ * Exit alternate screen buffer with state tracking.
+ * Safe to call multiple times - will log warning but not double-exit.
+ *
+ * @param terminal - The xterm terminal instance
+ * @param reason - Description of why we're exiting (for debugging)
+ * @returns true if buffer was exited, false if not in buffer or terminal invalid
+ */
+declare function exitAlternateBuffer(terminal: Terminal, reason: string): boolean;
+/**
+ * Check if terminal is currently in alternate buffer
+ */
+declare function isInAlternateBuffer(terminal: Terminal): boolean;
+/**
+ * Force exit alternate buffer without state check (for error recovery)
+ * Use sparingly - prefer exitAlternateBuffer for normal operations
+ */
+declare function forceExitAlternateBuffer(terminal: Terminal, reason: string): void;
+/**
+ * Get theme-appropriate ANSI color escape code
+ */
+declare function getThemeColorCode(mode: PhosphorMode): string;
+/**
+ * Get current theme color code
+ */
+declare function getCurrentThemeColor(): string;
+/**
+ * Check if current theme is a light theme (needs dark text)
+ */
+declare function isLightTheme(): boolean;
+/**
+ * Get a subtle/muted color that blends with the terminal background
+ * Useful for background elements like doors, walls, etc.
+ */
+declare function getSubtleBackgroundColor(): string;
+interface VerticalAnchorOptions {
+    headerRows?: number;
+    footerRows?: number;
+    minTop?: number;
+}
+/**
+ * Compute a vertically-centered top row for content while reserving header/footer space.
+ */
+declare function getVerticalAnchor(terminalRows: number, contentRows: number, options?: VerticalAnchorOptions): number;
+
+/**
+ * Game Transitions - Centralized hacker-style transition effects
+ *
+ * Provides cinematic transitions for game entry, exit, and switching.
+ * Games don't need to know about these - they just dispatch events.
+ */
+
+/**
+ * Boot transition - plays before game starts
+ */
+declare function playBootTransition(terminal: Terminal): Promise<void>;
+/**
+ * Exit transition - plays when game quits back to shell
+ */
+declare function playExitTransition(terminal: Terminal): Promise<void>;
+/**
+ * Switch transition - plays when switching to a new game
+ */
+declare function playSwitchTransition(terminal: Terminal): Promise<void>;
+/**
+ * Quick boot - shorter version for game switching (game-to-game)
+ */
+declare function playQuickBoot(terminal: Terminal): Promise<void>;
+/**
+ * Select transition - plays when selecting a game from the menu
+ * Shows the game name with a cool reveal effect
+ */
+declare function playSelectTransition(terminal: Terminal, gameName: string): Promise<void>;
+declare const GAME_EVENTS: {
+    readonly QUIT: "hypersurge:game-quit";
+    readonly SWITCH: "hypersurge:random-game";
+    readonly GAMES_MENU: "hypersurge:games-menu";
+    readonly LAUNCH_GAME: "hypersurge:launch-game";
+};
+/**
+ * Helper for games to dispatch quit event
+ * This triggers the exit transition before returning to shell
+ */
+declare function dispatchGameQuit(terminal: Terminal): void;
+/**
+ * Helper for games to dispatch switch event
+ * This triggers the switch transition before loading new game
+ */
+declare function dispatchGameSwitch(terminal: Terminal): void;
+/**
+ * Helper for games to dispatch games menu event
+ * This triggers the games menu to let user select a game
+ */
+declare function dispatchGamesMenu(terminal: Terminal): void;
+/**
+ * Helper to dispatch launch game event
+ * This triggers TerminalPool to launch a specific game with proper tracking
+ */
+declare function dispatchLaunchGame(terminal: Terminal, gameId: string): void;
+
+/**
+ * Shared Menu System for Easter Egg Games
+ *
+ * Provides consistent menu navigation (arrow keys + Enter/Space)
+ * while maintaining keyboard shortcuts for quick access.
+ */
+interface MenuItem {
+    label: string;
+    shortcut?: string;
+    action: () => void;
+}
+interface MenuState {
+    selection: number;
+    items: MenuItem[];
+}
+/**
+ * Create a new menu state
+ */
+declare function createMenuState(items: MenuItem[]): MenuState;
+/**
+ * Navigate menu selection up
+ */
+declare function menuUp(state: MenuState): void;
+/**
+ * Navigate menu selection down
+ */
+declare function menuDown(state: MenuState): void;
+/**
+ * Reset menu selection to top
+ */
+declare function menuReset(state: MenuState): void;
+/**
+ * Execute the currently selected menu item
+ */
+declare function menuConfirm(state: MenuState): void;
+/**
+ * Handle keyboard input for menu navigation
+ * Returns true if the key was handled, false otherwise
+ */
+declare function handleMenuInput(state: MenuState, key: string, domEvent: KeyboardEvent): boolean;
+interface RenderMenuOptions {
+    title: string;
+    x: number;
+    y: number;
+    width?: number;
+    showShortcuts?: boolean;
+    blinkTitle?: boolean;
+}
+/**
+ * Render a menu box with highlighted selection
+ * Returns ANSI escape sequence string
+ */
+declare function renderMenu(state: MenuState, options: RenderMenuOptions): string;
+/**
+ * Standard pause menu items used across most games
+ */
+declare function createPauseMenuItems(callbacks: {
+    onResume: () => void;
+    onRestart: () => void;
+    onQuit: () => void;
+    onListGames?: () => void;
+    onNextGame?: () => void;
+    onHelp?: () => void;
+}): MenuItem[];
+/**
+ * Standard game over menu items
+ */
+declare function createGameOverMenuItems(callbacks: {
+    onRestart: () => void;
+    onQuit: () => void;
+    onNextGame?: () => void;
+}): MenuItem[];
+/**
+ * Mode selection menu (Tutorial/Play) used by games with tutorials
+ */
+declare function createModeSelectMenuItems(callbacks: {
+    onTutorial: () => void;
+    onPlay: () => void;
+}): MenuItem[];
+interface SimpleMenuItem {
+    label: string;
+    shortcut?: string;
+}
+/**
+ * Handle menu navigation without callbacks
+ * Returns new selection index
+ */
+declare function navigateMenu(currentSelection: number, itemCount: number, key: string, domEvent: KeyboardEvent): {
+    newSelection: number;
+    confirmed: boolean;
+};
+/**
+ * Check if a shortcut key was pressed
+ * Returns the index of the matching item, or -1 if no match
+ */
+declare function checkShortcut(items: SimpleMenuItem[], key: string): number;
+/**
+ * Render a simple menu (index-based, no callbacks)
+ * Returns ANSI escape sequence string
+ */
+declare function renderSimpleMenu(items: SimpleMenuItem[], selection: number, options: {
+    centerX: number;
+    startY: number;
+    showShortcuts?: boolean;
+}): string;
+/**
+ * Common pause menu items definition
+ */
+declare const PAUSE_MENU_ITEMS: SimpleMenuItem[];
+/**
+ * Common mode select items definition
+ */
+declare const MODE_SELECT_ITEMS: SimpleMenuItem[];
+
+/**
+ * Hyper 2048
+ *
+ * Slide and merge DATA PACKETS to reach TERABYTE (2048).
+ * Cyberpunk-themed with glitchy effects and theme-aware colors.
+ */
+
+/**
+ * 2048 Game Controller
+ */
+interface Game2048Controller {
+    stop: () => void;
+    isRunning: boolean;
+}
+declare function run2048Game(terminal: Terminal): Game2048Controller;
+
+/**
+ * Hyper Asteroids
+ *
+ * Classic asteroids with ship rotation, thrust physics, and shooting.
+ * Simplified visuals for terminal - single-character asteroids and ship.
+ * Features screen wrapping, asteroid splitting, particle effects.
+ */
+
+interface AsteroidsController {
+    stop: () => void;
+    isRunning: boolean;
+}
+declare function runAsteroidsGame(terminal: Terminal): AsteroidsController;
+
+/**
+ * Hyper Breakout
+ *
+ * Classic breakout/brick breaker with cyberpunk theme.
+ * Paddle at bottom, ball bounces to break bricks at top.
+ * Features power-ups, particle explosions, and screen shake.
+ */
+
+/**
+ * Breakout Game Controller
+ */
+interface BreakoutController {
+    stop: () => void;
+    isRunning: boolean;
+}
+declare function runBreakoutGame(terminal: Terminal): BreakoutController;
+
+/**
+ * Hyper Chopper
+ *
+ * UGH!-inspired 2D physics delivery game.
+ * Fly a prehistoric helicopter, pick up passengers,
+ * deliver them to platforms. Don't fall in the water!
+ *
+ * FIXED SCREEN - no scrolling, like Pac-Man
+ */
+
+/**
+ * Courier Game Controller
+ */
+interface CourierController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Hyper Chopper Game
+ */
+declare function runCourierGame(terminal: Terminal): CourierController;
+
+/**
+ * Hyper Crack - Terminal Hacking Game
+ *
+ * Crack passwords to breach security layers before
+ * the trace detection catches you. Wordle-style mechanics
+ * with cyberpunk hacker aesthetics.
+ */
+
+/**
+ * Crack Game Controller
+ */
+interface CrackController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Cyberpunk Terminal Hacking Game
+ */
+declare function runCrackGame(terminal: Terminal): CrackController;
+
+/**
+ * Hyper Frogger
+ *
+ * Guide your frog across dangerous roads and rivers!
+ * - Avoid cars and trucks on the road
+ * - Hop on logs and turtles to cross the water
+ * - Reach all 5 lily pads to advance
+ *
+ * Features:
+ * - Progressive difficulty (starts easy)
+ * - Visual frog character with animation
+ * - Better themed obstacles
+ * - Lower terminal requirements
+ */
+
+interface FroggerController {
+    stop: () => void;
+    isRunning: boolean;
+}
+declare function runFroggerGame(terminal: Terminal): FroggerController;
+
+/**
+ * Hyper Hangman
+ *
+ * Cyberpunk-themed word guessing game with glitchy effects,
+ * neon visuals, and theme-aware colors.
+ */
+
+/**
+ * Hangman Game Controller
+ */
+interface HangmanController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Cyberpunk Hangman Game
+ */
+declare function runHangmanGame(terminal: Terminal): HangmanController;
+
+/**
+ * Hyper Minesweeper
+ *
+ * Cyberpunk minesweeper - "defuse the malware grid".
+ * Navigate the grid, flag malware, reveal safe sectors.
+ * Theme-aware with glitchy effects and particle systems.
+ */
+
+/**
+ * Minesweeper Game Controller
+ */
+interface MinesweeperController {
+    stop: () => void;
+    isRunning: boolean;
+}
+declare function runMinesweeperGame(terminal: Terminal): MinesweeperController;
+
+/**
+ * Hyper Pong
+ *
+ * Cyberpunk-themed Pong game with glitchy effects,
+ * neon visuals, and theme-aware colors.
+ * Single player vs AI.
+ */
+
+/**
+ * Pong Game Controller
+ */
+interface PongController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Cyberpunk Pong Game
+ */
+declare function runPongGame(terminal: Terminal): PongController;
+
+/**
+ * Hyper Runner
+ *
+ * Cyberpunk endless runner game - dodge obstacles,
+ * collect power-ups, and survive as long as you can.
+ * Subway Surfers-style vertical perspective with cyberpunk aesthetics.
+ */
+
+/**
+ * Runner Game Controller
+ */
+interface RunnerController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Cyberpunk Endless Runner - Vertical perspective
+ */
+declare function runRunnerGame(terminal: Terminal): RunnerController;
+
+/**
+ * Hyper Simon
+ *
+ * Cyberpunk memory sequence game - "hack the mainframe" by repeating patterns.
+ * Features 4 quadrants (1/2/3/4 or arrow keys), visual flash effects,
+ * speed increases, and particle bursts on success.
+ */
+
+/**
+ * Simon Game Controller
+ */
+interface SimonController {
+    stop: () => void;
+    isRunning: boolean;
+}
+declare function runSimonGame(terminal: Terminal): SimonController;
+
+/**
+ * Hyper Snake Game
+ *
+ * Cyberpunk-themed snake game with glitchy title,
+ * neon borders, and theme-aware colors.
+ */
+
+/**
+ * Snake Game Controller
+ */
+interface SnakeController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Cyberpunk Snake Game
+ */
+declare function runSnakeGame(terminal: Terminal): SnakeController;
+
+/**
+ * Hyper Space Invaders
+ *
+ * Cyberpunk-themed Space Invaders with glitchy effects,
+ * neon visuals, and theme-aware colors.
+ */
+
+/**
+ * Space Invaders Game Controller
+ */
+interface SpaceInvadersController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Cyberpunk Space Invaders
+ */
+declare function runSpaceInvadersGame(terminal: Terminal): SpaceInvadersController;
+
+/**
+ * Hyper Tetris
+ *
+ * Cyberpunk-themed Tetris with glitchy effects,
+ * neon borders, and theme-aware colors.
+ */
+
+/**
+ * Tetris Game Controller
+ */
+interface TetrisController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Cyberpunk Tetris Game
+ */
+declare function runTetrisGame(terminal: Terminal): TetrisController;
+
+/**
+ * Hyper Tower
+ *
+ * Stack falling blocks perfectly to build the tallest tower.
+ * Blocks swing left/right - press space to drop.
+ * Overhanging parts fall off, making subsequent blocks narrower.
+ * Perfect alignments give bonus points and combo multipliers.
+ * Cyberpunk-themed with glitchy effects and theme-aware colors.
+ */
+
+/**
+ * Tower Game Controller
+ */
+interface TowerController {
+    stop: () => void;
+    isRunning: boolean;
+}
+declare function runTowerGame(terminal: Terminal): TowerController;
+
+/**
+ * Hyper Tron
+ *
+ * Light cycles - you vs AI. Don't hit walls or trails.
+ * Cyberpunk-themed with glitchy effects and theme-aware colors.
+ * Best of 5 rounds, speed increases each round, optional shrinking arena.
+ */
+
+/**
+ * Tron Game Controller
+ */
+interface TronController {
+    stop: () => void;
+    isRunning: boolean;
+}
+declare function runTronGame(terminal: Terminal): TronController;
+
+/**
+ * Hyper Typing Test
+ *
+ * Cyberpunk-themed typing speed test with glitchy effects,
+ * neon visuals, and theme-aware colors.
+ * Tests WPM (words per minute) and accuracy.
+ */
+
+/**
+ * Typing Test Game Controller
+ */
+interface TypingTestController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Cyberpunk Typing Test
+ */
+declare function runTypingTest(terminal: Terminal): TypingTestController;
+
+/**
+ * Hyper Wordle
+ *
+ * Classic 5-letter word guessing game with cyberpunk aesthetics.
+ * Crack the cipher in 6 attempts. Green = correct, Yellow = wrong position, Gray = absent.
+ * Features on-screen keyboard, statistics tracking, and particle celebrations.
+ */
+
+/**
+ * Wordle Game Controller
+ */
+interface WordleController {
+    stop: () => void;
+    isRunning: boolean;
+}
+declare function runWordleGame(terminal: Terminal): WordleController;
+
+/**
+ * Games Menu
+ *
+ * Interactive game selection menu accessible via ::games command
+ * or by pressing L in any game's pause menu.
+ */
+
+interface GamesMenuController {
+    stop: () => void;
+    isRunning: boolean;
+}
+interface GamesMenuOptions {
+    onGameSelect?: (gameId: string) => void;
+    onQuit?: () => void;
+}
+/**
+ * Show interactive games menu
+ */
+declare function showGamesMenu(terminal: Terminal, optionsOrCallback?: GamesMenuOptions | ((gameId: string) => void)): GamesMenuController;
+
+/**
+ * Matrix Rain Effect
+ *
+ * Digital rain animation inspired by The Matrix.
+ * Shows intro text, then starts the rain on keypress.
+ */
+
+/**
+ * Matrix controller for managing the animation state
+ */
+interface MatrixController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Get the current matrix controller (if running)
+ */
+declare function getActiveMatrixController(): MatrixController | null;
+/**
+ * Execute matrix rain effect - fullscreen, theme-aware, key-to-stop
+ */
+declare function runMatrixEffect(terminal: Terminal): MatrixController;
+/**
+ * Start the actual matrix rain (called after intro keypress)
+ */
+declare function startMatrixRain(terminal: Terminal): void;
+/**
+ * Check if we're in matrix intro phase
+ */
+declare function isMatrixWaitingForKey(): boolean;
+/**
+ * Handle keypress during matrix effect
+ */
+declare function handleMatrixKeypress(_terminal: Terminal): boolean;
+
+/**
+ * Fake Hacking Animation
+ *
+ * Displays a fake "hacking" sequence for fun.
+ */
+
+interface HackController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Execute fake hacking animation
+ */
+declare function runHackEffect(terminal: Terminal): HackController;
+
+/**
+ * Fake Reboot Animation
+ *
+ * Simulates a system reboot sequence.
+ */
+
+interface RebootController {
+    stop: () => void;
+    isRunning: boolean;
+}
+/**
+ * Execute fake reboot animation
+ */
+declare function runRebootEffect(terminal: Terminal): RebootController;
+
+/**
+ * Game registry with metadata
+ */
+interface GameInfo {
+    id: string;
+    name: string;
+    description: string;
+    run: (terminal: _xterm_xterm.Terminal) => {
+        stop: () => void;
+        isRunning: boolean;
+    };
+}
+declare const games: GameInfo[];
+/**
+ * Get a game by ID
+ */
+declare function getGame(id: string): GameInfo | undefined;
+/**
+ * Get a random game
+ */
+declare function getRandomGame(): GameInfo;
+/**
+ * Run a game by ID
+ */
+declare function runGame(id: string, terminal: _xterm_xterm.Terminal): {
+    stop: () => void;
+    isRunning: boolean;
+} | undefined;
+
+export { GAME_EVENTS, type GameInfo, type GamesMenuController, type GamesMenuOptions, type HackController, MODE_SELECT_ITEMS, type MatrixController, type MenuItem, type MenuState, PAUSE_MENU_ITEMS, PhosphorMode, type RebootController, type RenderMenuOptions, type SimpleMenuItem, checkShortcut, createGameOverMenuItems, createMenuState, createModeSelectMenuItems, createPauseMenuItems, dispatchGameQuit, dispatchGameSwitch, dispatchGamesMenu, dispatchLaunchGame, enterAlternateBuffer, exitAlternateBuffer, forceExitAlternateBuffer, games, getActiveMatrixController, getCurrentThemeColor, getGame, getRandomGame, getSubtleBackgroundColor, getTheme, getThemeColorCode, getVerticalAnchor, handleMatrixKeypress, handleMenuInput, isInAlternateBuffer, isLightTheme, isMatrixWaitingForKey, isTerminalValid, menuConfirm, menuDown, menuReset, menuUp, navigateMenu, playBootTransition, playExitTransition, playQuickBoot, playSelectTransition, playSwitchTransition, renderMenu, renderSimpleMenu, run2048Game, runAsteroidsGame, runBreakoutGame, runCourierGame, runCrackGame, runFroggerGame, runGame, runHackEffect, runHangmanGame, runMatrixEffect, runMinesweeperGame, runPongGame, runRebootEffect, runRunnerGame, runSimonGame, runSnakeGame, runSpaceInvadersGame, runTetrisGame, runTowerGame, runTronGame, runTypingTest, runWordleGame, setTheme, showGamesMenu, startMatrixRain };