@visualizevalue/img-grid 0.1.3 → 0.1.4

package/README.md

@@ -30,7 +30,9 @@ const highlightedBuffer = await grid(images, {
   highlight: ['img2', 'img3'], // Images with these IDs will be 2×2
   maxWidth: 1920, // Maximum width of output image
   concurrency: 10, // Maximum concurrent downloads
-  background: '#000', // Background and letterbox color
+  background: '#000', // Fills background, padding, gutters, and letterboxing
+  padding: 16, // Space around the whole grid, in pixels
+  gutter: 8, // Gap between cells (rows and columns), in pixels
   pixelated: true, // Nearest-neighbour resize — keeps pixel art crisp
   format: 'webp', // Output as png (default), jpeg, or webp
   quality: 80, // Quality for jpeg/webp
@@ -45,6 +47,7 @@ writeFileSync('grid.png', buffer)
 
 - Packs images into a compact, near-square grid
 - Supports highlighting specific images (makes them 2×2)
+- Configurable `background` color, `padding` around the grid, and `gutter` between cells
 - Optional nearest-neighbour scaling to keep pixel art crisp (`pixelated`)
 - Downloads images concurrently (with a configurable limit)
 - Leaves a blank cell for failed downloads instead of failing the grid
@@ -58,7 +61,9 @@ writeFileSync('grid.png', buffer)
 | `highlight`   | `[]`        | Array of image IDs to highlight (make 2×2)         |
 | `maxWidth`    | `1920`      | Maximum width of output image in pixels            |
 | `concurrency` | `10`        | Maximum concurrent image downloads                 |
-| `background`  | `'#000'`    | Background and letterbox color (any sharp color)   |
+| `background`  | `'#000'`    | Fills background, padding, gutters, letterboxing   |
+| `padding`     | `0`         | Space around the whole grid, in pixels             |
+| `gutter`      | `0`         | Gap between cells (rows and columns), in pixels     |
 | `pixelated`   | `false`     | Nearest-neighbour resize; keeps pixel art crisp    |
 | `format`      | `'png'`     | Output format: `'png'`, `'jpeg'`, or `'webp'`      |
 | `quality`     | sharp's     | Quality (1–100) for `jpeg`/`webp`; ignored for png |

package/dist/index.d.ts

@@ -10,8 +10,15 @@ export interface GridOptions {
     maxWidth?: number;
     /** Maximum number of images downloaded at once. */
     concurrency?: number;
-    /** Background and letterbox color (any sharp-compatible color). */
+    /**
+     * Color filling the background, padding, gutters, and image letterboxing
+     * (any sharp-compatible color).
+     */
     background?: string;
+    /** Space around the whole grid, in pixels. Filled with `background`. */
+    padding?: number;
+    /** Gap between cells (rows and columns), in pixels. Filled with `background`. */
+    gutter?: number;
     /**
      * Resize with nearest-neighbour instead of the default smooth (lanczos)
      * kernel. Keeps pixel art (e.g. NFTs) crisp instead of blurring it when

package/dist/index.js

@@ -8,6 +8,8 @@ const sharp_1 = __importDefault(require("sharp"));
 const DEFAULT_MAX_WIDTH = 1920;
 const DEFAULT_CONCURRENCY = 10;
 const DEFAULT_BACKGROUND = '#000';
+const DEFAULT_PADDING = 0;
+const DEFAULT_GUTTER = 0;
 const DEFAULT_FORMAT = 'png';
 const FETCH_TIMEOUT_MS = 15_000;
 const HIGHLIGHT_SPAN = 2;
@@ -20,25 +22,38 @@ const HIGHLIGHT_SPAN = 2;
  */
 async function grid(images, opts = {}) {
     const { highlight = [], maxWidth = DEFAULT_MAX_WIDTH, concurrency = DEFAULT_CONCURRENCY, background = DEFAULT_BACKGROUND, pixelated = false, format = DEFAULT_FORMAT, quality, onError, } = opts;
+    const padding = Math.max(0, Math.floor(opts.padding ?? DEFAULT_PADDING));
+    const gutter = Math.max(0, Math.floor(opts.gutter ?? DEFAULT_GUTTER));
     const highlightIds = new Set(highlight);
     const isHighlighted = (img) => img.id !== undefined && highlightIds.has(img.id);
     const highlighted = images.filter(isHighlighted);
     const normal = images.filter((img) => !isHighlighted(img));
     const totalCells = normal.length + highlighted.length * HIGHLIGHT_SPAN ** 2;
-    if (totalCells === 0)
-        return encode(blankCanvas(1, 1, background), format, quality);
+    if (totalCells === 0) {
+        const side = Math.max(1, 2 * padding);
+        return encode(blankCanvas(side, side, background), format, quality);
+    }
     const { columns, rows, placements } = chooseLayout(highlighted, normal);
-    const cellSize = Math.max(1, Math.floor(maxWidth / columns));
+    // Carve padding and inter-column gutters out of the width budget before
+    // dividing what's left among the columns, so the output never exceeds maxWidth.
+    const available = maxWidth - 2 * padding - (columns - 1) * gutter;
+    const cellSize = Math.max(1, Math.floor(available / columns));
+    // Top-left pixel of cell (col, row); a span-N block also covers the N−1
+    // gutters between the cells it spans, so it reads as one solid larger tile.
+    const offset = (index) => padding + index * (cellSize + gutter);
+    const spanSize = (span) => span * cellSize + (span - 1) * gutter;
     const layers = await mapWithConcurrency(placements, concurrency, async (placement) => {
-        const size = cellSize * placement.span;
+        const size = spanSize(placement.span);
         const cell = await renderCell(placement.img, size, background, pixelated, onError);
         return {
             input: cell,
-            left: placement.col * cellSize,
-            top: placement.row * cellSize,
+            left: offset(placement.col),
+            top: offset(placement.row),
         };
     });
-    const canvas = blankCanvas(columns * cellSize, rows * cellSize, background).composite(layers);
+    const width = 2 * padding + columns * cellSize + (columns - 1) * gutter;
+    const height = 2 * padding + rows * cellSize + (rows - 1) * gutter;
+    const canvas = blankCanvas(width, height, background).composite(layers);
     return encode(canvas, format, quality);
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visualizevalue/img-grid",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Generate an image grid (PNG, JPEG, or WebP) from image URLs (and highlight images).",
   "license": "MIT",
   "author": "Visualize Value",