gomoku-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# Gomoku
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local 15×15 freestyle Gomoku (five-in-a-row) game that runs in the terminal. You play as `X` against a machine opponent (`O`).
+
+## Play without cloning
+
+Once `gomoku-cli` has been published to npm, launch it from an interactive
+terminal with **Node.js 22 or newer**:
+
+```bash
+npx gomoku-cli
+# or
+pnpm dlx gomoku-cli
+```
+
+These commands will not work until the package owner publishes it and the
+chosen npm package name is available. `npx` downloads and caches an npm
+package; it does not launch a standalone executable or remove the need for
+Node.js. The game requires an interactive terminal with TTY input and output.
+
+For an optional global install, after publication:
+
+```bash
+npm install -g gomoku-cli
+gomoku
+```
+
+## Develop from source
+
+Install Node.js 22 or newer and pnpm (this repository's package manager),
+then run:
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm play
+```
+
+To prepare the distributable JavaScript, run `pnpm build`. This compiles the
+CLI into `dist/cli.js` and its required modules without bundling React or Ink.
+`npm pack` automatically builds before creating a tarball. The published
+package must install its runtime dependencies (`ink` and `react`), but does
+not require `tsx`, the TypeScript compiler, or repository sources to play.
+
+The game opens in the terminal's alternate screen, hiding the previous shell
+output while you play. Press `Q` to quit and restore the original shell screen.
+Ctrl+C and normal termination signals also restore it where the terminal and
+runtime permit. A forced kill or terminal crash may prevent restoration.
+
+Both standard input and standard output must be interactive TTYs. When launched
+with redirected input/output or in a non-interactive environment, the CLI
+prints a short error to stderr and exits with code 1 without rendering the game
+or emitting alternate-screen escape sequences.
+
+The board and status panel form one centered, bounded dashboard on terminals at least
+**78 columns × 27 rows** (including 80×30). The approved emblem is centered
+above the GOMOKU wordmark and subtitle. Smaller terminals use a centered, stacked
+layout with the complete board at a minimum of **57 columns × 24 rows**.
+On taller terminals, the game is positioned near the vertical center, slightly
+above the midpoint. Below the compact minimum, a resize notice replaces the game.
+Resizing never restarts the game or moves your selection.
+
+Interactive terminals with SGR mouse reporting support left-click placement.
+Click any part of a board intersection (including its two side-padding columns)
+to select and place an X in one action. The arrow/WASD and Enter/Space controls
+continue to work alongside clicks. In wide mode, the visible `U Undo`, `M Mode`, `N New`, and `? Help`
+footer labels are also clickable. Right/middle clicks, wheel events, drags, and
+releases do nothing.
+Terminals without supported mouse events remain fully keyboard-operable.
+Mouse reporting is disabled before the previous terminal screen is restored.
+
+## Controls
+
+| Key                                     | Action                                                                   |
+| --------------------------------------- | ------------------------------------------------------------------------ |
+| Arrow keys / W, A, S, D                 | Move the selection cursor (up, left, down, right)                        |
+| Enter / Space                           | Place your mark                                                          |
+| Left click (supported terminals)        | Select and place at a board intersection                                 |
+| Left click footer actions (wide layout) | Undo, Mode, New, or Help                                                 |
+| U                                       | Undo your last move and any machine reply                                |
+| N                                       | New game; an unfinished match requires Y confirmation (N/Escape cancels) |
+| ?                                       | Open or close Help (Escape also closes it)                               |
+| M                                       | Cycle difficulty: Easy → Normal → Hard → Easy (default: Normal)          |
+| Q                                       | Quit                                                                     |
+
+Arrow keys and WASD are interchangeable. Letter commands are case-insensitive:
+`D` moves right, while `M` changes difficulty.
+
+Each press of `U` takes back your most recent `X` and the machine's `O`
+reply, if one has been placed. The cursor returns to your undone square, and
+play resumes on your turn without an automatic machine reply. You can undo
+multiple earlier decisions by pressing `U` repeatedly, including after a win
+or draw. Changing difficulty does not reset the board.
+
+Press `?` to see the concise Help view, which also closes with Escape. In wide
+mode, Help occupies the sidebar while the board remains visible. In compact
+mode, it temporarily replaces the board without changing game state or screen
+geometry.
+
+`N` immediately starts a new game on an empty board or after a finished match.
+During an unfinished match, it shows **Start a new game? Y/N**. Press `Y` to
+confirm, or `N` / Escape to keep playing. Placement, navigation, and mouse board
+clicks are blocked during confirmation. Pending machine replies cannot apply
+after an interrupted or restarted session. `Q` always quits immediately.
+
+## Reading the board
+
+`X` is your red mark and `O` uses the terminal's default foreground. Every
+intersection is three columns wide. `[·]` means selected empty; `[X]` means
+selected X; `(O)` marks the latest O; `<O>` means the cursor is **also** on
+the latest O. A winning run uses `{X}` or `{O}` for every winning stone,
+including runs longer than five. Winning braces take precedence over all other
+indicators, so state remains readable without color.
+
+Five `*` landmarks mark empty reference intersections. They disappear when
+occupied or selected. The selected row and column labels are underlined, while
+ordinary coordinates remain readable. Coordinates are always **row then
+column**, one-based: `R08 C11` means row 8, column 11.
+
+In wide mode, the sidebar shows the latest move and up to four recent moves
+in chronological order; `>` marks the newest entry. Completed games instead
+show the result and immediate New, Undo, and Quit actions. Compact mode keeps
+the status, difficulty, players, last move, and selected coordinates visible
+without changing the board's position. Feedback is confined to a reserved
+line: occupied cells, mode changes, undo, reset, and game completion do not
+shift the board. Pressing a movement key clears an occupied-cell warning.
+
+## Machine opponent
+
+The local opponent offers three deterministic levels. Press `M` at any time to
+cycle the level; the change applies to the next machine decision, even in the
+middle of a game, without resetting the board or selection. `N` starts a new
+game at the currently selected difficulty.
+
+- **Easy:** basic tactical safety with a small two-ply search (32-node budget).
+- **Normal (default):** positional evaluation and bounded reply search (120
+  nodes, up to four plies on forcing lines).
+- **Hard:** more candidate replies and deeper forcing-line search (320 nodes,
+  up to six plies).
+
+All levels use the same rules and engine-validated move simulation. Immediate
+wins and blocks take priority. A forcing move extends the search through its
+reply and counter-move; quiet continuations stop extending. Fixed node, depth,
+and candidate limits bound the search. Stronger levels are not guaranteed to
+win every position.
+
+Run `pnpm benchmark:bot` to compare all three difficulties on fixed early-,
+middle-, late-game, forcing, fork-defense, unsafe-attack, edge, and dense
+positions. It reports chosen moves, node/depth limits, whether the search
+finished within its budget, immediate winning replies for both players, and
+elapsed time. Timings depend on hardware and are not fixed performance targets.
+
+## Commands
+
+```bash
+pnpm build         # compile the npm executable
+pnpm test          # run the test suite
+pnpm typecheck     # type-check with tsc
+pnpm lint          # lint with ESLint
+pnpm format        # format with Prettier
+pnpm format:check  # check formatting without writing
+pnpm benchmark:bot # measure deterministic bot search positions
+```
+
+See [BOT.4 audit](docs/BOT4_AUDIT.md) for the reproduced search-budget issue and before/after measurements.

package/dist/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from 'ink';
+import { GomokuApp } from './components/GomokuApp.js';
+import { runFullscreenApp } from './terminal/fullscreen.js';
+import { MouseInputAdapter } from './terminal/mouse.js';
+const SIGNAL_EXIT_CODES = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };
+async function main() {
+    const input = new MouseInputAdapter(process.stdin);
+    const result = await runFullscreenApp({
+        stdin: process.stdin,
+        stdout: process.stdout,
+        signals: process,
+        input,
+        mount: () => render(_jsx(GomokuApp, { mouseInput: input }), { stdin: input.inkStdin }),
+    });
+    if (result === 'not-interactive') {
+        process.stderr.write('Gomoku requires an interactive terminal (stdin and stdout must be TTYs).\n');
+        process.exitCode = 1;
+    }
+    else if (result !== 'completed') {
+        process.exitCode = SIGNAL_EXIT_CODES[result];
+    }
+}
+void main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/components/Board.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { BOARD_SIZE } from '../domain/types.js';
+import { CELL_WIDTH, isStarPoint, renderCell } from '../ui/glyphs.js';
+import { formatCoord } from '../ui/labels.js';
+import { cellStyle, theme } from '../ui/theme.js';
+import { winningCoordinates } from '../ui/winning.js';
+export function Board({ state, selection }) {
+    const latest = state.moves.at(-1) ?? null;
+    const winningCells = new Set(winningCoordinates(state).map(({ row, col }) => row * BOARD_SIZE + col));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { children: '   ' }), state.board[0].map((_, col) => (_jsx(Text, { ...(selection.col === col
+                            ? theme.selectedCoordinate
+                            : theme.coordinate), children: formatCoord(col).padEnd(CELL_WIDTH) }, col)))] }), state.board.map((rowCells, row) => (_jsxs(Box, { children: [_jsx(Text, { ...(selection.row === row
+                            ? theme.selectedCoordinate
+                            : theme.coordinate), children: formatCoord(row) }), _jsx(Text, { children: " " }), rowCells.map((cell, col) => {
+                        const selected = selection.row === row && selection.col === col;
+                        const lastMove = latest?.row === row && latest.col === col;
+                        const winning = winningCells.has(row * BOARD_SIZE + col);
+                        const starPoint = cell === null && isStarPoint(row, col);
+                        const rendered = renderCell({
+                            cell,
+                            selected,
+                            lastMove,
+                            winning,
+                            starPoint,
+                        });
+                        if (winning && cell !== null) {
+                            return (_jsxs(Text, { children: [_jsx(Text, { ...theme.winningRun, children: rendered.text[0] }), _jsx(Text, { ...cellStyle(cell, selected, lastMove, true), children: cell }), _jsx(Text, { ...theme.winningRun, children: rendered.text[2] })] }, col));
+                        }
+                        return (_jsx(Text, { ...cellStyle(cell, selected, lastMove, false, starPoint), children: rendered.text }, col));
+                    })] }, row)))] }));
+}

package/dist/components/Feedback.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { theme } from '../ui/theme.js';
+/** A single reserved line; an empty message still occupies it so nothing shifts. */
+export function Feedback({ message }) {
+    return (_jsx(Box, { children: _jsx(Text, { ...theme.feedback, children: message.length > 0 ? message : ' ' }) }));
+}

package/dist/components/GameInfoPanel.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { difficultyLabel } from '../opponent/profiles.js';
+import { captionText, formatPosition, recentMoves } from '../ui/labels.js';
+import { BOARD_HEIGHT } from '../ui/layout.js';
+import { HelpView } from './HelpView.js';
+import { theme } from '../ui/theme.js';
+/** One 16-row panel beside the board. Never renders unbounded history. */
+export function GameInfoPanel({ state, status, difficulty, view = 'game', }) {
+    if (view === 'help')
+        return _jsx(HelpView, {});
+    if (view === 'confirm-new') {
+        return (_jsxs(Box, { flexDirection: "column", height: BOARD_HEIGHT, children: [_jsx(Text, { ...theme.muted, children: "NEW GAME" }), _jsx(Text, { ...theme.gameResult, children: "Start a new game?" }), _jsx(Text, { children: " " }), _jsx(Text, { children: "Y Confirm" }), _jsx(Text, { children: "N / Esc Cancel" }), _jsx(Text, { children: " " }), _jsx(Text, { ...theme.muted, children: "Current match stays" }), _jsx(Text, { ...theme.muted, children: "until you confirm." })] }));
+    }
+    const finished = state.status !== 'playing';
+    const moves = recentMoves(state);
+    return (_jsxs(Box, { flexDirection: "column", height: BOARD_HEIGHT, children: [_jsx(Text, { ...theme.muted, children: "STATUS" }), _jsx(Text, { ...theme.gameResult, children: status.heading }), _jsx(Text, { ...theme.muted, children: status.supporting }), _jsx(Text, { children: " " }), finished ? (_jsxs(_Fragment, { children: [_jsxs(Text, { children: ["MODE: ", difficultyLabel(difficulty)] }), _jsx(Text, { children: captionText(state) }), _jsxs(Text, { children: ["MOVES: ", state.moves.length] }), _jsx(Text, { children: " " }), _jsx(Text, { ...theme.muted, children: "NEXT" }), _jsx(Text, { children: "N New U Undo Q Quit" })] })) : (_jsxs(_Fragment, { children: [_jsxs(Text, { children: ["MODE: ", difficultyLabel(difficulty)] }), _jsxs(Text, { children: [_jsx(Text, { ...theme.playerX, children: "X" }), " You", '   ', _jsx(Text, { ...theme.playerO, children: "O" }), " Machine"] }), _jsxs(Text, { children: ["MOVES: ", state.moves.length] }), _jsx(Text, { children: captionText(state) }), _jsx(Text, { children: " " }), _jsx(Text, { ...theme.muted, children: "RECENT" }), moves.map((move, index) => (_jsxs(Text, { ...(index === moves.length - 1 ? theme.gameResult : theme.text), children: [index === moves.length - 1 ? '> ' : '  ', _jsx(Text, { ...(move.player === 'X' ? theme.playerX : theme.playerO), children: move.player }), ' ', formatPosition(move)] }, `${state.moves.length - moves.length + index}`)))] }))] }));
+}

package/dist/components/GameShell.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { difficultyLabel } from '../opponent/profiles.js';
+import { COMPACT_CONTROLS_TEXT, CONTROLS_TEXT, captionText, formatPosition, } from '../ui/labels.js';
+import { BOARD_WIDTH, PANEL_GAP, PANEL_WIDTH, } from '../ui/layout.js';
+import { theme } from '../ui/theme.js';
+import { Board } from './Board.js';
+import { Feedback } from './Feedback.js';
+import { GameInfoPanel } from './GameInfoPanel.js';
+import { HelpView } from './HelpView.js';
+import { Wordmark } from './Wordmark.js';
+/** Every status row stays within the fixed geometry established by POST.6. */
+export function GameShell({ geometry, state, selection, status, difficulty, feedback, view, }) {
+    const displayFeedback = view === 'confirm-new' ? 'Start a new game? Y/N' : feedback;
+    if (geometry.mode === 'compact') {
+        return (_jsxs(Box, { flexDirection: "column", width: geometry.dashboard.width, children: [_jsx(Box, { marginLeft: geometry.banner.left - geometry.dashboard.left, children: _jsx(Wordmark, { compact: true }) }), _jsxs(Text, { children: [_jsx(Text, { ...theme.gameResult, children: status.heading }), _jsx(Text, { ...theme.muted, children: ` · ${difficultyLabel(difficulty)}` }), state.status !== 'playing' && (_jsx(Text, { children: " \u00B7 N New / U Undo / Q Quit" }))] }), _jsxs(Text, { children: [_jsx(Text, { ...theme.playerX, children: "X" }), " You", '   ', _jsx(Text, { ...theme.playerO, children: "O" }), " Machine", '   ', "MOVES:", ' ', state.moves.length] }), _jsx(Text, { ...theme.muted, children: captionText(state) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [view === 'help' ? (_jsx(HelpView, { compact: true })) : (_jsx(Board, { state: state, selection: selection })), _jsxs(Text, { ...theme.muted, children: ["SELECTED ", formatPosition(selection)] })] }), _jsx(Feedback, { message: displayFeedback }), _jsx(Text, { ...theme.muted, children: COMPACT_CONTROLS_TEXT })] }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", width: geometry.dashboard.width, children: [_jsx(Box, { marginLeft: geometry.banner.left - geometry.dashboard.left, children: _jsx(Wordmark, {}) }), _jsxs(Box, { marginTop: 1, children: [_jsx(Box, { flexDirection: "column", width: BOARD_WIDTH, children: _jsx(Board, { state: state, selection: selection }) }), _jsx(Box, { width: PANEL_WIDTH, marginLeft: PANEL_GAP, children: _jsx(GameInfoPanel, { state: state, status: status, difficulty: difficulty, view: view }) })] }), _jsx(Feedback, { message: displayFeedback }), _jsx(Text, { ...theme.divider, children: '─'.repeat(geometry.dashboard.width) }), _jsx(Text, { ...theme.muted, children: CONTROLS_TEXT })] }));
+}

package/dist/components/GomokuApp.js

@@ -0,0 +1,100 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, useApp, useInput, useWindowSize } from 'ink';
+import { useEffect, useMemo, useReducer } from 'react';
+import { chooseMove } from '../opponent/opponent.js';
+import { hitTestMouse } from '../ui/hitTest.js';
+import { resolveMovement } from '../ui/input.js';
+import { resolveGeometry } from '../ui/layout.js';
+import { statusText } from '../ui/status.js';
+import { GameShell } from './GameShell.js';
+import { gameSessionReducer, initialSession } from './gameSession.js';
+import { TooSmallNotice } from './TooSmallNotice.js';
+export function GomokuApp({ viewportSize, initialState, mouseInput, }) {
+    const { exit } = useApp();
+    const windowSize = useWindowSize();
+    const [session, dispatch] = useReducer(gameSessionReducer, initialState, initialSession);
+    const { game, selection, difficulty, feedback, revision, view } = session;
+    const viewport = viewportSize ?? windowSize;
+    const { columns, rows } = viewport;
+    const geometry = useMemo(() => resolveGeometry({ columns, rows }), [columns, rows]);
+    useEffect(() => {
+        if (!mouseInput)
+            return;
+        return mouseInput.subscribe((press) => {
+            const target = hitTestMouse(geometry, press);
+            if (!target)
+                return;
+            if (target.type === 'cell') {
+                dispatch({ type: 'place-at', row: target.row, col: target.col });
+            }
+            else {
+                dispatch({ type: target.command });
+            }
+        });
+    }, [mouseInput, geometry]);
+    // Each timer captures a specific turn revision. A new game, undo, mode
+    // change, or fresh move invalidates outstanding results in the reducer,
+    // even if cancellation loses a race with a queued callback.
+    useEffect(() => {
+        if (view !== 'game' ||
+            game.status !== 'playing' ||
+            game.currentPlayer !== 'O') {
+            return;
+        }
+        const timer = setTimeout(() => {
+            const move = chooseMove(game, { difficulty });
+            dispatch({ type: 'machine-reply', move, revision });
+        }, 0);
+        return () => clearTimeout(timer);
+    }, [game, difficulty, revision, view]);
+    useInput((input, key) => {
+        const command = input.toLowerCase();
+        if (command === 'q') {
+            exit();
+            return;
+        }
+        if (view === 'confirm-new') {
+            if (command === 'y')
+                dispatch({ type: 'confirm-new' });
+            else if (command === 'n' || key.escape) {
+                dispatch({ type: 'dismiss' });
+            }
+            return;
+        }
+        if (view === 'help') {
+            if (input === '?' || key.escape)
+                dispatch({ type: 'dismiss' });
+            return;
+        }
+        if (input === '?') {
+            dispatch({ type: 'help' });
+        }
+        else if (command === 'm') {
+            dispatch({ type: 'mode' });
+        }
+        else if (command === 'n') {
+            dispatch({ type: 'new' });
+        }
+        else if (command === 'u') {
+            dispatch({ type: 'undo' });
+        }
+        else {
+            const direction = resolveMovement(command, key);
+            if (direction) {
+                dispatch({ type: 'move', direction });
+            }
+            else if (key.return || input === ' ') {
+                dispatch({ type: 'place' });
+            }
+        }
+    });
+    if (!geometry)
+        return _jsx(TooSmallNotice, { viewport: viewport });
+    const machineThinking = game.status === 'playing' && game.currentPlayer === 'O';
+    const status = view === 'confirm-new'
+        ? { heading: 'Confirm restart', supporting: 'Y confirm · N cancel' }
+        : view === 'help'
+            ? { heading: 'Help', supporting: '? or Escape to close' }
+            : statusText(game, machineThinking);
+    return (_jsx(Box, { flexDirection: "column", paddingLeft: geometry.dashboard.left, paddingTop: geometry.dashboard.top, children: _jsx(GameShell, { geometry: geometry, state: game, selection: selection, status: status, difficulty: difficulty, feedback: feedback, view: view }) }));
+}

package/dist/components/HelpView.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { BOARD_HEIGHT, PANEL_WIDTH } from '../ui/layout.js';
+import { theme } from '../ui/theme.js';
+const HELP_LINES = [
+    'Arrows / WASD   Move',
+    'Enter / Space   Place X',
+    'Left click      Place X',
+    'U               Undo',
+    'M               Mode',
+    'N               New game',
+    'Q               Quit',
+    '',
+    'Click Undo / Mode in',
+    'the wide footer.',
+    '',
+    '? / Esc         Close',
+];
+/** Replaces only an existing fixed-height region; board geometry never shifts. */
+export function HelpView({ compact = false }) {
+    return (_jsxs(Box, { flexDirection: "column", height: BOARD_HEIGHT, width: compact ? undefined : PANEL_WIDTH, children: [_jsx(Text, { ...theme.gameResult, children: "HELP" }), HELP_LINES.map((line, index) => (_jsx(Text, { ...(line ? theme.text : theme.muted), children: line || ' ' }, index)))] }));
+}

package/dist/components/TooSmallNotice.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { MIN_COLUMNS, MIN_ROWS } from '../ui/layout.js';
+import { theme } from '../ui/theme.js';
+/** Never print a line wider than the reported terminal, even at extreme sizes. */
+export function TooSmallNotice({ viewport }) {
+    const columns = Number.isFinite(viewport.columns)
+        ? Math.max(0, Math.floor(viewport.columns))
+        : MIN_COLUMNS;
+    const rows = Number.isFinite(viewport.rows)
+        ? Math.max(0, Math.floor(viewport.rows))
+        : 2;
+    if (columns === 0 || rows === 0)
+        return null;
+    const title = columns >= 19 ? 'Terminal too small.' : 'Resize terminal';
+    const details = `Need ${MIN_COLUMNS} columns x ${MIN_ROWS} rows.`;
+    const centerLine = (message) => {
+        const text = message.slice(0, columns);
+        return `${' '.repeat(Math.floor((columns - text.length) / 2))}${text}`;
+    };
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { ...theme.gameResult, children: centerLine(title) }), rows > 1 && _jsx(Text, { ...theme.muted, children: centerLine(details) })] }));
+}

package/dist/components/Wordmark.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { COMPACT_WORDMARK, FULL_BANNER_ROWS } from '../ui/branding.js';
+import { theme } from '../ui/theme.js';
+export function Wordmark({ compact = false }) {
+    if (compact) {
+        return _jsx(Text, { bold: true, children: COMPACT_WORDMARK });
+    }
+    return (_jsx(Box, { flexDirection: "column", children: FULL_BANNER_ROWS.map((line, index) => (_jsx(Text, { ...(index === FULL_BANNER_ROWS.length - 1
+                ? theme.muted
+                : { bold: true }), children: line }, line))) }));
+}

package/dist/components/gameSession.js

@@ -0,0 +1,135 @@
+import { applyMove, createInitialState, latestHumanMove, undoHumanTurn, } from '../domain/engine.js';
+import { CENTER } from '../opponent/opponent.js';
+import { DEFAULT_DIFFICULTY, difficultyLabel, nextDifficulty, } from '../opponent/profiles.js';
+import { moveSelection } from '../ui/input.js';
+import { completionFeedback, feedbackText } from '../ui/status.js';
+export function initialSession(initialState) {
+    return {
+        game: initialState ?? createInitialState(),
+        selection: { row: CENTER, col: CENTER },
+        difficulty: DEFAULT_DIFFICULTY,
+        feedback: '',
+        view: 'game',
+        revision: 0,
+    };
+}
+export function gameSessionReducer(session, action) {
+    const { game, view } = session;
+    // Confirmation and Help are exclusive input modes. A pending bot decision
+    // cannot apply while either is open, even if its timer already fired.
+    if (view === 'confirm-new') {
+        if (action.type === 'confirm-new')
+            return restart(session);
+        if (action.type === 'dismiss' || action.type === 'new') {
+            return resume(session);
+        }
+        return session;
+    }
+    if (view === 'help') {
+        if (action.type === 'help' || action.type === 'dismiss') {
+            return resume(session);
+        }
+        return session;
+    }
+    switch (action.type) {
+        case 'new':
+            if (game.status !== 'playing' || game.moves.length === 0) {
+                return restart(session);
+            }
+            return {
+                ...session,
+                view: 'confirm-new',
+                revision: session.revision + 1,
+            };
+        case 'help':
+            return { ...session, view: 'help', revision: session.revision + 1 };
+        case 'confirm-new':
+        case 'dismiss':
+            return session;
+        case 'undo': {
+            const undone = latestHumanMove(game);
+            if (!undone)
+                return session;
+            return {
+                ...session,
+                game: undoHumanTurn(game),
+                selection: { row: undone.row, col: undone.col },
+                feedback: 'Last turn undone.',
+                revision: session.revision + 1,
+            };
+        }
+        case 'mode': {
+            const difficulty = nextDifficulty(session.difficulty);
+            return {
+                ...session,
+                difficulty,
+                feedback: `Mode: ${difficultyLabel(difficulty)}.`,
+                revision: session.revision + 1,
+            };
+        }
+        case 'move':
+            if (game.status !== 'playing' || game.currentPlayer !== 'X') {
+                return session;
+            }
+            return {
+                ...session,
+                selection: moveSelection(session.selection, action.direction),
+                feedback: '',
+            };
+        case 'place':
+        case 'place-at': {
+            const selection = action.type === 'place-at'
+                ? { row: action.row, col: action.col }
+                : session.selection;
+            if (game.status !== 'playing' || game.currentPlayer !== 'X') {
+                return {
+                    ...session,
+                    feedback: feedbackText(game.status !== 'playing' ? 'game-over' : 'not-your-turn'),
+                };
+            }
+            // Mouse and keyboard share this authoritative engine transition.
+            const result = applyMove(game, selection.row, selection.col);
+            return result.ok
+                ? {
+                    ...session,
+                    selection,
+                    game: result.state,
+                    feedback: completionFeedback(result.state),
+                    revision: session.revision + 1,
+                }
+                : { ...session, selection, feedback: feedbackText(result.reason) };
+        }
+        case 'machine-reply': {
+            if (action.revision !== session.revision ||
+                game.status !== 'playing' ||
+                game.currentPlayer !== 'O' ||
+                action.move.player !== 'O') {
+                return session;
+            }
+            const result = applyMove(game, action.move.row, action.move.col);
+            return result.ok
+                ? {
+                    ...session,
+                    game: result.state,
+                    feedback: completionFeedback(result.state),
+                    revision: session.revision + 1,
+                }
+                : session;
+        }
+    }
+}
+/** A reset is deliberate, either from an empty/finished board or confirmed. */
+function restart(session) {
+    return {
+        ...session,
+        game: createInitialState(),
+        selection: { row: CENTER, col: CENTER },
+        view: 'game',
+        feedback: 'New game started.',
+        revision: session.revision + 1,
+    };
+}
+/** Resume a suspended machine turn with a fresh revision. */
+function resume(session) {
+    return { ...session, view: 'game', revision: session.revision + 1 };
+}

package/dist/domain/board.js

@@ -0,0 +1,28 @@
+import { BOARD_SIZE } from './types.js';
+export function createEmptyBoard() {
+    const board = [];
+    for (let row = 0; row < BOARD_SIZE; row += 1) {
+        board.push(new Array(BOARD_SIZE).fill(null));
+    }
+    return board;
+}
+export function cloneBoard(board) {
+    return board.map((row) => row.slice());
+}
+export function inBounds(row, col) {
+    return row >= 0 && row < BOARD_SIZE && col >= 0 && col < BOARD_SIZE;
+}
+export function isBoardFull(board) {
+    return board.every((row) => row.every((cell) => cell !== null));
+}
+export function emptyCells(board) {
+    const cells = [];
+    for (let row = 0; row < board.length; row += 1) {
+        for (let col = 0; col < board[row].length; col += 1) {
+            if (board[row][col] === null) {
+                cells.push([row, col]);
+            }
+        }
+    }
+    return cells;
+}