skills/plugins/document-navigator/docs/foundation/random/pseudo-random/README.md

@suaveplan/pseudo-random - Deterministic seeded PRNG implementations (Mulberry32, SFC32, Xoshiro256++, CounterRng) with offset/fork/checkpoint/restore semantics

Summary

Deterministic, seeded pseudo-random number generators (PRNGs) conforming to the Rng interface from @suaveplan/types. Ships four algorithms — Mulberry32, SFC32, Xoshiro256++, and CounterRng — with a unified SeededRng surface that includes nextUint32, nextFloat, skip, at, fork, checkpoint, and restore. Use this package when you need reproducible randomness (procedural generation, game simulations, property tests) or seek O(1) access to arbitrary positions in the sequence. For cryptographically secure randomness use @suaveplan/random (CSPRNG-backed) or @suaveplan/crypto (raw bytes). Utility functions shuffle, sample, choice, and weightedChoice accept any Rng and work with both seeded and crypto-backed sources.

Documentation tree

• counter-rng — CounterRng is a hash-based PRNG: its output at logical position i is splitmix64(seed XOR i). Because the output d…
• mulberry32 — Mulberry32Rng implements the Mulberry32 PRNG — a compact 32-bit linear-congruential-plus-mix generator with a period…
• sfc32 — Sfc32Rng is a 128-bit SFC32 (Small Fast Counting) generator by Chris Doty-Humphrey. It carries four uint32 state word…
• xoshiro256 — Xoshiro256PlusPlusRng implements Blackman and Vigna's Xoshiro256++ PRNG — 256 bits of state, period 2^256 − 1, with a…
• errors — (no submodules)
  • pseudo-random-error — (no submodules)
• seed — (no submodules)
  • normalize — (no submodules)
• sample — The sample module covers the two sampling primitives that sit above shuffle: unique-without-replacement sample fo…
• shuffle — The shuffle module provides deterministic Fisher-Yates shuffling and single-element choice drawn from a user-suppli…

- [pseudo-random-error](./src/errors/pseudo-random-error.md) — _(no submodules)_- [seed](./src/seed/normalize.md) — _(no submodules)_- [normalize](./src/seed/normalize.md) — _(no submodules)_- [sample](./src/utils/sample.md) — The `sample` module covers the two sampling primitives that sit above `shuffle`: unique-without-replacement `sample` fo…

• shuffle — The shuffle module provides deterministic Fisher-Yates shuffling and single-element choice drawn from a user-suppli…
• pseudo-random-error — (no submodules)- seed — (no submodules)- normalize — (no submodules)- sample — The sample module covers the two sampling primitives that sit above shuffle: unique-without-replacement sample fo…
• shuffle — The shuffle module provides deterministic Fisher-Yates shuffling and single-element choice drawn from a user-suppli…
• pseudo-random-error — (no submodules)- seed — (no submodules)- normalize — (no submodules)- sample — The sample module covers the two sampling primitives that sit above shuffle: unique-without-replacement sample fo…
• shuffle — The shuffle module provides deterministic Fisher-Yates shuffling and single-element choice drawn from a user-suppli…
• pseudo-random-error — (no submodules)- seed — (no submodules) - normalize — (no submodules)- sample — The sample module covers the two sampling primitives that sit above shuffle: unique-without-replacement sample fo…
• shuffle — The shuffle module provides deterministic Fisher-Yates shuffling and single-element choice drawn from a user-suppli…

Packages

Four algorithms with identical SeededRng surface:

Algorithm	State	Period	Best for
Mulberry32Rng	32 bit	~2^32	Tiny, per-UI seeding
Sfc32Rng	128bit	≥2^32	High-quality default
Xoshiro256PlusPlusRng	256bit	2^256 − 1	Simulations + parallel streams
CounterRng	64 bit	—	O(1) seek, procedural tiles

Each implements nextUint32, nextFloat, skip, at, fork, checkpoint, restore, plus Xoshiro256PlusPlusRng.jump() for jumping by 2^128 steps.

Install

bun add @suaveplan/pseudo-random

Quick start

import { Sfc32Rng, shuffle } from "@suaveplan/pseudo-random";

const rng = new Sfc32Rng("game-42");
const deck = shuffle(["A", "K", "Q", "J"], rng);

Subpath exports

• @suaveplan/pseudo-random/algorithms — the four generators
• @suaveplan/pseudo-random/seed — normalizeSeed, splitmix32/64, expandSeed
• @suaveplan/pseudo-random/utils — shuffle, sample, choice, weightedChoice
• @suaveplan/pseudo-random/errors — PseudoRandomError, PSEUDO_RANDOM_CODES
• @suaveplan/pseudo-random/schemas — Zod schemas for serialised state

Module docs

• algorithms/mulberry32
• algorithms/sfc32
• algorithms/xoshiro256
• algorithms/counter-rng
• seed/normalize
• utils/shuffle
• utils/sample
• errors
• types