@scriptonita/chess-football-ui 0.9.0 → 0.10.0

package/README.md

@@ -67,6 +67,45 @@ expect(REQUIRED_TOKENS.filter(t => !css.includes(`${t}:`))).toEqual([])
 `--field-frame` is new in 0.9.0: the board frame was hardcoded `#1a3317` in three places,
 hand-tuned for the webapp's grass and visibly wrong against the CrazyGames pitch.
 
+`--ball-color` joins the contract in 0.10.0: the ball was a hardcoded sky blue, the same
+hue as `--pass-highlight`, while both apps defined a `--ball-color` nobody read.
+
+## Bot turn
+
+`useBotTurn` owns a bot's turn end to end — entry gates (turn, pending goal, match over),
+timed replay, cancellation on unmount, error + retry, and skip. The app only says where the
+turn comes from, so the same hook serves a local search and a server call:
+
+```tsx
+import { useBotTurn } from '@scriptonita/chess-football-ui'
+import { playBotTurn } from '@scriptonita/chess-football-engine'
+
+const { botThinking, error, retry, skip } = useBotTurn({
+  boardState, botSide,
+  getTurn: (board, side) => playBotTurn(bot, board, side),       // local
+  // getTurn: (board) => fetch('/api/turn', …).then(r => r.json()), // server
+  onApplyState: setBoardState,
+  matchOver: !!matchResult,
+  goalPending: !!goalScored,
+})
+```
+
+Pacing is fixed in one place: `BOT_TURN_START_DELAY_MS` (400) before the first action,
+`BOT_TURN_STEP_MS` (900) between actions and `BOT_TURN_SETTLE_MS` (500) for the last one to
+land. The closing end-of-turn state takes no step of its own, so a full 5-AP turn lasts 4.5 s.
+
+## First-match hints
+
+`<GameHints userSide seen onSeen />` shows one dismissible sentence the first time each
+situation happens (`GAME_HINT_IDS`: first turn, selecting a piece, holding the ball, last
+action point). The texts are `hints.*` keys of `GAME_I18N_KEYS`. The app decides when to mount
+it and where `seen` is stored.
+
+## Forgiving taps
+
+`<GameBoard forgivingTaps />` resolves a touch on an empty square that borders exactly one
+legal target to that target. Opt-in, touch only, never when the tap is ambiguous.
+
 ## Peer dependencies
 
 `react`, `react-dom`, `framer-motion`, `lucide-react`.

package/dist/index.cjs

@@ -44,12 +44,17 @@ var EMBOSS_FILTER = {
   white: "drop-shadow(0 -0.75px 0 rgba(255,255,255,0.65)) drop-shadow(0 1.25px 1px rgba(0,0,0,0.45))",
   black: "drop-shadow(0 -0.5px 0 rgba(255,255,255,0.3)) drop-shadow(0 1.25px 1.5px rgba(0,0,0,0.8))"
 };
-var PieceIcon = ({ type, side }) => {
+var MOVED_GLYPH_COLOR = {
+  white: "#8b8b94",
+  black: "#bdbdc3"
+};
+var PieceIcon = ({ type, side, moved = false }) => {
   const Icon = PIECE_ICON[type] ?? lucideReact.ShieldQuestion;
   const style = {
     width: "clamp(16px, 7.4cqw, 44px)",
     height: "clamp(16px, 7.4cqw, 44px)",
-    filter: EMBOSS_FILTER[side]
+    filter: EMBOSS_FILTER[side],
+    ...moved ? { color: MOVED_GLYPH_COLOR[side] } : null
   };
   return /* @__PURE__ */ jsxRuntime.jsx(Icon, { style, strokeWidth: 2, "aria-hidden": "true" });
 };
@@ -93,24 +98,20 @@ var ON_BOARD_CHIP_STYLE = {
     ].join(", ")
   }
 };
-var MOVED_STYLE = {
-  filter: "saturate(0.15) brightness(0.75)"
-};
 function GamePiece({ piece, isSelected, hasBall, onClick, isMoving = false }) {
   const chipStyle = ON_BOARD_CHIP_STYLE[piece.side];
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
       onClick,
-      style: piece.hasMovedThisTurn ? MOVED_STYLE : void 0,
+      "data-moved": piece.hasMovedThisTurn ? "true" : "false",
       className: cn(
         "relative w-[88%] h-[88%] rounded-full cursor-pointer z-10 transition-transform duration-200 ease-out motion-reduce:transition-none",
         // `--primary` was the package's one remaining shadcn token, and
         // CrazyGames had to define it by hand just to make the selection
         // ring visible. It is part of the design system now.
         isSelected && "ring-4 ring-accent-green scale-110 z-30",
-        isMoving && "scale-[1.08] z-40",
-        piece.hasMovedThisTurn && "opacity-70"
+        isMoving && "scale-[1.08] z-40"
       ),
       children: [
         /* @__PURE__ */ jsxRuntime.jsx(
@@ -132,7 +133,7 @@ function GamePiece({ piece, isSelected, hasBall, onClick, isMoving = false }) {
             style: chipStyle,
             className: "absolute inset-0 rounded-full flex items-center justify-center",
             children: [
-              /* @__PURE__ */ jsxRuntime.jsx(PieceIcon, { type: piece.type, side: piece.side }),
+              /* @__PURE__ */ jsxRuntime.jsx(PieceIcon, { type: piece.type, side: piece.side, moved: piece.hasMovedThisTurn }),
               hasBall && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "absolute inset-0 rounded-full ring-2 ring-orange-400 pointer-events-none" }),
               isSelected && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "absolute inset-0 rounded-full animate-pulse motion-reduce:animate-none ring-2 ring-yellow-400 ring-offset-2 ring-offset-transparent" })
             ]
@@ -142,6 +143,8 @@ function GamePiece({ piece, isSelected, hasBall, onClick, isMoving = false }) {
     }
   );
 }
+var BALL_COLOR = "var(--ball-color, #ffffff)";
+var BALL_SHADE = "color-mix(in srgb, var(--ball-color, #ffffff) 74%, #000000)";
 var Football = ({ className }) => {
   const bodyId = React.useId();
   const hiId = `${bodyId}-h`;
@@ -155,9 +158,9 @@ var Football = ({ className }) => {
       children: [
         /* @__PURE__ */ jsxRuntime.jsxs("defs", { children: [
           /* @__PURE__ */ jsxRuntime.jsxs("radialGradient", { id: bodyId, cx: "36%", cy: "32%", r: "68%", children: [
-            /* @__PURE__ */ jsxRuntime.jsx("stop", { offset: "0%", stopColor: "#f0f9ff" }),
-            /* @__PURE__ */ jsxRuntime.jsx("stop", { offset: "55%", stopColor: "#bae6fd" }),
-            /* @__PURE__ */ jsxRuntime.jsx("stop", { offset: "100%", stopColor: "#38bdf8" })
+            /* @__PURE__ */ jsxRuntime.jsx("stop", { offset: "0%", style: { stopColor: "#ffffff" } }),
+            /* @__PURE__ */ jsxRuntime.jsx("stop", { offset: "55%", style: { stopColor: BALL_COLOR } }),
+            /* @__PURE__ */ jsxRuntime.jsx("stop", { offset: "100%", style: { stopColor: BALL_SHADE } })
           ] }),
           /* @__PURE__ */ jsxRuntime.jsxs("radialGradient", { id: hiId, cx: "32%", cy: "28%", r: "22%", children: [
             /* @__PURE__ */ jsxRuntime.jsx("stop", { offset: "0%", stopColor: "#ffffff", stopOpacity: "0.85" }),
@@ -200,6 +203,11 @@ var STATIC_I18N_KEYS = [
   "endTurnConfirmDescription",
   "endTurnConfirmYes",
   "endTurnKeepPlaying",
+  "hints.dismiss",
+  "hints.hasBall",
+  "hints.lastActionPoint",
+  "hints.selectPiece",
+  "hints.start",
   "history.empty",
   "history.goal",
   "history.interception",
@@ -462,9 +470,10 @@ var ROWS = 12;
 var clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
 var cellX = (x) => `${x * 100}%`;
 var cellY = (y) => `${(ROWS - 1 - y) * 100}%`;
+var TOUCH_CLICK_WINDOW_MS = 800;
 var PIECE_SLIDE = { type: "spring", stiffness: 190, damping: 28, mass: 1 };
 var BALL_SLIDE = { type: "spring", stiffness: 300, damping: 26, mass: 0.6 };
-function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, toolbar = true, className }) {
+function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, toolbar = true, forgivingTaps = false, className }) {
   const t = useGameT();
   const boardId = React.useId();
   const prefersReducedMotion = framerMotion.useReducedMotion();
@@ -508,6 +517,7 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
     setInvalidClickAt({ x, y, nonce: invalidClickNonceRef.current });
   };
   const [hoveredPassAt, setHoveredPassAt] = React.useState(null);
+  const lastTouchAtRef = React.useRef(0);
   const [movingIds, setMovingIds] = React.useState(() => /* @__PURE__ */ new Set());
   const setMoving = (id, moving) => setMovingIds((prev) => {
     if (prev.has(id) === moving) return prev;
@@ -593,11 +603,24 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
   const passCarrier = boardState.pieces.find((p) => p.id === selectedPieceId && boardState.ball.holderId === p.id) ?? null;
   const trajectoryPath = hoveredPassAt && passCarrier ? passCarrier.type === "knight" ? [hoveredPassAt] : chessFootballEngine.getPath(passCarrier.pos, hoveredPassAt) : null;
   const trajectoryIntercepted = !!(trajectoryPath && passCarrier && trajectoryPath.some((sq) => boardState.pieces.some((p) => p.pos.x === sq.x && p.pos.y === sq.y && p.side !== passCarrier.side)));
-  const handleSquareClick = (x, y) => {
+  const soleAdjacentTarget = (x, y) => {
+    const near = [...validMoves, ...validPasses].filter(
+      (t2, i, all) => Math.max(Math.abs(t2.x - x), Math.abs(t2.y - y)) === 1 && all.findIndex((o) => o.x === t2.x && o.y === t2.y) === i
+    );
+    return near.length === 1 ? near[0] : null;
+  };
+  const handleSquareClick = (x, y, fromTouch = false) => {
     if (replay) return;
     setCursor(null);
     const isValidMove = validMoves.some((m) => m.x === x && m.y === y);
     const isValidPass = validPasses.some((p) => p.x === x && p.y === y);
+    if (!isValidMove && !isValidPass && fromTouch && forgivingTaps && selectedPieceId) {
+      const target = soleAdjacentTarget(x, y);
+      if (target) {
+        handleSquareClick(target.x, target.y);
+        return;
+      }
+    }
     if (isValidMove && isValidPass) {
       setDisambiguateAt({ x, y });
       return;
@@ -754,12 +777,13 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
               role: "gridcell",
               "aria-label": squareLabel(x, y, pieceAt, isValidMove, isValidPass),
               "aria-selected": !!pieceAt && pieceAt.id === selectedPieceId,
-              onClick: () => handleSquareClick(x, y),
+              onClick: () => handleSquareClick(x, y, Date.now() - lastTouchAtRef.current < TOUCH_CLICK_WINDOW_MS),
               onMouseEnter: () => {
                 if (isValidPass) setHoveredPassAt({ x, y });
               },
               onMouseLeave: () => setHoveredPassAt(null),
               onTouchStart: () => {
+                lastTouchAtRef.current = Date.now();
                 if (isValidPass) setHoveredPassAt({ x, y });
               },
               className: cn(
@@ -880,7 +904,7 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
                     },
                     "aria-label": t("shortcuts.buttonLabel"),
                     "aria-expanded": shortcutsOpen,
-                    className: "w-8 h-8 flex items-center justify-center rounded-full bg-bg-secondary/80 border border-border-subtle text-fg-muted hover:text-fg-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-green",
+                    className: "w-11 h-11 flex items-center justify-center rounded-full bg-bg-secondary/80 border border-border-subtle text-fg-muted hover:text-fg-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-green",
                     children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.HelpCircle, { size: 16, strokeWidth: 2, "aria-hidden": "true" })
                   }
                 ),
@@ -1902,7 +1926,7 @@ function SheetHeader({ titleId, onClose }) {
       "button",
       {
         onClick: onClose,
-        className: "w-8 h-8 flex items-center justify-center rounded-full bg-bg-surface hover:bg-bg-surface-elevated text-fg-muted hover:text-fg-primary transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-green",
+        className: "w-11 h-11 -mr-2 flex items-center justify-center rounded-full bg-bg-surface hover:bg-bg-surface-elevated text-fg-muted hover:text-fg-primary transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-green",
         "aria-label": t("history.close"),
         children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.X, { size: 14, "aria-hidden": "true" })
       }
@@ -1956,6 +1980,160 @@ function HistoryChip({ lastMove, onClick, className }) {
     }
   );
 }
+var GAME_HINT_IDS = ["lastActionPoint", "hasBall", "selectPiece", "start"];
+function GameHints({ userSide, seen, onSeen, className }) {
+  const t = useGameT();
+  const boardState = chunkBSE4DUXM_cjs.useGameStore((s) => s.boardState);
+  const selectedPieceId = chunkBSE4DUXM_cjs.useGameStore((s) => s.selectedPieceId);
+  const [done, setDone] = React.useState([]);
+  const myTurn = !!boardState && userSide !== null && boardState.turn === userSide;
+  const selected = myTurn ? boardState.pieces.find((p) => p.id === selectedPieceId) : void 0;
+  const applies = {
+    lastActionPoint: myTurn && boardState.actionPoints === 1,
+    hasBall: !!selected && boardState?.ball.holderId === selected.id,
+    selectPiece: !!selected,
+    start: myTurn && !selected
+  };
+  const current = GAME_HINT_IDS.find((id) => applies[id] && !seen.includes(id) && !done.includes(id)) ?? null;
+  const onSeenRef = React.useRef(onSeen);
+  onSeenRef.current = onSeen;
+  const markSeen = (id) => {
+    setDone((d) => d.includes(id) ? d : [...d, id]);
+    onSeenRef.current(id);
+  };
+  const shownRef = React.useRef(null);
+  React.useEffect(() => {
+    const prev = shownRef.current;
+    shownRef.current = current;
+    if (prev && prev !== current && !done.includes(prev)) markSeen(prev);
+  }, [current]);
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { role: "status", "aria-live": "polite", "aria-atomic": "true", className: cn("pointer-events-none flex justify-center", className), children: current && /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      "data-testid": "game-hint",
+      "data-hint": current,
+      className: "pointer-events-auto flex items-center gap-1 max-w-sm pl-4 pr-0.5 rounded-xl bg-bg-secondary/95 border border-border-subtle shadow-lg backdrop-blur-sm",
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx("p", { className: "py-2 font-inter text-sm leading-snug text-fg-primary", children: t(`hints.${current}`) }),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "button",
+          {
+            type: "button",
+            onClick: () => markSeen(current),
+            "aria-label": t("hints.dismiss"),
+            className: "shrink-0 w-11 h-11 flex items-center justify-center rounded-full text-fg-muted hover:text-fg-primary transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-green",
+            children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.X, { size: 16, "aria-hidden": "true" })
+          }
+        )
+      ]
+    }
+  ) });
+}
+var BOT_TURN_START_DELAY_MS = 400;
+var BOT_TURN_STEP_MS = 900;
+var BOT_TURN_SETTLE_MS = 500;
+var PROVIDER_DEFER_MS = 30;
+function useBotTurn(opts) {
+  const [botThinking, setBotThinking] = React.useState(false);
+  const [error, setError] = React.useState(null);
+  const [retryNonce, setRetryNonce] = React.useState(0);
+  const optsRef = React.useRef(opts);
+  optsRef.current = opts;
+  const pending = React.useRef(false);
+  const runId = React.useRef(0);
+  const timers = React.useRef(/* @__PURE__ */ new Set());
+  const skipRef = React.useRef(null);
+  const clearTimers = () => {
+    timers.current.forEach(clearTimeout);
+    timers.current.clear();
+  };
+  React.useEffect(() => () => {
+    runId.current++;
+    clearTimers();
+    pending.current = false;
+    skipRef.current = null;
+  }, []);
+  const { boardState, enabled = true, matchOver = false, goalPending = false } = opts;
+  React.useEffect(() => {
+    const o = optsRef.current;
+    const board = o.boardState;
+    if (!board || !enabled || board.turn !== o.botSide) return;
+    if (pending.current || matchOver || goalPending) return;
+    if (chessFootballEngine.checkGoal(board)) return;
+    const run = ++runId.current;
+    const alive = () => runId.current === run;
+    const wait = (ms) => new Promise((resolve) => {
+      const id = setTimeout(() => {
+        timers.current.delete(id);
+        resolve();
+      }, ms);
+      timers.current.add(id);
+    });
+    const settle = () => {
+      pending.current = false;
+      skipRef.current = null;
+      setBotThinking(false);
+      optsRef.current.onProcessingChange?.(false);
+    };
+    pending.current = true;
+    setBotThinking(true);
+    setError(null);
+    o.onProcessingChange?.(true);
+    let skipRequested = false;
+    skipRef.current = () => {
+      skipRequested = true;
+    };
+    const startDelay = o.startDelayMs ?? BOT_TURN_START_DELAY_MS;
+    const stepMs = o.stepMs ?? BOT_TURN_STEP_MS;
+    const settleMs = o.settleMs ?? BOT_TURN_SETTLE_MS;
+    (async () => {
+      try {
+        const [turn] = await Promise.all([
+          wait(Math.min(PROVIDER_DEFER_MS, startDelay)).then(() => o.getTurn(board, o.botSide)),
+          wait(startDelay)
+        ]);
+        if (!alive()) return;
+        if (!turn?.states?.length) throw new Error("Bot turn returned no states");
+        const { states } = turn;
+        const last = states[states.length - 1];
+        const shown = turn.closedByEndTurn ? states.length - 1 : states.length;
+        const finish = () => {
+          clearTimers();
+          optsRef.current.onApplyState(last);
+          settle();
+          const scorer = turn.goalScored ?? null;
+          if (scorer) optsRef.current.onGoal?.(scorer, last);
+        };
+        skipRef.current = () => {
+          if (alive()) finish();
+        };
+        if (skipRequested) {
+          finish();
+          return;
+        }
+        for (let i = 0; i < shown; i++) {
+          optsRef.current.onApplyState(states[i]);
+          await wait(i === shown - 1 ? settleMs : stepMs);
+          if (!alive()) return;
+        }
+        finish();
+      } catch (err) {
+        if (!alive()) return;
+        clearTimers();
+        settle();
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    })();
+  }, [boardState?.turn, enabled, matchOver, goalPending, retryNonce]);
+  const retry = React.useCallback(() => {
+    setError(null);
+    setRetryNonce((n) => n + 1);
+  }, []);
+  const skip = React.useCallback(() => {
+    skipRef.current?.();
+  }, []);
+  return { botThinking, error, retry, skip };
+}
 
 // src/tokens.ts
 var REQUIRED_TOKENS = [
@@ -1983,22 +2161,28 @@ var REQUIRED_TOKENS = [
   "--field-frame",
   "--move-highlight",
   "--pass-highlight",
-  "--last-move-highlight"
+  "--last-move-highlight",
+  "--ball-color"
 ];
 
 exports.ActionPoints = ActionPoints;
 exports.Avatar = Avatar;
 exports.AvatarFallback = AvatarFallback;
 exports.AvatarImage = AvatarImage;
+exports.BOT_TURN_SETTLE_MS = BOT_TURN_SETTLE_MS;
+exports.BOT_TURN_START_DELAY_MS = BOT_TURN_START_DELAY_MS;
+exports.BOT_TURN_STEP_MS = BOT_TURN_STEP_MS;
 exports.BallHolderChip = BallHolderChip;
 exports.Button = Button;
 exports.ConfirmDialog = ConfirmDialog;
 exports.EventToast = EventToast;
 exports.Football = Football;
+exports.GAME_HINT_IDS = GAME_HINT_IDS;
 exports.GAME_I18N_KEYS = GAME_I18N_KEYS;
 exports.GOAL_AREA_SHADE_CLASS = GOAL_AREA_SHADE_CLASS;
 exports.GameBoard = GameBoard;
 exports.GameControls = GameControls;
+exports.GameHints = GameHints;
 exports.GameI18nProvider = GameI18nProvider;
 exports.GamePiece = GamePiece;
 exports.GrassOverlay = GrassOverlay;
@@ -2019,6 +2203,7 @@ exports.TurnBanner = TurnBanner;
 exports.cn = cn;
 exports.isGoalAreaSquare = isGoalAreaSquare;
 exports.pitchSquareClass = pitchSquareClass;
+exports.useBotTurn = useBotTurn;
 exports.useDialogA11y = useDialogA11y;
 exports.useGameT = useGameT;
 //# sourceMappingURL=index.cjs.map