@flighthq/spritesheet-formats 0.1.0

package/src/libgdxAtlasParse.test.ts

@@ -0,0 +1,100 @@
+import { parseLibgdxAtlasSpritesheet } from './libgdxAtlasParse';
+
+const MINIMAL_ATLAS = `
+atlas.png
+  size: 128, 64
+  format: RGBA8888
+  filter: Linear, Linear
+  repeat: none
+hero
+  rotate: false
+  xy: 0, 0
+  size: 64, 64
+  orig: 64, 64
+  offset: 0, 0
+  index: -1
+coin
+  rotate: false
+  xy: 64, 0
+  size: 32, 32
+  orig: 32, 32
+  offset: 0, 0
+  index: -1
+`;
+
+// Animations are inferred from the `baseName_NNN` frame-naming convention.
+const ANIMATED_ATLAS = `
+run.png
+  size: 256, 64
+  format: RGBA8888
+  filter: Nearest, Nearest
+  repeat: none
+run_0
+  rotate: false
+  xy: 0, 0
+  size: 64, 64
+  orig: 64, 64
+  offset: 0, 0
+  index: -1
+run_1
+  rotate: false
+  xy: 64, 0
+  size: 64, 64
+  orig: 64, 64
+  offset: 0, 0
+  index: -1
+run_2
+  rotate: false
+  xy: 128, 0
+  size: 64, 64
+  orig: 64, 64
+  offset: 0, 0
+  index: -1
+`;
+
+describe('parseLibgdxAtlasSpritesheet', () => {
+  it('parses frame names', () => {
+    const data = parseLibgdxAtlasSpritesheet(MINIMAL_ATLAS);
+    expect(data.frames).toHaveLength(2);
+    expect(data.frames[0]?.name).toBe('hero');
+    expect(data.frames[1]?.name).toBe('coin');
+  });
+
+  it('parses frame positions and dimensions', () => {
+    const data = parseLibgdxAtlasSpritesheet(MINIMAL_ATLAS);
+    expect(data.frames[0]?.x).toBe(0);
+    expect(data.frames[0]?.y).toBe(0);
+    expect(data.frames[0]?.width).toBe(64);
+    expect(data.frames[0]?.height).toBe(64);
+    expect(data.frames[1]?.x).toBe(64);
+    expect(data.frames[1]?.y).toBe(0);
+    expect(data.frames[1]?.width).toBe(32);
+    expect(data.frames[1]?.height).toBe(32);
+  });
+
+  it('parses page image file and dimensions', () => {
+    const data = parseLibgdxAtlasSpritesheet(MINIMAL_ATLAS);
+    expect(data.imageFile).toBe('atlas.png');
+    expect(data.imageWidth).toBe(128);
+    expect(data.imageHeight).toBe(64);
+  });
+
+  it('infers animations from baseName_NNN frame names', () => {
+    const data = parseLibgdxAtlasSpritesheet(ANIMATED_ATLAS);
+    expect(data.frames).toHaveLength(3);
+    expect(data.frames[0]?.name).toBe('run_0');
+    expect(data.animations).toHaveLength(1);
+    expect(data.animations[0]?.name).toBe('run');
+    expect(data.animations[0]?.frameNames).toEqual(['run_0', 'run_1', 'run_2']);
+  });
+
+  it('respects custom frameDuration option', () => {
+    const data = parseLibgdxAtlasSpritesheet(ANIMATED_ATLAS, { frameDuration: 200 });
+    expect(data.animations[0]?.frameDuration).toBe(200);
+  });
+
+  it('sets non-indexed frames without rotation', () => {
+    const data = parseLibgdxAtlasSpritesheet(MINIMAL_ATLAS);
+    expect(data.frames[0]?.rotated).toBe(false);
+  });
+});

package/src/spritesheetDetect.test.ts

@@ -0,0 +1,217 @@
+import {
+  SpritesheetFormatKindAseprite,
+  SpritesheetFormatKindCocosPlist,
+  SpritesheetFormatKindLibgdxAtlas,
+  SpritesheetFormatKindStarling,
+  SpritesheetFormatKindTexturePacker,
+} from '@flighthq/types';
+
+import type { SpritesheetParseOptions } from './spritesheetDetect';
+import {
+  detectSpritesheetFormat,
+  getSpritesheetFormat,
+  parseSpritesheet,
+  registerSpritesheetFormat,
+} from './spritesheetDetect';
+
+const TEXTURE_PACKER_JSON = JSON.stringify({
+  frames: {},
+  meta: {
+    app: 'https://www.codeandweb.com/texturepacker',
+    format: 'RGBA8888',
+    image: 'atlas.png',
+    scale: 1,
+    size: { h: 128, w: 128 },
+    version: '1.0',
+  },
+});
+
+const ASEPRITE_JSON = JSON.stringify({
+  frames: {},
+  meta: {
+    app: 'https://www.aseprite.org/',
+    format: 'RGBA8888',
+    frameTags: [],
+    image: 'sprite.png',
+    scale: '1',
+    size: { h: 64, w: 64 },
+    version: '1.3',
+  },
+});
+
+const STARLING_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<TextureAtlas imagePath="atlas.png">
+  <SubTexture name="hero" x="0" y="0" width="64" height="64"/>
+</TextureAtlas>`;
+
+const LIBGDX_ATLAS = `
+atlas.png
+size: 128, 64
+format: RGBA8888
+filter: Linear, Linear
+repeat: none
+hero
+  rotate: false
+  xy: 0, 0
+  size: 64, 64
+  orig: 64, 64
+  offset: 0, 0
+  index: -1
+`;
+
+const COCOS_PLIST = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>frames</key>
+  <dict>
+    <key>hero.png</key>
+    <dict>
+      <key>textureRect</key>
+      <string>{{0,0},{64,64}}</string>
+    </dict>
+  </dict>
+  <key>metadata</key>
+  <dict>
+    <key>textureFileName</key>
+    <string>atlas.png</string>
+  </dict>
+</dict>
+</plist>`;
+
+describe('detectSpritesheetFormat', () => {
+  it('detects TexturePacker JSON', () => {
+    expect(detectSpritesheetFormat(TEXTURE_PACKER_JSON)).toBe(SpritesheetFormatKindTexturePacker);
+  });
+
+  it('detects Aseprite JSON', () => {
+    expect(detectSpritesheetFormat(ASEPRITE_JSON)).toBe(SpritesheetFormatKindAseprite);
+  });
+
+  it('detects Starling XML', () => {
+    expect(detectSpritesheetFormat(STARLING_XML)).toBe(SpritesheetFormatKindStarling);
+  });
+
+  it('detects Cocos plist XML', () => {
+    expect(detectSpritesheetFormat(COCOS_PLIST)).toBe(SpritesheetFormatKindCocosPlist);
+  });
+
+  it('detects libGDX atlas', () => {
+    expect(detectSpritesheetFormat(LIBGDX_ATLAS)).toBe(SpritesheetFormatKindLibgdxAtlas);
+  });
+
+  it('returns null for unknown format', () => {
+    expect(detectSpritesheetFormat('completely unknown content')).toBeNull();
+  });
+});
+
+describe('getSpritesheetFormat', () => {
+  it('returns the registered entry for a known kind', () => {
+    const entry = getSpritesheetFormat(SpritesheetFormatKindTexturePacker);
+    expect(entry).not.toBeNull();
+    expect(typeof entry?.detect).toBe('function');
+    expect(typeof entry?.parse).toBe('function');
+  });
+
+  it('returns null for an unknown kind', () => {
+    expect(getSpritesheetFormat('acme.NonExistent')).toBeNull();
+  });
+
+  it('reflects a format registered via registerSpritesheetFormat', () => {
+    const kind = 'test.GetFormatTest';
+    const detect = (text: string) => text.startsWith('GFT:');
+    registerSpritesheetFormat(kind, {
+      detect,
+      parse: () => ({ animations: [], frames: [], imageFile: '', imageHeight: 0, imageWidth: 0, scale: 1 }),
+    });
+    const entry = getSpritesheetFormat(kind);
+    expect(entry).not.toBeNull();
+    expect(entry?.detect).toBe(detect);
+  });
+});
+
+describe('parseSpritesheet', () => {
+  it('auto-detects and parses TexturePacker JSON', () => {
+    const data = parseSpritesheet(TEXTURE_PACKER_JSON);
+    expect(data).not.toBeNull();
+    expect(data?.imageFile).toBe('atlas.png');
+  });
+
+  it('auto-detects and parses Aseprite JSON', () => {
+    const data = parseSpritesheet(ASEPRITE_JSON);
+    expect(data).not.toBeNull();
+    expect(data?.imageFile).toBe('sprite.png');
+  });
+
+  it('auto-detects and parses Starling XML', () => {
+    const data = parseSpritesheet(STARLING_XML);
+    expect(data).not.toBeNull();
+    expect(data?.frames[0]?.name).toBe('hero');
+  });
+
+  it('returns null for unknown format', () => {
+    const data = parseSpritesheet('unknown format content here');
+    expect(data).toBeNull();
+  });
+
+  it('respects explicit formatKind override', () => {
+    const data = parseSpritesheet(TEXTURE_PACKER_JSON, SpritesheetFormatKindTexturePacker);
+    expect(data).not.toBeNull();
+  });
+
+  it('passes frameDuration option to parsers', () => {
+    const json = JSON.stringify({
+      frames: {},
+      meta: {
+        app: 'https://www.codeandweb.com/texturepacker',
+        format: 'RGBA8888',
+        frameTags: [{ direction: 'forward', from: 0, name: 'run', to: 0 }],
+        image: 'atlas.png',
+        scale: 1,
+        size: { h: 64, w: 64 },
+        version: '1.0',
+      },
+    });
+    const opts: SpritesheetParseOptions = { frameDuration: 250 };
+    const data = parseSpritesheet(json, SpritesheetFormatKindTexturePacker, opts);
+    // frameTags reference frame index 0 which doesn't exist → animation gets empty frameNames
+    // But the option is passed without throwing
+    expect(data).not.toBeNull();
+  });
+});
+
+describe('registerSpritesheetFormat', () => {
+  it('allows registering a custom format', () => {
+    const customKind = 'test.CustomFormat';
+    registerSpritesheetFormat(customKind, {
+      detect: (text) => text.startsWith('CUSTOM:'),
+      parse: () => ({
+        animations: [],
+        frames: [
+          {
+            height: 10,
+            name: 'custom',
+            offsetX: 0,
+            offsetY: 0,
+            pivotX: null,
+            pivotY: null,
+            rotated: false,
+            sourceHeight: 10,
+            sourceWidth: 10,
+            width: 10,
+            x: 0,
+            y: 0,
+          },
+        ],
+        imageFile: 'custom.png',
+        imageHeight: 10,
+        imageWidth: 10,
+        scale: 1,
+      }),
+    });
+
+    expect(detectSpritesheetFormat('CUSTOM: data here')).toBe(customKind);
+    const data = parseSpritesheet('CUSTOM: data here');
+    expect(data?.imageFile).toBe('custom.png');
+  });
+});

package/src/starlingParse.test.ts

@@ -0,0 +1,176 @@
+import { parseStarlingSpritesheet, parseStarlingSpritesheetDocument } from './starlingParse';
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const ATLAS_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<TextureAtlas imagePath="atlas.png">
+  <SubTexture name="hero_idle_0001" x="0" y="0" width="60" height="56"
+              frameX="-2" frameY="-4" frameWidth="64" frameHeight="64"
+              pivotX="32" pivotY="64"/>
+  <SubTexture name="hero_idle_0002" x="60" y="0" width="60" height="56"
+              frameX="-2" frameY="-4" frameWidth="64" frameHeight="64"
+              pivotX="32" pivotY="64"/>
+  <SubTexture name="hero_idle_0003" x="120" y="0" width="60" height="56"
+              frameX="-2" frameY="-4" frameWidth="64" frameHeight="64"
+              pivotX="32" pivotY="64"/>
+  <SubTexture name="fx_spark" x="0" y="56" width="16" height="16"/>
+</TextureAtlas>`;
+
+const ROTATED_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<TextureAtlas imagePath="sprites.png">
+  <SubTexture name="run_001" x="0" y="0" width="32" height="32" rotated="true"/>
+  <SubTexture name="run_002" x="32" y="0" width="32" height="32" rotated="true"/>
+</TextureAtlas>`;
+
+const MINIMAL_XML = `<TextureAtlas imagePath="mini.png">
+  <SubTexture name="tile" x="0" y="0" width="8" height="8"/>
+</TextureAtlas>`;
+
+describe('parseStarlingSpritesheet', () => {
+  it('returns a SpritesheetData (not a Parsed object)', () => {
+    const result = parseStarlingSpritesheet(ATLAS_XML);
+    expect(typeof result.frames).toBe('object');
+    expect((result as unknown as Record<string, unknown>).document).toBeUndefined();
+  });
+
+  it('parses all SubTexture elements', () => {
+    expect(parseStarlingSpritesheet(ATLAS_XML).frames).toHaveLength(4);
+  });
+
+  it('maps name, x, y, width, height', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    const frame = data.frames[0];
+    expect(frame.name).toBe('hero_idle_0001');
+    expect(frame.x).toBe(0);
+    expect(frame.y).toBe(0);
+    expect(frame.width).toBe(60);
+    expect(frame.height).toBe(56);
+  });
+
+  it('converts frameX/Y to positive offsetX/Y', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    const frame = data.frames[0];
+    expect(frame.offsetX).toBe(2); // -(-2) = 2
+    expect(frame.offsetY).toBe(4); // -(-4) = 4
+  });
+
+  it('maps frameWidth/Height as sourceWidth/Height', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    const frame = data.frames[0];
+    expect(frame.sourceWidth).toBe(64);
+    expect(frame.sourceHeight).toBe(64);
+  });
+
+  it('falls back to atlas width/height as sourceWidth/Height when no frame attrs', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    const spark = data.frames.find((f) => f.name === 'fx_spark')!;
+    expect(spark.sourceWidth).toBe(16);
+    expect(spark.sourceHeight).toBe(16);
+  });
+
+  it('normalises pivotX/Y to 0–1 range', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    const frame = data.frames[0]; // pivotX=32, sourceWidth=64 → 0.5
+    expect(frame.pivotX).toBeCloseTo(0.5);
+    expect(frame.pivotY).toBeCloseTo(1.0);
+  });
+
+  it('sets pivot to null when absent', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    const spark = data.frames.find((f) => f.name === 'fx_spark')!;
+    expect(spark.pivotX).toBeNull();
+    expect(spark.pivotY).toBeNull();
+  });
+
+  it('maps rotated flag', () => {
+    const data = parseStarlingSpritesheet(ROTATED_XML);
+    expect(data.frames[0].rotated).toBe(true);
+    expect(data.frames[1].rotated).toBe(true);
+  });
+
+  it('defaults rotated to false when absent', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    expect(data.frames[0].rotated).toBe(false);
+  });
+
+  it('extracts imagePath as imageFile', () => {
+    expect(parseStarlingSpritesheet(ATLAS_XML).imageFile).toBe('atlas.png');
+    expect(parseStarlingSpritesheet(MINIMAL_XML).imageFile).toBe('mini.png');
+  });
+
+  it('infers animations from numbered frame names', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    const anim = data.animations.find((a) => a.name === 'hero_idle');
+    expect(anim).toBeDefined();
+    expect(anim!.frameNames).toHaveLength(3);
+  });
+
+  it('sorts animation frames by numeric suffix', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    const anim = data.animations.find((a) => a.name === 'hero_idle')!;
+    expect(anim.frameNames[0]).toBe('hero_idle_0001');
+    expect(anim.frameNames[1]).toBe('hero_idle_0002');
+    expect(anim.frameNames[2]).toBe('hero_idle_0003');
+  });
+
+  it('does not create animation for singleton frames', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    expect(data.animations.find((a) => a.name === 'fx')).toBeUndefined();
+    expect(data.animations.find((a) => a.name === 'fx_spark')).toBeUndefined();
+  });
+
+  it('uses frameDuration option for inferred animations', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML, { frameDuration: 200 });
+    const anim = data.animations[0];
+    expect(anim.frameDuration).toBe(200);
+  });
+
+  it('defaults frameDuration to 100 when option is absent', () => {
+    const data = parseStarlingSpritesheet(ATLAS_XML);
+    expect(data.animations[0].frameDuration).toBe(100);
+  });
+
+  it('infers run animation from numbered frames', () => {
+    const data = parseStarlingSpritesheet(ROTATED_XML);
+    expect(data.animations).toHaveLength(1);
+    expect(data.animations[0].name).toBe('run');
+    expect(data.animations[0].frameNames).toHaveLength(2);
+  });
+
+  it('handles a single frame with no numbered pattern', () => {
+    const data = parseStarlingSpritesheet(MINIMAL_XML);
+    expect(data.frames).toHaveLength(1);
+    expect(data.animations).toHaveLength(0);
+  });
+});
+
+describe('parseStarlingSpritesheetDocument', () => {
+  it('returns the same data as parseStarlingSpritesheet', () => {
+    const parsed = parseStarlingSpritesheet(ATLAS_XML);
+    const { data } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    expect(data.frames.length).toBe(parsed.frames.length);
+    expect(data.imageFile).toBe(parsed.imageFile);
+  });
+
+  it('preserves all SubTexture nodes in document', () => {
+    const { document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    expect(document.subTextures).toHaveLength(4);
+  });
+
+  it('preserves imagePath in document', () => {
+    const { document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    expect(document.imagePath).toBe('atlas.png');
+  });
+
+  it('preserves numeric attributes exactly', () => {
+    const { document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    const st = document.subTextures[0];
+    expect(st.name).toBe('hero_idle_0001');
+    expect(st.x).toBe(0);
+    expect(st.width).toBe(60);
+    expect(st.frameX).toBe(-2);
+    expect(st.frameY).toBe(-4);
+    expect(st.frameWidth).toBe(64);
+    expect(st.frameHeight).toBe(64);
+  });
+});

package/src/starlingSerialize.test.ts

@@ -0,0 +1,117 @@
+import { parseStarlingSpritesheet, parseStarlingSpritesheetDocument } from './starlingParse';
+import { serializeStarlingSpritesheet } from './starlingSerialize';
+
+const XML = `<?xml version="1.0" encoding="UTF-8"?>
+<TextureAtlas imagePath="atlas.png">
+  <SubTexture name="hero" x="0" y="0" width="64" height="64"/>
+  <SubTexture name="coin" x="64" y="0" width="32" height="32"/>
+</TextureAtlas>`;
+
+const ATLAS_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<TextureAtlas imagePath="atlas.png">
+  <SubTexture name="hero_idle_0001" x="0" y="0" width="60" height="56"
+              frameX="-2" frameY="-4" frameWidth="64" frameHeight="64"
+              pivotX="32" pivotY="64"/>
+  <SubTexture name="hero_idle_0002" x="60" y="0" width="60" height="56"
+              frameX="-2" frameY="-4" frameWidth="64" frameHeight="64"
+              pivotX="32" pivotY="64"/>
+  <SubTexture name="hero_idle_0003" x="120" y="0" width="60" height="56"
+              frameX="-2" frameY="-4" frameWidth="64" frameHeight="64"
+              pivotX="32" pivotY="64"/>
+  <SubTexture name="fx_spark" x="0" y="56" width="16" height="16"/>
+</TextureAtlas>`;
+
+const ROTATED_XML = `<?xml version="1.0" encoding="UTF-8"?>
+<TextureAtlas imagePath="sprites.png">
+  <SubTexture name="run_001" x="0" y="0" width="32" height="32" rotated="true"/>
+  <SubTexture name="run_002" x="32" y="0" width="32" height="32" rotated="true"/>
+</TextureAtlas>`;
+
+const MINIMAL_XML = `<TextureAtlas imagePath="mini.png">
+  <SubTexture name="tile" x="0" y="0" width="8" height="8"/>
+</TextureAtlas>`;
+
+describe('serializeStarlingSpritesheet', () => {
+  it('produces a TextureAtlas XML string', () => {
+    const data = parseStarlingSpritesheet(XML);
+    const serialized = serializeStarlingSpritesheet(data);
+    expect(serialized).toContain('<TextureAtlas');
+    expect(serialized).toContain('imagePath="atlas.png"');
+  });
+
+  it('preserves frame count on round-trip', () => {
+    const data = parseStarlingSpritesheet(XML);
+    const serialized = serializeStarlingSpritesheet(data);
+    const reparsed = parseStarlingSpritesheet(serialized);
+    expect(reparsed.frames).toHaveLength(data.frames.length);
+  });
+
+  it('round-trips frame names', () => {
+    const { data, document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    const data2 = parseStarlingSpritesheet(serializeStarlingSpritesheet(data, document));
+    expect(data2.frames.map((f) => f.name)).toEqual(data.frames.map((f) => f.name));
+  });
+
+  it('round-trips atlas positions', () => {
+    const { data, document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    const data2 = parseStarlingSpritesheet(serializeStarlingSpritesheet(data, document));
+    expect(data2.frames[0].x).toBe(data.frames[0].x);
+    expect(data2.frames[0].width).toBe(data.frames[0].width);
+  });
+
+  it('round-trips trim offsets', () => {
+    const { data, document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    const data2 = parseStarlingSpritesheet(serializeStarlingSpritesheet(data, document));
+    expect(data2.frames[0].offsetX).toBe(data.frames[0].offsetX);
+    expect(data2.frames[0].offsetY).toBe(data.frames[0].offsetY);
+  });
+
+  it('round-trips source size', () => {
+    const { data, document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    const data2 = parseStarlingSpritesheet(serializeStarlingSpritesheet(data, document));
+    expect(data2.frames[0].sourceWidth).toBe(data.frames[0].sourceWidth);
+    expect(data2.frames[0].sourceHeight).toBe(data.frames[0].sourceHeight);
+  });
+
+  it('round-trips pivot normalised values', () => {
+    const { data, document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    const data2 = parseStarlingSpritesheet(serializeStarlingSpritesheet(data, document));
+    expect(data2.frames[0].pivotX).toBeCloseTo(data.frames[0].pivotX!);
+    expect(data2.frames[0].pivotY).toBeCloseTo(data.frames[0].pivotY!);
+  });
+
+  it('round-trips rotated flag', () => {
+    const { data, document } = parseStarlingSpritesheetDocument(ROTATED_XML);
+    const data2 = parseStarlingSpritesheet(serializeStarlingSpritesheet(data, document));
+    expect(data2.frames[0].rotated).toBe(true);
+  });
+
+  it('round-trips imagePath', () => {
+    const { data, document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    const data2 = parseStarlingSpritesheet(serializeStarlingSpritesheet(data, document));
+    expect(data2.imageFile).toBe('atlas.png');
+  });
+
+  it('produces well-formed XML with root element', () => {
+    const data = parseStarlingSpritesheet(MINIMAL_XML);
+    const xml = serializeStarlingSpritesheet(data);
+    expect(xml).toContain('<TextureAtlas');
+    expect(xml).toContain('<SubTexture');
+    expect(xml).toContain('</TextureAtlas>');
+  });
+
+  it('omits optional attributes when not needed', () => {
+    const data = parseStarlingSpritesheet(MINIMAL_XML);
+    const xml = serializeStarlingSpritesheet(data);
+    expect(xml).not.toContain('frameX');
+    expect(xml).not.toContain('pivotX');
+    expect(xml).not.toContain('rotated');
+  });
+
+  it('includes frameX/Y when offset is non-zero', () => {
+    const { data, document } = parseStarlingSpritesheetDocument(ATLAS_XML);
+    const xml = serializeStarlingSpritesheet(data, document);
+    expect(xml).toContain('frameX="-2"');
+    expect(xml).toContain('frameY="-4"');
+  });
+});