@flighthq/textureatlas 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './textureAtlas';
+export * from './textureAtlasFrom';
+export * from './textureAtlasRegion';
+//# 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,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './textureAtlas';
+export * from './textureAtlasFrom';
+export * from './textureAtlasRegion';
+//# 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,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC"}

package/dist/textureAtlas.d.ts

@@ -0,0 +1,4 @@
+import type { TextureAtlas } from '@flighthq/types';
+export declare function createTextureAtlas(obj?: Partial<TextureAtlas>): TextureAtlas;
+export declare function getTextureAtlasByteSize(atlas: Readonly<TextureAtlas>): number;
+//# sourceMappingURL=textureAtlas.d.ts.map

package/dist/textureAtlas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textureAtlas.d.ts","sourceRoot":"","sources":["../src/textureAtlas.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAK5E;AAID,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,MAAM,CAE7E"}

package/dist/textureAtlas.js

@@ -0,0 +1,14 @@
+import { createEntity } from '@flighthq/entity';
+import { getImageResourceByteSize } from '@flighthq/image';
+export function createTextureAtlas(obj) {
+    return createEntity({
+        image: obj?.image ?? null,
+        regions: obj?.regions ?? [],
+    });
+}
+// Returns the byte footprint of the atlas's CPU-side image data. Equivalent to calling
+// `getImageResourceByteSize` on the atlas image; returns 0 when the image is null or element-only.
+export function getTextureAtlasByteSize(atlas) {
+    return atlas.image !== null ? getImageResourceByteSize(atlas.image) : 0;
+}
+//# sourceMappingURL=textureAtlas.js.map

package/dist/textureAtlas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textureAtlas.js","sourceRoot":"","sources":["../src/textureAtlas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAG3D,MAAM,UAAU,kBAAkB,CAAC,GAA2B;IAC5D,OAAO,YAAY,CAAC;QAClB,KAAK,EAAE,GAAG,EAAE,KAAK,IAAI,IAAI;QACzB,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,EAAE;KAC5B,CAAC,CAAC;AACL,CAAC;AAED,uFAAuF;AACvF,mGAAmG;AACnG,MAAM,UAAU,uBAAuB,CAAC,KAA6B;IACnE,OAAO,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,wBAAwB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1E,CAAC"}

package/dist/textureAtlasFrom.d.ts

@@ -0,0 +1,10 @@
+import type { ImageResource, TextureAtlas } from '@flighthq/types';
+export declare function createTextureAtlasFromCanvas(canvas: HTMLCanvasElement): TextureAtlas;
+export declare function createTextureAtlasFromImageBitmap(bitmap: ImageBitmap): TextureAtlas;
+export declare function createTextureAtlasFromImageElement(img: HTMLImageElement): TextureAtlas;
+export declare function createTextureAtlasFromImageResource(resource: ImageResource): TextureAtlas;
+export declare function loadTextureAtlasFromBase64(base64: string, mimeType: string, signal?: AbortSignal): Promise<TextureAtlas>;
+export declare function loadTextureAtlasFromBlob(blob: Blob, signal?: AbortSignal): Promise<TextureAtlas>;
+export declare function loadTextureAtlasFromBytes(bytes: Uint8Array, mimeType?: string, signal?: AbortSignal): Promise<TextureAtlas>;
+export declare function loadTextureAtlasFromUrl(url: string, crossOrigin?: string, signal?: AbortSignal): Promise<TextureAtlas>;
+//# sourceMappingURL=textureAtlasFrom.d.ts.map

package/dist/textureAtlasFrom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textureAtlasFrom.d.ts","sourceRoot":"","sources":["../src/textureAtlasFrom.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAInE,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,CAEpF;AAED,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAEnF;AAED,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,gBAAgB,GAAG,YAAY,CAEtF;AAED,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,aAAa,GAAG,YAAY,CAEzF;AAED,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAEtG;AAED,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,CAAC,CAEvB"}

package/dist/textureAtlasFrom.js

@@ -0,0 +1,27 @@
+import { createImageResourceFromCanvas, createImageResourceFromImageBitmap, createImageResourceFromImageElement, loadImageResourceFromBase64, loadImageResourceFromBlob, loadImageResourceFromBytes, loadImageResourceFromUrl, } from '@flighthq/image';
+import { createTextureAtlas } from './textureAtlas';
+export function createTextureAtlasFromCanvas(canvas) {
+    return createTextureAtlas({ image: createImageResourceFromCanvas(canvas) });
+}
+export function createTextureAtlasFromImageBitmap(bitmap) {
+    return createTextureAtlas({ image: createImageResourceFromImageBitmap(bitmap) });
+}
+export function createTextureAtlasFromImageElement(img) {
+    return createTextureAtlas({ image: createImageResourceFromImageElement(img) });
+}
+export function createTextureAtlasFromImageResource(resource) {
+    return createTextureAtlas({ image: resource });
+}
+export async function loadTextureAtlasFromBase64(base64, mimeType, signal) {
+    return createTextureAtlasFromImageResource(await loadImageResourceFromBase64(base64, mimeType, signal));
+}
+export async function loadTextureAtlasFromBlob(blob, signal) {
+    return createTextureAtlasFromImageResource(await loadImageResourceFromBlob(blob, signal));
+}
+export async function loadTextureAtlasFromBytes(bytes, mimeType, signal) {
+    return createTextureAtlasFromImageResource(await loadImageResourceFromBytes(bytes, mimeType, signal));
+}
+export async function loadTextureAtlasFromUrl(url, crossOrigin, signal) {
+    return createTextureAtlasFromImageResource(await loadImageResourceFromUrl(url, crossOrigin, signal));
+}
+//# sourceMappingURL=textureAtlasFrom.js.map

package/dist/textureAtlasFrom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textureAtlasFrom.js","sourceRoot":"","sources":["../src/textureAtlasFrom.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,kCAAkC,EAClC,mCAAmC,EACnC,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,MAAM,UAAU,4BAA4B,CAAC,MAAyB;IACpE,OAAO,kBAAkB,CAAC,EAAE,KAAK,EAAE,6BAA6B,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,iCAAiC,CAAC,MAAmB;IACnE,OAAO,kBAAkB,CAAC,EAAE,KAAK,EAAE,kCAAkC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,kCAAkC,CAAC,GAAqB;IACtE,OAAO,kBAAkB,CAAC,EAAE,KAAK,EAAE,mCAAmC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,mCAAmC,CAAC,QAAuB;IACzE,OAAO,kBAAkB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,MAAc,EACd,QAAgB,EAChB,MAAoB;IAEpB,OAAO,mCAAmC,CAAC,MAAM,2BAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAC1G,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,IAAU,EAAE,MAAoB;IAC7E,OAAO,mCAAmC,CAAC,MAAM,yBAAyB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAAiB,EACjB,QAAiB,EACjB,MAAoB;IAEpB,OAAO,mCAAmC,CAAC,MAAM,0BAA0B,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AACxG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,GAAW,EACX,WAAoB,EACpB,MAAoB;IAEpB,OAAO,mCAAmC,CAAC,MAAM,wBAAwB,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;AACvG,CAAC"}

package/dist/textureAtlasRegion.d.ts

@@ -0,0 +1,12 @@
+import type { RectangleLike, TextureAtlas, TextureAtlasRegion, TextureAtlasRegionLike, Vector2Like } from '@flighthq/types';
+export declare function addTextureAtlasRegion(target: TextureAtlas, x: number, y: number, width: number, height: number, pivotX?: number, pivotY?: number, name?: string): void;
+export declare function addTextureAtlasRegionRectangle(target: TextureAtlas, rect: Readonly<RectangleLike>, pivot?: Readonly<Vector2Like>, name?: string): void;
+export declare function addTextureAtlasRegionRectangleXY(target: TextureAtlas, ax: number, ay: number, bx: number, by: number, pivotX?: number, pivotY?: number, name?: string): void;
+export declare function addTextureAtlasRegionVector2(target: TextureAtlas, a: Readonly<Vector2Like>, b: Readonly<Vector2Like>, pivot?: Readonly<Vector2Like>, name?: string): void;
+export declare function createTextureAtlasRegion(obj?: Partial<TextureAtlasRegionLike>): TextureAtlasRegion;
+export declare function getTextureAtlasRegionById(atlas: Readonly<TextureAtlas>, id: number): TextureAtlasRegion | null;
+export declare function getTextureAtlasRegionByName(atlas: Readonly<TextureAtlas>, name: string): TextureAtlasRegion | null;
+export declare function getTextureAtlasRegionSequence(atlas: Readonly<TextureAtlas>, prefix: string): TextureAtlasRegion[];
+export declare function getTextureAtlasRegionUv(region: Readonly<TextureAtlasRegion>, imageWidth: number, imageHeight: number, out: RectangleLike): RectangleLike;
+export declare function setTextureAtlasRegion(out: TextureAtlasRegion, x: number, y?: number, width?: number, height?: number, pivotX?: number, pivotY?: number): void;
+//# sourceMappingURL=textureAtlasRegion.d.ts.map

package/dist/textureAtlasRegion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textureAtlasRegion.d.ts","sourceRoot":"","sources":["../src/textureAtlasRegion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,WAAW,EACZ,MAAM,iBAAiB,CAAC;AAEzB,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAaN;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC7B,KAAK,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAWN;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,YAAY,EACpB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAEN;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,YAAY,EACpB,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,EACxB,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,EACxB,KAAK,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC7B,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAWN;AAED,wBAAgB,wBAAwB,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,kBAAkB,CAiBlG;AAGD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAK9G;AAID,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAKlH;AAKD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAMjH;AAQD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACpC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,aAAa,GACjB,aAAa,CAkBf;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,EACvB,CAAC,EAAE,MAAM,EACT,CAAC,GAAE,MAAU,EACb,KAAK,GAAE,MAAU,EACjB,MAAM,GAAE,MAAU,EAClB,MAAM,GAAE,MAAU,EAClB,MAAM,GAAE,MAAU,GACjB,IAAI,CAON"}

package/dist/textureAtlasRegion.js

@@ -0,0 +1,102 @@
+import { createEntity } from '@flighthq/entity';
+export function addTextureAtlasRegion(target, x, y, width, height, pivotX, pivotY, name) {
+    target.regions.push(createTextureAtlasRegion({
+        x: x,
+        y: y,
+        width: width,
+        height: height,
+        id: target.regions.length,
+        pivotX: pivotX ?? null,
+        pivotY: pivotY ?? null,
+        name: name ?? null,
+    }));
+}
+export function addTextureAtlasRegionRectangle(target, rect, pivot, name) {
+    addTextureAtlasRegion(target, rect.x, rect.y, rect.width, rect.height, pivot ? pivot.x : undefined, pivot ? pivot.y : undefined, name);
+}
+export function addTextureAtlasRegionRectangleXY(target, ax, ay, bx, by, pivotX, pivotY, name) {
+    addTextureAtlasRegion(target, ax, ay, bx - ax, by - ay, pivotX, pivotY, name);
+}
+export function addTextureAtlasRegionVector2(target, a, b, pivot, name) {
+    addTextureAtlasRegion(target, a.x, a.y, b.x - a.x, b.y - a.y, pivot ? pivot.x : undefined, pivot ? pivot.y : undefined, name);
+}
+export function createTextureAtlasRegion(obj) {
+    return createEntity({
+        x: obj?.x ?? 0,
+        y: obj?.y ?? 0,
+        width: obj?.width ?? 0,
+        height: obj?.height ?? 0,
+        id: obj?.id ?? -1,
+        name: obj?.name ?? null,
+        originalHeight: obj?.originalHeight ?? null,
+        originalWidth: obj?.originalWidth ?? null,
+        pivotX: obj?.pivotX ?? null,
+        pivotY: obj?.pivotY ?? null,
+        rotated: obj?.rotated ?? false,
+        sourceX: obj?.sourceX ?? 0,
+        sourceY: obj?.sourceY ?? 0,
+        trimmed: obj?.trimmed ?? false,
+    });
+}
+// Returns the first region with the given id, or null if not found.
+export function getTextureAtlasRegionById(atlas, id) {
+    for (const region of atlas.regions) {
+        if (region.id === id)
+            return region;
+    }
+    return null;
+}
+// Returns the first region whose name matches exactly, or null if not found.
+// Case-sensitive. Linear scan — acceptable for typical atlas sizes (< 2000 regions).
+export function getTextureAtlasRegionByName(atlas, name) {
+    for (const region of atlas.regions) {
+        if (region.name === name)
+            return region;
+    }
+    return null;
+}
+// Returns all regions whose name starts with the given prefix, in insertion order.
+// Useful for collecting animation frame sequences following a `baseName_NNN` naming convention.
+// Returns an empty array when no region names match.
+export function getTextureAtlasRegionSequence(atlas, prefix) {
+    const result = [];
+    for (const region of atlas.regions) {
+        if (region.name !== null && region.name.startsWith(prefix))
+            result.push(region);
+    }
+    return result;
+}
+// Writes normalized UV coordinates (0–1) for the region into `out`.
+// Accounts for the atlas image dimensions: `out.x = region.x / imageWidth`, etc.
+// When `region.rotated` is true the packed rectangle is transposed — the UV rect still
+// covers the packed (rotated) texels; callers drawing a rotated region must swap width/height.
+// Returns `out` for chaining. Returns `out` with all zeros when `imageWidth` or `imageHeight`
+// is zero to avoid division by zero.
+export function getTextureAtlasRegionUv(region, imageWidth, imageHeight, out) {
+    if (imageWidth <= 0 || imageHeight <= 0) {
+        out.x = 0;
+        out.y = 0;
+        out.width = 0;
+        out.height = 0;
+        return out;
+    }
+    // Read all inputs before writing — alias-safe.
+    const rx = region.x;
+    const ry = region.y;
+    const rw = region.width;
+    const rh = region.height;
+    out.x = rx / imageWidth;
+    out.y = ry / imageHeight;
+    out.width = rw / imageWidth;
+    out.height = rh / imageHeight;
+    return out;
+}
+export function setTextureAtlasRegion(out, x, y = 0, width = 0, height = 0, pivotX = 0, pivotY = 0) {
+    out.x = x;
+    out.y = y;
+    out.width = width;
+    out.height = height;
+    out.pivotX = pivotX;
+    out.pivotY = pivotY;
+}
+//# sourceMappingURL=textureAtlasRegion.js.map

package/dist/textureAtlasRegion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textureAtlasRegion.js","sourceRoot":"","sources":["../src/textureAtlasRegion.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@flighthq/textureatlas",
+  "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/geometry": "0.1.0",
+    "@flighthq/image": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Texture atlases and tilesets: regions, UVs, and constructors over image resources",
+  "sideEffects": false
+}

package/src/textureAtlas.test.ts

@@ -0,0 +1,59 @@
+import { createImageResource } from '@flighthq/image';
+import type { ImageResource, TextureAtlas, TextureAtlasRegion } from '@flighthq/types';
+
+import { createTextureAtlas, getTextureAtlasByteSize } from './textureAtlas';
+
+describe('createTextureAtlas', () => {
+  let atlas: TextureAtlas;
+
+  beforeEach(() => {
+    atlas = createTextureAtlas();
+  });
+
+  it('allows pre-defined values', () => {
+    const base = {
+      image: {} as ImageResource,
+      regions: [{} as TextureAtlasRegion],
+    };
+    const obj = createTextureAtlas(base);
+    expect(obj.image).toStrictEqual(base.image);
+    expect(obj.regions).toStrictEqual(base.regions);
+  });
+
+  it('initializes default values', () => {
+    expect(atlas.image).toBeNull();
+    expect(atlas.regions).toEqual([]);
+  });
+
+  it('returns a new object for better hidden-class performance', () => {
+    const base = {};
+    const obj = createTextureAtlas(base);
+    expect(obj).not.toStrictEqual(base);
+  });
+
+  it('uses a provided regions array directly', () => {
+    const regions = [{} as TextureAtlasRegion];
+    const atlas = createTextureAtlas({ regions });
+    expect(atlas.regions).toBe(regions);
+  });
+});
+
+describe('getTextureAtlasByteSize', () => {
+  it('returns 0 when the atlas has no image', () => {
+    const atlas = createTextureAtlas();
+    expect(getTextureAtlasByteSize(atlas)).toBe(0);
+  });
+
+  it('returns 0 when the atlas image has no data (element-only)', () => {
+    const image = createImageResource();
+    const atlas = createTextureAtlas({ image });
+    expect(getTextureAtlasByteSize(atlas)).toBe(0);
+  });
+
+  it('returns the image data byteLength when data is present', () => {
+    const image = createImageResource();
+    image.data = new Uint8ClampedArray(256);
+    const atlas = createTextureAtlas({ image });
+    expect(getTextureAtlasByteSize(atlas)).toBe(256);
+  });
+});

package/src/textureAtlasFrom.test.ts

@@ -0,0 +1,142 @@
+import { createImageResourceFromImageElement } from '@flighthq/image';
+
+import {
+  createTextureAtlasFromCanvas,
+  createTextureAtlasFromImageBitmap,
+  createTextureAtlasFromImageElement,
+  createTextureAtlasFromImageResource,
+  loadTextureAtlasFromBase64,
+  loadTextureAtlasFromBlob,
+  loadTextureAtlasFromBytes,
+  loadTextureAtlasFromUrl,
+} from './textureAtlasFrom';
+
+// 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('createTextureAtlasFromCanvas', () => {
+  it('wraps a canvas with correct dimensions', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 320;
+    canvas.height = 240;
+    const atlas = createTextureAtlasFromCanvas(canvas);
+
+    expect(atlas.image?.source).toBe(canvas);
+    expect(atlas.image?.width).toBe(320);
+    expect(atlas.image?.height).toBe(240);
+  });
+
+  it('starts with an empty regions array', () => {
+    const canvas = document.createElement('canvas');
+    expect(createTextureAtlasFromCanvas(canvas).regions).toHaveLength(0);
+  });
+
+  it('returns a new object each call', () => {
+    const canvas = document.createElement('canvas');
+    expect(createTextureAtlasFromCanvas(canvas)).not.toBe(createTextureAtlasFromCanvas(canvas));
+  });
+});
+
+describe('createTextureAtlasFromImageBitmap', () => {
+  it('wraps an ImageBitmap with correct dimensions', () => {
+    const bitmap = { width: 64, height: 128, close: () => {} } as ImageBitmap;
+    const atlas = createTextureAtlasFromImageBitmap(bitmap);
+
+    expect(atlas.image?.source).toBe(bitmap);
+    expect(atlas.image?.width).toBe(64);
+    expect(atlas.image?.height).toBe(128);
+  });
+
+  it('returns a new object each call', () => {
+    const bitmap = { width: 1, height: 1, close: () => {} } as ImageBitmap;
+    expect(createTextureAtlasFromImageBitmap(bitmap)).not.toBe(createTextureAtlasFromImageBitmap(bitmap));
+  });
+});
+
+describe('createTextureAtlasFromImageElement', () => {
+  it('wraps an HTMLImageElement with correct dimensions', () => {
+    const img = { width: 200, height: 100 } as HTMLImageElement;
+    const atlas = createTextureAtlasFromImageElement(img);
+
+    expect(atlas.image?.source).toBe(img);
+    expect(atlas.image?.width).toBe(200);
+    expect(atlas.image?.height).toBe(100);
+  });
+
+  it('returns a new object each call', () => {
+    const img = document.createElement('img');
+    expect(createTextureAtlasFromImageElement(img)).not.toBe(createTextureAtlasFromImageElement(img));
+  });
+});
+
+describe('createTextureAtlasFromImageResource', () => {
+  it('uses the provided ImageResource as the atlas image', () => {
+    const source = createImageResourceFromImageElement({ width: 128, height: 64 } as HTMLImageElement);
+    const atlas = createTextureAtlasFromImageResource(source);
+
+    expect(atlas.image).toBe(source);
+    expect(atlas.image?.width).toBe(128);
+    expect(atlas.image?.height).toBe(64);
+  });
+
+  it('starts with an empty regions array', () => {
+    const source = createImageResourceFromImageElement({ width: 1, height: 1 } as HTMLImageElement);
+    expect(createTextureAtlasFromImageResource(source).regions).toHaveLength(0);
+  });
+
+  it('returns a new object each call', () => {
+    const source = createImageResourceFromImageElement({ width: 1, height: 1 } as HTMLImageElement);
+    expect(createTextureAtlasFromImageResource(source)).not.toBe(createTextureAtlasFromImageResource(source));
+  });
+});
+
+describe('loadTextureAtlasFromBase64', () => {
+  it('resolves to a TextureAtlas with a non-null image', async () => {
+    const atlas = await loadTextureAtlasFromBase64('abc123', 'image/png');
+    expect(atlas.image?.source).toBeInstanceOf(HTMLImageElement);
+  });
+});
+
+describe('loadTextureAtlasFromBlob', () => {
+  it('resolves to a TextureAtlas with a non-null image', async () => {
+    const blob = new Blob([], { type: 'image/png' });
+    const atlas = await loadTextureAtlasFromBlob(blob);
+    expect(atlas.image?.source).toBeInstanceOf(HTMLImageElement);
+  });
+});
+
+describe('loadTextureAtlasFromBytes', () => {
+  it('resolves to a TextureAtlas with a non-null image', async () => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0, 0, 0, 0, 0]);
+    const atlas = await loadTextureAtlasFromBytes(bytes);
+
+    expect(atlas.image).not.toBeNull();
+    expect(atlas.image?.source).toBeInstanceOf(HTMLImageElement);
+  });
+
+  it('starts with an empty regions array', async () => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0, 0, 0, 0, 0]);
+    const atlas = await loadTextureAtlasFromBytes(bytes);
+
+    expect(atlas.regions).toHaveLength(0);
+  });
+
+  it('throws when mime type cannot be detected', async () => {
+    const bytes = new Uint8Array(16);
+    await expect(loadTextureAtlasFromBytes(bytes)).rejects.toThrow('Unable to determine image type');
+  });
+});
+
+describe('loadTextureAtlasFromUrl', () => {
+  it('resolves to a TextureAtlas whose image src is an HTMLImageElement', async () => {
+    const atlas = await loadTextureAtlasFromUrl('data:image/png;base64,abc');
+    expect(atlas.image?.source).toBeInstanceOf(HTMLImageElement);
+  });
+});

package/src/textureAtlasRegion.test.ts

@@ -0,0 +1,397 @@
+import { createRectangle, createVector2 } from '@flighthq/geometry';
+import type { TextureAtlasRegion } from '@flighthq/types';
+
+import { createTextureAtlas } from './textureAtlas';
+import {
+  addTextureAtlasRegion,
+  addTextureAtlasRegionRectangle,
+  addTextureAtlasRegionRectangleXY,
+  addTextureAtlasRegionVector2,
+  createTextureAtlasRegion,
+  getTextureAtlasRegionById,
+  getTextureAtlasRegionByName,
+  getTextureAtlasRegionSequence,
+  getTextureAtlasRegionUv,
+  setTextureAtlasRegion,
+} from './textureAtlasRegion';
+
+describe('addTextureAtlasRegion', () => {
+  it('pushes a new region onto the atlas with the given coordinates', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 10, 20, 30, 40);
+    expect(atlas.regions).toHaveLength(1);
+    expect(atlas.regions[0].x).toBe(10);
+    expect(atlas.regions[0].y).toBe(20);
+    expect(atlas.regions[0].width).toBe(30);
+    expect(atlas.regions[0].height).toBe(40);
+  });
+
+  it('assigns id equal to the region index before insertion', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10);
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10);
+    expect(atlas.regions[0].id).toBe(0);
+    expect(atlas.regions[1].id).toBe(1);
+  });
+
+  it('sets optional pivot values', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10, 5, 5);
+    expect(atlas.regions[0].pivotX).toBe(5);
+    expect(atlas.regions[0].pivotY).toBe(5);
+  });
+
+  it('sets optional name', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10, undefined, undefined, 'hero');
+    expect(atlas.regions[0].name).toBe('hero');
+  });
+
+  it('defaults name to null when not provided', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10);
+    expect(atlas.regions[0].name).toBeNull();
+  });
+});
+
+describe('addTextureAtlasRegionRectangle', () => {
+  it('accepts rectangle-like and vector-like objects', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegionRectangle(atlas, { x: 10, y: 20, width: 30, height: 40 }, { x: 5, y: 6 });
+    expect(atlas.regions[0].x).toBe(10);
+    expect(atlas.regions[0].y).toBe(20);
+    expect(atlas.regions[0].width).toBe(30);
+    expect(atlas.regions[0].height).toBe(40);
+    expect(atlas.regions[0].pivotX).toBe(5);
+    expect(atlas.regions[0].pivotY).toBe(6);
+  });
+
+  it('adds a region from a Rectangle', () => {
+    const atlas = createTextureAtlas();
+    const rect = createRectangle(10, 20, 30, 40);
+    addTextureAtlasRegionRectangle(atlas, rect);
+    expect(atlas.regions[0].x).toBe(10);
+    expect(atlas.regions[0].width).toBe(30);
+  });
+
+  it('sets optional name', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegionRectangle(atlas, createRectangle(0, 0, 10, 10), undefined, 'frame_00');
+    expect(atlas.regions[0].name).toBe('frame_00');
+  });
+
+  it('sets pivot from optional Vector2', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegionRectangle(atlas, createRectangle(0, 0, 10, 10), createVector2(3, 4));
+    expect(atlas.regions[0].pivotX).toBe(3);
+    expect(atlas.regions[0].pivotY).toBe(4);
+  });
+});
+
+describe('addTextureAtlasRegionRectangleXY', () => {
+  it('computes width and height from corner coordinates', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegionRectangleXY(atlas, 5, 10, 25, 30);
+    expect(atlas.regions[0].x).toBe(5);
+    expect(atlas.regions[0].y).toBe(10);
+    expect(atlas.regions[0].width).toBe(20);
+    expect(atlas.regions[0].height).toBe(20);
+  });
+
+  it('sets optional name', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegionRectangleXY(atlas, 0, 0, 10, 10, undefined, undefined, 'tile_0');
+    expect(atlas.regions[0].name).toBe('tile_0');
+  });
+});
+
+describe('addTextureAtlasRegionVector2', () => {
+  it('accepts vector-like corner and pivot objects', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegionVector2(atlas, { x: 5, y: 10 }, { x: 25, y: 30 }, { x: 3, y: 4 });
+    expect(atlas.regions[0].x).toBe(5);
+    expect(atlas.regions[0].y).toBe(10);
+    expect(atlas.regions[0].width).toBe(20);
+    expect(atlas.regions[0].height).toBe(20);
+    expect(atlas.regions[0].pivotX).toBe(3);
+    expect(atlas.regions[0].pivotY).toBe(4);
+  });
+
+  it('computes region from two Vector2 corner points', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegionVector2(atlas, createVector2(5, 10), createVector2(25, 30));
+    expect(atlas.regions[0].x).toBe(5);
+    expect(atlas.regions[0].y).toBe(10);
+    expect(atlas.regions[0].width).toBe(20);
+    expect(atlas.regions[0].height).toBe(20);
+  });
+
+  it('sets optional name', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegionVector2(atlas, { x: 0, y: 0 }, { x: 10, y: 10 }, undefined, 'walk_01');
+    expect(atlas.regions[0].name).toBe('walk_01');
+  });
+});
+
+describe('createTextureAtlasRegion', () => {
+  let region: TextureAtlasRegion;
+
+  beforeEach(() => {
+    region = createTextureAtlasRegion();
+  });
+
+  it('allows pre-defined values', () => {
+    const base = {
+      x: 1,
+      y: 2,
+      width: 3,
+      height: 4,
+      id: 5,
+      name: 'hero',
+      pivotX: 6,
+      pivotY: 7,
+    };
+    const obj = createTextureAtlasRegion(base);
+    expect(obj.x).toStrictEqual(base.x);
+    expect(obj.y).toStrictEqual(base.y);
+    expect(obj.width).toStrictEqual(base.width);
+    expect(obj.height).toStrictEqual(base.height);
+    expect(obj.id).toStrictEqual(base.id);
+    expect(obj.name).toStrictEqual(base.name);
+    expect(obj.pivotX).toStrictEqual(base.pivotX);
+    expect(obj.pivotY).toStrictEqual(base.pivotY);
+  });
+
+  it('initializes default values', () => {
+    expect(region.x).toStrictEqual(0);
+    expect(region.y).toStrictEqual(0);
+    expect(region.id).toStrictEqual(-1);
+    expect(region.name).toBeNull();
+    expect(region.originalHeight).toBeNull();
+    expect(region.originalWidth).toBeNull();
+    expect(region.pivotX).toBeNull();
+    expect(region.pivotY).toBeNull();
+    expect(region.rotated).toBe(false);
+    expect(region.sourceX).toStrictEqual(0);
+    expect(region.sourceY).toStrictEqual(0);
+    expect(region.trimmed).toBe(false);
+    expect(region.width).toStrictEqual(0);
+    expect(region.height).toStrictEqual(0);
+  });
+
+  it('initializes trim and rotation fields', () => {
+    const trimmed = createTextureAtlasRegion({
+      trimmed: true,
+      rotated: true,
+      sourceX: 4,
+      sourceY: 8,
+      originalWidth: 64,
+      originalHeight: 32,
+    });
+    expect(trimmed.trimmed).toBe(true);
+    expect(trimmed.rotated).toBe(true);
+    expect(trimmed.sourceX).toBe(4);
+    expect(trimmed.sourceY).toBe(8);
+    expect(trimmed.originalWidth).toBe(64);
+    expect(trimmed.originalHeight).toBe(32);
+  });
+
+  it('returns a new object for better hidden-class performance', () => {
+    const base = {};
+    const obj = createTextureAtlasRegion(base);
+    expect(obj).not.toStrictEqual(base);
+  });
+});
+
+describe('getTextureAtlasRegionById', () => {
+  it('returns null for an empty atlas', () => {
+    const atlas = createTextureAtlas();
+    expect(getTextureAtlasRegionById(atlas, 0)).toBeNull();
+  });
+
+  it('returns null when no region matches the id', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10);
+    expect(getTextureAtlasRegionById(atlas, 99)).toBeNull();
+  });
+
+  it('returns the region with the matching id', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10);
+    addTextureAtlasRegion(atlas, 10, 0, 10, 10);
+    const region = getTextureAtlasRegionById(atlas, 1);
+    expect(region).not.toBeNull();
+    expect(region?.x).toBe(10);
+    expect(region?.id).toBe(1);
+  });
+});
+
+describe('getTextureAtlasRegionByName', () => {
+  it('returns null for an empty atlas', () => {
+    const atlas = createTextureAtlas();
+    expect(getTextureAtlasRegionByName(atlas, 'hero')).toBeNull();
+  });
+
+  it('returns null when no region matches the name', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10, undefined, undefined, 'hero');
+    expect(getTextureAtlasRegionByName(atlas, 'villain')).toBeNull();
+  });
+
+  it('returns null for regions with null name', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10);
+    expect(getTextureAtlasRegionByName(atlas, '')).toBeNull();
+  });
+
+  it('returns the region with the matching name', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10, undefined, undefined, 'hero_idle_0');
+    addTextureAtlasRegion(atlas, 10, 0, 10, 10, undefined, undefined, 'hero_walk_0');
+    const region = getTextureAtlasRegionByName(atlas, 'hero_walk_0');
+    expect(region).not.toBeNull();
+    expect(region?.x).toBe(10);
+    expect(region?.name).toBe('hero_walk_0');
+  });
+
+  it('is case-sensitive', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10, undefined, undefined, 'Hero');
+    expect(getTextureAtlasRegionByName(atlas, 'hero')).toBeNull();
+    expect(getTextureAtlasRegionByName(atlas, 'Hero')).not.toBeNull();
+  });
+});
+
+describe('getTextureAtlasRegionSequence', () => {
+  it('returns an empty array when the atlas has no regions', () => {
+    const atlas = createTextureAtlas();
+    expect(getTextureAtlasRegionSequence(atlas, 'walk')).toEqual([]);
+  });
+
+  it('returns regions whose names start with the given prefix', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10, undefined, undefined, 'walk_01');
+    addTextureAtlasRegion(atlas, 10, 0, 10, 10, undefined, undefined, 'walk_02');
+    addTextureAtlasRegion(atlas, 20, 0, 10, 10, undefined, undefined, 'idle_01');
+    const seq = getTextureAtlasRegionSequence(atlas, 'walk');
+    expect(seq).toHaveLength(2);
+    expect(seq[0].name).toBe('walk_01');
+    expect(seq[1].name).toBe('walk_02');
+  });
+
+  it('skips regions with null names', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10);
+    addTextureAtlasRegion(atlas, 10, 0, 10, 10, undefined, undefined, 'walk_01');
+    const seq = getTextureAtlasRegionSequence(atlas, 'walk');
+    expect(seq).toHaveLength(1);
+    expect(seq[0].name).toBe('walk_01');
+  });
+
+  it('returns regions in insertion order', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10, undefined, undefined, 'run_03');
+    addTextureAtlasRegion(atlas, 10, 0, 10, 10, undefined, undefined, 'run_01');
+    addTextureAtlasRegion(atlas, 20, 0, 10, 10, undefined, undefined, 'run_02');
+    const seq = getTextureAtlasRegionSequence(atlas, 'run');
+    expect(seq.map((r) => r.name)).toEqual(['run_03', 'run_01', 'run_02']);
+  });
+
+  it('returns an empty array when no region names match the prefix', () => {
+    const atlas = createTextureAtlas();
+    addTextureAtlasRegion(atlas, 0, 0, 10, 10, undefined, undefined, 'idle_01');
+    expect(getTextureAtlasRegionSequence(atlas, 'walk')).toEqual([]);
+  });
+});
+
+describe('getTextureAtlasRegionUv', () => {
+  it('returns zero rect when imageWidth is zero', () => {
+    const region = createTextureAtlasRegion({ x: 10, y: 20, width: 30, height: 40 });
+    const out = { x: 1, y: 1, width: 1, height: 1 };
+    getTextureAtlasRegionUv(region, 0, 100, out);
+    expect(out).toEqual({ x: 0, y: 0, width: 0, height: 0 });
+  });
+
+  it('returns zero rect when imageHeight is zero', () => {
+    const region = createTextureAtlasRegion({ x: 10, y: 20, width: 30, height: 40 });
+    const out = { x: 1, y: 1, width: 1, height: 1 };
+    getTextureAtlasRegionUv(region, 100, 0, out);
+    expect(out).toEqual({ x: 0, y: 0, width: 0, height: 0 });
+  });
+
+  it('computes normalized UV coordinates', () => {
+    const region = createTextureAtlasRegion({ x: 0, y: 0, width: 128, height: 64 });
+    const out = { x: 0, y: 0, width: 0, height: 0 };
+    getTextureAtlasRegionUv(region, 256, 256, out);
+    expect(out.x).toBe(0);
+    expect(out.y).toBe(0);
+    expect(out.width).toBeCloseTo(0.5);
+    expect(out.height).toBeCloseTo(0.25);
+  });
+
+  it('computes UVs for a region offset within the atlas', () => {
+    const region = createTextureAtlasRegion({ x: 128, y: 64, width: 64, height: 64 });
+    const out = { x: 0, y: 0, width: 0, height: 0 };
+    getTextureAtlasRegionUv(region, 256, 256, out);
+    expect(out.x).toBeCloseTo(0.5);
+    expect(out.y).toBeCloseTo(0.25);
+    expect(out.width).toBeCloseTo(0.25);
+    expect(out.height).toBeCloseTo(0.25);
+  });
+
+  it('is alias-safe when out shares no fields with region', () => {
+    const region = createTextureAtlasRegion({ x: 64, y: 64, width: 64, height: 64 });
+    const out = { x: 0, y: 0, width: 0, height: 0 };
+    const result = getTextureAtlasRegionUv(region, 256, 256, out);
+    expect(result).toBe(out);
+    expect(out.x).toBeCloseTo(0.25);
+    expect(out.y).toBeCloseTo(0.25);
+    expect(out.width).toBeCloseTo(0.25);
+    expect(out.height).toBeCloseTo(0.25);
+  });
+});
+
+describe('setTextureAtlasRegion', () => {
+  it('defaults optional parameters to 0', () => {
+    const region = createTextureAtlasRegion();
+    setTextureAtlasRegion(region, 5);
+    expect(region.x).toBe(5);
+    expect(region.y).toBe(0);
+    expect(region.width).toBe(0);
+    expect(region.height).toBe(0);
+  });
+
+  it('is alias-safe when out is also an input reference', () => {
+    const region = createTextureAtlasRegion({ x: 10, y: 20, width: 30, height: 40 });
+    setTextureAtlasRegion(region, region.x, region.y, region.width, region.height);
+    expect(region.x).toBe(10);
+    expect(region.y).toBe(20);
+    expect(region.width).toBe(30);
+    expect(region.height).toBe(40);
+  });
+
+  it('reuses the existing region object', () => {
+    const region = createTextureAtlasRegion();
+    const target = region;
+    setTextureAtlasRegion(region, 10, 20, 30, 40, 5, 6);
+    expect(region).toBe(target);
+    expect(region.x).toBe(10);
+    expect(region.y).toBe(20);
+    expect(region.width).toBe(30);
+    expect(region.height).toBe(40);
+    expect(region.pivotX).toBe(5);
+    expect(region.pivotY).toBe(6);
+  });
+
+  it('sets all fields on an existing region', () => {
+    const region = createTextureAtlasRegion();
+    const result = setTextureAtlasRegion(region, 10, 20, 30, 40, 5, 6);
+    expect(result).toBeUndefined();
+    expect(region.x).toBe(10);
+    expect(region.y).toBe(20);
+    expect(region.width).toBe(30);
+    expect(region.height).toBe(40);
+    expect(region.pivotX).toBe(5);
+    expect(region.pivotY).toBe(6);
+  });
+});