@xavatech/create-xara-game 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @xavatech/create-xara-game
 
-Starts a game for Xara chats: a working starter built with [`@xavatech/xara-game-sdk`](https://www.npmjs.com/package/@xavatech/xara-game-sdk), with tests, and with the [game skill](https://docs.usexara.ai/games/skill) installed, so a coding assistant can turn your description into the real game.
+Starts a game for Xara chats: an empty page built with [`@xavatech/xara-game-sdk`](https://www.npmjs.com/package/@xavatech/xara-game-sdk), and with the [game skill](https://docs.usexara.ai/games/skill) installed, so a coding assistant can turn your description into the real game. Outside the app, a bar switches which player's phone the page is.
 
 ```bash
 npx @xavatech/create-xara-game word-chain --name "Word Chain" --players 2-4
@@ -13,19 +13,17 @@ npm run dev
 | `--name` | The game's name, as players see it. Defaults to the folder's name. |
 | `--description` | One line about the game. |
 | `--players` | `2`, or a range like `2-4`. Defaults to `2`. |
-| `--xara-games <dir>` | For Xara's own games. Also adds the game to that [xara-games](https://github.com/xavatech/xara-games) checkout. |
-
-The starter is a placeholder game: add 1, 2, or 3, and whoever makes the total 10 wins.
+| `--xara-games <dir>` | For Xara's own games. Creates the game inside that [xara-games](https://github.com/xavatech/xara-games) checkout instead of the current folder. |
 
 ## Xara's own games
 
 Name the folder `xara-<game>` and pass `--xara-games`:
 
 ```bash
-npx @xavatech/create-xara-game xara-word-chain --name "Word Chain" --players 2-4 --xara-games ./xara-games
+npx @xavatech/create-xara-game xara-word-chain --name "Word Chain" --players 2-4 --xara-games path/to/xara-games
 ```
 
-This also adds the game as the submodule `games/word-chain` (pointing at `github.com/xavatech/xara-word-chain`), adds it to `games.json`, and builds it into `site/word-chain/`. With the site served at `GAMES_URL`, run the backend's `Game` seeder to list it. Then push the game's repo.
+Run it from any folder, including inside `xara-games` with `--xara-games .`. The game is created at `games/word-chain` in that checkout and registered there as a submodule whose remote is `github.com/xavatech/xara-word-chain`. Nothing is created in the folder you run it from. It is added to `games.json` and built into `site/word-chain/`. With the site served at `GAMES_URL`, run the backend's `Game` seeder to list it. Then create the GitHub repo and push.
 
 ## Change the starter
 

package/index.mjs

@@ -12,7 +12,7 @@ const USAGE = `Start a game for Xara chats.
   --name <name>                The game's name, as players see it. Defaults to the folder's name.
   --description <description>  One line about the game.
   --players <players>          How many play: 2, or a range like 2-4. Defaults to 2.
-  --xara-games <dir>           For Xara's own games: also add it to that xara-games checkout.`;
+  --xara-games <dir>           For Xara's own games: create it in that xara-games checkout, at games/<game>.`;
 
 const fail = (message) => {
   console.error(`\n${message}\n`);
@@ -34,13 +34,15 @@ if (values.help || !positionals[0]) {
   process.exit(values.help ? 0 : 1);
 }
 
-const dir = resolve(positionals[0]);
-const folder = basename(dir);
+const folder = basename(positionals[0]);
 if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(folder)) fail("Name the folder like word-chain: lowercase letters, numbers, and dashes.");
-if (existsSync(dir)) fail(`${dir} already exists.`);
 
-// Xara's own repos are named xara-<game>; the game is served at /<game>/.
+// Xara's own repos are named xara-<game>; the game lives in xara-games at games/<game> and is served at /<game>/.
 const path = folder.replace(/^xara-/, "");
+const gamesDir = values["xara-games"] && resolve(values["xara-games"]);
+const dir = gamesDir ? join(gamesDir, "games", path) : resolve(positionals[0]);
+const repoUrl = `https://github.com/xavatech/${folder}.git`;
+if (existsSync(dir)) fail(`${dir} already exists.`);
 const name = values.name?.trim() || path.split("-").map((word) => word[0].toUpperCase() + word.slice(1)).join(" ");
 const description = values.description?.trim() ?? "";
 const [minPlayers, maxPlayers = minPlayers] = values.players.split("-").map(Number);
@@ -48,7 +50,6 @@ if (![minPlayers, maxPlayers].every(Number.isInteger) || minPlayers < 2 || maxPl
   fail("--players is from 2 to 8, like 2 or 2-4.");
 }
 
-const gamesDir = values["xara-games"] && resolve(values["xara-games"]);
 const listFile = gamesDir && join(gamesDir, "games.json");
 const list = listFile && (existsSync(listFile) ? JSON.parse(readFileSync(listFile, "utf8")) : fail(`${listFile} was not found.`));
 if (list?.some((game) => game.path === path || game.name === name)) fail(`${path} or "${name}" is already in games.json.`);
@@ -75,8 +76,9 @@ run("npm install --no-fund --no-audit", dir);
 run(`git init -q -b main && git add -A && git commit -q -m "${name.replace(/"/g, "")} for Xara chats"`, dir);
 
 if (gamesDir) {
-  run(`git -c protocol.file.allow=always submodule add -q "${dir}" games/${path}`, gamesDir);
-  run(`git config -f .gitmodules submodule.games/${path}.url https://github.com/xavatech/${folder}.git`, gamesDir);
+  // The game is already at games/<game>, so this registers that repo in place instead of cloning it.
+  run(`git remote add origin ${repoUrl}`, dir);
+  run(`git submodule add -q ${repoUrl} games/${path}`, gamesDir);
   writeFileSync(listFile, `${JSON.stringify([...list, { path, name, description, minPlayers, maxPlayers }], null, 2)}\n`);
   run(`node build.mjs ${path}`, gamesDir);
   run("git add -A", gamesDir);
@@ -85,7 +87,7 @@ if (gamesDir) {
 console.log(`
 ${name} is ready.
 
-  cd ${positionals[0]}
+  cd ${dir}
   npm run dev        Play it in a browser; every player shares the screen.
 
 Then describe the real game to your coding assistant in that folder.`);
@@ -96,7 +98,7 @@ It is in xara-games at games/${path}, and built into site/${path}/.
 
   List it:  bun run avanda.ts app seed -t Game     (in xara_backend, with xara-games served at GAMES_URL)
   Push it:  create github.com/xavatech/${folder}, then
-            cd ${dir} && git remote add origin https://github.com/xavatech/${folder}.git && git push -u origin main
+            cd ${dir} && git push -u origin main
             cd ${gamesDir} && git commit -m "Add ${name}"`);
 } else {
   console.log(`To ship it, see README.md.`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xavatech/create-xara-game",
-  "version": "1.0.0",
-  "description": "Start a game for Xara chats: a working starter with the Xara game SDK and the coding-assistant skill.",
+  "version": "1.0.2",
+  "description": "Start a game for Xara chats: an empty page with the Xara game SDK and the coding-assistant skill.",
   "type": "module",
   "bin": {
     "create-xara-game": "index.mjs"

package/template/.cursor/skills/build-xara-game/SKILL.md

@@ -55,7 +55,7 @@ No other origins, no CDN fonts, no iframes.
 ```ts
 import { connect, inXara, mockApp } from "@xavatech/xara-game-sdk";
 
-if (import.meta.env.DEV && !inXara()) {
+if (!inXara()) {
   mockApp({
     players: [
       { id: 1, name: "Ada" },
@@ -71,7 +71,7 @@ xara.onChange(draw);
 draw(await xara.load());
 ```
 
-`mockApp` is for the browser during development. It is not part of the build the app opens.
+`mockApp` runs only outside the app. It adds a bar that switches which player's phone the page is, and a move only goes through on that player's turn. Inside the app it never runs.
 
 ## Draw and play
 
@@ -130,6 +130,6 @@ Use the names above. These older names are not the SDK: `ready`, `onState`, `vie
 
 ## What to tell the user
 
-The built `dist/` is a static site. It has to be served over https on one origin. They submit that URL in the Xara business dashboard with the player counts and SDK version `2.0.0`. The game stays in review until an admin approves it. Changing the URL or the player counts after approval sends it back to review. Changing the name, description, or icon does not.
+The built `dist/` is a static site. It has to be served over https on one origin. They submit that URL in the Xara business dashboard with the player counts and SDK version `2.1.0`. The game stays in review until an admin approves it. Changing the URL or the player counts after approval sends it back to review. Changing the name, description, or icon does not.
 
 Do not submit, host, or publish the package unless the user asks.

package/template/README.md

@@ -2,20 +2,20 @@
 
 __DESCRIPTION__
 
-A game people start from a Xara chat, built with [`@xavatech/xara-game-sdk`](https://www.npmjs.com/package/@xavatech/xara-game-sdk). It starts as a placeholder: add 1, 2, or 3, and whoever makes the total 10 wins. Describe the real game to your coding assistant. The skill in `.cursor/skills/build-xara-game` tells it how.
+A game people start from a Xara chat, built with [`@xavatech/xara-game-sdk`](https://www.npmjs.com/package/@xavatech/xara-game-sdk). The page starts empty. Outside the Xara app, a bar at the bottom switches which player's phone it is. Describe the real game to your coding assistant. The skill in `.cursor/skills/build-xara-game` tells it how.
 
 ## Run it
 
 ```bash
-npm run dev     # http://localhost:5173, with a mock app: every player shares the screen
-npm test        # the rules
+npm run dev     # http://localhost:5173
+npm test
 npm run build   # static files in dist/
 ```
 
 ## Ship it
 
 1. Serve `dist/` over **https**. Xara only opens https games, and only answers SDK calls from that URL's origin.
-2. In the Xara business dashboard, open **Games → Submit a game** with the URL, __PLAYERS__ players, and SDK version `2.0.0`.
+2. In the Xara business dashboard, open **Games → Submit a game** with the URL, __PLAYERS__ players, and SDK version `2.1.0`.
 3. Once an admin approves it, people find it under **+ → Game** in their chats.
 
 See [Games overview](https://docs.usexara.ai/games/overview).

package/template/index.html

@@ -7,16 +7,7 @@
     <title>__NAME__</title>
   </head>
   <body>
-    <main>
-      <ol id="players" class="players" aria-label="Players"></ol>
-      <p id="status" class="status" aria-live="polite">Loading…</p>
-      <p id="total" class="total" aria-label="Total">0</p>
-      <div id="pad" class="pad" role="group" aria-label="Add to the total"></div>
-      <div class="actions">
-        <button id="accept" class="action" tabindex="-1">Accept and play</button>
-      </div>
-      <p id="note" class="note" role="alert"></p>
-    </main>
+    <p id="status" class="status" role="alert"></p>
     <script type="module" src="./src/main.ts"></script>
   </body>
 </html>

package/template/package.json

@@ -11,7 +11,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@xavatech/xara-game-sdk": "^2.0.0"
+    "@xavatech/xara-game-sdk": "^2.1.0"
   },
   "devDependencies": {
     "typescript": "^5.7.2",

package/template/src/main.ts

@@ -1,9 +1,8 @@
 import "./style.css";
-import { connect, inXara, mockApp, XaraGameError, type GameState } from "@xavatech/xara-game-sdk";
-import { STEPS, TARGET, canAdd, isWon, totalOf, type Move } from "./rules";
+import { connect, inXara, mockApp, XaraGameError } from "@xavatech/xara-game-sdk";
 
-// In `npm run dev` outside the app, a mock app lets every player take turns on one screen.
-if (import.meta.env.DEV && !inXara()) {
+// Outside the app, a bar switches which player's phone this page is.
+if (!inXara()) {
   mockApp({
     game: { id: 1, name: "__NAME__" },
     players: [
@@ -14,103 +13,13 @@ if (import.meta.env.DEV && !inXara()) {
   });
 }
 
-type State = GameState<Move>;
-
-const xara = connect<Move>();
-const playersEl = document.getElementById("players")!;
+const xara = connect();
 const statusEl = document.getElementById("status")!;
-const totalEl = document.getElementById("total")!;
-const padEl = document.getElementById("pad")!;
-const acceptEl = document.getElementById("accept") as HTMLButtonElement;
-const noteEl = document.getElementById("note")!;
 
-const keys = STEPS.map((add) => {
-  const button = document.createElement("button");
-  button.className = "key";
-  button.textContent = `+${add}`;
-  button.disabled = true;
-  button.addEventListener("click", () => play(add));
-  padEl.append(button);
-  return button;
+xara.onChange(() => {
+  statusEl.textContent = "";
 });
 
-let busy = false;
-
-const nameOf = (state: State, playerId: number | null) =>
-  state.players.find((player) => player.id === playerId)?.name ?? "Someone";
-
-function statusText(state: State): string {
-  const { session, me } = state;
-  switch (session.status) {
-    case "invited":
-      return state.players.find((player) => player.you)?.status === "invited"
-        ? "You've been invited to play"
-        : "Waiting for everyone to accept";
-    case "active":
-      return xara.isMyTurn() ? "Your turn" : `${nameOf(state, session.turn)}'s turn`;
-    case "completed": {
-      const outcome = session.outcome!;
-      if (outcome.leftBy) return `${nameOf(state, outcome.leftBy)} left the game`;
-      if (!outcome.winners.length) return "It's a draw";
-      return outcome.winners.includes(me.id) ? "You won!" : `${nameOf(state, outcome.winners[0])} won`;
-    }
-    case "declined":
-      return "The invite was declined";
-    default:
-      return "This game was called off";
-  }
-}
-
-function render(state: State) {
-  const total = totalOf(state.moves);
-  const playable = xara.isMyTurn() && !busy;
-
-  playersEl.replaceChildren(
-    ...state.players.map((player) => {
-      const item = document.createElement("li");
-      item.textContent = player.name;
-      item.classList.toggle("turn", state.session.status === "active" && player.id === state.session.turn);
-      return item;
-    })
-  );
-  statusEl.textContent = statusText(state);
-  totalEl.textContent = `${total} / ${TARGET}`;
-  keys.forEach((button, i) => (button.disabled = !playable || !canAdd(total, STEPS[i])));
-
-  const invited = state.session.status === "invited" && state.players.find((player) => player.you)?.status === "invited";
-  acceptEl.classList.toggle("shown", invited && !busy);
-  acceptEl.disabled = !invited || busy;
-}
-
-async function run(action: () => Promise<unknown>) {
-  busy = true;
-  noteEl.textContent = "";
-  if (xara.state) render(xara.state);
-  try {
-    await action();
-  } catch (error) {
-    noteEl.textContent = error instanceof XaraGameError ? error.message : "Something went wrong";
-  } finally {
-    busy = false;
-    if (xara.state) render(xara.state);
-  }
-}
-
-function play(add: number) {
-  const state = xara.state;
-  if (!state || !xara.isMyTurn() || busy) return;
-  const total = totalOf(state.moves);
-  if (!canAdd(total, add)) return;
-  // Every player reads the same summary, so it can't say "you".
-  const outcome = isWon(total + add)
-    ? { winners: [state.me.id], summary: `${nameOf(state, state.me.id)} reached ${TARGET}` }
-    : undefined;
-  return run(() => xara.move({ add }, { outcome }));
-}
-
-acceptEl.addEventListener("click", () => run(() => xara.accept()));
-
-xara.onChange(render);
 xara.load().catch((error) => {
   statusEl.textContent = error instanceof XaraGameError ? error.message : "Couldn't start the game";
 });

package/template/src/style.css

@@ -1,134 +1,18 @@
 :root {
-  --blue: #1e5eff;
-  --blue-soft: #e8efff;
-  --ink: #102a24;
-  --muted: #607080;
-  font-family: system-ui, -apple-system, sans-serif;
-  color: var(--ink);
+  color: #102a24;
   background: #f4f8ff;
-  -webkit-tap-highlight-color: transparent;
-}
-
-* {
-  box-sizing: border-box;
+  font-family: system-ui, sans-serif;
 }
 
 html,
 body {
   margin: 0;
   height: 100%;
-  overscroll-behavior: none;
-  user-select: none;
-  -webkit-user-select: none;
-}
-
-/* Every row has a fixed height, so a new state never moves the page. */
-main {
-  min-height: 100dvh;
-  max-width: 420px;
-  margin: 0 auto;
-  padding: max(24px, env(safe-area-inset-top)) 20px max(24px, env(safe-area-inset-bottom));
-  display: grid;
-  grid-template-rows: 40px 28px 96px 64px 52px 20px;
-  align-content: center;
-  row-gap: 20px;
-}
-
-.players {
-  margin: 0;
-  padding: 0;
-  list-style: none;
-  display: flex;
-  justify-content: center;
-  gap: 8px;
-  overflow: hidden;
-}
-
-.players li {
-  padding: 8px 12px;
-  border-radius: 14px;
-  background: #fff;
-  border: 1.5px solid transparent;
-  font-size: 14px;
-  font-weight: 600;
-  white-space: nowrap;
-}
-
-.players li.turn {
-  border-color: var(--blue);
-}
-
-.status,
-.note {
-  margin: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  text-align: center;
 }
 
 .status {
-  line-height: 28px;
-  font-size: 18px;
-  font-weight: 700;
-}
-
-.total {
   margin: 0;
-  display: grid;
-  place-items: center;
-  border-radius: 24px;
-  background: #fff;
-  font-size: 40px;
-  font-weight: 800;
-  font-variant-numeric: tabular-nums;
-}
-
-.pad {
-  display: grid;
-  grid-template-columns: repeat(3, 1fr);
-  gap: 10px;
-}
-
-.key {
-  border: 0;
-  border-radius: 18px;
-  background: var(--blue);
-  color: #fff;
-  font: inherit;
-  font-size: 22px;
-  font-weight: 800;
-  touch-action: manipulation;
-}
-
-.key:disabled {
-  background: var(--blue-soft);
-  color: var(--muted);
-}
-
-.actions {
-  display: grid;
-  place-items: center;
-}
-
-.action {
-  height: 48px;
-  padding: 0 24px;
-  border: 0;
-  border-radius: 999px;
-  background: var(--blue);
-  color: #fff;
-  font: inherit;
-  font-size: 15px;
-  font-weight: 700;
-  visibility: hidden;
-}
-
-.action.shown {
-  visibility: visible;
-}
-
-.note {
-  font-size: 13px;
-  color: #c0392b;
+  padding: 24px;
+  text-align: center;
+  font-size: 14px;
 }

package/template/vite.config.ts

@@ -4,4 +4,5 @@ import { defineConfig } from "vite";
 export default defineConfig({
   base: "./",
   build: { outDir: "dist", emptyOutDir: true },
+  test: { passWithNoTests: true },
 });

package/template/src/rules.test.ts

@@ -1,22 +0,0 @@
-import { describe, expect, test } from "vitest";
-import type { PlayedMove } from "@xavatech/xara-game-sdk";
-import { canAdd, isWon, totalOf, type Move } from "./rules";
-
-const moves = (adds: number[]): PlayedMove<Move>[] =>
-  adds.map((add, i) => ({ step: i + 1, playerId: (i % 2) + 1, move: { add }, at: "" }));
-
-describe("rules", () => {
-  test("adds up every move, as after a reload", () => {
-    expect(totalOf(moves([3, 2, 1]))).toBe(6);
-  });
-
-  test("skips moves that break the rules", () => {
-    expect(totalOf(moves([3, 5, 3, 3, 3]))).toBe(9);
-    expect(canAdd(9, 2)).toBe(false);
-  });
-
-  test("making the total 10 wins", () => {
-    expect(isWon(totalOf(moves([3, 3, 3, 1])))).toBe(true);
-    expect(isWon(9)).toBe(false);
-  });
-});

package/template/src/rules.ts

@@ -1,20 +0,0 @@
-import type { PlayedMove } from "@xavatech/xara-game-sdk";
-
-/** A starter game: take turns adding 1, 2, or 3. Whoever makes the total 10 wins. Replace it with yours. */
-export const TARGET = 10;
-export const STEPS = [1, 2, 3] as const;
-
-export type Move = { add: number };
-
-/** The total after every move so far. Moves that don't follow the rules are skipped, on every phone alike. */
-export function totalOf(moves: PlayedMove<Move>[]): number {
-  return moves.reduce((total, played) => (canAdd(total, played.move.add) ? total + played.move.add : total), 0);
-}
-
-export function canAdd(total: number, add: number): boolean {
-  return (STEPS as readonly number[]).includes(add) && total + add <= TARGET;
-}
-
-export function isWon(total: number): boolean {
-  return total === TARGET;
-}