@adobe/data 0.9.39 → 0.9.41

package/AGENTS.md

@@ -2,6 +2,16 @@
 
 Adobe data-oriented programming library. Use this file when editing code in this package or when consuming `@adobe/data` in an application.
 
+## References
+
+Source for peer packages and sample apps is included under `references/` (when present). Use these as living reference code:
+
+- **references/data-lit** — Support functions for Lit based projects.
+- **references/data-lit-tictactoe** — **Exemplary types and state.** Tic-Tac-Toe sample with Lit UI. The `types/` (BoardState namespace, PlayMoveArgs, etc.) and `state/` (tictactoe-plugin, agent-plugin) are a very good reference for proper type namespaces, ECS resources, computed observables, and transactions — even for consumers not using Lit.
+- **references/data-react** — Support functions for React based projects.
+- **references/data-react-hello** — Very simple react hello world sample.
+- **references/data-react-pixie** — Simple sample for react pixie based 2d games.
+
 ## Stack
 
 - **Package manager:** pnpm
@@ -52,10 +62,52 @@ Source lives under `src/` with one main `index.ts` per area; built output is in
 
 - **Store:** low-level, synchronous, direct mutations. No transactions, no observability.
 - **Database:** wraps a Store; **transaction-based** and **observable**. All mutations go through transaction functions; undo/redo and observers are supported.
-- **Plugins:** use `Database.Plugin.create()`. Property order is **enforced at runtime:** `extends` → `services` → `components` → `resources` → `archetypes` → `computed` → `transactions` → `actions` → `systems`. Wrong order throws.
-- **Composition:** one plugin via `extends`; multiple peers via `Database.Plugin.combine(...)`.
-- **Transactions:** synchronous and deterministic. Receive `(store, payload)`. Mutate via `store.update(entity, data)`, `store.resources.x = value`, etc.
-- **Actions:** may be async; call at most one transaction per action to keep undo/redo correct. Callers should not rely on return values for UI flow (data down via Observe, actions for side effects).
+- **Plugins:** use `Database.Plugin.create()` from `@adobe/data/ecs`. Property order is **enforced at runtime**; wrong order throws.
+
+### Plugin property order (all optional)
+
+`extends` → `services` → `components` → `resources` → `archetypes` → `computed` → `transactions` → `actions` → `systems`
+
+| Property | Purpose |
+|----------|---------|
+| `extends` | Base plugin to extend (single parent only) |
+| `services` | `(db) => ServiceInstance` — singleton service factories; extended plugin services initialize first |
+| `components` | Schema object for ECS component data. Use `transient: true` for non-persistable values (DOM refs, HTML elements). |
+| `resources` | `{ default: value as Type }` — global state. Use `as Type` for compile-time type; use `null as unknown as Type` for resources initialized later in a system. |
+| `archetypes` | `['comp1', 'comp2']` — standard ECS archetypes for querying and inserting related components |
+| `computed` | `(db) => Observe<T>` — factory returning observable; receives full db |
+| `transactions` | `(store, payload) => void` — synchronous, deterministic atomic mutations |
+| `actions` | `(db, payload) => T` — general functions; may be async |
+| `systems` | `{ create: (db) => fn | void }` — per-frame (60fps) or init-only; optional `schedule: { before, after, during }` for ordering |
+
+### Composition
+
+- **Single extension:** one plugin via `extends`.
+- **Multiple peers:** use `Database.Plugin.combine(aPlugin, bPlugin, ...)` — `extends` accepts only one plugin.
+- **Type utilities:** `Database.Plugin.ToDatabase<typeof myPlugin>`, `Database.Plugin.ToStore<typeof myPlugin>`.
+
+### Transactions and Store API
+
+Transactions receive `(store, payload)`. Mutate via:
+
+- `store.update(entity, data)` — update entity components
+- `store.resources.x = value` — mutate resources
+- `store.get(entity, 'component')` — read component value
+- `store.read(entity)` — read all entity component values
+- `store.read(entity, archetype)` — read entity components in archetype
+- `store.select(archetype.components, { where })` — query entities
+
+### Actions
+
+- May be async. Call **at most one transaction per action** to keep undo/redo correct.
+- UI must **never consume return values** — call for side effects only. Data down via Observe, actions up as void.
+
+### Plugin naming
+
+- **File:** `*-plugin.ts` (kebab-case), e.g. `layout-plugin.ts`
+- **Export:** `*Plugin` (camelCase), e.g. `layoutPlugin`
+- **System:** `plugin_name__system` (snake_case, double underscore)
+- **Init system:** `plugin_name_initialize`
 
 ## Observables
 
@@ -71,21 +123,37 @@ Source lives under `src/` with one main `index.ts` per area; built output is in
 
 ## Data and schemas
 
-- **Data:** immutable, JSON-serializable values. Use `normalize()` for stable keys (e.g. cache keys).
-- **Schemas:** JSON Schema with `as const` so `FromSchema` (or equivalent) can derive TypeScript types. Use schema namespaces for component/resource definitions in ECS.
+- **Data:** immutable, JSON-serializable values.
+- **Schemas:** JSON Schema with `as const` so `FromSchema` (or equivalent) can derive TypeScript types. Use schema namespaces for component definitions in ECS if we the types are numeric and we want them stored in linear memory for performance. See Vec2, Vec3 etc. Follow those patterns for numeric values. Do not use an explicit schema for resources, just use `{ default: value as Type }` since there is only one value we don't need linear memory layout.
+
+### Data modeling example
+
+```ts
+import { Database } from '@adobe/data/ecs';
+import { F32, Vec3, Vec4 } from '@adobe/data/math';
+
+const particleDataPlugin = Database.Plugin.create({
+  components: {
+    position: Vec3.schema,
+    velocity: Vec3.schema,
+    color: Vec4.schema,
+    mass: F32.schema,
+  },
+  resources: {
+    gravity: { default: 9.8 as number },
+  },
+  archetypes: {
+    Particle: ['position', 'velocity', 'color', 'mass'],
+  },
+});
+```
+
+- **Components:** per-entity data. Use numeric schemas from `@adobe/data/math` or type namespace schemas for custom shapes.
+- **Resources:** global state. Use only `{ default: value as Type }`.
+- **Archetypes:** one per entity kind. List all components that kind requires.
 
 ## Gotchas
 
 - **Breaking changes:** Before 1.0.0, minor version bumps may include breaking API changes.
 - **ECS plugin order:** Reordering plugin properties (e.g. putting `transactions` before `components`) will throw at runtime.
 - **BlobStore / BlobRef:** Prefer BlobRef for persistence and cache keys; resolve to Blob when needed.
-
-## References
-
-Source for peer packages and sample apps is included under `references/` (when present). Use these as living reference code:
-
-- **references/data-lit** — Extra support for Lit-based projects.
-- **references/data-react** — Same but for React.
-- **references/data-lit-todo** — Sample with best practices for Lit apps.
-- **references/data-react-hello** — Minimal starting React sample.
-- **references/data-react-pixie** — Sample of using React Pixie for 2D rendering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data",
-  "version": "0.9.39",
+  "version": "0.9.41",
   "description": "Adobe data oriented programming library",
   "type": "module",
   "sideEffects": false,

package/references/data-lit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-lit",
-  "version": "0.9.39",
+  "version": "0.9.41",
   "description": "Adobe data Lit bindings - hooks, elements, decorators",
   "type": "module",
   "private": false,

package/references/data-lit-tictactoe/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "data-lit-tictactoe",
+  "version": "0.9.41",
+  "description": "Tic-Tac-Toe sample - Lit web components with @adobe/data-lit and AgenticService",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "publish-public": "true"
+  },
+  "dependencies": {
+    "@adobe/data": "workspace:*",
+    "@adobe/data-lit": "workspace:*",
+    "lit": "^3.3.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "vite": "^5.1.1",
+    "vite-plugin-checker": "^0.12.0"
+  }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-app/tictactoe-app.css.ts

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { css } from "lit";
+
+export const styles = css`
+  :host {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+  }
+`;

package/references/data-lit-tictactoe/src/elements/tictactoe-app/tictactoe-app.ts

@@ -0,0 +1,22 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement } from "lit/decorators.js";
+import { html } from "lit";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-app.css.js";
+import "../tictactoe-board/tictactoe-board.js";
+import "../tictactoe-hud/tictactoe-hud.js";
+
+export const tagName = "tictactoe-app";
+
+@customElement(tagName)
+export class TictactoeApp extends TictactoeElement {
+  static styles = styles;
+
+  render() {
+    return html`
+      <tictactoe-board></tictactoe-board>
+      <tictactoe-hud></tictactoe-hud>
+    `;
+  }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-board/tictactoe-board-presentation.ts

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { html } from "lit";
+
+export function render() {
+  return html`
+    <div class="board">
+      ${[0, 1, 2, 3, 4, 5, 6, 7, 8].map(
+        (index) => html`<tictactoe-cell .index=${index}></tictactoe-cell>`,
+      )}
+    </div>
+  `;
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-board/tictactoe-board.css.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { css } from "lit";
+
+export const styles = css`
+  :host {
+    display: block;
+  }
+
+  .board {
+    display: grid;
+    grid-template-columns: repeat(3, 100px);
+    grid-template-rows: repeat(3, 100px);
+    gap: 4px;
+    width: fit-content;
+  }
+`;

package/references/data-lit-tictactoe/src/elements/tictactoe-board/tictactoe-board.ts

@@ -0,0 +1,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement } from "lit/decorators.js";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-board.css.js";
+import * as presentation from "./tictactoe-board-presentation.js";
+import "../tictactoe-cell/tictactoe-cell.js";
+
+export const tagName = "tictactoe-board";
+
+@customElement(tagName)
+export class TictactoeBoard extends TictactoeElement {
+  static styles = styles;
+
+  render() {
+    return presentation.render();
+  }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-cell/tictactoe-cell-presentation.ts

@@ -0,0 +1,22 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { html } from "lit";
+
+export function render(args: {
+  cell: string;
+  isWinning: boolean;
+  isPlayable: boolean;
+  playMove: () => void;
+}) {
+  const { cell, isWinning, isPlayable, playMove } = args;
+  const hasMark = cell === "X" || cell === "O";
+
+  return html`
+    <div
+      class="cell ${isWinning ? "winning" : ""} ${isPlayable ? "playable" : ""}"
+      @click=${() => isPlayable && playMove()}
+    >
+      ${hasMark ? cell : ""}
+    </div>
+  `;
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-cell/tictactoe-cell.css.ts

@@ -0,0 +1,31 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { css } from "lit";
+
+export const styles = css`
+  :host {
+    display: block;
+  }
+
+  .cell {
+    width: 100px;
+    height: 100px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 48px;
+    font-weight: bold;
+    background: #1f2937;
+    border: 2px solid #6b7280;
+    color: #e5e7eb;
+    box-sizing: border-box;
+  }
+
+  .cell.playable {
+    cursor: pointer;
+  }
+
+  .cell.winning {
+    background: #2e7d32;
+  }
+`;

package/references/data-lit-tictactoe/src/elements/tictactoe-cell/tictactoe-cell.ts

@@ -0,0 +1,41 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement, property } from "lit/decorators.js";
+import { useObservableValues } from "@adobe/data-lit";
+import { BoardState } from "../../types/board-state/board-state.js";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-cell.css.js";
+import * as presentation from "./tictactoe-cell-presentation.js";
+
+export const tagName = "tictactoe-cell";
+
+@customElement(tagName)
+export class TictactoeCell extends TictactoeElement {
+  static styles = styles;
+
+  @property({ type: Number })
+  declare index: number;
+
+  render() {
+    const values = useObservableValues(
+      () => ({
+        board: this.service.observe.resources.board,
+      }),
+      [],
+    );
+
+    const board = values?.board ?? "         ";
+    const cell = BoardState.getCell(board, this.index);
+    const isWinning = BoardState.isCellWinning(board, this.index);
+    const isPlayable = BoardState.isCellPlayable(board, this.index);
+
+    return presentation.render({
+      cell,
+      isWinning,
+      isPlayable,
+      playMove: () => {
+        this.service.transactions.playMove({ index: this.index });
+      },
+    });
+  }
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-hud/tictactoe-hud-presentation.ts

@@ -0,0 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { html } from "lit";
+
+export function render(args: {
+  statusText: string;
+  restartGame: () => void;
+}) {
+  const { statusText, restartGame } = args;
+  return html`
+    <div class="hud">
+      <span>${statusText}</span>
+      <button type="button" @click=${restartGame}>Restart</button>
+    </div>
+  `;
+}

package/references/data-lit-tictactoe/src/elements/tictactoe-hud/tictactoe-hud.css.ts

@@ -0,0 +1,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { css } from "lit";
+
+export const styles = css`
+  .hud {
+    padding: 0.5rem 1rem;
+    font-family: system-ui, sans-serif;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  .hud button {
+    padding: 0.25rem 0.75rem;
+    cursor: pointer;
+  }
+`;

package/references/data-lit-tictactoe/src/elements/tictactoe-hud/tictactoe-hud.ts

@@ -0,0 +1,44 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { customElement } from "lit/decorators.js";
+import { useObservableValues } from "@adobe/data-lit";
+import { BoardState } from "../../types/board-state/board-state.js";
+import { TictactoeElement } from "../../tictactoe-element.js";
+import { styles } from "./tictactoe-hud.css.js";
+import * as presentation from "./tictactoe-hud-presentation.js";
+
+export const tagName = "tictactoe-hud";
+
+@customElement(tagName)
+export class TictactoeHud extends TictactoeElement {
+  static styles = styles;
+
+  render() {
+    const values = useObservableValues(
+      () => ({
+        board: this.service.observe.resources.board,
+        firstPlayer: this.service.observe.resources.firstPlayer,
+      }),
+      [],
+    );
+
+    const board = values?.board ?? "         ";
+    const firstPlayer = values?.firstPlayer ?? "X";
+
+    const currentPlayer = BoardState.currentPlayer(board, firstPlayer);
+    const status = BoardState.deriveStatus(board);
+    const winner = BoardState.getWinner(board);
+
+    const statusText =
+      status === "won" && winner !== null
+        ? `Winner: ${winner}`
+        : status === "draw"
+          ? "Draw"
+          : `Current Player: ${currentPlayer}`;
+
+    return presentation.render({
+      statusText,
+      restartGame: () => this.service.transactions.restartGame(),
+    });
+  }
+}

package/references/data-lit-tictactoe/src/main.ts

@@ -0,0 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import "./elements/tictactoe-app/tictactoe-app.js";
+
+const app = document.getElementById("app");
+if (app) {
+  const el = document.createElement("tictactoe-app");
+  app.appendChild(el);
+}

package/references/data-lit-tictactoe/src/state/agent-plugin.ts

@@ -0,0 +1,117 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { Observe } from "@adobe/data/observe";
+import { AgenticService } from "@adobe/data/service";
+import { BoardState } from "../types/board-state/board-state";
+import type { PlayerMark } from "../types/player-mark/player-mark";
+import { tictactoePlugin } from "./tictactoe-plugin";
+import type { TictactoeDatabase } from "./tictactoe-plugin";
+
+const roleDescription = (mark: PlayerMark): string =>
+  `You are playing as ${mark} in tic-tac-toe. Play to the best of your ability.`;
+
+const createTictactoeAgentService = (
+  db: TictactoeDatabase,
+  agentMark: PlayerMark,
+): AgenticService => {
+  const board = db.observe.resources.board;
+  const isGameOver = Observe.withFilter(board, BoardState.isGameOver);
+  const currentPlayer = Observe.withFilter(
+    board,
+    (nextBoard) =>
+      BoardState.currentPlayer(nextBoard, db.resources.firstPlayer),
+  );
+  const yourTurn = Observe.withMap(
+    Observe.fromProperties({ isGameOver, currentPlayer }),
+    ({ isGameOver: over, currentPlayer: cur }) => !over && cur === agentMark,
+  );
+
+  return AgenticService.create({
+    interface: {
+      role: {
+        type: "state",
+        schema: { type: "string" as const },
+        description: "Your role and objective",
+      },
+      board: {
+        type: "state",
+        schema: BoardState.schema,
+        description: "Board state",
+      },
+      yourTurn: {
+        type: "state",
+        schema: { type: "boolean" as const },
+        description: "True when it is your turn to play",
+      },
+      resetGame: {
+        type: "action",
+        description: "Reset the game after completion",
+        parameters: [],
+      },
+      winner: {
+        type: "state",
+        schema: {
+          type: "string" as const,
+          enum: ["X", "O", "cat", null],
+        },
+        description: "Winner mark when game over",
+      },
+      playMove: {
+        type: "action",
+        description: `Play a ${agentMark} move on the board`,
+        parameters: [
+          {
+            title: "index",
+            type: "integer" as const,
+            minimum: 0,
+            maximum: 8,
+          },
+        ],
+      },
+    },
+    implementation: {
+      role: Observe.fromConstant(roleDescription(agentMark)),
+      board,
+      yourTurn,
+      winner: Observe.withFilter(board, BoardState.getWinner),
+      resetGame: async () => {
+        db.transactions.restartGame();
+      },
+      playMove: async (index: number) => {
+        db.transactions.playMove({ index });
+      },
+    },
+    conditional: {
+      resetGame: isGameOver,
+      playMove: yourTurn,
+    },
+  });
+};
+
+const tictactoeLinkDescriptions = { x: "Play as X", o: "Play as O" } as const;
+
+const createTictactoeRootAgentService = (
+  db: TictactoeDatabase,
+): AgenticService => {
+  const root = AgenticService.create({
+    interface: {
+      x: { type: "link", description: tictactoeLinkDescriptions.x },
+      o: { type: "link", description: tictactoeLinkDescriptions.o },
+    },
+    implementation: {
+      x: createTictactoeAgentService(db, "X"),
+      o: createTictactoeAgentService(db, "O"),
+    },
+  });
+  return { ...root, linkDescriptions: tictactoeLinkDescriptions } as AgenticService;
+};
+
+export const agentPlugin = Database.Plugin.create({
+  extends: tictactoePlugin,
+  services: {
+    agent: (db): AgenticService => createTictactoeRootAgentService(db),
+    agentX: (db): AgenticService => createTictactoeAgentService(db, "X"),
+    agentO: (db): AgenticService => createTictactoeAgentService(db, "O"),
+  },
+});

package/references/data-lit-tictactoe/src/state/tictactoe-plugin.ts

@@ -0,0 +1,56 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Database } from "@adobe/data/ecs";
+import { Observe } from "@adobe/data/observe";
+import { BoardState } from "../types/board-state/board-state";
+import type { PlayerMark } from "../types/player-mark/player-mark";
+import { PlayMoveArgs } from "../types/play-move-args/play-move-args";
+
+export const tictactoePlugin = Database.Plugin.create({
+  resources: {
+    board: { default: BoardState.createInitialBoard() },
+    firstPlayer: { default: "X" as PlayerMark },
+  },
+  computed: {
+    currentPlayer: (db) =>
+      Observe.withFilter(db.observe.resources.board, (board) =>
+        BoardState.currentPlayer(board, db.resources.firstPlayer),
+      ),
+    moveCount: (db) =>
+      Observe.withFilter(db.observe.resources.board, BoardState.getMoveCount),
+    status: (db) =>
+      Observe.withFilter(db.observe.resources.board, BoardState.deriveStatus),
+    winningLine: (db) =>
+      Observe.withFilter(db.observe.resources.board, BoardState.getWinningLine),
+    winner: (db) =>
+      Observe.withFilter(db.observe.resources.board, BoardState.getWinner),
+    isGameOver: (db) =>
+      Observe.withFilter(db.observe.resources.board, BoardState.isGameOver),
+  },
+  transactions: {
+    restartGame: (t) => {
+      t.resources.firstPlayer =
+        t.resources.firstPlayer === "X" ? "O" : "X";
+      t.resources.board = BoardState.createInitialBoard();
+    },
+    playMove: (t, { index }: PlayMoveArgs) => {
+      const validation = PlayMoveArgs.canPlayMove({
+        board: t.resources.board,
+        index,
+      });
+      if (!validation.ok) return;
+      const mark = BoardState.currentPlayer(
+        t.resources.board,
+        t.resources.firstPlayer,
+      );
+      const nextBoard = BoardState.setBoardCell({
+        board: t.resources.board,
+        index,
+        mark,
+      });
+      t.resources.board = nextBoard;
+    },
+  },
+});
+
+export type TictactoeDatabase = Database.FromPlugin<typeof tictactoePlugin>;

package/references/data-lit-tictactoe/src/tictactoe-element.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { DatabaseElement } from "@adobe/data-lit";
+import { agentPlugin } from "./state/agent-plugin.js";
+
+export class TictactoeElement extends DatabaseElement<typeof agentPlugin> {
+  get plugin() {
+    return agentPlugin;
+  }
+}

package/references/data-lit-tictactoe/src/types/board-cell.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { PlayerMark } from "./player-mark/player-mark";
+
+export type BoardCell = PlayerMark | " ";

package/references/data-lit-tictactoe/src/types/board-state/board-state.ts

@@ -0,0 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { Schema } from "@adobe/data/schema";
+import { schema } from "./schema";
+
+export type BoardState = Schema.ToType<typeof schema>;
+export * as BoardState from "./public";

package/references/data-lit-tictactoe/src/types/board-state/create-initial-board.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { BoardState } from "./board-state";
+
+export const createInitialBoard = (): BoardState => "         ";

package/references/data-lit-tictactoe/src/types/board-state/current-player.ts

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { BoardState } from "./board-state";
+import type { PlayerMark } from "../player-mark/player-mark";
+
+export const currentPlayer = (
+  board: BoardState,
+  firstPlayer: PlayerMark,
+): PlayerMark => {
+  const xCount = (board.match(/X/g) ?? []).length;
+  const oCount = (board.match(/O/g) ?? []).length;
+  return xCount === oCount ? firstPlayer : firstPlayer === "X" ? "O" : "X";
+};