tests: game and tic tac toe

src/core/context.ts

@@ -1,94 +0,0 @@
-import {createModel, Signal, signal} from '@preact/signals-core';
-import {createEntityCollection} from "../utils/entity";
-import {Part} from "./part";
-import {Region} from "./region";
-import {RuleDef, RuleRegistry, RuleContext, RuleEngineHost, dispatchCommand as dispatchRuleCommand} from "./rule";
-
-export type Context = {
-    type: string;
-}
-
-export const GameContext = createModel((root: Context) => {
-    const parts = createEntityCollection<Part>();
-    const regions = createEntityCollection<Region>();
-    const rules = signal<RuleRegistry>(new Map());
-    const ruleContexts = signal<RuleContext<unknown>[]>([]);
-    const contexts = signal<Signal<Context>[]>([]);
-    contexts.value = [signal(root)];
-
-    function pushContext(context: Context) {
-        const ctxSignal = signal(context);
-        contexts.value = [...contexts.value, ctxSignal];
-        return context;
-    }
-
-    function popContext() {
-        if (contexts.value.length > 1) {
-            contexts.value = contexts.value.slice(0, -1);
-        }
-    }
-
-    function latestContext<T extends Context>(type: T['type']): Signal<T> | undefined {
-        for(let i = contexts.value.length - 1; i >= 0; i--){
-            if(contexts.value[i].value.type === type){
-                return contexts.value[i] as Signal<T>;
-            }
-        }
-        return undefined;
-    }
-
-    function registerRule(name: string, rule: RuleDef<unknown, RuleEngineHost>) {
-        const newRules = new Map(rules.value);
-        newRules.set(name, rule);
-        rules.value = newRules;
-    }
-
-    function unregisterRule(name: string) {
-        const newRules = new Map(rules.value);
-        newRules.delete(name);
-        rules.value = newRules;
-    }
-
-    function addRuleContext(ctx: RuleContext<unknown>) {
-        ruleContexts.value = [...ruleContexts.value, ctx];
-    }
-
-    function removeRuleContext(ctx: RuleContext<unknown>) {
-        ruleContexts.value = ruleContexts.value.filter(c => c !== ctx);
-    }
-
-    function dispatchCommand(this: GameContextInstance, input: string) {
-        return dispatchRuleCommand({
-            rules: rules.value,
-            ruleContexts: ruleContexts.value,
-            addRuleContext,
-            removeRuleContext,
-            pushContext,
-            popContext,
-            latestContext,
-            parts,
-            regions,
-        } as any, input);
-    }
-
-    return {
-        parts,
-        regions,
-        rules,
-        ruleContexts,
-        contexts,
-        pushContext,
-        popContext,
-        latestContext,
-        registerRule,
-        unregisterRule,
-        dispatchCommand,
-    }
-})
-
-/** 创建游戏上下文实<E69687>?*/
-export function createGameContext(root: Context = { type: 'game' }) {
-    return new GameContext(root);
-}
-
-export type GameContextInstance = ReturnType<typeof createGameContext>;

src/core/game.ts

@@ -0,0 +1,49 @@
+import {createEntityCollection} from "../utils/entity";
+import {Part} from "./part";
+import {Region} from "./region";
+import {
+    Command,
+    CommandRegistry,
+    type CommandRunner, CommandRunnerContext,
+    CommandRunnerContextExport, CommandSchema,
+    createCommandRunnerContext, parseCommandSchema,
+    PromptEvent
+} from "../utils/command";
+import {AsyncQueue} from "../utils/async-queue";
+
+export interface IGameContext {
+    parts: ReturnType<typeof createEntityCollection<Part>>;
+    regions: ReturnType<typeof createEntityCollection<Region>>;
+    commands: CommandRunnerContextExport<IGameContext>;
+    prompts: AsyncQueue<PromptEvent>;
+}
+
+/**
+ * creates a game context.
+ * expects a command registry already registered with commands.
+ * @param commandRegistry
+ */
+export function createGameContext(commandRegistry: CommandRegistry<IGameContext>) {
+    const parts = createEntityCollection<Part>();
+    const regions = createEntityCollection<Region>();
+    const ctx: IGameContext = {
+        parts,
+        regions,
+        commands: null!,
+        prompts: new AsyncQueue(),
+    };
+    ctx.commands = createCommandRunnerContext(commandRegistry, ctx);
+    ctx.commands.on('prompt', (prompt: PromptEvent) => ctx.prompts.push(prompt));
+
+    return ctx;
+}
+
+export function createGameCommand<TResult>(
+    schema: CommandSchema | string,
+    run: (this: CommandRunnerContext<IGameContext>, command: Command) => Promise<TResult>
+): CommandRunner<IGameContext, TResult> {
+    return {
+        schema: typeof schema === 'string' ? parseCommandSchema(schema) : schema,
+        run,
+    };
+}

src/core/rule.ts

@@ -1,233 +0,0 @@
-import {Command, CommandSchema, parseCommand, parseCommandSchema, applyCommandSchema} from "../utils/command";
-
-export type RuleState = 'running' | 'yielded' | 'waiting' | 'invoking' | 'done';
-
-export type SchemaYield = { type: 'schema'; value: string | CommandSchema };
-export type InvokeYield = { type: 'invoke'; rule: string; command: Command };
-export type RuleYield = SchemaYield | InvokeYield;
-
-export type RuleContext<T = unknown> = {
-    type: string;
-    schema?: CommandSchema;
-    generator: Generator<RuleYield, T, Command | RuleContext<unknown>>;
-    parent?: RuleContext<unknown>;
-    children: RuleContext<unknown>[];
-    state: RuleState;
-    resolution?: T;
-}
-
-export type RuleDef<T = unknown, H extends RuleEngineHost = RuleEngineHost> = {
-    schema: CommandSchema;
-    create: (this: H, cmd: Command) => Generator<RuleYield, T, Command | RuleContext<unknown>>;
-};
-
-export type RuleRegistry = Map<string, RuleDef<unknown, RuleEngineHost>>;
-
-export type RuleEngineHost = {
-    rules: RuleRegistry;
-    ruleContexts: RuleContext<unknown>[];
-    addRuleContext: (ctx: RuleContext<unknown>) => void;
-    removeRuleContext: (ctx: RuleContext<unknown>) => void;
-};
-
-export function createRule<T, H extends RuleEngineHost = RuleEngineHost>(
-    schemaStr: string,
-    fn: (this: H, cmd: Command) => Generator<RuleYield, T, Command | RuleContext<unknown>>
-): RuleDef<T, H> {
-    return {
-        schema: parseCommandSchema(schemaStr, ''),
-        create: fn as RuleDef<T, H>['create'],
-    };
-}
-
-function parseYieldedSchema(value: string | CommandSchema): CommandSchema {
-    if (typeof value === 'string') {
-        return parseCommandSchema(value, '');
-    }
-    return value;
-}
-
-function addContextToHost(host: RuleEngineHost, ctx: RuleContext<unknown>) {
-    host.addRuleContext(ctx);
-}
-
-function discardChildren(host: RuleEngineHost, parent: RuleContext<unknown>) {
-    for (const child of parent.children) {
-        host.removeRuleContext(child);
-    }
-    parent.children = [];
-    parent.state = 'yielded';
-}
-
-function commandMatchesSchema(command: Command, schema: CommandSchema): boolean {
-    const requiredParams = schema.params.filter(p => p.required);
-    const variadicParam = schema.params.find(p => p.variadic);
-
-    if (command.params.length < requiredParams.length) {
-        return false;
-    }
-
-    if (!variadicParam && command.params.length > schema.params.length) {
-        return false;
-    }
-
-    const requiredOptions = Object.values(schema.options).filter(o => o.required);
-    for (const opt of requiredOptions) {
-        const hasOption = opt.name in command.options || (opt.short && opt.short in command.options);
-        if (!hasOption) {
-            return false;
-        }
-    }
-
-    return true;
-}
-
-function applySchemaToCommand(command: Command, schema: CommandSchema): Command {
-    return applyCommandSchema(command, schema).command;
-}
-
-function findYieldedContext(contexts: RuleContext<unknown>[]): RuleContext<unknown> | undefined {
-    for (let i = contexts.length - 1; i >= 0; i--) {
-        const ctx = contexts[i];
-        if (ctx.state === 'yielded') {
-            return ctx;
-        }
-    }
-    return undefined;
-}
-
-function createContext<T>(
-    command: Command,
-    ruleDef: RuleDef<T>,
-    host: RuleEngineHost,
-    parent?: RuleContext<unknown>
-): RuleContext<T> {
-    return {
-        type: ruleDef.schema.name,
-        schema: undefined,
-        generator: ruleDef.create.call(host, command),
-        parent,
-        children: [],
-        state: 'running',
-        resolution: undefined,
-    };
-}
-
-function handleGeneratorResult<T>(
-    host: RuleEngineHost,
-    ctx: RuleContext<T>,
-    result: IteratorResult<RuleYield, T>
-): RuleContext<unknown> | undefined {
-    if (result.done) {
-        ctx.resolution = result.value;
-        ctx.state = 'done';
-        return resumeParentAfterChildComplete(host, ctx as RuleContext<unknown>);
-    }
-
-    const yielded = result.value;
-    if (yielded.type === 'invoke') {
-        const childRuleDef = host.rules.get(yielded.rule);
-        if (childRuleDef) {
-            ctx.state = 'invoking';
-            return invokeChildRule(host, yielded.rule, yielded.command, ctx as RuleContext<unknown>);
-        } else {
-            ctx.schema = parseYieldedSchema({ name: '', params: [], options: {}, flags: {} });
-            ctx.state = 'yielded';
-        }
-    } else {
-        ctx.schema = parseYieldedSchema(yielded.value);
-        ctx.state = 'yielded';
-    }
-
-    return undefined;
-}
-
-function stepGenerator<T>(
-    host: RuleEngineHost,
-    ctx: RuleContext<T>
-): RuleContext<T> {
-    const result = ctx.generator.next();
-    const resumed = handleGeneratorResult(host, ctx, result);
-    if (resumed) return resumed as RuleContext<T>;
-    return ctx;
-}
-
-function invokeChildRule<T>(
-    host: RuleEngineHost,
-    ruleName: string,
-    command: Command,
-    parent: RuleContext<unknown>
-): RuleContext<T> {
-    const ruleDef = host.rules.get(ruleName)!;
-    const ctx = createContext(command, ruleDef, host, parent);
-
-    parent.children.push(ctx as RuleContext<unknown>);
-    addContextToHost(host, ctx as RuleContext<unknown>);
-
-    return stepGenerator(host, ctx) as RuleContext<T>;
-}
-
-function resumeParentAfterChildComplete(
-    host: RuleEngineHost,
-    childCtx: RuleContext<unknown>
-): RuleContext<unknown> | undefined {
-    const parent = childCtx.parent;
-    if (!parent || parent.state !== 'invoking') return undefined;
-
-    parent.children = parent.children.filter(c => c !== childCtx);
-
-    const result = parent.generator.next(childCtx);
-    const resumed = handleGeneratorResult(host, parent, result);
-    if (resumed) return resumed;
-    return parent;
-}
-
-function invokeRule<T>(
-    host: RuleEngineHost,
-    command: Command,
-    ruleDef: RuleDef<T>,
-    parent?: RuleContext<unknown>
-): RuleContext<T> {
-    const ctx = createContext(command, ruleDef, host, parent);
-
-    if (parent) {
-        discardChildren(host, parent);
-        parent.children.push(ctx as RuleContext<unknown>);
-        parent.state = 'waiting';
-    }
-
-    addContextToHost(host, ctx as RuleContext<unknown>);
-
-    return stepGenerator(host, ctx);
-}
-
-function feedYieldedContext(
-    host: RuleEngineHost,
-    ctx: RuleContext<unknown>,
-    command: Command
-): RuleContext<unknown> {
-    const typedCommand = applySchemaToCommand(command, ctx.schema!);
-    const result = ctx.generator.next(typedCommand);
-    const resumed = handleGeneratorResult(host, ctx, result);
-    return resumed ?? ctx;
-}
-
-export function dispatchCommand(host: RuleEngineHost, input: string): RuleContext<unknown> | undefined {
-    const command = parseCommand(input);
-
-    const matchedRule = host.rules.get(command.name);
-    if (matchedRule) {
-        const typedCommand = applySchemaToCommand(command, matchedRule.schema);
-        const parent = findYieldedContext(host.ruleContexts);
-        return invokeRule(host, typedCommand, matchedRule, parent);
-    }
-
-    for (let i = host.ruleContexts.length - 1; i >= 0; i--) {
-        const ctx = host.ruleContexts[i];
-        if (ctx.state === 'yielded' && ctx.schema && commandMatchesSchema(command, ctx.schema)) {
-            return feedYieldedContext(host, ctx, command);
-        }
-    }
-
-    return undefined;
-}

src/index.ts

@@ -4,8 +4,8 @@
  */
 
 // Core types
-export type { Context } from './core/context';
-export { GameContext, createGameContext } from './core/context';
+export type { IGameContext } from './core/game';
+export { createGameContext } from './core/game';
 
 export type { Part } from './core/part';
 export { flip, flipTo, roll } from './core/part';
@@ -13,15 +13,12 @@ export { flip, flipTo, roll } from './core/part';
 export type { Region, RegionAxis } from './core/region';
 export { applyAlign, shuffle } from './core/region';
 
-export type { RuleContext, RuleState, RuleDef, RuleRegistry } from './core/rule';
-export { createRule, dispatchCommand } from './core/rule';
-
 // Utils
 export type { Command, CommandSchema, CommandParamSchema, CommandOptionSchema, CommandFlagSchema } from './utils/command';
 export { parseCommand, parseCommandSchema, validateCommand, parseCommandWithSchema, applyCommandSchema } from './utils/command';
 
-export type { CommandRunner, CommandRunnerHandler, CommandRegistry, CommandRunnerContext } from './utils/command';
-export { createCommandRegistry, registerCommand, unregisterCommand, hasCommand, getCommand, runCommand, createCommandRunnerContext } from './utils/command';
+export type { CommandRunner, CommandRunnerHandler, CommandRunnerContext, PromptEvent, CommandRunnerEvents } from './utils/command';
+export { createCommandRegistry, registerCommand, unregisterCommand, hasCommand, getCommand, runCommand, runCommandParsed, createCommandRunnerContext, type CommandRegistry, type CommandRunnerContextExport } from './utils/command';
 
 export type { Entity, EntityAccessor } from './utils/entity';
 export { createEntityCollection } from './utils/entity';

src/samples/tic-tac-toe.ts

@@ -1,13 +1,9 @@
-import { GameContextInstance } from '../core/context';
-import type { RuleEngineHost, RuleContext } from '../core/rule';
-import { createRule, type InvokeYield, type SchemaYield } from '../core/rule';
-import type { Command } from '../utils/command';
+import { IGameContext } from '../core/game';
+import {CommandRegistry, CommandRunner, registerCommand} from '../utils/command';
 import type { Part } from '../core/part';
-import type { Region } from '../core/region';
-import type { Context } from '../core/context';
+import {createGameCommand} from "../core/game";
 
-export type TicTacToeState = Context & {
-    type: 'tic-tac-toe';
+export type TicTacToeState = {
     currentPlayer: 'X' | 'O';
     winner: 'X' | 'O' | 'draw' | null;
     moveCount: number;
@@ -17,37 +13,18 @@ type TurnResult = {
     winner: 'X' | 'O' | 'draw' | null;
 };
 
-type TicTacToeHost = RuleEngineHost & {
-    pushContext: (context: Context) => any;
-    latestContext: <T>(type: string) => { value: T } | undefined;
-    regions: { add: (...entities: any[]) => void; get: (id: string) => { value: { children: any[] } } };
-    parts: { add: (...entities: any[]) => void; get: (id: string) => any; collection: { value: Record<string, { value: Part }> } };
-};
-
-function getBoardRegion(host: TicTacToeHost) {
+export function getBoardRegion(host: IGameContext) {
     return host.regions.get('board');
 }
 
-function isCellOccupied(host: TicTacToeHost, row: number, col: number): boolean {
+export function isCellOccupied(host: IGameContext, row: number, col: number): boolean {
     const board = getBoardRegion(host);
     return board.value.children.some(
         (child: { value: { position: number[] } }) => child.value.position[0] === row && child.value.position[1] === col
     );
 }
 
-function checkWinner(host: TicTacToeHost): 'X' | 'O' | 'draw' | null {
-    const parts = Object.values(host.parts.collection.value).map((s: { value: Part }) => s.value);
-
-    const xPositions = parts.filter((_: Part, i: number) => i % 2 === 0).map((p: Part) => p.position);
-    const oPositions = parts.filter((_: Part, i: number) => i % 2 === 1).map((p: Part) => p.position);
-
-    if (hasWinningLine(xPositions)) return 'X';
-    if (hasWinningLine(oPositions)) return 'O';
-
-    return null;
-}
-
-function hasWinningLine(positions: number[][]): boolean {
+export function hasWinningLine(positions: number[][]): boolean {
     const lines = [
         [[0, 0], [0, 1], [0, 2]],
         [[1, 0], [1, 1], [1, 2]],
@@ -66,7 +43,19 @@ function hasWinningLine(positions: number[][]): boolean {
     );
 }
 
-function placePiece(host: TicTacToeHost, row: number, col: number, moveCount: number) {
+export function checkWinner(host: IGameContext): 'X' | 'O' | 'draw' | null {
+    const parts = Object.values(host.parts.collection.value).map((s: { value: Part }) => s.value);
+
+    const xPositions = parts.filter((_: Part, i: number) => i % 2 === 0).map((p: Part) => p.position);
+    const oPositions = parts.filter((_: Part, i: number) => i % 2 === 1).map((p: Part) => p.position);
+
+    if (hasWinningLine(xPositions)) return 'X';
+    if (hasWinningLine(oPositions)) return 'O';
+
+    return null;
+}
+
+export function placePiece(host: IGameContext, row: number, col: number, moveCount: number) {
     const board = getBoardRegion(host);
     const piece: Part = {
         id: `piece-${moveCount}`,
@@ -79,84 +68,58 @@ function placePiece(host: TicTacToeHost, row: number, col: number, moveCount: nu
     board.value.children.push(host.parts.get(piece.id));
 }
 
-const playSchema: SchemaYield = { type: 'schema', value: 'play <player> <row:number> <col:number>' };
-
-export function createSetupRule() {
-    return createRule('start', function*(this: TicTacToeHost) {
-        this.pushContext({
-            type: 'tic-tac-toe',
-            currentPlayer: 'X',
-            winner: null,
-            moveCount: 0,
-        } as TicTacToeState);
-
-        this.regions.add({
+const setup = createGameCommand(
+    'setup',
+    async function() {
+        this.context.regions.add({
             id: 'board',
             axes: [
                 { name: 'x', min: 0, max: 2 },
                 { name: 'y', min: 0, max: 2 },
             ],
             children: [],
-        } as Region);
+        });
 
         let currentPlayer: 'X' | 'O' = 'X';
         let turnResult: TurnResult | undefined;
+        let turn = 1;
 
         while (true) {
-            const yieldValue: InvokeYield = {
-                type: 'invoke',
-                rule: 'turn',
-                command: { name: 'turn', params: [currentPlayer], flags: {}, options: {} } as Command,
-            };
-            const ctx = yield yieldValue;
-            turnResult = (ctx as RuleContext<TurnResult>).resolution;
-            if (turnResult?.winner) break;
+            const turnOutput = await this.run<TurnResult>(`turn ${currentPlayer} ${turn++}`);
+            if (!turnOutput.success) throw new Error(turnOutput.error);
+            turnResult = turnOutput?.result.winner;
+            if (turnResult) break;
 
             currentPlayer = currentPlayer === 'X' ? 'O' : 'X';
-            const state = this.latestContext<TicTacToeState>('tic-tac-toe')!;
-            state.value.currentPlayer = currentPlayer;
         }
 
-        const state = this.latestContext<TicTacToeState>('tic-tac-toe')!;
-        state.value.winner = turnResult?.winner ?? null;
-        return { winner: state.value.winner };
-    });
+        return { winner: turnResult };
     }
+)
 
-export function createTurnRule() {
-    return createRule('turn <player>', function*(this: TicTacToeHost, cmd) {
+const turn = createGameCommand(
+    'turn <player> <turn:number>',
+    async function(cmd) {
+        const [turnPlayer, turnNumber] = cmd.params as [string, number];
         while (true) {
-            const received = yield playSchema;
-            if ('resolution' in received) continue;
-
-            const playCmd = received as Command;
-            if (playCmd.name !== 'play') continue;
-
-            const row = playCmd.params[1] as number;
-            const col = playCmd.params[2] as number;
+            const playCmd = await this.prompt('play <player> <row:number> <col:number>');
+            const [player, row, col] = playCmd.params as [string, number, number];
+            if(turnPlayer !== player) continue;
 
             if (isNaN(row) || isNaN(col) || row < 0 || row > 2 || col < 0 || col > 2) continue;
-            if (isCellOccupied(this, row, col)) continue;
+            if (isCellOccupied(this.context, row, col)) continue;
 
-            const state = this.latestContext<TicTacToeState>('tic-tac-toe')!;
-            if (state.value.winner) continue;
+            placePiece(this.context, row, col, turnNumber);
 
-            placePiece(this, row, col, state.value.moveCount);
-            state.value.moveCount++;
-
-            const winner = checkWinner(this);
+            const winner = checkWinner(this.context);
             if (winner) return { winner };
 
-            if (state.value.moveCount >= 9) return { winner: 'draw' as const };
+            if (turnNumber >= 9) return { winner: 'draw' as const };
         }
-    });
     }
+);
 
-export function registerTicTacToeRules(game: GameContextInstance) {
-    game.registerRule('start', createSetupRule());
-    game.registerRule('turn', createTurnRule());
-}
-
-export function startTicTacToe(game: GameContextInstance) {
-    game.dispatchCommand('start');
+export function registerTicTacToeCommands(registry: CommandRegistry<IGameContext>) {
+    registerCommand(registry, setup);
+    registerCommand(registry, turn);
 }

src/utils/async-queue.ts

@@ -0,0 +1,32 @@
+export class AsyncQueue<T> {
+  private items: T[] = [];
+  private resolvers: ((value: T) => void)[] = [];
+
+  push(item: T): void {
+    if (this.resolvers.length > 0) {
+      const resolve = this.resolvers.shift()!;
+      resolve(item);
+    } else {
+      this.items.push(item);
+    }
+  }
+
+  pushAll(items: Iterable<T>): void {
+    for (const item of items) {
+      this.push(item);
+    }
+  }
+
+  async pop(): Promise<T> {
+    if (this.items.length > 0) {
+      return this.items.shift()!;
+    }
+    return new Promise<T>((resolve) => {
+      this.resolvers.push(resolve);
+    });
+  }
+
+  get length(): number {
+    return this.items.length - this.resolvers.length;
+  }
+}

src/utils/command/command-registry.ts

@@ -1,7 +1,7 @@
-import type { Command } from './types.js';
-import type { CommandRunner, CommandRunnerContext, PromptEvent } from './command-runner.js';
+import type { Command, CommandSchema } from './types.js';
+import type {CommandResult, CommandRunner, CommandRunnerContext, PromptEvent} from './command-runner.js';
 import { parseCommand } from './command-parse.js';
-import { applyCommandSchema } from './command-apply.js';
+import { applyCommandSchema } from './command-validate.js';
 import { parseCommandSchema } from './schema-parse.js';
 
 export type CommandRegistry<TContext> = Map<string, CommandRunner<TContext, unknown>>;
@@ -42,6 +42,10 @@ type Listener = (e: PromptEvent) => void;
 
 export type CommandRunnerContextExport<TContext> = CommandRunnerContext<TContext> & {
     registry: CommandRegistry<TContext>;
+    _activePrompt: PromptEvent | null;
+    _resolvePrompt: (command: Command) => void;
+    _rejectPrompt: (error: Error) => void;
+    _pendingInput: string | null;
 };
 
 export function createCommandRunnerContext<TContext>(
@@ -58,9 +62,26 @@ export function createCommandRunnerContext<TContext>(
         listeners.delete(listener);
     };
 
+    let activePrompt: PromptEvent | null = null;
+
+    const resolvePrompt = (command: Command) => {
+        if (activePrompt) {
+            activePrompt.resolve(command);
+            activePrompt = null;
+        }
+    };
+
+    const rejectPrompt = (error: Error) => {
+        if (activePrompt) {
+            activePrompt.reject(error);
+            activePrompt = null;
+        }
+    };
+
     const prompt = (schema: Parameters<CommandRunnerContext<TContext>['prompt']>[0]): Promise<Command> => {
         const resolvedSchema = typeof schema === 'string' ? parseCommandSchema(schema) : schema;
         return new Promise((resolve, reject) => {
+            activePrompt = { schema: resolvedSchema, resolve, reject };
             const event: PromptEvent = { schema: resolvedSchema, resolve, reject };
             for (const listener of listeners) {
                 listener(event);
@@ -71,13 +92,21 @@ export function createCommandRunnerContext<TContext>(
     const runnerCtx: CommandRunnerContextExport<TContext> = {
         registry,
         context,
-        run: (input: string) => runCommandWithContext(registry, runnerCtx, input),
-        runParsed: (command: Command) => runCommandParsedWithContext(registry, runnerCtx, command),
+        run: <T=unknown>(input: string) => runCommandWithContext(runnerCtx, input) as Promise<CommandResult<T>>,
+        runParsed: (command: Command) => runCommandParsedWithContext(runnerCtx, command),
         prompt,
         on,
         off,
+        _activePrompt: null,
+        _resolvePrompt: resolvePrompt,
+        _rejectPrompt: rejectPrompt,
+        _pendingInput: null,
     };
 
+    Object.defineProperty(runnerCtx, '_activePrompt', {
+        get: () => activePrompt,
+    });
+
     return runnerCtx;
 }
 
@@ -85,7 +114,7 @@ async function executeWithRunnerContext<TContext>(
     runnerCtx: CommandRunnerContextExport<TContext>,
     runner: CommandRunner<TContext, unknown>,
     command: Command
-): Promise<{ success: true; result: unknown } | { success: false; error: string }> {
+): Promise<CommandResult> {
     try {
         const result = await runner.run.call(runnerCtx, command);
         return { success: true, result };
@@ -99,35 +128,33 @@ export async function runCommand<TContext>(
     registry: CommandRegistry<TContext>,
     context: TContext,
     input: string
-): Promise<{ success: true; result: unknown } | { success: false; error: string }> {
+): Promise<CommandResult> {
     const runnerCtx = createCommandRunnerContext(registry, context);
-    return await runCommandWithContext(registry, runnerCtx, input);
+    return await runCommandWithContext(runnerCtx, input);
 }
 
 async function runCommandWithContext<TContext>(
-    registry: CommandRegistry<TContext>,
     runnerCtx: CommandRunnerContextExport<TContext>,
     input: string
 ): Promise<{ success: true; result: unknown } | { success: false; error: string }> {
     const command = parseCommand(input);
-    return await runCommandParsedWithContext(registry, runnerCtx, command);
+    return await runCommandParsedWithContext(runnerCtx, command);
 }
 
 export async function runCommandParsed<TContext>(
     registry: CommandRegistry<TContext>,
     context: TContext,
     command: Command
-): Promise<{ success: true; result: unknown } | { success: false; error: string }> {
+): Promise<CommandResult> {
     const runnerCtx = createCommandRunnerContext(registry, context);
-    return await runCommandParsedWithContext(registry, runnerCtx, command);
+    return await runCommandParsedWithContext(runnerCtx, command);
 }
 
 async function runCommandParsedWithContext<TContext>(
-    registry: CommandRegistry<TContext>,
     runnerCtx: CommandRunnerContextExport<TContext>,
     command: Command
-): Promise<{ success: true; result: unknown } | { success: false; error: string }> {
-    const runner = registry.get(command.name);
+): Promise<CommandResult> {
+    const runner = runnerCtx.registry.get(command.name);
     if (!runner) {
         return { success: false, error: `Unknown command: ${command.name}` };
     }

src/utils/command/command-runner.ts

@@ -10,9 +10,17 @@ export type CommandRunnerEvents = {
     prompt: PromptEvent;
 };
 
+export type CommandResult<T=unknown> = {
+    success: true;
+    result: T;
+} | {
+    success: false;
+    error: string;
+}
+
 export type CommandRunnerContext<TContext> = {
     context: TContext;
-    run: (input: string) => Promise<{ success: true; result: unknown } | { success: false; error: string }>;
+    run: <T=unknown>(input: string) => Promise<CommandResult<T>>;
     runParsed: (command: Command) => Promise<{ success: true; result: unknown } | { success: false; error: string }>;
     prompt: (schema: CommandSchema | string) => Promise<Command>;
     on: <T extends keyof CommandRunnerEvents>(event: T, listener: (e: CommandRunnerEvents[T]) => void) => void;

tests/core/game.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest';
+import { createGameContext, createGameCommand } from '../../src/core/game';
+import { createCommandRegistry, parseCommandSchema, type CommandRegistry } from '../../src/utils/command';
+import type { IGameContext } from '../../src/core/game';
+
+describe('createGameContext', () => {
+    it('should create a game context with empty parts and regions', () => {
+        const registry = createCommandRegistry<IGameContext>();
+        const ctx = createGameContext(registry);
+
+        expect(ctx.parts.collection.value).toEqual({});
+        expect(ctx.regions.collection.value).toEqual({});
+    });
+
+    it('should wire commands to the context', () => {
+        const registry = createCommandRegistry<IGameContext>();
+        const ctx = createGameContext(registry);
+
+        expect(ctx.commands).not.toBeNull();
+        expect(ctx.commands.registry).toBe(registry);
+        expect(ctx.commands.context).toBe(ctx);
+    });
+
+    it('should forward prompt events to the prompts queue', async () => {
+        const registry = createCommandRegistry<IGameContext>();
+        const ctx = createGameContext(registry);
+
+        const schema = parseCommandSchema('test <value>');
+        registry.set('test', {
+            schema,
+            run: async function () {
+                return this.prompt('prompt <answer>');
+            },
+        });
+
+        const runPromise = ctx.commands.run('test hello');
+
+        await new Promise((r) => setTimeout(r, 0));
+
+        const promptEvent = await ctx.prompts.pop();
+        expect(promptEvent).not.toBeNull();
+        expect(promptEvent.schema.name).toBe('prompt');
+
+        promptEvent.resolve({ name: 'prompt', params: ['yes'], options: {}, flags: {} });
+
+        const result = await runPromise;
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect((result.result as any).params[0]).toBe('yes');
+        }
+    });
+});
+
+describe('createGameCommand', () => {
+    it('should create a command from a string schema', () => {
+        const cmd = createGameCommand('test <a>', async function () {
+            return 1;
+        });
+
+        expect(cmd.schema.name).toBe('test');
+        expect(cmd.schema.params[0].name).toBe('a');
+        expect(cmd.schema.params[0].required).toBe(true);
+    });
+
+    it('should create a command from a CommandSchema object', () => {
+        const schema = parseCommandSchema('foo <x> [y]');
+        const cmd = createGameCommand(schema, async function () {
+            return 2;
+        });
+
+        expect(cmd.schema.name).toBe('foo');
+        expect(cmd.schema.params[0].name).toBe('x');
+        expect(cmd.schema.params[0].required).toBe(true);
+        expect(cmd.schema.params[1].name).toBe('y');
+        expect(cmd.schema.params[1].required).toBe(false);
+    });
+
+    it('should run a command with access to game context', async () => {
+        const registry = createCommandRegistry<IGameContext>();
+        const ctx = createGameContext(registry);
+
+        const addRegion = createGameCommand('add-region <id>', async function (cmd) {
+            const id = cmd.params[0] as string;
+            this.context.regions.add({ id, axes: [], children: [] });
+            return id;
+        });
+
+        registry.set('add-region', addRegion);
+
+        const result = await ctx.commands.run('add-region board');
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.result).toBe('board');
+        }
+        expect(ctx.regions.get('board')).not.toBeNull();
+    });
+
+    it('should run a command that adds parts', async () => {
+        const registry = createCommandRegistry<IGameContext>();
+        const ctx = createGameContext(registry);
+
+        ctx.regions.add({ id: 'zone', axes: [], children: [] });
+
+        const addPart = createGameCommand('add-part <id>', async function (cmd) {
+            const id = cmd.params[0] as string;
+            const part = {
+                id,
+                sides: 1,
+                side: 0,
+                region: this.context.regions.get('zone'),
+                position: [0],
+            };
+            this.context.parts.add(part);
+            return id;
+        });
+
+        registry.set('add-part', addPart);
+
+        const result = await ctx.commands.run('add-part piece-1');
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.result).toBe('piece-1');
+        }
+        expect(ctx.parts.get('piece-1')).not.toBeNull();
+    });
+});

tests/core/rule.test.ts

@@ -1,396 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { createRule, type RuleContext, type RuleEngineHost } from '../../src/core/rule';
-import { createGameContext } from '../../src/core/context';
-import type { Command } from '../../src/utils/command';
-
-function isCommand(value: Command | RuleContext<unknown>): value is Command {
-    return 'name' in value;
-}
-
-function schema(value: string | { name: string; params: any[]; options: any[]; flags: any[] }) {
-    return { type: 'schema' as const, value };
-}
-
-describe('Rule System', () => {
-    function createTestGame() {
-        const game = createGameContext();
-        return game;
-    }
-
-    describe('createRule', () => {
-        it('should create a rule definition with parsed schema', () => {
-            const rule = createRule('<from> <to> [--force]', function*(cmd) {
-                return { from: cmd.params[0], to: cmd.params[1] };
-            });
-
-            expect(rule.schema.params).toHaveLength(2);
-            expect(rule.schema.params[0].name).toBe('from');
-            expect(rule.schema.params[0].required).toBe(true);
-            expect(rule.schema.params[1].name).toBe('to');
-            expect(rule.schema.params[1].required).toBe(true);
-            expect(Object.keys(rule.schema.flags)).toHaveLength(1);
-            expect(rule.schema.flags.force.name).toBe('force');
-        });
-
-        it('should create a generator when called', () => {
-            const game = createTestGame();
-            const rule = createRule('<target>', function*(cmd) {
-                return cmd.params[0];
-            });
-
-            const gen = rule.create.call(game as unknown as RuleEngineHost, { name: 'test', params: ['card1'], flags: {}, options: {} });
-            const result = gen.next();
-            expect(result.done).toBe(true);
-            expect(result.value).toBe('card1');
-        });
-    });
-
-    describe('dispatchCommand - rule invocation', () => {
-        it('should invoke a registered rule and yield schema', () => {
-            const game = createTestGame();
-
-            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
-                yield schema({ name: '', params: [], options: [], flags: [] });
-                return { moved: cmd.params[0] };
-            }));
-
-            const ctx = game.dispatchCommand('move card1 hand');
-
-            expect(ctx).toBeDefined();
-            expect(ctx!.state).toBe('yielded');
-            expect(ctx!.schema).toBeDefined();
-            expect(ctx!.resolution).toBeUndefined();
-        });
-
-        it('should complete a rule when final command matches yielded schema', () => {
-            const game = createTestGame();
-
-            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
-                const confirm = yield schema({ name: '', params: [], options: [], flags: [] });
-                const confirmCmd = isCommand(confirm) ? confirm : undefined;
-                return { moved: cmd.params[0], confirmed: confirmCmd?.name === 'confirm' };
-            }));
-
-            game.dispatchCommand('move card1 hand');
-            const ctx = game.dispatchCommand('confirm');
-
-            expect(ctx).toBeDefined();
-            expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toEqual({ moved: 'card1', confirmed: true });
-        });
-
-        it('should return undefined when command matches no rule and no yielded context', () => {
-            const game = createTestGame();
-
-            const result = game.dispatchCommand('unknown command');
-
-            expect(result).toBeUndefined();
-        });
-
-        it('should pass the initial command to the generator', () => {
-            const game = createTestGame();
-
-            game.registerRule('attack', createRule('<target> [--power: number]', function*(cmd) {
-                return { target: cmd.params[0], power: cmd.options.power || '1' };
-            }));
-
-            const ctx = game.dispatchCommand('attack goblin --power 5');
-
-            expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toEqual({ target: 'goblin', power: 5 });
-        });
-
-        it('should complete immediately if generator does not yield', () => {
-            const game = createTestGame();
-
-            game.registerRule('look', createRule('[--at]', function*() {
-                return 'looked';
-            }));
-
-            const ctx = game.dispatchCommand('look');
-
-            expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toBe('looked');
-        });
-    });
-
-    describe('dispatchCommand - rule priority', () => {
-        it('should prioritize new rule invocation over feeding yielded context', () => {
-            const game = createTestGame();
-
-            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
-                yield schema({ name: '', params: [], options: [], flags: [] });
-                return { moved: cmd.params[0] };
-            }));
-
-            game.registerRule('confirm', createRule('', function*() {
-                return 'new confirm rule';
-            }));
-
-            game.dispatchCommand('move card1 hand');
-
-            const ctx = game.dispatchCommand('confirm');
-
-            expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toBe('new confirm rule');
-            expect(ctx!.type).toBe('');
-        });
-    });
-
-    describe('dispatchCommand - fallback to yielded context', () => {
-        it('should feed a yielded context when command does not match any rule', () => {
-            const game = createTestGame();
-
-            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
-                const response = yield schema({ name: '', params: [], options: [], flags: [] });
-                const rcmd = isCommand(response) ? response : undefined;
-                return { moved: cmd.params[0], response: rcmd?.name };
-            }));
-
-            game.dispatchCommand('move card1 hand');
-            const ctx = game.dispatchCommand('yes');
-
-            expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toEqual({ moved: 'card1', response: 'yes' });
-        });
-
-        it('should skip non-matching commands for yielded context', () => {
-            const game = createTestGame();
-
-            game.registerRule('move', createRule('<from> <to>', function*(cmd) {
-                const response = yield schema('<item>');
-                const rcmd = isCommand(response) ? response : undefined;
-                return { response: rcmd?.params[0] };
-            }));
-
-            game.dispatchCommand('move card1 hand');
-
-            const ctx = game.dispatchCommand('goblin');
-
-            expect(ctx).toBeUndefined();
-        });
-
-        it('should validate command against yielded schema', () => {
-            const game = createTestGame();
-
-            game.registerRule('trade', createRule('<from> <to>', function*(cmd) {
-                const response = yield schema('<item> [amount: number]');
-                const rcmd = isCommand(response) ? response : undefined;
-                return { traded: rcmd?.params[0] };
-            }));
-
-            game.dispatchCommand('trade player1 player2');
-            const ctx = game.dispatchCommand('offer gold 5');
-
-            expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toEqual({ traded: 'gold' });
-        });
-    });
-
-    describe('dispatchCommand - deepest context first', () => {
-        it('should feed the deepest yielded context', () => {
-            const game = createTestGame();
-
-            game.registerRule('parent', createRule('<action>', function*() {
-                yield schema({ name: '', params: [], options: [], flags: [] });
-                return 'parent done';
-            }));
-
-            game.registerRule('child', createRule('<target>', function*() {
-                yield schema({ name: '', params: [], options: [], flags: [] });
-                return 'child done';
-            }));
-
-            game.dispatchCommand('parent start');
-            game.dispatchCommand('child target1');
-
-            const ctx = game.dispatchCommand('grandchild_cmd');
-
-            expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toBe('child done');
-        });
-    });
-
-    describe('nested rule invocations', () => {
-        it('should link child to parent', () => {
-            const game = createTestGame();
-
-            game.registerRule('parent', createRule('<action>', function*() {
-                yield schema('child_cmd');
-                return 'parent done';
-            }));
-
-            game.registerRule('child_cmd', createRule('<target>', function*() {
-                return 'child done';
-            }));
-
-            game.dispatchCommand('parent start');
-            const parentCtx = game.ruleContexts.value[0];
-
-            game.dispatchCommand('child_cmd target1');
-
-            expect(parentCtx.state).toBe('waiting');
-
-            const childCtx = game.ruleContexts.value[1];
-            expect(childCtx.parent).toBe(parentCtx);
-            expect(parentCtx.children).toContain(childCtx);
-        });
-
-        it('should discard previous children when a new child is invoked', () => {
-            const game = createTestGame();
-
-            game.registerRule('parent', createRule('<action>', function*() {
-                yield schema('child_a | child_b');
-                return 'parent done';
-            }));
-
-            game.registerRule('child_a', createRule('<target>', function*() {
-                return 'child_a done';
-            }));
-
-            game.registerRule('child_b', createRule('<target>', function*() {
-                return 'child_b done';
-            }));
-
-            game.dispatchCommand('parent start');
-            game.dispatchCommand('child_a target1');
-
-            expect(game.ruleContexts.value.length).toBe(2);
-
-            const oldParent = game.ruleContexts.value[0];
-            expect(oldParent.children).toHaveLength(1);
-
-            game.dispatchCommand('parent start');
-            game.dispatchCommand('child_b target2');
-
-            const newParent = game.ruleContexts.value[2];
-            expect(newParent.children).toHaveLength(1);
-            expect(newParent.children[0].resolution).toBe('child_b done');
-        });
-    });
-
-    describe('context tracking', () => {
-        it('should track rule contexts in ruleContexts signal', () => {
-            const game = createTestGame();
-
-            game.registerRule('test', createRule('<arg>', function*() {
-                yield schema({ name: '', params: [], options: [], flags: [] });
-                return 'done';
-            }));
-
-            expect(game.ruleContexts.value.length).toBe(0);
-
-            game.dispatchCommand('test arg1');
-
-            expect(game.ruleContexts.value.length).toBe(1);
-            expect(game.ruleContexts.value[0].state).toBe('yielded');
-        });
-    });
-
-    describe('error handling', () => {
-        it('should leave context in place when generator throws', () => {
-            const game = createTestGame();
-
-            game.registerRule('failing', createRule('<arg>', function*() {
-                throw new Error('rule error');
-            }));
-
-            expect(() => game.dispatchCommand('failing arg1')).toThrow('rule error');
-
-            expect(game.ruleContexts.value.length).toBe(1);
-        });
-
-        it('should leave children in place when child generator throws', () => {
-            const game = createTestGame();
-
-            game.registerRule('parent', createRule('<action>', function*() {
-                yield schema('child');
-                return 'parent done';
-            }));
-
-            game.registerRule('child', createRule('<target>', function*() {
-                throw new Error('child error');
-            }));
-
-            game.dispatchCommand('parent start');
-            expect(() => game.dispatchCommand('child target1')).toThrow('child error');
-
-            expect(game.ruleContexts.value.length).toBe(2);
-        });
-    });
-
-    describe('schema yielding', () => {
-        it('should accept a CommandSchema object as yield value', () => {
-            const game = createTestGame();
-
-            const customSchema = {
-                name: 'custom',
-                params: [{ name: 'x', required: true, variadic: false }],
-                options: [],
-                flags: [],
-            };
-
-            game.registerRule('test', createRule('<arg>', function*() {
-                const cmd = yield schema(customSchema);
-                const rcmd = isCommand(cmd) ? cmd : undefined;
-                return { received: rcmd?.params[0] };
-            }));
-
-            game.dispatchCommand('test val1');
-            const ctx = game.dispatchCommand('custom hello');
-
-            expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toEqual({ received: 'hello' });
-        });
-
-        it('should parse string schema on each yield', () => {
-            const game = createTestGame();
-
-            game.registerRule('multi', createRule('<start>', function*() {
-                const a = yield schema('<value>');
-                const b = yield schema('<value>');
-                const acmd = isCommand(a) ? a : undefined;
-                const bcmd = isCommand(b) ? b : undefined;
-                return { a: acmd?.params[0], b: bcmd?.params[0] };
-            }));
-
-            game.dispatchCommand('multi init');
-            game.dispatchCommand('cmd first');
-            const ctx = game.dispatchCommand('cmd second');
-
-            expect(ctx!.state).toBe('done');
-            expect(ctx!.resolution).toEqual({ a: 'first', b: 'second' });
-        });
-    });
-
-    describe('complex flow', () => {
-        it('should handle a multi-step game flow', () => {
-            const game = createTestGame();
-
-            game.registerRule('start', createRule('<player>', function*(cmd) {
-                const player = cmd.params[0];
-                const action = yield schema({ name: '', params: [], options: [], flags: [] });
-
-                if (isCommand(action)) {
-                    if (action.name === 'move') {
-                        yield schema('<target>');
-                    } else if (action.name === 'attack') {
-                        yield schema('<target> [--power: number]');
-                    }
-                }
-
-                return { player, action: isCommand(action) ? action.name : '' };
-            }));
-
-            const ctx1 = game.dispatchCommand('start alice');
-            expect(ctx1!.state).toBe('yielded');
-
-            const ctx2 = game.dispatchCommand('attack');
-            expect(ctx2!.state).toBe('yielded');
-
-            const ctx3 = game.dispatchCommand('attack goblin --power 3');
-            expect(ctx3!.state).toBe('done');
-            expect(ctx3!.resolution).toEqual({ player: 'alice', action: 'attack' });
-        });
-    });
-});

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

@@ -1,127 +1,346 @@
 import { describe, it, expect } from 'vitest';
-import { createGameContext } from '../../src/core/context';
-import { registerTicTacToeRules, startTicTacToe, type TicTacToeState } from '../../src/samples/tic-tac-toe';
+import { createGameContext } from '../../src/core/game';
+import { createCommandRegistry } from '../../src/utils/command';
+import { registerTicTacToeCommands, checkWinner, isCellOccupied, placePiece } from '../../src/samples/tic-tac-toe';
+import type { IGameContext } from '../../src/core/game';
+import type { Part } from '../../src/core/part';
 
-describe('Tic-Tac-Toe', () => {
-    function createGame() {
-        const game = createGameContext();
-        registerTicTacToeRules(game);
-        return game;
+function createTestContext() {
+    const registry = createCommandRegistry<IGameContext>();
+    registerTicTacToeCommands(registry);
+    const ctx = createGameContext(registry);
+    return { registry, ctx };
 }
 
-    function getBoardState(game: ReturnType<typeof createGame>) {
-        return game.latestContext<TicTacToeState>('tic-tac-toe')!.value;
+function setupBoard(ctx: IGameContext) {
+    ctx.regions.add({
+        id: 'board',
+        axes: [
+            { name: 'x', min: 0, max: 2 },
+            { name: 'y', min: 0, max: 2 },
+        ],
+        children: [],
+    });
 }
 
-    it('should initialize the board and start the game', () => {
-        const game = createGame();
-        startTicTacToe(game);
+function addPiece(ctx: IGameContext, id: string, row: number, col: number) {
+    const board = ctx.regions.get('board');
+    const part: Part = {
+        id,
+        sides: 1,
+        side: 0,
+        region: board,
+        position: [row, col],
+    };
+    ctx.parts.add(part);
+    board.value.children.push(ctx.parts.get(id));
+}
 
-        const state = getBoardState(game);
-        expect(state.currentPlayer).toBe('X');
-        expect(state.winner).toBeNull();
-        expect(state.moveCount).toBe(0);
+describe('TicTacToe - helper functions', () => {
+    describe('checkWinner', () => {
+        it('should return null for empty board', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
 
-        const board = game.regions.get('board');
-        expect(board.value.axes).toHaveLength(2);
-        expect(board.value.axes[0].name).toBe('x');
-        expect(board.value.axes[1].name).toBe('y');
+            expect(checkWinner(ctx)).toBeNull();
         });
 
-    it('should play moves and determine a winner', () => {
-        const game = createGame();
-        startTicTacToe(game);
+        it('should detect horizontal win for X', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
 
-        // X wins with column 0
-        game.dispatchCommand('play X 0 0');
-        game.dispatchCommand('play O 0 1');
-        game.dispatchCommand('play X 1 0');
-        game.dispatchCommand('play O 1 1');
-        game.dispatchCommand('play X 2 0');
+            addPiece(ctx, 'piece-1', 0, 0);
+            addPiece(ctx, 'piece-2', 1, 0);
+            addPiece(ctx, 'piece-3', 0, 1);
+            addPiece(ctx, 'piece-4', 1, 1);
+            addPiece(ctx, 'piece-5', 0, 2);
 
-        const state = getBoardState(game);
-        expect(state.winner).toBe('X');
-        expect(state.moveCount).toBe(5);
+            expect(checkWinner(ctx)).toBe('X');
         });
 
-    it('should reject out-of-bounds moves', () => {
-        const game = createGame();
-        startTicTacToe(game);
+        it('should detect horizontal win for O', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
 
-        const beforeCount = getBoardState(game).moveCount;
+            addPiece(ctx, 'piece-1', 2, 0);
+            addPiece(ctx, 'piece-2', 1, 0);
+            addPiece(ctx, 'piece-3', 2, 1);
+            addPiece(ctx, 'piece-4', 1, 1);
+            addPiece(ctx, 'piece-5', 0, 0);
+            addPiece(ctx, 'piece-6', 1, 2);
 
-        game.dispatchCommand('play X 5 5');
-        game.dispatchCommand('play X -1 0');
-        game.dispatchCommand('play X 3 3');
-
-        expect(getBoardState(game).moveCount).toBe(beforeCount);
+            expect(checkWinner(ctx)).toBe('O');
         });
 
-    it('should reject moves on occupied cells', () => {
-        const game = createGame();
-        startTicTacToe(game);
+        it('should detect vertical win', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
 
-        game.dispatchCommand('play X 1 1');
-        expect(getBoardState(game).moveCount).toBe(1);
+            addPiece(ctx, 'piece-1', 0, 0);
+            addPiece(ctx, 'piece-2', 0, 1);
+            addPiece(ctx, 'piece-3', 1, 0);
+            addPiece(ctx, 'piece-4', 1, 1);
+            addPiece(ctx, 'piece-5', 2, 0);
 
-        // Try to play on the same cell
-        game.dispatchCommand('play O 1 1');
-        expect(getBoardState(game).moveCount).toBe(1);
+            expect(checkWinner(ctx)).toBe('X');
         });
 
-    it('should ignore moves after game is over', () => {
-        const game = createGame();
-        startTicTacToe(game);
+        it('should detect diagonal win (top-left to bottom-right)', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
 
-        // X wins
-        game.dispatchCommand('play X 0 0');
-        game.dispatchCommand('play O 0 1');
-        game.dispatchCommand('play X 1 0');
-        game.dispatchCommand('play O 1 1');
-        game.dispatchCommand('play X 2 0');
+            addPiece(ctx, 'piece-1', 0, 0);
+            addPiece(ctx, 'piece-2', 0, 1);
+            addPiece(ctx, 'piece-3', 1, 1);
+            addPiece(ctx, 'piece-4', 0, 2);
+            addPiece(ctx, 'piece-5', 2, 2);
 
-        expect(getBoardState(game).winner).toBe('X');
-        const moveCountAfterWin = getBoardState(game).moveCount;
-
-        // Try to play more
-        game.dispatchCommand('play X 2 1');
-        game.dispatchCommand('play O 2 2');
-
-        expect(getBoardState(game).moveCount).toBe(moveCountAfterWin);
+            expect(checkWinner(ctx)).toBe('X');
         });
 
-    it('should detect a draw', () => {
-        const game = createGame();
-        startTicTacToe(game);
+        it('should detect diagonal win (top-right to bottom-left)', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
 
-        // Fill board with no winner (cat's game)
-        // X: (1,1), (0,2), (2,2), (1,0), (2,1)
-        // O: (0,0), (2,0), (0,1), (1,2)
-        game.dispatchCommand('play X 1 1');  // X
-        game.dispatchCommand('play O 0 0');  // O
-        game.dispatchCommand('play X 0 2');  // X
-        game.dispatchCommand('play O 2 0');  // O
-        game.dispatchCommand('play X 2 2');  // X
-        game.dispatchCommand('play O 0 1');  // O
-        game.dispatchCommand('play X 1 0');  // X
-        game.dispatchCommand('play O 1 2');  // O
-        game.dispatchCommand('play X 2 1');  // X (last move, draw)
+            addPiece(ctx, 'piece-1', 0, 0);
+            addPiece(ctx, 'piece-2', 0, 2);
+            addPiece(ctx, 'piece-3', 1, 0);
+            addPiece(ctx, 'piece-4', 1, 1);
+            addPiece(ctx, 'piece-5', 1, 2);
+            addPiece(ctx, 'piece-6', 2, 0);
 
-        const state = getBoardState(game);
-        expect(state.winner).toBe('draw');
-        expect(state.moveCount).toBe(9);
+            expect(checkWinner(ctx)).toBe('O');
         });
 
-    it('should place parts on the board region at correct positions', () => {
-        const game = createGame();
-        startTicTacToe(game);
+        it('should return null for no winner', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
 
-        game.dispatchCommand('play X 1 2');
+            addPiece(ctx, 'piece-1', 0, 0);
+            addPiece(ctx, 'piece-2', 0, 1);
+            addPiece(ctx, 'piece-3', 1, 2);
 
-        const board = game.regions.get('board');
-        expect(board.value.children).toHaveLength(1);
-
-        const piece = board.value.children[0].value;
-        expect(piece.position).toEqual([1, 2]);
+            expect(checkWinner(ctx)).toBeNull();
+        });
+    });
+
+    describe('isCellOccupied', () => {
+        it('should return false for empty cell', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
+
+            expect(isCellOccupied(ctx, 1, 1)).toBe(false);
+        });
+
+        it('should return true for occupied cell', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
+            addPiece(ctx, 'piece-1', 1, 1);
+
+            expect(isCellOccupied(ctx, 1, 1)).toBe(true);
+        });
+
+        it('should return false for different cell', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
+            addPiece(ctx, 'piece-1', 0, 0);
+
+            expect(isCellOccupied(ctx, 1, 1)).toBe(false);
+        });
+    });
+
+    describe('placePiece', () => {
+        it('should add a piece to the board', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
+            placePiece(ctx, 1, 1, 1);
+
+            expect(ctx.parts.get('piece-1')).not.toBeNull();
+            expect(ctx.parts.get('piece-1').value.position).toEqual([1, 1]);
+        });
+
+        it('should add piece to board region children', () => {
+            const { ctx } = createTestContext();
+            setupBoard(ctx);
+            placePiece(ctx, 0, 0, 1);
+
+            const board = ctx.regions.get('board');
+            expect(board.value.children.length).toBe(1);
+        });
+    });
+});
+
+describe('TicTacToe - game flow', () => {
+    it('should have setup and turn commands registered', () => {
+        const { registry } = createTestContext();
+
+        expect(registry.has('setup')).toBe(true);
+        expect(registry.has('turn')).toBe(true);
+    });
+
+    it('should setup board when setup command runs', async () => {
+        const { ctx } = createTestContext();
+
+        const runPromise = ctx.commands.run('setup');
+
+        const promptEvent = await ctx.prompts.pop();
+        expect(promptEvent).not.toBeNull();
+        expect(promptEvent.schema.name).toBe('play');
+
+        promptEvent.reject(new Error('test end'));
+
+        const result = await runPromise;
+        expect(result.success).toBe(false);
+    });
+
+    it('should accept valid move via turn command', async () => {
+        const { ctx } = createTestContext();
+        setupBoard(ctx);
+
+        const runPromise = ctx.commands.run('turn X 1');
+
+        const promptEvent = await ctx.prompts.pop();
+        expect(promptEvent).not.toBeNull();
+        expect(promptEvent.schema.name).toBe('play');
+
+        promptEvent.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });
+
+        // After valid non-winning move, turn command prompts again, reject to stop
+        const promptEvent2 = await ctx.prompts.pop();
+        promptEvent2.reject(new Error('done'));
+
+        const result = await runPromise;
+        expect(result.success).toBe(false);
+        expect(ctx.parts.get('piece-1')).not.toBeNull();
+        expect(ctx.parts.get('piece-1').value.position).toEqual([1, 1]);
+    });
+
+    it('should reject move for wrong player and re-prompt', async () => {
+        const { ctx } = createTestContext();
+        setupBoard(ctx);
+
+        const runPromise = ctx.commands.run('turn X 1');
+
+        const promptEvent1 = await ctx.prompts.pop();
+        promptEvent1.resolve({ name: 'play', params: ['O', 1, 1], options: {}, flags: {} });
+
+        const promptEvent2 = await ctx.prompts.pop();
+        expect(promptEvent2).not.toBeNull();
+
+        promptEvent2.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });
+
+        // After valid non-winning move, reject next prompt
+        const promptEvent3 = await ctx.prompts.pop();
+        promptEvent3.reject(new Error('done'));
+
+        const result = await runPromise;
+        expect(result.success).toBe(false);
+    });
+
+    it('should reject move to occupied cell and re-prompt', async () => {
+        const { ctx } = createTestContext();
+        setupBoard(ctx);
+
+        addPiece(ctx, 'piece-0', 1, 1);
+
+        const runPromise = ctx.commands.run('turn X 1');
+
+        const promptEvent1 = await ctx.prompts.pop();
+        promptEvent1.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });
+
+        const promptEvent2 = await ctx.prompts.pop();
+        expect(promptEvent2).not.toBeNull();
+
+        promptEvent2.resolve({ name: 'play', params: ['X', 0, 0], options: {}, flags: {} });
+
+        // After valid non-winning move, reject next prompt
+        const promptEvent3 = await ctx.prompts.pop();
+        promptEvent3.reject(new Error('done'));
+
+        const result = await runPromise;
+        expect(result.success).toBe(false);
+    });
+
+    it('should detect winner after winning move', async () => {
+        const { ctx } = createTestContext();
+        setupBoard(ctx);
+
+        // X plays (0,0)
+        let runPromise = ctx.commands.run('turn X 1');
+        let prompt = await ctx.prompts.pop();
+        prompt.resolve({ name: 'play', params: ['X', 0, 0], options: {}, flags: {} });
+        let promptNext = await ctx.prompts.pop();
+        promptNext.reject(new Error('next turn'));
+        let result = await runPromise;
+        expect(result.success).toBe(false);
+
+        // O plays (0,1)
+        runPromise = ctx.commands.run('turn O 2');
+        prompt = await ctx.prompts.pop();
+        prompt.resolve({ name: 'play', params: ['O', 0, 1], options: {}, flags: {} });
+        promptNext = await ctx.prompts.pop();
+        promptNext.reject(new Error('next turn'));
+        result = await runPromise;
+        expect(result.success).toBe(false);
+
+        // X plays (1,0)
+        runPromise = ctx.commands.run('turn X 3');
+        prompt = await ctx.prompts.pop();
+        prompt.resolve({ name: 'play', params: ['X', 1, 0], options: {}, flags: {} });
+        promptNext = await ctx.prompts.pop();
+        promptNext.reject(new Error('next turn'));
+        result = await runPromise;
+        expect(result.success).toBe(false);
+
+        // O plays (0,2)
+        runPromise = ctx.commands.run('turn O 4');
+        prompt = await ctx.prompts.pop();
+        prompt.resolve({ name: 'play', params: ['O', 0, 2], options: {}, flags: {} });
+        promptNext = await ctx.prompts.pop();
+        promptNext.reject(new Error('next turn'));
+        result = await runPromise;
+        expect(result.success).toBe(false);
+
+        // X plays (2,0) - wins with vertical line
+        runPromise = ctx.commands.run('turn X 5');
+        prompt = await ctx.prompts.pop();
+        prompt.resolve({ name: 'play', params: ['X', 2, 0], options: {}, flags: {} });
+        result = await runPromise;
+        expect(result.success).toBe(true);
+        if (result.success) expect((result.result as any).winner).toBe('X');
+    });
+
+    it('should detect draw after 9 moves', async () => {
+        const { ctx } = createTestContext();
+        setupBoard(ctx);
+
+        // Pre-place 8 pieces that don't form any winning line for either player
+        // Using positions that clearly don't form lines
+        // X pieces at even indices, O pieces at odd indices
+        const pieces = [
+            { id: 'p1', pos: [0, 0] }, // X
+            { id: 'p2', pos: [2, 2] }, // O
+            { id: 'p3', pos: [0, 2] }, // X
+            { id: 'p4', pos: [2, 0] }, // O
+            { id: 'p5', pos: [1, 0] }, // X
+            { id: 'p6', pos: [0, 1] }, // O
+            { id: 'p7', pos: [2, 1] }, // X
+            { id: 'p8', pos: [1, 2] }, // O
+        ];
+
+        for (const { id, pos } of pieces) {
+            addPiece(ctx, id, pos[0], pos[1]);
+        }
+
+        // Verify no winner before 9th move
+        expect(checkWinner(ctx)).toBeNull();
+
+        // Now X plays (1,1) for the 9th move -> draw
+        const runPromise = ctx.commands.run('turn X 9');
+        const prompt = await ctx.prompts.pop();
+        prompt.resolve({ name: 'play', params: ['X', 1, 1], options: {}, flags: {} });
+        const result = await runPromise;
+        expect(result.success).toBe(true);
+        if (result.success) expect((result.result as any).winner).toBe('draw');
     });
 });

tests/utils/async-queue.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { AsyncQueue } from '../../src/utils/async-queue';
+
+describe('AsyncQueue', () => {
+    describe('push', () => {
+        it('should add item to queue', () => {
+            const queue = new AsyncQueue<number>();
+            queue.push(1);
+            expect(queue.length).toBe(1);
+        });
+    });
+
+    describe('pop', () => {
+        it('should return item immediately if queue is not empty', async () => {
+            const queue = new AsyncQueue<number>();
+            queue.push(1);
+            queue.push(2);
+
+            const result = await queue.pop();
+            expect(result).toBe(1);
+            expect(queue.length).toBe(1);
+        });
+
+        it('should wait for item if queue is empty', async () => {
+            const queue = new AsyncQueue<number>();
+
+            const popPromise = queue.pop();
+
+            queue.push(42);
+
+            const result = await popPromise;
+            expect(result).toBe(42);
+            expect(queue.length).toBe(0);
+        });
+
+        it('should return items in FIFO order', async () => {
+            const queue = new AsyncQueue<number>();
+            queue.push(1);
+            queue.push(2);
+            queue.push(3);
+
+            expect(await queue.pop()).toBe(1);
+            expect(await queue.pop()).toBe(2);
+            expect(await queue.pop()).toBe(3);
+        });
+    });
+
+    describe('pushAll', () => {
+        it('should add all items to queue', async () => {
+            const queue = new AsyncQueue<number>();
+            queue.pushAll([1, 2, 3]);
+
+            expect(queue.length).toBe(3);
+            expect(await queue.pop()).toBe(1);
+            expect(await queue.pop()).toBe(2);
+            expect(await queue.pop()).toBe(3);
+        });
+
+        it('should accept any iterable', async () => {
+            const queue = new AsyncQueue<number>();
+            queue.pushAll(new Set([10, 20, 30]));
+
+            expect(await queue.pop()).toBe(10);
+            expect(await queue.pop()).toBe(20);
+            expect(await queue.pop()).toBe(30);
+        });
+
+        it('should resolve waiting pops', async () => {
+            const queue = new AsyncQueue<number>();
+
+            const pop1 = queue.pop();
+            const pop2 = queue.pop();
+
+            queue.pushAll([1, 2]);
+
+            expect(await pop1).toBe(1);
+            expect(await pop2).toBe(2);
+            expect(queue.length).toBe(0);
+        });
+    });
+
+    describe('length', () => {
+        it('should return 0 for empty queue', () => {
+            const queue = new AsyncQueue<number>();
+            expect(queue.length).toBe(0);
+        });
+
+        it('should reflect pending consumers as negative', () => {
+            const queue = new AsyncQueue<number>();
+            queue.pop(); // no await, so it's pending
+            expect(queue.length).toBe(-1);
+        });
+
+        it('should update after push and pop', async () => {
+            const queue = new AsyncQueue<number>();
+            queue.push(1);
+            queue.push(2);
+            expect(queue.length).toBe(2);
+
+            await queue.pop();
+            expect(queue.length).toBe(1);
+        });
+    });
+});