@flighthq/particles-formats 0.1.0

package/dist/unitySchema.d.ts

@@ -0,0 +1,109 @@
+export type UnityParticleShapeType = 'Sphere' | 'Hemisphere' | 'Cone' | 'Box' | 'Circle' | 'Edge' | 'Rectangle' | 'Donut';
+export interface UnityColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** A two-value range used for min/max curves with constant mode. */
+export interface UnityMinMaxValue {
+    mode: 'constant' | 'twoConstants' | 'curve' | 'twoCurves';
+    constant?: number;
+    constantMin?: number;
+    constantMax?: number;
+}
+export interface UnityBurst {
+    time: number;
+    count: number;
+    cycleCount: number;
+    repeatInterval: number;
+}
+export interface UnityEmission {
+    rateOverTime: UnityMinMaxValue;
+    bursts: UnityBurst[];
+}
+export interface UnityShape {
+    enabled: boolean;
+    shapeType: UnityParticleShapeType;
+    /** Sphere / Hemisphere / Circle / Donut outer radius */
+    radius: number;
+    /** Cone angle (degrees) */
+    angle: number;
+    /** Box / Rectangle dimensions */
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** A Unity gradient key (RGB stop at a normalised lifetime position). */
+export interface UnityGradientColorKey {
+    time: number;
+    color: {
+        r: number;
+        g: number;
+        b: number;
+    };
+}
+/** A Unity gradient alpha key. */
+export interface UnityGradientAlphaKey {
+    time: number;
+    alpha: number;
+}
+/** Multi-stop gradient (full MinMaxGradient fidelity). */
+export interface UnityGradient {
+    colorKeys: UnityGradientColorKey[];
+    alphaKeys: UnityGradientAlphaKey[];
+}
+/** A Unity AnimationCurve key. */
+export interface UnityCurveKey {
+    time: number;
+    value: number;
+}
+/** Multi-key AnimationCurve. */
+export interface UnityAnimationCurve {
+    keys: UnityCurveKey[];
+}
+export interface UnityColorOverLifetime {
+    enabled: boolean;
+    /** Color at start and end of lifetime */
+    colorStart: UnityColor;
+    colorEnd: UnityColor;
+    /** Full multi-stop gradient; when present it carries the complete color/alpha
+     *  timeline that colorStart/colorEnd only approximate. */
+    gradient?: UnityGradient;
+}
+export interface UnitySizeOverLifetime {
+    enabled: boolean;
+    /** Size multiplier at start and end of lifetime */
+    sizeStart: number;
+    sizeEnd: number;
+    /** Full AnimationCurve; when present it carries the complete size-over-lifetime shape. */
+    curve?: UnityAnimationCurve;
+}
+export interface UnityRotationOverLifetime {
+    enabled: boolean;
+    /** Angular velocity in degrees/sec */
+    angularVelocity: UnityMinMaxValue;
+}
+/** Full Unity Shuriken particle system JSON document. */
+export interface UnityParticleDocument {
+    name: string;
+    duration: number;
+    looping: boolean;
+    prewarm: boolean;
+    maxParticles: number;
+    startLifetime: UnityMinMaxValue;
+    startSpeed: UnityMinMaxValue;
+    startSize: UnityMinMaxValue;
+    startRotation: UnityMinMaxValue;
+    startColor: UnityColor;
+    gravityModifier: number;
+    physicsGravity: number;
+    emission: UnityEmission;
+    shape: UnityShape;
+    colorOverLifetime: UnityColorOverLifetime;
+    sizeOverLifetime: UnitySizeOverLifetime;
+    rotationOverLifetime: UnityRotationOverLifetime;
+}
+//# sourceMappingURL=unitySchema.d.ts.map

package/dist/unitySchema.d.ts.map

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

package/dist/unitySchema.js

@@ -0,0 +1,9 @@
+// Unity Shuriken particle system JSON schema.
+// Based on the Unity Particle System component's serialized field names as exported
+// by Unity's JsonUtility and common third-party particle-system exporters.
+// Targets Unity 2021 LTS and later.
+//
+// Curves (MinMaxCurve) are simplified to constant or two-keyframe linear values.
+// Gradients (MinMaxGradient) are simplified to start/end color stops.
+export {};
+//# sourceMappingURL=unitySchema.js.map

package/dist/unitySchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unitySchema.js","sourceRoot":"","sources":["../src/unitySchema.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,oFAAoF;AACpF,2EAA2E;AAC3E,oCAAoC;AACpC,EAAE;AACF,iFAAiF;AACjF,sEAAsE"}

package/dist/unitySerialize.d.ts

@@ -0,0 +1,20 @@
+import type { ParticleEmitterConfig } from '@flighthq/types';
+import type { ParticleSerializeResult } from './serializeResult';
+import type { UnityParticleDocument } from './unitySchema';
+export interface UnitySerializeOptions {
+    /** Pixels-per-unit — reverses the conversion applied during parsing.  Defaults to 100. */
+    pixelsPerUnit?: number;
+}
+/** Serialise a ParticleEmitterConfig to a Unity Shuriken particle system JSON string.
+ *
+ *  Pass the `document` returned by `parseUnityParticle` to preserve fields that
+ *  don't round-trip through the config (name, duration, looping, prewarm, etc.). */
+export declare function serializeUnityParticle(config: Readonly<ParticleEmitterConfig>, existing?: Partial<UnityParticleDocument>, options?: UnitySerializeOptions): string;
+/** Serialise a ParticleEmitterConfig to a Unity Shuriken particle system JSON
+ *  string, returning both the serialized text and any warnings for features the
+ *  format cannot represent.
+ *
+ *  Pass the `document` returned by `parseUnityParticleDocument` to preserve
+ *  fields that don't round-trip through the config. */
+export declare function serializeUnityParticleDocument(config: Readonly<ParticleEmitterConfig>, existing?: Partial<UnityParticleDocument>, options?: UnitySerializeOptions): ParticleSerializeResult;
+//# sourceMappingURL=unitySerialize.d.ts.map

package/dist/unitySerialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unitySerialize.d.ts","sourceRoot":"","sources":["../src/unitySerialize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAKV,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA2HD;;;oFAGoF;AACpF,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,EACvC,QAAQ,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,EACzC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,CAIR;AAED;;;;;uDAKuD;AACvD,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,EACvC,QAAQ,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,EACzC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,uBAAuB,CAIzB"}

package/dist/unitySerialize.js

@@ -0,0 +1,148 @@
+import { particleColorCurveToKeyframes, particleCurveToKeyframes } from '@flighthq/particles';
+const RAD2DEG = 180 / Math.PI;
+const DEFAULT_PPU = 100;
+function color(r, g, b, a) {
+    return { r, g, b, a };
+}
+function constant(v) {
+    return { mode: 'constant', constant: v };
+}
+function twoConst(low, high) {
+    if (low === high)
+        return constant(low);
+    return { mode: 'twoConstants', constantMin: low, constantMax: high };
+}
+function configToDocument(config, existing, ppu) {
+    const rotSpeedDegLow = config.rotationSpeedMin * RAD2DEG;
+    const rotSpeedDegHigh = config.rotationSpeedMax * RAD2DEG;
+    const hasRotation = config.rotationSpeedMin !== 0 || config.rotationSpeedMax !== 0;
+    const hasBurst = config.burstCount > 0;
+    // Gravity: pixel/s² → Unity world units / s²
+    const gravWorldUnit = config.gravityY / ppu;
+    const physicsGravity = existing.physicsGravity ?? 9.81;
+    const gravModifier = physicsGravity !== 0 ? gravWorldUnit / physicsGravity : 0;
+    // Shape
+    let shapeType = 'Cone';
+    let radius = 0;
+    let angle = config.spread * RAD2DEG;
+    const scaleXY = 1;
+    if (config.emitterShape === 'circle') {
+        shapeType = 'Circle';
+        radius = config.emitterRadius / ppu;
+        angle = 0;
+    }
+    else if (config.emitterShape === 'rect') {
+        shapeType = 'Box';
+    }
+    return {
+        name: existing.name ?? '',
+        duration: config.duration > 0 ? config.duration : (existing.duration ?? 5),
+        looping: config.loop,
+        prewarm: existing.prewarm ?? false,
+        maxParticles: config.maxParticles,
+        startLifetime: twoConst(config.lifetimeMin, config.lifetimeMax),
+        startSpeed: twoConst(config.speedMin / ppu, config.speedMax / ppu),
+        startSize: twoConst(config.scaleMin, config.scaleMax),
+        startRotation: constant(0),
+        startColor: color(config.colorStartR, config.colorStartG, config.colorStartB, config.alphaStart),
+        gravityModifier: gravModifier,
+        physicsGravity,
+        emission: {
+            rateOverTime: constant(config.spawnRate),
+            bursts: hasBurst
+                ? [
+                    {
+                        time: 0,
+                        count: config.burstCount,
+                        cycleCount: config.burstInterval > 0 ? 0 : 1,
+                        repeatInterval: config.burstInterval,
+                    },
+                ]
+                : [],
+        },
+        shape: {
+            enabled: config.emitterShape !== 'point',
+            shapeType,
+            radius,
+            angle,
+            scale: {
+                x: config.emitterShape === 'rect' ? config.emitterWidth / ppu : scaleXY,
+                y: config.emitterShape === 'rect' ? config.emitterHeight / ppu : scaleXY,
+                z: 1,
+            },
+        },
+        colorOverLifetime: {
+            enabled: true,
+            colorStart: color(config.colorStartR, config.colorStartG, config.colorStartB, config.alphaStart),
+            colorEnd: color(config.colorEndR, config.colorEndG, config.colorEndB, config.alphaEnd),
+            // Emit a full gradient when the config carries baked color/alpha curves so
+            // the complete timeline round-trips back out (not just the endpoints).
+            ...(config.colorCurve || config.alphaCurve ? { gradient: buildGradient(config) } : {}),
+        },
+        sizeOverLifetime: {
+            enabled: config.scaleEnd !== 1 || config.scaleCurve != null,
+            sizeStart: 1,
+            sizeEnd: config.scaleEnd,
+            ...(config.scaleCurve ? { curve: buildSizeCurve(config.scaleCurve) } : {}),
+        },
+        rotationOverLifetime: {
+            enabled: hasRotation,
+            angularVelocity: hasRotation ? twoConst(rotSpeedDegLow, rotSpeedDegHigh) : constant(0),
+        },
+    };
+}
+function buildGradient(config) {
+    const colorKeys = config.colorCurve
+        ? particleColorCurveToKeyframes(config.colorCurve).map((k) => ({ time: k.time, color: { r: k.r, g: k.g, b: k.b } }))
+        : [
+            { time: 0, color: { r: config.colorStartR, g: config.colorStartG, b: config.colorStartB } },
+            { time: 1, color: { r: config.colorEndR, g: config.colorEndG, b: config.colorEndB } },
+        ];
+    const alphaKeys = config.alphaCurve
+        ? particleCurveToKeyframes(config.alphaCurve).map((k) => ({ time: k.time, alpha: k.value }))
+        : [
+            { time: 0, alpha: config.alphaStart },
+            { time: 1, alpha: config.alphaEnd },
+        ];
+    return { colorKeys, alphaKeys };
+}
+function buildSizeCurve(scaleCurve) {
+    return { keys: particleCurveToKeyframes(scaleCurve).map((k) => ({ time: k.time, value: k.value })) };
+}
+/** Serialise a ParticleEmitterConfig to a Unity Shuriken particle system JSON string.
+ *
+ *  Pass the `document` returned by `parseUnityParticle` to preserve fields that
+ *  don't round-trip through the config (name, duration, looping, prewarm, etc.). */
+export function serializeUnityParticle(config, existing, options) {
+    const ppu = options?.pixelsPerUnit ?? DEFAULT_PPU;
+    const doc = configToDocument(config, existing ?? {}, ppu);
+    return JSON.stringify(doc, null, 2);
+}
+/** Serialise a ParticleEmitterConfig to a Unity Shuriken particle system JSON
+ *  string, returning both the serialized text and any warnings for features the
+ *  format cannot represent.
+ *
+ *  Pass the `document` returned by `parseUnityParticleDocument` to preserve
+ *  fields that don't round-trip through the config. */
+export function serializeUnityParticleDocument(config, existing, options) {
+    const text = serializeUnityParticle(config, existing, options);
+    const warnings = collectUnitySerializeWarnings(config);
+    return { text, warnings };
+}
+function collectUnitySerializeWarnings(config) {
+    const warnings = [];
+    if (config.colorEndVarianceR !== 0 || config.colorEndVarianceG !== 0 || config.colorEndVarianceB !== 0) {
+        warnings.push('colorEndVariance is not supported by the Unity format and was ignored');
+    }
+    if (config.colorStartVarianceR !== 0 || config.colorStartVarianceG !== 0 || config.colorStartVarianceB !== 0) {
+        warnings.push('colorStartVariance is not supported by the Unity format and was ignored');
+    }
+    if (config.velocityInheritance !== 0) {
+        warnings.push('velocityInheritance is not supported by the Unity format and was ignored');
+    }
+    if (config.gravityX !== 0) {
+        warnings.push('gravityX (horizontal gravity) is not supported by the Unity format and was ignored');
+    }
+    return warnings;
+}
+//# sourceMappingURL=unitySerialize.js.map

package/dist/unitySerialize.js.map

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

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/particles-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/particles": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Import/export particle emitter configs from industry-standard formats (Particle Designer, Spine, Unity)",
+  "sideEffects": false
+}

package/src/detect.test.ts

@@ -0,0 +1,99 @@
+import {
+  LibgdxParticleFormatKind,
+  ParticleDesignerFormatKind,
+  PixiParticleFormatKind,
+  SpineParticleFormatKind,
+  StarlingPexFormatKind,
+  UnityParticleFormatKind,
+} from '@flighthq/types';
+
+import { detectParticleFormat } from './detect';
+
+const PLIST_SNIPPET = `<?xml version="1.0" encoding="utf-8"?>
+<plist version="1.0">
+<dict>
+  <key>maxParticles</key><integer>200</integer>
+</dict>
+</plist>`;
+const SPINE_JSON = JSON.stringify({
+  name: 'spark',
+  continuous: true,
+  emission: { low: 10, high: 30 },
+  life: { low: 500, high: 1500 },
+});
+const UNITY_JSON = JSON.stringify({
+  name: 'smoke',
+  looping: true,
+  startLifetime: { mode: 'twoConstants', constantMin: 1.0, constantMax: 2.5 },
+  gravityModifier: 0.1,
+});
+const LIBGDX_SNIPPET = `Particle Effect
+- Spark -
+maxParticleCount: 50
+additive: true
+`;
+const STARLING_PEX_SNIPPET = `<?xml version="1.0" encoding="utf-8"?>
+<particleEmitterConfig>
+  <attribute name="maxParticles" value="200"/>
+</particleEmitterConfig>`;
+const PIXI_JSON = JSON.stringify({
+  pos: { x: 0, y: 0 },
+  alpha: { start: 1, end: 0 },
+  speed: { start: 100, end: 50 },
+  lifetime: { min: 0.5, max: 1.5 },
+  maxParticles: 500,
+});
+
+describe('detectParticleFormat', () => {
+  it('detects libGDX .p by "Particle Effect" first line', () => {
+    expect(detectParticleFormat(LIBGDX_SNIPPET)).toBe(LibgdxParticleFormatKind);
+  });
+  it('detects libGDX .p with leading whitespace before Particle Effect', () => {
+    expect(detectParticleFormat('  \nParticle Effect\n- Emitter -\n')).toBe(LibgdxParticleFormatKind);
+  });
+  it('detects Particle Designer plist by <plist tag', () => {
+    expect(detectParticleFormat(PLIST_SNIPPET)).toBe(ParticleDesignerFormatKind);
+  });
+  it('detects Particle Designer plist with leading whitespace', () => {
+    expect(detectParticleFormat('  \n' + PLIST_SNIPPET)).toBe(ParticleDesignerFormatKind);
+  });
+  it('detects Pixi particle JSON by pos + alpha.start/end fields', () => {
+    expect(detectParticleFormat(PIXI_JSON)).toBe(PixiParticleFormatKind);
+  });
+  it('detects Spine JSON by continuous boolean', () => {
+    expect(detectParticleFormat(SPINE_JSON)).toBe(SpineParticleFormatKind);
+  });
+  it('detects Spine JSON by emission range object', () => {
+    const json = JSON.stringify({ emission: { low: 10, high: 30 }, life: { low: 500, high: 1500 } });
+    expect(detectParticleFormat(json)).toBe(SpineParticleFormatKind);
+  });
+  it('detects Starling PEX by <particleEmitterConfig root element', () => {
+    expect(detectParticleFormat(STARLING_PEX_SNIPPET)).toBe(StarlingPexFormatKind);
+  });
+  it('detects Unity JSON by startLifetime mode field', () => {
+    expect(detectParticleFormat(UNITY_JSON)).toBe(UnityParticleFormatKind);
+  });
+  it('detects Unity JSON by gravityModifier', () => {
+    const json = JSON.stringify({ gravityModifier: 0.5 });
+    expect(detectParticleFormat(json)).toBe(UnityParticleFormatKind);
+  });
+  it('detects Unity JSON by looping + startLifetime', () => {
+    const json = JSON.stringify({ looping: true, startLifetime: { mode: 'constant', constant: 1 } });
+    expect(detectParticleFormat(json)).toBe(UnityParticleFormatKind);
+  });
+  it('returns null for garbage input', () => {
+    expect(detectParticleFormat('not a particle file at all')).toBeNull();
+  });
+  it('returns null for empty string', () => {
+    expect(detectParticleFormat('')).toBeNull();
+  });
+  it('returns null for valid JSON that matches no format', () => {
+    expect(detectParticleFormat(JSON.stringify({ foo: 'bar', baz: 42 }))).toBeNull();
+  });
+  it('returns null for a JSON array', () => {
+    expect(detectParticleFormat(JSON.stringify([1, 2, 3]))).toBeNull();
+  });
+  it('returns null for XML that is not a plist or PEX', () => {
+    expect(detectParticleFormat('<svg width="100"><circle/></svg>')).toBeNull();
+  });
+});

package/src/formatRegistry.test.ts

@@ -0,0 +1,118 @@
+import { createParticleEmitterConfig } from '@flighthq/particles';
+
+import type { ParticleFormatCodec } from './formatRegistry';
+import {
+  detectRegisteredParticleFormat,
+  getParticleFormatCodec,
+  getRegisteredParticleFormats,
+  parseRegisteredParticleFormat,
+  registerParticleFormat,
+  unregisterParticleFormat,
+} from './formatRegistry';
+
+// A minimal test codec for use across all tests
+const TEST_KIND = 'test.MyFormat';
+const testCodec: ParticleFormatCodec = {
+  detect: (text) => text.startsWith('MY_FORMAT:'),
+  parseToConfig: (text) => createParticleEmitterConfig({ maxParticles: parseInt(text.slice(10), 10) || 50 }),
+  parseToDocument: (text) => ({
+    config: createParticleEmitterConfig({ maxParticles: parseInt(text.slice(10), 10) || 50 }),
+    warnings: [],
+  }),
+  serialize: () => ({ text: 'MY_FORMAT:50', warnings: [] }),
+};
+
+describe('detectRegisteredParticleFormat', () => {
+  it('returns the kind when a codec detects the input', () => {
+    registerParticleFormat(TEST_KIND, testCodec);
+    expect(detectRegisteredParticleFormat('MY_FORMAT:100')).toBe(TEST_KIND);
+    unregisterParticleFormat(TEST_KIND);
+  });
+  it('returns null when no codec matches', () => {
+    expect(detectRegisteredParticleFormat('totally unknown')).toBeNull();
+  });
+  it('ignores codecs that throw in detect()', () => {
+    const throwingCodec: ParticleFormatCodec = {
+      ...testCodec,
+      detect: () => {
+        throw new Error('boom');
+      },
+    };
+    registerParticleFormat(TEST_KIND, throwingCodec);
+    expect(() => detectRegisteredParticleFormat('anything')).not.toThrow();
+    unregisterParticleFormat(TEST_KIND);
+  });
+});
+
+describe('getParticleFormatCodec', () => {
+  it('returns null when no codec is registered for the kind', () => {
+    expect(getParticleFormatCodec('nope.Missing')).toBeNull();
+  });
+  it('returns the registered codec', () => {
+    registerParticleFormat(TEST_KIND, testCodec);
+    expect(getParticleFormatCodec(TEST_KIND)).toBe(testCodec);
+    unregisterParticleFormat(TEST_KIND);
+  });
+});
+
+describe('getRegisteredParticleFormats', () => {
+  it('returns an array including newly registered kinds', () => {
+    registerParticleFormat(TEST_KIND, testCodec);
+    expect(getRegisteredParticleFormats()).toContain(TEST_KIND);
+    unregisterParticleFormat(TEST_KIND);
+  });
+  it('does not include unregistered kinds', () => {
+    registerParticleFormat(TEST_KIND, testCodec);
+    unregisterParticleFormat(TEST_KIND);
+    expect(getRegisteredParticleFormats()).not.toContain(TEST_KIND);
+  });
+});
+
+describe('parseRegisteredParticleFormat', () => {
+  it('parses using the registered codec and returns config and format', () => {
+    registerParticleFormat(TEST_KIND, testCodec);
+    const result = parseRegisteredParticleFormat('MY_FORMAT:75', TEST_KIND);
+    expect(result.format).toBe(TEST_KIND);
+    expect(result.config.maxParticles).toBe(75);
+    expect(result.warnings).toEqual([]);
+    unregisterParticleFormat(TEST_KIND);
+  });
+  it('returns a default config with unknown-format warning when no codec is registered', () => {
+    const result = parseRegisteredParticleFormat('whatever', 'nope.Missing');
+    expect(result.config).toBeDefined();
+    expect(result.warnings.some((w) => w.includes('unknown-format'))).toBe(true);
+  });
+  it('catches codec parse errors and returns them as parse-error warnings', () => {
+    const errCodec: ParticleFormatCodec = {
+      ...testCodec,
+      parseToDocument: () => {
+        throw new Error('bad input');
+      },
+    };
+    registerParticleFormat(TEST_KIND, errCodec);
+    const result = parseRegisteredParticleFormat('MY_FORMAT:bad', TEST_KIND);
+    expect(result.warnings.some((w) => w.includes('parse-error'))).toBe(true);
+    unregisterParticleFormat(TEST_KIND);
+  });
+});
+
+describe('registerParticleFormat', () => {
+  it('is last-write-wins: second registration replaces the first', () => {
+    const codec1: ParticleFormatCodec = { ...testCodec, detect: () => true };
+    const codec2: ParticleFormatCodec = { ...testCodec, detect: () => false };
+    registerParticleFormat(TEST_KIND, codec1);
+    registerParticleFormat(TEST_KIND, codec2);
+    expect(getParticleFormatCodec(TEST_KIND)).toBe(codec2);
+    unregisterParticleFormat(TEST_KIND);
+  });
+});
+
+describe('unregisterParticleFormat', () => {
+  it('returns true when a codec is found and removed', () => {
+    registerParticleFormat(TEST_KIND, testCodec);
+    expect(unregisterParticleFormat(TEST_KIND)).toBe(true);
+  });
+  it('returns false when no codec was registered for the kind', () => {
+    expect(unregisterParticleFormat('nope.NotRegistered')).toBe(false);
+  });
+});