miaoda-game-hearts-react

React bindings and a framework-neutral controller for the fixed four-player American Hearts profile.

pnpm add miaoda-game-hearts-react

import {
  createHeartsGame,
  HeartsController,
  useHeartsView,
} from 'miaoda-game-hearts-react';

const controller = new HeartsController(
  createHeartsGame({ playerIds: ['north', 'east', 'south', 'west'], seed: 2026 }),
  'north',
);

function PlayControls() {
  const view = useHeartsView(controller);
  const cardId = view.legalActions.playCardIds[0];
  return cardId ? (
    <button onClick={() => controller.dispatch({ type: 'play-card', playerId: view.viewerId, cardId })}>
      Play
    </button>
  ) : null;
}

Render pass, trick-play, moon-score, and next-hand controls only from legalActions. The view includes the selected player's hand and public game facts, never opponent hands or pending secret selections.

Commits and reconnects

const unsubscribe = controller.onCommit(({ revision, view, events }) => {
  queueAnimations(events);
  persistRevision(revision);
  renderHud(view);
});

controller.replaceSnapshot(JSON.parse(savedJson), serverRevision);
controller.setViewerId('east');

Only accepted actions advance revision or publish commits. Snapshot replacement validates the authoritative Hearts state and updates the view without fabricating historical events. Invalid viewers, corrupt snapshots, and lower revisions throw without partially changing the controller.

Phaser

pnpm add miaoda-game-command-phaser

import { PhaserGameBridge } from 'miaoda-game-command-phaser';

const bridge = new PhaserGameBridge().setup(controller);
bridge.consumeWith((event) => animateHeartsEvent(event));
bridge.dispatch({ type: 'play-card', playerId: controller.view.viewerId, cardId });

bridge.destroy();
unsubscribe();

The bridge consumes successful commits in order and exposes the same player-safe view and detached public events as React. Secret pass card ids never appear in commit events.