@flighthq/textureatlas-formats 0.1.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flighthq/textureatlas-formats",
+  "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/textureatlas": "0.1.0",
+    "@flighthq/types": "0.1.0",
+    "@flighthq/xml": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Texture-atlas descriptor format parsers (TexturePacker / Starling / LibGDX / Aseprite -> TextureAtlas)",
+  "sideEffects": false
+}

package/src/textureAtlasAsepriteParse.test.ts

@@ -0,0 +1,131 @@
+import { createTextureAtlas } from '@flighthq/textureatlas';
+
+import { parseTextureAtlasAsepriteDocument, parseTextureAtlasAsepriteJson } from './textureAtlasAsepriteParse';
+import type { TextureAtlasAsepriteArrayDocument, TextureAtlasAsepriteHashDocument } from './textureAtlasAsepriteSchema';
+
+const HASH_DOC: TextureAtlasAsepriteHashDocument = {
+  frames: {
+    'hero_idle.png': {
+      duration: 100,
+      frame: { x: 0, y: 0, w: 64, h: 64 },
+      rotated: false,
+      sourceSize: { w: 64, h: 64 },
+      spriteSourceSize: { x: 0, y: 0, w: 64, h: 64 },
+      trimmed: false,
+    },
+    'hero_walk.png': {
+      duration: 80,
+      frame: { x: 64, y: 0, w: 48, h: 56 },
+      rotated: false,
+      sourceSize: { w: 64, h: 64 },
+      spriteSourceSize: { x: 8, y: 4, w: 48, h: 56 },
+      trimmed: true,
+    },
+  },
+  meta: {
+    app: 'https://www.aseprite.org/',
+    format: 'RGBA8888',
+    image: 'atlas.png',
+    scale: 1,
+    size: { w: 256, h: 256 },
+    version: '1.3',
+  },
+};
+
+const ARRAY_DOC: TextureAtlasAsepriteArrayDocument = {
+  frames: [
+    {
+      duration: 100,
+      filename: 'tile_0.png',
+      frame: { x: 0, y: 0, w: 32, h: 32 },
+      rotated: false,
+      sourceSize: { w: 32, h: 32 },
+      spriteSourceSize: { x: 0, y: 0, w: 32, h: 32 },
+      trimmed: false,
+    },
+  ],
+  meta: {
+    app: 'https://www.aseprite.org/',
+    format: 'RGBA8888',
+    image: 'tiles.png',
+    scale: '1',
+    size: { w: 32, h: 32 },
+    version: '1.3',
+  },
+};
+
+describe('parseTextureAtlasAsepriteDocument', () => {
+  it('populates regions from a hash-format document', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasAsepriteDocument(HASH_DOC, atlas);
+    expect(atlas.regions).toHaveLength(2);
+  });
+  it('populates regions from an array-format document', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasAsepriteDocument(ARRAY_DOC, atlas);
+    expect(atlas.regions).toHaveLength(1);
+    expect(atlas.regions[0].name).toBe('tile_0.png');
+  });
+  it('assigns sequential ids starting at 0', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasAsepriteDocument(ARRAY_DOC, atlas);
+    expect(atlas.regions[0].id).toBe(0);
+  });
+  it('sets x/y/width/height from frame', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasAsepriteDocument(ARRAY_DOC, atlas);
+    expect(atlas.regions[0].x).toBe(0);
+    expect(atlas.regions[0].y).toBe(0);
+    expect(atlas.regions[0].width).toBe(32);
+    expect(atlas.regions[0].height).toBe(32);
+  });
+  it('sets trimmed fields when frame is trimmed', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasAsepriteDocument(HASH_DOC, atlas);
+    const walk = atlas.regions.find((r) => r.name === 'hero_walk.png')!;
+    expect(walk.trimmed).toBe(true);
+    expect(walk.originalWidth).toBe(64);
+    expect(walk.originalHeight).toBe(64);
+    expect(walk.sourceX).toBe(8);
+    expect(walk.sourceY).toBe(4);
+  });
+  it('sets null originalWidth/Height when not trimmed', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasAsepriteDocument(HASH_DOC, atlas);
+    const idle = atlas.regions.find((r) => r.name === 'hero_idle.png')!;
+    expect(idle.trimmed).toBe(false);
+    expect(idle.originalWidth).toBeNull();
+    expect(idle.originalHeight).toBeNull();
+  });
+  it('sets null pivot (Aseprite does not export pivot)', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasAsepriteDocument(ARRAY_DOC, atlas);
+    expect(atlas.regions[0].pivotX).toBeNull();
+    expect(atlas.regions[0].pivotY).toBeNull();
+  });
+  it('clears existing regions before parsing', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasAsepriteDocument(ARRAY_DOC, atlas);
+    parseTextureAtlasAsepriteDocument(ARRAY_DOC, atlas);
+    expect(atlas.regions).toHaveLength(1);
+  });
+  it('returns the atlas for chaining', () => {
+    const atlas = createTextureAtlas();
+    const result = parseTextureAtlasAsepriteDocument(ARRAY_DOC, atlas);
+    expect(result).toBe(atlas);
+  });
+});
+
+describe('parseTextureAtlasAsepriteJson', () => {
+  it('parses a JSON string and populates atlas regions', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasAsepriteJson(JSON.stringify(ARRAY_DOC), atlas);
+    expect(atlas.regions).toHaveLength(1);
+    expect(atlas.regions[0].name).toBe('tile_0.png');
+  });
+  it('returns the atlas for chaining', () => {
+    const atlas = createTextureAtlas();
+    const result = parseTextureAtlasAsepriteJson(JSON.stringify(ARRAY_DOC), atlas);
+    expect(result).toBe(atlas);
+  });
+});

package/src/textureAtlasDetect.test.ts

@@ -0,0 +1,98 @@
+import {
+  TextureAtlasFormatKindAseprite,
+  TextureAtlasFormatKindLibgdxAtlas,
+  TextureAtlasFormatKindStarling,
+  TextureAtlasFormatKindTexturePacker,
+} from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { detectTextureAtlasFormat } from './textureAtlasDetect';
+
+const STARLING_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<TextureAtlas imagePath="atlas.png">
+  <SubTexture name="hero_idle" x="0" y="0" width="64" height="64"/>
+</TextureAtlas>`;
+
+const LIBGDX_ATLAS = `
+atlas.png
+size: 256,256
+format: RGBA8888
+filter: Nearest,Nearest
+repeat: none
+hero_idle
+  rotate: false
+  xy: 0, 0
+  size: 64, 64
+  orig: 64, 64
+  offset: 0, 0
+  index: -1`;
+
+const ASEPRITE_JSON = JSON.stringify({
+  frames: {
+    hero_idle: {
+      frame: { x: 0, y: 0, w: 64, h: 64 },
+      rotated: false,
+      trimmed: false,
+      spriteSourceSize: { x: 0, y: 0, w: 64, h: 64 },
+      sourceSize: { w: 64, h: 64 },
+      duration: 100,
+    },
+  },
+  meta: { app: 'https://www.aseprite.org/', image: 'atlas.png', size: { w: 64, h: 64 }, scale: 1 },
+});
+
+const TEXTUREPACKER_JSON = JSON.stringify({
+  frames: {
+    hero_idle: {
+      frame: { x: 0, y: 0, w: 64, h: 64 },
+      rotated: false,
+      trimmed: false,
+      spriteSourceSize: { x: 0, y: 0, w: 64, h: 64 },
+      sourceSize: { w: 64, h: 64 },
+    },
+  },
+  meta: { app: 'https://www.codeandweb.com/texturepacker', image: 'atlas.png', size: { w: 64, h: 64 }, scale: 1 },
+});
+
+describe('detectTextureAtlasFormat', () => {
+  it('detects Starling XML by its <TextureAtlas> root', () => {
+    expect(detectTextureAtlasFormat(STARLING_XML)).toBe(TextureAtlasFormatKindStarling);
+  });
+
+  it('detects a libGDX / Spine text atlas by its header and region blocks', () => {
+    expect(detectTextureAtlasFormat(LIBGDX_ATLAS)).toBe(TextureAtlasFormatKindLibgdxAtlas);
+  });
+
+  it('detects Aseprite JSON by its meta.app string', () => {
+    expect(detectTextureAtlasFormat(ASEPRITE_JSON)).toBe(TextureAtlasFormatKindAseprite);
+  });
+
+  it('detects TexturePacker JSON by its meta.app string', () => {
+    expect(detectTextureAtlasFormat(TEXTUREPACKER_JSON)).toBe(TextureAtlasFormatKindTexturePacker);
+  });
+
+  it('detects an array-shaped Aseprite document', () => {
+    const arrayDoc = JSON.stringify({
+      frames: [{ filename: 'a', frame: { x: 0, y: 0, w: 1, h: 1 }, duration: 50 }],
+      meta: { app: 'aseprite' },
+    });
+    expect(detectTextureAtlasFormat(arrayDoc)).toBe(TextureAtlasFormatKindAseprite);
+  });
+
+  it('falls back to the per-frame duration field when meta.app is unrecognised', () => {
+    const asepriteNoApp = JSON.stringify({ frames: { a: { duration: 100 } }, meta: { app: 'unknown' } });
+    const packerNoApp = JSON.stringify({ frames: { a: { rotated: false } }, meta: { app: 'unknown' } });
+    expect(detectTextureAtlasFormat(asepriteNoApp)).toBe(TextureAtlasFormatKindAseprite);
+    expect(detectTextureAtlasFormat(packerNoApp)).toBe(TextureAtlasFormatKindTexturePacker);
+  });
+
+  it('returns null for unrecognised, empty, or malformed input', () => {
+    expect(detectTextureAtlasFormat('')).toBeNull();
+    expect(detectTextureAtlasFormat('   ')).toBeNull();
+    expect(detectTextureAtlasFormat('not a known format')).toBeNull();
+    expect(detectTextureAtlasFormat('{ not json')).toBeNull();
+    expect(detectTextureAtlasFormat('<plist><dict></dict></plist>')).toBeNull();
+    expect(detectTextureAtlasFormat('{"meta":{"app":"aseprite"}}')).toBeNull();
+    expect(detectTextureAtlasFormat('[1,2,3]')).toBeNull();
+  });
+});

package/src/textureAtlasLibgdxParse.test.ts

@@ -0,0 +1,114 @@
+import { createTextureAtlas } from '@flighthq/textureatlas';
+
+import { parseTextureAtlasLibgdxAtlas } from './textureAtlasLibgdxParse';
+
+const SIMPLE_ATLAS = `
+atlas.png
+size: 256,256
+format: RGBA8888
+filter: Nearest,Nearest
+repeat: none
+hero_idle
+  rotate: false
+  xy: 0, 0
+  size: 64, 64
+  orig: 64, 64
+  offset: 0, 0
+  index: -1
+hero_walk
+  rotate: false
+  xy: 64, 0
+  size: 48, 56
+  orig: 64, 64
+  offset: 8, 4
+  index: -1
+hero_run
+  rotate: true
+  xy: 112, 0
+  size: 32, 48
+  orig: 48, 32
+  offset: 0, 0
+  index: -1
+`;
+
+describe('parseTextureAtlasLibgdxAtlas', () => {
+  it('populates regions from a libGDX atlas string', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    expect(atlas.regions).toHaveLength(3);
+  });
+  it('assigns sequential ids starting at 0', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    expect(atlas.regions[0].id).toBe(0);
+    expect(atlas.regions[2].id).toBe(2);
+  });
+  it('sets region name', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    expect(atlas.regions[0].name).toBe('hero_idle');
+    expect(atlas.regions[1].name).toBe('hero_walk');
+  });
+  it('sets x/y/width/height from xy and size', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    expect(atlas.regions[0].x).toBe(0);
+    expect(atlas.regions[0].y).toBe(0);
+    expect(atlas.regions[0].width).toBe(64);
+    expect(atlas.regions[0].height).toBe(64);
+    expect(atlas.regions[1].x).toBe(64);
+    expect(atlas.regions[1].width).toBe(48);
+  });
+  it('sets trimmed fields when orig differs from size', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    const walk = atlas.regions[1];
+    expect(walk.trimmed).toBe(true);
+    expect(walk.originalWidth).toBe(64);
+    expect(walk.originalHeight).toBe(64);
+    expect(walk.sourceX).toBe(8);
+    expect(walk.sourceY).toBe(4);
+  });
+  it('marks non-trimmed regions correctly', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    expect(atlas.regions[0].trimmed).toBe(false);
+    expect(atlas.regions[0].originalWidth).toBeNull();
+  });
+  it('sets rotated on rotated regions', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    expect(atlas.regions[2].rotated).toBe(true);
+    expect(atlas.regions[0].rotated).toBe(false);
+  });
+  it('appends index to name when index >= 0', () => {
+    const indexedAtlas = `
+atlas.png
+size: 256,256
+format: RGBA8888
+filter: Nearest,Nearest
+repeat: none
+hero_walk
+  rotate: false
+  xy: 0, 0
+  size: 64, 64
+  orig: 64, 64
+  offset: 0, 0
+  index: 1
+`;
+    const atlas = createTextureAtlas();
+    parseTextureAtlasLibgdxAtlas(indexedAtlas, atlas);
+    expect(atlas.regions[0].name).toBe('hero_walk_1');
+  });
+  it('clears existing regions before parsing', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    expect(atlas.regions).toHaveLength(3);
+  });
+  it('returns the atlas for chaining', () => {
+    const atlas = createTextureAtlas();
+    const result = parseTextureAtlasLibgdxAtlas(SIMPLE_ATLAS, atlas);
+    expect(result).toBe(atlas);
+  });
+});

package/src/textureAtlasPackerParse.test.ts

@@ -0,0 +1,206 @@
+import { createTextureAtlas } from '@flighthq/textureatlas';
+
+import { parseTextureAtlasPackerDocument, parseTextureAtlasPackerJson } from './textureAtlasPackerParse';
+import type { TextureAtlasPackerArrayDocument, TextureAtlasPackerHashDocument } from './textureAtlasPackerSchema';
+
+// Minimal TexturePacker JSON-Hash fixture
+const HASH_FIXTURE: TextureAtlasPackerHashDocument = {
+  frames: {
+    'hero_idle_0.png': {
+      frame: { x: 0, y: 0, w: 64, h: 64 },
+      pivot: { x: 0.5, y: 0.5 },
+      rotated: false,
+      sourceSize: { w: 64, h: 64 },
+      spriteSourceSize: { x: 0, y: 0, w: 64, h: 64 },
+      trimmed: false,
+    },
+    'hero_walk_0.png': {
+      frame: { x: 64, y: 0, w: 48, h: 56 },
+      pivot: { x: 0.5, y: 1.0 },
+      rotated: false,
+      sourceSize: { w: 64, h: 64 },
+      spriteSourceSize: { x: 8, y: 4, w: 48, h: 56 },
+      trimmed: true,
+    },
+  },
+  meta: {
+    app: 'https://www.codeandweb.com/texturepacker',
+    format: 'RGBA8888',
+    image: 'atlas.png',
+    scale: 1,
+    size: { w: 256, h: 256 },
+    version: '1.0',
+  },
+};
+
+// Minimal TexturePacker JSON-Array fixture
+const ARRAY_FIXTURE: TextureAtlasPackerArrayDocument = {
+  frames: [
+    {
+      filename: 'tile_0.png',
+      frame: { x: 0, y: 0, w: 32, h: 32 },
+      rotated: false,
+      sourceSize: { w: 32, h: 32 },
+      spriteSourceSize: { x: 0, y: 0, w: 32, h: 32 },
+      trimmed: false,
+    },
+    {
+      filename: 'tile_1.png',
+      frame: { x: 32, y: 0, w: 32, h: 32 },
+      rotated: true,
+      sourceSize: { w: 32, h: 32 },
+      spriteSourceSize: { x: 0, y: 0, w: 32, h: 32 },
+      trimmed: false,
+    },
+  ],
+  meta: {
+    app: 'https://www.codeandweb.com/texturepacker',
+    format: 'RGBA8888',
+    image: 'tiles.png',
+    scale: '1',
+    size: { w: 64, h: 32 },
+    version: '1.0',
+  },
+};
+
+describe('parseTextureAtlasPackerDocument', () => {
+  it('populates regions from a hash-format document', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(HASH_FIXTURE, atlas);
+    expect(atlas.regions).toHaveLength(2);
+  });
+  it('populates regions from an array-format document', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(ARRAY_FIXTURE, atlas);
+    expect(atlas.regions).toHaveLength(2);
+  });
+  it('sets region name from the frame key (hash format)', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(HASH_FIXTURE, atlas);
+    const names = atlas.regions.map((r) => r.name);
+    expect(names).toContain('hero_idle_0.png');
+    expect(names).toContain('hero_walk_0.png');
+  });
+  it('sets region name from filename field (array format)', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(ARRAY_FIXTURE, atlas);
+    expect(atlas.regions[0].name).toBe('tile_0.png');
+    expect(atlas.regions[1].name).toBe('tile_1.png');
+  });
+  it('assigns sequential ids starting at 0', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(ARRAY_FIXTURE, atlas);
+    expect(atlas.regions[0].id).toBe(0);
+    expect(atlas.regions[1].id).toBe(1);
+  });
+  it('populates x/y/width/height from the frame rect', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(ARRAY_FIXTURE, atlas);
+    expect(atlas.regions[0].x).toBe(0);
+    expect(atlas.regions[0].y).toBe(0);
+    expect(atlas.regions[0].width).toBe(32);
+    expect(atlas.regions[0].height).toBe(32);
+  });
+  it('sets trimmed fields when the frame is trimmed', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(HASH_FIXTURE, atlas);
+    const trimmed = atlas.regions.find((r) => r.name === 'hero_walk_0.png');
+    expect(trimmed).toBeDefined();
+    expect(trimmed!.trimmed).toBe(true);
+    expect(trimmed!.sourceX).toBe(8);
+    expect(trimmed!.sourceY).toBe(4);
+    expect(trimmed!.originalWidth).toBe(64);
+    expect(trimmed!.originalHeight).toBe(64);
+  });
+  it('sets null originalWidth/Height when the frame is not trimmed', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(HASH_FIXTURE, atlas);
+    const idle = atlas.regions.find((r) => r.name === 'hero_idle_0.png')!;
+    expect(idle.trimmed).toBe(false);
+    expect(idle.originalWidth).toBeNull();
+    expect(idle.originalHeight).toBeNull();
+  });
+  it('sets pivot when pivot is present', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(HASH_FIXTURE, atlas);
+    const idle = atlas.regions.find((r) => r.name === 'hero_idle_0.png')!;
+    expect(idle.pivotX).toBe(0.5);
+    expect(idle.pivotY).toBe(0.5);
+  });
+  it('sets null pivot when pivot is absent', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(ARRAY_FIXTURE, atlas);
+    expect(atlas.regions[0].pivotX).toBeNull();
+    expect(atlas.regions[0].pivotY).toBeNull();
+  });
+  it('sets rotated on rotated regions', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(ARRAY_FIXTURE, atlas);
+    expect(atlas.regions[0].rotated).toBe(false);
+    expect(atlas.regions[1].rotated).toBe(true);
+  });
+  it('swaps width/height for rotated regions', () => {
+    // Rotated 90°: packed w=32,h=32 with rotation → logical w=h, h=w (same here since square)
+    const rotatedDoc: TextureAtlasPackerArrayDocument = {
+      frames: [
+        {
+          filename: 'rotated.png',
+          frame: { x: 0, y: 0, w: 20, h: 40 },
+          rotated: true,
+          sourceSize: { w: 40, h: 20 },
+          spriteSourceSize: { x: 0, y: 0, w: 40, h: 20 },
+          trimmed: false,
+        },
+      ],
+      meta: { app: 'tp', format: 'RGBA8888', image: 'a.png', scale: 1, size: { w: 64, h: 64 }, version: '1.0' },
+    };
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(rotatedDoc, atlas);
+    // When rotated: logical width = packed h, logical height = packed w
+    expect(atlas.regions[0].width).toBe(40);
+    expect(atlas.regions[0].height).toBe(20);
+  });
+  it('clears existing regions before parsing', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerDocument(ARRAY_FIXTURE, atlas);
+    parseTextureAtlasPackerDocument(ARRAY_FIXTURE, atlas);
+    expect(atlas.regions).toHaveLength(2);
+  });
+  it('returns the atlas for chaining', () => {
+    const atlas = createTextureAtlas();
+    const result = parseTextureAtlasPackerDocument(HASH_FIXTURE, atlas);
+    expect(result).toBe(atlas);
+  });
+});
+
+describe('parseTextureAtlasPackerJson', () => {
+  it('parses a JSON string and populates atlas regions', () => {
+    const atlas = createTextureAtlas();
+    const json = JSON.stringify(ARRAY_FIXTURE);
+    parseTextureAtlasPackerJson(json, atlas);
+    expect(atlas.regions).toHaveLength(2);
+    expect(atlas.regions[0].name).toBe('tile_0.png');
+  });
+  it('accepts an optional stripPathPrefix option', () => {
+    const docWithPaths: TextureAtlasPackerHashDocument = {
+      frames: {
+        'sprites/hero.png': {
+          frame: { x: 0, y: 0, w: 32, h: 32 },
+          rotated: false,
+          sourceSize: { w: 32, h: 32 },
+          spriteSourceSize: { x: 0, y: 0, w: 32, h: 32 },
+          trimmed: false,
+        },
+      },
+      meta: { app: 'tp', format: 'RGBA8888', image: 'a.png', scale: 1, size: { w: 64, h: 64 }, version: '1.0' },
+    };
+    const atlas = createTextureAtlas();
+    parseTextureAtlasPackerJson(JSON.stringify(docWithPaths), atlas, { stripPathPrefix: true });
+    expect(atlas.regions[0].name).toBe('hero.png');
+  });
+  it('returns the atlas for chaining', () => {
+    const atlas = createTextureAtlas();
+    const result = parseTextureAtlasPackerJson(JSON.stringify(ARRAY_FIXTURE), atlas);
+    expect(result).toBe(atlas);
+  });
+});

package/src/textureAtlasStarlingParse.test.ts

@@ -0,0 +1,92 @@
+import { createTextureAtlas } from '@flighthq/textureatlas';
+
+import { parseTextureAtlasStarlingXml } from './textureAtlasStarlingParse';
+
+const SIMPLE_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<TextureAtlas imagePath="atlas.png">
+  <SubTexture name="hero_idle" x="0" y="0" width="64" height="64"/>
+  <SubTexture name="hero_walk" x="64" y="0" width="48" height="56"
+    frameX="-8" frameY="-4" frameWidth="64" frameHeight="64"/>
+  <SubTexture name="hero_jump" x="112" y="0" width="40" height="50" rotated="true"/>
+  <SubTexture name="coin" x="152" y="0" width="32" height="32" pivotX="16" pivotY="16"/>
+</TextureAtlas>`;
+
+describe('parseTextureAtlasStarlingXml', () => {
+  it('populates regions from a Starling XML string', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    expect(atlas.regions).toHaveLength(4);
+  });
+  it('assigns sequential ids starting at 0', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    expect(atlas.regions[0].id).toBe(0);
+    expect(atlas.regions[3].id).toBe(3);
+  });
+  it('sets region name from the SubTexture name attribute', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    expect(atlas.regions[0].name).toBe('hero_idle');
+    expect(atlas.regions[1].name).toBe('hero_walk');
+  });
+  it('sets x/y/width/height from SubTexture attributes', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    expect(atlas.regions[0].x).toBe(0);
+    expect(atlas.regions[0].y).toBe(0);
+    expect(atlas.regions[0].width).toBe(64);
+    expect(atlas.regions[0].height).toBe(64);
+  });
+  it('sets trimmed fields when frameX/frameWidth are present', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    const walk = atlas.regions[1];
+    expect(walk.trimmed).toBe(true);
+    expect(walk.originalWidth).toBe(64);
+    expect(walk.originalHeight).toBe(64);
+    expect(walk.sourceX).toBe(8); // -frameX = 8
+    expect(walk.sourceY).toBe(4); // -frameY = 4
+  });
+  it('marks non-trimmed regions correctly', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    expect(atlas.regions[0].trimmed).toBe(false);
+    expect(atlas.regions[0].originalWidth).toBeNull();
+    expect(atlas.regions[0].originalHeight).toBeNull();
+  });
+  it('sets rotated on regions with rotated="true"', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    expect(atlas.regions[2].rotated).toBe(true);
+    expect(atlas.regions[0].rotated).toBe(false);
+  });
+  it('sets pivot when pivotX/pivotY attributes are present', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    const coin = atlas.regions[3];
+    expect(coin.pivotX).toBe(16);
+    expect(coin.pivotY).toBe(16);
+  });
+  it('sets null pivot when pivot attributes are absent', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    expect(atlas.regions[0].pivotX).toBeNull();
+    expect(atlas.regions[0].pivotY).toBeNull();
+  });
+  it('clears existing regions before parsing', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    expect(atlas.regions).toHaveLength(4);
+  });
+  it('returns the atlas for chaining', () => {
+    const atlas = createTextureAtlas();
+    const result = parseTextureAtlasStarlingXml(SIMPLE_XML, atlas);
+    expect(result).toBe(atlas);
+  });
+  it('returns the atlas unchanged when no SubTexture elements exist', () => {
+    const atlas = createTextureAtlas();
+    parseTextureAtlasStarlingXml('<TextureAtlas imagePath="a.png"></TextureAtlas>', atlas);
+    expect(atlas.regions).toHaveLength(0);
+  });
+});