@chessdrive/board 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 ChessDrive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The chess pieces are Kosal by philatype (https://github.com/philatype/kosal),
+licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).
+chess.js (https://github.com/jhlywa/chess.js) is bundled under its BSD 2-Clause
+licence, and Svelte (https://svelte.dev) under its MIT licence.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @chessdrive/board
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The Board by ChessDrive**: a chess board your agent shows you and drives, and you can move and draw on. One self-contained `<chessdrive-board>` element: no key, no network calls, no external images or fonts. It runs in Claude artifacts, MCP Apps and any local page.
+
+## Load it
+
+Pin the exact version, from jsDelivr:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@chessdrive/board@0.1.1/dist/board.umd.js"></script>
+<chessdrive-board></chessdrive-board>
+```
+
+That is a playable board. Use jsDelivr, never unpkg: legacy Claude chat artifacts block unpkg. As a module: `import '@chessdrive/board'` (ESM, `dist/board.js`). The UMD build also defines `window.ChessDriveBoard`.
+
+**Never put an API key in the page.** Get paid answers, such as engine lines or game search, through the ChessDrive Connector: in a Claude artifact through the viewer's own MCP connection, elsewhere through your agent's own tool calls. Then pass them to `board.set()`.
+
+## Drive it
+
+```js
+const board = document.querySelector('chessdrive-board');
+
+board.set({
+  fen: 'r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3',
+  marks: [{ arrow: 'f1b5', color: 'green' }, { circle: 'e5', color: 'red' }],
+  eval: { cp: 35 },
+  mode: 'play-white',
+});
+
+board.on('move', ({ san, fen }) => {
+  // The person moved. Reply with your own move:
+  board.play('Nf6');
+});
+```
+
+Or create one: `ChessDriveBoard.create(document.body, { pgn, ply: 12, moves: true })`.
+
+## The State
+
+One object describes the whole Board. `board.state` returns it; `board.set(patch)` merges any part of it. Unknown fields are ignored, never an error.
+
+| Field | Value | Default |
+|---|---|---|
+| `fen` | The position. With a game, the position at `ply`. | the start |
+| `pgn`, `ply` | A game, and the half-moves into it on view (0 to its length). Set a `pgn` or a `fen`, not both. | |
+| `orientation` | `white` or `black`: the side at the bottom. | `white` |
+| `lastMove` | The move into the position, in UCI (`e2e4`), tinted. A game supplies its own. | `null` |
+| `marks` | Arrows `{ arrow: 'e2e4' }`, circles `{ circle: 'f7' }` and square highlights `{ square: 'd5' }`, each with a `color` (`green`, `red`, `blue`, `yellow`, `orange`) and an `author`. | `[]` |
+| `annotations` | Verdicts on a game's moves: a map from ply to `{ glyph, comment }`, either part optional. `glyph` is `!!` (best), `!` (good), `?!` (inaccuracy), `?` (mistake) or `??` (blunder). See [Verdicts](#verdicts). | none |
+| `eval` | `{ cp: 35 }` (centipawns, White's view) or `{ mate: -3 }`. `null` hides the bar, and leaves its place once it has shown, so the squares don't move. | `null` |
+| `mode` | `view` (locked), `play-white`, `play-black` or `play-both`. | `play-both` |
+| `moves` | `true` shows the move list. | `false` |
+| `players` | `{ white: { name, rating }, black: { name, rating } }`, or `true` for plain rows, with captures and material. | `null` |
+| `size` | `full` (squares up to 560 px, 520 beside the eval bar, with the moves to their side on a wide page), `phone` (360 px, moves below), `embed` (240 px: the board, buttons and link) or `thumb` (160 px: the board alone). | `full` |
+| `outcome` | Read only, and left out while the game goes on: `{ result, reason }`, with `result` `1-0`, `0-1` or `1/2-1/2`. `reason` is `checkmate`, `stalemate` or `insufficient material`, or in a game the person plays against you (`play-white`, `play-black`) `repetition` or `fifty moves`. It comes from the position, so a resignation in a PGN isn't one. `ChessDriveBoard.outcomeText(outcome)` gives the line shown under the board. | |
+
+Marks you set are always yours, the agent's: they're drawn outlined and opaque. Setting `marks` replaces yours and leaves the person's alone.
+
+### Verdicts
+
+```js
+board.set({
+  pgn: '1. e4 e5 2. Nf3 Nc6 3. Bb5 a6',
+  ply: 5,
+  moves: true,
+  annotations: {
+    5: { glyph: '!', comment: 'The Ruy Lopez.' },
+    6: { glyph: '?!' },
+  },
+});
+```
+
+A ply is the half-moves played once the move is made, so `1` is White's first move, the same count as `ply`. The glyph shows after the move in the move list, in a chip of its colour, and on the move's destination square while that ply is on view. The comment shows under the move list while that ply is on view, as plain text; `embed` and `thumb` leave it out. `0` is the start: it has no move to carry a glyph, but its comment shows.
+
+Setting `annotations` replaces them, and `{}` clears them. A new game or position starts without them, and a move played from an earlier ply drops those on the moves it replaced. Each bad annotation is ignored and fires `error`. They never change your Marks, and they stay out of the link back and `toFragment`, so links stay short.
+
+## Commands
+
+- `set(patch)` merges a partial State. Returns `false`, and fires `error` for each bad value, which is left as it was.
+- `play(move)` animates one legal move from the position on view, in SAN (`Nf3`) or UCI (`g1f3`, `e7e8n`). An illegal move fires `error` and changes nothing.
+- `animate(line)` plays a sequence (`['e4', 'e5', 'Nf3']` or `'1. e4 e5 2. Nf3'`) move by move. A line with an illegal move plays nothing. Resolves `true` when done, `false` when cut short.
+- `clear()` removes your Marks; the person's stay.
+
+There is no `undo`: set `ply` or `pgn`.
+
+## Events
+
+The person's actions arrive as DOM `CustomEvent`s on the element and through `board.on(name, fn)`, which returns a function that stops listening. Your own commands never echo back, except as `error`.
+
+| Event | Detail |
+|---|---|
+| `move` | `{ uci, san, fen, ply }`: the person's move, a promotion included. A premove arrives when it is played. |
+| `marks` | `{ marks }`: the person's Marks, after they drew or cleared one. |
+| `ply` | `{ ply, fen }`: the person stepped through the game. |
+| `flip` | `{ orientation }`: the person flipped the board. |
+| `ready` | `{ state }`: the Board is on the page. `on('ready')` after that is called at once. |
+| `error` | `{ code, message }`: `invalid_state` or `illegal_move`. |
+
+The person moves by drag or click-click, with legal-move dots and a promotion column, and premoves while it's your turn in a `play-white` or `play-black` game. In `view` mode with a game, ← → step it with the squares focused; in a play mode they move the keyboard's square cursor there. They draw arrows with a right-drag and circles with a right-click (Shift red, Alt blue, Ctrl or ⌘ yellow), or with the pen button on a touch screen. A click on the board clears their own Marks.
+
+## Attributes
+
+For a page with no script of its own: `fen`, `pgn`, `ply`, `orientation`, `last-move`, `mode`, `moves`, `players` and `size`, read as `set()` reads them.
+
+```html
+<chessdrive-board pgn="1. e4 e5 2. Nf3 Nc6" ply="3" moves size="phone"></chessdrive-board>
+```
+
+## The look and the link back
+
+Maple squares, Kosal pieces, corner coordinates. The Board follows the viewer's light or dark setting (`prefers-color-scheme`), not the page's: on a dark setting its panels turn dark and its squares dim, whatever the page's own colours. To keep it light, add the `data-light` attribute: `<chessdrive-board data-light></chessdrive-board>`. The State can't change the look. Under the board, at every size but `thumb`, a "Board by ChessDrive" link opens the same position on platform.chessdrive.io/board. `ChessDriveBoard.toFragment(state)` and `fromFragment(hash)` read and write that address's fragment.
+
+## On the Connector
+
+`app/` is the same build as an MCP App, the page behind the Connector's `show_board` tool: `npm run build:app` inlines `dist/board.umd.js` and the view into `api/connector/board.gen.html`. Commit that file: Railway builds `api` from its own folder, and `make contract` fails while it is stale.
+
+## Versions
+
+Semver: adding a State field or an event is a minor version; removing or renaming one is a major. Pin the exact version in pages you share.
+
+## Licence
+
+MIT. The Kosal pieces are by philatype, CC BY 4.0.

package/dist/board.d.ts

@@ -0,0 +1,116 @@
+// @chessdrive/board's types, published as dist/board.d.ts. src/types.check.ts keeps them the same as the build's own.
+
+export type MarkColour = 'green' | 'red' | 'blue' | 'yellow' | 'orange';
+export type MarkAuthor = 'agent' | 'person';
+/** An arrow (`e2e4`), a circle (`f7`) or a square highlight (`d5`), with a colour and an author. */
+export type Mark =
+	| { arrow: string; color: MarkColour; author: MarkAuthor }
+	| { circle: string; color: MarkColour; author: MarkAuthor }
+	| { square: string; color: MarkColour; author: MarkAuthor };
+/** From White's side: centipawns, or moves to mate (negative when Black mates). */
+export type Eval = { cp: number } | { mate: number };
+export type Player = { name?: string; rating?: number };
+export type Players = { white: Player; black: Player };
+export type Mode = 'view' | 'play-white' | 'play-black' | 'play-both';
+export type Size = 'full' | 'phone' | 'embed' | 'thumb';
+export type Orientation = 'white' | 'black';
+export type Glyph = '!!' | '!' | '?!' | '?' | '??';
+/** A verdict on the move that ends a ply: a glyph, a comment, or both. */
+export type Annotation = { glyph?: Glyph; comment?: string };
+/** How the game on view ended, from its position alone: a resignation in a PGN isn't one. */
+export type Outcome = { result: '1-0' | '0-1' | '1/2-1/2'; reason: 'checkmate' | 'stalemate' | 'insufficient material' | 'repetition' | 'fifty moves' };
+
+/** The whole Board. set() takes any part of it; unknown fields are ignored. */
+export type State = {
+	/** The position on view: the game's at `ply` when there is a game. */
+	fen: string;
+	/** The game, when there is one: set as a PGN, or moves played from `fen`. */
+	pgn?: string;
+	/** Half-moves into the game on view, 0 to its length. */
+	ply?: number;
+	orientation: Orientation;
+	/** The move into the position on view, in UCI. */
+	lastMove: string | null;
+	marks: Mark[];
+	/** Verdicts by ply, shown while that ply is on view; left out when there are none. */
+	annotations?: Record<number, Annotation>;
+	/** null hides the eval bar; once shown it keeps its place, so the squares don't move. */
+	eval: Eval | null;
+	mode: Mode;
+	/** Shows the move list. */
+	moves: boolean;
+	/** Shows a row for each player, with captures and material; null hides them. */
+	players: Players | null;
+	size: Size;
+	/** Read only: how the game ended, left out while it goes on. */
+	outcome?: Outcome;
+};
+
+export type BoardEvents = {
+	/** The person's move, a promotion included; a premove arrives when it is played. */
+	move: { uci: string; san: string; fen: string; ply: number };
+	/** The person's Marks, after they drew or cleared one. */
+	marks: { marks: Mark[] };
+	/** The person stepped to another ply. */
+	ply: { ply: number; fen: string };
+	/** The person flipped the board. */
+	flip: { orientation: Orientation };
+	ready: { state: State };
+	error: { code: 'invalid_state' | 'illegal_move'; message: string };
+};
+export type BoardEvent = keyof BoardEvents;
+
+/** A patch for set(): any State fields, with `players: true` for plain rows, an eval as a number of centipawns,
+ * and arrows as { from, to } too. */
+export type StatePatch = Partial<Omit<State, 'marks' | 'players' | 'eval'>> & {
+	marks?: (Partial<Mark> | { from: string; to: string; color?: MarkColour })[];
+	players?: Partial<Players> | boolean | null;
+	eval?: Eval | number | null;
+	[unknown: string]: unknown;
+};
+
+/** <chessdrive-board>. Its animate(line) replaces Element.animate (Web Animations). */
+export interface ChessDriveBoardElement extends Omit<HTMLElement, 'animate'> {
+	/** The whole Board as one State: a copy, so changing it changes nothing. */
+	readonly state: State;
+	/** True once the Board is on the page; on('ready') after that is called at once. */
+	readonly ready: boolean;
+	/** Merges a partial State. Unknown fields are ignored; each bad value fires `error`. False if any did. */
+	set(patch: StatePatch): boolean;
+	/** Plays one legal move (SAN or UCI) from the position on view; an illegal one fires `error` and returns false. */
+	play(move: string): boolean;
+	/** Plays a line move by move; resolves false when it is illegal or cut short. */
+	animate(line: string[] | string): Promise<boolean>;
+	/** Removes the agent's Marks; the person's stay. */
+	clear(): void;
+	/** Listens for one of the Board's events; returns the function that stops listening. */
+	on<E extends BoardEvent>(name: E, fn: (detail: BoardEvents[E]) => void): () => void;
+}
+export declare const ChessDriveBoardElement: { prototype: ChessDriveBoardElement; new (): ChessDriveBoardElement };
+
+/** A new Board in `target`, at `state`. */
+export declare function create(target: Element, state?: StatePatch): ChessDriveBoardElement;
+/** The fragment, with its `#`, that opens `state` on chessdrive.io/board. */
+export declare function toFragment(state: State): string;
+/** A fragment as a patch for set(). */
+export declare function fromFragment(hash: string): StatePatch;
+/** An outcome in words: "Checkmate. White wins." */
+export declare function outcomeText(outcome: Outcome): string;
+/** The address of `state` on chessdrive.io/board, as the link back gives it. */
+export declare function boardLink(state: State, site: string): string;
+export declare const START_FEN: string;
+/** This build's version. */
+export declare const version: string;
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'chessdrive-board': ChessDriveBoardElement;
+	}
+	interface HTMLElementEventMap {
+		move: CustomEvent<BoardEvents['move']>;
+		marks: CustomEvent<BoardEvents['marks']>;
+		ply: CustomEvent<BoardEvents['ply']>;
+		flip: CustomEvent<BoardEvents['flip']>;
+		ready: CustomEvent<BoardEvents['ready']>;
+	}
+}