@table-games-engine/game-kit 0.0.0-stage → 0.1.0

package/nakama/init.ts

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Nakama TypeScript runtime entry point.
+ *
+ * Nakama hosts this file as a CommonJS bundle (single file, no `node_modules`
+ * resolution at runtime, no ESM). The host invokes the top-level
+ * `InitModule(ctx, logger, nk, initializer)` function exactly once on boot.
+ *
+ * Wires `@table-games-engine/nakama-adapter`'s match handler into Nakama,
+ * registers the reference games via `GameRegistry`, and exposes an RPC
+ * `create_tabletop_match(payload)` that clients call to spawn a match.
+ *
+ * IMPORTANT — Nakama 3.x match-handler binding requirement:
+ * `initializer.registerMatch(name, handler)` looks up the handler's seven
+ * methods by NAME in the bundle's global object scope. A closure-bound
+ * object (the value `createMatchHandler` returns) doesn't satisfy this
+ * lookup. We define top-level named functions `matchInit`/`matchJoinAttempt`/
+ * etc. that delegate to a module-scope singleton populated inside
+ * `InitModule`. This keeps the M3 adapter's API untouched while satisfying
+ * Nakama's global-name binding contract.
+ *
+ * The trailing `!InitModule && InitModule;` expression keeps the function
+ * symbol alive when the bundler tree-shakes the module — the function is
+ * only ever called by the runtime host.
+ */
+
+/// <reference path="./nkruntime.d.ts" />
+
+import {
+  createMatchHandler,
+  GameRegistry,
+  IdempotencyCache,
+} from '@table-games-engine/nakama-adapter';
+import { registerPlugin } from '@table-games-engine/nakama-adapter';
+import game from '__game__';
+
+const MATCH_HANDLER_NAME = 'tabletop_match';
+
+// Nakama allocates a pool of independent JS runtimes; module-level state
+// is NOT shared between the InitModule runtime and the per-match runtimes.
+// Lazy-build the handler per-runtime on first match-handler invocation.
+let _handler: ReturnType<typeof createMatchHandler> | null = null;
+
+function _ensureHandler(): ReturnType<typeof createMatchHandler> {
+  if (!_handler) {
+    const registry = new GameRegistry();
+    registerPlugin(registry, game);
+    _handler = createMatchHandler({
+      registry,
+      idempotencyCache: new IdempotencyCache(),
+    });
+  }
+  return _handler;
+}
+
+// Nakama-required match-handler entry points. Each function MUST be
+// declared at the bundle's top level so Nakama can resolve it by name.
+// The arity is intentional and matches Nakama's TS runtime contract.
+
+function matchInit(
+  ctx: nkruntime.Context,
+  logger: nkruntime.Logger,
+  nk: nkruntime.Nakama,
+  params: { [key: string]: string },
+): { state: unknown; tickRate: number; label: string } {
+  return _ensureHandler().matchInit(ctx, logger, nk, params) as never;
+}
+
+function matchJoinAttempt(
+  ctx: nkruntime.Context,
+  logger: nkruntime.Logger,
+  nk: nkruntime.Nakama,
+  dispatcher: nkruntime.MatchDispatcher,
+  tick: number,
+  state: unknown,
+  presence: nkruntime.Presence,
+  metadata: { [key: string]: unknown },
+): { state: unknown; accept: boolean; rejectMessage?: string } | null {
+  return _ensureHandler().matchJoinAttempt(
+    ctx, logger, nk, dispatcher as never, tick, state as never, presence as never, metadata,
+  ) as never;
+}
+
+function matchJoin(
+  ctx: nkruntime.Context,
+  logger: nkruntime.Logger,
+  nk: nkruntime.Nakama,
+  dispatcher: nkruntime.MatchDispatcher,
+  tick: number,
+  state: unknown,
+  presences: nkruntime.Presence[],
+): { state: unknown } | null {
+  return _ensureHandler().matchJoin(
+    ctx, logger, nk, dispatcher as never, tick, state as never, presences as never,
+  ) as never;
+}
+
+function matchLeave(
+  ctx: nkruntime.Context,
+  logger: nkruntime.Logger,
+  nk: nkruntime.Nakama,
+  dispatcher: nkruntime.MatchDispatcher,
+  tick: number,
+  state: unknown,
+  presences: nkruntime.Presence[],
+): { state: unknown } | null {
+  return _ensureHandler().matchLeave(
+    ctx, logger, nk, dispatcher as never, tick, state as never, presences as never,
+  ) as never;
+}
+
+function matchLoop(
+  ctx: nkruntime.Context,
+  logger: nkruntime.Logger,
+  nk: nkruntime.Nakama,
+  dispatcher: nkruntime.MatchDispatcher,
+  tick: number,
+  state: unknown,
+  messages: nkruntime.MatchData[],
+): { state: unknown } | null {
+  return _ensureHandler().matchLoop(
+    ctx, logger, nk, dispatcher as never, tick, state as never, messages as never,
+  ) as never;
+}
+
+function matchTerminate(
+  ctx: nkruntime.Context,
+  logger: nkruntime.Logger,
+  nk: nkruntime.Nakama,
+  dispatcher: nkruntime.MatchDispatcher,
+  tick: number,
+  state: unknown,
+  graceSeconds: number,
+): { state: unknown } | null {
+  return _ensureHandler().matchTerminate(
+    ctx, logger, nk, dispatcher as never, tick, state as never, graceSeconds,
+  ) as never;
+}
+
+function matchSignal(
+  ctx: nkruntime.Context,
+  logger: nkruntime.Logger,
+  nk: nkruntime.Nakama,
+  dispatcher: nkruntime.MatchDispatcher,
+  tick: number,
+  state: unknown,
+  data: string,
+): { state: unknown; data?: string } | null {
+  return _ensureHandler().matchSignal(
+    ctx, logger, nk, dispatcher as never, tick, state as never, data,
+  ) as never;
+}
+
+function createTabletopMatchRpc(
+  _rpcCtx: nkruntime.Context,
+  rpcLogger: nkruntime.Logger,
+  nk: nkruntime.Nakama,
+  payload: string,
+): string {
+  let parsed: { gameId?: string; matchId?: string; playerIds?: string[]; config?: Record<string, unknown> } = {};
+  try {
+    parsed = payload ? JSON.parse(payload) : {};
+    // nakama-js's `client.rpc(session, id, input)` JSON-encodes `input`
+    // before posting. When callers pass an object, we receive an empty body
+    // string ("{}"); when callers pre-stringify (the supported path) we
+    // receive the string twice-encoded — an outer JSON string wrapping the
+    // inner object. After the first parse we get the inner string; parse
+    // again to land on the actual object.
+    if (typeof parsed === 'string') {
+      parsed = JSON.parse(parsed);
+    }
+  } catch (err) {
+    rpcLogger.warn('create_tabletop_match: invalid JSON payload: %s', String(err));
+    throw new Error('Invalid JSON payload');
+  }
+  const gameId = parsed.gameId;
+  if (!gameId) {
+    throw new Error('payload.gameId is required');
+  }
+  // Nakama's matchCreate accepts only string-valued params; stringify
+  // any complex shapes (player lists) here, the match handler decodes.
+  const params: { [key: string]: string } = { gameId };
+  if (parsed.matchId) params.matchId = parsed.matchId;
+  if (parsed.playerIds && parsed.playerIds.length > 0) {
+    params.playerIds = parsed.playerIds.join(',');
+  }
+  if (parsed.config) params.config = JSON.stringify(parsed.config);
+  const matchId = nk.matchCreate(MATCH_HANDLER_NAME, params);
+  rpcLogger.info('Created tabletop match %s for game %s', matchId, gameId);
+  return JSON.stringify({ matchId });
+}
+
+function InitModule(
+  _ctx: nkruntime.Context,
+  logger: nkruntime.Logger,
+  _nk: nkruntime.Nakama,
+  initializer: nkruntime.Initializer,
+): void {
+  initializer.registerMatch(MATCH_HANDLER_NAME, {
+    matchInit,
+    matchJoinAttempt,
+    matchJoin,
+    matchLeave,
+    matchLoop,
+    matchTerminate,
+    matchSignal,
+  });
+
+  initializer.registerRpc('create_tabletop_match', createTabletopMatchRpc);
+
+  logger.info('game-kit preview runtime loaded - game %s', String(game.id));
+}
+
+// Keep the symbol live for Nakama's V8 host. Do not remove.
+// eslint-disable-next-line @typescript-eslint/no-unused-expressions
+!InitModule && InitModule;

package/nakama/local.yml

@@ -0,0 +1,28 @@
+# Nakama local config for the SaaS Game Engine playground.
+#
+# `runtime.path` is the directory Nakama scans on boot for runtime
+# modules (Lua / Go / TypeScript). `runtime.js_entrypoint` names the
+# bundled CommonJS file; Nakama then calls its top-level
+# `InitModule(ctx, logger, nk, initializer)` function once.
+name: game-kit-nakama
+data_dir: /nakama/data
+
+logger:
+  level: INFO
+  stdout: true
+
+session:
+  encryption_key: defaultencryptionkey
+  token_expiry_sec: 7200
+
+socket:
+  server_key: defaultkey
+
+console:
+  port: 7351
+  username: admin
+  password: localdev
+
+runtime:
+  path: /nakama/data/modules
+  js_entrypoint: index.js

package/nakama/nkruntime.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview Minimal `nkruntime` namespace type stubs.
+ *
+ * Nakama's official `nkruntime` types ship inside the Nakama runtime image
+ * itself (no public npm package as of 2026). For local typechecking we declare
+ * the structural subset of the namespace this server actually uses. The real
+ * implementation is provided by the V8 host at runtime; nothing in this file
+ * appears in the bundled output.
+ *
+ * Reference:
+ *   https://heroiclabs.com/docs/nakama/server-framework/typescript-setup/
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+declare namespace nkruntime {
+  interface Logger {
+    debug(format: string, ...args: unknown[]): void;
+    info(format: string, ...args: unknown[]): void;
+    warn(format: string, ...args: unknown[]): void;
+    error(format: string, ...args: unknown[]): void;
+  }
+
+  interface Context {
+    [key: string]: unknown;
+  }
+
+  interface Presence {
+    userId: string;
+    sessionId: string;
+    username?: string;
+    node?: string;
+    status?: string;
+  }
+
+  interface MatchData {
+    opCode: number;
+    data: Uint8Array;
+    sender: Presence;
+    reliable?: boolean;
+  }
+
+  interface MatchDispatcher {
+    broadcastMessage(
+      opCode: number,
+      data?: string | Uint8Array | null,
+      presences?: Presence[] | null,
+      sender?: Presence | null,
+      reliable?: boolean,
+    ): void;
+    matchKick?(presences: Presence[]): void;
+    matchLabelUpdate?(label: string): void;
+  }
+
+  interface MatchState {
+    [key: string]: unknown;
+  }
+
+  interface MatchHandler<T = MatchState> {
+    matchInit(
+      ctx: Context,
+      logger: Logger,
+      nk: Nakama,
+      params: { [key: string]: string },
+    ): { state: T; tickRate: number; label: string };
+
+    matchJoinAttempt(
+      ctx: Context,
+      logger: Logger,
+      nk: Nakama,
+      dispatcher: MatchDispatcher,
+      tick: number,
+      state: T,
+      presence: Presence,
+      metadata: { [key: string]: unknown },
+    ): { state: T; accept: boolean; rejectMessage?: string } | null;
+
+    matchJoin(
+      ctx: Context,
+      logger: Logger,
+      nk: Nakama,
+      dispatcher: MatchDispatcher,
+      tick: number,
+      state: T,
+      presences: Presence[],
+    ): { state: T } | null;
+
+    matchLeave(
+      ctx: Context,
+      logger: Logger,
+      nk: Nakama,
+      dispatcher: MatchDispatcher,
+      tick: number,
+      state: T,
+      presences: Presence[],
+    ): { state: T } | null;
+
+    matchLoop(
+      ctx: Context,
+      logger: Logger,
+      nk: Nakama,
+      dispatcher: MatchDispatcher,
+      tick: number,
+      state: T,
+      messages: MatchData[],
+    ): { state: T } | null;
+
+    matchSignal(
+      ctx: Context,
+      logger: Logger,
+      nk: Nakama,
+      dispatcher: MatchDispatcher,
+      tick: number,
+      state: T,
+      data: string,
+    ): { state: T; data?: string } | null;
+
+    matchTerminate(
+      ctx: Context,
+      logger: Logger,
+      nk: Nakama,
+      dispatcher: MatchDispatcher,
+      tick: number,
+      state: T,
+      graceSeconds: number,
+    ): { state: T } | null;
+  }
+
+  type RpcFunction = (
+    ctx: Context,
+    logger: Logger,
+    nk: Nakama,
+    payload: string,
+  ) => string | void;
+
+  interface Initializer {
+    registerMatch(name: string, handler: MatchHandler): void;
+    registerRpc(id: string, fn: RpcFunction): void;
+  }
+
+  interface Nakama {
+    matchCreate(module: string, params?: { [key: string]: string }): string;
+    matchGet?(matchId: string): unknown;
+    [key: string]: unknown;
+  }
+}
+
+declare module '__game__' {
+  const plugin: import('@table-games-engine/core').GamePlugin;
+  export default plugin;
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@table-games-engine/game-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "publishConfig": { "access": "public" },
+  "description": "Build, check, simulate and preview store games on table-games-engine.",
+  "type": "module",
+  "bin": { "game-kit": "dist/cli.js" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./bridge": { "types": "./dist/bridge.d.ts", "default": "./dist/bridge.js" }
+  },
+  "files": ["dist", "schema", "template", "nakama", "host", "skill"],
+  "scripts": {
+    "build": "esbuild src/index.ts src/bridge.ts --bundle --format=esm --platform=node --packages=external --outdir=dist && esbuild src/cli.ts --bundle --format=esm --platform=node --packages=external --outfile=dist/cli.js --banner:js='#!/usr/bin/env node' && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@heroiclabs/nakama-js": "^2.7.0",
+    "@table-games-engine/core": "^0.1.0",
+    "@table-games-engine/nakama-adapter": "^0.1.0",
+    "@table-games-engine/persistence": "^0.1.0",
+    "ajv": "^8.17.0",
+    "esbuild": "^0.24.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.19.0",
+    "typescript-eslint": "^8.0.0",
+    "vite": "^5.4.0"
+  },
+  "devDependencies": { "typescript": "^5.4.0", "vitest": "^2.0.0" }
+}

package/schema/game.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/Dmitry-Kucher/table-games-engine/game.schema.json",
+  "title": "Store game metadata (game.json)",
+  "type": "object",
+  "definitions": {
+    "localized": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "object", "minProperties": 1, "additionalProperties": { "type": "string", "minLength": 1 } }
+      ]
+    }
+  },
+  "required": ["slug", "name", "version", "engine", "players", "locales", "description", "rules", "authors", "listed", "client"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "slug": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" },
+    "name": { "$ref": "#/definitions/localized" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "engine": { "type": "string", "minLength": 1 },
+    "players": {
+      "type": "object", "required": ["min", "max"], "additionalProperties": false,
+      "properties": { "min": { "type": "integer", "minimum": 2 }, "max": { "type": "integer", "minimum": 2 } }
+    },
+    "locales": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" } },
+    "description": { "$ref": "#/definitions/localized" },
+    "rules": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "string", "pattern": "\\.md$" } },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "cover": { "type": "string" },
+    "authors": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "credits": { "type": "string" },
+    "listed": { "type": "boolean" },
+    "client": {
+      "type": "object", "required": ["kind", "entry"], "additionalProperties": false,
+      "properties": { "kind": { "enum": ["iframe"] }, "entry": { "type": "string", "minLength": 1 } }
+    },
+    "presets": {
+      "type": "array", "minItems": 1,
+      "items": {
+        "type": "object", "required": ["id", "name", "config"], "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+          "name": { "$ref": "#/definitions/localized" },
+          "config": { "type": "object" }
+        }
+      }
+    },
+    "simulation": {
+      "type": "object", "additionalProperties": false,
+      "properties": { "maxSteps": { "type": "integer", "minimum": 1 } }
+    }
+  }
+}

package/skill/create-store-game.md

@@ -0,0 +1,135 @@
+# Skill: create-store-game
+
+Build a store game on table-games-engine in a standalone package created by
+`game-kit create`. You are done when `npx game-kit check` exits 0 and prints `check: OK`.
+Do not edit anything under `node_modules/`.
+
+> **Unpublished packages:** until `@table-games-engine/*` is on npm, you need the five
+> local tarballs (`core`, `persistence`, `nakama-adapter`, `client-sdk`, `game-kit`). Then:
+> ```sh
+> mkdir installer && (cd installer && npm init -y && npm install /path/to/tarballs/*.tgz)
+> npx --prefix ./installer game-kit create <slug> --no-install
+> cd <slug> && npm install /path/to/tarballs/*.tgz
+> ```
+> (`npx --package=<game-kit tgz>` alone fails: it cannot resolve the sibling packages.)
+> Once published, plain `npx @table-games-engine/game-kit create <slug>` installs for you.
+
+## Inputs (ask the user if missing)
+
+1. Rules text for every locale the game ships (`rules.md`, `rules.<locale>.md`).
+2. Locales (first = default) and presets (match configurations, first = default).
+3. Player count.
+
+## What `game-kit create` gives you
+
+```
+game.json  rules.md  AGENTS.md  package.json  tsconfig.json
+logic/index.ts        a working 2-player "Fire Bolt" duel: replace it
+tests/game.test.ts    drives a full match: copy its pattern
+client/index.html, client/main.ts   bridge client: replace it
+```
+
+Read `logic/index.ts` and `tests/game.test.ts` first; they are the reference for everything below.
+
+## The contract you implement
+
+`logic/index.ts` does `export default plugin`, where `plugin` is a `GamePlugin`
+from `@table-games-engine/core` with:
+
+| Field | What it must do |
+|---|---|
+| `id`, `version`, `requiredMechanics: []` | As in the template. |
+| `manifest` | Phases and actions. Keep one phase with `exitCondition: 'manual'` unless the game really has phases. Every action id a player can take must be in that phase's `legalActions`, and defined in `actions.actions` with `usesStack: true`, `effects: []`. Copy the template's manifest shape. |
+| `setup(ctx, config, seats)` | Return `ok({ state })`. `ctx.state` is already a valid empty state with the seats in turn order and the first seat holding priority: spread it and set `players` and `shared`. `config` is the chosen preset's `config` (`{}` with no presets); only `config` reaches `setup`, never the preset's `id`, so put everything the logic needs (board size, variant flags) into `config`. |
+| `actionHandlers` | `{ [actionTypeId]: (ctx, frame) => ... }`. Pure: read `ctx.state` and `frame.payload`, return `resolved(mutations)` (or `resolved(mutations, events)`), both helpers imported from `@table-games-engine/core`; no `as never` casts needed. The acting player is `'actor' in frame ? frame.actor : frame.controller`. **To end the turn, include `{ domain: 'turn', operation: { type: 'advance' } }` in `mutations`**: the engine then gives priority to the next player. If the same player moves again (bonus move), do not emit it. **To reject an illegal move, `return reject('rule-violation')`** (i.e. `{ success: false, failureReason: 'rule-violation', mutations: [], events: [], newFrames: [], firedTriggers: [] }`; other reasons: `'condition-failed'`, `'targets-illegal'`): the server rejects the input (`driveAction` returns `ok: false` with code `CONDITION_NOT_MET`, the player gets a `rejected` notice) and nothing changes, even if you returned mutations. |
+| `winConditionChecker(ctx)` | `{ gameOver: false }` or `{ gameOver: true, winners: [...playerIds], reason }`. A draw is `winners: []`. Every game must end: add a turn limit if the rules have none. (The engine also ends the match when at most one non-eliminated player remains.) |
+| `legalMoves(state, playerId)` | **Every** concrete move this player may submit now, each `{ playerId, type: 'action', data: { type: 'action', actionTypeId, targets: {}, payload } }` (type `LegalMove`). Return `[]` when `state.result` is set or `state.priority.holder !== playerId`. Never return `[]` for the holder of an unfinished game. |
+
+Store game data in `state.shared` (JSON only: no class instances, `Map`, `Set`,
+`undefined`). Update it with `{ domain: 'shared', operation: { type: 'merge', updates } }`
+(shallow merge of top-level keys) or `{ domain: 'shared', operation: { type: 'set', path, value } }` (`path` is the literal top-level key `shared[path]`, not a nested path).
+Other useful mutations: `{ domain: 'player', operation: { type: 'add-resource', playerId, resource, delta } }`,
+`{ domain: 'turn', operation: { type: 'eliminate-player', playerId } }`.
+
+### Randomness
+
+`ctx.random()`, `ctx.randomInt(min, max)`, `ctx.randomPick(arr)`, `ctx.randomShuffle(arr)` return
+`{ value, newRngState, consumed }` and do **not** change state by themselves. Every call within one
+handler reads the same RNG state, so do **one draw per handler** (use `randomShuffle` for many items)
+and persist it by emitting `{ domain: 'rng', operation: { type: 'set-state', state: result.newRngState } }`.
+Otherwise the next action draws the same number.
+
+### Logic rules (`game-kit check` lint stage enforces them; all files under `logic/`)
+
+- Import only `@table-games-engine/core` and relative files.
+- No `Math.random`, `Date`, `process`, `window`, `globalThis`, `setTimeout`, `setInterval`, `fetch`, `require`, dynamic `import()`.
+- No module-level `let`/`var`: modules are shared by every match on the server (`const` is fine).
+- Never mutate `ctx.state`; return mutations.
+
+## The client
+
+`client/` is a vite app (`client/index.html` -> `client/main.ts`) shown to each player in a sandboxed
+iframe **with no network access** (no fetch, no CDN, no remote fonts or images: bundle everything).
+It talks to the store only through the bridge:
+
+```ts
+import { connectBridge, type StatePayload } from '@table-games-engine/game-kit/bridge';
+const bridge = connectBridge(
+  (s: StatePayload) => render(s),   // s.view (this player's view; s.view.viewerId is you), s.seat, s.legalMoves, s.status ('active'|'finished'), s.result
+  (kind) => showNotice(kind),       // 'rejected' | 'reconnecting' | 'server-restart' | 'opponent-left'
+);
+// on a click: bridge.send(oneOf_s.legalMoves)
+```
+
+- Only send moves taken from the latest `s.legalMoves`; anything else is rejected (you get a `rejected` notice).
+- Build the UI from `s.legalMoves`: they are exactly what is clickable now. `s.legalMoves` is empty when it is not your turn.
+- Read the locale from `new URLSearchParams(location.search).get('locale')`, fall back
+  to the first locale in `game.json`, and ship UI strings for every listed locale.
+- Must work on a phone-width screen (>= 360 px).
+
+## game.json
+
+Edit the template's file; keep every field the schema requires (`slug`, `name`, `version`, `engine`, `players`, `locales`, `description`, `rules`, `authors`, `listed`, `client`) and add no unknown fields. `locales` (first = default); `name` / `description` either a string or
+`{ "<locale>": "..." }` covering every locale; `rules` = `{ "<locale>": "<file>.md" }` with every file present;
+`presets` = `[{ "id": "small", "name": "..." or { ... }, "config": { ... } }]` (first = default, unique ids; `config`
+is passed to `setup`); `players` `{min,max}`; `credits` with the original author and licence when adapting an
+existing game; `client` stays `{ "kind": "iframe", "entry": "client/dist/index.html" }`;
+`simulation.maxSteps` (default 2000) high enough for the longest legal game (one step = one move).
+`players.min` is at least 2. `simulate` and `check` play every player count from `players.min` to `players.max`.
+
+## Procedure
+
+1. Read `rules.md` (and translations) completely. List every rule, then every
+   ambiguity; decide each one and write the decision into the rules files.
+2. Write `logic/` (split board geometry / move generation / handlers into
+   files). Write `legalMoves` from the same helpers the handler validates with,
+   so they cannot disagree.
+3. Write `tests/` (vitest): at least one scripted full match ending in a result, plus a
+   test per tricky rule. Drive moves with `setupMatch` + `driveAction` exactly
+   like `tests/game.test.ts` in the template. Read a move's fields with its typed
+   helper `actionOf(m)` (`m.data.type === 'action' ? m.data : null`, then
+   `actionOf(m)?.actionTypeId`, `actionOf(m)?.payload['x']`) instead of casting `m.data`.
+   A rejected move is `expect(r.ok).toBe(false)`.
+4. Run `npx game-kit test`, then `npx game-kit simulate -n 200` (flags: `-n` matches per preset and
+   player count, default 1000; `--seed` default 1; `--preset <id>`; `--players <n>` one count instead of
+   every count in `players`). On a failure
+   it prints `FAIL preset=… players=… seed=… step=…: <reason>`, a `replay:` line and the last moves; replay one match with
+   `npx game-kit simulate --preset <id> --players <n> --seed <seed> -n 1` and fix the logic.
+5. Write the client. If Docker is available run `npx game-kit preview --preset <id> --locale <l>`
+   and play both seats.
+6. Run `npx game-kit check` (game.json, lint, typecheck, tests, simulate with 1000 matches per preset and player count, client build)
+   until it prints `check: OK`. On failure it prints `check: FAILED at <stage>` and the details.
+
+## Common failures
+
+| Symptom from `simulate` | Cause |
+|---|---|
+| `no result after maxSteps=N` | The game can loop forever (also: a handler that forgets the turn `advance` lets the same player act forever): add a turn limit/draw rule and make every handler end the turn, or raise `simulation.maxSteps` if games are legitimately long. |
+| `legalMoves is empty for pX, who must act` | `legalMoves` returned `[]` for the priority holder of an unfinished game: no moves left and no win/draw ended the match, or a wrong holder/`state.result` check inside `legalMoves`. |
+| `legalMoves offered a move the engine rejected (NOT_PRIORITY_HOLDER …)` | A move returned by `legalMoves` carries a `playerId` other than the priority holder. |
+| `… (CONDITION_NOT_MET: <reason>)` | Your handler returned `reject(...)` / `success: false` for a move `legalMoves` offered: the two disagree. Build both from the same helper. |
+| `… (INVALID_ACTION_TYPE …)` | The action id is missing from the manifest's `actions.actions`. |
+| `… (ILLEGAL_IN_WINDOW: <id> not legal in current window)` | The action id is not in the current phase's `legalActions` (or its speed does not fit the window). |
+| `non-deterministic: replaying the same seed produced a different final state` | Module-level state, iteration over something unordered, or randomness outside `ctx`. |
+| `setup threw: …` / `legalMoves threw: …` / `game logic threw: …` | Exception in your code; fix it. |
+| `legalMoves returned N moves (> 5000)` (warning) | Too many concrete moves; the UI and bots get slow. Consider splitting the move into steps. |

package/template/AGENTS.md

@@ -0,0 +1,6 @@
+# Agent instructions
+
+This is a store game for table-games-engine. Follow the skill at
+`node_modules/@table-games-engine/game-kit/skill/create-store-game.md`
+step by step. You are done when `npx game-kit check` exits 0.
+Do not edit anything under `node_modules/`.

package/template/client/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Game</title>
+    <style>
+      body { font-family: system-ui, sans-serif; margin: 16px; }
+      .row { display: flex; justify-content: space-between; max-width: 320px; }
+      button { margin-top: 12px; padding: 8px 16px; }
+    </style>
+  </head>
+  <body>
+    <main id="app"></main>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>