@visualizevalue/img-grid 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Visualize Value
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -30,6 +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
+  format: 'webp', // Output as png (default), jpeg, or webp
+  quality: 80, // Quality for jpeg/webp
+  onError: (img, err) => console.warn(`failed: ${img.url}`, err),
 })
 
 // Save to file
@@ -38,16 +41,21 @@ writeFileSync('grid.png', buffer)
 
 ## Features
 
-- Arranges images in an optimal grid layout
+- Packs images into a compact, near-square grid
 - Supports highlighting specific images (makes them 2×2)
-- Handles failed image downloads with placeholders
-- Limits concurrent downloads
+- Downloads images concurrently (with a configurable limit)
+- Leaves a blank cell for failed downloads instead of failing the grid
+- Output as PNG, JPEG, or WebP
 - Resizes all images to fit grid cells
 
 ## Options
 
-| Option        | Default | Description                                |
-| ------------- | ------- | ------------------------------------------ |
-| `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         |
+| Option        | Default     | Description                                        |
+| ------------- | ----------- | -------------------------------------------------- |
+| `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)   |
+| `format`      | `'png'`     | Output format: `'png'`, `'jpeg'`, or `'webp'`      |
+| `quality`     | sharp's     | Quality (1–100) for `jpeg`/`webp`; ignored for png |
+| `onError`     | `undefined` | `(img, error) => void` called when an image fails  |

package/dist/index.d.ts

@@ -1,10 +1,29 @@
+export type ImageFormat = 'png' | 'jpeg' | 'webp';
 export interface Img {
     url: string;
     id?: string;
 }
 export interface GridOptions {
+    /** IDs of images to enlarge into a 2×2 block. */
     highlight?: string[];
+    /** Maximum width of the output image, in pixels. */
     maxWidth?: number;
+    /** Maximum number of images downloaded at once. */
     concurrency?: number;
+    /** Background and letterbox color (any sharp-compatible color). */
+    background?: string;
+    /** Output image format. */
+    format?: ImageFormat;
+    /** Quality (1–100) for lossy formats (`jpeg`, `webp`); ignored for `png`. */
+    quality?: number;
+    /** Called when an image can't be fetched or decoded; its cell is left blank. */
+    onError?: (img: Img, error: unknown) => void;
 }
+/**
+ * Generate a PNG (or JPEG/WebP) grid from a list of image URLs.
+ *
+ * Images are packed into a near-square grid; highlighted images occupy a 2×2
+ * block. Unreachable or undecodable images leave a blank cell (and trigger
+ * `onError`) instead of failing the whole grid.
+ */
 export declare function grid(images: Img[], opts?: GridOptions): Promise<Buffer>;

package/dist/index.js

@@ -5,125 +5,159 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.grid = grid;
 const sharp_1 = __importDefault(require("sharp"));
+const DEFAULT_MAX_WIDTH = 1920;
+const DEFAULT_CONCURRENCY = 10;
+const DEFAULT_BACKGROUND = '#000';
+const DEFAULT_FORMAT = 'png';
+const FETCH_TIMEOUT_MS = 15_000;
+const HIGHLIGHT_SPAN = 2;
+/**
+ * Generate a PNG (or JPEG/WebP) grid from a list of image URLs.
+ *
+ * Images are packed into a near-square grid; highlighted images occupy a 2×2
+ * block. Unreachable or undecodable images leave a blank cell (and trigger
+ * `onError`) instead of failing the whole grid.
+ */
 async function grid(images, opts = {}) {
-    const highlightIds = new Set(opts.highlight ?? []);
-    const concurrency = opts.concurrency ?? 10;
-    const highlightScale = 2;
-    const maxWidth = opts.maxWidth ?? 1920;
-    const highlightedImages = images.filter((img) => img.id && highlightIds.has(img.id));
-    const normalImages = images.filter((img) => !highlightIds.has(img.id ?? ''));
-    const totalCells = normalImages.length + highlightedImages.length * highlightScale * highlightScale;
-    const gridSize = Math.ceil(Math.sqrt(totalCells));
-    const cellSize = Math.floor(maxWidth / gridSize);
-    const highlightedCellSize = cellSize * highlightScale;
-    const gridWidth = Math.max(gridSize, Math.ceil(Math.sqrt(totalCells * 1.5)));
-    const gridHeight = gridSize * highlightScale;
-    const grid = Array(gridHeight)
-        .fill(0)
-        .map(() => Array(gridWidth).fill(false));
-    function isFree(x, y, width, height) {
-        for (let dy = 0; dy < height; dy++) {
-            for (let dx = 0; dx < width; dx++) {
-                if (y + dy >= gridHeight || x + dx >= gridWidth || grid[y + dy][x + dx]) {
-                    return false;
-                }
-            }
+    const { highlight = [], maxWidth = DEFAULT_MAX_WIDTH, concurrency = DEFAULT_CONCURRENCY, background = DEFAULT_BACKGROUND, format = DEFAULT_FORMAT, quality, onError, } = opts;
+    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);
+    const { columns, rows, placements } = chooseLayout(highlighted, normal);
+    const cellSize = Math.max(1, Math.floor(maxWidth / columns));
+    const layers = await mapWithConcurrency(placements, concurrency, async (placement) => {
+        const size = cellSize * placement.span;
+        const cell = await renderCell(placement.img, size, background, onError);
+        return {
+            input: cell,
+            left: placement.col * cellSize,
+            top: placement.row * cellSize,
+        };
+    });
+    const canvas = blankCanvas(columns * cellSize, rows * cellSize, background).composite(layers);
+    return encode(canvas, format, quality);
+}
+/**
+ * Search candidate column counts and keep the one that packs into the smallest
+ * bounding square (then least wasted space, then widest). A closed-form column
+ * count can't predict how 2×2 highlight blocks pack, so we measure each instead.
+ */
+function chooseLayout(highlighted, normal) {
+    const totalCells = normal.length + highlighted.length * HIGHLIGHT_SPAN ** 2;
+    const minColumns = highlighted.length > 0 ? HIGHLIGHT_SPAN : 1;
+    const maxColumns = Math.max(minColumns, Math.ceil(Math.sqrt(totalCells)) + HIGHLIGHT_SPAN);
+    let best;
+    for (let columns = minColumns; columns <= maxColumns; columns++) {
+        const { placements, rows } = pack(highlighted, normal, columns);
+        const score = [
+            Math.max(columns, rows), // smallest bounding square
+            columns * rows - totalCells, // least wasted cells
+            -columns, // prefer wider (fills the width)
+        ];
+        if (best === undefined || lexLess(score, best.score)) {
+            best = { columns, rows, placements, score };
         }
-        return true;
     }
-    function markOccupied(x, y, width, height) {
-        for (let dy = 0; dy < height; dy++) {
-            for (let dx = 0; dx < width; dx++) {
-                grid[y + dy][x + dx] = true;
+    // minColumns ≤ maxColumns guarantees at least one candidate was evaluated.
+    const { columns, rows, placements } = best;
+    return { columns, rows, placements };
+}
+/** Lexicographic "less than" over equal-length numeric tuples. */
+function lexLess(a, b) {
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    return false;
+}
+/**
+ * Greedily place images into a grid with a fixed number of columns, growing
+ * rows as needed so no image is ever dropped. Larger (highlighted) blocks are
+ * placed first, then single cells fill the gaps.
+ */
+function pack(highlighted, normal, columns) {
+    const occupied = [];
+    const cellFree = (col, row) => {
+        while (occupied.length <= row)
+            occupied.push(new Array(columns).fill(false));
+        return !occupied[row][col];
+    };
+    const fits = (col, row, span) => {
+        if (col + span > columns)
+            return false;
+        for (let r = row; r < row + span; r++) {
+            for (let c = col; c < col + span; c++) {
+                if (!cellFree(c, r))
+                    return false;
             }
         }
-    }
-    function findSpot(width, height) {
-        for (let y = 0; y <= gridHeight - height; y++) {
-            for (let x = 0; x <= gridWidth - width; x++) {
-                if (isFree(x, y, width, height)) {
-                    return [x, y];
+        return true;
+    };
+    const place = (img, span) => {
+        for (let row = 0;; row++) {
+            for (let col = 0; col + span <= columns; col++) {
+                if (!fits(col, row, span))
+                    continue;
+                for (let r = row; r < row + span; r++) {
+                    for (let c = col; c < col + span; c++)
+                        occupied[r][c] = true;
                 }
+                return { img, col, row, span };
             }
         }
-        return null;
-    }
-    let inFlight = 0;
-    async function fetchImage(url, size) {
-        while (inFlight >= concurrency) {
-            await new Promise((resolve) => setTimeout(resolve, 100));
-        }
-        inFlight++;
-        try {
-            const response = await fetch(url, {
-                signal: AbortSignal.timeout(15000),
-                headers: { Accept: 'image/*' },
-            });
-            if (!response.ok)
-                throw new Error(`HTTP error ${response.status}`);
-            const data = await response.arrayBuffer();
-            return (0, sharp_1.default)(Buffer.from(data))
-                .resize(size, size, { fit: 'contain', background: '#000' })
-                .toBuffer();
-        }
-        catch (error) {
-            // return placeholder if error
-            return (0, sharp_1.default)({
-                create: {
-                    width: size,
-                    height: size,
-                    channels: 3,
-                    background: '#007F00',
-                },
-            })
-                .png()
-                .toBuffer();
-        }
-        finally {
-            inFlight--;
-        }
-    }
-    const compositeLayers = [];
-    let maxY = 0;
-    for (const img of highlightedImages) {
-        const spot = findSpot(highlightScale, highlightScale);
-        if (!spot)
-            continue;
-        const [x, y] = spot;
-        markOccupied(x, y, highlightScale, highlightScale);
-        const imageBuffer = await fetchImage(img.url, highlightedCellSize);
-        compositeLayers.push({
-            input: imageBuffer,
-            left: x * cellSize,
-            top: y * cellSize,
+    };
+    const placements = [
+        ...highlighted.map((img) => place(img, HIGHLIGHT_SPAN)),
+        ...normal.map((img) => place(img, 1)),
+    ];
+    return { placements, rows: occupied.length };
+}
+/** Fetch and resize a single image; fall back to a blank cell on any failure. */
+async function renderCell(img, size, background, onError) {
+    try {
+        const response = await fetch(img.url, {
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            headers: { Accept: 'image/*' },
         });
-        maxY = Math.max(maxY, y + highlightScale);
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status} for ${img.url}`);
+        const data = Buffer.from(await response.arrayBuffer());
+        return await (0, sharp_1.default)(data)
+            .resize(size, size, { fit: 'contain', background })
+            .png()
+            .toBuffer();
     }
-    for (const img of normalImages) {
-        const spot = findSpot(1, 1);
-        if (!spot)
-            break;
-        const [x, y] = spot;
-        markOccupied(x, y, 1, 1);
-        const imageBuffer = await fetchImage(img.url, cellSize);
-        compositeLayers.push({
-            input: imageBuffer,
-            left: x * cellSize,
-            top: y * cellSize,
-        });
-        maxY = Math.max(maxY, y + 1);
+    catch (error) {
+        onError?.(img, error);
+        return blankCanvas(size, size, background).png().toBuffer();
+    }
+}
+/** Run `task` over `items` with at most `limit` in flight, preserving order. */
+async function mapWithConcurrency(items, limit, task) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < items.length) {
+            const index = cursor++;
+            results[index] = await task(items[index]);
+        }
+    };
+    const workers = Array.from({ length: Math.min(limit, items.length) }, worker);
+    await Promise.all(workers);
+    return results;
+}
+const blankCanvas = (width, height, background) => (0, sharp_1.default)({ create: { width, height, channels: 4, background } });
+function encode(image, format, quality) {
+    switch (format) {
+        case 'jpeg':
+            return image.jpeg({ quality }).toBuffer();
+        case 'webp':
+            return image.webp({ quality }).toBuffer();
+        case 'png':
+            return image.png().toBuffer();
     }
-    const outputHeight = Math.max(1, maxY) * cellSize;
-    const outputWidth = gridWidth * cellSize;
-    return (0, sharp_1.default)({
-        create: {
-            width: outputWidth,
-            height: outputHeight,
-            channels: 3,
-            background: '#000',
-        },
-    })
-        .composite(compositeLayers)
-        .png()
-        .toBuffer();
 }

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "@visualizevalue/img-grid",
-  "version": "0.1.0",
-  "description": "Generate a PNG grid from image URLs (and highlight images).",
+  "version": "0.1.2",
+  "description": "Generate an image grid (PNG, JPEG, or WebP) from image URLs (and highlight images).",
+  "license": "MIT",
+  "author": "Visualize Value",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/visualizevalue/img-grid.git"
+  },
+  "homepage": "https://github.com/visualizevalue/img-grid#readme",
+  "bugs": "https://github.com/visualizevalue/img-grid/issues",
+  "keywords": [
+    "image",
+    "grid",
+    "montage",
+    "thumbnail",
+    "sharp"
+  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -10,10 +25,14 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "packageManager": "npm@11.4.0",
   "scripts": {
     "build": "tsc",
-    "format": "prettier --write",
+    "test": "tsx --test src/*.test.ts",
+    "format": "prettier . --write",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {