chess2img 0.1.4 → 0.2.1

package/README.md

@@ -20,7 +20,7 @@
 - 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.
+- Customize board colors, size, padding, border sizing, coordinates, 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.
@@ -89,6 +89,61 @@ const png = await renderChess({
 await writeFile("board.png", png);
 ```
 
+### Automatic Coordinates
+
+```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",
+  coordinates: true,
+});
+
+await writeFile("board-with-auto-coordinates.png", png);
+```
+
+`coordinates: true` chooses `border` mode when `borderSize > 0`, otherwise it falls back to `inside` mode.
+
+### Border Coordinates
+
+```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",
+  borderSize: 24,
+  coordinates: {
+    enabled: true,
+    position: "border",
+    color: "#333",
+  },
+});
+
+await writeFile("board-with-border-coordinates.png", png);
+```
+
+### Inside Coordinates
+
+```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",
+  coordinates: "inside",
+});
+
+await writeFile("board-with-inside-coordinates.png", png);
+```
+
 ### Class API
 
 ```ts
@@ -202,14 +257,22 @@ Semantics:
 
 - `size`: board size in pixels
 - `padding`: `[top, right, bottom, left]`
+- `borderSize`: inner border size in pixels, from `0` up to `Math.floor(size / 8)`
 - `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"]`
+- `coordinates`: `boolean`, `"border"`, `"inside"`, or `{ enabled?: boolean; position?: "border" | "inside"; color?: string }`
 - `colors.lightSquare`
 - `colors.darkSquare`
 - `colors.highlight`
 
+`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.
+
+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.
+
 ### Errors
 
 The library exports:

package/dist/index.cjs

@@ -81,8 +81,10 @@ function createEmptyBoardPosition() {
 }
 
 // src/core/validators.ts
+var import_canvas = require("canvas");
 var SQUARE_PATTERN = /^[a-h][1-8]$/;
 var PIECE_PATTERN = /^[prnbqkPRNBQK]$/;
+var colorValidationContext = (0, import_canvas.createCanvas)(1, 1).getContext("2d");
 function validateSize(size) {
   if (!Number.isFinite(size) || size <= 0) {
     throw new ValidationError(`Invalid board size: ${size}`);
@@ -135,6 +137,88 @@ function validateThemeName(name) {
   }
   return normalized;
 }
+function validateBorderSize(borderSize, size) {
+  const normalizedSize = validateSize(size);
+  const normalizedBorderSize = Math.round(borderSize);
+  const maxBorderSize = Math.floor(normalizedSize / 8);
+  if (!Number.isFinite(borderSize) || normalizedBorderSize < 0) {
+    throw new ValidationError(`Invalid borderSize: ${borderSize}`);
+  }
+  if (normalizedBorderSize > maxBorderSize) {
+    throw new ValidationError(
+      `Invalid borderSize: ${borderSize}. Maximum allowed for size ${normalizedSize} is ${maxBorderSize}`
+    );
+  }
+  return normalizedBorderSize;
+}
+function validateColorString(color, label = "color") {
+  if (typeof color !== "string" || color.trim() === "") {
+    throw new ValidationError(`Invalid ${label}: ${String(color)}`);
+  }
+  const normalized = color.trim();
+  colorValidationContext.fillStyle = "#010203";
+  colorValidationContext.fillStyle = normalized;
+  const firstPass = String(colorValidationContext.fillStyle);
+  colorValidationContext.fillStyle = "#fefefe";
+  colorValidationContext.fillStyle = normalized;
+  const secondPass = String(colorValidationContext.fillStyle);
+  if (firstPass !== secondPass) {
+    throw new ValidationError(`Invalid ${label}: ${color}`);
+  }
+  return normalized;
+}
+function validateBoardColors(colors) {
+  if (!colors) {
+    return;
+  }
+  if (colors.lightSquare !== void 0) {
+    validateColorString(colors.lightSquare, "lightSquare color");
+  }
+  if (colors.darkSquare !== void 0) {
+    validateColorString(colors.darkSquare, "darkSquare color");
+  }
+  if (colors.highlight !== void 0) {
+    validateColorString(colors.highlight, "highlight color");
+  }
+}
+function isCoordinatesOptions(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCoordinatesPosition(value) {
+  return value === "border" || value === "inside";
+}
+function validateCoordinatesOption(coordinates, borderSize) {
+  if (coordinates === void 0 || typeof coordinates === "boolean") {
+    return;
+  }
+  if (isCoordinatesPosition(coordinates)) {
+    if (coordinates === "border" && borderSize === 0) {
+      throw new ValidationError(
+        "coordinates position 'border' requires borderSize > 0"
+      );
+    }
+    return;
+  }
+  if (!isCoordinatesOptions(coordinates)) {
+    throw new ValidationError(
+      "coordinates must be false, true, 'border', 'inside', or an options object"
+    );
+  }
+  if (coordinates.enabled !== void 0 && typeof coordinates.enabled !== "boolean") {
+    throw new ValidationError("coordinates.enabled must be a boolean");
+  }
+  if (coordinates.position !== void 0 && !isCoordinatesPosition(coordinates.position)) {
+    throw new ValidationError("coordinates.position must be 'border' or 'inside'");
+  }
+  if (coordinates.enabled !== false && coordinates.position === "border" && borderSize === 0) {
+    throw new ValidationError(
+      "coordinates position 'border' requires borderSize > 0"
+    );
+  }
+  if (coordinates.color !== void 0) {
+    validateColorString(coordinates.color, "coordinates.color");
+  }
+}
 
 // src/core/parsers.ts
 var PIECE_SYMBOL_TO_KEY = {
@@ -204,32 +288,103 @@ function normalizeHighlights(input) {
 }
 
 // src/render/canvas-renderer.ts
-var import_canvas2 = require("canvas");
+var import_canvas3 = require("canvas");
 
 // src/core/geometry.ts
 function createBoardGeometry({
   size,
   padding,
+  borderSize,
   flipped
 }) {
   const [top, right, bottom, left] = padding;
-  const squareSize = size / 8;
+  const boardOuterSize = size;
+  const boardOuterX = left;
+  const boardOuterY = top;
+  const boardX = left + borderSize;
+  const boardY = top + borderSize;
+  const boardSize = size - borderSize * 2;
+  const squareSize = boardSize / 8;
   const squares = Object.fromEntries(
     SQUARES.map((square, index) => {
       const fileIndex = index % 8;
       const rankIndex = Math.floor(index / 8);
-      const x = left + (flipped ? 7 - fileIndex : fileIndex) * squareSize;
-      const y = top + (flipped ? 7 - rankIndex : rankIndex) * squareSize;
+      const x = boardX + (flipped ? 7 - fileIndex : fileIndex) * squareSize;
+      const y = boardY + (flipped ? 7 - rankIndex : rankIndex) * squareSize;
       return [square, { x, y, size: squareSize }];
     })
   );
+  const displayedFiles = flipped ? [...FILES].reverse() : [...FILES];
+  const displayedRanks = flipped ? [...RANKS].reverse() : [...RANKS];
+  const bottomEdgeRank = flipped ? "8" : "1";
+  const leftEdgeFile = flipped ? "h" : "a";
+  const borderFileLabels = borderSize ? displayedFiles.map((file, fileIndex) => ({
+    text: file,
+    x: boardX + fileIndex * squareSize + squareSize / 2,
+    y: boardOuterY + boardOuterSize - borderSize / 2,
+    square: `${file}${bottomEdgeRank}`,
+    textAlign: "center",
+    textBaseline: "middle"
+  })) : [];
+  const borderRankLabels = borderSize ? displayedRanks.map((rank, rankIndex) => ({
+    text: rank,
+    x: boardOuterX + borderSize / 2,
+    y: boardY + rankIndex * squareSize + squareSize / 2,
+    square: `${leftEdgeFile}${rank}`,
+    textAlign: "center",
+    textBaseline: "middle"
+  })) : [];
+  const insideFileInsetX = squareSize * 0.14;
+  const insideFileInsetY = squareSize * 0.1;
+  const insideRankInsetX = squareSize * 0.14;
+  const insideRankInsetY = squareSize * 0.1;
+  const insideLabelMaxWidth = squareSize * 0.26;
+  const insideLabelMaxHeight = squareSize * 0.24;
+  const insideFileLabels = displayedFiles.map((file) => {
+    const square = `${file}${bottomEdgeRank}`;
+    const squareGeometry = squares[square];
+    return {
+      text: file,
+      x: squareGeometry.x + insideFileInsetX,
+      y: squareGeometry.y + squareGeometry.size - insideFileInsetY,
+      square,
+      textAlign: "left",
+      textBaseline: "bottom"
+    };
+  });
+  const insideRankLabels = displayedRanks.map((rank) => {
+    const square = `${leftEdgeFile}${rank}`;
+    const squareGeometry = squares[square];
+    return {
+      text: rank,
+      x: squareGeometry.x + insideRankInsetX,
+      y: squareGeometry.y + insideRankInsetY,
+      square,
+      textAlign: "left",
+      textBaseline: "top"
+    };
+  });
   return {
     imageWidth: left + size + right,
     imageHeight: top + size + bottom,
     squareSize,
-    boardX: left,
-    boardY: top,
-    boardSize: size,
+    borderSize,
+    boardOuterX,
+    boardOuterY,
+    boardOuterSize,
+    boardX,
+    boardY,
+    boardSize,
+    borderFileLabels,
+    borderRankLabels,
+    insideFileLabels,
+    insideRankLabels,
+    insideFileInsetX,
+    insideFileInsetY,
+    insideRankInsetX,
+    insideRankInsetY,
+    insideLabelMaxWidth,
+    insideLabelMaxHeight,
     squares
   };
 }
@@ -259,7 +414,7 @@ var SourceAssetCache = class {
 
 // src/render/rasterizer.ts
 var import_promises = require("fs/promises");
-var import_canvas = require("canvas");
+var import_canvas2 = require("canvas");
 var import_resvg_js = require("@resvg/resvg-js");
 var svgSourceCache = new SourceAssetCache();
 var imageBufferCache = new SourceAssetCache();
@@ -299,8 +454,8 @@ async function rasterizeSvgAsset(filePath, squareSize) {
       }
     });
     const pngBuffer = resvg.render().asPng();
-    const image = await (0, import_canvas.loadImage)(pngBuffer);
-    const canvas = (0, import_canvas.createCanvas)(squareSize, squareSize);
+    const image = await (0, import_canvas2.loadImage)(pngBuffer);
+    const canvas = (0, import_canvas2.createCanvas)(squareSize, squareSize);
     const context = canvas.getContext("2d");
     context.drawImage(image, 0, 0, squareSize, squareSize);
     return canvas;
@@ -311,8 +466,8 @@ async function rasterizeSvgAsset(filePath, squareSize) {
 async function rasterizePngAsset(filePath, squareSize) {
   try {
     const pngSource = await readBinaryAsset(filePath);
-    const image = await (0, import_canvas.loadImage)(pngSource);
-    const canvas = (0, import_canvas.createCanvas)(squareSize, squareSize);
+    const image = await (0, import_canvas2.loadImage)(pngSource);
+    const canvas = (0, import_canvas2.createCanvas)(squareSize, squareSize);
     const context = canvas.getContext("2d");
     context.drawImage(image, 0, 0, squareSize, squareSize);
     return canvas;
@@ -329,6 +484,13 @@ async function rasterizeThemeAsset(asset, squareSize) {
 
 // src/render/canvas-renderer.ts
 var pieceRasterCache = new RasterAssetCache();
+var MIN_COORDINATE_FONT_SIZE = 8;
+var MAX_FILE_LABEL_WIDTH_RATIO = 0.75;
+var MAX_RANK_LABEL_WIDTH_RATIO = 0.7;
+var MAX_LABEL_HEIGHT_RATIO = 0.7;
+var INSIDE_COORDINATE_MAX_FONT_RATIO = 0.34;
+var INSIDE_LIGHT_LABEL_COLOR = "rgba(255,255,255,0.6)";
+var INSIDE_DARK_LABEL_COLOR = "rgba(0,0,0,0.45)";
 function isDarkSquare(square) {
   const fileIndex = square.charCodeAt(0) - 97;
   const rankNumber = Number(square[1]);
@@ -344,15 +506,118 @@ async function getPieceRaster(themeName, pieceKey, asset, squareSize) {
   pieceRasterCache.set(cacheKey, raster);
   return raster;
 }
+function resolveInsideLabelColor(request, square) {
+  if (request.coordinates.color) {
+    return request.coordinates.color;
+  }
+  return isDarkSquare(square) ? INSIDE_LIGHT_LABEL_COLOR : INSIDE_DARK_LABEL_COLOR;
+}
+function resolveBorderCoordinateFontSize(context, geometry) {
+  const maxFontSize = Math.floor(
+    Math.min(geometry.squareSize * 0.6, geometry.borderSize * 0.65)
+  );
+  let fontSize = null;
+  for (let candidate = maxFontSize; candidate >= MIN_COORDINATE_FONT_SIZE; candidate -= 1) {
+    context.font = `${candidate}px sans-serif`;
+    const filesFit = geometry.borderFileLabels.every((label) => {
+      const metrics = context.measureText(label.text);
+      const textHeight = metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent;
+      return metrics.width <= geometry.squareSize * MAX_FILE_LABEL_WIDTH_RATIO && textHeight <= geometry.borderSize * MAX_LABEL_HEIGHT_RATIO;
+    });
+    const ranksFit = geometry.borderRankLabels.every((label) => {
+      const metrics = context.measureText(label.text);
+      const textHeight = metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent;
+      return metrics.width <= geometry.borderSize * MAX_RANK_LABEL_WIDTH_RATIO && textHeight <= geometry.squareSize * MAX_LABEL_HEIGHT_RATIO;
+    });
+    if (filesFit && ranksFit) {
+      fontSize = candidate;
+      break;
+    }
+  }
+  return fontSize;
+}
+function resolveInsideCoordinateFontSize(context, geometry) {
+  const maxFontSize = Math.floor(
+    geometry.squareSize * INSIDE_COORDINATE_MAX_FONT_RATIO
+  );
+  let fontSize = null;
+  for (let candidate = maxFontSize; candidate >= MIN_COORDINATE_FONT_SIZE; candidate -= 1) {
+    context.font = `${candidate}px sans-serif`;
+    const filesFit = geometry.insideFileLabels.every((label) => {
+      const metrics = context.measureText(label.text);
+      const textHeight = metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent;
+      return metrics.width <= geometry.insideLabelMaxWidth && textHeight <= geometry.insideLabelMaxHeight;
+    });
+    const ranksFit = geometry.insideRankLabels.every((label) => {
+      const metrics = context.measureText(label.text);
+      const textHeight = metrics.actualBoundingBoxAscent + metrics.actualBoundingBoxDescent;
+      return metrics.width <= geometry.insideLabelMaxWidth && textHeight <= geometry.insideLabelMaxHeight;
+    });
+    if (filesFit && ranksFit) {
+      fontSize = candidate;
+      break;
+    }
+  }
+  return fontSize;
+}
+function drawBorderCoordinates(context, request, geometry) {
+  if (geometry.borderSize === 0) {
+    return;
+  }
+  const fontSize = resolveBorderCoordinateFontSize(context, geometry);
+  if (fontSize === null) {
+    return;
+  }
+  context.fillStyle = request.coordinates.color ?? "#333";
+  context.font = `${fontSize}px sans-serif`;
+  context.textAlign = "center";
+  context.textBaseline = "middle";
+  for (const label of geometry.borderFileLabels) {
+    context.fillText(label.text, label.x, label.y);
+  }
+  for (const label of geometry.borderRankLabels) {
+    context.fillText(label.text, label.x, label.y);
+  }
+}
+function drawInsideCoordinates(context, request, geometry) {
+  const fontSize = resolveInsideCoordinateFontSize(context, geometry);
+  if (fontSize === null) {
+    return;
+  }
+  context.font = `${fontSize}px sans-serif`;
+  for (const label of geometry.insideFileLabels) {
+    context.fillStyle = resolveInsideLabelColor(request, label.square);
+    context.textAlign = label.textAlign;
+    context.textBaseline = label.textBaseline;
+    context.fillText(label.text, label.x, label.y);
+  }
+  for (const label of geometry.insideRankLabels) {
+    context.fillStyle = resolveInsideLabelColor(request, label.square);
+    context.textAlign = label.textAlign;
+    context.textBaseline = label.textBaseline;
+    context.fillText(label.text, label.x, label.y);
+  }
+}
+function drawCoordinates(context, request, geometry) {
+  if (!request.coordinates.enabled) {
+    return;
+  }
+  if (request.coordinates.position === "border") {
+    drawBorderCoordinates(context, request, geometry);
+    return;
+  }
+  drawInsideCoordinates(context, request, geometry);
+}
 var CanvasPngRenderer = class {
   async render(request) {
     try {
       const geometry = createBoardGeometry({
         size: request.size,
         padding: request.padding,
+        borderSize: request.borderSize,
         flipped: request.flipped
       });
-      const canvas = (0, import_canvas2.createCanvas)(geometry.imageWidth, geometry.imageHeight);
+      const canvas = (0, import_canvas3.createCanvas)(geometry.imageWidth, geometry.imageHeight);
       const context = canvas.getContext("2d");
       context.fillStyle = request.colors.lightSquare;
       context.fillRect(0, 0, geometry.imageWidth, geometry.imageHeight);
@@ -392,6 +657,7 @@ var CanvasPngRenderer = class {
           squareGeometry.size
         );
       }
+      drawCoordinates(context, request, geometry);
       return canvas.toBuffer("image/png");
     } catch (error) {
       if (error instanceof RenderError) {
@@ -554,11 +820,16 @@ function resolveTheme({ theme, style }) {
 // src/utils/normalization.ts
 var DEFAULT_SIZE = 480;
 var DEFAULT_PADDING = [0, 0, 0, 0];
+var DEFAULT_BORDER_SIZE = 0;
 var DEFAULT_COLORS = {
   lightSquare: "#f0d9b5",
   darkSquare: "#b58863",
   highlight: "rgba(255, 206, 0, 0.45)"
 };
+var DEFAULT_COORDINATES = {
+  enabled: false,
+  position: "inside"
+};
 function normalizeColors(colors) {
   return {
     lightSquare: colors?.lightSquare ?? DEFAULT_COLORS.lightSquare,
@@ -566,17 +837,52 @@ function normalizeColors(colors) {
     highlight: colors?.highlight ?? DEFAULT_COLORS.highlight
   };
 }
+function normalizeCoordinates(coordinates, borderSize) {
+  if (coordinates === void 0 || coordinates === false) {
+    return { ...DEFAULT_COORDINATES };
+  }
+  const defaultPosition = borderSize > 0 ? "border" : "inside";
+  if (coordinates === true) {
+    return {
+      enabled: true,
+      position: defaultPosition,
+      color: defaultPosition === "border" ? "#333" : void 0
+    };
+  }
+  if (coordinates === "border" || coordinates === "inside") {
+    return {
+      enabled: true,
+      position: coordinates,
+      color: coordinates === "border" ? "#333" : void 0
+    };
+  }
+  const position = coordinates.position ?? defaultPosition;
+  return {
+    enabled: coordinates.enabled ?? true,
+    position,
+    color: coordinates.color ?? (position === "border" ? "#333" : void 0)
+  };
+}
 function normalizeRenderInputs(options) {
+  const size = validateSize(options.size ?? DEFAULT_SIZE);
+  const borderSize = validateBorderSize(
+    options.borderSize ?? DEFAULT_BORDER_SIZE,
+    size
+  );
+  validateBoardColors(options.colors);
+  validateCoordinatesOption(options.coordinates, borderSize);
   return {
-    size: validateSize(options.size ?? DEFAULT_SIZE),
+    size,
     padding: normalizePadding(options.padding ?? DEFAULT_PADDING),
+    borderSize,
     flipped: options.flipped ?? false,
     theme: resolveTheme({
       theme: options.theme,
       style: options.style
     }),
     highlightSquares: normalizeHighlights(options.highlightSquares ?? []),
-    colors: normalizeColors(options.colors)
+    colors: normalizeColors(options.colors),
+    coordinates: normalizeCoordinates(options.coordinates, borderSize)
   };
 }
 
@@ -625,8 +931,10 @@ var ChessImageGenerator = class {
       highlights: normalized.highlightSquares,
       size: normalized.size,
       padding: normalized.padding,
+      borderSize: normalized.borderSize,
       flipped: normalized.flipped,
-      colors: normalized.colors
+      colors: normalized.colors,
+      coordinates: normalized.coordinates
     });
   }
   async toFile(filePath) {
@@ -666,8 +974,10 @@ async function renderChess(options) {
     highlights: normalized.highlightSquares,
     size: normalized.size,
     padding: normalized.padding,
+    borderSize: normalized.borderSize,
     flipped: normalized.flipped,
-    colors: normalized.colors
+    colors: normalized.colors,
+    coordinates: normalized.coordinates
   });
 }
 // Annotate the CommonJS export names for ESM import in node: