dots-engine 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Cláudio Silva
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# dots-engine
+
+A TypeScript engine for the classic "Dots" game (a.k.a. Dots and Boxes) — a
+paper-and-pencil strategy game, played here as a strict 1v1 turn-based match.
+
+The engine is designed to be **deterministic**: given the same sequence of
+moves, it always produces the same result, which makes it suitable for
+decentralized applications as well as any ordinary client/server setup.
+
+## About the Game
+
+- Start with a grid of dots.
+- Players take turns connecting two adjacent dots with a horizontal or
+vertical line.
+- When a move completes a square (its fourth edge), that square is owned by
+whoever drew the line, and that player gets an extra move.
+- The game ends when no more lines can be drawn.
+- The player who owns the most completed squares wins; a tie is a draw.
+
+
+
+## Features
+
+- **Complete Game Logic**: Full implementation of the dots-and-boxes rules.
+- **Configurable Grid**: Support for different grid sizes (minimum 2x2).
+- **Strict 1v1 Matches**: Exactly two players per match, alternating turns,
+with an extra move for the player who closes a square.
+- **Score Tracking**: Automatic per-player tally of closed squares.
+- **King-of-the-Chain Tracking**: Each player's longest run of squares closed
+in one uninterrupted turn.
+- **Game State Management**: Tracks game status (in progress, over, draw).
+- **Move Validation**: Enforces turn order, grid bounds, dot adjacency, and
+rejects already-drawn edges.
+- **Move Log**: Records every applied move as a JSON-serializable log, ready
+for a client to replay or persist.
+- **Player Identity Normalization**: Case-insensitive player IDs, so the same
+player never forks into separate score buckets.
+- **Point-Based Model**: Players connect dots using coordinate pairs.
+- **Square-Based Logic**: Internal square tracking for scoring and game state.
+
+
+
+## Key Components
+
+- `Dots.ts`: Main game class that orchestrates a match — turns, scoring,
+status, and the move log.
+- `Grid.ts`: Manages the game board, points, squares, and edges.
+- `Edge.ts`: Represents connections between dots using coordinate pairs.
+- `Point.ts`: Represents individual dots on the grid.
+- `Square.ts`: Represents the squares that can be completed.
+- `GameConstants.ts`: Game constants and status definitions.
+- `address.ts`: Normalizes player identifiers so identity is consistent
+regardless of input casing.
+
+
+
+## Game Model
+
+The engine uses a hybrid model that matches how the game is actually played:
+
+- **Points/Dots**: The primary entities that players interact with.
+- **Edges**: Connections between adjacent points specified by coordinate pairs.
+- **Squares**: Internal entities for tracking completed squares and scoring.
+- **Coordinate System**: Players specify moves as two adjacent dots, `[x1, y1]` and `[x2, y2]`.
+
+
+
+### Example: 3x3 Grid
+
+```
+Points: (0,0) (1,0) (2,0)
+        (0,1) (1,1) (2,1)
+        (0,2) (1,2) (2,2)
+
+Squares: 4 squares arranged as 2x2
+Square 0 at (0,0)  Square 1 at (0,1)
+Square 2 at (1,0)  Square 3 at (1,1)
+```
+
+
+
+## Installation
+
+```bash
+npm install dots-engine
+```
+
+
+
+## Usage
+
+
+
+### Basic Example
+
+```typescript
+import { Dots } from "dots-engine";
+
+const alice = "0xAl1ce";
+const bob = "0xB0b";
+
+// Create a 3x3 grid (2x2 squares) for a match between alice and bob.
+// alice is players[0], so she moves first.
+const dots = new Dots(3, [alice, bob], "match-1");
+
+// Each move connects two adjacent dots, submitted by the player on turn.
+dots.play([0, 0], [0, 1], alice);
+dots.play([0, 0], [1, 0], bob);
+dots.play([0, 1], [1, 1], alice);
+
+// play() returns what changed, so you can re-render straight from it.
+const result = dots.play([1, 0], [1, 1], bob); // Completes square 0, owned by bob
+console.log(result); // { squaresClosed: 1, submitter: "0xb0b", status: 2 }
+
+console.log("Game over:", dots.isOVer());
+console.log("Score:", dots.getScore()); // { "0xb0b": 1 }
+```
+
+
+
+### Advanced Example
+
+```typescript
+import { Dots } from "dots-engine";
+
+const alice = "0xAl1ce";
+const bob = "0xB0b";
+const dots = new Dots(4, [alice, bob], "match-2"); // Create a 4x4 grid
+
+dots.play([0, 0], [0, 1], alice);
+dots.play([0, 0], [1, 0], bob);
+dots.play([0, 1], [1, 1], alice);
+dots.play([1, 0], [1, 1], bob);
+
+console.log("Game over:", dots.isOVer());
+console.log("Score:", dots.getScore());
+console.log("Is draw:", dots.isDraw());
+console.log("Winner:", dots.getWinner());
+console.log("Longest chains:", dots.getLongestChain());
+console.log("Move log:", dots.moveLog);
+
+// Get square position from ID
+const grid = dots.grid;
+const [row, col] = grid.getSquarePosition(5); // Square 5
+console.log("Square 5 is at position:", row, col);
+
+// Get square ID from position
+const squareId = grid.getSquareId(1, 2); // Position (1,2)
+console.log("Position (1,2) corresponds to square:", squareId);
+
+// Show all points in the grid
+console.log("All points in the grid:");
+for (let point of grid.getPoints()) {
+    console.log(`Point: ${point.toString()}`);
+}
+```
+
+
+
+### Frontend usage
+
+The engine speaks plain coordinate tuples, so the same `Coord` type can
+describe your UI state and feed `play` directly — no engine-internal classes
+to import, and everything is JSON-serializable.
+
+```typescript
+import { Dots, type Coord } from "dots-engine";
+
+const dots = new Dots(3, ["0xAl1ce", "0xB0b"], "match-3");
+let selected: Coord | null = null;
+const myAddress = "0xAl1ce"; // the connected wallet's address
+
+// Call this whenever the user clicks a dot.
+function onDotClick(dot: Coord) {
+  if (!selected) {
+    selected = dot;          // first click: remember the start dot
+    return;
+  }
+  try {
+    const result = dots.play(selected, dot, myAddress); // second click: complete the move
+    // re-render from result.submitter / result.status / dots.getScore()
+  } catch (err) {
+    // not this player's turn / not adjacent / out of bounds — show feedback to the user
+  } finally {
+    selected = null;
+  }
+}
+```
+
+A move is always an *edge* (two dots), so the two-click selection lives in
+your UI; the engine only ever receives one complete `play(from, to, submitter)` call.
+
+## Determinism
+
+The engine never reads the wall clock or uses randomness — `Date.now()` and
+`Math.random()` are both banned by lint rules — so two independent
+executions of the same sequence of `play()` calls always produce the same
+state, score, and outcome, whether that's in a browser, on a server, or
+inside a blockchain's execution environment.
+
+The engine itself doesn't timestamp moves, detect a stalled turn, or forfeit
+a non-responding player. Timing, turn timeouts, and replaying a match's
+history from a log are all client/orchestration concerns built on top of
+`Dots` (e.g. by pairing each `play()` call with your own timestamp), not
+things this engine implements.
+
+## Coordinate System
+
+- **Dots**: A dot is a `Coord` tuple `[x, y]`, where `x` is the column and `y` the row (both 0-based), ranging from `[0, 0]` to `[gridSize-1, gridSize-1]`.
+- **Moves**: A move connects two orthogonally adjacent dots (the edge between them).
+- **Squares**: Internal tracking with IDs `0, 1, 2, …` arranged in rows.
+- **Validation**: `play` enforces turn order, and that the two dots are adjacent and within grid bounds.
+
+
+
+## Development
+
+
+
+### Running Tests
+
+```bash
+npm test
+```
+
+
+
+### Running Demo
+
+```bash
+npm run dev
+```
+
+
+
+## License
+
+ISC License

package/dist/Dots.d.ts

@@ -0,0 +1,66 @@
+import Grid from "./Grid";
+import { Coord, MatchId, MoveRecord, MoveResult, PlayerId } from "./types";
+declare class Dots {
+    grid: Grid;
+    /** Identifier of this match; stamped onto every {@link MoveRecord}. */
+    matchId: MatchId;
+    /** The two players in this match; `players[0]` moves first. */
+    players: [PlayerId, PlayerId];
+    /** Player allowed to submit the next move. */
+    turn: PlayerId;
+    /** Squares closed per submitter. JSON-serializable by design. */
+    scores: Record<PlayerId, number>;
+    /** Squares closed so far in the current uninterrupted turn; reset when the turn changes. */
+    private chainCounter;
+    /** Each player's longest uninterrupted-turn chain this match (king-of-the-chain). */
+    longestChain: Record<PlayerId, number>;
+    status: number;
+    /** Full move history — simultaneously the per-move notice payload and the replay input (F6). */
+    moveLog: MoveRecord[];
+    /**
+     * @param matchId Identifier of this match, assigned by the caller
+     *        (today: tests; later: the Match orchestrator).
+     * @param players The two players, normalized on entry; `players[0]`
+     *        moves first (the first joiner, per the matchmaking queue).
+     * @throws If the two players are not distinct once normalized.
+     */
+    constructor(gridsize: number, players: [string, string], matchId: MatchId);
+    /**
+     * Connect two adjacent dots, drawing the edge between them.
+     *
+     * A move is always an edge (two dots); collecting the two endpoints — e.g.
+     * the two-click selection in a UI — is the caller's responsibility, so the
+     * engine stays stateless about selection and receives one complete move.
+     *
+     * Only the player currently on turn may draw an edge, and any square the
+     * move closes is owned by that player.
+     *
+     * Extra move on close: a move that closes one or two squares keeps the
+     * turn with the same player instead of alternating (PRD-v5 §6.4).
+     *
+     * @param from Start dot as `[x, y]` (x = column, y = row, 0-based).
+     * @param to   End dot as `[x, y]`; must be orthogonally adjacent to `from`.
+     * @param submitter Identifier of the player drawing the edge; owns any
+     *        squares it closes. Normalized before use, so formatting
+     *        differences never affect scoring or the returned `MoveResult`.
+     * @returns A {@link MoveResult} describing the outcome of the move.
+     * @throws If the game is over, `submitter` is not the player on turn, a
+     *         coordinate is out of bounds, the two dots are not adjacent, or
+     *         the edge has already been drawn.
+     */
+    play(from: Coord, to: Coord, submitter: string): MoveResult;
+    getScore(): Record<string, number>;
+    /** Each player's longest uninterrupted-turn chain this match so far. */
+    getLongestChain(): Record<string, number>;
+    isOVer(): boolean;
+    isDraw(): boolean;
+    /**
+     * The submitter who owns the most closed squares, or `null` when the top
+     * count is shared by two or more addresses (a draw).
+     */
+    getWinner(): PlayerId | null;
+    private addScore;
+    private otherPlayer;
+    private updateStatus;
+}
+export default Dots;

package/dist/Dots.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const address_1 = require("./address");
+const GameConstants_1 = require("./GameConstants");
+const Grid_1 = __importDefault(require("./Grid"));
+class Dots {
+    /**
+     * @param matchId Identifier of this match, assigned by the caller
+     *        (today: tests; later: the Match orchestrator).
+     * @param players The two players, normalized on entry; `players[0]`
+     *        moves first (the first joiner, per the matchmaking queue).
+     * @throws If the two players are not distinct once normalized.
+     */
+    constructor(gridsize, players, matchId) {
+        /** Squares closed per submitter. JSON-serializable by design. */
+        this.scores = {};
+        /** Squares closed so far in the current uninterrupted turn; reset when the turn changes. */
+        this.chainCounter = 0;
+        /** Each player's longest uninterrupted-turn chain this match (king-of-the-chain). */
+        this.longestChain = {};
+        this.status = GameConstants_1.GameConstants.STATUS_NOT_INITIATED;
+        /** Full move history — simultaneously the per-move notice payload and the replay input (F6). */
+        this.moveLog = [];
+        this.grid = new Grid_1.default(gridsize);
+        this.matchId = matchId;
+        const p1 = (0, address_1.normalizePlayerId)(players[0]);
+        const p2 = (0, address_1.normalizePlayerId)(players[1]);
+        if (p1 === p2) {
+            throw new Error(`A match needs two distinct players, got the same player twice: ${p1}`);
+        }
+        this.players = [p1, p2];
+        this.turn = p1;
+    }
+    /**
+     * Connect two adjacent dots, drawing the edge between them.
+     *
+     * A move is always an edge (two dots); collecting the two endpoints — e.g.
+     * the two-click selection in a UI — is the caller's responsibility, so the
+     * engine stays stateless about selection and receives one complete move.
+     *
+     * Only the player currently on turn may draw an edge, and any square the
+     * move closes is owned by that player.
+     *
+     * Extra move on close: a move that closes one or two squares keeps the
+     * turn with the same player instead of alternating (PRD-v5 §6.4).
+     *
+     * @param from Start dot as `[x, y]` (x = column, y = row, 0-based).
+     * @param to   End dot as `[x, y]`; must be orthogonally adjacent to `from`.
+     * @param submitter Identifier of the player drawing the edge; owns any
+     *        squares it closes. Normalized before use, so formatting
+     *        differences never affect scoring or the returned `MoveResult`.
+     * @returns A {@link MoveResult} describing the outcome of the move.
+     * @throws If the game is over, `submitter` is not the player on turn, a
+     *         coordinate is out of bounds, the two dots are not adjacent, or
+     *         the edge has already been drawn.
+     */
+    play(from, to, submitter) {
+        var _a;
+        if (this.isOVer()) {
+            throw new Error("Game is over");
+        }
+        submitter = (0, address_1.normalizePlayerId)(submitter);
+        if (submitter !== this.turn) {
+            throw new Error(`Not this player's turn: expected ${this.turn}, got ${submitter}`);
+        }
+        const edge = this.grid.buildEdge(from, to);
+        if (this.grid.isEdgeDrawn(edge)) {
+            const [x1, y1] = from;
+            const [x2, y2] = to;
+            throw new Error(`Edge already drawn: [${x1}, ${y1}] -> [${x2}, ${y2}]`);
+        }
+        const squaresClosed = this.grid.conquerEdge(edge, submitter);
+        if (squaresClosed > 0) {
+            this.addScore(submitter, squaresClosed);
+            this.chainCounter += squaresClosed;
+            // Update the max here, not on turn change: the move that ends the
+            // match closes squares without ever flipping the turn, so a
+            // turn-change-gated update would silently drop the final chain.
+            this.longestChain[submitter] = Math.max((_a = this.longestChain[submitter]) !== null && _a !== void 0 ? _a : 0, this.chainCounter);
+        }
+        this.updateStatus();
+        if (squaresClosed === 0) {
+            // The turn can only flip when nothing was closed
+            this.turn = this.otherPlayer(submitter);
+            this.chainCounter = 0;
+        }
+        this.moveLog.push({
+            matchId: this.matchId,
+            moveIndex: this.moveLog.length,
+            edge: [from, to],
+            submitter,
+            squaresClosed,
+            turnAfter: this.turn,
+        });
+        return {
+            squaresClosed,
+            submitter,
+            status: this.status,
+        };
+    }
+    getScore() {
+        return this.scores;
+    }
+    /** Each player's longest uninterrupted-turn chain this match so far. */
+    getLongestChain() {
+        return this.longestChain;
+    }
+    isOVer() {
+        return this.status === GameConstants_1.GameConstants.STATUS_OVER ||
+            this.status === GameConstants_1.GameConstants.STATUS_OVER_BY_DRAW;
+    }
+    isDraw() {
+        return this.isOVer() && this.getWinner() === null;
+    }
+    /**
+     * The submitter who owns the most closed squares, or `null` when the top
+     * count is shared by two or more addresses (a draw).
+     */
+    getWinner() {
+        let winner = null;
+        let topScore = 0;
+        let tied = false;
+        for (const [address, score] of Object.entries(this.scores)) {
+            if (score > topScore) {
+                topScore = score;
+                winner = address;
+                tied = false;
+            }
+            else if (score === topScore) {
+                tied = true;
+            }
+        }
+        return tied ? null : winner;
+    }
+    addScore(submitter, nClosedSquares) {
+        var _a;
+        this.scores[submitter] = ((_a = this.scores[submitter]) !== null && _a !== void 0 ? _a : 0) + nClosedSquares;
+    }
+    otherPlayer(player) {
+        return this.players[0] === player ? this.players[1] : this.players[0];
+    }
+    updateStatus() {
+        if (!this.grid.hasOpenSquare()) {
+            this.status = this.getWinner() !== null
+                ? GameConstants_1.GameConstants.STATUS_OVER
+                : GameConstants_1.GameConstants.STATUS_OVER_BY_DRAW;
+        }
+        else {
+            this.status = GameConstants_1.GameConstants.STATUS_IN_PROGRESS;
+        }
+    }
+}
+exports.default = Dots;

package/dist/Edge.d.ts

@@ -0,0 +1,15 @@
+import Point from './Point';
+import { PlayerId } from './types';
+declare class Edge {
+    p1: Point;
+    p2: Point;
+    relatedSquareId: number[];
+    owner: PlayerId;
+    constructor(p1: Point, p2: Point);
+    setOwner(owner: PlayerId): void;
+    hasOwner(): boolean;
+    equals(other: Edge): boolean;
+    relatesTo(squareId: number): void;
+    getRelatedSquareOtherThan(id: number): number;
+}
+export default Edge;

package/dist/Edge.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class Edge {
+    constructor(p1, p2) {
+        this.relatedSquareId = [];
+        this.owner = "";
+        this.p1 = p1;
+        this.p2 = p2;
+    }
+    setOwner(owner) {
+        if (!this.hasOwner()) {
+            this.owner = owner;
+        }
+    }
+    hasOwner() {
+        return (this.owner.length > 0) ? true : false;
+    }
+    equals(other) {
+        // Check if edges are the same (in either direction)
+        return (this.p1.equals(other.p1) && this.p2.equals(other.p2)) ||
+            (this.p1.equals(other.p2) && this.p2.equals(other.p1));
+    }
+    relatesTo(squareId) {
+        this.relatedSquareId.push(squareId);
+    }
+    getRelatedSquareOtherThan(id) {
+        if (this.relatedSquareId[0] === id) {
+            return this.relatedSquareId[1];
+        }
+        else {
+            return this.relatedSquareId[0];
+        }
+    }
+}
+exports.default = Edge;

package/dist/GameConstants.d.ts

@@ -0,0 +1,7 @@
+export declare class GameConstants {
+    static readonly GRID_SIZE = 6;
+    static readonly STATUS_NOT_INITIATED: number;
+    static readonly STATUS_IN_PROGRESS: number;
+    static readonly STATUS_OVER: number;
+    static readonly STATUS_OVER_BY_DRAW: number;
+}

package/dist/GameConstants.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GameConstants = void 0;
+class GameConstants {
+}
+exports.GameConstants = GameConstants;
+GameConstants.GRID_SIZE = 6;
+// Game possible statuses
+GameConstants.STATUS_NOT_INITIATED = 1;
+GameConstants.STATUS_IN_PROGRESS = 2;
+GameConstants.STATUS_OVER = 3;
+GameConstants.STATUS_OVER_BY_DRAW = 4;
+;

package/dist/Grid.d.ts

@@ -0,0 +1,87 @@
+import Square from './Square';
+import Point from './Point';
+import Edge from './Edge';
+import { Coord, PlayerId } from './types';
+declare class Grid {
+    size: number;
+    squares: Square[];
+    points: Point[];
+    uniqueEdges: Edge[];
+    /**
+     * Constructor
+     * @param gridSize n. points (horizontal and vertical) for the grid
+     */
+    constructor(gridSize: number);
+    private build;
+    private createPoints;
+    private createSquares;
+    private createEdges;
+    private getEdge;
+    /**
+     * Get square position from square ID
+     * @param squareId The square ID
+     * @returns [row, col] position
+     */
+    getSquarePosition(squareId: number): [number, number];
+    /**
+     * Get square ID from position
+     * @param row Row position
+     * @param col Column position
+     * @returns Square ID
+     */
+    getSquareId(row: number, col: number): number;
+    /**
+     * Get all squares that share an edge
+     * @param edge The edge
+     * @returns Array of square IDs that share this edge
+     */
+    getSquaresForEdge(edge: Edge): number[];
+    /**
+     * Build the edge for a move, validating it first. Single source of truth
+     * for move geometry: bounds + orthogonal adjacency.
+     */
+    buildEdge(from: Coord, to: Coord): Edge;
+    /**
+     * Whether the given edge has already been drawn (claimed by a submitter).
+     */
+    isEdgeDrawn(edge: Edge): boolean;
+    /**
+     * Find an edge by its points
+     * @param p1 First point
+     * @param p2 Second point
+     * @returns The edge if found, null otherwise
+     */
+    findEdge(p1: Point, p2: Point): Edge | null;
+    /**
+     * Get squares that still have available edges
+     * @param squareIds List of squares' ids
+     */
+    private getAvailableSquaresbyId;
+    /**
+     * Close an edge
+     *
+     * @param edge Edge to close
+     * @param owner User who wants to own the edge
+     *
+     * @returns Number of closed squares by closing the edge provided.
+     */
+    conquerEdge(edge: Edge, owner: PlayerId): number;
+    private conquerSquare;
+    /**
+     * Check if there is any open square.
+     */
+    hasOpenSquare(): boolean;
+    /**
+     * Get all squares
+     */
+    getSquares(): Square[];
+    /**
+     * Get all edges
+     */
+    getEdges(): Edge[];
+    /**
+     * Get all points
+     */
+    getPoints(): Point[];
+}
+export default Grid;

package/dist/Grid.js

@@ -0,0 +1,229 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Square_1 = __importDefault(require("./Square"));
+const Point_1 = __importDefault(require("./Point"));
+const Edge_1 = __importDefault(require("./Edge"));
+class Grid {
+    /**
+     * Constructor
+     * @param gridSize n. points (horizontal and vertical) for the grid
+     */
+    constructor(gridSize) {
+        this.size = 0;
+        this.squares = [];
+        this.points = [];
+        this.uniqueEdges = [];
+        if (gridSize < 2)
+            throw new Error("Grid size must be greater or equal to 2");
+        this.build(gridSize);
+    }
+    build(gridSize) {
+        this.size = gridSize;
+        this.createPoints(gridSize);
+        this.createSquares(gridSize);
+    }
+    createPoints(gridSize) {
+        for (let x = 0; x < gridSize; x++) {
+            for (let y = 0; y < gridSize; y++) {
+                this.points.push(new Point_1.default(x, y));
+            }
+        }
+    }
+    createSquares(gridSize) {
+        const squaresPerRow = gridSize - 1;
+        const totalRows = gridSize - 1;
+        for (let row = 0; row < totalRows; row++) {
+            for (let col = 0; col < squaresPerRow; col++) {
+                const squareId = row * squaresPerRow + col;
+                console.log('CreateSquare #' + squareId + ' at position (' + row + ',' + col + ')');
+                let edges = this.createEdges(row, col);
+                this.squares.push(new Square_1.default(squareId, edges));
+            }
+        }
+        console.log('createSquares - created #uniqueEdges=' + this.uniqueEdges.length);
+    }
+    createEdges(row, col) {
+        // Create the four edges for a square at position (row, col)
+        // Each edge connects two adjacent points
+        let leftEdge = this.getEdge(new Point_1.default(col, row), new Point_1.default(col, row + 1));
+        let bottomEdge = this.getEdge(new Point_1.default(col, row + 1), new Point_1.default(col + 1, row + 1));
+        let rightEdge = this.getEdge(new Point_1.default(col + 1, row + 1), new Point_1.default(col + 1, row));
+        let topEdge = this.getEdge(new Point_1.default(col + 1, row), new Point_1.default(col, row));
+        let edges = [leftEdge, bottomEdge, rightEdge, topEdge];
+        return edges;
+    }
+    getEdge(p1, p2) {
+        let tempEdge = new Edge_1.default(p1, p2);
+        for (let i = 0; i < this.uniqueEdges.length; i++) {
+            const existingEdge = this.uniqueEdges[i];
+            if (existingEdge.equals(tempEdge)) {
+                return existingEdge;
+            }
+        }
+        this.uniqueEdges.push(tempEdge);
+        return tempEdge;
+    }
+    /**
+     * Get square position from square ID
+     * @param squareId The square ID
+     * @returns [row, col] position
+     */
+    getSquarePosition(squareId) {
+        const squaresPerRow = this.size - 1;
+        const row = Math.floor(squareId / squaresPerRow);
+        const col = squareId % squaresPerRow;
+        return [row, col];
+    }
+    /**
+     * Get square ID from position
+     * @param row Row position
+     * @param col Column position
+     * @returns Square ID
+     */
+    getSquareId(row, col) {
+        const squaresPerRow = this.size - 1;
+        return row * squaresPerRow + col;
+    }
+    /**
+     * Get all squares that share an edge
+     * @param edge The edge
+     * @returns Array of square IDs that share this edge
+     */
+    getSquaresForEdge(edge) {
+        return edge.relatedSquareId;
+    }
+    /**
+     * Build the edge for a move, validating it first. Single source of truth
+     * for move geometry: bounds + orthogonal adjacency.
+     */
+    buildEdge(from, to) {
+        const size = this.size;
+        const endpoints = [["from", from], ["to", to]];
+        for (const [label, [x, y]] of endpoints) {
+            if (!Number.isInteger(x) || !Number.isInteger(y) ||
+                x < 0 || x >= size || y < 0 || y >= size) {
+                throw new Error(`Invalid "${label}" coordinate [${x}, ${y}]: out of bounds for a ${size}x${size} grid`);
+            }
+        }
+        const [x1, y1] = from;
+        const [x2, y2] = to;
+        const dx = Math.abs(x2 - x1);
+        const dy = Math.abs(y2 - y1);
+        if (!((dx === 1 && dy === 0) || (dx === 0 && dy === 1))) {
+            throw new Error(`Dots must be adjacent: [${x1}, ${y1}] -> [${x2}, ${y2}]`);
+        }
+        return new Edge_1.default(new Point_1.default(x1, y1), new Point_1.default(x2, y2));
+    }
+    /**
+     * Whether the given edge has already been drawn (claimed by a submitter).
+     */
+    isEdgeDrawn(edge) {
+        var _a;
+        const tracked = this.findEdge(edge.p1, edge.p2);
+        return (_a = tracked === null || tracked === void 0 ? void 0 : tracked.hasOwner()) !== null && _a !== void 0 ? _a : false;
+    }
+    /**
+     * Find an edge by its points
+     * @param p1 First point
+     * @param p2 Second point
+     * @returns The edge if found, null otherwise
+     */
+    findEdge(p1, p2) {
+        const searchEdge = new Edge_1.default(p1, p2);
+        for (let edge of this.uniqueEdges) {
+            if (edge.equals(searchEdge)) {
+                return edge;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get squares that still have available edges
+     * @param squareIds List of squares' ids
+     */
+    getAvailableSquaresbyId(squareIds) {
+        let squaresFound = [];
+        for (let i = 0; i < this.squares.length; i++) {
+            const currSquare = this.squares[i];
+            squareIds.forEach(id => {
+                if ((currSquare.id === id) && (currSquare.hasAvailableFace())) {
+                    squaresFound.push(currSquare);
+                }
+            });
+        }
+        return squaresFound;
+    }
+    /**
+     * Close an edge
+     *
+     * @param edge Edge to close
+     * @param owner User who wants to own the edge
+     *
+     * @returns Number of closed squares by closing the edge provided.
+     */
+    conquerEdge(edge, owner) {
+        let nClosedSquares = 0;
+        for (let i = 0; i < this.uniqueEdges.length; i++) {
+            const gameEdge = this.uniqueEdges[i];
+            if ((gameEdge.equals(edge)) && (!gameEdge.hasOwner())) {
+                let squareIds = gameEdge.relatedSquareId;
+                let availSquaresBeforeClosing = this.getAvailableSquaresbyId(squareIds);
+                gameEdge.setOwner(owner);
+                let availSquaresAfterClosing = this.getAvailableSquaresbyId(squareIds);
+                nClosedSquares = availSquaresBeforeClosing.length - availSquaresAfterClosing.length;
+                if (nClosedSquares > 0) {
+                    this.conquerSquare(availSquaresBeforeClosing, availSquaresAfterClosing, owner);
+                }
+                break;
+            }
+        }
+        return nClosedSquares;
+    }
+    conquerSquare(availSquaresBeforeClosing, availSquaresAfterClosing, owner) {
+        for (let i = 0; i < availSquaresBeforeClosing.length; i++) {
+            let foundSquare = false;
+            for (let j = 0; j < availSquaresAfterClosing.length; j++) {
+                if (availSquaresBeforeClosing[i].id === availSquaresAfterClosing[j].id) {
+                    foundSquare = true;
+                    break;
+                }
+            }
+            if (!foundSquare) {
+                availSquaresBeforeClosing[i].owner = owner;
+            }
+        }
+    }
+    /**
+     * Check if there is any open square.
+     */
+    hasOpenSquare() {
+        for (let i = 0; i < this.squares.length; i++) {
+            if (this.squares[i].hasAvailableFace()) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Get all squares
+     */
+    getSquares() {
+        return this.squares;
+    }
+    /**
+     * Get all edges
+     */
+    getEdges() {
+        return this.uniqueEdges;
+    }
+    /**
+     * Get all points
+     */
+    getPoints() {
+        return this.points;
+    }
+}
+exports.default = Grid;

package/dist/Point.d.ts

@@ -0,0 +1,8 @@
+declare class Point {
+    x: number;
+    y: number;
+    constructor(x: number, y: number);
+    equals(other: Point): boolean;
+    toString(): string;
+}
+export default Point;

package/dist/Point.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class Point {
+    constructor(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    equals(other) {
+        return this.x === other.x && this.y === other.y;
+    }
+    toString() {
+        return `${this.x},${this.y}`;
+    }
+}
+exports.default = Point;

package/dist/Square.d.ts

@@ -0,0 +1,19 @@
+import Edge from './Edge';
+import { PlayerId } from './types';
+declare class Square {
+    id: number;
+    owner: PlayerId;
+    edges: Edge[];
+    constructor(id: number, edges: Edge[]);
+    /**
+     * Return true if there is, at least, one available face
+     * and false otherwise
+     */
+    hasAvailableFace(): boolean;
+    getNumberOfAvailableFaces(): number;
+    /**
+     * true if the square has owner or false otherwise
+     */
+    hasOwner(): boolean;
+}
+export default Square;

package/dist/Square.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const SIDES = 4;
+class Square {
+    constructor(id, edges) {
+        if (edges.length != SIDES) {
+            throw new Error("Edge array must have exactly 4 edges");
+        }
+        this.id = id;
+        this.owner = '';
+        edges.forEach(edge => {
+            edge.relatesTo(this.id);
+        });
+        this.edges = edges;
+    }
+    /**
+     * Return true if there is, at least, one available face
+     * and false otherwise
+     */
+    hasAvailableFace() {
+        for (let i = 0; i < this.edges.length; i++) {
+            const edge = this.edges[i];
+            if (edge.hasOwner() === false)
+                return true;
+        }
+        return false;
+    }
+    getNumberOfAvailableFaces() {
+        let cont = 0;
+        for (let i = 0; i < this.edges.length; i++) {
+            const edge = this.edges[i];
+            if (edge.hasOwner() === false)
+                cont++;
+        }
+        return cont;
+    }
+    /**
+     * true if the square has owner or false otherwise
+     */
+    hasOwner() {
+        var _a;
+        return ((_a = this.owner) === null || _a === void 0 ? void 0 : _a.length) > 0 ? true : false;
+    }
+}
+exports.default = Square;

package/dist/address.d.ts

@@ -0,0 +1,11 @@
+import { PlayerId } from "./types";
+/**
+ * Canonicalize an EOA address for use as a player identifier.
+ *
+ * Cartesi supplies `msg_sender` already lowercase, but wallets supply
+ * EIP-55 checksum-cased addresses. Without normalizing, the same player
+ * submitted under different casing would fork replays and score buckets
+ * between consumers. This is the only place in the engine allowed to know
+ * player identifiers are case-insensitive hex strings.
+ */
+export declare function normalizePlayerId(id: string): PlayerId;

package/dist/address.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePlayerId = void 0;
+/**
+ * Canonicalize an EOA address for use as a player identifier.
+ *
+ * Cartesi supplies `msg_sender` already lowercase, but wallets supply
+ * EIP-55 checksum-cased addresses. Without normalizing, the same player
+ * submitted under different casing would fork replays and score buckets
+ * between consumers. This is the only place in the engine allowed to know
+ * player identifiers are case-insensitive hex strings.
+ */
+function normalizePlayerId(id) {
+    return id.toLowerCase();
+}
+exports.normalizePlayerId = normalizePlayerId;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Dots } from "./Dots";
+export { GameConstants } from "./GameConstants";
+export type { Coord, MatchId, MoveRecord, MoveResult, PlayerId } from "./types";

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GameConstants = exports.Dots = void 0;
+var Dots_1 = require("./Dots");
+Object.defineProperty(exports, "Dots", { enumerable: true, get: function () { return __importDefault(Dots_1).default; } });
+var GameConstants_1 = require("./GameConstants");
+Object.defineProperty(exports, "GameConstants", { enumerable: true, get: function () { return GameConstants_1.GameConstants; } });

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A dot on the grid, expressed as `[x, y]` where `x` is the column and `y` the
+ * row (both 0-based). Ranges from `[0, 0]` to `[gridSize - 1, gridSize - 1]`.
+ *
+ * Plain tuples are intentionally the only move vocabulary: they are
+ * JSON-serializable and need no engine-internal classes, so the same `Coord`
+ * type can describe a frontend's state and feed {@link Dots.play} directly.
+ */
+export type Coord = [number, number];
+/**
+ * A player identifier, already normalized by the engine at every ingress so
+ * the same player never forks into separate score buckets. Opaque to game
+ * logic — see {@link ../address.normalizePlayerId} for the one place that
+ * knows its concrete format.
+ */
+export type PlayerId = string;
+/**
+ * A match identifier, opaque to game logic. Assigned once per match by
+ * whoever constructs the engine (today: tests; later: the Match
+ * orchestrator).
+ */
+export type MatchId = string;
+/**
+ * One applied move, in canonical form. Doubles as the per-move notice
+ * payload (F6) and, as a log, the replay input — the shape is shared on
+ * purpose so the two never drift.
+ */
+export interface MoveRecord {
+    matchId: MatchId;
+    /** 0-based position of this move within the match's move log. */
+    moveIndex: number;
+    /** The move exactly as submitted: `[from, to]`. */
+    edge: [Coord, Coord];
+    /** Identifier of the player who submitted this move; already normalized. */
+    submitter: PlayerId;
+    /** Squares completed by this move (0, 1, or 2). */
+    squaresClosed: number;
+    /** Player on turn immediately after this move resolved. */
+    turnAfter: PlayerId;
+}
+/**
+ * Outcome of a single {@link Dots.play} call — everything a UI needs to
+ * re-render after a move, returned from the one call instead of forcing the
+ * caller to diff `getScore()` / `isOVer()` by hand.
+ */
+export interface MoveResult {
+    /** Squares completed by this move (0, 1, or 2). */
+    squaresClosed: number;
+    /** Identifier of the player who submitted this move (owns any squares it closed); already normalized. */
+    submitter: PlayerId;
+    /** Game status after the move (see `GameConstants.STATUS_*`). */
+    status: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "dots-engine",
+  "version": "0.1.0-alpha.0",
+  "description": "js engine for dots game",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "ts-node examples/demo.ts",
+    "test": "jest",
+    "lint": "eslint .",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "claudioantonio",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^29.5.7",
+    "eslint": "^10.8.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.2.2",
+    "typescript-eslint": "^8.65.0"
+  }
+}