@flighthq/tileset 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './tileset';
+export * from './tilesetFrom';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './tileset';
+export * from './tilesetFrom';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/dist/tileset.d.ts

@@ -0,0 +1,4 @@
+import type { Tileset } from '@flighthq/types';
+export declare function buildTilesetRegions(target: Tileset): void;
+export declare function createTileset(obj?: Partial<Tileset>): Tileset;
+//# sourceMappingURL=tileset.d.ts.map

package/dist/tileset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tileset.d.ts","sourceRoot":"","sources":["../src/tileset.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAazD;AAED,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAU7D"}

package/dist/tileset.js

@@ -0,0 +1,34 @@
+import { createEntity } from '@flighthq/entity';
+import { createTextureAtlasRegion, setTextureAtlasRegion } from '@flighthq/textureatlas';
+// Fills or refreshes the atlas region array with one region per tile in the grid, using the
+// tileset's tileWidth/tileHeight, margin (border padding), and spacing (inter-tile gap).
+// Existing region objects are reused in place when the capacity matches — zero new allocations
+// for repeated calls on an already-populated tileset.
+export function buildTilesetRegions(target) {
+    const { atlas, rows, columns, tileWidth, tileHeight, margin, spacing } = target;
+    if (atlas === null)
+        return;
+    let i = 0;
+    for (let row = 0; row < rows; row++) {
+        for (let column = 0; column < columns; column++) {
+            if (i >= atlas.regions.length)
+                atlas.regions.push(createTextureAtlasRegion());
+            const x = margin + column * (tileWidth + spacing);
+            const y = margin + row * (tileHeight + spacing);
+            setTextureAtlasRegion(atlas.regions[i], x, y, tileWidth, tileHeight);
+            i++;
+        }
+    }
+}
+export function createTileset(obj) {
+    return createEntity({
+        atlas: obj?.atlas ?? null,
+        columns: obj?.columns ?? 0,
+        margin: obj?.margin ?? 0,
+        rows: obj?.rows ?? 0,
+        spacing: obj?.spacing ?? 0,
+        tileHeight: obj?.tileHeight ?? 0,
+        tileWidth: obj?.tileWidth ?? 0,
+    });
+}
+//# sourceMappingURL=tileset.js.map

package/dist/tileset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tileset.js","sourceRoot":"","sources":["../src/tileset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGzF,4FAA4F;AAC5F,yFAAyF;AACzF,+FAA+F;AAC/F,sDAAsD;AACtD,MAAM,UAAU,mBAAmB,CAAC,MAAe;IACjD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAChF,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO;IAC3B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;QACpC,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC;YAChD,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM;gBAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,wBAAwB,EAAE,CAAC,CAAC;YAC9E,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,SAAS,GAAG,OAAO,CAAC,CAAC;YAClD,MAAM,CAAC,GAAG,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,GAAG,OAAO,CAAC,CAAC;YAChD,qBAAqB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;YACrE,CAAC,EAAE,CAAC;QACN,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAsB;IAClD,OAAO,YAAY,CAAC;QAClB,KAAK,EAAE,GAAG,EAAE,KAAK,IAAI,IAAI;QACzB,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,CAAC;QAC1B,MAAM,EAAE,GAAG,EAAE,MAAM,IAAI,CAAC;QACxB,IAAI,EAAE,GAAG,EAAE,IAAI,IAAI,CAAC;QACpB,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,CAAC;QAC1B,UAAU,EAAE,GAAG,EAAE,UAAU,IAAI,CAAC;QAChC,SAAS,EAAE,GAAG,EAAE,SAAS,IAAI,CAAC;KAC/B,CAAC,CAAC;AACL,CAAC"}

package/dist/tilesetFrom.d.ts

@@ -0,0 +1,8 @@
+import type { ImageResource, TextureAtlas, Tileset } from '@flighthq/types';
+export declare function createTilesetFromAtlas(atlas: TextureAtlas, tileWidth: number, tileHeight: number, margin?: number, spacing?: number): Tileset;
+export declare function createTilesetFromImageResource(resource: ImageResource, tileWidth: number, tileHeight: number, margin?: number, spacing?: number): Tileset;
+export declare function loadTilesetFromBase64(base64: string, mimeType: string, tileWidth: number, tileHeight: number, signal?: AbortSignal): Promise<Tileset>;
+export declare function loadTilesetFromBlob(blob: Blob, tileWidth: number, tileHeight: number, signal?: AbortSignal): Promise<Tileset>;
+export declare function loadTilesetFromBytes(bytes: Uint8Array, tileWidth: number, tileHeight: number, mimeType?: string, signal?: AbortSignal): Promise<Tileset>;
+export declare function loadTilesetFromUrl(url: string, tileWidth: number, tileHeight: number, crossOrigin?: string, signal?: AbortSignal): Promise<Tileset>;
+//# sourceMappingURL=tilesetFrom.d.ts.map

package/dist/tilesetFrom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilesetFrom.d.ts","sourceRoot":"","sources":["../src/tilesetFrom.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAO5E,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAU,EAClB,OAAO,GAAE,MAAU,GAClB,OAAO,CAST;AAED,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAU,EAClB,OAAO,GAAE,MAAU,GAClB,OAAO,CAET;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAMlB"}

package/dist/tilesetFrom.js

@@ -0,0 +1,30 @@
+import { loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, } from '@flighthq/image';
+import { createTextureAtlas } from '@flighthq/textureatlas';
+import { buildTilesetRegions, createTileset } from './tileset';
+// Derives rows/columns from the atlas image size, honoring margin and inter-tile spacing.
+// `margin` is the number of pixels of padding between the tile grid and the image edge.
+// `spacing` is the number of pixels between adjacent tiles (inner gap).
+export function createTilesetFromAtlas(atlas, tileWidth, tileHeight, margin = 0, spacing = 0) {
+    const image = atlas.image;
+    const columns = image !== null && tileWidth > 0 ? Math.floor((image.width - margin * 2 + spacing) / (tileWidth + spacing)) : 0;
+    const rows = image !== null && tileHeight > 0 ? Math.floor((image.height - margin * 2 + spacing) / (tileHeight + spacing)) : 0;
+    const tileset = createTileset({ atlas, columns, margin, rows, spacing, tileHeight, tileWidth });
+    buildTilesetRegions(tileset);
+    return tileset;
+}
+export function createTilesetFromImageResource(resource, tileWidth, tileHeight, margin = 0, spacing = 0) {
+    return createTilesetFromAtlas(createTextureAtlas({ image: resource }), tileWidth, tileHeight, margin, spacing);
+}
+export async function loadTilesetFromBase64(base64, mimeType, tileWidth, tileHeight, signal) {
+    return createTilesetFromImageResource(await loadImageResourceFromBase64(base64, mimeType, signal), tileWidth, tileHeight);
+}
+export async function loadTilesetFromBlob(blob, tileWidth, tileHeight, signal) {
+    return createTilesetFromImageResource(await loadImageResourceFromBlob(blob, signal), tileWidth, tileHeight);
+}
+export async function loadTilesetFromBytes(bytes, tileWidth, tileHeight, mimeType, signal) {
+    return createTilesetFromImageResource(await loadImageResourceFromBytes(bytes, mimeType, signal), tileWidth, tileHeight);
+}
+export async function loadTilesetFromUrl(url, tileWidth, tileHeight, crossOrigin, signal) {
+    return createTilesetFromImageResource(await loadImageResourceFromUrl(url, crossOrigin, signal), tileWidth, tileHeight);
+}
+//# sourceMappingURL=tilesetFrom.js.map

package/dist/tilesetFrom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilesetFrom.js","sourceRoot":"","sources":["../src/tilesetFrom.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG5D,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/D,0FAA0F;AAC1F,wFAAwF;AACxF,wEAAwE;AACxE,MAAM,UAAU,sBAAsB,CACpC,KAAmB,EACnB,SAAiB,EACjB,UAAkB,EAClB,SAAiB,CAAC,EAClB,UAAkB,CAAC;IAEnB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,MAAM,OAAO,GACX,KAAK,KAAK,IAAI,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjH,MAAM,IAAI,GACR,KAAK,KAAK,IAAI,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpH,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IAChG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,8BAA8B,CAC5C,QAAuB,EACvB,SAAiB,EACjB,UAAkB,EAClB,SAAiB,CAAC,EAClB,UAAkB,CAAC;IAEnB,OAAO,sBAAsB,CAAC,kBAAkB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACjH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAc,EACd,QAAgB,EAChB,SAAiB,EACjB,UAAkB,EAClB,MAAoB;IAEpB,OAAO,8BAA8B,CACnC,MAAM,2BAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,EAC3D,SAAS,EACT,UAAU,CACX,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAU,EACV,SAAiB,EACjB,UAAkB,EAClB,MAAoB;IAEpB,OAAO,8BAA8B,CAAC,MAAM,yBAAyB,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AAC9G,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAiB,EACjB,SAAiB,EACjB,UAAkB,EAClB,QAAiB,EACjB,MAAoB;IAEpB,OAAO,8BAA8B,CACnC,MAAM,0BAA0B,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,EACzD,SAAS,EACT,UAAU,CACX,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,GAAW,EACX,SAAiB,EACjB,UAAkB,EAClB,WAAoB,EACpB,MAAoB;IAEpB,OAAO,8BAA8B,CACnC,MAAM,wBAAwB,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,CAAC,EACxD,SAAS,EACT,UAAU,CACX,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@flighthq/tileset",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/entity": "0.1.0",
+    "@flighthq/image": "0.1.0",
+    "@flighthq/textureatlas": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Tilesets: uniform-grid texture atlases and constructors from images",
+  "sideEffects": false
+}

package/src/tileset.test.ts

@@ -0,0 +1,123 @@
+import { createImageResourceFromImageElement } from '@flighthq/image';
+import { createTextureAtlas } from '@flighthq/textureatlas';
+import type { TextureAtlas, Tileset } from '@flighthq/types';
+
+import { buildTilesetRegions, createTileset } from './tileset';
+
+describe('buildTilesetRegions', () => {
+  it('advances y by tileHeight for each row', () => {
+    const source = createImageResourceFromImageElement({ width: 32, height: 64 } as HTMLImageElement);
+    const atlas = createTextureAtlas({ image: source });
+    const tileset = createTileset({ atlas, columns: 1, rows: 2, tileWidth: 32, tileHeight: 32 });
+    buildTilesetRegions(tileset);
+    // region 0: column=0, row=0 → x=0, y=0
+    expect(atlas.regions[0].x).toBe(0);
+    expect(atlas.regions[0].y).toBe(0);
+    // region 1: column=0, row=1 → x=0, y=32
+    expect(atlas.regions[1].x).toBe(0);
+    expect(atlas.regions[1].y).toBe(32);
+  });
+
+  it('does nothing when atlas is null', () => {
+    const tileset = createTileset({ columns: 2, rows: 2, tileWidth: 32, tileHeight: 32 });
+    expect(buildTilesetRegions(tileset)).toBeUndefined();
+    expect(tileset.atlas).toBeNull();
+  });
+
+  it('honors margin offset for each region', () => {
+    const source = createImageResourceFromImageElement({ width: 68, height: 34 } as HTMLImageElement);
+    const atlas = createTextureAtlas({ image: source });
+    const tileset = createTileset({ atlas, columns: 2, rows: 1, tileWidth: 32, tileHeight: 32, margin: 2 });
+    buildTilesetRegions(tileset);
+    // margin=2: first tile starts at x=2, second at x=2+32=34
+    expect(atlas.regions[0].x).toBe(2);
+    expect(atlas.regions[0].y).toBe(2);
+    expect(atlas.regions[1].x).toBe(34);
+    expect(atlas.regions[1].y).toBe(2);
+  });
+
+  it('honors spacing gap between tiles', () => {
+    const source = createImageResourceFromImageElement({ width: 66, height: 32 } as HTMLImageElement);
+    const atlas = createTextureAtlas({ image: source });
+    // spacing=2: two 32x32 tiles with a 2px gap between them
+    const tileset = createTileset({ atlas, columns: 2, rows: 1, tileWidth: 32, tileHeight: 32, spacing: 2 });
+    buildTilesetRegions(tileset);
+    // region 0: x=0, region 1: x=32+2=34
+    expect(atlas.regions[0].x).toBe(0);
+    expect(atlas.regions[1].x).toBe(34);
+  });
+
+  it('positions regions at (column * tileWidth, row * tileHeight)', () => {
+    const source = createImageResourceFromImageElement({ width: 64, height: 32 } as HTMLImageElement);
+    const atlas = createTextureAtlas({ image: source });
+    const tileset = createTileset({ atlas, columns: 2, rows: 1, tileWidth: 32, tileHeight: 32 });
+    buildTilesetRegions(tileset);
+    // region 0: column=0, row=0 → x=0, y=0
+    expect(atlas.regions[0].x).toBe(0);
+    expect(atlas.regions[0].y).toBe(0);
+    // region 1: column=1, row=0 → x=32, y=0
+    expect(atlas.regions[1].x).toBe(32);
+    expect(atlas.regions[1].y).toBe(0);
+  });
+
+  it('reuses existing region objects when capacity is already available', () => {
+    const source = createImageResourceFromImageElement({ width: 64, height: 32 } as HTMLImageElement);
+    const atlas = createTextureAtlas({ image: source });
+    const firstRegion = {} as TextureAtlas['regions'][number];
+    const secondRegion = {} as TextureAtlas['regions'][number];
+    atlas.regions.push(firstRegion, secondRegion);
+    const tileset = createTileset({ atlas, columns: 2, rows: 1, tileWidth: 32, tileHeight: 32 });
+
+    buildTilesetRegions(tileset);
+
+    expect(atlas.regions).toHaveLength(2);
+    expect(atlas.regions[0]).toBe(firstRegion);
+    expect(atlas.regions[1]).toBe(secondRegion);
+    expect(atlas.regions[0].x).toBe(0);
+    expect(atlas.regions[1].x).toBe(32);
+  });
+});
+
+describe('createTileset', () => {
+  let tileset: Tileset;
+
+  beforeEach(() => {
+    tileset = createTileset();
+  });
+
+  it('allows pre-defined values', () => {
+    const base = {
+      atlas: {} as TextureAtlas,
+      tileWidth: 10,
+      tileHeight: 20,
+      rows: 1,
+      columns: 2,
+      margin: 4,
+      spacing: 2,
+    };
+    const obj = createTileset(base);
+    expect(obj.atlas).toStrictEqual(base.atlas);
+    expect(obj.tileWidth).toStrictEqual(base.tileWidth);
+    expect(obj.tileHeight).toStrictEqual(base.tileHeight);
+    expect(obj.rows).toStrictEqual(base.rows);
+    expect(obj.columns).toStrictEqual(base.columns);
+    expect(obj.margin).toStrictEqual(base.margin);
+    expect(obj.spacing).toStrictEqual(base.spacing);
+  });
+
+  it('initializes default values', () => {
+    expect(tileset.atlas).toBeNull();
+    expect(tileset.tileWidth).toStrictEqual(0);
+    expect(tileset.tileHeight).toStrictEqual(0);
+    expect(tileset.rows).toStrictEqual(0);
+    expect(tileset.columns).toStrictEqual(0);
+    expect(tileset.margin).toStrictEqual(0);
+    expect(tileset.spacing).toStrictEqual(0);
+  });
+
+  it('returns a new object for better hidden-class performance', () => {
+    const base = {};
+    const obj = createTileset(base);
+    expect(obj).not.toStrictEqual(base);
+  });
+});

package/src/tilesetFrom.test.ts

@@ -0,0 +1,131 @@
+import { createImageResourceFromImageElement } from '@flighthq/image';
+import { createTextureAtlas } from '@flighthq/textureatlas';
+
+import {
+  createTilesetFromAtlas,
+  createTilesetFromImageResource,
+  loadTilesetFromBase64,
+  loadTilesetFromBlob,
+  loadTilesetFromBytes,
+  loadTilesetFromUrl,
+} from './tilesetFrom';
+
+function makeAtlas(width: number, height: number) {
+  const source = createImageResourceFromImageElement({ width, height } as HTMLImageElement);
+  return createTextureAtlas({ image: source });
+}
+
+// Stub img.decode() so async load functions resolve immediately in jsdom.
+beforeEach(() => {
+  HTMLImageElement.prototype.decode = vi.fn().mockResolvedValue(undefined);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  delete (HTMLImageElement.prototype as Partial<HTMLImageElement>).decode;
+});
+
+describe('createTilesetFromAtlas', () => {
+  it('accounts for margin and spacing when computing rows and columns', () => {
+    // 2px margin on each side, 2px spacing between tiles: (70 - 4 + 2) / (32 + 2) = 68/34 = 2
+    const atlas = makeAtlas(70, 70);
+    const tileset = createTilesetFromAtlas(atlas, 32, 32, 2, 2);
+    expect(tileset.columns).toBe(2);
+    expect(tileset.rows).toBe(2);
+    expect(tileset.margin).toBe(2);
+    expect(tileset.spacing).toBe(2);
+  });
+
+  it('derives rows and columns from atlas image dimensions', () => {
+    const atlas = makeAtlas(64, 32);
+    const tileset = createTilesetFromAtlas(atlas, 32, 32);
+
+    expect(tileset.columns).toBe(2);
+    expect(tileset.rows).toBe(1);
+    expect(tileset.tileWidth).toBe(32);
+    expect(tileset.tileHeight).toBe(32);
+  });
+
+  it('initializes atlas regions for each tile', () => {
+    const atlas = makeAtlas(64, 32);
+    createTilesetFromAtlas(atlas, 32, 32);
+
+    expect(atlas.regions).toHaveLength(2);
+  });
+
+  it('uses the provided atlas', () => {
+    const atlas = makeAtlas(32, 32);
+    const tileset = createTilesetFromAtlas(atlas, 32, 32);
+
+    expect(tileset.atlas).toBe(atlas);
+  });
+
+  it('yields zero rows and columns when atlas image is null', () => {
+    const atlas = createTextureAtlas();
+    const tileset = createTilesetFromAtlas(atlas, 32, 32);
+
+    expect(tileset.rows).toBe(0);
+    expect(tileset.columns).toBe(0);
+    expect(atlas.regions).toHaveLength(0);
+  });
+});
+
+describe('createTilesetFromImageResource', () => {
+  it('creates an atlas and tileset from an ImageResource', () => {
+    const source = createImageResourceFromImageElement({ width: 128, height: 64 } as HTMLImageElement);
+    const tileset = createTilesetFromImageResource(source, 32, 32);
+
+    expect(tileset.columns).toBe(4);
+    expect(tileset.rows).toBe(2);
+    expect(tileset.atlas?.image).toBe(source);
+  });
+
+  it('initializes regions for each tile', () => {
+    const source = createImageResourceFromImageElement({ width: 64, height: 32 } as HTMLImageElement);
+    const tileset = createTilesetFromImageResource(source, 32, 32);
+
+    expect(tileset.atlas?.regions).toHaveLength(2);
+  });
+});
+
+describe('loadTilesetFromBase64', () => {
+  it('resolves to a Tileset with the correct tile dimensions', async () => {
+    const tileset = await loadTilesetFromBase64('abc123', 'image/png', 16, 16);
+    expect(tileset.tileWidth).toBe(16);
+    expect(tileset.tileHeight).toBe(16);
+    expect(tileset.atlas?.image?.source).toBeInstanceOf(HTMLImageElement);
+  });
+});
+
+describe('loadTilesetFromBlob', () => {
+  it('resolves to a Tileset with a non-null atlas image', async () => {
+    const blob = new Blob([], { type: 'image/png' });
+    const tileset = await loadTilesetFromBlob(blob, 32, 32);
+    expect(tileset.atlas?.image?.source).toBeInstanceOf(HTMLImageElement);
+  });
+});
+
+describe('loadTilesetFromBytes', () => {
+  it('resolves to a Tileset with tileWidth and tileHeight set', async () => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0, 0, 0, 0, 0]);
+    const tileset = await loadTilesetFromBytes(bytes, 32, 16);
+
+    expect(tileset.tileWidth).toBe(32);
+    expect(tileset.tileHeight).toBe(16);
+    expect(tileset.atlas?.image?.source).toBeInstanceOf(HTMLImageElement);
+  });
+
+  it('throws when mime type cannot be detected', async () => {
+    const bytes = new Uint8Array(16);
+    await expect(loadTilesetFromBytes(bytes, 32, 32)).rejects.toThrow('Unable to determine image type');
+  });
+});
+
+describe('loadTilesetFromUrl', () => {
+  it('resolves to a Tileset with the correct tile dimensions', async () => {
+    const tileset = await loadTilesetFromUrl('data:image/png;base64,abc', 32, 32);
+    expect(tileset.tileWidth).toBe(32);
+    expect(tileset.tileHeight).toBe(32);
+    expect(tileset.atlas?.image?.source).toBeInstanceOf(HTMLImageElement);
+  });
+});