Build the playable game

import { z } from 'zod';

// The wire contract shared by the server and the board view. It imports only `zod`, so a view
// bundle that includes it carries no server code. Application-owned: nothing here is a SAGA export.

export const NEW_GAME_TOOL = 'new_game';
export const SHOW_GAME_TOOL = 'show_game';
export const GET_GAME_TOOL = 'get_game';
export const PLAY_MOVE_TOOL = 'play_move';

/** The person plays X and moves first; the assistant plays O. */
export const PlayerSchema = z.enum(['X', 'O']);
export type Player = z.infer<typeof PlayerSchema>;

/** A square, numbered 0 to 8 across the rows from the top left. */
export const SquareSchema = z.number().int().min(0).max(8);

/**
 * An unguessable random identifier. It names a game and authorizes nothing else: the game is an
 * example, not an adversarial service, and anyone who holds the identifier may play either side.
 */
export const GameIdSchema = z.string().regex(/^[A-Za-z0-9_-]{16,64}$/);

export const GameSchema = z.strictObject({
  gameId: GameIdSchema,
  /** The nine squares, `null` while empty. */
  board: z.array(PlayerSchema.nullable()).length(9),
  /** Who plays next. */
  turn: PlayerSchema,
  /** How many moves have been made. A move names the number it expects. */
  moveNumber: z.number().int().min(0).max(9),
  status: z.enum(['playing', 'won', 'draw']),
  winner: PlayerSchema.nullable(),
  /** The three winning squares, or `null`. */
  line: z.tuple([SquareSchema, SquareSchema, SquareSchema]).nullable(),
  /** Every move so far, in order. */
  history: z
    .array(z.strictObject({ player: PlayerSchema, square: SquareSchema }))
    .max(9),
});
export type Game = z.infer<typeof GameSchema>;

/** Why `play_move` changed nothing. */
export const RefusalSchema = z.enum([
  'game_over',
  'stale_move',
  'not_your_turn',
  'occupied',
]);
export type Refusal = z.infer<typeof RefusalSchema>;

/** `new_game`, `show_game` and `get_game`: the whole game, always. */
export const GameOutputSchema = z.strictObject({ game: GameSchema });

/**
 * `play_move`: the game after the move, or, when the move was refused, the current game unchanged
 * and why. A refusal is a normal result that carries the game, not a failure.
 */
export const MoveOutputSchema = z.strictObject({
  game: GameSchema,
  outcome: z.enum(['played', 'refused']),
  reason: RefusalSchema.optional(),
});
export type MoveOutput = z.infer<typeof MoveOutputSchema>;

export const GameIdInputSchema = z.strictObject({ gameId: GameIdSchema });
export const MoveInputSchema = z.strictObject({
  gameId: GameIdSchema,
  square: SquareSchema,
  player: PlayerSchema,
  expectedMoveNumber: z.number().int().min(0).max(9),
});
export type MoveInput = z.infer<typeof MoveInputSchema>;

/** Fixed sentences. A failure never repeats a backend message or an identifier. */
export const TEXT = {
  noGame:
    'That game is not available any more, so there is no board to show. Start a new one with new_game.',
  unavailable: 'The game is unavailable right now.',
  invalidOutput: 'The game could not be shown.',
} as const;

/** The tool annotations: what each operation does to the stored games. */
export const READS = {
  readOnlyHint: true,
  destructiveHint: false,
  idempotentHint: true,
  openWorldHint: false,
} as const;
export const WRITES = {
  readOnlyHint: false,
  destructiveHint: false,
  idempotentHint: false,
  openWorldHint: false,
} as const;

/**
 * What the built page must contain for the server to serve it: the element the view renders into.
 * The server refuses to start with a page that lacks it, so a missing or wrong build fails early.
 */
export const VIEW_MARKER = '<div id="root"';

import type { Game, Player, Refusal } from '../src/contract.js';

// The rules of tic-tac-toe, as pure functions: no clock, no randomness, no storage and no
// mutation of what they are given. X moves first, the players alternate, the eight lines win, a
// full board with no line is a draw, and nothing is accepted after the game ends.

/** Everything about a game except its identifier. */
export type GameState = Omit<Game, 'gameId'>;

/** The eight winning lines: three rows, three columns and the two diagonals. */
export const LINES: readonly (readonly [number, number, number])[] = [
  [0, 1, 2],
  [3, 4, 5],
  [6, 7, 8],
  [0, 3, 6],
  [1, 4, 7],
  [2, 5, 8],
  [0, 4, 8],
  [2, 4, 6],
];

export const playerOnMove = (moveNumber: number): Player =>
  moveNumber % 2 === 0 ? 'X' : 'O';

export function emptyGame(): GameState {
  return {
    board: Array.from({ length: 9 }, () => null),
    turn: 'X',
    moveNumber: 0,
    status: 'playing',
    winner: null,
    line: null,
    history: [],
  };
}

/** What a player asks for. `expectedMoveNumber` is the number of moves the player saw on the board. */
export interface Move {
  readonly player: Player;
  readonly square: number;
  readonly expectedMoveNumber: number;
}

export type MoveResult =
  | { readonly ok: true; readonly state: GameState }
  | { readonly ok: false; readonly reason: Refusal };

/**
 * Applies one move to a game that is left untouched, or says why not. The reasons are checked in
 * this order, so one move has exactly one answer: the game is over, the move was made for an
 * older board, it is not that player's turn, the square is taken.
 */
export function applyMove(state: GameState, move: Move): MoveResult {
  if (state.status !== 'playing') return { ok: false, reason: 'game_over' };
  if (move.expectedMoveNumber !== state.moveNumber)
    return { ok: false, reason: 'stale_move' };
  if (move.player !== state.turn) return { ok: false, reason: 'not_your_turn' };
  if (
    !Number.isInteger(move.square) ||
    move.square < 0 ||
    move.square > 8 ||
    state.board[move.square] !== null
  )
    return { ok: false, reason: 'occupied' };

  const board = state.board.map((cell, square) =>
    square === move.square ? move.player : cell,
  );
  const moveNumber = state.moveNumber + 1;
  const line = LINES.find(
    ([a, b, c]) =>
      board[a] === move.player &&
      board[b] === move.player &&
      board[c] === move.player,
  );
  const history = [
    ...state.history,
    { player: move.player, square: move.square },
  ];
  return {
    ok: true,
    state: {
      board,
      turn: playerOnMove(moveNumber),
      moveNumber,
      status: line ? 'won' : moveNumber === 9 ? 'draw' : 'playing',
      winner: line ? move.player : null,
      line: line ? [line[0], line[1], line[2]] : null,
      history,
    },
  };
}

import { randomBytes } from 'node:crypto';
import type { Game, Refusal } from '../src/contract.js';
import { applyMove, emptyGame, type GameState, type Move } from './rules.js';

// Where the games live. `GameStore` is the seam: a deployment that outgrows one Node process
// replaces `createMemoryGameStore` with a store of its own (a key-value store, a Durable Object)
// and keeps the interface. The operations never see the map.

export type PlayResult =
  | { readonly kind: 'unknown' }
  | { readonly kind: 'played'; readonly game: Game }
  | { readonly kind: 'refused'; readonly reason: Refusal; readonly game: Game };

export interface GameStore {
  /** Starts a game under a new unguessable identifier. */
  create(): Promise<Game>;
  /** The current game, or `undefined` when the identifier is unknown or the game has expired. */
  get(gameId: string): Promise<Game | undefined>;
  /**
   * Checks the move against the game as it is now and applies it, as one step: two requests that
   * name the same `expectedMoveNumber` cannot both be applied. A refused move changes nothing and
   * returns the current game.
   */
  play(gameId: string, move: Move): Promise<PlayResult>;
}

export interface MemoryGameStoreOptions {
  /** How many games are kept. When full, the game that was played longest ago is dropped. */
  readonly capacity?: number;
  /** How long a game lives after it was created or last played. */
  readonly ttlMs?: number;
  readonly now?: () => number;
  /** Supplies identifiers; the default is 128 random bits. */
  readonly newId?: () => string;
}

interface Stored {
  state: GameState;
  expiresAt: number;
}

export const DEFAULT_CAPACITY = 200;
export const DEFAULT_TTL_MS = 30 * 60 * 1000;

const randomId = (): string => randomBytes(16).toString('base64url');

/**
 * A bounded map of short-lived games, in one process. Entries are ordered by when they were last
 * played, so the first entry is the one to drop when the map is full.
 *
 * Every method does its whole work before it returns control: `play` reads the game, checks the
 * move and stores the result without an `await` between, so on one thread no other request can
 * come between the check and the write. A store over a remote service must give the same
 * guarantee in its own way (a conditional write on the move number).
 */
export function createMemoryGameStore(
  options: MemoryGameStoreOptions = {},
): GameStore {
  const capacity = options.capacity ?? DEFAULT_CAPACITY;
  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
  const now = options.now ?? Date.now;
  const newId = options.newId ?? randomId;
  if (!Number.isInteger(capacity) || capacity < 1)
    throw new RangeError('capacity must be a positive integer');
  if (!Number.isFinite(ttlMs) || ttlMs <= 0)
    throw new RangeError('ttlMs must be a positive number');
  const games = new Map<string, Stored>();

  const live = (gameId: string): Stored | undefined => {
    const stored = games.get(gameId);
    if (stored === undefined) return undefined;
    if (stored.expiresAt <= now()) {
      games.delete(gameId);
      return undefined;
    }
    return stored;
  };
  const snapshot = (gameId: string, state: GameState): Game => ({
    gameId,
    ...state,
    board: [...state.board],
    history: state.history.map((entry) => ({ ...entry })),
    line: state.line === null ? null : [...state.line],
  });
  const dropExpired = (): void => {
    const at = now();
    for (const [gameId, stored] of games)
      if (stored.expiresAt <= at) games.delete(gameId);
  };

  return {
    async create() {
      dropExpired();
      while (games.size >= capacity) {
        const oldest = games.keys().next();
        if (oldest.done) break;
        games.delete(oldest.value);
      }
      let gameId = newId();
      while (games.has(gameId)) gameId = newId();
      const state = emptyGame();
      games.set(gameId, { state, expiresAt: now() + ttlMs });
      return snapshot(gameId, state);
    },
    async get(gameId) {
      const stored = live(gameId);
      return stored && snapshot(gameId, stored.state);
    },
    async play(gameId, move) {
      const stored = live(gameId);
      if (stored === undefined) return { kind: 'unknown' };
      const result = applyMove(stored.state, move);
      if (!result.ok)
        return {
          kind: 'refused',
          reason: result.reason,
          game: snapshot(gameId, stored.state),
        };
      games.delete(gameId); // re-inserted last: the map stays in the order games were played
      games.set(gameId, { state: result.state, expiresAt: now() + ttlMs });
      return { kind: 'played', game: snapshot(gameId, result.state) };
    },
  };
}

import { McpServer, type Implementation } from '@modelcontextprotocol/server';
import {
  registerPublicOperation,
  operationViewFromHtml,
  type OperationOutcome,
  type OperationView,
  type RequestLifetime,
} from '@saga-a2ui/react-mcp-stack/server';
import { z } from 'zod';
import {
  GameIdInputSchema,
  GameOutputSchema,
  GET_GAME_TOOL,
  MoveInputSchema,
  MoveOutputSchema,
  NEW_GAME_TOOL,
  PLAY_MOVE_TOOL,
  READS,
  SHOW_GAME_TOOL,
  TEXT,
  VIEW_MARKER,
  WRITES,
  type Game,
  type Refusal,
} from '../src/contract.js';
import type { GameStore, PlayResult } from './game-store.js';

// The game's MCP operations, declared with SAGA's server export. The application supplies the
// rules, store and built view; the SDK's local listener handles HTTP and MCP delivery.
// Each request builds its own server; the one store is shared by all of them.

/** The built view is required before the server can claim to serve anything. */
export class ViewArtifactMissing extends Error {
  constructor() {
    super(
      'The view has not been built: the server needs the built page and will not start without it.',
    );
    this.name = 'ViewArtifactMissing';
  }
}

/** The board, declared once for each operation that opens it. */
export interface BoardViews {
  readonly newGame: OperationView;
  readonly showGame: OperationView;
}

/**
 * Validate and fingerprint the deployment document once, before listening.
 *
 * `new_game` and `show_game` both open the board. A server registers a view's resource once per
 * address, and an operation's view is registered with it, so two operations cannot declare one
 * view object on the same server. Each therefore declares the same page under its own address
 * (`new-game` and `show-game`); a host that mounts either gets the same bytes.
 */
export function prepareBoardViews(html: unknown): BoardViews {
  if (typeof html !== 'string' || !html.includes(VIEW_MARKER))
    throw new ViewArtifactMissing();
  const board = (filename: string, title: string): OperationView =>
    operationViewFromHtml({ html, filename, title });
  return Object.freeze({
    newGame: board('new-game.html', 'Tic-tac-toe board (new game)'),
    showGame: board('show-game.html', 'Tic-tac-toe board (show game)'),
  });
}

/** What the model reads beside the structured game: the state in a few words. */
export function describeGame(game: Game): string {
  const rows = [0, 3, 6]
    .map((start) =>
      game.board
        .slice(start, start + 3)
        .map((cell) => cell ?? '-')
        .join(''),
    )
    .join('/');
  const where =
    game.status === 'won'
      ? `${game.winner} won with squares ${game.line?.join(', ')}.`
      : game.status === 'draw'
        ? 'The game ended in a draw.'
        : `It is ${game.turn}'s turn.`;
  return `Tic-tac-toe game ${game.gameId}, after move ${game.moveNumber}. Squares 0 to 8, row by row, with - for empty: ${rows}. ${where}`;
}

const REFUSAL_TEXT: Record<Refusal, string> = {
  game_over: 'The game is over.',
  stale_move: 'The board has moved on since that move was chosen.',
  not_your_turn: 'It is not that player’s turn.',
  occupied: 'That square is not available.',
};

const gameFound = (game: Game | undefined) =>
  game === undefined
    ? ({ kind: 'absent' } as const)
    : ({ kind: 'record', record: game } as const);

export interface GameServerOptions {
  /** The immutable views prepared before the listener opened. */
  readonly views: BoardViews;
  /** The request this server was built for, started by the listener at admission. */
  readonly lifetime: RequestLifetime;
  /** Every request's server shares this one store. */
  readonly store: GameStore;
  /** The icons the server announces to a host, such as its brand in light and dark. None by default. */
  readonly icons?: Implementation['icons'];
}

const failures = {
  absent: TEXT.noGame,
  unavailable: TEXT.unavailable,
  invalidOutput: TEXT.invalidOutput,
} as const;

// #region saga-snippet:register-game-operations
/**
 * The four operations. `new_game` and `show_game` open the board; `get_game` and `play_move` omit
 * `view`, so they return the game as data and open no card. The person's click and the assistant's
 * tool call reach the same `play_move`.
 */
export function createGameServer({
  views,
  lifetime,
  store,
  icons,
}: GameServerOptions): McpServer {
  const server = new McpServer({
    name: 'saga-tic-tac-toe',
    version: '0.0.0',
    ...(icons === undefined ? {} : { icons }),
  });
  const project = (game: Game) => ({
    text: describeGame(game),
    data: { game },
  });

  registerPublicOperation(
    server,
    {
      name: NEW_GAME_TOOL,
      title: 'Start a new game',
      description:
        'Starts a new game of tic-tac-toe and shows the board. The person plays X and moves first; you play O.',
      annotations: WRITES,
      input: z.strictObject({}),
      output: GameOutputSchema,
      view: views.newGame,
      failures,
      handle: async () => ({ kind: 'record', record: await store.create() }),
      project,
    },
    { lifetime },
  );

  registerPublicOperation(
    server,
    {
      name: SHOW_GAME_TOOL,
      title: 'Show a game',
      description:
        'Shows the board of an existing game, as it is now. Use it to display a game again; use get_game to read one.',
      annotations: READS,
      input: GameIdInputSchema,
      output: GameOutputSchema,
      view: views.showGame,
      failures,
      handle: async ({ gameId }) => gameFound(await store.get(gameId)),
      project,
    },
    { lifetime },
  );

  registerPublicOperation(
    server,
    {
      name: GET_GAME_TOOL,
      title: 'Read a game',
      description:
        'Reads the current state of a game, without showing a board: the squares, whose turn it is, the move number and how the game stands.',
      annotations: READS,
      input: GameIdInputSchema,
      output: GameOutputSchema,
      failures,
      handle: async ({ gameId }) => gameFound(await store.get(gameId)),
      project,
    },
    { lifetime },
  );

  registerPublicOperation(
    server,
    {
      name: PLAY_MOVE_TOOL,
      title: 'Play a move',
      description: [
        'Plays one square (0 to 8, row by row from the top left) for X or O and returns the game afterwards.',
        'You play O. Place X only when the person tells you their move in the conversation; their own clicks on the board place X for them.',
        'Give expectedMoveNumber as the moveNumber of the game you are answering. A move for an older board, a taken square, the wrong turn or a finished game is refused with no effect, and the result carries the current game.',
        'If the board is not in your context, read it with get_game first.',
        'If the board card cannot call the server, call show_game to display the board.',
      ].join(' '),
      annotations: WRITES,
      input: MoveInputSchema,
      output: MoveOutputSchema,
      failures,
      handle: async ({
        gameId,
        ...move
      }): Promise<
        OperationOutcome<Exclude<PlayResult, { kind: 'unknown' }>>
      > => {
        const result = await store.play(gameId, move);
        return result.kind === 'unknown'
          ? ({ kind: 'absent' } as const)
          : ({ kind: 'record', record: result } as const);
      },
      project: (result) =>
        result.kind === 'refused'
          ? {
              text: `Refused, and nothing changed: ${REFUSAL_TEXT[result.reason]} ${describeGame(result.game)}`,
              data: {
                game: result.game,
                outcome: 'refused' as const,
                reason: result.reason,
              },
            }
          : {
              text: describeGame(result.game),
              data: { game: result.game, outcome: 'played' as const },
            },
    },
    { lifetime },
  );
  return server;
}
// #endregion saga-snippet:register-game-operations

import type { BudgetSettings } from '@saga-a2ui/react-mcp-stack/server';
import {
  startLocalMcpServer,
  type LocalMcpServer,
} from '@saga-a2ui/react-mcp-stack/server/node';
import { createMemoryGameStore, type GameStore } from './game-store.js';
import { createGameServer, prepareBoardViews } from './operations.js';

export interface ListenerOptions {
  readonly html: string;
  readonly port: number;
  readonly store?: GameStore;
  readonly budgets?: BudgetSettings;
}

export function startListener(
  options: ListenerOptions,
): Promise<LocalMcpServer> {
  const views = prepareBoardViews(options.html);
  const store = options.store ?? createMemoryGameStore();
  return startLocalMcpServer({
    port: options.port,
    budgets: options.budgets,
    createServer: (lifetime) => createGameServer({ views, store, lifetime }),
  });
}

import { readFile } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { startListener } from './listener.js';

// The server entry. It reads the built view before it opens a port, so a missing build stops the
// process instead of serving a listener without its view. `npm run build` writes the view beside
// this file; `npm start` runs it.
const html = await readFile(
  path.join(path.dirname(fileURLToPath(import.meta.url)), 'index.html'),
  'utf8',
);
const listener = await startListener({
  html,
  port: Number(process.env.PORT ?? 3000),
});

console.log(`Tic-tac-toe MCP endpoint: ${listener.url}`);

// Stop the MCP handler and every HTTP exchange before allowing Node to exit.
for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => {
    void listener.close().catch(() => {
      process.exitCode = 1;
    });
  });
}

import '@saga-a2ui/react-mcp-stack/attribution.css';
import './index.css';
import { startView } from './view.js';

await startView();

import type { Game, Refusal } from './contract.js';
import type { RequestOutcome } from '@saga-a2ui/react-mcp-stack';

// Everything the person reads or the conversation receives, in one place. Fixed sentences: none of
// them repeats a backend message.

export const VIEW_TEXT = {
  sendHint: 'When a message appears in the chat box, click Send to continue.',
  waiting: 'Waiting for a game…',
  checking: 'Checking the current game…',
  yourTurn: 'Your move. You are X.',
  assistantTurn: 'Waiting for the assistant to play O…',
  assistantSlow: 'Could not read the game. Check the connection.',
  stillWaiting: 'Still no move from the assistant.',
  won: 'You won!',
  lost: 'The assistant won.',
  draw: 'It is a draw.',
  gone: 'That game is not available any more. Start a new game.',
  problem: 'This could not be shown.',
  mismatch:
    'This could not be shown: the view and its server are from different builds. Reopen it; if this continues, update the server and the view together.',
  unconfirmed: 'Could not read the current game. Check the connection.',
  contextFailed: 'The host could not share this game with the assistant.',
  closed: 'This view was closed.',
} as const;

/** An unconfirmed message may still have arrived; do not resend it automatically. */
export const MESSAGE_FAILURE: Record<RequestOutcome, string> = {
  unavailable: 'This host does not support messages from this card.',
  denied: 'The host declined the message. Check its confirmation controls.',
  failed:
    'The host did not confirm the message. Check for a pending confirmation.',
};

export const REFUSAL_TEXT: Record<Refusal, string> = {
  game_over: 'That game is over.',
  stale_move: 'The board had moved on, so that move was not played.',
  not_your_turn: 'It is not your turn.',
  occupied: 'That square is taken.',
};

/** "Row 1, column 2, empty": what a screen reader says for a square. */
export function squareLabel(index: number, mark: 'X' | 'O' | null): string {
  return `Row ${Math.floor(index / 3) + 1}, column ${(index % 3) + 1}, ${mark ?? 'empty'}`;
}

/** One move in words, for the history: "You: row 2, column 2". */
export function moveText(
  move: Game['history'][number],
  at: number,
): { text: string } {
  return {
    text: `${at + 1}. ${move.player === 'X' ? 'You' : 'Assistant'}: row ${Math.floor(move.square / 3) + 1}, column ${(move.square % 3) + 1}`,
  };
}

/** The status line for a game, before any note is added. */
export function headline(
  game: Game,
  assistant: 'idle' | 'waiting' | 'expired',
): string {
  if (game.status === 'won')
    return game.winner === 'X' ? VIEW_TEXT.won : VIEW_TEXT.lost;
  if (game.status === 'draw') return VIEW_TEXT.draw;
  if (game.turn === 'X') return VIEW_TEXT.yourTurn;
  return assistant === 'expired'
    ? VIEW_TEXT.assistantSlow
    : VIEW_TEXT.assistantTurn;
}

// Short messages for the person; game identity and move instructions stay in context.

export const CONVERSATION = {
  newGame: "Let's play a new game.",
  /** Gives the assistant its turn. */
  yourMove: 'Your turn',
  /** Reports how a game that X's move ended came out, and asks for no move. */
  result: (game: Game): string =>
    game.winner === 'X'
      ? 'I won our tic-tac-toe game.'
      : 'Our tic-tac-toe game ended in a draw.',
  /** The context that goes with the move message: for the assistant, not shown in the conversation. */
  boardForAssistant: (game: Game): string =>
    `Tic-tac-toe game ${game.gameId} after move ${game.moveNumber}. Squares 0 to 8, row by row, with - for empty: ${[
      0, 3, 6,
    ]
      .map((start) =>
        game.board
          .slice(start, start + 3)
          .map((cell) => cell ?? '-')
          .join(''),
      )
      .join(
        '/',
      )}. It is ${game.turn}'s turn. Play O in this game with play_move, using this move number. If you need its current state, read get_game.`,
} as const;

import {
  ActionButtonEntry,
  Catalog,
  ColumnApi,
  CommonSchemas,
  createComponentImplementation,
  ListApi,
  RowApi,
  SagaAttribution,
  z,
  type HostLinks,
  type ReactCatalogComponent,
} from '@saga-a2ui/react-mcp-stack';
import type { ReactNode } from 'react';
import { CATALOG_ID } from './surface.js';

// The application-owned catalog: the components its layout may name, and nothing else. Every
// component here is this application's own and shows supplied text as text, never as markup;
// `ActionButton` is SAGA's opt-in control. Nothing is registered globally by the SDK.

type ChildReference =
  string | { readonly id: string; readonly basePath: string };

// The view hands a child list over as tokens, or `{ id, basePath }` for a template item.
function childrenOf(
  buildChild: (id: string, basePath?: string) => ReactNode,
  value: unknown,
): ReactNode[] {
  const list = Array.isArray(value) ? (value as ChildReference[]) : [];
  return list.map((child) =>
    typeof child === 'string'
      ? buildChild(child)
      : buildChild(child.id, child.basePath),
  );
}

const LineApi = {
  name: 'Line',
  schema: z
    .object({
      text: CommonSchemas.DynamicString,
      kind: z.enum(['body', 'status']),
    })
    .strict(),
};

const Line: ReactCatalogComponent = createComponentImplementation(
  LineApi,
  ({ props }) => {
    const text = String(props.text ?? '');
    // The status element is present before it speaks, so a screen reader announces each change.
    return props.kind === 'status' ? (
      <p className="status" role="status">
        {text}
      </p>
    ) : (
      <span>{text}</span>
    );
  },
);

/** Native disclosure keeps the identifier available without crowding the board. */
const GameDetails: ReactCatalogComponent = createComponentImplementation(
  {
    name: 'GameDetails',
    schema: z.object({ gameId: CommonSchemas.DynamicString }).strict(),
  },
  ({ props }) => (
    <details>
      <summary>Show game ID</summary>
      <code>{String(props.gameId ?? '')}</code>
    </details>
  ),
);

const Column: ReactCatalogComponent = createComponentImplementation(
  ColumnApi,
  ({ props, buildChild }) => (
    <div className="column">{childrenOf(buildChild, props.children)}</div>
  ),
);

const Row: ReactCatalogComponent = createComponentImplementation(
  RowApi,
  ({ props, buildChild }) => (
    <div className="row">{childrenOf(buildChild, props.children)}</div>
  ),
);

/** The nine squares in a three-by-three grid. */
const Board: ReactCatalogComponent = createComponentImplementation(
  { ...ListApi, name: 'Board' },
  ({ props, buildChild }) => (
    <div className="board" role="group" aria-label="Tic-tac-toe board">
      {childrenOf(buildChild, props.children)}
    </div>
  ),
);

const SquareFaceApi = {
  name: 'SquareFace',
  schema: z
    .object({
      mark: CommonSchemas.DynamicString,
      label: CommonSchemas.DynamicString,
      winning: CommonSchemas.DynamicString,
    })
    .strict(),
};

/**
 * What goes inside a square's button: the mark for the eye, and the full name for assistive
 * technology ("Row 1, column 2, empty"), which becomes the button's accessible name.
 */
const SquareFace: ReactCatalogComponent = createComponentImplementation(
  SquareFaceApi,
  ({ props }) => (
    <span className={props.winning ? 'square winning' : 'square'}>
      <span aria-hidden="true">{String(props.mark ?? '')}</span>
      <span className="visually-hidden">{String(props.label ?? '')}</span>
    </span>
  ),
);

const ShownApi = {
  name: 'Shown',
  schema: z
    .object({
      when: CommonSchemas.DynamicString,
      child: CommonSchemas.ComponentId,
    })
    .strict(),
};

/** Shows its child only while `when` is not empty, so a control can be absent instead of disabled. */
const Shown: ReactCatalogComponent = createComponentImplementation(
  ShownApi,
  ({ props, buildChild }) =>
    String(props.when ?? '') !== '' && typeof props.child === 'string'
      ? buildChild(props.child)
      : null,
);

/**
 * The framework credit, placed once at the foot of the card so it shows while playing, after the
 * game ends and beside a recoverable error. The application supplies it with the host's way to
 * open a link; deleting this component and the layout's `credit` entry removes the credit.
 */
function createCredit(
  links: () => HostLinks | undefined,
): ReactCatalogComponent {
  return createComponentImplementation(
    { name: 'Credit', schema: z.object({}).strict() },
    () => (
      <footer className="credit">
        <SagaAttribution links={links()} />
      </footer>
    ),
  );
}

export const boardEntries: readonly ReactCatalogComponent[] = [
  Column,
  Row,
  Board,
  Line,
  SquareFace,
  Shown,
  GameDetails,
  ActionButtonEntry,
];

/**
 * The one function the layout calls: the squares' `checks` use it to disable a control. A catalog
 * holds only the functions its application declares, so this one is the application's own; it
 * is `required` from the A2UI basic catalog, written out: a value that is missing or empty fails.
 */
const required = {
  name: 'required',
  returnType: 'boolean',
  schema: z.object({ value: z.any() }).strict(),
  execute: (args: Record<string, unknown>): boolean =>
    args.value !== undefined && args.value !== null && args.value !== '',
};

/**
 * What the stack presents the layout over. `links` returns the host's way to open a link, which
 * the stack hands over when the view starts and before the first render.
 */
export function createBoardCatalog(
  links: () => HostLinks | undefined,
): Catalog<ReactCatalogComponent> {
  return new Catalog<ReactCatalogComponent>(
    CATALOG_ID,
    'v0.9',
    [...boardEntries, createCredit(links)],
    [required],
  );
}

import { defineSurface, z } from '@saga-a2ui/react-mcp-stack';
import { VIEW_TEXT } from './text.js';

// The layout of the board: its data and its components. The layout gives the markup its IDs and its
// structure and nothing else: it names no action, no handler and no function. Which behavior a
// control has is decided by application code that attaches an action to the rendered instance
// (view.tsx), never by a name in this layout.

export const CATALOG_ID = 'https://saga-a2ui.dev/catalogs/tic-tac-toe/board/v1';

/** The IDs the application attaches actions to. */
export const SQUARE_ID = 'square';
export const NEW_GAME_ID = 'new-game';
export const CHECK_ID = 'check-move';

const SquareDataSchema = z.object({
  /** The square's number, 0 to 8, which the square action sends. */
  index: z.number(),
  /** What a screen reader says: "Row 1, column 2, empty". */
  label: z.string(),
  /** "X", "O" or empty. */
  mark: z.string(),
  /** Non-empty when the square can be played now; an empty string disables the control. */
  playable: z.string(),
  /** Non-empty for the three squares of a winning line. */
  winning: z.string(),
});

const BoardDataSchema = z.object({
  gameId: z.string(),
  /** The one status line: whose turn it is, how the game ended, or what to do next. */
  status: z.string(),
  squares: z.array(SquareDataSchema),
  /** Non-empty when "Check for the assistant's move" should be offered. */
  canCheck: z.string(),
  /** The moves so far, in words, one line each. */
  history: z.array(z.object({ text: z.string() })),
});

export const boardSurface = defineSurface({
  surfaceId: 'board',
  catalogId: CATALOG_ID,
  data: BoardDataSchema,
  initial: { gameId: '', status: '', squares: [], canCheck: '', history: [] },
  root: {
    component: 'Column',
    bind: {},
    props: {
      children: [
        'status',
        'send-hint',
        'board',
        'controls',
        'game-details',
        'credit',
      ],
    },
  },
  components: [
    {
      id: 'send-hint',
      component: 'Line',
      kind: 'body',
      text: VIEW_TEXT.sendHint,
    },
    { id: 'credit', component: 'Credit' },
    {
      id: 'game-details',
      component: 'GameDetails',
      gameId: { path: '/gameId' },
    },
    {
      id: 'status',
      component: 'Line',
      kind: 'status',
      text: { path: '/status' },
    },
    {
      id: 'board',
      component: 'Board',
      children: { componentId: SQUARE_ID, path: '/squares' },
    },
    {
      id: SQUARE_ID,
      component: 'ActionButton',
      child: 'square-face',
      // A control whose check fails is disabled, so an occupied square, the assistant's turn and a
      // finished game all leave nothing to press.
      checks: [
        {
          condition: {
            call: 'required',
            args: { value: { path: 'playable' } },
          },
          message: 'This square cannot be played now.',
        },
      ],
    },
    {
      id: 'square-face',
      component: 'SquareFace',
      mark: { path: 'mark' },
      label: { path: 'label' },
      winning: { path: 'winning' },
    },
    {
      id: 'controls',
      component: 'Row',
      children: [NEW_GAME_ID, 'check-slot'],
    },
    { id: NEW_GAME_ID, component: 'ActionButton', child: 'new-game-label' },
    {
      id: 'new-game-label',
      component: 'Line',
      kind: 'body',
      text: 'New game',
    },
    {
      id: 'check-slot',
      component: 'Shown',
      when: { path: '/canCheck' },
      child: CHECK_ID,
    },
    { id: CHECK_ID, component: 'ActionButton', child: 'check-label' },
    {
      id: 'check-label',
      component: 'Line',
      kind: 'body',
      text: "Check for the assistant's move",
    },
  ],
});

/** The data the surface shows: replaced whole by each update. */
export type BoardData = z.infer<typeof BoardDataSchema>;

:root {
  color-scheme: light dark;
  font-family: system-ui, sans-serif;
}
body {
  margin: 0;
  padding: 1rem;
}
.column {
  display: grid;
  gap: 0.75rem;
  justify-items: start;
}
.row {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}
.status {
  margin: 0;
  min-height: 1.5em;
  font-size: 1.05rem;
}
.board {
  display: grid;
  grid-template-columns: repeat(3, 5rem);
  gap: 0.4rem;
}
.board button {
  width: 5rem;
  height: 5rem;
  padding: 0;
  font-size: 2.25rem;
  font-weight: 600;
  border: 2px solid currentColor;
  border-radius: 0.5rem;
  background: transparent;
  color: inherit;
  cursor: pointer;
}
.board button:disabled {
  cursor: default;
}
.board button:not(:disabled):hover {
  background: color-mix(in srgb, currentColor 12%, transparent);
}
.board button:focus-visible,
.row button:focus-visible {
  outline: 3px solid Highlight;
  outline-offset: 2px;
}
.square.winning {
  text-decoration: underline;
  text-decoration-thickness: 0.2rem;
}
.row button {
  padding: 0.45rem 0.9rem;
  font: inherit;
  border: 2px solid currentColor;
  border-radius: 0.5rem;
  background: transparent;
  color: inherit;
  cursor: pointer;
}
.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  overflow: hidden;
  clip: rect(0 0 0 0);
  white-space: nowrap;
}
.credit {
  margin-top: 1rem;
}

import {
  GameOutputSchema,
  GET_GAME_TOOL,
  TEXT,
  type Game,
} from './contract.js';
import type { BoardData } from './surface.js';
import { headline, moveText, squareLabel, VIEW_TEXT } from './text.js';

// The part of the view that does not depend on React: which game the board shows, what it says,
// which squares can be played, and the wait for the assistant's move. The stack's bound surface is
// the only thing it draws on. Every game the board shows goes through `present`.

/** The stack's bound surface, as far as the controller needs it. */
export interface BoardSurface {
  /** Replaces the data shown, in place. Does nothing once the view is gone. */
  update(data: BoardData): unknown;
}

/** The server as the view reaches it; the host proxies each call. */
export interface GameServer {
  callServerTool(
    request: {
      readonly name: string;
      readonly arguments: Record<string, unknown>;
    },
    options?: { readonly signal?: AbortSignal },
  ): Promise<{
    readonly isError?: boolean;
    readonly content: readonly unknown[];
    readonly structuredContent?: unknown;
  }>;
}

/** The game and move a request was made for. */
export interface Shown {
  readonly gameId: string;
  readonly moveNumber: number;
}

/** Keep watching while the game exists, including time spent confirming a host message. */
export const WAIT = {
  everyMs: 1_500,
  slowMs: 5_000,
  fastReads: 40,
  failures: 40,
} as const;

export type ReadResult =
  | { readonly kind: 'game'; readonly game: Game }
  | { readonly kind: 'gone' }
  | { readonly kind: 'failed' };

interface Reply {
  readonly isError?: boolean;
  readonly content: readonly unknown[];
  readonly structuredContent?: unknown;
}

/** An error whose fixed text says the server has no such game: unknown, or expired. */
export function replyIsGone(reply: Reply): boolean {
  if (reply.isError !== true) return false;
  const first = reply.content[0] as { text?: unknown } | undefined;
  return first?.text === TEXT.noGame;
}

/** What a `get_game`-shaped reply says. */
export function readGameReply(reply: Reply): ReadResult {
  if (replyIsGone(reply)) return { kind: 'gone' };
  if (reply.isError === true) return { kind: 'failed' };
  const parsed = GameOutputSchema.safeParse(reply.structuredContent);
  return parsed.success
    ? { kind: 'game', game: parsed.data.game }
    : { kind: 'failed' };
}

export async function readGame(
  server: GameServer,
  gameId: string,
  signal?: AbortSignal,
): Promise<ReadResult> {
  try {
    return readGameReply(
      await server.callServerTool(
        { name: GET_GAME_TOOL, arguments: { gameId } },
        signal === undefined ? undefined : { signal },
      ),
    );
  } catch {
    return { kind: 'failed' };
  }
}

type Assistant = 'idle' | 'waiting' | 'expired';

export interface GameController {
  /** Draws on this surface from now on. */
  attach(surface: BoardSurface): void;
  /**
   * Shows a game. One function for every game the board shows, and it checks the game's identity
   * before its move number: a game other than the selected one is ignored (a late answer for the
   * previous game cannot replace the current one), and within the selected game an older move
   * number is ignored. Only `select` changes which game is selected. Returns whether it was shown.
   */
  present(game: Game, mode?: 'follow' | 'select'): boolean;
  /** The game on screen. */
  current(): Game | undefined;
  /** Whether this game and move are on screen, that is, nothing newer has replaced them. */
  isShowing(shown: Shown): boolean;
  /** The identity the square actions compare: it changes when the game or its move number does. */
  subject(): string;
  /** A note after the status line, shown until a newer move replaces it. */
  say(note: string): void;
  /** The selected game is not there any more. */
  markGone(): void;
  /** Takes the squares away from the person while their request is in flight; give the token back to `unlock`. */
  lock(): object;
  unlock(token: object): void;
  /** Reads the current game, keeping squares off on failure. Returns nothing for an obsolete read. */
  refresh(): Promise<Game | undefined>;
  /** Starts the wait for the assistant's move on the game on screen. */
  startWait(): void;
  /** Ends the view: nothing is drawn or read afterwards. */
  retire(): void;
}

export function createGameController(server: GameServer): GameController {
  let surface: BoardSurface | undefined;
  let game: Game | undefined;
  let note = '';
  let gone = false;
  let confirmed = false;
  let retired = false;
  // Recovery reads in flight for the selected game. Selecting another game empties it, so an old
  // read neither holds the new game's squares off nor, when it settles, changes anything.
  const readings = new Set<object>();
  const locks = new Set<object>();
  let assistant: Assistant = 'idle';
  let wait: { readonly stop: () => void } | undefined;
  let waitingFor = '';

  const render = (): void => {
    if (retired || surface === undefined) return;
    const open =
      game !== undefined &&
      !gone &&
      confirmed &&
      game.status === 'playing' &&
      game.turn === 'X' &&
      readings.size === 0 &&
      locks.size === 0;
    const text =
      game === undefined
        ? VIEW_TEXT.waiting
        : gone
          ? VIEW_TEXT.gone
          : readings.size > 0
            ? VIEW_TEXT.checking
            : !confirmed
              ? VIEW_TEXT.unconfirmed
              : [headline(game, assistant), note].filter(Boolean).join(' ');
    surface.update({
      gameId: game?.gameId ?? '',
      status: text,
      canCheck:
        game !== undefined &&
        !gone &&
        game.status === 'playing' &&
        game.turn === 'O' &&
        assistant === 'expired'
          ? 'yes'
          : '',
      history: (game?.history ?? []).map(moveText),
      squares: (game?.board ?? Array.from({ length: 9 }, () => null)).map(
        (mark, index) => ({
          index,
          label: squareLabel(index, mark),
          mark: mark ?? '',
          playable: open && mark === null ? 'yes' : '',
          winning: game?.line?.includes(index) ? 'yes' : '',
        }),
      ),
    });
  };

  const stopWait = (): void => {
    wait?.stop();
    wait = undefined;
    if (assistant === 'waiting') assistant = 'idle';
  };

  const controller: GameController = {
    attach(target) {
      surface = target;
      render();
    },

    present(next, mode = 'follow') {
      if (retired) return false;
      if (game !== undefined && next.gameId !== game.gameId) {
        if (mode !== 'select') return false;
        stopWait();
        assistant = 'idle';
        gone = false;
        note = '';
        readings.clear(); // a read for the previous game no longer concerns the board
        game = next;
        confirmed = true;
        render();
        return true;
      }
      if (game !== undefined && next.moveNumber < game.moveNumber) return false;
      if (game === undefined || next.moveNumber > game.moveNumber) note = '';
      gone = false;
      game = next;
      confirmed = true;
      if (game.status !== 'playing' || game.turn === 'X') {
        stopWait();
        assistant = 'idle';
      }
      render();
      return true;
    },

    current: () => game,

    isShowing: (shown) =>
      game !== undefined &&
      game.gameId === shown.gameId &&
      game.moveNumber === shown.moveNumber,

    subject: () =>
      game === undefined ? '' : `${game.gameId}:${game.moveNumber}`,

    say(text) {
      note = text;
      render();
    },

    markGone() {
      stopWait();
      gone = true;
      render();
    },

    lock() {
      const token = {};
      locks.add(token);
      render();
      return token;
    },

    unlock(token) {
      locks.delete(token);
      render();
    },

    async refresh() {
      const shown = game;
      if (shown === undefined) return;
      const token = {};
      readings.add(token);
      confirmed = false;
      render();
      const result = await readGame(server, shown.gameId);
      // Selecting another game, or ending the view, drops the token: the answer is ignored.
      if (!readings.delete(token) || retired) return;
      if (result.kind === 'game') {
        controller.present(result.game);
        controller.startWait();
        return controller.current();
      } else if (result.kind === 'gone') controller.markGone();
      render();
    },

    startWait() {
      const waiting = game;
      if (
        retired ||
        waiting === undefined ||
        waiting.status !== 'playing' ||
        waiting.turn !== 'O'
      )
        return;
      if (wait !== undefined && waitingFor === waiting.gameId) return; // already waiting on this game
      stopWait();
      waitingFor = waiting.gameId;
      const ended = new AbortController();
      let timer: ReturnType<typeof setTimeout> | undefined;
      let reads = 0;
      let failures = 0;
      const mine = {
        stop: () => {
          ended.abort();
          clearTimeout(timer);
        },
      };
      wait = mine;
      assistant = 'waiting';
      render();

      const schedule = (): void => {
        timer = setTimeout(
          () => void tick(),
          reads < WAIT.fastReads ? WAIT.everyMs : WAIT.slowMs,
        );
      };
      const tick = async (): Promise<void> => {
        if (wait !== mine) return;
        reads += 1;
        const result = await readGame(server, waiting.gameId, ended.signal);
        if (wait !== mine) return; // another game, the assistant's move, the limit or the end of the view
        if (result.kind === 'game') {
          failures = 0;
          controller.present(result.game);
          if (wait !== mine) return; // `present` ended the wait: the assistant moved
        } else if (result.kind === 'gone') {
          controller.markGone();
          return;
        }
        if (result.kind === 'failed') failures += 1;
        if (failures >= WAIT.failures) {
          wait = undefined;
          assistant = 'expired';
          render();
          return;
        }
        schedule();
      };
      schedule();
    },

    retire() {
      retired = true;
      wait?.stop();
      wait = undefined;
      surface = undefined;
    },
  };
  return controller;
}