Skip to content

Mulberry32

Jump to bottom
Ferran Buireu edited this page Oct 4, 2026 · 7 revisions

Deterministic Randomness (Mulberry32)

Some UI surfaces need a contribution grid that looks plausible without real data: the placeholder the landing page draws for a visitor who asked for no Username, the Home Screen Widget preview's mini-grid, and the error page's decorative calendar. Rather than Math.random() (which would flicker on every render and can't be tested), ContribKit uses a seeded PRNG: Mulberry32. It lives in web/src/ui/utils/mulberry.ts.

Why seeded

  • Deterministic: the same seed always yields the same sequence, so a placeholder grid is stable across re-renders and identical between SSR and hydration (no layout flicker, no mismatch).
  • Testable: a fixed seed gives a fixed output, so the PRNG and anything built on it can be unit-tested.
  • Tiny & fast: Mulberry32 is a single-uint32-state generator, ideal for non-cryptographic visual use.

Mulberry32 is not cryptographically secure. It is only used for visual placeholder data, never for anything security-sensitive.

The algorithm

export const mulberry32 = (seed: number): (() => number) => {
  let state = seed;
  return () => {
    state += WEYL_INCREMENT;
    let hash = state;
    hash = Math.imul(hash ^ (hash >>> FIRST_MIX_SHIFT), hash | FIRST_ODD_MASK);
    hash ^= hash + Math.imul(hash ^ (hash >>> SECOND_MIX_SHIFT), hash | SECOND_ODD_MASK);
    return ((hash ^ (hash >>> FINAL_MIX_SHIFT)) >>> 0) / UINT32_RANGE;
  };
};

It advances an internal state by a fixed odd increment, runs it through two Math.imul mixing steps, and normalizes the final uint32 to a float in [0, 1). Every magic number is a named constant, because the repository allows no code comments to explain one:

Constant Value Role
WEYL_INCREMENT 0x6d2b79f5 per-step state advance (a Weyl sequence)
FIRST_MIX_SHIFT / FIRST_ODD_MASK 15 / 1 first imul mix
SECOND_MIX_SHIFT / SECOND_ODD_MASK 7 / 61 second imul mix
FINAL_MIX_SHIFT 14 final xorshift before normalizing
UINT32_RANGE 0x1_00_00_00_00 divisor that maps the uint32 into [0, 1)

Mulberry32 holds a single 32-bit state, giving a period of 2³². That's far more than enough for a few hundred placeholder cells, and the whole generator compiles to a handful of integer ops.

Where it's used

Caller Purpose
ui/components/grid/calendar.ts seeded placeholder levels for the grid a visitor who asked for no Username sees
ui/components/grid/mini-grid.ts the small decorative grid
ui/components/error/ContributionCode.astro the calendar art on error pages

Each caller picks a seed, calls mulberry32(seed), then draws from the returned function to assign placeholder levels.

See also

Clone this wiki locally