@my-games/2048-react 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @my-games/2048-react
 
-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.
+> 2048 游戏的 React 18 组件适配器（函数组件 + Hooks + forwardRef）。
+
+## 安装
+
+```bash
+pnpm add @my-games/2048-react react react-dom
+```
+
+## 用法
+
+```tsx
+import { Game2048 } from '@my-games/2048-react';
+
+export function Demo() {
+  return (
+    <Game2048
+      size={4}
+      saveKey="my-app:2048:save"
+      bestKey="my-app:2048:best"
+      enableAI={false}
+      onMove={(dir, gained) => console.log(dir, gained)}
+      onWon={() => console.log('won')}
+    />
+  );
+}
+```
+
+组件样式已经内嵌（`import '@my-games/2048-core/styles.css'`），不用额外引 CSS。
+
+## Props
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `size` | `3 \| 4 \| 5 \| 6` | `4` | 棋盘边长 |
+| `storage` | `SaveStorage \| null` | `localStorage` | 传 `null` 关闭持久化（SSR） |
+| `saveKey` | `string` | `game-2048:save` | 存档键，多实例分开 |
+| `bestKey` | `string` | `game-2048:best` | 最高分独立键 |
+| `freshStart` | `boolean` | `false` | 忽略已有存档开新局 |
+| `autofocus` | `boolean` | `true` | mount 后自动 focus 让键盘立刻可用 |
+| `enableAI` | `boolean` | `false` | 是否渲染 AI 按钮（API 一直可用） |
+| `aiDepth` | `number` | `3` | expectimax 搜索深度 |
+| `title` | `string` | `'2048'` | 传空串隐藏 header |
+| `onMove` | `(dir, gained) => void` | — | 一次成功的滑动后触发 |
+| `onWon` | `() => void` | — | 首次凑出目标值 |
+| `onLost` | `() => void` | — | 无合法方向 |
+| `className` | `string` | — | 追加到最外层 `<div className="game-2048">` |
+
+## Ref 命令式方法
+
+```tsx
+import { useRef } from 'react';
+import { Game2048, type Game2048Handle } from '@my-games/2048-react';
+
+const g = useRef<Game2048Handle>(null);
+// g.current?.move('left');
+// g.current?.suggestMove();
+// g.current?.aiMove();
+```
+
+## Hook（想自己画 UI）
+
+```tsx
+import { useGame } from '@my-games/2048-react';
+
+function MyBoard() {
+  const { state, move, suggestMove } = useGame({ size: 4 });
+  return <div>{state.score}</div>;
+}
+```
+
+---
+
+完整玩法、引擎 API、设计取舍见仓库根 README：
+<https://github.com/my-gam/2048#readme>
+
+## License
+
+MIT.

package/dist/Game2048.d.ts

@@ -0,0 +1,35 @@
+import '@my-games/2048-core/styles.css';
+import type { Direction, SaveStorage } from '@my-games/2048-core';
+/**
+ * Game2048 —— React 18 组件。与 Vue 版行为对齐：
+ * - 键盘：window keydown + 严格 focus 判定（多实例并存只活动那个响应）；
+ *   方向键 / WASD。
+ * - 触摸：单指 swipe 主导轴 ≥24px；touchstart 时把焦点抢过来。
+ * - 动画：新块 / 合并 / 位移全走 core 的 styles.css。
+ * - AI：`enableAI` prop 控制按钮渲染；通过 ref 一直可以命令式访问。
+ */
+export interface Game2048Props {
+    size?: 3 | 4 | 5 | 6;
+    storage?: SaveStorage | null;
+    saveKey?: string;
+    bestKey?: string;
+    freshStart?: boolean;
+    autofocus?: boolean;
+    enableAI?: boolean;
+    aiDepth?: number;
+    title?: string;
+    onMove?: (dir: Direction, gained: number) => void;
+    onWon?: () => void;
+    onLost?: () => void;
+    className?: string;
+}
+export interface Game2048Handle {
+    suggestMove(): Direction | null;
+    aiMove(): Direction | null;
+    newGame(): void;
+    undo(): boolean;
+    move(dir: Direction): boolean;
+    continuePlaying(): void;
+}
+export declare const Game2048: import("react").ForwardRefExoticComponent<Game2048Props & import("react").RefAttributes<Game2048Handle>>;
+//# sourceMappingURL=Game2048.d.ts.map

package/dist/Game2048.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Game2048.d.ts","sourceRoot":"","sources":["../src/Game2048.tsx"],"names":[],"mappings":"AAYA,OAAO,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlE;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,IAAI,SAAS,GAAG,IAAI,CAAC;IAChC,MAAM,IAAI,SAAS,GAAG,IAAI,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;IAChB,IAAI,IAAI,OAAO,CAAC;IAChB,IAAI,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,eAAe,IAAI,IAAI,CAAC;CACzB;AA0UD,eAAO,MAAM,QAAQ,0GAA4B,CAAC"}

package/dist/Game2048.js

@@ -0,0 +1,164 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import '@my-games/2048-core/styles.css';
+import { useGame } from './useGame';
+const KEY_TO_DIR = {
+    ArrowUp: 'up',
+    ArrowDown: 'down',
+    ArrowLeft: 'left',
+    ArrowRight: 'right',
+    w: 'up',
+    a: 'left',
+    s: 'down',
+    d: 'right',
+    W: 'up',
+    A: 'left',
+    S: 'down',
+    D: 'right'
+};
+function cssVars(vars) {
+    return vars;
+}
+function Game2048Inner(props, ref) {
+    const { size = 4, storage, saveKey, bestKey, freshStart = false, autofocus = true, enableAI = false, aiDepth = 3, title = '2048', onMove, onWon, onLost, className } = props;
+    const { state, move, newGame, undo, continuePlaying, suggestMove, aiMove } = useGame({
+        size,
+        storage,
+        saveKey,
+        bestKey,
+        freshStart,
+        aiDepth
+    });
+    const boardRef = useRef(null);
+    const touchStartPoint = useRef(null);
+    const lastScoreRef = useRef(state.score);
+    const lastStatusRef = useRef(state.status);
+    const [scoreDelta, setScoreDelta] = useState(null);
+    const [aiHint, setAiHint] = useState(null);
+    const deltaTimer = useRef(undefined);
+    // --- 键盘 ---
+    const performMove = useCallback((dir) => {
+        const before = lastScoreRef.current;
+        const ok = move(dir);
+        if (ok) {
+            onMove?.(dir, state.score - before);
+            if (enableAI)
+                setAiHint(null);
+        }
+    }, [move, onMove, state.score, enableAI]);
+    useEffect(() => {
+        const handler = (ev) => {
+            const dir = KEY_TO_DIR[ev.key];
+            if (!dir)
+                return;
+            // 只有本实例 board 有 DOM 焦点时才响应
+            if (document.activeElement !== boardRef.current)
+                return;
+            ev.preventDefault();
+            performMove(dir);
+        };
+        window.addEventListener('keydown', handler, { passive: false });
+        return () => window.removeEventListener('keydown', handler);
+    }, [performMove]);
+    useEffect(() => {
+        if (autofocus)
+            boardRef.current?.focus({ preventScroll: true });
+    }, [autofocus]);
+    // --- 触摸 ---
+    const onTouchStart = (ev) => {
+        if (ev.touches.length !== 1)
+            return;
+        const t = ev.touches[0];
+        if (!t)
+            return;
+        touchStartPoint.current = { x: t.clientX, y: t.clientY };
+        boardRef.current?.focus({ preventScroll: true });
+    };
+    const onTouchEnd = (ev) => {
+        const start = touchStartPoint.current;
+        touchStartPoint.current = null;
+        if (!start)
+            return;
+        const t = ev.changedTouches[0];
+        if (!t)
+            return;
+        const dx = t.clientX - start.x;
+        const dy = t.clientY - start.y;
+        const adx = Math.abs(dx);
+        const ady = Math.abs(dy);
+        if (Math.max(adx, ady) < 24)
+            return;
+        const dir = adx > ady ? (dx > 0 ? 'right' : 'left') : dy > 0 ? 'down' : 'up';
+        performMove(dir);
+    };
+    // --- 分数 delta 与状态副作用 ---
+    useEffect(() => {
+        const gained = state.score - lastScoreRef.current;
+        if (gained > 0) {
+            setScoreDelta({ amount: gained, key: Date.now() + Math.random() });
+            if (deltaTimer.current)
+                window.clearTimeout(deltaTimer.current);
+            deltaTimer.current = window.setTimeout(() => setScoreDelta(null), 700);
+        }
+        lastScoreRef.current = state.score;
+    }, [state.score]);
+    useEffect(() => {
+        if (state.status === lastStatusRef.current)
+            return;
+        if (state.status === 'won')
+            onWon?.();
+        else if (state.status === 'lost')
+            onLost?.();
+        lastStatusRef.current = state.status;
+    }, [state.status, onWon, onLost]);
+    useEffect(() => () => {
+        if (deltaTimer.current)
+            window.clearTimeout(deltaTimer.current);
+    }, []);
+    // --- 渲染派生 ---
+    const gridStyle = useMemo(() => cssVars({
+        gridTemplateColumns: `repeat(${state.size}, 1fr)`,
+        gridTemplateRows: `repeat(${state.size}, 1fr)`
+    }), [state.size]);
+    const boardVars = useMemo(() => cssVars({ '--cols': state.size }), [state.size]);
+    const undoDisabled = state.historySize === 0;
+    const overlayVisible = state.status !== 'playing';
+    const isWon = state.status === 'won';
+    const isLost = state.status === 'lost';
+    useImperativeHandle(ref, () => ({
+        suggestMove,
+        aiMove,
+        newGame,
+        undo,
+        move,
+        continuePlaying
+    }), [suggestMove, aiMove, newGame, undo, move, continuePlaying]);
+    return (_jsxs("div", { className: ['game-2048', className].filter(Boolean).join(' '), children: [title ? (_jsxs("header", { className: "game-2048-header", children: [_jsx("h1", { className: "game-2048-title", children: title }), _jsxs("div", { className: "game-2048-scores", children: [_jsxs("div", { className: "game-2048-score-box", children: [_jsx("span", { className: "label", children: "Score" }), _jsx("span", { className: "value", children: state.score }), scoreDelta ? (_jsxs("span", { className: "delta", children: ["+", scoreDelta.amount] }, scoreDelta.key)) : null] }), _jsxs("div", { className: "game-2048-score-box", children: [_jsx("span", { className: "label", children: "Best" }), _jsx("span", { className: "value", children: state.bestScore })] })] })] })) : null, _jsxs("div", { className: "game-2048-toolbar", children: [_jsxs("p", { className: "game-2048-desc", children: ["\u5408\u5E76\u76F8\u540C\u6570\u5B57\uFF0C\u51B2\u8FC7 ", _jsx("b", { children: "2048" }), "\u3002\u65B9\u5411\u952E / WASD / \u89E6\u5C4F\u6ED1\u52A8\u3002"] }), _jsxs("div", { className: "game-2048-actions", children: [enableAI ? (_jsx("button", { className: "game-2048-button", type: "button", disabled: isLost, onClick: () => setAiHint(suggestMove()), children: "\u63D0\u793A" })) : null, enableAI ? (_jsx("button", { className: "game-2048-button", type: "button", disabled: isLost, onClick: () => {
+                                    const before = state.score;
+                                    const dir = aiMove();
+                                    if (dir) {
+                                        onMove?.(dir, state.score - before);
+                                        setAiHint(null);
+                                    }
+                                }, children: "AI \u5E2E\u8D70" })) : null, _jsx("button", { className: "game-2048-button", type: "button", disabled: undoDisabled, onClick: () => undo(), children: "\u64A4\u9500" }), _jsx("button", { className: "game-2048-button is-primary", type: "button", onClick: () => newGame(), children: "\u65B0\u6E38\u620F" })] })] }), _jsxs("div", { ref: boardRef, className: "game-2048-board", style: boardVars, tabIndex: 0, role: "application", "aria-label": `2048 游戏板 ${state.status}`, onTouchStart: onTouchStart, onTouchEnd: onTouchEnd, children: [_jsx("div", { className: "game-2048-grid", style: gridStyle, children: Array.from({ length: state.size * state.size }).map((_, i) => (_jsx("div", { className: "game-2048-cell" }, i))) }), _jsx("div", { className: "game-2048-tile-layer", children: state.tiles.map((t) => {
+                            const cls = [
+                                'game-2048-tile',
+                                t.isNew ? 'is-new' : '',
+                                t.merged ? 'is-merged' : '',
+                                t.value > 2048 ? 'is-super' : ''
+                            ]
+                                .filter(Boolean)
+                                .join(' ');
+                            return (_jsx("div", { className: cls, style: cssVars({ '--row': t.row, '--col': t.col }), "data-value": t.value, ...(t.value > 2048 ? { 'data-super': '1' } : {}), children: t.value }, t.id));
+                        }) }), enableAI && aiHint ? (_jsxs("div", { className: "game-2048-ai-indicator", style: cssVars({ position: 'absolute', top: '8px', left: '8px', zIndex: 3 }), children: ["\u63A8\u8350\uFF1A", aiHint] })) : null, _jsxs("div", { className: [
+                            'game-2048-overlay',
+                            overlayVisible ? 'is-visible' : '',
+                            isWon ? 'is-won' : '',
+                            isLost ? 'is-lost' : ''
+                        ]
+                            .filter(Boolean)
+                            .join(' '), children: [isWon ? _jsx("h2", { children: "\u4F60\u8D62\u4E86\uFF01" }) : null, isLost ? _jsx("h2", { children: "\u6E38\u620F\u7ED3\u675F" }) : null, _jsxs("div", { className: "row", children: [isWon ? (_jsx("button", { className: "game-2048-button", type: "button", onClick: () => continuePlaying(), children: "\u7EE7\u7EED\u6E38\u620F" })) : null, isLost && !undoDisabled ? (_jsx("button", { className: "game-2048-button", type: "button", onClick: () => undo(), children: "\u6094\u4E00\u6B65" })) : null, overlayVisible ? (_jsx("button", { className: "game-2048-button is-primary", type: "button", onClick: () => newGame(), children: "\u518D\u6765\u4E00\u5C40" })) : null] })] })] })] }));
+}
+export const Game2048 = forwardRef(Game2048Inner);
+Game2048.displayName = 'Game2048';
+//# sourceMappingURL=Game2048.js.map

package/dist/Game2048.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Game2048.js","sourceRoot":"","sources":["../src/Game2048.tsx"],"names":[],"mappings":";AAAA,OAAO,EAIL,UAAU,EACV,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,OAAO,EACP,MAAM,EACN,QAAQ,EACT,MAAM,OAAO,CAAC;AACf,OAAO,gCAAgC,CAAC;AAExC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoCpC,MAAM,UAAU,GAA8B;IAC5C,OAAO,EAAE,IAAI;IACb,SAAS,EAAE,MAAM;IACjB,SAAS,EAAE,MAAM;IACjB,UAAU,EAAE,OAAO;IACnB,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,OAAO;IACV,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,OAAO;CACX,CAAC;AAEF,SAAS,OAAO,CAAC,IAAqC;IACpD,OAAO,IAAqB,CAAC;AAC/B,CAAC;AAED,SAAS,aAAa,CAAC,KAAoB,EAAE,GAAwB;IACnE,MAAM,EACJ,IAAI,GAAG,CAAC,EACR,OAAO,EACP,OAAO,EACP,OAAO,EACP,UAAU,GAAG,KAAK,EAClB,SAAS,GAAG,IAAI,EAChB,QAAQ,GAAG,KAAK,EAChB,OAAO,GAAG,CAAC,EACX,KAAK,GAAG,MAAM,EACd,MAAM,EACN,KAAK,EACL,MAAM,EACN,SAAS,EACV,GAAG,KAAK,CAAC;IAEV,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QACnF,IAAI;QACJ,OAAO;QACP,OAAO;QACP,OAAO;QACP,UAAU;QACV,OAAO;KACR,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,MAAM,CAAiB,IAAI,CAAC,CAAC;IAC9C,MAAM,eAAe,GAAG,MAAM,CAAkC,IAAI,CAAC,CAAC;IACtE,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAE3C,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAyC,IAAI,CAAC,CAAC;IAC3F,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAmB,IAAI,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,MAAM,CAAqB,SAAS,CAAC,CAAC;IAEzD,aAAa;IACb,MAAM,WAAW,GAAG,WAAW,CAC7B,CAAC,GAAc,EAAE,EAAE;QACjB,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC;QACpC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,EAAE,EAAE,CAAC;YACP,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;YACpC,IAAI,QAAQ;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;IACH,CAAC,EACD,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CACtC,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,OAAO,GAAG,CAAC,EAAiB,EAAE,EAAE;YACpC,MAAM,GAAG,GAAG,UAAU,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,GAAG;gBAAE,OAAO;YACjB,2BAA2B;YAC3B,IAAI,QAAQ,CAAC,aAAa,KAAK,QAAQ,CAAC,OAAO;gBAAE,OAAO;YACxD,EAAE,CAAC,cAAc,EAAE,CAAC;YACpB,WAAW,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAChE,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9D,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAElB,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,SAAS;YAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhB,aAAa;IACb,MAAM,YAAY,GAAG,CAAC,EAAmC,EAAE,EAAE;QAC3D,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACpC,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,CAAC,CAAC;YAAE,OAAO;QACf,eAAe,CAAC,OAAO,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QACzD,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC,CAAC;IACF,MAAM,UAAU,GAAG,CAAC,EAAmC,EAAE,EAAE;QACzD,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC;QACtC,eAAe,CAAC,OAAO,GAAG,IAAI,CAAC;QAC/B,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,CAAC,CAAC;YAAE,OAAO;QACf,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC;QAC/B,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE;YAAE,OAAO;QACpC,MAAM,GAAG,GAAc,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QACxF,WAAW,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC,CAAC;IAEF,0BAA0B;IAC1B,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC;QAClD,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,aAAa,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACnE,IAAI,UAAU,CAAC,OAAO;gBAAE,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YAChE,UAAU,CAAC,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACzE,CAAC;QACD,YAAY,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC;IACrC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAElB,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,KAAK,CAAC,MAAM,KAAK,aAAa,CAAC,OAAO;YAAE,OAAO;QACnD,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK;YAAE,KAAK,EAAE,EAAE,CAAC;aACjC,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;YAAE,MAAM,EAAE,EAAE,CAAC;QAC7C,aAAa,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC;IACvC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAElC,SAAS,CACP,GAAG,EAAE,CAAC,GAAG,EAAE;QACT,IAAI,UAAU,CAAC,OAAO;YAAE,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAClE,CAAC,EACD,EAAE,CACH,CAAC;IAEF,eAAe;IACf,MAAM,SAAS,GAAG,OAAO,CACvB,GAAG,EAAE,CACH,OAAO,CAAC;QACN,mBAAmB,EAAE,UAAU,KAAK,CAAC,IAAI,QAAQ;QACjD,gBAAgB,EAAE,UAAU,KAAK,CAAC,IAAI,QAAQ;KAC/C,CAAC,EACJ,CAAC,KAAK,CAAC,IAAI,CAAC,CACb,CAAC;IACF,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACjF,MAAM,YAAY,GAAG,KAAK,CAAC,WAAW,KAAK,CAAC,CAAC;IAC7C,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC;IAEvC,mBAAmB,CACjB,GAAG,EACH,GAAG,EAAE,CAAC,CAAC;QACL,WAAW;QACX,MAAM;QACN,OAAO;QACP,IAAI;QACJ,IAAI;QACJ,eAAe;KAChB,CAAC,EACF,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC,CAC5D,CAAC;IAEF,OAAO,CACL,eAAK,SAAS,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,aAC/D,KAAK,CAAC,CAAC,CAAC,CACP,kBAAQ,SAAS,EAAC,kBAAkB,aAClC,aAAI,SAAS,EAAC,iBAAiB,YAAE,KAAK,GAAM,EAC5C,eAAK,SAAS,EAAC,kBAAkB,aAC/B,eAAK,SAAS,EAAC,qBAAqB,aAClC,eAAM,SAAS,EAAC,OAAO,sBAAa,EACpC,eAAM,SAAS,EAAC,OAAO,YAAE,KAAK,CAAC,KAAK,GAAQ,EAC3C,UAAU,CAAC,CAAC,CAAC,CACZ,gBAA2B,SAAS,EAAC,OAAO,kBACxC,UAAU,CAAC,MAAM,KADV,UAAU,CAAC,GAAG,CAElB,CACR,CAAC,CAAC,CAAC,IAAI,IACJ,EACN,eAAK,SAAS,EAAC,qBAAqB,aAClC,eAAM,SAAS,EAAC,OAAO,qBAAY,EACnC,eAAM,SAAS,EAAC,OAAO,YAAE,KAAK,CAAC,SAAS,GAAQ,IAC5C,IACF,IACC,CACV,CAAC,CAAC,CAAC,IAAI,EAER,eAAK,SAAS,EAAC,mBAAmB,aAChC,aAAG,SAAS,EAAC,gBAAgB,wEACjB,+BAAW,wEACnB,EACJ,eAAK,SAAS,EAAC,mBAAmB,aAC/B,QAAQ,CAAC,CAAC,CAAC,CACV,iBACE,SAAS,EAAC,kBAAkB,EAC5B,IAAI,EAAC,QAAQ,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,6BAGhC,CACV,CAAC,CAAC,CAAC,IAAI,EACP,QAAQ,CAAC,CAAC,CAAC,CACV,iBACE,SAAS,EAAC,kBAAkB,EAC5B,IAAI,EAAC,QAAQ,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,EAAE;oCACZ,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC;oCAC3B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC;oCACrB,IAAI,GAAG,EAAE,CAAC;wCACR,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;wCACpC,SAAS,CAAC,IAAI,CAAC,CAAC;oCAClB,CAAC;gCACH,CAAC,gCAGM,CACV,CAAC,CAAC,CAAC,IAAI,EACR,iBACE,SAAS,EAAC,kBAAkB,EAC5B,IAAI,EAAC,QAAQ,EACb,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,6BAGd,EACT,iBACE,SAAS,EAAC,6BAA6B,EACvC,IAAI,EAAC,QAAQ,EACb,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,mCAGjB,IACL,IACF,EAEN,eACE,GAAG,EAAE,QAAQ,EACb,SAAS,EAAC,iBAAiB,EAC3B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,CAAC,EACX,IAAI,EAAC,aAAa,gBACN,YAAY,KAAK,CAAC,MAAM,EAAE,EACtC,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,UAAU,aAEtB,cAAK,SAAS,EAAC,gBAAgB,EAAC,KAAK,EAAE,SAAS,YAC7C,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAC7D,cAAa,SAAS,EAAC,gBAAgB,IAA7B,CAAC,CAA+B,CAC3C,CAAC,GACE,EACN,cAAK,SAAS,EAAC,sBAAsB,YAClC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;4BACrB,MAAM,GAAG,GAAG;gCACV,gBAAgB;gCAChB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;gCACvB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;gCAC3B,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;6BACjC;iCACE,MAAM,CAAC,OAAO,CAAC;iCACf,IAAI,CAAC,GAAG,CAAC,CAAC;4BACb,OAAO,CACL,cAEE,SAAS,EAAE,GAAG,EACd,KAAK,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,gBACtC,CAAC,CAAC,KAAK,KACf,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,YAEhD,CAAC,CAAC,KAAK,IANH,CAAC,CAAC,EAAE,CAOL,CACP,CAAC;wBACJ,CAAC,CAAC,GACE,EAEL,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,CACpB,eACE,SAAS,EAAC,wBAAwB,EAClC,KAAK,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,mCAExE,MAAM,IACN,CACP,CAAC,CAAC,CAAC,IAAI,EAER,eACE,SAAS,EAAE;4BACT,mBAAmB;4BACnB,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE;4BAClC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;4BACrB,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;yBACxB;6BACE,MAAM,CAAC,OAAO,CAAC;6BACf,IAAI,CAAC,GAAG,CAAC,aAEX,KAAK,CAAC,CAAC,CAAC,oDAAa,CAAC,CAAC,CAAC,IAAI,EAC5B,MAAM,CAAC,CAAC,CAAC,oDAAa,CAAC,CAAC,CAAC,IAAI,EAC9B,eAAK,SAAS,EAAC,KAAK,aACjB,KAAK,CAAC,CAAC,CAAC,CACP,iBACE,SAAS,EAAC,kBAAkB,EAC5B,IAAI,EAAC,QAAQ,EACb,OAAO,EAAE,GAAG,EAAE,CAAC,eAAe,EAAE,yCAGzB,CACV,CAAC,CAAC,CAAC,IAAI,EACP,MAAM,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CACzB,iBACE,SAAS,EAAC,kBAAkB,EAC5B,IAAI,EAAC,QAAQ,EACb,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,mCAGd,CACV,CAAC,CAAC,CAAC,IAAI,EACP,cAAc,CAAC,CAAC,CAAC,CAChB,iBACE,SAAS,EAAC,6BAA6B,EACvC,IAAI,EAAC,QAAQ,EACb,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,yCAGjB,CACV,CAAC,CAAC,CAAC,IAAI,IACJ,IACF,IACF,IACF,CACP,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC;AAClD,QAAQ,CAAC,WAAW,GAAG,UAAU,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Game2048, type Game2048Props, type Game2048Handle } from './Game2048';
+export { useGame, type UseGameOptions, type UseGameReturn } from './useGame';
+export type { BoardSize, Direction, GameState, GameStatus, SaveStorage, Tile } from '@my-games/2048-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE7E,YAAY,EACV,SAAS,EACT,SAAS,EACT,SAAS,EACT,UAAU,EACV,WAAW,EACX,IAAI,EACL,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Game2048 } from './Game2048';
+export { useGame } from './useGame';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAA2C,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,OAAO,EAA2C,MAAM,WAAW,CAAC"}

package/dist/useGame.d.ts

@@ -0,0 +1,25 @@
+import { Game2048, type Direction, type GameOptions, type GameState } from '@my-games/2048-core';
+/**
+ * `useGame` —— React Hook 版引擎桥接。
+ *
+ * - 引擎实例在 `useMemo` 里按 `size`/`saveKey` 等关键 prop 缓存，避免每次 render
+ *   重新构造；这些 prop 变化 = 重开一局，视为预期语义。
+ * - `useState` 订阅引擎快照；`useEffect` 里挂 unsubscribe 防泄漏。
+ * - 用 `useRef` 保留最新 game 实例给 imperative handler（move / undo）用，
+ *   防止闭包过期。
+ */
+export interface UseGameOptions extends GameOptions {
+    aiDepth?: number;
+}
+export interface UseGameReturn {
+    state: GameState;
+    game: Game2048;
+    move: (dir: Direction) => boolean;
+    newGame: () => void;
+    undo: () => boolean;
+    continuePlaying: () => void;
+    suggestMove: () => Direction | null;
+    aiMove: () => Direction | null;
+}
+export declare function useGame(options?: UseGameOptions): UseGameReturn;
+//# sourceMappingURL=useGame.d.ts.map

package/dist/useGame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGame.d.ts","sourceRoot":"","sources":["../src/useGame.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,QAAQ,EACR,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC;IAClC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC;IACpB,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,SAAS,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,MAAM,SAAS,GAAG,IAAI,CAAC;CAChC;AAED,wBAAgB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,aAAa,CAoCnE"}

package/dist/useGame.js

@@ -0,0 +1,34 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { bestMove as aiBestMove, Game2048 } from '@my-games/2048-core';
+export function useGame(options = {}) {
+    const { aiDepth = 3, size, storage, saveKey, bestKey, freshStart, target, undoLimit, rng } = options;
+    // useMemo 依赖里不放 rng / storage（函数/对象引用不稳定；重开一次即可）
+    const game = useMemo(() => new Game2048({ size, storage, saveKey, bestKey, freshStart, target, undoLimit, rng }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [size, saveKey, bestKey, target, undoLimit]);
+    const gameRef = useRef(game);
+    gameRef.current = game;
+    const [state, setState] = useState(() => game.getState());
+    useEffect(() => {
+        // 引擎替换时重新订阅；先把 state 拉齐到最新，防止首帧错位
+        setState(game.getState());
+        const unsub = game.subscribe((s) => setState(s));
+        return unsub;
+    }, [game]);
+    return {
+        state,
+        game,
+        move: (dir) => gameRef.current.move(dir),
+        newGame: () => gameRef.current.newGame(),
+        undo: () => gameRef.current.undo(),
+        continuePlaying: () => gameRef.current.continuePlaying(),
+        suggestMove: () => aiBestMove(gameRef.current.getGridValues(), { depth: aiDepth }),
+        aiMove: () => {
+            const dir = aiBestMove(gameRef.current.getGridValues(), { depth: aiDepth });
+            if (dir)
+                gameRef.current.move(dir);
+            return dir;
+        }
+    };
+}
+//# sourceMappingURL=useGame.js.map

package/dist/useGame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGame.js","sourceRoot":"","sources":["../src/useGame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC7D,OAAO,EACL,QAAQ,IAAI,UAAU,EACtB,QAAQ,EAIT,MAAM,qBAAqB,CAAC;AA0B7B,MAAM,UAAU,OAAO,CAAC,UAA0B,EAAE;IAClD,MAAM,EAAE,OAAO,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAErG,iDAAiD;IACjD,MAAM,IAAI,GAAG,OAAO,CAClB,GAAG,EAAE,CAAC,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;IAC3F,uDAAuD;IACvD,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAC5C,CAAC;IAEF,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAEvB,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAY,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAErE,SAAS,CAAC,GAAG,EAAE;QACb,kCAAkC;QAClC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,OAAO;QACL,KAAK;QACL,IAAI;QACJ,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;QACxC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE;QACxC,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE;QAClC,eAAe,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE;QACxD,WAAW,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAClF,MAAM,EAAE,GAAG,EAAE;YACX,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YAC5E,IAAI,GAAG;gBAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnC,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@my-games/2048-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "2048 游戏的 React 18 组件适配器（函数组件 + Hooks）。",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "@my-games/2048-core/styles.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "dependencies": {
+    "@my-games/2048-core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.11",
+    "@types/react-dom": "^18.3.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "2048",
+    "react",
+    "react18",
+    "game",
+    "puzzle",
+    "component",
+    "hooks"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "xyj2156"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/my-gam/2048.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/my-gam/2048/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/my-gam/2048/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
 }

package/src/Game2048.tsx

@@ -0,0 +1,380 @@
+import {
+  type CSSProperties,
+  type Ref,
+  type TouchEvent as ReactTouchEvent,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState
+} from 'react';
+import '@my-games/2048-core/styles.css';
+import type { Direction, SaveStorage } from '@my-games/2048-core';
+import { useGame } from './useGame';
+
+/**
+ * Game2048 —— React 18 组件。与 Vue 版行为对齐：
+ * - 键盘：window keydown + 严格 focus 判定（多实例并存只活动那个响应）；
+ *   方向键 / WASD。
+ * - 触摸：单指 swipe 主导轴 ≥24px；touchstart 时把焦点抢过来。
+ * - 动画：新块 / 合并 / 位移全走 core 的 styles.css。
+ * - AI：`enableAI` prop 控制按钮渲染；通过 ref 一直可以命令式访问。
+ */
+
+export interface Game2048Props {
+  size?: 3 | 4 | 5 | 6;
+  storage?: SaveStorage | null;
+  saveKey?: string;
+  bestKey?: string;
+  freshStart?: boolean;
+  autofocus?: boolean;
+  enableAI?: boolean;
+  aiDepth?: number;
+  title?: string;
+  onMove?: (dir: Direction, gained: number) => void;
+  onWon?: () => void;
+  onLost?: () => void;
+  className?: string;
+}
+
+export interface Game2048Handle {
+  suggestMove(): Direction | null;
+  aiMove(): Direction | null;
+  newGame(): void;
+  undo(): boolean;
+  move(dir: Direction): boolean;
+  continuePlaying(): void;
+}
+
+const KEY_TO_DIR: Record<string, Direction> = {
+  ArrowUp: 'up',
+  ArrowDown: 'down',
+  ArrowLeft: 'left',
+  ArrowRight: 'right',
+  w: 'up',
+  a: 'left',
+  s: 'down',
+  d: 'right',
+  W: 'up',
+  A: 'left',
+  S: 'down',
+  D: 'right'
+};
+
+function cssVars(vars: Record<string, string | number>): CSSProperties {
+  return vars as CSSProperties;
+}
+
+function Game2048Inner(props: Game2048Props, ref: Ref<Game2048Handle>) {
+  const {
+    size = 4,
+    storage,
+    saveKey,
+    bestKey,
+    freshStart = false,
+    autofocus = true,
+    enableAI = false,
+    aiDepth = 3,
+    title = '2048',
+    onMove,
+    onWon,
+    onLost,
+    className
+  } = props;
+
+  const { state, move, newGame, undo, continuePlaying, suggestMove, aiMove } = useGame({
+    size,
+    storage,
+    saveKey,
+    bestKey,
+    freshStart,
+    aiDepth
+  });
+
+  const boardRef = useRef<HTMLDivElement>(null);
+  const touchStartPoint = useRef<{ x: number; y: number } | null>(null);
+  const lastScoreRef = useRef(state.score);
+  const lastStatusRef = useRef(state.status);
+
+  const [scoreDelta, setScoreDelta] = useState<{ amount: number; key: number } | null>(null);
+  const [aiHint, setAiHint] = useState<Direction | null>(null);
+  const deltaTimer = useRef<number | undefined>(undefined);
+
+  // --- 键盘 ---
+  const performMove = useCallback(
+    (dir: Direction) => {
+      const before = lastScoreRef.current;
+      const ok = move(dir);
+      if (ok) {
+        onMove?.(dir, state.score - before);
+        if (enableAI) setAiHint(null);
+      }
+    },
+    [move, onMove, state.score, enableAI]
+  );
+
+  useEffect(() => {
+    const handler = (ev: KeyboardEvent) => {
+      const dir = KEY_TO_DIR[ev.key];
+      if (!dir) return;
+      // 只有本实例 board 有 DOM 焦点时才响应
+      if (document.activeElement !== boardRef.current) return;
+      ev.preventDefault();
+      performMove(dir);
+    };
+    window.addEventListener('keydown', handler, { passive: false });
+    return () => window.removeEventListener('keydown', handler);
+  }, [performMove]);
+
+  useEffect(() => {
+    if (autofocus) boardRef.current?.focus({ preventScroll: true });
+  }, [autofocus]);
+
+  // --- 触摸 ---
+  const onTouchStart = (ev: ReactTouchEvent<HTMLDivElement>) => {
+    if (ev.touches.length !== 1) return;
+    const t = ev.touches[0];
+    if (!t) return;
+    touchStartPoint.current = { x: t.clientX, y: t.clientY };
+    boardRef.current?.focus({ preventScroll: true });
+  };
+  const onTouchEnd = (ev: ReactTouchEvent<HTMLDivElement>) => {
+    const start = touchStartPoint.current;
+    touchStartPoint.current = null;
+    if (!start) return;
+    const t = ev.changedTouches[0];
+    if (!t) return;
+    const dx = t.clientX - start.x;
+    const dy = t.clientY - start.y;
+    const adx = Math.abs(dx);
+    const ady = Math.abs(dy);
+    if (Math.max(adx, ady) < 24) return;
+    const dir: Direction = adx > ady ? (dx > 0 ? 'right' : 'left') : dy > 0 ? 'down' : 'up';
+    performMove(dir);
+  };
+
+  // --- 分数 delta 与状态副作用 ---
+  useEffect(() => {
+    const gained = state.score - lastScoreRef.current;
+    if (gained > 0) {
+      setScoreDelta({ amount: gained, key: Date.now() + Math.random() });
+      if (deltaTimer.current) window.clearTimeout(deltaTimer.current);
+      deltaTimer.current = window.setTimeout(() => setScoreDelta(null), 700);
+    }
+    lastScoreRef.current = state.score;
+  }, [state.score]);
+
+  useEffect(() => {
+    if (state.status === lastStatusRef.current) return;
+    if (state.status === 'won') onWon?.();
+    else if (state.status === 'lost') onLost?.();
+    lastStatusRef.current = state.status;
+  }, [state.status, onWon, onLost]);
+
+  useEffect(
+    () => () => {
+      if (deltaTimer.current) window.clearTimeout(deltaTimer.current);
+    },
+    []
+  );
+
+  // --- 渲染派生 ---
+  const gridStyle = useMemo(
+    () =>
+      cssVars({
+        gridTemplateColumns: `repeat(${state.size}, 1fr)`,
+        gridTemplateRows: `repeat(${state.size}, 1fr)`
+      }),
+    [state.size]
+  );
+  const boardVars = useMemo(() => cssVars({ '--cols': state.size }), [state.size]);
+  const undoDisabled = state.historySize === 0;
+  const overlayVisible = state.status !== 'playing';
+  const isWon = state.status === 'won';
+  const isLost = state.status === 'lost';
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      suggestMove,
+      aiMove,
+      newGame,
+      undo,
+      move,
+      continuePlaying
+    }),
+    [suggestMove, aiMove, newGame, undo, move, continuePlaying]
+  );
+
+  return (
+    <div className={['game-2048', className].filter(Boolean).join(' ')}>
+      {title ? (
+        <header className="game-2048-header">
+          <h1 className="game-2048-title">{title}</h1>
+          <div className="game-2048-scores">
+            <div className="game-2048-score-box">
+              <span className="label">Score</span>
+              <span className="value">{state.score}</span>
+              {scoreDelta ? (
+                <span key={scoreDelta.key} className="delta">
+                  +{scoreDelta.amount}
+                </span>
+              ) : null}
+            </div>
+            <div className="game-2048-score-box">
+              <span className="label">Best</span>
+              <span className="value">{state.bestScore}</span>
+            </div>
+          </div>
+        </header>
+      ) : null}
+
+      <div className="game-2048-toolbar">
+        <p className="game-2048-desc">
+          合并相同数字，冲过 <b>2048</b>。方向键 / WASD / 触屏滑动。
+        </p>
+        <div className="game-2048-actions">
+          {enableAI ? (
+            <button
+              className="game-2048-button"
+              type="button"
+              disabled={isLost}
+              onClick={() => setAiHint(suggestMove())}
+            >
+              提示
+            </button>
+          ) : null}
+          {enableAI ? (
+            <button
+              className="game-2048-button"
+              type="button"
+              disabled={isLost}
+              onClick={() => {
+                const before = state.score;
+                const dir = aiMove();
+                if (dir) {
+                  onMove?.(dir, state.score - before);
+                  setAiHint(null);
+                }
+              }}
+            >
+              AI 帮走
+            </button>
+          ) : null}
+          <button
+            className="game-2048-button"
+            type="button"
+            disabled={undoDisabled}
+            onClick={() => undo()}
+          >
+            撤销
+          </button>
+          <button
+            className="game-2048-button is-primary"
+            type="button"
+            onClick={() => newGame()}
+          >
+            新游戏
+          </button>
+        </div>
+      </div>
+
+      <div
+        ref={boardRef}
+        className="game-2048-board"
+        style={boardVars}
+        tabIndex={0}
+        role="application"
+        aria-label={`2048 游戏板 ${state.status}`}
+        onTouchStart={onTouchStart}
+        onTouchEnd={onTouchEnd}
+      >
+        <div className="game-2048-grid" style={gridStyle}>
+          {Array.from({ length: state.size * state.size }).map((_, i) => (
+            <div key={i} className="game-2048-cell" />
+          ))}
+        </div>
+        <div className="game-2048-tile-layer">
+          {state.tiles.map((t) => {
+            const cls = [
+              'game-2048-tile',
+              t.isNew ? 'is-new' : '',
+              t.merged ? 'is-merged' : '',
+              t.value > 2048 ? 'is-super' : ''
+            ]
+              .filter(Boolean)
+              .join(' ');
+            return (
+              <div
+                key={t.id}
+                className={cls}
+                style={cssVars({ '--row': t.row, '--col': t.col })}
+                data-value={t.value}
+                {...(t.value > 2048 ? { 'data-super': '1' } : {})}
+              >
+                {t.value}
+              </div>
+            );
+          })}
+        </div>
+
+        {enableAI && aiHint ? (
+          <div
+            className="game-2048-ai-indicator"
+            style={cssVars({ position: 'absolute', top: '8px', left: '8px', zIndex: 3 })}
+          >
+            推荐：{aiHint}
+          </div>
+        ) : null}
+
+        <div
+          className={[
+            'game-2048-overlay',
+            overlayVisible ? 'is-visible' : '',
+            isWon ? 'is-won' : '',
+            isLost ? 'is-lost' : ''
+          ]
+            .filter(Boolean)
+            .join(' ')}
+        >
+          {isWon ? <h2>你赢了！</h2> : null}
+          {isLost ? <h2>游戏结束</h2> : null}
+          <div className="row">
+            {isWon ? (
+              <button
+                className="game-2048-button"
+                type="button"
+                onClick={() => continuePlaying()}
+              >
+                继续游戏
+              </button>
+            ) : null}
+            {isLost && !undoDisabled ? (
+              <button
+                className="game-2048-button"
+                type="button"
+                onClick={() => undo()}
+              >
+                悔一步
+              </button>
+            ) : null}
+            {overlayVisible ? (
+              <button
+                className="game-2048-button is-primary"
+                type="button"
+                onClick={() => newGame()}
+              >
+                再来一局
+              </button>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export const Game2048 = forwardRef(Game2048Inner);
+Game2048.displayName = 'Game2048';

package/src/index.ts

@@ -0,0 +1,11 @@
+export { Game2048, type Game2048Props, type Game2048Handle } from './Game2048';
+export { useGame, type UseGameOptions, type UseGameReturn } from './useGame';
+
+export type {
+  BoardSize,
+  Direction,
+  GameState,
+  GameStatus,
+  SaveStorage,
+  Tile
+} from '@my-games/2048-core';

package/src/useGame.ts

@@ -0,0 +1,70 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import {
+  bestMove as aiBestMove,
+  Game2048,
+  type Direction,
+  type GameOptions,
+  type GameState
+} from '@my-games/2048-core';
+
+/**
+ * `useGame` —— React Hook 版引擎桥接。
+ *
+ * - 引擎实例在 `useMemo` 里按 `size`/`saveKey` 等关键 prop 缓存，避免每次 render
+ *   重新构造；这些 prop 变化 = 重开一局，视为预期语义。
+ * - `useState` 订阅引擎快照；`useEffect` 里挂 unsubscribe 防泄漏。
+ * - 用 `useRef` 保留最新 game 实例给 imperative handler（move / undo）用，
+ *   防止闭包过期。
+ */
+export interface UseGameOptions extends GameOptions {
+  aiDepth?: number;
+}
+
+export interface UseGameReturn {
+  state: GameState;
+  game: Game2048;
+  move: (dir: Direction) => boolean;
+  newGame: () => void;
+  undo: () => boolean;
+  continuePlaying: () => void;
+  suggestMove: () => Direction | null;
+  aiMove: () => Direction | null;
+}
+
+export function useGame(options: UseGameOptions = {}): UseGameReturn {
+  const { aiDepth = 3, size, storage, saveKey, bestKey, freshStart, target, undoLimit, rng } = options;
+
+  // useMemo 依赖里不放 rng / storage（函数/对象引用不稳定；重开一次即可）
+  const game = useMemo(
+    () => new Game2048({ size, storage, saveKey, bestKey, freshStart, target, undoLimit, rng }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [size, saveKey, bestKey, target, undoLimit]
+  );
+
+  const gameRef = useRef(game);
+  gameRef.current = game;
+
+  const [state, setState] = useState<GameState>(() => game.getState());
+
+  useEffect(() => {
+    // 引擎替换时重新订阅；先把 state 拉齐到最新，防止首帧错位
+    setState(game.getState());
+    const unsub = game.subscribe((s) => setState(s));
+    return unsub;
+  }, [game]);
+
+  return {
+    state,
+    game,
+    move: (dir) => gameRef.current.move(dir),
+    newGame: () => gameRef.current.newGame(),
+    undo: () => gameRef.current.undo(),
+    continuePlaying: () => gameRef.current.continuePlaying(),
+    suggestMove: () => aiBestMove(gameRef.current.getGridValues(), { depth: aiDepth }),
+    aiMove: () => {
+      const dir = aiBestMove(gameRef.current.getGridValues(), { depth: aiDepth });
+      if (dir) gameRef.current.move(dir);
+      return dir;
+    }
+  };
+}