image-grid-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cutmyimage.com
+
+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

@@ -0,0 +1,133 @@
+# image-grid-kit
+
+Zero-dependency helpers for two jobs that keep showing up when you work with
+sprite sheets and tiled images:
+
+1. **Splitting** — work out the exact pixel rectangles when an image is cut
+   into rows, columns or a grid, including the case where the pieces have to
+   come out at a fixed aspect ratio.
+2. **Playback** — turn those rectangles into CSS: one class per frame plus a
+   `@keyframes` block that steps through the sheet.
+
+No build step, no dependencies, Node 18+.
+
+## Install
+
+```bash
+npm install image-grid-kit
+```
+
+or use it straight from a clone:
+
+```bash
+node bin/cli.js grid --width 1600 --height 900 --cols 3 --rows 1
+```
+
+## Library
+
+```js
+import { planGrid, planAspect, spriteCss } from "image-grid-kit";
+
+const { pieces } = planGrid({ width: 1600, height: 900, cols: 3, rows: 1 });
+// -> [{ n:1, x:0,    y:0, w:534, h:900 },
+//     { n:2, x:534,  y:0, w:533, h:900 },
+//     { n:3, x:1067, y:0, w:533, h:900 }]
+
+console.log(spriteCss({ pieces, sheetUrl: "walk.png", prefix: "walk" }));
+```
+
+### `planGrid({ width, height, mode, sizing, cols, rows, tileW, tileH })`
+
+`mode` is `grid`, `columns` or `rows`. `sizing` is `count` (number of pieces)
+or `pixel` (fixed cell size, with an optional `--dropPartial` to throw the
+short remainder away).
+
+When the width does not divide evenly, the first `width % cols` columns get one
+extra pixel, so the pieces always add back up to the original width:
+
+```js
+planGrid({ width: 1600, height: 900, cols: 3, rows: 1 }).xs; // [534, 533, 533]
+```
+
+### `planAspect({ width, height, cols, rows, ratioW, ratioH })`
+
+The largest centre crop whose shape makes every cell of a `cols x rows` grid
+come out at exactly `ratioW : ratioH`. For a 3-piece grid at 4:5 on a 1600x900
+image:
+
+```js
+planAspect({ width: 1600, height: 900, cols: 3, rows: 1, ratioW: 4, ratioH: 5 });
+// { crop: { x: 2, y: 117, w: 1596, h: 665 },
+//   cut:  { left: 2, right: 2, top: 117, bottom: 118 },
+//   pieceW: 532, pieceH: 665 }
+```
+
+Returns `null` when the image is too small to hold even one cell at that ratio.
+
+### `spriteCss({ pieces, sheetUrl, prefix, duration, timing, iterations })`
+
+Emits a positioned class per frame, a `@keyframes` block, and an animation
+class. `timing` defaults to `step-end`, which is what makes a sprite sheet play
+frame by frame instead of sliding between frames:
+
+```css
+@keyframes walk-play {
+  0%   { background-position: -0px -0px; }
+  25%  { background-position: -48px -0px; }
+  50%  { background-position: -96px -0px; }
+  75%  { background-position: -144px -0px; }
+  100% { background-position: -144px -0px; }
+}
+.walk-anim { animation: walk-play 800ms step-end infinite; }
+```
+
+## CLI
+
+```
+grid    --width N --height N [--mode grid|columns|rows] [--cols N --rows N]
+                             [--sizing count|pixel --tileW N --tileH N] [--dropPartial] [--json]
+aspect  --width N --height N --cols N --rows N [--ratio 4:5] [--json]
+css     --width N --height N --cols N --rows N [--sheet FILE] [--prefix NAME]
+                             [--duration 1s] [--timing step-end] [--iterations infinite]
+```
+
+`--json` prints the rectangles as JSON, which is the convenient form if you are
+feeding them to an image library such as `sharp` or ImageMagick.
+
+## Why `step-end` and not `steps()`
+
+Both work, they just fail differently. `steps(n)` divides one animation cycle
+into n equal slices and needs `background-position` to move linearly across the
+whole sheet, which breaks as soon as frames are trimmed or the last row is
+partial. `step-end` with explicit percentage keyframes pins every frame to a
+known offset, so trimmed frames, ragged last rows and multi-row sheets all work.
+The `data/` folder in this repo shows what three other tools actually ship.
+
+## `data/`
+
+- `sprite-sheet-tools-export-formats-2026-09-15.csv` — for each tool that ranked
+  for `sprite sheet maker` or `texture packer` on 2026-09-15: what it exports,
+  whether a CSS file was actually downloaded, and the literal keyword counts
+  inside that file.
+- `serp-top10-2026-09-15.csv` — the raw result lists behind that sample.
+
+Read `data/README.md` before quoting any number: it says exactly which cells are
+measured and which are "we looked and did not see one".
+
+## Browser version
+
+The same grid and crop math, with a preview and a ZIP download, runs at
+[cutmyimage.com](https://cutmyimage.com) if you would rather not open a
+terminal.
+
+## Tests
+
+```bash
+npm test
+```
+
+10 tests, no dependencies, `node --test`.
+
+## Licence
+
+MIT. The CSV files in `data/` are CC0.

package/bin/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * image-grid-kit CLI
+ *
+ *   node bin/cli.js grid --width 1600 --height 900 --cols 3 --rows 1
+ *   node bin/cli.js grid --width 1600 --height 900 --mode columns --cols 3 --json
+ *   node bin/cli.js aspect --width 1600 --height 900 --cols 3 --rows 1 --ratio 4:5
+ *   node bin/cli.js css --width 192 --height 64 --cols 4 --rows 1 --sheet walk.png --prefix walk
+ */
+import { planGrid, planAspect, splitFixed } from "../src/grid.js";
+import { spriteCss } from "../src/css.js";
+
+const argv = process.argv.slice(2);
+
+function args() {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith("--")) { out[key] = true; }
+    else { out[key] = next; i++; }
+  }
+  return out;
+}
+
+function num(v, dflt) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+function help() {
+  console.log(`image-grid-kit
+
+  grid    --width N --height N [--mode grid|columns|rows] [--cols N --rows N]
+                               [--sizing count|pixel --tileW N --tileH N] [--dropPartial] [--json]
+  aspect  --width N --height N --cols N --rows N [--ratio 4:5] [--json]
+  css     --width N --height N --cols N --rows N [--sheet FILE] [--prefix NAME]
+                               [--duration 1s] [--timing step-end] [--iterations infinite]
+`);
+}
+
+const cmd = argv[0];
+const a = args();
+
+if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") { help(); process.exit(0); }
+
+if (cmd === "grid") {
+  const res = planGrid({
+    width: num(a.width, 0),
+    height: num(a.height, 0),
+    mode: a.mode || "grid",
+    sizing: a.sizing || "count",
+    cols: num(a.cols, 3),
+    rows: num(a.rows, 3),
+    tileW: num(a.tileW, 500),
+    tileH: num(a.tileH, 500),
+    dropPartial: !!a.dropPartial
+  });
+  if (a.json) { console.log(JSON.stringify(res, null, 2)); }
+  else {
+    console.log("xs: " + res.xs.join(", "));
+    console.log("ys: " + res.ys.join(", "));
+    res.pieces.forEach((p) => {
+      console.log(String(p.n).padStart(3) + "  x=" + p.x + " y=" + p.y + " w=" + p.w + " h=" + p.h);
+    });
+  }
+} else if (cmd === "aspect") {
+  const ratio = String(a.ratio || "4:5").split(":");
+  const res = planAspect({
+    width: num(a.width, 0),
+    height: num(a.height, 0),
+    cols: num(a.cols, 3),
+    rows: num(a.rows, 1),
+    ratioW: num(ratio[0], 4),
+    ratioH: num(ratio[1], 5)
+  });
+  if (!res) {
+    console.log("image too small for a single cell at that ratio");
+    process.exit(1);
+  }
+  if (a.json) { console.log(JSON.stringify(res, null, 2)); }
+  else {
+    console.log("crop: " + res.crop.w + " x " + res.crop.h + " at (" + res.crop.x + "," + res.crop.y + ")");
+    console.log("cut:  left " + res.cut.left + "  right " + res.cut.right +
+                "  top " + res.cut.top + "  bottom " + res.cut.bottom);
+    console.log("each piece: " + res.pieceW + " x " + res.pieceH);
+  }
+} else if (cmd === "css") {
+  const res = planGrid({
+    width: num(a.width, 0),
+    height: num(a.height, 0),
+    mode: "grid",
+    sizing: "count",
+    cols: num(a.cols, 4),
+    rows: num(a.rows, 1)
+  });
+  process.stdout.write(spriteCss({
+    pieces: res.pieces,
+    sheetUrl: a.sheet || "spritesheet.png",
+    prefix: a.prefix || "sprite",
+    duration: a.duration || "1s",
+    timing: a.timing || "step-end",
+    iterations: a.iterations || "infinite"
+  }));
+} else {
+  help();
+  process.exit(1);
+}

package/data/README.md

@@ -0,0 +1,46 @@
+# Data in this folder
+
+Two small CSV files, both produced by hand on 2026-09-15. Read this before
+quoting any number from them.
+
+## How the numbers were produced
+
+- Browser: a normal desktop Chrome (Windows 11), driven over the DevTools
+  protocol. Not a headless crawler.
+- Search results: `google.com/search?num=20&hl=en&gl=us`, one snapshot per
+  keyword, taken 2026-09-15 around 16:20 GMT+8. Rank in the CSV is the order
+  the `<h3>` headings appeared in the page source.
+- Tool exports: four 64x64 PNG frames were uploaded to each tool that accepts
+  files. Where a CSS export existed, the download was clicked for real and the
+  file that landed on disk was opened and counted.
+- Counts (`at_keyframes`, `animation`, `steps_open`, `background_position`) are
+  literal substring counts inside the downloaded `.css` text. Nothing was
+  parsed or interpreted.
+
+## What is verified and what is not
+
+- `css_export = yes` and a `css_bytes` value: a file was really downloaded and
+  counted. Verified.
+- `css_export = unknown`: the tool was opened, but no CSS option was seen. This
+  is an absence of evidence, not evidence of absence. Do not read it as "this
+  tool has no CSS export".
+- `export_formats_observed = not observed`: the page gave nothing to read. Same
+  caveat.
+- `steps_open` counts the literal string `steps(`. A tool can animate a sprite
+  sheet with `step-end` instead, which this column does not count. The
+  cutmyimage.com row shows exactly that: `steps_open` 0 but `animation` 3.
+
+## Known limits
+
+- One snapshot, one location setting, one day. Search results move.
+- The 14 tool rows come from the two result pages above, so they are a sample
+  of what ranked that day, not a census of every sprite sheet tool.
+- `texture packer` returned 10 headings, but number 2 is a Google Play app
+  block, not a web page. Natural web results for that keyword: 9. Three of
+  those 9 are sub-pages of codeandweb.com, so distinct hosts: 7.
+- `sprite sheet maker` returned 10 headings, all natural web results, 10
+  distinct hosts.
+
+## Licence
+
+The CSV files are released under CC0. Quote them freely, ideally with the date.

package/data/serp-top10-2026-09-15.csv

@@ -0,0 +1,21 @@
+keyword,rank,title,host,url,result_type,note,measured_on
+sprite sheet maker,1,Sprite Sheet Maker,www.finalparsec.com,https://www.finalparsec.com/tools/sprite_sheet_maker,natural,"top block of the results page",2026-09-15
+sprite sheet maker,2,Spritesheet Generator - Create Game Sprite Sheets Online,spritesheetgenerator.online,https://spritesheetgenerator.online/,natural,,2026-09-15
+sprite sheet maker,3,Sprite Sheet Maker & Generator — Create Sprites Instantly,spritesheetmaker.com,https://spritesheetmaker.com/,natural,,2026-09-15
+sprite sheet maker,4,Free Sprite Sheet Packer & Generator,www.codeandweb.com,https://www.codeandweb.com/free-sprite-sheet-packer,natural,,2026-09-15
+sprite sheet maker,5,Piskel - Free online sprite editor,www.piskelapp.com,https://www.piskelapp.com/,natural,,2026-09-15
+sprite sheet maker,6,PixelLab - AI Generator for Pixel Art Game Assets,www.pixellab.ai,https://www.pixellab.ai/,natural,,2026-09-15
+sprite sheet maker,7,Images to Sprite Sheet Generator - Texture Atlas Maker,codeshack.io,https://codeshack.io/images-sprite-sheet-generator/,natural,,2026-09-15
+sprite sheet maker,8,The Spriters Toolkit,tools.spriters-resource.com,https://tools.spriters-resource.com/,natural,,2026-09-15
+sprite sheet maker,9,AI Sprite Sheet Generator - AI Tool,layer.ai,https://layer.ai/tools/layer--generate-a-sprite-sheet,natural,,2026-09-15
+sprite sheet maker,10,Tool to create sprite sheets : r/gamedev,www.reddit.com,https://www.reddit.com/r/gamedev/comments/126lek8/tool_to_create_sprite_sheets/,natural,,2026-09-15
+texture packer,1,TexturePacker - Create Sprite Sheets for your game!,www.codeandweb.com,https://www.codeandweb.com/texturepacker,natural,"top block of the results page",2026-09-15
+texture packer,2,Texture Packer Maker - Apps on Google Play,play.google.com,https://play.google.com/store/apps/details,module,"app pack block, not a web page result - excluded from the natural count",2026-09-15
+texture packer,3,Download TexturePacker Free Trial - Windows Mac Linux,www.codeandweb.com,https://www.codeandweb.com/texturepacker/download,natural,,2026-09-15
+texture packer,4,TexturePacker Online (free) - by CodeAndWeb,www.codeandweb.com,https://www.codeandweb.com/tp-online,natural,,2026-09-15
+texture packer,5,TexturePacker and Unity - Sprite sheets and normal maps,www.codeandweb.com,https://www.codeandweb.com/texturepacker/for-unity,natural,,2026-09-15
+texture packer,6,Texture packer,libgdx.com,https://libgdx.com/wiki/tools/texture-packer,natural,,2026-09-15
+texture packer,7,benbaker76/TexturePacker,github.com,https://github.com/benbaker76/TexturePacker,natural,,2026-09-15
+texture packer,8,I just released a free alternative to Texture Packer on itch.io,www.reddit.com,https://www.reddit.com/r/gamedev/comments/1027zx0/i_just_released_a_free_alternative_to_texture/,natural,,2026-09-15
+texture packer,9,Texture Packer | Sprite Management,assetstore.unity.com,https://assetstore.unity.com/packages/tools/sprite-management/texture-packer-264773,natural,,2026-09-15
+texture packer,10,Online Texture Packer | Create Sprite sheet free for your game,www.toolbuddy.io,https://www.toolbuddy.io/texturepacker,natural,,2026-09-15

package/data/sprite-sheet-tools-export-formats-2026-09-15.csv

@@ -0,0 +1,16 @@
+keyword,name,host,url,kind,export_formats_observed,css_export,css_file_downloaded,css_bytes,at_keyframes,animation,steps_open,background_position,evidence,measured_on
+sprite sheet maker,spritesheetgenerator.online,spritesheetgenerator.online,https://spritesheetgenerator.online/,web tool,"PNG, JSON, ZIP, GIF — quoted from the page: ""Export as PNG, or JSON, ZIP, or GIF if your engine prefers it.""",unknown,no,,,,,,"real Chrome read; 4 test frames uploaded; export area reached; no CSS option seen",2026-09-15
+sprite sheet maker,finalparsec,www.finalparsec.com,https://www.finalparsec.com/tools/sprite_sheet_maker,web tool,"CSS file downloaded (sprite_sheet.css) plus the packed image",yes,yes,644,0,0,0,4,"file downloaded and opened; counts are literal string counts in the CSS text",2026-09-15
+sprite sheet maker,CodeAndWeb free sprite sheet packer,www.codeandweb.com,https://www.codeandweb.com/free-sprite-sheet-packer,web tool,"JSON (hash) seen in the export area; no CSS option seen",unknown,no,,,,,,"real Chrome read; 4 test frames uploaded",2026-09-15
+sprite sheet maker,spritesheetmaker.com,spritesheetmaker.com,https://spritesheetmaker.com/,web tool,"PNG + JSON + CSS + XML (export format toggles on the page)",yes,yes,473,0,0,0,4,"spritesheet.zip downloaded by clicking Download ZIP in a real Chrome; counts from spritesheet.css",2026-09-15
+sprite sheet maker,codeshack,codeshack.io,https://codeshack.io/images-sprite-sheet-generator/,web tool,not observed,unknown,no,,,,,,"page opened; no file input and no export control found, so nothing could be downloaded",2026-09-15
+sprite sheet maker,sprite-ai.art,www.sprite-ai.art,https://www.sprite-ai.art/tools/sprite-sheet-maker,AI site,"PNG, or PNG + JSON together in a ZIP — quoted from the page",unknown,no,,,,,,"real Chrome read; 4 test frames uploaded",2026-09-15
+sprite sheet maker,pixellab.ai,www.pixellab.ai,https://www.pixellab.ai/,AI site,not observed,unknown,no,,,,,,"page opened; export sits behind sign-up, not measured",2026-09-15
+texture packer,CodeAndWeb TexturePacker,www.codeandweb.com,https://www.codeandweb.com/texturepacker,desktop software,"many engine data formats; page says you can also create your own custom format",unknown,no,,,,,,"page text read; desktop product, nothing to download from the page",2026-09-15
+texture packer,CodeAndWeb TexturePacker download page,www.codeandweb.com,https://www.codeandweb.com/texturepacker/download,download page,not applicable,unknown,no,,,,,,"page text read (changelog); no export area on the page",2026-09-15
+texture packer,TexturePacker Online,www.codeandweb.com,https://www.codeandweb.com/tp-online,web tool,"JSON (a Format control is present); no CSS option seen",unknown,no,,,,,,"real Chrome read; 4 test frames uploaded",2026-09-15
+texture packer,free-tex-packer (odrick),github.com,https://github.com/odrick/free-tex-packer,open-source repo,not measured,unknown,no,,,,,,"repository page read; package not installed or run",2026-09-15
+texture packer,libGDX texture packer wiki,libgdx.com,https://libgdx.com/wiki/tools/texture-packer,documentation,not applicable,unknown,no,,,,,,"documentation page read",2026-09-15
+texture packer,ToolBuddy Texture Packer,www.toolbuddy.io,https://www.toolbuddy.io/texturepacker,web tool,"16 export presets incl. CSS (exporter dropdown)",yes,yes,659,0,0,0,4,"atlas.zip downloaded by clicking Export package then Export ZIP in a real Chrome; counts from atlas.sprites.css",2026-09-15
+texture packer,Texture Packer (Unity Asset Store),assetstore.unity.com,https://assetstore.unity.com/packages/tools/sprite-management/texture-packer-264773,store plugin,not measured,unknown,no,,,,,,"store page read; plugin not installed",2026-09-15
+n/a,cutmyimage.com sprite sheet maker,cutmyimage.com,https://cutmyimage.com/sprite-sheet-maker/,web tool (this project's site),"PNG, JSON, CSS",yes,yes,913,1,3,0,9,"our own export, downloaded and counted the same way; the animation uses step-end, not steps()",2026-09-15

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "image-grid-kit",
+  "version": "1.0.0",
+  "description": "Zero-dependency helpers for splitting an image into a grid and generating CSS sprite-sheet animations from the resulting coordinates.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./grid": "./src/grid.js",
+    "./css": "./src/css.js"
+  },
+  "bin": {
+    "image-grid-kit": "bin/cli.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "data"
+  ],
+  "scripts": {
+    "test": "node --test test/",
+    "cli": "node bin/cli.js"
+  },
+  "keywords": [
+    "image",
+    "split",
+    "grid",
+    "sprite",
+    "spritesheet",
+    "css",
+    "keyframes",
+    "texture-atlas"
+  ],
+  "homepage": "https://cutmyimage.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jessica7168295-ux/image-grid-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jessica7168295-ux/image-grid-kit/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/css.js

@@ -0,0 +1,80 @@
+/**
+ * image-grid-kit — CSS sprite-sheet output.
+ *
+ * Takes the piece rectangles from planGrid() (or any list of
+ * {name, x, y, w, h}) and writes:
+ *   - one class per frame, positioned with background-position
+ *   - one @keyframes block that steps through the frames
+ *   - one animation class
+ *
+ * The `step-end` timing function is what makes the sheet play frame by frame
+ * instead of sliding between frames.
+ */
+
+function slug(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "frame";
+}
+
+function pad2(n) { return n < 10 ? "0" + n : String(n); }
+
+function pct(i, n) {
+  const v = (i / n) * 100;
+  return String(Number(v.toFixed(3)));
+}
+
+/**
+ * @param {object} o
+ * @param {Array<{name?:string,x:number,y:number,w:number,h:number}>} o.pieces
+ * @param {string} [o.sheetUrl]   url() value, defaults to "spritesheet.png"
+ * @param {string} [o.prefix]     class prefix, defaults to "sprite"
+ * @param {string} [o.duration]   animation-duration, defaults to "1s"
+ * @param {string} [o.timing]     animation-timing-function, defaults to "step-end"
+ * @param {string} [o.iterations] animation-iteration-count, defaults to "infinite"
+ * @returns {string} CSS text
+ */
+export function spriteCss(o) {
+  const pieces = (o.pieces || []).slice();
+  if (!pieces.length) throw new Error("spriteCss: no pieces given");
+  const sheetUrl = o.sheetUrl || "spritesheet.png";
+  const prefix = slug(o.prefix || "sprite");
+  const duration = o.duration || "1s";
+  const timing = o.timing || "step-end";
+  const iterations = o.iterations || "infinite";
+  const n = pieces.length;
+
+  const lines = [];
+  lines.push("/* Generated by image-grid-kit */");
+  lines.push("." + prefix + " {");
+  lines.push("  background-image: url('" + sheetUrl + "');");
+  lines.push("  background-repeat: no-repeat;");
+  lines.push("  display: inline-block;");
+  lines.push("}");
+  lines.push("");
+
+  pieces.forEach((p, i) => {
+    const nm = p.name ? slug(p.name) : "frame-" + pad2(i + 1);
+    lines.push("." + prefix + "." + prefix + "-" + nm + " {");
+    lines.push("  width: " + p.w + "px;");
+    lines.push("  height: " + p.h + "px;");
+    lines.push("  background-position: -" + p.x + "px -" + p.y + "px;");
+    lines.push("}");
+  });
+
+  lines.push("");
+  lines.push("/* Frame-by-frame playback: change animation-duration to taste. */");
+  lines.push("@keyframes " + prefix + "-play {");
+  pieces.forEach((p, i) => {
+    lines.push("  " + pct(i, n) + "% { background-position: -" + p.x + "px -" + p.y + "px; }");
+  });
+  const last = pieces[n - 1];
+  lines.push("  100% { background-position: -" + last.x + "px -" + last.y + "px; }");
+  lines.push("}");
+  lines.push("." + prefix + "-anim {");
+  lines.push("  width: " + pieces[0].w + "px;");
+  lines.push("  height: " + pieces[0].h + "px;");
+  lines.push("  animation: " + prefix + "-play " + duration + " " + timing + " " + iterations + ";");
+  lines.push("}");
+  return lines.join("\n") + "\n";
+}
+
+export { slug };

package/src/grid.js

@@ -0,0 +1,135 @@
+/**
+ * image-grid-kit — grid math.
+ *
+ * These two functions mirror the behaviour of the browser tool at
+ * https://cutmyimage.com so that a script and the web page agree on where
+ * the cut lines fall.
+ */
+
+/**
+ * Split `total` pixels into `n` integer parts. The first `total % n` parts
+ * get one extra pixel, so the parts always sum back to `total`.
+ *
+ * splitEven(900, 3) -> [300, 300, 300]
+ * splitEven(1600, 3) -> [534, 533, 533]
+ */
+export function splitEven(total, n) {
+  const t = Math.floor(total);
+  const count = Math.floor(n);
+  if (!(t > 0) || !(count > 0)) return [];
+  const base = Math.floor(t / count);
+  const rem = t % count;
+  const out = [];
+  for (let i = 0; i < count; i++) out.push(base + (i < rem ? 1 : 0));
+  return out;
+}
+
+/**
+ * Split `total` pixels into parts of at most `step` pixels. The last part is
+ * the remainder and may be shorter.
+ *
+ * splitFixed(1000, 300) -> [300, 300, 300, 100]
+ */
+export function splitFixed(total, step) {
+  const t = Math.floor(total);
+  const s = Math.floor(step);
+  if (!(t > 0) || !(s > 0)) return [];
+  const out = [];
+  let left = t;
+  while (left > 0) {
+    const part = Math.min(s, left);
+    out.push(part);
+    left -= part;
+  }
+  return out.length ? out : [t];
+}
+
+/**
+ * Lay a grid over an image and return one rectangle per piece.
+ *
+ * @param {object} o
+ * @param {number} o.width   image width in px
+ * @param {number} o.height  image height in px
+ * @param {'grid'|'columns'|'rows'} [o.mode]
+ * @param {'count'|'pixel'} [o.sizing]  'count' = number of pieces, 'pixel' = fixed cell size
+ * @param {number} [o.cols]
+ * @param {number} [o.rows]
+ * @param {number} [o.tileW]  used when sizing === 'pixel'
+ * @param {number} [o.tileH]  used when sizing === 'pixel'
+ * @param {boolean} [o.dropPartial]  with sizing 'pixel': drop the short remainder piece
+ * @returns {{xs:number[], ys:number[], pieces:Array<{n:number,x:number,y:number,w:number,h:number}>}}
+ */
+export function planGrid(o) {
+  const width = Math.floor(o.width);
+  const height = Math.floor(o.height);
+  const mode = o.mode || "grid";
+  const sizing = o.sizing || "count";
+  let xs, ys;
+
+  if (sizing === "count") {
+    const cols = Math.max(1, Math.floor(o.cols || 1));
+    const rows = Math.max(1, Math.floor(o.rows || 1));
+    if (mode === "columns") { xs = splitEven(width, cols); ys = [height]; }
+    else if (mode === "rows") { xs = [width]; ys = splitEven(height, rows); }
+    else { xs = splitEven(width, cols); ys = splitEven(height, rows); }
+  } else {
+    const tileW = Math.max(1, Math.floor(o.tileW || 1));
+    const tileH = Math.max(1, Math.floor(o.tileH || 1));
+    if (mode === "columns") { xs = splitFixed(width, tileW); ys = [height]; }
+    else if (mode === "rows") { xs = [width]; ys = splitFixed(height, tileH); }
+    else { xs = splitFixed(width, tileW); ys = splitFixed(height, tileH); }
+    if (o.dropPartial) {
+      if (mode !== "rows") xs = xs.filter((v, i) => !(i === xs.length - 1 && v < tileW));
+      if (mode !== "columns") ys = ys.filter((v, i) => !(i === ys.length - 1 && v < tileH));
+    }
+  }
+
+  const pieces = [];
+  let n = 0;
+  let y = 0;
+  for (let r = 0; r < ys.length; r++) {
+    let x = 0;
+    for (let c = 0; c < xs.length; c++) {
+      n += 1;
+      pieces.push({ n, x, y, w: xs[c], h: ys[r] });
+      x += xs[c];
+    }
+    y += ys[r];
+  }
+  return { xs, ys, pieces };
+}
+
+/**
+ * Plan the largest centre crop of `width` x `height` whose aspect ratio is
+ * exactly (ratioW x cols) : (ratioH x rows), so that every piece of the
+ * `cols` x `rows` grid comes out at exactly ratioW : ratioH.
+ *
+ * This is how the 4:5 (1080 x 1350) mode works on the Instagram page:
+ * planAspect({width:1600, height:900, rows:1, cols:3, ratioW:4, ratioH:5})
+ *   -> crop 1596 x 665, 4 px cut left and right, 235 px cut top and bottom,
+ *      each piece 532 x 665.
+ *
+ * @returns {null|object} null when the image is too small for even one cell
+ */
+export function planAspect(o) {
+  const w = Math.floor(o.width);
+  const h = Math.floor(o.height);
+  const rows = Math.max(1, Math.floor(o.rows || 1));
+  const cols = Math.max(1, Math.floor(o.cols || 1));
+  const rw = Math.floor(o.ratioW || 4);
+  const rh = Math.floor(o.ratioH || 5);
+  const aw = rw * cols;
+  const ah = rh * rows;
+  const k = Math.floor(Math.min(w / aw, h / ah));
+  if (!(k >= 1)) return null;
+  const cw = aw * k;
+  const ch = ah * k;
+  const sx = Math.floor((w - cw) / 2);
+  const sy = Math.floor((h - ch) / 2);
+  return {
+    crop: { x: sx, y: sy, w: cw, h: ch },
+    cut: { left: sx, right: w - cw - sx, top: sy, bottom: h - ch - sy },
+    pieceW: rw * k,
+    pieceH: rh * k
+  };
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { splitEven, splitFixed, planGrid, planAspect } from "./grid.js";
+export { spriteCss, slug } from "./css.js";