chore: add more tests

src/core/game-host.ts

@@ -3,8 +3,9 @@ import {
     CommandSchema,
     CommandRegistry,
     PromptEvent,
+    parseCommandSchema,
 } from '@/utils/command';
-import {createGameCommandRegistry, createGameContext, IGameContext} from './game';
+import {createGameCommandRegistry, createGameContext, IGameContext, PromptDef} from './game';
 
 export type GameHostStatus = 'created' | 'running' | 'disposed';
 
@@ -68,13 +69,23 @@ export class GameHost<TState extends Record<string, unknown>, TResult=unknown> {
         this._activePromptPlayer.value = null;
     }
 
-    onInput(input: string): string | null {
+    tryInput(input: string): string | null {
         if (this._isDisposed) {
             return 'GameHost is disposed';
         }
         return this._context._commands._tryCommit(input);
     }
     
+    tryAnswerPrompt<TArgs extends any[]>(def: PromptDef<TArgs>, ...args: TArgs){
+        if(typeof def.schema === 'string') def.schema = parseCommandSchema(def.schema);
+        return this._context._commands._tryCommit({
+            name: def.schema.name,
+            params: args,
+            options: {},
+            flags: {}
+        });
+    }
+
     /**
      * 为下一个 produceAsync 注册中断 Promise（通常用于 UI 动画）。
      * @see MutableSignal.addInterruption

src/core/game.ts

@@ -15,7 +15,7 @@ export interface IGameContext<TState extends Record<string, unknown> = {} > {
     produceAsync(fn: (draft: TState) => void): Promise<void>;
     run<T>(input: string): Promise<CommandResult<T>>;
     runParsed<T>(command: Command): Promise<CommandResult<T>>;
-    prompt: <TResult,TArgs extends any[]=any[]>(schema: CommandSchema | string, validator: PromptValidator<TResult,TArgs>, currentPlayer?: string | null) => Promise<TResult>;
+    prompt: <TResult,TArgs extends any[]=any[]>(def: PromptDef<TArgs>, validator: PromptValidator<TResult,TArgs>, currentPlayer?: string | null) => Promise<TResult>;
     addInterruption(promise: Promise<void>): void;
     
     // test only
@@ -47,8 +47,8 @@ export function createGameContext<TState extends Record<string, unknown> = {} >(
         runParsed<T>(command: Command) {
             return commands.runParsed<T>(command);
         },
-        prompt(schema, validator, currentPlayer) {
-            return commands.prompt(schema, validator, currentPlayer);
+        prompt(def, validator, currentPlayer) {
+            return commands.prompt(def.schema, validator, currentPlayer);
         },
         addInterruption(promise) {
             state.addInterruption(promise);
@@ -63,6 +63,13 @@ export function createGameContext<TState extends Record<string, unknown> = {} >(
     return context;
 }
 
+export type PromptDef<TArgs extends any[]=any[]> = {
+    schema: CommandSchema | string,
+}
+export function createPromptDef<TArgs extends any[]=any[]>(schema: CommandSchema | string): PromptDef<TArgs> {
+    return { schema };
+}
+
 export function createGameCommandRegistry<TState extends Record<string, unknown> = {} >() {
     return createCommandRegistry<IGameContext<TState>>();
 }

src/core/part-factory.ts

@@ -1,7 +1,7 @@
 import {Part} from "./part";
 import {Immutable} from "mutative";
 
-export function createPartsFromTable<T>(items: T[], getId: (item: T, index: number) => string, getCount?: ((item: T) => number) | number){
+export function createPartsFromTable<T>(items: readonly T[], getId: (item: T, index: number) => string, getCount?: ((item: T) => number) | number){
   const pool: Record<string, Part<T>> = {};
   for (const entry of items) {
     const count = getCount ? (typeof getCount === 'function' ? getCount(entry) : getCount) : 1;

src/index.ts

@@ -5,7 +5,7 @@
 
 // Core types
 export type { IGameContext } from './core/game';
-export { createGameCommandRegistry } from './core/game';
+export { createGameCommandRegistry, createPromptDef } from './core/game';
 
 export type { GameHost, GameHostStatus, GameModule } from './core/game-host';
 export { createGameHost } from './core/game-host';

src/samples/boop/commands.ts

@@ -5,7 +5,9 @@
     PlayerType,
     WinnerType,
     WIN_LENGTH,
-    MAX_PIECES_PER_PLAYER, BoopGame
+    MAX_PIECES_PER_PLAYER,
+    BoopGame,
+    prompts
 } from "./data";
 import {createGameCommandRegistry} from "@/core/game";
 import {moveToRegion} from "@/core/region";
@@ -186,8 +188,8 @@ async function handleCheckFullBoard(game: BoopGame, turnPlayer: PlayerType){
     }
     
     const partId = await game.prompt(
-        'choose <player> <row:number> <col:number>',
-        (player: PlayerType, row: number, col: number) => {
+        prompts.choose,
+        (player, row, col) => {
             if (player !== turnPlayer) {
                 throw `Invalid player: ${player}. Expected ${turnPlayer}.`;
             }
@@ -218,8 +220,8 @@ const checkFullBoard = registry.register({
 
 async function handleTurn(game: BoopGame, turnPlayer: PlayerType) {
     const {row, col, type} = await game.prompt(
-        'play <player> <row:number> <col:number> [type:string]',
-        (player: PlayerType, row: number, col: number, type?: PieceType) => {
+        prompts.play,
+        (player, row, col, type) => {
             const pieceType = type === 'cat' ? 'cat' : 'kitten';
 
             if (player !== turnPlayer) {

src/samples/boop/data.ts

@@ -2,7 +2,7 @@
 import {createRegion, moveToRegion, Region} from "@/core/region";
 import {createPartsFromTable} from "@/core/part-factory";
 import {Part} from "@/core/part";
-import {IGameContext} from "@/core/game";
+import {createPromptDef, IGameContext} from "@/core/game";
 
 export const BOARD_SIZE = 6;
 export const MAX_PIECES_PER_PLAYER = 8;
@@ -14,6 +14,12 @@ export type WinnerType = PlayerType | 'draw' | null;
 export type RegionType = 'white' | 'black' | 'board' | '';
 export type BoopPartMeta = { player: PlayerType; type: PieceType };
 export type BoopPart = Part<BoopPartMeta>;
+export const prompts = {
+    play: createPromptDef<[PlayerType, number, number, PieceType?]>(
+        'play <player> <row:number> <col:number> [type:string]'),
+    choose: createPromptDef<[PlayerType, number, number]>(
+        'choose <player> <row:number> <col:number>')
+}
 
 export function createInitialState() {
     const pieces = createPartsFromTable(

src/samples/tic-tac-toe.ts

@@ -2,6 +2,7 @@ import {
     createGameCommandRegistry, Part, createRegion,
     IGameContext
 } from '@/index';
+import {createPromptDef} from "@/core/game";
 
 const BOARD_SIZE = 3;
 const MAX_TURNS = BOARD_SIZE * BOARD_SIZE;
@@ -35,6 +36,10 @@ export function createInitialState() {
 export type TicTacToeState = ReturnType<typeof createInitialState>;
 export type TicTacToeGame = IGameContext<TicTacToeState>;
 export const registry = createGameCommandRegistry<TicTacToeState>();
+export const prompts = {
+    play: createPromptDef<[PlayerType, number, number]>(
+        'play <player> <row:number> <col:number>')
+}
 
 export async function start(game: TicTacToeGame) {
     while (true) {
@@ -59,8 +64,8 @@ const turn = registry.register({
     schema: 'turn <player> <turnNumber:number>',
     async run(game: TicTacToeGame, turnPlayer: PlayerType, turnNumber: number) {
         const {player, row, col} = await game.prompt(
-            'play <player> <row:number> <col:number>',
-            (player: string, row: number, col: number) => {
+            prompts.play,
+            (player, row, col) => {
                 if (player !== turnPlayer) {
                     throw `Invalid player: ${player}. Expected ${turnPlayer}.`;
                 } else if (!isValidMove(row, col)) {

src/utils/command/command-registry.ts

@@ -11,7 +11,6 @@ import type {
 import { parseCommand } from './command-parse';
 import { applyCommandSchema } from './command-validate';
 import { parseCommandSchema } from './schema-parse';
-import {AsyncQueue} from "@/utils/async-queue";
 
 type CanRunParsed = {
     runParsed<T=unknown>(command: Command): Promise<CommandResult<T>>,
@@ -89,7 +88,6 @@ type PromptEndListener = () => void;
 
 export type CommandRunnerContextExport<TContext> = CommandRunnerContext<TContext> & {
     registry: CommandRegistry<TContext>;
-    promptQueue: AsyncQueue<PromptEvent>;
     _activePrompt: PromptEvent | null;
     _tryCommit: (commandOrInput: Command | string) => string | null;
     _cancel: (reason?: string) => void;
@@ -196,26 +194,12 @@ export function createCommandRunnerContext<TContext>(
         _tryCommit: tryCommit,
         _cancel: cancel,
         _pendingInput: null,
-        promptQueue: null!
     };
 
     Object.defineProperty(runnerCtx, '_activePrompt', {
         get: () => activePrompt,
     });
     
-    let promptQueue: AsyncQueue<PromptEvent>;
-    Object.defineProperty(runnerCtx, 'promptQueue', {
-        get(){
-            if (!promptQueue) {
-                promptQueue = new AsyncQueue();
-                promptListeners.add(async (event) => {
-                    promptQueue.push(event);
-                });
-            }
-            return promptQueue;
-        }
-    });
-
     return runnerCtx;
 }
 

src/utils/command/command-runner.ts

@@ -1,6 +1,4 @@
 import type { Command, CommandSchema } from './types';
-import { parseCommand } from './command-parse';
-import { applyCommandSchema } from './command-validate';
 
 export type PromptEvent = {
     schema: CommandSchema;

tests/core/game-host.test.ts

@@ -55,11 +55,11 @@ describe('GameHost', () => {
         });
     });
 
-    describe('onInput', () => {
+    describe('tryInput', () => {
         it('should return "No active prompt" when no prompt is active', () => {
             const { host } = createTestHost();
 
-            const result = host.onInput('play X 1 1');
+            const result = host.tryInput('play X 1 1');
             expect(result).toBe('No active prompt');
         });
 
@@ -73,7 +73,7 @@ describe('GameHost', () => {
             expect(promptEvent.schema.name).toBe('play');
             expect(host.activePromptSchema.value?.name).toBe('play');
 
-            const error = host.onInput('play X 1 1');
+            const error = host.tryInput('play X 1 1');
             expect(error).toBeNull();
 
             // Cancel to end the game since start runs until game over
@@ -97,7 +97,7 @@ describe('GameHost', () => {
 
             const promptEvent = await promptPromise;
 
-            const error = host.onInput('invalid command');
+            const error = host.tryInput('invalid command');
             expect(error).not.toBeNull();
 
             promptEvent.cancel('test cleanup');
@@ -113,7 +113,7 @@ describe('GameHost', () => {
             const { host } = createTestHost();
             host.dispose();
 
-            const result = host.onInput('play X 1 1');
+            const result = host.tryInput('play X 1 1');
             expect(result).toBe('GameHost is disposed');
         });
     });
@@ -423,7 +423,7 @@ describe('GameHost', () => {
                 expect(promptEvent.schema.name).toBe('play');
 
                 // Submit the move
-                const error = host.onInput(moves[i]);
+                const error = host.tryInput(moves[i]);
                 expect(error).toBeNull();
                 
                 // Wait for the command to complete before submitting next move
@@ -515,4 +515,122 @@ describe('GameHost', () => {
             expect(host.activePromptPlayer.value).toBeNull();
         });
     });
+
+    describe('tryAnswerPrompt', () => {
+        it('should answer prompt with valid arguments', async () => {
+            const { host } = createTestHost();
+
+            const promptPromise = waitForPromptEvent(host);
+            const runPromise = host.start();
+
+            const promptEvent = await promptPromise;
+            expect(promptEvent.schema.name).toBe('play');
+
+            // Use tryAnswerPrompt with the prompt def
+            const { prompts } = await import('@/samples/tic-tac-toe');
+            const error = host.tryAnswerPrompt(prompts.play, 'X', 1, 1);
+            expect(error).toBeNull();
+
+            // Wait for next prompt and cancel
+            const nextPromptPromise = waitForPromptEvent(host);
+            const nextPrompt = await nextPromptPromise;
+            nextPrompt.cancel('test cleanup');
+
+            try {
+                await runPromise;
+            } catch (e) {
+                const error = e as Error;
+                expect(error.message).toBe('test cleanup');
+            }
+        });
+
+        it('should reject invalid arguments', async () => {
+            const { host } = createTestHost();
+
+            const promptPromise = waitForPromptEvent(host);
+            const runPromise = host.start();
+
+            const promptEvent = await promptPromise;
+
+            // Use tryAnswerPrompt with invalid position
+            const { prompts } = await import('@/samples/tic-tac-toe');
+            const error = host.tryAnswerPrompt(prompts.play, 'X', 5, 5);
+            expect(error).not.toBeNull();
+
+            promptEvent.cancel('test cleanup');
+            try {
+                await runPromise;
+            } catch (e) {
+                const error = e as Error;
+                expect(error.message).toBe('test cleanup');
+            }
+        });
+    });
+
+    describe('addInterruption and clearInterruptions', () => {
+        it('should add interruption promise to state', async () => {
+            const { host } = createTestHost();
+
+            let resolveInterruption: () => void;
+            const interruptionPromise = new Promise<void>(resolve => {
+                resolveInterruption = resolve;
+            });
+
+            // Add interruption
+            host.addInterruption(interruptionPromise);
+
+            // Start the game - produceAsync should wait for interruption
+            const promptPromise = waitForPromptEvent(host);
+            const runPromise = host.start();
+
+            const promptEvent = await promptPromise;
+            
+            // Resolve interruption
+            resolveInterruption!();
+            
+            // Cancel and cleanup
+            promptEvent.cancel('test cleanup');
+            try {
+                await runPromise;
+            } catch {
+                // Expected
+            }
+        });
+
+        it('should clear all pending interruptions', async () => {
+            const { host } = createTestHost();
+
+            let resolveInterruption1: () => void;
+            let resolveInterruption2: () => void;
+            const interruptionPromise1 = new Promise<void>(resolve => {
+                resolveInterruption1 = resolve;
+            });
+            const interruptionPromise2 = new Promise<void>(resolve => {
+                resolveInterruption2 = resolve;
+            });
+
+            // Add multiple interruptions
+            host.addInterruption(interruptionPromise1);
+            host.addInterruption(interruptionPromise2);
+
+            // Clear all interruptions
+            host.clearInterruptions();
+
+            // Start the game - should not wait for cleared interruptions
+            const promptPromise = waitForPromptEvent(host);
+            const runPromise = host.start();
+
+            const promptEvent = await promptPromise;
+            promptEvent.cancel('test cleanup');
+
+            try {
+                await runPromise;
+            } catch {
+                // Expected
+            }
+
+            // Original interruption promises should still be pending
+            // (they were cleared, not resolved)
+        });
+    });
 });

tests/core/game.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createGameContext, createGameCommandRegistry, IGameContext } from '@/core/game';
+import { createGameContext, createGameCommandRegistry, createPromptDef, IGameContext, PromptDef } from '@/core/game';
 import type { PromptEvent, Command } from '@/utils/command';
 
 type MyState = {
@@ -51,7 +51,7 @@ describe('createGameContext', () => {
         const ctx = createGameContext(registry);
 
         registry.register('test <value>', async function (_ctx, value) {
-            return this.prompt<string>('prompt <answer>', () => 'ok');
+            return this.prompt({schema: 'prompt <answer>'}, () => 'ok');
         });
 
         const promptPromise = new Promise<PromptEvent>(resolve => {
@@ -132,3 +132,59 @@ describe('createGameCommand', () => {
         }
     });
 });
+
+describe('createPromptDef', () => {
+    it('should create a PromptDef with string schema', () => {
+        const promptDef = createPromptDef<[string, number]>('play <player> <score:number>');
+        
+        expect(promptDef).toBeDefined();
+        expect(promptDef.schema).toBe('play <player> <score:number>');
+    });
+
+    it('should create a PromptDef with CommandSchema object', () => {
+        const schemaObj = {
+            name: 'test',
+            params: [],
+            options: {},
+            flags: {}
+        };
+        const promptDef = createPromptDef<[]>(schemaObj);
+        
+        expect(promptDef.schema).toEqual(schemaObj);
+    });
+
+    it('should be usable with game.prompt', async () => {
+        const registry = createGameCommandRegistry<{ score: number }>();
+        
+        registry.register('test-prompt', async function(ctx) {
+            const promptDef = createPromptDef<[number]>('input <value:number>');
+            const result = await ctx.prompt(
+                promptDef,
+                (value) => {
+                    if (value < 0) throw 'Value must be positive';
+                    return value;
+                }
+            );
+            return result;
+        });
+
+        const ctx = createGameContext(registry, { score: 0 });
+
+        const promptPromise = new Promise<PromptEvent>(resolve => {
+            ctx._commands.on('prompt', resolve);
+        });
+        const runPromise = ctx.run('test-prompt');
+
+        const promptEvent = await promptPromise;
+        expect(promptEvent.schema.name).toBe('input');
+
+        const error = promptEvent.tryCommit({ name: 'input', params: [42], options: {}, flags: {} });
+        expect(error).toBeNull();
+
+        const result = await runPromise;
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.result).toBe(42);
+        }
+    });
+});

tests/core/region.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createRegion, applyAlign, shuffle, moveToRegion, type Region, type RegionAxis } from '@/core/region';
+import { createRegion, createRegionAxis, applyAlign, shuffle, moveToRegion, type Region, type RegionAxis } from '@/core/region';
 import { createRNG } from '@/utils/rng';
 import { type Part } from '@/core/part';
 
@@ -304,3 +304,48 @@ describe('Region', () => {
         });
     });
 });
+
+describe('createRegionAxis', () => {
+    it('should create axis with name only', () => {
+        const axis = createRegionAxis('x');
+        
+        expect(axis.name).toBe('x');
+        expect(axis.min).toBeUndefined();
+        expect(axis.max).toBeUndefined();
+        expect(axis.align).toBeUndefined();
+    });
+
+    it('should create axis with min and max', () => {
+        const axis = createRegionAxis('y', 0, 10);
+        
+        expect(axis.name).toBe('y');
+        expect(axis.min).toBe(0);
+        expect(axis.max).toBe(10);
+    });
+
+    it('should create axis with align start', () => {
+        const axis = createRegionAxis('x', 0, 5, 'start');
+        
+        expect(axis.name).toBe('x');
+        expect(axis.min).toBe(0);
+        expect(axis.max).toBe(5);
+        expect(axis.align).toBe('start');
+    });
+
+    it('should create axis with align end', () => {
+        const axis = createRegionAxis('x', undefined, 10, 'end');
+        
+        expect(axis.name).toBe('x');
+        expect(axis.max).toBe(10);
+        expect(axis.align).toBe('end');
+    });
+
+    it('should create axis with align center', () => {
+        const axis = createRegionAxis('x', 0, 10, 'center');
+        
+        expect(axis.name).toBe('x');
+        expect(axis.min).toBe(0);
+        expect(axis.max).toBe(10);
+        expect(axis.align).toBe('center');
+    });
+});

tests/samples/boop-utils.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect } from 'vitest';
+import {
+    getLineCandidates,
+    isInBounds,
+    isCellOccupied,
+    getNeighborPositions,
+    findPartInRegion,
+    findPartAtPosition
+} from '@/samples/boop/utils';
+import { createInitialState, BOARD_SIZE, WIN_LENGTH } from '@/samples/boop/data';
+import { createGameContext } from '@/core/game';
+import { registry } from '@/samples/boop';
+
+describe('Boop Utils', () => {
+    describe('isInBounds', () => {
+        it('should return true for valid board positions', () => {
+            expect(isInBounds(0, 0)).toBe(true);
+            expect(isInBounds(3, 3)).toBe(true);
+            expect(isInBounds(5, 5)).toBe(true);
+        });
+
+        it('should return false for positions outside board', () => {
+            expect(isInBounds(-1, 0)).toBe(false);
+            expect(isInBounds(0, -1)).toBe(false);
+            expect(isInBounds(BOARD_SIZE, 0)).toBe(false);
+            expect(isInBounds(0, BOARD_SIZE)).toBe(false);
+            expect(isInBounds(6, 6)).toBe(false);
+        });
+    });
+
+    describe('getLineCandidates', () => {
+        it('should generate all possible winning lines', () => {
+            const lines = Array.from(getLineCandidates());
+            // For 8x8 board with WIN_LENGTH=3:
+            // 4 directions × various starting positions
+            expect(lines.length).toBeGreaterThan(0);
+        });
+
+        it('should generate lines with correct length', () => {
+            const lines = Array.from(getLineCandidates());
+            for (const line of lines) {
+                expect(line.length).toBe(WIN_LENGTH);
+            }
+        });
+
+        it('should generate horizontal lines', () => {
+            const lines = Array.from(getLineCandidates());
+            const horizontalLines = lines.filter(line => 
+                line.every(([_, y]) => y === line[0][1])
+            );
+            expect(horizontalLines.length).toBeGreaterThan(0);
+            // First horizontal line should start at [0,0], [1,0], [2,0] (direction [0,1] means varying x)
+            const firstHorizontal = horizontalLines[0];
+            expect(firstHorizontal).toEqual([[0, 0], [1, 0], [2, 0]]);
+        });
+
+        it('should generate vertical lines', () => {
+            const lines = Array.from(getLineCandidates());
+            const verticalLines = lines.filter(line => 
+                line.every(([x, _]) => x === line[0][0])
+            );
+            expect(verticalLines.length).toBeGreaterThan(0);
+        });
+
+        it('should generate diagonal lines', () => {
+            const lines = Array.from(getLineCandidates());
+            const diagonalLines = lines.filter(line => {
+                const [[x1, y1], [x2, y2]] = line;
+                return x1 !== x2 && y1 !== y2;
+            });
+            expect(diagonalLines.length).toBeGreaterThan(0);
+        });
+
+        it('should only include lines that fit within board bounds', () => {
+            const lines = Array.from(getLineCandidates());
+            for (const line of lines) {
+                for (const [x, y] of line) {
+                    expect(isInBounds(x, y)).toBe(true);
+                }
+            }
+        });
+    });
+
+    describe('isCellOccupied', () => {
+        it('should return false for empty cell in initial state', () => {
+            const state = createInitialState();
+            expect(isCellOccupied(state, 0, 0)).toBe(false);
+            expect(isCellOccupied(state, 3, 3)).toBe(false);
+        });
+
+        it('should return true for occupied cell', async () => {
+            const ctx = createGameContext(registry, createInitialState());
+            
+            // Place a piece via command (need to await)
+            await ctx._commands.run('place 2 2 white kitten');
+            
+            expect(isCellOccupied(ctx, 2, 2)).toBe(true);
+        });
+    });
+
+    describe('getNeighborPositions', () => {
+        it('should return 8 neighbor positions for center position', () => {
+            const neighbors = Array.from(getNeighborPositions(2, 2));
+            expect(neighbors.length).toBe(8);
+            
+            const expected = [
+                [1, 1], [1, 2], [1, 3],
+                [2, 1],          [2, 3],
+                [3, 1], [3, 2], [3, 3]
+            ];
+            expect(neighbors).toEqual(expect.arrayContaining(expected));
+        });
+
+        it('should include diagonal neighbors', () => {
+            const neighbors = Array.from(getNeighborPositions(0, 0));
+            expect(neighbors).toContainEqual([1, 1]);
+            expect(neighbors).toContainEqual([-1, -1]);
+        });
+
+        it('should not include the center position itself', () => {
+            const neighbors = Array.from(getNeighborPositions(5, 5));
+            expect(neighbors).not.toContainEqual([5, 5]);
+        });
+    });
+
+    describe('findPartInRegion', () => {
+        it('should find a piece in the specified region', () => {
+            const state = createInitialState();
+            
+            // Find a white kitten in white's supply
+            const piece = findPartInRegion(state, 'white', 'kitten');
+            expect(piece).not.toBeNull();
+            expect(piece?.player).toBe('white');
+            expect(piece?.type).toBe('kitten');
+            expect(piece?.regionId).toBe('white');
+        });
+
+        it('should return null if no matching piece in region', () => {
+            const state = createInitialState();
+            
+            // No kittens on board initially
+            const piece = findPartInRegion(state, 'board', 'kitten');
+            expect(piece).toBeNull();
+        });
+
+        it('should filter by player when specified', () => {
+            const state = createInitialState();
+            
+            const whitePiece = findPartInRegion(state, 'white', 'kitten', 'white');
+            expect(whitePiece).not.toBeNull();
+            expect(whitePiece?.player).toBe('white');
+
+            const blackPiece = findPartInRegion(state, 'white', 'kitten', 'black');
+            expect(blackPiece).toBeNull();
+        });
+
+        it('should search all regions when regionId is empty string', () => {
+            const state = createInitialState();
+            
+            // Find any cat piece
+            const piece = findPartInRegion(state, '', 'cat');
+            expect(piece).not.toBeNull();
+            expect(piece?.type).toBe('cat');
+        });
+    });
+
+    describe('findPartAtPosition', () => {
+        it('should return null for empty position', () => {
+            const state = createInitialState();
+            expect(findPartAtPosition(state, 0, 0)).toBeNull();
+        });
+
+        it('should find piece at specified position', async () => {
+            const ctx = createGameContext(registry, createInitialState());
+            
+            // Place a piece
+            await ctx._commands.run('place 3 3 white kitten');
+            
+            const piece = findPartAtPosition(ctx, 3, 3);
+            expect(piece).not.toBeNull();
+            expect(piece?.player).toBe('white');
+            expect(piece?.type).toBe('kitten');
+        });
+
+        it('should work with game context', () => {
+            const ctx = createGameContext(registry, createInitialState());
+            const piece = findPartAtPosition(ctx, 5, 5);
+            expect(piece).toBeNull();
+        });
+    });
+});

tests/samples/boop.test.ts

@@ -531,4 +531,141 @@ describe('Boop Game', () => {
             expect(whiteCatsInSupply.length).toBe(0);
         });
     });
+
+    describe('Check Full Board', () => {
+        it('should not trigger when player has fewer than 8 pieces on board', async () => {
+            const { ctx } = createTestContext();
+
+            // White places a single kitten
+            const promptPromise = waitForPrompt(ctx);
+            const runPromise = ctx.run('turn white');
+            const prompt = await promptPromise;
+            const error = prompt.tryCommit({ name: 'play', params: ['white', 2, 2, 'kitten'], options: {}, flags: {} });
+            expect(error).toBeNull();
+            const result = await runPromise;
+            expect(result.success).toBe(true);
+
+            // check-full-board should return without prompting
+            const fullBoardResult = await ctx._commands.run('check-full-board white');
+            expect(fullBoardResult.success).toBe(true);
+        });
+
+        it('should force graduation when all 8 pieces are on board', async () => {
+            const { ctx } = createTestContext();
+
+            // Manually place all 8 white pieces on the board
+            ctx.produce(state => {
+                for (let i = 1; i <= 8; i++) {
+                    const piece = state.pieces[`white-kitten-${i}`];
+                    if (piece) {
+                        const row = Math.floor((i - 1) / 4);
+                        const col = (i - 1) % 4;
+                        piece.regionId = 'board';
+                        piece.position = [row, col];
+                        state.regions.board.partMap[`${row},${col}`] = piece.id;
+                        state.regions.white.childIds = state.regions.white.childIds.filter(id => id !== piece.id);
+                    }
+                }
+            });
+
+            // Verify 8 pieces on board
+            const stateBefore = ctx.value;
+            expect(Object.keys(stateBefore.regions.board.partMap).length).toBe(8);
+
+            // Run check-full-board - should prompt for piece to graduate
+            const promptPromise = waitForPrompt(ctx);
+            const runPromise = ctx._commands.run('check-full-board white');
+            const prompt = await promptPromise;
+            expect(prompt.schema.name).toBe('choose');
+
+            // Select a piece to graduate
+            const error = prompt.tryCommit({ name: 'choose', params: ['white', 0, 0], options: {}, flags: {} });
+            expect(error).toBeNull();
+
+            const result = await runPromise;
+            expect(result.success).toBe(true);
+
+            const state = ctx.value;
+            // Position 0,0 should be empty (piece moved to box)
+            expect(state.regions.board.partMap['0,0']).toBeUndefined();
+        });
+
+        it('should not trigger when player has a winner', async () => {
+            const { ctx } = createTestContext();
+
+            // Set up a winning state for white
+            ctx.produce(state => {
+                state.winner = 'white';
+                for (let i = 1; i <= 8; i++) {
+                    const piece = state.pieces[`white-kitten-${i}`];
+                    if (piece) {
+                        const row = Math.floor((i - 1) / 4);
+                        const col = (i - 1) % 4;
+                        piece.regionId = 'board';
+                        piece.position = [row, col];
+                        state.regions.board.partMap[`${row},${col}`] = piece.id;
+                        state.regions.white.childIds = state.regions.white.childIds.filter(id => id !== piece.id);
+                    }
+                }
+            });
+
+            // check-full-board should return without prompting
+            const fullBoardResult = await ctx._commands.run('check-full-board white');
+            expect(fullBoardResult.success).toBe(true);
+        });
+    });
+
+    describe('Start Command', () => {
+        it('should run a complete game until there is a winner', async () => {
+            const { ctx } = createTestContext();
+
+            // Set up a quick win scenario
+            ctx.produce(state => {
+                // Place three white cats in a row
+                const c1 = state.pieces['white-cat-1'];
+                const c2 = state.pieces['white-cat-2'];
+                const c3 = state.pieces['white-cat-3'];
+
+                if (c1) {
+                    c1.type = 'cat';
+                    c1.regionId = 'board';
+                    c1.position = [0, 0];
+                    state.regions.board.partMap['0,0'] = c1.id;
+                    state.regions.white.childIds = state.regions.white.childIds.filter(id => id !== c1.id);
+                }
+                if (c2) {
+                    c2.type = 'cat';
+                    c2.regionId = 'board';
+                    c2.position = [0, 1];
+                    state.regions.board.partMap['0,1'] = c2.id;
+                    state.regions.white.childIds = state.regions.white.childIds.filter(id => id !== c2.id);
+                }
+                if (c3) {
+                    c3.type = 'cat';
+                    c3.regionId = 'board';
+                    c3.position = [0, 2];
+                    state.regions.board.partMap['0,2'] = c3.id;
+                    state.regions.white.childIds = state.regions.white.childIds.filter(id => id !== c3.id);
+                }
+            });
+
+            // start() should detect the win and return quickly
+            // Note: start() runs indefinitely until there's a winner
+            // Since we already set up a win, it should complete after one turn
+            const promptPromise = waitForPrompt(ctx);
+            const startPromise = ctx.run('turn white');
+            
+            const prompt = await promptPromise;
+            // Complete the turn
+            const error = prompt.tryCommit({ name: 'play', params: ['white', 3, 3, 'kitten'], options: {}, flags: {} });
+            expect(error).toBeNull();
+            
+            const result = await startPromise;
+            expect(result.success).toBe(true);
+
+            // Game should have detected white's win
+            const state = ctx.value;
+            // After turn, check-win would find white's existing win
+        });
+    });
 });

tests/samples/tic-tac-toe.test.ts

@@ -8,7 +8,8 @@ import {
     TicTacToeState,
     TicTacToeGame,
     WinnerType,
-    PlayerType
+    PlayerType,
+    hasWinningLine
 } from '@/samples/tic-tac-toe';
 import { createGameContext } from '@/core/game';
 import type { PromptEvent } from '@/utils/command';
@@ -143,6 +144,42 @@ describe('TicTacToe - helper functions', () => {
         });
     });
 
+    describe('hasWinningLine', () => {
+        it('should return true for horizontal winning line', () => {
+            const positions = [[0, 0], [0, 1], [0, 2]];
+            expect(hasWinningLine(positions)).toBe(true);
+        });
+
+        it('should return true for vertical winning line', () => {
+            const positions = [[0, 0], [1, 0], [2, 0]];
+            expect(hasWinningLine(positions)).toBe(true);
+        });
+
+        it('should return true for diagonal winning line (top-left to bottom-right)', () => {
+            const positions = [[0, 0], [1, 1], [2, 2]];
+            expect(hasWinningLine(positions)).toBe(true);
+        });
+
+        it('should return true for diagonal winning line (top-right to bottom-left)', () => {
+            const positions = [[0, 2], [1, 1], [2, 0]];
+            expect(hasWinningLine(positions)).toBe(true);
+        });
+
+        it('should return false for non-winning positions', () => {
+            const positions = [[0, 0], [0, 1], [1, 0]];
+            expect(hasWinningLine(positions)).toBe(false);
+        });
+
+        it('should return false for empty positions', () => {
+            expect(hasWinningLine([])).toBe(false);
+        });
+
+        it('should return true when positions contain winning line plus extra', () => {
+            const positions = [[0, 0], [0, 1], [0, 2], [2, 2]];
+            expect(hasWinningLine(positions)).toBe(true);
+        });
+    });
+
     describe('placePiece', () => {
         it('should add a piece to the board', () => {
             const { ctx } = createTestContext();

tests/utils/rng.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createRNG } from '@/utils/rng';
+import { createRNG, Mulberry32RNG } from '@/utils/rng';
 
 describe('createRNG', () => {
     it('should create RNG with default seed', () => {
@@ -90,3 +90,47 @@ describe('createRNG', () => {
         });
     });
 });
+
+describe('Mulberry32RNG', () => {
+    it('should instantiate with default seed', () => {
+        const rng = new Mulberry32RNG();
+        expect(rng.getSeed()).toBe(1);
+    });
+
+    it('should instantiate with custom seed', () => {
+        const rng = new Mulberry32RNG(99999);
+        expect(rng.getSeed()).toBe(99999);
+    });
+
+    it('should implement RNG interface', () => {
+        const rng = new Mulberry32RNG(42);
+        
+        // Should have all RNG methods
+        expect(typeof rng.next).toBe('function');
+        expect(typeof rng.nextInt).toBe('function');
+        expect(typeof rng.setSeed).toBe('function');
+        expect(typeof rng.getSeed).toBe('function');
+    });
+
+    it('should produce same results as createRNG with same seed', () => {
+        const factoryRng = createRNG(12345);
+        const directRng = new Mulberry32RNG(12345);
+
+        for (let i = 0; i < 10; i++) {
+            expect(factoryRng.next()).toBe(directRng.next());
+            expect(factoryRng.nextInt(100)).toBe(directRng.nextInt(100));
+        }
+    });
+
+    it('should allow seed changes after instantiation', () => {
+        const rng = new Mulberry32RNG(100);
+        expect(rng.getSeed()).toBe(100);
+
+        rng.setSeed(200);
+        expect(rng.getSeed()).toBe(200);
+
+        const value = rng.next();
+        expect(value).toBeGreaterThanOrEqual(0);
+        expect(value).toBeLessThan(1);
+    });
+});