# Capability: noise-functions

## Requirements

### Package identity

- REQ-NOISE-001: Package name `@suaveplan/noise`, `packages/universal/noise`.
- REQ-NOISE-002: Runtime deps: `@suaveplan/error`, `tslib`. Zero PRNG deps — noise uses its own internal seeded hash permutation tables.
- REQ-NOISE-003: `"sideEffects": false`.

### Output contract

- REQ-NOISE-010: All noise functions return values normalised to `[-1, 1]` except Worley which returns `[0, 1]` distance values.
- REQ-NOISE-011: All noise functions accept `seed: number` as first parameter. Same seed + same coordinates always returns same value.

### Perlin noise

- REQ-NOISE-020: Exports `perlin2(seed: number, x: number, y: number): number`.
- REQ-NOISE-021: Exports `perlin3(seed: number, x: number, y: number, z: number): number`.

### Simplex noise

- REQ-NOISE-030: Exports `simplex2(seed: number, x: number, y: number): number`.
- REQ-NOISE-031: Exports `simplex3(seed: number, x: number, y: number, z: number): number`.
- REQ-NOISE-032: Exports `simplex4(seed: number, x: number, y: number, z: number, w: number): number`.

### Value noise

- REQ-NOISE-040: Exports `value2(seed: number, x: number, y: number): number`.
- REQ-NOISE-041: Exports `value3(seed: number, x: number, y: number, z: number): number`.

### Worley / cell noise

- REQ-NOISE-050: Exports `WorleyMode = "F1" | "F2" | "F1-F2"`.
- REQ-NOISE-051: Exports `worley2(seed: number, x: number, y: number, mode?: WorleyMode): number`. Default mode `"F1"`.
- REQ-NOISE-052: Exports `worley3(seed: number, x: number, y: number, z: number, mode?: WorleyMode): number`.

### Fractional Brownian Motion

- REQ-NOISE-060: Exports `FbmOptions = { octaves?: number; lacunarity?: number; gain?: number }`. Defaults: `octaves=6, lacunarity=2.0, gain=0.5`.
- REQ-NOISE-061: Exports `fbm2(noiseFn: (seed, x, y) => number, seed: number, x: number, y: number, opts?: FbmOptions): number`.
- REQ-NOISE-062: Exports `fbm3(noiseFn: (seed, x, y, z) => number, seed: number, x: number, y: number, z: number, opts?: FbmOptions): number`.

### Blue noise / Poisson disk sampling

- REQ-NOISE-070: Exports `blueNoiseSample(width: number, height: number, minDistance: number, opts?: { seed?: number; rng?: Rng; maxSamples?: number }): [number, number][]`.
- REQ-NOISE-071: Uses Bridson's algorithm. Default `maxSamples = 100_000`; throws `NoiseError("NOISE.BLUE.SAMPLE_LIMIT_EXCEEDED")` if exceeded.

### Error surface

- REQ-NOISE-080: Exports `NoiseError extends SuaveplanError<NoiseCode>`.
- REQ-NOISE-081: Codes: `NOISE.BLUE.SAMPLE_LIMIT_EXCEEDED`, `NOISE.FBM.INVALID_OCTAVES`.

### Quality

- REQ-NOISE-090: 100% statement + branch coverage.
- REQ-NOISE-091: fast-check: determinism (same seed+coords → same output), output range `[-1,1]` (or `[0,1]` for Worley).
- REQ-NOISE-092: mitata benchmarks: each function at 1k and 100k evaluations.