chess2img 0.2.2 → 0.3.0

package/README.md

@@ -50,7 +50,7 @@ const png = await renderChess({
     darkSquare: "#769656",
     highlight: "rgba(246, 246, 105, 0.6)",
   },
-  highlightSquares: ["e2", "e4"],
+  highlights: ["e2", "e4"],
 });
 
 await writeFile("board.png", png);
@@ -144,6 +144,38 @@ const png = await renderChess({
 await writeFile("board-with-inside-coordinates.png", png);
 ```
 
+### Circle Highlights
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { renderChess } from "chess2img";
+
+const png = await renderChess({
+  fen: "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
+  size: 480,
+  style: "cburnett",
+  highlights: [{ square: "e4", style: "circle" }],
+});
+
+await writeFile("board-with-circle-highlight.png", png);
+```
+
+### Combined Fill And Circle Highlights
+
+```ts
+import { writeFile } from "node:fs/promises";
+import { renderChess } from "chess2img";
+
+const png = await renderChess({
+  fen: "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
+  size: 480,
+  style: "cburnett",
+  highlights: ["e4", { square: "e4", style: "circle" }],
+});
+
+await writeFile("board-with-fill-and-circle-highlights.png", png);
+```
+
 ### Class API
 
 ```ts
@@ -241,7 +273,7 @@ Methods:
 - `loadFEN(fen: string): Promise<void>`
 - `loadPGN(pgn: string): Promise<void>`
 - `loadBoard(board: BoardArray): Promise<void>`
-- `setHighlights(squares: Square[]): void`
+- `setHighlights(highlights: HighlightInput[]): void`
 - `clearHighlights(): void`
 - `toBuffer(): Promise<Buffer>`
 - `toFile(filePath: string): Promise<void>`
@@ -261,7 +293,8 @@ Semantics:
 - `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"]`
+- `highlights`: array of square strings or highlight objects such as `["e4", { square: "d5", style: "circle" }]`
+- `highlightSquares`: compatibility alias for `highlights`
 - `coordinates`: `boolean`, `"border"`, `"inside"`, or `{ enabled?: boolean; position?: "border" | "inside"; color?: string }`
 - `colors.lightSquare`
 - `colors.darkSquare`
@@ -269,6 +302,8 @@ Semantics:
 
 `coordinates: false` or omitting the option disables labels. `coordinates: true` enables labels and chooses `border` mode when `borderSize > 0`, otherwise `inside` mode. Explicit `coordinates: "inside"` is always valid. Explicit `coordinates: "border"` requires `borderSize > 0` and throws `ValidationError` otherwise.
 
+`highlights` is the preferred API. Each entry may be a square string for a filled highlight, or an object with `square`, `style`, `color`, `opacity`, and `lineWidth`. `highlightSquares` remains available for backward compatibility, but should not be used together with `highlights` in the same call.
+
 Inside coordinates use automatic light/dark contrast by default, similar to chess.com. If `coordinates.color` is provided, that exact color is used instead. Border coordinates keep a single-color label style with `#333` as the default.
 
 At very small valid sizes, the renderer suppresses coordinates when they cannot fit legibly in the available border band or edge-square area.

package/dist/index.cjs

@@ -187,6 +187,12 @@ function isCoordinatesOptions(value) {
 function isCoordinatesPosition(value) {
   return value === "border" || value === "inside";
 }
+function isHighlightOptions(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHighlightStyle(value) {
+  return value === "fill" || value === "circle";
+}
 function validateCoordinatesOption(coordinates, borderSize) {
   if (coordinates === void 0 || typeof coordinates === "boolean") {
     return;
@@ -219,6 +225,49 @@ function validateCoordinatesOption(coordinates, borderSize) {
     validateColorString(coordinates.color, "coordinates.color");
   }
 }
+function validateHighlightEntry(entry) {
+  if (typeof entry === "string") {
+    validateSquare(entry);
+    return;
+  }
+  if (!isHighlightOptions(entry)) {
+    throw new ValidationError("highlights entries must be square strings or highlight objects");
+  }
+  if (typeof entry.square !== "string") {
+    throw new ValidationError("highlight.square must be a valid algebraic square");
+  }
+  validateSquare(entry.square);
+  if (entry.style !== void 0 && !isHighlightStyle(entry.style)) {
+    throw new ValidationError("highlight.style must be 'fill' or 'circle'");
+  }
+  if (entry.color !== void 0) {
+    validateColorString(entry.color, "highlight.color");
+  }
+  if (entry.opacity !== void 0 && (!Number.isFinite(entry.opacity) || entry.opacity < 0 || entry.opacity > 1)) {
+    throw new ValidationError("highlight.opacity must be a finite number between 0 and 1");
+  }
+  if (entry.lineWidth !== void 0 && (!Number.isFinite(entry.lineWidth) || entry.lineWidth <= 0)) {
+    throw new ValidationError("highlight.lineWidth must be a finite number greater than 0");
+  }
+}
+function validateHighlightOptions(highlights) {
+  if (highlights === void 0) {
+    return;
+  }
+  if (!Array.isArray(highlights)) {
+    throw new ValidationError("highlights must be an array");
+  }
+  for (const entry of highlights) {
+    validateHighlightEntry(entry);
+  }
+}
+function validateHighlightsInput(highlights, highlightSquares) {
+  if (highlights !== void 0 && highlightSquares !== void 0) {
+    throw new ValidationError("Use either highlights or highlightSquares, not both");
+  }
+  validateHighlightOptions(highlights);
+  validateHighlightOptions(highlightSquares);
+}
 
 // src/core/parsers.ts
 var PIECE_SYMBOL_TO_KEY = {
@@ -282,11 +331,6 @@ function parseBoardArray(board) {
   return position;
 }
 
-// src/core/highlights.ts
-function normalizeHighlights(input) {
-  return [...new Set(input.map(validateSquare))].sort();
-}
-
 // src/render/canvas-renderer.ts
 var import_canvas3 = require("canvas");
 
@@ -512,6 +556,19 @@ function resolveInsideLabelColor(request, square) {
   }
   return isDarkSquare(square) ? INSIDE_LIGHT_LABEL_COLOR : INSIDE_DARK_LABEL_COLOR;
 }
+function resolveHighlightOpacity(style, color, opacity) {
+  if (opacity !== void 0) {
+    return opacity;
+  }
+  if (style === "circle" || color !== void 0) {
+    return 0.9;
+  }
+  return 1;
+}
+function resolveCircleLineWidth(squareSize, lineWidth) {
+  const candidate = lineWidth ?? squareSize * 0.08;
+  return Math.max(2, Math.min(8, candidate));
+}
 function resolveBorderCoordinateFontSize(context, geometry) {
   const maxFontSize = Math.floor(
     Math.min(geometry.squareSize * 0.6, geometry.borderSize * 0.65)
@@ -608,6 +665,93 @@ function drawCoordinates(context, request, geometry) {
   }
   drawInsideCoordinates(context, request, geometry);
 }
+function drawBoardSquares(context, request, geometry) {
+  for (const square of SQUARES) {
+    const squareGeometry = geometry.squares[square];
+    context.fillStyle = isDarkSquare(square) ? request.colors.darkSquare : request.colors.lightSquare;
+    context.fillRect(
+      squareGeometry.x,
+      squareGeometry.y,
+      squareGeometry.size,
+      squareGeometry.size
+    );
+  }
+}
+function drawFillHighlights(context, request, geometry) {
+  for (const highlight of request.highlights) {
+    if (highlight.style !== "fill") {
+      continue;
+    }
+    const squareGeometry = geometry.squares[highlight.square];
+    context.save();
+    context.globalAlpha = resolveHighlightOpacity(
+      highlight.style,
+      highlight.color,
+      highlight.opacity
+    );
+    context.fillStyle = highlight.color ?? request.colors.highlight;
+    context.fillRect(
+      squareGeometry.x,
+      squareGeometry.y,
+      squareGeometry.size,
+      squareGeometry.size
+    );
+    context.restore();
+  }
+}
+function drawCircleHighlights(context, request, geometry) {
+  for (const highlight of request.highlights) {
+    if (highlight.style !== "circle") {
+      continue;
+    }
+    const squareGeometry = geometry.squares[highlight.square];
+    const centerX = squareGeometry.x + squareGeometry.size / 2;
+    const centerY = squareGeometry.y + squareGeometry.size / 2;
+    context.save();
+    context.globalAlpha = resolveHighlightOpacity(
+      highlight.style,
+      highlight.color,
+      highlight.opacity
+    );
+    context.strokeStyle = highlight.color ?? "#ffcc00";
+    context.lineWidth = resolveCircleLineWidth(
+      squareGeometry.size,
+      highlight.lineWidth
+    );
+    context.beginPath();
+    context.arc(
+      centerX,
+      centerY,
+      squareGeometry.size * 0.32,
+      0,
+      Math.PI * 2
+    );
+    context.stroke();
+    context.restore();
+  }
+}
+async function drawPieces(context, request, geometry) {
+  for (const square of SQUARES) {
+    const squareGeometry = geometry.squares[square];
+    const pieceKey = request.board.squares[square];
+    if (!pieceKey) {
+      continue;
+    }
+    const raster = await getPieceRaster(
+      request.theme.name,
+      pieceKey,
+      request.theme.pieces[pieceKey],
+      Math.round(geometry.squareSize)
+    );
+    context.drawImage(
+      raster,
+      squareGeometry.x,
+      squareGeometry.y,
+      squareGeometry.size,
+      squareGeometry.size
+    );
+  }
+}
 var CanvasPngRenderer = class {
   async render(request) {
     try {
@@ -621,43 +765,11 @@ var CanvasPngRenderer = class {
       const context = canvas.getContext("2d");
       context.fillStyle = request.colors.lightSquare;
       context.fillRect(0, 0, geometry.imageWidth, geometry.imageHeight);
-      for (const square of SQUARES) {
-        const squareGeometry = geometry.squares[square];
-        context.fillStyle = isDarkSquare(square) ? request.colors.darkSquare : request.colors.lightSquare;
-        context.fillRect(
-          squareGeometry.x,
-          squareGeometry.y,
-          squareGeometry.size,
-          squareGeometry.size
-        );
-        if (request.highlights.includes(square)) {
-          context.fillStyle = request.colors.highlight;
-          context.fillRect(
-            squareGeometry.x,
-            squareGeometry.y,
-            squareGeometry.size,
-            squareGeometry.size
-          );
-        }
-        const pieceKey = request.board.squares[square];
-        if (!pieceKey) {
-          continue;
-        }
-        const raster = await getPieceRaster(
-          request.theme.name,
-          pieceKey,
-          request.theme.pieces[pieceKey],
-          Math.round(geometry.squareSize)
-        );
-        context.drawImage(
-          raster,
-          squareGeometry.x,
-          squareGeometry.y,
-          squareGeometry.size,
-          squareGeometry.size
-        );
-      }
+      drawBoardSquares(context, request, geometry);
+      drawFillHighlights(context, request, geometry);
+      drawCircleHighlights(context, request, geometry);
       drawCoordinates(context, request, geometry);
+      await drawPieces(context, request, geometry);
       return canvas.toBuffer("image/png");
     } catch (error) {
       if (error instanceof RenderError) {
@@ -678,6 +790,26 @@ async function writeBufferToFile(filePath, buffer) {
   }
 }
 
+// src/core/highlights.ts
+function normalizeHighlightEntries(input) {
+  return input.map((entry) => {
+    if (typeof entry === "string") {
+      return {
+        square: validateSquare(entry),
+        style: "fill"
+      };
+    }
+    const style = entry.style ?? "fill";
+    return {
+      square: validateSquare(entry.square),
+      style,
+      color: entry.color ?? (style === "circle" ? "#ffcc00" : void 0),
+      opacity: entry.opacity ?? (style === "circle" ? 0.9 : void 0),
+      lineWidth: entry.lineWidth
+    };
+  });
+}
+
 // src/themes/builtins.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
@@ -863,6 +995,9 @@ function normalizeCoordinates(coordinates, borderSize) {
     color: coordinates.color ?? (position === "border" ? "#333" : void 0)
   };
 }
+function normalizeHighlightEntries2(highlights) {
+  return normalizeHighlightEntries(highlights ?? []);
+}
 function normalizeRenderInputs(options) {
   const size = validateSize(options.size ?? DEFAULT_SIZE);
   const borderSize = validateBorderSize(
@@ -871,6 +1006,8 @@ function normalizeRenderInputs(options) {
   );
   validateBoardColors(options.colors);
   validateCoordinatesOption(options.coordinates, borderSize);
+  validateHighlightsInput(options.highlights, options.highlightSquares);
+  const highlightInput = options.highlights ?? options.highlightSquares;
   return {
     size,
     padding: normalizePadding(options.padding ?? DEFAULT_PADDING),
@@ -880,7 +1017,7 @@ function normalizeRenderInputs(options) {
       theme: options.theme,
       style: options.style
     }),
-    highlightSquares: normalizeHighlights(options.highlightSquares ?? []),
+    highlights: normalizeHighlightEntries2(highlightInput),
     colors: normalizeColors(options.colors),
     coordinates: normalizeCoordinates(options.coordinates, borderSize)
   };
@@ -893,10 +1030,7 @@ var ChessImageGenerator = class {
   highlights = [];
   constructor(options = {}) {
     this.defaults = { ...options };
-    normalizeRenderInputs({
-      ...this.defaults,
-      highlightSquares: []
-    });
+    normalizeRenderInputs(this.defaults);
   }
   async loadFEN(fen) {
     this.position = parseFEN(fen);
@@ -910,8 +1044,9 @@ var ChessImageGenerator = class {
     this.position = parseBoardArray(board);
     this.clearHighlights();
   }
-  setHighlights(squares) {
-    this.highlights = normalizeHighlights(squares);
+  setHighlights(highlights) {
+    validateHighlightsInput(highlights, void 0);
+    this.highlights = [...highlights];
   }
   clearHighlights() {
     this.highlights = [];
@@ -923,12 +1058,13 @@ var ChessImageGenerator = class {
     const renderer = new CanvasPngRenderer();
     const normalized = normalizeRenderInputs({
       ...this.defaults,
-      highlightSquares: this.highlights
+      highlights: this.highlights,
+      highlightSquares: void 0
     });
     return renderer.render({
       board: this.position,
       theme: normalized.theme,
-      highlights: normalized.highlightSquares,
+      highlights: normalized.highlights,
       size: normalized.size,
       padding: normalized.padding,
       borderSize: normalized.borderSize,
@@ -971,7 +1107,7 @@ async function renderChess(options) {
   return renderer.render({
     board: position,
     theme: normalized.theme,
-    highlights: normalized.highlightSquares,
+    highlights: normalized.highlights,
     size: normalized.size,
     padding: normalized.padding,
     borderSize: normalized.borderSize,