chess2img 0.2.2 → 0.3.0

package/dist/index.js

@@ -161,6 +161,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;
@@ -193,6 +199,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 = {
@@ -256,11 +305,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
 import { createCanvas as createCanvas3 } from "canvas";
 
@@ -486,6 +530,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)
@@ -582,6 +639,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 {
@@ -595,43 +739,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) {
@@ -652,6 +764,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
 import { existsSync } from "fs";
 import { resolve } from "path";
@@ -837,6 +969,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(
@@ -845,6 +980,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),
@@ -854,7 +991,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)
   };
@@ -867,10 +1004,7 @@ var ChessImageGenerator = class {
   highlights = [];
   constructor(options = {}) {
     this.defaults = { ...options };
-    normalizeRenderInputs({
-      ...this.defaults,
-      highlightSquares: []
-    });
+    normalizeRenderInputs(this.defaults);
   }
   async loadFEN(fen) {
     this.position = parseFEN(fen);
@@ -884,8 +1018,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 = [];
@@ -897,12 +1032,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,
@@ -945,7 +1081,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,