rn-gamekit 0.1.0 → 0.2.1

package/src/particles/createParticleSystem.ts

@@ -0,0 +1,505 @@
+import { ParticleError } from './errors';
+import { defineParticleEffect } from './defineParticleEffect';
+import { createRng, sampleInitialSlot, sampleSlotAtAge } from './sampling';
+import type {
+  ParticleDiagnostics,
+  ParticleEmissionRecord,
+  ParticleUiRegistry,
+  ParticleDriverHandle,
+  ParticleEffectDefinition,
+  ParticleEffectDefinitionInput,
+  ParticlePresentationBinding,
+  ParticleSlotSnapshot,
+  ParticleSystem,
+  ParticleSystemOptions,
+} from './types';
+import type { Point2D } from '../geometry/types';
+
+/** Adapter from the mutable pool slot to the pure sampler's input. */
+function ageView(slot: MutableSlot): {
+  readonly lifetime: number;
+  readonly origin: Point2D;
+  readonly velocity: Point2D;
+  readonly rotation: number;
+  readonly rotationSpeed: number;
+  readonly scaleStart: number;
+  readonly scaleEnd: number;
+} {
+  return {
+    lifetime: slot.lifetime,
+    origin: { x: slot.originX, y: slot.originY },
+    velocity: { x: slot.vx, y: slot.vy },
+    rotation: slot.rotation,
+    rotationSpeed: slot.rotationSpeed,
+    scaleStart: slot.scaleStart,
+    scaleEnd: slot.scaleEnd,
+  };
+}
+
+function assertCommand(cmd: unknown): asserts cmd is { position: Point2D; seed: number } {
+  if (cmd === null || typeof cmd !== 'object' || Array.isArray(cmd)) {
+    throw new ParticleError('emit command must be an object');
+  }
+  const c = cmd as Record<string, unknown>;
+  const pos = c.position;
+  if (pos === null || typeof pos !== 'object' || Array.isArray(pos)) {
+    throw new ParticleError('emit command position must be {x,y}');
+  }
+  const pp = pos as Record<string, unknown>;
+  if (typeof pp.x !== 'number' || !Number.isFinite(pp.x)) {
+    throw new ParticleError('emit command position.x must be a finite number');
+  }
+  if (typeof pp.y !== 'number' || !Number.isFinite(pp.y)) {
+    throw new ParticleError('emit command position.y must be a finite number');
+  }
+  if (typeof c.seed !== 'number' || !Number.isFinite(c.seed)) {
+    throw new ParticleError('emit command seed must be a finite number');
+  }
+}
+
+interface MutableSlot {
+  active: boolean;
+  age: number;
+  bornAt: number;
+  lifetime: number;
+  originX: number;
+  originY: number;
+  vx: number;
+  vy: number;
+  rotation: number;
+  rotationSpeed: number;
+  scaleStart: number;
+  scaleEnd: number;
+  color: string;
+  spawnSequence: number;
+}
+
+// T20A-R3: accept raw author definitions or already-normalized definitions
+// (normalized definitions are assignable to the author-input union); every
+// value is validated, cloned, and frozen at this boundary.
+export function createParticleSystem<
+  TEffects extends Record<string, ParticleEffectDefinitionInput>,
+>(
+  options: ParticleSystemOptions & { effects: TEffects },
+): ParticleSystem<TEffects> {
+  if (options === null || typeof options !== 'object') {
+    throw new ParticleError('createParticleSystem requires options');
+  }
+  const rawEffects = options.effects;
+  if (rawEffects === null || typeof rawEffects !== 'object') {
+    throw new ParticleError('createParticleSystem requires { effects }');
+  }
+  const names = Object.keys(rawEffects);
+  if (names.length === 0) {
+    throw new ParticleError('createParticleSystem effects must not be empty');
+  }
+
+  // T15-F6: validate, clone, and freeze every definition at the boundary so
+  // callers cannot bypass defineParticleEffect or mutate after creation.
+  const definitions = new Map<string, ParticleEffectDefinition>();
+  for (const name of names) {
+    definitions.set(name, defineParticleEffect(rawEffects[name]!));
+  }
+
+  let status: 'running' | 'paused' | 'disposed' = 'running';
+  let generation = 0;
+  let spawnSequence = 0;
+  // Accumulated ACTIVE time — freezes while paused (T15-SF3).
+  let activeClock = 0;
+  // Emission registry revision (membership changes only).
+  let registryRevision = 0;
+  const emissionsLog: Map<string, ParticleEmissionRecord[]> = new Map();
+
+  const pools = new Map<string, MutableSlot[]>();
+  const diagnostics = new Map<string, ParticleDiagnostics>();
+  for (const [name, def] of definitions) {
+    pools.set(
+      name,
+      Array.from({ length: def.capacity }, () => ({
+        active: false,
+        age: 0,
+        bornAt: 0,
+        lifetime: 1,
+        originX: 0,
+        originY: 0,
+        vx: 0,
+        vy: 0,
+        rotation: 0,
+        rotationSpeed: 0,
+        scaleStart: 1,
+        scaleEnd: 1,
+        color: '#ffffff',
+        spawnSequence: -1,
+      })),
+    );
+    diagnostics.set(name, { active: 0, emitted: 0, dropped: 0, recycled: 0 });
+    emissionsLog.set(name, []);
+  }
+
+  function requireEffect(effect: string): ParticleEffectDefinition {
+    const def = definitions.get(effect);
+    if (def === undefined) {
+      throw new ParticleError(`unknown particle effect ${JSON.stringify(effect)}`);
+    }
+    return def;
+  }
+
+  function frozenSnapshot(effect: string): ParticleDiagnostics {
+    const d = diagnostics.get(effect);
+    return d === undefined
+      ? Object.freeze({ active: 0, emitted: 0, dropped: 0, recycled: 0 })
+      : Object.freeze({ ...d });
+  }
+
+  function emit(effect: string, command: unknown): void {
+    // T15-F6: validate effect key and command BEFORE the paused policy so
+    // malformed input is never silently swallowed as a paused drop.
+    const def = requireEffect(effect);
+    assertCommand(command);
+    if (status === 'disposed') {
+      throw new ParticleError('particle system is disposed');
+    }
+    if (status === 'paused') {
+      const d = diagnostics.get(effect)!;
+      diagnostics.set(effect, {
+        ...d,
+        dropped: d.dropped + def.burst.count,
+      });
+      return;
+    }
+
+    const pool = pools.get(effect)!;
+    const diag = diagnostics.get(effect)!;
+    const rng = createRng(command.seed >>> 0);
+    let emitted = 0;
+    let dropped = 0;
+    let recycled = 0;
+
+    for (let i = 0; i < def.burst.count; i++) {
+      let slotIndex = -1;
+      let oldestIndex = -1;
+      let oldestSeq = Number.POSITIVE_INFINITY;
+      for (let s = 0; s < pool.length; s++) {
+        const slot = pool[s]!;
+        if (!slot.active) {
+          slotIndex = s;
+          break;
+        }
+        if (slot.spawnSequence < oldestSeq) {
+          oldestSeq = slot.spawnSequence;
+          oldestIndex = s;
+        }
+      }
+      if (slotIndex === -1) {
+        if (def.overflow === 'drop-new') {
+          dropped++;
+          continue;
+        }
+        slotIndex = oldestIndex;
+        if (slotIndex === -1) {
+          dropped++;
+          continue;
+        }
+        recycled++;
+      }
+      emitted++;
+      const slot = pool[slotIndex]!;
+      const sampled = sampleInitialSlot(rng, def, command.position, spawnSequence++, effect);
+      slot.active = true;
+      slot.age = 0;
+      slot.bornAt = activeClock;
+      slot.lifetime = sampled.lifetime;
+      slot.originX = sampled.origin.x;
+      slot.originY = sampled.origin.y;
+      slot.vx = sampled.velocity.x;
+      slot.vy = sampled.velocity.y;
+      slot.rotation = sampled.rotation;
+      slot.rotationSpeed = sampled.rotationSpeed;
+      slot.scaleStart = sampled.scaleStart;
+      slot.scaleEnd = sampled.scaleEnd;
+      slot.color = sampled.color;
+      slot.spawnSequence = sampled.spawnSequence;
+      const log = emissionsLog.get(effect)!;
+      log.push(Object.freeze({
+        bornAt: activeClock,
+        originX: sampled.origin.x,
+        originY: sampled.origin.y,
+        vx: sampled.velocity.x,
+        vy: sampled.velocity.y,
+        rotation: sampled.rotation,
+        rotationSpeed: sampled.rotationSpeed,
+        scaleStart: sampled.scaleStart,
+        scaleEnd: sampled.scaleEnd,
+        lifetime: sampled.lifetime,
+        spawnSequence: sampled.spawnSequence,
+      }));
+      if (log.length > def.capacity * 4) log.splice(0, log.length - def.capacity * 4);
+    }
+
+    let active = 0;
+    for (const s of pool) if (s.active) active++;
+    diagnostics.set(effect, {
+      active,
+      emitted: diag.emitted + emitted,
+      dropped: diag.dropped + dropped,
+      recycled: diag.recycled + recycled,
+    });
+    // T15-RF3: an accepted emission may end an idle period — wake the driver.
+    if (emitted > 0) {
+      registryRevision++;
+      if (wakeListener) wakeListener();
+    }
+  }
+
+  function stepClock(deltaSeconds: number): void {
+    if (status === 'disposed') throw new ParticleError('particle system is disposed');
+    if (status === 'paused') return;
+    if (!Number.isFinite(deltaSeconds) || deltaSeconds < 0) {
+      throw new ParticleError('deltaSeconds must be a finite number >= 0');
+    }
+    activeClock += deltaSeconds;
+    for (const [name, pool] of pools) {
+      let active = 0;
+      for (const slot of pool) {
+        if (!slot.active) continue;
+        slot.age += deltaSeconds;
+        if (slot.age >= slot.lifetime) {
+          // T15-TF1: expiry IS a registry membership change — bump so the
+          // pruned registry ships before the driver sleeps.
+          slot.active = false;
+          registryRevision++;
+          continue;
+        }
+        active++;
+      }
+      const d = diagnostics.get(name)!;
+      if (d.active !== active) diagnostics.set(name, { ...d, active });
+    }
+  }
+
+  let driverOwned = false;
+  let releaseDriver: (() => void) | null = null;
+  let wakeListener: (() => void) | null = null;
+
+  function totalActive(): number {
+    let n = 0;
+    for (const pool of pools.values()) {
+      for (const slot of pool) if (slot.active) n++;
+    }
+    return n;
+  }
+
+  function advance(deltaSeconds: number): void {
+    stepClock(deltaSeconds);
+  }
+
+  /**
+   * Public headless step (GS-PARTICLE-01): rejected while a presentation
+   * driver owns the clock — stepping here as well would double-step every
+   * driver step. Release the driver to resume headless updates.
+   */
+  function update(deltaSeconds: number): void {
+    if (driverOwned) {
+      throw new ParticleError(
+        'presentation clock is owned by an acquired driver — use the driver handle to step',
+      );
+    }
+    stepClock(deltaSeconds);
+  }
+
+  function buildRegistry(): ParticleUiRegistry {
+    const effects: Record<string, { capacity: number; particles: ParticleEmissionRecord[] }> = {};
+    for (const [name, def] of definitions) {
+      // GS-PARTICLE-01: the terminal registry after disposal is empty, not
+      // an error — the emissions log is cleared on dispose, and scheduled
+      // presentation callbacks may still read once before they detach.
+      const log = emissionsLog.get(name) ?? [];
+      const pool = pools.get(name)!;
+      // Only ACTIVE emissions are shipped; expired entries are pruned here so
+      // the registry stays bounded by live particles.
+      const activeSeqs = new Set<number>();
+      for (const slot of pool) if (slot.active) activeSeqs.add(slot.spawnSequence);
+      effects[name] = {
+        capacity: def.capacity,
+        particles: log.filter((r) => activeSeqs.has(r.spawnSequence)),
+      };
+    }
+    return { registryRevision, activeClock, effects };
+  }
+
+  const binding: ParticlePresentationBinding = {
+    systemGeneration: generation,
+    definition(effect: string): ParticleEffectDefinition {
+      return requireEffect(effect);
+    },
+    effects: Object.freeze([...definitions.keys()]),
+    tick(deltaSeconds: number): void {
+      if (driverOwned) {
+        throw new ParticleError(
+          'presentation clock is owned by an acquired driver — use the driver handle to step',
+        );
+      }
+      if (status === 'disposed') return;
+      advance(deltaSeconds);
+    },
+    acquireDriver(): ParticleDriverHandle {
+      if (driverOwned) {
+        throw new ParticleError('presentation clock already owned — one driver per system');
+      }
+      if (status === 'disposed') {
+        throw new ParticleError('particle system is disposed');
+      }
+      driverOwned = true;
+      let released = false;
+      releaseDriver = () => {
+        driverOwned = false;
+      };
+      const handle: ParticleDriverHandle = {
+        step(deltaSeconds: number): void {
+          if (released || status === 'disposed') return;
+          advance(deltaSeconds);
+        },
+        isIdle(): boolean {
+          return totalActive() === 0;
+        },
+        setWakeListener(listener: (() => void) | null): void {
+          wakeListener = listener;
+        },
+        release(): void {
+          if (released) return;
+          released = true;
+          wakeListener = null;
+          if (releaseDriver) {
+            const r = releaseDriver;
+            releaseDriver = null;
+            r();
+          }
+        },
+      };
+      return handle;
+    },
+    get driverOwned() {
+      return driverOwned;
+    },
+    get registryRevision() {
+      return registryRevision;
+    },
+    get activeClock() {
+      return activeClock;
+    },
+    get activeCount() {
+      return status === 'disposed' ? 0 : totalActive();
+    },
+    buildUiRegistry(): ParticleUiRegistry {
+      return Object.freeze(buildRegistry());
+    },
+    emissions(effect: string) {
+      requireEffect(effect);
+      const log = emissionsLog.get(effect);
+      if (log === undefined) throw new ParticleError(`unknown particle effect ${JSON.stringify(effect)}`);
+      return log.slice();
+    },
+  };
+  Object.freeze(binding);
+
+  // Expose the UI registry builder to the presentation layer without adding
+  // it to the public binding type: the hook receives it via a typed symbol
+  // free accessor defined below.
+
+
+  const system: ParticleSystem<TEffects> = {
+    emit: emit as ParticleSystem<TEffects>['emit'],
+    update,
+    pause(): void {
+      if (status === 'disposed') throw new ParticleError('particle system is disposed');
+      status = 'paused';
+    },
+    resume(): void {
+      if (status === 'disposed') throw new ParticleError('particle system is disposed');
+      status = 'running';
+    },
+    dispose(): void {
+      if (status === 'disposed') return;
+      status = 'disposed';
+      generation++;
+      if (wakeListener) wakeListener = null;
+      if (releaseDriver) {
+        const r = releaseDriver;
+        releaseDriver = null;
+        driverOwned = false;
+        r();
+      }
+      for (const pool of pools.values()) {
+        for (const slot of pool) {
+          slot.active = false;
+          slot.age = 0;
+          slot.spawnSequence = -1;
+        }
+      }
+      emissionsLog.clear();
+      registryRevision++;
+      for (const [name, d] of diagnostics) {
+        diagnostics.set(name, { ...d, active: 0 });
+      }
+    },
+    getDiagnostics(effect?: keyof TEffects & string): ParticleDiagnostics {
+      if (effect !== undefined) {
+        requireEffect(effect);
+        return frozenSnapshot(effect);
+      }
+      let active = 0;
+      let emitted = 0;
+      let dropped = 0;
+      let recycled = 0;
+      for (const d of diagnostics.values()) {
+        active += d.active;
+        emitted += d.emitted;
+        dropped += d.dropped;
+        recycled += d.recycled;
+      }
+      return Object.freeze({ active, emitted, dropped, recycled });
+    },
+    getActiveParticles(effect: keyof TEffects & string): readonly ParticleSlotSnapshot[] {
+      requireEffect(effect);
+      if (status === 'disposed') return [];
+      const def = definitions.get(effect)!;
+      const out: ParticleSlotSnapshot[] = [];
+      for (const slot of pools.get(effect)!) {
+        if (!slot.active) continue;
+        const sampled = sampleSlotAtAge(ageView(slot), def, slot.age);
+        const origin = { x: slot.originX, y: slot.originY };
+        out.push(
+          Object.freeze({
+            active: true,
+            age: slot.age,
+            lifetime: slot.lifetime,
+            origin: Object.freeze(origin),
+            position: Object.freeze({ x: sampled.x, y: sampled.y }),
+            velocity: Object.freeze({ x: slot.vx, y: slot.vy }),
+            rotation: sampled.rotation,
+            scale: sampled.scale,
+            opacity: sampled.opacity,
+            color: slot.color,
+            spawnSequence: slot.spawnSequence,
+            effect,
+          }),
+        );
+      }
+      return out;
+    },
+    pauseIfRunning(): void {
+      if (status === 'running') status = 'paused';
+    },
+    resumeIfPaused(): void {
+      if (status === 'paused') status = 'running';
+    },
+    get status() {
+      return status;
+    },
+    bindPresentation(): ParticlePresentationBinding {
+      if (status === 'disposed') throw new ParticleError('particle system is disposed');
+      return binding;
+    },
+  };
+  return Object.freeze(system);
+}

package/src/particles/defineParticleEffect.ts

@@ -0,0 +1,164 @@
+import { ParticleError } from './errors';
+import type {
+  ParticleEffectDefinition,
+  ParticleEffectDefinitionInput,
+  ParticleScaleEnvelope,
+  Range,
+} from './types';
+
+function assertRange(range: unknown, name: string): void {
+  if (!range || typeof range !== 'object') throw new ParticleError(`${name} must be {min,max}`);
+  const r = range as { min: unknown; max: unknown };
+  if (typeof r.min !== 'number' || !Number.isFinite(r.min)) throw new ParticleError(`${name}.min must be finite`);
+  if (typeof r.max !== 'number' || !Number.isFinite(r.max)) throw new ParticleError(`${name}.max must be finite`);
+  if (r.min > r.max) throw new ParticleError(`${name}.min must be <= max`);
+}
+
+function assertPositiveSize(value: unknown, name: string): void {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new ParticleError(`${name} must be a finite number greater than zero`);
+  }
+}
+
+function assertNonnegative(value: unknown, name: string): void {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    throw new ParticleError(`${name} must be a finite number greater than or equal to zero`);
+  }
+}
+
+function assertPoint(p: unknown, name: string): void {
+  if (!p || typeof p !== 'object') throw new ParticleError(`${name} must be {x,y}`);
+  const pt = p as { x: unknown; y: unknown };
+  if (typeof pt.x !== 'number' || !Number.isFinite(pt.x)) throw new ParticleError(`${name}.x must be finite`);
+  if (typeof pt.y !== 'number' || !Number.isFinite(pt.y)) throw new ParticleError(`${name}.y must be finite`);
+}
+
+/**
+ * Validate one T20.1 envelope endpoint and normalize it to a frozen Range.
+ * Endpoints are non-negative and finite (T20A-R1): zero collapses to a point;
+ * negative scale has no defined rendering semantics and is rejected.
+ */
+function normalizeScaleEndpoint(value: unknown, name: string): Range {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new ParticleError(`${name} must be finite`);
+    if (value < 0) throw new ParticleError(`${name} must be >= 0`);
+    return Object.freeze({ min: value, max: value });
+  }
+  assertRange(value, name);
+  const r = value as Range;
+  if (r.min < 0 || r.max < 0) throw new ParticleError(`${name} must be >= 0`);
+  return Object.freeze({ min: r.min, max: r.max });
+}
+
+export function defineParticleEffect(def: ParticleEffectDefinitionInput): ParticleEffectDefinition {
+  if (!def || typeof def !== 'object') throw new ParticleError('effect definition must be an object');
+  if (typeof def.capacity !== 'number' || !Number.isFinite(def.capacity) || def.capacity < 1 || def.capacity > 1024 || Math.floor(def.capacity) !== def.capacity) {
+    throw new ParticleError('capacity must be integer 1..1024');
+  }
+  if (def.space !== 'world' && def.space !== 'screen') throw new ParticleError('space must be world or screen');
+  if (def.overflow !== 'drop-new' && def.overflow !== 'recycle-oldest') throw new ParticleError('overflow must be drop-new or recycle-oldest');
+  if (!def.particle || typeof def.particle !== 'object') throw new ParticleError('particle must be object');
+  if (def.particle.kind === 'sprite') {
+    if (typeof def.particle.sheet !== 'string' || !def.particle.sheet) throw new ParticleError('sprite sheet must be non-empty string');
+    if (typeof def.particle.frame !== 'string' || !def.particle.frame) throw new ParticleError('sprite frame must be non-empty string');
+    // GS-PARTICLE-03: drawable dimensions only — NaN/Infinity/zero would
+    // reach native drawing or break the uniform-ratio check.
+    if (!def.particle.size || typeof def.particle.size !== 'object') {
+      throw new ParticleError('sprite size must be {width,height}');
+    }
+    assertPositiveSize(def.particle.size.width, 'sprite size.width');
+    assertPositiveSize(def.particle.size.height, 'sprite size.height');
+  } else if (def.particle.kind === 'shape') {
+    if (def.particle.shape !== 'circle' && def.particle.shape !== 'rectangle') throw new ParticleError('shape must be circle or rectangle');
+    // GS-PARTICLE-03: shape dimensions validate by presence — absent
+    // fields keep their render defaults, present fields must be finite and
+    // drawable (radius zero collapses to a point, like scale zero).
+    if (def.particle.shape === 'circle') {
+      if (def.particle.radius !== undefined) assertNonnegative(def.particle.radius, 'circle radius');
+      if (def.particle.width !== undefined || def.particle.height !== undefined) {
+        throw new ParticleError('circle particles take radius, not width/height');
+      }
+    } else {
+      if (def.particle.width !== undefined) assertPositiveSize(def.particle.width, 'rectangle width');
+      if (def.particle.height !== undefined) assertPositiveSize(def.particle.height, 'rectangle height');
+      if (def.particle.radius !== undefined) {
+        throw new ParticleError('rectangle particles take width/height, not radius');
+      }
+    }
+    if (def.particle.color !== undefined && typeof def.particle.color !== 'string') {
+      throw new ParticleError('shape color must be a string');
+    }
+  } else {
+    throw new ParticleError('particle.kind must be sprite or shape');
+  }
+  // GS-PARTICLE-03: integer counts only — a fractional count would emit
+  // ceil(count) particles from a loop bound that promises otherwise.
+  if (!def.burst || typeof def.burst.count !== 'number' || !Number.isFinite(def.burst.count) || !Number.isInteger(def.burst.count) || def.burst.count < 1 || def.burst.count > def.capacity) {
+    throw new ParticleError('burst.count must be an integer 1..capacity');
+  }
+  assertRange(def.lifetimeSeconds, 'lifetimeSeconds');
+  if (def.lifetimeSeconds.min <= 0) throw new ParticleError('lifetimeSeconds.min must be >0');
+  assertRange(def.speed, 'speed');
+  if (def.speed.min < 0) throw new ParticleError('speed.min must be >=0');
+  // GS-PARTICLE-03: optional ranges validate by PRESENCE — a null or
+  // otherwise present-but-invalid value must fail, not fall through.
+  if (def.direction !== undefined) assertRange(def.direction, 'direction');
+  if (def.rotation !== undefined) assertRange(def.rotation, 'rotation');
+  // T20A-R2: optional scale fields validate by PRESENCE, not truthiness —
+  // raw JavaScript values such as null, false, or 0 must fail at the boundary
+  // instead of silently falling back to the default scale.
+  const hasLegacyScale = def.scaleOverLife !== undefined;
+  const hasExplicitScale = def.scale !== undefined;
+  if (hasLegacyScale && hasExplicitScale) {
+    throw new ParticleError('scaleOverLife and scale are mutually exclusive — specify only one');
+  }
+  if (hasLegacyScale) {
+    const legacy = def.scaleOverLife;
+    if (legacy === null || typeof legacy !== 'object' || Array.isArray(legacy)) {
+      throw new ParticleError('scaleOverLife must be {min,max}');
+    }
+    assertRange(legacy, 'scaleOverLife');
+  }
+  let scale: ParticleScaleEnvelope | undefined;
+  if (hasExplicitScale) {
+    const raw = def.scale;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+      throw new ParticleError('scale must be an object with start and end endpoints');
+    }
+    if (!('start' in raw) || !('end' in raw)) {
+      throw new ParticleError('scale must specify start and end endpoints');
+    }
+    scale = Object.freeze({
+      start: normalizeScaleEndpoint(raw.start, 'scale.start'),
+      end: normalizeScaleEndpoint(raw.end, 'scale.end'),
+    });
+  }
+  assertPoint(def.gravity, 'gravity');
+  if (typeof def.fadeOut !== 'boolean') throw new ParticleError('fadeOut must be boolean');
+  return Object.freeze(
+    {
+      ...def,
+      // GS-PARTICLE-03: the nested size record is cloned, never aliased —
+      // caller mutation after definition cannot reach the system.
+      particle: Object.freeze({
+        ...def.particle,
+        ...('size' in def.particle && def.particle.size !== undefined
+          ? { size: Object.freeze({ ...def.particle.size as { width: number; height: number } }) }
+          : {}),
+      }),
+      burst: Object.freeze({ ...def.burst }),
+      lifetimeSeconds: Object.freeze({ ...def.lifetimeSeconds }),
+      speed: Object.freeze({ ...def.speed }),
+      gravity: Object.freeze({ ...def.gravity }),
+      // T20.1: every nested range in the normalized definition is frozen.
+      ...(def.direction ? { direction: Object.freeze({ ...def.direction }) } : {}),
+      ...(def.rotation ? { rotation: Object.freeze({ ...def.rotation }) } : {}),
+      // T20A-R2: normalized scale fields always overwrite the raw input
+      // values so an unchecked optional can never survive the input spread.
+      scaleOverLife: hasLegacyScale
+        ? Object.freeze({ ...def.scaleOverLife })
+        : undefined,
+      scale,
+    } as ParticleEffectDefinition,
+  );
+}

package/src/particles/errors.ts

@@ -0,0 +1,6 @@
+export class ParticleError extends Error {
+  override name = 'ParticleError';
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/particles/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './errors';
+export * from './defineParticleEffect';
+export * from './createParticleSystem';
+export * from './sampling';