chess2img 0.1.1 → 0.1.3

package/README.md

@@ -1,145 +1,131 @@
 # chess2img
 
-Modern chess board image rendering for Node.js.
+<div align="center">
+  <img src="./assets/themes/cburnett/wK.png" alt="chess2img king icon" width="88" />
+  <p>Generate PNG chessboard images from FEN, PGN, or board arrays in Node.js.</p>
+  <p>
+    <a href="https://www.npmjs.com/package/chess2img"><img src="https://img.shields.io/npm/v/chess2img" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/chess2img"><img src="https://img.shields.io/npm/dm/chess2img" alt="npm downloads" /></a>
+    <a href="https://www.npmjs.com/package/chess2img"><img src="https://img.shields.io/npm/l/chess2img" alt="license" /></a>
+    <a href="https://github.com/ZiriloXXX/chess2img"><img src="https://img.shields.io/github/stars/ZiriloXXX/chess2img" alt="GitHub stars" /></a>
+  </p>
+</div>
 
-`chess2img` renders PNG chess board images from FEN, PGN, or board-array inputs with a small Promise-based API for both JavaScript and TypeScript users.
+## Overview
 
-## Installation
+`chess2img` renders chessboard PNGs from FEN, PGN, or board-array inputs with a small Promise-based API for JavaScript and TypeScript users on Node.js.
 
-```bash
-npm install chess2img
-```
+## Features
 
-## Node And Canvas Requirements
+- Render PNG chessboard images from `fen`, `pgn`, or `board` input.
+- Use five bundled built-in themes: `merida`, `alpha`, `cburnett`, `cheq`, and `leipzig`.
+- Highlight squares such as the last move or key tactical ideas.
+- Customize board colors, size, padding, and board orientation.
+- Use either the functional `renderChess(...)` API or the `ChessImageGenerator` class API.
+- Register custom themes globally or pass a theme inline for one-off rendering.
+- Consume the package from both JavaScript and TypeScript projects.
 
-- Node.js `18+`
-- native build support for `canvas`
-- common Linux packages usually include Cairo, Pango, libpng, libjpeg, giflib, a C/C++ toolchain, and Python for `node-gyp`
+## Example Output
 
-If `canvas` fails to install, verify your system packages first. The library ships `canvas` as a direct dependency, but native prerequisites still need to exist on the host.
+Opening `1.e4` with a Chess.com-like board palette, highlighted origin and destination squares, and the built-in `cburnett` piece set.
+
+<img src="./assets/readme/chesscom-opening-e4-cburnett.png" alt="Opening 1.e4 example board" width="480" />
 
 ## Quick Start
 
+```bash
+npm install chess2img
+```
+
 ```ts
+import { writeFile } from "node:fs/promises";
 import { renderChess } from "chess2img";
 
-const buffer = await renderChess({
-  fen: "4k3/8/8/8/8/8/8/4K3 w - - 0 1",
+const png = await renderChess({
+  fen: "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
   size: 480,
-  style: "merida",
+  style: "cburnett",
+  colors: {
+    lightSquare: "#EEEED2",
+    darkSquare: "#769656",
+    highlight: "rgba(246, 246, 105, 0.6)",
+  },
+  highlightSquares: ["e2", "e4"],
 });
+
+await writeFile("board.png", png);
 ```
 
-## JavaScript Usage
+`renderChess(...)` returns a `Promise<Buffer>` containing PNG data.
 
-```js
-const { ChessImageGenerator } = require("chess2img");
+## Installation
 
-async function main() {
-  const generator = new ChessImageGenerator({
-    size: 800,
-    style: "alpha",
-  });
+```bash
+npm install chess2img
+```
 
-  await generator.loadPGN("1. e4 e5 2. Nf3 Nc6 3. Bb5 a6");
-  generator.setHighlights(["e4", "e5"]);
+### Node And Canvas Requirements
 
-  const buffer = await generator.toBuffer();
-  await generator.toFile("board.png");
-}
+- Node.js `18+`
+- native build support for `canvas`
+- common Linux packages usually include Cairo, Pango, libpng, libjpeg, giflib, a C/C++ toolchain, and Python for `node-gyp`
 
-main().catch(console.error);
-```
+If `canvas` fails to install, verify your system packages first. The library ships `canvas` as a direct dependency, but native prerequisites still need to exist on the host.
 
-## TypeScript Usage
+## Basic Usage
+
+### Functional API
 
 ```ts
-import { ChessImageGenerator, renderChess } from "chess2img";
-
-const buffer = await renderChess({
-  board: [
-    ["r", "n", "b", "q", "k", "b", "n", "r"],
-    ["p", "p", "p", "p", "p", "p", "p", "p"],
-    [null, null, null, null, null, null, null, null],
-    [null, null, null, null, null, null, null, null],
-    [null, null, null, null, null, null, null, null],
-    [null, null, null, null, null, null, null, null],
-    ["P", "P", "P", "P", "P", "P", "P", "P"],
-    ["R", "N", "B", "Q", "K", "B", "N", "R"],
-  ],
-  size: 640,
-  style: "cburnett",
+import { writeFile } from "node:fs/promises";
+import { renderChess } from "chess2img";
+
+const png = await renderChess({
+  fen: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
+  size: 480,
+  style: "merida",
 });
 
-const generator = new ChessImageGenerator({ size: 640, theme: "leipzig" });
-await generator.loadFEN("4k3/8/8/3p4/4P3/8/8/4K3 w - - 0 1");
-await generator.toFile("board.png");
+await writeFile("board.png", png);
 ```
 
-## API
-
 ### Class API
 
 ```ts
+import { ChessImageGenerator } from "chess2img";
+
 const generator = new ChessImageGenerator({
   size: 800,
-  style: "merida",
-  flipped: false,
+  style: "alpha",
 });
 
-await generator.loadFEN(fen);
-generator.setHighlights(["e4", "d5"]);
+await generator.loadPGN("1. e4 e5 2. Nf3 Nc6 3. Bb5 a6");
+generator.setHighlights(["e4", "e5"]);
 
-const buffer = await generator.toBuffer();
 await generator.toFile("board.png");
 ```
 
-Methods:
-
-- `loadFEN(fen: string): Promise<void>`
-- `loadPGN(pgn: string): Promise<void>`
-- `loadBoard(board: BoardArray): Promise<void>`
-- `setHighlights(squares: Square[]): void`
-- `clearHighlights(): void`
-- `toBuffer(): Promise<Buffer>`
-- `toFile(filePath: string): Promise<void>`
+### JavaScript Usage
 
-Semantics:
+```js
+const { renderChess } = require("chess2img");
+const { writeFile } = require("node:fs/promises");
 
-- `setHighlights` replaces the current highlight set
-- `clearHighlights` removes all highlights
-- loading a new position clears highlights
-- constructor defaults persist across position loads
+async function main() {
+  const png = await renderChess({
+    fen: "4k3/8/8/8/8/8/8/4K3 w - - 0 1",
+    style: "merida",
+  });
 
-### Functional API
+  await writeFile("board.png", png);
+}
 
-```ts
-const buffer = await renderChess({
-  fen,
-  size: 800,
-  style: "merida",
-});
+main().catch(console.error);
 ```
 
-`renderChess` accepts exactly one of:
-
-- `fen`
-- `pgn`
-- `board`
-
-## Options Reference
-
-- `size`: board size in pixels
-- `padding`: `[top, right, bottom, left]`
-- `flipped`: render from black's perspective when `true`
-- `style`: built-in theme alias
-- `theme`: built-in theme name, registered custom theme name, or inline `ThemeDefinition`
-- `highlightSquares`: array of algebraic squares such as `["e4", "d5"]`
-- `colors.lightSquare`
-- `colors.darkSquare`
-- `colors.highlight`
+## Built-In Themes
 
-## Built-In Styles
+Bundled built-in themes:
 
 - `merida`
 - `alpha`
@@ -147,6 +133,8 @@ const buffer = await renderChess({
 - `cheq`
 - `leipzig`
 
+Built-in themes are vendored in-package and render through the same theme pipeline as custom themes.
+
 ## Custom Themes
 
 Register a reusable theme globally:
@@ -158,7 +146,7 @@ registerTheme({
   name: "custom-theme",
   displayName: "Custom Theme",
   license: "MIT",
-  attribution: "Project-authored",
+  attribution: "Theme author or package source",
   pieces: {
     // 12 canonical pieces required
   },
@@ -175,7 +163,54 @@ Custom themes may use either:
 - `svg` assets
 - `png` assets
 
-## Error Model
+## API
+
+### Public Exports
+
+- `new ChessImageGenerator(options?)`
+- `renderChess(options)`
+- `registerTheme(theme)`
+
+### Functional API
+
+`renderChess(...)` accepts exactly one position source:
+
+- `fen`
+- `pgn`
+- `board`
+
+### Class API
+
+Methods:
+
+- `loadFEN(fen: string): Promise<void>`
+- `loadPGN(pgn: string): Promise<void>`
+- `loadBoard(board: BoardArray): Promise<void>`
+- `setHighlights(squares: Square[]): void`
+- `clearHighlights(): void`
+- `toBuffer(): Promise<Buffer>`
+- `toFile(filePath: string): Promise<void>`
+
+Semantics:
+
+- `setHighlights` replaces the current highlight set
+- `clearHighlights` removes all highlights
+- loading a new position clears highlights
+- constructor defaults persist across position loads
+
+### Options
+
+- `size`: board size in pixels
+- `padding`: `[top, right, bottom, left]`
+- `flipped`: render from black's perspective when `true`
+- `style`: built-in theme alias
+- `theme`: built-in theme name, registered custom theme name, or inline `ThemeDefinition`
+- `highlightSquares`: array of algebraic squares such as `["e4", "d5"]`
+- `colors.lightSquare`
+- `colors.darkSquare`
+- `colors.highlight`
+
+### Errors
 
 The library exports:
 
@@ -185,30 +220,8 @@ The library exports:
 - `RenderError`
 - `IOError`
 
-## Architecture Summary
-
-- `core` parses and validates chess position input into a canonical board model
-- `themes` validates, registers, and resolves built-in or custom themes
-- `render` rasterizes SVG or PNG theme assets and renders PNG output through `canvas`
-- `api` orchestrates parsing, theme resolution, rendering, and file output
-
-## Migration From `chess-image-generator`
-
-| Old | New | Difference |
-| --- | --- | --- |
-| `loadArray` | `loadBoard` | renamed for clarity |
-| `highlightSquares([...])` | `setHighlights([...])` | replacement semantics are explicit |
-| `generateBuffer()` | `toBuffer()` | same role, new naming |
-| `generatePNG(path)` | `toFile(path)` | IO is explicit in the API name |
-| `style` only | `style` or `theme` | `theme` is the canonical path |
-
-## Troubleshooting
-
-- `canvas` install failures usually indicate missing native prerequisites on the host
-- `ValidationError` from `renderChess` usually means multiple position inputs were provided or an option shape is invalid
-- `ThemeError` usually indicates an unknown theme name or an incomplete custom theme definition
-- `RenderError` usually indicates asset decoding/rasterization problems
+## License
 
-## Asset Attribution
+`chess2img` is distributed under the MIT license in package metadata.
 
-Bundled built-in themes are derived from the upstream `andyruwruw/chess-image-generator` resource packs and are vendored in-package for deterministic installs. Provenance and licensing notes live in [ATTRIBUTION.md](/root/Chess2img/ATTRIBUTION.md).
+Bundled built-in themes are derived from the upstream `andyruwruw/chess-image-generator` resource packs and are vendored in-package for deterministic installs. Provenance and licensing notes live in [ATTRIBUTION.md](./ATTRIBUTION.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chess2img",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Modern chess board image rendering for Node.js",
   "license": "MIT",
   "repository": {
@@ -11,6 +11,16 @@
     "url": "https://github.com/ZiriloXXX/chess2img/issues"
   },
   "homepage": "https://github.com/ZiriloXXX/chess2img#readme",
+  "keywords": [
+    "chess",
+    "chessboard",
+    "fen",
+    "pgn",
+    "png",
+    "image",
+    "chess-image",
+    "chess-render"
+  ],
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",