gomoku-cli 0.0.0-stage → 0.1.0

package/dist/terminal/mouse.js

@@ -0,0 +1,158 @@
+import { PassThrough } from 'node:stream';
+/**
+ * Keeps keyboard bytes intact while extracting SGR mouse events. CSI sequences
+ * beginning ESC[< belong exclusively to the mouse parser, not Ink's useInput.
+ */
+export class SgrMouseDecoder {
+    keyboard;
+    mouse;
+    pending = Buffer.alloc(0);
+    discardingMouse = false;
+    prefix = Buffer.from('\x1b[<');
+    constructor(keyboard, mouse) {
+        this.keyboard = keyboard;
+        this.mouse = mouse;
+    }
+    push(bytes) {
+        if (this.discardingMouse) {
+            const end = bytes.findIndex((byte) => byte === 0x4d || byte === 0x6d);
+            if (end === -1)
+                return;
+            this.discardingMouse = false;
+            bytes = bytes.subarray(end + 1);
+        }
+        this.pending = Buffer.concat([this.pending, bytes]);
+        while (this.pending.length > 0) {
+            const marker = this.pending.indexOf(this.prefix);
+            if (marker >= 0) {
+                if (marker > 0)
+                    this.keyboard(this.pending.subarray(0, marker));
+                this.pending = this.pending.subarray(marker);
+                // Only M/m complete SGR mouse reports. Keep malformed reports away
+                // from Ink rather than leaking their tail as keyboard shortcuts.
+                let end = -1;
+                for (let i = this.prefix.length; i < this.pending.length; i += 1) {
+                    if (this.pending[i] === 0x4d || this.pending[i] === 0x6d) {
+                        end = i;
+                        break;
+                    }
+                }
+                if (end === -1) {
+                    // Continue discarding long malformed reports until their terminator.
+                    if (this.pending.length > 64) {
+                        this.pending = Buffer.alloc(0);
+                        this.discardingMouse = true;
+                    }
+                    break;
+                }
+                const event = this.pending.subarray(this.prefix.length, end + 1);
+                this.consume(event.toString('ascii'));
+                this.pending = this.pending.subarray(end + 1);
+                continue;
+            }
+            // Preserve a partial mouse prefix across raw-data chunk boundaries.
+            let keep = 0;
+            for (let n = Math.min(this.prefix.length - 1, this.pending.length); n > 0; n -= 1) {
+                if (this.pending
+                    .subarray(this.pending.length - n)
+                    .equals(this.prefix.subarray(0, n))) {
+                    keep = n;
+                    break;
+                }
+            }
+            const ready = this.pending.length - keep;
+            if (ready > 0)
+                this.keyboard(this.pending.subarray(0, ready));
+            this.pending = this.pending.subarray(ready);
+            break;
+        }
+    }
+    /** No pending prefix should leak into Ink during shutdown. */
+    reset() {
+        this.pending = Buffer.alloc(0);
+        this.discardingMouse = false;
+    }
+    consume(sequence) {
+        const match = /^(\d+);(\d+);(\d+)([Mm])$/.exec(sequence);
+        if (!match || match[4] !== 'M' || Number(match[1]) !== 0)
+            return;
+        const column = Number(match[2]);
+        const row = Number(match[3]);
+        if (!Number.isSafeInteger(column) ||
+            !Number.isSafeInteger(row) ||
+            column < 1 ||
+            row < 1)
+            return;
+        this.mouse({ column, row });
+    }
+}
+export class MouseInputAdapter {
+    stdin;
+    keyboard;
+    active = false;
+    initialRaw = false;
+    listeners = new Set();
+    decoder;
+    onData = (bytes) => {
+        this.decoder.push(Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes));
+    };
+    constructor(stdin) {
+        this.stdin = stdin;
+        const keyboard = new PassThrough();
+        Object.defineProperty(keyboard, 'isTTY', { value: true });
+        Object.defineProperty(keyboard, 'fd', { value: stdin.fd ?? 0 });
+        Object.defineProperty(keyboard, 'isRaw', {
+            get: () => stdin.isRaw === true,
+        });
+        keyboard.setRawMode = (mode) => {
+            stdin.setRawMode?.(mode);
+            return keyboard;
+        };
+        keyboard.ref = () => {
+            stdin.ref?.();
+            return keyboard;
+        };
+        keyboard.unref = () => {
+            stdin.unref?.();
+            return keyboard;
+        };
+        this.keyboard = keyboard;
+        this.decoder = new SgrMouseDecoder((bytes) => this.keyboard.write(bytes), (event) => {
+            for (const listener of this.listeners)
+                listener(event);
+        });
+    }
+    /**
+     * Ink types stdin as a concrete TTY ReadStream, while this adapter must
+     * provide a filtered PassThrough so Ink never receives mouse sequences.
+     * Its input contract (data events, raw mode, TTY flags and ref/unref) is
+     * implemented above; keep the structural type adaptation at this boundary.
+     */
+    get inkStdin() {
+        return this.keyboard;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    start() {
+        if (this.active)
+            return;
+        this.initialRaw = this.stdin.isRaw === true;
+        this.active = true;
+        this.stdin.on('data', this.onData);
+    }
+    stop() {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.stdin.off('data', this.onData);
+        // Ink normally restores raw mode itself, but a failed mount may not.
+        if (this.stdin.isRaw !== undefined &&
+            this.stdin.isRaw !== this.initialRaw) {
+            this.stdin.setRawMode?.(this.initialRaw);
+        }
+        this.decoder.reset();
+        this.listeners.clear();
+    }
+}

package/dist/ui/branding.js

@@ -0,0 +1,17 @@
+export const FULL_WORDMARK = [
+    '╔═╗ ╔═╗ ╔╦╗ ╔═╗ ╦╔═ ╦ ╦',
+    '║ ╦ ║ ║ ║║║ ║ ║ ╠╩╗ ║ ║',
+    '╚═╝ ╚═╝ ╩ ╩ ╚═╝ ╩ ╩ ╚═╝',
+];
+export const EMBLEM_ROWS = ['┌───┬───┐', '│ X │ ● │', '└───┴───┘'];
+export const WORDMARK_TAGLINE = 'FIVE IN A ROW · 15 × 15';
+export const COMPACT_WORDMARK = 'GOMOKU';
+export const FULL_WORDMARK_WIDTH = Math.max(...FULL_WORDMARK.map((line) => line.length), WORDMARK_TAGLINE.length);
+// Center the approved three-row emblem over the entire wordmark.
+const EMBLEM_INSET = Math.floor((FULL_WORDMARK_WIDTH - EMBLEM_ROWS[0].length) / 2);
+export const FULL_BANNER_ROWS = [
+    ...EMBLEM_ROWS.map((line) => ' '.repeat(EMBLEM_INSET) + line),
+    ...FULL_WORDMARK,
+    WORDMARK_TAGLINE,
+];
+export const FULL_BANNER_WIDTH = Math.max(...FULL_BANNER_ROWS.map((line) => line.length));

package/dist/ui/glyphs.js

@@ -0,0 +1,38 @@
+import { BOARD_SIZE } from '../domain/types.js';
+export const CELL_WIDTH = 3;
+/** Five symmetric reference intersections on a 15×15 board. */
+const STAR_POINTS = new Set(['3,3', '3,11', '7,7', '11,3', '11,11']);
+export function isStarPoint(row, col) {
+    return (Number.isInteger(row) &&
+        Number.isInteger(col) &&
+        row >= 0 &&
+        row < BOARD_SIZE &&
+        col >= 0 &&
+        col < BOARD_SIZE &&
+        STAR_POINTS.has(`${row},${col}`));
+}
+/**
+ * Every cell occupies exactly three terminal columns. Markers communicate
+ * winning > selected-and-latest > selected > latest > ordinary, without color.
+ * Star points are displayed only on empty, unselected intersections.
+ */
+export function renderCell({ cell, selected, lastMove, winning = false, starPoint = false, ascii = false, }) {
+    const glyph = cell ?? (ascii ? '.' : '·');
+    let text;
+    if (winning && cell !== null) {
+        text = `{${glyph}}`;
+    }
+    else if (selected && lastMove && cell !== null) {
+        text = `<${glyph}>`;
+    }
+    else if (selected) {
+        text = `[${glyph}]`;
+    }
+    else if (lastMove) {
+        text = `(${glyph})`;
+    }
+    else {
+        text = ` ${cell === null && starPoint ? '*' : glyph} `;
+    }
+    return { text, selected, lastMove, winning: winning && cell !== null };
+}

package/dist/ui/hitTest.js

@@ -0,0 +1,40 @@
+import { BOARD_SIZE } from '../domain/types.js';
+import { CONTROLS_TEXT } from './labels.js';
+/** The whole three-character cell is clickable, including its side padding. */
+export function hitTestMouse(geometry, press) {
+    if (!geometry ||
+        !Number.isSafeInteger(press.column) ||
+        !Number.isSafeInteger(press.row)) {
+        return null;
+    }
+    const x = press.column - 1;
+    const y = press.row - 1;
+    const { firstCell, cellWidth } = geometry;
+    const relativeX = x - firstCell.left;
+    const relativeY = y - firstCell.top;
+    if (relativeX >= 0 &&
+        relativeX < BOARD_SIZE * cellWidth &&
+        relativeY >= 0 &&
+        relativeY < BOARD_SIZE) {
+        return {
+            type: 'cell',
+            row: relativeY,
+            col: Math.floor(relativeX / cellWidth),
+        };
+    }
+    // Only the visible wide footer advertises clickable command targets.
+    if (geometry.mode === 'wide' && y === geometry.controls.top) {
+        for (const [text, command] of [
+            ['U Undo', 'undo'],
+            ['M Mode', 'mode'],
+            ['N New', 'new'],
+            ['? Help', 'help'],
+        ]) {
+            const start = geometry.controls.left + CONTROLS_TEXT.indexOf(text);
+            if (x >= start && x < start + text.length) {
+                return { type: 'command', command };
+            }
+        }
+    }
+    return null;
+}

package/dist/ui/input.js

@@ -0,0 +1,37 @@
+import { BOARD_SIZE } from '../domain/types.js';
+/** Arrow keys and WASD resolve to the same movement intent. */
+export function resolveMovement(input, key) {
+    if (key.upArrow)
+        return 'up';
+    if (key.downArrow)
+        return 'down';
+    if (key.leftArrow)
+        return 'left';
+    if (key.rightArrow)
+        return 'right';
+    switch (input.toLowerCase()) {
+        case 'w':
+            return 'up';
+        case 's':
+            return 'down';
+        case 'a':
+            return 'left';
+        case 'd':
+            return 'right';
+        default:
+            return null;
+    }
+}
+/** Clamps cursor movement to the 15×15 board without mutating its position. */
+export function moveSelection(current, direction) {
+    switch (direction) {
+        case 'up':
+            return { ...current, row: Math.max(0, current.row - 1) };
+        case 'down':
+            return { ...current, row: Math.min(BOARD_SIZE - 1, current.row + 1) };
+        case 'left':
+            return { ...current, col: Math.max(0, current.col - 1) };
+        case 'right':
+            return { ...current, col: Math.min(BOARD_SIZE - 1, current.col + 1) };
+    }
+}

package/dist/ui/labels.js

@@ -0,0 +1,18 @@
+export const CONTROLS_TEXT = 'Arrows/WASD · Enter/Space Place · U Undo · N New · M Mode · ? Help · Q Quit';
+// Explicit compact copy, without dropping a command or causing a second row.
+export const COMPACT_CONTROLS_TEXT = 'Arrows/WASD Enter/Space U Undo N New M Mode ? Help Q Quit';
+/** Zero-pads a zero-based coordinate to its 1-based display form (`01`..`15`). */
+export function formatCoord(n) {
+    return String(n + 1).padStart(2, '0');
+}
+export function formatPosition({ row, col, }) {
+    return `R${formatCoord(row)} C${formatCoord(col)}`;
+}
+export function captionText(state) {
+    const move = state.moves.at(-1);
+    return move ? `LAST ${move.player} ${formatPosition(move)}` : 'LAST: NONE YET';
+}
+/** Chronological order, including only actually committed moves. */
+export function recentMoves(state) {
+    return state.moves.slice(-4);
+}

package/dist/ui/layout.js

@@ -0,0 +1,86 @@
+import { BOARD_SIZE } from '../domain/types.js';
+import { COMPACT_WORDMARK, FULL_BANNER_ROWS, FULL_BANNER_WIDTH, } from './branding.js';
+import { CELL_WIDTH } from './glyphs.js';
+import { COMPACT_CONTROLS_TEXT } from './labels.js';
+// The second digit of each heading aligns with the cell's center glyph.
+// Keep one right-side spacer so the established board/panel geometry is stable.
+export const ROW_LABEL_WIDTH = 3;
+export const COLUMN_HEADER_INSET = ROW_LABEL_WIDTH;
+export const BOARD_WIDTH = COLUMN_HEADER_INSET + BOARD_SIZE * CELL_WIDTH + 1;
+export const BOARD_HEIGHT = 1 + BOARD_SIZE;
+export const PANEL_GAP = 2;
+export const PANEL_WIDTH = 27;
+export const DASHBOARD_WIDTH = BOARD_WIDTH + PANEL_GAP + PANEL_WIDTH;
+const WIDE_BANNER_ROWS = FULL_BANNER_ROWS.length; // emblem + wordmark + subtitle
+const WIDE_BANNER_GAP = 1;
+const WIDE_FOOTER_ROWS = 3; // reserved feedback, divider, controls
+const COMPACT_HEADER_ROWS = 5; // logo, status, two metadata rows, gap
+const COMPACT_FOOTER_ROWS = 3; // board caption, feedback, controls
+// No redundant board caption in wide mode. This is the measured physical height.
+export const WIDE_MIN_ROWS = WIDE_BANNER_ROWS + WIDE_BANNER_GAP + BOARD_HEIGHT + WIDE_FOOTER_ROWS;
+export const COMPACT_MIN_ROWS = COMPACT_HEADER_ROWS + BOARD_HEIGHT + COMPACT_FOOTER_ROWS;
+export const COMPACT_MIN_COLUMNS = Math.max(57, BOARD_WIDTH, COMPACT_CONTROLS_TEXT.length);
+export const MIN_COLUMNS = COMPACT_MIN_COLUMNS;
+export const MIN_ROWS = COMPACT_MIN_ROWS;
+export function resolveLayout({ columns, rows }) {
+    if (!Number.isFinite(columns) || !Number.isFinite(rows)) {
+        return 'too-small';
+    }
+    if (columns >= DASHBOARD_WIDTH && rows >= WIDE_MIN_ROWS) {
+        return 'wide';
+    }
+    if (columns >= COMPACT_MIN_COLUMNS && rows >= COMPACT_MIN_ROWS) {
+        return 'compact';
+    }
+    return 'too-small';
+}
+/**
+ * Single source for rendered coordinates, including future mouse hit-testing.
+ * The slight upward bias leaves more breathing room below than above on tall
+ * screens. At the minimum height, the top offset is exactly zero.
+ */
+export function resolveGeometry(size) {
+    const mode = resolveLayout(size);
+    if (mode === 'too-small')
+        return null;
+    const width = mode === 'wide' ? DASHBOARD_WIDTH : COMPACT_MIN_COLUMNS;
+    const height = mode === 'wide' ? WIDE_MIN_ROWS : COMPACT_MIN_ROWS;
+    const left = Math.floor((Math.floor(size.columns) - width) / 2);
+    const spareRows = Math.floor(size.rows) - height;
+    const top = Math.max(0, Math.floor(spareRows / 2) - (spareRows > 0 ? 1 : 0));
+    const bannerWidth = mode === 'wide' ? FULL_BANNER_WIDTH : COMPACT_WORDMARK.length;
+    const bannerHeight = mode === 'wide' ? WIDE_BANNER_ROWS : 1;
+    const headerRows = mode === 'wide' ? WIDE_BANNER_ROWS + WIDE_BANNER_GAP : COMPACT_HEADER_ROWS;
+    const footerRows = mode === 'wide' ? WIDE_FOOTER_ROWS : COMPACT_FOOTER_ROWS;
+    const boardTop = top + headerRows;
+    return {
+        mode,
+        dashboard: { left, top, width, height },
+        banner: {
+            left: left + Math.floor((width - bannerWidth) / 2),
+            top,
+            width: bannerWidth,
+            height: bannerHeight,
+        },
+        board: { left, top: boardTop, width: BOARD_WIDTH, height: BOARD_HEIGHT },
+        panel: mode === 'wide'
+            ? {
+                left: left + BOARD_WIDTH + PANEL_GAP,
+                top: boardTop,
+                width: PANEL_WIDTH,
+                height: BOARD_HEIGHT,
+            }
+            : null,
+        headerRows,
+        footerRows,
+        feedback: {
+            left,
+            top: boardTop + BOARD_HEIGHT + (mode === 'compact' ? 1 : 0),
+        },
+        firstCell: { left: left + ROW_LABEL_WIDTH, top: boardTop + 1 },
+        columnLabels: { left: left + COLUMN_HEADER_INSET, top: boardTop },
+        controls: { left, top: top + height - 1 },
+        rowLabelWidth: ROW_LABEL_WIDTH,
+        cellWidth: CELL_WIDTH,
+    };
+}

package/dist/ui/status.js

@@ -0,0 +1,36 @@
+export function statusText(state, machineThinking) {
+    if (state.status === 'won') {
+        return state.winner === 'X'
+            ? { heading: 'You win', supporting: 'Five in a row' }
+            : { heading: 'You lose', supporting: 'Machine made five' };
+    }
+    if (state.status === 'draw') {
+        return { heading: 'Draw', supporting: 'No more legal moves' };
+    }
+    if (machineThinking) {
+        return { heading: 'Machine thinking', supporting: 'Waiting for O' };
+    }
+    return { heading: 'Your turn', supporting: 'Choose an intersection' };
+}
+export function feedbackText(reason) {
+    switch (reason) {
+        case 'game-over':
+            return 'Game over. Press N for a new game.';
+        case 'out-of-bounds':
+            return 'Outside the board.';
+        case 'occupied':
+            return 'That cell is taken.';
+        case 'not-your-turn':
+            return 'Wait for the machine to move.';
+    }
+}
+export function completionFeedback(state) {
+    if (state.status === 'draw')
+        return 'Draw. N New · U Undo · Q Quit';
+    if (state.status === 'won') {
+        return state.winner === 'X'
+            ? 'Five in a row. N New · U Undo · Q Quit'
+            : 'Machine wins. N New · U Undo · Q Quit';
+    }
+    return '';
+}

package/dist/ui/theme.js

@@ -0,0 +1,41 @@
+export const theme = {
+    text: {},
+    muted: { dimColor: true },
+    divider: { dimColor: true },
+    playerX: { color: 'red', bold: true },
+    playerO: { bold: true },
+    // No dimColor: it makes dots and coordinates almost invisible on some themes.
+    emptyCell: { color: 'gray' },
+    starPoint: { color: 'gray', bold: true },
+    coordinate: {},
+    selectedCoordinate: { bold: true, underline: true },
+    selectedCell: { inverse: true },
+    latestMove: { underline: true },
+    selectedLatestMove: { inverse: true, underline: true },
+    winningRun: { color: 'green', bold: true },
+    feedback: { color: 'yellow' },
+    gameResult: { bold: true },
+};
+/** Overlays never replace the foreground color identifying the stone owner. */
+export function cellStyle(cell, selected, lastMove, winning = false, starPoint = false) {
+    const ownerStyle = cell === 'X'
+        ? theme.playerX
+        : cell === 'O'
+            ? theme.playerO
+            : starPoint && !selected
+                ? theme.starPoint
+                : theme.emptyCell;
+    if (winning && cell !== null) {
+        return { ...ownerStyle, bold: true, underline: true };
+    }
+    if (selected && lastMove && cell !== null) {
+        return { ...ownerStyle, ...theme.selectedLatestMove };
+    }
+    if (selected) {
+        return { ...ownerStyle, ...theme.selectedCell };
+    }
+    if (lastMove) {
+        return { ...ownerStyle, ...theme.latestMove };
+    }
+    return ownerStyle;
+}

package/dist/ui/winning.js

@@ -0,0 +1,20 @@
+import { findWinningLine } from '../domain/win.js';
+/**
+ * Coordinates of the engine-confirmed winning run, including runs over five.
+ * The last move is the move that ended a well-formed finished game.
+ */
+export function winningCoordinates(state) {
+    if (state.status !== 'won')
+        return [];
+    const last = state.moves.at(-1);
+    if (!last || last.player !== state.winner)
+        return [];
+    const line = findWinningLine(state.board, last.row, last.col);
+    if (!line || line.player !== state.winner)
+        return [];
+    const [dr, dc] = line.direction;
+    return Array.from({ length: line.count }, (_, index) => ({
+        row: line.start.row + index * dr,
+        col: line.start.col + index * dc,
+    }));
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "gomoku-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Local 15x15 terminal Gomoku against a deterministic machine opponent",
+  "type": "module",
+  "scripts": {
+    "play": "tsx src/cli.tsx",
+    "dev": "tsx watch src/cli.tsx",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "benchmark:bot": "tsx scripts/benchmark-opponent.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.33.0",
+  "dependencies": {
+    "ink": "^8.0.0",
+    "react": "^19.3.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.4",
+    "@types/react": "^19.3.0",
+    "eslint": "^10.12.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "ink-testing-library": "^4.0.0",
+    "prettier": "^3.9.9",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3"
+  },
+  "bin": {
+    "gomoku": "./dist/cli.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "engines": {
+    "node": ">=22"
+  }
+}