@flighthq/particles-formats 0.1.0

package/src/spineParse.test.ts

@@ -0,0 +1,289 @@
+import {
+  createParticleEmitterConfig,
+  particleColorCurveFromKeyframes,
+  particleCurveFromKeyframes,
+  sampleParticleColorCurve,
+  sampleParticleCurve,
+} from '@flighthq/particles';
+
+import { parseSpineParticle, parseSpineParticleDocument } from './spineParse';
+import { serializeSpineParticle } from './spineSerialize';
+
+const SPARK_JSON = JSON.stringify({
+  name: 'spark',
+  maxParticles: 300,
+  continuous: true,
+  duration: -1,
+  emission: { low: 80, high: 120 },
+  life: { low: 400, high: 800 },
+  lifeOffset: { low: 0, high: 0 },
+  x: { low: 0, high: 0 },
+  y: { low: 0, high: 0 },
+  spawnShape: 'point',
+  spawnWidth: { low: 0, high: 0 },
+  spawnHeight: { low: 0, high: 0 },
+  velocity: { low: 50, high: 200 },
+  angle: { low: 60, high: 120 },
+  rotation: { low: 0, high: 360 },
+  wind: { low: 0, high: 0 },
+  gravity: { low: 200, high: 200 },
+  scale: { low: 0.5, high: 1.5 },
+  scaleEnd: { low: 0, high: 0 },
+  tint: [
+    { time: 0, color: 'ffaa00' },
+    { time: 1, color: 'ff0000' },
+  ],
+  alpha: [
+    { time: 0, alpha: 1 },
+    { time: 1, alpha: 0 },
+  ],
+  blendMode: 'additive',
+  premultiplied: false,
+  images: ['spark.png'],
+});
+
+describe('parseSpineParticle', () => {
+  describe('blend mode', () => {
+    it('maps additive blendMode to "add"', () => {
+      expect(parseSpineParticle(SPARK_JSON).blendMode).toBe('add');
+    });
+
+    it('maps normal blendMode to "normal"', () => {
+      const json = JSON.stringify({ ...JSON.parse(SPARK_JSON), blendMode: 'normal' });
+      expect(parseSpineParticle(json).blendMode).toBe('normal');
+    });
+
+    it('round-trips blendMode through serialize', () => {
+      const config = parseSpineParticle(SPARK_JSON);
+      const { document } = parseSpineParticleDocument(SPARK_JSON);
+      const config2 = parseSpineParticle(serializeSpineParticle(config, document));
+      expect(config2.blendMode).toBe('add');
+    });
+  });
+
+  describe('lightweight, returns config directly', () => {
+    it('returns a ParticleEmitterConfig (not a Parsed object)', () => {
+      const result = parseSpineParticle(SPARK_JSON);
+      expect(typeof result.maxParticles).toBe('number');
+      expect((result as unknown as Record<string, unknown>).document).toBeUndefined();
+    });
+
+    it('parses maxParticles', () => {
+      expect(parseSpineParticle(SPARK_JSON).maxParticles).toBe(300);
+    });
+
+    it('converts life range from ms to seconds', () => {
+      const c = parseSpineParticle(SPARK_JSON);
+      expect(c.lifetimeMin).toBeCloseTo(0.4);
+      expect(c.lifetimeMax).toBeCloseTo(0.8);
+    });
+
+    it('converts emission to spawnRate', () => {
+      expect(parseSpineParticle(SPARK_JSON).spawnRate).toBeCloseTo(100);
+    });
+
+    it('maps velocity to speedMin/Max', () => {
+      const c = parseSpineParticle(SPARK_JSON);
+      expect(c.speedMin).toBeCloseTo(50);
+      expect(c.speedMax).toBeCloseTo(200);
+    });
+
+    it('derives direction from angle midpoint and spread from range', () => {
+      const c = parseSpineParticle(SPARK_JSON);
+      expect(c.directionX).toBeCloseTo(0, 2);
+      expect(c.directionY).toBeCloseTo(-1, 2);
+      expect(c.spread).toBeCloseTo((30 * Math.PI) / 180, 3);
+    });
+
+    it('maps gravity', () => {
+      expect(parseSpineParticle(SPARK_JSON).gravityY).toBeCloseTo(200);
+    });
+
+    it('maps tint keyframes to colorStart/End', () => {
+      const c = parseSpineParticle(SPARK_JSON);
+      expect(c.colorStartR).toBeCloseTo(1);
+      expect(c.colorStartG).toBeCloseTo(0xaa / 255, 2);
+      expect(c.colorEndR).toBeCloseTo(1);
+      expect(c.colorEndG).toBeCloseTo(0);
+    });
+
+    it('maps alpha keyframes', () => {
+      const c = parseSpineParticle(SPARK_JSON);
+      expect(c.alphaStart).toBeCloseTo(1);
+      expect(c.alphaEnd).toBeCloseTo(0);
+    });
+
+    it('maps rotation range to rotationSpeedMin/Max', () => {
+      const c = parseSpineParticle(SPARK_JSON);
+      expect(c.rotationSpeedMin).toBeCloseTo(0);
+      expect(c.rotationSpeedMax).toBeCloseTo((360 * Math.PI) / 180, 3);
+    });
+
+    it('maps continuous=true to a looping emitter (emit forever)', () => {
+      const c = parseSpineParticle(SPARK_JSON);
+      expect(c.loop).toBe(true);
+      expect(c.duration).toBe(0);
+    });
+
+    it('maps continuous=false with a duration to a finite, non-looping emitter', () => {
+      const json = JSON.stringify({ ...JSON.parse(SPARK_JSON), continuous: false, duration: 2000 });
+      const c = parseSpineParticle(json);
+      expect(c.loop).toBe(false);
+      expect(c.duration).toBeCloseTo(2); // 2000 ms → 2 s
+    });
+  });
+
+  describe('malformed input', () => {
+    it('throws a clear, format-tagged error on invalid JSON', () => {
+      expect(() => parseSpineParticle('{not valid')).toThrow(/Invalid Spine particle JSON/);
+    });
+
+    it('throws a clear error when the root is not an object', () => {
+      expect(() => parseSpineParticle('null')).toThrow(/expected a JSON object/);
+      expect(() => parseSpineParticle('"a string"')).toThrow(/expected a JSON object/);
+      expect(() => parseSpineParticle('[1,2,3]')).toThrow(/expected a JSON object/);
+    });
+
+    it('falls back to safe channel values for an unparseable tint color (no NaN)', () => {
+      const c = parseSpineParticle(JSON.stringify({ tint: [{ time: 0, color: 'zzzzzz' }] }));
+      expect(Number.isFinite(c.colorStartR)).toBe(true);
+      expect(Number.isFinite(c.colorStartG)).toBe(true);
+      expect(Number.isFinite(c.colorStartB)).toBe(true);
+    });
+
+    it('falls back to defaults for an empty object rather than producing NaN', () => {
+      const c = parseSpineParticle('{}');
+      expect(Number.isFinite(c.lifetimeMin)).toBe(true);
+      expect(Number.isFinite(c.spawnRate)).toBe(true);
+      expect(Number.isFinite(c.colorStartR)).toBe(true);
+    });
+  });
+
+  describe('multi-stop timelines bake into curves', () => {
+    it('leaves curves null for a 2-stop tint/alpha (linear path)', () => {
+      const c = parseSpineParticle(SPARK_JSON); // tint/alpha each have 2 keyframes
+      expect(c.colorCurve).toBeNull();
+      expect(c.alphaCurve).toBeNull();
+    });
+
+    it('bakes a 3-stop tint timeline into colorCurve preserving the middle stop', () => {
+      const json = JSON.stringify({
+        ...JSON.parse(SPARK_JSON),
+        tint: [
+          { time: 0, color: 'ff0000' }, // red
+          { time: 0.5, color: '00ff00' }, // green
+          { time: 1, color: '0000ff' }, // blue
+        ],
+      });
+      const c = parseSpineParticle(json);
+      expect(c.colorCurve).not.toBeNull();
+      const out = [0, 0, 0];
+      sampleParticleColorCurve(out, 0, c.colorCurve!, 0.5);
+      expect(out[1]).toBeGreaterThan(0.8); // green dominant at mid-life
+      expect(out[0]).toBeLessThan(0.2);
+    });
+
+    it('bakes a 3-stop alpha timeline into alphaCurve', () => {
+      const json = JSON.stringify({
+        ...JSON.parse(SPARK_JSON),
+        alpha: [
+          { time: 0, alpha: 0 },
+          { time: 0.5, alpha: 1 }, // peak mid-life
+          { time: 1, alpha: 0 },
+        ],
+      });
+      const c = parseSpineParticle(json);
+      expect(c.alphaCurve).not.toBeNull();
+      expect(sampleParticleCurve(c.alphaCurve!, 0.5)).toBeGreaterThan(0.9);
+      expect(sampleParticleCurve(c.alphaCurve!, 0)).toBeLessThan(0.1);
+    });
+  });
+});
+
+describe('parseSpineParticleDocument', () => {
+  describe('full round-trip, returns { config, document }', () => {
+    it('returns the same config values as parseSpineParticle', () => {
+      const config = parseSpineParticle(SPARK_JSON);
+      const { config: loaded } = parseSpineParticleDocument(SPARK_JSON);
+      expect(loaded.maxParticles).toBe(config.maxParticles);
+      expect(loaded.gravityY).toBeCloseTo(config.gravityY, 5);
+    });
+
+    it('preserves name, blendMode, and images in document', () => {
+      const { document } = parseSpineParticleDocument(SPARK_JSON);
+      expect(document.name).toBe('spark');
+      expect(document.blendMode).toBe('additive');
+      expect(document.images[0]).toBe('spark.png');
+    });
+  });
+
+  describe('import warnings', () => {
+    it('has no warnings for a 2-keyframe tint/alpha effect', () => {
+      expect(parseSpineParticleDocument(SPARK_JSON).warnings).toEqual([]);
+    });
+
+    it('does NOT warn for multi-keyframe tint timelines (they are baked into curves)', () => {
+      const json = JSON.stringify({
+        ...JSON.parse(SPARK_JSON),
+        tint: [
+          { time: 0, color: 'ff0000' },
+          { time: 0.5, color: '00ff00' },
+          { time: 1, color: '0000ff' },
+        ],
+      });
+      const { warnings } = parseSpineParticleDocument(json);
+      expect(warnings.some((w) => w.includes('Tint'))).toBe(false);
+    });
+
+    it('warns about unsupported lifeOffset', () => {
+      const json = JSON.stringify({ ...JSON.parse(SPARK_JSON), lifeOffset: { low: 100, high: 200 } });
+      expect(parseSpineParticleDocument(json).warnings.some((w) => w.includes('lifeOffset'))).toBe(true);
+    });
+  });
+});
+
+describe('serializeSpineParticle', () => {
+  it('round-trips key config fields', () => {
+    const config = parseSpineParticle(SPARK_JSON);
+    const { document } = parseSpineParticleDocument(SPARK_JSON);
+    const config2 = parseSpineParticle(serializeSpineParticle(config, document));
+    expect(config2.maxParticles).toBe(config.maxParticles);
+    expect(config2.lifetimeMin).toBeCloseTo(config.lifetimeMin, 3);
+    expect(config2.speedMax).toBeCloseTo(config.speedMax, 2);
+    expect(config2.gravityY).toBeCloseTo(config.gravityY, 2);
+  });
+
+  it('preserves blendMode in round-trip', () => {
+    const config = parseSpineParticle(SPARK_JSON);
+    const { document } = parseSpineParticleDocument(SPARK_JSON);
+    expect(parseSpineParticleDocument(serializeSpineParticle(config, document)).document.blendMode).toBe('additive');
+  });
+
+  it('produces valid JSON', () => {
+    expect(() => JSON.parse(serializeSpineParticle(parseSpineParticle(SPARK_JSON)))).not.toThrow();
+  });
+});
+
+describe('serializeSpineParticle — curve round-trip', () => {
+  it('emits a baked color/alpha curve as a multi-stop timeline that re-imports identically', () => {
+    const colorCurve = particleColorCurveFromKeyframes([
+      { time: 0, r: 1, g: 0, b: 0 },
+      { time: 0.5, r: 0, g: 1, b: 0 },
+      { time: 1, r: 0, g: 0, b: 1 },
+    ]);
+    const alphaCurve = particleCurveFromKeyframes([
+      { time: 0, value: 0 },
+      { time: 0.5, value: 1 },
+      { time: 1, value: 0 },
+    ]);
+    const config = createParticleEmitterConfig({ colorCurve, alphaCurve });
+    const c2 = parseSpineParticle(serializeSpineParticle(config));
+    expect(c2.colorCurve).not.toBeNull();
+    expect(c2.alphaCurve).not.toBeNull();
+    const out = [0, 0, 0];
+    sampleParticleColorCurve(out, 0, c2.colorCurve!, 0.5);
+    expect(out[1]).toBeGreaterThan(0.8); // green still peaks mid-life
+    expect(sampleParticleCurve(c2.alphaCurve!, 0.5)).toBeGreaterThan(0.9);
+    expect(sampleParticleCurve(c2.alphaCurve!, 0)).toBeLessThan(0.1);
+  });
+});

package/src/spineSerialize.test.ts

@@ -0,0 +1,81 @@
+import { createParticleEmitterConfig } from '@flighthq/particles';
+
+import { parseSpineParticle, parseSpineParticleDocument } from './spineParse';
+import { serializeSpineParticle, serializeSpineParticleDocument } from './spineSerialize';
+
+const SPARK_JSON = JSON.stringify({
+  name: 'spark',
+  maxParticles: 300,
+  continuous: true,
+  duration: -1,
+  emission: { low: 80, high: 120 },
+  life: { low: 400, high: 800 },
+  lifeOffset: { low: 0, high: 0 },
+  x: { low: 0, high: 0 },
+  y: { low: 0, high: 0 },
+  spawnShape: 'point',
+  spawnWidth: { low: 0, high: 0 },
+  spawnHeight: { low: 0, high: 0 },
+  velocity: { low: 50, high: 200 },
+  angle: { low: 60, high: 120 },
+  rotation: { low: 0, high: 0 },
+  wind: { low: 0, high: 0 },
+  gravity: { low: 0, high: 0 },
+  scale: { low: 0.5, high: 1.5 },
+  scaleEnd: { low: 0, high: 0 },
+  tint: [
+    { time: 0, color: 'ffffff' },
+    { time: 1, color: 'ff0000' },
+  ],
+  alpha: [
+    { time: 0, alpha: 1 },
+    { time: 1, alpha: 0 },
+  ],
+  blendMode: 'normal',
+  premultiplied: false,
+  images: ['spark.png'],
+});
+
+describe('serializeSpineParticle', () => {
+  it('produces valid JSON', () => {
+    const config = parseSpineParticle(SPARK_JSON);
+    expect(() => JSON.parse(serializeSpineParticle(config))).not.toThrow();
+  });
+
+  it('round-trips key config fields through parse → serialize → parse', () => {
+    const config = parseSpineParticle(SPARK_JSON);
+    const { document } = parseSpineParticleDocument(SPARK_JSON);
+    const json2 = serializeSpineParticle(config, document);
+    const config2 = parseSpineParticle(json2);
+    expect(config2.maxParticles).toBe(config.maxParticles);
+    expect(config2.lifetimeMin).toBeCloseTo(config.lifetimeMin, 3);
+    expect(config2.lifetimeMax).toBeCloseTo(config.lifetimeMax, 3);
+  });
+
+  it('preserves name from existing document', () => {
+    const config = parseSpineParticle(SPARK_JSON);
+    const { document } = parseSpineParticleDocument(SPARK_JSON);
+    const json2 = JSON.parse(serializeSpineParticle(config, document)) as Record<string, unknown>;
+    expect(json2.name).toBe('spark');
+  });
+});
+
+describe('serializeSpineParticleDocument', () => {
+  it('returns text and empty warnings for a default config', () => {
+    const config = createParticleEmitterConfig();
+    const result = serializeSpineParticleDocument(config);
+    expect(typeof result.text).toBe('string');
+    expect(JSON.parse(result.text)).toBeDefined();
+    expect(result.warnings).toEqual([]);
+  });
+  it('warns when config has emission bursts', () => {
+    const config = createParticleEmitterConfig({ burstCount: 5 });
+    const result = serializeSpineParticleDocument(config);
+    expect(result.warnings.some((w) => w.toLowerCase().includes('burst'))).toBe(true);
+  });
+  it('warns when config has color start variance', () => {
+    const config = createParticleEmitterConfig({ colorStartVarianceR: 0.1 });
+    const result = serializeSpineParticleDocument(config);
+    expect(result.warnings.some((w) => w.includes('colorStartVariance'))).toBe(true);
+  });
+});

package/src/starlingPexParse.test.ts

@@ -0,0 +1,154 @@
+import { parseStarlingPex, parseStarlingPexDocument } from './starlingPexParse';
+
+// Attribute-style PEX (the canonical Sparrow/Starling variant)
+const FIRE_PEX_ATTR = `<?xml version="1.0" encoding="utf-8"?>
+<particleEmitterConfig>
+  <attribute name="maxParticles" value="200"/>
+  <attribute name="emitterType" value="0"/>
+  <attribute name="duration" value="-1"/>
+  <attribute name="particleLifespan" value="1.5"/>
+  <attribute name="particleLifespanVariance" value="0.5"/>
+  <attribute name="speed" value="100"/>
+  <attribute name="speedVariance" value="20"/>
+  <attribute name="angle" value="90"/>
+  <attribute name="angleVariance" value="30"/>
+  <attribute name="gravityx" value="0"/>
+  <attribute name="gravityy" value="200"/>
+  <attribute name="sourcePositionVariancex" value="0"/>
+  <attribute name="sourcePositionVariancey" value="0"/>
+  <attribute name="startParticleSize" value="32"/>
+  <attribute name="startParticleSizeVariance" value="8"/>
+  <attribute name="finishParticleSize" value="8"/>
+  <attribute name="finishParticleSizeVariance" value="0"/>
+  <attribute name="startColor" red="1" green="0.5" blue="0" alpha="1"/>
+  <attribute name="startColorVariance" red="0" green="0" blue="0" alpha="0"/>
+  <attribute name="finishColor" red="1" green="0" blue="0" alpha="0"/>
+  <attribute name="finishColorVariance" red="0" green="0" blue="0" alpha="0"/>
+  <attribute name="rotationStart" value="0"/>
+  <attribute name="rotationStartVariance" value="0"/>
+  <attribute name="rotationEnd" value="0"/>
+  <attribute name="rotationEndVariance" value="0"/>
+  <attribute name="maxRadius" value="0"/>
+  <attribute name="maxRadiusVariance" value="0"/>
+  <attribute name="minRadius" value="0"/>
+  <attribute name="minRadiusVariance" value="0"/>
+  <attribute name="rotatePerSecond" value="0"/>
+  <attribute name="rotatePerSecondVariance" value="0"/>
+  <attribute name="radialAcceleration" value="0"/>
+  <attribute name="radialAccelVariance" value="0"/>
+  <attribute name="tangentialAcceleration" value="0"/>
+  <attribute name="tangentialAccelVariance" value="0"/>
+  <attribute name="blendFuncSource" value="770"/>
+  <attribute name="blendFuncDestination" value="771"/>
+  <attribute name="textureFileName" value="fire.png"/>
+</particleEmitterConfig>`;
+
+describe('parseStarlingPex', () => {
+  it('returns a ParticleEmitterConfig (not a ParseResult object)', () => {
+    const result = parseStarlingPex(FIRE_PEX_ATTR) as unknown as Record<string, unknown>;
+    expect(typeof result.maxParticles).toBe('number');
+    expect(result.document).toBeUndefined();
+  });
+  it('parses maxParticles from attribute-style PEX', () => {
+    expect(parseStarlingPex(FIRE_PEX_ATTR).maxParticles).toBe(200);
+  });
+  it('converts lifetime with variance to min/max', () => {
+    const c = parseStarlingPex(FIRE_PEX_ATTR);
+    expect(c.lifetimeMin).toBeCloseTo(1.0);
+    expect(c.lifetimeMax).toBeCloseTo(2.0);
+  });
+  it('converts speed with variance to min/max', () => {
+    const c = parseStarlingPex(FIRE_PEX_ATTR);
+    expect(c.speedMin).toBeCloseTo(80);
+    expect(c.speedMax).toBeCloseTo(120);
+  });
+  it('maps angle=90 to upward direction (-Y screen)', () => {
+    const c = parseStarlingPex(FIRE_PEX_ATTR);
+    expect(c.directionX).toBeCloseTo(0, 3);
+    expect(c.directionY).toBeCloseTo(-1, 3);
+  });
+  it('converts angleVariance to spread in radians', () => {
+    expect(parseStarlingPex(FIRE_PEX_ATTR).spread).toBeCloseTo((30 * Math.PI) / 180, 4);
+  });
+  it('maps gravity directly', () => {
+    const c = parseStarlingPex(FIRE_PEX_ATTR);
+    expect(c.gravityX).toBeCloseTo(0);
+    expect(c.gravityY).toBeCloseTo(200);
+  });
+  it('maps startColor/finishColor to colorStart/End', () => {
+    const c = parseStarlingPex(FIRE_PEX_ATTR);
+    expect(c.colorStartR).toBeCloseTo(1);
+    expect(c.colorStartG).toBeCloseTo(0.5);
+    expect(c.colorStartB).toBeCloseTo(0);
+    expect(c.colorEndR).toBeCloseTo(1);
+    expect(c.colorEndG).toBeCloseTo(0);
+    expect(c.colorEndB).toBeCloseTo(0);
+  });
+  it('maps startColor.alpha / finishColor.alpha to alphaStart/End', () => {
+    const c = parseStarlingPex(FIRE_PEX_ATTR);
+    expect(c.alphaStart).toBeCloseTo(1);
+    expect(c.alphaEnd).toBeCloseTo(0);
+  });
+  it('normalises scale by textureSize', () => {
+    const c = parseStarlingPex(FIRE_PEX_ATTR, { textureSize: 32 });
+    expect(c.scaleMin).toBeCloseTo(0.75);
+    expect(c.scaleMax).toBeCloseTo(1.25);
+  });
+  it('maps normal blend func (770, 771) to blendMode="normal"', () => {
+    expect(parseStarlingPex(FIRE_PEX_ATTR).blendMode).toBe('normal');
+  });
+  it('maps additive blend func (770, 1) to blendMode="add"', () => {
+    const pex = FIRE_PEX_ATTR.replace('blendFuncDestination" value="771"', 'blendFuncDestination" value="1"');
+    expect(parseStarlingPex(pex).blendMode).toBe('add');
+  });
+  it('maps duration=-1 to an infinite (looping) emitter', () => {
+    const c = parseStarlingPex(FIRE_PEX_ATTR);
+    expect(c.loop).toBe(true);
+    expect(c.duration).toBe(0);
+  });
+  it('uses point emitter shape when sourcePositionVariance is zero', () => {
+    expect(parseStarlingPex(FIRE_PEX_ATTR).emitterShape).toBe('point');
+  });
+  it('maps circle emitter shape when x=y variance', () => {
+    const pex = FIRE_PEX_ATTR.replace(
+      'sourcePositionVariancex" value="0"',
+      'sourcePositionVariancex" value="20"',
+    ).replace('sourcePositionVariancey" value="0"', 'sourcePositionVariancey" value="20"');
+    const c = parseStarlingPex(pex);
+    expect(c.emitterShape).toBe('circle');
+    expect(c.emitterRadius).toBeCloseTo(20);
+  });
+  it('throws a clear error for non-XML input', () => {
+    expect(() => parseStarlingPex('not xml')).toThrow(/Invalid Starling PEX/);
+    expect(() => parseStarlingPex('{}')).toThrow(/Invalid Starling PEX/);
+  });
+});
+
+describe('parseStarlingPexDocument', () => {
+  it('returns the same config values as parseStarlingPex', () => {
+    const config = parseStarlingPex(FIRE_PEX_ATTR, { textureSize: 32 });
+    const { config: loaded } = parseStarlingPexDocument(FIRE_PEX_ATTR, { textureSize: 32 });
+    expect(loaded.maxParticles).toBe(config.maxParticles);
+    expect(loaded.directionY).toBeCloseTo(config.directionY, 5);
+    expect(loaded.gravityY).toBeCloseTo(config.gravityY, 5);
+  });
+  it('preserves textureFileName in document', () => {
+    expect(parseStarlingPexDocument(FIRE_PEX_ATTR).document.textureFileName).toBe('fire.png');
+  });
+  it('preserves blend function in document', () => {
+    const { document } = parseStarlingPexDocument(FIRE_PEX_ATTR);
+    expect(document.blendFuncSource).toBe(770);
+    expect(document.blendFuncDestination).toBe(771);
+  });
+  it('has no warnings for a standard gravity emitter', () => {
+    expect(parseStarlingPexDocument(FIRE_PEX_ATTR).warnings).toEqual([]);
+  });
+  it('warns that a radial emitter is approximated', () => {
+    const pex = FIRE_PEX_ATTR.replace('emitterType" value="0"', 'emitterType" value="1"');
+    expect(parseStarlingPexDocument(pex).warnings.some((w) => w.toLowerCase().includes('radial'))).toBe(true);
+  });
+  it('warns about unsupported radial/tangential acceleration', () => {
+    const pex = FIRE_PEX_ATTR.replace('radialAcceleration" value="0"', 'radialAcceleration" value="50"');
+    expect(parseStarlingPexDocument(pex).warnings.some((w) => w.includes('radialAcceleration'))).toBe(true);
+  });
+});

package/src/starlingPexSerialize.test.ts

@@ -0,0 +1,115 @@
+import { createParticleEmitterConfig } from '@flighthq/particles';
+
+import { parseStarlingPex, parseStarlingPexDocument } from './starlingPexParse';
+import { serializeStarlingPex, serializeStarlingPexDocument } from './starlingPexSerialize';
+
+// Attribute-style PEX (the canonical Sparrow/Starling variant)
+const FIRE_PEX_ATTR = `<?xml version="1.0" encoding="utf-8"?>
+<particleEmitterConfig>
+  <attribute name="maxParticles" value="200"/>
+  <attribute name="emitterType" value="0"/>
+  <attribute name="duration" value="-1"/>
+  <attribute name="particleLifespan" value="1.5"/>
+  <attribute name="particleLifespanVariance" value="0.5"/>
+  <attribute name="speed" value="100"/>
+  <attribute name="speedVariance" value="20"/>
+  <attribute name="angle" value="90"/>
+  <attribute name="angleVariance" value="30"/>
+  <attribute name="gravityx" value="0"/>
+  <attribute name="gravityy" value="200"/>
+  <attribute name="sourcePositionVariancex" value="0"/>
+  <attribute name="sourcePositionVariancey" value="0"/>
+  <attribute name="startParticleSize" value="32"/>
+  <attribute name="startParticleSizeVariance" value="8"/>
+  <attribute name="finishParticleSize" value="8"/>
+  <attribute name="finishParticleSizeVariance" value="0"/>
+  <attribute name="startColor" red="1" green="0.5" blue="0" alpha="1"/>
+  <attribute name="startColorVariance" red="0" green="0" blue="0" alpha="0"/>
+  <attribute name="finishColor" red="1" green="0" blue="0" alpha="0"/>
+  <attribute name="finishColorVariance" red="0" green="0" blue="0" alpha="0"/>
+  <attribute name="rotationStart" value="0"/>
+  <attribute name="rotationStartVariance" value="0"/>
+  <attribute name="rotationEnd" value="0"/>
+  <attribute name="rotationEndVariance" value="0"/>
+  <attribute name="maxRadius" value="0"/>
+  <attribute name="maxRadiusVariance" value="0"/>
+  <attribute name="minRadius" value="0"/>
+  <attribute name="minRadiusVariance" value="0"/>
+  <attribute name="rotatePerSecond" value="0"/>
+  <attribute name="rotatePerSecondVariance" value="0"/>
+  <attribute name="radialAcceleration" value="0"/>
+  <attribute name="radialAccelVariance" value="0"/>
+  <attribute name="tangentialAcceleration" value="0"/>
+  <attribute name="tangentialAccelVariance" value="0"/>
+  <attribute name="blendFuncSource" value="770"/>
+  <attribute name="blendFuncDestination" value="771"/>
+  <attribute name="textureFileName" value="fire.png"/>
+</particleEmitterConfig>`;
+
+describe('serializeStarlingPex', () => {
+  it('round-trips key config fields', () => {
+    const config = parseStarlingPex(FIRE_PEX_ATTR, { textureSize: 32 });
+    const { document } = parseStarlingPexDocument(FIRE_PEX_ATTR, { textureSize: 32 });
+    const xml = serializeStarlingPex(config, document, { textureSize: 32 });
+    const config2 = parseStarlingPex(xml, { textureSize: 32 });
+    expect(config2.maxParticles).toBe(config.maxParticles);
+    expect(config2.directionX).toBeCloseTo(config.directionX, 3);
+    expect(config2.gravityY).toBeCloseTo(config.gravityY, 1);
+    expect(config2.colorStartR).toBeCloseTo(config.colorStartR, 3);
+    expect(config2.alphaEnd).toBeCloseTo(config.alphaEnd, 3);
+  });
+  it('preserves textureFileName in round-trip', () => {
+    const config = parseStarlingPex(FIRE_PEX_ATTR);
+    const { document } = parseStarlingPexDocument(FIRE_PEX_ATTR);
+    expect(serializeStarlingPex(config, document)).toContain('fire.png');
+  });
+  it('produces valid XML with particleEmitterConfig root', () => {
+    const config = parseStarlingPex(FIRE_PEX_ATTR);
+    const xml = serializeStarlingPex(config);
+    expect(xml).toContain('<?xml version="1.0"');
+    expect(xml).toContain('<particleEmitterConfig>');
+    expect(xml).toContain('</particleEmitterConfig>');
+  });
+  it('produces XML parseable by parseStarlingPex for a fresh config', () => {
+    const config = createParticleEmitterConfig({ maxParticles: 50, blendMode: 'add' });
+    const xml = serializeStarlingPex(config);
+    const c2 = parseStarlingPex(xml);
+    expect(c2.maxParticles).toBe(50);
+    expect(c2.blendMode).toBe('add');
+  });
+  it('maps blendMode="normal" to blendFuncDestination 771', () => {
+    const config = createParticleEmitterConfig({ blendMode: 'normal' });
+    const xml = serializeStarlingPex(config);
+    expect(xml).toContain('blendFuncDestination" value="771"');
+  });
+  it('maps blendMode="add" to blendFuncDestination 1', () => {
+    const config = createParticleEmitterConfig({ blendMode: 'add' });
+    const xml = serializeStarlingPex(config);
+    expect(xml).toContain('blendFuncDestination" value="1"');
+  });
+});
+
+describe('serializeStarlingPexDocument', () => {
+  it('returns text and empty warnings for a default config', () => {
+    const config = createParticleEmitterConfig();
+    const result = serializeStarlingPexDocument(config);
+    expect(typeof result.text).toBe('string');
+    expect(result.text).toContain('<particleEmitterConfig>');
+    expect(result.warnings).toEqual([]);
+  });
+  it('warns when multiply/screen blend mode cannot be represented', () => {
+    const config = createParticleEmitterConfig({ blendMode: 'multiply' });
+    const result = serializeStarlingPexDocument(config);
+    expect(result.warnings.some((w) => w.toLowerCase().includes('multiply'))).toBe(true);
+  });
+  it('warns when config has emission bursts', () => {
+    const config = createParticleEmitterConfig({ burstCount: 5 });
+    const result = serializeStarlingPexDocument(config);
+    expect(result.warnings.some((w) => w.toLowerCase().includes('burst'))).toBe(true);
+  });
+  it('has no warnings for add blend mode (supported)', () => {
+    const config = createParticleEmitterConfig({ blendMode: 'add' });
+    const result = serializeStarlingPexDocument(config);
+    expect(result.warnings.filter((w) => w.toLowerCase().includes('blend'))).toEqual([]);
+  });
+});