react-chess-puzzle-kit 1.0.0 → 1.0.1

package/dist/features/board/LineBoardWithControls.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import { type BoardThemeId } from 'react-chess-core';
 export type LineTrainSide = 'w' | 'b';
 /** A line to drill: a start position plus the moves to walk, from one side. */
 export interface LineSpec {
@@ -29,6 +30,7 @@ export interface LineControlsRenderProps {
 }
 export interface LineBoardWithControlsProps {
     theme: 'light' | 'dark';
+    boardTheme?: BoardThemeId;
     line: LineSpec;
     /** Called once when the whole line has been walked. */
     onComplete: (perMove: LineMoveResult[]) => void;
@@ -47,4 +49,4 @@ export interface LineBoardWithControlsProps {
  * tactical puzzles. Mount one instance per drill (key it by line) so its
  * internal state resets between lines.
  */
-export declare const LineBoardWithControls: ({ theme, line, onComplete, onMove, renderControls, boardWidth, opponentMoveDelayMs, }: LineBoardWithControlsProps) => React.JSX.Element;
+export declare const LineBoardWithControls: ({ theme, boardTheme, line, onComplete, onMove, renderControls, boardWidth, opponentMoveDelayMs, }: LineBoardWithControlsProps) => React.JSX.Element;

package/dist/features/board/PuzzleBoard.d.ts

@@ -6,5 +6,10 @@ export interface PuzzleBoardProps {
     boardWidth: number;
     /** After a wrong guess, play the correct move instead of allowing retries. */
     revealAnswerOnIncorrect?: boolean;
+    /** After a wrong guess, show an arrow to the correct square. */
+    showAnswerArrowOnIncorrect?: boolean;
+    /** With {@link showAnswerArrowOnIncorrect}, allow wrong retries after the arrow. When false, only the arrow move is accepted. */
+    allowRetryOnIncorrect?: boolean;
+    answerArrowColor?: string;
 }
-export declare const PuzzleBoard: ({ position, onFeedback, incInteractionNum, boardWidth, revealAnswerOnIncorrect, }: PuzzleBoardProps) => import("react").JSX.Element;
+export declare const PuzzleBoard: ({ position, onFeedback, incInteractionNum, boardWidth, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, answerArrowColor, }: PuzzleBoardProps) => import("react").JSX.Element;

package/dist/features/board/PuzzleBoardWithControls.d.ts

@@ -1,7 +1,8 @@
 import React from 'react';
 import { PuzzleResultStatus } from '../analysis';
-import { AnalysisContainerRenderProps, AnalysisControls, AnalysisEngineOptions, AnalysisLayoutConfig, AnalysisMainRenderProps, AnalysisSidebarRenderProps, EngineEvaluationRenderProps } from 'react-chess-core';
+import { AnalysisContainerRenderProps, AnalysisControls, AnalysisEngineOptions, AnalysisLayoutConfig, AnalysisMainRenderProps, AnalysisSidebarRenderProps, EngineEvaluationRenderProps, type BoardThemeId } from 'react-chess-core';
 import { type PuzzleControlState } from './defaults/DefaultPuzzleControls';
+import { type PuzzleMissFeedback } from './PuzzlePlaySurface';
 export type { PuzzleMoveRecord } from '../position/moveHistory';
 export type { AnalysisContainerRenderProps, AnalysisControls, AnalysisLayoutConfig, AnalysisMainRenderProps, AnalysisSidebarRenderProps, EngineEvaluationRenderProps, } from 'react-chess-core';
 export type { PuzzleAnalysisContext, PuzzleResultStatus } from '../analysis';
@@ -9,13 +10,52 @@ export { DEFAULT_ANALYSIS_LAYOUT } from 'react-chess-core';
 export { DEFAULT_PUZZLE_BOARD_WIDTH } from './puzzleBoardLayout';
 export { DefaultPuzzleControls, defaultRenderControls, } from './defaults/DefaultPuzzleControls';
 export type { PuzzleControlState, PuzzleControlsRenderProps, } from './defaults/DefaultPuzzleControls';
+export type BoardCaptionRenderProps = {
+    /** null while the puzzle position is loading */
+    sideToMove: 'white' | 'black' | null;
+    /** Side the user is solving for; null while loading */
+    playerColor: 'white' | 'black' | null;
+    /** True after a wrong guess, hint, or solution reveal on the current card. */
+    incorrectAttempt?: boolean;
+    /** True when the current card is finished. */
+    complete?: boolean;
+    /** False when the card was finished after a miss, hint, or solution reveal. */
+    cleanSolve?: boolean;
+    /** Engine refutation SAN while a miss sequence is active. */
+    refutationSan?: string | null;
+    /** Current miss-sequence phase (wrong → refutation → answer). */
+    missPhase?: PuzzleMissFeedback['phase'];
+    /** True while the board shows the correct-move answer arrow. */
+    answerArrowVisible?: boolean;
+    /** True when the card finished after a wrong move, hint, or solution reveal. */
+    completedAfterMiss?: boolean;
+};
+export type BoardFeedbackRenderProps = {
+    resultStatus: Extract<PuzzleResultStatus, 'complete' | 'incorrect'>;
+    /** False when the puzzle was finished after a miss, hint, or solution reveal. */
+    cleanSolve: boolean;
+    /** Engine refutation SAN while a miss sequence is active. */
+    refutationSan?: string | null;
+    /** Current miss-sequence phase (wrong → refutation → answer). */
+    missPhase?: PuzzleMissFeedback['phase'];
+    /** True while the board shows the correct-move answer arrow. */
+    answerArrowVisible?: boolean;
+    /** True when the card finished after a wrong move, hint, or solution reveal. */
+    completedAfterMiss?: boolean;
+};
+export type PuzzleFetchResult = {
+    fen: string;
+    moves: string[];
+    resume?: {
+        startIndex: number;
+        quizAtIndices: number[];
+    };
+};
 export interface PuzzleBoardWithControlsProps {
     theme: 'light' | 'dark';
+    boardTheme?: BoardThemeId;
     apiProxy: {
-        onFetch: () => Promise<{
-            fen: string;
-            moves: string[];
-        }>;
+        onFetch: () => Promise<PuzzleFetchResult>;
         /** Called when {@link onFetch} rejects (e.g. network / server down). */
         onFetchError?: (error: unknown) => void;
         onFeedback: (feedbackData: {
@@ -36,6 +76,10 @@ export interface PuzzleBoardWithControlsProps {
     renderAnalysisSidebar?: (props: AnalysisSidebarRenderProps) => React.ReactNode;
     renderAnalysisContainer?: (props: AnalysisContainerRenderProps) => React.ReactNode;
     renderEngineEvaluation?: (props: EngineEvaluationRenderProps) => React.ReactNode;
+    /** Optional label below the board (e.g. side to move). */
+    renderBoardCaption?: (props: BoardCaptionRenderProps) => React.ReactNode;
+    /** Optional result feedback shown at the bottom of the controls column. */
+    renderBoardFeedback?: (props: BoardFeedbackRenderProps) => React.ReactNode;
     /** Pixel width of the live puzzle board (separate from analysis). */
     puzzleBoardWidth?: number;
     /** Board + sidebar grid sizes when analysis is open. */
@@ -45,7 +89,20 @@ export interface PuzzleBoardWithControlsProps {
     engine?: AnalysisEngineOptions;
     /** After a clean solve (no wrong move, hint, or solution reveal), load the next card. */
     autoAdvanceOnComplete?: boolean;
+    /** With {@link autoAdvanceOnComplete}, also advance after finishing following a miss or hint. */
+    autoAdvanceOnCompleteAfterIncorrect?: boolean;
     /** After a wrong guess, play the correct move and wait for the user to advance. */
     revealAnswerOnIncorrect?: boolean;
+    /** After a wrong guess, show an arrow to the correct square. */
+    showAnswerArrowOnIncorrect?: boolean;
+    /** With {@link showAnswerArrowOnIncorrect}, allow wrong retries after the arrow. When false, only the arrow move is accepted. */
+    allowRetryOnIncorrect?: boolean;
+    /** With {@link showAnswerArrowOnIncorrect}, show wrong move + engine refutation before the answer arrow. */
+    showRefutationOnIncorrect?: boolean;
+    /** When {@link showRefutationOnIncorrect}, show the wrong move on the board before the refutation. */
+    autoShowWrongMoves?: boolean;
+    /** Stockfish options for refutation analysis (requires scriptUrl when not using AnalysisEngineProvider). */
+    refutationEngine?: AnalysisEngineOptions;
+    answerArrowColor?: string;
 }
-export declare const PuzzleBoardWithControls: ({ theme, apiProxy, renderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, puzzleBoardWidth, analysisLayout, renderAnalysisMain, engine, autoAdvanceOnComplete, revealAnswerOnIncorrect, }: PuzzleBoardWithControlsProps) => React.JSX.Element;
+export declare const PuzzleBoardWithControls: ({ theme, boardTheme, apiProxy, renderControls, renderAnalysisSidebar, renderAnalysisContainer, renderEngineEvaluation, renderBoardCaption, renderBoardFeedback, puzzleBoardWidth, analysisLayout, renderAnalysisMain, engine, autoAdvanceOnComplete, autoAdvanceOnCompleteAfterIncorrect, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, }: PuzzleBoardWithControlsProps) => React.JSX.Element;

package/dist/features/board/PuzzlePlaySurface.d.ts

@@ -1,4 +1,11 @@
+import { type AnalysisEngineOptions, type MissSequencePhase } from 'react-chess-core';
 import { PuzzlePosition } from '../position/Position';
+export type PuzzleMissFeedback = {
+    refutationSan: string | null;
+    phase: MissSequencePhase | null;
+    /** True while the board shows the correct-move answer arrow. */
+    answerArrowVisible: boolean;
+};
 export interface PuzzlePlaySurfaceProps {
     position: PuzzlePosition | null;
     onFeedback: (feedbackData: {
@@ -15,11 +22,28 @@ export interface PuzzlePlaySurfaceProps {
     }) => void;
     incInteractionNum: () => void;
     boardWidth: number;
+    /** After a correct move in resume review, auto-show intervening plies. */
+    onResumeCorrect?: (position: PuzzlePosition) => void;
     /** After a wrong guess, play the correct move instead of allowing retries. */
     revealAnswerOnIncorrect?: boolean;
+    /** After a wrong guess, show an arrow to the correct square. */
+    showAnswerArrowOnIncorrect?: boolean;
+    /** With {@link showAnswerArrowOnIncorrect}, allow wrong retries after the arrow. When false, only the arrow move is accepted. */
+    allowRetryOnIncorrect?: boolean;
+    /** With {@link showAnswerArrowOnIncorrect}, show wrong move + engine refutation before the answer arrow. */
+    showRefutationOnIncorrect?: boolean;
+    /** When {@link showRefutationOnIncorrect}, show the wrong move on the board before the refutation. */
+    autoShowWrongMoves?: boolean;
+    /** Stockfish options for refutation analysis. */
+    refutationEngine?: AnalysisEngineOptions;
+    answerArrowColor?: string;
+    /** While the next card is loading, keep the prior board visible but locked. */
+    positionLocked?: boolean;
+    /** Fired when refutation miss feedback changes (for host UI). */
+    onMissFeedbackChange?: (feedback: PuzzleMissFeedback | null) => void;
 }
 /**
- * Single mounted board for puzzle play. Shows an empty board while the next
- * position loads so the layout and controls do not flicker between cards.
+ * Single mounted board for puzzle play. Keeps the prior board (and orientation)
+ * visible while the next position loads so layout and perspective do not flicker.
  */
-export declare const PuzzlePlaySurface: ({ position, onFeedback, incInteractionNum, boardWidth, revealAnswerOnIncorrect, }: PuzzlePlaySurfaceProps) => import("react").JSX.Element;
+export declare const PuzzlePlaySurface: ({ position, onFeedback, incInteractionNum, boardWidth, onResumeCorrect, revealAnswerOnIncorrect, showAnswerArrowOnIncorrect, allowRetryOnIncorrect, showRefutationOnIncorrect, autoShowWrongMoves, refutationEngine, answerArrowColor, positionLocked, onMissFeedbackChange, }: PuzzlePlaySurfaceProps) => import("react").JSX.Element;

package/dist/features/board/puzzleBoardLayout.d.ts

@@ -1,8 +1,21 @@
 import { CSSProperties } from 'react';
 /** Default pixel width for the live puzzle board (analysis uses {@link DEFAULT_ANALYSIS_LAYOUT}). */
 export declare const DEFAULT_PUZZLE_BOARD_WIDTH = 480;
-/** Minimum height reserved below the board so controls do not shift when status changes. */
-export declare const PUZZLE_CONTROLS_MIN_HEIGHT = 96;
-export declare const puzzlePlayColumnStyle: (boardWidth: number) => CSSProperties;
+/** Width reserved for the vertical controls column beside the board. */
+export declare const PUZZLE_CONTROLS_COLUMN_WIDTH = 160;
+/** Gap between the board column and controls column. */
+export declare const PUZZLE_BOARD_CONTROLS_GAP = 16;
+/** Viewports at or below this width stack controls under the board (through tablet landscape). */
+export declare const PUZZLE_CONTROLS_STACK_BREAKPOINT_PX = 1365;
+/** Horizontal space taken by the controls column when it sits beside the board. */
+export declare const PUZZLE_CONTROLS_BESIDE_RESERVE_PX: number;
+/** Minimum height reserved below the board so the caption slot does not shift between loads. */
+export declare const PUZZLE_BOARD_CAPTION_MIN_HEIGHT = 24;
+export type PuzzleControlsPlacement = 'beside' | 'below';
+export declare const puzzlePlayRowStyle: (placement?: PuzzleControlsPlacement) => CSSProperties;
+export declare const puzzleBoardColumnStyle: (boardWidth: number, placement?: PuzzleControlsPlacement) => CSSProperties;
+export declare const puzzleBoardCaptionSlotStyle: () => CSSProperties;
+export declare const puzzleBoardSlotWrapperStyle: () => CSSProperties;
 export declare const puzzleBoardSlotStyle: () => CSSProperties;
-export declare const puzzleControlsSlotStyle: () => CSSProperties;
+export declare const puzzleControlsFeedbackStyle: (placement?: PuzzleControlsPlacement) => CSSProperties;
+export declare const puzzleControlsSlotStyle: (placement?: PuzzleControlsPlacement) => CSSProperties;

package/dist/features/board/useStackPuzzleControlsBelow.d.ts

@@ -0,0 +1,2 @@
+/** True when hint / next controls should sit below the board instead of beside it. */
+export declare const useStackPuzzleControlsBelow: () => boolean;

package/dist/features/position/Position.d.ts

@@ -15,11 +15,16 @@ export declare abstract class Position implements Traversable {
     /** True when a correct guess at the current index completes the puzzle. */
     isCompletedByCorrectGuess(): boolean;
     fen(): string;
+    getSideToMove(): 'white' | 'black';
     getCheckSquare(): string;
 }
 export declare function getCheckSquareFromChess(chess: Chess): string;
 /** Side to move for the final (user) ply in a puzzle line. */
 export declare function playerColorForSolution(initialFen: string, moves: string[]): 'white' | 'black';
+export type PuzzleResumeConfig = {
+    startIndex: number;
+    quizAtIndices: number[];
+};
 export declare class PuzzlePosition extends Position {
     protected isCorrect: boolean;
     protected guessedMove: string;
@@ -29,7 +34,8 @@ export declare class PuzzlePosition extends Position {
     protected readonly initialFen: string;
     protected moveHistory: PuzzleMoveRecord[];
     private usedAlternativeCheckmate;
-    constructor(initialFEN: string, moves: string[]);
+    private readonly resumeConfig?;
+    constructor(initialFEN: string, moves: string[], resumeConfig?: PuzzleResumeConfig);
     next(): boolean;
     getInitialFen(): string;
     getSolutionMoves(): string[];
@@ -46,7 +52,11 @@ export declare class PuzzlePosition extends Position {
     private tryMakeUciMove;
     private isCheckmatingMove;
     private applyCheckmateGuess;
-    tryGuess: (sourceSquare: string, targetSquare: string, piece: string) => {
+    /** True when dragging from/to matches the expected move at the current index. */
+    isExpectedGuess(sourceSquare: string, targetSquare: string): boolean;
+    tryGuess: (sourceSquare: string, targetSquare: string, piece: string, options?: {
+        recordIfIncorrect?: boolean;
+    }) => {
         accepted: boolean;
         finished: boolean;
     };
@@ -60,7 +70,13 @@ export declare class PuzzlePosition extends Position {
     getHintSquare(): string;
     private hint;
     getIncorrectMoveSquare(): string;
+    /** UCI of the move the player should play at the current index. */
+    getExpectedMoveUci(): string;
     getPlayerColor(): string;
+    hasResumeConfig(): boolean;
+    getResumeConfig(): PuzzleResumeConfig | undefined;
+    /** True when the user must find the move at the current index. */
+    isQuizIndex(): boolean;
 }
 export declare class GamePosition extends Position {
     constructor(PGN: string);

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export * from './features/board/LineBoardWithControls';
 export { DefaultPuzzleControls, defaultRenderControls, } from './features/board/defaults/DefaultPuzzleControls';
 export { DefaultLineControls, defaultRenderLineControls, } from './features/board/defaults/DefaultLineControls';
 export type { PuzzleControlState, PuzzleControlsRenderProps, } from './features/board/defaults/DefaultPuzzleControls';
-export { DEFAULT_PUZZLE_BOARD_WIDTH } from './features/board/puzzleBoardLayout';
+export { DEFAULT_PUZZLE_BOARD_WIDTH, PUZZLE_CONTROLS_BESIDE_RESERVE_PX, PUZZLE_CONTROLS_STACK_BREAKPOINT_PX, } from './features/board/puzzleBoardLayout';
 export * from './features/position/moveHistory';
 export * from './features/position/Position';
 export * from './features/position/Traversable';